@rafinery/cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,64 @@ The machine-readable version of this lives in [`lib/releases.mjs`](lib/releases.
 CLI reads it to tell a client, on `rafa update`, exactly what an upgrade requires (nothing,
 a re-scan, or a `rafa migrate`).
 
+## 0.8.0 — the OKF surface: every brain is an Open Knowledge Format bundle
+
+**Adopt with:** `npx @rafinery/cli@latest update`, then `rafa push` — the next push
+materializes the surface. Brain data schema unchanged (manifest shape + `schemaVersion: 1`
++ checker v2 — all additive per contract §8); no re-scan.
+
+**The protocol (contract §11, owner-ratified 2026-07-15):** if rafa writes a `.md`, it is a
+valid [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+concept — frontmatter, `type`, markdown links, cited — and a pushed brain repo IS a
+conformant bundle any foreign OKF consumer reads without rafa tooling. OKF standardizes
+format and has no truth story; rafa's gates are the layer above it. Anyone can emit OKF —
+only rafa proves its OKF against the code at a sha.
+
+- **New workspace package [`@rafinery/okf`](../okf/)** (zero-dep): the strict frontmatter
+  parser (moved out of the gate — one parser everywhere), concept split/join/stamp
+  primitives, link transpile + extraction, citations render, index builders, the OKF §9
+  conformance validator, and the concept generator. The CLI now depends on it.
+- **`rafa okf`** — the emit step, run inside `rafa push` BEFORE the gates (its output is
+  validated like any authored file): stamps ONLY derivable values (`description` from
+  `summary` · singleton `type`/`title` from the class registry · `timestamp` from authored
+  `created:`/`found:` → brain-repo git history → the emit run itself; a value that cannot
+  be derived is omitted — never guessed); renders a generated `# Citations` section from
+  the `cites:` DSL (sha-pinned GitHub URLs when the repo is known) inside `okf:citations`
+  markers; transpiles resolvable `[[wikilinks]]` into bundle-relative markdown links (the
+  authored form going forward — rafa-scan/improve/validate SOPs updated); generates the
+  `index.md` tree — progressive disclosure from the bundle root (root index frontmatter:
+  `okf_version: "0.1"` + `repo` + `codeSha`), any concept reachable in ≤ 2 hops.
+- **`rafa okf check`** — the §9 conformance walk; documented exemptions (`active.md`,
+  `log.md` heading decoration) are explicit and surfaced as warnings, never silent.
+- **`rafa okf new <class> <id> [--key=v] [--cite='f:l :: t'] [--link=id]`** — mint a
+  conformant concept skeleton; the generator refuses to invent values (omitted required
+  fields fail loudly at compile — the validate-and-correct loop). The **rafa-okf skill**
+  is the SOP: a NEW file class = one profile-registry entry + one contract row + a compile
+  validator — minutes, not hours.
+- **Checker (still v2, additive):** a non-failing **LINKS warn lane** — every frontmatter
+  `links:` id, body wikilink, and bundle-relative markdown link resolved bundle-wide;
+  dangling = not-yet-written knowledge (OKF §5.3), listed for prism, never a gate failure
+  (closes the 2026-06-19 `[[…]]`-lint ratchet). `citation-check.md` now self-describes
+  (frontmatter), and `citation-check.json` gains additive `linkWarns`.
+- **Reserved names:** `index.md` + `log.md` are OKF-reserved at every level — skipped by
+  the compile/checker walkers, never concept documents.
+- **Plans carry the surface too:** §7 work items ride the brain-repo transport, so
+  emit stamps `type: Plan Epic|Task|Subtask` from `kind` + `tags: [plan, kind]`, and
+  builds a per-epic `plans/index.md`.
+- **Totality (the TypeScript bar):** every `.md` class rafa touches is registered with a
+  schema or a declared class — `*.theirs.md` checkpoint conflicts now fail compile with a
+  TYPED rule ("unresolved checkpoint conflict", not an incidental id error) and are
+  invisible to the OKF walkers; shipped SOPs (`.claude/skills/rafa-*/SKILL.md` + the
+  conductor) and sage learnings (`.claude/rafa/learnings/*.md`) are compile-gated local
+  classes beside the agent cards. Declared exemptions stay visible (`active.md`,
+  `log.md` headings) — an allowlist, never an implicit any.
+- **Fleet adoption — the whole workforce:** `okf-surface` duty on the atlas (3.8.0) ·
+  bloom (0.8.0) · prism (0.7.0) · sage (0.2.0) cards; the conductor's verb map carries
+  the protocol note (plans · journals); rafa-plan/build/distill SOPs point at §11.
+  **compass (0.4.0) carries `okf-awareness`** — it writes platform state, never bundle
+  files, and owns the portability law: OKF bundles are exchangeable by design, so
+  person-scoped content NEVER lands in one.
+
 ## 0.6.0 — core solidity: checker v2 + the M5 capture engine
 
 **Adopt with:** `npx @rafinery/cli@latest update` — re-vendors the new lockstep hook

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/bin/rafa.mjs

@@ -5,7 +5,9 @@
 //   rafa update               re-sync the blueprint into this repo (shadcn-style)
 //   rafa compile              run the contract gate → .rafa/manifest.json
 //   rafa verify-citations     deterministic citation checker (B1/B2/policy/absence/inventory)
-//   rafa push                 compile + push .rafa/ to the brain remote (main-branch act)
+//   rafa okf [check|new]      the OKF surface: emit (stamps·links·citations·indexes) ·
+//                             conformance check · mint a new concept skeleton
+//   rafa push                 okf emit + gates + push .rafa/ to the brain remote (main-branch act)
 //   rafa pull [--full]        make this clone brain-ready (lazy skeleton; --full mirrors)
 //   rafa checkpoint           sync this branch's working set (CAS; conflicts → .theirs.md)
 //   rafa hydrate              fault knowledge into the lazy .rafa/
@@ -23,6 +25,7 @@
 // vendored LOCKSTEP; commands are agent-internal machinery (zero-command rule).
 
 import { readFileSync } from "node:fs";
+import { OKF_VERSION } from "@rafinery/okf";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -34,6 +37,7 @@ const COMMANDS = [
   "update",
   "compile",
   "verify-citations",
+  "okf",
   "push",
   "pull",
   "checkpoint",
@@ -69,8 +73,19 @@ Commands:
                        every contract anchor's code occurrences are cited (B2), policy
                        holds, declared absences re-grepped (B3), coverage inventories
                        re-counted. Records the run (citation-check.json → manifest).
-  push                 Compile, then push .rafa/ to your brain remote (from main — the
-                       org brain describes the default branch). Stamps the contract copy.
+  okf                  The OKF surface (contract §11) — a pushed brain repo is a conformant
+                       Open Knowledge Format v${OKF_VERSION} bundle. You never need to run this:
+                       emit happens automatically inside "rafa push" (zero-command rule).
+                       Standalone forms are agent/maintainer machinery — "rafa okf"
+                       re-materializes the surface for debugging; "rafa okf check" walks
+                       §9 conformance (ours is conformant by construction — this is for
+                       CI belt-and-suspenders and, later, grading foreign bundles);
+                       "rafa okf new <class> <id>" mints a conformant skeleton (used by
+                       the agents per the rafa-okf skill — brain files are never
+                       hand-authored).
+  push                 OKF emit + citation checker + compile, then push .rafa/ to your
+                       brain remote (from main — the org brain describes the default
+                       branch). Stamps the contract copy.
   pull                 Make this clone brain-ready — bootstraps the lazy .rafa/ skeleton
                        from the committed rafa.json (clone → npx rafa pull just works).
                        --full mirrors the whole brain repo locally (offline reads);

package/blueprint/.claude/agents/atlas.md

@@ -1,6 +1,6 @@
 ---
 name: atlas
-version: 3.7.0
+version: 3.8.0
 model: opus   # authoring is correctness-critical — a hallucinated note poisons the brain; best model, never cheap
 groundTruth: code-at-sha
 description: >-
@@ -18,6 +18,7 @@ duties:
   - "plan-drafting :: .claude/skills/rafa-plan/SKILL.md :: recall-grounded decomposition (coverage → search → notes) · blast radius named · contract §7 files · every child carries a Done-check"
   - "build-execution :: .claude/skills/rafa-build/SKILL.md :: implement per recalled knowledge · never hand-edit brain files around the gate · return what changed, cited"
   - "scoped-refresh :: .claude/skills/rafa-scan/SKILL.md :: re-derive ONLY the dirty-cited notes against current code (input: rafa dirty --json) · same gates as scan (verify-citations exit 0) · on main: compile+push; on a branch: working-set edit + checkpoint · queue consumed only after the refresh ships"
+  - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: authored files pass rafa okf check as written — body links are markdown (never wikilinks); emit-owned sections untouched"
 ---
 
 # atlas — senior design engineer
@@ -28,8 +29,8 @@ reasons about systems, not a code-completion assistant.
 ## The brain
 
 rafa's core is the **brain** — a **knowledge map**: atomic, cited, interlinked notes
-(Obsidian-style markdown with `[[links]]`; the graph is derived from the links, never
-stored). atlas and other surfaces *contribute* notes; the org *consumes* them.
+(markdown cross-linked with bundle-relative links + `links:` frontmatter — the OKF
+surface, contract §11; the graph is derived from the links, never stored). atlas and other surfaces *contribute* notes; the org *consumes* them.
 
 The notes exist to answer the questions that fire at **work-time** — when a dev plans a
 feature or fixes a bug — without re-reading the repo:

package/blueprint/.claude/agents/bloom.md

@@ -1,6 +1,6 @@
 ---
 name: bloom
-version: 0.7.0
+version: 0.8.0
 model: opus   # a false flag mutes the whole ledger — best model, never cheap
 groundTruth: code-trend
 description: >-
@@ -17,6 +17,7 @@ duties:
   - "plan-pull :: .claude/skills/rafa-plan/SKILL.md :: top-leverage OPEN improvements in the blast radius surfaced as optional child tasks — dismissible, never blocking"
   - "build-sweep :: .claude/skills/rafa-build/SKILL.md :: newly spotted → ledger files · fixed-in-passing → status fixed · at most ONE opt-in nudge per task"
   - "staleness-watch :: .claude/skills/rafa-improve/SKILL.md :: median open-item age stays minimal — every sweep re-validates or closes aged items; no improvement ages silently"
+  - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: improvements/ledger pass rafa okf check as written · found: authored so timestamps are authored truth"
 ---
 
 # bloom — continuous improvement

package/blueprint/.claude/agents/compass.md

@@ -1,6 +1,6 @@
 ---
 name: compass
-version: 0.3.0
+version: 0.4.0
 model: opus   # a false note about a PERSON is worse than one about code — best model, never cheap
 groundTruth: sessions-over-time
 description: >-
@@ -18,6 +18,7 @@ duties:
   - "steering :: .claude/skills/rafa-insights/SKILL.md :: propose-dev-disposes at natural boundaries · at most one nudge · dismissal is final for the session · never rank, never compare, never nag"
   - "leverage-coaching :: .claude/skills/rafa-insights/SKILL.md :: the one boundary nudge may be sourced from toolbox × patterns (repo inventory + the dev's tooling insights) — always HAS a candidate ready, never raises nudge frequency; only capabilities actually installed"
   - "tooling-capture :: .claude/skills/rafa-insights/SKILL.md :: personal ~/.claude tooling (names + descriptions ONLY) banked as kind:tooling insights under STANDING consent · legible/deletable · never enters org stores"
+  - "okf-awareness :: .claude/skills/rafa-okf/SKILL.md :: person-scoped content NEVER lands in a bundle .md (bundles are portable by design); anything compass materializes self-describes"
 ---
 
 # compass — the dev's coach

package/blueprint/.claude/agents/prism.md

@@ -1,6 +1,6 @@
 ---
 name: prism
-version: 0.6.1
+version: 0.7.0
 model: opus   # the trust anchor — a hallucinated verdict/finding is the worst failure; best model, never cheap
 groundTruth: code-vs-claim
 description: >-
@@ -17,6 +17,7 @@ duties:
   - "plan-gate :: .claude/skills/rafa-plan/SKILL.md :: PASS = every task grounded in brain + code (none hallucinated) · every child carries a Done-check · blast radius named from coverage; else REJECT with cited reasons"
   - "execution-validation :: .claude/skills/rafa-build/SKILL.md :: done only when the child's Done-check demonstrably holds — run it yourself against the working tree; FAIL returns cited reasons to the producer"
   - "distillation-validation :: .claude/skills/rafa-distill/SKILL.md :: every working-set file judged against MERGED MAIN (never the fork point) with a confirming/refuting file:line — survivors enter the org brain only through compile; refutations go back to their author, cited"
+  - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: every checker LINKS warn judged (unwritten knowledge vs typo) — never ignored, never auto-failed"
 ---
 
 # prism — the validator

package/blueprint/.claude/agents/sage.md

@@ -1,6 +1,6 @@
 ---
 name: sage
-version: 0.1.0
+version: 0.2.0
 model: opus   # a wrong learning re-shapes an agent for every repo — best model, never cheap
 groundTruth: sessions-over-time
 description: >-
@@ -19,6 +19,7 @@ duties:
   - "scrub :: .claude/skills/rafa-sage/SKILL.md :: every entry passes the SCRUB STEP before write — anything asset-shaped (code content, snippets, repo-specific facts, repo-identifying detail) abstracted to the pattern or DROPPED; the ledger entry schema has NO code-content-capable field"
   - "route-person-shaped :: .claude/skills/rafa-sage/SKILL.md :: a person-shaped observation is NEVER a learning — it routes to compass's consent path (rafa-insights, user brain), never sage's ledger"
   - "propose-only :: .claude/skills/rafa-sage/SKILL.md :: output is PROPOSED diffs to agent cards/SOPs — applying a change is a separate human/MR-reviewed act; sage never self-applies and never edits an agent card or SOP"
+  - "okf-surface :: .claude/skills/rafa-okf/SKILL.md :: learnings pass the compile learning gate (id · type · title · description) — the same protocol outside the bundle"
 ---
 
 # sage — the silent L5 observer

package/blueprint/.claude/commands/rafa.md

@@ -196,6 +196,10 @@ Two destinations, one rule — route by what the observation is ABOUT:
 
 ## Verb map — one line each; the procedure lives in the linked skill
 
+> **Every verb that writes `.md` is under the OKF surface** (contract §11): files
+> self-describe, body links are bundle-relative markdown, `rafa push` materializes
+> the rest — protocol + the two declared exceptions live in [rafa-okf](../skills/rafa-okf/SKILL.md).
+
 Each work/admin verb dispatches to its SOP. Read the skill only when the verb runs; it is
 self-contained and ADR-shaped. **You orchestrate + push on approval; the subagent follows
 its skill verbatim.** Admin verbs (init · scan · push · migrate · update) run ONLY when

package/blueprint/.claude/rafa/contract.md

@@ -16,7 +16,10 @@ Pipeline:
 
 ```
 agents write .md (frontmatter per this contract)
-  → rafa compile   (deterministic: parse frontmatter, VALIDATE, fail loudly)
+  → rafa okf       (deterministic OKF surface, §11: stamp derivable fields,
+                    transpile [[wikilinks]], render # Citations, index tree)
+  → rafa compile   (deterministic: parse frontmatter, VALIDATE, fail loudly —
+                    the emitted surface is gated like any authored file)
        ├ FAIL → structured error (file · field · rule) → author agent fixes → retry
        └ PASS → emit manifest.json
   → git push → webhook → INGEST = JSON.parse(manifest) + shape-check → Convex
@@ -44,14 +47,18 @@ doesn't validate, compile fails.
 | improvement           | `improve/improvements/*.md`       | **structured**                                                                                                                     | §3                                                                                                                                                            | bloom      |
 | ledger                | `improve/ledger.md`               | **structured**                                                                                                                     | §5                                                                                                                                                            | bloom      |
 | plan                  | `plans/**/*.md`                   | **structured**                                                                                                                     | §7                                                                                                                                                            | plan/build |
-| log                   | `brain/log.md`                    | **verbatim**                                                                                                                       | — (prose trail)                                                                                                                                               | conductor  |
-| citation-check        | `**/citation-check.md`            | **generated**                                                                                                                      | — (by `rafa verify-citations`)                                                                                                                                | tool       |
+| log                   | `brain/log.md`                    | **verbatim**                                                                                                                       | — (prose trail; OKF-reserved name, §11)                                                                                                                       | conductor  |
+| index                 | `**/index.md`                     | **generated**                                                                                                                      | — (OKF §6 listings, by `rafa okf`; the ROOT index alone carries frontmatter: `okf_version` + provenance)                                                      | tool       |
+| citation-check        | `**/citation-check.md`            | **generated**                                                                                                                      | — (by `rafa verify-citations`; self-describing frontmatter, §11)                                                                                              | tool       |
 | citation-check record | `**/citation-check.json`          | **generated**                                                                                                                      | `{ checkerVersion, at, pass, gates, warns }` (by `rafa verify-citations`; compile folds it into `manifest.citations`)                                         | tool       |
 | active pointer        | `active.md`                       | **generated**                                                                                                                      | — (`# <plan-id>` or "No active plan"; compile emits it as `activePlanId`, §7)                                                                                 | conductor  |
-| contract copy         | `contract.md`                     | **generated**                                                                                                                      | — (stamped copy of `.claude/rafa/contract.md`, written by `rafa push`)                                                                                        | tool       |
+| contract copy         | `contract.md`                     | **generated**                                                                                                                      | — (stamped copy of `.claude/rafa/contract.md`, written by `rafa push`; self-describing frontmatter, §11)                                                      | tool       |
 | dirty queue           | `dirty.jsonl`                     | **generated** (local state — transport-excluded, NEVER pushed/ingested)                                                            | one `{f, t}` JSON line per code edit (by the PostToolUse sensor hook; read by `rafa dirty` + the SessionStart digest)                                         | tool       |
 | reflex queue          | `reflex.jsonl`                    | **generated** (local state — transport-excluded, NEVER pushed/ingested; transcript pointers are LOCAL, raw transcripts never ship) | `{id, p, t, tp}` per detected correction + append-only `{id, done, verdict, at}` markers (by the UserPromptSubmit sensor; read by `rafa reflex` + the digest) | tool       |
 | agent                 | `.claude/agents/*.md` (code repo) | **structured** (local gate — NOT in manifest)                                                                                      | §10                                                                                                                                                           | rafa       |
+| skill SOP             | `.claude/skills/rafa-*/SKILL.md` + `.claude/commands/rafa.md` (code repo) | **structured** (local gate — NOT in manifest)                                                                             | frontmatter parses · `name` == skill dir (conductor: semver `version`) · non-empty `description` — a workforce whose procedures don't parse doesn't ship      | rafa       |
+| learning              | `.claude/rafa/learnings/*.md` (code repo) | **structured** (local gate — NOT in manifest)                                                                              | OKF quartet-lite: `id` == stem · non-empty `type`/`title`/`description` (§11 outside the bundle; `learnings/ledger.md` is sage's generated index, skipped)     | sage       |
+| conflict copy         | `**/*.theirs.md`                  | **generated** (transient — a pending HUMAN decision)                                                                               | none — compile FAILS with the typed rule "unresolved checkpoint conflict" while one exists; every walker (emit · checker · validator) skips them              | tool       |
 
 The `agent` type is the one structured type outside `.rafa/`: the shipped agent cards
 in the code repo. Compile validates them (§10) so a malformed card fails the gate like
@@ -600,4 +607,79 @@ Versioning: bump `version:` with any card change; record the _why_ outside the c
 
 ---
 
+## 11. The OKF surface — every generated `.md` self-describes
+
+**Ratified 2026-07-15 (owner decision, `.fable/decisions.md`).** The [Open
+Knowledge Format v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+is the interchange **floor** of everything rafa generates (pinned ONCE as
+`OKF_VERSION` in `@rafinery/okf` — machine surfaces interpolate it, never
+re-declare it); this contract stays the strict **ceiling**. The protocol in one sentence: *if rafa writes a `.md`,
+it is a valid OKF concept — frontmatter, `type`, markdown links, cited — and a
+pushed brain repo IS a conformant OKF v0.1 bundle any foreign consumer can read
+without rafa tooling.* The format machinery is the `@rafinery/okf` package
+(strict parser · concept primitives · links · citations · indexes · validator ·
+generator); the gate, the emitter, and the platform all parse through it.
+
+**The emit step (`rafa okf`, run inside `rafa push` BEFORE the gates so its
+output is validated like any authored file):**
+
+- **Stamps** — missing `type` / `title` / `description` / `timestamp` / `tags`
+  are added ONLY where derivable: `description` from `summary`; singleton
+  `type`/`title` from the file-class registry (`Coverage Report` ·
+  `Health Report` · `Improvement Ledger`; improvements → `Improvement`; plan
+  items → `Plan Epic|Task|Subtask` derived from `kind` (§7 files ride the
+  brain-repo transport, so they carry the surface; per-epic `plans/index.md`);
+  notes keep their authored §2 enum — those ARE valid OKF types); `timestamp` from
+  authored `created:`/`found:` verbatim, else brain-repo git history, else the
+  emit run itself (a fresh file IS changing now). **Authored values are never
+  rewritten; a value that cannot be derived is omitted** — the no-assumed-values
+  law applied to interchange. Stamped fields are OPTIONAL at compile and
+  validated when present — additive per §8, so **`schemaVersion` stays 1** and
+  the manifest shape is untouched.
+- **Links** — bodies use standard **bundle-relative markdown links**
+  (`[Title](/brain/rules/<id>.md)`), the OKF §5.1 recommended form. Legacy
+  `[[wikilinks]]` are transpiled at emit when the id resolves; a dangling link
+  is *not-yet-written knowledge* (OKF §5.3): the checker lists it in a
+  non-failing **LINKS warn lane** — prism's worklist, never a gate failure.
+  `links:` frontmatter stays the machine edge list (graph without body parsing).
+- **Citations** — the `cites:` DSL stays the machine truth; emit renders a
+  generated `# Citations` section (OKF §8) inside `okf:citations` markers —
+  sha-pinned GitHub URLs when the repo is known, plain locators otherwise.
+  Generated body sections are display-only: the body is still NEVER parsed for
+  data (§0 holds).
+- **Indexes** — an `index.md` in every concept directory + the bundle root
+  (OKF §6 progressive disclosure): a foreign agent reaches any concept from the
+  root in ≤ 2 hops. `index.md` and `log.md` are **reserved names** — never
+  concept documents, skipped by every walker. The ROOT index alone carries
+  frontmatter: `okf_version: "0.1"` + provenance (`repo` · `codeSha`) — bundle
+  freshness rides here, pinned to the code sha.
+
+**Conformance:** `rafa okf check` walks OKF §9 over the bundle (every
+non-reserved `.md` parses + carries a non-empty `type`). **Strictness is
+total, TypeScript-style:** every `.md` class rafa touches is in the file-type
+registry with a schema or a declared class; unregistered shapes fail loudly
+(`*.theirs.md` → the typed conflict rule), and shipped SOPs + sage learnings
+are compile-gated in the code repo alongside the agent cards. **Documented
+exceptions**, passed as explicit exemptions and surfaced as warnings, never
+silently skipped: `active.md` (one-line pointer protocol) and `log.md` heading
+decoration (our date-led `## YYYY-MM-DD — …` headings stay; OKF prefers bare
+dates).
+
+**Minting a new file type** (`rafa okf new` + the
+[rafa-okf skill](../skills/rafa-okf/SKILL.md)): a class = one registry entry in
+`@rafinery/okf`'s rafa profile + a row in the file-type registry above + a
+compile validator. The generator refuses to invent values — flags you omit are
+absent and compile fails required ones loudly (the validate-and-correct loop,
+not a generator bug).
+
+**Fleet adoption:** every agent that authors `.md` carries an `okf-surface`
+duty in its card (§10) pointing at the rafa-okf SOP — atlas (notes · coverage),
+bloom (improvements · ledger), prism (checklist + validation lens), sage
+(learnings); the conductor's verbs inherit it via the verb-map note (plans ·
+journals). compass carries `okf-awareness`: it writes platform state, never
+bundle files, and owns the PORTABILITY law — bundles are exchangeable by
+design, so person-scoped content never lands in one.
+
+---
+
 This contract is the thing to test against.

package/blueprint/.claude/skills/rafa-build/SKILL.md

@@ -35,7 +35,8 @@ platform MCP (one read path — the same surface any third-party agent uses).
    offer.
 2. **Per task:** atlas recalls → implements → prism validates vs `## Done-check` →
    bloom sweeps (push new / close fixed / nudge) → update the child file's `status`
-   **and append a dated entry to the child's `## Log`** — what was done, what was
+   **and append a dated entry to the child's `## Log`** (body links: markdown,
+   per [rafa-okf](../rafa-okf/SKILL.md)) — what was done, what was
    decided, what surprised (body prose: displayed verbatim on the platform, never
    parsed; the plan files at `.rafa/plans/<plan>/` ARE the local cache) → at the
    task-done CHECKPOINT (under the session consent): `push_plan` /

package/blueprint/.claude/skills/rafa-distill/SKILL.md

@@ -53,7 +53,8 @@ code it describes.
 4. **Gate + ship** — `rafa verify-citations` AND `rafa compile` to exit 0 →
    `rafa push`. Only now has anything entered the org brain. A failed gate
    aborts EVERYTHING: nothing resolved, nothing pushed, working set intact.
-5. **Resolve** — `resolve_working_file(path, distilled)` for survivors —
+5. **Resolve** — `resolve_working_file(path, distilled)` for survivors — authored
+   per the OKF surface ([rafa-okf](../rafa-okf/SKILL.md); push emits the rest) —
    CAS: only a live row resolves; a failure means ANOTHER runner already
    distilled this branch — STOP and reconcile against what it shipped.
    `resolve_working_file(path, refuted, note)` for failures — TELL the author

package/blueprint/.claude/skills/rafa-improve/SKILL.md

@@ -72,7 +72,7 @@ cites:                                      # required ≥1 · `file:line :: tok
 found: 2026-06-03                           # optional
 ---
 Route-level `"use client"` silently disables RSC down the subtree (violates the RSC boundary
-convention — see [[rsc-client-boundary]]). Compiles + runs, so no gate catches it.
+convention — see [RSC client boundary](/brain/rules/rsc-client-boundary.md)). Compiles + runs, so no gate catches it.
 ```
 
 ---

package/blueprint/.claude/skills/rafa-okf/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: rafa-okf
+description: "rafa SOP — the OKF surface (contract §11): every generated .md self-describes as an Open Knowledge Format v0.1 concept, and a pushed brain repo is a conformant bundle any foreign agent can read. How every authoring agent writes OKF-natively, and how to mint a NEW file type in minutes via rafa okf new + the @rafinery/okf registry. Loaded via the okf-surface duty on atlas · bloom · prism · sage cards."
+---
+
+# okf — the interchange surface every writer shares
+
+**The protocol in one sentence:** *if rafa writes a `.md`, it is a valid OKF
+concept — frontmatter, `type`, markdown links, cited — and a pushed brain repo
+IS a conformant [OKF v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+bundle.* The spec version is pinned ONCE — `OKF_VERSION` in `@rafinery/okf`
+(v0.1 today); machine surfaces interpolate it, never re-declare it. OKF is the
+interchange **floor** (what any foreign agent can read);
+the [contract](../../rafa/contract.md) stays the strict **ceiling** (what our
+gates enforce). Canonical spec: contract **§11**. Machinery: the
+**`@rafinery/okf`** package ([packages/okf/](../../../packages/okf/)) — parser,
+concept primitives, links, citations, indexes, validator, generator. Nothing is
+buried in gate output; every surface (gate CLI · emitter · platform · tests)
+imports the same package.
+
+Why it matters: OKF standardizes format and has **no truth story** — anyone
+can emit OKF; only rafa mechanically proves its OKF against the code at a sha.
+Conformance is our distribution wedge; verification stays the moat.
+
+---
+
+## Prime directives
+
+1. **Every generated `.md` self-describes** — frontmatter with a non-empty
+   `type`, no exceptions beyond the two documented ones (`active.md` pointer,
+   `log.md` heading decoration), which are declared exemptions surfaced by
+   `rafa okf check`, never silent skips.
+2. **No assumed values, extended to interchange** — a stamp is derived from
+   authored data or real history (git), or it is **omitted**. Authored values
+   are never rewritten by tooling.
+3. **Author markdown links, not wikilinks** — bundle-relative form:
+   `[Title](/brain/rules/<id>.md)` (OKF §5.1). Legacy `[[wikilinks]]` are
+   transpiled at emit when they resolve; a dangling link is *not-yet-written
+   knowledge* (OKF §5.3) — the checker's non-failing LINKS lane lists it as
+   your worklist. `links:` frontmatter stays the machine edge list.
+4. **`cites:` stays the machine truth** — the generated `# Citations` body
+   section (inside `okf:citations` markers) is display-only render, re-emitted
+   each push, never hand-edited.
+5. **Naming is navigation** — kebab-case ids that equal filename stems,
+   semantic directories, an `index.md` at every level: a foreign agent reaches
+   any concept from the bundle root in ≤ 2 hops with zero rafa tooling.
+
+## How each agent writes OKF-natively (the adoption map)
+
+| Agent | Files | What OKF-native means for you |
+|---|---|---|
+| **atlas** | `brain/rules/` · `brain/playbooks/` · `brain/coverage.md` | author `type` (§2 enum) + `title` + `summary` as ever; body cross-links as markdown links; optionally author `description`/`tags` — emit derives them from `summary`/`domain` if you don't |
+| **bloom** | `improve/improvements/` · `improve/ledger.md` | same; your files gain `type: Improvement` + `tags: [lens, priority]` at emit — author `found:` so timestamps are yours, not git's |
+| **prism** | `brain/checklist.md` | verdict frontmatter as ever (emit stamps `type: Health Report` + a derived description); at validation, treat the checker's LINKS warns as a worklist — dangling links are claims of future knowledge |
+| **sage** | `.claude/rafa/learnings/` | learnings are OKF concepts too: frontmatter + `type: Learning` + markdown links; outside the bundle but under the same protocol |
+| **conductor / plan·build** | `plans/**` · `brain/log.md` | plan items gain `type` from `kind` at emit (per-epic `plans/index.md`); journals + bodies use markdown links; `log.md` stays the reserved trail |
+| **compass** | — | writes platform state, never bundle `.md` — its duty is the PORTABILITY law: OKF bundles are exchangeable, so person-scoped content never lands in one; anything it ever materializes self-describes |
+
+The tooling backstop: `rafa push` runs `rafa okf` (emit) → `verify-citations`
+→ `compile`, so the surface exists even where an agent forgot — but authoring
+natively keeps stamps honest (your `created:`/`found:` beats git history).
+
+## Minting a NEW file type — minutes, not hours
+
+A new generated file class is **four small moves**, conformant by construction:
+
+1. **Registry** — add the class to `FILE_CLASSES` in
+   [packages/okf/lib/profile-rafa.mjs](../../../packages/okf/lib/profile-rafa.mjs)
+   (dir or singleton path · OKF `type` name · index title) and, if any stamp is
+   derivable, a `derivedStamps` case. Derivation law: authored data or real
+   history, else omit.
+2. **Contract row** — one row in the contract's file-type registry
+   ([contract.md](../../rafa/contract.md), the §-table): path glob · class
+   (`structured`/`verbatim`/`generated`) · schema section · author. A
+   `structured` class also gets its schema section + a compile validator in
+   [packages/cli/lib/gate/compile.mjs](../../../packages/cli/lib/gate/compile.mjs)
+   (required fields fail loudly; enums closed).
+3. **Skeleton** — `rafa okf new <class> <id> --type=… --key=value
+   --cite="file:line :: token" --link=<id>` mints the file in the class's
+   directory. The generator REFUSES to invent values: flags you omit are
+   absent, and `rafa compile` fails required ones loudly — that is the
+   validate-and-correct loop working, not a bug to paper over.
+4. **Prove it** — `rafa verify-citations` (cites/anchors real) →
+   `rafa compile` (schema holds) → `rafa okf check` (bundle still conformant).
+   Add a case to the gate e2e
+   ([packages/cli/test/okf-gate.test.mjs](../../../packages/cli/test/okf-gate.test.mjs))
+   when the class carries new emit behavior.
+
+Naming rules for new classes (directive 5): class name = singular kebab noun;
+instances live in a plural semantic directory (`brain/<things>/`) or a fixed
+singleton path; ids kebab-case = filename stem; the OKF `type` value is a
+short, self-explanatory Title Case string (consumers route on it — OKF types
+are unregistered by design).
+
+## Commands
+
+```bash
+rafa okf          # materialize the surface (runs automatically inside rafa push)
+rafa okf check    # OKF §9 conformance walk — errors fail, exemptions surface as warnings
+rafa okf new …    # mint a conformant concept skeleton (see above)
+```

package/blueprint/.claude/skills/rafa-plan/SKILL.md

@@ -53,6 +53,7 @@ Planning is a choreography, not one agent (spec: knowledge-mcp-build-agent):
    never plan to hand-roll what a capability already does.
 5. **prism plan-validation** → REJECT/fix loop until clean.
 6. **Approval gate** (owner). Then materialize `plans/<plan>/*.md` per contract §7
+   (plan files ride the OKF surface — markdown links in bodies; see [rafa-okf](../rafa-okf/SKILL.md))
    (parent + child-owned files, globally-unique prefixed ids) + `active.md` pointer
    → `rafa compile` (validate the files) → **`push_plan` + `set_active_plan`
    immediately, no second prompt — plan approval IS the push trigger** (the

package/blueprint/.claude/skills/rafa-scan/SKILL.md

@@ -14,7 +14,9 @@ You run this as a **context-isolated subagent spawned by the `/rafa` conductor**
 whole-repo read happens in *your* window, not the conductor's; return a coverage summary, not
 the raw reads. The conductor owns the validate/iterate loop (Gate 2, below).
 
-The notes ARE the knowledge map. They are cited markdown with `[[links]]`; the graph is
+The notes ARE the knowledge map. They are cited markdown, cross-linked with
+**bundle-relative markdown links** — `[Title](/brain/rules/<id>.md)` (the OKF §5.1
+form; contract §11) — plus the `links:` frontmatter edge list; the graph is
 derived from the links, never stored. No `graph.json`.
 
 ## Governing law — memory must be net-positive
@@ -34,7 +36,7 @@ than none. Every rule below serves this law.
 
 A note earns its place only if it helps answer one of these, for a real feature/bug:
 - **"How does X flow end to end?"** → a `flow` playbook
-- **"What breaks if I touch Y?"** (blast radius) → `contract` rules + the `[[links]]`
+- **"What breaks if I touch Y?"** (blast radius) → `contract` rules + the link graph
 - **"Where does Z live / what's the convention?"** → `convention` rules
 - **"How do I add W here?"** → a `how-to` playbook
 
@@ -47,7 +49,7 @@ Code is the source of truth; the brain is the **index over it**. A note's job is
 reproduce code that will go stale. Optimize each note for:
 - precise `cites` — *go here* (this is the navigation; a wrong pointer sends you wrong)
 - the durable contract / gotcha — *watch this*
-- `[[links]]` — *these connect*
+- body markdown links + `links:` frontmatter — *these connect*
 
 The model then opens the cited files for current specifics. **Capture the durable, not
 the volatile** — don't copy implementation that drifts; copy the map and the warnings.
@@ -126,10 +128,11 @@ cites:                                    # required ≥1 · `file:line :: token
 failure: silent                           # contracts only: silent|loud
 ---
 The string must match across all four sites or the agent silently never connects.
-See [[copilotkit-frontend-action-routing]] and [[agent-tool-to-ui-flow]].
+See [frontend action routing](/brain/rules/copilotkit-frontend-action-routing.md)
+and [agent tool → UI flow](/brain/playbooks/agent-tool-to-ui-flow.md).
 ```
 `summary` is the one-line the platform shows; **`links` in frontmatter** are the machine-read
-graph edges (body `[[links]]` are for human reading only). `cites` + `domain` + `links` are the
+graph edges (body links are for human + foreign-agent reading). `cites` + `domain` + `links` are the
 retrieval index. Bodies read like a senior engineer explaining that one concept to a teammate.
 
 ---
@@ -296,7 +299,7 @@ A scan **PASSES only if every box below is true.** Any single failure → `itera
 - [ ] **C2** Every note answers ≥1 of the four questions. A note that only describes code = drop.
 - [ ] **C3** Every note has: `type` (convention|contract|flow|how-to), `domain`, ≥1 `cite`.
       Contracts also carry `failure: silent|loud`.
-- [ ] **C4** Contracts and flows `[[link]]` to the notes they touch — blast-radius and
+- [ ] **C4** Contracts and flows link (bundle-relative markdown) to the notes they touch — blast-radius and
       end-to-end flow are traversable by following links.
 
 **D · Format & contract**
@@ -317,5 +320,7 @@ targets the exact failing box.
   verified, or it doesn't ship. (Off-by-N lines, wrong-file attribution, missed sites.)
 - **Absence-claims** ("none yet", "greenfield") without an exhaustive repo-wide grep.
 - Uncited claims; notes that describe code but answer none of the four questions.
-- Literal `[[...]]` in prose (write `wiki-links` instead) — it pollutes the derived link graph.
+- Literal `[[...]]` in prose — legacy wikilinks are transpiled at emit when they resolve,
+  but AUTHOR bundle-relative markdown links (contract §11); a `[[...]]`-as-ellipsis literal
+  pollutes the link graph and lands in the checker's LINKS warn lane.
 - Silent truncation — if a domain is thin, say so.

package/blueprint/.claude/skills/rafa-validate/SKILL.md

@@ -78,7 +78,8 @@ agent. So:
 7. **Claim-truth check** — for a sample of notes, verify the note's *claim* matches the code
    (the checker only proved the cite *resolves*). A false/misleading claim → **blocker**
    (it violates the net-positive law: a wrong note is worse than none).
-8. **Connectivity** — orphan notes, dangling `[[links]]`, literal `[[...]]` in prose → minor.
+8. **Connectivity** — orphan notes, dangling links (the checker's LINKS warn lane —
+   `citation-check.md` § Links — is your pre-built worklist), literal `[[...]]` in prose → minor.
 
 ## Severity + decision
 - **Blocker** — hard-gate failure, broken checker, or a wrong/misleading note. Must be **0**.

package/lib/blueprint.mjs

@@ -43,6 +43,7 @@ export const BLUEPRINT = {
     ".claude/skills/rafa-insights",
     ".claude/skills/rafa-leverage",
     ".claude/skills/rafa-sage",
+    ".claude/skills/rafa-okf",
   ],
   lockstep: [".claude/rafa/contract.md"],
   // The M5 sensor hooks — deterministic protocol machinery (like the contract):