superbee 0.1.1 → 0.1.2-pre.2

package/SKILL.md

@@ -1,465 +1,92 @@
 ---
 name: superbee
 description: >-
-  Read and write a local OKF knowledge bundle (agent context notes, docs, cross-links, and live
-  bundle Views) from the shell via the Superbee CLI. Use when an agent
-  needs to persist a context note across sessions, store a decision/spec as a doc, link concepts,
-  query a bundle, share the project's board with teammates (`sync`), or open its local View UI.
-  Runs standalone via `npx -y superbee`.
+  Use Superbee to preserve important knowledge, model recurring domain concepts, relate evidence,
+  coordinate work when appropriate, and present durable information to humans. Apply it when the
+  user's work would benefit from continuity, provenance, reusable structure, or reduced repeated
+  interpretation—not only when the user names Superbee.
 ---
 
-# superbee
+# Superbee
 
-read and write a local OKF knowledge bundle (context notes, docs, cross-links, live bundle Views).
+Superbee is a local, user-owned knowledge environment shared by humans and agents. Help with the
+user's work first; improve that environment only where doing so removes real future effort.
 
-It is a standalone npm package (`superbee`) installing only the canonical `superbee` bin.
-Legacy `aslite` and `agentstate-lite` invocations are recognized only for migration.
+## Keep the front door short
 
-Output is TOON on stdout (a `--json` hatch exists). Errors are structured TOON on stdout with a
-capped exit-code taxonomy (0 ok/no-op, 2 usage, 4 auth, 5 conflict, 6 not-found, 1 runtime).
+- If the user asks for concrete work, do it. Do not interrupt with onboarding.
+- When the user is orienting, inspect the available project and bundle facts, then offer two or
+  three relevant one-line outcomes and one easy question. Each outcome is one short sentence;
+  omit its rationale unless asked. Keep the complete opener to five lines and at most 80 words.
+- Use the user's language, not product vocabulary. Make declining explicit and drop declined offers
+  for the rest of the session.
+- Treat `superbee home` offers as grounded candidates, not mandatory slots to fill.
+- Never mutate while merely explaining options.
 
-<!-- GENERATED from src/reference.ts by scripts/gen-skill.mjs — do not edit by hand. -->
+## Recognize the smallest useful opportunity
 
-## If `superbee` is not on PATH
+Look for evidence that people or agents repeatedly:
 
-Every example below assumes the `superbee` bin is on PATH. If it is not:
+- reconstruct the same context, rule, or decision;
+- lose provenance between evidence and conclusions;
+- handle a stable entity, lifecycle, state, or relationship inconsistently;
+- assemble the same overview to understand or decide something; or
+- coordinate dependencies, owners, and milestones across sessions.
 
-- `npm install -g superbee` puts the canonical `superbee` command on PATH.
-- `npx -y superbee …` runs any command below with no install at all — swap the leading `superbee`
-  for that prefix and the rest of the line runs unchanged.
+Offer the smallest durable improvement that matches the observed friction. Possibilities include
+Release and Release Check; Claim, Evidence, and Verification; Interview, Need, and Insight;
+Experiment, Run, and Result; Decision, Alternative, and Assumption; or Task, Roadmap, Milestone, and
+Dependency when coordinated execution actually warrants them. These are examples, not a catalog.
 
-## Complete host setup
+A document preserves one important thing. A Kind makes a recurring domain concept consistent. A
+recipe packages stable reusable definitions. A bundle View reduces repeated human interpretation without
+becoming a second source of truth. Add only the layer justified by current evidence.
 
-After the global npm install, run:
+## Preserve boundaries and authority
 
-```sh
-superbee setup
-```
+- Operate only on the bundle resolved from the current project or one the user explicitly selects.
+  A catalog entry is available for selection; it is not ambient project context.
+- If no bundle resolves, determine whether this repository already shares a board and clarify the
+  intended purpose, privacy, participants, and sharing boundary before creating anything.
+  `superbee sync` joins an existing shared board; `superbee init --create-only --dir .superbee` is
+  only for a confirmed greenfield local bundle.
+- Ask before creating durable structure or publishing a local bundle. `sync --establish` is an
+  explicit publication decision.
+- Never silently rewrite an established Kind, recipe, or its instances. Inspect dependencies and
+  explain migration consequences first.
 
-Without `--host`, setup returns the four supported host rows. Select the exact host running
-this agent, run that row's command, then follow the one `next.command` in each host-scoped
-plan, filling any explicit placeholder it identifies. Bare and host-scoped setup are read-only: they compose npm,
-Skill, Hook, MCP, bundle, and catalog status but never treat detection as permission to write.
-Ask the human before running a returned mutating command. Restart the host after Skill, Hook,
-or MCP changes, then rerun the same setup command to verify. Foreign or unreadable state
-returns a read-only inspection command instead of overwriting it.
-If setup returns `superbee setup migrate-state`, that exact explicit command copies only
-validated private operational records into Superbee's canonical state root; it never moves
-bundles or deletes legacy bytes.
+## Deliver after acceptance
 
-A catalog entry preserves a workspace for explicit MCP selection; it never selects that
-workspace as the current project's context. Do not read, write, orient from, or sync a
-cataloged workspace merely because setup or a legacy MCP registration references it. Operate
-only on a bundle resolved from the current checkout or one the user explicitly selects. If
-the current checkout has no bundle, report that fact and stop bundle-oriented work.
+Set `$REFS` from the skill base directory reported by the host:
 
-## Stable MCP launch
+`REFS="<skill-base-dir>/references"`
 
-For a persistent MCP integration, install the supported CLI with
-`npm install -g superbee`, then run `superbee mcp install --host <id>` with the exact
-current host: `codex`, `claude-code`, `claude-desktop`, or `opencode`. The command
-registers the durable npm runtime once at user scope, never an npx cache or one bundle directory.
-Use `superbee mcp status --host <id>` to verify it and restart the host after a change.
+When the user accepts a domain-modeling offer, read `$REFS/modeling-and-delivery.md`. Inspect
+existing documents, Kinds, recipes, and links before choosing a shape. Create the smallest coherent
+representation, normally with one representative example, verify it, remove temporary authoring
+files, and stop. Use `superbee <command> --help` for exact current syntax rather than relying on a
+copied command manual. Use `--body-file` for multiline Markdown.
 
-## Commands
+Focused shipped material is available under `$REFS/recipes/` for portable examples,
+`$REFS/views/` for View authoring and examples, and `$REFS/sample-bundle/` for OKF interop.
+Read only what the accepted work requires.
 
-### Bundle
+## Make the value visible
 
-- `superbee bundle locate [--dir <path>]`
-  — Resolve the exact canonical local bundle path and report why it won selection
-- `superbee catalog (add <label> [--dir <path>] | list | resolve <label-or-id> [--field path])`
-  — Register and deterministically resolve this user's explicitly named local workspaces
-- `superbee init [--dir <path>] [--okf-version <v>] [--recipe <name-or-path>] [--create-only]`
-  — Create (or open) an OKF knowledge bundle in a directory — greenfield setup; a project that already shares a board is set up by sync, not init. --create-only requires a genuinely NEW target and refuses existing, non-empty, symlinked, enclosing, bound, or concurrent targets before publication; runtime failures retain and report any empty directories they created instead of deleting them — 'recipe add' modifies a verified existing bundle
-- `superbee index generate [--dir <path>] [--check] [--force] [--actor <name>]`
-  — Generate complete portable Markdown navigation explicitly; refuses curated indexes unless --force adopts them
-- `superbee status [--limit <n>] [--dir <path>] [--remote <url>]`
-  — Read-only bundle health report (kind lint, unresolved links, orphans, staleness, graph lints)
+At a tangible result, say in one or two sentences what became durable or structured and what the
+user or a later agent no longer needs to reconstruct. Show or offer the most useful authoritative
+document or View once. Never return only a Markdown link or local filesystem path. When the user
+asks to see it, invoke `show_document` or `show_view` in an MCP Apps host; otherwise invoke
+`superbee doc open <id>`.
 
-### Documents & links
+## Host setup
 
-- `superbee doc write <id> --type <t> [--title <t>] [--body <s> | --body-file <p>] [--actor <n>] [--dir <path>] [--remote <url>]`
-  — Write a generic OKF concept document
-- `superbee doc update <id> [--<field> <value> ...] [--title <t>] [--tag <t>] [--type <t>] [--body <s> | --body-file <p>] [--expected-version <v>] [--actor <n>] [--dir <path>] [--remote <url>]`
-  — Patch given fields (incl. kind-declared fields like --progress_status) of an existing doc, preserving the rest; optimistic-CAS with --expected-version
-- `superbee doc read <id> [--out (<path> | -) | --body-out (<path> | -) | --field <name>] [--dir <path>] [--remote <url>]`
-  — Read a doc, export its raw markdown, export its body with a same-read CAS version, or print one raw field for scripting
-- `superbee doc open <id> [--dir <path> | --remote <url>] [--port <n>] [--actor <name>]`
-  — Open one exact authoritative document in the existing rendered browser UI
-- `superbee doc history <id> [--limit <n>] [--dir <path>] [--remote <url>]`
-  — Show a doc's version history (newest first, capped at 20 by default — --limit 0 for all; a history-keeping backend returns the full attributed chain, a local bundle just the current revision) — the tokens for --expected-version
-- `superbee doc delete <id> [--expected-version <v>] [--dir <path>] [--remote <url>]`
-  — Hard-delete a doc (idempotent: absent -> deleted:false, exit 0)
-- `superbee list [--type <t>] [--tag <t>] [--field <k=v>] [--prefix <p>] [--open] [--limit <n>] [--dir <path>] [--remote <url>]`
-  — Query concepts over their frontmatter (alias: query) — a comma in --field's value is set membership (OR); --open excludes terminal instances (declared kinds only)
-- `superbee link (add <from> <to> [--text <t>] [--actor <n>] | show <id> [--limit <n>] [--text <t>] | list [--from <id|prefix/>] [--to <id|prefix/>] [--text <t>] [--limit <n>]) [--dir <path>] [--remote <url>]`
-  — Add a cross-link, show a concept's links + backlinks, or query the whole bundle's derived edge list filtered by from/to (id or prefix/, repeatable/union) and exact-match text
+Persistent integrations require `npm install -g superbee` followed by `superbee setup`.
+Setup is a read-only conductor: select the exact host, ask before running its returned mutating
+command, restart after Skill, Hook, or MCP changes, and rerun setup to verify. A catalog entry
+preserves a workspace for explicit selection; it never makes that workspace the current project.
+If home or SessionStart reports `skill_update`, run its exact scope-specific command, restart the
+host, and continue; Superbee never rewrites an installed Skill automatically.
+`npx -y superbee` is suitable for ordinary bundle commands, not durable host integration.
 
-### Artifacts
-
-- `superbee artifact create <file> --title <title> [--description <text>] [--supersedes <id>] [--actor <n>] [--dir <path>] [--remote <url>]`
-  — Produce a shareable output (HTML) a human can view: one command promotes the bytes and writes the type:Artifact record
-- `superbee promote <file> --doc-key <key> [--content-type <mime>] [--expected-version <v>] [--dir <path>] [--remote <url>]`
-  — Move a local file's bytes into the store (a .md key routes through the engine; else a blob)
-- `superbee pull --doc-key <key> --out (<path> | -) [--dir <path>] [--remote <url>]`
-  — Pull a doc's canonical form or a blob's raw bytes out of the store (the reverse of promote)
-- `superbee blobs [--prefix <p>] [--limit <n>] [--dir <path>] [--remote <url>]`
-  — List the store's blob (non-document) keys (documents are listed by 'list'/'query')
-- `superbee delete --doc-key <key> [--expected-version <v>] [--dir <path>] [--remote <url>]`
-  — Hard-delete a doc or blob by key (idempotent: absent -> deleted:false, exit 0)
-
-### Kinds
-
-- `superbee new "<Kind>" <id> --<field> <value> [...] [--body <markdown> | --body-file <path>] [--link "<type>=<target-id>" ...] [--no-prefix] [--actor <n>] [--dir <path>] [--remote <url>]`
-  — Create a new instance of a bundle-declared kind — initial Markdown may come from --body or --body-file (otherwise declared sections are scaffolded); validates strictly, and repeatable --link wires typed cross-links in the same step
-- `superbee kinds [--dir <path>] [--remote <url>]`
-  — List the kind conventions this bundle declares (purpose, described fields, exact required body headings, typed-link vocabulary, horizon)
-- `superbee kind field "<Kind>" (add <name> [--required] [--values <a,b,c>] | remove <name>) [--dir <path>] [--remote <url>]`
-  — Edit a kind's schema — add/remove a declared field or enum value on its convention (idempotent)
-- `superbee recipes [--dir <path>] [--remote <url>]`
-  — Browse built-in recipes before or after init; with a bundle, also show whether each is already applied
-- `superbee recipe add <name-or-path> [--dir <path>] [--remote <url>]`
-  — Apply a recipe's content-free definitions — Kinds plus optional declared References and Views — idempotently
-
-### Remote
-
-- `superbee serve [--dir <path>] [--host <h>] [--port <p>]`
-  — Boot the reference wire-protocol server over a local bundle (loopback, no auth)
-- `superbee ui [--dir <path> | --remote <url>] [--port <p>] [--open]`
-  — Boot the local web UI over the bundle (same origin, loopback-only): READ the bundle's docs as rendered pages (frontmatter, cross-links you can follow, derived backlinks), LAUNCH its registered Views (type: View docs framed in sandboxed iframes with live updates; legacy Page-typed docs no longer register — see status's legacy_naming finding), and see a live activity feed, the bundle's sharing status, and your registered workspaces. The header shows the bundle's display name — derived from the project folder unless set explicitly: doc write docs/bundle --type "Bundle Name" --title "<name>"
-- `superbee mcp [install|status|uninstall | --dir <path>]`
-  — Run the local MCP Apps adapter, or explicitly install, inspect, and uninstall its user-level registration for Codex/ChatGPT, Claude Code, Claude Desktop, and OpenCode
-- `superbee view list [--limit <n>] [--dir <path> | --remote <url>]`
-  — List the bundle's registered durable Views from the same catalog used by the web launcher and MCP list_views
-- `superbee sync [--establish [--yes] | --pull-only | --show-incoming <id> [--out <file>]] [--dir <path>] [--limit <n>]`
-  — Share the board branch with a remote — commits, pulls, and pushes (git tier; --pull-only skips commit+push). `init` makes a LOCAL bundle; --establish is the separate, explicit act that starts sharing it (creates the board branch, pushes; never automatic). A bundle folder already committed on the code branch is the same flag's hard case: preview first, --yes executes, and the folder's removal from the code branch rides a prepared side-branch commit you push and open as a PR. A bundle committed with code and NO board branch anywhere is the IN-TREE mode (read-side): full sync refuses (sharing rides your normal commit/push), --pull-only fetches the branch's tracking upstream and reports incoming board docs ('git pull' delivers them), and --establish converts to a dedicated board branch. A doc changed on both sides converges: teammate's version kept, yours exported; --show-incoming <id> (exclusive with --pull-only) prints the incoming version as of the last fetch. Board-reading commands (list/doc read/status/home/link show) auto-run the ff-only pull when board state is >~5m stale — silent, bounded (~2s), never a push; SUPERBEE_NO_AUTOPULL=<any value, even 0> disables it
-
-### Session
-
-- `superbee version [--check] [--tag latest|next] [--json]`
-  — Show the complete local build/runtime identity, or perform one bounded read-only comparison against npm's exact latest/next release policy
-- `superbee session-start [--dir <path>] [--no-update-check]`
-  — The SessionStart hook payload: pull then render; default TOON uses a nonblocking 24-hour cached latest check, while --no-update-check or SUPERBEE_NO_UPDATE_CHECK/NO_UPDATE_NOTIFIER/CI presence disables both display and refresh (legacy ASLITE_NO_UPDATE_CHECK remains supported); npm receives only the public package request and ordinary network metadata, never installed version, cwd, bundle, actor, or usage data
-- `superbee hook install|status|uninstall [--scope project|user]`
-  — Install the SessionStart hook (runs session-start: pull the board, then render) for Claude Code, Codex, OpenCode
-- `superbee skill install|status|uninstall [--scope project|user]`
-  — Install this package's Agent Skill (SKILL.md + references/) into Claude Code and Codex skill folders (OpenCode has no skill surface — its integration is `hook install`); manifest-tracked, idempotent, refuses folders it does not manage
-- `superbee setup [migrate-state] [--host codex|claude-code|claude-desktop|opencode] [--scope project|user] [--json]`
-  — Inspect npm, private state, Skill, Hook, MCP, bundle, and catalog readiness, then emit one deterministic safe next command
-
-## Workspaces — the project's bundle lives at `.superbee/` in the project root
-
-Unless the user directs otherwise, a project's workspace bundle lives in a `.superbee/`
-folder at the project root. Two verbs, two different jobs — `init` always creates a LOCAL
-bundle (solo use is first-class, nothing forces sharing); `sync` is how a project's board
-becomes — or stays — shared memory across clones and teammates. Three modes:
-
-- **A local-only board** — `init` creates a bundle that doesn't exist anywhere yet, and it
-  stays LOCAL until someone chooses to share it. This is a first-class mode, not a limbo:
-  everything works offline and remote-free, and board changes stay on this machine. A bare
-  `sync` on a local-only bundle reports that state honestly (its note points at `--establish`)
-  — it never establishes on its own, which would silently publish a bundle nobody asked to
-  share.
-- **Joining an existing shared board** — if `.superbee/` or a legacy `.agentstate-lite/` is already in the clone, there
-  is NOTHING to set up. If it isn't but the project already shares its board (the repo's
-  remote has a `board` branch), `sync` is the setup verb — run it once and it creates the
-  folder and pulls the shared state. NEVER init a project that already has a workspace: that
-  creates a divergent second bundle.
-- **Sharing a board (`sync --establish`, once)** — the explicit act that publishes a local
-  bundle as the repo's `board` branch; teammates then just run `sync` to join. It handles
-  both shapes: an uncommitted local folder is snapshotted, pushed, and converted in place;
-  a folder ALREADY COMMITTED on the code branch gets a preview first — re-run with `--yes`
-  to execute, which also prepares a cleanup commit on a side branch that you push and open
-  as a PR (it removes the folder from the code branch; the board branch takes over after the
-  merge). If origin cannot be checked, `sync` reports the shared-board state as unknown and
-  waits for a retry instead of recommending publication.
-
-```sh
-superbee sync                            # existing shared project — provisions the board; a local-only bundle reports its state
-superbee init --create-only --dir .superbee  # greenfield — creates one genuinely new LOCAL bundle
-superbee sync --establish                # establish a new shared board after user approval
-```
-
-That's the whole setup. The CLI discovers the conventional folder on its own (the way git
-finds `.git`), so every command runs BARE from anywhere in the project tree — no flags, no
-config files:
-
-```sh
-superbee list
-superbee doc read context-notes/cycle-1
-```
-
-Surfaces that label the workspace (the `ui` header, home's bundle block) derive its DISPLAY
-NAME from the project folder's name. To set it explicitly (it syncs to teammates with the
-board), write the well-known name doc — its title becomes the display name:
-
-```sh
-superbee doc write docs/bundle --type "Bundle Name" --title "<display name>"
-superbee doc update docs/bundle --title "<new name>"   # rename later
-```
-
-The folder is LOCAL until you choose to share it: `superbee sync --establish` (once) publishes it
-onto its own `board` branch — from then on `sync` commits and pushes board changes itself, never
-batched with code. Until established, the bundle stays local — a fully supported mode, not a
-temporary one: everything works offline and remote-free, and board changes stay on this machine
-(either left uncommitted, or committed directly on the code branch like any other file,
-whichever the user prefers). (Gitignore the folder only if the workspace should stay private
-to this machine.)
-
-Write with attribution: set `SUPERBEE_ACTOR=<your-name>` once for `new`, `doc write`,
-`doc update`, and `link add`, or pass `--actor <your-name>` per command (the flag wins).
-Existing `AGENTSTATE_LITE_ACTOR` settings remain supported as a compatibility input.
-With neither source, no advisory actor label is stored in frontmatter or sent as an agent label;
-backend history still reports its own principal (for example, the local OS owner or an
-authenticated remote user). A present-but-blank flag or environment value is a usage error.
-Advisory attribution describes a real mutation and never creates a no-op write.
-Actor labels are advisory metadata, not authentication or authorization credentials.
-
-Each invocation is stateless. HTTP is activated only by explicit `--remote <url>`.
-Otherwise bundle resolution stays local: explicit `--dir` → nearest `.superbee.json` or
-supported `.agentstate.json` local-path binding up-tree → the cwd walk, which at each
-ancestor checks both binding names together (both at one level fail closed), then the
-directory's own `index.md`, then its
-conventional `.superbee/index.md` or legacy `.agentstate-lite/index.md`. Reserve `--dir` for the exceptions: a bundle outside
-If both conventional directories contain valid bundles at one project level, discovery refuses with a conflict; move the bundle you do not intend to use outside the project before retrying.
-any project, a second workspace, or reaching another project's bundle from elsewhere.
-
-Two things override the default:
-
-1. **Explicit user direction** — the user names a directory or a `--remote`; use that. A local
-   `.superbee.json` binding (`{ "bundle": "<path>" }` at the project root) is the
-   preferred durable form; existing `.agentstate.json` bindings remain supported. A binding
-   beats the conventional folder; both binding names at one level are a conflict.
-   Remote URLs are never durable ambient bindings; pass `--remote <url>` per invocation.
-2. **An existing workspace** — if a bare command already resolves (a binding, an enclosing
-   bundle, or a conventional folder exists up-tree), that IS this project's workspace — use
-   it rather than creating a second one.
-
-If the user wants the workspace PRIVATE to their machine instead of shared (a personal
-scratch workspace), keep the bundle OUT of the repo (e.g. under `~/superbee-workspaces/<name>/`)
-and point a git-excluded `.superbee.json` at it. Choose by one question: do teammates
-share this bundle? When the user's intent is ambiguous, ask rather than defaulting silently.
-
-Do not raise a sharing decision during ordinary local work. When the user names teammates,
-a shared board, a handoff, synchronization, or cross-clone coordination, use Superbee's
-built-in board path: run `sync` to join an existing `origin/board`; if none exists, explain
-that `sync --establish` creates it and offer to run that explicit one-time operation. If the
-user prefers an in-tree bundle, custom Git branch/path, or another sharing mechanism, surface
-the tradeoff and record that explicit choice; never silently substitute one for Superbee sync.
-
-## Typical flow
-
-```sh
-# One-time setup at the project root (see the Workspaces section) — run ONE of these:
-superbee sync                          # existing project that shares a board — sets up AND pulls the shared board
-superbee init --create-only --dir .superbee  # GREENFIELD — never on a project that already has a workspace; makes a LOCAL bundle
-
-# If collaboration is requested, offer the explicit one-time shared-board operation:
-superbee sync --establish
-
-# Everything after runs bare, from anywhere in the project tree
-# Create a complete context note (an OKF concept) for the next session in one command
-superbee new "Context Note" cycle-1 --title "cycle-1" --body '# Summary
-
-What this session did and what comes next' --actor <your-name>
-
-# Read it back
-superbee doc read context-notes/cycle-1
-
-# Store a doc, cross-link it, and query the bundle
-superbee doc write specs/auth --type Spec --title "Auth" --body "…" --actor <your-name>
-superbee link add specs/auth context-notes/cycle-1
-superbee list --type Spec
-
-# For a shared board, sync after a unit of work; local-only work stays complete locally
-# (safe everywhere: a local-only board reports its state; outside any workspace it prints
-#  "sync: nothing to sync" — in both cases nothing is committed or pushed)
-superbee sync
-```
-
-## Sharing the board — `sync`
-
-Ordinary `superbee sync` shares your board — commits your changes, pulls your teammate's, pushes yours,
-while leaving code-project files untouched.
-
-On a shared board, run it whenever you close a unit of work — a task finished, a decision recorded, a session
-ending. Local-only work remains complete locally. Three known empty states (all exit 0):
-in an ordinary directory outside any git repo or workspace it prints `sync: nothing to sync`
-(inside Superbee's private user-state root it refuses — that is a conflict, not an empty
-state); a LOCAL-ONLY board (a
-bundle with no shared `board` branch — a supported mode) reports itself as local-only, with
-nothing committed, pulled, or pushed, and its note points at `--establish` — but bare `sync`
-NEVER establishes on its own (that would silently publish a bundle nobody asked to share);
-a clean, already-current shared board prints `sync: already up to date`.
-If origin cannot be checked and no board ref is available, sync reports the remote state as
-unknown and recommends retrying before `--establish`.
-
-`sync --establish` is the one explicit, one-time act that starts sharing a project's local
-bundle: it snapshots and publishes the bundle, checks out the `board` branch at the same path,
-and appends that path to the root working-tree `.gitignore`; teammates then just run plain
-`sync` to join. Never run it on a project that already shares a board (it
-detects that state, notes `already established`, and proceeds as an ordinary sync instead of
-erroring).
-
-The same flag handles a bundle folder ALREADY COMMITTED on the code branch: `sync --establish`
-prints a preview and changes nothing; `sync --establish --yes` creates the `board` branch from
-the folder's current files (files only — the folder's history stays on the code branch),
-pushes it, and prepares ONE commit on a local `board-cleanup` branch that removes the folder
-from the code branch and gitignores it — you push that branch and open the PR yourself;
-nothing on the code branch is pushed or changed. Until that PR merges, the old committed
-folder is a frozen read-only snapshot; after the merge, `git pull` then `sync` brings the
-live board back on every clone.
-
-Sharing is an explicit act: nothing ever creates or publishes a board branch on its own —
-only `sync --establish` does. The session-start hook and the read-time refresh below only
-ever PULL an already-shared board (bounded, fast-forward, never a push); your changes leave
-the machine only when you run `sync`.
-
-When a doc changed on BOTH sides, sync converges instead of stopping: your teammate's version
-is kept on the board, YOURS is saved to an export file named in the receipt, and the run
-exits 5 with one row per conflicted doc. Reconcile with the doc verbs, never git:
-
-```sh
-superbee sync --show-incoming <id>                 # view the kept incoming version (as of the last fetch)
-superbee doc update <id> --body-file <export-file> # write your merged version on top
-superbee sync                                      # share it
-```
-
-`sync --pull-only` picks up teammates' changes without publishing local ones. If a push fails
-(offline, auth), your work is already committed locally — re-running sync retries the push.
-
-Reads stay fresh on their own: board-reading commands (`list`, `doc read`, `status`, `home`,
-`link show`) automatically run the same fast-forward-only pull when the board's state is older
-than ~5 minutes — silent, time-boxed (~2s), never a rebase, never a push, and it never sets a
-board up (that stays `sync`'s job) — so a plain `list` can advance the board checkout's HEAD.
-Your OWN changes still only leave the machine when you run `sync`. To disable the auto-pull
-(CI, scripted runs), set `SUPERBEE_NO_AUTOPULL` to any non-empty value — even `0`
-disables it; the variable's presence is the switch.
-Legacy `AGENTSTATE_LITE_NO_AUTOPULL` remains supported with the same presence semantics.
-
-On projects that share their board you may notice a `board` branch in the repo's GitHub —
-that's the board; it never merges into main (it has no common history with it, by design).
-Protect it like main: enable delete and force-push protection on `board` in the repo settings
-— sync only ever appends commits to it.
-
-## Remote bundle access (--remote, serve)
-
-Remote bundle access remains explicit and wired the same way as `--dir`: use `serve` to expose
-a local bundle over the wire protocol, or pass `--remote <url>` to a bundle-facing command.
-For an authenticated remote, provide `SUPERBEE_API_KEY`; an already-provisioned
-stored per-origin credential is also consumed when present. Legacy `AGENTSTATE_LITE_API_KEY`
-remains supported as a compatibility input. Account and admin credential
-provisioning is outside the default CLI surface.
-
-```bash
-superbee serve --dir ./my-bundle --port 4818 &
-superbee list --remote http://127.0.0.1:4818
-```
-
-## Shipped references — worked examples & contracts alongside this file
-
-A few capabilities below (bundle views, custom recipes) are backed by a full contract or a
-worked example shipped in this package's `references/` folder rather than inlined here. The
-folder sits NEXT TO this SKILL.md — in the npm package root, and in any host skill folder
-this file is installed into (`superbee skill install`).
-
-Shell commands resolve paths against YOUR working directory, not this file's folder, so set
-`$REFS` once per session: your host names this skill's base directory when it loads it
-(e.g. "Base directory for this skill: <path>"). Use that:
-
-```bash
-REFS="<skill-base-dir>/references"   # substitute the base directory your host reported
-```
-
-Every `$REFS/…` path below then runs from any cwd. Each shipped file is a byte-for-byte copy
-of the matching file in the CLI's own repo — one authority, regenerated on every release,
-never hand-duplicated.
-
-## Bundle views — ship a live UI as bundle content
-
-A **bundle view** is a self-contained HTML file living IN the bundle: promoted as a blob under
-`views/…`, declared by a `type: View` registry doc (`title`, `entry`, `access` — the legacy
-`bridge` spelling is no longer read: a doc declaring only `bridge` resolves to `access: none`,
-so author with `access`), and rendered by
-`superbee ui` inside a sandboxed, opaque-origin iframe. A data-bearing View is executable
-code: the shell requires local approval of its exact bytes and declared access, and changed
-bytes ask again. The sandbox and CSP deny direct credentials/data-API access and restrict
-ordinary network APIs as defense-in-depth; approval remains the decision to trust the View's
-source. Bundle data flows only through the narrow postMessage bridge to the trusted shell.
-(`Page` is the legacy name and no longer registers: the launcher ignores `type: Page` docs.
-`superbee status` lists legacy-named docs under its legacy_naming finding, and the
-repo's migrate-legacy-view-names script renames legacy content in place; docs under the
-legacy `pages-registry/`/`pages/` folders stay recognized once typed `View`.)
-
-The bridge (protocol `v0`) has six read-only data request types: `hello` (bundle identity), `query`
-(frontmatter-filtered rows — the same head projection `list` uses), `read` (one doc), `render-document`
-(the shared bounded Markdown presentation for one canonical doc), `edges` (the general
-from/to/text graph query — backlinks and containment both reduce to this), and `subscribe`
-(opt into a server-pushed `change` event whenever the watched bundle moves). There
-is no mutation message in v0 — read-only is enforced by construction. A View that declares
-`bundle-propose` may use the local-only v1 contract to propose ONE governed scalar-field
-change; the trusted shell revalidates it, shows canonical before/after values, and writes
-only after explicit human confirmation with hard CAS. The View never receives a write token.
-`open-page`
-(a wire verb, stable across the rename) is a separate fire-and-forget shell action available
-to every View capability; it opens only another valid registered View and returns none of
-that target's content or metadata.
-
-Author a view in four steps:
-
-```bash
-# 1. write a self-contained views/my-view.html (inline CSS/JS, no external hosts),
-#    embedding the bridge client copied from the shipped contract below
-superbee promote my-view.html --doc-key views/my-view.html                        # 2. promote the HTML blob
-superbee promote my-view-registry.md --doc-key views-registry/my-view.md           # 3. promote its type: View doc (title, entry, access)
-superbee promote "$REFS/views/conventions/view.md" --doc-key conventions/view.md   # 4. declare the View convention (once per bundle, ready-made)
-```
-
-Full message shapes, the trust model, the copy-paste bridge client with safe live-refresh
-examples (including a live graph view over Roadmap Items) are in the shipped contract:
-
-```bash
-cat "$REFS/views/references/view-authoring-v0.md"
-```
-
-## Human review
-
-When you create or materially revise a bundle document for human review, display it when the
-human asks and otherwise offer once. In an MCP Apps host, call `list_workspaces` when needed,
-then `show_document` with the exact workspace label or ID and document ID; do not return only
-a filesystem path. In fixed `mcp --dir` compatibility mode, the workspace argument is omitted.
-To present an existing interactive View, call `list_views` and then `show_view` with that same
-workspace and the exact View ID; later View lifecycle calls use only the returned launch ID.
-Outside an MCP Apps host, run
-`superbee doc open <id>` to open that exact document in the existing browser reader.
-
-## Notes
-
-- `doc read <id>` truncates a large body and points at `doc read <id> --out <file>`, which streams
-  the raw markdown bytes to disk without loading them into the model context window.
-- To revise body prose without parsing YAML, run `doc read <id> --body-out <file> --json`; edit the
-  file, then pass it to `doc update <id> --body-file <file> --expected-version <receipt-version>`.
-  The body-out receipt's version comes from the same read, so this is a safe CAS edit cycle.
-- Mutations are idempotent: re-writing a doc or re-adding an existing link is a no-op (exit 0).
-- `new` and `doc update` accept a kind's declared fields as `--<field> <value>` (e.g. `--progress_status done`);
-  an unknown field or an out-of-enum value is rejected (exit 2). Run `kinds` to see a kind's fields.
-- `hook install` registers a SessionStart hook (Claude Code, Codex, OpenCode) that runs
-  `session-start`: a quick best-effort pull of the shared board, then the home view — so a new
-  session starts with the bundle's state AND any teammate changes already in context. Offline is
-  fine: the render always appears, labeled with the last known state. A global npm install binds
-  absolute Node and CLI paths, so GUI sessions do not depend on their inherited PATH. If you
-  installed the hook before `session-start` existed, re-run `hook install` once to upgrade it.
-- Edit a doc's body through `doc update --body-file` (or `--body`), never by pulling the raw file
-  with `--out`, editing it with text tools, and re-promoting it — that risks corrupting the
-  frontmatter (the engine rejects it, but the right tool avoids the dance entirely).
-- Writing a custom recipe: a worked example (the `Claim` kind — event-lifecycle findings with
-  provenance, composed from lite primitives) ships at `$REFS/recipes/claims/`; copy its shape,
-  then `superbee recipe add <folder>` to apply it (built-in recipes are named directly, e.g.
-  `superbee recipe add work-tracking`).
-- Packaging a content-free cognitive ecosystem: `$REFS/recipes/review-workflow/` carries a
-  self-describing Review Request kind plus a generic live View, but no review instances. A
-  definitions-only recipe may contain only its manifest, convention docs, explicitly declared
-  static Reference docs, and View registry/HTML pairs; install it with the same `recipe add <folder>` command.
-- A full interop-shaped example bundle (externally-authored markdown: unquoted timestamps,
-  relative links, wrapped bullets) ships at `$REFS/sample-bundle/` — copy it and point `--dir` at
-  the copy to explore a populated bundle without writing one from scratch.
+<!-- GENERATED by packages/cli/scripts/gen-skill.mjs — do not edit by hand. -->