okf 1.7.0 → 1.9.0

data/lib/okf/cli.rb

@@ -10,6 +10,10 @@ module OKF
   #
   # Exit codes: 0 success, 1 non-conformant / failing bundle, 2 usage error.
   class CLI
+    # The `registry` umbrella's subcommands — the dispatch, and the words a
+    # flag-first invocation is checked against.
+    SUBCOMMANDS = %w[set del list default rename].freeze
+
     # Lint findings grouped for display, in category order.
     LINT_CATEGORIES = {
       "Reachability" => %i[orphan not_in_index disconnected_component unlinked],
@@ -42,38 +46,88 @@ module OKF
 
     def run(argv)
       argv = argv.dup
-      case (command = argv.shift)
-      when "graph" then graph(argv)
-      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)
-      when "tags" then tags(argv)
-      when "types" then types(argv)
-      when "stats" then stats(argv)
-      when "server" then server(argv)
-      when "render" then render(argv)
-      when "skill" then skill(argv)
-      when "version", "--version", "-v" then @out.puts(OKF::VERSION); 0
-      when "help", "--help", "-h" then usage(@out); 0
-      when nil then usage(@err); 2
-      else
-        @err.puts "okf: unknown command '#{command}'"
-        usage(@err)
-        2
+      # Per-run state, reset so a reused instance never inherits the last run's
+      # answer: the ref→slug memo, and the --pretty a previous argv turned on.
+      @ref_slugs = {}
+      @pretty = false
+      # -h/--help is answered wherever a parser sees it — deep inside
+      # positional_dir, where returning would only mean "usage error, exit 2".
+      # Thrown here instead, so help keeps the contract every other path keeps:
+      # a status this method returns. See #help_flag.
+      catch(:help) do
+        case (command = argv.shift)
+        when "graph" then graph(argv)
+        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)
+        when "tags" then tags(argv)
+        when "types" then types(argv)
+        when "stats" then stats(argv)
+        when "server" then server(argv)
+        when "render" then render(argv)
+        when "registry" then registry(argv)
+        when "skill" then skill(argv)
+        when "version", "--version", "-v" then @out.puts(OKF::VERSION); 0
+        when "help", "--help", "-h" then usage(@out); 0
+        when nil then usage(@err); 2
+        else
+          @err.puts "okf: unknown command '#{command}'"
+          usage(@err)
+          2
+        end
       end
     end
 
+    # "every registered bundle" as a ref, in its canonical spelling — what the
+    # messages say, and (normalized) what #all_ref? recognizes. Only `search`
+    # expands it: it is the one verb that merges across bundles, so it is the one
+    # verb for which "all" names something it can answer about. See
+    # resolve_registered for why the others refuse it outright rather than
+    # treating it as an unknown slug. Its slug half is reserved by
+    # Registry::RESERVED_SLUGS so no bundle can answer to it; a test pins the two
+    # together.
+    ALL_REF = "@all"
+
+    # The core raises `:regexp`; a user typed `--regexp`. Translating here keeps
+    # the flag vocabulary in the shell, where it belongs, and lets the message end
+    # with the fix rather than only the complaint: an engine that *can* do what was
+    # asked is named, so the next command is obvious.
+    CAPABILITY_FLAGS = { regexp: "--regexp", fuzzy: "--fuzzy" }.freeze
+
+    # The row shape each list view emits, so `--fields`/`--except` can be checked
+    # against a name even when the result is empty. Without it the typo guard
+    # keyed off the data: `--fields bogus` was a usage error against a bundle
+    # with matches and silently fine against one without, which made a typo's
+    # fate depend on whether a filter happened to match. A test asserts each
+    # view's real rows carry exactly these, so the two cannot drift.
+    # Declared in emission order, so the "available:" list a typo prints reads
+    # the same as the rows themselves.
+    ROW_FIELDS = {
+      "matches" => %w[id title type area tags matched score snippet],
+      # Registry mode labels every row with the bundle it came from; a plain-dir
+      # search has one bundle and no slug to carry. Two shapes, because the typo
+      # guard checks against the *declared* one — a single shape covering both
+      # would let `--fields slug` pass on a search whose rows have none, and hand
+      # back an empty object per match under a count that says otherwise.
+      "matches_by_ref" => %w[slug id title type area tags matched score snippet],
+      "concepts" => %w[id title type description tags timestamp status backlog_ref dir area links_out links_in],
+      "files" => %w[path id dir type title description],
+      "directories" => %w[dir index_path present synthesized count types tags subdirs body listing],
+      "bundles" => %w[slug title dir mount default missing]
+    }.freeze
+
     private
 
     def validate(argv)
       options = { json: false }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf validate <bundle-dir> [--json]"
+        o.banner = "Usage: okf validate <dir|@slug> [--json]"
         json_flags(o, options, "emit a JSON report")
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -85,13 +139,14 @@ module OKF
     def lint(argv)
       options = { json: false, min_body: OKF::Bundle::Linter::DEFAULT_MIN_BODY, stale_after: nil, only: nil, except: nil, fail_on: :never }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf lint <bundle-dir> [--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] [--only a,b] [--except a,b] [--fail-on 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("--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 }
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -121,8 +176,9 @@ module OKF
     def loose(argv)
       options = { json: false }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf loose <bundle-dir> [--json]"
+        o.banner = "Usage: okf loose <dir|@slug> [--json]"
         json_flags(o, options, "emit the loose files as JSON")
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -133,36 +189,80 @@ 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.
+    # Ranked text retrieval — the browser page's search brought to the CLI on the
+    # same engine (a MiniFTS index) and extended to bodies. Terms after the
+    # directory are ANDed tokens, matched whole or by prefix (Ruby regexps with
+    # --regexp, typo tolerance with --fuzzy); rows rank by BM25+ weighted toward
+    # 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. Exact by default —
+    # the consuming agent is the fuzzy layer, until it asks not to be.
     def search(argv)
-      options = { json: false, regexp: false }
+      options = { json: false, regexp: false, fuzzy: false, engine: nil }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf search <bundle-dir> <term> [term ...] [--regexp] [--in FIELDS] [--type T] [--area A] [--tag T] [--json]"
+        o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] [--in FIELDS] [--type T] [--area A] [--tag T] [--json]"
+        search_engine_note(o)
         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("-e", "--regexp", "read each term as a Ruby regular expression rather",
+          "than literal text — case-insensitive (scan engine)") { options[:regexp] = true }
+        o.on("--fuzzy",
+          "tolerate typos, edit distance #{OKF::Bundle::Search::FUZZY_DISTANCE} × term length (index engine)") { options[:fuzzy] = true }
+        o.on("--engine NAME", "match with this engine instead of the default",
+          "(#{engine_names}) — index is BM25+ ranked, token-based") { |v| options[:engine] = v }
         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)
+        help_flag(o)
       end
-      dir = positional_dir(parser, argv) or return 2
+      begin
+        parser.parse!(argv)
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        return 2
+      end
+
+      # Registry mode — leading @refs, @all among them — searches several bundles
+      # and labels every match; a plain dir keeps the classic single-bundle output.
+      if argv.first&.start_with?("@")
+        pairs = ref_targets(argv) or return 2
+        dir = nil
+      else
+        dir = argv.shift
+        if dir.nil?
+          @err.puts parser.banner
+          return 2
+        end
+        dir = resolve_ref(dir) or return 2
+      end
+
       terms = argv
       if terms.empty?
         @err.puts parser.banner
         return 2
       end
 
+      # A non-leading @arg is a literal term by the grammar — say so, since the
+      # user may have meant a ref (refs must lead) and would otherwise see only
+      # a silent zero-match.
+      stray = terms.find { |term| term.start_with?("@") }
+      @err.puts "note: '#{stray}' searches as a literal term — an @slug or @all must lead" if stray
+
       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?
 
+      # Two query languages, not two dials on one: a regexp is matched against raw
+      # text, --fuzzy is an edit distance over indexed tokens. Silently honouring
+      # one and dropping the other would answer a question nobody asked.
+      if options[:regexp] && options[:fuzzy]
+        return usage_error("--regexp and --fuzzy are mutually exclusive (a pattern is matched literally, not by edit distance)")
+      end
+
+      return multi_search(pairs, terms, options) if pairs
+
       folder = OKF::Bundle::Folder.load(dir)
       report_skipped(folder)
-      rows = OKF::Bundle::Search.call(folder.bundle, terms, fields: options[:in], regexp: options[:regexp])
+      rows = OKF::Bundle::Search.call(folder.bundle, terms, fields: options[:in], regexp: options[:regexp],
+        fuzzy: options[:fuzzy], engine: options[:engine])
       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]
@@ -171,10 +271,115 @@ module OKF
       0
     rescue RegexpError => e
       usage_error("invalid pattern: #{e.message}")
+    rescue OKF::Bundle::Search::UnknownEngine => e
+      usage_error(e.message)
+    rescue OKF::Bundle::Search::UnsupportedQuery => e
+      usage_error(unsupported_query_message(e))
+    end
+
+    # Every registered bundle, as [slug, dir] pairs — what @all expands to.
+    # Asking for everything tolerates gaps: a registered directory that has since
+    # vanished is skipped with a note, the same forgiveness the hub shows a stale
+    # entry. Naming one bundle demands it, so a plain @slug still fails hard.
+    def all_targets
+      registry = load_registry
+      return nil unless registry
+
+      if registry.empty?
+        @err.puts "error: no bundles registered (okf registry set <dir>)"
+        return nil
+      end
+      pairs = []
+      registry.each do |entry|
+        if File.directory?(entry.path)
+          pairs << [ entry.slug, entry.path ]
+        else
+          skip_registered(entry)
+        end
+      end
+      if pairs.empty?
+        @err.puts "error: every registered bundle is missing on disk (okf registry list)"
+        return nil
+      end
+      pairs
+    end
+
+    # Dedupe by resolved path, not ref spelling — `@ @one` is one bundle when
+    # "one" is the default, and must be searched once. `@all @one` is the same
+    # story with a wider first ref: all ⊇ one, so the result is right and the
+    # duplicate simply drops. No error branch, because there is no wrong answer
+    # to warn about.
+    def ref_targets(argv)
+      refs = []
+      refs << argv.shift while argv.first&.start_with?("@")
+      pairs = []
+      refs.each do |ref|
+        found = all_ref?(ref) ? all_targets : ref_pair(ref)
+        return nil unless found
+
+        found.each { |slug, path| pairs << [ slug, path ] unless pairs.any? { |_, seen| seen == path } }
+      end
+      pairs
+    end
+
+    # Does this @ref name every registered bundle? Takes a ref, sigil and all —
+    # both callers reach it only past a start_with?("@") of their own, so a
+    # third check here would be a branch no run can take.
+    #
+    # Compared *normalized*, because the ref grammar has exactly one
+    # normalization and a ref exempt from it is a trapdoor: `@ALL` has to reach
+    # `@all` for the same reason `@One` reaches the bundle registered from dir
+    # `One`. It normalizes through Registry.normalize — the very call the slug
+    # lookup makes — rather than a second downcase that could be forgotten while
+    # the first was maintained.
+    def all_ref?(ref)
+      require "okf/registry"
+      OKF::Registry.normalize(ref[1..-1]) == ALL_REF[1..-1]
+    end
+
+    # One @ref as a single-element [[slug, dir]], or nil after reporting.
+    def ref_pair(ref)
+      path = resolve_registered(ref)
+      unless path
+        # Only an unknown slug is plausibly a mistyped term — a broken registry
+        # or a gone directory has nothing to do with the grammar.
+        @err.puts "note: searching for a literal @-term? put a non-@ term first, or use -e '\\@term'" if @ref_failure == :unknown
+        return nil
+      end
+      [ [ ref_slugs[path], path ] ]
+    end
+
+    # Search every bundle at once and merge the rankings, each row labeled with
+    # its bundle's slug. The bundles go in as *one* corpus rather than one search
+    # each: BM25 weighs a term by how rare it is, so ranking each bundle on its own
+    # statistics and then interleaving the lists would let the same match score
+    # differently for no reason a reader could see. One index, one ranking.
+    #
+    # Filters stay per-bundle — they are per-folder questions — so they apply to
+    # the merged rows by (slug, id) afterwards.
+    def multi_search(pairs, terms, options)
+      bundles = []
+      keeps = {}
+      total = 0
+      pairs.each do |slug, dir|
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        total += folder.bundle.concepts.size
+        bundles << [ slug, folder.bundle ]
+        keep = filter_ids(folder, options)
+        keeps[slug] = keep unless keep.nil?
+      end
+      rows = OKF::Bundle::Search.across(bundles, terms, fields: options[:in], regexp: options[:regexp],
+        fuzzy: options[:fuzzy], engine: options[:engine])
+      rows = rows.select { |row| !keeps.key?(row[:slug]) || keeps[row[:slug]].include?(row[:id]) }
+      return print_multi_search_json(pairs, terms, rows, options) if options[:json]
+
+      print_multi_search(pairs, terms, rows, total)
+      0
     end
 
     def print_search(dir, terms, rows, total)
-      @out.puts "Search — #{dir} · #{terms.join(" ")} (#{counted(rows.size, total, "concepts")})"
+      @out.puts "Search — #{bundle_label(dir)} · #{terms.join(" ")} (#{counted(rows.size, total, "concept")})"
       if rows.empty?
         @out.puts "  no matches — fewer or broader terms, or scan `okf tags #{dir}` for the vocabulary"
         return
@@ -192,71 +397,416 @@ module OKF
       emit_list_json(dir, "matches", rows.map { |row| stringify(row) }, options, "query" => terms)
     end
 
+    def print_multi_search(pairs, terms, rows, total)
+      @out.puts "Search — #{pairs.map { |slug, _| "@#{slug}" }.join(" ")} · #{terms.join(" ")} (#{counted(rows.size, total, "concept")})"
+      if rows.empty?
+        @out.puts "  no matches — fewer or broader terms, or scan `okf tags @<slug>` for a bundle's vocabulary"
+        return
+      end
+
+      slug_width = rows.map { |row| row[:slug].length }.max + 1
+      width = rows.map { |row| row[:id].length }.max
+      rows.each do |row|
+        @out.puts
+        @out.puts "  #{"@#{row[:slug]}".ljust(slug_width)}  #{row[:id].ljust(width)}  #{row[:title]}  ·  #{row[:type]}  ·  #{row[:matched].join("+")}"
+        @out.puts "    #{truncate(row[:snippet], 100)}" unless row[:snippet].empty?
+      end
+    end
+
+    # The head maps every searched slug to its directory once, so a row's
+    # `slug` resolves to `<dir>/<id>.md` without a second lookup — and without
+    # repeating a long path on every row.
+    def print_multi_search_json(pairs, terms, rows, options)
+      head = { "bundles" => pairs.map { |slug, dir| { "slug" => slug, "dir" => dir } } }
+      emit_list_json(head, "matches", rows.map { |row| stringify(row) }, options, { "query" => terms }, "matches_by_ref")
+    end
+
     def server(argv)
       require "okf/server/app"
       require "rack/deflater"
 
       options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose" }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf server <bundle-dir> [-p PORT] [--bind ADDR] [--layout NAME] [-t title] [-l url]"
+        o.banner = "Usage: okf server [DIR|@slug…] [-p PORT] [--bind ADDR] [--layout NAME] [-t title] [-l url]"
         o.on("-p", "--port PORT", Integer, "port to serve on (default #{options[:port]})") { |v| options[:port] = v }
         o.on("--bind ADDR", "address to bind (default #{options[:bind]})") { |v| options[:bind] = v }
-        o.on("-t", "--title TITLE", "graph title (default: parent/bundle dir name)") { |v| options[:title] = v }
-        o.on("-l", "--link URL", "source URL shown in the header") { |v| options[:link] = v }
-        o.on("--layout NAME", OKF::Server::Graph::LAYOUTS, "initial layout (#{OKF::Server::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+        o.on("-t", "--title TITLE", "graph title, single bundle only (default: parent/bundle dir name)") { |v| options[:title] = v }
+        o.on("-l", "--link URL", "source URL shown in the header, single bundle only") { |v| options[:link] = v }
+        o.on("--layout NAME", OKF::Render::Graph::LAYOUTS, "initial layout (#{OKF::Render::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+        help_flag(o)
       end
-      dir = positional_dir(parser, argv) or return 2
+      dirs = positional_dirs(parser, argv) or return 2
 
-      folder = OKF::Bundle::Folder.load(dir)
-      report_skipped(folder)
-      run_server(folder, options)
+      # A flag that will have no effect in this mode gets a note, not silence.
+      @err.puts "note: --title/--link apply to a single-bundle server; ignored" if dirs.size != 1 && (options[:title] || options[:link])
+
+      # One dir keeps the historical single-bundle server at `/`; zero (the
+      # persistent registry) or many (ephemeral) fan out behind a hub.
+      if dirs.size == 1
+        folder = OKF::Bundle::Folder.load(dirs.first)
+        report_skipped(folder)
+        run_server(folder, options)
+      else
+        run_hub(dirs, options)
+      end
       0
+    rescue OKF::Error => e
+      usage_error(e.message)
     end
 
-    # Build the Rack app and hand it to the runner (WEBrick by default, injected so
-    # tests drive this without a socket).
+    # Build the single-bundle Rack app and hand it to the runner (WEBrick by
+    # default, injected so tests drive this without a socket).
     def run_server(folder, options)
       app = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link], layout: options[:layout])
-      app = Rack::Deflater.new(app) # gzip responses when the client accepts it — transparent, no new dependency
-      @out.puts "serving #{folder.graph.nodes.size} concepts at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"
-      @runner.call(app, options[:bind], options[:port])
+      # minimal: the banner wants a count, not bodies — and Folder#graph is not
+      # memoized, so a full build here parses every concept a second time (the
+      # App builds its own) purely to print one number.
+      count = folder.graph(minimal: true).nodes.size
+      @out.puts "serving #{count} #{pluralize(count, "concept")} at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"
+      serve(app, options)
+    end
+
+    # Build the multi-bundle hub and hand it to the runner. With dirs it serves
+    # those ephemerally; with none it serves the persistent registry. Either way
+    # the first bundle is the one `/` opens — for the registry that is its own
+    # order, and a first entry whose directory has vanished drops out here, so
+    # `/` lands on the next one that is actually there.
+    def run_hub(dirs, options)
+      require "okf/server/hub"
+      require "okf/registry"
+      if dirs.empty?
+        # A malformed registry raises OKF::Error, which `server` rescues into a
+        # usage error — no guarded load needed on this path.
+        reg = OKF::Registry.load
+        bundles = reg.map { |entry| load_registered(entry) }.compact
+      else
+        bundles = ephemeral_bundles(dirs)
+      end
+      hub = OKF::Server::Hub.new(bundles, layout: options[:layout])
+      concepts = bundles.inject(0) { |sum, bundle| sum + bundle.folder.graph(minimal: true).nodes.size }
+      @out.puts "serving #{bundles.size} #{pluralize(bundles.size,
+        "bundle")}, #{concepts} #{pluralize(concepts, "concept")} at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"
+      print_mounts(hub)
+      serve(hub, options)
+    end
+
+    # The one boot seam every served app passes through, so a hub gzips exactly
+    # like a single bundle — the wrap belongs to booting a server, not to either
+    # mode, and a mode added later gets it for free. Deliberately not inside the
+    # runner: an embedding app mounting OKF::Server::App brings its own middleware.
+    def serve(app, options)
+      # gzip responses when the client accepts it — transparent, no new dependency
+      @runner.call(Rack::Deflater.new(app), options[:bind], options[:port])
+    end
+
+    # The mount table — which dir landed on which /b/<slug>/ and where `/` goes.
+    # Mirrors the Hub's own default resolution (explicit slug, else first).
+    # Ask the hub which bundle it chose rather than re-deriving the
+    # explicit-else-first rule, and mount at its own prefix: two copies of a
+    # rule is two answers waiting to disagree.
+    def print_mounts(hub)
+      hub.bundles.each do |bundle|
+        marker = bundle.equal?(hub.default) ? "*" : " "
+        @out.puts "  #{marker} #{OKF::Server::Hub::MOUNT}/#{bundle.slug}/  #{bundle.title}"
+      end
+    end
+
+    # Load the given directories as unregistered bundles, slugged by basename and
+    # deduped within the run. The same directory listed twice mounts once — two
+    # windows on one bundle would just burn a slug on a URL that vanishes next run.
+    def ephemeral_bundles(dirs)
+      roots = []
+      dirs.each do |dir|
+        root = File.expand_path(dir)
+        roots << root unless roots.include?(root)
+      end
+
+      # A registered slug owns its mount outright: reserve every ref's slug
+      # before any basename is deduped. Otherwise argv order decides, and
+      # `server ./two @two` mounts the *unregistered* ./two at /b/two/ while
+      # pushing the ref — the bundle whose slug that is — to /b/two-2/, so a
+      # bookmark from a bundle-less run silently opens the wrong graph.
+      taken = roots.map { |root| ref_slugs[root] }.compact
+      roots.each_with_object([]) do |root, bundles|
+        folder = OKF::Bundle::Folder.load(root)
+        report_skipped(folder)
+        slug = ref_slugs[root]
+        unless slug
+          slug = OKF::Registry.dedupe(File.basename(root), taken)
+          taken << slug
+        end
+        bundles << OKF::Server::Hub::Bundle.new(slug, folder, folder.name)
+      end
+    end
+
+    # Load one registered bundle; a path that has gone missing or no longer reads
+    # drops to nil with a note (to stderr) rather than sinking the whole run. The
+    # directory check is explicit — the Reader maps a nonexistent directory to an
+    # empty bundle, so nothing would raise for the common "dir was deleted" case.
+    # Method-level rescue (not a `do…end`-block rescue — a 2.6 feature).
+    def load_registered(entry)
+      return skip_registered(entry) unless File.directory?(entry.path)
+
+      folder = OKF::Bundle::Folder.load(entry.path)
+      report_skipped(folder)
+      OKF::Server::Hub::Bundle.new(entry.slug, folder, entry.title)
+    rescue SystemCallError, OKF::Error
+      skip_registered(entry)
+    end
+
+    def skip_registered(entry)
+      @err.puts "note: skipping #{entry.slug} — cannot read #{entry.path}"
+      nil
     end
 
     # The static counterpart to `server`: bake the whole bundle into one
     # self-contained HTML file (bodies, catalog, index, logs baked in, no server
     # needed — e.g. hosting on GitHub Pages). Prints to stdout unless -o is given.
     def render(argv)
-      require "okf/server/app"
+      require "okf/render/graph"
 
       options = { output: nil, title: nil, link: nil, layout: "cose" }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf render <bundle-dir> [-o FILE] [--layout NAME] [-t title] [-l url]"
+        o.banner = "Usage: okf render <dir|@slug> [-o FILE] [--layout NAME] [-t title] [-l url]"
         o.on("-o", "--output FILE", "write to FILE instead of stdout") { |v| options[:output] = v }
         o.on("-t", "--title TITLE", "graph title (default: parent/bundle dir name)") { |v| options[:title] = v }
         o.on("-l", "--link URL", "source URL shown in the header") { |v| options[:link] = v }
-        o.on("--layout NAME", OKF::Server::Graph::LAYOUTS, "initial layout (#{OKF::Server::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+        o.on("--layout NAME", OKF::Render::Graph::LAYOUTS, "initial layout (#{OKF::Render::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
       folder = OKF::Bundle::Folder.load(dir)
       report_skipped(folder)
-      html = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link], layout: options[:layout]).render_static
+      html = OKF::Render::Graph.static(folder, title: options[:title], link: options[:link], layout: options[:layout])
       if options[:output]
-        File.write(options[:output], html)
-        @out.puts "wrote #{folder.graph(minimal: true).nodes.size} concepts to #{options[:output]}"
+        # A bad -o path (a missing directory, a permission denial) is a bad
+        # *argument*: exit 2 with the reason, never a backtrace and an exit code
+        # that means "failing bundle".
+        begin
+          File.write(options[:output], html)
+        rescue SystemCallError => e
+          return usage_error("cannot write #{options[:output]}: #{e.message}")
+        end
+        count = folder.graph(minimal: true).nodes.size
+        @out.puts "wrote #{count} #{pluralize(count, "concept")} to #{options[:output]}"
       else
         @out.print html
       end
       0
     end
 
+    # The registry umbrella, split by what each verb keys on. `set`/`del`/`list`
+    # act on entries — `set` keys on the bundle's path, so --as means one thing
+    # ("the slug this entry has") whether it adds or renames. `default`/`rename`
+    # act on slugs, the names actually to hand once a bundle is registered. Every
+    # positional stays unambiguous, and `config` is left free for real settings.
+    def registry(argv)
+      require "okf/registry"
+
+      sub = argv.first
+      case sub
+      when "set" then registry_set(argv.drop(1))
+      when "del" then registry_del(argv.drop(1))
+      when "list" then registry_list(argv.drop(1))
+      when "default" then registry_default(argv.drop(1))
+      when "rename" then registry_rename(argv.drop(1))
+      else
+        # A bare word that isn't a known subcommand is a typo (`registry remove x`
+        # must not silently render the list and read as success).
+        return usage_error("unknown registry subcommand '#{sub}' (expected: #{SUBCOMMANDS.join(", ")})") if sub && !sub.start_with?("-")
+
+        # Same rule for a subcommand hiding behind a flag: `registry --json set
+        # dir` would otherwise list an empty registry and exit 0, having written
+        # nothing the user asked for. It cannot just be dispatched from wherever
+        # it turns up — the word may be a flag's value (`registry --as set <dir>`
+        # asks for the slug "set"), and a grammar where that reading depends on
+        # which flag precedes it is a trapdoor. So the subcommand must lead, and
+        # the error says which one was found rather than guessing at the intent.
+        stray = argv.find { |arg| SUBCOMMANDS.include?(arg) }
+        return usage_error("put the subcommand first: okf registry #{stray} … (flags follow it)") if stray
+
+        registry_list(argv)
+      end
+    end
+
+    # Add a bundle to the persistent registry (so a later bare `okf server` finds
+    # it), or update one already there. The entry is keyed by the bundle's path: a
+    # path already registered refreshes its title in place, and --as renames it. A
+    # new path is added, slugged by directory basename unless --as says otherwise.
+    def registry_set(argv)
+      options = { as: nil, default: false }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf registry set <dir|@slug> [--as SLUG] [--default]"
+        o.on("--as SLUG", "slug to register under (default: directory basename)") { |v| options[:as] = v }
+        o.on("--default", "put it first — the bundle a bare `okf server` opens") { options[:default] = true }
+        help_flag(o)
+      end
+      dir = positional_dir(parser, argv) or return 2
+      no_extras?(argv) or return 2
+
+      reg = OKF::Registry.load
+      # Said before the upsert: after it, an update is indistinguishable from an
+      # add, and "registered" for what was a rename reads as a duplicate entry.
+      known = reg.listing.any? { |row| row[:dir] == File.expand_path(dir) }
+      entry = reg.add(dir, as: options[:as], default: options[:default])
+      # Through report_skipped like every other bundle-reading verb: the reader
+      # tolerates a file it cannot open, so a count taken straight off the graph
+      # reports "0 concepts" for a bundle whose files are simply unreadable.
+      folder = OKF::Bundle::Folder.load(entry.path)
+      report_skipped(folder)
+      count = folder.graph(minimal: true).nodes.size
+      @out.puts "#{known ? "updated" : "registered"} #{entry.slug} → #{entry.path} (#{count} #{pluralize(count, "concept")})"
+      0
+    rescue OKF::Error => e
+      usage_error(e.message)
+    end
+
+    # Remove a bundle from the persistent registry by slug or by its directory.
+    def registry_del(argv)
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf registry del <dir|@slug>"
+        help_flag(o)
+      end
+      slug = positional(parser, argv) or return 2
+      no_extras?(argv) or return 2
+
+      reg = OKF::Registry.load
+      slug = registry_slug(slug, reg) or return 2
+      removed = reg.remove(slug)
+      return usage_error("no such bundle: #{slug}") unless removed
+
+      @out.puts "removed #{removed.slug}"
+      0
+    rescue OKF::Error => e
+      usage_error(e.message)
+    end
+
+    def registry_list(argv)
+      options = { json: false }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf registry list [--json] [--pretty]\n       " \
+                   "okf registry set <dir|@slug> | del <dir|@slug> | default <@slug> | rename <@slug> <new>"
+        json_flags(o, options, "emit the registry as JSON")
+        help_flag(o)
+      end
+      begin
+        parser.parse!(argv)
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        return 2
+      end
+      no_extras?(argv) or return 2
+
+      reg = OKF::Registry.load
+      return emit_list_json({ "registry" => reg.path }, "bundles", reg.listing.map { |row| stringify(row) }, options) if options[:json]
+
+      print_registry(reg)
+      0
+    rescue OKF::Error => e
+      usage_error(e.message)
+    end
+
+    # Choose which registered bundle a bare `okf server` opens at `/`, by moving
+    # it to the front of the registry. The listing is ordered and the JSON is
+    # meant to be hand-editable, so the move is stated rather than left to be
+    # discovered from a reordered file.
+    def registry_default(argv)
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf registry default <@slug>\n       " \
+                   "moves it to the front — the first registered bundle is the default until you do"
+        help_flag(o)
+      end
+      slug = positional(parser, argv) or return 2
+      no_extras?(argv) or return 2
+
+      reg = OKF::Registry.load
+      slug = registry_slug(slug, reg) or return 2
+      reg.default = slug
+      @out.puts "default bundle → #{reg.default.slug} (now first)"
+      0
+    rescue OKF::Error => e
+      usage_error(e.message)
+    end
+
+    # The @ref grammar for a verb that takes a *slug*, read by name. These three
+    # must reach an entry whose directory is gone — that is the one worth
+    # deleting or renaming — so they cannot go through resolve_ref, which
+    # insists the directory exist. Without this the refs only appeared to work:
+    # `normalize` strips the `@` off `@slug`, so `default @slug` resolved by
+    # accident while a bare `@` normalized to "" and failed. Returns the slug,
+    # or nil after reporting.
+    def registry_slug(arg, registry)
+      return arg unless arg.start_with?("@")
+
+      asked = arg[1..-1]
+      return asked unless asked.empty?
+
+      default = registry.default
+      return default.slug if default
+
+      @err.puts "error: no bundle is registered, so `@` names nothing (okf registry set <dir>)"
+      nil
+    end
+
+    # Rename a registered bundle's slug — its mount path and switcher name.
+    def registry_rename(argv)
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: okf registry rename <@slug> <new>"
+        help_flag(o)
+      end
+      parser.parse!(argv)
+      old_slug, new_slug = argv.shift(2)
+      if old_slug.nil? || new_slug.nil?
+        @err.puts parser.banner
+        return 2
+      end
+      no_extras?(argv) or return 2
+
+      reg = OKF::Registry.load
+      # The old name may be a ref; the new one is a name being minted, never one.
+      old_slug = registry_slug(old_slug, reg) or return 2
+      entry = reg.rename(old_slug, new_slug)
+      # The slug it *found*, not the argv that found it: rename normalizes to look
+      # the entry up, so echoing the raw ask names a bundle that never existed.
+      @out.puts "renamed #{OKF::Registry.normalize(old_slug)} → #{entry.slug}"
+      0
+    rescue OptionParser::ParseError => e
+      @err.puts e.message
+      2
+    rescue OKF::Error => e
+      usage_error(e.message)
+    end
+
+    # The registry verbs take an exact number of positionals — a leftover argument
+    # is a typo'd invocation, not something to drop silently.
+    def no_extras?(argv)
+      return true if argv.empty?
+
+      @err.puts "error: unexpected argument '#{argv.first}'"
+      false
+    end
+
+    def print_registry(reg)
+      return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty?
+
+      rows = reg.listing
+      width = rows.map { |row| row[:slug].length }.max
+      rows.each do |row|
+        marker = row[:default] ? "*" : " "
+        missing = row[:missing] ? "  (missing)" : ""
+        @out.puts "#{marker} #{row[:slug].ljust(width)}  #{row[:title]}  (#{row[:dir]})#{missing}"
+      end
+    end
+
     def graph(argv)
       options = { json: false, minimal: false, body: true }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf graph <bundle-dir> [--json] [--minimal] [--no-body]"
+        o.banner = "Usage: okf graph <dir|@slug> [--json] [--minimal] [--no-body]"
         json_flags(o, options, "emit nodes and edges as JSON")
         o.on("--minimal", "leanest nodes (id + title); adds type/tag indexes") { options[:minimal] = true }
         o.on("--[no-]body", "include each concept's body (default: yes)") { |v| options[:body] = v }
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -264,11 +814,15 @@ module OKF
       graph = folder.graph(minimal: options[:minimal], body: options[:body])
       report_skipped(folder)
       if options[:json]
-        payload = graph.to_h
+        # The head every view carries: a payload of nodes and edges that never
+        # says which bundle they came from is exactly what an agent holding
+        # several bundles has to guess at.
+        payload = bundle_head(dir).merge(graph.to_h)
         payload = payload.merge(types: graph.type_index, tags: graph.tag_index) if options[:minimal]
         emit_json(payload)
       else
-        @out.puts "#{graph.nodes.size} concepts, #{graph.edges.size} links"
+        @out.puts "Graph — #{bundle_label(dir)} (#{graph.nodes.size} #{pluralize(graph.nodes.size, "concept")}, " \
+                  "#{graph.edges.size} #{pluralize(graph.edges.size, "link")})"
       end
       0
     end
@@ -282,11 +836,12 @@ module OKF
     def index(argv)
       options = { json: false, body: true, areas: nil }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf index <bundle-dir> [--area AREA] [--no-body] [--json]"
+        o.banner = "Usage: okf index <dir|@slug> [--area AREA] [--no-body] [--json]"
         json_flags(o, options, "emit the index map as JSON")
         projection_flags(o, options)
         o.on("--area AREA", "only this directory/area (repeatable; `root` for the bundle root)") { |v| (options[:areas] ||= []) << v }
         o.on("--[no-]body", "include each index's prose body (default: yes)") { |v| options[:body] = v }
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -295,6 +850,13 @@ module OKF
       entries = folder.directory_index
       selected = select_directories(entries, options[:areas])
       if options[:json]
+        # --no-body is shorthand for --except body, so asking for the body by
+        # name in the same breath is a contradiction. Letting --fields quietly
+        # win would hand back the very thing the other flag was there to drop.
+        if !options[:body] && Array(options[:fields]).map(&:downcase).include?("body")
+          return usage_error("--no-body and --fields body contradict each other: drop one")
+        end
+
         options[:except] = Array(options[:except]) + [ "body" ] unless options[:body] || options[:fields]
         return print_index_map_json(dir, selected, options)
       end
@@ -314,7 +876,7 @@ module OKF
 
     def print_index_map(dir, entries, body)
       noun = entries.size == 1 ? "directory" : "directories"
-      @out.puts "Index map — #{dir} (#{entries.size} #{noun})"
+      @out.puts "Index map — #{bundle_label(dir)} (#{entries.size} #{noun})"
       entries.each do |entry|
         @out.puts
         @out.puts "  #{index_dir_label(entry)}#{index_dir_meta(entry)}"
@@ -334,8 +896,8 @@ module OKF
     end
 
     def index_dir_meta(entry)
-      count = "#{entry[:count]} #{entry[:count] == 1 ? "concept" : "concepts"}"
-      types = entry[:types].map { |type, n| "#{type.empty? ? "Untyped" : type} #{n}" }.join(", ")
+      count = "#{entry[:count]} #{pluralize(entry[:count], "concept")}"
+      types = entry[:types].map { |type, n| "#{OKF.blank?(type) ? "Untyped" : type} #{n}" }.join(", ")
       types.empty? ? "  ·  #{count}" : "  ·  #{count} · #{types}"
     end
 
@@ -377,10 +939,11 @@ module OKF
     def catalog(argv)
       options = { json: false }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf catalog <bundle-dir> [--type T] [--area A] [--tag T] [--json]"
+        o.banner = "Usage: okf catalog <dir|@slug> [--type T] [--area A] [--tag T] [--json]"
         json_flags(o, options, "emit the catalog as JSON")
         projection_flags(o, options)
         filter_flags(o, options, :type, :area, :tag)
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -397,10 +960,11 @@ module OKF
     def files(argv)
       options = { json: false }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf files <bundle-dir> [--type T] [--area A] [--tag T] [--json]"
+        o.banner = "Usage: okf files <dir|@slug> [--type T] [--area A] [--tag T] [--json]"
         json_flags(o, options, "emit the file tree as JSON")
         projection_flags(o, options)
         filter_flags(o, options, :type, :area, :tag)
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -417,10 +981,11 @@ module OKF
     def tags(argv)
       options = { json: false, by: nil }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf tags <bundle-dir> [--by type|area] [--type T] [--area A] [--json]"
+        o.banner = "Usage: okf tags <dir|@slug> [--by type|area] [--type T] [--area A] [--json]"
         json_flags(o, options, "emit the tag index as JSON")
         o.on("--by DIM", %w[type area], "group the tags by a concept dimension (type | area)") { |v| options[:by] = v.to_sym }
         filter_flags(o, options, :type, :area)
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -432,9 +997,10 @@ module OKF
     def types(argv)
       options = { json: false }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf types <bundle-dir> [--area A] [--tag T] [--json]"
+        o.banner = "Usage: okf types <dir|@slug> [--area A] [--tag T] [--json]"
         json_flags(o, options, "emit the type index as JSON")
         filter_flags(o, options, :area, :tag)
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -494,15 +1060,15 @@ module OKF
 
     # A catalog entry's type for display — "Untyped" when blank, matching the graph.
     def entry_type(entry)
-      entry[:type].empty? ? "Untyped" : entry[:type]
+      OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
     end
 
     def print_grouped_tags(dir, dim, groups, titles)
-      @out.puts "Tags — #{dir} (#{distinct_tags(groups)} distinct, by #{dim})"
+      @out.puts "Tags — #{bundle_label(dir)} (#{distinct_tags(groups)} distinct, by #{dim})"
       groups.each do |key, rows|
         label = dim == :area && key != "(root)" ? "#{key}/" : key
         @out.puts
-        @out.puts "  #{label} (#{rows.size} tags)"
+        @out.puts "  #{label} (#{rows.size} #{pluralize(rows.size, "tag")})"
         width = rows.map { |row| row[:tag].length }.max || 0
         rows.each do |row|
           names = row[:concepts].map { |id| titles[id] || id }.join(", ")
@@ -512,12 +1078,10 @@ module OKF
     end
 
     def print_grouped_tags_json(dir, dim, groups)
-      emit_json(
-        "bundle" => dir, "count" => distinct_tags(groups), "by" => dim.to_s,
-        "groups" => groups.map do |key, rows|
-          { dim.to_s => key, "count" => rows.size, "tags" => index_rows_json(:tag, rows) }
-        end
-      )
+      groups_json = groups.map do |key, rows|
+        { dim.to_s => key, "count" => rows.size, "tags" => index_rows_json(:tag, rows) }
+      end
+      emit_json(bundle_head(dir).merge("count" => distinct_tags(groups), "by" => dim.to_s, "groups" => groups_json))
     end
 
     def distinct_tags(groups)
@@ -527,8 +1091,9 @@ module OKF
     def stats(argv)
       options = { json: false }
       parser = OptionParser.new do |o|
-        o.banner = "Usage: okf stats <bundle-dir> [--json]"
+        o.banner = "Usage: okf stats <dir|@slug> [--json]"
         json_flags(o, options, "emit the stats as JSON")
+        help_flag(o)
       end
       dir = positional_dir(parser, argv) or return 2
 
@@ -569,6 +1134,58 @@ module OKF
       parser.on("--pretty", "indent the JSON for reading (implies --json)") { options[:json] = true; @pretty = true }
     end
 
+    # Every parser answers its own -h/--help, so no parser inherits
+    # OptionParser's officious one: that prints to the process's $stdout rather
+    # than @out (an embedding app that injects streams never sees it) and ends
+    # the process with `exit` rather than returning a status (a test that asks a
+    # command for help takes the whole runner down with it). Thrown, not
+    # returned — #run catches it — because a parser is parsed inside
+    # positional_dir, where every other early exit means "exit 2".
+    # on_tail, so help sorts last in the list it is printing.
+    def help_flag(parser)
+      parser.on_tail("-h", "--help", "print this message") do
+        @out.puts parser.help
+        throw :help, 0
+      end
+    end
+
+    # The registered engines, read at parse time so an addon that registers one
+    # shows up in `--help` without the CLI knowing it exists.
+    def engine_names
+      OKF::Bundle::Search.engines.map(&:id).join(" | ")
+    end
+
+    def unsupported_query_message(error)
+      wanted = error.missing.map { |name| CAPABILITY_FLAGS.fetch(name, ":#{name}") }.join(", ")
+      return "no available search engine offers #{wanted}" if error.engine.nil?
+
+      able = OKF::Bundle::Search.engines.select { |engine| (error.missing - engine.capabilities).empty? }
+      message = "--engine #{error.engine} does not support #{wanted}"
+      message += " (try --engine #{able.map(&:id).join(" or ")})" unless able.empty?
+      message
+    end
+
+    # The engine story, told once, in the only place there is to tell it. `search`
+    # routes on what the query needs — a pattern needs the scan, --fuzzy needs the
+    # index — and says nothing about it at runtime: no note on stderr, nothing in
+    # the header, and deliberately no --engine flag. So this is where a user learns
+    # that the exactness a token index gives up is still reachable, and that -e is
+    # how. Without it that capability is present but undiscoverable.
+    #
+    # It leads rather than trails because #help_flag registers -h with `on_tail`,
+    # which OptionParser renders after every separator: a closing paragraph would
+    # print *above* the -h line and split the option list in half. Stating the
+    # matching model before the flags reads better anyway.
+    def search_engine_note(parser)
+      parser.separator ""
+      parser.separator "Terms match raw text, so a phrase (\"dedup key\"), a dotted identifier (7.2.0,"
+      parser.separator "customer_id) and a word inside `backticks` all match literally — the scan engine."
+      parser.separator "--engine index matches whole tokens and the tokens they prefix, ranked by BM25+:"
+      parser.separator "better ranking and the engine the browser page runs, at the cost of that"
+      parser.separator "exactness. --fuzzy implies it. Add -e to read the terms as regular expressions."
+      parser.separator ""
+    end
+
     # --fields/--except project the JSON down to the properties an agent wants, so it
     # never pays tokens for fields it will not read. --fields is an allowlist,
     # --except a denylist (mutually exclusive); both imply --json and apply per item
@@ -633,6 +1250,7 @@ module OKF
         o.banner = "Usage: okf skill <dest-dir> [--here] [--force]"
         o.on("--here", "install straight into <dest-dir>, wherever it is (no skills/okf nesting)") { options[:nest] = false }
         o.on("--force", "overwrite a non-empty destination") { options[:force] = true }
+        help_flag(o)
       end
       parser.parse!(argv)
       dest = argv.shift
@@ -662,10 +1280,14 @@ module OKF
       note_skipped(folder.bundle.unparseable.size)
     end
 
+    # The bucket holds two kinds now — frontmatter that would not parse, and a
+    # file that would not open — so the note names neither and points at the verb
+    # that names both. "invalid frontmatter" was a guess the summary had no need
+    # to make: `validate` prints the file and the reason for every one of them.
     def note_skipped(count)
       return if count.nil? || count <= 0
 
-      @err.puts "note: skipped #{count} file(s) with invalid frontmatter (run `okf validate` for details)"
+      @err.puts "note: skipped #{count} unusable file(s) (run `okf validate` for details)"
     end
 
     # Turn a --stale-after value (90d, 12w, or an ISO date) into an absolute cutoff
@@ -684,8 +1306,9 @@ module OKF
       :invalid
     end
 
-    # Parse options, then require a single existing-directory positional argument.
-    # Returns the directory, or nil (after reporting) so the caller returns 2.
+    # Parse options, then require a single bundle positional — a directory, or an
+    # @ref into the registry. Returns the bundle's directory, or nil (after
+    # reporting) so the caller returns 2.
     def positional_dir(parser, argv)
       parser.parse!(argv)
       dir = argv.shift
@@ -693,11 +1316,143 @@ module OKF
         @err.puts parser.banner
         return nil
       end
-      unless File.directory?(dir)
-        @err.puts "error: #{dir} is not a directory"
+      # A second bundle is a question this verb cannot answer: only `search`
+      # merges across bundles and only `server` mounts several. Reading the
+      # first and dropping the rest would answer confidently about a bundle the
+      # user never asked about — the silent-wrong-answer shape, so: exit 2.
+      return nil unless no_extras?(argv)
+
+      resolve_ref(dir)
+    rescue OptionParser::ParseError => e
+      @err.puts e.message
+      nil
+    end
+
+    # Parse options, then take zero or more bundle positionals (the multi-bundle
+    # server) — directories or @refs. Returns the resolved array (possibly
+    # empty), or nil (after reporting) so the caller returns 2.
+    def positional_dirs(parser, argv)
+      parser.parse!(argv)
+      dirs = argv.map { |dir| resolve_ref(dir) }
+      dirs.include?(nil) ? nil : dirs
+    rescue OptionParser::ParseError => e
+      @err.puts e.message
+      nil
+    end
+
+    # "@slug" — or bare "@", the registry's default — names a registered bundle
+    # wherever a <dir> goes; anything else must be a directory on disk. A
+    # leading @ always means the registry (a directory literally named that way
+    # stays reachable as ./@name), and the registry loads only when a ref
+    # appears, so plain-dir invocations never pay for it. Returns the bundle's
+    # directory, or nil after reporting.
+    def resolve_ref(arg)
+      return resolve_registered(arg) if arg.start_with?("@")
+
+      unless File.directory?(arg)
+        @err.puts "error: #{arg} is not a directory or a registry ref " \
+                  "(@slug names a registered bundle, @ the default; okf registry list)"
         return nil
       end
-      dir
+      arg
+    end
+
+    # Load the registry, turning a malformed file into a reported usage error
+    # instead of an OKF::Error escaping through whatever verb took an @ref —
+    # only `server` and the `registry` verbs rescue one. Returns nil after
+    # reporting, so every caller returns 2.
+    def load_registry
+      require "okf/registry"
+      OKF::Registry.load
+    rescue OKF::Error => e
+      @err.puts "error: #{e.message}"
+      nil
+    end
+
+    # Resolve one @ref through the registry under $OKF_HOME (default ~/.okf).
+    # The slug part is normalized
+    # exactly as registration normalized it, so @One finds the bundle
+    # registered from dir One — but never through #slugify's mint-a-name
+    # placeholder, so "@***" is a bad ref rather than whatever is slugged
+    # "bundle". An explicit ask fails hard: an unknown slug or a
+    # registered-but-gone directory is a usage error naming the registry file
+    # and the next move, never a silent skip.
+    #
+    # @all never resolves here. `search` expands it before this point; every
+    # other verb takes exactly one bundle, so letting it through would mean
+    # @all lints when one bundle is registered and exits 2 when two are —
+    # behavior that varies with the size of the registry, which is the
+    # silent-wrong-answer shape the second-bundle rule exists to stop. Say what
+    # @all is instead of calling it a bundle nobody registered ("all" cannot be
+    # registered — Registry::RESERVED_SLUGS sees to that).
+    def resolve_registered(ref)
+      @ref_failure = :registry
+      if all_ref?(ref)
+        @err.puts "error: #{ALL_REF} is only supported by `okf search` (it names every registered bundle)"
+        return nil
+      end
+      registry = load_registry
+      return nil unless registry
+
+      asked = ref[1..-1]
+      slug = OKF::Registry.normalize(asked)
+      entry = if asked.empty?
+                registry.default # bare "@"
+              elsif slug.empty?
+                nil # "@***" — nothing to look up, and no placeholder to fall back on
+              else
+                registry.get(slug)
+              end
+      if entry.nil?
+        @ref_failure = :unknown
+        hint = registry.empty? ? "okf registry set <dir>" : "okf registry list"
+        @err.puts "error: not a registered bundle: #{ref} in #{registry.path} (#{hint})"
+        return nil
+      end
+      unless File.directory?(entry.path)
+        @ref_failure = :missing
+        @err.puts "error: #{ref} points to #{entry.path}, which is not a directory (okf registry del #{entry.slug}, or restore it)"
+        return nil
+      end
+      ref_slugs[entry.path] = entry.slug
+      entry.path
+    end
+
+    # Which slug each @ref resolved to, by absolute path — so a hub built from
+    # refs mounts each bundle under its registered slug, not its dir basename.
+    # Reset by every run; never memoized here, or a stale run would seed it.
+    attr_reader :ref_slugs
+
+    # Every bundle-scoped output names its bundle in the identity the caller
+    # used: `@handbook (/path)` when they named a registered bundle, the plain
+    # path otherwise. A dir named by path stays a path — inventing a slug for it
+    # would imply a registration that does not exist, and looking one up would
+    # cost a registry read on every plain-dir run.
+    def bundle_label(dir)
+      slug = ref_slugs[dir]
+      slug ? "@#{slug} (#{dir})" : dir.to_s
+    end
+
+    # The JSON head for one bundle. `bundle` is always its directory and `slug`
+    # always a registry slug — never the same key meaning two things — so a
+    # consumer resolves a row to a file without a second lookup.
+    def bundle_head(dir)
+      head = { "bundle" => dir }
+      slug = ref_slugs[dir]
+      head["slug"] = slug if slug
+      head
+    end
+
+    # Parse options, then require a single non-directory positional (e.g. a slug).
+    # Returns it, or nil (after reporting the banner) so the caller returns 2.
+    def positional(parser, argv)
+      parser.parse!(argv)
+      value = argv.shift
+      if value.nil?
+        @err.puts parser.banner
+        return nil
+      end
+      value
     rescue OptionParser::ParseError => e
       @err.puts e.message
       nil
@@ -705,7 +1460,7 @@ module OKF
 
     def print_validation(dir, result)
       counts = result.counts
-      @out.puts "OKF v0.1 conformance — #{dir}"
+      @out.puts "OKF v0.1 conformance — #{bundle_label(dir)}"
       @out.puts "  concepts: #{counts[:concepts]}   index.md: #{counts[:indexes]}   log.md: #{counts[:logs]}"
       result.errors.each { |e| @out.puts "  #{paint("✗ ERROR", 31)}  #{e[:path]}: #{e[:message]}" }
       result.warnings.each { |w| @out.puts "  #{paint("! warn", 33)}  #{w[:path]}: #{w[:message]}" }
@@ -719,18 +1474,17 @@ module OKF
     end
 
     def print_validation_json(dir, result)
-      emit_json(
-        "bundle" => dir,
+      emit_json(bundle_head(dir).merge(
         "conformant" => result.valid?,
         "counts" => result.counts,
         "errors" => result.errors,
         "warnings" => result.warnings
-      )
+      ))
     end
 
     def print_lint(dir, report)
       stats = report.stats
-      @out.puts "OKF lint — #{dir}"
+      @out.puts "OKF lint — #{bundle_label(dir)}"
       @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?
@@ -751,12 +1505,11 @@ module OKF
     end
 
     def print_lint_json(dir, report)
-      emit_json(
-        "bundle" => dir,
+      emit_json(bundle_head(dir).merge(
         "healthy" => report.healthy?,
         "stats" => report.stats,
         "findings" => report.findings
-      )
+      ))
     end
 
     # Degree-0 nodes as { id:, title:, dir: }, sorted by path — the same set lint's
@@ -769,7 +1522,7 @@ module OKF
     end
 
     def print_loose(dir, files)
-      @out.puts "Loose files — #{dir} (#{files.size})"
+      @out.puts "Loose files — #{bundle_label(dir)} (#{files.size})"
       if files.empty?
         @out.puts "  #{paint("✓ none — every concept links or is linked", 32)}"
         return
@@ -786,15 +1539,14 @@ module OKF
     end
 
     def print_loose_json(dir, files)
-      emit_json(
-        "bundle" => dir,
+      emit_json(bundle_head(dir).merge(
         "count" => files.size,
         "loose" => files.map { |file| stringify(file) }
-      )
+      ))
     end
 
     def print_catalog(dir, entries, total)
-      @out.puts "Catalog — #{dir} (#{counted(entries.size, total, "concepts")})"
+      @out.puts "Catalog — #{bundle_label(dir)} (#{counted(entries.size, total, "concept")})"
       entries.group_by { |entry| entry[:area] }.sort_by(&:first).each do |area, group|
         @out.puts
         @out.puts "  #{area == "(root)" ? "(root)" : "#{area}/"} (#{group.size})"
@@ -812,7 +1564,7 @@ module OKF
     end
 
     def print_files(dir, entries, total)
-      @out.puts "Files — #{dir} (#{counted(entries.size, total, "files")})"
+      @out.puts "Files — #{bundle_label(dir)} (#{counted(entries.size, total, "file")})"
       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
@@ -832,7 +1584,7 @@ module OKF
     end
 
     def print_index(dir, label, key, rows, titles)
-      @out.puts "#{label} — #{dir} (#{rows.size} distinct)"
+      @out.puts "#{label} — #{bundle_label(dir)} (#{rows.size} distinct)"
       @out.puts
       width = rows.map { |row| row[key].length }.max || 0
       rows.each do |row|
@@ -842,19 +1594,29 @@ module OKF
     end
 
     def print_index_json(dir, plural, key, rows)
-      emit_json("bundle" => dir, "count" => rows.size, plural => index_rows_json(key, rows))
+      emit_json(bundle_head(dir).merge("count" => rows.size, plural => index_rows_json(key, rows)))
     end
 
     def index_rows_json(key, rows)
       rows.map { |row| { key.to_s => row[key], "count" => row[:count], "concepts" => row[:concepts] } }
     end
 
+    # "3 concepts", "1 concept", "1 of 7 concepts" — the noun agrees with the
+    # number it follows: the size when that is all we show, the total otherwise.
     def counted(size, total, noun)
-      size == total ? "#{size} #{noun}" : "#{size} of #{total} #{noun}"
+      return "#{size} #{pluralize(size, noun)}" if size == total
+
+      "#{size} of #{total} #{pluralize(total, noun)}"
+    end
+
+    # The gem's whole vocabulary is regular, so a naive +s is not a shortcut —
+    # it is the rule. Callers pass the singular.
+    def pluralize(count, noun)
+      count == 1 ? noun : "#{noun}s"
     end
 
     def print_stats(dir, stats)
-      @out.puts "Stats — #{dir}"
+      @out.puts "Stats — #{bundle_label(dir)}"
       @out.puts
       @out.puts "  concepts       #{stats[:concepts]}"
       @out.puts "  areas          #{stats[:areas]}"
@@ -875,11 +1637,11 @@ module OKF
     end
 
     def print_stats_json(dir, stats)
-      emit_json(
-        "bundle" => dir, "concepts" => stats[:concepts], "areas" => stats[:areas],
+      emit_json(bundle_head(dir).merge(
+        "concepts" => stats[:concepts], "areas" => stats[:areas],
         "concept_types" => stats[:types], "cross_links" => stats[:cross_links], "distinct_tags" => stats[:tags],
         "by_type" => stats[:by_type], "by_area" => stats[:by_area]
-      )
+      ))
     end
 
     # The single JSON writer. Compact by default — the token-efficient substrate an
@@ -892,13 +1654,18 @@ 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, extra = {})
+    # +dir+ is the bundle's directory — or a ready-made head Hash when the
+    # payload spans bundles (multi-bundle search's "bundles" key).
+    # +key+ names the JSON property the rows land under; +shape+ names the row
+    # shape to check --fields/--except against. They are the same for every view
+    # but search, whose two modes emit the same property from different rows.
+    def emit_list_json(dir, key, items, options, extra = {}, shape = key)
       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?
+      unknown = unknown_fields(items, options, shape)
+      return usage_error("unknown field(s): #{unknown.join(", ")} (available: #{available_fields(items, shape).join(", ")})") unless unknown.empty?
 
-      payload = { "bundle" => dir }.merge(extra)
+      payload = (dir.is_a?(Hash) ? dir.dup : bundle_head(dir)).merge(extra)
       payload["count"] = items.size
       payload[key] = project(items, options)
       emit_json(payload)
@@ -917,17 +1684,22 @@ module OKF
       end
     end
 
-    def available_fields(items)
-      items.first ? items.first.keys.map(&:to_s) : []
+    # The declared shape wins over the data's, so the same typo gets the same
+    # answer whether or not the result happened to have rows; a view with no
+    # declared shape falls back to what it actually emitted.
+    def available_fields(items, key = nil)
+      ROW_FIELDS[key] || (items.first ? items.first.keys.map(&:to_s) : [])
     end
 
     # Requested field names that no item actually carries — a typo guard (exit 2),
     # matching how lint rejects unknown check names.
-    def unknown_fields(items, options)
+    def unknown_fields(items, options, key = nil)
       requested = (Array(options[:fields]) + Array(options[:except])).map(&:downcase)
-      return [] if requested.empty? || items.empty?
+      return [] if requested.empty?
+
+      known = available_fields(items, key).map(&:downcase)
+      return [] if known.empty? # an unknown view: no shape to check against, so accept
 
-      known = available_fields(items).map(&:downcase)
       requested.reject { |field| known.include?(field) }.uniq
     end
 
@@ -976,23 +1748,37 @@ module OKF
       io.puts <<~USAGE
         okf <command> [options]
 
-          skill     <dest> [--here] [--force]               install the companion agent skill
-          server    <dir> [-p PORT] [--bind ADDR] [...]     serve an interactive HTML graph
-          render    <dir> [-o FILE] [--layout NAME] [...]   write a static, self-contained HTML graph
-
-          lint      <dir> [--json] [--fail-on warn] [...]   report curation-quality issues
-          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
-          tags      <dir> [--json] [--by DIM] [filters]     list tags with their concepts, by count
-          files     <dir> [--json] [filters]                list files with titles, by folder
-          catalog   <dir> [--json] [filters]                list concepts with metadata, by area
-
-          graph     <dir> [--json] [--minimal] [--no-body]  print the knowledge graph
+          skill     <dest> [--here] [--force]                     install the companion agent skill
+          server    [DIR|@slug…] [-p PORT] [--bind ADDR] [...]    serve one bundle, or many behind a hub
+          render    <dir|@slug> [-o FILE] [--layout NAME] [...]   write a static, self-contained HTML graph
+
+          registry  list [--json]                                 list registered bundles (* marks the default)
+          registry  set <dir|@slug> [--as SLUG] [--default]       add or update a bundle (a bare `server` serves them)
+          registry  del <dir|@slug>                               remove a bundle from the registry
+          registry  default <@slug>                               move a bundle to the front (the default)
+          registry  rename <@slug> <new>                          rename a registered bundle (<new> is a new name, not a ref)
+
+          lint      <dir|@slug> [--json] [--fail-on warn] [...]   report curation-quality issues
+          loose     <dir|@slug> [--json]                          list files with no graph links, by folder
+          validate  <dir|@slug> [--json]                          check OKF v0.1 conformance
+
+          search    <dir|@slug…|@all> <term…> [-e|--fuzzy] [...]  find concepts by text or regexp, ranked (@all: every bundle)
+          index     <dir|@slug> [--json] [--area A] [--no-body]   the index map: dirs, their listings and rollups
+          stats     <dir|@slug> [--json]                          bundle rollups (concepts, types, areas, links, tags)
+          types     <dir|@slug> [--json] [filters]                list types with their concepts, by count
+          tags      <dir|@slug> [--json] [--by DIM] [filters]     list tags with their concepts, by count
+          files     <dir|@slug> [--json] [filters]                list files with titles, by folder
+          catalog   <dir|@slug> [--json] [filters]                list concepts with metadata, by area
+
+          graph     <dir|@slug> [--json] [--minimal] [--no-body]  print the knowledge graph
+
+        @slug names a registered bundle instead of a path — the slug from
+        `okf registry set`, or bare @ for the registry default. Anywhere a <dir>
+        goes, an @slug goes: `okf lint @handbook`, `okf render @ -o graph.html`.
+        The registry lives under $OKF_HOME (default ~/.okf); set it to point
+        every verb at another one.
+        search spans bundles: several leading @slugs, or @all for every registered one
+        (@all skips a bundle whose directory is gone; a named @slug insists on it).
 
         [filters] narrow a view to matching concepts: --type TYPE, --area AREA, --tag TAG
         (each view takes the ones orthogonal to it; matching is case-insensitive).