@pasko70/pibo 1.9.2 → 1.9.4

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
+```

package/docs/ops/vscode-extension-release.md

@@ -1,160 +1,160 @@
-# 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.
-
-## Distribution channels
-
-The extension is published through two channels that are intentionally separate:
-
-| Channel | Owner | Cadence | What it carries |
-|---|---|---|---|
-| npm `@pasko70/pibo` | automated via `npm publish` (or the release script's `--publish-npm` flag) | every `main` commit that includes a version bump | the `pibo` CLI, the gateway, the WebView bundle at `dist/apps/chat-vscode-web/` |
-| VS Code Marketplace `pibo.pibo-vscode` | **maintainer uploads the VSIX manually** via <https://marketplace.visualstudio.com/manage> | every release that needs the extension UI updated | the `.vsix` produced by `npm run vscode:package` |
-
-The npm package and the Marketplace extension are versioned together. The release script bumps both `package.json` (npm) and `src/apps/chat-vscode/package.json` (extension) in one go so the published artifacts stay in lockstep.
-
-`pibo vscode install` (new since the distribution rework) downloads the VSIX from the GitHub Release for the configured repo (`Pascapone/pibo` by default). When the maintainer also uploads the same VSIX to the Marketplace, both channels serve identical bytes.
-
-## Versioning
-
-- The root `package.json#version` is the npm version. It follows [SemVer](https://semver.org/).
-- The extension's `src/apps/chat-vscode/package.json#version` is the Marketplace version. It is kept equal to the npm version (the release script enforces this).
-- A SemVer **minor** bump (e.g., `1.2.0` → `1.3.0`) is appropriate when the change is additive and backward-compatible. The distribution rework itself is a minor bump: existing `pibo` users are unaffected, and the new `pibo vscode install` command is opt-in.
-- A SemVer **major** bump is reserved for breaking changes to either the public CLI surface or the WebView host↔Web postMessage contract.
-
-## Release steps
-
-The release script does the heavy lifting. The maintainer's job is to review, commit, and push.
-
-### 1. Pick the version
-
-Decide on the next version. For the distribution rework that introduces `pibo vscode install`, the right bump is `1.2.0` → `1.3.0` (new CLI command, new marketplace-ready extension, no breaking changes).
-
-### 2. Bump + build + package (local)
-
-From the repo root:
-
-```bash
-node scripts/release.mjs --version 1.3.0
-```
-
-The script:
-
-1. Reads the current version from both `package.json` files.
-2. Writes the new version to both files.
-3. Runs `npm run build` (which includes the WebView build).
-4. Runs `npm run vscode:package` to produce `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix` and a stable `latest.vsix` copy.
-5. Prints the VSIX path and size.
-
-The script does **not** push to git or create a tag. The maintainer reviews the diff and commits it.
-
-### 3. Commit and tag
-
-```bash
-git add package.json src/apps/chat-vscode/package.json
-git commit -m "chore(release): bump @pasko70/pibo and pibo.pibo-vscode to 1.3.0"
-git tag -a v1.3.0 -m "@pasko70/pibo 1.3.0"
-git push origin main
-git push origin v1.3.0
-```
-
-### 4. Create a GitHub Release with the VSIX attached
-
-The maintainer's local machine has the `gh` CLI installed:
-
-```bash
-gh release create v1.3.0 \
-  dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix \
-  --title "pibo 1.3.0" \
-  --notes "..."
-```
-
-In environments where `gh` is not available (e.g. the pibo compute workers),
-`scripts/create-github-release.mjs` performs the same action via the Pibo
-GitHub App, which has been installed on `Pascapone/pibo` with the
-`contents: write` scope. The script accepts the GitHub App credentials from
-`PIBO_GITHUB_APP_ID` and `PIBO_GITHUB_APP_KEY` environment variables, or
-from the well-known env file at
-`/root/.pibo/uploads/github-app.env` (with the PEM key auto-discovered
-next to it).
-
-```bash
-node scripts/create-github-release.mjs \
-  --tag v1.3.0 \
-  --asset dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix
-```
-
-Both paths make the VSIX downloadable from a stable URL
-(`https://github.com/Pascapone/pibo/releases/download/v1.3.0/pibo-vscode-1.3.0.vsix`).
-The `pibo vscode install` command uses the GitHub Releases API to discover
-this URL automatically.
-
-The release script can also do this in one step:
-
-```bash
-node scripts/release.mjs --version 1.3.0 --create-release
-```
-
-…if the tag has already been pushed. Internally the release script calls
-`scripts/create-github-release.mjs`, so it works in worker environments
-without `gh`.
-
-### 5. Publish the npm package
-
-```bash
-npm publish
-```
-
-Or, in one go with the release script:
-
-```bash
-node scripts/release.mjs --version 1.3.0 --publish-npm --create-release
-```
-
-The publish step uploads the `pibo` CLI, the gateway plugins, and the WebView bundle. The Marketplace upload is intentionally **not** automated — see step 6.
-
-### 6. Upload the VSIX to the VS Code Marketplace (manual)
-
-The Marketplace does not currently accept a Personal Access Token from this account (Azure-side provisioning issue). The release is therefore finished by uploading the VSIX through the Marketplace web UI:
-
-1. Open <https://marketplace.visualstudio.com/manage>.
-2. Pick the publisher `pibo` (created during the first marketplace publish).
-3. Click **Upload new extension** and select `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix`.
-4. The Marketplace validates the manifest and publishes the extension. The publisher ID is `pibo.pibo-vscode`.
-
-After the upload, `code --install-extension pibo.pibo-vscode` works for end users.
-
-### 7. Verify
-
-```bash
-pibo vscode install --vsix dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix
-pibo vscode status
-```
-
-Confirm that `status` reports `pibo.pibo-vscode@1.3.0` installed via the expected `code` binary, and that the WebView loads the gateway at `http://127.0.0.1:4788/apps/chat-vscode/`.
-
-## Rollback
-
-If a release is broken:
-
-- **npm**: `npm unpublish @pasko70/pibo@1.3.0` works only within 72 hours of publish. After that, publish `1.3.1` with a fix.
-- **VSIX via `pibo vscode install`**: delete the GitHub Release and re-create it with a fixed VSIX. Users who have already installed the extension will not auto-update until they run `pibo vscode install` again.
-- **Marketplace**: the Marketplace UI supports un-publishing or un-listing. For a fast fix, upload a corrected `.vsix` with the same version (the Marketplace accepts a re-upload before processing the original).
-
-## What ships in the `pibo` npm package
-
-The `files` whitelist in `package.json` controls what is published:
-
-- `dist/` — the compiled server, the gateway plugins, the WebView bundles (chat-ui, context-files-ui, chat-vscode-web).
-- `context/` — the bundled agent skills.
-- `skills/builtin/**` — built-in user skills.
-- `docs/ops/**` — operator runbooks.
-- `README.md` and `src/mcp/LICENSE.mcp-cli`.
-
-The `.vsix` is **not** in the npm package. It lives on the GitHub Release and (after the maintainer uploads it) on the VS Code Marketplace.
-
-## Why the WebView bundle is in the npm package
-
-The extension's WebView loads from `http://<gateway>/apps/chat-vscode/`, not from the `.vsix`. The gateway serves the bundle out of `dist/apps/chat-vscode-web/`. If the bundle were not in the npm package, the gateway would return 404 for the WebView and the extension would be unusable.
-
-Including the bundle in npm costs about 1 MB of disk per `pibo` install and zero runtime cost for users who never open the extension. Users who only use the `pibo` CLI never load the bundle.
+# 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.
+
+## Distribution channels
+
+The extension is published through two channels that are intentionally separate:
+
+| Channel | Owner | Cadence | What it carries |
+|---|---|---|---|
+| npm `@pasko70/pibo` | automated via `npm publish` (or the release script's `--publish-npm` flag) | every `main` commit that includes a version bump | the `pibo` CLI, the gateway, the WebView bundle at `dist/apps/chat-vscode-web/` |
+| VS Code Marketplace `pibo.pibo-vscode` | **maintainer uploads the VSIX manually** via <https://marketplace.visualstudio.com/manage> | every release that needs the extension UI updated | the `.vsix` produced by `npm run vscode:package` |
+
+The npm package and the Marketplace extension are versioned together. The release script bumps both `package.json` (npm) and `src/apps/chat-vscode/package.json` (extension) in one go so the published artifacts stay in lockstep.
+
+`pibo vscode install` (new since the distribution rework) downloads the VSIX from the GitHub Release for the configured repo (`Pascapone/pibo` by default). When the maintainer also uploads the same VSIX to the Marketplace, both channels serve identical bytes.
+
+## Versioning
+
+- The root `package.json#version` is the npm version. It follows [SemVer](https://semver.org/).
+- The extension's `src/apps/chat-vscode/package.json#version` is the Marketplace version. It is kept equal to the npm version (the release script enforces this).
+- A SemVer **minor** bump (e.g., `1.2.0` → `1.3.0`) is appropriate when the change is additive and backward-compatible. The distribution rework itself is a minor bump: existing `pibo` users are unaffected, and the new `pibo vscode install` command is opt-in.
+- A SemVer **major** bump is reserved for breaking changes to either the public CLI surface or the WebView host↔Web postMessage contract.
+
+## Release steps
+
+The release script does the heavy lifting. The maintainer's job is to review, commit, and push.
+
+### 1. Pick the version
+
+Decide on the next version. For the distribution rework that introduces `pibo vscode install`, the right bump is `1.2.0` → `1.3.0` (new CLI command, new marketplace-ready extension, no breaking changes).
+
+### 2. Bump + build + package (local)
+
+From the repo root:
+
+```bash
+node scripts/release.mjs --version 1.3.0
+```
+
+The script:
+
+1. Reads the current version from both `package.json` files.
+2. Writes the new version to both files.
+3. Runs `npm run build` (which includes the WebView build).
+4. Runs `npm run vscode:package` to produce `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix` and a stable `latest.vsix` copy.
+5. Prints the VSIX path and size.
+
+The script does **not** push to git or create a tag. The maintainer reviews the diff and commits it.
+
+### 3. Commit and tag
+
+```bash
+git add package.json src/apps/chat-vscode/package.json
+git commit -m "chore(release): bump @pasko70/pibo and pibo.pibo-vscode to 1.3.0"
+git tag -a v1.3.0 -m "@pasko70/pibo 1.3.0"
+git push origin main
+git push origin v1.3.0
+```
+
+### 4. Create a GitHub Release with the VSIX attached
+
+The maintainer's local machine has the `gh` CLI installed:
+
+```bash
+gh release create v1.3.0 \
+  dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix \
+  --title "pibo 1.3.0" \
+  --notes "..."
+```
+
+In environments where `gh` is not available (e.g. the pibo compute workers),
+`scripts/create-github-release.mjs` performs the same action via the Pibo
+GitHub App, which has been installed on `Pascapone/pibo` with the
+`contents: write` scope. The script accepts the GitHub App credentials from
+`PIBO_GITHUB_APP_ID` and `PIBO_GITHUB_APP_KEY` environment variables, or
+from the well-known env file at
+`/root/.pibo/uploads/github-app.env` (with the PEM key auto-discovered
+next to it).
+
+```bash
+node scripts/create-github-release.mjs \
+  --tag v1.3.0 \
+  --asset dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix
+```
+
+Both paths make the VSIX downloadable from a stable URL
+(`https://github.com/Pascapone/pibo/releases/download/v1.3.0/pibo-vscode-1.3.0.vsix`).
+The `pibo vscode install` command uses the GitHub Releases API to discover
+this URL automatically.
+
+The release script can also do this in one step:
+
+```bash
+node scripts/release.mjs --version 1.3.0 --create-release
+```
+
+…if the tag has already been pushed. Internally the release script calls
+`scripts/create-github-release.mjs`, so it works in worker environments
+without `gh`.
+
+### 5. Publish the npm package
+
+```bash
+npm publish
+```
+
+Or, in one go with the release script:
+
+```bash
+node scripts/release.mjs --version 1.3.0 --publish-npm --create-release
+```
+
+The publish step uploads the `pibo` CLI, the gateway plugins, and the WebView bundle. The Marketplace upload is intentionally **not** automated — see step 6.
+
+### 6. Upload the VSIX to the VS Code Marketplace (manual)
+
+The Marketplace does not currently accept a Personal Access Token from this account (Azure-side provisioning issue). The release is therefore finished by uploading the VSIX through the Marketplace web UI:
+
+1. Open <https://marketplace.visualstudio.com/manage>.
+2. Pick the publisher `pibo` (created during the first marketplace publish).
+3. Click **Upload new extension** and select `dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix`.
+4. The Marketplace validates the manifest and publishes the extension. The publisher ID is `pibo.pibo-vscode`.
+
+After the upload, `code --install-extension pibo.pibo-vscode` works for end users.
+
+### 7. Verify
+
+```bash
+pibo vscode install --vsix dist/apps/vscode-artifacts/pibo-vscode-1.3.0.vsix
+pibo vscode status
+```
+
+Confirm that `status` reports `pibo.pibo-vscode@1.3.0` installed via the expected `code` binary, and that the WebView loads the gateway at `http://127.0.0.1:4788/apps/chat-vscode/`.
+
+## Rollback
+
+If a release is broken:
+
+- **npm**: `npm unpublish @pasko70/pibo@1.3.0` works only within 72 hours of publish. After that, publish `1.3.1` with a fix.
+- **VSIX via `pibo vscode install`**: delete the GitHub Release and re-create it with a fixed VSIX. Users who have already installed the extension will not auto-update until they run `pibo vscode install` again.
+- **Marketplace**: the Marketplace UI supports un-publishing or un-listing. For a fast fix, upload a corrected `.vsix` with the same version (the Marketplace accepts a re-upload before processing the original).
+
+## What ships in the `pibo` npm package
+
+The `files` whitelist in `package.json` controls what is published:
+
+- `dist/` — the compiled server, the gateway plugins, the WebView bundles (chat-ui, context-files-ui, chat-vscode-web).
+- `context/` — the bundled agent skills.
+- `skills/builtin/**` — built-in user skills.
+- `docs/ops/**` — operator runbooks.
+- `README.md` and `src/mcp/LICENSE.mcp-cli`.
+
+The `.vsix` is **not** in the npm package. It lives on the GitHub Release and (after the maintainer uploads it) on the VS Code Marketplace.
+
+## Why the WebView bundle is in the npm package
+
+The extension's WebView loads from `http://<gateway>/apps/chat-vscode/`, not from the `.vsix`. The gateway serves the bundle out of `dist/apps/chat-vscode-web/`. If the bundle were not in the npm package, the gateway would return 404 for the WebView and the extension would be unusable.
+
+Including the bundle in npm costs about 1 MB of disk per `pibo` install and zero runtime cost for users who never open the extension. Users who only use the `pibo` CLI never load the bundle.