okf 1.9.0 → 1.11.0

data/lib/okf/cli/dirs.rb

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

data/lib/okf/cli/files.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Every file with its title, grouped by folder — the view for "what is on disk"
+    # rather than "what is modelled".
+    class Files < Command
+      def self.id
+        :files
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "files     <dir|@slug> [--json] [filters]", "list files with titles, by folder" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf files <dir|@slug> [--type T] [--dir D] [--tag T] [--json]"
+          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
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        entries = folder.catalog
+        selected = filter_entries(entries, options)
+        return print_files_json(dir, selected, options) if options[:json]
+
+        print_files(dir, selected, entries.size)
+        0
+      end
+
+      private
+
+      def print_files(dir, entries, total)
+        @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
+          @out.puts "  #{dir_label(folder, slash: true)}"
+          group.each do |entry|
+            @out.puts "    #{File.basename("#{entry[:id]}.md").ljust(width)}  #{entry[:title]}"
+          end
+        end
+      end
+
+      def print_files_json(dir, entries, options)
+        files = entries.map do |entry|
+          { "path" => "#{entry[:id]}.md", "id" => entry[:id], "dir" => entry[:dir], "type" => entry[:type], "title" => entry[:title],
+            "description" => entry[:description] }
+        end
+        emit_list_json(dir, "files", files, options)
+      end
+    end
+
+    register(Files)
+  end
+end

data/lib/okf/cli/graph.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The knowledge graph as text — nodes, edges and the rollups the browser page
+    # draws, for a reader that has no browser.
+    class Graph < Command
+      def self.id
+        :graph
+      end
+
+      def self.group
+        :graph
+      end
+
+      def self.help_rows
+        [
+          [ "graph     <dir|@slug> [--json] [--minimal] [--hubs]", "print the knowledge graph" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false, minimal: false, body: true, hubs: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf graph <dir|@slug> [--json] [--minimal] [--no-body] [--hubs]"
+          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 }
+          o.on("--hubs", "rank concepts by inbound links, with the source areas") { options[:hubs] = true }
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        return print_hubs(dir, options) if options[:hubs]
+
+        folder = OKF::Bundle::Folder.load(dir)
+        graph = folder.graph(minimal: options[:minimal], body: options[:body])
+        report_skipped(folder)
+        if options[:json]
+          # 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 — #{bundle_label(dir)} (#{graph.nodes.size} #{pluralize(graph.nodes.size, "concept")}, " \
+                    "#{graph.edges.size} #{pluralize(graph.edges.size, "link")})"
+        end
+        0
+      end
+
+      private
+
+      # `graph --hubs`: the inbound ranking with each hub's links grouped by
+      # source area — the "is this hub well-homed?" evidence. A hub whose
+      # inbound majority comes from outside its own area is a move candidate;
+      # --minimal/--no-body shape node payloads and change nothing here.
+      def print_hubs(dir, options)
+        folder = OKF::Bundle::Folder.load(dir)
+        hubs = folder.hubs
+        report_skipped(folder)
+        if options[:json]
+          rows = hubs.map { |row| { "id" => row[:id], "area" => row[:area], "inbound" => row[:inbound], "by_area" => row[:by_area] } }
+          emit_json(bundle_head(dir).merge("count" => hubs.size, "hubs" => rows))
+        else
+          @out.puts "Hubs — #{bundle_label(dir)} (#{counted(hubs.size, folder.concepts.size, "concept")} with inbound links)"
+          @out.puts
+          width = hubs.map { |row| row[:id].length }.max || 0
+          dwidth = hubs.map { |row| row[:inbound].to_s.length }.max || 0
+          hubs.each do |row|
+            sources = row[:by_area].map { |area, count| "#{area} #{count}" }.join(", ")
+            @out.puts "  #{row[:id].ljust(width)}  ×#{row[:inbound].to_s.rjust(dwidth)}   #{sources}"
+          end
+        end
+        0
+      end
+    end
+
+    register(Graph)
+  end
+end

data/lib/okf/cli/index.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # 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. `--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
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "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, dirs: nil, areas: nil, depth: nil, ancestors: true }
+        parser = OptionParser.new do |o|
+          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("--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, 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
+          # 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, chain, options)
+        end
+        print_index_map(dir, selected, chain, options[:body])
+        0
+      end
+
+      private
+
+      # 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, chain, body)
+        noun = entries.size == 1 ? "directory" : "directories"
+        @out.puts "Index map — #{bundle_label(dir)} (#{entries.size} #{noun})"
+        entries.each do |entry|
+          @out.puts
+          # ↑ 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]
+            print_index_body(entry[:body]) if body
+          else
+            print_synthesized_listing(entry[:listing])
+          end
+        end
+      end
+
+      def index_dir_label(entry)
+        base = dir_label(entry[:dir], slash: true)
+        entry[:present] ? base : "#{base}  (no index.md)"
+      end
+
+      def index_dir_meta(entry)
+        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
+
+      def print_index_body(body)
+        text = body.to_s.strip
+        return if text.empty?
+
+        text.each_line { |line| @out.puts "    #{line.chomp}" }
+      end
+
+      def print_synthesized_listing(listing)
+        listing.each do |item|
+          suffix = item[:description].empty? ? "" : " — #{truncate(item[:description], 72)}"
+          @out.puts "    • #{item[:title]}#{suffix}"
+        end
+      end
+
+      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, ancestor)
+        {
+          "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],
+          "listing" => entry[:listing].map { |item| stringify(item) }
+        }
+      end
+    end
+
+    register(Index)
+  end
+end

data/lib/okf/cli/lint.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The curation judge: is this bundle *good*? Advisory by design — findings
+    # never change the exit code unless --fail-on says so, because a stub or a
+    # loose leaf can be deliberate. Freshness is off unless --stale-after asks.
+    class Lint < Command
+      # Lint findings grouped for display, in category order.
+      LINT_CATEGORIES = {
+        "Reachability" => %i[orphan not_in_index disconnected_component unlinked],
+        "Backlog" => %i[missing_concept broken_index_entry],
+        "Completeness" => %i[stub missing_title missing_description missing_timestamp],
+        "Freshness" => %i[stale],
+        "Provenance" => %i[uncited_external broken_citation],
+        "Hygiene" => %i[duplicate_title unused_reference_def undefined_reference self_link]
+      }.freeze
+
+      def self.id
+        :lint
+      end
+
+      def self.group
+        :judge
+      end
+
+      def self.help_rows
+        [
+          [ "lint      <dir|@slug> [--json] [--fail-on warn] [...]", "report curation-quality issues" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false, min_body: OKF::Bundle::Linter::DEFAULT_MIN_BODY, stale_after: nil, only: nil, except: nil, fail_on: :never }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf lint <dir|@slug> [--json] [--min-body N] [--stale-after DUR] [--only a,b] [--except a,b] [--fail-on warn]"
+          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
+
+        unknown = ((options[:only] || []) + (options[:except] || [])) - OKF::Bundle::Linter::CHECKS
+        unless unknown.empty?
+          @err.puts "error: unknown check(s): #{unknown.uniq.join(", ")}"
+          return 2
+        end
+
+        stale_before = parse_stale_after(options[:stale_after])
+        if stale_before == :invalid
+          @err.puts "error: invalid --stale-after `#{options[:stale_after]}` (use 90d, 12w, or an ISO date like 2026-01-01)"
+          return 2
+        end
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report = folder.lint(min_body: options[:min_body], stale_before: stale_before, only: options[:only], except: options[:except])
+        note_skipped(report.stats[:skipped])
+        options[:json] ? print_lint_json(dir, report) : print_lint(dir, report)
+        options[:fail_on] == :warn && report.warnings.any? ? 1 : 0
+      end
+
+      private
+
+      # Turn a --stale-after value (90d, 12w, or an ISO date) into an absolute cutoff
+      # Time so the pure Linter never reads the clock. nil when unset, :invalid on a
+      # bad value.
+      def parse_stale_after(value)
+        return nil if value.nil?
+
+        if (match = value.match(/\A(\d+)([dw])\z/))
+          days = match[1].to_i * (match[2] == "w" ? 7 : 1)
+          Time.now - (days * 86_400)
+        else
+          Date.iso8601(value).to_time
+        end
+      rescue ArgumentError
+        :invalid
+      end
+
+      def print_lint(dir, report)
+        stats = report.stats
+        @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?
+
+        LINT_CATEGORIES.each do |name, checks|
+          findings = report.findings.select { |finding| checks.include?(finding[:check]) }
+          next if findings.empty?
+
+          @out.puts
+          @out.puts "  #{name}"
+          findings.each do |finding|
+            @out.puts "    #{lint_glyph(finding)}  #{[ finding[:path], finding[:message] ].compact.join(": ")}"
+          end
+        end
+
+        @out.puts
+        @out.puts "  #{lint_verdict(report)}"
+      end
+
+      def print_lint_json(dir, report)
+        emit_json(bundle_head(dir).merge(
+          "healthy" => report.healthy?,
+          "stats" => report.stats,
+          "findings" => report.findings
+        ))
+      end
+
+      def lint_summary(stats)
+        parts = []
+        hubs = stats[:hubs].map { |hub| "#{hub[:id]} (×#{hub[:in_degree]})" }.join(", ")
+        types = stats[:types].map { |type, count| "#{type} #{count}" }.join(", ")
+        parts << "hubs: #{hubs}" unless hubs.empty?
+        parts << "types: #{types}" unless types.empty?
+        parts.join("   ")
+      end
+
+      def lint_glyph(finding)
+        finding[:severity] == :warn ? paint("! warn", 33) : "· info"
+      end
+
+      def lint_verdict(report)
+        warnings = report.warnings.size
+        infos = report.info.size
+        return paint("✓ healthy — no issues", 32) if warnings.zero? && infos.zero?
+
+        marker = warnings.zero? ? paint("✓", 32) : paint("⚠", 33)
+        "#{marker} #{warnings} warn, #{infos} info"
+      end
+    end
+
+    register(Lint)
+  end
+end

data/lib/okf/cli/loose.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # List the "loose" files — concepts with graph degree 0 (no cross-links in or
+    # out), grouped by folder. A folder-grouped view over lint's `unlinked` check,
+    # for the common "which files float in the graph?" question. Advisory (exit 0):
+    # a terminal leaf can be loose by design. `--json` for a machine substrate.
+    class Loose < Command
+      def self.id
+        :loose
+      end
+
+      def self.group
+        :judge
+      end
+
+      def self.help_rows
+        [
+          [ "loose     <dir|@slug> [--json]", "list files with no graph links, by folder" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          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
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        files = loose_files(folder.graph(minimal: true))
+        options[:json] ? print_loose_json(dir, files) : print_loose(dir, files)
+        0
+      end
+
+      private
+
+      # Degree-0 nodes as { id:, title:, dir: }, sorted by path — the same set lint's
+      # `unlinked` check reports, resolved to titles/folders for display.
+      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: OKF.dir_of(id) } }
+             .sort_by { |file| file[:id] }
+      end
+
+      def print_loose(dir, files)
+        @out.puts "Loose files — #{bundle_label(dir)} (#{files.size})"
+        if files.empty?
+          @out.puts "  #{paint("✓ none — every concept links or is linked", 32)}"
+          return
+        end
+
+        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 "  #{dir_label(folder, slash: true)}"
+          group.each do |file|
+            @out.puts "    #{File.basename("#{file[:id]}.md").ljust(width)}  #{file[:title]}"
+          end
+        end
+      end
+
+      def print_loose_json(dir, files)
+        emit_json(bundle_head(dir).merge(
+          "count" => files.size,
+          "loose" => files.map { |file| stringify(file) }
+        ))
+      end
+    end
+
+    register(Loose)
+  end
+end