okf 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43476118366ed4610628f4692f1c1432e4babe4a9d5749f06eb69fc41738c4e5
-  data.tar.gz: 218144bd22483995d933cf9d89f44e9602c2c95255d9e1c95626700a4f5b2f2e
+  metadata.gz: 047d30628ab36abdfe517a2722753dc8f4a6eb60cea9a41d6015508d64784af6
+  data.tar.gz: 637ce26fbb8375b9c4d0daeab6ef6bdc8b8cee0258838e73151944b772445c47
 SHA512:
-  metadata.gz: 40ccd9ca9a9fe8580856825a972753b0f58ff2158fec6262db84d0b9d504e24c071a78e5b05939c0c5648ac7da67083621085417547ae194a0343ae1de34694b
-  data.tar.gz: 506f9d1feb6c6428c9db8845b4880207e904901636b35411b8b85f37dc909abb08b96d82246f06e410c97f6991ccfd947a559eed1d9c5b8d8e429b4790bd5929
+  metadata.gz: e30d74c10e269546cd81a433ff91b8f4f662540a81de9010de03c5e245d59eae3f7fff2743519379bbc2de53319501b2e517a6d7c613bf24d7e21a9ab447dd5d
+  data.tar.gz: 862d1454d20f6ff1f51e0f17829676becdf1503df42f2d6ca5bf9b0004437ba43e65f6db381bba14b0126f2f40bb3704a6f29c8e12bafc237d405612604610a8

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-08-17
+
+### Changed
+
+- **The skill's CLI reference is an index and seven leaves.** `reference/cli.md`
+  answered every question about every verb in one 46,234-byte file, so an agent
+  asking about `search` paid for `serve`, `registry` and the graph too. The
+  shared contract — refs, exit codes, `--json`, the filters — stays in `cli.md`
+  and routes to one file per surface under `reference/cli/`. Measured on the
+  worst question rather than the mean: 9,084 bytes for a routing question,
+  19,533 for the heaviest leaf. `reference/spec-map.md` is the other half, a
+  pointer from a spec clause to the file that answers it, so the vendored
+  `SPEC.md` keeps its index beside it instead of cut into it.
+- **Cross-file citations in the skill name a `rule:` marker**, not a section
+  anchor: the key travels with the paragraph the next time anything moves.
+- **`okf help` prints one row per extension**, plus a pointer to
+  `okf <verb> --help` for the rest. An addon with an umbrella verb and several
+  subcommands used to dwarf the built-ins the map exists to teach.
+
+### Added
+
+- **The skill teaches what a log records.** `log.md` carries durable knowledge
+  and shipped behavior, never the process that produced them —
+  `rule:okf-log-durable-only` in `reference/authoring.md`, cited by the maintain
+  playbook and the Closeout gate. It was the okf-gem repository's own contract
+  before this, which an agent maintaining any other bundle never reads.
+
 ## [2.0.0] - 2026-08-14
 
 > Major, not minor. The Breaking entries below change public shapes a shipped

data/README.md

@@ -158,9 +158,12 @@ without ever failing it.
 Publish a gem named `okf-*` carrying an `okf/plugin.rb` and installing it is the
 whole installation: your verb answers to `okf` and behaves like a built-in.
 Nothing an addon registers can displace one, and a broken addon is skipped rather
-than taking the CLI down. [`okf-mcp`](https://rubygems.org/gems/okf-mcp) is the
-first one — install it and `okf mcp` serves your bundles over the Model Context
-Protocol, with nothing in this gem naming it.
+than taking the CLI down. Three ship alongside this one, with nothing in this
+gem naming any of them: [`okf-mcp`](https://rubygems.org/gems/okf-mcp) serves
+your bundles over the Model Context Protocol,
+[`okf-tui`](https://rubygems.org/gems/okf-tui) browses them full-screen in a
+terminal, and [`okf-pro`](https://rubygems.org/gems/okf-pro) writes an
+agent's knowledge repository and enforces it at three doors.
 
 The graph page treats a bundle as untrusted content: inlined data is escaped and
 every concept body is sanitized before it reaches the DOM, so a script hidden in
@@ -171,8 +174,9 @@ do not know.
 ## More
 
 The [project README](https://github.com/serradura/okf-gem#readme) carries the
-diagrams, the comparison with `CLAUDE.md`, agent auto-memory and wikis, and the
-Claude Code plugin. The [docs](https://okfgem.com/docs/) are the manual. And the
+diagrams, the comparison with `CLAUDE.md`, agent auto-memory and wikis, the
+Claude Code plugin, and the way to install the skill into any agent without this
+gem (`npx skills add serradura/okf-gem`). The [docs](https://okfgem.com/docs/) are the manual. And the
 repo documents *itself* in OKF — clone it and run `okf server .okf` to read this
 gem's own knowledge as a graph.
 

data/lib/okf/cli.rb

@@ -92,7 +92,7 @@ module OKF
       [ :judge, nil ],
       [ :read, nil ],
       [ :graph, nil ],
-      [ :extension, "  installed extensions:" ]
+      [ :extension, "  installed extensions (`okf <verb> --help` for each):" ]
     ].freeze
 
     # Everything the map's grammar column cannot say for itself. A test finds the
@@ -476,13 +476,31 @@ module OKF
     end
 
     def print_group(io, group, heading)
-      rows = self.class.commands.reject(&:hidden?).select { |command| command.group == group }.flat_map(&:help_rows)
+      commands = self.class.commands.reject(&:hidden?).select { |command| command.group == group }
+      rows = group == :extension ? extension_rows(commands) : commands.flat_map(&:help_rows)
       return if rows.empty?
 
       io.puts heading if heading
       rows.each { |left, desc| io.puts "  #{left.to_s.ljust(56)}#{desc}" }
       io.puts
     end
+
+    # One line per extension, whatever it declares — its FIRST row, which is why
+    # an addon's first row should be its summary.
+    #
+    # Enforced here rather than asked of each addon, because a rule an addon has
+    # to remember is a rule this map cannot rely on. An umbrella verb is a shape
+    # an addon legitimately has — the built-in `registry` has it too — and one
+    # arriving with eight subcommands made this block the longest section on the
+    # page, dwarfing the built-ins above it and burying the single-line addons
+    # beside it.
+    #
+    # A built-in keeps every row: those are this gem's own surface, they are what
+    # the map exists to teach, and there is no second place to read them. An
+    # extension has one — `okf <verb> --help`, which the heading points at.
+    def extension_rows(commands)
+      commands.map { |command| command.help_rows.first }.compact
+    end
   end
 end
 

data/lib/okf/skill/SKILL.md

@@ -96,11 +96,18 @@ The one trap worth carrying in your head: **the age cutoff is off by default**
 a plain `okf lint` reports concepts past their own declared `stale_after` (the
 `expired` check reads the clock the CLI supplies), but never judges *age*; pass
 `--stale-after <90d|12w|ISO-date>` when you want anything not touched since then
-flagged too. <!-- check:stale -->
-
-Read [cli.md](reference/cli.md) before *interpreting* a verb's output in depth:
-what `validate` may and may not reject, lint's categories and check ids, the JSON
-shapes, the tag-curation views, the server's trust boundary.
+flagged too — the two mechanisms share a spelling and nothing else
+([cli/checks.md](reference/cli/checks.md), rule `okf-two-clocks`).
+<!-- check:stale -->
+
+Read [cli.md](reference/cli.md) before *interpreting* a verb's output in depth.
+It is the index and the shared contract — refs, exit codes, `--json`, the
+filters — and its table routes to the one file the verb lives in:
+[checks](reference/cli/checks.md) (what `validate` may and may not reject, lint's
+categories and check ids), [search](reference/cli/search.md),
+[map](reference/cli/map.md) (`index`/`dirs`), [views](reference/cli/views.md)
+(the tag-curation views), [serve](reference/cli/serve.md) (the trust boundary),
+[registry](reference/cli/registry.md), [graph](reference/cli/graph.md).
 
 ## Orient before you touch anything
 
@@ -123,8 +130,9 @@ playbooks (the Commands table below; no `okf` installed? read the root
 `consume` (use it as context) carry the judgment the executable can't — this is
 where the skill earns its keep. Each has a playbook (the Commands table below);
 read the modelling craft in [authoring.md](reference/authoring.md) before
-producing or maintaining, and the verbatim spec [SPEC.md](reference/SPEC.md)
-when you need chapter and verse.
+producing or maintaining. When you need chapter and verse, go through
+[spec-map.md](reference/spec-map.md) — which § settles which question — into the
+verbatim [SPEC.md](reference/SPEC.md).
 
 **No subcommand?** Infer intent: "document this / capture X" → `produce`;
 "convert / migrate / OKFy these existing docs into a bundle" → `migrate`; "the

data/lib/okf/skill/playbooks/maintain.md

@@ -25,7 +25,9 @@ lives in [authoring.md](../reference/authoring.md).
    silently deleting the context that explains them.
 4. **Update every enumeration that names what you changed — including `index.md`
    bodies**, not just the concept files: a new, renamed, or removed concept changes
-   its directory's index listing too. Append a dated `log.md` entry. Step 1's map
+   its directory's index listing too. Append a dated `log.md` entry — what changed and why it
+   matters, never the rounds it took (rule `okf-log-durable-only` in
+   [authoring.md](../reference/authoring.md)). Step 1's map
    is how you verify this — re-run `okf index` and confirm each listing matches
    reality.
 5. Run `validate`, then `lint` to catch the curation drift the change introduced —

data/lib/okf/skill/playbooks/produce.md

@@ -4,7 +4,8 @@ The craft that makes these steps land well — granularity, choosing `type`, tag
 vocabulary, topology, links, sources — lives in
 [authoring.md](../reference/authoring.md). Read it before a non-trivial produce.
 
-1. Read [SPEC.md](../reference/SPEC.md) if you are unsure of any rule.
+1. Unsure of a rule? [spec-map.md](../reference/spec-map.md) names the § that
+   settles it; read that section of [SPEC.md](../reference/SPEC.md).
 2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings,
    config), **docs/wiki** (distill pages into concepts; record the originals in
    `sources:` and key claims with `[^id]` footnotes), **manual** (decisions,
@@ -27,5 +28,6 @@ vocabulary, topology, links, sources — lives in
    `okf_version: "0.2"`. Append a dated entry to `log.md`.
 6. **Close out** — walk the
    [Closeout gate](../reference/authoring.md#closeout--the-finishing-gate)
-   (`validate` + `lint` are part of it, see [cli.md](../reference/cli.md))
+   (`validate` + `lint` are part of it, see
+   [cli/checks.md](../reference/cli/checks.md))
    before finishing.

data/lib/okf/skill/reference/authoring.md

@@ -1,33 +1,13 @@
 # Authoring OKF well — the craft
 
-The spec ([SPEC.md](SPEC.md)) tells you what is *legal*. This file is what is
-*good* — the modelling judgment that turns a pile of conformant files into
+The spec ([SPEC.md](SPEC.md)) tells you what is *legal*, and
+[spec-map.md](spec-map.md) says which § settles which question. This file is
+what is *good* — the modelling judgment that turns a pile of conformant files into
 knowledge worth consuming. Read it before `produce` or `maintain`, and keep the
 §11 conformance rules in mind (parseable frontmatter, a non-empty `type`, and
 well-formed reserved files — the hard rules in [SKILL.md](../SKILL.md));
 everything else is guidance a consumer must tolerate.
 
-## What each SPEC section governs
-
-Consult the right section on demand instead of re-reading all of [SPEC.md](SPEC.md):
-
-| § | Governs | Reach for it when |
-|---|---------|-------------------|
-| §3 | bundle structure, reserved filenames | laying out directories |
-| §4 | concept documents & frontmatter | writing or validating a concept |
-| §5.1 | provenance — `sources` and its credibility signals | any external or empirical claim |
-| §5.2 / §5.3 | trust — `generated`, `verified`, and the derived tiers | recording who wrote or confirmed content |
-| §5.4 / §5.5 | lifecycle — `status`, `stale_after` | marking drafts, deprecations, expiries |
-| §6 / §6.1 | cross-links; **broken links are tolerated** | linking; judging a "broken" link |
-| §6.2 / §6.3 | path-valued fields; the `references/` convention | pointing at non-concept assets |
-| §7 | the actor convention | filling any `by` |
-| §8 | index files & progressive disclosure | orienting; writing or synthesizing an index |
-| §9 | log files | recording history |
-| §10 | attested computations | a concept that *is* a sanctioned computation |
-| §11 | conformance — the hard gate | what `validate` may and may not reject |
-| §12 | versioning (`okf_version`) | the root index's one allowed field |
-| §13 | changes from v0.1 | migrating a bundle; reading an unmigrated one |
-
 ## Modelling principles
 
 These are the decisions that make or break a bundle. None are enforced by the
@@ -177,7 +157,8 @@ declare it only when it says something. `stale_after` is an absolute
 the day itself. Use it for knowledge with a known shelf life (a quota, a
 migration window); `lint`'s `expired` check reports the ones whose date has
 passed. It is a declared expiry, distinct from the `--stale-after` *flag*,
-which is a reader-supplied age cutoff — see [cli.md](cli.md).
+which is a reader-supplied age cutoff — see [cli/checks.md](cli/checks.md),
+rule `okf-two-clocks`.
 
 ### Capture the non-obvious — not what code already says <!-- rule:okf-non-obvious -->
 A bundle that restates function signatures or config keys goes stale the moment
@@ -217,6 +198,21 @@ concepts. Templates: [concept](../templates/concept.md),
 nested [index](../templates/index.md), bundle-root
 [root-index](../templates/root-index.md), [log](../templates/log.md).
 
+### The log records what shipped, not how it shipped <!-- rule:okf-log-durable-only -->
+`log.md` carries durable knowledge and shipped behavior — never the process that
+produced them. A bug fixed in a release is an entry; the review rounds that found
+it are not. A capability that shipped is an entry; the iterations it took to
+stabilize it before it shipped are not. When a change taught a lesson, the lesson
+belongs in the concept it is about, stated as a principle, and the log entry
+*points* at that concept instead of re-narrating the rounds — a reader finds it
+where the subject lives, not by reading history.
+
+The bar is what a reader six months out needs: *what changed and why it matters*,
+never *how many passes it took to get there*. Watch for the shape this invites —
+the newest entries sit at the top where every reader lands, so a stretch of work
+stabilized by iteration accretes "round N found M defects" exactly where a durable
+summary belongs.
+
 ## Migrating from v0.1 (§13)
 
 A v0.1 bundle is consumable forever — §13.1 sanctions reading `timestamp` as
@@ -237,7 +233,7 @@ verb (search, produce, migrate, maintain, consume, curate, doctor), routed by th
 Commands table in [SKILL.md](../SKILL.md). The Closeout below is their shared
 finishing gate.
 
-## Closeout — the finishing gate
+## Closeout — the finishing gate <!-- rule:okf-closeout-gate -->
 
 `produce` step 6 and `maintain` steps 4–7 both land here: before calling an
 authoring task done, walk this once. It is the repo's "turn every task into a check
@@ -247,7 +243,8 @@ grep can't:
 - **Index enumerations** — every `index.md` that lists what you added, renamed, or
   removed is updated; re-run `okf index` and eyeball each listing against reality.
   Easy to skip, expensive to miss — this is the check that was missing.
-- **`log.md`** — a dated entry, newest first.
+- **`log.md`** — a dated entry, newest first, and durable only (rule
+  `okf-log-durable-only` above).
 - **`generated.at`** bumped on the concepts you touched (and `generated.by` says
   who touched them — you, in §7's spelling).
 - **`validate`** — zero §11 errors.

data/lib/okf/skill/reference/cli/checks.md

@@ -0,0 +1,171 @@
+# Checking a bundle — `validate`, `lint`, `loose`, `references`
+
+Kind: reference. Answers: what makes a bundle non-conformant, what each lint
+check means and the severity it is pinned at, which of the two clocks a flag
+reads, and which dangling pointers each surface can and cannot see.
+
+The shared contract — `@slug` refs, exit codes, `--json`, the filters — is in
+[cli.md](../cli.md) and is not repeated here.
+
+## validate — the hard gate (§11)
+
+Implements the spec's §11 conformance definition exactly (its words are in
+[SPEC.md](../SPEC.md), routed by [spec-map.md](../spec-map.md)):
+
+- **§11 cond. 1** every non-reserved file has a parseable YAML frontmatter block;
+- **§11 cond. 2** every such block has a non-empty `type`;
+- **§11 cond. 3** any `index.md`/`log.md` present follows §8/§9 (a nested
+  `index.md` has no frontmatter, a root `index.md` carries only `okf_version`,
+  `log.md` date headings are ISO `YYYY-MM-DD`).
+
+`ERROR`s are the three conditions above; the bundle is non-conformant until every
+one is fixed. `warn`s are soft — missing recommended fields, non-list tags, an
+unparseable timestamp, **broken cross-links, which §6.1 explicitly tolerates**,
+the shape of every §5/§10 family (`generated` not a mapping, a non-integer
+`usage_count`, a `stale_after` that is not `YYYY-MM-DD`, a missing `runtime` on
+an Attested Computation, …), and an `okf_version` the gem does not know (read
+best-effort under §12; an absent one never warns). Absence of an optional family
+is never a fault — a pure v0.1 bundle validates with zero warnings.
+
+In `--json`, every warning carries `check` (a stable id) and `source` — `spec`
+when the SPEC's own words state the rule, `convention` for a shape this gem asks
+for beyond them (`verified[].by` presence, integer `usage_count`, a per-entry
+`usage_window` mapping, `parameters[].name`, `executor`/`attester` `resource`).
+Gate on `source` when you want only the spec-normative set; errors keep their
+two-key `{ path, message }` shape. Fix warnings when cheap; never block on them.
+Use `--json` in CI.
+
+## lint — curation quality (advisory)
+
+Asks the complementary question to `validate`: not "is this legal OKF?" but "is
+this well-curated, navigable, trustworthy?" — precisely over the things §11
+forbids `validate` from rejecting. It has its own report, never emits
+conformance errors, and **exits `0` even with findings** unless you pass
+`--fail-on warn` (exit 1 on any `warn` finding) or `--fail-on info` (exit 1 on
+any finding at all).
+
+**Severity is API.** Every check has a pinned level — `warn` or `info` — and
+machine consumers gate on it, so the levels below are stable, not advisory. A
+finding you want to gate on that is `info` gets `--fail-on info` (usually with
+`--only`), never a hope that its severity changes. <!-- rule:okf-severity-is-api -->
+
+Eight categories, each backed by individual checks (severity in brackets):
+
+- **Reachability** — `orphan` [warn], `not_in_index` [warn],
+  `disconnected_component` [info], `unlinked` [info]
+- **Backlog** — `missing_concept` [info], `broken_index_entry` [warn]
+- **Completeness** — `stub` [info], `missing_title` [info],
+  `missing_description` [info], `missing_generated` [info] (quiet on either
+  spelling — a legacy `timestamp` still counts as a recorded change)
+- **Freshness** — `expired` [info] (§5.5: past the concept's own declared
+  `stale_after`, on the day itself), `stale` [warn] (older than the
+  reader-supplied `--stale-after` cutoff, keyed on `generated_at`)
+- **Provenance** — `uncited_external` [info] (external body links and no
+  sources, in either spelling), `broken_source` [warn] (an in-bundle `.md`
+  source target that names no concept; URLs and scope descriptors are out of
+  scope, and a non-`.md` asset is out of reach — the reader models concepts,
+  so lint never sees the file; `okf references` is the view that checks those
+  pointers), `unattributed_claim` [warn] (a footnote
+  no `sources[].id` answers — it *misattributes* a claim, which is why it
+  outranks its join-twin), `unused_source` [info] (a keyed source no footnote
+  cites — slack, not a defect), `unprefixed_actor` [info] (a `verified[].by`
+  outside §7's three forms reads as machine-confirmed; a `generated.by`
+  outside them feeds no tier but leaves a reader unable to tell a person
+  from a process; info so it informs, never blocks). A missing `generated.by` is the *validator's* warning —
+  REQUIRED-within is shape, not curation — so lint never double-reports it
+- **Attestation** — `incomplete_computation` [warn] (an Attested Computation
+  providing its computation neither way, or both ways — §10.3 says a
+  `computation:` path is used *instead of* the body fence),
+  `broken_attestation_ref` [warn] (on an `Attested Computation`, a
+  `computation`, `executor.resource` or `attester.resource` naming an
+  in-bundle `.md` that is not there — a contract no consumer can follow; the
+  keys are read only on that type, since §4.1 lets any other concept use them
+  for its own purpose). Its reach is exactly the `.md` files: URLs are out
+  of scope, and a `.sql` or `.py` target is invisible to *every* check here,
+  because the linter reads the concept model and the model carries only
+  markdown — `okf references` is the surface that sees those files and reports
+  a pointer that misses, whatever the extension. Remember §6.2 reads a bare
+  `references/…` as relative to the concept, so from a nested concept it wants
+  the leading `/`
+- **Migration** — `legacy_timestamp` [info], `legacy_citations` [info]: one
+  finding per bundle naming the files still in a retired v0.1 spelling, with
+  the rewrite instructions in the message. Info on purpose — §13 says a v0.1
+  bundle is consumable forever, so `--fail-on warn` must not turn red on one.
+  A migration campaign gates explicitly:
+  `okf lint <dir> --only legacy_timestamp,legacy_citations --fail-on info`,
+  exit 1 until clean.
+- **Hygiene** — `duplicate_title` [info], `unused_reference_def` [info],
+  `undefined_reference` [warn], `self_link` [info], `log_order` [info] (§9
+  reads a log newest-first; disorder is slack, never a §11 error)
+
+`--only` / `--except` filter by the **individual check names above**, not the
+category labels — `okf lint <dir> --only orphan,stub` works; `--only reachability`
+is an error. Two knobs tune specific checks: `--min-body N` sets the `stub` body
+threshold in characters (default 50), and `--stale-after DUR` sets the `stale`
+cutoff — a duration like `90d` or `12w`, or an ISO date like `2026-01-01` (a bare
+number is rejected).
+
+**Two different clocks, one unlucky name.** The `--stale-after` *flag* and the
+`stale_after:` *frontmatter field* are different mechanisms that happen to share
+a spelling. The flag is the **reader's** age cutoff: "flag anything not touched
+since DUR", keyed on `generated_at`, feeding the `stale` check. The field is the
+**author's** declared expiry: "do not trust this past DATE", feeding the
+`expired` check. Never read one as the other, and never show them adjacent
+without the distinction. <!-- rule:okf-two-clocks -->
+
+**The clock is explicit.** `expired` compares against a day the CLI supplies —
+today by default, or `--today YYYY-MM-DD` for a reproducible report (CI wants
+this). The pure library runs no clock check unless handed `today:`, and every
+clock-gated check that was selected but could not run is *named* in
+`stats.skipped_checks` (the human report prints one `skipped:` line) — a gate
+that is sometimes absent and does not confess converts "unchecked" into
+"checked and fine".
+
+The report's stats carry the bundle's posture too: `trust` (the §5.3 tier
+distribution, in the hyphenated wire spelling) and `status` (effective-status
+frequency).
+
+`lint --json` is the structured substrate you consume to reason about the two
+things lint deliberately does **not** compute — contradictions and *semantic*
+staleness — which need understanding of meaning.
+
+## loose — files with no graph connections (by folder)
+
+Lists the **loose** files — concepts with graph **degree 0**: no cross-links in
+*or* out — grouped by folder. It is a focused, folder-organized view over `lint`'s
+`unlinked` check (`okf loose <dir>` ≈ `okf lint <dir> --only unlinked`, regrouped),
+for the "which files float in the graph?" question. Advisory: **exits `0`**; `--json`
+emits `{ bundle, count, loose: [{ id, title, dir }] }`.
+
+**Loose ≠ orphan** — the trap. `lint`'s `orphan` is about *reachability*, and an
+`index.md` listing makes a file reachable, so an indexed file is never an orphan.
+But an index listing is **not a graph edge**: a file can be listed in an index yet
+have no cross-links, so it floats in the graph while `lint` reports it as reachable.
+`loose`/`unlinked` catch exactly that gap. A loose file is not automatically a
+defect — a terminal leaf (a backlog item, a spec reference) can be loose by design;
+`loose` surfaces the set so you can judge intent (see the
+[maintain playbook](../../playbooks/maintain.md)).
+<!-- rule:okf-loose-not-orphan -->
+
+## references — the `references/` inventory (§6.3)
+
+Lists every file under `references/` — including the non-markdown ones no other
+verb can see, since the concept model carries only markdown — with which
+concepts cite each file through the §6.2 path-valued fields (`resource`,
+`sources[].resource`, `computation`, `executor.resource`, `attester.resource`),
+plus every pointer into `references/` that resolves to nothing. Advisory:
+**exits `0`** even with dangling pointers — the findings are the output. JSON:
+`{ bundle, dangling, count, references: [{ path, dir, kind, referenced_by }] }`,
+with `--fields`/`--except` projecting the rows. A file that is itself a concept
+(§6.3 allows both) is marked `kind: "concept"`; body links are the graph's
+business and are not counted here.
+
+**The dangling list is where §6.2's bare-path trap surfaces.** A bare
+`references/attesters/rev.py` written from `metrics/` resolves relative to the
+concept — `metrics/references/attesters/rev.py`, nothing — and when the
+leading-slash spelling would have hit, the entry says so:
+`/references/attesters/rev.py exists — missing leading slash?`. Reach is any
+extension, which is exactly what `broken_source` and `broken_attestation_ref`
+cannot offer (their exemptions above), so run it wherever a bundle carries
+attester code or computation files.
+

data/lib/okf/skill/reference/cli/graph.md

@@ -0,0 +1,49 @@
+# `graph` — the raw structure
+
+Kind: reference. Answers: what a full dump costs and how to plan a traversal
+without paying it, plus the two rankings that give `refine` its evidence —
+`--hubs` by concept, `--traffic` by directory.
+
+The shared contract — `@slug` refs, exit codes, `--json` — is in
+[cli.md](../cli.md) and is not repeated here.
+
+Prints the node/edge graph. `--json` emits a machine-readable dump — the
+`bundle`/`slug` head every view carries, then `nodes` (with
+`id`/`type`/`title`/`description`/`tags` **and, by default, every `body`** — the
+part that dominates the bytes on a real bundle) plus `edges` — you can pipe into
+other analysis. A concept with a missing *or blank* `type` indexes under
+`Untyped`: §11 condition 2 rejects both identically, so both land in one bucket. To *plan* a traversal, structure is all you need: `--no-body`
+drops each node's body, and `--minimal` ships only `id`/`title` plus the type/tag
+indexes — the lean shape the `server` page boots from. Reach for the full dump
+only when the task truly consumes every body; for one question, the
+[search verb](search.md) is orders cheaper.
+
+`--hubs` swaps the dump for the **inbound ranking**: every concept with at
+least one inbound link, ranked by inbound degree, each with its links grouped
+by *source top-level dir* (`core/status  ×3   flows 2, billing 1`) — the evidence for
+[refine](../../playbooks/refine.md)'s hub origin test ("is this hub well-homed?").
+A source at the bundle root counts under `(root)`. JSON: `{ bundle, count,
+hubs: [{ id, top_dir, inbound, by_top_dir: { <top_dir>: n } }] }`. Advisory read, exit 0;
+`--minimal`/`--no-body` shape node payloads and change nothing here.
+
+`--traffic` asks the same question one grain coarser: **directories**, not
+concepts. Every concept collapses into the directory it lives in and every link
+between two directories collapses into one weighted arc, so a bundle's wiring
+becomes a table you can read — measured on one 47-concept bundle, 227 links
+collapsed into 50 arcs, of which the fitted cut draws 22. Each row carries the
+directory's traffic split three ways
+(`internal` / `out` / `in`) plus **cohesion**, its internal share of the total:
+the evidence for [refine](../../playbooks/refine.md)'s container test, where
+`--hubs` only ever answered about concepts. Rows lead with the lowest cohesion,
+so the directories with a case to answer come first, and a directory with no
+traffic at all prints `—` rather than a `0%` it did not earn.
+
+`--cut N` is the least arc weight drawn. It defaults to a value **fitted to the
+bundle** — enough arcs for roughly 1.5 per directory, floored at 8 — because a
+fixed weight cannot serve both ends: measured at weight 3 across ten bundles it
+left 2 arcs on one and 136 on another. The JSON says which you got. Cohesion is
+computed over *every* arc and never the drawn ones, so tightening the cut
+changes the picture and never the evidence. JSON: `{ bundle, cut, fitted, dirs:
+[{ dir, parent, count, subtree, internal, out, in, cohesion }], arcs: [{ source,
+target, weight }], total_arcs }` — a fraction of the full dump (2.6 KB against
+27 KB on that bundle), and the shape rather than the contents. Advisory, exit 0.

data/lib/okf/skill/reference/cli/map.md

@@ -0,0 +1,98 @@
+# Orienting — `index` and `dirs`
+
+Kind: reference. Answers: which view to run first on a bundle you do not know,
+how `--dir`, `--depth` and the ancestor chain compose, what a synthesized
+listing means, and how to keep the map from paging the whole bundle.
+
+The shared contract — `@slug` refs, exit codes, `--json`, the filters — is in
+[cli.md](../cli.md) and is not repeated here.
+
+## index — the progressive-disclosure map (§8)
+
+The "orient before you read" view, and the read verb that sees the layer the
+concept views can't: `index.md` files are reserved/structural, so
+`catalog`/`files`/… never show them (in the browser, the Indexes tab and
+folder clicks render this same map). `okf index <dir>` prints one entry per directory
+that holds concepts or carries an `index.md`, root first — the authored index body
+(frontmatter stripped), a `type`/`tag` rollup over the concepts that live directly
+there, its child directories, and the concept listing. Run it first when picking up
+an existing bundle: it is the cheapest high-signal orientation, and it surfaces
+enumeration drift a grep can't (you can't grep for a listing entry that is *missing*).
+
+`--dir PATH` narrows to a directory **and everything below it**, and is
+**repeatable** — `--dir model --dir format` shows both; `root` (or `.`) names the
+bundle root, unless the bundle really has a `root/` directory, which owns the
+word. A `--dir` also brings the **chain from the root down to it**, so a branch is
+never shown adrift of the authored context that says what it is — the root
+`index.md`'s prose first among it. Those rows print with a leading `↑` and carry
+`ancestor: true`; `--no-ancestors` drops them. Ascent and descent are separate
+axes, so `--depth` never bounds the chain: `--dir X --depth 0` is X alone, plus
+how you get to X. A `--dir` that names nothing gains no chain — a lone root row
+would read as a partial answer to a query that matched nothing.
+
+`--depth N` bounds how far below the starting point the map reaches
+(the `--dir` when one is given, else the bundle root), counted **relatively**:
+`--depth 1` is the top of the tree, `--dir X --depth 1` is one branch of it, and
+the pair walks down a level at a time.
+
+**On a bundle of any size the map is unreadable whole** — every directory is a
+section, and even `--no-body` keeps one listing row per *concept* — so narrow
+rather than paging it: `okf dirs` is the orientation, `--dir <branch> --depth 1`
+is the step down into it,
+and `--except body,listing` on top of either is the lean JSON skeleton. Full
+`index` output on a few hundred concepts runs to hundreds of KB; the same map at
+`--depth 1` is a couple of KB.
+
+`--no-body` drops the prose to a
+skeleton (headers, rollups, child pointers). For a directory that has concepts but
+**no `index.md`**, the listing is **synthesized** from the concepts' descriptions
+and tagged `(no index.md)` — §8 explicitly permits synthesizing a map on the fly.
+
+It is a **read view**: advisory, always exit 0. A synthesized directory is a
+*signal* (a map worth writing), never a defect — `index` emits no lint findings and
+never fails a bundle. JSON: `{ bundle, count, directories: [{ dir, index_path,
+present, synthesized, count, types, tags, subdirs, body, listing: [{ id, title,
+description, type, tags }] }] }` — `ancestor` marks a row that is there to place
+the branch rather than to answer about it.
+
+## dirs — the bundle's clusters and their sizes
+
+`okf dirs <dir>` lists every directory the bundle has — the ones holding
+concepts, the ones carrying an `index.md`, and the empty intermediates that only
+exist to connect the tree — with the number of concepts living **directly** in
+each and the number in its **subtree**. A cluster *is* a directory here, so this
+is the view that tells you what `--dir` can be pointed at and how much sits
+behind each choice.
+
+Two numbers, because one cannot answer the question. `count` is direct, so the
+column sums to the bundle's concept total and a dir holding only sub-directories
+reads `0` rather than a hidden rollup. `subtree` is defined as *exactly what
+`--dir <that row>` returns*, so the row and the flag can never disagree — which
+is also why the root's subtree is its own direct count (`.` is a prefix of
+nothing). Without it a truncated listing is all zeroes at the top of a deep tree,
+which is where you most need to know where the mass is. The human table shows the
+second column only where some dir actually nests.
+
+`--dir PATH` (repeatable) narrows to a directory and its subtree, and brings the
+**chain up to the root** with it so the branch is placed rather than shown
+adrift — those rows are marked `↑`, carry `ancestor: true`, and stay out of
+`total` (`--no-ancestors` drops them). `--depth N` keeps only N levels below the
+starting point — the `--dir` when one is given,
+the bundle root otherwise. Relative, not absolute, so `--dir a/b --depth 1`
+reads "a/b and one level under it" without your first working out how deep `a/b`
+is. `--depth 0` is the starting point alone. A `--depth` that is not a whole
+number is a usage error (exit 2).
+
+**This is the first command to run on a bundle you do not know** — the same first
+move [SKILL.md](../../SKILL.md) prescribes. `okf dirs <dir>` is one row per
+directory, so its size tracks the tree rather than the concept count: it tells
+you the shape and where the weight sits, `--depth 1` trims it further on a deep
+bundle, and you then descend with `okf index --dir`, one level at a time.
+
+The root prints `(root)` and stores `.` — the split every grouped view keeps, so
+a table and its `--json` never disagree about which spelling is the data. JSON:
+`{ bundle, total, count, dirs: [{ dir, ancestor, count, subtree, subdirs }] }`,
+root first. `count` is rows printed, chain included; `total` sums the direct
+counts of the rows you actually asked for, which is what keeps a row's `subtree`
+equal to the `total` that `--dir` on that row returns.
+