okf 1.10.0 → 1.12.0

data/lib/okf/skill/reference/cli.md

@@ -150,7 +150,7 @@ as Ruby regular expressions with `--regexp`/`-e` (an invalid pattern is a usage
 error, exit 2). `--fuzzy` forgives typos; pairing it with `-e` is a usage error,
 since a pattern is matched literally rather than by edit distance.
 `--in a,b` restricts the searched fields (title, id, tags, type, description,
-body); the shared `--type/--area/--tag` filters narrow the candidates *first*,
+body); the shared `--type/--dir/--tag` filters narrow the candidates *first*,
 so a search scoped by what `index` taught you stays surgical.
 
 **The default is exact, so an exact query means what it looks like.** A phrase in
@@ -250,8 +250,8 @@ consuming agent is the fuzzy layer — when terms miss, learn the bundle's
 vocabulary from `tags`/`types` and re-ask in its own words, rather than
 hammering synonyms or reaching for `--fuzzy` before you have looked. Advisory read: **exit 0 even with zero matches**.
 JSON, plain-dir mode: `{ bundle, query, count, matches: [{ id, title, type,
-area, tags, matched, score, snippet }] }`. Registry mode — any leading @ref,
-`@all` among them — swaps the envelope: `{ bundles: [{ slug, dir }, …],
+dir, top_dir, tags, matched, score, snippet }] }`. Registry mode — any leading @ref,
+`@all` or a `@group` among them (a group fans out to its member bundles) — swaps the envelope: `{ bundles: [{ slug, dir }, …],
 query, count, matches: [{ slug, id, … }] }`; a parser must branch on which form
 it called. The head maps each slug to its dir once, so a row resolves to
 `<dir>/<id>.md` without a second lookup and without repeating a path per row.
@@ -273,8 +273,30 @@ there, its child directories, and the concept listing. Run it first when picking
 an existing bundle: it is the cheapest high-signal orientation, and it surfaces
 enumeration drift a grep can't (you can't grep for a listing entry that is *missing*).
 
-`--area A` narrows to a directory and is **repeatable** — `--area model --area
-format` shows both; `root` names the bundle root. `--no-body` drops the prose to a
+`--dir PATH` narrows to a directory **and everything below it**, and is
+**repeatable** — `--dir model --dir format` shows both; `root` (or `.`) names the
+bundle root. A `--dir` also brings the **chain from the root down to it**, so a branch is
+never shown adrift of the authored context that says what it is — the root
+`index.md`'s prose first among it. Those rows print with a leading `↑` and carry
+`ancestor: true`; `--no-ancestors` drops them. Ascent and descent are separate
+axes, so `--depth` never bounds the chain: `--dir X --depth 0` is X alone, plus
+how you get to X. A `--dir` that names nothing gains no chain — a lone root row
+would read as a partial answer to a query that matched nothing.
+
+`--depth N` bounds how far below the starting point the map reaches
+(the `--dir` when one is given, else the bundle root), counted **relatively**:
+`--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.
+
+**On a bundle of any size the map is unreadable whole** — every directory is a
+section, and even `--no-body` keeps one listing row per *concept* — so narrow
+rather than paging it: `okf dirs` is the orientation, `--dir <branch> --depth 1`
+is the step down into it,
+and `--except body,listing` on top of either is the lean JSON skeleton. Full
+`index` output on a few hundred concepts runs to hundreds of KB; the same map at
+`--depth 1` is a couple of KB.
+
+`--no-body` drops the prose to a
 skeleton (headers, rollups, child pointers). For a directory that has concepts but
 **no `index.md`**, the listing is **synthesized** from the concepts' descriptions
 and tagged `(no index.md)` — §6 explicitly permits synthesizing a map on the fly.
@@ -283,7 +305,49 @@ It is a **read view**: advisory, always exit 0. A synthesized directory is a
 *signal* (a map worth writing), never a defect — `index` emits no lint findings and
 never fails a bundle. JSON: `{ bundle, count, directories: [{ dir, index_path,
 present, synthesized, count, types, tags, subdirs, body, listing: [{ id, title,
-description, type, tags }] }] }`.
+description, type, tags }] }] }` — `ancestor` marks a row that is there to place
+the branch rather than to answer about it.
+
+## dirs — the bundle's clusters and their sizes
+
+`okf dirs <dir>` lists every directory the bundle has — the ones holding
+concepts, the ones carrying an `index.md`, and the empty intermediates that only
+exist to connect the tree — with the number of concepts living **directly** in
+each and the number in its **subtree**. A cluster *is* a directory here, so this
+is the view that tells you what `--dir` can be pointed at and how much sits
+behind each choice.
+
+Two numbers, because one cannot answer the question. `count` is direct, so the
+column sums to the bundle's concept total and a dir holding only sub-directories
+reads `0` rather than a hidden rollup. `subtree` is defined as *exactly what
+`--dir <that row>` returns*, so 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). Without it a truncated listing is all zeroes at the top of a deep tree,
+which is where you most need to know where the mass is. The human table shows the
+second column only where some dir actually nests.
+
+`--dir PATH` (repeatable) narrows to a directory and its subtree, and brings the
+**chain up to the root** with it so the branch is placed rather than shown
+adrift — those rows are marked `↑`, carry `ancestor: true`, and stay out of
+`total` (`--no-ancestors` drops them). `--depth N` keeps only N levels below the
+starting point — the `--dir` when one is given,
+the bundle root otherwise. Relative, not absolute, so `--dir a/b --depth 1`
+reads "a/b and one level under it" without your first working out how deep `a/b`
+is. `--depth 0` is the starting point alone. A `--depth` that is not a whole
+number is a usage error (exit 2).
+
+**This is the first command to run on a bundle you do not know** — the same first
+move [SKILL.md](../SKILL.md) prescribes. `okf dirs <dir>` is one row per
+directory, so its size tracks the tree rather than the concept count: it tells
+you the shape and where the weight sits, `--depth 1` trims it further on a deep
+bundle, and you then descend with `okf index --dir`, one level at a time.
+
+The root prints `(root)` and stores `.` — the split every grouped view keeps, so
+a table and its `--json` never disagree about which spelling is the data. JSON:
+`{ bundle, total, count, dirs: [{ dir, ancestor, count, subtree, subdirs }] }`,
+root first. `count` is rows printed, chain included; `total` sums the direct
+counts of the rows you actually asked for, which is what keeps a row's `subtree`
+equal to the `total` that `--dir` on that row returns.
 
 ## catalog / files / tags / types / stats — the server views, as text
 
@@ -293,15 +357,16 @@ All are advisory reads (exit 0) sharing one data source (per-concept metadata pl
 in/out link degree). Add `--json` to any for a machine substrate.
 
 - **`catalog`** — every concept with its metadata (type, status, tags, timestamp,
-  in/out link degree, description), grouped by top-level area. The "what's here, in
+  in/out link degree, description), grouped by top-level dir (`dir` on every row
+  carries the full path, `top_dir` the first segment). The "what's here, in
   detail" view. JSON: `{ bundle, count, concepts: [{ id, title, type, description,
-  tags, timestamp, status, backlog_ref, dir, area, links_out, links_in }] }`.
+  tags, timestamp, status, backlog_ref, dir, top_dir, links_out, links_in }] }`.
 - **`files`** — the folder tree: each concept's filename + title, grouped by
   directory. The "how it's organised" view. JSON: `{ bundle, count, files: [{ path,
   id, dir, type, title, description }] }`.
 - **`tags`** — every tag with the concepts that carry it, ordered by count
   descending. The "what themes dominate" view. JSON: `{ bundle, count, tags: [{ tag,
-  count, concepts: [id, …] }] }`. `--by type|area` regroups the list per concept
+  count, concepts: [id, …] }] }`. `--by type|dir` regroups the list per concept
   dimension with **within-group** counts (a tag spanning groups appears in each);
   each row also carries the tag's **total** across the narrowed set, printed
   `count/total` when they differ — so a tag's locality reads per row (a plain
@@ -313,18 +378,32 @@ in/out link degree). Add `--json` to any for a machine substrate.
 - **`types`** — every type with the concepts that carry it, ordered by count
   descending. The "what kinds of knowledge" view. JSON: `{ bundle, count, types:
   [{ type, count, concepts: [id, …] }] }`.
-- **`stats`** — bundle rollups: concept / area / type / cross-link / distinct-tag
-  totals plus per-type and per-area breakdowns. The "shape at a glance" view. JSON:
-  `{ bundle, concepts, areas, concept_types, cross_links, distinct_tags, by_type, by_area }`.
+- **`stats`** — bundle rollups: concept / dir / type / cross-link / distinct-tag
+  totals plus per-type and per-dir breakdowns. The "shape at a glance" view. JSON:
+  `{ bundle, concepts, dirs, top_dirs, concept_types, cross_links, distinct_tags,
+  by_type, by_dir, by_top_dir }` (`top_dirs`/`by_top_dir` are the first-segment
+  rollup). `dirs`/`by_dir` cover every directory `okf dirs`
+  lists — counts are direct, so a directory holding nothing itself is present at
+  `0` rather than missing, and `by_dir.keys` is a complete list of what `--dir`
+  can address.
 
 The four list views narrow with the same filters the browser panels offer —
-`--type TYPE`, `--area AREA`, `--tag TAG`; each takes the ones orthogonal to
-itself (`tags` can't filter by tag). Matching is case-insensitive and exact; a
-concept at the bundle root lives in the `(root)` area, which `--area` also accepts
-as plain `root` (no shell quoting). A filter that matches nothing is an empty view,
-not an error: `okf tags <dir> --area billing --json` answers "which tags does the
-billing area use?", `okf catalog <dir> --tag auth` answers "what carries the auth
-tag?".
+`--type TYPE`, `--dir PATH`, `--tag TAG`; each takes the ones orthogonal to
+itself (`tags` can't filter by tag). Matching is case-insensitive; `--type` and
+`--tag` are exact, `--dir` takes the named directory **and everything below it**
+(`--dir platform` reaches `platform/services/api`). A concept at the bundle root
+lives in `.`, which `--dir` also accepts as plain `root` (no shell quoting). A
+filter that matches nothing is an empty view, not an error: `okf tags <dir> --dir
+billing --json` answers "which tags does the billing cluster use?",
+`okf catalog <dir> --tag auth` answers "what carries the auth tag?".
+
+**`--area` is deprecated.** It still works — matching the *first path segment*
+only, its old behavior unchanged — and prints `warning: --area is deprecated, use
+--dir` on stderr (stdout stays clean, so a `--json` consumer is unaffected). Same
+for `tags --by area`. Both go in a later release; write `--dir` in anything new.
+On `index` it combines with neither `--depth` nor `--dir` — exit 2, because it is
+*exact* and both of those select a range, so the pair used to return the area
+plus whatever the other flag selected: an answer to neither question.
 
 Reach for `stats` first to size a bundle, `catalog`/`files` to enumerate it, `tags`
 to find thematic clusters — all without standing up the server.
@@ -340,10 +419,13 @@ in a body render as diagrams, and a click (or tap) opens the diagram full
 screen with drag-to-pan and wheel/pinch zoom. Concepts render as nodes
 coloured by `type` and sized by degree, links as edges, with a detail panel
 (rendered markdown, "Links to" / "Linked from" backlinks), layout switching,
-type/area/tag filters on every view, and search. The authored layer is in the
+type/dir/tag filters on every view (the dir chips take a directory *and* its
+subtree, the same rule `--dir` uses), and search. Cluster mode groups the
+concepts into one box per directory, nested to a depth picked beside the layout
+select — depth 1 is the flat view, and a flat bundle is offered no control. The authored layer is in the
 UI too: the Files view carries **Files | Indexes** tabs — the Indexes tab
 lists the log first (the chronological index), then every `index.md` — and
-folder nodes in file-tree mode and area boxes in cluster mode open a
+folder nodes in file-tree mode and directory boxes in cluster mode open a
 directory's §6 map in the inspector (authored, or synthesized when none
 exists). Links to an `index.md`, `log.md`, or bare directory navigate instead
 of dead-ending, and the log is fetched fresh on every read, so a
@@ -360,20 +442,38 @@ page listing the hosted bundles, so a stale bookmark after a rename gets a way
 home. With **no** dir it serves the *persistent registry*, a plain JSON file
 under `$OKF_HOME` (default `~/.okf`), managed by the
 `okf registry` umbrella — like git's `remote` family, and split by what each
-verb keys on. **Entry verbs** take a path: `okf registry set <dir>` adds it
+verb keys on.
+**`okf registry init`** creates a *project-local* registry instead: a
+`.okf-registry.json` in the current directory, which okf discovers by walking up
+from the working directory and uses in place of the global one while you are
+inside its tree (the nearest wins, so nested registries resolve nearest-first).
+Every registry op — and every `@slug` — then resolves through it, so a bare
+`okf server` inside a repo serves that repo's bundles with no `$OKF_HOME` setup;
+`okf registry list` names the local file it found. `OKF_NO_DISCOVERY=1` forces
+the global registry — the escape hatch for a fixed-cwd caller (CI, a tool). A
+local registry stores **portable** paths: a bundle inside its tree is written
+relative to the `.okf-registry.json`, so committing the file lets it travel with
+the repo (a checkout elsewhere, a container mounting it) and resolve unchanged;
+a bundle outside the tree stays absolute, since it cannot travel. Paths still read
+back absolute wherever the CLI reports them.
+**Entry verbs** take a path: `okf registry set <dir>` adds it
 (slug from the basename, or `--as`, which errors on a collision; `--default`
 puts it first), and because the entry is keyed by path, `set` on an
 already-registered dir updates it in place — refreshing its title, and renaming
-it when `--as` is given. `okf registry del <dir|@slug>` removes one — by name, so an entry whose
-directory is already gone still deletes. Slug *or* dir, never both readings at
+it when `--as` is given. `okf registry del <dir|@slug>` removes a bundle *or* a group — by name, so an
+entry whose directory is already gone still deletes, and removing a bundle
+**cascade-drops** it from every group that named it (a group emptied that way is
+deleted). Slug *or* dir, never both readings at
 once: an argument with a `/` in it names a location and only a location, so
 `del ./notes` refuses when no entry points there rather than stripping to the
 slug `notes` and deleting a bundle somewhere else entirely.
 <!-- rule:okf-registry-del-path-or-slug -->
 **Slug verbs** take the name — bare, or as an `@slug`: `okf registry default <@slug>`
-chooses which bundle `/` opens **by moving that entry to the front**, and
-`okf registry rename <@slug> <new>` renames a slug (mount path and switcher
-name) — `<new>` is a name being minted, so it is never a ref. The registry is ordered and **the first entry still on disk is the
+chooses which bundle `/` opens **by moving that entry to the front** (a group is
+refused — the default is one bundle), and
+`okf registry rename <@slug> <new>` renames a bundle *or* group slug (mount path
+and switcher name), **cascading** the new name into every group's member list —
+`<new>` is a name being minted, so it is never a ref. The registry is ordered and **the first entry still on disk is the
 default** — that is the whole rule, so the first bundle you register is the
 default until you move another one, a rename keeps its position, and a `del`
 promotes whatever is next. A vanished directory is stepped over (the server
@@ -382,11 +482,25 @@ cannot open one, so starring it would name a bundle `/` never serves), and
 gives a directory that is not there. The file is hand-editable and reorders
 visibly, which is the point: there is no stored slug that can dangle.
 <!-- rule:okf-registry-default-position -->
+**Group verbs** name a *set* of bundles under one slug — a durable subset for the
+two verbs that take several bundles. `okf registry group <slug> <@member…>`
+creates a group, or adds members to one (a union); members are bundle *or* group
+slugs, so groups nest. A group shares the slug namespace with bundles (a slug
+names one *or* the other, never both), `all` stays reserved, and a member set that
+would make the group reach itself is refused. `okf registry ungroup <slug>
+<@member…>` removes members; emptying a group deletes it. A group resolves,
+recursively and path-deduped, to its bundle leaves — which **only `okf search`
+and `okf server` consume**: every single-bundle verb (`lint`, `index`, …) refuses
+a `@group` with exit 2, the same rule that refuses a second bundle. `@all` is
+unchanged — it still names every registered *bundle*, groups being named subsets
+of that.
 `okf registry list` (or a bare
 `okf registry`) stars the default and flags vanished dirs `(missing)` — the
-server skips those with a note; `--json` answers
+server skips those with a note — and lists any groups with their members and
+resolved leaf count; `--json` answers
 `{ registry: <file>, count, bundles: [{ slug, title, dir, mount, default,
-missing }] }`, naming the file it read so a `$OKF_HOME` mismatch is visible. The hub roster is a
+missing }], groups: [{ slug, members, resolved }] }`, naming the file it read so a
+`$OKF_HOME` mismatch is visible. The hub roster is a
 **boot-time snapshot**: restart `okf server` after registry changes. Behind a
 hub the page gains a **bundle switcher** (⌘/Ctrl-K, or the rail button with its
 bundle-count badge): the current bundle is pinned, the default chipped; ⏎
@@ -399,7 +513,10 @@ them all with the registry's first entry still on disk at `/` — the way to kee
 several bundles a keystroke apart without re-passing paths.
 `okf server @a @b` serves a registry subset, each mounted under its registered
 slug — but as with any dirs-given run, the *first argument* lands at `/`; the
-registry's own order applies only to the bundle-less run.
+registry's own order applies only to the bundle-less run. A `@group` argument
+fans out to its member bundles in the same way (`okf server @backend`), its first
+member landing at `/`; `okf search @group <term…>` merges the group's members
+into one ranking, exactly as naming them individually would.
 
 **Trust boundary:** the page renders each fetched markdown body through
 DOMPurify and escapes everything it inlines (every `<` in the graph data is
@@ -440,8 +557,30 @@ only when the task truly consumes every body; for one question, the
 
 `--hubs` swaps the dump for the **inbound ranking**: every concept with at
 least one inbound link, ranked by inbound degree, each with its links grouped
-by *source area* (`core/status  ×3   flows 2, billing 1`) — the evidence for
+by *source top-level dir* (`core/status  ×3   flows 2, billing 1`) — the evidence for
 [refine](../playbooks/refine.md)'s hub origin test ("is this hub well-homed?").
 A source at the bundle root counts under `(root)`. JSON: `{ bundle, count,
-hubs: [{ id, area, inbound, by_area: { <area>: n } }] }`. Advisory read, exit 0;
+hubs: [{ id, top_dir, inbound, by_top_dir: { <top_dir>: n } }] }`. Advisory read, exit 0;
 `--minimal`/`--no-body` shape node payloads and change nothing here.
+
+`--traffic` asks the same question one grain coarser: **directories**, not
+concepts. Every concept collapses into the directory it lives in and every link
+between two directories collapses into one weighted arc, so a bundle's wiring
+becomes a table you can read — measured on one 47-concept bundle, 227 links
+collapsed into 50 arcs, of which the fitted cut draws 22. Each row carries the
+directory's traffic split three ways
+(`internal` / `out` / `in`) plus **cohesion**, its internal share of the total:
+the evidence for [refine](../playbooks/refine.md)'s container test, where
+`--hubs` only ever answered about concepts. Rows lead with the lowest cohesion,
+so the directories with a case to answer come first, and a directory with no
+traffic at all prints `—` rather than a `0%` it did not earn.
+
+`--cut N` is the least arc weight drawn. It defaults to a value **fitted to the
+bundle** — enough arcs for roughly 1.5 per directory, floored at 8 — because a
+fixed weight cannot serve both ends: measured at weight 3 across ten bundles it
+left 2 arcs on one and 136 on another. The JSON says which you got. Cohesion is
+computed over *every* arc and never the drawn ones, so tightening the cut
+changes the picture and never the evidence. JSON: `{ bundle, cut, fitted, dirs:
+[{ dir, parent, count, subtree, internal, out, in, cohesion }], arcs: [{ source,
+target, weight }], total_arcs }` — a fraction of the full dump (2.6 KB against
+27 KB on that bundle), and the shape rather than the contents. Advisory, exit 0.

data/lib/okf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OKF
-  VERSION = "1.10.0"
+  VERSION = "1.12.0"
 end

data/lib/okf.rb

@@ -25,6 +25,15 @@ module OKF
     value.respond_to?(:empty?) ? value.empty? : false
   end
 
+  # The directory a concept lives in, derived from its §2 id: the id *is* the
+  # path minus `.md`, so putting the suffix back and taking the dirname is the
+  # definition rather than a parse of it. One home for it because three views
+  # answer with a `dir` — the catalog, the search rows, the linter's per-directory
+  # checks — and a rule spelled three times is three things to keep in step.
+  def self.dir_of(id)
+    File.dirname("#{id}.md")
+  end
+
   require "okf/version"
 
   # ── kernel: cross-cutting primitives ──
@@ -39,6 +48,7 @@ module OKF
   require "okf/concept"
   require "okf/bundle"
   require "okf/bundle/graph"
+  require "okf/bundle/skeleton"
   require "okf/bundle/search"
   # These two lines ARE the engine preference order. Each engine registers itself
   # at load, `Search.engines` is registration order, and the router walks it after

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -54,11 +54,22 @@ dependencies:
 description: |
   OKF (Open Knowledge Format) is portable knowledge: Markdown files with YAML
   frontmatter that both humans and agents read from one source. This gem is the
-  Ruby-native way to work with it. Its companion agent skill authors and curates
-  a bundle; the `okf` command-line tool validates the result for v0.1 (§9)
-  conformance, lints its curation quality, and serves it as an interactive graph
-  (a mountable Rack app). The same validate, lint, and graph run in-process
-  through a library API (OKF::Bundle and friends).
+  Ruby-native way to work with it.
+
+  Its companion agent skill authors and curates a bundle. The `okf` command-line
+  tool validates the result for v0.1 (§9) conformance, lints its curation
+  quality, and answers questions about it: ranked full-text search, and a
+  progressive-disclosure map that reads a large bundle a directory at a time
+  rather than loading it whole. `okf server` opens it as an interactive
+  knowledge graph and `okf render` bakes that same page into one self-contained
+  HTML file you can host anywhere. A per-user registry names your bundles, so
+  every verb reaches them by @slug from any directory and one search can span
+  them all.
+
+  Everything the CLI does also runs in-process through a library API
+  (OKF::Bundle and friends), and the graph server is a mountable Rack app. It
+  adds no service to your stack: rack, webrick and minifts are the only runtime
+  dependencies, and it runs on every Ruby since 2.4.
 email:
 - rodrigo.serradura@gmail.com
 executables:
@@ -82,12 +93,14 @@ files:
 - lib/okf/bundle/search.rb
 - lib/okf/bundle/search/index.rb
 - lib/okf/bundle/search/scan.rb
+- lib/okf/bundle/skeleton.rb
 - lib/okf/bundle/validator.rb
 - lib/okf/bundle/validator/result.rb
 - lib/okf/bundle/writer.rb
 - lib/okf/cli.rb
 - lib/okf/cli/catalog.rb
 - lib/okf/cli/command.rb
+- lib/okf/cli/dirs.rb
 - lib/okf/cli/files.rb
 - lib/okf/cli/graph.rb
 - lib/okf/cli/index.rb
@@ -160,6 +173,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: 'The complete toolkit for the Open Knowledge Format: an agent skill, a CLI
-  and library, and a live knowledge graph. 100% local.'
+summary: 'The complete Open Knowledge Format toolkit: an agent skill, a CLI and library,
+  ranked search, and a live knowledge graph. 100% local.'
 test_files: []