okf 1.0.0

data/lib/okf/skill/reference/cli.md

@@ -0,0 +1,196 @@
+# OKF tool verbs — the `okf` CLI
+
+`validate`, `lint`, `loose`, `index`, `catalog`, `files`, `tags`, `types`, `stats`,
+`server`, and `graph` are **not** eyeball passes and are not
+reimplemented in this skill. They run the deterministic `okf` executable shipped by
+the companion gem — the single source of truth for OKF mechanics. Your job is to
+invoke it correctly and interpret the result, not to reason out conformance by hand.
+
+## Presence guard
+
+Check the tool exists before relying on it. If it is missing, the gem is not
+installed — say so and stop; never fabricate a result:
+
+```bash
+command -v okf >/dev/null || echo "okf CLI not found — install it: 'gem install okf' (or from a checkout: 'cd gem && bundle exec rake install')"
+```
+
+## Invocation
+
+The surface is self-describing — `okf --help` maps every verb, `okf <verb> --help`
+its flags. Ask the tool for what exists; this file carries only what `--help`
+cannot: each verb's semantics, its traps, and its JSON shape.
+
+**`--json` is compact by design.** Every emitting verb prints single-line JSON —
+the token-efficient substrate you consume; `--pretty` (which implies `--json`)
+indents it for a human. The bytes differ, the JSON is identical, so parse either.
+When you only need to *scan* a bundle, the plain text views are lighter still than
+JSON (they print each key once, not per row) — reach for `--json` when you need to
+extract structure, not merely read it.
+
+**Project the JSON to what you'll read.** On `index`, `catalog`, and `files`,
+`--fields a,b` keeps only those properties and `--except a,b` drops them
+(mutually exclusive; both imply `--json`; an unknown name is a usage error that
+lists the valid ones). Projection happens before emission, so you pay no tokens
+for a field you dropped — e.g. `okf index <dir> --except body,listing` is the lean
+directory *skeleton* (structure + rollups), and on a large bundle that is the
+difference between a few hundred bytes and hundreds of KB, since the per-item rows
+(`listing`) dominate at scale. `okf index --no-body` is shorthand for dropping just
+`body`.
+
+**Exit codes:** `0` success · `1` non-conformant bundle (or a `lint --fail-on`
+threshold crossed) · `2` usage error. `graph` and `server` are best-effort
+(§9): a file with invalid frontmatter is skipped and noted on stderr, never fatal.
+
+## validate — the hard gate (§9)
+
+Implements the spec's §9 conformance definition exactly:
+
+- **§9.1** every non-reserved file has a parseable YAML frontmatter block;
+- **§9.2** every such block has a non-empty `type`;
+- **§9.3** any `index.md`/`log.md` present follows §6/§7 (a nested `index.md` has
+  no frontmatter, a root `index.md` carries only `okf_version`, `log.md` date
+  headings are ISO `YYYY-MM-DD`).
+
+`ERROR`s are the three conditions above; the bundle is non-conformant until every
+one is fixed. `warn`s are soft — missing recommended fields, non-list tags, an
+unparseable timestamp, and **broken cross-links, which §5.3 explicitly tolerates**.
+Fix warnings when cheap; never block on them. Use `--json` in CI.
+
+## lint — curation quality (advisory)
+
+Asks the complementary question to `validate`: not "is this legal OKF?" but "is
+this well-curated, navigable, trustworthy?" — precisely over the things §9 forbids
+`validate` from rejecting. It has its own report, never emits conformance errors,
+and **exits `0` even with findings** unless you pass `--fail-on warn`.
+
+Six conceptual categories, each backed by individual checks (names in parens):
+
+- **reachability** — orphans, concepts not in any index, disconnected islands,
+  and unlinked (degree-0) files
+  (`orphan`, `not_in_index`, `disconnected_component`, `unlinked`)
+- **backlog** — demand-ranked missing concepts (linked-to but absent), broken index entries
+  (`missing_concept`, `broken_index_entry`)
+- **completeness** — stubs, missing `title` / `description` / `timestamp`
+  (`stub`, `missing_title`, `missing_description`, `missing_timestamp`)
+- **freshness** — concepts older than a cutoff (`stale`) — **only computed when you
+  pass `--stale-after`; a plain `okf lint` never reports staleness at all**
+- **provenance** — uncited external claims, broken citations, spec §8
+  (`uncited_external`, `broken_citation`)
+- **hygiene** — duplicate titles, unused/undefined reference links, self-links
+  (`duplicate_title`, `unused_reference_def`, `undefined_reference`, `self_link`)
+
+`--only` / `--except` filter by the **individual check names above**, not the
+category labels — `okf lint <dir> --only orphan,stub` works; `--only reachability`
+is an error. Two knobs tune specific checks: `--min-body N` sets the `stub` body
+threshold in characters (default 50), and `--stale-after DUR` sets the `stale`
+cutoff — a duration like `90d` or `12w`, or an ISO date like `2026-01-01` (a bare
+number is rejected).
+
+`lint --json` is the structured substrate you consume to reason about the two
+things lint deliberately does **not** compute — contradictions and *semantic*
+staleness — which need understanding of meaning.
+
+## loose — files with no graph connections (by folder)
+
+Lists the **loose** files — concepts with graph **degree 0**: no cross-links in
+*or* out — grouped by folder. It is a focused, folder-organized view over `lint`'s
+`unlinked` check (`okf loose <dir>` ≈ `okf lint <dir> --only unlinked`, regrouped),
+for the "which files float in the graph?" question. Advisory: **exits `0`**; `--json`
+emits `{ bundle, count, loose: [{ id, title, dir }] }`.
+
+**Loose ≠ orphan** — the trap. `lint`'s `orphan` is about *reachability*, and an
+`index.md` listing makes a file reachable, so an indexed file is never an orphan.
+But an index listing is **not a graph edge**: a file can be listed in an index yet
+have no cross-links, so it floats in the graph while `lint` reports it as reachable.
+`loose`/`unlinked` catch exactly that gap. A loose file is not automatically a
+defect — a terminal leaf (a backlog item, a spec reference) can be loose by design;
+`loose` surfaces the set so you can judge intent (see `maintain` in authoring.md).
+
+## index — the progressive-disclosure map (§6)
+
+The "orient before you read" view, and the one read verb that sees the layer the
+others can't: `index.md` files are reserved/structural, so `catalog`/`files`/… (all
+concept views) never show them. `okf index <dir>` prints one entry per directory
+that holds concepts or carries an `index.md`, root first — the authored index body
+(frontmatter stripped), a `type`/`tag` rollup over the concepts that live directly
+there, its child directories, and the concept listing. Run it first when picking up
+an existing bundle: it is the cheapest high-signal orientation, and it surfaces
+enumeration drift a grep can't (you can't grep for a listing entry that is *missing*).
+
+`--area A` narrows to a directory and is **repeatable** — `--area model --area
+format` shows both; `root` names the bundle root. `--no-body` drops the prose to a
+skeleton (headers, rollups, child pointers). For a directory that has concepts but
+**no `index.md`**, the listing is **synthesized** from the concepts' descriptions
+and tagged `(no index.md)` — §6 explicitly permits synthesizing a map on the fly.
+
+It is a **read view**: advisory, always exit 0. A synthesized directory is a
+*signal* (a map worth writing), never a defect — `index` emits no lint findings and
+never fails a bundle. JSON: `{ bundle, count, directories: [{ dir, index_path,
+present, synthesized, count, types, tags, subdirs, body, listing: [{ id, title,
+description, type, tags }] }] }`.
+
+## catalog / files / tags / types / stats — the server views, as text
+
+The browser server (below) has Catalog, Files, Tags and Stats panels; these
+verbs reproduce them on the CLI so an agent can read a bundle without a browser.
+All are advisory reads (exit 0) sharing one data source (per-concept metadata plus
+in/out link degree). Add `--json` to any for a machine substrate.
+
+- **`catalog`** — every concept with its metadata (type, status, tags, timestamp,
+  in/out link degree, description), grouped by top-level area. The "what's here, in
+  detail" view. JSON: `{ bundle, count, concepts: [{ id, title, type, description,
+  tags, timestamp, status, backlog_ref, dir, area, links_out, links_in }] }`.
+- **`files`** — the folder tree: each concept's filename + title, grouped by
+  directory. The "how it's organised" view. JSON: `{ bundle, count, files: [{ path,
+  id, dir, type, title, description }] }`.
+- **`tags`** — every tag with the concepts that carry it, ordered by count
+  descending. The "what themes dominate" view. JSON: `{ bundle, count, tags: [{ tag,
+  count, concepts: [id, …] }] }`. `--by type|area` regroups the list per concept
+  dimension with **within-group** counts (a tag spanning groups appears in each) —
+  the substrate for tag curation; the judgment recipe lives in
+  [authoring.md](authoring.md)'s maintain playbook. JSON: `{ bundle, count, by,
+  groups: [{ <dim>, count, tags: […] }] }`.
+- **`types`** — every type with the concepts that carry it, ordered by count
+  descending. The "what kinds of knowledge" view. JSON: `{ bundle, count, types:
+  [{ type, count, concepts: [id, …] }] }`.
+- **`stats`** — bundle rollups: concept / area / type / cross-link / distinct-tag
+  totals plus per-type and per-area breakdowns. The "shape at a glance" view. JSON:
+  `{ bundle, concepts, areas, concept_types, cross_links, distinct_tags, by_type, by_area }`.
+
+The four list views narrow with the same filters the browser panels offer —
+`--type TYPE`, `--area AREA`, `--tag TAG`; each takes the ones orthogonal to
+itself (`tags` can't filter by tag). Matching is case-insensitive and exact; a
+concept at the bundle root lives in the `(root)` area, which `--area` also accepts
+as plain `root` (no shell quoting). A filter that matches nothing is an empty view,
+not an error: `okf tags <dir> --area billing --json` answers "which tags does the
+billing area use?", `okf catalog <dir> --tag auth` answers "what carries the auth
+tag?".
+
+Reach for `stats` first to size a bundle, `catalog`/`files` to enumerate it, `tags`
+to find thematic clusters — all without standing up the server.
+
+## server — interactive graph server
+
+Starts a local HTTP server (`okf server <dir>`; `-p`/`--port`, default 8808, and
+`--bind`) and prints its URL — stop it with Ctrl-C. The page boots from a lean
+payload (nodes carry only `id` and `title`, plus compact type/tag indexes) and
+fetches each concept's markdown body **live from disk** as you click it, so the
+initial load stays small and edits show without a restart. Concepts render as nodes
+coloured by `type` and sized by degree, links as edges, with a detail panel
+(rendered markdown, "Links to" / "Linked from" backlinks), layout switching,
+type/area/tag filters on every view, and search. It is a Rack app, so the same
+server can be mounted in a host app (e.g. Rails).
+
+**Trust boundary:** the page loads Cytoscape and marked from a CDN and
+renders each concept's markdown body **without sanitization**, so only serve
+bundles you trust. Inlined graph data cannot break out of its `<script>` (every
+`<` is escaped), but the fetched markdown is rendered unsanitized.
+
+## graph — the raw structure
+
+Prints the node/edge graph. `--json` emits a machine-readable dump (`nodes` with
+`id`/`type`/`title`/`description`/`tags`, and `edges`) you can pipe into other
+analysis or use to plan a traversal before consuming a large bundle. `--no-body`
+drops each node's body; `--minimal` ships only `id`/`title` plus the type/tag
+indexes — the lean shape the `server` page boots from.

data/lib/okf/skill/templates/concept.md

@@ -0,0 +1,24 @@
+---
+type: <Concept type, e.g. Service, BigQuery Table, Metric, Playbook, Decision>
+title: <Human-readable display name>
+description: <Single sentence summarizing the concept.>
+resource: <Canonical URI of the underlying asset — omit for abstract concepts>
+tags: [<tag>, <tag>]
+timestamp: <ISO 8601, e.g. 2026-06-14T10:00:00Z>
+---
+
+# Overview
+
+<What this concept is and why it matters.>
+
+# Schema
+
+<Use for assets with fields/columns; otherwise replace with relevant sections.>
+
+| Field | Type | Description |
+|-------|------|-------------|
+|       |      |             |
+
+# Citations
+
+[1] [<source title>](<url>)

data/lib/okf/skill/templates/index.md

@@ -0,0 +1,8 @@
+# <Directory / Group Heading>
+
+* [<Title>](<relative-url>) - <short description from the concept's frontmatter>
+* [<Title>](<relative-url>) - <short description>
+
+# <Another Group>
+
+* [<Subdirectory>](<subdir>/) - <short description of the subdirectory>

data/lib/okf/skill/templates/log.md

@@ -0,0 +1,6 @@
+# Update Log
+
+## <YYYY-MM-DD>
+* **Creation**: <what was created> — [<concept>](<bundle-relative-path>).
+* **Update**: <what changed> — [<concept>](<bundle-relative-path>).
+* **Deprecation**: <what was retired> — [<concept>](<bundle-relative-path>).

data/lib/okf/skill/templates/root-index.md

@@ -0,0 +1,12 @@
+---
+okf_version: "0.1"
+---
+
+# <Directory / Group Heading>
+
+* [<Title>](<relative-url>) - <short description from the concept's frontmatter>
+* [<Title>](<relative-url>) - <short description>
+
+# <Another Group>
+
+* [<Subdirectory>](<subdir>/) - <short description of the subdirectory>

data/lib/okf/skill.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OKF
+  # Installs this gem's companion agent skill — the SKILL.md + reference/ +
+  # templates/ that teach an agent to author, maintain, and consume OKF bundles
+  # and to drive the `okf` executable — into a destination directory.
+  #
+  # The skill ships *inside* the gem (under lib/okf/skill), so `gem install okf`
+  # provides both the CLI and the skill that uses it, and the two can never drift
+  # apart in version: the skill's own reference/cli.md always matches the CLI it
+  # was released with.
+  class Skill
+    class Error < OKF::Error
+    end
+
+    # The canonical skill tree, bundled in the sibling skill/ directory.
+    ASSETS = File.expand_path("skill", __dir__)
+
+    # An agent discovers a skill as <skills-dir>/<name>/SKILL.md, so by default
+    # (nest: true) the tree lands in a skills/okf/ folder under the destination:
+    #
+    #   okf skill .claude         -> .claude/skills/okf   (adds skills/ then okf/)
+    #   okf skill .agents/skills  -> .agents/skills/okf   (already a skills dir)
+    #   okf skill .../skills/okf  -> .../skills/okf        (already the skill dir)
+    #
+    # Point it at a project or skills directory and the skill settles in its own
+    # folder instead of splattering its files loose among the others. Pass
+    # nest: false (`--here`) to install straight into the destination, wherever it
+    # is.
+    NAME = "okf"
+    SKILLS_DIR = "skills"
+
+    def self.install(dest, force: false, nest: true)
+      new(dest, force: force, nest: nest).install
+    end
+
+    attr_reader :dest
+
+    def initialize(dest, force: false, nest: true)
+      @dest = nest ? resolve(dest.to_s) : dest.to_s
+      @path = File.expand_path(@dest)
+      @force = force
+    end
+
+    # Copy the skill tree into dest, creating it if needed. Refuses to write over
+    # a non-empty directory unless forced, so an existing (possibly customized)
+    # skill is never silently clobbered. Returns the relative paths written.
+    def install
+      if File.exist?(@path) && !File.directory?(@path)
+        raise Error, "destination #{@dest} exists and is not a directory"
+      end
+      if File.directory?(@path) && !Dir.empty?(@path) && !@force
+        raise Error, "destination #{@dest} is not empty (pass --force to overwrite)"
+      end
+
+      FileUtils.mkdir_p(@path)
+      FileUtils.cp_r(File.join(ASSETS, "."), @path)
+      files
+    end
+
+    # Relative paths of every file in the bundled skill, sorted for stable output.
+    def files
+      Dir.glob(File.join(ASSETS, "**", "*"))
+         .select { |path| File.file?(path) }
+         .map { |path| path[(ASSETS.length + 1)..-1] }
+         .sort
+    end
+
+    private
+
+    # Resolve the destination to a skills/okf leaf, so the skill always sits in its
+    # own folder under whatever the user pointed at. A destination already named
+    # okf is the skill dir itself (idempotent); one named skills only needs okf/.
+    def resolve(dest)
+      case File.basename(dest)
+      when NAME then dest
+      when SKILLS_DIR then File.join(dest, NAME)
+      else File.join(dest, SKILLS_DIR, NAME)
+      end
+    end
+  end
+end

data/lib/okf/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OKF
+  VERSION = "1.0.0"
+end

data/lib/okf.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "date"
+require "json"
+require "optparse"
+require "pathname"
+require "securerandom"
+require "set"
+require "time"
+require "yaml"
+
+module OKF
+  class Error < StandardError
+  end
+
+  # Blank in the frontmatter sense: nil, false, an empty/whitespace-only string,
+  # or an empty collection. Numbers and other scalars are never blank. The one
+  # domain-wide predicate behind "non-empty type" (§9.2) and the recommended-field
+  # warnings, kept here so the gem needs no ActiveSupport.
+  def self.blank?(value)
+    return true if value.nil? || value == false
+    return value.strip.empty? if value.is_a?(String)
+
+    value.respond_to?(:empty?) ? value.empty? : false
+  end
+
+  require "okf/version"
+
+  # ── kernel: cross-cutting primitives ──
+  require "okf/path"
+
+  # ── Markdown: parse structure out of a markdown document (§4/§5/§8) ──
+  require "okf/markdown/frontmatter"
+  require "okf/markdown/links"
+  require "okf/markdown/citations"
+
+  # ── domain: pure representations + analyzers (no disk, no CLI) ──
+  require "okf/concept"
+  require "okf/bundle"
+  require "okf/bundle/graph"
+  require "okf/bundle/validator"
+  require "okf/bundle/validator/result"
+  require "okf/bundle/linter"
+  require "okf/bundle/linter/report"
+
+  # ── shell: everything that touches the outside world ──
+  require "okf/concept/file"
+  require "okf/bundle/reader"
+  require "okf/bundle/writer"
+  require "okf/bundle/folder"
+  require "okf/skill"
+  require "okf/cli"
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: okf
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Rodrigo Serradura
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: |
+  OKF is portable knowledge — Markdown files with YAML frontmatter that both
+  humans and agents read. This gem reads OKF bundles, checks them for v0.1 (§9)
+  conformance, and serves them as an interactive graph (a mountable Rack app).
+  It ships a library API (OKF::Bundle and friends) plus an `okf` command-line
+  tool (validate / lint / loose / server / graph / skill).
+email:
+- rodrigo.serradura@gmail.com
+executables:
+- okf
+extensions: []
+extra_rdoc_files: []
+files:
+- ".okf/capabilities/agent-skill.md"
+- ".okf/capabilities/graph-server.md"
+- ".okf/capabilities/index.md"
+- ".okf/capabilities/library-api.md"
+- ".okf/capabilities/linter.md"
+- ".okf/capabilities/read-views.md"
+- ".okf/capabilities/validator.md"
+- ".okf/cli.md"
+- ".okf/design/core-shell-split.md"
+- ".okf/design/index.md"
+- ".okf/design/ruby-floor.md"
+- ".okf/design/runtime-dependencies.md"
+- ".okf/design/server-trust-boundary.md"
+- ".okf/format/citations.md"
+- ".okf/format/cross-links.md"
+- ".okf/format/frontmatter.md"
+- ".okf/format/index.md"
+- ".okf/format/okf-format.md"
+- ".okf/index.md"
+- ".okf/log.md"
+- ".okf/model/bundle.md"
+- ".okf/model/concept.md"
+- ".okf/model/graph.md"
+- ".okf/model/index.md"
+- ".okf/overview.md"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- NOTICE
+- README.md
+- exe/okf
+- lib/okf.rb
+- lib/okf/bundle.rb
+- lib/okf/bundle/folder.rb
+- lib/okf/bundle/graph.rb
+- lib/okf/bundle/linter.rb
+- lib/okf/bundle/linter/report.rb
+- lib/okf/bundle/reader.rb
+- lib/okf/bundle/validator.rb
+- lib/okf/bundle/validator/result.rb
+- lib/okf/bundle/writer.rb
+- lib/okf/cli.rb
+- lib/okf/concept.rb
+- lib/okf/concept/file.rb
+- lib/okf/markdown/citations.rb
+- lib/okf/markdown/frontmatter.rb
+- lib/okf/markdown/links.rb
+- lib/okf/path.rb
+- lib/okf/server/app.rb
+- lib/okf/server/graph.rb
+- lib/okf/server/runner.rb
+- lib/okf/server/templates/graph.html.erb
+- lib/okf/skill.rb
+- lib/okf/skill/SKILL.md
+- lib/okf/skill/reference/APACHE-2.0.txt
+- lib/okf/skill/reference/SPEC.md
+- lib/okf/skill/reference/authoring.md
+- lib/okf/skill/reference/cli.md
+- lib/okf/skill/templates/concept.md
+- lib/okf/skill/templates/index.md
+- lib/okf/skill/templates/log.md
+- lib/okf/skill/templates/root-index.md
+- lib/okf/version.rb
+homepage: https://github.com/serradura/okf-gem
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/serradura/okf-gem
+  source_code_uri: https://github.com/serradura/okf-gem
+  changelog_uri: https://github.com/serradura/okf-gem/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Read, validate, and serve Open Knowledge Format (OKF) v0.1 bundles.
+test_files: []