@pasko70/pibo 3.1.3 → 3.2.0

package/docs/project/guides/pibo-vscode-ext-quickstart.md

@@ -0,0 +1,287 @@
+---
+type: "Guide"
+title: "Pibo Quick Start — CLI + VS Code Extension"
+description: "Provides a German-language quick start for installing Pibo and using its VS Code extension."
+tags: ["cli", "installation", "quickstart", "vscode"]
+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/guides/pibo-vscode-ext-quickstart.md"
+    title: "Original byte-preserved Pibo VS Code extension quick start"
+    commit: "2aef244301f5d181624662fdad53e18e83e80bd9"
+    path: "docs/guides/pibo-vscode-ext-quickstart.md"
+    sha256: "ff1b33edf70c89ce9b128382d05d5fa28735ede3fc3ba40429bece172fc2d716"
+    relation: "Byte-identical body lineage before Foundation relocation."
+---
+# Pibo Quick Start — CLI + VS Code Extension
+
+Diese Anleitung bringt dich in ungefähr 15 Minuten vom frischen Laptop zur
+laufenden Pibo-VSCode-Extension.
+
+## Was du am Ende hast
+
+- `pibo` CLI global installiert
+- Ein laufendes `pibo gateway:web` (Auth-Gateway) auf `http://127.0.0.1:4788`
+- Die Pibo VS Code Extension in deinem Editor
+- Eine erste Session in deinem aktuellen Projekt-Workspace
+
+## 0. Voraussetzungen
+
+| Was | Warum | Wie prüfen |
+|---|---|---|
+| **Node.js 24+** | Pibo läuft auf Node 24 (steht so in `package.json#engines`) | `node --version` |
+| **VS Code** (oder Insiders / VSCodium) | Ziel der Extension | `code --version` |
+| **Internet** | npm + GitHub Releases | ping `registry.npmjs.org` |
+| Optional: **Google OAuth Client** | Echter Login via Google | Console holen: <https://console.cloud.google.com/apis/credentials> |
+
+Falls dein `apt`-Node zu alt ist: <https://nodejs.org/en/download> oder `fnm`/`nvm` benutzen.
+
+## 1. Pibo CLI installieren
+
+```bash
+npm install -g @pasko70/pibo
+pibo --version        # soll 1.3.0 (oder neuer) zeigen
+pibo --help           # zeigt die Top-Level-Commands
+```
+
+Falls du eine Permission-Fehlermeldung bekommst (Linux/macOS):
+
+```bash
+mkdir -p ~/.local
+npm config set prefix ~/.local
+export PATH="$HOME/.local/bin:$PATH"
+npm install -g @pasko70/pibo
+```
+
+Diese PATH-Zeile am besten in deine `~/.bashrc` / `~/.zshrc` schreiben.
+
+## 2. Auth einrichten (einmalig)
+
+Pibo nutzt Better Auth + Google OAuth. Die Werte landen in `~/.pibo/config.json`.
+
+```bash
+pibo config set auth.baseURL http://127.0.0.1:4788
+pibo config set auth.secret "$(openssl rand -hex 32)"   # beliebiger 32+ Zeichen-String
+pibo config set auth.googleClientId     <aus-google-console>
+pibo config set auth.googleClientSecret <aus-google-console>
+pibo config set auth.allowedEmails      deine@email.com
+```
+
+**Woher bekomme ich die Google-Werte?**
+1. <https://console.cloud.google.com/apis/credentials> öffnen
+2. "OAuth 2.0 Client IDs" → "Create OAuth client ID" → Typ "Web application"
+3. Authorized redirect URIs: `http://127.0.0.1:4788/api/auth/callback/google` eintragen
+4. Client ID und Client Secret in die Config setzen
+5. In deiner Google-Console unter "OAuth consent screen" die gewünschten Test-User hinzufügen
+
+**Lokal ohne Google testen?** Setze `auth.baseURL=http://localhost:4788` und melde dich ohne externe Auth an (Pibo akzeptiert auf Loopback auch direkten Zugriff). Für die VSCode-Extension reicht das zum Ausprobieren.
+
+Verify:
+
+```bash
+pibo config show
+```
+
+## 3. Gateway starten
+
+In einem Terminal (das Terminal offen lassen):
+
+```bash
+pibo gateway:web
+```
+
+Erwartete Ausgabe (ungefähr):
+
+```text
+[gateway:web] listening on http://127.0.0.1:4788
+[gateway:web] auth baseURL = http://127.0.0.1:4788
+```
+
+Im Browser öffnen: <http://127.0.0.1:4788>. Du solltest die Pibo-Web-Oberfläche sehen und dich einloggen können.
+
+> Tipp: Wenn du das Gateway dauerhaft laufen lassen willst (z.B. auf einem
+> Server), schau dir `pibo gateway web status/start/restart` an — das ist
+> der produktive Pfad mit `pibo-web.service` dahinter.
+
+## 4. VS Code Extension installieren
+
+Du hast zwei Wege.
+
+### Weg A: Über die CLI (empfohlen)
+
+```bash
+pibo vscode install
+```
+
+Das Script:
+
+1. Findet deine `code` (oder `code-insiders` / `codium`) Binary im PATH
+2. Lädt die neueste VSIX aus dem GitHub Release von `Pascapone/pibo`
+3. Installiert sie via `code --install-extension <vsix>`
+4. Verifiziert mit `code --list-extensions --show-versions`
+
+Verify:
+
+```bash
+pibo vscode status
+```
+
+Erwartete Ausgabe:
+
+```text
+extension:   pibo.pibo-vscode@1.3.0 installed
+binary:      code (at /usr/bin/code)
+latest:      v1.3.0
+cache:       /home/<du>/.pibo/vscode/cache/v1.3.0/pibo.vsix
+```
+
+### Weg B: Über den VS Code Marketplace
+
+1. VS Code öffnen
+2. Sidebar → Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`)
+3. Suchen nach "Pibo" (Publisher: `pibo`)
+4. "Install" klicken
+
+Falls die Extension noch nicht im Marketplace sichtbar ist, nimm Weg A — der lädt direkt aus dem GitHub Release.
+
+## 5. Erste Session in VS Code
+
+1. **VS Code öffnen**, einen Projektordner als Workspace laden
+   (z.B. `File → Open Folder` → irgendein Repo)
+2. **Pibo-Sidebar** öffnen: Klick auf das Pibo-Icon in der linken
+   Activity Bar (es heißt einfach "Pibo")
+3. Beim ersten Öffnen passiert automatisch:
+   - Die Extension mappt deinen Workspace-Folder auf einen Pibo-Room
+   - Falls noch kein Room existiert: einer wird angelegt
+   - Falls genau ein Room existiert: direkt rein
+   - Falls mehrere existieren: ein Room-Picker erscheint
+4. **Neue Session starten**: in der Sidebar auf "New Session" klicken
+   (oder Command Palette → `Pibo: New Session`)
+5. **Chatten**: im Composer Loss tippen, Enter
+
+Die Session erscheint automatisch auch in der Web App unter
+<http://127.0.0.1:4788> — und umgekehrt.
+
+## 6. Nützliche Kommandos
+
+In der **Command Palette** (`Ctrl+Shift+P` / `Cmd+Shift+P`):
+
+| Kommando | Was es tut |
+|---|---|
+| `Pibo: New Session` | Neue Session im aktuellen Room |
+| `Pibo: Delete Current Session` | Aktuelle Session löschen |
+| `Pibo: Rename Current Session` | Session umbenennen |
+| `Pibo: Open in Chat Web` | Springt zur aktuellen Session im Browser |
+| `Pibo: Sign In` | Login mit openai/anthropic/google Provider |
+
+In der **CLI**:
+
+| Kommando | Was es tut |
+|---|---|
+| `pibo vscode install` | Extension installieren / upgraden |
+| `pibo vscode status` | Installations-Status prüfen |
+| `pibo vscode uninstall` | Extension entfernen |
+| `pibo vscode install --vsix <pfad>` | Lokale VSIX installieren (z.B. selbst gebaute) |
+| `pibo vscode install --from-url <url>` | VSIX von beliebiger URL (z.B. internem Mirror) |
+| `pibo vscode install --version v1.4.0` | Bestimmte Version installieren |
+| `pibo config show` | Config anzeigen (Werte sind redacted) |
+| `pibo data rooms` | Rooms / Workspaces anzeigen |
+| `pibo debug session <id>` | Session-Details inspizieren |
+
+## 7. Konfiguration
+
+Die Extension kennt folgende Einstellungen:
+
+- **`pibo.chatWebUrl`** (default: `http://127.0.0.1:4788`)
+  → URL des laufenden Gateway. Anpassen, wenn dein Gateway woanders läuft
+  (anderer Port, LAN-IP, Tunnel, etc.). Per-Workspace oder global setzen.
+- **`pibo.sidecar.port`** (default: `4789`)
+  → Loopback-Port für den eingebetteten Sidecar, der ab VS Code 1.117.0
+  die Web-App im Sidebar hostet. Wird automatisch auf einen freien
+  Loopback-Port umgestellt, wenn der Default belegt ist.
+- **`pibo.sidecar.gatewayProbeTimeoutMs`** (default: `1500`)
+  → Timeout für die Erreichbarkeits-Probe des Gateway. Wenn die Probe
+  fehlschlägt, fällt die Sidebar auf den Empty-State-Shell zurück.
+
+Ändern via:
+
+- VS Code: Settings → "Pibo"
+- JSON: `"pibo.chatWebUrl": "http://192.168.1.50:4788"` in `.vscode/settings.json`
+- Env: `PIBO_CHAT_WEB_URL=http://...` (überschreibt alles)
+
+## 7a. Architektur (ab 1.4.0): Sidecar + Inlined SPA
+
+VS Code ab 1.117.0 hat die Workbench-CSP für Webviews verschärft
+(`frame-src 'self'`). Die ältere Sidebar-Implementierung hat das
+Chat-vscode-SPA über `window.location.replace('http://127.0.0.1:4788/...')`
+geladen — das wird seit 1.117.0 von der Workbench blockiert.
+
+Die neue Architektur umgeht die Sperre, ohne die Workbench-CSP zu lockern:
+
+1. **Sidecar** — eine kleine Node.js HTTP-Server-Instanz im Extension-Host,
+   gebunden an `127.0.0.1:<port>` (Default 4789). Proxied `/api/...`-Calls
+   vom Webview zum Gateway, hält die dev-auth-Cookie-Session im Speicher
+   und streamt Antworten 1:1 (wichtig für SSE). Bindet ausschließlich auf
+   Loopback, erzwingt `vscode-webview://`-CORS, niemals extern erreichbar.
+2. **Port-Mapping** — VS Code routet Anfragen an
+   `https://<webviewId>.vscode-resource.vscode-cdn.net:<port>` intern
+   auf `http://127.0.0.1:<port>` weiter. Diese Origin ist in der
+   Workbench-`connect-src` whitelisted.
+3. **Inlined Bundle** — der gebaute Vite-Output (`assets/index-*.js`,
+   `assets/index-*.css`) wird in den Webview-HTML als `<script nonce=...>`
+   und `<style nonce=...>` inlined. Dadurch umgehen wir die strikte
+   `script-src`-Direktive der Workbench.
+4. **Health-Probe** — beim Webview-Setup prüft der Sidecar, ob das
+   Gateway erreichbar ist. Wenn ja, inlined SPA. Wenn nein, klassische
+   Empty-State-Shell mit `pibo gateway:web`-Hinweis.
+
+Trade-offs und Sicherheitsanalyse stehen im Implementierungs-Plan
+`docs/plans/vscode-webview-sidecar-implementation-plan-2026-06-15.md`.
+
+## 8. Troubleshooting
+
+**"Gateway not available" / Sidebar zeigt Fehler**
+→ Ist `pibo gateway:web` gestartet? Auf `curl http://127.0.0.1:4788/api/chat/bootstrap` testen.
+
+**Sidebar zeigt "Swap fehlgeschlagen: dev-auth handshake did not complete"**
+→ Du betreibst das Production-Gateway (Better Auth / Google OAuth). Die VS-Code-Extension hat keinen Browser, kann den OAuth-Flow nicht durchlaufen, und braucht den lokalen Dev-Auth-Flow. Lösung: `pibo gateway:web --auth=local` starten oder `pibo config set auth.mode local && pibo gateway:web`. Die Sidebar swapt dann automatisch von der Shell zur inlined SPA.
+
+**Login funktioniert nicht**
+→ Google OAuth Client korrekt? Redirect-URI `http://127.0.0.1:4788/api/auth/callback/google` eingetragen? `pibo config show` zeigt deine Werte (redacted)?
+
+**Extension findet das Gateway nicht**
+→ Andere URL? `pibo.chatWebUrl` Setting prüfen. Für andere Maschine: `--web-host 0.0.0.0` beim Start, dann `pibo.chatWebUrl=http://<lan-ip>:4788` setzen.
+
+**Sidebar bleibt leer nach Workspace-Öffnen**
+→ In der Output-Panel → "Pibo" schauen. Steht dort der Grund? Meist: fehlender `code`-Binary auf PATH (Extension kann sich dann nicht installieren) oder Auth-Bridge-Problem.
+
+**Updates installieren**
+→ `pibo vscode install` zieht die neueste GitHub-Release-VSIX. So upgrade-st du.
+
+**Komplett zurücksetzen**
+```bash
+pibo vscode uninstall
+pibo vscode install
+```
+Plus VS Code: `Developer: Reload Window`.
+
+## 9. Wo die Daten liegen
+
+```text
+~/.pibo/                                    Pibo-User-State
+├── config.json                             deine `pibo config set` Werte
+├── pibo.sqlite                             Sessions, Rooms, Events (geteilt mit Web)
+└── vscode/cache/                           VSIX-Cache pro Release-Tag
+    ├── v1.3.0/pibo.vsix
+    └── last-installed.json
+
+<dein-workspace>/.pibo/                     Workspace-scoped State
+├── PROMPTS.md                              Custom Prompts
+└── pi-package.json                         Pi-Package-Registrierung
+```
+
+Mehr Details: <https://github.com/Pascapone/pibo>

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.3",
+  "version": "3.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@pasko70/pibo",
-      "version": "3.1.3",
+      "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.3",
+  "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;