okf dirs

When to use it

• As the first read on a bundle you do not know. One row per directory stays small whether the bundle holds thirty concepts or three thousand, so it orients you before you open anything.
• To find where the mass sits before a consume or a refine pass: --dir adds a subtree count, so you can see which branch carries the weight.
• To plan a descent. Name the branch here, then open it with okf index --dir. The skill leads with okf dirs for exactly this reason: dirs emits one row per directory where index emits one row per concept, so the two scale with different things.

How it works

okf dirs <dir|@slug> lists every directory in the bundle with the number of concepts living directly in it, root first and the total last. The count is direct, never a rollup, so a directory holding nothing but sub-directories reads 0 rather than a hidden sum, and the column adds up to the bundle's concept count exactly. Every directory the tree has appears, including the empty intermediates that exist only to connect one branch to another, because each is still a directory you can address. JSON shape: { bundle, total, count, dirs: [{ dir, count, subdirs }] }.

Three flags shape the view:

• --dir PATH (repeatable) narrows to one directory and everything below it, and adds a subtree count per row: the concepts at or below that directory. The subtree number is defined as exactly what --dir PATH itself returns, so the count and the flag can never disagree. A concept matches when its directory is the path or sits below it, so --dir platform reaches platform/services/api. root is the unquoted spelling of ., the bundle root alone; since 1.13.0 a bundle that actually has a root/ directory keeps it addressable, because the real directory wins over the alias. Matching folds case, and a trailing slash on the label the views print is accepted.
• --depth N keeps only that many directory levels below the starting point, where the starting point is the --dir when one is given and the bundle root otherwise. It is relative, not absolute, so --dir a/b --depth 1 reads "a/b and one level under it" with no need to know how deep a/b already is. --depth 0 is the starting point alone. Anything but a whole number is a usage error (exit 2).
• --fields / --except project the JSON down to the properties you want, over the row shape above.

With --dir, the chain of ancestors up to the root is shown by default so the branch is never adrift of the context that names it; --no-ancestors drops it. Ascent and descent are separate axes, so --depth never bounds that chain.

Try it

okf dirs docs/

Dirs — docs

  Dir           Concepts
  (root)               3
  cli                 15
  skill                9
  guides               3

  4 dirs · 30 concepts

Find where the weight sits, with subtree counts:

okf dirs docs/ --dir cli --depth 1

The subtree column then reads the concepts at or below each row, and the deprecated first-segment rollup never enters it. To walk a large tree a level at a time, raise --depth one step at a time; to project the JSON, add --fields dir,count,subtree.

Pitfalls

• The count is direct, not a subtree. A parent directory's row counts only the concepts directly in it, which is why the column sums to the total. When you want "how much is at or below here", reach for --dir and read the subtree count.
• Empty intermediate directories read 0, not nothing. A directory that holds only sub-directories still appears, because it is still one --dir can address. That is information, not noise.
• --depth is relative to the starting point. --dir a/b --depth 1 is "a/b and one level under it", not "the second level of the whole tree". Ascent to the root is a separate axis and is not bounded by --depth.
• dirs speaks the full path. The row platform/services is the whole directory, not a first segment. The deprecated --area / --by area only ever saw the first segment; the full-path world is --dir and stats's by_dir.