okf 1.13.0 → 2.0.0

data/lib/okf/bundle.rb

@@ -66,6 +66,28 @@ module OKF
       entry ? entry.content.to_s : ""
     end
 
+    # The spec version the root index.md declares (§12), as the producer wrote
+    # it, or nil when it declares none — which §12 explicitly permits, so nil is
+    # an answer rather than a fault, and a consumer that must name a version
+    # should say "conformant" rather than guess one.
+    #
+    # Stringified and stripped for the reason the validator compares that way:
+    # an unquoted `okf_version: 0.2` is a Psych Float, and a consumer switching
+    # on it must not be handed 0.2 the number. Public because a version stated
+    # on screen is otherwise a literal — which is how a reader gets told "v0.1"
+    # about a bundle that declares 0.2. Unparseable frontmatter is the
+    # validator's error to report, not this reader's to raise.
+    def okf_version
+      content = reserved_content("index.md")
+      return nil unless content.match?(/\A---[ \t]*\n/)
+
+      frontmatter, = Markdown::Frontmatter.parse(content)
+      declared = frontmatter["okf_version"]
+      OKF.blank?(declared) ? nil : declared.to_s.strip
+    rescue Markdown::Frontmatter::ParseError
+      nil
+    end
+
     # ── id ↔ path (the single source of "which concept an id names") ──
     # A concept's id may be a frontmatter `id`, so it is not derivable from the path
     # alone. These maps let the shell resolve an id back to its file (the server's
@@ -119,8 +141,13 @@ module OKF
           type: concept.type.to_s,
           description: concept.description.to_s,
           tags: Array(concept.tags).map(&:to_s),
-          timestamp: concept.timestamp&.to_s,
-          status: concept.frontmatter["status"]&.to_s,
+          generated_at: iso8601(concept.generated_at),
+          generated_by: concept.generated_by&.to_s,
+          generated: concept.declared_generated?,
+          trust: concept.trust,
+          status: concept.declared_status&.to_s,
+          stale_after: iso8601(concept.stale_after),
+          sources: concept.sources.length,
           backlog_ref: concept.frontmatter["backlog_ref"]&.to_s,
           dir: OKF.dir_of(id),
           top_dir: top_dir_of(id),
@@ -148,14 +175,71 @@ module OKF
       end.sort_by { |row| [ -row[:inbound], row[:id] ] }
     end
 
-    # The progressive-disclosure map (spec §6): one entry per directory that holds
+    # Bundle-level rollups — concepts, dirs, types, links, tags, with the
+    # by_type/by_dir/by_top_dir distributions. One home, shared by `okf stats`
+    # and the MCP stats tool, because the by_dir subtlety already diverged once
+    # when hand-copied: it reads Bundle#directory_index (the map `--dir` is
+    # answered against), so a directory holding nothing directly appears at 0
+    # rather than disappearing, and `dirs` equals `by_dir.size`.
+    # Note the recorded split: by_dir is the disk, by_top_dir rolls up the id.
+    def stats
+      minimal = graph(minimal: true)
+      entries = catalog
+      by_type = minimal.type_index.transform_values(&:size).sort_by { |_, size| -size }.to_h
+      by_top_dir = entries.group_by { |entry| entry[:top_dir] }.transform_values(&:size).sort_by { |_, size| -size }.to_h
+      by_dir = directory_index.map { |entry| [ entry[:dir], entry[:count] ] }
+                              .sort_by { |dir, count| [ -count, dir ] }.to_h
+      {
+        concepts: entries.size,
+        dirs: by_dir.size,
+        top_dirs: by_top_dir.size,
+        types: by_type.size,
+        cross_links: minimal.edges.size,
+        tags: minimal.tag_index.size,
+        by_type: by_type,
+        by_dir: by_dir,
+        by_top_dir: by_top_dir
+      }
+    end
+
+    # The tag index re-cut per concept dimension — the vocabulary-curation
+    # view: [ [ group-key, rows ], … ] with each row carrying `count` (within
+    # the group) beside `total` (across the set), so a tag local to one group
+    # and one cutting across several read differently without cross-referencing
+    # by hand. `by:` is :type (blank folds to "Untyped", matching the graph),
+    # :dir (the stored spelling — `.` for the root), or anything else for the
+    # deprecated first-segment cut. `entries:` narrows the concepts counted —
+    # the CLI passes its filtered catalog; default is everything.
+    def tag_groups(by:, entries: nil)
+      entries ||= catalog
+      by_id = entries.map { |entry| [ entry[:id], entry ] }.to_h
+      groups = {}
+      totals = Hash.new(0)
+      graph(minimal: true).tag_index.each do |tag, ids|
+        ids.each do |id|
+          entry = by_id[id]
+          next if entry.nil?
+
+          key = tag_group_key(entry, by)
+          ((groups[key] ||= {})[tag] ||= []) << id
+          totals[tag] += 1
+        end
+      end
+      groups.map do |key, tags|
+        rows = tags.map { |tag, ids| { tag: tag, count: ids.length, total: totals[tag], concepts: ids } }
+                   .sort_by { |row| [ -row[:count], row[:tag] ] }
+        [ key, rows ]
+      end.sort_by(&:first)
+    end
+
+    # The progressive-disclosure map (spec §8): one entry per directory that holds
     # concepts or carries an index.md, sorted with the root (".") first. Each entry
     # gives the authored index body (frontmatter stripped) when an index.md is
     # present, a type/tag rollup over the concepts that live *directly* in the
     # directory, its immediate child directories, and the concept listing an
     # index.md there would enumerate. A directory with concepts but no index.md has
     # `present: false` and still carries the listing, so a consumer can synthesize
-    # the map on the fly (§6 permits exactly that). Grouped by the concept's file
+    # the map on the fly (§8 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
@@ -205,6 +289,12 @@ module OKF
 
     private
 
+    # The one temporal-serialization rule, shared with /node/meta — see
+    # OKF.iso8601.
+    def iso8601(value)
+      OKF.iso8601(value)
+    end
+
     # A concept's top-level dir, derived from its id — the first path segment, the
     # same derivation the catalog exposes, so every grouped view labels the bundle
     # root "(root)". OKF.dir_of keeps the levels this one rolls up.
@@ -233,6 +323,17 @@ module OKF
       dirs.keys.sort_by { |dir| dir == "." ? "" : dir }
     end
 
+    # The group a concept falls in, in its *stored* spelling — `.` for the
+    # root under :dir, never "(root)": the human label is applied at print
+    # time, so the JSON and a table cannot disagree about which is the data.
+    def tag_group_key(entry, dim)
+      case dim
+      when :type then OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
+      when :dir then entry[:dir]
+      else entry[:top_dir]
+      end
+    end
+
     # { value => count }, ordered by count descending then value.
     def tally(values)
       counts = values.each_with_object(Hash.new(0)) { |value, acc| acc[value] += 1 }

data/lib/okf/cli/catalog.rb

@@ -22,7 +22,7 @@ module OKF
       def call(argv)
         options = { json: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf catalog <dir|@slug> [--type T] [--dir D] [--tag T] [--json]"
+          o.banner = "Usage: okf catalog <dir|@slug> [--type T] [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the catalog as JSON")
           projection_flags(o, options)
           filter_flags(o, options, :type, :area, :tag)

data/lib/okf/cli/command.rb

@@ -23,6 +23,11 @@ module OKF
       # it is installed instead of the first time a user types its verb.
       DUCK_TYPE = %i[id group help_rows hidden? new].freeze
 
+      # Every key a filter flag can set. One list, read by both the narrowing
+      # itself and the "is anything narrowing?" guard, so adding a filter cannot
+      # leave one of them behind.
+      FILTER_KEYS = %i[type area dir tag status trust].freeze
+
       class << self
         # The verb this answers to, as a Symbol. The registry is keyed on it.
         def id
@@ -188,6 +193,17 @@ module OKF
           end
         end
         parser.on("--tag TAG", "only concepts carrying this tag") { |v| options[:tag] = v } if keys.include?(:tag)
+        # The read-side payoff of v0.2, and the two questions no v0.1 tool could
+        # answer: which concepts nobody has verified, and which are on their way
+        # out. Unconditional — every filtering verb narrows the same catalog
+        # rows, and on a v0.1 bundle the answers still read (`stable` for every
+        # concept, `unverified` for every concept — §13.1, not an error).
+        parser.on("--status STATUS", "only concepts at this lifecycle status (draft | stable | deprecated)") do |v|
+          options[:status] = v
+        end
+        parser.on("--trust TIER", "only concepts at this trust tier (unverified | machine-confirmed | human-reviewed)") do |v|
+          options[:trust] = v
+        end
       end
 
       # The argument is resolved once per view, not once per entry: the `root`
@@ -206,14 +222,17 @@ module OKF
       # shape. An out-of-tree caller that never learned the third argument gets
       # exactly the resolution it was written against — the alias folds with no
       # directory set consulted — no better and no worse.
+      # The row rules live in Bundle::RowFilter, shared with the MCP shell;
+      # this layer keeps only what is the CLI's own — the deprecated --area
+      # (a top_dir compare no other surface offers) and the argument spelling
+      # (the `root`/`.` aliases resolved against the bundle's real dirs).
       def filter_entries(entries, options, dirs = nil)
         area = options[:area] && fold_area(options[:area], dirs)
         base = options[:dir] && fold_dir(options[:dir], dirs)
         entries.select do |entry|
-          (options[:type].nil? || fold(entry[:type]) == fold(options[:type])) &&
-            (area.nil? || fold(entry[:top_dir]) == area) &&
-            (base.nil? || under_dir?(entry[:dir], base)) &&
-            (options[:tag].nil? || entry[:tags].any? { |tag| fold(tag) == fold(options[:tag]) })
+          (area.nil? || fold(entry[:top_dir]) == area) &&
+            Bundle::RowFilter.matches?(entry, type: options[:type], dir: base, tag: options[:tag],
+              status: options[:status], trust: options[:trust])
         end
       end
 
@@ -234,9 +253,9 @@ module OKF
       # and #fold for a stored one. A stored dir is never an alias — that is the
       # distinction the old signature could not make, and it is what had a row
       # named `root` counting the bundle root's subtree instead of its own.
+      # The comparison itself is Bundle::RowFilter's (fold is idempotent).
       def under_dir?(entry_dir, path)
-        entry = fold(entry_dir)
-        entry == path || entry.start_with?("#{path}/")
+        Bundle::RowFilter.under_dir?(entry_dir, path)
       end
 
       def fold(value)
@@ -429,12 +448,12 @@ module OKF
       # into a single ranking with nothing saying so. One invocation, one
       # meaning — see Search#multi_search.
       def filter_ids(folder, options, dirs = nil)
-        return nil if options[:type].nil? && options[:area].nil? && options[:dir].nil? && options[:tag].nil?
+        return nil if FILTER_KEYS.none? { |key| options[key] }
 
         filter_entries(folder.catalog, options, dirs || dir_scope(folder, options)).map { |entry| entry[:id] }
       end
 
-      # §9 best-effort: the graph is built from concepts that parse. Surface any that
+      # §11 best-effort: the graph is built from concepts that parse. Surface any that
       # the reader could not parse (to stderr, so JSON on stdout stays clean) rather
       # than dropping them silently.
       def report_skipped(folder)

data/lib/okf/cli/files.rb

@@ -22,7 +22,7 @@ module OKF
       def call(argv)
         options = { json: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf files <dir|@slug> [--type T] [--dir D] [--tag T] [--json]"
+          o.banner = "Usage: okf files <dir|@slug> [--type T] [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the file tree as JSON")
           projection_flags(o, options)
           filter_flags(o, options, :type, :area, :tag)

data/lib/okf/cli/index.rb

@@ -2,7 +2,7 @@
 
 module OKF
   class CLI
-    # The progressive-disclosure map (spec §6): every directory that holds concepts
+    # The progressive-disclosure map (spec §8): every directory that holds concepts
     # or carries an index.md, with its authored index body, a type/tag rollup, its
     # child directories, and — for a directory with no index.md — the listing
     # synthesized from the concepts there. The "orient before you read" view. `--dir`

data/lib/okf/cli/lint.rb

@@ -10,12 +10,19 @@ module OKF
       LINT_CATEGORIES = {
         "Reachability" => %i[orphan not_in_index disconnected_component unlinked],
         "Backlog" => %i[missing_concept broken_index_entry],
-        "Completeness" => %i[stub missing_title missing_description missing_timestamp],
-        "Freshness" => %i[stale],
-        "Provenance" => %i[uncited_external broken_citation],
-        "Hygiene" => %i[duplicate_title unused_reference_def undefined_reference self_link]
+        "Completeness" => %i[stub missing_title missing_description missing_generated],
+        "Freshness" => %i[expired stale],
+        "Provenance" => %i[uncited_external broken_source unattributed_claim unused_source unprefixed_actor],
+        "Attestation" => %i[incomplete_computation broken_attestation_ref],
+        "Migration" => %i[legacy_timestamp legacy_citations],
+        "Hygiene" => %i[duplicate_title unused_reference_def undefined_reference self_link log_order]
       }.freeze
 
+      # `--today` reason for existing, in one line: a CI consumer wanting a
+      # reproducible `expired` report needs a fixed clock. Semver-stable API,
+      # documented in the skill's cli.md; absent, the CLI reads the wall clock —
+      # the library default (`Linter.call` with no `today:`) reads none at all.
+
       def self.id
         :lint
       end
@@ -26,20 +33,24 @@ module OKF
 
       def self.help_rows
         [
-          [ "lint      <dir|@slug> [--json] [--fail-on warn] [...]", "report curation-quality issues" ]
+          [ "lint      <dir|@slug> [--json] [--fail-on LEVEL] [...]", "report curation-quality issues" ]
         ]
       end
 
       def call(argv)
-        options = { json: false, min_body: OKF::Bundle::Linter::DEFAULT_MIN_BODY, stale_after: nil, only: nil, except: nil, fail_on: :never }
+        options = { json: false, min_body: OKF::Bundle::Linter::DEFAULT_MIN_BODY, stale_after: nil,
+                    today: nil, only: nil, except: nil, fail_on: :never }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf lint <dir|@slug> [--json] [--min-body N] [--stale-after DUR] [--only a,b] [--except a,b] [--fail-on warn]"
+          o.banner = "Usage: okf lint <dir|@slug> [--json] [--min-body N] [--stale-after DUR] [--today DATE] " \
+                     "[--only a,b] [--except a,b] [--fail-on never|info|warn]"
           json_flags(o, options, "emit a JSON report")
           o.on("--min-body N", Integer, "stub threshold in body characters (default #{OKF::Bundle::Linter::DEFAULT_MIN_BODY})") { |v| options[:min_body] = v }
-          o.on("--stale-after DUR", "flag concepts older than DUR (e.g. 90d, 12w, 2026-01-01)") { |v| options[:stale_after] = v }
+          o.on("--stale-after DUR", "flag concepts older than DUR (e.g. 90d, 12w, 2026-01-01,",
+            "or a full 2026-01-01T09:00:00Z timestamp)") { |v| options[:stale_after] = v }
+          o.on("--today DATE", "the day `expired` compares stale_after against (default: today)") { |v| options[:today] = v }
           o.on("--only LIST", Array, "run only these checks (comma-separated)") { |v| options[:only] = v.map(&:to_sym) }
           o.on("--except LIST", Array, "skip these checks (comma-separated)") { |v| options[:except] = v.map(&:to_sym) }
-          o.on("--fail-on LEVEL", %w[never warn], "exit 1 when a finding at LEVEL exists (never | warn)") { |v| options[:fail_on] = v.to_sym }
+          o.on("--fail-on LEVEL", %w[never info warn], "exit 1 when a finding at LEVEL exists (never | info | warn)") { |v| options[:fail_on] = v.to_sym }
           help_flag(o)
         end
         dir = positional_dir(parser, argv) or return 2
@@ -56,15 +67,42 @@ module OKF
           return 2
         end
 
+        today = parse_today(options[:today])
+        if today == :invalid
+          @err.puts "error: invalid --today `#{options[:today]}` (use YYYY-MM-DD)"
+          return 2
+        end
+
         folder = OKF::Bundle::Folder.load(dir)
-        report = folder.lint(min_body: options[:min_body], stale_before: stale_before, only: options[:only], except: options[:except])
+        report = folder.lint(min_body: options[:min_body], stale_before: stale_before, today: today,
+          only: options[:only], except: options[:except])
         note_skipped(report.stats[:skipped])
         options[:json] ? print_lint_json(dir, report) : print_lint(dir, report)
-        options[:fail_on] == :warn && report.warnings.any? ? 1 : 0
+        lint_exit(options[:fail_on], report)
       end
 
       private
 
+      def lint_exit(fail_on, report)
+        case fail_on
+        when :warn then report.warnings.any? ? 1 : 0
+        when :info then report.findings.any? ? 1 : 0
+        else 0
+        end
+      end
+
+      # The CLI always supplies a clock — Date.today unless --today pins one —
+      # so `okf lint` reports `expired` out of the box while the pure library
+      # default runs no clock check at all (and confesses via skipped_checks).
+      def parse_today(value)
+        return Date.today if value.nil?
+        return :invalid unless value.match?(Concept::ISO_DATE)
+
+        Date.iso8601(value)
+      rescue ArgumentError
+        :invalid
+      end
+
       # Turn a --stale-after value (90d, 12w, or an ISO date) into an absolute cutoff
       # Time so the pure Linter never reads the clock. nil when unset, :invalid on a
       # bad value.
@@ -74,8 +112,14 @@ module OKF
         if (match = value.match(/\A(\d+)([dw])\z/))
           days = match[1].to_i * (match[2] == "w" ? 7 : 1)
           Time.now - (days * 86_400)
-        else
+        elsif value.match?(Concept::ISO_CUTOFF)
+          # Not --today's grammar: that one is a calendar day, this one a
+          # moment, so a full `generated.at` timestamp is accepted and reduced
+          # to its date. What both refuse is the same — the basic and week
+          # spellings Date.iso8601 would silently reinterpret.
           Date.iso8601(value).to_time
+        else
+          :invalid
         end
       rescue ArgumentError
         :invalid
@@ -87,6 +131,8 @@ module OKF
         @out.puts "  concepts: #{stats[:concepts]}   edges: #{stats[:edges]}   index.md: #{stats[:indexes]}   log.md: #{stats[:logs]}"
         summary = lint_summary(stats)
         @out.puts "  #{summary}" unless summary.empty?
+        posture = lint_posture(stats)
+        @out.puts "  #{posture}" unless posture.empty?
 
         LINT_CATEGORIES.each do |name, checks|
           findings = report.findings.select { |finding| checks.include?(finding[:check]) }
@@ -99,6 +145,8 @@ module OKF
           end
         end
 
+        skipped = Array(report.stats[:skipped_checks])
+        @out.puts "  skipped: #{skipped.join(", ")} (no clock or cutoff supplied)" unless skipped.empty?
         @out.puts
         @out.puts "  #{lint_verdict(report)}"
       end
@@ -120,6 +168,16 @@ module OKF
         parts.join("   ")
       end
 
+      # The bundle's trust/status posture, printed only when there is a bundle
+      # to have one (an empty bundle has no distribution worth a line).
+      def lint_posture(stats)
+        return "" if stats[:concepts].zero?
+
+        trust = stats[:trust].map { |tier, count| "#{tier} #{count}" }.join(", ")
+        status = stats[:status].map { |value, count| "#{value} #{count}" }.join(", ")
+        "trust: #{trust}   status: #{status}"
+      end
+
       def lint_glyph(finding)
         finding[:severity] == :warn ? paint("! warn", 33) : "· info"
       end

data/lib/okf/cli/references.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The §6.3 inventory: every file under `references/`, which concepts cite
+    # it through the §6.2 path-valued fields, and the pointers into
+    # `references/` that resolve to nothing — with the leading-slash fix named
+    # when a bare path written from a subdirectory is what missed. An advisory
+    # read (exit 0): what a curator acts on lives in the output, never the
+    # status.
+    class References < Command
+      def self.id
+        :references
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "references <dir|@slug> [--json]", "inventory references/ files and the concepts citing them" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf references <dir|@slug> [--json]"
+          json_flags(o, options, "emit the inventory as JSON")
+          projection_flags(o, options)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        references = folder.references
+        return print_references_json(dir, references, options) if options[:json]
+
+        print_references(dir, references)
+        0
+      end
+
+      private
+
+      def print_references(dir, references)
+        entries = references.entries
+        @out.puts "References — #{bundle_label(dir)} (#{entries.size} #{pluralize(entries.size, "file")})"
+        @out.puts "  (none)" if entries.empty?
+        entries.group_by { |entry| entry[:dir] }.sort_by(&:first).each do |folder, group|
+          width = group.map { |entry| File.basename(entry[:path]).length }.max
+          @out.puts
+          @out.puts "  #{folder}/"
+          group.each do |entry|
+            @out.puts "    #{File.basename(entry[:path]).ljust(width)}  #{entry_note(entry)}"
+          end
+        end
+        print_dangling(references.dangling)
+      end
+
+      def entry_note(entry)
+        marker = entry[:kind] == "concept" ? "[concept]  " : ""
+        cited = entry[:referenced_by]
+        return "#{marker}(unreferenced)" if cited.empty?
+
+        "#{marker}← #{cited.map { |ref| "#{ref[:id]} (#{ref[:field]})" }.join(", ")}"
+      end
+
+      def print_dangling(rows)
+        return if rows.empty?
+
+        @out.puts
+        @out.puts "  dangling pointers:"
+        rows.each do |row|
+          @out.puts "    #{row[:id]} — #{row[:field]}: #{row[:raw]}"
+          line = "      resolves to #{row[:resolved]}, which does not exist"
+          # hint is only ever the leading-slash fix, so the human line can name
+          # the spelling that would have hit without restating the sentence.
+          line += " — /#{row[:raw]} does (missing leading slash?)" if row[:hint]
+          @out.puts line
+        end
+      end
+
+      def print_references_json(dir, references, options)
+        rows = references.entries.map do |entry|
+          { "path" => entry[:path], "dir" => entry[:dir], "kind" => entry[:kind],
+            "referenced_by" => entry[:referenced_by].map { |ref| stringify(ref) } }
+        end
+        dangling = references.dangling.map { |row| stringify(row) }
+        emit_list_json(dir, "references", rows, options, "dangling" => dangling)
+      end
+    end
+
+    register(References)
+  end
+end

data/lib/okf/cli/search.rb

@@ -34,7 +34,8 @@ module OKF
       def call(argv)
         options = { json: false, regexp: false, fuzzy: false, engine: nil }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] [--in FIELDS] [--type T] [--dir D] [--tag T] [--json]"
+          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] " \
+                     "[--in FIELDS] [--type T] [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           search_engine_note(o)
           json_flags(o, options, "emit the matches as JSON")
           projection_flags(o, options)

data/lib/okf/cli/stats.rb

@@ -29,51 +29,15 @@ module OKF
 
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
-        stats = bundle_stats(folder)
+        stats = folder.stats
         options[:json] ? print_stats_json(dir, stats) : print_stats(dir, stats)
         0
       end
 
       private
 
-      # Bundle-level rollups derived from the catalog and the graph indexes.
-      def bundle_stats(folder)
-        graph = folder.graph(minimal: true)
-        entries = folder.catalog
-        by_type = graph.type_index.transform_values(&:size).sort_by { |_, n| -n }.to_h
-        by_top_dir = entries.group_by { |entry| entry[:top_dir] }.transform_values(&:size).sort_by { |_, n| -n }.to_h
-        by_dir = directory_counts(folder)
-        {
-          concepts: entries.size,
-          dirs: by_dir.size,
-          top_dirs: by_top_dir.size,
-          types: by_type.size,
-          cross_links: graph.edges.size,
-          tags: graph.tag_index.size,
-          by_type: by_type,
-          by_dir: by_dir,
-          by_top_dir: by_top_dir
-        }
-      end
-
-      # Every directory the bundle has, with the concepts that live *directly* in
-      # it. Read off Bundle#directory_index — the same map `okf dirs` lists and
-      # `--dir` is answered against — rather than off the catalog, which knows
-      # only the directories that happen to hold a concept. Grouping the catalog
-      # made `stats` and `dirs` report different totals for one bundle, and left
-      # an addressable directory out of by_dir entirely: `--dir deeply` answers,
-      # but nothing in `stats` said `deeply` was there to ask about.
-      #
-      # A directory holding nothing directly therefore appears at 0. That is the
-      # honest reading — it is the same zero `okf dirs` prints in its Concepts
-      # column — and it keeps `dirs` equal to `by_dir.size`. Ties break by path so
-      # the order is total, not whatever the sort happened to leave.
-      def directory_counts(folder)
-        folder.directory_index
-              .map { |entry| [ entry[:dir], entry[:count] ] }
-              .sort_by { |dir, count| [ -count, dir ] }.to_h
-      end
-
+      # The rollup itself is Bundle#stats — one home, shared with the MCP
+      # shell, after the by_dir subtlety diverged once when hand-copied.
       def print_stats(dir, stats)
         @out.puts "Stats — #{bundle_label(dir)}"
         @out.puts

data/lib/okf/cli/tags.rb

@@ -23,7 +23,7 @@ module OKF
       def call(argv)
         options = { json: false, by: nil }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf tags <dir|@slug> [--by type|dir] [--type T] [--dir D] [--json]"
+          o.banner = "Usage: okf tags <dir|@slug> [--by type|dir] [--type T] [--dir D] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the tag index as JSON")
           o.on("--by DIM", %w[type dir area], "group the tags by a concept dimension (type | dir)") do |v|
             options[:by] = v.to_sym
@@ -50,52 +50,15 @@ module OKF
         report_skipped(folder)
         graph = folder.graph(minimal: true)
         titles = graph.nodes.map { |node| [ node[:id], node[:title] ] }.to_h
-        groups = tag_groups(graph.tag_index, folder, options)
+        groups = folder.tag_groups(by: options[:by],
+          entries: filter_entries(folder.catalog, options, dir_scope(folder, options)))
         options[:json] ? print_grouped_tags_json(dir, options[:by], groups) : print_grouped_tags(dir, options[:by], groups, titles)
         0
       end
 
-      # [ [ group, rows ], … ] — groups sorted by name, rows shaped like index_rows'
-      # plus each tag's total across the narrowed set. A tag carried in several
-      # groups appears in each, counted per group; count/total per row is what
-      # makes a tag's spread — local to one group, or cutting across several —
-      # readable without cross-referencing the groups by hand.
-      def tag_groups(tag_index, folder, options)
-        by_id = filter_entries(folder.catalog, options, dir_scope(folder, options)).map { |entry| [ entry[:id], entry ] }.to_h
-        groups = {}
-        totals = Hash.new(0)
-        tag_index.each do |tag, ids|
-          ids.each do |id|
-            entry = by_id[id]
-            next if entry.nil?
-
-            key = group_key(entry, options[:by])
-            ((groups[key] ||= {})[tag] ||= []) << id
-            totals[tag] += 1
-          end
-        end
-        groups.map do |key, tags|
-          rows = tags.map { |tag, ids| { tag: tag, count: ids.length, total: totals[tag], concepts: ids } }
-                     .sort_by { |row| [ -row[:count], row[:tag] ] }
-          [ key, rows ]
-        end.sort_by(&:first)
-      end
-
-      # A catalog entry's type for display — "Untyped" when blank, matching the graph.
-      def entry_type(entry)
-        OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
-      end
-
-      # The group a concept falls in, in its *stored* spelling — `.` for the root
-      # under --by dir, never "(root)". The human label is applied at print time,
-      # so the JSON and the table cannot disagree about which one is the data.
-      def group_key(entry, dim)
-        case dim
-        when :type then entry_type(entry)
-        when :dir then entry[:dir]
-        else entry[:top_dir]
-        end
-      end
+      # The grouping itself is Bundle#tag_groups — one home, shared with the
+      # MCP shell; this layer keeps only what is the CLI's own, the filter
+      # narrowing passed through `entries:`.
 
       # `.` prints "(root)" bare; every other dir carries the trailing slash that
       # says it is one. The deprecated --by area already stores "(root)" itself.

data/lib/okf/cli/types.rb

@@ -21,7 +21,7 @@ module OKF
       def call(argv)
         options = { json: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf types <dir|@slug> [--dir D] [--tag T] [--json]"
+          o.banner = "Usage: okf types <dir|@slug> [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the type index as JSON")
           filter_flags(o, options, :area, :tag)
           help_flag(o)