superbee 0.3.0-pre.1 → 0.3.0-pre.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.3.0-pre.1",
+  "version": "0.3.0-pre.3",
   "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": [
@@ -86,6 +86,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\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 Node.js 20 or newer on macOS and 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\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 Node.js 20 or newer on macOS and 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\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",
   "readmeFilename": "README.md"
 }

package/references/hosted-checkout.md

@@ -0,0 +1,135 @@
+# Working in a hosted checkout
+
+Read this when you work in a folder made by `superbee checkout`, or when `superbee sync` reports a
+conflict there. The hosted bundle is the authority. The folder is a working copy. `superbee sync`
+applies changes directly under the signed-in person's own access, and nobody has to approve them.
+
+## Sign-in: relay the link, then retry
+
+Hosted commands start sign-in by themselves. When a command returns `AUTH_REQUIRED` (exit 4):
+
+1. Give the person `details.sign_in_url` and `details.user_code` exactly as returned.
+2. Wait until they say they have confirmed.
+3. Run the same command again (`details.resume`). It finishes sign-in and continues.
+
+Never ask for a password, token or code the person did not see in their browser.
+`superbee setup hosted` signs in and records the default hosted workspace in one step. If the
+receipt says `choose_workspace`, ask the person which workspace to use, then run the command it
+lists for that workspace.
+
+## Sync at the end of a batch of edits
+
+Edit files as usual, then run `superbee sync` once when a batch of related edits is done, not after
+every file. Sync always pulls before it sends. Its receipt has one row per document:
+`committed`, `conflict`, `held`, `refused`, `unknown` or `paused`. It exits 0 only when every row is
+committed.
+
+Reads keep the folder current on their own:
+- `list`, `doc read`, `status`, `home`, `link show` and `view list` pull first when the last pull
+  is more than five minutes old. They wait at most two seconds and never send anything.
+- These pulls never start a sign-in. When you are signed out, they print a note on stderr and skip
+  the pull. Run `superbee sync`, which returns the sign-in link to relay.
+- When the last pull is more than thirty minutes old, they print a warning on stderr. Run sync
+  then.
+- `SUPERBEE_NO_AUTOPULL=<any value>` turns these pulls off.
+
+## Conflicts: inspect, then keep, take or revise
+
+Changes to different documents merge automatically. Any concurrent change to the same document,
+even to different frontmatter keys, comes back as a `conflict` row, and nothing is sent for that
+document until you resolve it:
+
+```sh
+superbee sync --inspect --doc <id>            # base, your version, the host's version
+superbee sync --resolve take --doc <id>       # use the host's version
+superbee sync --resolve keep --doc <id>       # send yours over the inspected host version
+superbee sync --resolve revise --doc <id>     # edit the file to the combined result first, then send it
+superbee sync                                 # sends what keep or revise decided
+```
+
+- `--resolve` only records the decision in the checkout. It never sends anything: its receipt
+  says `sent: false`, and after `keep` or `revise` its `next` and `help` name the `superbee sync`
+  that sends it. `take` has nothing to send.
+- `keep` or `revise` again before that sync answers `already_resolved: true` ("waiting to send");
+  the first decision stands. `take` after an unsent `keep` or `revise` replaces it (`replaces`),
+  and nothing is sent. When the change may already have been sent, `take` is refused
+  (`resolution_not_replaceable`): run `superbee sync`, then resolve any conflict it reports.
+
+- `keep` and `revise` need an `--inspect` first (`not_inspected` otherwise). If the host changes
+  after the inspection, they refuse with `stale_review`: inspect again, and decide again.
+- `--inspect <id>` is an alias of `--inspect --doc <id>`.
+- `keep` refuses a file edited since the conflict (`file_edited`). Use `revise` to send the file as
+  it is now.
+- To discard your edits with `take`, remove the file first if the command says it would discard
+  them.
+- If you cannot tell which version is right, ask the person. Do not merge by guessing.
+
+## Deleting documents
+
+Deleting a file (or running `superbee doc delete`) sends a delete of the version you had at the
+next sync. The host keeps the document's history.
+
+Deleting many files at once is held instead. The rule: when the deletes of the last day are more
+than half the checkout and at least 3, the new ones are not sent. The same rule is applied to the
+documents this checkout did not create itself, so documents it added earlier never dilute the
+count. The sync receipt then carries `deletions_held`, which names the held documents. The hold
+stays in place across syncs until the person decides. Accepting it is the person's step, never
+yours:
+
+1. Name the held documents to the person, and ask whether they should be removed from the bundle.
+2. If they want them removed, give them `deletions_held.confirmation_required.command_for_person`
+   (`superbee sync --accept-deletes <count>:<digest>`) to run in their own terminal. It lists the
+   documents and asks them to type the count. The token covers exactly that set; if the set
+   changes, nothing is accepted.
+3. Do not run it yourself. In a shell without a terminal it is refused with `FORBIDDEN`
+   `needs_person_at_terminal` (exit 2), and nothing is accepted. Do not retry it or work around it.
+   The check keeps the person in the loop; it is not a security boundary. A pseudo-terminal
+   (`script`, `expect`), typing into their terminal (`tmux send-keys`) or importing the CLI with
+   another terminal would get past it, and each of those is a violation of this rule.
+4. Otherwise run `superbee sync --restore-deletes`, which puts the files back. `--resolve take --doc
+   <id>` restores a single file. Both work from your shell.
+
+If the host deleted a document you edited, `--resolve keep` re-creates it, after an `--inspect`
+that shows the deletion. If you deleted a document the host changed, `keep` deletes the host's
+version (after `--inspect`), and `take` brings it back.
+
+When the host no longer lists most of the documents the folder holds (8 or more, and more than
+half, or all of them), the pull removes none of them and the receipt carries
+`pulled.refused_deletions`: a bundle emptied or replaced by mistake looks the same. Tell the person.
+Once they confirm, in the Superbee app, that the bundle really shrank, run its `take` command
+(`superbee sync --take-host-deletions <count>:<digest>`). It removes the files of exactly that set
+and keeps any file you edited. Nothing is sent to the host.
+
+A host document whose id cannot be a file in the folder (a path-like id such as `a/../b`) is held
+with a `held` row, reason `unsafe_id`, and the rest of the bundle syncs. A host document whose id
+differs only in letter case from another is held as `case_collision`. Both are renamed in the
+Superbee app, by the person.
+
+## Refusals that belong to the person
+
+Some commands are refused in a hosted checkout with "do this in the Superbee app". Examples:
+editing Kinds or recipes, artifacts, and `doc verify`. Tell the person what to do in the app. Do
+not work around a refusal by editing files, using another command, or copying the bundle
+somewhere else.
+
+`checkout` adds the folder to the workspace catalog, where `catalog list` shows it with
+`home: hosted`. The local MCP app (`superbee mcp`) can read it by that label, but refuses every
+write there with the same "do this in the Superbee app": Views and documents written through it
+could not sync.
+
+`sync_busy` means another command is working, or is just taking or releasing the lock: wait,
+then retry, and never remove that lock. Only `lock_orphaned` means the lock's holder is gone:
+confirm that no superbee command is still running, then remove the lock named in the help.
+
+## Session hooks (opt-in)
+
+- `superbee hook install` installs the SessionStart hook. In a hosted checkout, it pulls from the
+  host at the start of each session.
+- `superbee hook install --turn-end-sync` also installs a Stop hook for Claude Code and Codex. It
+  syncs the checkout when each turn ends, and skips the network when nothing changed and the last
+  pull is recent. If that sync finds a conflict, a held file or a sign-in link, the hook hands it
+  back to you before the turn ends: handle it as above. It reports each condition once; the same
+  unresolved condition is not reported on later turns, so check `superbee sync` yourself.
+- Offer the Stop hook, but install it only when the person agrees.
+  `superbee hook uninstall --turn-end-sync` removes it, and `SUPERBEE_NO_TURN_SYNC=<any value>`
+  turns it off for a shell.