@astralyn/pi 0.82.2 → 0.82.4

package/examples/extensions/overlay-qa-tests.ts

@@ -485,13 +485,13 @@ class StreamingOverflowComponent extends BaseOverlay {
 			echo ""
 			for i in $(seq 1 100); do
 				# Simulate long file paths with OSC 8 hyperlinks (clickable) - tests width overflow
-				DIR="/Users/nicobailon/Documents/development/pi-mono/packages/coding-agent/src/modes/interactive"
+				DIR="/opt/overlay-qa-fixtures/a-deliberately-long-project-directory/src/modes/interactive"
 				FILE="\${DIR}/components/very-long-component-name-that-exceeds-width-\${i}.ts"
 				echo -e "\\033]8;;file://\${FILE}\\007▶ read: \${FILE}\\033]8;;\\007"
 
 				# Add some colored status messages with long text
 				if [ $((i % 5)) -eq 0 ]; then
-					echo -e "  \\033[32m✓ Successfully processed \${i} files in /Users/nicobailon/Documents/development/pi-mono\\033[0m"
+					echo -e "  \\033[32m✓ Successfully processed \${i} files in \${DIR}\\033[0m"
 				fi
 				if [ $((i % 7)) -eq 0 ]; then
 					echo -e "  \\033[33m⚠ Warning: potential issue detected at line \${i} in very-long-component-name-that-exceeds-width.ts\\033[0m"

package/examples/extensions/project-trust.ts

@@ -4,11 +4,11 @@
  * Demonstrates the project_trust event. Install globally or pass via -e:
  *
  *   mkdir -p ~/.pi/agent/extensions
- *   cp packages/coding-agent/examples/extensions/project-trust.ts ~/.pi/agent/extensions/
+ *   cp examples/extensions/project-trust.ts ~/.pi/agent/extensions/
  *
  * Or:
  *
- *   pi -e packages/coding-agent/examples/extensions/project-trust.ts
+ *   pi -e examples/extensions/project-trust.ts
  *
  * Try it in a project containing .pi, AGENTS.md/CLAUDE.md, or .agents/skills.
  */

package/examples/sdk/README.md

@@ -1,6 +1,6 @@
 # SDK Examples
 
-Programmatic usage of pi-coding-agent via `createAgentSession()` and `createAgentSessionRuntime()`.
+Programmatic usage of `@astralyn/pi` via `createAgentSession()` and `createAgentSessionRuntime()`.
 
 The runtime example shows how to build a recreate function that closes over process-global fixed inputs and recreates cwd-bound services and sessions as the active session cwd changes.
 
@@ -15,7 +15,7 @@ The runtime example shows how to build a recreate function that closes over proc
 | `05-tools.ts` | Built-in tool allowlists |
 | `06-extensions.ts` | Logging, blocking, result modification |
 | `07-context-files.ts` | AGENTS.md context files |
-| `08-slash-commands.ts` | File-based slash commands |
+| `08-prompt-templates.ts` | File-based prompt templates |
 | `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
 | `10-settings.ts` | Override compaction, retry, terminal settings |
 | `11-sessions.ts` | In-memory, persistent, continue, list sessions |
@@ -24,75 +24,69 @@ The runtime example shows how to build a recreate function that closes over proc
 
 ## Running
 
+From the repository root, or from the root of an unpacked npm package:
+
 ```bash
-cd packages/coding-agent
 npx tsx examples/sdk/01-minimal.ts
 ```
 
 ## Quick Reference
 
 ```typescript
-import { getModel } from "@earendil-works/pi-ai";
 import {
   createAgentSession,
   DefaultResourceLoader,
+  getAgentDir,
   ModelRuntime,
   SessionManager,
   SettingsManager,
 } from "@astralyn/pi";
+import { getModel } from "@earendil-works/pi-ai/compat";
 
-const modelRuntime = await ModelRuntime.create();
-
-// Minimal
-const { session } = await createAgentSession({ modelRuntime });
+// Minimal: uses the default model, resources, tools, settings, and session storage.
+const { session } = await createAgentSession();
 
-// Custom model
+// Select a built-in model.
+const modelRuntime = await ModelRuntime.create();
 const model = getModel("anthropic", "claude-opus-4-5");
-const { session } = await createAgentSession({ model, thinkingLevel: "high", modelRuntime });
-
-// Modify prompt
-const loader = new DefaultResourceLoader({
-  systemPromptOverride: (base) => `${base}\n\nBe concise.`,
+if (model) {
+  const { session: modelSession } = await createAgentSession({
+    model,
+    thinkingLevel: "high",
+    modelRuntime,
+  });
+}
+
+// Replace the system prompt.
+const resourceLoader = new DefaultResourceLoader({
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  systemPromptOverride: () => "You are helpful and concise.",
+  appendSystemPromptOverride: () => [],
 });
-await loader.reload();
-const { session } = await createAgentSession({ resourceLoader: loader, modelRuntime });
-
-// Read-only
-const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], modelRuntime });
-
-// In-memory
-const { session } = await createAgentSession({
+await resourceLoader.reload();
+const { session: promptSession } = await createAgentSession({
+  resourceLoader,
   sessionManager: SessionManager.inMemory(),
-  modelRuntime,
 });
 
-// Full control
-const customRuntime = await ModelRuntime.create({
-  authPath: "/my/app/auth.json",
-  modelsPath: "/my/app/models.json",
+// Enable only read-only built-in tools and keep the session in memory.
+const { session: readOnlySession } = await createAgentSession({
+  tools: ["read", "grep", "find", "ls"],
+  sessionManager: SessionManager.inMemory(),
 });
-customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
 
-const resourceLoader = new DefaultResourceLoader({
-  systemPromptOverride: () => "You are helpful.",
-  extensionFactories: [myExtension],
-  skillsOverride: () => ({ skills: [], diagnostics: [] }),
-  agentsFilesOverride: () => ({ agentsFiles: [] }),
-  promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+// Override settings without file I/O.
+const settingsManager = SettingsManager.inMemory({
+  compaction: { enabled: false },
+  retry: { enabled: true, maxRetries: 2 },
 });
-await resourceLoader.reload();
-
-const { session } = await createAgentSession({
-  model,
-  modelRuntime: customRuntime,
-  resourceLoader,
-  tools: ["read", "bash", "my_tool"],
-  customTools: [myTool],
+const { session: configuredSession } = await createAgentSession({
+  settingsManager,
   sessionManager: SessionManager.inMemory(),
-  settingsManager: SettingsManager.inMemory(),
 });
 
-// Run prompts
+// Stream a response.
 session.subscribe((event) => {
   if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
     process.stdout.write(event.assistantMessageEvent.delta);

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.82.2",
+	"version": "0.82.4",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@astralyn/pi",
-			"version": "0.82.2",
+			"version": "0.82.4",
 			"license": "MIT",
 			"dependencies": {
 				"@earendil-works/pi-agent-core": "0.82.1",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "0.82.2",
+	"version": "0.82.4",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -31,11 +31,15 @@
 		"clean": "shx rm -rf dist",
 		"build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
 		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/",
+		"dev": "node scripts/run-source.mjs",
 		"format": "biome check --write .",
-		"check": "biome check --error-on-warnings . && npm run check:pinned-deps && npm run check:ts-imports && tsgo --noEmit && tsgo -p tsconfig.examples.json",
+		"check": "biome check --error-on-warnings . && npm run check:pinned-deps && npm run check:ts-imports && npm run check:docs && tsgo --noEmit && tsgo -p tsconfig.examples.json",
 		"check:pinned-deps": "node scripts/check-pinned-deps.mjs",
 		"check:ts-imports": "node scripts/check-ts-relative-imports.mjs",
+		"check:docs": "node scripts/check-docs.mjs",
 		"test": "vitest --run",
+		"test:isolated": "node scripts/test-isolated.mjs",
+		"diff:upstream": "node scripts/diff-upstream.mjs",
 		"verify:package-install": "node scripts/verify-package-install.mjs",
 		"profile:tui": "node scripts/profile-node.mjs --mode tui",
 		"profile:rpc": "node scripts/profile-node.mjs --mode rpc",

package/docs/development.md

@@ -1,68 +0,0 @@
-# Development
-
-See the repository [AGENTS.md](../AGENTS.md) for the distribution contract and coding conventions.
-
-## Setup
-
-```bash
-git clone https://github.com/ming-kang/pi
-cd pi
-npm install --ignore-scripts
-npm run build
-npm run check
-```
-
-The repository is the standalone `@astralyn/pi` package. AI, Agent core, and TUI are installed as exact upstream npm dependencies; no sibling workspace build is required.
-
-Run from source:
-
-```bash
-./pi-test.sh
-```
-
-The script can be invoked from any directory. Pi keeps the caller's current working directory. Use `./pi-test.sh --no-env` to clear provider credentials for the source run.
-
-## Package identity
-
-Distribution identity and configuration directory defaults are defined in `package.json`:
-
-```json
-{
-  "name": "@astralyn/pi",
-  "piConfig": {
-    "configDir": ".pi"
-  },
-  "bin": {
-    "pi": "dist/cli.js"
-  }
-}
-```
-
-## Path resolution
-
-Pi supports npm installation and `tsx` source execution. Always use `src/config.ts` helpers such as `getPackageDir()` and `getThemeDir()` for package assets; do not derive asset paths directly from `__dirname`.
-
-## Debug command
-
-`/debug` (hidden) writes rendered TUI lines and the latest model messages to `~/.pi/agent/pi-debug.log`.
-
-## Testing
-
-```bash
-npm run check
-node node_modules/vitest/dist/cli.js --run test/specific.test.ts
-./test.sh  # complete isolated test suite
-```
-
-Release CI runs the full suite on Ubuntu. Interactive UI changes should also be verified in a real terminal.
-
-## Project structure
-
-```text
-src/                 runtime source
- test/                automated tests and local test helpers
- docs/                product and public API documentation
- examples/            SDK and extension examples
- docs/distribution/   standalone distribution documentation
- scripts/             package maintenance scripts
-```

package/docs/distribution/README.md

@@ -1,34 +0,0 @@
-# Distribution documentation
-
-This directory contains documentation owned by the standalone `@astralyn/pi` distribution. Product usage and public API documentation inherited from upstream coding-agent lives one level above under `docs/`.
-
-## User documentation
-
-- [Distribution overview](../../README.md) — package identity, installation, bundled features, and development entry points.
-- [Quickstart](../quickstart.md) — install, authenticate, and run a first session.
-- [User and API documentation](../index.md) — interactive mode, settings, customization, SDK, RPC, and platform notes.
-- [Extension API](../extensions.md) — write external TypeScript extensions.
-- [Theme API](../themes.md) — create and load custom themes.
-
-## Architecture and design
-
-- [Architecture and dependency boundaries](architecture.md)
-- [Native tool presentation](tool-presentation.md)
-- [Bundled theme design](themes.md)
-
-## Bundled extensions
-
-- [Catalog](extensions/README.md)
-- [deepwiki](extensions/deepwiki.md)
-- [question](extensions/question.md)
-- [rewind](extensions/rewind.md)
-- [router](extensions/router.md)
-- [statusline](extensions/statusline.md)
-- [subagent](extensions/subagent.md)
-- [todo](extensions/todo.md)
-
-## Maintainer documentation
-
-- [Upstream synchronization](maintenance.md)
-- [OIDC npm release checklist](release.md)
-- [Repository contract](../../AGENTS.md)

package/docs/distribution/architecture.md

@@ -1,102 +0,0 @@
-# Distribution architecture
-
-## Purpose
-
-This repository is a standalone personal distribution of Pi's coding-agent package. Its goals are to:
-
-- maintain only code that ships in `@astralyn/pi`;
-- consume AI, Agent core, and TUI from upstream npm releases;
-- keep native tool presentation, bundled workflow extensions, themes, and context-safety behavior local to this package;
-- avoid cross-workspace source changes and multi-package release coordination.
-
-## Package boundary
-
-The repository root is the npm package:
-
-```text
-src/                 coding-agent runtime
- test/                coding-agent tests
- docs/                product and API documentation
- examples/            SDK and extension examples
- docs/distribution/   distribution-owned documentation
- package.json          @astralyn/pi
- npm-shrinkwrap.json   development and published dependency lock
-```
-
-The runtime boundary is explicit and versioned in `package.json`:
-
-- `@earendil-works/pi-ai`
-- `@earendil-works/pi-agent-core`
-- `@earendil-works/pi-tui`
-
-These are exact registry dependencies. Their source is not copied into this repository and local verification resolves the same published packages that npm users install. A coding-agent synchronization that needs new upstream APIs must update all compatible dependency versions in the same change.
-
-Presentation-only metadata such as `toolGroup` uses coding-agent-local intersection types rather than changing `AgentTool`. The long-tool-loop compaction implementation uses the upstream stateful Agent's public `prepareNextTurnWithContext` callback for successful same-run continuation. Exceptional fail-closed paths are represented locally as explicit error/aborted lifecycle boundaries because the stateful Agent does not expose its low-level graceful turn-stop callback.
-
-## Core and extension boundary
-
-Pi core changes are reserved for behavior that must be global:
-
-- native tool call/result chrome and generic renderer fallback;
-- built-in renderer integration;
-- context-safety checks such as between-tool-batch auto-compaction;
-- globally configurable keybindings required by bundled UI.
-
-Personal workflow features remain self-contained extensions:
-
-```text
-src/extensions/
-├── deepwiki/
-├── question/
-├── todo/
-├── rewind/
-├── router/
-├── statusline/
-└── subagent/
-```
-
-They are registered as hidden `InlineExtension` entries in `src/extensions/index.ts`. No shared Fork framework, feature registry, or cross-extension internal API is used.
-
-## Configuration compatibility
-
-The command remains `pi`, and settings and sessions remain under `~/.pi/agent`. Built-in extensions store their first-class data alongside the normal agent data, including:
-
-```text
-~/.pi/agent/router.json
-~/.pi/agent/rewind/
-```
-
-No separate Fork configuration layer is introduced.
-
-## Themes
-
-`ice-cream-dark` and `ice-cream-light` are native theme assets under `src/modes/interactive/theme/`. The normal package build copies all theme JSON files into `dist`.
-
-## Upstream synchronization
-
-The `upstream` remote still points to `earendil-works/pi`, but upstream monorepo tags are not merged into this standalone branch. Synchronization extracts and reviews only `packages/coding-agent/**` from an upstream release tag, maps that subtree to the repository root, and updates exact registry dependency versions. See [maintenance.md](maintenance.md).
-
-Recurring review hotspots are:
-
-```text
-src/extensions/index.ts
-src/core/agent-session.ts
-src/core/keybindings.ts
-src/core/tools/*.ts
-src/modes/interactive/components/tool-execution.ts
-src/modes/interactive/interactive-mode.ts
-src/modes/interactive/theme/theme.ts
-package.json
-CHANGELOG.md
-```
-
-## Release model
-
-Only `@astralyn/pi` is published. Fork releases track the upstream `major.minor` line while using the patch number for this distribution's release sequence:
-
-```text
-upstream 0.82.x -> Fork 0.82.0, 0.82.1, 0.82.2, ...
-upstream 0.83.x -> Fork 0.83.0, 0.83.1, 0.83.2, ...
-```
-
-Tags use `pi-v<full-version>` so they do not collide with upstream `v<version>` tags. Ubuntu CI verifies the standalone package, and the manually dispatched publish workflow uploads the repository root with npm Trusted Publishing. No other package, binary release flow, model catalog, or update service is maintained here.

package/docs/distribution/extensions/README.md

@@ -1,17 +0,0 @@
-# Bundled extensions
-
-These are extensions shipped by the distribution. For the public API used to write external extensions, see the [Extension API documentation](../../extensions.md).
-
-The bundled extensions are maintained as self-contained TypeScript modules under `src/extensions/` and registered as hidden built-in extensions.
-
-| Extension | Tool or command | Documentation |
-|---|---|---|
-| `deepwiki` | `deepwiki` | [deepwiki.md](deepwiki.md) |
-| `question` | `question` | [question.md](question.md) |
-| `todo` | `todo`, `/todos` | [todo.md](todo.md) |
-| `rewind` | `/rewind`, `/tree` lifecycle | [rewind.md](rewind.md) |
-| `router` | `/router` | [router.md](router.md) |
-| `statusline` | Footer | [statusline.md](statusline.md) |
-| `subagent` | `subagent`, `/agents` | [subagent.md](subagent.md) |
-
-The extensions continue to use Pi's public Extension API. Keeping their distribution notes here does not merge their implementations into the coding-agent core.

package/docs/distribution/maintenance.md

@@ -1,121 +0,0 @@
-# Distribution maintenance
-
-This guide describes how to keep the standalone `@astralyn/pi` package aligned with upstream Pi. The repository contract in [`AGENTS.md`](../../AGENTS.md) is authoritative; publishing is covered separately in [`release.md`](release.md).
-
-## Repository model
-
-```text
-origin    private distribution repository
-upstream  earendil-works/pi monorepo
-```
-
-`main` contains a standalone package, not an upstream monorepo checkout. Upstream tags must therefore be inspected and selectively imported; never merge an upstream tag directly into `main`, because that would recreate every workspace.
-
-## Ownership layers
-
-| Layer | Typical paths | Policy |
-|---|---|---|
-| Upstream-aligned coding-agent | most of `src/**`, `test/**`, `docs/**`, `examples/**` | Import compatible changes from an upstream release tag. |
-| Distribution-owned | `docs/distribution/**`, bundled personal extensions, ice-cream themes, release workflow, package identity | Preserve local design and update deliberately. |
-| Hybrid | `src/core/agent-session.ts`, native tool presentation, built-in tools, keybindings, extension registration, `package.json`, `CHANGELOG.md` | Review function by function; retain upstream lifecycle semantics and local behavior. |
-| Registry boundary | exact upstream AI, Agent core, and TUI dependencies | Upgrade together with the imported coding-agent release; never patch their installed files. |
-
-Recurring hybrid hotspots include:
-
-```text
-src/extensions/index.ts
-src/core/agent-session.ts
-src/core/keybindings.ts
-src/core/tools/*.ts
-src/modes/interactive/components/tool-execution.ts
-src/modes/interactive/interactive-mode.ts
-src/modes/interactive/theme/theme.ts
-package.json
-CHANGELOG.md
-```
-
-## Synchronization workflow
-
-Synchronize only against upstream release tags, never upstream `main`. Start from a clean branch and fetch tags:
-
-```bash
-git status --short
-git fetch upstream --tags
-git tag --list 'v<upstream-minor>.*'
-git switch -c sync/upstream-<version> main
-```
-
-Extract the upstream coding-agent subtree into a temporary directory without changing the current checkout:
-
-```bash
-tmp="$(mktemp -d)"
-git archive v<version> packages/coding-agent | tar -x -C "$tmp"
-```
-
-Review `$tmp/packages/coding-agent/` against the standalone root. Import upstream changes in bounded groups:
-
-1. Review source and tests, paying special attention to the hybrid hotspots above.
-2. Update product/API documentation and examples while retaining distribution-specific references.
-3. Adapt upstream package and TypeScript changes to the standalone root rather than copying monorepo-relative paths.
-4. Set the exact `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, and `@earendil-works/pi-tui` versions published for that upstream release.
-5. Run `npm install --ignore-scripts` to refresh `npm-shrinkwrap.json`, then inspect dependency and lifecycle-script changes.
-
-Do not copy these upstream monorepo assumptions into the standalone repository:
-
-- workspace declarations or `packages/*` paths;
-- TypeScript or Vitest aliases to sibling source workspaces;
-- Server, storage, model-catalog, binary, or multi-package release scripts;
-- cross-package source modifications needed only by an unreleased upstream checkout.
-
-If imported coding-agent code requires an API absent from the published upstream dependencies, stop and use a later compatible release. Do not solve the mismatch by vendoring or locally forking another package.
-
-## Conflict policy
-
-When reconciling upstream changes:
-
-1. Preserve security fixes, protocol correctness, execution semantics, and public API compatibility first.
-2. Keep local behavior only where it is intentionally documented and tested.
-3. For native UI, integrate upstream execution changes before adapting presentation.
-4. Keep model-facing output bounded and avoid schema/result changes for display-only work.
-5. Prefer a small local type intersection or adapter over changing an upstream dependency API.
-
-Git may detect many imports as renames from the historical `packages/coding-agent` path. Review content, not rename percentages.
-
-## Dependency and lock maintenance
-
-All direct registry dependencies are exact. When package metadata changes:
-
-```bash
-npm install --ignore-scripts
-npm run check:pinned-deps
-```
-
-`npm-shrinkwrap.json` is both the development lock and the lock published with `@astralyn/pi`. Review new or changed transitive packages, platform-specific optional packages, and lifecycle scripts before accepting it. The pre-commit hook requires an explicit `PI_ALLOW_LOCKFILE_CHANGE=1` acknowledgment when committing an intentional shrinkwrap change.
-
-## Verification
-
-At minimum:
-
-```bash
-npm run build
-npm run check
-```
-
-Run focused tests for each changed subsystem. For native transcript changes, verify pending, success, error, collapsed, and expanded states, plus `Ctrl+O`, `/reload`, and `/tree` in a real TTY. The Ubuntu CI workflow runs Build, Check, and the full test suite.
-
-Before integrating a synchronization branch:
-
-```bash
-git status --short
-git diff --stat main...HEAD
-git log --oneline main..HEAD
-```
-
-## Changelog and release ownership
-
-- `CHANGELOG.md` is the runtime and release changelog for `@astralyn/pi`.
-- `docs/**` remains structurally close to upstream coding-agent user/API documentation.
-- `docs/distribution/**` records standalone architecture, bundled behavior, maintenance, and release operations.
-- Dependency package changelogs are not copied; consult their upstream releases during synchronization.
-
-After synchronization and verification, follow the [release checklist](release.md).

package/docs/distribution/release.md

@@ -1,85 +0,0 @@
-# Release checklist
-
-This repository publishes one npm package from its root: `@astralyn/pi`. It does not use the upstream multi-package, binary, source-archive, or model-catalog release flows. Upstream synchronization is documented in [maintenance.md](maintenance.md).
-
-## Scope and versioning
-
-Track the upstream Pi `major.minor` line and reserve the patch number for this distribution's release sequence:
-
-```text
-upstream 0.82.x -> Fork 0.82.0, 0.82.1, 0.82.2, ...
-upstream 0.83.x -> Fork 0.83.0, 0.83.1, 0.83.2, ...
-```
-
-The first distribution release after moving to a new upstream minor uses patch `0`. Every later release on that line uses the next unused patch, including releases that absorb an upstream patch update. Use `pi-v<full-version>` Git tags so they remain distinct from fetched upstream tags such as `v0.82.0`.
-
-## Prepare the release
-
-1. Start from a clean `main` branch and choose the next unused distribution version.
-2. Move current `CHANGELOG.md` entries from `[Unreleased]` into one `## [<version>] - YYYY-MM-DD` section, then leave a new empty `[Unreleased]` section.
-3. Update `package.json` version.
-4. Refresh and review the authoritative shrinkwrap:
-
-```bash
-npm install --package-lock-only --ignore-scripts
-```
-
-Direct dependencies are exact. If a synchronized upstream release is still blocked by the `.npmrc` age gate, prefer waiting; use `--min-release-age=0` only after explicitly verifying the package versions, provenance, and release contents.
-
-Confirm `package.json` and the root entry in `npm-shrinkwrap.json` carry the same `@astralyn/pi` version and that the intended exact upstream AI, Agent core, and TUI versions are locked.
-
-## Verify
-
-Local development verification:
-
-```bash
-npm run build
-npm run check
-```
-
-Release verification runs on Ubuntu through GitHub Actions. The CI and publish workflows both install from `npm-shrinkwrap.json`, build, check, verify that generated files remain clean, and run the complete test suite.
-
-## Review the package
-
-After building, inspect the root package:
-
-```bash
-npm pack --dry-run
-```
-
-The tarball must contain the built `dist`, product documentation, examples, README, changelog, and `npm-shrinkwrap.json`. It must not contain source workspaces or local configuration. For stronger verification, create a real tarball, install it in a temporary directory outside the repository, and run `pi --version` and `pi --list-models`.
-
-## Publish and tag
-
-Publishing uses npm Trusted Publishing through GitHub Actions OIDC. Configure the package once on npm:
-
-```text
-Publisher: GitHub Actions
-Organization or user: ming-kang
-Repository: pi
-Workflow filename: publish-npm.yml
-Environment name: (blank)
-Allowed action: Allow npm publish
-```
-
-After the release commit is pushed and CI passes, trigger the workflow from an authenticated GitHub CLI session:
-
-```bash
-gh workflow run publish-npm.yml --repo ming-kang/pi --ref main -f version=0.82.0
-
-gh run list --repo ming-kang/pi --workflow publish-npm.yml --limit 1
-gh run watch <run-id> --repo ming-kang/pi --exit-status
-```
-
-The workflow validates the requested version, repeats Ubuntu Build/Check/Test, publishes the repository root with provenance, and verifies the registry version. A normal push to `main` never publishes.
-
-After publication, verify the registry and perform a global-install/self-update smoke test from a separate shell or after restarting Pi. Do not replace the package currently running the release session.
-
-Finally tag the exact release commit:
-
-```bash
-git tag pi-v<full-version>
-git push origin pi-v<full-version>
-```
-
-No other package is published from this repository.