superbee 0.2.1-pre.2 → 0.3.0-pre.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.2.1-pre.2",
+  "version": "0.3.0-pre.1",
   "type": "module",
   "description": "Agent-facing Superbee CLI for reading and writing local OKF knowledge bundles: context notes, docs, cross-links, and live bundle Views.",
   "keywords": [
@@ -54,11 +54,9 @@
   "scripts": {
     "build": "node build.mjs local-dev",
     "build:npm-package": "node build.mjs npm-package",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "typecheck": "tsc --noEmit",
     "pretest": "node build.mjs local-dev",
-    "test:host-class": "node scripts/run-test-command.mjs node --test --import ./test/ts-loader.mjs ./test/private-state-bundle-boundary.test.ts ./test/filesystem-cross-process-cas.test.ts ./test/link.test.ts ./test/promote-pull.test.ts ./test/recipe-source.test.ts ./test/command-text.test.ts",
-    "test": "node scripts/run-test-command.mjs node --test --import ./test/ts-loader.mjs ./test/*.test.ts",
-    "mutation": "node scripts/run-test-command.mjs npm-exec stryker run",
+    "test": "node --test test/*.test.mjs",
     "gen:skill": "node scripts/gen-skill.mjs",
     "check:skill": "node scripts/gen-skill.mjs --check",
     "prepublishOnly": "node -e \"console.error('superbee is released by .github/workflows/release.yml (npm stage publish); do not run npm publish here'); process.exit(1)\""
@@ -73,7 +71,7 @@
     "@superbee/publication": "*",
     "@superbee/server": "*",
     "@superbee/ui-server": "*",
-    "@toon-format/toon": "2.3.0",
+    "@toon-format/toon": "2.3.1",
     "@types/node": "^22.0.0",
     "axi-sdk-js": "0.1.8",
     "esbuild": "0.25.12",
@@ -81,8 +79,13 @@
     "pako": "2.1.0",
     "typescript": "^5.4.0",
     "js-yaml": "3.15.2",
-    "@types/js-yaml": "3.12.10"
+    "@types/js-yaml": "3.12.10",
+    "@superbee/cli": "*"
   },
-  "readme": "# superbee\n\nShared, versioned, conflict-safe knowledge for AI coding agents, stored as plain markdown in\nyour repo.\n\nSuperbee is pre-1.0. Commands and formats may change between releases.\n\n## What is Superbee?\n\nAgents forget everything between sessions, overwrite each other's work, and keep what they know\ninvisible to the humans they work for. Superbee fixes all three with a **knowledge bundle**: a\nfolder of markdown documents, by convention `.superbee/` at your project root, that agents read\nand write through a small command-line tool.\n\n- **Context that persists.** Agents write context notes, decisions, plans, and research into the\n  bundle. The next session, or a different agent, picks up where the last one left off. An\n  optional `SessionStart` hook for Claude Code, Codex, and OpenCode orients every new session\n  automatically.\n- **Safe for many writers.** Each write can carry the actor that made it. A writer can name the\n  version it last read; if anyone changed the document since, the write fails with a typed\n  conflict error instead of silently overwriting their work.\n- **Visible to humans.** The bundle is plain markdown. Open it in any editor, render it on\n  GitHub, diff it in git. `superbee ui` serves it locally as cross-linked pages with backlinks and\n  a live activity feed. No bundle content leaves your machine until you run `superbee sync`, which\n  shares the bundle with teammates through the board: a copy of the bundle kept on its own git\n  branch, separate from your code.\n- **Views on demand.** Ask your agent for a dashboard, a timeline, a filtered task queue, or a\n  reading view of one dense document. It builds a self-contained HTML page, stores it in the bundle\n  as a View, and `superbee ui` hosts it in a sandboxed frame. A View reads the bundle live and can\n  change it only through a write you confirm. Views are bundle content, so they travel with `sync`.\n- **Built for agents.** Output is structured and token-lean, and errors carry a small, stable set\n  of exit codes. Agents act on responses without parsing prose or flooding their context window.\n- **Yours, and portable.** Bundles follow the Open Knowledge Format (OKF), a convention of\n  markdown with frontmatter, so they outlive the tool: hand the folder to someone else, or read it\n  with anything that speaks markdown. New bundles are written as OKF v0.2, and existing v0.1\n  bundles keep working as they are. Reading and writing the bundle works offline; only sharing\n  needs a network. The document schemas, called kinds, live inside the bundle, so it describes\n  its own structure.\n\nThe npm package is one self-contained executable with zero runtime dependencies, plus an Agent\nSkill, an instruction file your agent loads, that teaches it how to use the tool.\n\n## Install\n\nRequires Node.js 20 or newer on macOS, Linux, or Windows. Native Windows is supported; you do not\nneed WSL or Docker.\n\n```sh\nnpm install -g superbee\n```\n\nStable releases publish on npm's `latest` tag and prereleases on `next`. To try the prerelease:\n\n```sh\nnpm install -g superbee@next\n```\n\nOn Windows, Superbee keeps its private per-user state, such as the workspace catalog and remote\ncredentials, under `%LOCALAPPDATA%\\Superbee`. npm installs `superbee.cmd` alongside the `superbee`\ncommand; if PowerShell's execution policy blocks the `.ps1` wrapper, call `superbee.cmd` instead.\n\nRun `superbee version --check` to compare your install with the current stable release.\n\n## First run: let your agent finish setup\n\n`npm install` gives you the CLI. The integrations (the Agent Skill, the `SessionStart` hook, and\nMCP server registration, where MCP is the Model Context Protocol) are installed by your agent,\nnot by hand. Ask it:\n\n> Run `superbee setup` and follow its instructions.\n\nSetup itself changes nothing. It inspects your configuration and returns one safe next command at\na time, and the agent runs each with your approval. Setup knows Claude Code, Codex, and OpenCode,\nplus Claude Desktop for the MCP registration only.\n\n## Everyday use\n\nYou rarely type Superbee commands yourself. You ask your agent, and the Agent Skill translates the\nrequest into CLI calls:\n\n- \"Set up a Superbee bundle for this project and track our tasks in it.\"\n- \"Write up what we decided about the auth design as a doc, and link it to the task.\"\n- \"What did the last session leave off on? Check the context notes.\"\n- \"Sync the board so my teammate's agent sees this.\"\n- \"Give me a view of the open tasks grouped by owner.\"\n\nBehind those requests the agent uses a small set of commands: `init --dir .superbee` creates the\nbundle, `new` creates a document of a declared kind, `doc write` writes a free-form one,\n`doc update` changes a document, `link add` connects two, `list` and `doc read` query them, and\n`sync` shares the board. `superbee --help` lists the commands, and `superbee <command> --help`\ngives each one's full reference.\n\nThe two commands meant for you are the ones that show you the knowledge:\n\n```sh\nsuperbee ui --open        # the whole bundle, rendered in your browser\nsuperbee doc open <id>    # one document, by an id from `superbee list`\n```\n\n## Upgrading from aslite\n\nIf you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install\n`superbee` alongside it, have your agent run `superbee setup` to migrate the integrations, then\nrun `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and\n`.agentstate.json` bindings keep working with no migration.\n\n## Learn more\n\nThe [repository](https://github.com/Holaxis-ai/superbee) holds the source, the\n[CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/cli/AXI-CONTRACT.md),\nand the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).\n\n## License\n\nApache-2.0 © 2026 Holaxis\n",
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "readme": "# superbee\n\nShared, versioned, conflict-safe knowledge for AI coding agents, stored as plain markdown in\nyour repo.\n\nSuperbee is pre-1.0. Commands and formats may change between releases.\n\n## What is Superbee?\n\nAgents forget everything between sessions, overwrite each other's work, and keep what they know\ninvisible to the humans they work for. Superbee fixes all three with a **knowledge bundle**: a\nfolder of markdown documents, by convention `.superbee/` at your project root, that agents read\nand write through a small command-line tool.\n\n- **Context that persists.** Agents write context notes, decisions, plans, and research into the\n  bundle. The next session, or a different agent, picks up where the last one left off. An\n  optional `SessionStart` hook for Claude Code, Codex, and OpenCode orients every new session\n  automatically.\n- **Safe for many writers.** Each write can carry the actor that made it. A writer can name the\n  version it last read; if anyone changed the document since, the write fails with a typed\n  conflict error instead of silently overwriting their work.\n- **Visible to humans.** The bundle is plain markdown. Open it in any editor, render it on\n  GitHub, diff it in git. `superbee ui` serves it locally as cross-linked pages with backlinks and\n  a live activity feed. No bundle content leaves your machine until you run `superbee sync`, which\n  shares the bundle with teammates through the board: a copy of the bundle kept on its own git\n  branch, separate from your code.\n- **Views on demand.** Ask your agent for a dashboard, a timeline, a filtered task queue, or a\n  reading view of one dense document. It builds a self-contained HTML page, stores it in the bundle\n  as a View, and `superbee ui` hosts it in a sandboxed frame. A View reads the bundle live and can\n  change it only through a write you confirm. Views are bundle content, so they travel with `sync`.\n- **Built for agents.** Output is structured and token-lean, and errors carry a small, stable set\n  of exit codes. Agents act on responses without parsing prose or flooding their context window.\n- **Yours, and portable.** Bundles follow the Open Knowledge Format (OKF), a convention of\n  markdown with frontmatter, so they outlive the tool: hand the folder to someone else, or read it\n  with anything that speaks markdown. New bundles are written as OKF v0.2, and existing v0.1\n  bundles keep working as they are. Reading and writing the bundle works offline; only sharing\n  needs a network. The document schemas, called kinds, live inside the bundle, so it describes\n  its own structure.\n\nThe npm package is one self-contained executable with zero runtime dependencies, plus an Agent\nSkill, an instruction file your agent loads, that teaches it how to use the tool.\n\n## Install\n\nRequires Node.js 20 or newer on macOS and Linux. Native Windows is not supported by this package.\n\n```sh\nnpm install -g superbee\n```\n\nStable releases publish on npm's `latest` tag and prereleases on `next`. To try the prerelease:\n\n```sh\nnpm install -g superbee@next\n```\n\nWindows adapters and the `superbee-windows` executable live in a separate repository and are\nnot included in `superbee`. Most Windows users should run Superbee in WSL2, where npm sees a\nLinux platform and the normal installation applies. An experimental, unsupported native Windows\nbuild is available as open source, with build-from-source instructions: https://github.com/Holaxis-ai/superbee-windows-cli\n\n### Upgrading an existing Windows installation\n\nThe first release containing the Windows extraction removes native Windows support from this\npackage. Its npm `os` metadata permits only `darwin` and `linux`, so a Windows upgrade to an affected\nversion is rejected with `EBADPLATFORM`. This applies to existing prerelease users too. Forcing the\ninstallation does not restore support: the executable refuses commands on unsupported hosts\nbefore running them (the bare `--version` flag can still identify the installed build).\n\nThere is no supported Windows replacement on npm. The alternatives are WSL2 or the experimental\nbuild from source at https://github.com/Holaxis-ai/superbee-windows-cli; neither carries a\nfirst-party support promise for native Windows. An older installed version is not converted or\nremoved by this source change, and existing bundle files are not migrated by it. Review the affected release's notes before changing an existing\nWindows installation. macOS/Linux users can continue using the normal installation and setup flow.\n\nRun `superbee version --check` to compare your install with the current stable release.\n\n## First run: let your agent finish setup\n\n`npm install` gives you the CLI. The integrations (the Agent Skill, the `SessionStart` hook, and\nMCP server registration, where MCP is the Model Context Protocol) are installed by your agent,\nnot by hand. Ask it:\n\n> Run `superbee setup` and follow its instructions.\n\nSetup itself changes nothing. It inspects your configuration and returns one safe next command at\na time, and the agent runs each with your approval. Setup knows Claude Code, Codex, and OpenCode,\nplus Claude Desktop for the MCP registration only.\n\n## Everyday use\n\nYou rarely type Superbee commands yourself. You ask your agent, and the Agent Skill translates the\nrequest into CLI calls:\n\n- \"Set up a Superbee bundle for this project and track our tasks in it.\"\n- \"Write up what we decided about the auth design as a doc, and link it to the task.\"\n- \"What did the last session leave off on? Check the context notes.\"\n- \"Sync the board so my teammate's agent sees this.\"\n- \"Give me a view of the open tasks grouped by owner.\"\n\nBehind those requests the agent uses a small set of commands: `init --dir .superbee` creates the\nbundle, `new` creates a document of a declared kind, `doc write` writes a free-form one,\n`doc update` changes a document, `link add` connects two, `list` and `doc read` query them, and\n`sync` shares the board. `superbee --help` lists the commands, and `superbee <command> --help`\ngives each one's full reference.\n\nThe two commands meant for you are the ones that show you the knowledge:\n\n```sh\nsuperbee ui --open        # the whole bundle, rendered in your browser\nsuperbee doc open <id>    # one document, by an id from `superbee list`\n```\n\n## Upgrading from aslite\n\nIf you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install\n`superbee` alongside it, have your agent run `superbee setup` to migrate the integrations, then\nrun `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and\n`.agentstate.json` bindings keep working with no migration.\n\n## Learn more\n\nThe [repository](https://github.com/Holaxis-ai/superbee) holds the source, the\n[CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/superbee/AXI-CONTRACT.md),\nand the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).\n\n## License\n\nApache-2.0 © 2026 Holaxis\n",
   "readmeFilename": "README.md"
 }

package/references/recipes/review-workflow/references/view-authoring-v0.md

@@ -1,190 +1,98 @@
 ---
 type: Reference
-title: Bundle View authoring — shared web and MCP contract
+title: Bundle View authoring
 protocol: v0+v1
-timestamp: "2026-07-22T00:00:00.000Z"
+timestamp: "2026-09-15T00:00:00.000Z"
 ---
 
-# Bundle View authoring — shared web and MCP contract
+# Bundle View authoring
 
-Author **one durable View** for both local web and MCP hosts: a self-contained, responsive HTML
-blob under `views/…` plus a `type: View` registry doc under `views-registry/…`. Both hosts launch
-the same registry id, exact HTML bytes, access declaration, and bridge contract. The host chooses
-the available size and may offer expansion; do not create separate inline, expanded, web, or MCP
-implementations.
+Author **one durable View** for every host: a self-contained, responsive HTML blob under `views/...`
+plus a `type: View` registry doc under `views-registry/...`. The local web shell, the MCP host, a
+published Portal artifact and the hosted workspace all launch the same registry id, exact HTML
+bytes, access declaration and bridge contract. The host chooses the available size and may offer
+expansion; do not create separate inline, expanded, web or MCP implementations.
 
-Use the bridge for bundle data and `render-document` for canonical Markdown presentation. Style
-the returned inert fragment inside the View; do not ship another Markdown parser. The sections
-below are the exact protocol contract and copy-paste client. This contract travels with portable
+The protocol a View speaks is owned by one document in the Superbee repository:
+`docs/VIEW-PROTOCOL.md` (https://github.com/Holaxis-ai/superbee/blob/main/docs/VIEW-PROTOCOL.md).
+It holds the exact message shapes, the `field` filter grammar, what `open` means, the host
+descriptor and capability registry, conformance levels, limits and the error table. This reference
+is the short bundle-installed companion: enough to build a View from a bundle, with a copy of the
+reference client. When the two disagree, the protocol document wins. It travels with portable
 View-bearing recipes, so authoring does not depend on an agent-harness skill.
 
 Legacy `Page` and `bridge` are retired authoring names. Use `type: View` and `access`; `superbee status`
 reports legacy content that needs migration. Legacy wire names such as `open-page` remain stable.
 
-## Trust model (exact-byte approval + no credential)
-
-The `ui` server serves two privilege tiers on one loopback origin:
-
-- **Data API** (`/v0/*`): reachable ONLY with the shell's per-run session token/cookie.
-- **View bytes** (`/__page/<nonce>`): a view's static HTML, served for a short-lived **nonce**
-  the session-authed shell mints (`POST /__page/mint`) for that view's one blob key. The nonce
-  is not the session token, so it is rejected by every data route; the session token does not
-  open the page route to arbitrary keys.
-
-The iframe is `sandbox="allow-scripts"` with **no** `allow-same-origin`, so the view runs at an
-**opaque origin**. A strict per-view CSP (`connect-src 'none'`) blocks ordinary direct network APIs
-such as fetch, XHR, WebSocket, and EventSource, while the View never receives the shell's credential
-or a data endpoint. Those controls are defense-in-depth: a data-bearing View is executable code,
-and approving its exact bytes and declared access is the decision to trust that code. Approve only
-a View whose source or author you trust; changed bytes or expanded access ask again. The supported
-bundle-data channel is `postMessage` to the shell, whose stable v0 bridge is read-only. A View that
-declares `bundle-propose` may additionally ask trusted shell chrome to prepare one v1 scalar-field
-action; only the human's shell-native Apply choice authorizes the CAS write.
-
-## Message shapes
-
-Every message carries `bridge: "v0"`. A request carries an `id`; the reply echoes it as
-`"<type>:result"` (or `"error"`). The shell drops any message whose `event.source` is not the
-view's own iframe; the view drops any message whose `event.source` is not `window.parent`.
-
-### View → shell (requests)
-
-| type        | payload                                                    | reply `result`                                             |
-| ----------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
-| `hello`     | —                                                          | `{ bundle: { root, name }, mode, protocol: "v0", grant }` |
-| `query`     | `{ params: { type?, prefix?, field?, open?, limit? } }`    | `{ rows: DocHead[], count }`                               |
-| `read`      | `{ docId }`                                                | `{ id, frontmatter, body }`                                |
-| `render-document` | `{ docId }`                                         | `{ document: { id, version }, html, bounded }`              |
-| `edges`     | `{ params: { from?, to?, text? } }`                        | `{ edges: { from, to, text }[], count }`                   |
-| `subscribe` | —                                                          | `{ ok: true }`, then a stream of `change` events          |
-| `open-page` | `{ pageId: "views-registry/…" }`                           | none; fire-and-forget shell navigation                    |
-
-`hello.result.grant` is `"read"` for `bundle-read` and `"propose"` for `bundle-propose`.
-
-`open-page` is the sole capability-independent action: `access: none`, `access: bundle-read`, and
-`access: bundle-propose` Views may ask the shell to open another usable registered View. The shell
-accepts only a conservative `views-registry/…` (or legacy-location `pages-registry/…`) concept
-id, validates that it resolves to a `type: View` doc with a safe `views/…`
-(or legacy-location `pages/…`) entry, and mounts the target normally with its own sandbox, nonce, and
-bridge capability. It returns no target body, frontmatter, entry, HTML, or nonce. A failed
-attempt can reveal that one caller-supplied registry id is not usable; this bounded existence
-oracle is the only information exposed by navigation.
-
-`DocHead` is `{ id, version, frontmatter }` — the same **head projection** `list` uses (full
-frontmatter, never a body). `query` params:
-
-`render-document` reads the canonical document and serializes its body with the shell's shared,
-bounded Markdown renderer. The returned `html` is inert semantic markup: it contains no scripts,
-event handlers, forms, controls, images, or navigable anchors. Internal concept links become
-passive elements carrying `data-aslite-doc-id`; the View may delegate clicks on those markers to
-its own selection logic and issue another `render-document` request. Insert only the unmodified
-`html` returned by this request. The accompanying document `version` is the exact version rendered;
-after a matching `change` event, refetch instead of treating old HTML as current. `bounded: true`
-means renderer safety limits truncated or collapsed part of the input.
-
-- `type` / `prefix` — server-side facets (a bundle-relative id prefix, a frontmatter `type`).
-- `field` — a client-side `key=value` filter; comma-separated values are OR (`progress_status=todo,blocked`).
-  Scalar and array-valued fields use the same string-coerced membership rule as CLI `list`.
-- `open` — drop terminal rows, derived from the BUNDLE'S OWN kind conventions exactly like
-  `list --open`: a row is dropped iff the convention governing its `type` declares the row's
-  current field value(s) terminal (`fields.terminal`, e.g. the Task kind's `done`/`canceled`).
-  A row with no governing kind is kept; a bundle where no kind declares a terminal set filters
-  nothing. (The shell loads the registry once per change from the server, which builds it with
-  core's `loadKinds` — one registry, no bridge-side schema.)
-- `limit` — a positive number caps `rows`; `0` or absence is unlimited. `count` remains the total
-  matched after `field`/`open` filtering and before the cap, matching CLI `list`.
-
-`edges` is the general graph query — the ONE primitive every edge-shaped question reduces to
-(the same `queryEdges` atom `link list` is a CLI face over). `params`:
-
-- `from` / `to` — each one exact nonblank concept id, a bundle-relative `prefix/` (trailing
-  slash), or an array of 1–32 such strings (union within the facet; giving both ANDs them). Omit
-  the property for "no restriction". Supplied empty/all-whitespace strings, empty arrays,
-  blank/non-string array entries, and arrays above 32 are invalid. Every string is preserved
-  byte-for-byte and may be at most 1,024 UTF-8 bytes; duplicate entries still count toward 32.
-- `text` — one exact nonblank link-display string (never substring/regex), preserved byte-for-byte
-  and at most 1,024 UTF-8 bytes; an empty/all-whitespace value is invalid.
-
-Backlinks are `edges({ to: docId })`; a container's contents are `edges({ from: itemId, text:
-"contains" })` (or whatever link text a bundle's convention uses) — there is no separate
-backlinks-only bridge call. A source linking to the same target twice with different text yields
-two rows (no dedup), matching `queryEdges`'s own granularity.
-
-### Shell → view (server-initiated)
-
-| type     | payload                                              |
-| -------- | --------------------------------------------------- |
-| `change` | `{ event: { changes: [{ id, version }], removed: [id] } }` |
-
-`change` is pushed only to a view that has `subscribe`d. It is a **delta signal** — refetch with
-`query` against it rather than trusting it as a full state. Removed ids have been deleted.
-
-For live data views, prefer `Bridge.watch(refresh)` over assembling the startup sequence yourself.
-It subscribes before the first snapshot, passes an ordered batch of raw `change` event payloads to
-each refresh, and never overlaps refresh calls. Events arriving during a refresh are coalesced into
-one follow-up batch. A failed refresh does not poison later event-driven refreshes; `watch` does not
-retry on a timer. Its returned Promise covers subscription plus the first refresh, so handle that
-Promise to surface startup failures. Raw `subscribe` remains available when a view needs the
-lower-level event stream.
-
-**There are no mutation messages in v0.** Read-only is enforced *by construction*: the shell
-defines no write/delete/update handler, so any such request returns an `error` reply.
-
-### Trusted action bridge v1
-
-`access: bundle-propose` includes the v0 read surface and adds two exact v1 requests:
-
-- `{ bridge: "v1", type: "read-versioned", id, docId }` returns one canonical document and the
-  version from the same read.
-- `{ bridge: "v1", type: "action.propose", requestId, action: { kind:
-  "document.set-field", docId, field, value, expectedVersion } }` proposes changing one declared
-  scalar field on an existing governed document.
-
-The shell independently re-reads the View registry, exact HTML version, target document, and Kind;
-shows canonical before/after values outside the iframe; and commits only after the human chooses
-Apply. The approval token and immutable launch identity never enter the iframe. A stale target is a
-visible conflict and is never retried behind the human's back. V1 is local `--dir` only and excludes
-body writes, links, creation, deletion, remote writes, and persistent grants. Start the shell with
-`superbee ui --actor <name>` (or set `SUPERBEE_ACTOR`; `AGENTSTATE_LITE_ACTOR` remains a
-supported compatibility input) to enable proposals.
-
-## Live updates
-
-The shell (only) holds one `EventSource('/events')`. The server watches the bundle — `fs.watch`
-in `--dir` mode, a poll in `--remote` mode — diffs content-addressed **version tokens**, and pushes
-a change delta. The shell fans doc changes into subscribed views as `change` events, and
-**hot-reloads** a view's iframe (with a fresh nonce) when the view's own HTML blob changes. (Remote
-view-blob hot-reload is a labeled follow-up; live doc updates work in both modes.)
-
-## `access` — the enforced data/content split
-
-The registry doc's `access` field decides whether the shell will answer THIS view's bridge
-requests at all — and the shell, not the view, is what enforces it:
-
-- `access: bundle-read` — a **data view**. The shell answers `hello`/`query`/`read`/
-  `render-document`/`edges`/`subscribe` as described above.
-- `access: bundle-propose` — an **interactive view**. It receives the same read surface and may
-  submit the narrow v1 proposal above. Each proposal still requires trusted-shell confirmation.
-- `access: none` — a **content view**. The shell replies to every bundle-data request with a
-  `FORBIDDEN` error, before touching any bundle data. It may still use `open-page` navigation.
-- `bridge` is the legacy spelling of this field, and it is no longer read: a doc declaring only
-  the legacy `bridge` field resolves to `access: none` (every bundle-data request is denied).
-  The repo's `migrate-legacy-view-names` script renames leftover legacy `bridge` fields to
-  `access` in place, and `superbee status` lists them under its `legacy_naming` finding.
-  Authoring uses `access`.
-- The `View` convention declares `access` REQUIRED — every view is an intentional
-  classification, not a silent default. At runtime the shell still fails closed for a doc this
-  convention didn't govern (an external bundle, a hand-edited file that skipped the lint): absent,
-  malformed, or any other value is treated as `access: none`. A view only gets bundle access by
-  declaring exactly `bundle-read` or `bundle-propose`.
-
-The launcher groups views by this same field: "Dashboards" for `bundle-read`, "Interactive" for
+## Trust model
+
+The View runs in an opaque-origin, script-only sandbox with `connect-src 'none'`. It never receives
+a credential, session token or data endpoint; its only channel to bundle data is `postMessage` to
+the shell, which validates every request before touching bundle data. Approving a View means
+approving its exact bytes and declared access; changed bytes or expanded access ask again. Approve
+only a View whose source or author you trust. A View that declares `bundle-propose` may ask the
+trusted shell to prepare one v1 scalar-field action; only the human's shell-native Apply choice
+authorizes the write.
+
+## The requests
+
+Every request carries `bridge: "v0"` (or `"v1"` for `read-versioned` and `action.propose`), an
+`id`, and a `type`; the reply echoes the id as `"<type>:result"` or `"error"` with a code. The
+client below wraps all of them.
+
+| request | ask | answer |
+| --- | --- | --- |
+| `hello` | who is hosting me | `{ bundle: { root, name }, mode, protocol, grant, host: { kind, capabilities, limits } }` |
+| `query` | `{ type?, prefix?, field?, open?, limit? }` | `{ rows: [{ id, version, frontmatter }], count }` |
+| `read` | `docId` | `{ id, frontmatter, body }` |
+| `read-versioned` | `docId` | `{ doc, version }` |
+| `render-document` | `docId` | `{ document: { id, version }, html, bounded }` |
+| `edges` | `{ from?, to?, text? }` | `{ edges: [{ from, to, text }], count }` |
+| `graph` | `includeBodies?` | `{ okfVersion, documents, relationships, counts }` |
+| `subscribe` | none | `{ ok: true }`, then `change` events |
+| `host` | `capability, input?` | `{ capability, output }` or `FORBIDDEN` |
+| `open-page` | `views-registry/...` id | none; fire-and-forget shell navigation |
+
+`hello.result.grant` is `"read"` for `bundle-read` and `"propose"` for `bundle-propose`. Read
+`hello.result.host.capabilities` to learn what this host honors (for example `query.field-or`,
+`query.open`, `edges`, `graph`, `subscribe-deltas`) instead of assuming; every host refuses what it
+does not offer with a `FORBIDDEN` error, never silently.
+
+Use `render-document` for canonical Markdown presentation: the returned `html` is inert markup
+whose internal links carry `data-aslite-doc-id`. Style it inside the View and insert it unmodified;
+do not ship another Markdown parser.
+
+`change` events are a signal to re-query, never full state. `Bridge.watch(refresh)` subscribes
+before the first snapshot, batches events, never overlaps refreshes, and works the same on a host
+that pushes real deltas and on one that only nudges.
+
+## `access`
+
+The registry doc's `access` field decides whether the shell answers this View's bridge requests at
+all, and the shell, not the View, enforces it:
+
+- `access: bundle-read`: a **data view**. The read requests above are answered.
+- `access: bundle-propose`: an **interactive view**. The same reads plus the narrow v1 proposal,
+  each proposal confirmed in trusted shell chrome. Start the shell with `superbee ui --actor <name>`
+  (or set `SUPERBEE_ACTOR`; `AGENTSTATE_LITE_ACTOR` remains a supported compatibility input) to
+  enable proposals.
+- `access: none`: a **content view**. Every bundle-data request answers `FORBIDDEN` before any
+  bundle data is touched. It may still use `open-page` navigation.
+- `bridge` is the legacy spelling of this field and is no longer read: a doc declaring only the
+  legacy `bridge` field resolves to `access: none`. The repo's `migrate-legacy-view-names` script
+  renames leftover legacy `bridge` fields to `access` in place, and `superbee status` lists them
+  under its `legacy_naming` finding.
+- The `View` convention declares `access` REQUIRED. At runtime the shell still fails closed for a
+  doc the convention did not govern: absent, malformed or any other value is treated as
+  `access: none`.
+
+The launcher groups Views by this field: "Dashboards" for `bundle-read`, "Interactive" for
 `bundle-propose`, and "Documents" for `none`.
 
 ## Authoring a view
 
 Start from a working installed View when possible, then adapt it responsively for the space the
-host provides. Keep data selection bounded and show empty, partial, over-limit, and unavailable
+host provides. Keep data selection bounded and show empty, partial, over-limit and unavailable
 states.
 
 ```sh
@@ -192,7 +100,7 @@ superbee blobs --prefix views/
 superbee pull --doc-key views/review-workflow/reviews.html --out my-view.html
 ```
 
-Keep HTML, CSS, and JavaScript self-contained with no external hosts. A data View embeds the bridge
+Keep HTML, CSS and JavaScript self-contained with no external hosts. A data View embeds the bridge
 client below. A content View (`access: none`) may use only `openPage`; bundle-data calls return
 `FORBIDDEN`.
 
@@ -215,23 +123,21 @@ recipe or promote the supplied `conventions/view.md` once before creating the re
 
 Verify the same registered id in both surfaces: open it with `superbee ui`, then have an MCP-capable
 desktop list and show that View. Confirm narrow and expanded layouts without changing the source.
-
-The seed views here are working examples: `pulse.html`/`roadmap.html` are `access: bundle-read`
-data views — `roadmap.html` is the one that exercises the `edges` request end-to-end (a live graph
-view of Roadmap Items and the tasks each one `contains`) — and `about.html` is an `access: none`
-content view (no bridge calls at all). `demo.sh` (repo only) wires all of this over a scratch copy
-of this repo's own board.
+Startup messages are optional: a View may stay quiet until human input and never has to send
+`hello` to prove it loaded.
 
 ## The bridge client (embedded copy)
 
+A byte-for-byte copy of the reference client in `docs/VIEW-PROTOCOL.md`.
+
 ```js
 (function () {
-  var PROTO = "v0", seq = 0, pending = {}, subs = [];
-  function send(type, extra) {
+  var PROTO = "v0", ACTION_PROTO = "v1", seq = 0, pending = {}, subs = [];
+  function send(type, extra, proto) {
     return new Promise(function (resolve, reject) {
       var id = String(++seq);
       pending[id] = { resolve: resolve, reject: reject };
-      var msg = { bridge: PROTO, id: id, type: type };
+      var msg = { bridge: proto || PROTO, id: id, type: type };
       if (extra) for (var k in extra) msg[k] = extra[k];
       parent.postMessage(msg, "*"); // parent origin is opaque to us; the shell validates by source
     });
@@ -274,20 +180,28 @@ of this repo's own board.
   window.addEventListener("message", function (e) {
     if (e.source !== window.parent) return; // only trust the shell
     var m = e.data;
-    if (!m || m.bridge !== PROTO) return;
+    if (!m || (m.bridge !== PROTO && m.bridge !== ACTION_PROTO)) return;
     if (m.type === "change") { subs.forEach(function (cb) { cb(m.event); }); return; }
     var p = pending[m.id];
     if (!p) return;
     delete pending[m.id];
-    if (m.type === "error") p.reject(new Error((m.error && m.error.message) || "bridge error"));
-    else p.resolve(m.result);
+    if (m.type === "error") {
+      var err = new Error((m.error && m.error.message) || "bridge error");
+      err.code = m.error && m.error.code; // one of USAGE, FORBIDDEN, REVOKED, TOO_LARGE, RUNTIME, NOT_FOUND
+      p.reject(err);
+    } else p.resolve(m.result);
   });
   window.Bridge = {
     hello: function () { return send("hello"); },
     query: function (params) { return send("query", { params: params }); },
     read: function (docId) { return send("read", { docId: docId }); },
+    readVersioned: function (docId) { return send("read-versioned", { docId: docId }, ACTION_PROTO); },
     renderDocument: function (docId) { return send("render-document", { docId: docId }); },
     edges: function (params) { return send("edges", { params: params }); },
+    graph: function (includeBodies) { return send("graph", includeBodies === undefined ? undefined : { includeBodies: includeBodies === true }); },
+    host: function (capability, input) {
+      return send("host", input === undefined ? { capability: capability } : { capability: capability, input: input });
+    },
     openPage: openPage,
     subscribe: function (cb) { subs.push(cb); return send("subscribe"); },
     watch: watch
@@ -308,12 +222,6 @@ documentPanel.addEventListener("click", function (event) {
 });
 ```
 
-```css
-.document-panel [data-aslite-rendered-document] { line-height: 1.6; }
-.document-panel h1 { font: 600 1.5rem/1.2 system-ui; }
-.document-panel [data-aslite-doc-id] { cursor: pointer; text-decoration: underline; }
-```
-
 A live view supplies only its domain snapshot and render work:
 
 ```js
@@ -323,20 +231,7 @@ Bridge.watch(async function (events) {
 }).catch(showStartupError);
 ```
 
-## Quiet startup and transport readiness
-
-Startup messages are optional. A View may render static content or remain quiet until human input;
-it does not have to send `hello`, subscribe, or make any other bridge request merely to prove that
-it loaded.
-
-The local web shell may use a shell-authenticated transport receipt after the iframe load event to
-confirm that the nonce response reached the host's completed-response boundary. That receipt stays
-outside the iframe and is **not authorization**: it grants no bridge or trusted-action access, and
-each data or action request still undergoes its own launch-currentness, capability, and exact-byte
-approval checks.
-
-The receipt proves transport completion, not pixels or script execution. With exact authored bytes
-and an opaque-origin iframe, browser cancellation after the response reaches the host's completion
-boundary may remain indistinguishable from successful delivery. The shell's bounded load diagnostic
-therefore cannot identify every response-stage failure without authored cooperation or a different
-isolation contract.
+The seed views shipped beside this reference are working examples: `pulse.html` and `roadmap.html`
+are `access: bundle-read` data views (`roadmap.html` exercises `edges` end to end), `about.html` is
+an `access: none` content view, and `conformance/` is the fixture that exercises every request type
+and reports one row per type.