@pasko70/pibo 1.0.5 → 1.2.0

package/README.md

@@ -1,318 +1,174 @@
 # pibo
 
-Pibo turns Pi Coding Agent into an agent-native runtime with discoverable CLI tools, plugins, channels, and local gateways.
+Pibo is a thin product boundary around Pi Coding Agent. Pi remains the inner engine for model turns, tools, streaming, sessions, and compaction. Pibo adds profiles, plugins, channels, local gateways, web auth, and operator tooling.
 
-Pi remains the inner engine for model turns, tools, streaming, sessions, and compaction. Pibo owns the outer product boundary: profiles, plugin registration, channels, routing, Pibo Sessions, auth, policy, and transport-specific adapters.
+The default posture is intentionally powerful: Pibo is built for agentic coding and server operation, not for a restrictive sandbox. Install and run it as the Linux user that should own its state and credentials.
 
 ## Install
 
-Pibo V1 targets Node.js 24+.
+Pibo is distributed as an npm package:
 
 ```bash
 npm install -g @pasko70/pibo
 pibo --help
 ```
 
-For local development from source:
+The current package declares Node.js 24+. Some Linux distributions still ship Node 22 through `apt`, so install a recent Node release first when needed. A user-local Node/npm setup through `nvm`, `fnm`, or a user-writable npm prefix works well.
+
+For a user-local global npm prefix:
 
 ```bash
-npm install
-npm run build
-npm run start -- --help
+mkdir -p ~/.local
+npm config set prefix ~/.local
+export PATH="$HOME/.local/bin:$PATH"
+npm install -g @pasko70/pibo
 ```
 
-## Docs
-
-- `docs/architecture.md` describes the current runtime architecture and boundaries.
-- `docs/mcp.md` documents the MCP CLI and registry.
-- `docs/tools.md` documents curated external CLI tools.
-- `docs/pi-packages.md` documents registered Pi Coding Agent packages and per-agent selection.
-- `docs/agent-run-yield-spec.md` documents yielded agent runs and run-control tools.
-- `docs/chat-rooms-event-log.md` documents Chat Web rooms, default-room startup, durable chat events, unread cursors, SSE cursors, and idempotent sends.
-- `docs/codex-compact-terminal-design.md` documents the compact Codex-style Chat session view.
-- `docs/progress.md` is the short implementation status snapshot.
-
-## Scripts
-
-- `npm run dev` runs the TypeScript entrypoint with `tsx`.
-- `npm run profile` prints the selected profile with loaded skills, tools, and context files.
-- `npm run profile -- gateway-producer` prints the parked gateway producer profile.
-- `npm run profile -- run-yield-qa` prints the yielded-run QA profile with subagents.
-- `npm run tui` starts the Pi TUI through the pibo wrapper.
-- `npm run tui:gateway` starts the Pi TUI with the gateway producer profile.
-- `npm run gateway` starts the local pibo gateway daemon.
-- `npm run gateway:web` starts the local gateway with Better Auth, the same-origin web host, and the chat app.
-- `npm run client -- <piboSessionId>` starts a console client connected to the gateway.
-- `npm run dev -- mcp` lists configured MCP servers and tools.
-- `npm run dev -- tools` lists curated external CLI tools.
-- `npm run dev -- pi-packages` lists registered Pi Coding Agent packages.
-- `npm run dev -- debug` inspects local Pibo SQLite stores.
-- `npm run dev -- config keys` lists supported local config keys.
-- `npm run build` compiles to `dist/`.
-- `npm run start` runs the compiled entrypoint.
-- `npm test` builds and runs the test suite.
-- `npm run typecheck` checks TypeScript without emitting files.
-- `npm run clean` removes `dist/`.
-
-## Philosophy
-
-Keep the wrapper thin. Pi Coding Agent should remain the inner engine; pibo adds only the product boundary we actually need: profiles, plugins, channels, auth, policy, routing, and opt-in operator tooling.
-
-Optional integrations stay outside the core package until the user installs them. MCP servers, Python virtual environments, and third-party CLIs are configured on demand through `pibo mcp` and `pibo tools`, not bundled into pibo itself.
-
-## Plugin Layer
-
-`src/plugins/` contains the minimal static plugin layer. Built-in plugins register tools, subagents, skills, context files, profiles, gateway actions, event listeners, channels, auth services, and web apps through `PiboPluginRegistry`.
-
-This is an extension boundary, not a marketplace. Plugins are internal and statically loaded for now, which keeps the runtime simple while supporting web auth, web apps, new tools, new skills, subagents, and future transports.
-
-The gateway producer plugin is parked outside the default plugin registry. It remains available for explicit local gateway experiments through the `gateway-producer` profile.
-
-## Channels And Pibo Sessions
-
-Plugins can register channels through `api.registerChannel(...)`. A channel maps an external transport into pibo events and maps pibo output events back to that transport.
-
-The channel context exposes only the pibo boundary:
-
-- `emit(event)` sends a `PiboInputEvent` to the session router.
-- `subscribe(listener)` receives normalized `PiboOutputEvent` values.
-- `getSession(id)`, `createSession(...)`, `updateSession(...)`, `deleteSession(...)`, and `findSessions(...)` work with first-class Pibo Session records.
-- `getGatewayActions()` exposes discoverable execution actions for channel UIs.
-
-Pibo Sessions are stored in SQLite by default at `.pibo/pibo-sessions.sqlite`. A Pibo Session keeps product identity (`id`), technical Pi identity (`piSessionId`), channel, kind, profile, owner scope, optional parent/origin relationships, optional workspace, title, and plugin metadata.
-
-In the Chat Web App, personal sessions can be archived before deletion. Permanent deletion is available only for archived sessions and requires typing `Delete this session`; it removes the selected Pibo Session, child sessions, and their Chat Web read-model/event-log rows.
-
-The Chat Web App also has Pibo Rooms. Each user gets a locked `Personal Chat` room automatically. The personal room is shown separately from user-created rooms and cannot be renamed, archived, or deleted. User-created rooms can be archived first, then permanently deleted after typing the room name. Archived rooms remain inspectable and show their contained sessions, but they are read-only: no new sessions, messages, or execution actions can be started in that room. Permanent room deletion removes the room subtree, contained sessions, subagent session descendants, and Chat Web read-model/event-log rows.
-
-Within the Sessions area, the Chat Web App now has an internal session-view registry. The existing nested trace renderer remains the default `Trace` view, and the same `PiboSessionTraceView` data can also be rendered through a compact Codex-style `Terminal` view selected by `?view=trace|terminal` or by browser-local preference.
-
-Managed context files are now a first-class product capability. The `pibo.context-files` plugin exposes editable global and agent-scoped markdown context files through `/api/context-files`, stores managed-file metadata and revisions in `.pibo/context-files/context-files.sqlite`, and emits product events when managed files are created, changed, removed, or updated on disk. Plugin-shipped context files remain immutable source files; the product can create linked managed copies from them, track source hashes and link state, diff the managed copy against its source, reset back to source, restore older revisions, or adopt a changed source as the new managed baseline.
-
-The main source folders are:
-
-- `src/core/` for runtime, events, profiles, and session routing
-- `src/plugins/` for the static plugin registry and built-in plugins
-- `src/channels/` for channel contracts
-- `src/sessions/` for Pibo Session storage
-- `src/gateway/` for the local TCP gateway transport
-- `src/runs/` for yielded run tracking and run-control tools
-- `src/auth/`, `src/web/`, and `src/apps/` for Better Auth, the same-origin web host, and web apps
-
-## Agent Designer
-
-The Chat Web App includes an Agent Designer in the Agents area. It creates custom agents, persists them in `.pibo/chat-agents.sqlite`, and registers each saved agent as a dynamic profile for routed sessions.
-
-The Agents area uses one sidebar for both editable custom agents and read-only plugin profiles. Plugin profiles can be inspected with their registered tools, skills, context files, subagents, built-in tool mode, and run-control package state, then copied into a custom agent when changes are needed.
-
-Custom agent names are profile names. They must be lowercase kebab-case, such as `test-agent`, and are used consistently in the UI, session records, and backend profile registry. Legacy `custom-agent:agent_*` names remain aliases for existing agents.
-
-Custom agents can be archived before deletion. Archived custom agents are removed from the active profile catalog, cannot start new sessions, and become read-only until restored. Permanent deletion is available only for archived agents and requires typing the agent profile name; it deletes the custom agent and Chat sessions using that profile.
-
-The designer configures native Pibo agent capabilities only: plugin-registered tools, skills, context files, subagents, automatic local context-file loading, built-in Pi tool visibility, and capability packages such as `pibo-run-control`. Curated external CLI tools from `pibo tools` remain global operator tooling and are not selected per agent.
-
-The Chat Web App now also has a dedicated Context area at `/apps/chat/context`. It reuses the managed context-file APIs inside the main Chat UI shell so operators can create, edit, relocate, and remove managed context files without leaving the authenticated Chat Web App. Plugin context files are shown there as read-only sources, and both the Context area and Agent Designer can create linked managed copies when a user wants to customize shipped content safely.
-
-The Context area also exposes the Pibo Base Prompt. The library prompt lives at `context/pibo-system-prompt.md`; the Chat Web App can switch between that read-only library prompt and a persisted custom prompt stored under `.pibo/base-prompt.md`. Runtime prompt templates replace `{{availableTools}}` and `{{guidelines}}` from the active Pi/Pibo tool surface before project context and skills are appended.
-
-The Context area also exposes the Pibo Compaction Prompt. The library prompt lives at `context/pibo-compaction-prompt.md`; the Chat Web App can switch between that read-only library prompt and a persisted custom prompt stored under `.pibo/compaction-prompt.md`. At runtime Pibo handles Pi's `session_before_compact` hook and uses the active compaction prompt sections for summary creation, update-summary creation, and split-turn prefix summaries.
-
-## Profiles
-
-The default profile is registered by the core plugin. It loads the local `pi-agent-harness` skill and uses Pi Coding Agent's built-in tools for normal coding work.
-
-The `codex` alias resolves to the `codex-compat-openai-web` profile. It keeps the Pibo runtime boundary while exposing Codex-like coding affordances: Pi/Pibo `read`, `edit`, and `write`; Pibo run-control `bash`; native `web_search`; `apply_patch` and `view_image`; generated `pibo_subagent_default`, `pibo_subagent_explorer`, and `pibo_subagent_worker`; and the `pibo_run_*` lifecycle tools. `web_search` is a normal Pibo native tool with a provider adapter; the default adapter injects OpenAI Responses hosted `web_search` into the model request instead of using a local DuckDuckGo function tool. It intentionally does not expose Pi's separate `grep`, `find`, or `ls` tools by default; codebase search remains Codex-style through `bash` and commands such as `rg`.
-
-Profiles can opt into registered subagents. Pibo exposes enabled subagents to Pi as generated tools named `pibo_subagent_<name>`, routed through normal pibo sessions. Generated subagent tools are always parallel-capable; agents sequence subagent work by waiting for a direct result before issuing a later call or by using `pibo_run_start` for yielded work.
+## State and user paths
 
-Subagent sessions use `parentId` for hierarchy and inherit the parent session's `metadata.chatRoomId` when the parent belongs to a Chat Web room, so room-scoped session views and room deletion include subagent work.
-
-The `run-yield-qa` profile adds two simple QA subagents. Profiles with yieldable tools can expose generated run-control tools through the `pibo-run-control` capability package:
+Pibo stores product-wide state under:
 
 ```text
-pibo_run_start
-pibo_run_list
-pibo_run_status
-pibo_run_wait
-pibo_run_read
-pibo_run_cancel
-pibo_run_ack
+${PIBO_HOME:-~/.pibo}
 ```
 
-Try the QA profile through the routed runtime:
+That means the executing Linux user owns the installation state:
 
-```bash
-npm run profile -- run-yield-qa
-npm run tui:routed -- run-yield-qa
+```text
+alice -> /home/alice/.pibo
+pibo  -> /home/pibo/.pibo
+root  -> /root/.pibo
 ```
 
-Subagent profiles require the routed runtime. Do not use direct `npm run tui -- run-yield-qa` for this profile.
-
-## Gateway
-
-The gateway is the current local transport boundary. It owns the session router, accepts newline-delimited JSON frames over TCP, routes messages by Pibo Session ID, and broadcasts normalized session events back to connected clients.
-
-The parked gateway producer profile adds `pibo_gateway_send`, a tool that sends a message into a target gateway session and returns the correlated assistant reply. See `examples/gateway/README.md` for the two supported manual flows.
-
-## MCP CLI
-
-Pibo includes an MCP helper CLI under `pibo mcp`. It reads MCP server definitions from `mcp_servers.json`, starts stdio or HTTP MCP servers, lists their tools, shows schemas, searches by glob, and calls tools from shell-friendly JSON input. See `docs/mcp.md` for the full guide.
-
-```bash
-npm run dev -- mcp
-npm run dev -- mcp info filesystem
-npm run dev -- mcp grep "*file*"
-npm run dev -- mcp call filesystem read_file '{"path":"README.md"}'
-```
+There is no requirement to run as `root`. If you SSH as root and run Pibo, state naturally lands in `/root/.pibo`. If you create or use a dedicated user, state lands in that user's home. This is the preferred way to keep SSH keys, config, logs, and sessions separated.
 
-The config file is created automatically as `mcp_servers.json` when needed. Manage it with:
+Workspace-scoped files are separate and live under the active workspace:
 
-```bash
-npm run dev -- mcp config init
-npm run dev -- mcp config help
-npm run dev -- mcp config path
-npm run dev -- mcp config paths
-npm run dev -- mcp config schema
-npm run dev -- mcp config add filesystem '{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}'
-npm run dev -- mcp config add deepwiki '{"url":"https://mcp.deepwiki.com/mcp"}'
-npm run dev -- mcp config remove filesystem
+```text
+<workspace>/.pibo
 ```
 
-Pibo also ships a small MCP registry for common optional servers. Presets are not active by default; install one when you want it:
-
-```bash
-npm run dev -- mcp registry list
-npm run dev -- mcp registry show <name>
-npm run dev -- mcp registry doctor <name>
-npm run dev -- mcp registry install <name>
-npm run dev -- mcp registry remove <name>
-```
+Examples include custom prompts and Pi package registrations.
 
-The registry currently has no bundled presets. The command surface remains in place so curated external MCP servers can be added later without changing the config model.
+## Server notes
 
-Config lookup order is `-c/--config`, `MCP_CONFIG_PATH`, `./mcp_servers.json`, `~/.mcp_servers.json`, then `~/.config/mcp/mcp_servers.json`. Use `MCP_NO_DAEMON=1` to force fresh MCP connections instead of using the short-lived connection cache.
+A fresh server install usually needs only three decisions:
 
-## CLI Tools
+1. Choose the Linux user that should own Pibo.
+2. Install Node.js 24+ for that user or system-wide.
+3. Install Pibo through npm.
 
-Pibo includes a separate `pibo tools` registry for curated external CLI tools. These tools are not MCP servers and their guides are not loaded into every agent profile. Agents can discover them on demand:
+Use the setup planner to keep the first run simple:
 
 ```bash
-npm run dev -- tools list
-npm run dev -- tools installed
-npm run dev -- tools show browser-use
-npm run dev -- tools install browser-use
-npm run dev -- tools remove browser-use
-npm run dev -- tools doctor browser-use
-npm run dev -- tools guides browser-use
-npm run dev -- tools guide browser-use browser-use
-npm run dev -- tools guide browser-use remote-browser
-npm run dev -- tools path browser-use
-npm run dev -- tools env browser-use
-npm run dev -- tools browser-use
-npm run dev -- tools browser-use targets
-npm run dev -- tools browser-use attach-chat
-npm run dev -- tools browser-use lease acquire
+pibo setup doctor --domain pibo.example.com --expected-ip <server-ip>
+pibo setup user-host --domain pibo.example.com --print-files
+pibo setup user-host --domain pibo.example.com --write-to /tmp/pibo-setup
 ```
 
-The first curated tool is `browser-use`, pinned to `browser-use[cli]==0.12.6` so the CLI surface stays aligned with the bundled guides. It is installed into an isolated runtime under `~/.pibo/tools/browser-use` and uses `~/.pibo/tools/browser-use/home` as its tool home. See `docs/tools.md`.
+This is the normal user path: one gateway, one `PIBO_HOME`, no required Docker, no dev gateway, and no GitHub App setup. After reviewing staged files, use `--apply --yes` to write the generated systemd/Caddy files.
 
-When using Browser Use from this repo, initialize its shell environment once in a persistent terminal with `eval "$(npm run --silent dev -- tools env browser-use)"`, then run later `browser-use` commands directly in that same terminal.
-
-For Chat Web debugging, start by reusing the browser that already exists: `npm run dev -- tools browser-use targets` lists Chrome CDP targets with Chat auth/composer hints, and `npm run dev -- tools browser-use attach-chat` exports the best authenticated Chat target for direct CDP inspection.
-
-## Debug CLI
-
-Pibo includes a local operator CLI under `pibo debug` for targeted SQLite diagnostics. It is not an agent profile tool and does not load Pi transcripts or full Chat Web payloads automatically.
+Developer hosts are opt-in and add production/dev separation plus Docker compute workers:
 
 ```bash
-npm run dev -- debug db stores
-npm run dev -- debug db schema sessions
-npm run dev -- debug db query sessions "select id, profile from pibo_sessions limit 5"
-npm run dev -- debug session /apps/chat/rooms/<roomId>/sessions/<piboSessionId>
-npm run dev -- debug trace <piboSessionId> --running-only
-npm run dev -- debug trace <piboSessionId> --check
-npm run dev -- debug events <piboSessionId> --type tool_execution_finished --fields toolName,toolCallId,result.details.status
-npm run dev -- debug events stats --topic pibo.output --session <piboSessionId> --retention live_delta
-npm run dev -- debug events prune --topic pibo.output --retention live_delta --before 2026-05-01T00:00:00.000Z
-```
-
-`pibo debug db query` opens known stores read-only, accepts only one read-only SQL statement, applies a default row limit when the query has no `limit`, and supports `--json` for machine-readable output. `pibo debug trace` rebuilds the same Chat Web trace view as `/api/chat/trace`; `--check` adds trace consistency diagnostics for ids, parents, stable order metadata, and source/stable-key coverage. `pibo debug events` extracts selected payload fields without dumping full event payloads, can summarize retained event counts by topic/session/retention class, and can prune old `live_delta` rows once replay consumers no longer need them.
+pibo setup developer-host \
+  --origin git@github.com:<your-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --print-files
 
-## Web Auth
+pibo setup developer-host \
+  --origin git@github.com:<your-fork>/pibo.git \
+  --prod-domain pibo.example.com \
+  --dev-domain dev.pibo.example.com \
+  --write-to /tmp/pibo-setup
+```
 
-`npm run gateway:web` starts three separate pieces on the same origin:
+See `docs/ops/install-user-host.md`, `docs/ops/install-developer-host.md`, and `docs/ops/upgrade-user-to-developer-host.md`. Developer-host services are source-pinned so production and dev do not fight over one global `pibo` symlink. Docker and swap are developer-host prerequisites only; verify them with `pibo setup doctor --require-docker --min-swap-gb 8`.
 
-- `pibo.better-auth` registers the Better Auth service and owns `/api/auth/*`.
-- `pibo.web-host` owns the HTTP server and dispatches same-origin web apps.
-- `pibo.chat-web` registers the chat app under `/apps/chat` and `/api/chat/*`.
+If the agent should be able to perform server administration, give that Linux user the required sudo or Docker permissions explicitly. Pibo does not need a special onboarding user to work correctly; normal Unix ownership is enough.
 
-V1 uses Better Auth with Google OAuth, the Better Auth bearer plugin, and SQLite at `.pibo/auth.sqlite`. Add the exact Google OAuth redirect URI for your instance. For local QA with `auth.baseURL` set to `http://localhost:4788`, use:
+## Docker notes
 
-```text
-http://localhost:4788/api/auth/callback/google
-```
-
-For a deployed instance, replace the host with that instance's public HTTPS origin:
+Docker is optional. If you run Pibo in a container, avoid hard-coding `/root` unless the container is intentionally root-owned. Prefer mapping the host user's state into the container user's home:
 
 ```text
-https://pibo.example.com/api/auth/callback/google
+$HOME/.pibo -> /home/pibo/.pibo
+$HOME/code  -> /workspace/code
 ```
 
-LAN development through an sslip.io host is also supported when a local reverse proxy exposes Pibo on port 80:
+Set `HOME` and `PIBO_HOME` consistently inside the container so the same path rule applies:
 
 ```text
-http://4788.192.168.0.204.sslip.io/api/auth/callback/google
+HOME=/home/pibo
+PIBO_HOME=/home/pibo/.pibo
 ```
 
-Google OAuth redirect URIs are exact per instance. Wildcard or "all deployments" redirects are not supported for this web-server flow, so each self-hosted deployment needs its own Google OAuth client or an explicitly configured redirect URI.
+## Web gateway auth
 
-Required config values:
+`pibo gateway:web` starts the authenticated web runtime. It requires Better Auth configuration before production use. This step is intentionally not automated because you must create/select the Google OAuth client and allowed user list:
 
 ```bash
-npm run dev -- config set auth.baseURL http://localhost:4788
-npm run dev -- config set auth.secret <32+ character secret>
-npm run dev -- config set auth.googleClientId <google oauth client id>
-npm run dev -- config set auth.googleClientSecret <google oauth client secret>
-npm run dev -- config set auth.allowedEmails you@example.com,friend@example.com
+pibo config set auth.baseURL https://your-host.example
+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
 ```
 
-For LAN access from another device, set the public origin as both the Better Auth base URL and a trusted origin:
-
-```bash
-npm run dev -- config set auth.baseURL http://4788.192.168.0.204.sslip.io
-npm run dev -- config set auth.trustedOrigins http://4788.192.168.0.204.sslip.io
-```
+For local loopback testing, `auth.baseURL` can be `http://localhost:4788`.
 
-The web host binds to `127.0.0.1` when `auth.baseURL` is loopback. When `auth.baseURL` is a non-loopback host, `npm run gateway:web` binds the HTTP web host to `0.0.0.0` by default. The internal TCP gateway remains on loopback.
+## Development from source
 
-When running behind a local nginx sslip.io proxy, preserve the original browser origin:
+Use source installs for development, not normal usage:
 
-```nginx
-proxy_set_header Host 127.0.0.1:$target_port;
-proxy_set_header X-Forwarded-Proto $scheme;
-proxy_set_header X-Forwarded-Host $host;
-proxy_pass http://127.0.0.1:$target_port;
+```bash
+git clone git@github.com:Pascapone-server/pibo.git
+cd pibo
+npm install
+npm run build
+npm run start -- --help
 ```
 
-Pibo trusts `X-Forwarded-Host` and `X-Forwarded-Proto` only from loopback proxy connections. Chat mutation routes still require JSON and same-origin `Origin` headers.
-
-`auth.secret` must be at least 32 characters. `auth.allowedEmails` must contain at least one email; pibo fails closed if the allowlist is missing or empty. Authenticated Google users whose email is not listed receive `403` from the pibo web API. Unauthenticated pibo API requests receive `401`.
+Useful scripts:
 
-All web chat API requests require Better Auth, including localhost.
+```bash
+npm run dev -- --help
+npm run profile -- codex
+npm run tui:routed -- codex
+npm run gateway
+npm run gateway:web
+npm test
+npm run typecheck
+```
 
-The Google provider requests `prompt=select_account`, so signing out of pibo and signing in again lets the user choose a different Google account. Pibo signout clears the Better Auth session; it does not sign the user out of Google globally.
+## Main CLI areas
 
-## Config CLI
+```bash
+pibo config       # local config under ${PIBO_HOME:-~/.pibo}/config.json
+pibo mcp          # discover and call configured MCP servers
+pibo tools        # install and inspect curated external CLI tools
+pibo pi-packages  # register Pi Coding Agent packages
+pibo debug        # inspect local Pibo data stores
+pibo setup        # plan user-host installs and developer-host upgrades
+pibo profile      # inspect runtime profiles
+pibo tui          # start the direct Pi TUI
+pibo tui:routed   # start the routed Pibo TUI
+pibo gateway      # local gateway runtime
+pibo gateway:web  # authenticated web gateway runtime
+```
+
+## Further docs
+
+- `docs/architecture.md` describes runtime architecture and boundaries.
+- `docs/mcp.md` documents MCP configuration and commands.
+- `docs/tools.md` documents curated external CLI tools.
+- `docs/pi-packages.md` documents Pi package registration.
+- `docs/chat-rooms-event-log.md` documents Chat Web rooms and durable event storage.
+- `docs/progress.md` is the short implementation status snapshot.
 
-Pibo reads local config from `.pibo/config.json`. The current CLI is intentionally small:
+## Philosophy
 
-```bash
-npm run dev -- config set auth.allowedEmails you@example.com,friend@example.com
-npm run dev -- config get auth.allowedEmails
-npm run dev -- config del auth.allowedEmails
-npm run dev -- config keys
-npm run dev -- config show
-```
+Keep Pibo thin. Pi Coding Agent should remain the inner engine; Pibo owns only the product boundary: profiles, plugins, channels, routing, auth, policy, and operator tooling.
 
-Supported V1 keys are `auth.baseURL`, `auth.secret`, `auth.googleClientId`, `auth.googleClientSecret`, `auth.allowedEmails`, `auth.trustedOrigins`, and `auth.databasePath`.
-Secret keys such as `auth.secret` and `auth.googleClientSecret` are stored in full but redacted in `config get` and `config show` output.
+Optional integrations should stay outside the core package until installed. MCP servers, Python virtual environments, external CLIs, and user skills are configured on demand rather than bundled into every runtime.

package/context/codex-base-prompt.md

@@ -99,6 +99,10 @@ In those cases, it is bad to output your proposed solution in a message. You sho
 
 If you encounter challenges or blockers, you should attempt to resolve them yourself.
 
+## Gateway Daemon
+
+Pibo can run as a persistent local gateway daemon (`pibo gateway`). If the gateway needs to be restarted (for example, after installing a package update), use `pibo gateway restart` for a graceful restart. The command sends SIGTERM, waits for the port to become free, spawns a new detached process, and waits until it is reachable again. Use `pibo gateway status` to check whether it is running.
+
 ## 7. Final Answer Instructions
 
 Always favor conciseness in your final answer. Usually avoid long-winded explanations and focus only on the most important details. For casual chit-chat, just chat.

package/context/compute-worker.md

@@ -0,0 +1,23 @@
+# Pibo Compute Worker
+
+When you need an isolated environment to work in (e.g. to restart the gateway without interrupting the main session, or to run tasks in parallel):
+
+1. Run `pibo compute spawn`.
+2. You will receive a JSON response with `id`, `gatewayHost` and `gatewayPort`.
+3. Connect to the worker:
+   - Shell access: `docker exec -it <id> bash`
+   - Gateway access: connect to `gatewayHost:gatewayPort`
+4. Do your work inside the worker.
+5. When finished, run `pibo compute release <id>` to clean up.
+
+If you are unsure which workers are running, use `pibo compute list`.
+
+If you have recently changed code and need a fresh build, run `pibo compute rebuild` before `spawn`.
+
+After worker validation, deploy host-level Chat Web changes to dev first:
+
+```bash
+./scripts/deploy-web-dev.sh
+```
+
+Use `./scripts/deploy-web.sh` only after dev testing succeeds and production deployment is approved.

package/context/pibo-native-tooling.md

@@ -0,0 +1,18 @@
+# Pibo Native Tooling
+
+Start with `pibo debug --help`.
+
+Use Pibo-owned operator/debug CLI capabilities before ad hoc scripts:
+- `pibo debug session <ps_...>` for session metadata and event summaries.
+- `pibo debug trace <ps_...> --check` for Chat Web trace reconstruction.
+- `pibo debug events <ps_...>` for compact event payload inspection.
+- `pibo debug signals tree <ps_...>` for live session signal state.
+- `pibo debug web ...` for CDP render snapshots, diffs, watch timelines, and Chat Web render scenarios.
+- `pibo debug pty ...` for real PTY-backed CLI/TUI smoke tests, scripted input, assertions, and raw/clean artifacts.
+
+For browser access, prefer `pibo tools agent-browser` for fast ref-based browser automation, Browser Use leases for existing Browser Use workflows, and `pibo debug web targets` for render-state analysis. Start with `pibo tools show agent-browser` and `pibo tools guide agent-browser agent-browser`.
+For interactive terminal debugging, start with `pibo debug pty --help`; prefer mocked/deterministic scenarios by default and use `--real-provider` only with bounded `--max-iterations`.
+
+Use `pibo skills --help` to manage user skills. This CLI covers user-installed skills only, not built-in or plugin-provided skills. Prefer `pibo skills list --json` when another agent will parse the result.
+
+Keep discovery in the CLI: run each command with `--help` before using deeper options.

package/context/pibo-system-prompt.md

@@ -1,17 +1,78 @@
+# Agent System
+
 You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
 
+## Tools
+
 Available tools:
 {{availableTools}}
 
 In addition to the tools above, you may have access to other custom tools depending on the project.
 
-Guidelines:
+## Guidelines
+
 {{guidelines}}
 
-Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
-- Main documentation: /home/pibo/code/pi-mono/packages/coding-agent/README.md
-- Additional docs: /home/pibo/code/pi-mono/packages/coding-agent/docs
-- Examples: /home/pibo/code/pi-mono/packages/coding-agent/examples (extensions, custom tools, SDK)
-- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
-- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
-- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.