superbee 0.0.1 → 0.1.1-pre.2

package/package.json

@@ -1,10 +1,41 @@
 {
   "name": "superbee",
-  "version": "0.0.1",
-  "description": "Shared agent memory. A versioned markdown knowledge bundle that lives in your repo, plus a CLI for humans and agents.",
-  "keywords": ["agents", "agent-memory", "context", "knowledge-base", "markdown", "cli", "coordination"],
-  "homepage": "https://getsuperbee.com",
-  "license": "MIT",
-  "author": "Holaxis",
-  "files": ["README.md"]
+  "version": "0.1.1-pre.2",
+  "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": [
+    "okf",
+    "knowledge",
+    "agent",
+    "axi",
+    "cli",
+    "markdown",
+    "context-notes"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Holaxis-ai/superbee#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Holaxis-ai/superbee.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Holaxis-ai/superbee/issues"
+  },
+  "bin": {
+    "superbee": "dist/superbee.mjs",
+    "aslite": "dist/superbee.mjs",
+    "agentstate-lite": "dist/superbee.mjs"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "references",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
 }

package/references/recipes/claims/conventions/claim.md

@@ -0,0 +1,39 @@
+---
+type: Convention
+title: Claim
+governs: Claim
+path: claims/
+links:
+  supersedes: Claim
+fields:
+  required:
+    - title
+    - progress_status
+    - reason
+  optional:
+    - artifacts
+    - evidence_command
+    - evidence_commit
+  values:
+    progress_status:
+      - active
+      - challenged
+      - locked
+      - deprecated
+---
+
+# Claim
+
+A data-derived finding with provenance and a verification lifecycle. The `title` IS the
+claim: one sentence carrying the specific numbers. `progress_status` is the lifecycle —
+`active` (filed) → `challenged` (under independent check) → `locked` (verified
+end-to-end; citable in final outputs) — or `deprecated` (superseded; never deleted).
+`reason` says how the number was derived or why it changed. `evidence_command` is the
+exact command that reproduces the number; `evidence_commit` the commit it ran against;
+`artifacts` points at supporting files.
+
+Transitions are CAS writes: capture the head with `doc read <id> --field head_version`,
+pass it as `--expected-version` — a racing writer is refused, never silently overwritten
+(the ported `--parent-event-id` semantics). Locked claims change only by deprecation plus
+a linked successor. Documents that cite a claim link to it; backlinks enumerate every
+citation when the claim changes.

package/references/recipes/claims/recipe.md

@@ -0,0 +1,34 @@
+---
+type: Recipe
+id: claims
+title: Claims
+version: 1.0.0
+summary: "Declares the Claim kind: event-lifecycle claims for data-derived numbers (progress_status enum active/challenged/locked/deprecated, required provenance), composed entirely from lite primitives"
+---
+
+# Claims
+
+Installs the `Claim` kind convention: a single source of truth for data-derived findings,
+ported from the holaxis-claims event-sourced JSONL system onto lite's native primitives.
+
+A claim is a `type: Claim` doc under `claims/<section>/`. Its **title carries the claim
+text with its specific numbers** ("759 tests pass across six workspaces" — not "the suite
+is green"). Its lifecycle is the validated `progress_status` enum: `active` (filed, working
+hypothesis) → `challenged` (under independent verification) → `locked` (provenance chain
+verified end-to-end; only locked claims belong in final outputs) — or `deprecated` (facts
+changed; never delete, file a successor and link it). `reason` records how the number was
+derived or why it changed; `evidence_command` + `evidence_commit` pin the exact
+reproduction.
+
+Everything composes from existing primitives — no claims engine:
+- the optimistic lock is `doc update --expected-version` (capture the token with
+  `doc read <id> --field head_version`);
+- the event trail is doc history (native on enforced backends; git log on file bundles);
+- actor attribution is the engine's own `--actor` on every write;
+- **citations are links**: a document that cites a claim links to it, so `link show
+  <claim>` lists every citing document — the blast radius of a deprecation, precomputed.
+
+Rules of use (the discipline the schema cannot enforce): claims are the source of truth
+for numbers — a number in a document without a locked claim is unverified; weight by
+progress status; verify by re-running `evidence_command`, not by re-reading the claim; a locked
+claim is never edited — deprecate it and file a successor.

package/references/recipes/review-workflow/conventions/review-request.md

@@ -0,0 +1,44 @@
+---
+type: Convention
+title: Review Request
+governs: Review Request
+path: review-requests/
+description: A durable request for a named human to judge a defined question against linked evidence.
+links:
+  reviews design: Design
+  reviews task: Task
+  reviews roadmap item: Roadmap Item
+link_descriptions:
+  reviews design: A design whose reasoning or contract is under review.
+  reviews task: Implementation work whose scope or result informs the judgment.
+  reviews roadmap item: The strategic commitment affected by the judgment.
+fields:
+  required: [title, progress_status, reviewer, requested_by, question]
+  optional: [decision_summary, decided_at]
+  values:
+    progress_status: [requested, in_review, changes_requested, approved, canceled]
+  value_descriptions:
+    progress_status:
+      requested: Ready for the reviewer; no review is yet in progress.
+      in_review: The reviewer is actively considering the request.
+      changes_requested: Work must be addressed before another decision.
+      approved: The reviewer accepted the proposal; terminal for this request.
+      canceled: The requester withdrew the request; terminal for this request.
+  terminal:
+    progress_status: [approved, canceled]
+  descriptions:
+    title: A concise label for the review outcome being sought.
+    progress_status: The persisted review lifecycle state, not an activity update.
+    reviewer: The human expected to make the judgment; coordination metadata, not authorization.
+    requested_by: The human accountable for the scope and evidence supplied.
+    question: The exact judgment the reviewer is being asked to make.
+    decision_summary: A concise persisted outcome recorded after the review.
+    decided_at: The ISO 8601 timestamp at which the persisted decision was made.
+sections: [Context, Requested decision, Acceptance criteria, Reviewer response]
+---
+# Review Request
+
+Create a Review Request when a decision must survive chat history and remain visible to humans and
+agents. The named reviewer owns the response; the requester owns scope, evidence, resubmission, and
+cancellation. Record responses through version-guarded, attributed updates. The View is a
+projection and never becomes the decision authority.

package/references/recipes/review-workflow/conventions/view.md

@@ -0,0 +1,71 @@
+---
+type: Convention
+title: View
+governs: View
+path: views-registry/
+fields:
+  required:
+    - title
+    - entry
+    - access
+  optional:
+    - description
+    - entry_version
+    - presentation
+  values:
+    access:
+      - none
+      - bundle-read
+      - bundle-propose
+    presentation:
+      - workspace
+      - inline
+      - adaptive
+  terminal: {}
+timestamp: "2026-07-24T00:00:00.000Z"
+---
+# View
+
+A bundle-hosted UI view. A `type: View` doc is a **registry entry**: it names a self-contained
+HTML blob (`entry`, a bundle-relative blob key under `views/…`) that the `superbee ui`
+launcher renders in a sandboxed, opaque-origin iframe. The view reaches bundle data only through
+the narrow postMessage bridge documented in the bundle's
+[View authoring reference](../references/view-authoring-v0.md) — it never holds a credential.
+V0 is read-only; `bundle-propose` adds only a trusted-shell-confirmed v1 scalar action.
+
+`Page` is the legacy name for this kind, and `bridge` the legacy spelling of `access` — and
+neither is read any longer: a legacy `type: Page` doc does not register, and a doc declaring
+only the legacy `bridge` field resolves to `access: none`. Docs under the legacy
+`pages-registry/`/`pages/` prefixes stay recognized where they are once typed `View`; the
+repo's `migrate-legacy-view-names` script renames leftover legacy names in place
+(`superbee status` lists them under `legacy_naming`). Author views as `type: View` with `access`.
+
+- `title` (required) — the launcher card's heading.
+- `entry` (required) — the HTML blob key, e.g. `views/roadmap.html`.
+- `entry_version` (optional) — an exact content-version pin. When present, every host refuses to
+  launch the View if the current entry bytes no longer match it. Ordinary mutable Views may omit it.
+- `description` (optional) — one line shown on the launcher card.
+- `presentation` (optional) — an advisory host-layout hint: `workspace | inline | adaptive`.
+  It never controls whether a host may run the View and never grants authority. A host may ignore
+  it when its available surface differs from the author's preference.
+- `access` (required) — `none | bundle-read | bundle-propose`. Required so every View is an INTENTIONAL
+  classification, not a silent default — an author who forgets to declare it gets a clear
+  authoring-time lint, not a view that quietly renders empty against a full bundle. ENFORCED by
+  the shell too, not just linted: absent, malformed, or any value other than exactly
+  `bundle-read` or `bundle-propose` is treated as `none` at runtime — fail-closed defense for a doc this convention
+  didn't govern (an external bundle, a hand-edited file that skipped the lint).
+  - `bundle-read` — a **data view**: the shell answers its bridge requests (`hello`/`query`/
+    `read`/`render-document`/`edges`/`subscribe`) with live bundle data. Groups under the launcher's "Dashboards".
+  - `bundle-propose` — an **interactive view**: includes the read surface and may propose one
+    declared scalar field update. Every proposal is independently validated and shown in trusted
+    shell chrome; only the human's Apply action authorizes a hard-CAS local write.
+  - `none` — a **content view**: the shell DENIES every bundle-data request. Arbitrary
+    self-contained HTML with zero bundle-data access — a report, a rendered design doc, a diagram.
+    It may still ask the shell to open another registered View. Groups under "Documents".
+
+Both capabilities may use `open-page` (the bridge's wire verb, kept stable across the rename) to
+navigate to another valid registered View. This shell action returns no target content or
+metadata and grants no bundle-data capability.
+
+Views sync, version, and attribute like any doc; the HTML bytes travel as an opaque blob via
+`promote`/`pull`, never through the model context window.

package/references/recipes/review-workflow/recipe.md

@@ -0,0 +1,20 @@
+---
+type: Recipe
+id: review-workflow
+title: Review Workflow
+version: "1"
+summary: Durable human review requests with a live, generic evidence View.
+content_policy: definitions-only
+references:
+  - references/view-authoring-v0.md
+pages:
+  - registry: views-registry/review-workflow-reviews.md
+    entry: views/review-workflow/reviews.html
+---
+# Review Workflow
+
+Install a durable human-review operating model without installing any review instances or project
+content. The `Review Request` Kind is the decision authority; the View is a live, read-only
+projection. Its versioned View-authoring reference travels into the target bundle with the
+definitions, so agents can inspect and extend the UI without an agent-harness skill. Agents create
+and update requests through the generic Kind-aware CLI.

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

@@ -0,0 +1,324 @@
+---
+type: Reference
+title: Bundle View authoring — shared web and MCP contract
+protocol: v0+v1
+timestamp: "2026-07-22T00:00:00.000Z"
+---
+
+# Bundle View authoring — shared web and MCP contract
+
+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.
+
+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
+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
+`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
+states.
+
+```sh
+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
+client below. A content View (`access: none`) may use only `openPage`; bundle-data calls return
+`FORBIDDEN`.
+
+Install the HTML blob and its registry entry:
+
+```sh
+superbee promote my-view.html --doc-key views/my-view.html
+superbee new "View" my-view \
+  --title "My view" \
+  --entry views/my-view.html \
+  --access bundle-read \
+  --description "A live view of this bundle."
+superbee ui --open
+```
+
+`new "View" my-view` applies the View Kind's declared `views-registry/` path. Use `access: none`
+for a static report or diagram. Re-promoting the HTML updates the open View; the shell reloads it
+with a fresh nonce. If the bundle does not yet declare the View Kind, install its View-bearing
+recipe or promote the supplied `conventions/view.md` once before creating the registry entry.
+
+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.
+
+## The bridge client (embedded copy)
+
+```js
+(function () {
+  var PROTO = "v0", seq = 0, pending = {}, subs = [];
+  function send(type, extra) {
+    return new Promise(function (resolve, reject) {
+      var id = String(++seq);
+      pending[id] = { resolve: resolve, reject: reject };
+      var msg = { bridge: 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
+    });
+  }
+  // A shell action, deliberately separate from send(): the source frame may unload immediately,
+  // so openPage is void/fire-and-forget and must not be awaited.
+  function openPage(pageId) {
+    parent.postMessage({ bridge: PROTO, type: "open-page", pageId: pageId }, "*");
+  }
+  function watch(refresh) {
+    if (typeof refresh !== "function") return Promise.reject(new TypeError("Bridge.watch requires a refresh function"));
+    var active = true, ready = false, running = false, queued = [];
+    function schedule(initial) {
+      running = true;
+      var batch = queued.splice(0);
+      return Promise.resolve().then(function () { return refresh(batch); }).then(function (value) {
+        running = false;
+        if (queued.length) void schedule(false);
+        return value;
+      }, function (err) {
+        running = false;
+        if (queued.length) void schedule(false);
+        if (initial) throw err;
+        console.error("Bridge.watch refresh failed", err);
+      });
+    }
+    function onChange(event) {
+      if (!active) return;
+      queued.push(event);
+      if (ready && !running) void schedule(false);
+    }
+    return window.Bridge.subscribe(onChange).then(function () {
+      ready = true;
+      return schedule(true);
+    }, function (err) {
+      active = false;
+      throw err;
+    });
+  }
+  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.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);
+  });
+  window.Bridge = {
+    hello: function () { return send("hello"); },
+    query: function (params) { return send("query", { params: params }); },
+    read: function (docId) { return send("read", { docId: docId }); },
+    renderDocument: function (docId) { return send("render-document", { docId: docId }); },
+    edges: function (params) { return send("edges", { params: params }); },
+    openPage: openPage,
+    subscribe: function (cb) { subs.push(cb); return send("subscribe"); },
+    watch: watch
+  };
+})();
+```
+
+Compose and style the trusted fragment inside the View; do not rewrite or concatenate its HTML:
+
+```js
+async function showDocument(docId) {
+  var rendered = await Bridge.renderDocument(docId);
+  documentPanel.innerHTML = rendered.html;
+}
+documentPanel.addEventListener("click", function (event) {
+  var target = event.target instanceof Element ? event.target.closest("[data-aslite-doc-id]") : null;
+  if (target) void showDocument(target.getAttribute("data-aslite-doc-id"));
+});
+```
+
+```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
+Bridge.watch(async function (events) {
+  var result = await Bridge.query({ type: "Task" });
+  render(result.rows, events);
+}).catch(showStartupError);
+```

package/references/recipes/review-workflow/views/review-workflow/reviews.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Review requests</title>
+<style>
+:root{color-scheme:light dark;--paper:#fffefa;--ink:#19212b;--muted:#68727d;--line:#d9d6ce;--navy:#173b57;--soft:#e5f0f5}*{box-sizing:border-box}body{margin:0;background:#f4f2ed;color:var(--ink);font:15px/1.5 system-ui,sans-serif}header{padding:24px max(20px,5vw);background:var(--navy);color:white}h1{margin:0;font:500 32px Georgia,serif}header p{margin:5px 0 0;opacity:.75}main{max-width:1000px;margin:auto;padding:28px max(20px,5vw)}.card{background:var(--paper);border:1px solid var(--line);border-radius:9px;padding:20px;margin:0 0 14px}.top{display:flex;justify-content:space-between;gap:16px;align-items:flex-start}.title{font:500 23px Georgia,serif}.status{font:700 11px ui-monospace,monospace;text-transform:uppercase;background:var(--soft);padding:5px 9px;border-radius:999px}.meta{color:var(--muted);font-size:13px;margin-top:8px}.question{font:500 18px Georgia,serif;margin-top:16px}.empty,.error{text-align:center;color:var(--muted);padding:15vh 10px}.error{color:#a8463d}@media(prefers-color-scheme:dark){:root{--paper:#17212a;--ink:#edf1f4;--muted:#a3afb9;--line:#34414c;--soft:#203846}body{background:#111820}}
+</style>
+</head>
+<body>
+<header><h1>Review requests</h1><p id="state">Connecting to this bundle…</p></header>
+<main id="app"><div class="empty">Subscribing before reading…</div></main>
+<script>
+(function(){
+  "use strict";
+  var seq=0,pending=Object.create(null),listeners=[],app=document.getElementById("app"),state=document.getElementById("state");
+  function request(type,extra){return new Promise(function(resolve,reject){var id=String(++seq),message={bridge:"v0",id:id,type:type};pending[id]={resolve:resolve,reject:reject};Object.assign(message,extra||{});parent.postMessage(message,"*")})}
+  window.addEventListener("message",function(event){if(event.source!==parent)return;var message=event.data;if(!message||message.bridge!=="v0")return;if(message.type==="change"){listeners.slice().forEach(function(listener){listener()});return}var item=pending[message.id];if(!item)return;delete pending[message.id];if(message.type==="error")item.reject(new Error(message.error&&message.error.message||"Bridge error"));else item.resolve(message.result)});
+  function esc(value){return String(value==null?"":value).replace(/[&<>"']/g,function(char){return{"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}[char]})}
+  function reload(){state.textContent="Refreshing…";return request("query",{params:{type:"Review Request"}}).then(function(result){var rows=(result.rows||[]).slice().sort(function(a,b){return String(b.frontmatter.timestamp||"").localeCompare(String(a.frontmatter.timestamp||""))});state.textContent=rows.length+" durable request"+(rows.length===1?"":"s")+" · live";if(!rows.length){app.innerHTML='<div class="empty">No Review Requests yet. This view will update when one is created.</div>';return}app.innerHTML=rows.map(function(row){var value=row.frontmatter||{},progress=value.progress_status;return '<article class="card"><div class="top"><div><div class="title">'+esc(value.title||row.id)+'</div><div class="meta">Reviewer: '+esc(value.reviewer||"not named")+' · Requested by: '+esc(value.requested_by||"not named")+'</div></div><span class="status">'+esc(progress||"unknown")+'</span></div><div class="question">'+esc(value.question||"No review question supplied")+'</div></article>'}).join("")}).catch(function(error){state.textContent="Read failed";app.innerHTML='<div class="error">'+esc(error.message)+'</div>'})}
+  listeners.push(reload);
+  request("subscribe").then(reload).catch(function(error){state.textContent="Subscription failed";app.innerHTML='<div class="error">'+esc(error.message)+'</div>'});
+})();
+</script>
+</body>
+</html>

package/references/recipes/review-workflow/views-registry/review-workflow-reviews.md

@@ -0,0 +1,8 @@
+---
+type: View
+title: Review requests
+entry: views/review-workflow/reviews.html
+description: Live, generic review handoffs with their dynamically linked evidence.
+access: bundle-read
+---
+A read-only projection of every Review Request in this bundle.

package/references/sample-bundle/concepts/index.md

@@ -0,0 +1,4 @@
+# Concept
+
+* [OKF Alignment](okf-alignment.md) - How Superbee maps agent knowledge onto Open Knowledge Format primitives.
+* [The Link Graph](link-graph.md) - How standard markdown links become an untyped directed graph with derived backlinks.

package/references/sample-bundle/concepts/link-graph.md

@@ -0,0 +1,25 @@
+---
+type: Concept
+title: The Link Graph
+description: How standard markdown links become an untyped directed graph with derived backlinks.
+tags: [okf, links, graph]
+timestamp: 2026-07-01T12:05:00Z
+---
+# Summary
+
+OKF cross-links are ordinary markdown links `[text](target)` — never wikilinks.
+A link `A -> B` is an *untyped* directed edge; the relationship kind lives in the
+surrounding prose, not in a typed-edge slot. Backlinks are **derived**, not
+stored: a consumer reverses the resolved edge set to compute "Cited by".
+
+# Example
+
+This concept explains the model that [OKF Alignment](./okf-alignment.md) depends
+on, so the alignment note links here and this note links back — a two-way edge
+the visualizer draws once and the backlink index reflects on both ends. The
+governing rules are defined in the
+[Open Knowledge Format v0.1 (Draft)](../references/okf-spec.md), §5.
+
+# Citations
+
+1. [Open Knowledge Format v0.1 (Draft)](../references/okf-spec.md)