okf 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3df6877dab7b0fa0bd7353d288b9bbec2657056744ad9d5513c1817921659875
-  data.tar.gz: 68f3b956056874fac093ec3114eea5ba420173727458ae1d97c562c3c22ff28c
+  metadata.gz: 54635358ffdec2a998c809e5080db6be498c1ae8cad0c0ed57f60ed2616a2362
+  data.tar.gz: 72053ffab89e8a5b3440a0985491b6677bfcb89c0fb709ce5afb0b1ee9b00f65
 SHA512:
-  metadata.gz: 2e9da0cf2f912c2473302266307e0180ac038c97c75636f06299e7b25adeb64cb38220f755bf4101bee6edbdb52ae9a4cb696b2b14f2c8b54dd28ce3225d4b5c
-  data.tar.gz: 0eb35fde3097549a55fde740816178d830628ade3639a356e1e2eea5e195ee3ea28b321ccb4bd9211284103a90c5ab33830fb1218a298034788d258a06cf5dab
+  metadata.gz: 934aac7bc308fb64246abc133cfffdae29fcfd36c4b97a7dd2bd6c61080506152d0f5f0d04fa514121dcce39be5bab9ad20f93500bc8343524b75adfdfcdd211
+  data.tar.gz: 41a97a7e62df5b6a5270978f9af8800df7448a8ae00a3abeef86b700cf356ccb191684e84eb5ce301f761be111f0628061da910a061c3e7492868f3a577e2a2d

data/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [1.5.0] - 2026-07-13
+
+- New CLI verb: `okf search <dir> <term…>` — deterministic ranked retrieval
+  over concept metadata *and bodies*, the browser page's search brought to the
+  CLI. Terms AND together as case-insensitive substrings, or as Ruby regexps
+  with `--regexp`/`-e`; `--in` restricts the searched fields; the shared
+  `--type/--area/--tag` filters and `--fields/--except` projections apply.
+  Matches rank by where they hit (title > id > tags > type/description > body)
+  and carry a bounded context snippet, so "which concept covers X?" costs a
+  few rows instead of a body read. Advisory read: exit 0 even with no matches.
+  Deliberately not fuzzy — the consuming agent is the fuzzy layer.
+- The skill learns retrieval as a first-class verb: a new `search` playbook
+  (progressive disclosure end to end: ingest `okf index`, decide where to
+  look, cut across with `okf search`, read only the winning bodies),
+  search-aware routing in SKILL.md and the menu/consume playbooks, and
+  `/okf:gem search <query>` first in the Claude Code plugin's routing.
+- Retrieval eval in the suite: the progressive path (index skeleton → search →
+  one body) must answer a planted question in under 25% of the bytes of the
+  full graph dump, so the playbook's economics stay true by construction.
+- Graph server: the authored layer joins the UI. The Files view carries two
+  tabs — **Files** (the per-directory concept groups, foldable) and
+  **Indexes** (the log first, as the chronological index, then every
+  `index.md`, root before nested) — with the files filters moved up into the
+  top bar. The rail's **Index** item, the `2` key, and `?view=index` are
+  shortcuts straight to the Indexes tab. Folder nodes in file-tree mode and
+  area boxes in cluster mode are clickable and open that directory's §6 map
+  in the inspector (authored, or the synthesized listing when none exists).
+  Links to an `index.md`, a `log.md`, or a bare directory (`model/`) navigate
+  everywhere a body renders instead of striking through as dead, and the log
+  is fetched fresh on every read, so a just-appended entry shows without a
+  restart. A reserved file's "Open in graph" jumps to its folder in the file
+  tree, map in the inspector. New `/index` and `/log` endpoints back it all.
+- Graph server: Mermaid diagrams in concept bodies are click-to-inspect. A
+  click (or tap) opens the diagram full screen — drag to pan, wheel or pinch
+  to zoom, buttons and double-click reset, Esc closes — powered by
+  [Panzoom](https://github.com/timmywil/panzoom), lazy-loaded from the CDN
+  exactly like Mermaid itself.
+- The Claude Code plugin's `/okf:gem` command now weighs the shape of a
+  free-form ask: a question about what the bundle knows routes through the
+  search playbook and answers from retrieved concepts instead of guessing.
+- Skill efficiency audit: every playbook now takes the CLI's lean paths.
+  `maintain` hunts affected concepts with `okf search` and pulls edges via
+  `graph --json --minimal` instead of the full-body dump, `menu` reads the
+  plain-text reports it only scans, and SKILL.md pins the discipline as a
+  rule: skeleton first, bodies last.
+- Docs: the CLI reference's server section now reflects the DOMPurify
+  sanitization that landed in 1.1.0 (it still said bodies render unsanitized),
+  and the server page's link-preview image points at the renamed
+  `okfgem.com/og-demo-v2.png`.
+
 ## [1.4.0] - 2026-07-12
 
 - Graph server UX round. Selecting a node now makes one camera move instead of

data/README.md

@@ -18,26 +18,21 @@
 </p>
 
 <p align="center">
-  <b><a href="https://okfgem.com">Website</a></b> &nbsp;·&nbsp;
+  <b><a href="https://okfgem.com">Site</a></b> &nbsp;·&nbsp;
+  <b><a href="https://okfgem.com/docs/">Docs</a></b> &nbsp;·&nbsp;
   <b><a href="https://demo.okfgem.com">Live demo</a></b> &nbsp;·&nbsp;
-  <b><a href="https://claude.okfgem.com">Claude Code plugin</a></b>
+  <b><a href="https://claude.okfgem.com">Claude plugin</a></b>
 </p>
 
-**okf-gem** — `okf` on RubyGems — reads, validates, lints, and serves
-**Open Knowledge Format (OKF)** v0.1 bundles: directories of Markdown files with YAML frontmatter that humans and agents read from one source. It does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown. Each file is a _concept_; a directory of them is a _bundle_.
+**okf-gem** (`okf` on RubyGems) is the complete toolkit for
+**Open Knowledge Format (OKF)** v0.1 bundles. The package is **Agent Skill + CLI/Lib + Live Graph**: an agent skill that authors and curates, a CLI and Ruby library that validate, lint, search, and embed, and a live graph server to explore, in one gem that runs 100% local. A bundle is a directory of Markdown files with YAML frontmatter that humans and agents read from one source; each file is a _concept_. The gem does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown.
 
-> **Quick start.** One skill, one command, a curation hook, and a CLI that
-> validates, lints, indexes, and serves your Markdown as a graph. In Claude Code,
-> add the plugin and let it set everything up: `/plugin marketplace add
-serradura/okf-gem`, then `/plugin install okf@okfgem`, then `/okf:gem`. On the
-> command line: `gem install okf`, then `okf validate <dir>`.
-
-Here is what it is able to do:
+The package, end to end:
 
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset=".github/overview-dark.png">
-    <img src=".github/overview-light.png" width="100%" alt="The companion agent skill authors and curates an OKF v0.1 bundle (Markdown + YAML). A pure model (Concept, Bundle, Graph) reads that bundle and feeds both the okf CLI (validate — legal per §9; lint — well-curated; server — explore) and a library API you embed in Ruby.">
+    <img src=".github/overview-light.png" width="760" alt="The package: the Agent Skill (your coding agent authors and curates, you stay the editor) writes and maintains the bundle, a folder of Markdown + YAML in your repo where one concept is one file and links between files are the knowledge graph. The bundle is read by the CLI/Lib (validate: legal OKF per section 9; lint: well-curated and fresh; search: ranked retrieval; require okf for Ruby objects) and by the Live Graph (okf server: click a node, read its Markdown; mounts in Rails). One gem, 100% local, Ruby 2.4 or newer, only rack and webrick as dependencies.">
   </picture>
 </p>
 
@@ -169,6 +164,7 @@ bundle exec rake install
 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 search    <dir> <term…> [-e] [--in a,b] [...]       # ranked text retrieval across metadata + bodies
 okf index     <dir> [--json] [--area A] [--no-body]     # progressive-disclosure map (§6): bodies, rollups, listings
 okf server    <dir> [-p PORT] [--bind ADDR] [...]       # serve the interactive graph over HTTP
 okf graph     <dir> [--json] [--minimal] [--no-body]    # print the knowledge graph
@@ -194,7 +190,7 @@ 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.">
+  <img src=".github/server-light.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
@@ -254,12 +250,13 @@ The skill routes a small set of verbs. In Claude Code they run as `/okf:gem
 | Verb             | What it does                                                                                      |
 | ---------------- | ------------------------------------------------------------------------------------------------- |
 | _(none)_         | Orient on the bundle and recommend the highest-value next move                                    |
+| `search`         | Answer a question from the bundle, token-lean: the map, the finder, only the winning bodies      |
 | `produce`        | Create or extend a bundle from code, docs, or knowledge in people's heads                         |
 | `maintain`       | Sync the bundle's content with reality after the code or docs change                              |
 | `consume`        | Use the bundle as context for a task, writing back what you learn                                 |
 | `curate`         | Structural upkeep as it stands: `validate` + `lint` + `loose`                                     |
 | `doctor`         | Install and verify the CLI, then doctor the bundle                                                |
-| `<okf-cli-verb>` | Run any CLI verb (`validate`, `lint`, `index`, `server`, the read views) and interpret its output |
+| `<okf-cli-verb>` | Run any CLI verb (`validate`, `lint`, `search`, `index`, `server`, the read views) and interpret its output |
 
 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
@@ -323,6 +320,8 @@ 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
+
+require "okf/server/app"         # the server loads on demand, like the CLI does
 OKF::Server::App.new(folder)     # => a Rack app: the interactive graph server
 
 # build in memory, then write it out (validates §9 before publishing):
@@ -335,7 +334,8 @@ 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)`.
+`OKF::Markdown::Frontmatter.parse(markdown)`. Mounting the graph in Rails, auth
+included: the [Rails guide](https://okfgem.com/docs/guides/rails/) walks it.
 
 ### Conformance model
 

data/lib/okf/bundle/search.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module OKF
+  class Bundle
+    # Deterministic text retrieval over an in-memory bundle — the browser page's
+    # search brought server-side and extended to bodies. Terms are ANDed: every
+    # term must hit at least one searched field, though not necessarily the same
+    # one. A term is a case-insensitive substring, or a Ruby regular expression
+    # with `regexp: true`. Matches rank by where they hit (a title hit outranks a
+    # body hit) and carry one bounded context snippet, so answering "which concept
+    # covers X?" costs a row, not a body read.
+    #
+    # Deliberately not fuzzy: the consuming agent is the fuzzy layer — synonyms
+    # and vocabulary drift are judgment over the index map, not string distance.
+    #
+    # Pure — no disk, no stdio. The CLI's `okf search` and any embedding app share
+    # it: OKF::Bundle::Search.call(bundle, [ "dedup", "key" ]).
+    class Search
+      # The searchable fields with their rank weight, strongest signal first.
+      # A concept's score sums the weights of the fields that matched; hitting a
+      # field twice does not stack. Tags match against the space-joined list,
+      # mirroring the server page's haystack.
+      WEIGHTS = {
+        "title" => 5,
+        "id" => 4,
+        "tags" => 3,
+        "type" => 2,
+        "description" => 2,
+        "body" => 1
+      }.freeze
+
+      FIELDS = WEIGHTS.keys.freeze
+
+      # Fields whose match is only meaningful with surrounding context. The other
+      # fields already appear whole on the result row.
+      SNIPPET_FIELDS = %w[description body].freeze
+
+      # Characters of context kept on each side of the first matched term.
+      SNIPPET_RADIUS = 44
+
+      def self.call(bundle, terms, fields: nil, regexp: false)
+        new(bundle, terms, fields: fields, regexp: regexp).results
+      end
+
+      # Raises RegexpError on an invalid pattern with `regexp: true` — the caller
+      # owns turning that into a usage error.
+      def initialize(bundle, terms, fields: nil, regexp: false)
+        @bundle = bundle
+        raw = Array(terms).reject { |term| OKF.blank?(term) }
+        @matchers = raw.map { |term| regexp ? Regexp.new(term.to_s, Regexp::IGNORECASE) : term.to_s.downcase }
+        @fields = fields.nil? || fields.empty? ? FIELDS : fields
+      end
+
+      # Ranked match rows, catalog-style identity plus where the terms hit:
+      # [{ id:, title:, type:, area:, tags:, matched: [field, …], score:, snippet: }, …]
+      # ordered by score descending, then id. No terms means no matches.
+      def results
+        return [] if @matchers.empty?
+
+        @bundle.concepts
+               .map { |concept| match(concept) }
+               .compact
+               .sort_by { |row| [ -row[:score], row[:id] ] }
+      end
+
+      private
+
+      def match(concept)
+        texts = searchable_texts(concept)
+        matched = matched_fields(texts)
+        return nil if matched.nil?
+
+        {
+          id: concept.id,
+          title: (concept.title || concept.id).to_s,
+          type: concept.type.to_s,
+          area: area_of(concept.id),
+          tags: Array(concept.tags).map(&:to_s),
+          matched: matched,
+          score: matched.map { |field| WEIGHTS[field] }.reduce(0, :+),
+          snippet: snippet(texts, matched)
+        }
+      end
+
+      # { field => original-case text } for the fields this search reads.
+      def searchable_texts(concept)
+        texts = {
+          "id" => concept.id,
+          "title" => concept.title.to_s,
+          "type" => concept.type.to_s,
+          "description" => concept.description.to_s,
+          "tags" => Array(concept.tags).join(" "),
+          "body" => concept.body
+        }
+        texts.each_with_object({}) do |(field, text), acc|
+          acc[field] = text if @fields.include?(field)
+        end
+      end
+
+      # The union of fields any term hit, in WEIGHTS order — or nil when some term
+      # hit nothing (terms are ANDed).
+      def matched_fields(texts)
+        hits = @matchers.map do |matcher|
+          fields = texts.keys.select { |field| hit?(matcher, texts[field]) }
+          return nil if fields.empty?
+
+          fields
+        end
+        FIELDS.select { |field| hits.flatten.include?(field) }
+      end
+
+      def hit?(matcher, text)
+        matcher.is_a?(Regexp) ? matcher.match?(text) : text.downcase.include?(matcher)
+      end
+
+      # One bounded context window around the first term that hit the strongest
+      # snippet-worthy field; "" when the match needs no context (id/title/type/tags).
+      def snippet(texts, matched)
+        field = SNIPPET_FIELDS.find { |candidate| matched.include?(candidate) }
+        return "" if field.nil?
+
+        matcher = @matchers.find { |candidate| hit?(candidate, texts[field]) }
+        context(texts[field], matcher)
+      end
+
+      def context(text, matcher)
+        flat = text.gsub(/\s+/, " ").strip
+        at, length = locate(flat, matcher)
+        from = [ at - SNIPPET_RADIUS, 0 ].max
+        to = at + length + SNIPPET_RADIUS
+        clip = flat[from, to - from].to_s.strip
+        clip = "…#{clip}" if from.positive?
+        clip = "#{clip}…" if to < flat.length
+        clip
+      end
+
+      # [ position, length ] of the matcher's first hit in the flattened text —
+      # [ 0, 0 ] when a pattern that hit the raw text cannot be found again after
+      # whitespace collapsing (e.g. an explicit \n), so the window opens at the top.
+      def locate(flat, matcher)
+        if matcher.is_a?(Regexp)
+          found = matcher.match(flat)
+          found ? [ found.begin(0), found[0].length ] : [ 0, 0 ]
+        else
+          [ flat.downcase.index(matcher) || 0, matcher.length ]
+        end
+      end
+
+      # A concept's top-level area, mirroring the catalog's definition.
+      def area_of(id)
+        id.include?("/") ? id.split("/").first : "(root)"
+      end
+    end
+  end
+end

data/lib/okf/bundle.rb

@@ -136,8 +136,8 @@ module OKF
     # the map on the fly (§6 permits exactly that). Grouped by the concept's file
     # path — index files are physical directory listings, so a custom frontmatter
     # `id` must not move a concept out of the directory it lives in. Pure: derived
-    # from the concepts and the reserved index text, no disk. Shared by the `okf
-    # index` view and the server's /index endpoint.
+    # from the concepts and the reserved index text, no disk. Shared by the
+    # `okf index` view and the server's Index panel (/index).
     def directory_index
       by_dir = concepts.group_by { |concept| File.dirname(concept.path) }
       dirs = directory_set(by_dir.keys)

data/lib/okf/cli.rb

@@ -3,7 +3,7 @@
 require "optparse"
 
 module OKF
-  # Command-line front end: `okf graph|validate|lint|loose|index|catalog|files|tags|types|stats|server <dir>`.
+  # Command-line front end: `okf graph|validate|lint|loose|search|index|catalog|files|tags|types|stats|server <dir>`.
   # This is the
   # only layer that parses argv, prints, writes files, and decides exit codes — the
   # lib classes below it just return data. Streams are injectable for testing.
@@ -47,6 +47,7 @@ module OKF
       when "validate" then validate(argv)
       when "lint" then lint(argv)
       when "loose" then loose(argv)
+      when "search" then search(argv)
       when "index" then index(argv)
       when "catalog" then catalog(argv)
       when "files" then files(argv)
@@ -131,6 +132,65 @@ module OKF
       0
     end
 
+    # Deterministic text retrieval — the browser page's search brought to the CLI
+    # and extended to bodies. Terms after the directory are ANDed case-insensitive
+    # substrings (Ruby regexps with --regexp); rows rank by where they hit (title >
+    # id > tags > type/description > body) and carry one bounded context snippet,
+    # so "which concept covers X?" costs a few rows, not a body read. Advisory
+    # read: exit 0 even with no matches. Deliberately not fuzzy — the consuming
+    # agent is the fuzzy layer.
+    def search(argv)
+      options = { json: false, regexp: false }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf search <bundle-dir> <term> [term ...] [--regexp] [--in FIELDS] [--type T] [--area A] [--tag T] [--json]"
+        json_flags(o, options, "emit the matches as JSON")
+        projection_flags(o, options)
+        o.on("-e", "--regexp", "treat each term as a Ruby regular expression (case-insensitive)") { options[:regexp] = true }
+        o.on("--in LIST", Array, "search only these fields (#{OKF::Bundle::Search::FIELDS.join(", ")})") { |v| options[:in] = v.map(&:downcase) }
+        filter_flags(o, options, :type, :area, :tag)
+      end
+      dir = positional_dir(parser, argv) or return 2
+      terms = argv
+      if terms.empty?
+        @err.puts parser.banner
+        return 2
+      end
+
+      unknown = Array(options[:in]) - OKF::Bundle::Search::FIELDS
+      return usage_error("unknown field(s): #{unknown.join(", ")} (searchable: #{OKF::Bundle::Search::FIELDS.join(", ")})") unless unknown.empty?
+
+      folder = OKF::Bundle::Folder.load(dir)
+      report_skipped(folder)
+      rows = OKF::Bundle::Search.call(folder.bundle, terms, fields: options[:in], regexp: options[:regexp])
+      keep = filter_ids(folder, options)
+      rows = rows.select { |row| keep.include?(row[:id]) } unless keep.nil?
+      return print_search_json(dir, terms, rows, options) if options[:json]
+
+      print_search(dir, terms, rows, folder.bundle.concepts.size)
+      0
+    rescue RegexpError => e
+      usage_error("invalid pattern: #{e.message}")
+    end
+
+    def print_search(dir, terms, rows, total)
+      @out.puts "Search — #{dir} · #{terms.join(" ")} (#{counted(rows.size, total, "concepts")})"
+      if rows.empty?
+        @out.puts "  no matches — fewer or broader terms, or scan `okf tags #{dir}` for the vocabulary"
+        return
+      end
+
+      width = rows.map { |row| row[:id].length }.max
+      rows.each do |row|
+        @out.puts
+        @out.puts "  #{row[:id].ljust(width)}  #{row[:title]}  ·  #{row[:type]}  ·  #{row[:matched].join("+")}"
+        @out.puts "    #{truncate(row[:snippet], 100)}" unless row[:snippet].empty?
+      end
+    end
+
+    def print_search_json(dir, terms, rows, options)
+      emit_list_json(dir, "matches", rows.map { |row| stringify(row) }, options, "query" => terms)
+    end
+
     def server(argv)
       require "okf/server/app"
 
@@ -801,13 +861,16 @@ module OKF
     # Emit a list view's JSON envelope with --fields/--except projection applied to
     # each item. Returns the verb's exit code (0, or 2 on a bad projection request —
     # both flags at once, or a field name no item carries).
-    def emit_list_json(dir, key, items, options)
+    def emit_list_json(dir, key, items, options, extra = {})
       return usage_error("--fields and --except are mutually exclusive") if options[:fields] && options[:except]
 
       unknown = unknown_fields(items, options)
       return usage_error("unknown field(s): #{unknown.join(", ")} (available: #{available_fields(items).join(", ")})") unless unknown.empty?
 
-      emit_json("bundle" => dir, "count" => items.size, key => project(items, options))
+      payload = { "bundle" => dir }.merge(extra)
+      payload["count"] = items.size
+      payload[key] = project(items, options)
+      emit_json(payload)
       0
     end
 
@@ -889,6 +952,7 @@ module OKF
           loose     <dir> [--json]                          list files with no graph links, by folder
           validate  <dir> [--json]                          check OKF v0.1 conformance
 
+          search    <dir> <term…> [-e] [--in FIELDS] [...]  find concepts by text or regexp, ranked
           index     <dir> [--json] [--area A] [--no-body]   the index map: dirs, their listings and rollups
           stats     <dir> [--json]                          bundle rollups (concepts, types, areas, links, tags)
           types     <dir> [--json] [filters]                list types with their concepts, by count
@@ -903,7 +967,7 @@ module OKF
         tags --by DIM regroups the tags per concept dimension — type or area — with
         within-group counts, the view for curating a tag vocabulary.
         --json emits compact JSON (the machine substrate); add --pretty to indent it.
-        --fields / --except project the JSON to the properties you want (index/catalog/files).
+        --fields / --except project the JSON to the properties you want (search/index/catalog/files).
 
         okf --version
       USAGE

data/lib/okf/server/app.rb

@@ -24,6 +24,12 @@ module OKF
     #                       tags, timestamp, status, area, dir, links_*} ] } (JSON)
     #   GET /tags           the tag index  { tag  => [id, …] } (JSON)
     #   GET /types          the type index { type => [id, …] } (JSON)
+    #   GET /index          the §6 progressive-disclosure map for the Index panel:
+    #                       { directories: [ …okf-index rows… ] } (JSON, from the
+    #                       boot snapshot — authored maps are structure)
+    #   GET /log            the §7 history for the Log panel: { logs: [ {path,
+    #                       dir, content} ] } (JSON; content read live from disk,
+    #                       like a body — the log is the file that changes most)
     class App
       def initialize(folder, title: nil, link: nil, layout: "cose")
         @folder = folder
@@ -43,6 +49,8 @@ module OKF
         when "/catalog" then respond_json(catalog)
         when "/tags" then respond_json(graph.tag_index)
         when "/types" then respond_json(graph.type_index)
+        when "/index" then respond_json(directory_index)
+        when "/log" then respond_json(logs)
         else not_found
         end
       end
@@ -63,6 +71,27 @@ module OKF
         { concepts: @folder.catalog }
       end
 
+      # The §6 map the Index panel renders — the same rows `okf index` prints,
+      # built by the pure OKF::Bundle#directory_index over the boot snapshot
+      # (authored index bodies are structure, read at load like the graph).
+      def directory_index
+        { directories: @folder.directory_index }
+      end
+
+      # Every log.md with its content, root scope first. Content is read live
+      # from disk so a just-appended entry shows without a restart; paths come
+      # from the loaded bundle, never from the request.
+      def logs
+        entries = @folder.bundle.log_files.sort_by { |path| [ path == "log.md" ? 0 : 1, path ] }
+        { logs: entries.map { |path| { path: path, dir: File.dirname(path), content: log_content(path) } } }
+      end
+
+      def log_content(path)
+        File.read(File.join(@folder.root, path), encoding: "UTF-8")
+      rescue SystemCallError
+        @folder.bundle.reserved_content(path)
+      end
+
       def page
         @page ||= Graph.new(graph, title: @title || @folder.name, link: @link, layout: @layout).render
       end