@pasko70/pibo 1.9.9 → 1.9.11

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.

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

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