superbee 0.1.6 → 0.2.1-pre.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.1.6",
+  "version": "0.2.1-pre.2",
   "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": [
@@ -79,8 +79,10 @@
     "esbuild": "0.25.12",
     "jsonc-parser": "3.3.1",
     "pako": "2.1.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "js-yaml": "3.15.2",
+    "@types/js-yaml": "3.12.10"
   },
-  "readme": "# superbee\n\n## What is Superbee?\n\nSuperbee gives AI coding agents shared, versioned, conflict-safe memory — as a folder of\nplain markdown in your repo.\n\nAgents forget everything between sessions, overwrite each other's work, and keep what they\nknow invisible to the humans they work for. Superbee fixes all three:\n\n- **Memory that persists.** Agents write context notes, decisions, plans, and research into a\n  knowledge bundle that survives the session. The next session — or a different agent — picks\n  up exactly where the last one left off. An optional `SessionStart` hook (Claude Code, Codex,\n  OpenCode) orients every new session automatically.\n- **Safe for many writers.** Every document write is compare-and-swap versioned and attributed\n  to an actor. Two agents racing on the same document get a clean, typed conflict instead of a\n  silent lost update — and `doc history` shows who changed what, when.\n- **Visible to humans.** Everything is plain markdown you can open in any editor, render on\n  GitHub, and diff in git. `superbee ui` serves the bundle locally as rendered, cross-linked\n  pages with derived backlinks, a live activity feed, and launchable bundle Views. `superbee\n  sync` shares the bundle with teammates on a dedicated `board` branch — pulling their changes\n  and pushing yours without touching your code.\n- **Views on demand.** Ask your agent to create whatever representation you need and Superbee will\n  create it: a self-contained HTML View, registered in the bundle as a typed document, that\n  `superbee ui` launches in a sandboxed iframe. A reading surface for one dense document, a board, a\n  timeline, a filtered queue, a chart, a dashboard — the shape follows the question rather than a\n  fixed set of built-in screens, and a view worth keeping stays. A data View reads live bundle\n  content through a narrow read-only bridge and refreshes as documents change. Views are bundle\n  content, so they travel with `sync` and open the same way for a teammate's agent.\n- **Agent-native by design.** The CLI follows the AXI principles for agent-facing tools:\n  structured, token-lean output; result counts and truncation with explicit escape hatches;\n  idempotent mutations; structured errors with a small, stable exit-code taxonomy. Agents get\n  predictable responses they can act on without parsing prose or flooding their context window.\n- **Yours, and portable.** Bundles conform to the Open Knowledge Format — new bundles are\n  written as OKF v0.2, and existing v0.1 bundles stay supported in place — so they survive the\n  tool: hand the folder to someone else, or read it with anything that speaks markdown.\n  Everything works offline; the filesystem is the source of truth. Typed document schemas\n  (\"kinds\") live in the bundle itself, so the bundle describes its own structure.\n\nThe npm package ships one self-contained executable with zero runtime dependencies, plus an\nAgent Skill that teaches agents how to use it.\n\n## How do I download Superbee on Windows?\n\n**Requirements: Node.js 20 or newer on macOS, Linux, or native Windows.** You do not need WSL,\nUbuntu, or Docker. On Windows, Superbee keeps per-user operational state under\n`%LOCALAPPDATA%\\Superbee`; npm installs the command as `superbee.cmd`.\n\nSuperbee currently has two npm release channels:\n\n- `latest` is the stable channel selected by bare `superbee`, including native Windows support.\n- `next` is the prerelease channel for release candidates.\n\nInstall Superbee on Windows:\n\n```powershell\nnpm install -g superbee\nsuperbee.cmd setup\n```\n\nOn macOS or Linux, install it with `npm install -g superbee` and then run `superbee setup`.\n\nAfter installation, ask your AI agent to run `superbee setup` (`superbee.cmd setup` when invoking\nthe Windows shim explicitly). Setup walks the agent through Agent Skill, SessionStart hook, and MCP\nregistration. It is read-only: it inspects your configuration and returns one safe next command at\na time, so the agent performs any actual changes with your approval.\n\nThe managed Agent Skill works in Claude Code, Codex, and OpenCode. OpenCode discovers Superbee from\nits documented Claude-compatible Skill path. It shares Claude Code's Skill bytes by default; if\nClaude Code is explicitly relocated, the installer manages the two documented host paths separately.\n\nUpgrading from the legacy `@holaxis/aslite` package or the retired marketplace plugin? Install\n`superbee` alongside it, have your agent run `superbee setup` to migrate the exact legacy\nintegrations, then remove the old package with `npm uninstall -g @holaxis/aslite`. Existing\n`.agentstate-lite/` bundles and `.agentstate.json` bindings keep working with no migration.\n\n## How to use Superbee\n\nSuperbee is agent-first: you don't type its commands yourself — you ask your agent for what\nyou need, and the Agent Skill included with this package helps the agent translate your\ninstructions into CLI commands. For example:\n\n- \"Set up a Superbee workspace 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 drives a small, predictable CLI: `init` creates a bundle in a\nconventional `.superbee/` folder (discovered automatically, the way git finds `.git`); `new`,\n`doc write`, `doc update`, and `link add` create and connect typed documents; `list` and\n`doc read` query them; `sync` shares the board with teammates.\n\nWhen you want to see the knowledge yourself, ask the agent to open it — or run the two\nhuman-facing commands directly:\n\n```sh\nsuperbee ui --open        # the bundle, rendered: pages, links, backlinks, live Views\nsuperbee doc open <id>    # one exact document in the same local browser reader\n```\n\nRun `superbee --help` (or any subcommand with `--help`) for the full command reference.\nDesign and format docs live in the [repository](https://github.com/Holaxis-ai/superbee).\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\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, Linux, or Windows. Native Windows is supported; you do not\nneed WSL or Docker.\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\nOn Windows, Superbee keeps its private per-user state, such as the workspace catalog and remote\ncredentials, under `%LOCALAPPDATA%\\Superbee`. npm installs `superbee.cmd` alongside the `superbee`\ncommand; if PowerShell's execution policy blocks the `.ps1` wrapper, call `superbee.cmd` instead.\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/cli/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"
 }