superbee 0.4.3 → 0.4.4-pre.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.3",
+  "version": "0.4.4-pre.10",
   "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": [
@@ -41,6 +41,10 @@
     "./portable-export": {
       "types": "./dist/portable-export.d.ts",
       "default": "./dist/portable-export.mjs"
+    },
+    "./publication/site-manifest": {
+      "types": "./dist/publication/site-manifest-entry.d.ts",
+      "default": "./dist/publication-site-manifest.mjs"
     }
   },
   "files": [
@@ -63,10 +67,9 @@
     "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)\""
+    "prepublishOnly": "node -e \"console.error('superbee is released by .github/workflows/release.yml (OIDC trusted publishing); do not run npm publish here'); process.exit(1)\""
   },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.1",
     "@superbee/board-git": "*",
     "@superbee/bundle-descriptor": "*",
     "@superbee/core": "*",
@@ -90,6 +93,6 @@
     "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\nBees build comb one cell at a time. The comb holds what the colony gathers, and its shape shows\nthe next bee where to build and what belongs where. Superbee works the same way: people and\nagents record what they learn in a structure that fits their domain, and that structure guides\nwhoever works next. Each session builds on the last instead of starting over.\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 a supported Node.js 22, 24, or 26 release (22.14.0 minimum) on macOS or 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`.\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\nFor a fresh cloud container, provision Superbee in the environment setup step before agent tool\nuse. Generated hooks bind absolute Node and CLI paths from their installation, so a project hook\ncopied from a laptop does not install Superbee or provide a working container launcher. Configure\nhooks inside the environment and verify startup in a fresh session. Startup pulls are best-effort;\ninspect an explicit `superbee sync` receipt to verify publication of edits.\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",
+  "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\nBees build comb one cell at a time. The comb holds what the colony gathers, and its shape shows\nthe next bee where to build and what belongs where. Superbee works the same way: people and\nagents record what they learn in a structure that fits their domain, and that structure guides\nwhoever works next. Each session builds on the last instead of starting over.\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 a supported Node.js 22, 24, or 26 release (22.14.0 minimum) on macOS or 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\nFor a fresh cloud container, provision Superbee in the environment setup step before agent tool\nuse. Generated hooks bind absolute Node and CLI paths from their installation, so a project hook\ncopied from a laptop does not install Superbee or provide a working container launcher. Configure\nhooks inside the environment and verify startup in a fresh session. Startup pulls are best-effort;\ninspect an explicit `superbee sync` receipt to verify publication of edits.\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`\nsuperbee view open <id>   # one exact local registered View, through a private one-use browser handoff\n```\n\nIn a hosted checkout, `superbee view read <id>` prints a View page's version on the host and\n`superbee view update <id> --expected-version <version>` replaces the page there (sync never sends\n`views/`). Uploading a page never approves its execution.\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/author-an-integration.md

@@ -23,7 +23,7 @@ invent an official support commitment or managed admission.
 
 Validation reads the selected recipe directory and inert accepted plugin metadata. It never imports a module named by the recipe,
 discovers a bundle, writes a document or makes a provider request. Unknown profiles are explicit
-`PROFILE_NOT_AVAILABLE` refusals, not successful compatibility claims. Core supplies `rest-json`; `github-issues` requires explicit registration of the independently installed GitHub plugin. Registered plugin spec checks are deferred to source test/bind/run; validation never imports its module.
+`PROFILE_NOT_AVAILABLE` refusals, not successful compatibility claims. Core supplies `rest-json`; `github-issues` requires explicit registration of the independently installed GitHub plugin. Registered plugin spec checks are deferred to source test/bind/run (new bound-GET policies defer them to run); validation never imports its module.
 An explicitly selected test double does not establish compatibility for an unavailable profile.
 
 The complete package is checked for core's secret-shaped text, including README files; `.env` and
@@ -81,6 +81,15 @@ and findings for every run. A recipe's definitions-only directory and recorded f
 separate. Expected values are compared exactly; missing expectation keys, changed receipts, unused
 recorded exchanges, unscripted requests and failed core invariants fail the command.
 
+For a source with an explicit `request.read_policy`, the fixture author may supply the optional
+top-level `readPolicyApproval` object: `{"contract":1,"digest":"sha256:<reviewed policy digest>"}`.
+Obtain that digest from Core's public `inspectSourceReadPolicy(connector, boundFeed)` for the exact
+reviewed declaration and bound Feed, then record it explicitly. The CLI forwards this fixture data
+to the public Core harness; it never calculates or grants approval automatically. Core refuses
+missing, stale or nonmatching approval before provider requests. The object permits only `contract`
+and `digest`; legacy fixtures without an explicit read policy need no approval. This assertion
+applies only to recorded testing: it grants no live feed binding consent, credential or transport.
+
 Each exchange records the method and URL expected by the public harness and a response (`status`,
 optional headers and body), `{ "fail": true }`, or `{ "hang": true }`. Runs may specify `mode`, `at`,
 `edits` and a bounded engine `budget`. Fixture records can include hostile URLs and other attack
@@ -119,6 +128,32 @@ The public [superbee-plugins repository](https://github.com/Holaxis-ai/superbee-
 qualify mapping and observation behavior; live provider access and managed catalog admission remain
 separate evidence.
 
+## Register a trusted source implementation
+
+Source registration accepts a reviewed built folder containing `package.json` with a
+`superbeeIntegration` descriptor: contract 1, a slug `id`, exact compatible `core`, 1–32
+`profiles` (`id`, positive `version`, relative `.mjs` `entry`) and a `recipes` mapping of
+slug keys to inert Markdown recipe roots. Profile ids cannot shadow built-ins or another
+accepted plugin. Each entry exports `createSourceProfile(helpers)` and returns its declared
+extension profile, using the existing public Core helpers. Entries must be self-contained;
+registration hashes finite UTF-8 bytes, not a dependency graph, publisher identity or sandbox.
+Names and declared paths are bounded; traversal, links, overlapping roots and reserved object
+keys are refused. No provider-specific CLI change is needed for another compatible source.
+
+Register each source folder explicitly, review the proposal and accept its exact digest.
+Resolve its recipes as `<plugin-id>:<recipe-key>`; `source plugin remove <plugin-id>`
+deactivates its future selections. Registration does not grant credentials or alter Core's
+provider host, method or resource policy. A new authenticated provider needs a reviewed Core
+credential-host policy change; additional local GET endpoints require the explicit bound policy and
+feed approval described below. Source and operation registrations are independent grants with separate bind/run
+contracts; a package descriptor never automatically activates another capability.
+
+Existing GitHub acceptance and feed consent remain valid for identical bytes. The first
+successful registration/removal converts the old single-GitHub pointer to a source collection
+at the same private state location. Listing and selection leave the active pointer unchanged. After that conversion, older
+CLI list/select/remove paths refuse the new state; older registration writers are unsupported
+and can replace that collection. Do not use old CLI binaries as writers after upgrading.
+
 ## Register the GitHub integration from a source checkout
 
 The GitHub integration is distributed through the public Git repository; no integration npm
@@ -154,6 +189,57 @@ Rebinding changed consent resets observations and accepted tuples for reacquisit
 availability with `superbee source plugin remove github`; already selected runs may finish their
 selected generation. Existing bundle content and retained generations are preserved.
 
+## Request a narrowly bound local GET policy
+
+A source may opt into a reviewed local endpoint through its existing Connector `request` block:
+
+```yaml
+host: api.github.com
+method: GET
+path: '/repos/{owner}/{repo}/pulls'
+items: ''
+query: {state: all}
+headers: {accept: application/vnd.github+json, x-github-api-version: '2026-03-10'}
+paging: {kind: page-number, page_param: page, size_param: per_page, size: 30}
+read_policy:
+  contract: 1
+  kind: bound-get
+  bindings: {owner: segment, repo: segment}
+  required_permissions: {pull_requests: read}
+  header_provider: github
+```
+
+Its identity resource can be `https://github.com/{owner}/{repo}/pulls`. For detail, declare a separate
+source with resource `https://github.com/{owner}/{repo}/pull/{number}`, path
+`/repos/{owner}/{repo}/pulls/{number}`, `number: positive-integer`, no list query and paging none.
+The integration owns object normalization. [GitHub's REST documentation](https://docs.github.com/en/rest/pulls/pulls)
+provides the endpoint and Pull requests read minimum; opaque token grants remain provider-enforced.
+
+Review the endpoint/query read semantics before accepting its binding: GET alone is not a safety
+proof. Core admits only the exact declared host/path and resource parameters. Contract 1 supports
+none/page-number paging with distinct page/size names outside query, required single page/size
+values, exact query literals or whole bound values, and no body, GraphQL, watermark or cursor form.
+Every declared header is required exactly once with its exact value on every hop. Case duplicates,
+omitted/changed headers, query/paging collisions and undeclared authority refuse. Credential and
+method-override headers remain forbidden. For anonymous version-header reads, use auth none,
+explicit `domains: [api.github.com]`, and omit permission minima. Header-provider constraints grant
+no credential host or environment lookup and preserve keyless robots checks.
+
+New-policy binding preview/acceptance is inert, using accepted profile metadata. Execution compares
+private consent before module import or credential lookup. Changing policy, binding, implementation
+or resolved semantics requires reapproval and resets observation/accepted state. Installing a plugin
+or recipe grants no network access. Managed execution still needs separately deployed operator
+admission, and local code remains trusted code with ambient process authority.
+
+Library hosts use inert `inspectSourceReadPolicy` from `@superbee/core/connectors` and pass its
+approved `{contract: 1, digest}` as `observeSource.readPolicyApproval`. Missing/stale approval denies
+before callbacks/replay. It is an explicit host assertion, not a review certificate. Public recorded
+`SourceFixture` accepts the same explicit `readPolicyApproval`; it is never production consent.
+CLI `source test` JSON remains unchanged and cannot approve these policies. Test them through the
+supported public Core/harness API; do not import private CLI runner/transport seams. Native installed
+registration/bind/refusal, installed public-Core observation, internal transport conformance and live
+provider execution are distinct evidence.
+
 ## Bind and run a local Source Feed
 
 After installing a recipe and creating its Source Feed in a local or Git bundle, preview consent:

package/references/hosted-checkout.md

@@ -80,17 +80,38 @@ Only run it when the person asks for the move.
 
 ## Sharing a hosted bundle, and retiring one
 
-`superbee access list <bundle>` shows the person's own access and, for a workspace admin, everyone
-with access. When the person asks you to share a bundle with someone, run
-`superbee access grant <bundle> <email> --level read|write` without `--yes` first, show the
-preview, then run the `--yes` command it names. `access revoke <bundle> <email>` works the same
-way. Only a workspace admin may change access. `person_not_member` means the person must invite
-them from the Members page in the Superbee app first. Repeating a grant or revoke is safe.
+`superbee access list <bundle>` shows the person's own access and, when the host names it, the
+workspace's web Access page (`access_page`). Sharing is managed there, not from the CLI: hosted
+Superbee answers `access grant` and `access revoke --yes` with `admin_on_web` and changes nothing.
+When the person asks you to share a bundle with someone, tell them a workspace admin gives that
+member read or write on the Access page (`https://<workspace host>/settings/access`); the person
+must already be a member of the workspace (invited from the Members page first). A bundle that
+`superbee publish --to hosted` creates is readable only by its creator until then.
 
 `superbee bundle retire <bundle>` is the person's step, never yours: it needs them to type the
 bundle id in their own terminal. If it refuses with `needs_person_at_terminal`, show the person
 the host's statement and give them the command; do not try to work around it.
 
+## Registering a site's CI: `workload register`
+
+A site whose content lives in hosted Superbee reads it in CI as a registered workload app. In the
+site's repository, `superbee workload register` reads the repository and owner ids and the default
+branch with the person's `gh` (`gh api repos/<owner>/<repo>`), and the workflow, workspace and
+bundle from `release.config.json`. It opens the workspace's workload apps page with the form filled
+in: both workflow refs `<owner>/<repo>/<workflow path>@refs/heads/<branch>`, events schedule,
+repository_dispatch and workflow_dispatch, and the bundle at read. A site that publishes to hosted
+(`reconcile.adapter: "hosted"`) also gets its `<bundle> site` line and the GitHub environment
+`reconcile.environment` names (hosted refuses a site app without one). Otherwise the environment
+stays empty, because the job that mints the token runs outside any GitHub environment; pass
+`--environment <name>` only when that job declares one. `--no-open` prints the link instead, and
+`--url` names the workspace's address when it can't be derived from `content.origin`.
+
+Nothing is registered by the command. Registering is the person's step on the web: a workspace
+administrator reviews every value on the page and clicks Register. Then the App id the page shows
+goes in `release.config.json` as `reconcile.app` for a hosted site; a site that only reads hosted
+content runs the printed `gh variable set HOSTED_APP_ID --repo <owner>/<repo> --body <app-id>`
+instead. The values travel in the link's fragment, which the browser never sends to a server.
+
 ## Sign-in: relay the link, then retry
 
 First run on a machine, in order:
@@ -307,6 +328,15 @@ with a `held` row, reason `unsafe_id`, and the rest of the bundle syncs. A host
 differs only in letter case from another is held as `case_collision`. Both are renamed in the
 Superbee app, by the person.
 
+An edit that removes an outbound link the document had is held as `dropped_links`, and the row
+names the links it removes. Usually the removal is a mistake (a rewrite from a partial read):
+restore the links. When removing them is intended, `superbee sync --replace-links <id>` sends that
+one document's edit as the file stands in that run, against the version it was checked against;
+once admitted it is sent like any other change, retried by a later sync if the host was busy. It
+covers no other document and no later edit, and it never admits a body carrying a
+truncated-preview notice.
+`superbee status` shows the same hold before you sync.
+
 ## The bundle's front page (the root `index.md`)
 
 The root `index.md` syncs as one file of its own when the host lets you change the bundle's front
@@ -370,7 +400,10 @@ bundle for everyone.
   the `superbee sync --accept-deletes blobs:<count>:<digest>` command it names.
 - **Receipt:** `blobs.rows` has one row per request, keyed by file and request id: `committed`,
   `conflict`, `refused`, `unknown` or `held`. `blobs.counts` totals them. An `unknown` row is
-  looked up by the same request on the next sync; it is never sent twice.
+  looked up by the same request on the next sync; it is never sent twice. A `refused` row whose
+  `result.error.code` is `path_collision` is a new file whose path, or one of its folders, differs
+  from an existing document or file only by letter case or Unicode form; nothing was written, and
+  sync exits 5. Rename the file or folder to a distinct path, then promote it again.
 - **Conflicts:** after a `conflict` row (the host's version changed), the file is held until it is
   resolved. `superbee sync --inspect --doc <key>` shows the recorded versions and MIME types.
   `superbee sync --resolve keep --doc <key>` keeps your file: the next sync sends it as it is over
@@ -406,7 +439,11 @@ somewhere else. Taking a bundle out of hosted is `superbee export` (below), and
 person asks for it.
 
 `checkout` adds the folder to the workspace catalog, where `catalog list` shows it with
-`home: hosted`. The local MCP app (`superbee mcp`) serves it through the folder, by that label or
+`home: hosted`. `checkout --release` forgets the label checkout gave it; a label you chose is
+kept. `superbee catalog remove <label>` forgets any other entry, such as one `catalog list`
+reports `available: false` (its folder is gone); it never touches the folder or the checkout. It
+refuses (`unsent_changes`, exit 5) a checkout whose folder holds changes sync has not sent: run
+`superbee sync --dir <folder>` first. The local MCP app (`superbee mcp`) serves it through the folder, by that label or
 with the session opened in it: a document written through a View lands in the folder and reaches
 the host at the next `superbee sync`. A write sync could not send (a View save, a convention, a
 retype, a document over the size limit, a change to `verified`) is refused before the file

package/references/modeling-and-delivery.md

@@ -47,13 +47,17 @@ instance together is appropriate.
 5. Relate the new record to its actual evidence, policies, decisions, or dependencies.
 6. Run `superbee status`, read the new record, and inspect its links. Repair only defects caused by
    this change.
-7. Remove temporary authoring or staging directories, present the authoritative result, and give a
-   brief value receipt.
+7. Remove temporary authoring or staging directories, summarize the value, and identify the
+   authoritative result by title and document reference. Follow the eager Skill's "Make the value
+   visible" guidance for explicit display requests.
 
 Use `--body-file` for multiline Markdown. Use `superbee new "<Kind>" --help` for the exact fields
 of an installed Kind. Prefer semantic no-ops, actor attribution, and version-aware updates when the
 CLI exposes them.
 
+Put write-time guidance in a Kind's field or value descriptions, never its body: a write that
+sets a described value returns that description as `guidance`.
+
 ## Evolve from use
 
 Refine fields or relationships only after actual instances expose a recurring need. Package a

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

@@ -34,6 +34,24 @@ only a View whose source or author you trust. A View that declares `bundle-propo
 trusted shell to prepare one v1 scalar-field action; only the human's shell-native Apply choice
 authorizes the write.
 
+## Opening a local View
+
+Use `superbee view open <viewId>` for an exact registered View in the selected local bundle;
+`--dir` and the resolved `--actor` select its managed UI authority. Use `show_view` in a supported
+MCP Apps host. These entry points establish their own host context; do not fabricate a bare View
+URL or copy a reusable session token into a link.
+
+For a fresh embedded browser, `superbee view open <viewId> --no-open --json` prepares a private
+`browser_launch.url`. Navigate the selected browser to that exact returned URL. The handoff is
+one-use and expires after 60 seconds: never share or log it. Its ordinary `url` field is a
+credential-free destination, useful only in a browser that already has the right local session.
+After expiry or ambiguous redemption, request a fresh handoff instead of replaying the old one.
+
+The handoff establishes the existing session for the entire selected local UI authority, not
+only this View. It does not approve execution, change the actor or bypass the normal approval of
+exact View bytes and access. `handoff_prepared` and `open_requested` do not prove rendering; verify
+the result in the receiving browser. Run `superbee view open --help` for current options.
+
 ## The requests
 
 Every request carries `bridge: "v0"` (or `"v1"` for `read-versioned` and `action.propose`), an

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

@@ -2,7 +2,7 @@
 type: Reference
 title: Open Knowledge Format v0.1 (Draft)
 description: A version-scoped OKF v0.1 interop reference, not Superbee's cross-edition authority.
-resource: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+resource: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a/okf/SPEC.md
 tags: [okf, spec, reference]
 timestamp: 2026-08-23T17:47:52Z
 ---
@@ -17,6 +17,11 @@ 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.
 
+OKF has since moved to its own repository,
+`GoogleCloudPlatform/open-knowledge-format`, which publishes v0.2. The
+`knowledge-catalog` copy is a frozen snapshot, so the v0.1 citation below is a
+permalink to the commit that published v0.1.
+
 # Key sections
 
 * §3 bundle structure and reserved filenames (`index.md`, `log.md`).
@@ -26,4 +31,5 @@ first-class concept (§8) so citations resolve inside the graph.
 
 # Citations
 
-1. [OKF SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+1. [OKF v0.1 SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a/okf/SPEC.md)
+2. [Open Knowledge Format repository](https://github.com/GoogleCloudPlatform/open-knowledge-format)

package/references/views/references/view-authoring-v0.md

@@ -34,6 +34,24 @@ only a View whose source or author you trust. A View that declares `bundle-propo
 trusted shell to prepare one v1 scalar-field action; only the human's shell-native Apply choice
 authorizes the write.
 
+## Opening a local View
+
+Use `superbee view open <viewId>` for an exact registered View in the selected local bundle;
+`--dir` and the resolved `--actor` select its managed UI authority. Use `show_view` in a supported
+MCP Apps host. These entry points establish their own host context; do not fabricate a bare View
+URL or copy a reusable session token into a link.
+
+For a fresh embedded browser, `superbee view open <viewId> --no-open --json` prepares a private
+`browser_launch.url`. Navigate the selected browser to that exact returned URL. The handoff is
+one-use and expires after 60 seconds: never share or log it. Its ordinary `url` field is a
+credential-free destination, useful only in a browser that already has the right local session.
+After expiry or ambiguous redemption, request a fresh handoff instead of replaying the old one.
+
+The handoff establishes the existing session for the entire selected local UI authority, not
+only this View. It does not approve execution, change the actor or bypass the normal approval of
+exact View bytes and access. `handoff_prepared` and `open_requested` do not prove rendering; verify
+the result in the receiving browser. Run `superbee view open --help` for current options.
+
 ## The requests
 
 Every request carries `bridge: "v0"` (or `"v1"` for `read-versioned` and `action.propose`), an