okf 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f1f08bf7a4a1a49ef0bea5953b380df85bdbe79e1b30998e0d168d122d4a20c2
+  data.tar.gz: 97aff0312275def9b514c0e50bcc3872a73e3a304efa7ac8d85046a846711a7f
+SHA512:
+  metadata.gz: '09c1784bee88f5a74087345fa3ee26a13ba2875ff9447559852c23cf294f6f05ffa457eabdd67cbbac4bc5e255b3cc91f128863fab92d9b5a88f3ae41062e871'
+  data.tar.gz: d26885ca8683d2de6ad036d7a158089ba4b7e12437131b617687bad51bd15157f64dd148bcd7f8f502a95ae48d644f9c5674464e82ff3f97bc34faf61a24dc24

data/.okf/capabilities/agent-skill.md

@@ -0,0 +1,46 @@
+---
+type: Capability
+title: Companion agent skill (skill)
+description: A SKILL.md plus references and templates, shipped inside the gem, that teaches an agent to author OKF.
+resource: lib/okf/skill.rb
+tags: [skill, agent, install]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+The gem carries the **OKF agent skill** — a `SKILL.md` with reference and
+template files that teach a coding agent to *produce*, *maintain*, and *consume*
+[OKF](../format/okf-format.md) bundles and to drive the [CLI](../cli.md). The
+authoring judgment the executable can't encode lives here; the executable handles
+the mechanics.
+
+# `okf skill <dest>` installs it
+
+`OKF::Skill.install` copies the skill into a destination you name — Claude Code's
+`.claude`, an agent-agnostic `.agents`, wherever your agent looks. The rules are
+deliberate:
+
+- the **destination is required** — no magic default — so a user always decides
+  where the skill lands;
+- it lands in a **`skills/okf/` folder** by default (`.claude` →
+  `.claude/skills/okf`), because an agent discovers a skill as
+  `<skills-dir>/<name>/SKILL.md` — so the skill settles in its own folder, not
+  loose among the others. A `<dest>` already ending in `skills` only gains the
+  `okf/` leaf; one already named `okf` is used as-is (idempotent); `--here`
+  pastes straight into `<dest>`, wherever it is;
+- the resolved directory must be **empty unless `--force`**, so a customized
+  skill is never clobbered.
+
+# One canonical copy, versioned with the gem
+
+The skill ships **only** from `lib/okf/skill/**` — that tree is the single source,
+and `install` copies from it. Because the skill rides inside the gem, installing
+the gem already puts the skill on the machine, and the skill's CLI reference can
+**never drift** from the executable it was released with. Local installs
+elsewhere are gitignored so they never masquerade as the source.
+
+# Citations
+
+[1] [lib/okf/skill.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill.rb) — the installer.
+[2] [lib/okf/skill/SKILL.md](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/SKILL.md) — the skill itself.

data/.okf/capabilities/graph-server.md

@@ -0,0 +1,60 @@
+---
+type: Capability
+title: Interactive graph server (server)
+description: A self-contained HTML knowledge graph served over HTTP, and a mountable Rack app.
+resource: lib/okf/server/app.rb
+tags: [server, graph, rack, diagram]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+`okf server` boots an interactive view of the [graph](../model/graph.md):
+`OKF::Server::App` is a Rack app that serves one self-contained HTML page which
+draws the bundle with Cytoscape and renders concept bodies with marked. Because
+it is a plain Rack app, it also mounts inside a host application (e.g. a Rails
+route) — the built-in WEBrick runner is just the default, injected so tests drive
+it without opening a socket.
+
+# The page stays self-contained
+
+One ERB template, inline CSS and JS, no build step and no bundler. The only
+external assets are Cytoscape and marked from a CDN — plus Mermaid, lazy-loaded
+only when a concept body actually contains a diagram; everything else is inlined.
+The graph draws from a **minimal** node payload and pulls each concept's body
+**on demand** via `fetch()`, which is why even a large bundle loads fast.
+
+# Request flow
+
+```mermaid
+sequenceDiagram
+  participant B as Browser
+  participant A as okf server (Rack app)
+  B->>A: GET /
+  A-->>B: HTML page + inlined minimal graph data
+  Note over A,B: angle brackets escaped (json_for_script) — safe
+  B->>A: GET /node?id=… (on demand)
+  A-->>B: concept Markdown body
+  Note over A,B: marked renders it UNSANITIZED — trust boundary
+```
+
+# Endpoints
+
+| Path | Serves |
+|------|--------|
+| `/` | the HTML page (graph + inlined minimal data) |
+| `/node?id=` | one concept's rendered body |
+| `/node/meta?id=` | one concept's metadata |
+| `/catalog`, `/tags`, `/types` | the JSON behind the browser panels |
+
+# Trust boundary
+
+Fetched Markdown bodies are rendered **without sanitization**, so only serve
+bundles you trust. Data inlined into the page is safe — it goes through
+`json_for_script`, which escapes `<` so it cannot break out of its `<script>` —
+but the on-demand body is not. See the
+[server trust boundary](../design/server-trust-boundary.md) for the full picture.
+
+# Citations
+
+[1] [lib/okf/server/app.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/app.rb) — the Rack app and its routes.

data/.okf/capabilities/index.md

@@ -0,0 +1,20 @@
+# Capabilities
+
+The five things the gem does over a bundle, plus the read views that print it at
+a glance. All of them run over the same [pure model](../model/) and are fronted
+by the [CLI](../cli.md).
+
+# Judge
+
+* [Conformance validator](validator.md) - the §9 legal check; the only capability that can fail a bundle.
+* [Curation linter](linter.md) - advisory quality report across six categories; never rejects.
+
+# Serve & read
+
+* [Interactive graph server](graph-server.md) - a self-contained HTML graph over HTTP, mountable as a Rack app.
+* [Read views](read-views.md) - `index`, `catalog`, `files`, `types`, `tags`, `stats`, `loose`, `graph` — the browser views as text, plus the `index` map.
+
+# 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.

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

@@ -0,0 +1,67 @@
+---
+type: Capability
+title: Library API
+description: The Ruby surface — a pure in-memory model plus on-disk handles, an "ActiveRecord for the filesystem".
+resource: lib/okf.rb
+tags: [library, api, ruby, diagram]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# 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.
+
+```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::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 §9
+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).
+
+# Citations
+
+[1] [README.md — Library](https://github.com/serradura/okf-gem/blob/main/README.md) — worked examples of both layers.
+[2] [lib/okf.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf.rb) — the require surface.

data/.okf/capabilities/linter.md

@@ -0,0 +1,49 @@
+---
+type: Capability
+title: Curation linter (lint)
+description: An advisory curation-quality report across six categories and sixteen checks — it never rejects a bundle.
+resource: lib/okf/bundle/linter.rb
+tags: [linting, curation, cli]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# 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 §9 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`.
+
+# Six categories, sixteen checks
+
+| Category | Checks |
+|----------|--------|
+| Reachability | `orphan`, `not_in_index`, `disconnected_component`, `unlinked` |
+| Backlog | `missing_concept`, `broken_index_entry` |
+| Completeness | `stub`, `missing_title`, `missing_description`, `missing_timestamp` |
+| Freshness | `stale` |
+| Provenance | `uncited_external`, `broken_citation` |
+| Hygiene | `duplicate_title`, `unused_reference_def`, `undefined_reference`, `self_link` |
+
+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`.
+
+# The freshness gotcha
+
+Freshness is **off by default** — a plain `lint` never reports `stale`. Pass
+`--stale-after <90d | 12w | 2026-01-01>` when concepts carry a
+[`timestamp`](../format/frontmatter.md). The CLI resolves that to an absolute
+cutoff so the pure linter never reads the clock.
+
+# 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.
+
+# Citations
+
+[1] [lib/okf/bundle/linter.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/bundle/linter.rb) — the sixteen checks and their categories.

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

@@ -0,0 +1,84 @@
+---
+type: Capability
+title: Read views (index, catalog, files, 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]
+timestamp: 2026-07-12T12:00:00Z
+---
+
+# 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.
+
+# The views
+
+| Verb | Shows | Grouped by |
+|------|-------|------------|
+| `index` | each directory's index body, type/tag rollup, child dirs, and concept listing | directory (root first) |
+| `catalog` | concepts with type, tags, link counts, status | area |
+| `files` | files with titles | folder |
+| `types` | [types](../format/frontmatter.md) with their concepts | count |
+| `tags` | [tags](../format/frontmatter.md) with their concepts | count |
+| `stats` | rollups: concepts, areas, types, cross-links, tags | — |
+| `loose` | degree-0 concepts (no [links](../format/cross-links.md) in or out) | folder |
+| `graph` | the raw nodes and edges | — (`--minimal` / `--no-body`) |
+
+# `index` is the orient-first map (§6)
+
+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](../format/okf-format.md) — 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. `--area`
+narrows to one directory and repeats (`root` names the bundle root); `--no-body`
+drops the prose to a skeleton. 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.
+
+# 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` — `--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`, `--area`, `--tag` |
+| `types` | `--area`, `--tag` (it already groups by type) |
+| `tags` | `--type`, `--area` (it already groups by tag) |
+
+`tags --by type|area` regroups the tag index under each concept dimension with
+within-group counts — the view for curating a
+[tag](../format/frontmatter.md) vocabulary: which tags cluster in which area,
+which type leans on which tags.
+
+# `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`.
+
+# Citations
+
+[1] [cli.md — read views](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/reference/cli.md) — the views and their flags.

data/.okf/capabilities/validator.md

@@ -0,0 +1,40 @@
+---
+type: Capability
+title: Conformance validator (validate)
+description: Implements the spec's §9 conformance definition exactly — three hard conditions, everything else a warning.
+resource: lib/okf/bundle/validator.rb
+tags: [validation, conformance, cli]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+`okf validate` answers one question: *is this a legal [OKF](../format/okf-format.md)
+bundle?* `OKF::Bundle::Validator` implements §9 exactly and is the **only**
+capability that can fail a bundle — exit `1` on any hard error, `0` otherwise.
+
+# The three hard conditions (errors)
+
+| Rule | Condition |
+|------|-----------|
+| §9.1 | every non-reserved file has a parseable [frontmatter](../format/frontmatter.md) block |
+| §9.2 | every such block has a **non-empty `type`** |
+| §9.3 | every `index.md` / `log.md` present is well-formed (nested index has no frontmatter, root index carries only `okf_version`, log dates are ISO) |
+
+# Everything else is a warning
+
+The validator is **forbidden by §9** from rejecting a bundle for soft issues, so
+these are warnings that never change conformance:
+
+- missing recommended fields, non-list `tags`, an unparseable `timestamp`;
+- **broken [cross-links](../format/cross-links.md)** (§5.3) — consumers MUST
+  tolerate them.
+
+Judging those is the [linter](linter.md)'s job, and keeping the two apart is a
+[hard design contract](../design/core-shell-split.md). The
+[writer](library-api.md) runs this validator *before* publishing, so a saved
+bundle is never written non-conformant.
+
+# Citations
+
+[1] [lib/okf/bundle/validator.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/bundle/validator.rb) — the §9 implementation.

data/.okf/cli.md

@@ -0,0 +1,52 @@
+---
+type: Component
+title: The okf command-line front end
+description: The only layer that parses argv, prints, writes files, and decides exit codes.
+resource: lib/okf/cli.rb
+tags: [cli, shell]
+timestamp: 2026-07-12T12:00:00Z
+---
+
+# Overview
+
+`OKF::CLI` is the executable's front end and the single place where the gem
+touches the outside world for a command: it parses `argv`, prints, writes files,
+and chooses the exit code. Every library class beneath it just returns data — the
+CLI is the [shell half](design/core-shell-split.md) of the architecture. Output
+streams are injected (`out:`/`err:`) so the whole surface is driven in tests
+without a real terminal or socket.
+
+# Subcommands
+
+Dispatch is a single `case` on the first argument. The verbs fall into three
+groups:
+
+| Group | Verbs | Notes |
+|-------|-------|-------|
+| Judge | `validate`, `lint`, `loose` | [validate](capabilities/validator.md) and [lint](capabilities/linter.md) answer different questions and stay separate. |
+| Read | `index`, `catalog`, `files`, `types`, `tags`, `stats`, `graph` | the [browser views as text](capabilities/read-views.md), plus the `index` map. |
+| Act | `server`, `skill` | boot the [graph server](capabilities/graph-server.md); install the [agent skill](capabilities/agent-skill.md). |
+
+Plus `version` / `--version` / `-v` and `help` / `--help` / `-h`.
+
+# Exit codes
+
+The contract every verb keeps:
+
+| Code | Meaning |
+|------|---------|
+| `0` | success — including a bundle with lint findings (`lint` is advisory) |
+| `1` | a non-conformant bundle (`validate`) or a `lint --fail-on warn` threshold crossed |
+| `2` | usage error — unknown command, missing directory, bad flag |
+
+# Best-effort reads
+
+`graph`, `server`, and the read views are best-effort under §9: a file with
+invalid frontmatter is kept in `bundle.unparseable`, skipped, and *noted on
+stderr* (so JSON on stdout stays clean) rather than aborting the whole command.
+One bad file never breaks the rest. Run [validate](capabilities/validator.md) for
+the details of what was skipped.
+
+# Citations
+
+[1] [lib/okf/cli.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/cli.rb) — the dispatch, option parsing, and printers.

data/.okf/design/core-shell-split.md

@@ -0,0 +1,58 @@
+---
+type: Constraint
+title: The core/shell split
+description: A pure functional core that never touches disk or stdio, and a thin shell that owns all I/O — enforced by a test.
+resource: test/unit/boundary_test.rb
+tags: [architecture, purity, testing, diagram]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+The gem is two halves. The **core** is pure — [`Concept`](../model/concept.md),
+[`Bundle`](../model/bundle.md), [`Graph`](../model/graph.md), the
+[validator](../capabilities/validator.md), the [linter](../capabilities/linter.md),
+the [format layer](../format/) — logic that returns data and does no I/O. The
+**shell** owns everything that touches the world: the on-disk handles
+(`Concept::File`, `Bundle::{Reader,Writer,Folder}`), the
+[server](../capabilities/graph-server.md), and the [CLI](../cli.md).
+
+```mermaid
+flowchart TB
+  subgraph shell ["Shell — the only layer that does I/O"]
+    CLI["CLI"]
+    Server["Server::App"]
+    RW["Reader · Writer · Folder"]
+    CF["Concept::File"]
+  end
+  subgraph core ["Core — pure: no File / Dir / stdio"]
+    Concept["Concept"]
+    Bundle["Bundle"]
+    Graph["Graph"]
+    VL["Validator · Linter"]
+    MD["Markdown layer"]
+  end
+  shell ==>|depends on| core
+  core -. "never — boundary_test.rb fails the build" .-> shell
+```
+
+# It is enforced, not just intended
+
+`test/unit/boundary_test.rb` fails the build if a core file names a shell class or
+reaches for `File` / `Dir` / `FileUtils` / stdio. The dependency rule is executable,
+so the boundary cannot rot silently: **put new I/O in the shell, put new logic in
+the core, pure.**
+
+# Why it pays off
+
+- **Testable without disk** — every feature runs against an in-memory
+  [bundle](../model/bundle.md), so the suite is fast and the 2.4 Docker check is
+  cheap.
+- **Embeddable** — the [library API](../capabilities/library-api.md) exposes the
+  pure core to host apps that never want the gem's filesystem opinions.
+- **Best-effort reads** — the reader collects unparseable files instead of
+  raising, so the pure graph still renders while the shell reports the skips.
+
+# Citations
+
+[1] [test/unit/boundary_test.rb](https://github.com/serradura/okf-gem/blob/main/test/unit/boundary_test.rb) — the boundary made executable.

data/.okf/design/index.md

@@ -0,0 +1,10 @@
+# Design constraints
+
+The enforced boundaries that keep the gem light, portable, and honest. These are
+not style preferences — most are checked by a test or CI, and they explain *why*
+the code looks the way it does.
+
+* [Core/shell split](core-shell-split.md) - pure logic must never touch disk, stdio, or the shell layer; a test enforces it.
+* [Ruby 2.4 floor](ruby-floor.md) - runs on the Ruby an OS already ships; newer APIs are banned.
+* [Runtime dependencies](runtime-dependencies.md) - exactly `rack` and `webrick`, no ActiveSupport.
+* [Server trust boundary](server-trust-boundary.md) - the served page renders concept bodies unsanitized.

data/.okf/design/ruby-floor.md

@@ -0,0 +1,45 @@
+---
+type: Constraint
+title: The Ruby 2.4 floor
+description: The gem runs on every Ruby since 2.4 so it works on the interpreter an OS already ships.
+tags: [ruby, compatibility, portability]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+`required_ruby_version >= 2.4.0`. The point is to run on the Ruby an operating
+system already ships, without asking anyone to install a newer one — the same
+floor as [rack](runtime-dependencies.md), the gem's core dependency. This is why
+the gem stays deliberately light.
+
+# The floor bans APIs RuboCop won't catch
+
+RuboCop parses at 2.4 and catches syntax, but **not** newer standard-library
+methods, so those are a manual discipline. A non-exhaustive list of what is off
+limits:
+
+- **2.5** — `delete_prefix`/`delete_suffix`, `transform_keys`, `Dir.children`,
+  `yield_self`;
+- **2.6** — `to_h { }`, `then`, endless string slices `str[i..]`, `YAML.safe_load`
+  keyword args (allowed **only** inside the
+  [Frontmatter shim](../format/frontmatter.md));
+- **2.7** — `filter_map`, `tally`, numbered block params;
+- **3.x** — endless methods, hash shorthand.
+
+These constraints apply to `test/` too, because the suite runs on 2.4 as well.
+
+# The truth test
+
+"Works on my Ruby" is not verification here. The floor is checked in CI across
+every supported Ruby, and locally with:
+
+```bash
+docker run --rm -v "$PWD":/app -w /app ruby:2.4 \
+  bash -c "bundle install && bundle exec rake test"
+```
+
+# Citations
+
+[1] [okf.gemspec](https://github.com/serradura/okf-gem/blob/main/okf.gemspec) — `required_ruby_version = ">= 2.4.0"`.
+[2] [AGENTS.md — Hard constraints](https://github.com/serradura/okf-gem/blob/main/AGENTS.md) — the banned-API list and the Docker truth test.

data/.okf/design/runtime-dependencies.md

@@ -0,0 +1,44 @@
+---
+type: Constraint
+title: Exactly two runtime dependencies
+description: The gem depends on rack and webrick only — no ActiveSupport, no build step, no JavaScript toolchain.
+resource: okf.gemspec
+tags: [dependencies, rack, portability]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+The runtime dependencies are exactly two, and adding a third is a design decision
+to be challenged, not a convenience:
+
+| Gem | Why |
+|-----|-----|
+| `rack` (`>= 2.2`) | the [server](../capabilities/graph-server.md) is a mountable Rack app |
+| `webrick` (`>= 1.4`) | the default runner — unbundled from Ruby in 3.0, so it must be declared |
+
+# No ActiveSupport, on purpose
+
+The gem refuses the usual reach for ActiveSupport. Two small pieces exist
+precisely so it is not needed:
+
+- `OKF.blank?` — the emptiness check;
+- `OKF::Markdown::Frontmatter.stringify_keys` — the key coercion, living in
+  [the one YAML gateway](../format/frontmatter.md).
+
+# What the leanness buys
+
+Together with the [Ruby 2.4 floor](ruby-floor.md), a two-dependency footprint is
+what lets the gem run on the interpreter an OS already ships — no build step, no
+bundler for the [served page](server-trust-boundary.md), no JavaScript toolchain.
+Leanness is a feature of this gem, not an accident.
+
+# A packaging note
+
+`spec.files` comes from `git ls-files` minus `test/`, `bin/`, `.github/`, etc., so
+a new top-level file ships in the gem unless the gemspec rejects it — check
+`gem build` output when adding one.
+
+# Citations
+
+[1] [okf.gemspec](https://github.com/serradura/okf-gem/blob/main/okf.gemspec) — the two `add_dependency` lines and `spec.files`.

data/.okf/design/server-trust-boundary.md

@@ -0,0 +1,35 @@
+---
+type: Constraint
+title: The server trust boundary
+description: The served page renders concept bodies without sanitization, so only serve bundles you trust.
+resource: lib/okf/server/templates/graph.html.erb
+tags: [security, server, xss]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+The [graph server](../capabilities/graph-server.md) is designed for trusted
+bundles. Its page renders each concept's Markdown body **without sanitization**
+(marked, no sanitizer), so a hostile bundle could carry active content. The rule
+is simple: **only serve bundles you trust.**
+
+# Where the boundary sits
+
+There are two different data paths into the page, and only one is escaped:
+
+| Path | Handling | Safe? |
+|------|----------|-------|
+| Graph data **inlined** into the page | through `json_for_script`, which escapes `<` | yes — it cannot break out of its `<script>` |
+| Concept bodies **fetched** on demand (`/node?id=`) | rendered as Markdown, unsanitized | no — this is the trust boundary |
+
+So the XSS boundary is not the inlined data (that is handled); it is the
+on-demand [body](../format/cross-links.md) render. The
+[self-contained page](../capabilities/graph-server.md) keeps external assets down
+to Cytoscape and marked from a CDN, but that does not make the rendered body
+safe.
+
+# Citations
+
+[1] [README.md — Server trust boundary](https://github.com/serradura/okf-gem/blob/main/README.md) — the unsanitized-render warning.
+[2] [lib/okf/server/templates/graph.html.erb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/templates/graph.html.erb) — `json_for_script` and the body render.

data/.okf/format/citations.md

@@ -0,0 +1,33 @@
+---
+type: Format
+title: Citations (spec §8)
+description: The provenance convention that ties empirical claims in a concept back to their sources.
+resource: lib/okf/markdown/citations.rb
+tags: [format, provenance, citations]
+timestamp: 2026-07-11T12:00:00Z
+---
+
+# Overview
+
+A `# Citations` heading holds the external sources backing claims in a concept's
+body. `OKF::Markdown::Citations` extracts them. Provenance is what separates
+trustworthy knowledge from folklore: any external or empirical claim — a latency
+number, an approval, a quota — should trace to a source here.
+
+# Why it matters to the tooling
+
+Citations are the input to the [linter](../capabilities/linter.md)'s
+**provenance** category, which flags two failure modes:
+
+- **uncited external claims** — a concept that asserts an external fact but cites
+  nothing;
+- **broken citations** — a citation whose link no longer resolves.
+
+Because the [validator](../capabilities/validator.md) is forbidden from rejecting
+a bundle over provenance, these live entirely on the lint side — advisory signal
+that a curator (or an agent) acts on, never a conformance failure.
+
+# Citations
+
+[1] [lib/okf/markdown/citations.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/markdown/citations.rb) — citation extraction.
+[2] [SPEC.md §8](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/reference/SPEC.md) — the citations convention.