superbee 0.2.1-pre.1 → 0.2.1

package/README.md

@@ -1,114 +1,110 @@
 # superbee
 
+Shared, versioned, conflict-safe knowledge for AI coding agents, stored as plain markdown in
+your repo.
+
+Superbee is pre-1.0. Commands and formats may change between releases.
+
 ## What is Superbee?
 
-Superbee gives AI coding agents shared, versioned, conflict-safe memory — as a folder of
-plain markdown in your repo.
-
-Agents forget everything between sessions, overwrite each other's work, and keep what they
-know invisible to the humans they work for. Superbee fixes all three:
-
-- **Memory that persists.** Agents write context notes, decisions, plans, and research into a
-  knowledge bundle that survives the session. The next session — or a different agent — picks
-  up exactly where the last one left off. An optional `SessionStart` hook (Claude Code, Codex,
-  OpenCode) orients every new session automatically.
-- **Safe for many writers.** Every document write is compare-and-swap versioned and attributed
-  to an actor. Two agents racing on the same document get a clean, typed conflict instead of a
-  silent lost update — and `doc history` shows who changed what, when.
-- **Visible to humans.** Everything is plain markdown you can open in any editor, render on
-  GitHub, and diff in git. `superbee ui` serves the bundle locally as rendered, cross-linked
-  pages with derived backlinks, a live activity feed, and launchable bundle Views. `superbee
-  sync` shares the bundle with teammates on a dedicated `board` branch — pulling their changes
-  and pushing yours without touching your code.
-- **Views on demand.** Ask your agent to create whatever representation you need and Superbee will
-  create it: a self-contained HTML View, registered in the bundle as a typed document, that
-  `superbee ui` launches in a sandboxed iframe. A reading surface for one dense document, a board, a
-  timeline, a filtered queue, a chart, a dashboard — the shape follows the question rather than a
-  fixed set of built-in screens, and a view worth keeping stays. A data View reads live bundle
-  content through a narrow read-only bridge and refreshes as documents change. Views are bundle
-  content, so they travel with `sync` and open the same way for a teammate's agent.
-- **Agent-native by design.** The CLI follows the AXI principles for agent-facing tools:
-  structured, token-lean output; result counts and truncation with explicit escape hatches;
-  idempotent mutations; structured errors with a small, stable exit-code taxonomy. Agents get
-  predictable responses they can act on without parsing prose or flooding their context window.
-- **Yours, and portable.** Bundles conform to the Open Knowledge Format — new bundles are
-  written as OKF v0.2, and existing v0.1 bundles stay supported in place — so they survive the
-  tool: hand the folder to someone else, or read it with anything that speaks markdown.
-  Everything works offline; the filesystem is the source of truth. Typed document schemas
-  ("kinds") live in the bundle itself, so the bundle describes its own structure.
-
-The npm package ships one self-contained executable with zero runtime dependencies, plus an
-Agent Skill that teaches agents how to use it.
-
-## How do I download Superbee on Windows?
-
-**Requirements: Node.js 20 or newer on macOS, Linux, or native Windows.** You do not need WSL,
-Ubuntu, or Docker. On Windows, Superbee keeps per-user operational state under
-`%LOCALAPPDATA%\Superbee`; npm installs the command as `superbee.cmd`.
-
-Superbee currently has two npm release channels:
-
-- `latest` is the stable channel selected by bare `superbee`, including native Windows support.
-- `next` is the prerelease channel for testing the current release candidate.
-
-Install the current prerelease on Windows:
-
-```powershell
-npm install -g superbee@next
-superbee.cmd setup
+Agents forget everything between sessions, overwrite each other's work, and keep what they know
+invisible to the humans they work for. Superbee fixes all three with a **knowledge bundle**: a
+folder of markdown documents, by convention `.superbee/` at your project root, that agents read
+and write through a small command-line tool.
+
+- **Context that persists.** Agents write context notes, decisions, plans, and research into the
+  bundle. The next session, or a different agent, picks up where the last one left off. An
+  optional `SessionStart` hook for Claude Code, Codex, and OpenCode orients every new session
+  automatically.
+- **Safe for many writers.** Each write can carry the actor that made it. A writer can name the
+  version it last read; if anyone changed the document since, the write fails with a typed
+  conflict error instead of silently overwriting their work.
+- **Visible to humans.** The bundle is plain markdown. Open it in any editor, render it on
+  GitHub, diff it in git. `superbee ui` serves it locally as cross-linked pages with backlinks and
+  a live activity feed. No bundle content leaves your machine until you run `superbee sync`, which
+  shares the bundle with teammates through the board: a copy of the bundle kept on its own git
+  branch, separate from your code.
+- **Views on demand.** Ask your agent for a dashboard, a timeline, a filtered task queue, or a
+  reading view of one dense document. It builds a self-contained HTML page, stores it in the bundle
+  as a View, and `superbee ui` hosts it in a sandboxed frame. A View reads the bundle live and can
+  change it only through a write you confirm. Views are bundle content, so they travel with `sync`.
+- **Built for agents.** Output is structured and token-lean, and errors carry a small, stable set
+  of exit codes. Agents act on responses without parsing prose or flooding their context window.
+- **Yours, and portable.** Bundles follow the Open Knowledge Format (OKF), a convention of
+  markdown with frontmatter, so they outlive the tool: hand the folder to someone else, or read it
+  with anything that speaks markdown. New bundles are written as OKF v0.2, and existing v0.1
+  bundles keep working as they are. Reading and writing the bundle works offline; only sharing
+  needs a network. The document schemas, called kinds, live inside the bundle, so it describes
+  its own structure.
+
+The npm package is one self-contained executable with zero runtime dependencies, plus an Agent
+Skill, an instruction file your agent loads, that teaches it how to use the tool.
+
+## Install
+
+Requires Node.js 20 or newer on macOS, Linux, or Windows. Native Windows is supported; you do not
+need WSL or Docker.
+
+```sh
+npm install -g superbee
 ```
 
-On macOS or Linux, the stable channel remains available with `npm install -g superbee`. To test the
-same prerelease as Windows, install `superbee@next` instead.
+Stable releases publish on npm's `latest` tag and prereleases on `next`.
+
+On Windows, Superbee keeps its private per-user state, such as the workspace catalog and remote
+credentials, under `%LOCALAPPDATA%\Superbee`. npm installs `superbee.cmd` alongside the `superbee`
+command; if PowerShell's execution policy blocks the `.ps1` wrapper, call `superbee.cmd` instead.
+
+Run `superbee version --check` to compare your install with the current stable release.
 
-After installation, ask your AI agent to run `superbee setup` (`superbee.cmd setup` when invoking
-the Windows shim explicitly). Setup walks the agent through Agent Skill, SessionStart hook, and MCP
-registration. It is read-only: it inspects your configuration and returns one safe next command at
-a time, so the agent performs any actual changes with your approval.
+## First run: let your agent finish setup
 
-The managed Agent Skill works in Claude Code, Codex, and OpenCode. OpenCode discovers Superbee from
-its documented Claude-compatible Skill path. It shares Claude Code's Skill bytes by default; if
-Claude Code is explicitly relocated, the installer manages the two documented host paths separately.
+`npm install` gives you the CLI. The integrations (the Agent Skill, the `SessionStart` hook, and
+MCP server registration, where MCP is the Model Context Protocol) are installed by your agent,
+not by hand. Ask it:
 
-Upgrading from the legacy `@holaxis/aslite` package or the retired marketplace plugin? Install
-`superbee` alongside it, have your agent run `superbee setup` to migrate the exact legacy
-integrations, then remove the old package with `npm uninstall -g @holaxis/aslite`. Existing
-`.agentstate-lite/` bundles and `.agentstate.json` bindings keep working with no migration.
+> Run `superbee setup` and follow its instructions.
 
-## How to use Superbee
+Setup itself changes nothing. It inspects your configuration and returns one safe next command at
+a time, and the agent runs each with your approval. Setup knows Claude Code, Codex, and OpenCode,
+plus Claude Desktop for the MCP registration only.
 
-Superbee is agent-first: you don't type its commands yourself — you ask your agent for what
-you need, and the Agent Skill included with this package helps the agent translate your
-instructions into CLI commands. For example:
+## Everyday use
 
-- "Set up a Superbee workspace for this project and track our tasks in it."
+You rarely type Superbee commands yourself. You ask your agent, and the Agent Skill translates the
+request into CLI calls:
+
+- "Set up a Superbee bundle for this project and track our tasks in it."
 - "Write up what we decided about the auth design as a doc, and link it to the task."
 - "What did the last session leave off on? Check the context notes."
 - "Sync the board so my teammate's agent sees this."
 - "Give me a view of the open tasks grouped by owner."
 
-Behind those requests, the agent drives a small, predictable CLI: `init` creates a bundle in a
-conventional `.superbee/` folder (discovered automatically, the way git finds `.git`); `new`,
-`doc write`, `doc update`, `doc field`, and `link add` create and connect typed documents; `list` and
-`doc read` query them; `sync` shares the board with teammates.
-
-Use `superbee doc field <action> <document-id> <field-name>` to change one field.
-`set` assigns a supported non-collection field; `add` and `remove` change tags or sources;
-`edit` changes a selected source; `replace-all` replaces the complete tags or sources list.
-`edit` and `replace-all` require `--expected-version` from a document read. Source selectors
-use an exact `--id` or a unique `--resource` for an ID-less source. Supply structured values
-through a JSON or YAML `--from-file`. Verification remains `doc verify`.
+Behind those requests the agent uses a small set of commands: `init --dir .superbee` creates the
+bundle, `new` creates a document of a declared kind, `doc write` writes a free-form one,
+`doc update` changes a document, `link add` connects two, `list` and `doc read` query them, and
+`sync` shares the board. `superbee --help` lists the commands, and `superbee <command> --help`
+gives each one's full reference.
 
-When you want to see the knowledge yourself, ask the agent to open it — or run the two
-human-facing commands directly:
+The two commands meant for you are the ones that show you the knowledge:
 
 ```sh
-superbee ui --open        # the bundle, rendered: pages, links, backlinks, live Views
-superbee doc open <id>    # one exact document in the same local browser reader
+superbee ui --open        # the whole bundle, rendered in your browser
+superbee doc open <id>    # one document, by an id from `superbee list`
 ```
 
-Run `superbee --help` (or any subcommand with `--help`) for the full command reference.
-Design and format docs live in the [repository](https://github.com/Holaxis-ai/superbee).
+## Upgrading from aslite
+
+If you installed the earlier `@holaxis/aslite` package or its marketplace plugin: install
+`superbee` alongside it, have your agent run `superbee setup` to migrate the integrations, then
+run `npm uninstall -g @holaxis/aslite`. Existing `.agentstate-lite/` bundles and
+`.agentstate.json` bindings keep working with no migration.
+
+## Learn more
+
+The [repository](https://github.com/Holaxis-ai/superbee) holds the source, the
+[CLI contract](https://github.com/Holaxis-ai/superbee/blob/main/packages/cli/AXI-CONTRACT.md),
+and the [wire protocol](https://github.com/Holaxis-ai/superbee/blob/main/docs/WIRE-PROTOCOL.md).
 
 ## License
 

package/dist/publication-bridge.mjs

@@ -2869,7 +2869,7 @@ var require_js_yaml2 = __commonJS({
 });
 
 // ../publication/src/bridge.ts
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 
 // ../core/src/backend.ts
 import path3 from "node:path";
@@ -4129,8 +4129,161 @@ var nodeFilesystemIdentityPort = Object.freeze({
   }
 });
 
-// ../core/src/versioning.ts
-import { createHash as createHash3 } from "node:crypto";
+// ../core/src/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+var INITIAL_STATE = new Uint32Array([
+  1779033703,
+  3144134277,
+  1013904242,
+  2773480762,
+  1359893119,
+  2600822924,
+  528734635,
+  1541459225
+]);
+var encoder = new TextEncoder();
+function rotr(value, bits) {
+  return value >>> bits | value << 32 - bits;
+}
+function compress(h, w, view, offset) {
+  for (let i = 0; i < 16; i++) {
+    w[i] = view.getUint32(offset + i * 4);
+  }
+  for (let i = 16; i < 64; i++) {
+    const w15 = w[i - 15];
+    const w2 = w[i - 2];
+    const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ w15 >>> 3;
+    const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ w2 >>> 10;
+    w[i] = w[i - 16] + s0 + w[i - 7] + s1 >>> 0;
+  }
+  let a = h[0];
+  let b = h[1];
+  let c = h[2];
+  let d = h[3];
+  let e = h[4];
+  let f = h[5];
+  let g = h[6];
+  let hh = h[7];
+  for (let i = 0; i < 64; i++) {
+    const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+    const ch = e & f ^ ~e & g;
+    const t1 = hh + S1 + ch + K[i] + w[i] >>> 0;
+    const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+    const maj = a & b ^ a & c ^ b & c;
+    const t2 = S0 + maj >>> 0;
+    hh = g;
+    g = f;
+    f = e;
+    e = d + t1 >>> 0;
+    d = c;
+    c = b;
+    b = a;
+    a = t1 + t2 >>> 0;
+  }
+  h[0] = h[0] + a >>> 0;
+  h[1] = h[1] + b >>> 0;
+  h[2] = h[2] + c >>> 0;
+  h[3] = h[3] + d >>> 0;
+  h[4] = h[4] + e >>> 0;
+  h[5] = h[5] + f >>> 0;
+  h[6] = h[6] + g >>> 0;
+  h[7] = h[7] + hh >>> 0;
+}
+function sha256HexOfBytes(bytes) {
+  const h = new Uint32Array(INITIAL_STATE);
+  const w = new Uint32Array(64);
+  const length = bytes.byteLength;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, length);
+  const fullBlocks = length >>> 6;
+  for (let block = 0; block < fullBlocks; block++) {
+    compress(h, w, view, block * 64);
+  }
+  const remaining = length - fullBlocks * 64;
+  const tail = new Uint8Array(remaining + 1 + 8 > 64 ? 128 : 64);
+  tail.set(bytes.subarray(fullBlocks * 64));
+  tail[remaining] = 128;
+  const tailView = new DataView(tail.buffer);
+  const bitLengthHigh = Math.floor(length / 536870912);
+  const bitLengthLow = length << 3 >>> 0;
+  tailView.setUint32(tail.length - 8, bitLengthHigh);
+  tailView.setUint32(tail.length - 4, bitLengthLow);
+  for (let offset = 0; offset < tail.length; offset += 64) {
+    compress(h, w, tailView, offset);
+  }
+  let hex = "";
+  for (let i = 0; i < 8; i++) {
+    hex += h[i].toString(16).padStart(8, "0");
+  }
+  return hex;
+}
+function sha256HexOfUtf8(input) {
+  return sha256HexOfBytes(encoder.encode(input));
+}
 
 // ../core/src/version-transport.ts
 var VersionConflict = class extends Error {
@@ -4150,16 +4303,17 @@ var VersionConflict = class extends Error {
 
 // ../core/src/versioning.ts
 function sha256Hex(input) {
-  return createHash3("sha256").update(input, "utf8").digest("hex");
+  return sha256HexOfUtf8(input);
 }
 function versionOfBytes(raw) {
   return `sha256:${sha256Hex(raw)}`;
 }
 function blobVersion(bytes) {
-  return `sha256:${createHash3("sha256").update(bytes).digest("hex")}`;
+  return `sha256:${sha256HexOfBytes(bytes)}`;
 }
 function defaultActor() {
-  return process.env.USER?.trim() || process.env.USERNAME?.trim() || process.env.LOGNAME?.trim() || "local";
+  const env = typeof process !== "undefined" ? process.env : void 0;
+  return env?.USER?.trim() || env?.USERNAME?.trim() || env?.LOGNAME?.trim() || "local";
 }
 
 // ../core/src/backend.ts
@@ -4401,9 +4555,19 @@ var FilesystemBackend = class _FilesystemBackend {
   }
 };
 
-// ../core/src/bundle.ts
+// ../core/src/bundle-ops.ts
+var defaultBackendFactory;
+function setDefaultBackendFactory(factory) {
+  defaultBackendFactory = factory;
+}
 function backendFor(bundle) {
-  return bundle.backend ?? new FilesystemBackend(bundle.root);
+  if (bundle.backend) return bundle.backend;
+  if (defaultBackendFactory === void 0) {
+    throw new InvalidInputError(
+      `Bundle '${bundle.root}' has no backend and this runtime installs no default: pass bundle.backend explicitly or register one with setDefaultBackendFactory.`
+    );
+  }
+  return defaultBackendFactory(bundle.root);
 }
 async function readBundleOkfVersion2(bundle) {
   return readBundleOkfVersion(backendFor(bundle));
@@ -4421,6 +4585,9 @@ async function queryEdges2(bundle, filter = {}) {
   return queryEdges(backendFor(bundle), filter);
 }
 
+// ../core/src/bundle.ts
+setDefaultBackendFactory((root) => new FilesystemBackend(root));
+
 // ../core/src/kinds.ts
 var CONVENTIONS_PREFIX = "conventions/";
 var CONVENTION_TYPE = "Convention";
@@ -5652,7 +5819,7 @@ var PUBLICATION_BRIDGE_V0 = "v0";
 // ../publication/src/bridge.ts
 var STATIC_LAUNCH_ID = "publication-snapshot";
 function digest(bytes) {
-  return `sha256:${createHash4("sha256").update(bytes).digest("hex")}`;
+  return `sha256:${createHash3("sha256").update(bytes).digest("hex")}`;
 }
 function createPublicationBridge(options) {
   if (options.protocol !== PUBLICATION_BRIDGE_V0) {