@pasko70/pibo 1.1.0 → 1.3.0

package/docs/README.md

@@ -0,0 +1,23 @@
+# Pibo Documentation
+
+This directory is the single home for project documentation, specs, plans, and reports.
+
+## Structure
+
+```text
+docs/
+  project/  Normal/current project docs and other canonical documentation
+  specs/    Product, technical, and implementation specifications
+  plans/    Implementation plans and design plans
+  reports/  Investigation reports, validation reports, and generated report artifacts
+  legacy/   Previous documentation set kept for reference
+```
+
+## Rules
+
+- Put normal/current project docs and other canonical documentation in `docs/project/`.
+- Put specifications in `docs/specs/`.
+- Put implementation plans in `docs/plans/`.
+- Put investigation, validation, and incident reports in `docs/reports/`.
+- Do not create new root-level `plans/`, `reports/`, or `specs/` directories.
+- Do not delete legacy docs unless there is a separate cleanup decision.

package/docs/ops/install-developer-host.md

@@ -0,0 +1,112 @@
+# Install Pibo as a Developer Host
+
+Use this path when the host is used to develop Pibo itself.
+
+## Philosophy
+
+Production must stay stable while development moves quickly. The dev gateway can restart, fail, or deploy the `dev` branch without interrupting the main production gateway.
+
+Docker compute workers are part of the developer setup. Each agent should get its own isolated container and gateway so agent restarts do not disturb other agents or the host gateways.
+
+## Target layout
+
+```text
+/root/code/pibo                  main / production
+/root/code/pibo/.worktrees/dev   dev / development
+
+/root/.pibo                      production data
+/root/.pibo-dev                  development data
+
+pibo-web.service                 prod web 4788, gateway 4789
+pibo-web-dev.service             dev web 4808, gateway 4809
+```
+
+## Remotes
+
+Each developer host should use its own fork as `origin` and the canonical repo as `upstream`:
+
+```text
+origin    git@github.com:<server-or-user-fork>/pibo.git
+upstream  git@github.com:Pascapone/pibo.git
+```
+
+## Plan the setup
+
+```bash
+pibo setup developer-host \
+  --origin git@github.com:<server-or-user-fork>/pibo.git \
+  --upstream git@github.com:Pascapone/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --print-files
+```
+
+Review the generated systemd units, dev start wrapper, environment template, and Caddyfile. Stage files before applying when testing a fresh host:
+
+```bash
+pibo setup developer-host \
+  --origin git@github.com:<server-or-user-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --write-to /tmp/pibo-setup
+```
+
+Apply after review:
+
+```bash
+pibo setup developer-host \
+  --origin git@github.com:<server-or-user-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --apply --yes
+systemctl daemon-reload
+```
+
+## Important detail: service pinning
+
+Do not globally install the dev worktree over the production install. `npm install -g .` from a local checkout creates a global symlink to that checkout; running it again from the dev worktree can accidentally move `/usr/bin/pibo` to dev.
+
+The generated developer services avoid this by pinning production to:
+
+```text
+/usr/bin/node /root/code/pibo/dist/bin/pibo.js
+```
+
+and dev to the wrapper in `/usr/local/bin/pibo-web-dev-start.mjs`, which imports the dev worktree directly.
+
+Run this in each checkout/worktree instead:
+
+```bash
+npm ci
+npm run build
+```
+
+## Important detail: dev internal gateway port
+
+Do not start dev only with:
+
+```bash
+pibo gateway:web --web-port 4808
+```
+
+That changes the web port but leaves the internal gateway at the default `4789`, which collides with production. The generated developer setup uses a wrapper that calls `runWebGatewayServer` with:
+
+```text
+web port:      4808
+internal port: 4809
+```
+
+## Validate
+
+```bash
+systemctl is-active pibo-web
+systemctl is-active pibo-web-dev
+pibo gateway web status
+PIBO_GATEWAY_DEV_PORT=4808 pibo gateway dev status
+pibo setup doctor --domain pibo.example.com --dev-domain dev.pibo.example.com --expected-ip <server-ip> --require-docker --min-swap-gb 8
+pibo compute spawn --help
+```
+
+DNS must point to the host before Caddy can issue public certificates.
+
+Docker and swap are developer-host prerequisites only. User-host installs can ignore Docker and swap. The setup command does not create swap automatically; provision it at the OS level, then verify it with `pibo setup doctor --min-swap-gb 8`.

package/docs/ops/install-user-host.md

@@ -0,0 +1,76 @@
+# Install Pibo as a User Host
+
+Use this path when you want to run Pibo, not develop Pibo itself.
+
+## What this installs
+
+A user host has one gateway and one data directory:
+
+```text
+/root/.pibo
+pibo-web.service
+127.0.0.1:4788  web app
+127.0.0.1:4789  internal gateway
+```
+
+It does not require Docker, a dev gateway, a GitHub App, or branch worktrees.
+
+## Recommended flow
+
+```bash
+npm install -g @pasko70/pibo
+pibo setup doctor --domain pibo.example.com --expected-ip <server-ip>
+pibo setup user-host --domain pibo.example.com --print-files
+```
+
+Review the generated files before installing them. To stage the exact paths without touching the host, use:
+
+```bash
+pibo setup user-host --domain pibo.example.com --write-to /tmp/pibo-setup
+find /tmp/pibo-setup -type f -maxdepth 5 -print
+```
+
+After review, apply directly on the host with:
+
+```bash
+pibo setup user-host --domain pibo.example.com --apply --yes
+systemctl daemon-reload
+```
+
+## Configure auth
+
+```bash
+pibo config set auth.baseURL https://pibo.example.com
+pibo config set auth.secret <at-least-32-characters>
+pibo config set auth.googleClientId <google-client-id>
+pibo config set auth.googleClientSecret <google-client-secret>
+pibo config set auth.allowedEmails you@example.com
+```
+
+## Start the gateway
+
+`pibo-web` will not start until Better Auth config is complete. This cannot be automated because you must create/select your Google OAuth client and allowed user list. Check it first:
+
+```bash
+pibo setup doctor --pibo-home /root/.pibo
+```
+
+If auth is incomplete, the doctor prints a hard blocker and the exact missing keys. After installing the rendered systemd unit:
+
+```bash
+systemctl daemon-reload
+systemctl enable --now pibo-web
+pibo gateway web status
+```
+
+If you use Caddy, point DNS at the host before expecting Let's Encrypt to issue a certificate.
+
+## When not to use this path
+
+Use the developer-host path if you need:
+
+- a separate dev gateway;
+- Docker compute workers;
+- multiple agents working in isolated containers;
+- GitHub App PR automation;
+- `main` and `dev` branch deployment on the same host.

package/docs/ops/upgrade-user-to-developer-host.md

@@ -0,0 +1,69 @@
+# Upgrade a User Host to a Developer Host
+
+A normal npm-installed Pibo host can be upgraded later. The upgrade must preserve the production gateway and add development infrastructure next to it.
+
+## Starting point
+
+```text
+/root/.pibo
+pibo-web.service
+```
+
+## Target point
+
+```text
+/root/.pibo                      unchanged production data
+/root/.pibo-dev                  new development data
+/root/code/pibo                  source checkout on main
+/root/code/pibo/.worktrees/dev   source worktree on dev
+pibo-web.service                 existing production service
+pibo-web-dev.service             new development service
+Docker                           installed for compute workers
+```
+
+## Plan first
+
+```bash
+pibo setup developer-host \
+  --origin git@github.com:<server-or-user-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --print-files
+
+pibo setup developer-host \
+  --origin git@github.com:<server-or-user-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --write-to /tmp/pibo-setup
+```
+
+## Upgrade rules
+
+- Do not replace `/root/.pibo`.
+- Do not stop production unless a user approves it.
+- Create `/root/.pibo-dev` separately.
+- Keep `pibo-web` on `4788/4789`.
+- Start `pibo-web-dev` on `4808/4809`.
+- Install Docker only for the developer path.
+- Provision swap at the OS level for developer hosts, then verify it with `--min-swap-gb 8`.
+- Build each checkout with `npm ci && npm run build`; do not globally install the dev worktree over production.
+- Keep generated services pinned to branch-specific entrypoints instead of relying on one mutable global `pibo` symlink.
+- Keep `origin` pointed at the host-specific fork.
+- Keep `upstream` pointed at `git@github.com:Pascapone/pibo.git`.
+
+## Validation
+
+```bash
+pibo setup doctor --domain pibo.example.com --dev-domain dev.pibo.example.com --expected-ip <server-ip> --require-docker --min-swap-gb 8
+pibo gateway web status
+PIBO_GATEWAY_DEV_PORT=4808 pibo gateway dev status
+docker --version
+pibo compute spawn --help
+```
+
+After DNS is updated, check both browser URLs:
+
+```text
+https://pibo.example.com/apps/chat
+https://dev.pibo.example.com/apps/chat
+```

package/docs/ops/vscode-extension-release.md

@@ -0,0 +1,138 @@
+# Pibo VS Code Extension Release Runbook
+
+The Pibo VS Code extension is shipped as a `.vsix` artifact. This runbook describes the end-to-end release process and the split of responsibilities between the maintainer and the `pibo` release script.
+
+## Distribution channels
+
+The extension is published through two channels that are intentionally separate:
+
+| Channel | Owner | Cadence | What it carries |
+|---|---|---|---|
+| npm `@pasko70/pibo` | automated via `npm publish` (or the release script's `--publish-npm` flag) | every `main` commit that includes a version bump | the `pibo` CLI, the gateway, the WebView bundle at `dist/apps/chat-vscode-web/` |
+| VS Code Marketplace `pibo.pibo-vscode` | **maintainer uploads the VSIX manually** via <https://marketplace.visualstudio.com/manage> | every release that needs the extension UI updated | the `.vsix` produced by `npm run vscode:package` |
+
+The npm package and the Marketplace extension are versioned together. The release script bumps both `package.json` (npm) and `src/apps/chat-vscode/package.json` (extension) in one go so the published artifacts stay in lockstep.
+
+`pibo vscode install` (new since the distribution rework) downloads the VSIX from the GitHub Release for the configured repo (`Pascapone/pibo` by default). When the maintainer also uploads the same VSIX to the Marketplace, both channels serve identical bytes.
+
+## Versioning
+
+- The root `package.json#version` is the npm version. It follows [SemVer](https://semver.org/).
+- The extension's `src/apps/chat-vscode/package.json#version` is the Marketplace version. It is kept equal to the npm version (the release script enforces this).
+- A SemVer **minor** bump (e.g., `1.2.0` → `1.3.0`) is appropriate when the change is additive and backward-compatible. The distribution rework itself is a minor bump: existing `pibo` users are unaffected, and the new `pibo vscode install` command is opt-in.
+- A SemVer **major** bump is reserved for breaking changes to either the public CLI surface or the WebView host↔Web postMessage contract.
+
+## Release steps
+
+The release script does the heavy lifting. The maintainer's job is to review, commit, and push.
+
+### 1. Pick the version
+
+Decide on the next version. For the distribution rework that introduces `pibo vscode install`, the right bump is `1.2.0` → `1.3.0` (new CLI command, new marketplace-ready extension, no breaking changes).
+
+### 2. Bump + build + package (local)
+
+From the repo root:
+
+```bash
+node scripts/release.mjs --version 1.3.0
+```
+
+The script:
+
+1. Reads the current version from both `package.json` files.
+2. Writes the new version to both files.
+3. Runs `npm run build` (which includes the WebView build).
+4. Runs `npm run vscode:package` to produce `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix` and a stable `latest.vsix` copy.
+5. Prints the VSIX path and size.
+
+The script does **not** push to git or create a tag. The maintainer reviews the diff and commits it.
+
+### 3. Commit and tag
+
+```bash
+git add package.json src/apps/chat-vscode/package.json
+git commit -m "chore(release): bump @pasko70/pibo and pibo.pibo-vscode to 1.3.0"
+git tag -a v1.3.0 -m "@pasko70/pibo 1.3.0"
+git push origin main
+git push origin v1.3.0
+```
+
+### 4. Create a GitHub Release with the VSIX attached
+
+```bash
+gh release create v1.3.0 \
+  dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix \
+  --title "pibo 1.3.0" \
+  --notes "..."
+```
+
+This makes the VSIX downloadable from a stable URL (`https://github.com/Pascapone/pibo/releases/download/v1.3.0/pibo-vscode-1.3.0.vsix`). The `pibo vscode install` command uses the GitHub Releases API to discover this URL automatically.
+
+The release script can also do this in one step:
+
+```bash
+node scripts/release.mjs --version 1.3.0 --create-release
+```
+
+…if the tag has already been pushed.
+
+### 5. Publish the npm package
+
+```bash
+npm publish
+```
+
+Or, in one go with the release script:
+
+```bash
+node scripts/release.mjs --version 1.3.0 --publish-npm --create-release
+```
+
+The publish step uploads the `pibo` CLI, the gateway plugins, and the WebView bundle. The Marketplace upload is intentionally **not** automated — see step 6.
+
+### 6. Upload the VSIX to the VS Code Marketplace (manual)
+
+The Marketplace does not currently accept a Personal Access Token from this account (Azure-side provisioning issue). The release is therefore finished by uploading the VSIX through the Marketplace web UI:
+
+1. Open <https://marketplace.visualstudio.com/manage>.
+2. Pick the publisher `pibo` (created during the first marketplace publish).
+3. Click **Upload new extension** and select `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix`.
+4. The Marketplace validates the manifest and publishes the extension. The publisher ID is `pibo.pibo-vscode`.
+
+After the upload, `code --install-extension pibo.pibo-vscode` works for end users.
+
+### 7. Verify
+
+```bash
+pibo vscode install --vsix dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix
+pibo vscode status
+```
+
+Confirm that `status` reports `pibo.pibo-vscode@1.3.0` installed via the expected `code` binary, and that the WebView loads the gateway at `http://127.0.0.1:4788/apps/chat-vscode/`.
+
+## Rollback
+
+If a release is broken:
+
+- **npm**: `npm unpublish @pasko70/pibo@1.3.0` works only within 72 hours of publish. After that, publish `1.3.1` with a fix.
+- **VSIX via `pibo vscode install`**: delete the GitHub Release and re-create it with a fixed VSIX. Users who have already installed the extension will not auto-update until they run `pibo vscode install` again.
+- **Marketplace**: the Marketplace UI supports un-publishing or un-listing. For a fast fix, upload a corrected `.vsix` with the same version (the Marketplace accepts a re-upload before processing the original).
+
+## What ships in the `pibo` npm package
+
+The `files` whitelist in `package.json` controls what is published:
+
+- `dist/` — the compiled server, the gateway plugins, the WebView bundles (chat-ui, context-files-ui, chat-vscode-web).
+- `context/` — the bundled agent skills.
+- `skills/builtin/**` — built-in user skills.
+- `docs/ops/**` — operator runbooks.
+- `README.md` and `src/mcp/LICENSE.mcp-cli`.
+
+The `.vsix` is **not** in the npm package. It lives on the GitHub Release and (after the maintainer uploads it) on the VS Code Marketplace.
+
+## Why the WebView bundle is in the npm package
+
+The extension's WebView loads from `http://<gateway>/apps/chat-vscode/`, not from the `.vsix`. The gateway serves the bundle out of `dist/apps/chat-vscode-web/`. If the bundle were not in the npm package, the gateway would return 404 for the WebView and the extension would be unusable.
+
+Including the bundle in npm costs about 1 MB of disk per `pibo` install and zero runtime cost for users who never open the extension. Users who only use the `pibo` CLI never load the bundle.

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@pasko70/pibo",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Minimal TypeScript wrapper around Pi Coding Agent.",
   "files": [
     "dist",
     "context",
-    "skills/builtin/pi-agent-harness/SKILL.md",
-    "skills/builtin/pi-agent-harness/agents/openai.yaml",
+    "skills/builtin/**",
+    "docs/ops/**",
     "README.md",
     "src/mcp/LICENSE.mcp-cli"
   ],
   "bin": {
-    "pibo": "dist/bin/pibo.js"
+    "pibo": "dist/bin/pibo.js",
+    "rg": "dist/bin/rg.js"
   },
   "engines": {
     "node": ">=24"
@@ -31,16 +32,24 @@
     "context-files-ui:build": "vite build --config src/apps/context-files-ui/vite.config.ts",
     "context-files-ui:typecheck": "tsc -p src/apps/context-files-ui/tsconfig.json --noEmit",
     "web-ui:build": "npm run chat-ui:build && npm run context-files-ui:build",
-    "build": "tsc -p tsconfig.json && npm run web-ui:build",
+    "vscode:typecheck": "tsc -p src/apps/chat-vscode/extension/tsconfig.json --noEmit && tsc -p src/apps/chat-vscode/extension/webview/tsconfig.json --noEmit",
+    "vscode:webview:build": "vite build --config src/apps/chat-vscode/extension/webview/vite.config.ts",
+    "vscode:extension:build": "esbuild src/apps/chat-vscode/extension/src/extension.ts --bundle --platform=node --target=node24 --format=cjs --outfile=src/apps/chat-vscode/dist/extension/extension.cjs --external:vscode --sourcemap=inline",
+    "vscode:package": "node scripts/vscode-package.mjs",
+    "release": "node scripts/release.mjs",
+    "build": "tsc -p tsconfig.json && npm run web-ui:build && npm run vscode:webview:build && node scripts/ensure-bin-executable.mjs",
     "start": "node dist/bin/pibo.js",
-    "test": "npm run build && node --test test/*.test.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit && npm run chat-ui:typecheck && npm run context-files-ui:typecheck",
+    "test": "npm run build && node --test test/*.test.mjs test/chat-vscode/*.test.mjs",
+    "check:product-vocab": "node scripts/legacy-product-vocabulary-gate.mjs",
+    "validate:ink-web-derived": "node scripts/ink-cli-web-derived-parity-validate.mjs",
+    "compute:limited-worker-smoke": "node scripts/compute-limited-worker-smoke.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && npm run chat-ui:typecheck && npm run context-files-ui:typecheck && npm run vscode:typecheck",
     "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@mariozechner/pi-ai": "^0.70.2",
-    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "@mariozechner/pi-ai": "^0.73.1",
+    "@mariozechner/pi-coding-agent": "^0.73.1",
     "@mdxeditor/editor": "^3.55.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@tailwindcss/vite": "^4.2.4",
@@ -48,14 +57,18 @@
     "@tanstack/react-router": "^1.168.25",
     "@tanstack/react-start": "^1.167.50",
     "@uiw/react-json-view": "^2.0.0-alpha.41",
+    "@vscode/ripgrep": "^1.18.0",
+    "@xyflow/react": "12.10.2",
     "better-auth": "^1.6.9",
     "commander": "^14.0.3",
+    "ink": "^7.0.3",
     "lexical": "^0.35.0",
     "lucide-react": "^0.545.0",
     "prismjs": "^1.30.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "react-markdown": "^10.1.0",
+    "react-virtuoso": "^4.18.6",
     "remark-gfm": "^4.0.1",
     "tailwindcss": "^4.2.4"
   },
@@ -66,6 +79,8 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
+    "@vscode/vsce": "^3.6.0",
+    "esbuild": "^0.27.7",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.10",

package/skills/builtin/pi-agent-harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-agent-harness
-description: Use when designing, specifying, implementing, or reviewing a modular system built around Pi Coding Agent / Pi Agent as an embedded agent engine. Trigger for Pi Agent docking, createAgentSession, custom tools, SessionManager, ResourceLoader, ExtensionRunner, Pi events, OpenClaw-style harnesses, plugin ecosystems, web chat channels, MCP/tool adapters, system prompt ownership, policy layers, or minimal runtimes around packages/coding-agent.
+description: Use when designing, specifying, implementing, or reviewing a modular system built around Pi Coding Agent / Pi Agent as an embedded agent engine. Trigger for Pi Agent docking, createAgentSession, custom tools, SessionManager, ResourceLoader, ExtensionRunner, Pi events, OpenClaw-style harnesses, plugin ecosystems, web chat channels, MCP/tool adapters, system prompt stewardship, policy layers, or minimal runtimes around packages/coding-agent.
 ---
 
 # Pi Agent Harness
@@ -26,34 +26,34 @@ Read only what the task needs. These are the important paths:
 
 Pi product layer:
 
-- `/home/pibo/code/pi-mono/packages/coding-agent/README.md` - product philosophy: minimal core, modes, skills, extensions, explicit tools.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/main.ts` - CLI entry and mode dispatch.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/core/sdk.ts` - `createAgentSession(...)`, SDK options, model/auth/settings wiring.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/core/agent-session.ts` - prompt pipeline, event persistence, compaction, tool registry, extension integration.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/core/session-manager.ts` - append-only JSONL session tree, branch/fork/compaction context.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/core/resource-loader.ts` - loads context files, skills, prompts, themes, extensions, `SYSTEM.md`, `APPEND_SYSTEM.md`.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/core/system-prompt.ts` - default prompt builder and tool/context/skill prompt assembly.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/core/extensions/types.ts` - extension contract and event names.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/core/extensions/runner.ts` - extension lifecycle, stale-context guard, event dispatch.
-- `/home/pibo/code/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts` - TUI integration, commands, selectors, rendering of events.
+- `<HOME>/code/pi-mono/packages/coding-agent/README.md` - product philosophy: minimal core, modes, skills, extensions, explicit tools.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/main.ts` - CLI entry and mode dispatch.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/core/sdk.ts` - `createAgentSession(...)`, SDK options, model/auth/settings wiring.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/core/agent-session.ts` - prompt pipeline, event persistence, compaction, tool registry, extension integration.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/core/session-manager.ts` - append-only JSONL session tree, branch/fork/compaction context.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/core/resource-loader.ts` - loads context files, skills, prompts, themes, extensions, `SYSTEM.md`, `APPEND_SYSTEM.md`.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/core/system-prompt.ts` - default prompt builder and tool/context/skill prompt assembly.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/core/extensions/types.ts` - extension contract and event names.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/core/extensions/runner.ts` - extension lifecycle, stale-context guard, event dispatch.
+- `<HOME>/code/pi-mono/packages/coding-agent/src/modes/interactive/interactive-mode.ts` - TUI integration, commands, selectors, rendering of events.
 
 Lower engine layers:
 
-- `/home/pibo/code/pi-mono/packages/agent/src/agent.ts` - stateful agent wrapper, `subscribe`, `prompt`, `steer`, `followUp`.
-- `/home/pibo/code/pi-mono/packages/agent/src/agent-loop.ts` - turn loop, streaming, tool execution, event emission.
-- `/home/pibo/code/pi-mono/packages/ai/src/stream.ts` - provider dispatch.
-- `/home/pibo/code/pi-mono/packages/tui/src/tui.ts` - terminal rendering if building TUI surfaces.
+- `<HOME>/code/pi-mono/packages/agent/src/agent.ts` - stateful agent wrapper, `subscribe`, `prompt`, `steer`, `followUp`.
+- `<HOME>/code/pi-mono/packages/agent/src/agent-loop.ts` - turn loop, streaming, tool execution, event emission.
+- `<HOME>/code/pi-mono/packages/ai/src/stream.ts` - provider dispatch.
+- `<HOME>/code/pi-mono/packages/tui/src/tui.ts` - terminal rendering if building TUI surfaces.
 
 OpenClaw reference pattern:
 
-- `/home/pibo/docs/research/tools/openclaw-pi-agent-docking-concept.md` - concise docking analysis.
-- `/home/pibo/code/openclaw/src/agents/pi-embedded-runner/run/attempt.ts` - embedded runner assembly.
-- `/home/pibo/code/openclaw/src/agents/pi-tools.ts` - OpenClaw tool catalog assembler.
-- `/home/pibo/code/openclaw/src/agents/pi-tool-definition-adapter.ts` - OpenClaw tool to Pi `ToolDefinition` adapter.
-- `/home/pibo/code/openclaw/src/agents/pi-embedded-runner/tool-split.ts` - custom-tool authority pattern.
-- `/home/pibo/code/openclaw/src/agents/pi-embedded-runner/system-prompt.ts` - external system prompt ownership.
-- `/home/pibo/code/openclaw/src/agents/pi-embedded-subscribe.ts` - Pi event subscription to product output.
-- `/home/pibo/code/openclaw/src/plugins/types.ts` - broad plugin-hook vocabulary, useful as design reference.
+- `<HOME>/docs/research/tools/openclaw-pi-agent-docking-concept.md` - concise docking analysis.
+- `<HOME>/code/openclaw/src/agents/pi-embedded-runner/run/attempt.ts` - embedded runner assembly.
+- `<HOME>/code/openclaw/src/agents/pi-tools.ts` - OpenClaw tool catalog assembler.
+- `<HOME>/code/openclaw/src/agents/pi-tool-definition-adapter.ts` - OpenClaw tool to Pi `ToolDefinition` adapter.
+- `<HOME>/code/openclaw/src/agents/pi-embedded-runner/tool-split.ts` - custom-tool authority pattern.
+- `<HOME>/code/openclaw/src/agents/pi-embedded-runner/system-prompt.ts` - external system prompt stewardship.
+- `<HOME>/code/openclaw/src/agents/pi-embedded-subscribe.ts` - Pi event subscription to product output.
+- `<HOME>/code/openclaw/src/plugins/types.ts` - broad plugin-hook vocabulary, useful as design reference.
 
 ## Mental Model
 
@@ -159,7 +159,7 @@ For MCP, browser tools, filesystem tools, subprocesses, message sending, or host
 
 OpenClaw reference: `src/agents/pi-tool-definition-adapter.ts`.
 
-## Prompt Ownership
+## Prompt Stewardship
 
 Pi can build a good default system prompt, but a product harness usually needs one explicit runtime contract.