okf 1.10.0 → 1.11.0

data/lib/okf/bundle/folder.rb

@@ -64,13 +64,28 @@ module OKF
         end
       end
 
-      # Human-readable "parent/dir" name — the default HTML title.
-      # The bundle's display label, "parent/dir" — path arithmetic, no disk. It
-      # is a class method so a caller that only wants the label (the registry
-      # naming an entry) can have it without a Reader.read of every file.
+      # The bundle's display label — path arithmetic, no disk. It is a class
+      # method so a caller that only wants the label (the registry naming an
+      # entry) can have it without a Reader.read of every file.
+      #
+      # "parent/dir", because a bundle directory's own name is rarely unique
+      # enough to name it by — except when that name is `.okf`, the conventional
+      # container, and then the parent carries the whole answer on its own. A
+      # registry of eight projects is eight rows reading `…/.okf`, which is the
+      # one word that tells none of them apart; `repo/.okf` is read as "repo" by
+      # anyone looking at it anyway.
+      #
+      # A directory with no parent to borrow (`/.okf`) keeps its own name: the
+      # parent is `/`, which names nothing. That case used to compose into
+      # `//.okf`.
       def self.label(root)
         pathname = Pathname.new(root)
-        "#{pathname.parent.basename}/#{pathname.basename}"
+        parent = pathname.parent.basename.to_s
+        base = pathname.basename.to_s
+        return base if [ "/", "." ].include?(parent)
+        return parent if base == ".okf"
+
+        "#{parent}/#{base}"
       end
 
       def name

data/lib/okf/bundle/linter.rb

@@ -324,7 +324,7 @@ module OKF
       end
 
       def concepts_in(dir)
-        @concepts.select { |concept| File.dirname("#{concept.id}.md") == dir }
+        @concepts.select { |concept| OKF.dir_of(concept.id) == dir }
       end
 
       def index_path_for(dir)

data/lib/okf/bundle/search/index.rb

@@ -12,8 +12,9 @@ module OKF
       #
       # Matching is by *token*: a term matches a whole word or a word it prefixes
       # ("dedup" reaches "deduplication"), and `fuzzy:` opts into typo tolerance.
-      # The index is built per call — see .okf/capabilities/search.md for why that
-      # ceiling stands and what lifts it.
+      # The index builds per call unless the caller holds a Search::Corpus, which
+      # builds it once through .prepare and reuses it — the server does, the
+      # one-shot CLI cannot. See .okf/capabilities/search.md.
       module Index
         CAPABILITIES = %i[fuzzy prefix].freeze
 
@@ -37,9 +38,18 @@ module OKF
           # can neither match nor be credited. The hit's `terms` are MiniFTS's
           # matched *document* terms — already lowercased, and present in the text
           # verbatim even when the query only prefixed them.
-          def call(documents, terms, fields:, fuzzy: false, **_options)
+          # The expensive half, separated so a long-lived caller can hold it. A
+          # Corpus calls this once; a one-shot call still goes through #call and
+          # builds inline, which is why this is an addition and not a new
+          # requirement on the engine contract.
+          def prepare(documents)
             index = MiniFTS.new(fields: FIELDS, id_field: "key")
             index.add_all(documents)
+            index
+          end
+
+          def call(documents, terms, fields:, fuzzy: false, prepared: nil, **_options)
+            index = prepared || prepare(documents)
 
             options = { combine_with: "AND", prefix: true, boost: WEIGHTS, fields: fields }
             options[:fuzzy] = FUZZY_DISTANCE if fuzzy

data/lib/okf/bundle/search.rb

@@ -186,12 +186,89 @@ module OKF
         new(bundles, terms, fields: fields, regexp: regexp, fuzzy: fuzzy, engine: engine, engines: engines).results
       end
 
+      # The searchable text of one concept, by field. Here rather than on an
+      # instance because a Corpus builds documents with no query in hand.
+      def self.field_texts(concept)
+        {
+          "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
+        }
+      end
+
+      # A corpus prepared once and queried many times: the documents, the key →
+      # concept map, and each engine's built index.
+      #
+      # This is the asymmetry the engine choice was always argued from. A CLI
+      # process loads a bundle, asks one question and exits, so an index build has
+      # exactly one query to amortize over and the scan wins. A server is the
+      # other case — the build is ~95% of the index path's cost, and paying it per
+      # request made every search re-read the whole corpus. Held once, it is paid
+      # once.
+      #
+      # Pure: it holds concepts, never disk. Which is also the cost — the corpus
+      # is a snapshot, so a body edited after it was built is searchable only
+      # after the holder drops it. That matches the graph, which is memoized the
+      # same way and for the same reason.
+      class Corpus
+        attr_reader :bundles, :documents, :sources
+
+        def initialize(bundles)
+          @bundles = bundles
+          @documents = []
+          @sources = {}
+          @indexes = {}
+          bundles.each do |slug, bundle|
+            bundle.concepts.each do |concept|
+              key = "#{slug}#{KEY_SEPARATOR}#{concept.id}"
+              @sources[key] = [ slug, concept ]
+              @documents << Search.field_texts(concept).merge("key" => key)
+            end
+          end
+        end
+
+        # nil for an engine with nothing to prebuild — the scan reads raw text and
+        # has no index to hold — so the option only ever reaches one that declared
+        # it can. Memoized per engine id: two engines over one corpus is legal.
+        def index_for(engine)
+          return nil unless engine.respond_to?(:prepare)
+
+          @indexes[engine.id] ||= engine.prepare(@documents)
+        end
+      end
+
+      # Prepare a corpus for a long-lived caller. Hand the result back to .with
+      # for every query.
+      #
+      # `engine:` builds that engine's index *now* rather than on the first query.
+      # Without it the corpus holds only the documents, and the expensive half —
+      # the index — is still built lazily, which puts the whole cost on whoever
+      # searches first. A server knows its engine at boot, so it can pay there.
+      def self.prepare(bundles, engine: nil, engines: nil)
+        corpus = Corpus.new(bundles)
+        return corpus if OKF.blank?(engine)
+
+        corpus.index_for(engine_for([], engines: engines || self.engines, name: engine))
+        corpus
+      end
+
+      # Query a prepared corpus. Same rows as .across, without rebuilding what the
+      # corpus already holds.
+      def self.with(corpus, terms, fields: nil, regexp: false, fuzzy: false, engine: nil, engines: nil)
+        new(corpus.bundles, terms, fields: fields, regexp: regexp, fuzzy: fuzzy,
+          engine: engine, engines: engines, corpus: corpus).results
+      end
+
       # Raises RegexpError on an invalid pattern with `regexp: true`, and
       # UnsupportedQuery when no engine can answer — the caller owns turning
       # either into a usage error. `engines:` overrides the registry, which is how
       # the "nothing qualifies" path stays reachable without an addon installed.
-      def initialize(bundles, terms, fields: nil, regexp: false, fuzzy: false, engine: nil, engines: nil)
+      def initialize(bundles, terms, fields: nil, regexp: false, fuzzy: false, engine: nil, engines: nil, corpus: nil)
         @bundles = bundles
+        @corpus = corpus
         @terms = Array(terms).reject { |term| OKF.blank?(term) }.map(&:to_s)
         @fields = fields.nil? || fields.empty? ? FIELDS : fields
         @regexp = regexp
@@ -202,7 +279,7 @@ module OKF
       end
 
       # Ranked match rows, catalog-style identity plus where the terms hit:
-      # [{ slug:, id:, title:, type:, area:, tags:, matched: [field, …], score:, snippet: }, …]
+      # [{ slug:, id:, title:, type:, dir:, area:, tags:, matched: [field, …], score:, snippet: }, …]
       # ordered by score descending, then slug, then id. `slug` is present only
       # when searching across bundles. No terms means no matches.
       def results
@@ -242,6 +319,7 @@ module OKF
       # what it can act on, so there is nothing left for it to ignore.
       def engine_options(chosen)
         options = { fields: @fields }
+        options[:prepared] = @corpus.index_for(chosen) if @corpus
         ROUTABLE.each do |capability|
           options[capability] = requested[capability] if chosen.capabilities.include?(capability)
         end
@@ -255,6 +333,13 @@ module OKF
       # Every concept as an indexable document, keyed uniquely across bundles.
       # @sources keeps the way back, so the index stores no fields of its own.
       def documents
+        # The corpus already walked every concept and kept the map that turns a
+        # hit back into a row; taking its sources is what makes that reuse whole.
+        if @corpus
+          @sources = @corpus.sources
+          return @corpus.documents
+        end
+
         docs = []
         @bundles.each do |slug, bundle|
           bundle.concepts.each do |concept|
@@ -269,14 +354,7 @@ module OKF
       # { field => original-case text } for every searchable field. The index reads
       # all of them; `fields:` narrows the search, not the document.
       def field_texts(concept)
-        {
-          "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
-        }
+        Search.field_texts(concept)
       end
 
       # `slug` leads the row so a merged result reads bundle-first, and drops
@@ -288,6 +366,7 @@ module OKF
           id: concept.id,
           title: (concept.title || concept.id).to_s,
           type: concept.type.to_s,
+          dir: OKF.dir_of(concept.id),
           area: area_of(concept.id),
           tags: Array(concept.tags).map(&:to_s),
           matched: matched,
@@ -342,7 +421,8 @@ module OKF
         end
       end
 
-      # A concept's top-level area, mirroring the catalog's definition.
+      # A concept's top-level area, mirroring the catalog's definition. Deprecated
+      # in favour of OKF.dir_of, which keeps the levels this one throws away.
       def area_of(id)
         id.include?("/") ? id.split("/").first : "(root)"
       end

data/lib/okf/bundle.rb

@@ -118,7 +118,7 @@ module OKF
           timestamp: concept.timestamp&.to_s,
           status: concept.frontmatter["status"]&.to_s,
           backlog_ref: concept.frontmatter["backlog_ref"]&.to_s,
-          dir: File.dirname("#{id}.md"),
+          dir: OKF.dir_of(id),
           area: area_of(id),
           links_out: out_degree[id],
           links_in: in_degree[id]

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] [--area A] [--tag T] [--json]"
+          o.banner = "Usage: okf catalog <dir|@slug> [--type T] [--dir D] [--tag 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

@@ -118,13 +118,15 @@ module OKF
       # reproduced on the CLI so an agent can read the same knowledge without one.
       # Each prints a scannable human view by default and machine JSON with --json;
       # all are advisory reads (exit 0). They share OKF::Bundle#catalog for their data,
-      # and (with `types`) narrow through the same --type/--area/--tag filters the
+      # and (with `types`) narrow through the same --type/--dir/--tag filters the
       # server UI offers, so browser and CLI can answer the same questions.
       #
-      # ── their shared --type/--area/--tag narrowing ──
+      # ── their shared --type/--dir/--tag narrowing ──
       # Each view takes the filters orthogonal to it (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).
+      # Matching is case-insensitive; --type and --tag are exact, --dir is a prefix
+      # over the whole path (see #under_dir?). The bundle root is `.`, spellable
+      # `root` so no shell quoting is needed. --area is --dir's deprecated
+      # predecessor and keeps its old first-segment-only behavior.
 
       # The shared back half of `tags` and `types`: load, narrow, print.
       def print_inverted_index(dir, label, key, plural, options)
@@ -177,7 +179,14 @@ module OKF
 
       def filter_flags(parser, options, *keys)
         parser.on("--type TYPE", "only concepts of this type") { |v| options[:type] = v } if keys.include?(:type)
-        parser.on("--area AREA", "only concepts in this top-level area") { |v| options[:area] = v } if keys.include?(:area)
+        if keys.include?(:area)
+          parser.on("--dir PATH", "only concepts in this directory or below it",
+            "(`root` — or `.` — for the bundle root)") { |v| options[:dir] = v }
+          parser.on("--area AREA", "deprecated: use --dir (matches the first path segment only)") do |v|
+            options[:area] = v
+            deprecated("--area", "--dir")
+          end
+        end
         parser.on("--tag TAG", "only concepts carrying this tag") { |v| options[:tag] = v } if keys.include?(:tag)
       end
 
@@ -185,19 +194,172 @@ module OKF
         entries.select do |entry|
           (options[:type].nil? || fold(entry[:type]) == fold(options[:type])) &&
             (options[:area].nil? || fold(entry[:area]) == fold_area(options[:area])) &&
+            (options[:dir].nil? || under_dir?(entry[:dir], options[:dir])) &&
             (options[:tag].nil? || entry[:tags].any? { |tag| fold(tag) == fold(options[:tag]) })
         end
       end
 
+      # The one rule --dir is built on: a dir names itself and everything beneath
+      # it. `--dir foo` reaches foo/bar, `--dir foo/bar` narrows, and `--dir .`
+      # needs no special case at all — nothing starts with "./", so the root
+      # selects only what lives directly in it.
+      def under_dir?(entry_dir, wanted)
+        entry = fold(entry_dir)
+        path = fold_dir(wanted)
+        entry == path || entry.start_with?("#{path}/")
+      end
+
       def fold(value)
         value.to_s.downcase
       end
 
       def fold_area(value)
-        folded = fold(value)
+        folded = trim_slash(fold(value))
         folded == "root" ? "(root)" : folded
       end
 
+      # `.` is the stored spelling of the root everywhere; `root` is the one a
+      # shell needs no quoting for, and the only reason the two exist.
+      def fold_dir(value)
+        folded = trim_slash(fold(value))
+        folded.empty? || folded == "root" ? "." : folded
+      end
+
+      # The human views print a directory with the slash that says it is one —
+      # `tables/`, `docs/api/` — so the flag has to accept the label the CLI
+      # itself just printed. Without this, pasting a row back into --dir matched
+      # nothing and exited 0: an empty answer that reads like a real one.
+      def trim_slash(value)
+        value.sub(%r{/+\z}, "")
+      end
+
+      # The inverse of fold_dir: `.` is the stored spelling of the root and
+      # "(root)" the human one, and every grouped view keeps that split so a
+      # table and its --json never disagree about which spelling is the data.
+      # `slash:` adds the trailing slash the listing views use to say "directory"
+      # — the same one fold_dir now accepts back.
+      def dir_label(dir, slash: false)
+        return "(root)" if [ ".", "(root)" ].include?(dir)
+
+        slash ? "#{dir}/" : dir
+      end
+
+      # How many path segments deep a directory sits. The root is 0.
+      def dir_depth(dir)
+        dir == "." ? 0 : dir.count("/") + 1
+      end
+
+      # --depth N: how many directory levels below the *starting point* to keep,
+      # where the starting point is each --dir when one is given and the bundle
+      # root otherwise. Relative rather than absolute on purpose: `--dir a/b
+      # --depth 1` reads "a/b and one level under it" without the caller first
+      # working out how deep a/b already is — and the two flags then compose the
+      # way a reader descending a tree actually moves.
+      def depth_flag(parser, options)
+        parser.on("--depth N", "keep only this many directory levels below the",
+          "starting point (--dir when given, else the bundle root)") { |v| options[:depth] = v }
+      end
+
+      # Checked here rather than with OptionParser's Integer coercion, which
+      # accepts "-1" and "0x2" and reports in its own words. Returns the exit
+      # status to hand back, or nil when the value is fine.
+      def depth_error(options)
+        raw = options[:depth]
+        return nil if raw.nil? || raw.to_s =~ /\A\d+\z/
+
+        usage_error("--depth takes a whole number of levels (got #{raw.inspect})")
+      end
+
+      # The chain from the bundle root down to each --dir, so a branch is never
+      # shown adrift. On by default in the *directory* views (`index`, `dirs`):
+      # the map's job there is orientation, and a subtree printed with nothing
+      # above it has dropped the authored context that says what it is — the root
+      # index.md's prose first among it. Off with --no-ancestors, which restores
+      # the subtree alone.
+      #
+      # Deliberately not offered on the concept filters (search/catalog/files/…):
+      # there --dir narrows *concepts*, and a concept in `a/` is simply not in
+      # `a/b`. Same flag, one meaning, because it is asked about two different
+      # kinds of row.
+      def ancestors_flag(parser, options)
+        parser.on("--[no-]ancestors", "with --dir, also show the chain up to the root",
+          "so the branch is placed (default: yes)") { |v| options[:ancestors] = v }
+      end
+
+      # Every proper ancestor of each --dir, root included. Empty unless --dir
+      # named something below the root: with no --dir the whole bundle is already
+      # the starting point, and `--dir .` has nothing above it.
+      #
+      # `known` is the map's own directory list, and a base outside it contributes
+      # no chain. Without that check `--dir typo` came back with the root — a
+      # chain to a place that does not exist, which reads as a partial answer to
+      # a query that in fact matched nothing.
+      #
+      # The deprecated --area gains no chain either: it is exact, and a deprecated
+      # flag that quietly answers with more than it used to is worse than one that
+      # is merely old.
+      # Matching folds case, but a row is found by its *stored* spelling, so the
+      # chain is walked folded and handed back in the map's own words. Returning
+      # the folded string instead dropped every ancestor a bundle spelled with a
+      # capital — the rows are selected with `include?`, which does not fold.
+      def ancestor_dirs(options, known)
+        return [] unless options[:ancestors]
+
+        stored = known.each_with_object({}) { |dir, out| out[fold(dir)] = dir }
+        Array(options[:dirs]).each_with_object([]) do |path, out|
+          base = fold_dir(path)
+          next unless stored.key?(base)
+
+          current = dir_parent(base)
+          while current
+            out << stored.fetch(current, current)
+            current = dir_parent(current)
+          end
+        end.uniq
+      end
+
+      # nil above the root, so the walk above terminates on it rather than on ".".
+      def dir_parent(dir)
+        return nil if dir == "."
+
+        slash = dir.rindex("/")
+        slash ? dir[0, slash] : "."
+      end
+
+      # The directories a --dir/--depth pair selects, out of the map's own
+      # ordered list. Neither flag given keeps everything — these narrow a view,
+      # they do not define one. The ancestor chain is unioned on top by the
+      # caller, which is also what tells a row apart from context.
+      def select_dirs(dirs, options)
+        bases = Array(options[:dirs]).map { |path| fold_dir(path) }
+        depth = options[:depth]&.to_i
+        return dirs if bases.empty? && depth.nil?
+        # No --dir means the whole bundle is the starting point, which is *not*
+        # `--dir .`: that one selects the root alone, by the same prefix rule
+        # everything else here uses.
+        return dirs.select { |dir| dir_depth(dir) <= depth } if bases.empty?
+
+        dirs.select do |dir|
+          bases.any? do |base|
+            # --depth bounds the *descent*; the chain above is the ascent, and the
+            # two are separate axes. That is what keeps `--depth 0` meaning "the
+            # named directory alone" even while its chain is printed with it.
+            under_dir?(dir, base) && (depth.nil? || dir_depth(dir) - dir_depth(base) <= depth)
+          end
+        end
+      end
+
+      # A deprecated spelling still does what it always did — never silently
+      # something else — and says so once per run, on stderr so a --json
+      # consumer's stdout stays a clean machine substrate.
+      def deprecated(what, instead)
+        @deprecated ||= {}
+        return if @deprecated[what]
+
+        @deprecated[what] = true
+        @err.puts "warning: #{what} is deprecated, use #{instead}"
+      end
+
       # Turn an inverted index ({ value => [id, …] }) into display rows ordered by
       # count, narrowed to the concepts the active filters select; rows the narrowing
       # empties drop. With no filters the index passes through whole.
@@ -212,7 +374,7 @@ module OKF
       # The ids the filters select, resolved through the catalog metadata — or nil
       # when no filter is active, meaning keep everything.
       def filter_ids(folder, options)
-        return nil if options[:type].nil? && options[:area].nil? && options[:tag].nil?
+        return nil if options[:type].nil? && options[:area].nil? && options[:dir].nil? && options[:tag].nil?
 
         filter_entries(folder.catalog, options).map { |entry| entry[:id] }
       end

data/lib/okf/cli/dirs.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The bundle's directories — its clusters — and how many concepts live
+    # directly in each. The shape view: `index` reads a directory's contents,
+    # `dirs` reads the layout they hang off, which is the question `--dir` is
+    # answered against.
+    #
+    # `count` is *direct*, never cumulative: a dir's number is what lives in it,
+    # so the column sums to the bundle's concept count and an empty intermediate
+    # dir reads as the zero it is. `subtree` is the other half of that honesty —
+    # what `--dir <that row>` would return — because a direct count alone cannot
+    # say where the mass is once `--depth` truncates the listing: on a deep
+    # bundle the top-level rows are then all zeroes.
+    #
+    # Presentation only — every number comes off Bundle#directory_index, the same
+    # source `okf index` and the server's Index panel read. Advisory: exit 0.
+    class Dirs < Command
+      def self.id
+        :dirs
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "dirs      <dir|@slug> [--json] [--dir D] [--depth N]", "list the bundle's dirs (clusters) and their concept counts" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false, dirs: nil, depth: nil, ancestors: true }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf dirs <dir|@slug> [--dir PATH] [--depth N] [--json]"
+          json_flags(o, options, "emit the dirs as JSON")
+          projection_flags(o, options)
+          o.on("--dir PATH", "only this directory and the ones below it",
+            "(repeatable; `root` for the bundle root)") { |v| (options[:dirs] ||= []) << v }
+          depth_flag(o, options)
+          ancestors_flag(o, options)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+        bad_depth = depth_error(options)
+        return bad_depth if bad_depth
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        rows = select_rows(folder.directory_index, options)
+        return emit_list_json(dir, "dirs", rows, options, "total" => total(rows)) if options[:json]
+
+        print_dirs(dir, rows)
+        0
+      end
+
+      private
+
+      # The subtree counts come off the *whole* map, before any narrowing — a
+      # truncated view still has to report the real weight hanging below a row,
+      # which is the only reason the column exists.
+      def select_rows(entries, options)
+        subtree = subtree_counts(entries)
+        all_dirs = entries.map { |entry| entry[:dir] }
+        wanted = select_dirs(all_dirs, options)
+        chain = ancestor_dirs(options, all_dirs) - wanted
+        entries.select { |entry| wanted.include?(entry[:dir]) || chain.include?(entry[:dir]) }.map do |entry|
+          { "dir" => entry[:dir], "ancestor" => chain.include?(entry[:dir]), "count" => entry[:count],
+            "subtree" => subtree[entry[:dir]], "subdirs" => entry[:subdirs] }
+        end
+      end
+
+      # Per dir, the concepts at or below it — defined as exactly what `--dir` on
+      # that row selects, so the number on the row and the flag can never
+      # disagree. Which is also why the root's subtree is its own direct count:
+      # `.` is a prefix of nothing, the same rule `--dir .` is built on.
+      def subtree_counts(entries)
+        entries.each_with_object({}) do |entry, out|
+          out[entry[:dir]] = entries.reduce(0) do |sum, other|
+            under_dir?(other[:dir], entry[:dir]) ? sum + other[:count] : sum
+          end
+        end
+      end
+
+      # The chain is context, not the answer, so it stays out of the total —
+      # which is what keeps a row's `subtree` equal to the total `--dir` on that
+      # row returns. `count` in the envelope is rows printed, chain included,
+      # because that is what it has always meant: how many rows came back.
+      def total(rows)
+        rows.reject { |row| row["ancestor"] }.map { |row| row["count"] }.reduce(0, :+)
+      end
+
+      def print_dirs(dir, rows)
+        @out.puts "Dirs — #{bundle_label(dir)}"
+        @out.puts
+        labels = rows.map { |row| "#{"↑ " if row["ancestor"]}#{dir_label(row["dir"])}" }
+        # The second column earns its place only where a dir actually nests. On a
+        # flat bundle it would repeat the first one down the page.
+        nested = rows.any? { |row| row["subtree"] != row["count"] }
+        unless rows.empty?
+          width = [ 3, *labels.map(&:length) ].max
+          @out.puts "  #{"Dir".ljust(width)}  Concepts#{"   Subtree" if nested}"
+          rows.each_with_index do |row, i|
+            line = "  #{labels[i].ljust(width)}  #{row["count"].to_s.rjust(8)}"
+            line += "   #{row["subtree"].to_s.rjust(7)}" if nested
+            @out.puts line
+          end
+          @out.puts
+        end
+        @out.puts "  #{rows.size} #{pluralize(rows.size, "dir")} · #{total(rows)} #{pluralize(total(rows), "concept")}"
+      end
+    end
+
+    register(Dirs)
+  end
+end

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] [--area A] [--tag T] [--json]"
+          o.banner = "Usage: okf files <dir|@slug> [--type T] [--dir D] [--tag T] [--json]"
           json_flags(o, options, "emit the file tree as JSON")
           projection_flags(o, options)
           filter_flags(o, options, :type, :area, :tag)
@@ -47,7 +47,7 @@ module OKF
         entries.group_by { |entry| entry[:dir] }.sort_by(&:first).each do |folder, group|
           width = group.map { |entry| File.basename("#{entry[:id]}.md").length }.max
           @out.puts
-          @out.puts "  #{folder == "." ? "(root)" : "#{folder}/"}"
+          @out.puts "  #{dir_label(folder, slash: true)}"
           group.each do |entry|
             @out.puts "    #{File.basename("#{entry[:id]}.md").ljust(width)}  #{entry[:title]}"
           end