superbee 0.4.4-pre.8 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.4-pre.8",
+  "version": "0.4.4",
   "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": [
@@ -67,7 +67,7 @@
     "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": {
     "@superbee/board-git": "*",
@@ -93,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`. 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",
+  "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` to see which build you have. `superbee version --check` is not available on published builds yet: it exits 1 with `policy_disabled` and makes no network request. Check the npm page or `npm view superbee version` for the current 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## Copying documents between bundles\n\n`superbee doc import` copies chosen documents from another bundle with new ids and rewritten links.\nDeclare the source first, then review the plan before applying it:\n\n```sh\nsuperbee deps add wave --bundle-id <source-bundle-id> --path ../wave\nsuperbee doc import --from wave --with wave=../wave --select type=Theme --prefix wave\nsuperbee doc import --from wave --with wave=../wave --select type=Theme --prefix wave --apply <plan-token>\nsuperbee doc import --from wave --with wave=../wave --refresh <record-id>\n```\n\nThe first import command only prints the plan and its token. Applying writes new documents and one\nPromotion record, and never overwrites a document. `--resume <record-id>` finishes an interrupted\nrun. `--refresh <record-id>` updates the copies from their sources with the same plan and apply\nsteps; a copy edited since the import is a conflict until you name it with `--overwrite <id>` or\n`--skip <id>`. The target must be a local bundle or Git board. `superbee doc import --help` has the\nfull reference.\n\n## When a document cannot be read\n\nSuperbee bounds how much frontmatter it parses: 262,144 characters of YAML, 32 levels of nesting, and limits on\nYAML alias use. Ordinary documents are far below these limits. A write over a limit is refused with\n`USAGE` and nothing is stored. A document already in the bundle that is over a limit, or whose YAML\nis invalid, cannot be read:\n\n- `doc read` on it fails with `RUNTIME`. `details.frontmatter.code` is `FRONTMATTER_TOO_LARGE`,\n  `FRONTMATTER_TOO_DEEP`, `FRONTMATTER_ALIAS_LIMIT`, `FRONTMATTER_CYCLE` or\n  `FRONTMATTER_MALFORMED`, and `details.frontmatter.document` names the file.\n- To find every affected document, run `superbee status` (the `malformed` count and rows) or\n  `superbee list` (the `skipped` rows). `search`, `query`, `index generate`, `link list`,\n  `link show`, `view list` and `kinds --coverage` also skip it, say so, and keep working.\n- To fix it, edit the lines between the `---` markers in a text editor, or remove the document with\n  `superbee doc delete <id>`. `doc update` and `doc field` cannot change a document they cannot read.\n\nOn a Git board, `sync` holds a changed file it cannot read: it exits 5, names the file, and commits\nand pushes nothing until you fix it. If a conflict kept a version that cannot be read, the receipt\ntells you to copy your saved export over the document.\n\nIn a hosted checkout, a host document this client cannot store comes back as a `held` row named with\nits `FRONTMATTER_*` code, exit 5, and everything else proceeds. The next sync places it once it is\nrepaired on the host. If the checkout's own local store holds a copy it cannot read, sync stops with\n`store_damaged` and sends and places nothing. Reads continue and `status` reports it. Copy out any\nunsent edits and make a fresh checkout, as the error's help describes.\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).\nSite builders can read a publication's Site declaration through `superbee/publication/site-manifest`;\nsee [Site declarations](https://github.com/Holaxis-ai/superbee/blob/main/packages/publication/SITE-MANIFEST.md).\n\n## License\n\nApache-2.0 © 2026 Holaxis\n",
   "readmeFilename": "README.md"
 }

package/references/hosted-checkout.md

@@ -92,6 +92,40 @@ must already be a member of the workspace (invited from the Members page first).
 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.
 
+## Requesting GitHub workload access
+
+A GitHub Actions job can use `superbee workload exec` with a bounded version1 JSON intent, an
+explicit HTTPS workspace origin and workspace slug, followed by its command after `--`.
+Run its `--help` for exact syntax. The intent contains a display name, supported events, exact
+bundle read/write capabilities and optional fixed sites. It contains no repository IDs, workflow
+refs, environment, credentials or app UUID. Each requested site must have its matching Read bundle
+capability. A protected main-only GitHub environment and `id-token: write` are required by the host.
+This works for custom research or documentation workflows without `release.config.json`.
+By default, the workspace pointer must name its own parent-domain gateway. Optional explicit
+`--host <HTTPS gateway origin>` selects the receiving service through ordinary protected-resource
+and issuer discovery, without pointer or environment fallback. That service receives the signed
+job token. In explicit mode, `--url` is the logical browser approval/audience origin (including a
+shared neutral origin), and `--workspace` independently names the exact workspace: no first-label
+inference is made. The server still decides current authority, and the CLI still checks returned
+workspace, exact capabilities and expiry. Selecting a service grants no access.
+
+The existing exchange verifies the job's GitHub identity and resolves exactly approved access.
+Pending approval is `FORBIDDEN` (exit 2) with `details.reason: workload_approval_pending`, an opaque
+request id, expiry and `review_url`. No child starts and no Superbee bearer is returned. A workspace
+administrator reviews the permissions at that URL and approves or denies them; an agent must not
+approve its own request. Run the workflow again after approval. There is no polling, implicit grant,
+UUID fallback or copied app-ID variable. Denied or expired requests remain terminal.
+
+On success only the child receives the short-lived bearer, resolved gateway host, and
+`SUPERBEE_WORKLOAD_APP_ID` from the validated response, replacing any inherited app ID. The latter
+is temporary identity metadata for a native principal check, never a grant; nothing is written to
+`GITHUB_ENV`, a file or a persistent GitHub variable. Its GitHub OIDC minting variables are removed. The command is spawned directly with its argument boundaries,
+not through a shell, and its exit status is preserved. Tokens are masked in GitHub Actions logs;
+do not print or upload the child's environment. A changed capability declaration needs its own
+approval and cannot silently inherit broader access. The host must serve this request mode before
+using it; merged client source alone does not establish deployment, registration or production
+qualification. Existing explicit app-ID clients and the registration fallback below remain supported.
+
 ## 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
@@ -195,6 +229,22 @@ superbee sync                                 # sends what keep or revise decide
   them.
 - If you cannot tell which version is right, ask the person. Do not merge by guessing.
 
+## A document this client cannot read
+
+A host document this client cannot store does not stop `checkout` or `sync`. It comes back as a
+`held` row whose reason is its `FRONTMATTER_*` code, the receipt's `status` is `incomplete`, and the
+command exits 5. The document is not placed, the rest of the bundle is, and edits to other documents
+are sent. Tell the person which document it is: it has to be repaired on the host, and the next sync
+then places it without any step here. If you edited an older copy in the folder, that edit comes
+back as a conflict: `--inspect` says what it cannot show, `--resolve take` is refused, and
+`--resolve keep` sends your version against the version inspected.
+
+If the checkout's local store holds a copy it cannot read, sync and the other hosted verbs stop with
+exit 5 and `details.reason` `store_damaged`, naming the documents. Nothing is sent or placed and your files
+are not changed. Reads continue, and `status` reports `state: store_damaged`. Copy any unsent edits
+out of the folder, then follow the error's help: `superbee checkout --release <folder>`, then a
+fresh `superbee checkout`.
+
 ## Document history
 
 In a checkout, `superbee doc history <id>` reads the host's version chain, not the folder: every
@@ -219,6 +269,21 @@ when the whole body fit in one page, so never loop on it. A page is not the docu
 it back as the body. To edit, use `doc read <id> --body-out <path-outside-bundle>`, edit that file,
 then `doc update <id> --body-file <path> --expected-version <version>`.
 
+## View pages: `view read` and `view update`
+
+Sync never sends `views/`. To change a View's page on the host:
+
+```sh
+superbee view read <viewId> --out <new-file>      # version and size; --out saves the exact bytes
+superbee view update <viewId> --expected-version <sha256:...> --file <path>
+```
+
+`--file` defaults to the View's entry in the checkout folder. `--expected-version` is the version you
+started from: if the host's page has moved, nothing changes and the command names the host's version.
+A page is at most 512 KiB of UTF-8. If the answer is lost, the command reads the page once and reports
+whether the update applied; it never resends on its own. Uploading never approves execution: a site
+keeps serving the version it pins until that pin moves, and a hosted app slot needs approving again.
+
 ## Notifications: `notify` and `inbox`
 
 Notifications are part of hosted Superbee, and there is no local inbox. `superbee notify
@@ -370,6 +435,15 @@ superbee sync --resolve keep --doc index.md     # the next sync sends yours over
 
 ## Ordinary files (SVGs, images, `data/*.json`)
 
+`pull --doc-key <key> --out <path> --from-host --dir <checkout>` reads one blob's bytes and stored
+content type directly from the bound host, using its version and content type together as the
+read pin. It checks the checkout's signed-in person and workspace and verifies the returned bytes.
+A changed pin, denied access or unsupported host refuses without falling back to local bytes.
+It does not sync, send edits or refresh the working copy; only the requested output is written.
+Use `--out -` for raw stdout with the receipt on stderr. Ordinary `pull` still reads the local
+working copy, including unsent edits; its content type is inferred from the filename. The explicit
+host option is for blobs only and cannot be combined with `--remote`.
+
 Files other than `.md` documents are ordinary files. Sync sends and refreshes only **tracked**
 ones. Treat an edit to a tracked file as a publish: the next `superbee sync` sends it to the hosted
 bundle for everyone.

package/references/modeling-and-delivery.md

@@ -47,8 +47,9 @@ 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
@@ -57,6 +58,38 @@ 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`.
 
+## Copy documents from another bundle
+
+Use `superbee doc import` when documents should exist here under their own ids instead of being
+linked with `okf:` links. Declare the source with `superbee deps add <alias> --bundle-id <id>`. The
+copy you bind with `--with` must declare the same bundle id.
+
+```sh
+superbee doc import --from <alias> --with <alias>=<path> --select type=<T> --prefix <p>
+superbee doc import --from <alias> --with <alias>=<path> --select type=<T> --prefix <p> --apply <plan-token>
+superbee doc import --from <alias> --with <alias>=<path> --refresh <record-id>
+```
+
+Without `--apply` the command only prints the plan. Show the person the plan, then apply its exact
+token. An import writes new documents plus one Promotion record and never overwrites. A refresh
+treats a copy edited since the import as a `target_edited` conflict: ask the person whether to name
+it with `--overwrite <id>` (discards the edit) or `--skip <id>`. On `TRANSFER_PLAN_CHANGED`, read
+the new plan before applying again. On `TRANSFER_INTERRUPTED`, run `--resume <record-id>`. Hosted
+checkouts and `--remote` are refused.
+
+## When a document cannot be read
+
+Frontmatter parsing is bounded, so a write over a limit is refused with `USAGE` and nothing is
+stored. A stored document over a limit, or with invalid YAML, fails `doc read` with `RUNTIME` and
+`details.frontmatter.code` (`FRONTMATTER_TOO_LARGE`, `FRONTMATTER_TOO_DEEP`,
+`FRONTMATTER_ALIAS_LIMIT`, `FRONTMATTER_CYCLE` or `FRONTMATTER_MALFORMED`).
+
+`superbee status` and `superbee list` name affected documents. `search`, `query`, `index generate`,
+`link list`, `link show` and `view list` skip it, say so, and keep working. `doc update` and
+`doc field` cannot change it. To clear it, edit the frontmatter in the file or run
+`superbee doc delete <id>`. Removing or rewriting someone's document is the person's call, so ask
+first.
+
 ## Evolve from use
 
 Refine fields or relationships only after actual instances expose a recurring need. Package a