@pasko70/pibo 1.9.7 → 1.9.9

package/context/pibo-system-prompt.md

@@ -1,78 +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}}
-
-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.
-
----
-
+# 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}}
+
+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.

package/docs/README.md

@@ -1,23 +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.
+# 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

@@ -1,112 +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`.
+# 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

@@ -1,96 +1,96 @@
-# 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
-
-For a public deployment with Google OAuth:
-
-```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
-```
-
-For a local development install on a developer laptop, use the local auth mode. This skips Google OAuth and binds the gateway to loopback only:
-
-```bash
-pibo config set auth.mode local
-pibo gateway:web --auth=local
-# Open http://localhost:4788/apps/chat and click "Sign in with Google".
-# The dev identity dev@pibo.local is auto-attached without OAuth.
-```
-
-Local auth refuses a non-loopback bind:
-
-```bash
-pibo gateway:web --auth=local --web-host=0.0.0.0
-# Error: --auth=local requires a loopback bind (127.0.0.1, ::1, or localhost).
-```
-
-Three independent request-time safety layers guard the local auth service. See `docs/specs/capabilities/web-auth-and-same-origin-host.md` REQ-010 and the `pibo-debug-auth` skill for the full model.
-
-## 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. Local auth mode bypasses the Better Auth requirement and prints a warning instead of a hard blocker.
-
-## 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.
+# 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
+
+For a public deployment with Google OAuth:
+
+```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
+```
+
+For a local development install on a developer laptop, use the local auth mode. This skips Google OAuth and binds the gateway to loopback only:
+
+```bash
+pibo config set auth.mode local
+pibo gateway:web --auth=local
+# Open http://localhost:4788/apps/chat and click "Sign in with Google".
+# The dev identity dev@pibo.local is auto-attached without OAuth.
+```
+
+Local auth refuses a non-loopback bind:
+
+```bash
+pibo gateway:web --auth=local --web-host=0.0.0.0
+# Error: --auth=local requires a loopback bind (127.0.0.1, ::1, or localhost).
+```
+
+Three independent request-time safety layers guard the local auth service. See `docs/specs/capabilities/web-auth-and-same-origin-host.md` REQ-010 and the `pibo-debug-auth` skill for the full model.
+
+## 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. Local auth mode bypasses the Better Auth requirement and prints a warning instead of a hard blocker.
+
+## 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.