@pasko70/pibo 1.0.5 → 1.2.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/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@pasko70/pibo",
-  "version": "1.0.5",
+  "version": "1.2.0",
   "type": "module",
   "description": "Minimal TypeScript wrapper around Pi Coding Agent.",
   "files": [
     "dist",
     "context",
-    ".codex/skills/pi-agent-harness/SKILL.md",
-    ".codex/skills/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,23 @@
     "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": "vsce package --no-dependencies",
+    "build": "tsc -p tsconfig.json && npm run web-ui: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 +56,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,9 +78,11 @@
     "@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",
     "vite-tsconfig-paths": "^5.1.4"
   }
-}
+}

package/{.codex/skills → 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.
 

package/skills/builtin/pibo-docker-system/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: pibo-docker-system
+description: Use this skill for Pibo Docker Compute System work, isolated implementation, worker worktrees, Chat Web or gateway testing, worker dev auth, browser/CDP validation, resource cleanup, and when coordinating Docker worker use with the github-server-flow strategy.
+---
+
+# Pibo Docker Compute System
+
+Use Docker compute workers as the isolated execution boundary for Pibo code work, gateway checks, Chat Web validation, browser automation, and end-to-end tests. Keep Docker-specific operating rules here instead of duplicating them in `AGENTS.md`.
+
+## Relationship to GitHub flow
+
+Use this skill together with `github-server-flow`:
+
+- `github-server-flow` owns branch, PR, fork mirror, and release strategy.
+- `pibo-docker-system` owns where implementation and validation run.
+- Normal code work starts from `upstream/dev` on a focused branch, then runs inside a Docker dev worker.
+- Do not use `origin/dev` as a preview or staging branch just to test work. Push focused branches to `origin` and open PRs to `upstream/dev`.
+- Documentation-only edits do not require a Docker worker unless they are coupled to code, build, gateway, or browser validation.
+
+### Worker branch pattern
+
+`pibo compute dev spawn --worktree <name>` creates or attaches a Git worktree and uses `<name>` as the local branch name. Because container names and worktree names should be simple, prefer a slash-free local worker branch and push it to a slash-based PR branch when ready.
+
+Recommended pattern:
+
+```bash
+cd /root/code/pibo
+git fetch origin --prune
+git fetch upstream --prune
+
+# Use a slash-free local branch/worktree name created from upstream/dev.
+git branch <short-topic> upstream/dev
+pibo compute dev spawn --worktree <short-topic>
+
+# Work in the returned worktree, then push as a focused PR branch.
+cd /root/code/pibo/.worktrees/<short-topic>
+git push -u origin HEAD:feature/<short-topic>
+```
+
+If the local branch already exists and points at the intended base, `pibo compute dev spawn --worktree <short-topic>` attaches a worktree for it. If it does not exist, the compute CLI creates it from the current checkout, so pre-create the branch from `upstream/dev` when strict upstream-first history matters.
+
+## Commands
+
+Discover progressively with the CLI first:
+
+```bash
+pibo compute --help
+pibo compute dev --help
+pibo compute dev spawn --help
+```
+
+Common commands:
+
+- `pibo compute spawn [--name <name>]` — create a short-lived worker container. It is useful for isolated checks but does not create the development worktree flow.
+- `pibo compute dev spawn --worktree <name>` — create a long-lived dev worker with a Git worktree and deterministic port block.
+- `pibo compute rebuild` — force a fresh Docker image build.
+- `pibo compute list` / `pibo compute list --all` — inspect worker and dev-worker containers.
+- `pibo compute release <id>` — stop and remove the named worker container. This does not delete the Git worktree.
+- `pibo compute reap --dry-run` — preview worker cleanup.
+- `pibo compute reap --apply` — apply selected cleanup. Dev workers are excluded unless the command explicitly includes them.
+- `pibo compute health` / `pibo compute doctor` — read-only resource health checks.
+- `pibo compute diagnostics` / `pibo compute disk` — read-only Docker disk diagnostics.
+
+## Development rule
+
+Use a Docker dev worker for Pibo code and feature implementation whenever the compute system is available, especially for:
+
+- gateway changes;
+- Chat Web changes;
+- browser automation;
+- auth behavior;
+- runtime/session routing changes;
+- CLI/TUI changes that need realistic user-visible validation;
+- end-to-end checks.
+
+Do not edit the host checkout as an experimental workspace for code changes. Do not restart, replace, or run ad hoc host gateways for development unless the user explicitly requests host operations or Docker is unavailable. The host gateway is for observation and production/dev deployment only.
+
+## Worker lifecycle
+
+1. Start from the GitHub strategy: fetch remotes, create a focused branch from `upstream/dev`, and spawn a dev worker for that branch.
+2. Use the returned worktree for edits.
+3. Use the returned web and CDP ports for app and browser checks.
+4. Run builds/tests inside the worker worktree when the work requires runtime validation.
+5. Release the container with `pibo compute release <id>` when done.
+6. Keep, merge, push, or discard the Git worktree only after review or explicit user approval.
+
+Releasing a dev worker removes the container, not the worktree. Worktree deletion is a separate Git cleanup decision.
+
+## Gateway and deployment boundaries
+
+Host gateways are managed only through the Pibo CLI:
+
+```bash
+pibo gateway web status
+pibo gateway web start
+pibo gateway web restart
+pibo gateway dev status
+pibo gateway dev start
+pibo gateway dev restart
+```
+
+After Docker validation, use the host dev gateway for host-level testing:
+
+```bash
+./scripts/deploy-web-dev.sh
+pibo gateway dev restart
+```
+
+The hosted dev Chat URL is host-specific. Set `PIBO_DEV_PUBLIC_URL` or `PIBO_DEV_BASE_URL` in the environment or repo-local `.env.developer-host`; do not hard-code public hostnames in docs, scripts, or skills.
+
+Deploy production only after dev testing succeeds and the user approves it:
+
+```bash
+./scripts/deploy-web.sh
+pibo gateway web restart
+```
+
+If the production gateway restart is blocked because active agent work is running, ask the user before interrupting sessions. Do not bypass the CLI restart guard without explicit confirmation.
+
+## Dev auth boundary
+
+Dev auth belongs only to Docker workers.
+
+- `gateway:web` inside a worker enables dev auth through the Docker entrypoint's internal option.
+- `PIBO_DEV_AUTH` does not enable dev auth for normal host gateways.
+- Never start the host gateway with dev-auth flags or fake-auth infrastructure.
+- The normal host gateway must use Better Auth.
+- Dev-auth web access is loopback-only; if a worker web port is accidentally reached through a public reverse proxy, auth requests are rejected.
+
+If auth is needed inside a Docker worker, use the `pibo-debug-auth` skill rather than bypassing auth ad hoc.
+
+## Browser and app validation
+
+For Chat Web browser debugging while changing Pibo, start from the Docker dev worker when one is available. Use the worker's returned web/CDP ports so browser automation and gateway restarts stay isolated from host gateways.
+
+Useful validation evidence includes:
+
+- route visited;
+- visible state or DOM assertions;
+- screenshot path;
+- CDP target details;
+- request/response evidence;
+- terminal output for CLI/TUI flows.
+
+A gateway healthcheck only proves the service responds. For Web, CLI, TUI, gateway, runtime, auth, or agent-routing work, also verify user-visible behavior when feasible:
+
+- Use browser/CDP or browser-use for Web UI flows.
+- Use a pseudo-TTY or interactive shell for Ink/TUI flows.
+- Use the real command, API, router, or persistence path when the default path is locally testable.
+
+Fake/demo checks and healthchecks are useful supporting evidence, but do not treat them as final validation for a user-facing default path unless the real path is unavailable or explicitly out of scope.
+
+## Resource hygiene
+
+- Workers are intended to be bounded and recyclable.
+- Prefer `pibo compute release <id>` when you finish with a worker.
+- Use `pibo compute list --all` to inspect running, stopped, dirty, and OOM-killed workers.
+- Use `pibo compute reap --dry-run` before destructive cleanup.
+- Use `pibo compute health` and `pibo compute diagnostics --json` for read-only resource investigations.
+- Do not delete worktrees just because containers were released. Worktree cleanup must be explicit.
+
+## Source docs
+
+For exact product requirements and implementation details, read the canonical docs on demand:
+
+- `docs/specs/capabilities/docker-compute-workers.md`
+- `docs/specs/capabilities/standalone-docker-runtime.md`
+- `docs/project/compute-browser-resource-operating-model.md`
+- `docs/project/compute-browser-resource-rollout-checklist.md`
+- `src/skills/pibo-debug-auth/SKILL.md`