superbee 0.0.1 → 0.1.1-pre.2

package/references/views/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/views/roadmap.html

@@ -0,0 +1,226 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Roadmap</title>
+<style>
+  :root {
+    --paper:#F8F6F2; --white:#fff; --rule:#E0DDD8; --mist:#EDF0F3;
+    --ink:#0F1A24; --slate:#4A5D6E; --ghost:#9AAAB8;
+    --blue:#1B6A9E; --teal:#0A8A7A; --amber:#B8832A;
+    --radius:2px;
+    --serif: "Cormorant Garamond", "Iowan Old Style", Georgia, "Times New Roman", serif;
+    --sans: -apple-system, "Segoe UI", system-ui, sans-serif;
+    --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root { --paper:#0B1926; --white:#0F2A3F; --rule:#26323d; --mist:#132636;
+      --ink:#F8F6F2; --slate:#9fb2c2; --ghost:#6f8494; --amber:#E0AA40; }
+  }
+  * { box-sizing:border-box; margin:0; }
+  body { background:var(--paper); color:var(--ink); font:15px/1.55 var(--sans); }
+  header { padding:22px 32px 14px; border-bottom:1px solid var(--rule); background:var(--white); }
+  header h1 { font-family:var(--serif); font-weight:500; font-size:30px; letter-spacing:.01em; display:flex; align-items:baseline; gap:12px; }
+  header h1 .chev { color:var(--blue); font-family:var(--sans); font-weight:700; }
+  header .sub { color:var(--slate); font-size:13px; margin-top:2px; }
+  header .live { float:right; font-size:11.5px; color:var(--teal); font-family:var(--mono); }
+  header .live .dot { display:inline-block; width:7px; height:7px; border-radius:50%; background:var(--teal); margin-right:5px; animation:pulse 1.4s infinite; }
+  @keyframes pulse { 50%{opacity:.3} }
+  main { max-width:900px; margin:0 auto; padding:26px 32px 80px; }
+  .group { margin-bottom:34px; }
+  .group > h2 { font-family:var(--sans); font-size:12px; font-weight:700; text-transform:uppercase; letter-spacing:.09em; color:var(--slate); display:flex; align-items:center; gap:9px; margin-bottom:4px; }
+  .group > h2 .swatch { width:10px; height:10px; border-radius:2px; }
+  .group > .note { font-size:12px; color:var(--ghost); margin-bottom:12px; }
+  .item { background:var(--white); border:1px solid var(--rule); border-radius:var(--radius); border-left:3px solid var(--rule); margin-bottom:10px; overflow:hidden; }
+  .item.active { border-left-color:var(--teal); }
+  .item.committed { border-left-color:var(--blue); }
+  .item.candidate { border-left-color:var(--amber); }
+  .item .head { display:flex; align-items:center; gap:12px; padding:13px 16px; cursor:pointer; }
+  .item .head:hover { background:var(--mist); }
+  .item .title { font-family:var(--serif); font-size:19px; font-weight:500; flex:1; line-height:1.2; }
+  .item .caret { color:var(--ghost); font-size:12px; transition:transform .15s; }
+  .item.open .caret { transform:rotate(90deg); }
+  .badge { font-family:var(--sans); font-size:10.5px; font-weight:600; padding:2px 8px; border-radius:999px; white-space:nowrap; letter-spacing:.02em; }
+  .badge.active { color:var(--teal); background:color-mix(in srgb,var(--teal) 13%,transparent); }
+  .badge.queued { color:var(--slate); background:var(--mist); }
+  .badge.candidate { color:var(--amber); background:color-mix(in srgb,var(--amber) 15%,transparent); }
+  .badge.done { color:var(--slate); background:var(--mist); }
+  .roll { display:flex; align-items:center; gap:9px; padding:0 16px 12px; }
+  .bar { flex:1; height:5px; background:var(--mist); border-radius:3px; overflow:hidden; display:flex; }
+  .bar i { height:100%; display:block; }
+  .bar i.done { background:var(--teal); } .bar i.prog { background:var(--amber); } .bar i.open { background:var(--rule); }
+  .roll .count { font-family:var(--mono); font-size:11.5px; color:var(--slate); white-space:nowrap; }
+  .roll .none { font-size:11.5px; color:var(--ghost); font-style:italic; }
+  .body { display:none; padding:2px 16px 14px; border-top:1px solid var(--rule); }
+  .item.open .body { display:block; }
+  .desc { font-size:13.5px; color:var(--slate); margin:12px 0; max-width:70ch; }
+  .tasks { display:flex; flex-direction:column; gap:1px; }
+  .task { display:flex; align-items:center; gap:10px; padding:6px 8px; border-radius:2px; }
+  .task:hover { background:var(--mist); }
+  .task .tdot { width:7px; height:7px; border-radius:50%; flex:none; }
+  .task .ttitle { flex:1; font-size:13.5px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .task .tid { font-family:var(--mono); font-size:11px; color:var(--ghost); }
+  .st-todo{color:var(--slate)} .st-in_progress{color:var(--amber)} .st-blocked,.st-canceled{color:#c0392b} .st-done{color:var(--teal)}
+  .d-todo{background:var(--ghost)} .d-in_progress{background:var(--amber)} .d-blocked,.d-canceled{background:#c0392b} .d-done{background:var(--teal)}
+  .item.fresh { animation:land 1.8s ease-out; }
+  @keyframes land { 0%{background:color-mix(in srgb,var(--amber) 18%,var(--white))} 100%{background:var(--white)} }
+  footer { text-align:center; color:var(--ghost); font-size:11.5px; padding:20px; font-family:var(--mono); }
+  .empty { color:var(--ghost); text-align:center; margin-top:16vh; font-family:var(--serif); font-size:20px; }
+</style>
+</head>
+<body>
+<header>
+  <span class="live" id="live"><span class="dot"></span>live</span>
+  <h1><span class="chev">&rsaquo;</span> Roadmap</h1>
+  <div class="sub" id="sub">loading the graph…</div>
+</header>
+<main id="main"><div class="empty">reading the roadmap…</div></main>
+<footer>rendered live from the bundle graph — items &middot; contained tasks &middot; candidate vs committed</footer>
+<script>
+(function () {
+  var PROTO="v0", seq=0, pending={}, subs=[];
+  function send(type, extra){ return new Promise(function(res,rej){ var id=String(++seq); pending[id]={res:res,rej:rej};
+    var m={bridge:PROTO,id:id,type:type}; if(extra) for(var k in extra) m[k]=extra[k]; parent.postMessage(m,"*"); }); }
+  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; 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.rej(new Error((m.error&&m.error.message)||"bridge error")); else p.res(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})}, edges:function(params){return send("edges",{params:params})},
+    openPage:openPage,
+    subscribe:function(cb){subs.push(cb); return send("subscribe")},
+    watch:watch };
+})();
+
+(function(){
+  "use strict";
+  var mainEl=document.getElementById("main"), subEl=document.getElementById("sub");
+  var openIds={}, freshIds=new Set();
+  function esc(s){return String(s==null?"":s).replace(/[&<>"]/g,function(c){return {"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"}[c]})}
+  function fm(r){return r.frontmatter||{}}
+  function progress(f){return f.progress_status}
+
+  function classify(it){
+    var s=progress(fm(it));
+    if(s==="active") return "active";
+    if(s==="done"||s==="canceled") return "done";
+    // queued: committed if it has a sequence, candidate if not
+    return (fm(it).sequence!=null && String(fm(it).sequence).trim()!=="") ? "committed" : "candidate";
+  }
+  var GROUPS=[
+    {key:"active",   label:"In motion",  swatch:"var(--teal)", note:"actively being worked"},
+    {key:"committed",label:"Committed",  swatch:"var(--blue)", note:"sequenced, not yet started"},
+    {key:"candidate",label:"Candidate",  swatch:"var(--amber)",note:"recognized direction — not yet committed or sequenced (queued + no sequence). Awaiting a founders' decision."},
+    {key:"done",     label:"Done",       swatch:"var(--slate)",note:""}
+  ];
+
+  function render(items, taskById, containsByItem){
+    if(!items.length){ mainEl.innerHTML='<div class="empty">no roadmap items yet</div>'; return; }
+    var byGroup={active:[],committed:[],candidate:[],done:[]};
+    items.forEach(function(it){ byGroup[classify(it)].push(it); });
+    // committed sorts by sequence
+    byGroup.committed.sort(function(a,b){ return (+fm(a).sequence||0)-(+fm(b).sequence||0); });
+    var html="";
+    GROUPS.forEach(function(g){
+      var list=byGroup[g.key]; if(!list.length) return;
+      html+='<div class="group"><h2><span class="swatch" style="background:'+g.swatch+'"></span>'+g.label+' &middot; '+list.length+'</h2>';
+      if(g.note) html+='<div class="note">'+esc(g.note)+'</div>';
+      list.forEach(function(it){
+        var id=it.id, f=fm(it), open=openIds[id];
+        var contained=(containsByItem[id]||[]);
+        var tstats=contained.map(function(tid){ var t=taskById[tid]; return t?progress(fm(t)):null; });
+        var done=tstats.filter(function(s){return s==="done"||s==="canceled"}).length;
+        var prog=tstats.filter(function(s){return s==="in_progress"||s==="blocked"}).length;
+        var total=contained.length;
+        html+='<div class="item '+g.key+(open?" open":"")+(freshIds.has(id)?" fresh":"")+'" data-id="'+esc(id)+'">';
+        html+='<div class="head" data-toggle="'+esc(id)+'"><span class="caret">&rsaquo;</span>'+
+              '<span class="title">'+esc(f.title||id)+'</span>'+
+              '<span class="badge '+(g.key==="candidate"?"candidate":(progress(f)||"queued"))+'">'+(g.key==="candidate"?"candidate":esc(progress(f)||"queued"))+'</span></div>';
+        // rollup
+        html+='<div class="roll">';
+        if(total){ var wd=Math.round(done/total*100), wp=Math.round(prog/total*100);
+          html+='<div class="bar"><i class="done" style="width:'+wd+'%"></i><i class="prog" style="width:'+wp+'%"></i><i class="open" style="width:'+(100-wd-wp)+'%"></i></div>'+
+                '<span class="count">'+done+'/'+total+' done</span>';
+        } else { html+='<span class="none">no contained tasks yet</span>'; }
+        html+='</div>';
+        // body
+        html+='<div class="body"><div class="desc">'+esc(f.description||"—")+'</div><div class="tasks">';
+        contained.forEach(function(tid){ var t=taskById[tid]; var s=t?progress(fm(t)):"?";
+          html+='<div class="task"><span class="tdot d-'+esc(s)+'"></span><span class="ttitle">'+esc(t?fm(t).title:tid)+'</span>'+
+                '<span class="badge st-'+esc(s)+'" style="background:transparent">'+esc(s)+'</span><span class="tid">'+esc(tid)+'</span></div>';
+        });
+        if(!total) html+='<div class="task"><span class="none">— no <code>contains</code> edges into this item</span></div>';
+        html+='</div></div></div>';
+      });
+      html+='</div>';
+    });
+    mainEl.innerHTML=html;
+    mainEl.querySelectorAll("[data-toggle]").forEach(function(el){
+      el.addEventListener("click",function(){ var id=el.getAttribute("data-toggle"); openIds[id]=!openIds[id];
+        el.closest(".item").classList.toggle("open"); });
+    });
+  }
+
+  function load(freshChanged){
+    return Promise.all([
+      Bridge.query({type:"Roadmap Item"}),
+      Bridge.query({type:"Task"}),
+      Bridge.edges({text:"contains"})   // <- the NEW edges bridge: all containment edges in one call
+    ]).then(function(r){
+      var items=r[0].rows||[], tasks=r[1].rows||[], edges=r[2].edges||[];
+      var taskById={}; tasks.forEach(function(t){ taskById[t.id]=t; });
+      var containsByItem={};
+      edges.forEach(function(e){ if(e.from.indexOf("roadmap-items/")===0 && e.to.indexOf("tasks/")===0){
+        (containsByItem[e.from]=containsByItem[e.from]||[]).push(e.to); } });
+      if(freshChanged){ freshChanged.forEach(function(id){freshIds.add(id)});
+        setTimeout(function(){ freshChanged.forEach(function(id){freshIds.delete(id)}); },1900); }
+      subEl.textContent=items.length+" roadmap items · "+edges.length+" contains-edges · "+tasks.length+" tasks — live graph";
+      render(items, taskById, containsByItem);
+    }).catch(function(err){ mainEl.innerHTML='<div class="empty">graph read failed: '+esc(err.message)+'</div>'; });
+  }
+
+  Bridge.hello().then(function(info){
+    document.querySelector("header .chev").title=(info.bundle&&info.bundle.name)||"";
+  }).catch(function(err){ console.error("Bridge.hello failed",err); });
+  Bridge.watch(function(events){
+    var changed=[];
+    events.forEach(function(ev){ (ev.changes||[]).forEach(function(c){changed.push(c.id)}); });
+    return load(changed.length?changed:null);
+  }).catch(function(err){ mainEl.innerHTML='<div class="empty">bridge failed: '+esc(err.message)+'</div>'; });
+  setInterval(function(){ /* keep-live heartbeat noop */ },60000);
+})();
+</script>
+</body>
+</html>

package/references/views/views-registry/about.md

@@ -0,0 +1,12 @@
+---
+type: View
+title: About this bundle
+entry: views/about.html
+description: A content view with no bundle-data access that demonstrates registered View navigation.
+access: none
+actor: mike/claude
+timestamp: "2026-07-10T00:00:00.000Z"
+---
+A fixture for the `access: none` content-view path: arbitrary self-contained HTML the shell
+frames like any bundle view. Bundle-data requests are denied; registered View navigation remains
+available as a capability-independent shell action.

package/references/views/views-registry/pulse.md

@@ -0,0 +1,13 @@
+---
+type: View
+title: Pulse — activity feed
+entry: views/pulse.html
+description: Live activity feed — every bundle doc, newest first, with type filters, search, and a markdown detail pane.
+access: bundle-read
+actor: mike/claude
+timestamp: "2026-07-09T00:00:00.000Z"
+---
+A live feed of every document in the bundle, newest first, grouped by recency with type filter
+chips and a search box. Selecting a row opens a detail pane that renders the doc's body as
+markdown, including clickable relative doc links. New writes stream in over the bridge's `change`
+events and land with a brief highlight — no reload.

package/references/views/views-registry/roadmap.md

@@ -0,0 +1,12 @@
+---
+type: View
+title: Roadmap
+entry: views/roadmap.html
+description: Live graph view — Roadmap Items grouped by status, each expandable to its contained tasks with a derived rollup bar.
+access: bundle-read
+actor: mike/claude
+timestamp: "2026-07-09T00:00:01.000Z"
+---
+Roadmap Items grouped into In motion / Committed / Candidate / Done, each expandable to the tasks
+it `contains` (fetched with one call to the bridge's `edges` request) with a derived done/total
+rollup bar. Updates to either an item or one of its tasks stream in live, no reload.