okf 2.1.0 → 2.2.0

data/.okf/model/bundle.md

@@ -0,0 +1,47 @@
+---
+type: Component
+title: OKF::Bundle
+description: The pure in-memory collection of concepts that validate, lint, and graph run over.
+resource: gems/okf/lib/okf/bundle.rb
+tags: [pure]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle.rb
+---
+
+# Overview
+
+`OKF::Bundle` is a set of [concepts](concept.md) held together in memory, with no
+disk involved. It is the object the three judging capabilities operate on:
+`#validate`, `#lint`, and `#graph` each hand the bundle to a dedicated pure
+class and return a result. A bundle also carries the reserved files
+(`index.md`, `log.md`) and — importantly — an `unparseable` list.
+
+# Best-effort by construction
+
+When a bundle is built from disk, files the reader cannot use do not vanish and do
+not abort the build: they are collected in `bundle.unparseable` — frontmatter that
+would not parse, and files that would not open, since a locked file is one file's
+problem and not the bundle's. That is what
+lets [graph](graph.md), the [server](../capabilities/graph-server.md), and the
+[read views](../capabilities/read-views.md) render everything that *is* valid
+while the [CLI](../cli.md) notes the skips on stderr — §11's best-effort posture,
+made structural.
+
+# Build it from data, not only from files
+
+Because the bundle is pure, an embedding application can construct concepts
+straight from its own records — no Markdown round-trip — and still get validate,
+lint, and graph for free. This is the surface the
+[library API](../capabilities/library-api.md) exposes to, say, a Rails store that
+already holds knowledge as rows. It also feeds the shared `#catalog`, the data
+behind every read view — and the rollups beside it, each kept in one home
+after a hand copy diverged: `#stats` (whose `by_dir` reads the directory
+index, so an empty directory reports its honest zero), `#tag_groups` (the
+vocabulary-curation cut, within-group counts beside cross-set totals), and
+`Bundle::References` (the §6.3 inventory — the one model that sees a bundle's
+non-markdown files, fed a manifest by the shell). The CLI verbs and the MCP
+tools consume the same three.

data/.okf/model/concept.md

@@ -0,0 +1,75 @@
+---
+type: Component
+title: OKF::Concept
+description: The pure in-memory model of a single OKF file — frontmatter, body, and a stable id.
+resource: gems/okf/lib/okf/concept.rb
+tags: [pure]
+generated:
+  by: human:maintainer
+  at: 2026-08-14T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/concept.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/concept.rb
+---
+
+# Overview
+
+`OKF::Concept` is the atomic node: a `path`, a parsed
+`frontmatter` (`@okf-eco format/frontmatter`) hash, and a Markdown `body`. It is
+[pure](../design/core-shell-split.md) — it holds no file handle and does no I/O.
+The on-disk counterpart is `OKF::Concept::File`, part of the
+[library API](../capabilities/library-api.md).
+
+# The id is the concept's identity
+
+`#id` is the concept's **stable identifier** across the whole system — the graph
+node key, the link target, and the thing you name a concept for. By default it is
+the `path` minus `.md` (e.g. `model/graph.md` → `model/graph`), which is why you
+name a file for what it *is*, not where it sits. A frontmatter `id`, when set,
+pins the identity explicitly — the path-derived name is the fallback, not the only
+source — so a concept can keep its id across a move.
+
+The override is this gem's **extension, not spec**: §2 defines the concept id
+as the path minus `.md`, full stop. Pinning one puts the concept in two worlds
+on purpose — the identity views ([catalog, hubs, `--dir`,
+search](../capabilities/read-views.md)) follow the id, because the edges do,
+while the physical views (`index`, `dirs`, stats' `by_dir`) keep the file where
+it lives, because an index is a physical listing. An integration test holds a
+concept whose id leaves its directory and asserts both worlds at once, so the
+split stays a decision; the authoring advice is the default's — rename the
+file, not the id.
+
+# What it derives from its own content
+
+The concept parses its body on demand into the structural facts the rest of the
+gem consumes:
+
+- `#type`, `#title`, `#description`, `#resource`, `#tags` — typed reads over
+  the frontmatter;
+- the §5 families, each carrying §13.1's fallbacks inline: `#generated` /
+  `#generated_at` / `#generated_by` (a legacy `timestamp` lifts into `at`,
+  per-key, with no actor ever invented), `#sources` (the native list, or the
+  legacy `# Citations` (`@okf-eco format/citations`) body list whenever the native
+  value yields zero mappings), `#verified` (a bare mapping reads as a
+  one-element list; degenerate shapes fold to unverified), `#trust_tier` /
+  `#trust` (derived per §5.3, never stored), `#status`/`#declared_status`
+  (absent reads stable; both keep the producer's spelling, because every
+  surface that *displays* a status prints what was written — the fold belongs
+  to `.effective_status`, which is what narrowing compares through), `#stale_after_date`/`#stale_on?(today)` (§5.5 — stale
+  on the day itself; the clock is always an argument, never read);
+- the §10 contract of an Attested Computation: `#runtime`, `#parameters`,
+  `#computation`, `#executor`, `#attester`, `#attested_computation?`;
+- `#usage_window` — validated for shape, deliberately consumed by nothing: no
+  gem surface computes over usage counts, so an effective-window resolver
+  would be speculative;
+- `#declared_generated?`, `#legacy_timestamp?`, `#legacy_citations?` — raw-key
+  detection for lint and the surfaces; detection never influences reading;
+- `#links` — every raw cross-link (`@okf-eco format/cross-links`) target in the body, in order; the bundle-relative ones become graph edges;
+- `#external_links` — the subset of those that are URLs or `mailto:` (not edges);
+- `#to_markdown` — the inverse of the frontmatter parser (`#citations` is gone,
+  subsumed by `#sources`);
+- `#lint` — the concept-scoped [lint](../capabilities/linter.md) checks in isolation.
+
+A concept never decides conformance alone; a [bundle](bundle.md) does, because
+some checks (duplicate titles, missing link targets) are only meaningful across
+the set.

data/.okf/model/graph.md

@@ -0,0 +1,59 @@
+---
+type: Component
+title: OKF::Bundle::Graph
+description: The in-memory knowledge graph — concepts as nodes, cross-links as directed edges, with type and tag indexes.
+resource: gems/okf/lib/okf/bundle/graph.rb
+tags: [graph, pure]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle/graph.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/graph.rb
+---
+
+# Overview
+
+`OKF::Bundle::Graph` turns a [bundle](bundle.md) into nodes and edges:
+[concepts](concept.md) become nodes keyed by id, and bundle-relative
+cross-links (`@okf-eco format/cross-links`) become directed edges. It is pure — it
+carries no presentation concerns; sizing and colour belong to a renderer like
+the [graph server](../capabilities/graph-server.md).
+
+# Fidelity is a build option
+
+The same graph ships at three weights, so a client downloads only what it needs
+and fetches the rest on demand:
+
+| Build | Node payload |
+|-------|--------------|
+| default (`body: true`) | id, type, title, description, tags, **body** |
+| `body: false` | everything but the body |
+| `minimal: true` | just id and title — the leanest payload to draw |
+
+# Indexes come free at every weight
+
+Regardless of node fidelity, the graph exposes two inverted indexes computed from
+every concept:
+
+- `type_index` — `{ type => [id, …] }`, so even a minimal client can colour nodes
+  by [`type`](concept.md). A concept whose type is missing *or blank* indexes
+  under `Untyped`: §11 condition 2 rejects the two identically (the
+  [validator](../capabilities/validator.md) asks `OKF.blank?`, not `empty?`), so
+  sorting them into different buckets would give `type: "  "` a row of its own,
+  labelled with spaces;
+- `tag_index` — `{ tag => [id, …] }`, so it can filter by tag.
+
+Those indexes, plus `unlinked_ids` (degree-0 nodes), are what the
+[read views](../capabilities/read-views.md) — `types`, `tags`, `stats`, `loose`
+— are built from, and what their `--type`/`--dir`/`--tag` filters match against.
+
+# Reduced to a skeleton
+
+Where this graph is the full wiring, the [skeleton](skeleton.md) is the same
+graph made holdable: concepts collapsed into their directory, the links between
+two directories collapsed into one weighted arc, and every link tagged with the
+cut it survives. It is the reduction [`graph --traffic`](../capabilities/read-views.md)
+reads for cohesion and the [graph page](../capabilities/graph-server.md) lays a
+large bundle out on — built from this graph's own nodes and edges, and just as
+pure.

data/.okf/model/index.md

@@ -0,0 +1,9 @@
+# The model
+
+The pure, in-memory data structures the gem builds a bundle out of — no disk, no
+stdio. Everything else reads or renders these.
+
+* [Concept](concept.md) - one file's worth of knowledge: frontmatter plus body, with a stable id.
+* [Bundle](bundle.md) - a collection of concepts you validate, lint, and graph.
+* [Graph](graph.md) - concepts as nodes, cross-links as edges, plus type and tag indexes.
+* [Skeleton](skeleton.md) - the graph reduced: directories, the weighted arcs between them, and each link with the cut it survives.

data/.okf/model/skeleton.md

@@ -0,0 +1,76 @@
+---
+type: Component
+title: OKF::Bundle::Skeleton
+description: The graph reduced to what a reader can hold — directories, the weighted arcs between them, and each link with the cut it survives.
+resource: gems/okf/lib/okf/bundle/skeleton.rb
+tags: [graph, pure]
+generated:
+  by: human:maintainer
+  at: 2026-07-23T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle/skeleton.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/skeleton.rb
+  - title: gems/okf/lib/okf/cli/graph.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/cli/graph.rb
+---
+
+# Overview
+
+`OKF::Bundle::Skeleton` is the [graph](graph.md) reduced to what a reader can
+hold in their head. It is built from a graph's nodes and edges, does no I/O, and
+decides nothing about how any of it is drawn — the same purity the graph keeps,
+one level of abstraction up. Two consumers read it: [`graph
+--traffic`](../capabilities/read-views.md) prints its directory reduction, and
+the [graph page](../capabilities/graph-server.md)'s link layer lays a large
+bundle out on the backbone it names.
+
+A dense bundle is not dense the way a hub-and-spoke picture is. Measured on a
+47-concept bundle with 227 links, the top hub takes 13 inbound and the median 4 —
+no 80/20 to exploit, so dropping two-thirds of the *concepts* still leaves 53
+edges. The density lives **between directories**: 173 of those 227 links (76%)
+cross a directory boundary. That is the reduction worth drawing, and it is why
+this class exists at all.
+
+# The two things it produces
+
+- **`dirs` + `arcs`** — the reduction as counts: one row per directory, one
+  weighted arc per ordered pair of directories. This is what `graph --traffic`
+  prints, with **cohesion** (a directory's internal share of its own traffic)
+  derived from them. Directories come off the concept *id* (`OKF.dir_of`), not
+  the file path, so this agrees with the graph's own `catalog` and `--dir`
+  filter — the side that follows the id, because the edges do.
+- **`edges`, each with its `keep_at`** — the smallest cut at which a link
+  survives. Nothing prints these; they are what lets the graph page lay a large
+  bundle out on its strongest links first, inlined into the page as `EDGE_CUT`
+  because the layout needs them before any `fetch()` could answer.
+
+Both are emitted **unthresholded**, and `#suggested_cut` *names* where to cut
+rather than cutting — so a caller narrows the picture without this class ever
+having to know what a picture is.
+
+# The cut is fitted, not fixed
+
+A fixed arc cut cannot serve both ends of the size range: measured at weight 3
+across ten bundles, it left **2 arcs on one and 136 on another** — too tight to
+be a picture at one end, no reduction at all at the other. What stays roughly
+constant as a bundle grows is not the arc count but the arcs *per box*, since a
+node-link diagram reads at about one to two edges per node regardless of size. So
+`#suggested_cut` targets 1.5 arcs per directory and reports the weight that
+delivers it, floored at 8 for the small end. Cohesion is computed over **every**
+arc regardless of the cut, so narrowing the drawn picture never moves the
+evidence under it.
+
+# The spine is a sparsifier, not a sample
+
+The `keep_at === 0` set is the **spine**: each concept's single most-connected
+neighbour. It is chosen, not sampled, and the property that earns it the name is
+that it **touches every linked concept**, so a layout run over it alone strands
+nothing and the arrangement is a real one rather than a sketch to be redone.
+
+It is the local-degree sparsifier (Lindner et al.) with a union rule — an edge
+survives if *either* endpoint kept it — which is what stops it from stranding the
+quiet half of a bundle the way a global "drop the weakest edges" rule does. It is
+**not** the disparity filter, the usual name in this territory: that reads an
+edge's weight against its endpoint's total, and every link here weighs exactly 1,
+which makes every proportion identical and the filter a coin toss. Weighted-graph
+tools do not transfer to an unweighted graph just because both are graphs.

data/.okf/overview.md

@@ -0,0 +1,87 @@
+---
+type: Overview
+title: okf at a glance
+description: A light Ruby gem that reads, searches, validates, lints, and serves Open Knowledge Format v0.2 bundles.
+tags: [okf, gem, diagram]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: README.md
+    resource: https://github.com/serradura/okf/blob/main/README.md
+  - title: AGENTS.md
+    resource: https://github.com/serradura/okf/blob/main/AGENTS.md
+---
+
+# Overview
+
+**okf** — the gem on RubyGems — operates on OKF v0.2 (`@okf-eco format/okf-format`)
+bundles: directories of Markdown files with YAML frontmatter that humans and
+agents both read from one source. It does not define new knowledge storage; it
+gives you leverage over knowledge that already lives as Markdown.
+
+```mermaid
+flowchart LR
+  skill["companion<br/>agent skill"] -. authors/curate .-> bundle[("OKF v0.2 bundle<br/>Markdown + YAML")]
+  bundle --> model["pure model<br/>Concept · Bundle · Graph"]
+  skill -. execute .-> cli
+  subgraph cli ["okf CLI"]
+    validate["validate — legal? §11"]
+    lint["lint — well-curated?"]
+    search["search — which concept?"]
+    server["server — explore"]
+  end
+  model --> cli
+  model --> library["library API<br/>embed in Ruby"]
+```
+
+Over such a bundle the gem gives you seven capabilities behind one
+[command-line tool](cli.md):
+
+| Capability                                               | What it answers                   | Verb             |
+| -------------------------------------------------------- | --------------------------------- | ---------------- |
+| [Companion agent skill](capabilities/agent-skill.md)     | Can an agent author it?           | `skill`          |
+| [Conformance validator](capabilities/validator.md)       | Is this a legal OKF bundle? (§11)  | `validate`       |
+| [Curation linter](capabilities/linter.md)                | Is it navigable, complete, fresh? | `lint` / `loose` |
+| [Ranked text search](capabilities/search.md)             | Which concept covers X?           | `search`         |
+| [Interactive graph server](capabilities/graph-server.md) | Can I explore it visually?        | `server`         |
+| [Static render](capabilities/render.md)                  | Can I ship a serverless snapshot? | `render`         |
+| [Library API](capabilities/library-api.md)               | Can my Ruby program use it?       | (in-process)     |
+
+Beside the gem's seven, the sibling surfaces. The
+MCP server (`@okf-mcp design/the-tool-set`) (`okf-mcp`) projects the same kernel
+onto the Model Context Protocol so any MCP-capable agent host reads these
+bundles without a terminal — ten read-only tools, concepts as resources a host
+can attach on its own, and the [skill's](capabilities/agent-skill.md) playbooks
+as prompts. The enforcement layer (`@okf-eco gems/okf-pro`) (`okf-pro`)
+goes the other way and is the only surface here that **writes**: it generates an
+agent's knowledge repository — bundle, hooks, pre-commit, CI, skill — and then
+holds it to a few invariants at all three doors, under a contract where a gate
+that cannot check refuses rather than shrugs.
+
+Alongside those, a family of [read views](capabilities/read-views.md) —
+`index`, `catalog`, `files`, `types`, `tags`, `stats`, `graph` — print the bundle at a
+glance so an agent reads it without a browser.
+
+Knowledge rarely lives in one bundle, so `okf server` hosts one, several, or every
+bundle in a per-user [registry](registry.md) — one hub, one switcher, no per-repo
+server to remember.
+
+# The two ideas it inherits from the format
+
+- **Dual audience.** Every file serves a human skimming it _and_ an agent
+  extracting from it, so bodies are structural Markdown and
+  links (`@okf-eco format/cross-links`) are plain Markdown links — both readers already
+  understand them.
+- **The graph is emergent.** Files are nodes, Markdown links are edges. You never
+  declare a graph; the gem [builds one](model/graph.md) from how concepts link.
+
+# Design ethos
+
+The gem is deliberately light so it runs on the Ruby an OS already ships. That
+ethos is not incidental — it is enforced by [hard constraints](design/):
+a [Ruby 2.4 floor](design/ruby-floor.md), exactly
+[three runtime dependencies](design/runtime-dependencies.md), and a
+[core/shell split](design/core-shell-split.md) that keeps all logic pure and
+testable without disk. Everything else — no ActiveSupport, no build step, no
+JavaScript toolchain — follows from those.