superbee 0.4.2 → 0.4.3-pre.1

package/README.md

@@ -53,7 +53,11 @@ Requires a supported Node.js 22, 24, or 26 release (22.14.0 minimum) on macOS or
 npm install -g superbee
 ```
 
-Stable releases publish on npm's `latest` tag and prereleases on `next`.
+Stable releases publish on npm's `latest` tag and prereleases on `next`. To try the prerelease:
+
+```sh
+npm install -g superbee@next
+```
 
 Windows adapters and the `superbee-windows` executable live in a separate repository and are
 not included in `superbee`. Most Windows users should run Superbee in WSL2, where npm sees a

package/dist/superbee.mjs

@@ -44,7 +44,7 @@ var __toESM = (mod, isNodeMode, target3) => (target3 = mod != null ? __create(__
 var define_SUPERBEE_BUILD_IDENTITY_default;
 var init_define_SUPERBEE_BUILD_IDENTITY = __esm({
   "<define:__SUPERBEE_BUILD_IDENTITY__>"() {
-    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.2" }, source: { commit: "069a42092f39d8261ccd4322c0dc7ff5488aa2c8", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
+    define_SUPERBEE_BUILD_IDENTITY_default = { schema: "superbee.build-identity.v1", package: { name: "superbee", version: "0.4.3-pre.1" }, source: { commit: "0c5c7f2b2437d3e33a4aa707f13704e9896482a6", dirty: false }, artifact: { channel: "npm-package" }, compatibility_contracts: { skill: 1, hook: 1, mcp: 1 } };
   }
 });
 
@@ -6070,15 +6070,15 @@ function lexicalPosixHookTokens(command) {
     const raw = command.slice(start, i);
     const current = renderGeneratedHookToken(token);
     const historical = renderHistoricalDoubleQuotedHookToken(token);
-    const envelope2 = raw === current ? "current" : raw === historical ? "historical_double" : void 0;
-    if (!envelope2) return void 0;
-    tokens.push({ raw, value: token, envelope: envelope2 });
+    const envelope3 = raw === current ? "current" : raw === historical ? "historical_double" : void 0;
+    if (!envelope3) return void 0;
+    tokens.push({ raw, value: token, envelope: envelope3 });
     if (i < command.length) {
       i += 1;
       if (i === command.length || command[i] === " ") return void 0;
     }
   }
-  if (tokens.some(({ envelope: envelope2 }) => envelope2 === "historical_double")) {
+  if (tokens.some(({ envelope: envelope3 }) => envelope3 === "historical_double")) {
     const exactHistoricalCommand = tokens.length === 2 && tokens[0]?.envelope === "historical_double" && tokens[1]?.envelope === "current" && tokens[1]?.raw === "session-start";
     if (!exactHistoricalCommand) return void 0;
   }
@@ -7980,8 +7980,8 @@ function render(value, mode) {
 `;
   }
 }
-function renderErrorEnvelope(envelope2) {
-  return `${encode(envelope2)}
+function renderErrorEnvelope(envelope3) {
+  return `${encode(envelope3)}
 `;
 }
 function renderUsage(usage3) {
@@ -8892,8 +8892,8 @@ function assertValidExpectedVersion(expectedVersion) {
 }
 async function refusesIdentity(res) {
   try {
-    const envelope2 = await res.json();
-    return envelope2?.error?.code === "USAGE" && envelope2.error.message === IDENTITY_UNSUPPORTED;
+    const envelope3 = await res.json();
+    return envelope3?.error?.code === "USAGE" && envelope3.error.message === IDENTITY_UNSUPPORTED;
   } catch {
     return false;
   }
@@ -8911,8 +8911,8 @@ function etagForm(token) {
 async function namesMalformedDocument(res) {
   if (res.status !== 500) return false;
   try {
-    const envelope2 = await res.clone().json();
-    return typeof envelope2?.error?.details?.malformed?.reason === "string";
+    const envelope3 = await res.clone().json();
+    return typeof envelope3?.error?.details?.malformed?.reason === "string";
   } catch {
     return false;
   }
@@ -9006,26 +9006,26 @@ var init_remote_backend = __esm({
       }
       /** Parse a non-2xx response into the typed error the engine expects. */
       async toError(res, fallbackId) {
-        let envelope2 = null;
+        let envelope3 = null;
         try {
-          envelope2 = await res.json();
+          envelope3 = await res.json();
         } catch {
-          envelope2 = null;
+          envelope3 = null;
         }
         if (res.status === 412) {
-          const expected = envelope2?.error?.details?.expected ?? null;
-          const actual = envelope2?.error?.details?.actual ?? null;
+          const expected = envelope3?.error?.details?.expected ?? null;
+          const actual = envelope3?.error?.details?.actual ?? null;
           return new VersionConflict(fallbackId, expected, actual);
         }
-        const malformedDoc = envelope2?.error?.details?.malformed;
+        const malformedDoc = envelope3?.error?.details?.malformed;
         if (malformedDoc && typeof malformedDoc.reason === "string") {
           return new MalformedDocumentError(
             typeof malformedDoc.id === "string" ? malformedDoc.id : fallbackId,
             new Error(malformedDoc.reason)
           );
         }
-        const message = envelope2?.error?.message ?? `wire request failed with status ${res.status}`;
-        const code3 = envelope2?.error?.code ?? (res.status === 401 ? "AUTH_REQUIRED" : res.status >= 500 ? "RUNTIME" : "USAGE");
+        const message = envelope3?.error?.message ?? `wire request failed with status ${res.status}`;
+        const code3 = envelope3?.error?.code ?? (res.status === 401 ? "AUTH_REQUIRED" : res.status >= 500 ? "RUNTIME" : "USAGE");
         return new RemoteError(message, code3, res.status);
       }
       async read(id) {
@@ -9048,8 +9048,8 @@ var init_remote_backend = __esm({
         if (res.status === 404) {
           let missing2 = [];
           try {
-            const envelope2 = await res.json();
-            missing2 = envelope2.error.details?.missing ?? [];
+            const envelope3 = await res.json();
+            missing2 = envelope3.error.details?.missing ?? [];
           } catch {
           }
           throw notFound3(missing2[0] ?? ids[0]);
@@ -11728,6 +11728,184 @@ var init_governed_body_write = __esm({
   }
 });
 
+// ../core/src/kind-coverage.ts
+function bodyProse(body) {
+  let relatedLevel;
+  for (const line2 of body.split("\n")) {
+    const text5 = line2.trim();
+    const heading = /^(#{1,6})[ \t]+(.+?)\s*#*\s*$/.exec(text5);
+    if (heading) {
+      const level2 = heading[1].length;
+      if (relatedLevel !== void 0 && level2 <= relatedLevel) relatedLevel = void 0;
+      if (heading[2].trim().toLowerCase() === "related" && relatedLevel === void 0) relatedLevel = level2;
+      continue;
+    }
+    if (relatedLevel !== void 0) continue;
+    const prose = text5.replace(/^[-*] +/, "");
+    if (!prose) continue;
+    const links = extractMarkdownLinks(prose);
+    if (!(links.length === 1 && prose === `[${links[0].text}](${links[0].href})`)) return true;
+  }
+  return false;
+}
+function fieldStats(docs, value) {
+  let present = 0, sentinels = 0, used = 0;
+  for (const doc2 of docs) {
+    const v2 = value(doc2);
+    if (v2 !== void 0) used++;
+    if (filled(v2)) present++;
+    else if (sentinel(v2)) sentinels++;
+  }
+  return { present: used, filled: present, sentinel: sentinels, empty: docs.length - present - sentinels, rate: ratio(present, docs.length) };
+}
+function checkedOn(kind2, docs, now) {
+  const buckets = { future: 0, "0-7d": 0, "8-30d": 0, "31-90d": 0, "91-180d": 0, "181-365d": 0, ">365d": 0 };
+  let missing2 = 0, invalid = 0, older = 0;
+  const horizon = freshnessHorizonMs(kind2);
+  for (const doc2 of docs) {
+    const value = doc2.frontmatter.checked_on;
+    if (!filled(value)) {
+      missing2++;
+      continue;
+    }
+    const ms = typeof value === "string" ? parseTimestamp(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00Z` : value, "0.2") : null;
+    if (ms === null) {
+      invalid++;
+      continue;
+    }
+    const ageMs2 = now.getTime() - ms;
+    const days = Math.floor(ageMs2 / DAY);
+    const bucket = days < 0 ? "future" : days <= 7 ? "0-7d" : days <= 30 ? "8-30d" : days <= 90 ? "31-90d" : days <= 180 ? "91-180d" : days <= 365 ? "181-365d" : ">365d";
+    buckets[bucket]++;
+    if (horizon !== void 0 && ageMs2 > horizon) older++;
+  }
+  return { clock: "checked_on", horizon: kind2.freshnessHorizon ?? null, horizon_ms: horizon ?? null, missing: missing2, invalid, buckets, older_than_horizon: horizon === void 0 ? null : older };
+}
+function sourceStats(docs) {
+  const domains = /* @__PURE__ */ new Map();
+  const distribution2 = { "0": 0, "1": 0, "2": 0, "3": 0, "4": 0, "5+": 0 };
+  let total = 0, zero2 = 0, invalid = 0, nonUrl = 0;
+  for (const doc2 of docs) {
+    const raw = doc2.frontmatter.sources;
+    const list4 = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
+    let count5 = 0;
+    for (const item of list4) {
+      const resource = typeof item === "string" ? item : item && typeof item === "object" && !Array.isArray(item) ? item.resource : void 0;
+      if (typeof resource !== "string" || !filled(resource)) {
+        invalid++;
+        continue;
+      }
+      count5++;
+      try {
+        const domain3 = new URL(resource).hostname.toLowerCase().replace(/^www\./, "");
+        if (!domain3) {
+          nonUrl++;
+          continue;
+        }
+        domains.set(domain3, (domains.get(domain3) ?? 0) + 1);
+      } catch {
+        nonUrl++;
+      }
+    }
+    if (!count5) zero2++;
+    total += count5;
+    distribution2[count5 >= 5 ? "5+" : String(count5)]++;
+  }
+  const ordered = [...domains].sort((a, b) => b[1] - a[1] || compare(a[0], b[0]));
+  return { zero: zero2, total, invalid_entries: invalid, non_url_resources: nonUrl, per_record: distribution2, distinct_domains: domains.size, domains_shown: Math.min(domains.size, DOMAIN_LIMIT), top_domains: ordered.slice(0, DOMAIN_LIMIT).map(([domain3, sources]) => ({ domain: domain3, sources })) };
+}
+function kindCoverage(registry2, documents, options) {
+  if (!Number.isFinite(options.now.getTime())) throw new TypeError("Coverage now must be a valid date");
+  const docs = [...documents].sort((a, b) => compare(a.id, b.id));
+  const index2 = new Map(docs.map((doc2) => [doc2.id, doc2]));
+  const edges = new Map(docs.map((doc2) => [doc2.id, parseLinksFromDoc(doc2)]));
+  const inbound = new Set([...edges.values()].flat().map((link4) => link4.to));
+  const groups = /* @__PURE__ */ new Map();
+  for (const doc2 of docs) {
+    const type = doc2.frontmatter.type;
+    const group = groups.get(type) ?? [];
+    group.push(doc2);
+    groups.set(type, group);
+  }
+  const kinds2 = [...registry2.kinds.values()].filter((kind2) => options.kind === void 0 || kind2.governs === options.kind).map((kind2) => {
+    const records = groups.get(kind2.governs) ?? [];
+    const authoring = projectKindForAuthoring(options.okfVersion, kind2);
+    const fields2 = [.../* @__PURE__ */ new Set([...authoring.fields.required, ...authoring.fields.optional])].sort(compare);
+    const stats = fields2.map((field) => ({ field, required: authoring.fields.required.includes(field), ...fieldStats(records, (doc2) => readKindField(options.okfVersion, kind2, doc2.frontmatter, field)) }));
+    const declaredStorage = new Set(fields2.map((field) => resolveKindFieldCoordinate(options.okfVersion, kind2, field)?.storageField ?? field));
+    const undeclared = /* @__PURE__ */ new Map(), envelopes = /* @__PURE__ */ new Map();
+    for (const doc2 of records) for (const key2 of Object.keys(doc2.frontmatter)) {
+      if (envelope(key2)) {
+        envelopes.set(key2, (envelopes.get(key2) ?? 0) + 1);
+        continue;
+      }
+      if (!declaredStorage.has(key2)) {
+        const ids = undeclared.get(key2) ?? [];
+        ids.push(doc2.id);
+        undeclared.set(key2, ids);
+      }
+    }
+    const relations = /* @__PURE__ */ new Map();
+    let citations = 0, dangling = 0, withLinks = 0;
+    const danglingExamples = [];
+    for (const doc2 of records) {
+      const links = edges.get(doc2.id);
+      if (links.length) withLinks++;
+      for (const link4 of links) {
+        const target3 = index2.get(link4.to);
+        if (!target3) {
+          dangling++;
+          if (danglingExamples.length < EXAMPLES) danglingExamples.push(doc2.id);
+        }
+        if (!Object.hasOwn(kind2.links ?? {}, link4.text)) {
+          citations++;
+          continue;
+        }
+        const targetKind = target3?.frontmatter.type ?? null;
+        const key2 = JSON.stringify([link4.text, targetKind]);
+        const row4 = relations.get(key2) ?? { relation: link4.text, target_kind: targetKind, target_matches: targetKind === null ? null : targetKind === kind2.links[link4.text], records: /* @__PURE__ */ new Set(), links: 0 };
+        row4.records.add(doc2.id);
+        row4.links++;
+        relations.set(key2, row4);
+      }
+    }
+    const used = new Set([...relations.values()].map((row4) => row4.relation));
+    return {
+      governs: kind2.governs,
+      records: records.length,
+      coverage: { fields: stats, body_prose: { filled: records.filter((doc2) => bodyProse(doc2.body)).length, rate: ratio(records.filter((doc2) => bodyProse(doc2.body)).length, records.length) } },
+      drift: { undeclared: [...undeclared].sort(([a], [b]) => compare(a, b)).map(([key2, ids]) => ({ key: key2, records: ids.length, rate: ratio(ids.length, records.length), examples: ids.slice(0, EXAMPLES), examples_total: ids.length })), declared_unused: stats.filter((row4) => row4.present === 0).map((row4) => row4.field), envelope: [...envelopes].sort(([a], [b]) => compare(a, b)).map(([key2, records2]) => ({ key: key2, records: records2 })) },
+      links: { with_links: withLinks, typed: [...relations.values()].sort((a, b) => compare(a.relation, b.relation) || compare(a.target_kind ?? "", b.target_kind ?? "")).map((row4) => ({ relation: row4.relation, target_kind: row4.target_kind, target_matches: row4.target_matches, records: row4.records.size, links: row4.links, rate: ratio(row4.records.size, records.length) })), untyped_citations: citations, declared_never_used: Object.keys(kind2.links ?? {}).filter((relation) => !used.has(relation)).sort(compare), dangling, dangling_examples: danglingExamples, no_inbound: records.filter((doc2) => !inbound.has(doc2.id)).length },
+      freshness: checkedOn(kind2, records, options.now),
+      sources: sourceStats(records)
+    };
+  });
+  return { now: options.now.toISOString(), documents: docs.length, undeclared_kinds: [...groups.keys()].filter((type) => !registry2.kinds.has(type)).sort(compare), kinds: kinds2 };
+}
+var SENTINELS, EXAMPLES, DOMAIN_LIMIT, DAY, compare, ratio, empty, sentinel, filled, envelope;
+var init_kind_coverage = __esm({
+  "../core/src/kind-coverage.ts"() {
+    "use strict";
+    init_define_SUPERBEE_BUILD_IDENTITY();
+    init_define_SUPERBEE_UPDATE_POLICY();
+    init_document_field_actions();
+    init_kinds();
+    init_links();
+    init_managed_document_metadata();
+    init_freshness();
+    SENTINELS = /* @__PURE__ */ new Set(["unknown", "n/a", "na", "none", "tbd", "null", "-", "?"]);
+    EXAMPLES = 3;
+    DOMAIN_LIMIT = 15;
+    DAY = 864e5;
+    compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+    ratio = (n, total) => total ? Math.round(n / total * 1e4) / 1e4 : null;
+    empty = (value) => value == null || typeof value === "string" && value.trim() === "" || (Array.isArray(value) ? value.length === 0 : typeof value === "object" && Object.keys(value).length === 0);
+    sentinel = (value) => typeof value === "string" && SENTINELS.has(value.trim().toLowerCase());
+    filled = (value) => !empty(value) && !sentinel(value);
+    envelope = (key2) => isManagedDocumentMetadataField(key2) || isStandardDocumentSetField(key2, "0.2") || key2 === "sources" || key2 === "tags";
+  }
+});
+
 // ../core/src/index.ts
 var init_src = __esm({
   "../core/src/index.ts"() {
@@ -11771,6 +11949,7 @@ var init_src = __esm({
     init_document_mutation();
     init_kind_field_mutation();
     init_managed_document_metadata();
+    init_kind_coverage();
   }
 });
 
@@ -15822,12 +16001,12 @@ function resolveCompatibleScalarEnv(opts) {
   const env = opts.env ?? process.env;
   const present = [opts.canonical, opts.legacy].filter((name) => hasOwn4(env, name)).map((name) => ({ name, value: (env[name] ?? "").trim() }));
   if (!present.length) return void 0;
-  const empty2 = present.filter((entry) => entry.value === "");
-  if (opts.requireNonEmpty && empty2.length) {
-    const sources = empty2.map((entry) => entry.name).join(" and ");
+  const empty3 = present.filter((entry) => entry.value === "");
+  if (opts.requireNonEmpty && empty3.length) {
+    const sources = empty3.map((entry) => entry.name).join(" and ");
     throw new CliError(
       "USAGE",
-      `${sources} ${empty2.length === 1 ? "was" : "were"} given an empty value - pass a ${opts.label} or unset the environment variable.`,
+      `${sources} ${empty3.length === 1 ? "was" : "were"} given an empty value - pass a ${opts.label} or unset the environment variable.`,
       opts.help ? { help: opts.help } : {}
     );
   }
@@ -17513,7 +17692,7 @@ var init_command_spec = __esm({
           {
             id: "kinds",
             leaves: [publicLeaf("kinds", "kinds", zero, 14, DIR_SURFACE)],
-            usage: "kinds [--dir <path>] [--remote <url>]",
+            usage: "kinds [--coverage [--kind <Kind>] [--now <ISO>]] [--dir <path>] [--remote <url>]",
             summary: "List the kind conventions this bundle declares (purpose, described fields, exact required body headings, typed-link vocabulary, horizon)"
           },
           {
@@ -25772,10 +25951,10 @@ function boundedLines(body, maximum) {
   );
 }
 function decodeDocumentRead(id, body, route) {
-  const envelope2 = body;
-  const data = envelope2?.data;
+  const envelope3 = body;
+  const data = envelope3?.data;
   const document4 = data?.document;
-  if (envelope2?.operationId !== "documents.read.v1" || envelope2.ok !== true || typeof data !== "object" || data === null || !isContentVersion(data.version) || typeof document4 !== "object" || document4 === null || document4.id !== id || typeof document4.frontmatter !== "object" || document4.frontmatter === null || Array.isArray(document4.frontmatter) || typeof document4.body !== "string")
+  if (envelope3?.operationId !== "documents.read.v1" || envelope3.ok !== true || typeof data !== "object" || data === null || !isContentVersion(data.version) || typeof document4 !== "object" || document4 === null || document4.id !== id || typeof document4.frontmatter !== "object" || document4.frontmatter === null || Array.isArray(document4.frontmatter) || typeof document4.body !== "string")
     throw malformed("document read answered an envelope that is not documents.read.v1's result for this document", route);
   return { doc: { id, frontmatter: document4.frontmatter, body: document4.body }, version: data.version };
 }
@@ -25792,9 +25971,9 @@ function decodeDocumentHistory(request3, body, route) {
   const fail4 = (why) => {
     throw malformed(`history answered ${why}`, route);
   };
-  const envelope2 = body;
-  if (envelope2?.operationId !== HISTORY_OPERATION_ID || envelope2.ok !== true) fail4(`an envelope that is not ${HISTORY_OPERATION_ID}'s result`);
-  const data = envelope2.data;
+  const envelope3 = body;
+  if (envelope3?.operationId !== HISTORY_OPERATION_ID || envelope3.ok !== true) fail4(`an envelope that is not ${HISTORY_OPERATION_ID}'s result`);
+  const data = envelope3.data;
   if (typeof data !== "object" || data === null || Array.isArray(data)) fail4("without its data");
   if (data.documentId !== request3.documentId) fail4("for another document");
   if (!Array.isArray(data.versions) || data.versions.length > request3.limit) fail4("more versions than asked for, or none as a list");
@@ -25836,10 +26015,10 @@ function decodeDocumentHistory(request3, body, route) {
   return Object.freeze({ documentId: request3.documentId, versions: Object.freeze(versions), more: data.more, ...total === void 0 ? {} : { total } });
 }
 function operationRefusal(body, operationId, route) {
-  const envelope2 = body;
-  if (envelope2?.ok !== false) return void 0;
-  const error51 = envelope2.error;
-  if (envelope2.operationId !== operationId || typeof error51 !== "object" || error51 === null || typeof error51.code !== "string" || !REFUSAL_CODE.test(error51.code))
+  const envelope3 = body;
+  if (envelope3?.ok !== false) return void 0;
+  const error51 = envelope3.error;
+  if (envelope3.operationId !== operationId || typeof error51 !== "object" || error51 === null || typeof error51.code !== "string" || !REFUSAL_CODE.test(error51.code))
     throw malformed(`answered a refusal that is not ${operationId}'s`, route);
   return refusalOf(error51.code, error51.message, error51.retryable);
 }
@@ -30216,10 +30395,10 @@ function ffSwallowToError(reason, inv, boardPath) {
 function syncEnvelope(home2, counts = {}) {
   return { home: home2, sent: counts.sent ?? 0, received: counts.received ?? 0, conflicts: counts.conflicts ?? 0, held: counts.held ?? 0, next: counts.next ?? [] };
 }
-function withSyncEnvelope(receipt3, envelope2) {
+function withSyncEnvelope(receipt3, envelope3) {
   const out = { ...receipt3 };
   if (!("schema_version" in out)) out.schema_version = SYNC_RECEIPT_SCHEMA_VERSION;
-  for (const key2 of SYNC_ENVELOPE_KEYS) if (!(key2 in out)) out[key2] = envelope2[key2];
+  for (const key2 of SYNC_ENVELOPE_KEYS) if (!(key2 in out)) out[key2] = envelope3[key2];
   return out;
 }
 function syncVerbNotApplicable(flags, home2, why, help2) {
@@ -31141,8 +31320,8 @@ async function showIncoming(id, values, deps, route) {
   try {
     await run();
   } catch (err) {
-    const { envelope: envelope2 } = toExit(err);
-    stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3 } = toExit(err);
+    stderr(renderErrorEnvelope(envelope3));
     throw asHandled(err);
   }
 }
@@ -35607,8 +35786,8 @@ async function sync(argv2, deps = {}) {
   try {
     await run();
   } catch (err) {
-    const { envelope: envelope2, handled } = toExit(err);
-    if (!handled) stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3, handled } = toExit(err);
+    if (!handled) stderr(renderErrorEnvelope(envelope3));
     throw handled ? err : asHandled(err);
   }
 }
@@ -35958,8 +36137,8 @@ async function failGate(run, board, commitResult, delta, reason, details) {
   );
   partial2.code = "GATE_FAILED";
   partial2.help = help2;
-  const envelope2 = syncEnvelope("git", { received: delta.originDelta.length, next: [`${run.inv} sync`] });
-  run.stdout(render(withSyncEnvelope(partial2, envelope2), run.mode));
+  const envelope3 = syncEnvelope("git", { received: delta.originDelta.length, next: [`${run.inv} sync`] });
+  run.stdout(render(withSyncEnvelope(partial2, envelope3), run.mode));
   await writeAwarenessCache(board.key, board.boardPath, delta.changes, delta.reanchorNote);
   throw new CliError("GATE_FAILED", `the sync gate ${reason}; nothing was pushed`, {
     help: help2,
@@ -36003,8 +36182,8 @@ function reportHeld(run, board, delta, held2, where, notPulled) {
   receipt3.held_documents = held2.map((doc2) => ({ id: doc2.id, path: doc2.relPath, reason: doc2.reason, detail: doc2.detail }));
   const fix = `fix the lines between the --- markers of ${held2.map((doc2) => doc2.relPath).join(", ")} (quote any value that contains ': '), check with ${run.inv} status, then run ${run.inv} sync`;
   receipt3.held_help = `not published: the YAML frontmatter of these documents does not parse, and publishing it would break every reader of the board, so this sync sent nothing. Your files are untouched; ${fix}` + (where === "committed locally" ? " (the fix is committed on top and both go out together)" : "");
-  const envelope2 = syncEnvelope("git", { received: delta.originDelta.length, held: held2.length, next: [`${run.inv} sync`] });
-  run.stdout(render(withSyncEnvelope(receipt3, envelope2), run.mode));
+  const envelope3 = syncEnvelope("git", { received: delta.originDelta.length, held: held2.length, next: [`${run.inv} sync`] });
+  run.stdout(render(withSyncEnvelope(receipt3, envelope3), run.mode));
   throw new CliError(
     "CONFLICT",
     `${held2.length} document(s) have invalid frontmatter (${held2.map((doc2) => doc2.id).join(", ")}); nothing was published`,
@@ -47352,7 +47531,7 @@ function visitParents(tree, test, visitor, reverse) {
     }
     return visit2;
     function visit2() {
-      let result3 = empty;
+      let result3 = empty2;
       let subresult;
       let offset;
       let grandparents;
@@ -47391,16 +47570,16 @@ function toResult(value) {
   if (typeof value === "number") {
     return [CONTINUE, value];
   }
-  return value === null || value === void 0 ? empty : [value];
+  return value === null || value === void 0 ? empty2 : [value];
 }
-var empty, CONTINUE, EXIT2, SKIP;
+var empty2, CONTINUE, EXIT2, SKIP;
 var init_lib5 = __esm({
   "../../node_modules/unist-util-visit-parents/lib/index.js"() {
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
     init_unist_util_is();
     init_color_node();
-    empty = [];
+    empty2 = [];
     CONTINUE = true;
     EXIT2 = false;
     SKIP = "skip";
@@ -48375,11 +48554,11 @@ var require_react_production = __commonJS({
         _init: lazyInitializer
       };
     };
-    exports.memo = function(type, compare) {
+    exports.memo = function(type, compare2) {
       return {
         $$typeof: REACT_MEMO_TYPE,
         type,
-        compare: void 0 === compare ? null : compare
+        compare: void 0 === compare2 ? null : compare2
       };
     };
     exports.startTransition = function(scope) {
@@ -49307,18 +49486,18 @@ var require_react_development = __commonJS({
         lazyType2._debugInfo = [{ awaited: ioInfo }];
         return lazyType2;
       };
-      exports.memo = function(type, compare) {
+      exports.memo = function(type, compare2) {
         null == type && console.error(
           "memo: The first argument must be a component. Instead received: %s",
           null === type ? "null" : typeof type
         );
-        compare = {
+        compare2 = {
           $$typeof: REACT_MEMO_TYPE,
           type,
-          compare: void 0 === compare ? null : compare
+          compare: void 0 === compare2 ? null : compare2
         };
         var ownName;
-        Object.defineProperty(compare, "displayName", {
+        Object.defineProperty(compare2, "displayName", {
           enumerable: false,
           configurable: true,
           get: function() {
@@ -49329,7 +49508,7 @@ var require_react_development = __commonJS({
             type.name || type.displayName || (Object.defineProperty(type, "name", { value: name }), type.displayName = name);
           }
         });
-        return compare;
+        return compare2;
       };
       exports.startTransition = function(scope) {
         var prevTransition = ReactSharedInternals.T, currentTransition = {};
@@ -76362,8 +76541,8 @@ async function docRead(argv2, deps) {
   try {
     await docReadInner(argv2, deps);
   } catch (err) {
-    const { envelope: envelope2, handled } = toExit(err);
-    if (!handled) stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3, handled } = toExit(err);
+    if (!handled) stderr(renderErrorEnvelope(envelope3));
     throw handled ? err : asHandled(err);
   }
 }
@@ -76558,8 +76737,8 @@ async function docReadInner(argv2, deps) {
       }
       stdout(formatFieldValue(resolveField(parsed2, version4, field, id)));
     } catch (err) {
-      const { envelope: envelope2 } = toExit(err);
-      stderr(renderErrorEnvelope(envelope2));
+      const { envelope: envelope3 } = toExit(err);
+      stderr(renderErrorEnvelope(envelope3));
       throw asHandled(err);
     }
     return;
@@ -77164,7 +77343,7 @@ function fields(value, required2, optional2 = []) {
   requireValue(required2.every((key2) => Object.hasOwn(value, key2)));
   requireValue(Object.keys(value).every((key2) => required2.includes(key2) || optional2.includes(key2)));
 }
-function envelope(value, schema) {
+function envelope2(value, schema) {
   const data = record3(value);
   requireValue(typeof data.schemaVersion === "string");
   requireValue(data.schemaVersion === schema, "unsupported_version");
@@ -77182,7 +77361,7 @@ function nullableVersion(value) {
   return value === null ? null : version2(value);
 }
 function target2(value) {
-  const data = envelope(value, "superbee.document-target.v1");
+  const data = envelope2(value, "superbee.document-target.v1");
   fields(data, ["schemaVersion", "authority", "bundleKey", "documentId"]);
   const authority = record3(data.authority);
   let parsedAuthority;
@@ -77221,12 +77400,12 @@ function provenance(value) {
   return data.state === "local-pending" ? { state: "local-pending", ...common } : { state: "local-conflict", ...common, remote: nullableVersion(data.remote) };
 }
 function observation(value) {
-  const data = envelope(value, "superbee.document-observation.v1");
+  const data = envelope2(value, "superbee.document-observation.v1");
   fields(data, ["schemaVersion", "target", "provenance", "lifecycle"]);
   return { schemaVersion: "superbee.document-observation.v1", target: target2(data.target), provenance: provenance(data.provenance), lifecycle: lifecycle(data.lifecycle) };
 }
 function request2(value) {
-  const data = envelope(value, "superbee.present-document.v1");
+  const data = envelope2(value, "superbee.present-document.v1");
   fields(data, ["schemaVersion", "operation", "invocationId", "target"], ["referenceVersion", "expectedLifecycle"]);
   requireValue(data.operation === "present_document");
   const expectedLifecycle = Object.hasOwn(data, "expectedLifecycle") ? lifecycle(data.expectedLifecycle) : void 0;
@@ -77258,7 +77437,7 @@ function presentation(value) {
   }
 }
 function receipt(value, expected) {
-  const data = envelope(value, "superbee.present-document-receipt.v1");
+  const data = envelope2(value, "superbee.present-document-receipt.v1");
   requireValue(typeof data.ok === "boolean");
   fields(data, ["schemaVersion", "operation", "invocationId", "target", "ok", data.ok ? "presentation" : "error"]);
   requireValue(data.operation === "present_document");
@@ -83519,8 +83698,8 @@ async function pull2(argv2, deps = {}) {
   try {
     await runToTarget();
   } catch (err) {
-    const { envelope: envelope2 } = toExit(err);
-    stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3 } = toExit(err);
+    stderr(renderErrorEnvelope(envelope3));
     throw asHandled(err);
   }
 }
@@ -85425,6 +85604,9 @@ async function kinds(argv2, deps = {}) {
     () => parseArgs20({
       args: argv2,
       options: {
+        coverage: { type: "boolean" },
+        kind: { type: "string" },
+        now: { type: "string" },
         dir: { type: "string" },
         remote: { type: "string" },
         json: { type: "boolean" },
@@ -85438,6 +85620,13 @@ async function kinds(argv2, deps = {}) {
     stdout(renderUsage(KINDS_USAGE));
     return;
   }
+  if (!values.coverage && (values.kind !== void 0 || values.now !== void 0)) {
+    throw new CliError("USAGE", "--kind and --now require --coverage");
+  }
+  if (values.coverage && values.remote !== void 0) throw new CliError("USAGE", "Kind coverage reads local bundles only; omit --remote");
+  const nowText = values.now;
+  const nowMs = nowText === void 0 ? Date.now() : parseTimestamp(/^\d{4}-\d{2}-\d{2}$/.test(nowText) ? `${nowText}T00:00:00Z` : nowText, "0.2");
+  if (nowMs === null) throw new CliError("USAGE", "--now requires a valid ISO date or explicit-zone instant");
   const bundle = await openBundle(values.dir, await resolveRemoteFlag(values.remote, values.dir));
   const [registry2, okfVersion] = await Promise.all([
     loadKinds(bundle),
@@ -85446,7 +85635,20 @@ async function kinds(argv2, deps = {}) {
   const declared = [...registry2.kinds.values()];
   const ordered = declared.some((kind2) => kind2.order !== void 0) ? declared : declared.sort((a, b) => a.governs.localeCompare(b.governs));
   const rows = ordered.map((kind2) => toRow(kind2, okfVersion));
+  if (values.coverage && values.kind !== void 0 && !registry2.kinds.has(values.kind)) {
+    throw new CliError("USAGE", "--kind must name an exact declared Kind");
+  }
   const out = { count: rows.length, kinds: rows };
+  if (values.coverage) {
+    const skipped = [];
+    const documents = await query2(bundle, {}, { onSkip: ({ id }) => skipped.push(id) });
+    const measurements = kindCoverage(registry2, documents, { now: new Date(nowMs), okfVersion, kind: values.kind });
+    const byKind = new Map(measurements.kinds.map((row4) => [row4.governs, row4]));
+    const selected2 = rows.filter((row4) => byKind.has(String(row4.governs))).map((row4) => ({ ...row4, ...byKind.get(String(row4.governs)) }));
+    out.count = selected2.length;
+    out.kinds = selected2;
+    out.coverage = { now: measurements.now, documents: measurements.documents, complete: skipped.length === 0, skipped_documents: skipped.length, skipped_examples: skipped.sort().slice(0, 3), undeclared_kinds: measurements.undeclared_kinds };
+  }
   if (registry2.warnings.length > 0) out.warnings = registry2.warnings;
   if (rows.length === 0) {
     out.help = [`${cliInvocation()} new "<Kind>" <id> --<field> <value>  (once a kind is declared)`];
@@ -85459,6 +85661,7 @@ var init_kinds2 = __esm({
     "use strict";
     init_define_SUPERBEE_BUILD_IDENTITY();
     init_define_SUPERBEE_UPDATE_POLICY();
+    init_errors4();
     init_output2();
     init_src();
     init_bundle2();
@@ -85470,6 +85673,7 @@ var init_kinds2 = __esm({
 
 Usage:
   superbee kinds [--dir <path>] [--remote <url>]
+  superbee kinds --coverage [--kind <Kind>] [--now <ISO instant or date>] [--dir <path>] [--json]
 
 A kind convention is a plain OKF doc (type: Convention) under conventions/ declaring a document
 kind's purpose, required/optional fields and their descriptions, allowed enum values, typed-link vocabulary, expected body
@@ -85528,7 +85732,22 @@ A misshaped or misplaced key here is a non-fatal registry warning (visible in 'k
 output), never a silent no-op. See 'superbee doc read conventions/context-note' on any
 --init'd bundle for a full worked example with a values: enum and sections:.
 
+Coverage is local and read-only: group all readable concepts by actual type, using the same
+registry, logical field aliases and concept-link resolver. Filled excludes null, blank strings,
+empty lists/maps and case-insensitive unknown/n/a/na/none/tbd/null/-/? sentinels; it is a measurement,
+not required-field validation. Zero-record rates are null. Body prose excludes headings, standalone
+links and Related sections at any ATX heading level (including descendants until the next same
+or higher-level heading). This is line measurement, not Markdown rendering. Drift separates standard/envelope fields. Typed links use exact
+Kind-declared labels; other concept links are untyped citations, not undeclared relation violations.
+Freshness measures checked_on domain date metadata against the Kind's minute/hour/day horizon,
+not its meaningful-change clock. Missing/invalid dates and absent horizons remain explicit.
+Examples are capped at 3 per drift field; source domains at 15 with total/shown counts. A skipped
+malformed document makes coverage partial; no remote, sync or network access is performed.
+
 Options:
+  --coverage           Add per-Kind field, drift, link, freshness and source measurements
+  --kind <Kind>        Select one exact declared type (requires --coverage)
+  --now <ISO>          Fixed UTC date or explicit-zone instant for coverage (requires --coverage)
   --dir <path>          Bundle directory (default: discovered from the cwd)
   --remote <url>        Talk to a wire-protocol server instead of a local bundle
                          (mutually exclusive with --dir; remote access is always explicit)
@@ -92145,12 +92364,12 @@ function cleanRegex(source) {
   return source.slice(start, end);
 }
 function floatSafeRemainder2(val, step) {
-  const ratio = val / step;
-  const roundedRatio = Math.round(ratio);
-  const tolerance = Number.EPSILON * Math.max(Math.abs(ratio), 1);
-  if (Math.abs(ratio - roundedRatio) < tolerance)
+  const ratio2 = val / step;
+  const roundedRatio = Math.round(ratio2);
+  const tolerance = Number.EPSILON * Math.max(Math.abs(ratio2), 1);
+  if (Math.abs(ratio2 - roundedRatio) < tolerance)
     return 0;
-  return ratio - roundedRatio;
+  return ratio2 - roundedRatio;
 }
 function defineLazy(object5, key2, getter) {
   let value = void 0;
@@ -119053,8 +119272,8 @@ var require_formats = __commonJS({
     init_define_SUPERBEE_UPDATE_POLICY();
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.formatNames = exports.fastFormats = exports.fullFormats = void 0;
-    function fmtDef(validate, compare) {
-      return { validate, compare };
+    function fmtDef(validate, compare2) {
+      return { validate, compare: compare2 };
     }
     exports.fullFormats = {
       // date: http://tools.ietf.org/html/rfc3339#section-5.6
@@ -125440,8 +125659,8 @@ async function mcp(argv2, deps = {}) {
   try {
     await mcpInner(argv2, deps);
   } catch (error51) {
-    const { envelope: envelope2, handled } = toExit(error51);
-    if (!handled) stderr(renderErrorEnvelope(envelope2));
+    const { envelope: envelope3, handled } = toExit(error51);
+    if (!handled) stderr(renderErrorEnvelope(envelope3));
     throw handled ? error51 : asHandled(error51);
   }
 }
@@ -128894,8 +129113,8 @@ async function postRoute(context, route, body, writeRequest) {
     }
     throw hostedFailure(error52, target3, resume2);
   }
-  const envelope2 = answer2.body ?? {};
-  const error51 = envelope2.error;
+  const envelope3 = answer2.body ?? {};
+  const error51 = envelope3.error;
   const code3 = typeof error51 === "string" ? error51 : typeof error51?.code === "string" ? error51.code : null;
   const message = typeof error51?.message === "string" ? error51.message : "";
   if (answer2.status === 503 && code3 === "write_outcome_unknown") throw unknown3();
@@ -128905,10 +129124,10 @@ async function postRoute(context, route, body, writeRequest) {
       help: "a later release of the host offers it; until then do this in the Superbee app"
     });
   }
-  if (answer2.status === 200 && envelope2.ok === true && typeof envelope2.data === "object" && envelope2.data !== null && !Array.isArray(envelope2.data)) {
-    return { ok: true, data: envelope2.data };
+  if (answer2.status === 200 && envelope3.ok === true && typeof envelope3.data === "object" && envelope3.data !== null && !Array.isArray(envelope3.data)) {
+    return { ok: true, data: envelope3.data };
   }
-  if (answer2.status === 200 && envelope2.ok === false && code3 !== null) return { ok: false, code: code3, message };
+  if (answer2.status === 200 && envelope3.ok === false && code3 !== null) return { ok: false, code: code3, message };
   throw hostedFailure(new RemoteError(`hosted ${route} answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), target3, resume2);
 }
 function accessRefusal(code3, hostMessage, subject) {
@@ -129280,8 +129499,8 @@ async function catalog(argv2, deps = {}) {
     try {
       await catalogInner(argv2, deps);
     } catch (err) {
-      const { envelope: envelope2, handled } = toExit(err);
-      if (!handled) stderr(renderErrorEnvelope(envelope2));
+      const { envelope: envelope3, handled } = toExit(err);
+      if (!handled) stderr(renderErrorEnvelope(envelope3));
       throw handled ? err : asHandled(err);
     }
     return;
@@ -134510,7 +134729,7 @@ function packParts(content3, versions) {
   const parts = [];
   let part = null;
   let size = 0;
-  const envelope2 = 512;
+  const envelope3 = 512;
   for (const version4 of new Set(versions)) {
     const object5 = content3.objects.get(version4);
     if (!object5) continue;
@@ -134518,7 +134737,7 @@ function packParts(content3, versions) {
     if (part === null || part.versions.length >= bounds.partObjects || size + bytes > bounds.partTargetBytes) {
       part = { documents: [], reserved: [], history: [], versions: [] };
       parts.push(part);
-      size = envelope2;
+      size = envelope3;
     }
     if (object5.kind === "documents") part.documents.push(object5.value);
     else if (object5.kind === "reserved") part.reserved.push(object5.value);
@@ -134642,19 +134861,19 @@ async function runStagedCreate(request3) {
     }
   }
   function read(name, answer2) {
-    const envelope2 = answer2.body ?? {};
-    const code3 = typeof envelope2.error?.code === "string" ? envelope2.error.code : null;
-    const message = typeof envelope2.error?.message === "string" ? envelope2.error.message : "";
-    if (answer2.status === 200 && envelope2.ok === true && typeof envelope2.data === "object" && envelope2.data !== null) return envelope2.data;
-    if (answer2.status === 200 && envelope2.ok === false && code3 === "staged_manifest_missing") return "no_manifest";
-    if (answer2.status === 200 && envelope2.ok === false && code3 === "request_conflict" && envelope2.error?.retryable === true) return "busy";
-    if (answer2.status === 200 && envelope2.ok === false && code3 === "validation_failed" && VERSION_MISMATCH.test(message)) {
+    const envelope3 = answer2.body ?? {};
+    const code3 = typeof envelope3.error?.code === "string" ? envelope3.error.code : null;
+    const message = typeof envelope3.error?.message === "string" ? envelope3.error.message : "";
+    if (answer2.status === 200 && envelope3.ok === true && typeof envelope3.data === "object" && envelope3.data !== null) return envelope3.data;
+    if (answer2.status === 200 && envelope3.ok === false && code3 === "staged_manifest_missing") return "no_manifest";
+    if (answer2.status === 200 && envelope3.ok === false && code3 === "request_conflict" && envelope3.error?.retryable === true) return "busy";
+    if (answer2.status === 200 && envelope3.ok === false && code3 === "validation_failed" && VERSION_MISMATCH.test(message)) {
       throw new CliError("RUNTIME", `${client.target.origin} stores an object differently from this CLI (client/host contract mismatch)`, {
         details: { reason: "staged_mismatch", route: name, host_message: message, host: client.target.origin, request_id: requestId2, retryable: false },
         help: `upgrade Superbee (npm install -g superbee), then re-run the same command, which resumes this creation: ${request3.resume}`
       });
     }
-    if (answer2.status === 200 && envelope2.ok === false && code3 !== null) throw new StagedRefusal(code3, message, reserved, name);
+    if (answer2.status === 200 && envelope3.ok === false && code3 !== null) throw new StagedRefusal(code3, message, reserved, name);
     if (answer2.status === 429 && code3 === "bundle_create_limit") throw new StagedRefusal(code3, message, reserved, name);
     if (answer2.status === 400 && !reserved) throw new StagedRefusal(code3 ?? "invalid_input", message || `the host refused ${name} as malformed`, false, name);
     throw hostedFailure(new RemoteError(`hosted ${name} answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), client.target, request3.resume);
@@ -135049,9 +135268,9 @@ async function sendCreation(plan, context) {
     }
     throw hostedFailure(error51, target3, yesCommand);
   }
-  const envelope2 = answer2.body ?? {};
-  const code3 = typeof envelope2.error?.code === "string" ? envelope2.error.code : null;
-  const hostMessage = typeof envelope2.error?.message === "string" ? envelope2.error.message : "";
+  const envelope3 = answer2.body ?? {};
+  const code3 = typeof envelope3.error?.code === "string" ? envelope3.error.code : null;
+  const hostMessage = typeof envelope3.error?.message === "string" ? envelope3.error.message : "";
   if (answer2.status === 503 && code3 === "write_outcome_unknown") {
     throw new CliError("TRANSIENT", `${target3.origin} may have partly created '${bundleId}'`, {
       details: { reason: "write_outcome_unknown", bundle_id: bundleId, workspace, host: target3.origin, request_id: requestId2, retryable: true },
@@ -135063,16 +135282,16 @@ async function sendCreation(plan, context) {
     if (forgettable) await clearPendingCreate(home2, canonical2, bundleId);
     throw createRefusal(code3, hostMessage, refusalContext);
   }
-  if (answer2.status === 200 && envelope2.ok === false && code3 !== null) {
+  if (answer2.status === 200 && envelope3.ok === false && code3 !== null) {
     if (code3 !== "request_conflict" && forgettable) await clearPendingCreate(home2, canonical2, bundleId);
     throw createRefusal(code3, hostMessage, refusalContext);
   }
-  if (answer2.status !== 200 || envelope2.ok !== true || typeof envelope2.data !== "object" || envelope2.data === null) {
+  if (answer2.status !== 200 || envelope3.ok !== true || typeof envelope3.data !== "object" || envelope3.data === null) {
     if (answer2.status === 400 && forgettable) await clearPendingCreate(home2, canonical2, bundleId);
     throw hostedFailure(new RemoteError(`hosted bundle-create answered ${answer2.status}`, code3 ?? "RUNTIME", answer2.status), target3, yesCommand);
   }
   await clearPendingCreate(home2, canonical2, bundleId);
-  return envelope2.data;
+  return envelope3.data;
 }
 async function publish(argv2, partial2 = {}) {
   const deps = publishDeps(partial2);
@@ -135800,7 +136019,7 @@ async function main(argv2) {
       await main(hoisted);
       return;
     }
-    const envelope2 = toEnvelope(
+    const envelope3 = toEnvelope(
       new CliError(
         "USAGE",
         `options must follow the command (e.g. '${cliInvocation()} ${commandWords(command)} \u2026').`,
@@ -135809,7 +136028,7 @@ async function main(argv2) {
         }
       )
     );
-    process.stdout.write(renderErrorEnvelope(envelope2));
+    process.stdout.write(renderErrorEnvelope(envelope3));
     process.exitCode = 2;
     return;
   }
@@ -135829,8 +136048,8 @@ async function main(argv2) {
     },
     renderUnknownCommand: (cmd) => renderErrorEnvelope(toEnvelope(unknownCommandError(cmd))),
     formatError: (err) => {
-      const { exitCode, envelope: envelope2, handled } = toExit(err);
-      return { output: handled ? "" : renderErrorEnvelope(envelope2), exitCode };
+      const { exitCode, envelope: envelope3, handled } = toExit(err);
+      return { output: handled ? "" : renderErrorEnvelope(envelope3), exitCode };
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbee",
-  "version": "0.4.2",
+  "version": "0.4.3-pre.1",
   "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": [
@@ -90,6 +90,6 @@
     "darwin",
     "linux"
   ],
-  "readme": "# superbee\n\nShared, versioned, conflict-safe knowledge for AI coding agents, stored as plain markdown in\nyour repo.\n\nSuperbee is pre-1.0. Commands and formats may change between releases.\n\n## What is Superbee?\n\nAgents forget everything between sessions, overwrite each other's work, and keep what they know\ninvisible to the humans they work for. Superbee fixes all three with a **knowledge bundle**: a\nfolder of markdown documents, by convention `.superbee/` at your project root, that agents read\nand write through a small command-line tool.\n\n- **Context that persists.** Agents write context notes, decisions, plans, and research into the\n  bundle. The next session, or a different agent, picks up where the last one left off. An\n  optional `SessionStart` hook for Claude Code, Codex, and OpenCode orients every new session\n  automatically.\n- **Safe for many writers.** Each write can carry the actor that made it. A writer can name the\n  version it last read; if anyone changed the document since, the write fails with a typed\n  conflict error instead of silently overwriting their work.\n- **Visible to humans.** The bundle is plain markdown. Open it in any editor, render it on\n  GitHub, diff it in git. `superbee ui` serves it locally as cross-linked pages with backlinks and\n  a live activity feed. No bundle content leaves your machine until you run `superbee sync`, which\n  shares the bundle with teammates through the board: a copy of the bundle kept on its own git\n  branch, separate from your code.\n- **Views on demand.** Ask your agent for a dashboard, a timeline, a filtered task queue, or a\n  reading view of one dense document. It builds a self-contained HTML page, stores it in the bundle\n  as a View, and `superbee ui` hosts it in a sandboxed frame. A View reads the bundle live and can\n  change it only through a write you confirm. Views are bundle content, so they travel with `sync`.\n- **Built for agents.** Output is structured and token-lean, and errors carry a small, stable set\n  of exit codes. Agents act on responses without parsing prose or flooding their context window.\n- **Yours, and portable.** Bundles follow the Open Knowledge Format (OKF), a convention of\n  markdown with frontmatter, so they outlive the tool: hand the folder to someone else, or read it\n  with anything that speaks markdown. New bundles are written as OKF v0.2, and existing v0.1\n  bundles keep working as they are. Reading and writing the bundle works offline; only sharing\n  needs a network. The document schemas, called kinds, live inside the bundle, so it describes\n  its own structure.\n\nBees build comb one cell at a time. The comb holds what the colony gathers, and its shape shows\nthe next bee where to build and what belongs where. Superbee works the same way: people and\nagents record what they learn in a structure that fits their domain, and that structure guides\nwhoever works next. Each session builds on the last instead of starting over.\n\nThe npm package is one self-contained executable with zero runtime dependencies, plus an Agent\nSkill, an instruction file your agent loads, that teaches it how to use the tool.\n\n## Install\n\nRequires a supported Node.js 22, 24, or 26 release (22.14.0 minimum) on macOS or Linux. Native Windows is not supported by this package.\n\n```sh\nnpm install -g superbee\n```\n\nStable releases publish on npm's `latest` tag and prereleases on `next`.\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 a supported Node.js 22, 24, or 26 release (22.14.0 minimum) on macOS or Linux. Native Windows is not supported by this package.\n\n```sh\nnpm install -g superbee\n```\n\nStable releases publish on npm's `latest` tag and prereleases on `next`. To try the prerelease:\n\n```sh\nnpm install -g superbee@next\n```\n\nWindows adapters and the `superbee-windows` executable live in a separate repository and are\nnot included in `superbee`. Most Windows users should run Superbee in WSL2, where npm sees a\nLinux platform and the normal installation applies. An experimental, unsupported native Windows\nbuild is available as open source, with build-from-source instructions: https://github.com/Holaxis-ai/superbee-windows-cli\n\n### Upgrading an existing Windows installation\n\nThe first release containing the Windows extraction removes native Windows support from this\npackage. Its npm `os` metadata permits only `darwin` and `linux`, so a Windows upgrade to an affected\nversion is rejected with `EBADPLATFORM`. This applies to existing prerelease users too. Forcing the\ninstallation does not restore support: the executable refuses commands on unsupported hosts\nbefore running them (the bare `--version` flag can still identify the installed build).\n\nThere is no supported Windows replacement on npm. The alternatives are WSL2 or the experimental\nbuild from source at https://github.com/Holaxis-ai/superbee-windows-cli; neither carries a\nfirst-party support promise for native Windows. An older installed version is not converted or\nremoved by this source change, and existing bundle files are not migrated by it. Review the affected release's notes before changing an existing\nWindows installation. macOS/Linux users can continue using the normal installation and setup flow.\n\nRun `superbee version --check` to compare your install with the current stable release.\n\n## First run: let your agent finish setup\n\n`npm install` gives you the CLI. The integrations (the Agent Skill, the `SessionStart` hook, and\nMCP server registration, where MCP is the Model Context Protocol) are installed by your agent,\nnot by hand. Ask it:\n\n> Run `superbee setup` and follow its instructions.\n\nSetup itself changes nothing. It inspects your configuration and returns one safe next command at\na time, and the agent runs each with your approval. Setup knows Claude Code, Codex, and OpenCode,\nplus Claude Desktop for the MCP registration only.\n\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"
 }