okf 1.4.0 → 1.5.0

data/.okf/cli.md

@@ -1,52 +0,0 @@
----
-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

@@ -1,58 +0,0 @@
----
-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

@@ -1,10 +0,0 @@
-# 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 sanitizes concept bodies and escapes inlined data; both XSS paths are closed.

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

@@ -1,45 +0,0 @@
----
-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

@@ -1,44 +0,0 @@
----
-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

@@ -1,40 +0,0 @@
----
-type: Constraint
-title: The server trust boundary
-description: The served page sanitizes each concept body before rendering and escapes inlined data, so both XSS paths into the page are closed.
-resource: lib/okf/server/graph/template.html.erb
-tags: [security, server, xss]
-timestamp: 2026-07-12T12:00:00Z
----
-
-# Overview
-
-The [graph server](../capabilities/graph-server.md) renders whatever bundle you
-point it at, and a bundle is just files, so the page has to assume a body might
-carry active content. Two defenses handle that — one for each path into the page.
-
-# Where the boundary sits
-
-There are two data paths into the page, and each carries its own guard:
-
-| 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=`) | `marked` renders the Markdown, then `DOMPurify.sanitize` scrubs it before it reaches the DOM | yes — scripts, handlers, and `javascript:` URLs are stripped |
-
-The [description](../format/cross-links.md) shown in the inspector takes a third
-path and never needs the client's help: the server escapes it
-(`OKF::Server::App#description_fragment`) before sending it, so it arrives inert.
-
-# What sanitizing does not cover
-
-DOMPurify removes the code, not the content. The page still fetches and shows the
-links, images, and Mermaid diagrams a body names (Mermaid runs in its `strict`
-mode), and it pulls Cytoscape, marked, and DOMPurify from a CDN. So the rule is no
-longer _only serve bundles you trust_ — it is the ordinary care you would give any
-document from a source you do not know.
-
-# Citations
-
-[1] [README.md — Server trust boundary](https://github.com/serradura/okf-gem/blob/main/README.md) — the two-defense summary.
-[2] [lib/okf/server/graph/template.html.erb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/graph/template.html.erb) — `json_for_script` and the `DOMPurify.sanitize(marked.parse(...))` render.

data/.okf/format/citations.md

@@ -1,33 +0,0 @@
----
-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.

data/.okf/format/cross-links.md

@@ -1,52 +0,0 @@
----
-type: Format
-title: Cross-links (spec §5)
-description: Plain Markdown links between concepts that become the knowledge graph's directed edges.
-resource: lib/okf/markdown/links.rb
-tags: [format, links, graph, diagram]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# Overview
-
-A cross-link is an ordinary Markdown link from one concept's body to another
-concept file. `OKF::Markdown::Links` extracts them, and that is the whole edge
-mechanism: the [graph](../model/graph.md) is *emergent* — you never declare it,
-it arises from the links you write. Good linking is good knowledge modelling.
-
-```mermaid
-flowchart LR
-  orders["orders.md"] -->|prose link| customers["customers.md"]
-  orders -->|prose link| refunds["refunds.md"]
-  refunds -->|prose link| customers
-```
-
-Files are the nodes; the Markdown links in their bodies are the directed edges.
-Nobody declared this graph — it fell out of three files linking each other.
-
-# Untyped on purpose
-
-A Markdown link asserts only "these two relate." The *kind* of relationship —
-depends-on, supersedes, derived-from — lives in the **prose around the link**,
-never in a made-up typed-edge syntax. Both a human and an agent already
-understand a Markdown link, which is the point of the [dual audience](../overview.md).
-
-# What counts as an edge
-
-- **Bundle-relative links** (e.g. `/model/graph.md`) resolve to another concept
-  and become a directed edge. Absolute bundle-relative targets are preferred so
-  links survive file moves.
-- **External links** — `http(s)://`, `mailto:` — are surfaced separately and are
-  *not* graph edges.
-- A link to a concept that does not exist yet is **not an error** (§5.3): it is
-  not-yet-written knowledge, which consumers MUST tolerate and the
-  [linter](../capabilities/linter.md) surfaces as backlog demand.
-
-The [graph server](../capabilities/graph-server.md) draws these edges; a
-degree-0 concept (no links in or out) is a *loose* file the
-[read views](../capabilities/read-views.md) flag.
-
-# Citations
-
-[1] [lib/okf/markdown/links.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/markdown/links.rb) — link extraction.
-[2] [SPEC.md §5](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/reference/SPEC.md) — cross-links and tolerance of broken targets.

data/.okf/format/frontmatter.md

@@ -1,38 +0,0 @@
----
-type: Format
-title: Frontmatter (spec §4)
-description: The YAML header on every concept, parsed through the gem's single, hardened YAML gateway.
-resource: lib/okf/markdown/frontmatter.rb
-tags: [format, yaml, frontmatter]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# Overview
-
-Every [concept](../model/concept.md) opens with a YAML frontmatter block delimited
-by `---` lines. `OKF::Markdown::Frontmatter` parses it and is the inverse of
-`Concept#to_markdown`. The only **required** key is
-[`type`](../format/okf-format.md); `title`, `description`, `resource`, `tags`, and
-`timestamp` are recommended, and producers may add any other keys — consumers
-preserve unknown keys and never reject a document for having them.
-
-# The one YAML gateway
-
-All YAML in the gem flows through this one class. That is a deliberate security
-and portability boundary, not an accident of layering:
-
-- it uses `safe_load` — permitting `Date`/`Time`, forbidding aliases — so a
-  bundle can never execute arbitrary Ruby on load;
-- it carries the Psych `<3.1` positional-argument shim, so the gem parses
-  identically on the old Ruby versions the [2.4 floor](../design/ruby-floor.md)
-  targets;
-- `stringify_keys` lives here so the gem needs no ActiveSupport (see
-  [runtime dependencies](../design/runtime-dependencies.md)).
-
-The rule is enforced by convention: `YAML.safe_load` / `YAML.load` appear
-**nowhere else** in the codebase.
-
-# Citations
-
-[1] [lib/okf/markdown/frontmatter.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/markdown/frontmatter.rb) — the parser and the Psych shim.
-[2] [SPEC.md §4](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/reference/SPEC.md) — concept documents and frontmatter.

data/.okf/format/index.md

@@ -1,9 +0,0 @@
-# The format
-
-What Open Knowledge Format v0.1 is — the substrate the gem reads, validates, and
-serves. The gem operates on this format; it does not extend it.
-
-* [OKF v0.1](okf-format.md) - portable knowledge as a directory of Markdown + YAML frontmatter files.
-* [Frontmatter](frontmatter.md) - the YAML header on every concept (spec §4) and the gem's one YAML gateway.
-* [Cross-links](cross-links.md) - plain Markdown links that become the knowledge graph's edges (spec §5).
-* [Citations](citations.md) - the provenance convention that keeps a bundle trustworthy (spec §8).

data/.okf/format/okf-format.md

@@ -1,43 +0,0 @@
----
-type: Format
-title: Open Knowledge Format v0.1
-description: Portable knowledge as a directory of Markdown files with YAML frontmatter that humans and agents both read.
-resource: lib/okf/skill/reference/SPEC.md
-tags: [okf, format, conformance]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# Overview
-
-OKF is a bundle: a directory of UTF-8 Markdown files. Each non-reserved file is
-one **concept** with two parts — a [YAML frontmatter block](frontmatter.md) and a
-Markdown body. Knowledge is the files; the graph is
-[how they link](cross-links.md). There is no schema registry, no runtime, no
-SDK — the format is minimal on purpose, and the gem is what gives it leverage.
-
-# Reserved files
-
-Two filenames are reserved and are never concepts:
-
-| File | Role | Constraint |
-|------|------|------------|
-| `index.md` | a directory listing for progressive disclosure | carries **no** frontmatter — except the bundle-root `index.md`, which may carry *only* `okf_version` |
-| `log.md` | a dated change history, newest first | date headings are ISO `YYYY-MM-DD` |
-
-# §9 conformance is narrow and tolerant
-
-The spec makes only three conditions **hard**, and the
-[validator](../capabilities/validator.md) fails a bundle on any of them:
-
-1. **§9.1** — every non-reserved `.md` file has a parseable frontmatter block;
-2. **§9.2** — every such block has a **non-empty `type`**;
-3. **§9.3** — every reserved file present is well-formed.
-
-Everything else is soft guidance a consumer MUST tolerate: missing optional
-fields, unknown [`type`](../model/concept.md) values, and **broken cross-links**.
-Judging those is the [linter](../capabilities/linter.md)'s job, held separate on
-purpose.
-
-# Citations
-
-[1] [SPEC.md](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/reference/SPEC.md) — the OKF v0.1 specification, authored by Google Cloud Platform, redistributed under Apache 2.0.

data/.okf/index.md

@@ -1,18 +0,0 @@
----
-okf_version: "0.1"
----
-
-# okf-gem capabilities
-
-What the `okf` gem does over an Open Knowledge Format v0.1 bundle: read it,
-validate it, lint it, serve it, and let an agent author it. Start here.
-
-* [Overview](overview.md) - the gem at a glance: the five capabilities and the design ethos behind them.
-* [Command line](cli.md) - the `okf` executable — the one layer that parses argv, prints, and exits.
-
-# Areas
-
-* [The format](format/) - what OKF v0.1 is — the Markdown + YAML frontmatter the gem operates on.
-* [The model](model/) - the pure in-memory data structures: concept, bundle, graph.
-* [Capabilities](capabilities/) - the five things the gem does: validate, lint, serve, the library, the skill.
-* [Design constraints](design/) - the enforced boundaries that keep the gem light and honest.

data/.okf/log.md

@@ -1,10 +0,0 @@
-# Update Log
-
-## 2026-07-12
-* **Sync**: caught the bundle up with the gem at 1.1.0 — the [graph server](capabilities/graph-server.md) now sanitizes each fetched body with DOMPurify before rendering, so the [server trust boundary](design/server-trust-boundary.md) closes the on-demand render path (its [design listing](design/) reworded to match), and the [library API](capabilities/library-api.md) notes that `require "okf"` loads the library alone now that the CLI and skill load on demand.
-* **Sync**: caught the bundle up with the CLI at 1.0.0 — documented the new `index` command (the §6 progressive-disclosure map, the read view that sees the reserved `index.md` layer), compact-by-default JSON with `--pretty`, and `--fields`/`--except` projection on the list views, in [read views](capabilities/read-views.md) plus the `index`-verb enumerations in the [CLI](cli.md), the [overview](overview.md), and the [capabilities](capabilities/) index listing.
-
-## 2026-07-11
-* **Creation**: seeded the bundle documenting okf-gem's capabilities at version 0.1.0 — the [overview](overview.md), the [CLI](cli.md), and the [format](format/), [model](model/), [capabilities](capabilities/), and [design](design/) areas.
-* **Update**: added Mermaid diagrams (tagged `diagram`) to five concepts — [overview](overview.md), the [core/shell split](design/core-shell-split.md), the [graph server](capabilities/graph-server.md), the [library API](capabilities/library-api.md), and [cross-links](format/cross-links.md).
-* **Sync**: caught the bundle up with the CLI — documented the new `types` command, the cross-view `--type`/`--area`/`--tag` filters, and `tags --by type|area` in [read views](capabilities/read-views.md), the [CLI](cli.md) front end, the [graph](model/graph.md) indexes, and the [capabilities](capabilities/) index listing.

data/.okf/model/bundle.md

@@ -1,38 +0,0 @@
----
-type: Component
-title: OKF::Bundle
-description: The pure in-memory collection of concepts that validate, lint, and graph run over.
-resource: lib/okf/bundle.rb
-tags: [model, bundle, pure]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# 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 that fail to parse do not vanish and do
-not abort the build: they are collected in `bundle.unparseable`. 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 — §9'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.
-
-# Citations
-
-[1] [lib/okf/bundle.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/bundle.rb) — the in-memory collection and its `#validate` / `#lint` / `#graph` entry points.

data/.okf/model/concept.md

@@ -1,44 +0,0 @@
----
-type: Component
-title: OKF::Concept
-description: The pure in-memory model of a single OKF file — frontmatter, body, and a stable id.
-resource: lib/okf/concept.rb
-tags: [model, concept, pure]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# Overview
-
-`OKF::Concept` is the atomic node: a `path`, a parsed
-[`frontmatter`](../format/frontmatter.md) 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 `path` minus `.md` (e.g. `model/graph.md` → `model/graph`). That id
-is the concept's **stable identifier** across the whole system — it is the graph
-node key, the link target, and the thing you name a concept for. Name a file for
-what it *is*, not where it sits, because the id follows the path.
-
-# 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`, `#timestamp` — typed
-  reads over the frontmatter;
-- `#links` — the bundle-relative [cross-links](../format/cross-links.md) (edges);
-- `#external_links` — URLs and `mailto:` (not edges);
-- `#citations` — the [`# Citations`](../format/citations.md) entries;
-- `#to_markdown` — the inverse of the frontmatter parser;
-- `#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.
-
-# Citations
-
-[1] [lib/okf/concept.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/concept.rb) — the pure concept model.

data/.okf/model/graph.md

@@ -1,44 +0,0 @@
----
-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: lib/okf/bundle/graph.rb
-tags: [model, graph, pure]
-timestamp: 2026-07-11T21:40:00Z
----
-
-# 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](../format/cross-links.md) 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);
-- `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`/`--area`/`--tag` filters match against.
-
-# Citations
-
-[1] [lib/okf/bundle/graph.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/bundle/graph.rb) — graph construction and the type/tag indexes.

data/.okf/model/index.md

@@ -1,8 +0,0 @@
-# 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.