okf 1.10.0 → 1.12.0

data/lib/okf/cli/index.rb

@@ -5,9 +5,15 @@ module OKF
     # The progressive-disclosure map (spec §6): every directory that holds concepts
     # or carries an index.md, with its authored index body, a type/tag rollup, its
     # child directories, and — for a directory with no index.md — the listing
-    # synthesized from the concepts there. The "orient before you read" view. `--area`
-    # is repeatable (one or many directories; `root` is the bundle root); `--no-body`
-    # drops the prose to a skeleton; advisory, exit 0.
+    # synthesized from the concepts there. The "orient before you read" view. `--dir`
+    # is repeatable and selects a directory *and its subtree* (`root` is the bundle
+    # root), `--depth N` bounds how far below the starting point that goes, and
+    # `--no-body` drops the prose to a skeleton; advisory, exit 0.
+    #
+    # The two narrowings are what make the map usable on a deep bundle: every
+    # directory is a section, so a few hundred concepts is a map nobody reads at
+    # once. `--depth 1` is the top of the tree, `--dir X --depth 1` is one branch
+    # of it, and the pair walks down a level at a time.
     class Index < Command
       def self.id
         :index
@@ -19,26 +25,47 @@ module OKF
 
       def self.help_rows
         [
-          [ "index     <dir|@slug> [--json] [--area A] [--no-body]", "the index map: dirs, their listings and rollups" ]
+          [ "index     <dir|@slug> [--dir D] [--depth N] [--no-body]", "the index map: dirs, their listings and rollups" ]
         ]
       end
 
       def call(argv)
-        options = { json: false, body: true, areas: nil }
+        options = { json: false, body: true, dirs: nil, areas: nil, depth: nil, ancestors: true }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf index <dir|@slug> [--area AREA] [--no-body] [--json]"
+          o.banner = "Usage: okf index <dir|@slug> [--dir PATH] [--depth N] [--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("--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)
+          o.on("--area AREA", "deprecated: use --dir (this directory exactly)") do |v|
+            (options[:areas] ||= []) << v
+            deprecated("--area", "--dir")
+          end
           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
+        bad_depth = depth_error(options)
+        return bad_depth if bad_depth
+        # --area is exact and names no starting point, so --depth has nothing to
+        # be relative *to*: the pair used to union the area with every directory
+        # at that depth from the root. Refusing beats answering with more.
+        #
+        # --dir is refused for the same reason and not a weaker one: one flag is
+        # exact and the other a prefix, so the pair came back with the area *and*
+        # the subtree — an answer to neither question, from a combination only
+        # someone mid-migration would type. A deprecated flag that quietly widens
+        # is worse than one that is merely old.
+        if options[:areas] && (options[:depth] || options[:dirs])
+          return usage_error("--area and #{options[:dirs] ? "--dir" : "--depth"} do not combine: use --dir")
+        end
 
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
         entries = folder.directory_index
-        selected = select_directories(entries, options[:areas])
+        selected, chain = select_directories(entries, options)
         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
@@ -48,30 +75,44 @@ module OKF
           end
 
           options[:except] = Array(options[:except]) + [ "body" ] unless options[:body] || options[:fields]
-          return print_index_map_json(dir, selected, options)
+          return print_index_map_json(dir, selected, chain, options)
         end
-        print_index_map(dir, selected, options[:body])
+        print_index_map(dir, selected, chain, options[:body])
         0
       end
 
       private
 
-      # Narrow the map to the named directories/areas — case-insensitive, `root`
-      # matching the bundle root (".") so no shell quoting is needed. No --area passed
-      # keeps the whole map.
-      def select_directories(entries, areas)
-        return entries if areas.nil? || areas.empty?
-
-        wanted = areas.map { |area| area.downcase == "root" ? "." : area.downcase }
-        entries.select { |entry| wanted.include?(entry[:dir].downcase) }
+      # Narrow the map — case-insensitive, `root` matching the bundle root (".").
+      # --dir takes the named directory *and its subtree* and --depth bounds how
+      # far below the starting point that reaches, both through the shared
+      # select_dirs so the whole CLI answers "which directories?" one way. The
+      # deprecated --area keeps its old exact match beside them, because a
+      # deprecated flag that quietly widens is worse than one that is merely old.
+      # Nothing passed keeps the whole map.
+      def select_directories(entries, options)
+        areas = Array(options[:areas]).map { |area| fold_dir(area) }
+        scoped = !options[:dirs].nil? || !options[:depth].nil?
+        return [ entries, [] ] if areas.empty? && !scoped
+
+        all_dirs = entries.map { |entry| entry[:dir] }
+        wanted = scoped ? select_dirs(all_dirs, options) : []
+        chain = ancestor_dirs(options, all_dirs) - wanted
+        selected = entries.select do |entry|
+          areas.include?(fold(entry[:dir])) || wanted.include?(entry[:dir]) || chain.include?(entry[:dir])
+        end
+        [ selected, chain ]
       end
 
-      def print_index_map(dir, entries, body)
+      def print_index_map(dir, entries, chain, body)
         noun = entries.size == 1 ? "directory" : "directories"
         @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)}"
+          # ↑ marks a row the reader did not ask for: it is here to place the
+          # branch, not to answer about it.
+          up = chain.include?(entry[:dir]) ? "↑ " : ""
+          @out.puts "  #{up}#{index_dir_label(entry)}#{index_dir_meta(entry)}"
           subdirs = entry[:subdirs]
           @out.puts "    → #{subdirs.map { |sub| "#{File.basename(sub)}/" }.join("  ")}" unless subdirs.empty?
           if entry[:present]
@@ -83,7 +124,7 @@ module OKF
       end
 
       def index_dir_label(entry)
-        base = entry[:dir] == "." ? "(root)" : "#{entry[:dir]}/"
+        base = dir_label(entry[:dir], slash: true)
         entry[:present] ? base : "#{base}  (no index.md)"
       end
 
@@ -107,13 +148,14 @@ module OKF
         end
       end
 
-      def print_index_map_json(dir, entries, options)
-        emit_list_json(dir, "directories", entries.map { |entry| index_map_entry_json(entry) }, options)
+      def print_index_map_json(dir, entries, chain, options)
+        rows = entries.map { |entry| index_map_entry_json(entry, chain.include?(entry[:dir])) }
+        emit_list_json(dir, "directories", rows, options)
       end
 
-      def index_map_entry_json(entry)
+      def index_map_entry_json(entry, ancestor)
         {
-          "dir" => entry[:dir], "index_path" => entry[:index_path],
+          "dir" => entry[:dir], "ancestor" => ancestor, "index_path" => entry[:index_path],
           "present" => entry[:present], "synthesized" => entry[:synthesized],
           "count" => entry[:count], "types" => entry[:types], "tags" => entry[:tags],
           "subdirs" => entry[:subdirs], "body" => entry[:body],

data/lib/okf/cli/loose.rb

@@ -44,7 +44,7 @@ module OKF
       def loose_files(graph)
         titles = graph.nodes.map { |node| [ node[:id], node[:title] ] }.to_h
         graph.unlinked_ids
-             .map { |id| { id: id, title: titles[id], dir: File.dirname("#{id}.md") } }
+             .map { |id| { id: id, title: titles[id], dir: OKF.dir_of(id) } }
              .sort_by { |file| file[:id] }
       end
 
@@ -58,7 +58,7 @@ module OKF
         files.group_by { |file| file[:dir] }.sort_by(&:first).each do |folder, group|
           width = group.map { |file| File.basename("#{file[:id]}.md").length }.max
           @out.puts
-          @out.puts "  #{folder == "." ? "(root)" : "#{folder}/"}"
+          @out.puts "  #{dir_label(folder, slash: true)}"
           group.each do |file|
             @out.puts "    #{File.basename("#{file[:id]}.md").ljust(width)}  #{file[:title]}"
           end

data/lib/okf/cli/registry.rb

@@ -10,7 +10,7 @@ module OKF
     class Registry < Command
       # 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
+      SUBCOMMANDS = %w[init set del list default rename group ungroup].freeze
 
       def self.id
         :registry
@@ -22,11 +22,14 @@ module OKF
 
       def self.help_rows
         [
+          [ "registry  init", "create a project-local .okf-registry.json (nearest one wins)" ],
           [ "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  del <dir|@slug>", "remove a bundle or group 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)" ]
+          [ "registry  rename <@slug> <new>", "rename a bundle or group (<new> is a new name, not a ref)" ],
+          [ "registry  group <slug> <@member…>", "create a group, or add members (search/server can target @slug)" ],
+          [ "registry  ungroup <slug> <@member…>", "remove members from a group (emptying it deletes it)" ]
         ]
       end
 
@@ -35,11 +38,14 @@ module OKF
 
         sub = argv.first
         case sub
+        when "init" then registry_init(argv.drop(1))
         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))
+        when "group" then registry_group(argv.drop(1))
+        when "ungroup" then registry_ungroup(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).
@@ -61,6 +67,38 @@ module OKF
 
       private
 
+      # Create a project-local .okf-registry.json in the current directory. Once it
+      # exists, discovery finds it (walking up from cwd) and every registry op —
+      # and every @ref — resolves through it instead of the global $OKF_HOME one.
+      # init only writes the empty file; `registry set` fills it. Refuses to clobber
+      # an existing local registry, and notes a parent one it would shadow.
+      def registry_init(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry init"
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        no_extras?(argv) or return 2
+
+        target = File.join(Dir.pwd, OKF::Registry::LOCAL_FILE)
+        display = "./#{OKF::Registry::LOCAL_FILE}"
+        return usage_error("already initialized: #{display}") if File.exist?(target)
+
+        # The parent it would shadow, if any — a courtesy, not a barrier: nested
+        # registries resolve nearest-first, so creating one here is legitimate.
+        parent = OKF::Registry.discover(File.dirname(Dir.pwd))
+        @err.puts "note: a parent registry at #{parent} — the nearest one wins" if parent
+
+        OKF::Registry.new(target).save
+        @out.puts "initialized #{display}"
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      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
@@ -78,7 +116,7 @@ module OKF
         # positional through `positional`, which does not check.
         dir = positional_dir(parser, argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         # 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) }
@@ -104,7 +142,7 @@ module OKF
         slug = positional(parser, argv) or return 2
         no_extras?(argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         slug = registry_slug(slug, reg) or return 2
         removed = reg.remove(slug)
         return usage_error("no such bundle: #{slug}") unless removed
@@ -131,8 +169,11 @@ module OKF
         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]
+        reg = open_registry
+        if options[:json]
+          groups = { "groups" => reg.groups_listing.map { |row| stringify(row) } }
+          return emit_list_json({ "registry" => reg.path }, "bundles", reg.listing.map { |row| stringify(row) }, options, groups)
+        end
 
         print_registry(reg)
         0
@@ -153,7 +194,7 @@ module OKF
         slug = positional(parser, argv) or return 2
         no_extras?(argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         slug = registry_slug(slug, reg) or return 2
         reg.default = slug
         @out.puts "default bundle → #{reg.default.slug} (now first)"
@@ -196,7 +237,7 @@ module OKF
         end
         no_extras?(argv) or return 2
 
-        reg = OKF::Registry.load
+        reg = open_registry
         # 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)
@@ -211,15 +252,111 @@ module OKF
         usage_error(e.message)
       end
 
+      # Create a group, or add members to one. Members are bundle or group slugs,
+      # bare or as @refs; the model normalizes, unions, checks each names something,
+      # and refuses a cycle. Only `search`/`server` can then target @slug.
+      def registry_group(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry group <slug> <@member…>"
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        slug = argv.shift
+        if slug.nil? || argv.empty?
+          @err.puts parser.banner
+          return 2
+        end
+
+        reg = open_registry
+        group = reg.set_group(slug, argv)
+        count = reg.expand(group.slug).size
+        @out.puts "grouped #{group.slug} → #{group.members.map { |m| "@#{m}" }.join(", ")} " \
+                  "(#{count} #{pluralize(count, "bundle")})"
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # Remove members from a group. Emptying it deletes the group — an empty group
+      # resolves to nothing, so it is not worth keeping.
+      def registry_ungroup(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry ungroup <slug> <@member…>"
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        slug = argv.shift
+        if slug.nil? || argv.empty?
+          @err.puts parser.banner
+          return 2
+        end
+
+        reg = open_registry
+        removed, emptied = reg.unset_group_members(slug, argv)
+        name = OKF::Registry.normalize(slug)
+        if emptied
+          @out.puts "removed empty group #{name}"
+        elsif removed.empty?
+          @out.puts "no members removed from #{name} (none of #{argv.join(", ")} were in it)"
+        else
+          @out.puts "ungrouped #{removed.map { |m| "@#{m}" }.join(", ")} from #{name}"
+        end
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
       def print_registry(reg)
-        return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty?
+        # A header only when a project-local registry is in play — the case where
+        # "which registry am I looking at?" is a real question. The global $OKF_HOME
+        # one is the default, so it stays headerless (and the JSON envelope names
+        # the file for a script either way).
+        @out.puts "registry: #{registry_display(reg)}" if local_registry?(reg)
+        groups = reg.groups_listing
+        return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty? && groups.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}"
+        unless rows.empty?
+          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
+        print_groups(groups, rows) unless groups.empty?
+      end
+
+      # Whether this registry was discovered as a project-local file rather than
+      # read from $OKF_HOME — the basename settles it (only a local one is named
+      # .okf-registry.json).
+      def local_registry?(reg)
+        File.basename(reg.path) == OKF::Registry::LOCAL_FILE
+      end
+
+      # How to name the local registry in the header: `./` when it sits in cwd
+      # (the common case, a bare `init` here), its absolute path when discovery
+      # walked up to an ancestor.
+      def registry_display(reg)
+        File.dirname(reg.path) == Dir.pwd ? "./#{OKF::Registry::LOCAL_FILE}" : reg.path
+      end
+
+      # The groups section under the bundle listing: one row per group, its members
+      # and how many bundles it resolves to (a hand-edited cycle shows `(cycle)`).
+      def print_groups(groups, rows)
+        @out.puts "" unless rows.empty?
+        @out.puts "groups:"
+        width = groups.map { |group| group[:slug].length }.max
+        groups.each do |group|
+          members = group[:members].map { |m| "@#{m}" }.join(", ")
+          count = group[:resolved].nil? ? "cycle" : "#{group[:resolved]} #{pluralize(group[:resolved], "bundle")}"
+          @out.puts "  #{group[:slug].ljust(width)}  #{members}  (#{count})"
         end
       end
     end

data/lib/okf/cli/render.rb

@@ -23,20 +23,21 @@ module OKF
       def call(argv)
         require "okf/render/graph"
 
-        options = { output: nil, title: nil, link: nil, layout: "cose" }
+        options = { output: nil, title: nil, link: nil, layout: "cose", map: false }
         parser = OptionParser.new do |o|
           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::Render::Graph::LAYOUTS, "initial layout (#{OKF::Render::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+          o.on("--map", "open in the Map view: concepts boxed by directory, links on selection") { options[:map] = true }
           help_flag(o)
         end
         dir = positional_dir(parser, argv) or return 2
 
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
-        html = OKF::Render::Graph.static(folder, title: options[:title], link: options[:link], layout: options[:layout])
+        html = OKF::Render::Graph.static(folder, title: options[:title], link: options[:link], layout: options[:layout], map: options[:map])
         if 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

data/lib/okf/cli/search.rb

@@ -34,7 +34,7 @@ module OKF
       def call(argv)
         options = { json: false, regexp: false, fuzzy: false, engine: nil }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] [--in FIELDS] [--type T] [--area A] [--tag T] [--json]"
+          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] [--in FIELDS] [--type T] [--dir D] [--tag T] [--json]"
           search_engine_note(o)
           json_flags(o, options, "emit the matches as JSON")
           projection_flags(o, options)
@@ -158,8 +158,17 @@ module OKF
         pairs
       end
 
-      # One @ref as a single-element [[slug, dir]], or nil after reporting.
+      # One @ref as [[slug, dir], …]: a group fans out to its readable member
+      # bundles, a plain @slug is the single-element pair it always was. nil after
+      # reporting. `ref_targets` dedupes across refs, and #expand within a group, so
+      # `@backend @okf` (okf ∈ backend) still searches okf once.
       def ref_pair(ref)
+        registry = load_registry
+        return nil unless registry
+
+        slug = OKF::Registry.normalize(ref[1..-1])
+        return group_pairs(registry, slug) if !slug.empty? && registry.group?(slug)
+
         path = resolve_registered(ref)
         unless path
           # Only an unknown slug is plausibly a mistyped term — a broken registry
@@ -170,6 +179,28 @@ module OKF
         [ [ ref_slugs[path], path ] ]
       end
 
+      # A group's readable member bundles as [slug, dir] pairs, skipping vanished
+      # ones with a note (as `@all` does) and labelling each leaf by its own slug.
+      # nil (reported) when nothing readable is left, or on a hand-edited cycle.
+      def group_pairs(registry, slug)
+        pairs = []
+        registry.expand(slug).each do |entry|
+          if File.directory?(entry.path)
+            ref_slugs[entry.path] = entry.slug
+            pairs << [ entry.slug, entry.path ]
+          else
+            skip_registered(entry)
+          end
+        end
+        return pairs unless pairs.empty?
+
+        @err.puts "error: @#{slug} resolves to no readable bundle (okf registry list)"
+        nil
+      rescue OKF::Error => e
+        @err.puts "error: #{e.message}"
+        nil
+      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

data/lib/okf/cli/server.rb

@@ -24,7 +24,7 @@ module OKF
         require "okf/server/app"
         require "rack/deflater"
 
-        options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose", read_only: false }
+        options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose", read_only: false, map: false }
         parser = OptionParser.new do |o|
           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 }
@@ -32,10 +32,14 @@ module OKF
           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 }
+          o.on("--map", "open in the Map view: concepts boxed by directory, links on selection") { options[:map] = true }
           o.on("--read-only", "serve the bundles list without its registry controls") { options[:read_only] = true }
           help_flag(o)
         end
-        dirs = positional_dirs(parser, argv) or return 2
+        # expand_groups: `okf server @backend` fans a group out to its member
+        # bundles (single-bundle verbs reject a group; server is one of the two that
+        # take a set).
+        dirs = positional_dirs(parser, argv, expand_groups: true) or return 2
 
         # 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])
@@ -59,10 +63,16 @@ module OKF
       # 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])
+        # search_endpoint is named here rather than defaulted in App: the page
+        # resolves it against the URL the reader is on, and this is the layer that
+        # knows the app is mounted at the root. An embedding host mounting App
+        # elsewhere passes its own.
+        app = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link],
+          layout: options[:layout], search_endpoint: "search", map: options[:map])
         # 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.
+        app.warm_search
         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)
@@ -80,7 +90,7 @@ module OKF
         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
+          reg = open_registry
           # The hub's own loader, so the set it rebuilds after a browser-side
           # write is built exactly the way this one was.
           bundles = OKF::Server::Hub.bundles_for(reg) { |entry| skip_registered(entry) }
@@ -91,7 +101,8 @@ module OKF
         # The hub keeps the registry so its /b/ manager can report on entries it
         # could not host — a folder deleted out from under one is the question
         # "where did my bundle go?", and only the registry can answer it.
-        hub = OKF::Server::Hub.new(bundles, layout: options[:layout], registry: reg, writable: writable?(options))
+        hub = OKF::Server::Hub.new(bundles, layout: options[:layout], registry: reg, writable: writable?(options), map: options[:map])
+        hub.warm_search
         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)"