@pasko70/pibo 3.1.4 → 3.2.0

package/docs/project/installation-profiles.md

@@ -0,0 +1,134 @@
+---
+type: "Reference"
+title: "Installation profiles"
+description: "Explains supported Pibo installation profiles, ownership boundaries, migration, upgrade, rollback, and recovery."
+tags: ["installation", "operations", "profiles"]
+status: "draft"
+authority: "informative"
+migration_lineage:
+  source_path: "docs/project/installation-profiles.md"
+  source_commit: "debba32a68137205df6351da9f3ae461004ca0c0"
+  baseline_commit: "2aef244301f5d181624662fdad53e18e83e80bd9"
+  baseline_blob_oid: "04ba7be002c1a1cee6f0fa173801dd870127f7b3"
+  source_bytes: 6918
+  source_sha256: "b0bc367fcf9fb515803da3f305b66467b1c1947c26ef755f1f8c019b5bfe7f82"
+  source_body_sha256: "b0bc367fcf9fb515803da3f305b66467b1c1947c26ef755f1f8c019b5bfe7f82"
+generated:
+  by: "process:pibo-okf-p-current-project-plans"
+  at: "2026-08-31T22:47:46Z"
+---
+# Installation profiles
+
+Pibo's package installation remains side-effect free. After `npm install -g @pasko70/pibo`, use `pibo setup` to inspect or apply one of two supported host profiles.
+
+## Supported hosts and resource budget
+
+Planning and staging work wherever the Pibo CLI runs. Host apply currently targets Linux with systemd and one of `apt-get`, `dnf`, or `pacman`. The pinned code-server download supports Linux amd64 and arm64. Containers and other service managers should use Vanilla plan JSON or a staged tree as the integration contract instead of `--apply`.
+
+Vanilla adds only the gateway service and Caddy beyond the installed npm package. Batteries Included also downloads a 235 MB code-server archive, installs Chromium and two isolated browser-tool runtimes, and installs isolated MCP packages. Exact extracted size and memory depend on the distribution and workload; budget several gigabytes of disk and at least 2 GiB of available memory for a practical BI workstation. Browser sessions and IDE extension hosts add workload-dependent processes.
+
+## Choose a profile
+
+### Batteries Included (recommended)
+
+Use this for a complete self-hosted Pibo workstation. It adds:
+
+- the Pibo gateway and Chat Web;
+- embedded VS Code Web at `/apps/vscode/`;
+- Browser Use and Agent Browser from Pibo's pinned tool registry;
+- managed Chromium/CDP prerequisites;
+- Web Annotations from the installed Pibo package;
+- an allowlisted Chrome DevTools MCP default;
+- systemd, Caddy, status, doctor, upgrade, and rollback metadata.
+
+It consumes more disk, memory, network downloads, and background processes than Vanilla. VS Code Web binds only to `127.0.0.1:4790`, runs as `pibo-code`, and is exposed by Caddy only after the request passes Pibo's authenticated Chat bootstrap endpoint. The managed service can write its data directory and the configured workspace root, not arbitrary protected host paths.
+
+```bash
+pibo setup plan --profile batteries-included --domain pibo.example.com
+pibo setup install --profile batteries-included --domain pibo.example.com --apply --yes
+pibo setup status
+pibo setup doctor --domain pibo.example.com
+```
+
+Configure Better Auth before applying a public domain. Setup refuses to expose local-auth mode through a public proxy because Caddy reaches the gateway over loopback. A domain enables trusted automatic TLS; without one Caddy remains loopback-only at `http://127.0.0.1:8080`.
+
+### Vanilla
+
+Use this when you want only the Pibo gateway and Chat Web, or when another system owns the proxy and optional tooling. Vanilla does not install or start VS Code Web, Chromium, browser automation tools, or MCP integrations.
+
+```bash
+pibo setup plan --profile vanilla --domain pibo.example.com
+pibo setup install --profile vanilla --domain pibo.example.com --apply --yes
+```
+
+## Review before applying
+
+Plans are deterministic JSON and never modify the host:
+
+```bash
+pibo setup plan --profile batteries-included --json
+```
+
+A staged installation writes the complete owned filesystem tree and manifest under a review directory, without installing packages or starting services:
+
+```bash
+pibo setup install --profile batteries-included \
+  --pibo-home /root/.pibo \
+  --domain pibo.example.com \
+  --write-to /tmp/pibo-install
+pibo setup status --pibo-home /root/.pibo --root /tmp/pibo-install
+```
+
+Real host mutation requires both `--apply` and `--yes`, requires root, validates pinned code-server downloads with SHA-256, and uses `pibo gateway web restart` instead of bypassing the gateway's active-session safety check.
+
+## Components and migration
+
+Add an optional component to an installed profile with:
+
+```bash
+pibo setup component add vscode-web --apply --yes
+```
+
+The profile identity remains visible, while the manifest records the added component and pinned version. To move from Vanilla to the complete maintained set, apply the Batteries Included profile explicitly after reviewing its plan. To move from Batteries Included to Vanilla, uninstall setup-owned resources and install Vanilla; Pibo Home, workspaces, browser profiles, sessions, and user data remain in place.
+
+## Upgrade, repair, and rollback
+
+```bash
+pibo setup status --json
+pibo setup doctor
+pibo setup upgrade --apply --yes
+pibo setup uninstall --apply --yes
+```
+
+The private manifest at `$PIBO_HOME/setup/installation.json` records the profile version, component versions, download checksums, and SHA-256 digest of each owned file. Reapplying an unchanged plan leaves files and the manifest untouched. Upgrade replaces only files still matching their previous owned digest and reruns an installation action only when its recorded fingerprint or health check is stale. Uninstall removes only unchanged owned files; locally modified files are reported and preserved.
+
+To roll back component pins, install the previous Pibo package version, inspect `pibo setup upgrade --json`, and apply that older catalog with `pibo setup upgrade --apply --yes`. Preserve a copy of the manifest before rollback when you need an audit record of both states.
+
+Package-manager removal is separate from profile removal. `npm uninstall -g @pasko70/pibo` does not delete Pibo Home or setup-managed system files. Run `pibo setup uninstall --apply --yes` first when you want to remove those owned host resources.
+
+## Migrating an existing manual installation
+
+Keep the existing Pibo Home and workspace directories. First stage the target profile and compare its service, environment, and proxy resources with the manually maintained files:
+
+```bash
+pibo setup install --profile batteries-included \
+  --pibo-home /root/.pibo \
+  --domain pibo.example.com \
+  --write-to /tmp/pibo-install
+```
+
+Stop the manually managed code-server unit, archive its unit and Caddy configuration outside `/etc`, and then apply the profile. Setup deliberately refuses to overwrite an unmanaged or locally modified target file. This makes ownership transfer explicit instead of silently deleting unrelated proxy sites or service customizations. Reuse the existing workspace root with `--workspace-root`; the installer does not copy or delete workspace data. Existing browser templates under Pibo Home also remain in place.
+
+If the old reverse proxy serves unrelated sites, keep it under operator ownership and copy only the staged Pibo route into that configuration instead of applying setup ownership. In that case, use the generated plan as the supported routing contract and retain the external proxy in your own upgrade and rollback procedure.
+
+## Recovery
+
+A failed package download, service start, or gateway restart leaves the manifest and completed files available for diagnosis. Correct the reported prerequisite and rerun:
+
+```bash
+pibo setup status
+pibo setup doctor
+pibo setup upgrade --apply --yes
+```
+
+The lifecycle is idempotent. Setup does not store OAuth secrets in plans or manifests and does not bypass an active-session restart block.

package/docs/project/operations/index.md

@@ -0,0 +1,10 @@
+# Project operations
+
+<!-- Generated by npm run docs:indexes:write. -->
+
+## Concepts
+
+* [Install Pibo as a Developer Host](install-developer-host.md) - Guides operators through planning, installing, and validating a Pibo developer host&#46;
+* [Install Pibo as a User Host](install-user-host.md) - Guides operators through installing and configuring a Pibo user host&#46;
+* [Pibo VS Code Extension Release Runbook](vscode-extension-release.md) - Describes the end&#45;to&#45;end release procedure for Pibo's VS Code extension and related package artifacts&#46;
+* [Upgrade a User Host to a Developer Host](upgrade-user-to-developer-host.md) - Guides operators through upgrading a Pibo user host to a developer host without replacing production state&#46;

package/docs/{ops → project/operations}/install-developer-host.md

@@ -1,3 +1,22 @@
+---
+type: "Guide"
+title: "Install Pibo as a Developer Host"
+description: "Guides operators through planning, installing, and validating a Pibo developer host."
+tags: ["developer-host", "installation", "operations", "setup"]
+status: "draft"
+authority: "directive"
+generated:
+  by: "openai/codex"
+  at: "2026-08-30T15:47:50Z"
+sources:
+  - id: "foundation-relocation-source"
+    resource: "https://github.com/Pascapone/pibo/blob/2aef244301f5d181624662fdad53e18e83e80bd9/docs/ops/install-developer-host.md"
+    title: "Original byte-preserved developer-host installation guide"
+    commit: "2aef244301f5d181624662fdad53e18e83e80bd9"
+    path: "docs/ops/install-developer-host.md"
+    sha256: "8e6ae80f901852ab0d38c0eb887d83f300107ecbebc2418da5e19ca9238e2e70"
+    relation: "Byte-identical body lineage before Foundation relocation."
+---
 # Install Pibo as a Developer Host
 
 Use this path when the host is used to develop Pibo itself.

package/docs/{ops → project/operations}/install-user-host.md

@@ -1,3 +1,22 @@
+---
+type: "Guide"
+title: "Install Pibo as a User Host"
+description: "Guides operators through installing and configuring a Pibo user host."
+tags: ["installation", "operations", "setup", "user-host"]
+status: "draft"
+authority: "directive"
+generated:
+  by: "openai/codex"
+  at: "2026-08-30T15:47:50Z"
+sources:
+  - id: "foundation-relocation-source"
+    resource: "https://github.com/Pascapone/pibo/blob/2aef244301f5d181624662fdad53e18e83e80bd9/docs/ops/install-user-host.md"
+    title: "Original byte-preserved user-host installation guide"
+    commit: "2aef244301f5d181624662fdad53e18e83e80bd9"
+    path: "docs/ops/install-user-host.md"
+    sha256: "f3f6c51fe9f7b30fe8828cf844c82d8ef5ffebb715bab06d78348d5a9d547722"
+    relation: "Byte-identical body lineage before Foundation relocation."
+---
 # Install Pibo as a User Host
 
 Use this path when you want to run Pibo, not develop Pibo itself.

package/docs/{ops → project/operations}/upgrade-user-to-developer-host.md

@@ -1,3 +1,22 @@
+---
+type: "Guide"
+title: "Upgrade a User Host to a Developer Host"
+description: "Guides operators through upgrading a Pibo user host to a developer host without replacing production state."
+tags: ["developer-host", "operations", "setup", "upgrade"]
+status: "draft"
+authority: "directive"
+generated:
+  by: "openai/codex"
+  at: "2026-08-30T15:47:50Z"
+sources:
+  - id: "foundation-relocation-source"
+    resource: "https://github.com/Pascapone/pibo/blob/2aef244301f5d181624662fdad53e18e83e80bd9/docs/ops/upgrade-user-to-developer-host.md"
+    title: "Original byte-preserved user-host upgrade guide"
+    commit: "2aef244301f5d181624662fdad53e18e83e80bd9"
+    path: "docs/ops/upgrade-user-to-developer-host.md"
+    sha256: "a48141d6456800b5e05472dfa7464d44a3b1605ad25a3209145a4d5bfcef22f8"
+    relation: "Byte-identical body lineage before Foundation relocation."
+---
 # 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.

package/docs/{ops → project/operations}/vscode-extension-release.md

@@ -1,3 +1,22 @@
+---
+type: "Runbook"
+title: "Pibo VS Code Extension Release Runbook"
+description: "Describes the end-to-end release procedure for Pibo's VS Code extension and related package artifacts."
+tags: ["release", "runbook", "vscode", "vsix"]
+status: "deprecated"
+authority: "directive"
+generated:
+  by: "openai/codex"
+  at: "2026-08-30T15:47:50Z"
+sources:
+  - id: "foundation-relocation-source"
+    resource: "https://github.com/Pascapone/pibo/blob/2aef244301f5d181624662fdad53e18e83e80bd9/docs/ops/vscode-extension-release.md"
+    title: "Original byte-preserved Pibo VS Code extension release runbook"
+    commit: "2aef244301f5d181624662fdad53e18e83e80bd9"
+    path: "docs/ops/vscode-extension-release.md"
+    sha256: "4d7588693a51389ebc3ea53eb088272743e707e3d81a5f436ab58578769f56c2"
+    relation: "Byte-identical body lineage before Foundation relocation."
+---
 # Pibo VS Code Extension Release Runbook
 
 The Pibo VS Code extension is shipped as a `.vsix` artifact. This runbook describes the end-to-end release process and the split of responsibilities between the maintainer and the `pibo` release script.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@pasko70/pibo",
-  "version": "3.1.4",
+  "version": "3.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@pasko70/pibo",
-      "version": "3.1.4",
+      "version": "3.2.0",
       "workspaces": [
         "packages/workflows"
       ],
@@ -59,7 +59,8 @@
         "typescript": "^6.0.3",
         "vite": "^8.0.10",
         "vite-tsconfig-paths": "^5.1.4",
-        "vscode": "file:src/apps/chat-vscode/extension/vscode-shim"
+        "vscode": "file:src/apps/chat-vscode/extension/vscode-shim",
+        "yaml": "^2.9.0"
       },
       "engines": {
         "node": ">=24"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pasko70/pibo",
-  "version": "3.1.4",
+  "version": "3.2.0",
   "type": "module",
   "workspaces": [
     "packages/workflows"
@@ -11,7 +11,12 @@
     "!dist/apps/vscode-artifacts/**",
     "context",
     "skills/builtin/**",
-    "docs/ops/**",
+    "docs/project/operations/**",
+    "docs/project/installation-profiles.md",
+    "docs/project/guides/pibo-on-windows-via-wsl.md",
+    "docs/project/guides/pibo-vscode-ext-quickstart.md",
+    "!docs/README.md",
+    "!docs/project/README.md",
     "README.md",
     "src/mcp/LICENSE.mcp-cli",
     "npm-shrinkwrap.json",
@@ -53,6 +58,14 @@
     "build": "npm run workflows:build && node --max-old-space-size=1200 node_modules/typescript/bin/tsc -p tsconfig.json && npm run web-ui:build && npm run vscode:webview:build && node scripts/ensure-bin-executable.mjs",
     "start": "node dist/bin/pibo.js",
     "test": "npm run build && node scripts/run-test-suite.mjs",
+    "docs:validate": "npm run docs:validate:strict",
+    "docs:validate:okf": "node scripts/validate-okf-docs.mjs --mode core",
+    "docs:validate:migration": "node scripts/validate-okf-docs.mjs --mode migration",
+    "docs:validate:strict": "node scripts/validate-okf-docs.mjs --mode strict",
+    "docs:indexes:write": "node scripts/generate-okf-indexes.mjs",
+    "docs:indexes:check": "node scripts/generate-okf-indexes.mjs --check",
+    "docs:log:check": "node scripts/check-okf-log.mjs",
+    "docs:validator:test": "node --test test/okf-validator.test.mjs test/okf-authoring-guidance.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",
@@ -111,6 +124,7 @@
     "typescript": "^6.0.3",
     "vite": "^8.0.10",
     "vite-tsconfig-paths": "^5.1.4",
-    "vscode": "file:src/apps/chat-vscode/extension/vscode-shim"
+    "vscode": "file:src/apps/chat-vscode/extension/vscode-shim",
+    "yaml": "^2.9.0"
   }
 }

package/skills/builtin/pibo-agent-runtime-adapter/references/testing-migration-and-validation.md

@@ -228,7 +228,9 @@ A turn that reaches queue/idle but fails provider authentication proves only rou
 
 ## Validation report
 
-Write `docs/reports/<adapter-or-milestone>-validation-YYYY-MM-DD.md` containing:
+Publish validation as an `Evidence Report` at `docs/reports/evidence/<adapter-or-milestone>-validation-YYYY-MM-DD.md`. Read `docs/project/documentation-profile.md` first, include all required frontmatter plus `evidence: { id, published_at }`, register the final SHA-256 in `docs/reports/artifacts/okf-migration/evidence-manifest.json`, and never edit the published bytes in place. Add the ledger record, run `npm run docs:indexes:write`, and update `docs/log.md` explicitly. Corrections and reruns receive a new identity and path.
+
+The report body contains:
 
 - status and scope;
 - branch, PR, commits, package version/path/checksum;