@rafinery/cli 0.7.0 → 0.8.0

package/lib/gate/okf-emit.mjs

@@ -0,0 +1,323 @@
+// The OKF surface emitter — makes the brain repo a conformant Open Knowledge
+// Format v0.1 bundle (contract §11). Runs inside `rafa push` BEFORE compile, so
+// everything it writes goes back through the gate like any authored file.
+//
+// The format machinery lives in @rafinery/okf (parser · concept primitives ·
+// links · citations · indexes · validator · generator); this module is the thin
+// orchestrator that applies the rafa PROFILE to a bundle:
+//
+//   stamp   · missing `type`/`title`/`description`/`timestamp`/`tags` where
+//             DERIVABLE from authored data or git history — authored values are
+//             never rewritten; a value we cannot derive is OMITTED, never guessed.
+//   render  · a generated `# Citations` body section from the `cites:` DSL
+//             (sha-pinned GitHub URLs when the repo is known), inside markers so
+//             re-emits replace their own section and never touch prose.
+//   links   · `[[wikilink]]` → `[Title](/brain/rules/<id>.md)` bundle-relative
+//             markdown links, ONLY when the id resolves (a dangling wikilink is
+//             not-yet-written knowledge — left for the checker's WARN lane).
+//   index   · an `index.md` at the bundle root and in every concept directory
+//             (OKF §6) so a foreign agent reaches any concept from the root in
+//             ≤ 2 hops with no rafa tooling. Root index frontmatter carries
+//             `okf_version: "0.1"` + provenance (repo · codeSha) — the only
+//             index frontmatter OKF permits.
+//
+// Never touched: log.md (OKF-reserved trail), active.md (one-line pointer
+// protocol — documented exception, surfaced by `rafa okf check`), citation-
+// check.* (the checker's artifact), contract.md (push stamps it), plans/**
+// (work objects — the plans channel).
+//
+// CLI:  rafa okf [--root=.rafa] [--repo=owner/repo] [--codeSha=<sha>]
+
+import {
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  existsSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import {
+  parseFrontmatter,
+  OKF_VERSION,
+  OKF_RESERVED,
+  splitConcept,
+  joinConcept,
+  missingStamps,
+  transpileWikilinks,
+  parseCites,
+  citationsSection,
+  upsertCitations,
+  indexBullet,
+  renderIndex,
+  renderRootIndex,
+  FILE_CLASSES,
+  derivedStamps,
+} from "@rafinery/okf";
+
+export function runOkfEmit(argv = []) {
+  const arg = (k, d) => {
+    const m = argv.find((a) => a.startsWith(`--${k}=`));
+    return m ? m.slice(k.length + 3) : d;
+  };
+  const ROOT = arg("root", ".rafa");
+  const gitOpts = (cwd) => ({
+    encoding: "utf8",
+    cwd,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const codeGit = (cmd, d = "") => {
+    try {
+      return execSync(cmd, gitOpts(process.cwd())).trim();
+    } catch {
+      return d;
+    }
+  };
+  const repo =
+    arg("repo", "") ||
+    (() => {
+      const origin = codeGit("git remote get-url origin");
+      const m = origin.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+      return m ? `${m[1]}/${m[2]}` : "";
+    })();
+  const codeSha = arg("codeSha", "") || codeGit("git rev-parse HEAD");
+  const now = new Date().toISOString();
+
+  // Last meaningful change of a bundle file — real signals only (contract §11):
+  // dirty/untracked in the brain repo → it is changing in THIS emit → now;
+  // clean → its last commit time; no git at all → now (the file is being
+  // materialized into a fresh bundle). Never a placeholder.
+  function fileTimestamp(relPath) {
+    try {
+      const dirty = execSync(
+        `git status --porcelain -- ${JSON.stringify(relPath)}`,
+        gitOpts(ROOT),
+      ).trim();
+      if (dirty) return now;
+      const t = execSync(
+        `git log -1 --format=%cI -- ${JSON.stringify(relPath)}`,
+        gitOpts(ROOT),
+      ).trim();
+      return t || now;
+    } catch {
+      return now;
+    }
+  }
+
+  function walk(dir) {
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .sort()
+      .flatMap((e) => {
+        const p = join(dir, e);
+        return statSync(p).isDirectory()
+          ? walk(p)
+          : e.endsWith(".md") &&
+              !e.startsWith("_") &&
+              !e.endsWith(".theirs.md") && // pending human decision — compile gates it
+              !OKF_RESERVED.has(e)
+            ? [p]
+            : [];
+      });
+  }
+  const rel = (p) => p.slice(ROOT.length + 1);
+  const read = (p) => readFileSync(p, "utf8");
+
+  // ── collect the bundle's concept files (per the rafa profile registry) ────
+  const concepts = [];
+  const collect = (paths, kind) => {
+    for (const path of paths) {
+      const raw = read(path);
+      const split = splitConcept(raw);
+      const parsed = split ? parseFrontmatter(raw) : { error: "no frontmatter" };
+      if (!split || parsed.error) {
+        console.log(`  ! ${rel(path)} — ${parsed.error} (skipped; compile will fail it)`);
+        continue;
+      }
+      concepts.push({ path, kind, raw, ...split, data: parsed.data });
+    }
+  };
+  for (const [kind, cls] of Object.entries(FILE_CLASSES)) {
+    if (cls.singleton) {
+      const p = join(ROOT, cls.path);
+      if (existsSync(p)) collect([p], kind);
+    } else {
+      collect(walk(join(ROOT, cls.dir)), kind);
+    }
+  }
+
+  // id → { title, bundlePath } for wikilink transpilation.
+  const resolve = new Map();
+  for (const c of concepts) {
+    if (!c.data.id) continue;
+    resolve.set(String(c.data.id), {
+      title: c.data.title ?? c.data.id,
+      bundlePath: "/" + rel(c.path),
+    });
+  }
+
+  // ── stamp + transform every concept ───────────────────────────────────────
+  let stamped = 0;
+  let transpiled = 0;
+  let citesSections = 0;
+  for (const c of concepts) {
+    const derived = derivedStamps(c.kind, c.data);
+    // timestamp: authored created/found verbatim → brain-repo git history → now.
+    if (!("timestamp" in c.data))
+      derived.timestamp = c.data.created ?? c.data.found ?? fileTimestamp(rel(c.path));
+    const stamps = missingStamps(c.data, derived);
+    let body = c.body;
+    const before = body;
+    body = transpileWikilinks(body, resolve);
+    if (body !== before) transpiled++;
+    const cites = parseCites(c.data.cites);
+    if (cites.length) {
+      body = upsertCitations(body, citationsSection(cites, { repo, sha: codeSha }));
+      citesSections++;
+    }
+    const next = joinConcept(c.fmLines, stamps, body);
+    if (next !== c.raw) {
+      writeFileSync(c.path, next);
+      if (stamps.length) stamped++;
+    }
+  }
+
+  // ── the index.md tree (OKF §6 progressive disclosure) ─────────────────────
+  const byKind = (k) => concepts.filter((c) => c.kind === k);
+  const meta = (c) => {
+    // post-stamp values: authored wins, then what emit just derived
+    const { data } = parseFrontmatter(read(c.path));
+    return {
+      title: data.title ?? data.id ?? rel(c.path),
+      description: data.description ?? data.summary ?? "",
+      name: c.path.split("/").pop(),
+    };
+  };
+  const bullets = (list) =>
+    list.map(meta).map((m) => indexBullet(m.title, m.name, m.description));
+
+  const indexes = [];
+  const writeIndex = (relPath, content) => {
+    writeFileSync(join(ROOT, relPath), content);
+    indexes.push(relPath);
+  };
+
+  for (const [kind, cls] of Object.entries(FILE_CLASSES)) {
+    if (cls.singleton || !cls.indexTitle) continue;
+    const list = byKind(kind);
+    if (!list.length) continue;
+    writeIndex(
+      join(cls.dir, "index.md"),
+      renderIndex([{ heading: cls.indexTitle, bullets: bullets(list) }]),
+    );
+  }
+
+  // Plans index — one section per epic, items listed beneath it (work items
+  // nest in subdirectories, so URLs are relative to plans/).
+  const planItems = byKind("plan");
+  if (planItems.length) {
+    const planUrl = (c) => rel(c.path).replace(/^plans\//, "");
+    writeIndex(
+      "plans/index.md",
+      renderIndex(
+        planItems
+          .filter((c) => c.data.kind === "epic")
+          .map((epic) => ({
+            heading: `${epic.data.title ?? epic.data.id} (${epic.data.id})`,
+            bullets: planItems
+              .filter((c) => c.data.plan === epic.data.id)
+              .map((c) => {
+                const m = meta(c);
+                return indexBullet(m.title, planUrl(c), m.description);
+              }),
+          })),
+      ),
+    );
+  }
+
+  const singleton = (kind, url) => {
+    const c = byKind(kind)[0];
+    return c ? indexBullet(meta(c).title, url, meta(c).description) : null;
+  };
+  if (existsSync(join(ROOT, "brain"))) {
+    const rules = byKind("rule");
+    const playbooks = byKind("playbook");
+    writeIndex(
+      "brain/index.md",
+      renderIndex([
+        {
+          heading: "Knowledge",
+          bullets: [
+            rules.length &&
+              indexBullet("Rules", "rules/", `${rules.length} cited invariants/contracts`),
+            playbooks.length &&
+              indexBullet("Playbooks", "playbooks/", `${playbooks.length} cited how-to/flow notes`),
+          ],
+        },
+        {
+          heading: "Reports",
+          bullets: [
+            singleton("coverage", "coverage.md"),
+            singleton("health", "checklist.md"),
+            existsSync(join(ROOT, "brain", "citation-check.md")) &&
+              indexBullet("Citation check", "citation-check.md", "generated gate report — every cite re-verified"),
+            existsSync(join(ROOT, "brain", "log.md")) &&
+              indexBullet("Scan log", "log.md", "chronological trail of scans and validations"),
+          ],
+        },
+      ]),
+    );
+  }
+  if (existsSync(join(ROOT, "improve"))) {
+    const improvements = byKind("improvement");
+    writeIndex(
+      "improve/index.md",
+      renderIndex([
+        {
+          heading: "Continuous improvement",
+          bullets: [
+            improvements.length &&
+              indexBullet("Improvements", "improvements/", `${improvements.length} items, leverage-ranked`),
+            singleton("ledger", "ledger.md"),
+          ],
+        },
+      ]),
+    );
+  }
+
+  // Root index — the bundle's front door (frontmatter: okf_version + provenance).
+  writeIndex(
+    "index.md",
+    renderRootIndex({
+      title: `${repo || "rafa brain"} — verified knowledge bundle`,
+      intro: [
+        `A rafa brain: every concept is cited into the code${codeSha ? ` at \`${codeSha.slice(0, 12)}\`` : ""} and`,
+        "mechanically re-verified on every push (cite resolution · anchor completeness ·",
+        `absence re-grep · coverage inventory). Conformant Open Knowledge Format v${OKF_VERSION} —`,
+        "any OKF consumer can read it; the verification layer is rafa's.",
+      ],
+      provenance: { ...(repo ? { repo } : {}), ...(codeSha ? { codeSha } : {}) },
+      sections: [
+        {
+          heading: "Contents",
+          bullets: [
+            existsSync(join(ROOT, "brain")) &&
+              indexBullet("Brain", "brain/", "the knowledge map — cited rules + playbooks, coverage, health"),
+            existsSync(join(ROOT, "improve")) &&
+              indexBullet("Improve", "improve/", "bloom's prioritized improvement ledger (P0–P3)"),
+            planItems.length > 0 &&
+              indexBullet("Plans", "plans/", "work-item trees (epic → task → subtask), per-epic index"),
+            existsSync(join(ROOT, "contract.md")) &&
+              indexBullet("Contract", "contract.md", "the file protocol this bundle conforms to (stamped copy)"),
+          ],
+        },
+      ],
+    }),
+  );
+
+  console.log(
+    `✓ rafa okf: ${concepts.length} concepts · ${stamped} stamped · ${transpiled} bodies transpiled · ` +
+      `${citesSections} citations sections · ${indexes.length} indexes → ${ROOT} (OKF v${OKF_VERSION} bundle)`,
+  );
+  return 0;
+}

package/lib/gate/verify-citations.mjs

@@ -38,6 +38,11 @@ import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdtemp
 import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+// Format utilities only (splitConcept/extractLinks/unresolvedLinks) — the five
+// GATES above stay independently implemented; the LINKS lane below is a
+// non-failing warn lane, so sharing the format package does not couple a gate
+// to the producer it checks.
+import { splitConcept, extractLinks, unresolvedLinks, OKF_RESERVED } from "@rafinery/okf";
 
 export const CHECKER_VERSION = 2; // v1 = the 3-gate era (resolution/completeness/policy)
 
@@ -60,7 +65,26 @@ function walk(dir) {
   if (!existsSync(dir)) return [];
   return readdirSync(dir).flatMap((e) => {
     const p = join(dir, e);
-    return statSync(p).isDirectory() ? walk(p) : (e.endsWith(".md") && !e.startsWith("_")) ? [p] : []; // ignore _*.md scratch
+    if (statSync(p).isDirectory()) return walk(p);
+    // ignore _*.md scratch + OKF-reserved listings (index.md is generated, never
+    // a note) + *.theirs.md conflict copies (compile gates those with a typed error)
+    return e.endsWith(".md") &&
+      !e.startsWith("_") &&
+      !e.endsWith(".theirs.md") &&
+      !OKF_RESERVED.has(e)
+      ? [p]
+      : [];
+  });
+}
+
+// Every .md in the bundle (reserved included — they are legitimate mdlink
+// targets), as "/bundle-relative" paths for the LINKS lane's resolution set.
+function walkBundleMd(dir, base = dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((e) => {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) return e === ".git" ? [] : walkBundleMd(p, base);
+    return e.endsWith(".md") ? ["/" + p.slice(base.length + 1)] : [];
   });
 }
 
@@ -178,12 +202,24 @@ export function runVerifyCitations(argv = []) {
     return 0;
   }
 
+  // LINKS lane resolution sets — BUNDLE-wide (a note may link across dirs):
+  // ids = concept stems of every knowledge class; paths = every bundle .md as
+  // "/bundle-relative" (reserved files included — legitimate mdlink targets).
+  const BUNDLE_ROOT = join(ROOT, "..");
+  const bundleIds = new Set(
+    ["brain/rules", "brain/playbooks", "improve/improvements"]
+      .flatMap((d) => walk(join(BUNDLE_ROOT, d)))
+      .map((p) => p.split("/").pop().replace(/\.md$/, "")),
+  );
+  const bundlePaths = new Set(walkBundleMd(BUNDLE_ROOT));
+
   const resolution = []; // { note, loc, token, ok, reason }
   const completeness = []; // { note, anchor, site, ok, reason }
   const policy = []; // { note, ok, reason }
   const absence = []; // { note, token, site, ok, reason }
   const inventory = []; // { name, glob, declared, found, ok, reason, paths }
   const warns = []; // { note, phrase }  — heuristic, never fails the gate
+  const linkWarns = []; // { note, kind, target } — dangling links (OKF §5.3), never fails the gate
 
   for (const note of notes) {
     const rel = note.replace(ROOT + "/", "");
@@ -256,6 +292,40 @@ export function runVerifyCitations(argv = []) {
       const m = (title + " · " + summary).match(ABSENCE_HEURISTIC);
       if (m) warns.push({ note: rel, phrase: m[0] });
     }
+
+    // LINKS lane (non-failing, OKF §5.3): every frontmatter `links:` id, body
+    // [[wikilink]], and body bundle-relative markdown link should resolve to a
+    // bundle concept/file. A dangling link may be not-yet-written knowledge —
+    // prism's worklist, never a gate failure.
+    {
+      const raw = lines.join("\n");
+      const split = splitConcept(raw);
+      const body = split ? split.body : raw;
+      const fmLinks = [];
+      let inLinks = false;
+      for (const l of split?.fmLines ?? []) {
+        const flow = l.match(/^links:\s*\[(.*)\]\s*$/);
+        if (flow) {
+          for (const item of flow[1].split(",")) {
+            const v = strip(item);
+            if (v) fmLinks.push(v);
+          }
+          inLinks = false;
+          continue;
+        }
+        if (/^links:\s*$/.test(l)) { inLinks = true; continue; }
+        if (inLinks) {
+          const item = l.match(/^\s*-\s+(.+?)\s*$/);
+          if (item) { fmLinks.push(strip(item[1])); continue; }
+          if (/^\S/.test(l)) inLinks = false;
+        }
+      }
+      const dangling = unresolvedLinks(extractLinks({ links: fmLinks }, body), {
+        ids: bundleIds,
+        paths: bundlePaths,
+      });
+      for (const d of dangling) linkWarns.push({ note: rel, kind: d.kind, target: d.target });
+    }
   }
 
   // INVENTORY — coverage.md declared counts vs tracked reality
@@ -309,10 +379,24 @@ export function runVerifyCitations(argv = []) {
     `## Warns (heuristic, non-failing — existence-shaped title/summary with no \`absent:\` declared): ${warns.length}`,
     ...warns.map((w) => `⚠ ${w.note} — reads as an absence claim ("${w.phrase}") — declare \`absent: <token>\` so the gate can re-grep it, or reword`),
     "",
+    `## Links (non-failing, OKF §5.3 — dangling cross-links, bundle-wide resolution): ${linkWarns.length}`,
+    ...linkWarns.map((w) => `⚠ ${w.note} — ${w.kind} → ${w.target} does not resolve in the bundle (not-yet-written knowledge, a typo, or a moved file)`),
+    "",
     fail ? `**${fail} FAILED.**` : "**All pass.**",
     "",
   ].join("\n");
-  writeFileSync(join(ROOT, "citation-check.md"), md);
+  // The report is itself a generated concept (contract §11): it self-describes.
+  const at = new Date().toISOString();
+  const reportFm = [
+    "---",
+    'type: "Citation Check"',
+    'title: "Citation check report"',
+    `description: "checker v${CHECKER_VERSION} — ${fail ? `${fail} failed` : "all gates pass"} · ${warns.length + linkWarns.length} warn(s)"`,
+    `timestamp: ${at}`,
+    "---",
+    "",
+  ].join("\n");
+  writeFileSync(join(ROOT, "citation-check.md"), reportFm + md);
 
   // Machine record of THIS run — compile folds it into manifest.citations so the
   // platform knows the gate level a brain passed. Recorded, never assumed.
@@ -321,7 +405,7 @@ export function runVerifyCitations(argv = []) {
     JSON.stringify(
       {
         checkerVersion: CHECKER_VERSION,
-        at: new Date().toISOString(),
+        at,
         pass: fail === 0,
         gates: {
           resolution: { pass: resolution.length - rFail.length, total: resolution.length },
@@ -331,6 +415,7 @@ export function runVerifyCitations(argv = []) {
           inventory: { pass: inventory.length - iFail.length, total: inventory.length },
         },
         warns: warns.length,
+        linkWarns: linkWarns.length, // additive optional — compile only reads { checkerVersion, pass, at }
       },
       null,
       2,
@@ -341,6 +426,7 @@ export function runVerifyCitations(argv = []) {
   console.log(
     `resolution ${resolution.length - rFail.length}/${resolution.length} · completeness ${completeness.length - cFail.length}/${completeness.length} · policy ${policy.length - pFail.length}/${policy.length} · absence ${absence.length - aFail.length}/${absence.length} · inventory ${inventory.length - iFail.length}/${inventory.length}` +
       (warns.length ? ` · ${warns.length} warn(s)` : "") +
+      (linkWarns.length ? ` · ${linkWarns.length} dangling link(s)` : "") +
       (fail ? ` · ${fail} FAILED` : " · all pass"),
   );
   return fail ? 1 : 0;

package/lib/mcp-client.mjs

@@ -26,7 +26,9 @@ const readJson = (file) => {
 // The platform repo id this working copy is provisioned for.
 export function repoIdOf(cwd) {
   const stamp = readStamp(cwd);
-  return typeof stamp.repoId === "string" && stamp.repoId !== "" ? stamp.repoId : null;
+  return typeof stamp.repoId === "string" && stamp.repoId !== ""
+    ? stamp.repoId
+    : null;
 }
 
 export function resolveMcp(cwd) {
@@ -66,26 +68,51 @@ let rpcId = 0;
 // message on transport or tool errors.
 export async function callTool(cwd, tool, args = {}) {
   const { repoId, key, mcpUrl } = resolveMcp(cwd);
-  const res = await fetch(mcpUrl, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${key}`,
-    },
-    body: JSON.stringify({
-      jsonrpc: "2.0",
-      id: ++rpcId,
-      method: "tools/call",
-      params: { name: tool, arguments: { repo: repoId, ...args } },
-    }),
-  });
+  // A localhost platform is only reachable on the machine running the dev
+  // server — on a CI runner it is a guaranteed dead end; say so up front
+  // instead of a bare "fetch failed".
+  if (
+    process.env.CI &&
+    /\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)[:/]/.test(mcpUrl)
+  )
+    throw new Error(
+      `platform MCP url is ${mcpUrl} — a localhost dev server is not reachable from CI.\n` +
+        `  Set the RAFA_MCP_URL secret to your deployed platform's /api/mcp URL, or run the\n` +
+        `  session fallback instead (/rafa distill <branch> in Claude Code).`,
+    );
+  let res;
+  try {
+    res = await fetch(mcpUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: ++rpcId,
+        method: "tools/call",
+        params: { name: tool, arguments: { repo: repoId, ...args } },
+      }),
+    });
+  } catch (e) {
+    throw new Error(
+      `cannot reach the platform MCP at ${mcpUrl} (${e instanceof Error ? e.message : e}) — ` +
+        `check the URL (RAFA_MCP_URL / credentials.json / .mcp.json) and that the platform is deployed and reachable from here.`,
+    );
+  }
   if (res.status === 401)
-    throw new Error("agent key rejected (401) — revoked or wrong platform; mint a new one (repo → Agent access)");
+    throw new Error(
+      "agent key rejected (401) — revoked or wrong platform; mint a new one (repo → Agent access)",
+    );
   if (res.status === 429)
     throw new Error("rate limited (429) — back off and retry");
   if (!res.ok) throw new Error(`MCP endpoint returned HTTP ${res.status}`);
   const body = await res.json();
-  if (body.error) throw new Error(`MCP error: ${body.error.message ?? JSON.stringify(body.error)}`);
+  if (body.error)
+    throw new Error(
+      `MCP error: ${body.error.message ?? JSON.stringify(body.error)}`,
+    );
   const result = body.result ?? {};
   const payload = result.structuredContent ?? null;
   if (result.isError) {

package/lib/okf.mjs

@@ -0,0 +1,110 @@
+// rafa okf — the OKF surface commands (contract §11). The format machinery is
+// @rafinery/okf; the rafa profile decides where classes live and what stamps
+// are derivable.
+//
+//   rafa okf                 materialize the surface on .rafa (stamps · link
+//                            transpile · citations sections · index tree).
+//                            Runs automatically inside `rafa push`.
+//   rafa okf check           OKF §9 conformance walk of the bundle — errors
+//                            fail (exit 1), soft guidance warns. Exemptions
+//                            (active.md) are explicit and surfaced.
+//   rafa okf new <class> <id> [--key=value …] [--cite="f:l :: tok" …] [--link=id …]
+//                            mint a conformant concept skeleton in the class's
+//                            directory. Nothing is invented: flags you omit are
+//                            absent, and `rafa compile` fails required ones
+//                            loudly — that is the validate-and-correct loop.
+
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { runOkfEmit } from "./gate/okf-emit.mjs";
+import { SCHEMA_VERSION } from "./gate/compile.mjs";
+import {
+  OKF_VERSION,
+  validateBundle,
+  newConcept,
+  FILE_CLASSES,
+  RAFA_EXEMPT,
+} from "@rafinery/okf";
+
+export default async function okf(args = []) {
+  const [sub, ...rest] = args[0]?.startsWith("--") ? [undefined, ...args] : args;
+  const ROOT =
+    (args.find((a) => a.startsWith("--root=")) ?? "").slice(7) || ".rafa";
+
+  if (sub === undefined || sub === "emit") {
+    process.exit(runOkfEmit(args.filter((a) => a.startsWith("--"))));
+  }
+
+  if (sub === "check") {
+    const { conformant, checked, errors, warnings } = validateBundle(ROOT, {
+      exempt: RAFA_EXEMPT,
+    });
+    for (const e of errors) console.log(`✗ ${e.path} — ${e.rule}`);
+    for (const w of warnings) console.log(`⚠ ${w.path} — ${w.rule}`);
+    console.log(
+      `${conformant ? "✓" : "✗"} rafa okf check: ${checked} files · ` +
+        `${errors.length} error(s) · ${warnings.length} warning(s) — ` +
+        (conformant ? `bundle conforms to OKF v${OKF_VERSION}` : "bundle is NOT conformant"),
+    );
+    process.exit(conformant ? 0 : 1);
+  }
+
+  if (sub === "new") {
+    const [cls, id] = rest.filter((a) => !a.startsWith("--"));
+    const registry = FILE_CLASSES[cls];
+    if (!registry || registry.singleton) {
+      console.error(
+        `✗ rafa okf new: <class> must be one of ${Object.entries(FILE_CLASSES)
+          .filter(([, c]) => !c.singleton)
+          .map(([k]) => k)
+          .join(" | ")} (singletons are authored at their fixed path)`,
+      );
+      process.exit(1);
+    }
+    if (!id) {
+      console.error("✗ rafa okf new: missing <id> (kebab-case, becomes the filename stem)");
+      process.exit(1);
+    }
+    const fields = { schemaVersion: SCHEMA_VERSION }; // never a literal — moves with the contract
+    const listFields = { cites: [], links: [] };
+    for (const a of rest.filter((a) => a.startsWith("--"))) {
+      const m = a.match(/^--([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      const [, key, value] = m;
+      if (key === "cite") listFields.cites.push(value);
+      else if (key === "link") listFields.links.push(value);
+      else if (key !== "root") fields[key] = value;
+    }
+    // The improvement class's OKF type is constant; notes author their own
+    // contract enum via --type (compile owns the enum — no default here).
+    const type = fields.type ?? registry.okfType ?? "";
+    delete fields.type;
+    let content;
+    try {
+      content = newConcept({ type, id, fields, listFields });
+    } catch (e) {
+      console.error(`✗ rafa okf new: ${e instanceof Error ? e.message : e}`);
+      console.error(
+        cls === "improvement"
+          ? ""
+          : "  notes require --type=<contract|convention|flow|how-to> (the compile enum)",
+      );
+      process.exit(1);
+    }
+    const path = join(ROOT, registry.dir, `${id}.md`);
+    if (existsSync(path)) {
+      console.error(`✗ rafa okf new: ${path} already exists — refusing to overwrite`);
+      process.exit(1);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+    console.log(
+      `✓ rafa okf new: ${path} — now write the body + fill required fields, ` +
+        `then \`rafa verify-citations\` + \`rafa compile\` gate it.`,
+    );
+    process.exit(0);
+  }
+
+  console.error(`✗ rafa okf: unknown subcommand "${sub}" (emit | check | new)`);
+  process.exit(1);
+}