okf 1.3.0 → 1.5.0

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.

data/.okf/overview.md

@@ -1,67 +0,0 @@
----
-type: Overview
-title: okf-gem at a glance
-description: A light Ruby gem that reads, validates, lints, and serves Open Knowledge Format v0.1 bundles.
-tags: [okf, gem, overview, diagram]
-timestamp: 2026-07-12T12:00:00Z
----
-
-# Overview
-
-**okf-gem** — `okf` on RubyGems — operates on [OKF v0.1](format/okf-format.md)
-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.1 bundle<br/>Markdown + YAML")]
-  bundle --> model["pure model<br/>Concept · Bundle · Graph"]
-  skill -. execute .-> cli
-  subgraph cli ["okf CLI"]
-    validate["validate — legal? §9"]
-    lint["lint — well-curated?"]
-    server["server — explore"]
-  end
-  model --> cli
-  model --> library["library API<br/>embed in Ruby"]
-```
-
-Over such a bundle the gem gives you five 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? (§9)  | `validate`       |
-| [Curation linter](capabilities/linter.md)                | Is it navigable, complete, fresh? | `lint` / `loose` |
-| [Interactive graph server](capabilities/graph-server.md) | Can I explore it visually?        | `server`         |
-| [Library API](capabilities/library-api.md)               | Can my Ruby program use it?       | (in-process)     |
-
-Alongside those, a family of [read views](capabilities/read-views.md) —
-`index`, `catalog`, `files`, `tags`, `stats`, `graph` — print the bundle at a
-glance so an agent reads it without a browser.
-
-# 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](format/cross-links.md) 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
-[two 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.
-
-# Citations
-
-[1] [README.md](https://github.com/serradura/okf-gem/blob/main/README.md) — the gem's own overview.
-[2] [AGENTS.md](https://github.com/serradura/okf-gem/blob/main/AGENTS.md) — the maintainer guide.