superbee 0.0.1 → 0.1.1-pre.2

package/references/sample-bundle/concepts/okf-alignment.md

@@ -0,0 +1,26 @@
+---
+type: Concept
+title: OKF Alignment
+description: How Superbee maps agent knowledge onto Open Knowledge Format primitives.
+tags: [okf, design, mapping]
+timestamp: 2026-07-01T12:00:00Z
+---
+# Summary
+
+Superbee is an OKF-native store. Every agent artifact is one OKF concept
+document: a markdown body with a YAML frontmatter block whose only required field
+is `type`. Nothing here is a bespoke database record — it is the format itself.
+
+# How it maps
+
+* An agent **context note** becomes a concept doc — see the
+  [cycle-okf-lite-vision](../context-notes/cycle-okf-lite-vision.md) note, whose
+  `type` is `Context Note`.
+* A **pointer** between notes becomes a standard markdown link, which the graph
+  reverses into backlinks — see [The Link Graph](./link-graph.md).
+* The format we conform to is the
+  [Open Knowledge Format v0.1 (Draft)](../references/okf-spec.md).
+
+# Citations
+
+1. [Open Knowledge Format v0.1 (Draft)](../references/okf-spec.md)

package/references/sample-bundle/context-notes/cycle-okf-lite-vision.md

@@ -0,0 +1,33 @@
+---
+type: Context Note
+title: cycle-okf-lite-vision
+description: Handoff for the OKF-native Superbee vision cycle.
+tags: [claude-orchestrator, superbee, cycle-okf-lite-vision]
+timestamp: 2026-07-01T12:10:00Z
+---
+# Summary
+
+This cycle established that Superbee should be OKF-native rather than a
+store that merely exports to OKF. Notes, links, and freshness map cleanly onto
+OKF concept docs, markdown links, and the `timestamp` field; remote sync is
+deferred to a later adapter. Treat the OKF mapping as settled; treat the exact
+cross-link form (relative vs absolute) as a deliberate, documented choice.
+
+# Decisions
+
+* Emit **relative** cross-links in produced bundles.
+  Rationale: relative links populate the reference visualizer's edge/backlink
+  graph, which skips absolute links.
+
+# Open Questions
+
+* Should the producer mirror Google's stricter `type+title+description+timestamp`
+  requirement, or only the spec's single required `type`? Unresolved until we
+  see how minimal real notes get.
+
+# Pointers
+
+* [OKF Alignment](../concepts/okf-alignment.md) — the concept that records the
+  full mapping this cycle settled.
+* [Open Knowledge Format v0.1 (Draft)](../references/okf-spec.md) — the spec the
+  decisions above are grounded in.

package/references/sample-bundle/context-notes/index.md

@@ -0,0 +1,3 @@
+# Context Note
+
+* [cycle-okf-lite-vision](cycle-okf-lite-vision.md) - Handoff for the OKF-native Superbee vision cycle.

package/references/sample-bundle/index.md

@@ -0,0 +1,8 @@
+---
+okf_version: "0.1"
+---
+# Subdirectories
+
+* [concepts](concepts/index.md) - Core design concepts for Superbee.
+* [context-notes](context-notes/index.md) - Cross-session agent handoffs stored as OKF concepts.
+* [references](references/index.md) - Mirrored external sources cited by the concepts.

package/references/sample-bundle/log.md

@@ -0,0 +1,7 @@
+# Log
+
+## 2026-07-01
+
+* **Creation** Seeded the sample bundle with the `OKF Alignment` and `Link Graph` concepts.
+* **Update** Added the `cycle-okf-lite-vision` context note and wired its pointers into the graph.
+* **Update** Mirrored the OKF spec under `references/` so citations resolve as first-class concepts.

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

@@ -0,0 +1,3 @@
+# Reference
+
+* [Open Knowledge Format v0.1 (Draft)](okf-spec.md) - The vendor-neutral spec Superbee conforms to.

package/references/sample-bundle/references/okf-spec.md

@@ -0,0 +1,27 @@
+---
+type: Reference
+title: Open Knowledge Format v0.1 (Draft)
+description: The vendor-neutral, filesystem-native knowledge format Superbee conforms to.
+resource: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+tags: [okf, spec, reference]
+timestamp: 2026-07-01T11:00:00Z
+---
+# Summary
+
+Open Knowledge Format (OKF) v0.1 (Draft), published by Google Cloud in
+`GoogleCloudPlatform/knowledge-catalog` under `okf/`, defines a "Knowledge
+Bundle" as a directory tree of UTF-8 markdown files. Each non-reserved `.md`
+file is a Concept whose ID is its path minus `.md`. The only required
+frontmatter field is `type`. This document mirrors the external spec as a
+first-class concept (§8) so citations resolve inside the graph.
+
+# Key sections
+
+* §3 bundle structure and reserved filenames (`index.md`, `log.md`).
+* §4 concept documents and §4.1 frontmatter (`type` required).
+* §5 cross-linking: standard markdown links, absolute or relative, untyped.
+* §9 conformance: parseable frontmatter, non-empty `type`, valid index/log.
+
+# Citations
+
+1. [OKF SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)

package/references/views/about.html

@@ -0,0 +1,102 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>About this bundle</title>
+<style>
+  :root {
+    --bg: #fafaf8; --panel: #ffffff; --ink: #1a1a1e; --muted: #71717a;
+    --line: #e4e4e7; --accent: #6d5ae6; --accent-soft: #ece9fc;
+    --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #101014; --panel: #17171c; --ink: #ececf1; --muted: #8e8e98;
+      --line: #26262e; --accent: #9b8cf7; --accent-soft: #262040;
+    }
+  }
+  * { box-sizing: border-box; margin: 0; }
+  html, body { height: 100%; }
+  body {
+    font: 15px/1.6 -apple-system, "Segoe UI", system-ui, sans-serif;
+    background: var(--bg); color: var(--ink);
+  }
+  main { max-width: 40rem; margin: 0 auto; padding: 2.5rem 1.5rem 4rem; }
+  h1 { font-size: 1.5rem; font-weight: 650; letter-spacing: -0.01em; margin-bottom: 0.4rem; }
+  .kicker {
+    color: var(--accent); font-family: var(--mono); font-size: 0.8rem;
+    text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 0.6rem;
+  }
+  p { color: var(--muted); margin-bottom: 1rem; }
+  p strong { color: var(--ink); font-weight: 600; }
+  .card {
+    background: var(--panel); border: 1px solid var(--line); border-radius: 10px;
+    padding: 1rem 1.2rem; margin: 1.5rem 0;
+  }
+  .card h2 { font-size: 0.95rem; margin-bottom: 0.5rem; }
+  .card ul { margin: 0; padding-left: 1.2rem; color: var(--muted); }
+  .card li { margin-bottom: 0.35rem; }
+  code {
+    font-family: var(--mono); background: var(--accent-soft); color: var(--ink);
+    padding: 0.1rem 0.35rem; border-radius: 5px; font-size: 0.85em;
+  }
+  #toggle, #open-roadmap {
+    border: 1px solid var(--line); background: var(--panel); color: var(--ink);
+    border-radius: 8px; padding: 0.4rem 0.9rem; font-size: 0.85rem; cursor: pointer;
+  }
+  #detail { display: none; margin-top: 0.75rem; }
+  #detail.open { display: block; }
+</style>
+</head>
+<body>
+<main>
+  <div class="kicker">Content view</div>
+  <h1>About this bundle</h1>
+  <p>
+    This view is a <strong>content view</strong>: a self-contained HTML file that carries no
+    bundle data of its own and asks the shell for none. It is promoted and served exactly like
+    any other bundle view — versioned, attributed, and portable as a plain HTML file — but it
+    declares <code>access: none</code> in its registry doc, so the shell refuses every bundle-data
+    request on its behalf. It may still ask the trusted shell to open another registered View.
+  </p>
+
+  <div class="card">
+    <h2>Two kinds of view, one mechanism</h2>
+    <ul>
+      <li><strong>Data views</strong> (<code>access: bundle-read</code>) — read live bundle
+        data through the shell's read-only postMessage bridge. Pulse and Roadmap are data views.</li>
+      <li><strong>Content views</strong> (<code>access: none</code>, this view) — arbitrary
+        self-contained HTML: a report, a rendered design doc, a diagram, a note. No bridge calls,
+        no bundle access, enforced by the shell rather than left to convention.</li>
+    </ul>
+  </div>
+
+  <button id="toggle" type="button">Why no bridge call here?</button>
+  <button id="open-roadmap" type="button">Open the Roadmap view</button>
+  <div id="detail">
+    <p>
+      Nothing below was fetched from anywhere — it is inert markup toggled by a few lines of
+      inline JS. A content view may still use scripts for local interaction (this button, for
+      instance); what it cannot do is reach the bundle's data API, because the shell denies every
+      bundle-data request an <code>access: none</code> view sends, regardless of what the view's own
+      script asks for. View navigation reveals only whether the requested registered View exists;
+      it does not expose that View's data or HTML.
+    </p>
+  </div>
+
+  <script>
+    var PROTO = "v0";
+    function openPage(pageId) {
+      parent.postMessage({ bridge: PROTO, type: "open-page", pageId: pageId }, "*");
+    }
+    document.getElementById("toggle").addEventListener("click", function () {
+      document.getElementById("detail").classList.toggle("open");
+    });
+    document.getElementById("open-roadmap").addEventListener("click", function () {
+      openPage("views-registry/roadmap");
+    });
+  </script>
+</main>
+</body>
+</html>

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