docs: managed-runtime guide + front-door feature refresh

CHANGELOG.md

@@ -12,6 +12,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Docs
+- **Managed Python runtime gets its guide, and the front doors catch up with the product.**
+  New `guides/python-runtime.md` covers the desktop one-click interpreter install
+  (ADR 0094) end to end — what needs it, both install paths, the pre-failure status
+  surfaces, the stale-baseline refresh, and the API. The README and docs landing now
+  mention archetypes (the wizard picks one, not a "persona preset"), the `execute_code`/
+  `coder`/`friction`/`orgchart` plugins, workflow `gate: human` approval steps, the ⌘K
+  palette + Fleet Room, and `/export` + `/btw`. protobanana left the core roadmap (it's a
+  plugin, tracked in its own repo and the directory), and the internal `plans/`/`design/`
+  working docs are excluded from the published site.
 - **Documentation audit — stale claims fixed, missing reference material added.** The docs
   landing no longer claims Discord/Google ship first-party (they're official external
   installs) or that cost-v1 rides a DataPart (it's the artifact metadata map); the README

README.md

@@ -53,7 +53,7 @@ rename / release-pipeline wiring.
 | Tracing | `observability/tracing.py` | Langfuse trace_session with distributed `a2a.trace` propagation and the OTel cross-context-detach filter |
 | Observability | `observability/metrics.py`, `observability/audit.py` | Prometheus metrics with per-agent prefix, JSONL audit log with trace IDs |
 | Output protocol | `graph/output_format.py` | `<scratch_pad>` / `<output>` parsing so the model can think without it leaking to users |
-| UI | `apps/web/` (React console) | React operator console (the default `--ui console` tier + the Tauri desktop app) over the REST/A2A API — live token-by-token streaming, chat continuity across navigation (+ interrupted-stream self-heal), plugin-contributed rail views, and a PWA shell. See [ADR 0010](./docs/adr/0010-headless-setup-and-ui-tiers.md) |
+| UI | `apps/web/` (React console) | React operator console (the default `--ui console` tier + the Tauri desktop app) over the REST/A2A API — live token-by-token streaming, chat continuity across navigation (+ interrupted-stream self-heal), plugin-contributed rail views, a ⌘K command palette + presence-aware Fleet Room, `/export` (save a chat to Markdown) and `/btw` (a side question answered from the chat's context, saved nowhere), and a PWA shell. See [ADR 0010](./docs/adr/0010-headless-setup-and-ui-tiers.md) |
 | Release pipeline | `.github/workflows/*.yml` | Autonomous semver bumps, GHCR image push, GitHub release with filtered notes, optional Discord post |
 
 ## Quickstart — from zero to chatting in 5 minutes
@@ -74,8 +74,9 @@ uv sync && uv run python -m server          # core, serves the React console (--
 #   python -m server
 
 # 3. Open the wizard — pick your endpoint, pick a model, name the
-#    agent, pick a persona preset, hit Launch. The console chat appears
-#    once setup completes.
+#    agent, pick an archetype (Basic, Cowork, Project Manager, Design System
+#    Engineer — or any installed bundle that declares one), hit Launch. The
+#    console chat appears once setup completes.
 open http://localhost:7870
 ```
 
@@ -172,9 +173,13 @@ First-party plugins ship in `plugins/` — `delegates` is a built-in, `notes`, `
 | [`artifact`](./plugins/artifact/) | tools · view · skill | **On by default** — generative UI; `show_artifact` renders charts, diagrams, Mermaid, Markdown, or live React into a sandboxed panel ([ADR 0038](./docs/adr/0038-generative-ui-artifacts-two-mode.md)) |
 | [`craft`](./plugins/craft/) | skills · subagent | **On by default** — engineering rituals as user-only slash commands (`/grill`, `/standup`, `/code-review`, `/writing-skills`) + the `skill_writer` subagent; prompt-only |
 | [`plugin-devkit`](./plugins/plugin-devkit/) | tool · subagent · skill · workflow · view | The authoring kit + reference plugin — the agent can scaffold and build its own plugins |
-| [`workflows`](./plugins/workflows/) | tools | Declarative multi-step subagent workflows (DAG recipes) |
+| [`workflows`](./plugins/workflows/) | tools | Declarative multi-step subagent workflows (DAG recipes) — a step can carry `gate: human`, pausing for operator approval before it runs |
 | [`telegram`](./plugins/telegram/) | surface | Run the agent as a Telegram bot — the reference [communication plugin](./docs/guides/communication-plugins.md) |
 | [`github`](./plugins/github/) | tools | Read-only GitHub tools over the `gh` CLI |
+| [`execute_code`](./plugins/execute_code/) | tool · settings | A Python interpreter the agent runs code in — on desktop, provision the one-click [managed runtime](./docs/guides/python-runtime.md) and the document skills (docx · xlsx · pptx · pdf) light up |
+| [`coder`](./plugins/coder/) | tool · settings | Verifier-grounded code-solve (`coder_solve`) — an execution-grounded search ladder for testable coding tasks ([guide](./docs/guides/coder.md)) |
+| [`friction`](./plugins/friction/) | tools | Friction log — the agent records its own missing/awkward tooling and confusing errors, so you can fix the sharp edges |
+| [`orgchart`](./plugins/orgchart/) | view | Live diagram of the agent fleet — every agent a node, delegation edges drawn as they happen |
 | [`hello`](./plugins/hello/) | tool · skill · view | Minimal example — copy it to start your own |
 
 Integrations like **Discord**, **Slack** (Socket Mode `ChatAdapter`) and **Google**

ROADMAP.md

@@ -17,7 +17,8 @@ In-progress ref points at a closed issue — rotate shipped work into `## Shippe
 
 ## In progress
 
-- **Image generation plugin (protobanana)** — generate → look → refine image workflows on the new media platform: tools save artifacts the chat renders inline, and the vision model critiques its own output.
+- **Design-system alignment** — migrating the remaining bespoke console surfaces onto DS primitives as the design system grows (bottom sheet for the mobile session sheet, dense icon buttons — tracked in protoContent).
+
 
 ## Shipped
 

docs/.vitepress/config.mts

@@ -20,7 +20,7 @@ export default defineConfig({
 
   // docs/dev/ is the team's internal engineering area (handoffs + notes) — it
   // lives in the repo (committed, shared) but is NOT part of the published site.
-  srcExclude: ["dev/**"],
+  srcExclude: ["dev/**", "design/**"],
 
   head: [
     ["link", { rel: "icon", type: "image/svg+xml", href: `${base}favicon.svg` }],
@@ -142,6 +142,7 @@ export default defineConfig({
           collapsed: false,
           items: [
             { text: "Operator console (React/Tauri)", link: "/guides/react-tauri-ui" },
+            { text: "Managed Python runtime (desktop)", link: "/guides/python-runtime" },
             { text: "Command palette (⌘K)", link: "/guides/command-palette" },
             { text: "Developer flags (gate pre-release features)", link: "/guides/developer-flags" },
             { text: "Access from your phone (LAN / Tailscale)", link: "/guides/phone-access" },

docs/guides/index.md

@@ -78,6 +78,7 @@ Surface the agent to people — the operator console, or no UI at all.
 | Guide | When to read |
 |---|---|
 | [Operator console (React/Tauri)](/guides/react-tauri-ui) | You want the multi-chat React console and to package it for desktop |
+| [Managed Python runtime (desktop)](/guides/python-runtime) | You're on the desktop app and `execute_code` / the document skills (docx · xlsx · pptx · pdf) need their one-click interpreter install |
 | [Command palette (⌘K)](/guides/command-palette) | You want the fast keyboard path to jump between surfaces + inline chat |
 | [Developer flags](/guides/developer-flags) | You want to merge a half-built feature behind a tiered flag (off/dev/beta/on) instead of a long-lived branch |
 | [Access from your phone (LAN / Tailscale)](/guides/phone-access) | You want to drive the agent from your phone — installable PWA over your LAN or tailnet, add-to-home-screen |

docs/guides/python-runtime.md

@@ -0,0 +1,74 @@
+# Managed Python runtime (desktop)
+
+On the **packaged desktop app** the server is a frozen binary — `sys.executable` *is*
+protoAgent, not a Python interpreter — so [`execute_code`](/guides/plugins) has nothing
+to run child code with. The **managed Python runtime**
+([ADR 0094](../adr/0094-managed-python-runtime.md)) fixes that: a one-click, consented
+download of a pinned CPython that the desktop app owns, plus the **document baseline**
+([ADR 0092](../adr/0092-desktop-document-baseline-and-versioned-file-artifacts.md)) —
+the libraries that let document skills produce real `.docx` / `.xlsx` / `.pptx` / `.pdf`
+files.
+
+**Source runs never need this.** A `python -m server` / `uv run` instance spawns its own
+interpreter; every status surface reports `needed: false` and stays hidden. This page is
+desktop-only behavior.
+
+## What needs it
+
+- **`execute_code`** — the in-tree Python-interpreter plugin. On a frozen build its tool
+  registers either way, but calls return an actionable "runtime isn't installed yet"
+  notice until you provision.
+- **Everything routed through `execute_code`** — above all the **Cowork document skills**
+  (docx / xlsx / pptx / reportlab-PDF). This is why the Cowork archetype declares
+  `requires: [python_runtime]` and the new-agent picker warns at choose-time
+  (see [Fleet § archetypes](/guides/fleet)).
+
+## Install it (once per machine)
+
+Two equivalent paths — both fetch a **hash-verified CPython 3.12.13** (the frozen
+sidecar's own interpreter line, ~35 MB) and then pip-install the document baseline
+(`apps/desktop/sidecar/requirements-docs.txt`) into the runtime's own site-packages:
+
+- **Console** — **Settings ▸ Tools** shows an install card while the runtime is missing:
+  one click, live progress (download → document libraries), done. The card renders
+  nothing once the runtime is present and current.
+- **CLI** — `protoagent runtime install-python` (and `protoagent runtime list` shows
+  `python: not provisioned — …` / version + baseline state).
+
+The download is a deliberate consent point — ~130 MB on disk after the baseline lands —
+so nothing auto-provisions.
+
+## How you find out before something fails
+
+- **Settings nav badge** — the **Tools** entry carries a warning dot whenever the
+  runtime needs attention (not provisioned, stale baseline, failed install; pulsing
+  while an install runs), so the state is visible while browsing, not mid-task.
+- **Archetype choose-time warning** — picking an archetype that declares
+  `requires: [python_runtime]` (Cowork) shows a notice under the card grid when this
+  host's runtime isn't ready.
+- **Actionable tool copy** — an `execute_code` call on an unprovisioned build returns
+  the fix ("Settings ▸ Tools, or `protoagent runtime install-python`") instead of a
+  bare error.
+
+## The baseline can go stale
+
+The runtime records a hash of the `requirements-docs.txt` it installed. When a release
+changes the document pins, the status flips to `baseline_current: false` and the
+surfaces above offer an **update** (re-runs the pip phase only) — the runtime itself
+stays put.
+
+## Status & API
+
+`GET /api/runtime/python` returns `{python, install}`:
+
+| Key | Meaning |
+|---|---|
+| `needed` | this process would use it (frozen builds only) |
+| `managed` / `managed_version` / `exe` | a working install is present, its version, its interpreter path |
+| `baseline_installed` / `baseline_current` | document-library state vs the current pins |
+| `supported` / `target_version` | can this platform/arch provision, and what an install fetches |
+
+`POST /api/runtime/python/install` starts the provisioning in the background (`202`;
+poll the GET for phase + percent). Unsupported platform/arch combinations return the
+banner state instead — `execute_code` (and the skills behind it) can't run on that
+desktop build.

docs/guides/react-tauri-ui.md

@@ -133,6 +133,10 @@ parallel with engine startup** (#2203): the in-app UpdateNotice pulls that resul
 it mounts and opens the changelog modal if a newer build exists — so the prompt lands before
 the engine finishes booting, then the normal 10s-settle + 6h re-check cycle takes over.
 
+On a frozen build, `execute_code` (and the document skills behind it) need the one-click
+[managed Python runtime](/guides/python-runtime) — Settings ▸ Tools shows the install card
+until it's provisioned.
+
 On macOS, `spawn_sidecar` augments the sidecar's `PATH` with the user's login-shell `PATH`
 (via `$SHELL -ilc`, plus the Homebrew/local fallbacks) before spawning. A Finder/Dock launch
 otherwise inherits only `launchd`'s minimal `PATH`, so `npx`/`node`/ACP coding-agent adapters

docs/index.md

@@ -21,6 +21,8 @@ features:
     details: DuckDuckGo web search, URL fetch, safe calculator, and IANA-timezone clock — zero API keys, enough to demo a real research loop on a fresh clone.
   - title: A lean core, opt-in plugins
     details: Start small; add tools, skills, subagents, workflows, FastAPI routes, console dashboards, memory backends, and managed MCP servers as git-URL plugins (python -m server plugin install, pinned in plugins.lock) — without touching core. Telegram and the plugin-devkit ship in-tree; Discord, Google (Gmail+Calendar), and more install as official external plugins from the directory.
+  - title: Archetypes + real documents
+    details: Spin up agents from starter types — Cowork, Project Manager, Design System Engineer, or any bundle that declares one. Cowork's document skills produce real .docx/.xlsx/.pptx/.pdf via execute_code and the one-click managed Python runtime on desktop.
   - title: Release pipeline
     details: Dispatch prepare-release → semver bump PR → merge → tag → GHCR image → GitHub release → Discord embed. Flip the RELEASE_ENABLED repo variable to enable it on a fork.
 ---

plugins/docs/nav.json

@@ -183,6 +183,10 @@
           "path": "guides/react-tauri-ui.md",
           "title": "Operator console (React/Tauri)"
         },
+        {
+          "path": "guides/python-runtime.md",
+          "title": "Managed Python runtime (desktop)"
+        },
         {
           "path": "guides/command-palette.md",
           "title": "Command palette (⌘K)"

sites/marketing/data/roadmap.json

@@ -43,8 +43,8 @@
     "status": "In progress",
     "items": [
       {
-        "title": "Image generation plugin (protobanana)",
-        "detail": "generate → look → refine image workflows on the new media platform: tools save artifacts the chat renders inline, and the vision model critiques its own output.",
+        "title": "Design-system alignment",
+        "detail": "migrating the remaining bespoke console surfaces onto DS primitives as the design system grows (bottom sheet for the mobile session sheet, dense icon buttons — tracked in protoContent).",
         "refs": []
       }
     ]