okf 2.1.0 → 2.2.0

data/.okf/capabilities/index.md

@@ -0,0 +1,26 @@
+# Capabilities
+
+The seven things the baseline gem does over a bundle, plus the read views that
+print it at a glance — and the sibling surfaces built on the same kernel. All of
+them run over the same [pure model](../model/); the gem's own are fronted by the
+[CLI](../cli.md).
+
+# Judge
+
+* [Conformance validator](validator.md) - the §11 legal check; the only capability that can fail a bundle.
+* [Curation linter](linter.md) - advisory quality report across eight categories; never rejects.
+
+# Serve & read
+
+* [Interactive graph server](graph-server.md) - a self-contained HTML graph over HTTP — one bundle or many behind a hub — mountable as a Rack app.
+* MCP server (`@okf-mcp design/the-tool-set`) - the sibling `okf-mcp` gem: the kernel's capabilities as MCP tools, resources and prompts for any agent host.
+* [Bundles manager](bundles-manager.md) - the hub's `/b/` page: every bundle with its size, health and default marker, and the forms that manage the registry from a browser.
+* [Static render](render.md) - the same page written to one self-contained static file, the bundle baked in, to host where there is no server (`okf render`).
+* [Read views](read-views.md) - `index`, `catalog`, `files`, `types`, `tags`, `stats`, `loose`, `graph` — the browser views as text, plus the `index` map.
+* [Ranked text search](search.md) - deterministic ranked retrieval over metadata and bodies; answers "which concept covers X?" in a few rows.
+
+# Use & author
+
+* [Library API](library-api.md) - the Ruby surface: pure model plus on-disk handles.
+* [Companion agent skill](agent-skill.md) - the skill shipped inside the gem that teaches an agent to author OKF.
+* Enforcement layer (`@okf-eco gems/okf-pro`) - the sibling `okf-pro` gem: writes an agent's knowledge repository, then holds it to a few invariants at three doors under a fail-closed contract.

data/.okf/capabilities/library-api.md

@@ -0,0 +1,82 @@
+---
+type: Capability
+title: Library API
+description: The Ruby surface — a pure in-memory model plus on-disk handles, an "ActiveRecord for the filesystem".
+resource: gems/okf/lib/okf.rb
+tags: [ruby, diagram]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: README.md — Library
+    resource: https://github.com/serradura/okf/blob/main/README.md
+  - title: gems/okf/lib/okf.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf.rb
+---
+
+# Overview
+
+Everything the [CLI](../cli.md) does is available in-process. `require "okf"`
+gives you two layers, split cleanly by the [core/shell rule](../design/core-shell-split.md):
+
+- **pure, in-memory** — [`OKF::Concept`](../model/concept.md) and
+  [`OKF::Bundle`](../model/bundle.md), which you build, interrogate, validate,
+  lint, and graph with **no disk involved**;
+- **on-disk handles** — `OKF::Concept::File` and `OKF::Bundle::Folder`, which add
+  `load` / `save` / `reload` / `delete` on top of the pure model.
+
+`require "okf"` stops at those two layers: the [CLI](../cli.md) and the skill
+installer load only when asked for (from `okf/exe/okf`, or an explicit
+`require "okf/cli"` / `require "okf/skill"`), so an app embedding the library
+never drags in the command-line machinery. The
+[registry](../registry.md) and the server's hub sit behind the same door — the CLI
+requires them at the moment a registry verb or a multi-bundle `server` runs, so
+the library surface stays the same size no matter what the executable grows.
+
+```mermaid
+classDiagram
+  class Concept {
+    <<pure>>
+  }
+  class Bundle {
+    <<pure>>
+  }
+  class Graph {
+    <<pure>>
+  }
+  class ConceptFile {
+    <<on-disk>>
+  }
+  class Folder {
+    <<on-disk>>
+  }
+  Bundle "1" o-- "*" Concept : contains
+  Bundle ..> Graph : builds
+  ConceptFile ..> Concept : wraps
+  Folder ..> Bundle : wraps
+```
+
+`ConceptFile` is `OKF::Concept::File`; `Folder` is `OKF::Bundle::Folder` — each
+on-disk handle wraps a pure counterpart and adds load/save/reload/delete.
+
+# Build knowledge without touching Markdown
+
+The pure layer is the surface an embedding app uses to reuse the gem over
+knowledge it already holds as records. Construct concepts from data, assemble a
+bundle, and call `#validate`, `#lint`, or `#graph` — no Markdown round-trip
+needed. The lower-level pieces work standalone too:
+`OKF::Bundle::Validator.call`, `OKF::Bundle::Linter.call`,
+`OKF::Bundle::Search.call`, `OKF::Bundle::Graph.build`,
+`OKF::Markdown::Frontmatter.parse`.
+
+# Folder is an ActiveRecord for the filesystem
+
+`OKF::Bundle::Folder.load(dir)` reads a directory into a pure bundle;
+`Folder.new(bundle:, root:).save` materializes one back — and **validates §11
+before publishing** through an atomic writer, so it never leaves a broken bundle
+on disk. `OKF::Server::App.new(folder)` turns a folder straight into the
+[graph server](graph-server.md) — mountable anywhere, and the one option a mount
+owns is `search_endpoint:`, since the page resolves it against the reader's URL
+and only the host knows its own prefix (the `/search` route answers either way).
+And `OKF::Render::Graph.static(folder)` bakes that
+same page into one self-contained file — the Ruby side of [`okf render`](render.md).

data/.okf/capabilities/linter.md

@@ -0,0 +1,83 @@
+---
+type: Capability
+title: Curation linter (lint)
+description: An advisory curation-quality report across eight categories and twenty-six checks — pinned severities, an explicit clock, and it never rejects a bundle.
+resource: gems/okf/lib/okf/bundle/linter.rb
+tags: [curation, cli]
+generated:
+  by: human:maintainer
+  at: 2026-08-14T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle/linter.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/linter.rb
+---
+
+# Overview
+
+`okf lint` answers the question [validate](validator.md) is forbidden to touch:
+*is this bundle well-curated — navigable, complete, trustworthy?* It reports over
+exactly the soft things §11 tolerates, has its own `OKF::Bundle::Linter` and
+report, and never emits a conformance error. It is **advisory**: exit `0` even
+with findings unless you opt in with `--fail-on warn` (any warn) or
+`--fail-on info` (any finding at all).
+
+# Eight categories, twenty-six checks — with pinned severities
+
+| Category | Checks |
+|----------|--------|
+| Reachability | `orphan`, `not_in_index`, `disconnected_component`, `unlinked` |
+| Backlog | `missing_concept`, `broken_index_entry` |
+| Completeness | `stub`, `missing_title`, `missing_description`, `missing_generated` |
+| Freshness | `expired`, `stale` |
+| Provenance | `uncited_external`, `broken_source`, `unattributed_claim`, `unused_source`, `unprefixed_actor` |
+| Attestation | `incomplete_computation`, `broken_attestation_ref` |
+| Migration | `legacy_timestamp`, `legacy_citations` |
+| Hygiene | `duplicate_title`, `unused_reference_def`, `undefined_reference`, `self_link`, `log_order` |
+
+`log_order` is the first log-side check: §9 describes the log as date-grouped
+entries newest first — prose, not an RFC keyword, so disorder is curation
+slack here, never a [validator](validator.md) error, and only shape-valid
+headings are compared (a malformed date is already the validator's, reported
+once). `unprefixed_actor` reads both §7 identity fields with one consequence
+each: a bare `verified[].by` reads as machine-confirmed (the §5.3 misread the
+tier system exists to prevent), while a bare `generated.by` feeds no tier and
+costs the audit trail — nobody downstream can tell a person from a process.
+
+**Severity is API.** Every id has a pinned level in one tested constant
+(`Linter::SEVERITIES`): machine consumers gate repo edits and CI on `:warn`
+and drop `:info`, so a severity change is a behavior change for them — a new
+gateable state gets a flag (`--fail-on info`), never a severity promotion.
+Two of the calls carry their argument in the code: `unattributed_claim` warns
+while its join-twin `unused_source` informs (a dangling footnote misattributes
+a claim; an uncited source is only slack), and `expired` informs because a
+`stale_after` passes on the calendar, not on a change — a warn would fail a
+`--fail-on warn` gate on a morning nobody chose. The Migration pair is info
+for the same reason: §13 says a v0.1 bundle is consumable forever, and a
+migration campaign gates explicitly with
+`--only legacy_timestamp,legacy_citations --fail-on info`.
+
+Select with `--only` / `--except` (by check id), tune the stub threshold with
+`--min-body`, and get the whole report as a machine substrate with `--json` —
+which also carries the bundle's posture: a `trust` tier distribution (in the
+hyphenated wire spelling) and an effective-`status` frequency.
+
+# The clock contract
+
+The linter is pure and never reads a clock: `expired` runs only when the
+caller supplies `today:` (the CLI passes today, or `--today YYYY-MM-DD` for a
+reproducible report), and `stale` only when `--stale-after
+<90d | 12w | 2026-01-01>` supplies a cutoff over `generated_at`. Every
+clock-gated check that was selected but could not run is *named* in
+`stats[:skipped_checks]` — a gate that is sometimes absent and does not
+confess converts "unchecked" into "checked and fine". The flag and the
+frontmatter field that share the `stale-after` spelling are different
+mechanisms: the flag is the reader's age cutoff (`stale`), the field the
+author's declared expiry (`expired`).
+
+# Where lint stops and an agent begins
+
+`lint` is structural: it cannot judge **contradictions** or **semantic**
+staleness (a concept that parses fine but no longer matches reality). Those need
+meaning. `lint --json` is precisely the structured input an agent reasons over to
+close that gap. The [`loose`](read-views.md) view is a folder-grouped lens over
+the single `unlinked` check.

data/.okf/capabilities/read-views.md

@@ -0,0 +1,228 @@
+---
+type: Capability
+title: Read views (index, dirs, catalog, files, references, types, tags, stats, loose, graph)
+description: The server's browser panels reproduced on the CLI, plus the index map, so an agent reads a bundle at a glance without a browser.
+tags: [read, cli, json]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: cli.md — read views
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/skill/reference/cli.md
+---
+
+# Overview
+
+The [graph server](graph-server.md) renders a bundle in a browser; these verbs
+render the same knowledge as text, so an agent (or a terminal) reads it directly.
+Each prints a scannable human view by default and machine JSON with `--json`, and
+all are advisory reads that exit `0`. They share
+[`OKF::Bundle#catalog`](../model/bundle.md) and the
+[graph indexes](../model/graph.md) for their data. When the question is lexical —
+"which concept covers X?" — [ranked search](search.md) cuts across every field
+these views group by, for the price of a few rows.
+
+# The views
+
+| Verb | Shows | Grouped by |
+|------|-------|------------|
+| `index` | each directory's index body, type/tag rollup, child dirs, and concept listing | directory (root first) |
+| `dirs` | every directory with the concepts living directly in it | directory (root first) |
+| `catalog` | concepts with type, tags, link counts, status | top-level dir |
+| `files` | files with titles | folder |
+| `references` | the on-disk `references/` tree (§6.3) with each file's citers and the dangling §6.2 pointers | folder |
+| `types` | types (`@okf-eco format/frontmatter`) with their concepts | count |
+| `tags` | tags (`@okf-eco format/frontmatter`) with their concepts | count |
+| `stats` | rollups: concepts, dirs, types, cross-links, tags | — |
+| `loose` | degree-0 concepts (no links (`@okf-eco format/cross-links`) in or out) | folder |
+| `graph` | the raw nodes and edges; `--hubs` ranks inbound links by source top-level dir; `--traffic` collapses concepts into dirs and links into weighted arcs, with cohesion | — (`--minimal` / `--no-body`) |
+
+`dirs` and `stats` answer about the *same* set of directories, deliberately:
+both read `Bundle#directory_index`, the map `--dir` is resolved against. Grouping
+the catalog instead — which knows only the directories that happen to hold a
+concept — made the two verbs disagree about how big a bundle was (`stats` said 2
+where `dirs` listed 3 on a bundle whose root carries an index.md and no
+concepts), and worse, left a directory out of `by_dir` that `--dir` answers
+about. Counts stay direct, so a directory holding nothing itself reports the zero
+it holds rather than disappearing; `by_dir.keys` is therefore the complete list
+of what `--dir` can name.
+
+`references` is the one view whose rows are not concepts: the reader models
+only markdown, so a `.py` attester or a `.sql` computation exists to no other
+surface, and this verb lists the `references/` tree from disk with which
+concepts cite each file through the §6.2 path-valued fields — plus every
+pointer that resolves to nothing, the bare-path trap (§6.2 resolves a bare
+`references/…` relative to the concept) named with its leading-slash fix.
+Folder scope is deliberate: §6.3 is a naming convention, not a requirement,
+and a computation stored beside its concept is legal and not inventoried.
+
+Every one of them names the bundle it answers about, in the identity the caller
+used — the rule the [CLI](../cli.md) keeps: `bundle` is always the directory,
+`slug` always a registry slug, and a header that reads `@handbook (/path)` when a
+[ref](../registry.md) named it. `graph` was the last holdout, printing a bare pair
+of counts over a bare `nodes`/`edges` payload; an agent holding several bundles
+had nothing in that answer to tell them apart.
+
+# `index` is the orient-first map (§8)
+
+Alone among the read views, `index` shows the reserved `index.md` layer: the
+concept views skip those structural files, so only `index` renders the
+progressive-disclosure map (`@okf-eco format/okf-format`) — one entry per directory
+(root first) with its authored index body, a type/tag rollup over the concepts
+living directly there, its child directories, and the concept listing. `--dir`
+narrows to a directory and its subtree and repeats (`root` names the bundle
+root, unless one is really called that) — bringing the chain up to the root with
+it, marked `↑`, since orientation
+is the whole point of this view and a branch shown alone has lost it —
+`--depth N` bounds how far below the starting point that reaches, and
+`--no-body` drops the prose to a skeleton. The last two are what make the map
+usable at scale: every directory is a section, so a few hundred concepts is a map
+nobody reads whole — `--depth 1 --no-body` orients, `--dir <branch> --depth 1`
+descends, and the pair walks the tree a level at a time instead of paging it. It is the cheapest orientation when picking up a
+bundle, and the only view that exposes *enumeration drift* — a listing entry that
+should exist but is missing, which no grep can find. A directory that holds
+concepts but no `index.md` gets its listing synthesized and tagged `(no index.md)`,
+a prompt to write a real map rather than a defect.
+
+# `dirs` is the shape, `index` is the contents
+
+`dirs` answers the question `--dir` is pointed at: every directory the bundle
+has — those holding concepts, those carrying an `index.md` or a scoped
+`log.md`, and the empty intermediates that exist only to connect the tree —
+with two counts each. A directory whose only file is its history is real (the
+log verbs read it); one holding only a file the reader skipped is not, and
+stays out of the map on every surface at once.
+
+`count` is **direct**, never cumulative: the column sums to the bundle's concept
+count, and a directory holding nothing but sub-directories reads `0` rather than
+borrowing its children's weight. That honesty is also its limit, and why
+`subtree` sits beside it: truncate the listing on a deep bundle and every row at
+the top of the tree reads `0`, which is precisely where "where is the mass?" is
+being asked. `subtree` is defined as *exactly what `--dir` on that row returns*,
+so the number and the flag can never disagree — and the root's subtree is
+therefore its own direct count, since `.` is a prefix of nothing. The human
+table shows the second column only where some directory actually nests; a flat
+bundle would only see the first one repeated.
+
+`--dir` (repeatable) takes a subtree — **and the chain up to the root with it**,
+so a branch is never shown adrift of the authored context that says what it is.
+Those rows are marked (`↑`, `ancestor: true`) and stay out of `total`, which is
+what keeps a row's `subtree` equal to the total `--dir` on that row returns;
+`--no-ancestors` drops them. A `--dir` naming nothing gains no chain, since 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 descent reaches — 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 the caller first working out how deep `a/b` is, and
+the two compose the way a reader descending a tree actually moves. `--depth 0`
+is the starting point alone. The deprecated `--area` combines with **neither**
+`--depth` nor `--dir` and is refused (exit 2) for one reason wearing two shapes:
+it is *exact*. With `--depth` it names no starting point to be relative to, so
+the pair unioned the area with every directory at that depth from the root; with
+`--dir` one side is exact where the other is a prefix, so the map came back with
+the area *and* the subtree. Both read like an answer and are an answer to neither
+question.
+
+Matching folds case, but a row is found by its *stored* spelling, so the chain is
+walked folded and handed back in the map's own words. It used to be handed back
+folded, which silently dropped every ancestor of a directory spelled with a
+capital — the chain the flag exists to draw, missing exactly the row that places
+the branch.
+
+One line per directory where `index` is the whole map, so it is the cheaper of
+the two when the question is shape rather than contents — and `dirs` is the first
+thing to run on an unfamiliar bundle. Cheaper structurally, not by measurement:
+`dirs` emits one row per *directory* and `index` one listing row per *concept*
+even under `--no-body`, so their costs scale with different things. The root stores `.` and
+prints `(root)` — the split every grouped view keeps, so a table and its `--json`
+never disagree about which spelling is the data.
+
+# JSON output — compact, and projectable
+
+`--json` is **compact by default** — single-line, the token-efficient substrate an
+agent consumes; `--pretty` (which implies `--json`) indents the same JSON for a
+human. On the per-item list views — `index`, `catalog`, `files`, `dirs` — `--fields a,b`
+keeps only those properties and `--except a,b` drops them (mutually exclusive; an
+unknown name is a usage error that lists the valid ones). Projection runs before
+emission, so an agent never pays tokens for a field it dropped: `okf index <dir>
+--except body,listing` is the lean directory skeleton, the difference between a few
+hundred bytes and hundreds of KB on a large bundle.
+
+# Narrowing and regrouping
+
+The four list views — `catalog`, `files`, `types`, `tags` — accept the filters
+*orthogonal* to how they group, so you ask a narrow question instead of paging
+the whole bundle (matching is case-insensitive):
+
+| View | Filters it accepts |
+|------|--------------------|
+| `catalog`, `files` | `--type`, `--dir`, `--tag` |
+| `types` | `--dir`, `--tag` (it already groups by type) |
+| `tags` | `--type`, `--dir` (it already groups by tag) |
+
+`--dir` is one rule: a concept matches when its directory *is* the path or sits
+below it, so `--dir platform` reaches `platform/services/api` and `--dir .` (or
+`root`) means the root alone. A trailing slash is accepted and ignored, because
+the human views print one — `index` labels a row `platform/services/` — and a
+flag that refuses the label the tool just printed answers "nothing found" to a
+directory that is full.
+
+The `root` spelling has one exception, and it is the shape that showed why an
+alias is never free: a bundle holding a real `root/` directory. There the word
+names that directory, not the bundle root, because the alias only ever bought a
+shell quote and the directory would otherwise be unaddressable — answering for
+the root instead, exit 0, nothing said. The resolution is against the bundle's
+own directories rather than the string alone, which is also what the *stored*
+spellings must not go through: `dirs` folded each row's own dir through the
+same helper, so a row named `root` computed its `subtree` against the bundle
+root and disagreed with what `--dir` on that row returns.
+
+"The bundle's own directories" has to mean one list, and that is the lesson the
+first attempt missed. The concept views asked the **catalog**, which knows only
+directories that hold concepts, while `dirs` and `index` asked the directory
+map, which counts an `index.md` too — so a `root/` carrying nothing but its
+index stayed folded in `catalog` and named in `dirs`, in the same bundle, on the
+same flag. One question gets one source (`Bundle#directories`) — and the list
+counts every file kind that makes a directory real, because the same bug came
+back one kind over: a `root/` holding only a scoped `log.md` was invisible to
+the set until the log joined the seed. The other half
+is *when*: the alias is a fact about a bundle, so a run naming several resolves
+it once across the served set — resolving inside the per-bundle loop let a
+single `--dir root` mean the subtree in one bundle and the root in the next,
+merged into one ranking with nothing saying so. It replaces `--area`, which saw only a concept id's
+first path segment — a word the OKF format (`@okf-eco format/okf-format`) never used —
+and which still works, warning on stderr, until a later release drops it.
+
+`tags --by type|dir` regroups the tag index under each concept dimension with
+within-group counts — the view for curating a
+tag (`@okf-eco format/frontmatter`) vocabulary: which tags cluster in which directory,
+which type leans on which tags. Each row also carries the tag's total across
+the narrowed set, printed `count/total` when they differ (`async  2/3`) and as
+a plain count when the tag is wholly local — so a tag's *locality* (domain
+confined to one directory, or concern cutting across several) reads per row. The
+same evidence question for the graph: `graph --hubs` ranks every concept with
+inbound links (`@okf-eco format/cross-links`) by inbound degree and groups each
+hub's links by *source top-level dir* — whether a hub is well-homed, answered
+mechanically.
+
+`graph --traffic` asks it one grain coarser, about **directories**. It reads the
+[skeleton](../model/skeleton.md): concepts collapse into the directory they live in
+and the links between two directories into one weighted arc, so each row carries
+that directory's traffic split three ways — internal, out, in — plus
+**cohesion**, its internal share. That is
+cohesion-versus-coupling applied to a knowledge tree, and it is the only read at
+the grain `refine` actually decides at: `--hubs` says whether a *concept* is
+well-homed, `--traffic` says whether a *directory* is holding together, acting
+as a shared vocabulary everyone cites, or behaving like a projection that should
+have been an index. `--cut` is fitted to the bundle rather than fixed, because a
+fixed weight left 2 arcs on one bundle and 136 on another; cohesion is computed
+over every arc regardless of the cut, so narrowing the picture never moves the
+evidence.
+
+# `loose` is a curation lens, not an error
+
+`loose` is the folder-grouped view over [lint](linter.md)'s `unlinked` check —
+distinct from `orphan`. An `index.md` listing makes a file *reachable* (not an
+orphan) but is **not a graph edge**, so a listed file can still float here. A
+loose file may be perfectly fine — a terminal leaf like a backlog item is loose
+by design — so `loose` surfaces the set for a human or agent to judge and always
+exits `0`.

data/.okf/capabilities/render.md

@@ -0,0 +1,66 @@
+---
+type: Capability
+title: Static render (render)
+description: One self-contained HTML file with the whole graph baked in — the same page `okf server` serves, written to disk so it hosts where nothing runs (`okf render`).
+resource: gems/okf/lib/okf/render/graph.rb
+tags: [server, graph]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/cli/render.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/cli/render.rb
+  - title: gems/okf/lib/okf/render/graph.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/render/graph.rb
+---
+
+# Overview
+
+`okf render` writes the [graph page](graph-server.md) as one static,
+self-contained HTML file with the whole bundle baked in — the *same* page
+[`okf server`](graph-server.md) serves live, one switch apart — so the graph
+hosts anywhere there is no server to answer a `fetch()`. GitHub Pages is the
+motivating case: commit the file and the graph is browsable with no process
+running behind it.
+
+# One template, two modes
+
+There is no second renderer to keep in sync with the server, because there is no
+second renderer. One `OKF::Render::Graph` — the view paired with the pure
+[graph model](../model/graph.md) — draws the page for both modes, and `okf render`
+bakes the bundle in through its `.static`/`.payload`. Every data read the page
+makes — a body, a description, the
+catalog, the §8 map, the §9 logs — flows through a small set of getter functions,
+and an injected `EMBED` constant chooses their source: `null` when served, so the
+getters `fetch()` the live endpoints; the whole payload when rendered, so they
+resolve from the page itself. One interface, two adapters, and the views never
+know which is behind them. The [bundle switcher](graph-server.md) obeys the same
+discipline in reverse — a static file injects an empty sibling list, so the
+affordance that could only dead-end never appears.
+
+# It carries both XSS guards
+
+Baking the bodies in does not lower the page's defenses. An embedded body takes
+the *inlined* path and the *rendered* one at once: `json_for_script` escapes it at
+inject time so a `</script>` inside a body cannot break out of its `<script>`, and
+it is still run through `DOMPurify.sanitize(marked.parse(...))` before the getter
+hands it to the DOM. The [same trust boundary](../design/server-trust-boundary.md)
+the live server keeps, carried onto the one static path — a rendered file is no
+laxer than the server it was baked from.
+
+# Output, flags, and the price
+
+`okf render <dir>` prints the page to stdout — `okf render ./docs > public/index.html` —
+or writes `-o FILE` directly, reporting the concept count when it does. A `-o`
+path it cannot write is a usage error (exit `2`), not a backtrace — the same
+[best-effort contract](../cli.md) the read views keep. `--layout NAME` bakes in a
+graph layout, `--map` bakes the [Map view](graph-server.md) as the opening state
+(no arrows, the directories boxed), and `-t`/`-l` set the title and the link the
+page unfurls as a preview card, since a static file cannot be told them later. The price is weight:
+every body is inlined, where a live [`okf server`](graph-server.md) ships a minimal
+graph and pulls bodies on demand — so the server stays the choice for a bundle too
+large to ship whole, and the static file carries no compression of its own
+(whatever host serves it compresses instead). That weight buys something back:
+because every body is already in the page, the static file's
+[full-text search](graph-server.md) reaches **bodies and source text** offline,
+where the live server — bodies still lazy — can only index their metadata.