okf 1.0.0

data/NOTICE

@@ -0,0 +1,10 @@
+OKF gem
+Copyright (c) 2026 Rodrigo Serradura
+
+Licensed under the Apache License, Version 2.0 (see LICENSE.txt).
+
+This product bundles the Open Knowledge Format (OKF) v0.1 specification
+(lib/okf/skill/reference/SPEC.md), authored by Google Cloud Platform and
+licensed under the Apache License, Version 2.0, Copyright (c) Google LLC.
+Source: https://github.com/GoogleCloudPlatform/knowledge-catalog
+Full license text: lib/okf/skill/reference/APACHE-2.0.txt

data/README.md

@@ -0,0 +1,276 @@
+<p align="center">
+<h1 align="center">
+  <img src=".github/logo.svg" alt="" width="128"><br/>
+  <i>okf-gem</i>
+</h1>
+</p>
+
+> A rough project, cut and polished into a jewel. And like any jewel, what it is
+> worth comes down to what it does with knowledge: reading it, validating it,
+> curating it, and putting it on display.
+
+**okf-gem** reads, validates, lints, and serves **Open Knowledge Format (OKF)**
+v0.1 bundles. OKF is portable knowledge: a directory of Markdown files with YAML
+frontmatter that both humans and agents read. Each file is a _concept_; a
+directory of them is a _bundle_. Over such a bundle the gem gives you five
+things: a library API, a conformance validator, a curation linter, an
+interactive graph server, and a companion agent skill. All but the library API
+are reachable through one `okf` command-line tool.
+
+It is deliberately light so it runs on the Ruby your OS already ships:
+
+- works on every Ruby since 2.4, the same floor as [rack](https://github.com/rack/rack),
+  its core dependency;
+- only two runtime dependencies: `rack` (the server is a mountable Rack app)
+  and `webrick` (unbundled from Ruby in 3.0);
+- no ActiveSupport, no build step, no JavaScript toolchain.
+
+## Installation
+
+```bash
+gem install okf
+# or, in a project
+bundle add okf
+```
+
+From a checkout, this builds the gem and installs it into your Ruby environment,
+putting the `okf` command on your `PATH`:
+
+```bash
+bundle exec rake install
+```
+
+## Command line
+
+```bash
+okf validate  <dir> [--json]                            # check OKF v0.1 conformance (§9)
+okf lint      <dir> [--json] [--fail-on warn] [...]     # report curation-quality issues
+okf loose     <dir> [--json]                            # list files with no graph links, by folder
+okf server    <dir> [-p PORT] [--bind ADDR] [...]       # serve the interactive graph over HTTP
+okf graph     <dir> [--json] [--minimal] [--no-body]    # print the knowledge graph
+okf catalog | files | tags | stats  <dir> [--json]      # the browser views, on the CLI
+okf skill     <dest> [--here] [--force]                 # install the companion agent skill
+okf --version
+```
+
+Exit codes: `0` success, `1` non-conformant bundle (or a `lint --fail-on`
+threshold crossed), `2` usage error.
+
+> [!NOTE]
+> Section numbers like §5, §8, and §9 refer to the OKF v0.1 spec, bundled with
+> the skill at [`lib/okf/skill/reference/SPEC.md`](lib/okf/skill/reference/SPEC.md).
+
+```bash
+$ okf validate docs
+OKF v0.1 conformance — docs
+  concepts: 37   index.md: 10   log.md: 1
+  ! warn  features/link-suggestions.md: cross-link target not found: `/graph-view.md` (tolerated under §5.3)
+  …
+  ✓ conformant (33 warning(s))
+
+$ okf server docs
+serving 37 concepts at http://127.0.0.1:8808 (Ctrl-C to stop)
+```
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/server-dark.png">
+  <img src=".github/server-dark.png" alt="The okf graph server: a force-directed knowledge graph with a concept selected, its neighbors highlighted, and the inspector panel showing the concept's type, tags, cross-links, and rendered Markdown body.">
+</picture>
+
+_The graph server on this repo's own [`.okf`](.okf) bundle, with the
+`capabilities/graph-server` concept selected._
+
+`graph` and `server` are best-effort (§9): a file with invalid frontmatter is
+skipped (and noted on stderr), not fatal, so one bad file never breaks the rest.
+Before serving a bundle you did not author, read the
+[server trust boundary](#server-trust-boundary).
+
+`lint` reports curation quality (reachability, backlog, completeness, freshness,
+provenance, and hygiene) separately from `validate`. It is advisory: it exits
+`0` even with findings unless you opt into gating with `--fail-on warn`.
+
+```bash
+$ okf lint docs
+OKF lint — docs
+  concepts: 37   edges: 87   index.md: 10   log.md: 1
+  hubs: features/chat/sources/source-ingestion-pipeline (×12), …
+
+  Backlog
+    · info  graph-view.md: referenced by 3 link(s) across 2 concept(s) but does not exist
+    ! warn  features/index.md: index links to missing concept `../../CHANGELOG.md`
+  Completeness
+    · info  features/bundles/entry-editor.md: missing recommended field: description
+  Hygiene
+    ! warn  link-suggestions.md: reference-style link `[:approved_ids]` has no matching definition (an invisible broken link)
+
+  ⚠ 3 warn, 31 info
+```
+
+`loose` lists the files that float in the graph: concepts with no cross-links
+in or out (graph degree 0), grouped by folder. It is a curation lens over
+`lint`'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 be loose. A loose file may be fine: a terminal leaf like a backlog
+item is loose by design. `loose` surfaces the set for you to judge and
+always exits `0`.
+
+## Agent skill
+
+The gem carries the companion OKF agent skill: a `SKILL.md` plus reference
+and template files that teach a coding agent to author, maintain, and consume OKF
+bundles and to drive the commands above. Because the skill ships inside the gem,
+installing the gem already puts the skill on your machine, and the skill's
+CLI reference can never drift from the executable it was released with.
+
+Point it at your agent's config directory (or its skills directory) and the tree
+settles in its own `skills/okf/` folder, so a shared skills directory never gets
+the files loose:
+
+```bash
+okf skill .claude     # Claude Code      -> .claude/skills/okf
+okf skill .agents     # agent-agnostic   -> .agents/skills/okf
+```
+
+The destination is required (no default). The skill lands in `<dest>/skills/okf`,
+unless `<dest>` already ends in `skills` (→ `<dest>/okf`) or `okf` (used as-is).
+Pass `--here` to paste the tree straight into `<dest>`, wherever it is. The
+resolved directory must be empty unless you pass `--force`, so a customized skill
+is never clobbered.
+
+## Library
+
+The gem is two layers: pure in-memory data (`OKF::Concept`, `OKF::Bundle`)
+you build, interrogate, and analyze with no disk involved, and on-disk
+handles (`OKF::Concept::File`, `OKF::Bundle::Folder`) that add
+load/save/reload/delete, an "ActiveRecord for the filesystem".
+
+### Pure, in-memory (no disk)
+
+Build knowledge straight from data, with no markdown round-trip, and run every
+feature against it. This is the surface an embedding app (e.g. a Rails store)
+uses to reuse the gem over knowledge it already holds as records:
+
+```ruby
+require "okf"
+
+concept = OKF::Concept.new(
+  path: "tables/orders.md",
+  frontmatter: { "type" => "BigQuery Table", "title" => "Orders" },
+  body: "Joined with [customers](/tables/customers.md).\n"
+)
+
+concept.id                       # => "tables/orders"
+concept.links                    # => ["/tables/customers.md"]  (spec §5 cross-links)
+concept.citations                # => [...]                     (spec §8 # Citations)
+concept.external_links           # => [...]                     (URLs / mailto:)
+concept.to_markdown              # => String  (inverse of OKF::Markdown::Frontmatter.parse)
+concept.lint                     # => OKF::Bundle::Linter::Report  (the concept-scoped checks)
+
+bundle = OKF::Bundle.new(concepts: [ concept ])   # also: reserved:, unparseable:
+bundle.validate                  # => OKF::Bundle::Validator::Result  (spec §9 conformance)
+bundle.lint                      # => OKF::Bundle::Linter::Report     (curation quality)
+bundle.graph                     # => OKF::Bundle::Graph              (#nodes, #edges, #to_h)
+```
+
+### On disk
+
+`OKF::Bundle::Folder` reads a directory into a pure bundle and materializes one
+back; `OKF::Concept::File` is a single-file handle:
+
+```ruby
+folder = OKF::Bundle::Folder.load("docs")
+folder.bundle                    # => OKF::Bundle  (the pure bundle it read)
+folder.concepts                  # => [OKF::Concept]  (reserved files excluded)
+folder.validate; folder.lint; folder.graph   # delegate to the pure core
+folder.concept("tables/orders")  # => OKF::Concept::File
+OKF::Server::App.new(folder)     # => a Rack app: the interactive graph server
+
+# build in memory, then write it out (validates §9 before publishing):
+OKF::Bundle::Folder.new(bundle: bundle, root: "out/dir").save
+
+file = OKF::Concept::File.read(root: "docs", path: "tables/orders.md")
+file.concept                     # => OKF::Concept (pure)
+file.save; file.delete; file.reload
+```
+
+The lower-level pieces are usable on their own too: `OKF::Bundle::Validator.call(bundle)`,
+`OKF::Bundle::Linter.call(bundle, min_body: 50)`, `OKF::Bundle::Graph.build(bundle)`,
+`OKF::Markdown::Frontmatter.parse(markdown)`.
+
+### Conformance model
+
+`validate` implements the spec's [§9 conformance definition](lib/okf/skill/reference/SPEC.md#9-conformance)
+exactly. There are three hard conditions, all errors:
+
+- **§9.1** every non-reserved file has a parseable YAML frontmatter block;
+- **§9.2** every such block has a non-empty `type`;
+- **§9.3** every `index.md`/`log.md` present follows §6/§7: a nested `index.md`
+  has no frontmatter, a root `index.md` carries only `okf_version`, and `log.md`
+  date headings are ISO `YYYY-MM-DD`.
+
+Everything the spec marks as soft guidance is a warning and never makes a
+bundle non-conformant: missing recommended fields, non-list tags, an unparseable
+timestamp, and broken cross-links (§5.3), which consumers MUST tolerate.
+`OKF::Bundle::Folder#save` validates before publishing, so it never writes a
+bundle that fails §9.
+
+### Curation model (`lint`)
+
+`validate` asks _"is this §9-conformant?"_ and is forbidden by §9 to reject for
+broken links or missing optional fields. `lint` asks the complementary question,
+_"is this well-curated, navigable, trustworthy?"_, over exactly those tolerated
+things. The two stay separate: `lint` has its own `OKF::Bundle::Linter` and
+report, never emits conformance errors, and is advisory unless you pass
+`--fail-on warn`.
+
+Checks span six categories: **reachability** (orphans, not-in-index, disconnected
+islands, unlinked), **backlog** (demand-ranked missing concepts, broken index entries),
+**completeness** (stubs, missing title/description/timestamp), **freshness**
+(`--stale-after`), **provenance** (uncited external claims, broken citations,
+spec §8), and **hygiene** (duplicate titles, unused/undefined reference links,
+self-links). Select with `--only`/`--except`; `--json` emits the full report as JSON.
+
+Two loop concerns from the format's own guidance, _contradictions_ and _semantic_
+staleness, need to understand meaning and are not computed here; `lint --json`
+is the structured input an agent consumes to reason about those.
+
+## Server trust boundary
+
+> [!WARNING]
+> The served page loads its JavaScript (Cytoscape, marked, mermaid, and layout
+> plugins) from a CDN and renders each concept's Markdown body **without
+> sanitization**, so only serve bundles you trust. Inlined graph data still
+> cannot break out of its `<script>` (`<` is escaped), but the fetched Markdown
+> is rendered unsanitized.
+
+## Development
+
+```bash
+bin/setup               # install dependencies
+bundle exec rake        # tests + RuboCop (what CI runs)
+bundle exec rake test   # just the test suite
+ruby -Ilib exe/okf validate <dir>   # run the CLI from a checkout
+```
+
+The suite runs on every supported Ruby; to check the 2.4 floor locally:
+
+```bash
+docker run --rm -v "$PWD":/app -w /app ruby:2.4 \
+  bash -c "bundle install && bundle exec rake test"
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/serradura/okf-gem>. This project is intended to be a safe,
+welcoming space for collaboration, and contributors are expected to adhere to
+the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the
+[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) (see
+`LICENSE.txt`). The Open Knowledge Format specification bundled with the skill
+is authored by Google Cloud Platform and included under its own Apache-2.0
+license, Copyright (c) Google LLC. See `NOTICE` and
+`lib/okf/skill/reference/APACHE-2.0.txt`.

data/exe/okf

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "okf"
+
+exit OKF::CLI.start(ARGV)

data/lib/okf/bundle/folder.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module OKF
+  class Bundle
+    # A bundle on disk — the directory-level handle. Reads a directory into a pure
+    # OKF::Bundle once, exposes the analyzers over it,
+    # and can materialize an in-memory bundle back to disk. Part of the shell.
+    #
+    #   folder = OKF::Bundle::Folder.load("docs")
+    #   folder.bundle             # => OKF::Bundle (pure)
+    #   folder.validate; folder.lint; folder.graph
+    #   folder.concept("tables/orders")   # => OKF::Concept::File (or nil)
+    #
+    #   # build in memory (the Rails / snapshot-publisher path) and write it out:
+    #   OKF::Bundle::Folder.new(bundle: pure_bundle, root: "out/dir").save
+    class Folder
+      attr_reader :root, :bundle
+
+      def self.load(dir)
+        root = File.expand_path(dir.to_s)
+        new(bundle: Reader.read(root), root: root)
+      end
+
+      def initialize(bundle:, root:)
+        @bundle = bundle
+        @root = File.expand_path(root.to_s)
+      end
+
+      def concepts
+        @bundle.concepts
+      end
+
+      def validate
+        @bundle.validate
+      end
+
+      def lint(**options)
+        @bundle.lint(**options)
+      end
+
+      def graph(minimal: false, body: true)
+        @bundle.graph(minimal: minimal, body: body)
+      end
+
+      def catalog
+        @bundle.catalog
+      end
+
+      def directory_index
+        @bundle.directory_index
+      end
+
+      # Human-readable "parent/dir" name — the default HTML title.
+      def name
+        pathname = Pathname.new(@root)
+        "#{pathname.parent.basename}/#{pathname.basename}"
+      end
+
+      # A single-file handle for one concept id (read live from disk), or nil when no
+      # concept in the loaded bundle has that id. The id may be a frontmatter `id`, so
+      # it is resolved to a path through the bundle rather than assumed to be "id.md".
+      def concept(id)
+        path = @bundle.paths_by_id[id] or return nil
+        Concept::File.read(root: @root, path: path)
+      end
+
+      # Materialize the in-memory bundle to disk (Writer validates §9 before
+      # publishing, so a malformed bundle is never written).
+      def save(overwrite: false)
+        Writer.call(
+          bundle_path: @root,
+          concepts: @bundle.concepts,
+          index_files: reserved_hash("index.md"),
+          log_files: reserved_hash("log.md"),
+          overwrite: overwrite
+        )
+        self
+      end
+
+      def reload
+        @bundle = Reader.read(@root)
+        self
+      end
+
+      private
+
+      def reserved_hash(basename)
+        @bundle.reserved
+               .select { |entry| File.basename(entry.path) == basename }
+               .each_with_object({}) { |entry, hash| hash[entry.path] = entry.content }
+      end
+    end
+  end
+end

data/lib/okf/bundle/graph.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module OKF
+  class Bundle
+    # An in-memory knowledge graph of a bundle: concepts become nodes and
+    # bundle-relative markdown links become directed edges. Pure — built from an
+    # OKF::Bundle (already in memory), does no I/O, and carries no presentation
+    # concerns (sizing/colour belong to a renderer).
+    #
+    # Node fidelity is a build option, so the graph can ship only what a consumer
+    # needs and let a server serve the rest on demand:
+    #   * default (minimal: false, body: true) — full: id, type, title, description,
+    #     tags, body.
+    #   * body: false — everything but the body.
+    #   * minimal: true — just id and title (the leanest payload to draw the graph).
+    # Regardless of node fidelity, #type_index and #tag_index expose compact inverted
+    # indexes ({ value => [id, …] }) computed from every concept, so a minimal client
+    # can still colour by type and filter by tag.
+    class Graph
+      attr_reader :nodes, :edges, :type_index, :tag_index
+
+      def self.build(bundle, minimal: false, body: true)
+        # Best-effort (§9): a malformed concept never reaches here — the reader keeps
+        # it in bundle.unparseable — so the rest of the bundle still renders. Inspect
+        # bundle.unparseable to detect skips.
+        concepts = bundle.concepts
+        id_by_path = concepts.map { |concept| [ concept.path, concept.id ] }.to_h
+        new(
+          nodes: concepts.map { |concept| node_for(concept, minimal: minimal, body: body) },
+          edges: edges_for(concepts, id_by_path, bundle.root),
+          type_index: type_index_for(concepts),
+          tag_index: tag_index_for(concepts)
+        )
+      end
+
+      def self.node_for(concept, minimal: false, body: true)
+        title = default(concept.title, File.basename(concept.id))
+        return { id: concept.id, title: title } if minimal
+
+        node = {
+          id: concept.id,
+          type: default(concept.type, "Untyped"),
+          title: title,
+          description: concept.description.to_s,
+          tags: tags_of(concept)
+        }
+        node[:body] = concept.body.to_s.strip if body
+        node
+      end
+
+      # Edges resolve by *path* — a markdown link is a file path — then map that path
+      # to the concept living there and use its id, so a frontmatter `id` that differs
+      # from the path still lands the edge on the right node.
+      def self.edges_for(concepts, id_by_path, root)
+        seen = Set.new
+        concepts.each_with_object([]) do |concept, edges|
+          Markdown::Links.extract(concept.body).each do |raw|
+            resolved = Markdown::Links.resolve(raw, from: concept.path, bundle: root)
+            next if resolved.nil?
+
+            target_id = id_by_path[resolved]
+            next if target_id.nil?
+            next if target_id == concept.id
+            next unless seen.add?([ concept.id, target_id ])
+
+            edges << { source: concept.id, target: target_id }
+          end
+        end
+      end
+
+      # { type => [id, …] } over every concept (one type each, "Untyped" if blank).
+      def self.type_index_for(concepts)
+        concepts.each_with_object({}) do |concept, index|
+          (index[default(concept.type, "Untyped")] ||= []) << concept.id
+        end
+      end
+
+      # { tag => [id, …] } over every concept (a concept contributes 0..n tags).
+      def self.tag_index_for(concepts)
+        concepts.each_with_object({}) do |concept, index|
+          tags_of(concept).each { |tag| (index[tag.to_s] ||= []) << concept.id }
+        end
+      end
+
+      def self.tags_of(concept)
+        concept.tags.is_a?(Array) ? concept.tags : []
+      end
+
+      def self.default(value, fallback)
+        value.nil? ? fallback : value.to_s
+      end
+
+      def initialize(nodes:, edges:, type_index: {}, tag_index: {})
+        @nodes = nodes
+        @edges = edges
+        @type_index = type_index
+        @tag_index = tag_index
+      end
+
+      def to_h
+        { nodes: nodes, edges: edges }
+      end
+
+      # Ids of nodes with graph degree 0 — no cross-links in *or* out. These are the
+      # "loose" files: they float in a rendered graph, reachable (if at all) only via
+      # an index.md listing, which is not an edge. Distinct from an orphan, a
+      # *reachability* notion that an index listing satisfies — a concept can be
+      # indexed (not an orphan) yet still be unlinked here. Preserves node order.
+      def unlinked_ids
+        @unlinked_ids ||= begin
+          linked = Set.new
+          edges.each { |edge| linked << edge[:source] << edge[:target] }
+          nodes.map { |node| node[:id] }.reject { |id| linked.include?(id) }
+        end
+      end
+    end
+  end
+end

data/lib/okf/bundle/linter/report.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module OKF
+  class Bundle
+    class Linter
+      # The result of linting a bundle for curation quality (see OKF::Bundle::Linter). Mirrors
+      # OKF::Bundle::Validator::Result, but lint has no errors — only `:warn` and `:info`
+      # findings — and carries free-form `stats` in place of conformance counts. A
+      # bundle is "healthy" when it has no `:warn` findings; `:info` never makes it
+      # unhealthy. Every finding is a self-describing Hash so #to_h is a stable machine
+      # substrate an agent can act on.
+      class Report
+        attr_reader :findings, :stats
+
+        def initialize
+          @findings = []
+          @stats = {}
+        end
+
+        def add_warning(check, path, message, metric: nil)
+          @findings << finding(:warn, check, path, message, metric)
+        end
+
+        def add_info(check, path, message, metric: nil)
+          @findings << finding(:info, check, path, message, metric)
+        end
+
+        def warnings
+          findings.select { |f| f[:severity] == :warn }
+        end
+
+        def info
+          findings.select { |f| f[:severity] == :info }
+        end
+
+        def healthy?
+          warnings.empty?
+        end
+
+        def stat(key, value)
+          @stats[key] = value
+        end
+
+        def to_h
+          { healthy: healthy?, stats: stats, findings: findings }
+        end
+
+        private
+
+        def finding(severity, check, path, message, metric)
+          { check: check, severity: severity, path: path, message: message, metric: metric }
+        end
+      end
+    end
+  end
+end