okf 1.10.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48baf9115b68a210ae385dbddc1a9956dfd16f5424614629db9fd43ff7b40fc4
-  data.tar.gz: 32824378ebd2856cf1272cc9bfd75b2d989ef87788f38759e794acf6c4594b99
+  metadata.gz: 9a83101e62e3b3bc97d7351580d50ecc017be391a5edbde2e8f52388de529111
+  data.tar.gz: 040be5295642da56cbeed342424872469d1c2b15efcb1b477f10076d7c90fafc
 SHA512:
-  metadata.gz: 8add8ee3eb50b29bb7169544a27135d8221a54bcd2f1a5b98c221ec90a3ac1e836fa2da76456da889f7b396958835ac4ee39cf308a4ea9be88c47e2d65b9636c
-  data.tar.gz: 8a84bfd874afff0cdf002f6fcff57df2042e6f04598d4ce41553bd3bde800e8645568008b5ad8491c89d1d0317477bd54c3cd7d6ab576dc2535fb722517fa43d
+  metadata.gz: 47fb84d8dffc04eee30eb65adfaca756ae43315e2d152e62692084a5bd04c6a7992529d243b2375412a8339a55db891c3ae18d679e171d5709e9426b93686047
+  data.tar.gz: 30390e1eecc1570b28531c374b21200309630aad87f821a7c3f25b631ca5285e03b91baab9048f69127931a09368da1ab38a089fc9bc25473c05da3c0fadfe2b

data/CHANGELOG.md

@@ -5,6 +5,299 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.12.0] - 2026-07-24
+
+### Added
+
+- **`okf graph --traffic`** — the link graph read one grain coarser. `--hubs`
+  measures concepts, but the refine playbook's directory judgements ("does this
+  directory prune? a concern, or a container?") had nothing measured at their
+  grain. `--traffic` collapses each concept into its directory and the links
+  between two directories into one weighted arc, so every row carries its
+  internal / out / in traffic and a **cohesion** — its internal share of that
+  total. That is cohesion versus coupling on a knowledge tree: near-zero cohesion
+  under heavy inbound is a shared vocabulary doing its job, heavy outbound with
+  nothing back is a projection wearing a directory. The rows sort by cohesion
+  ascending, 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. The arc
+  **cut** is fitted to the bundle, not fixed — at weight 3, ten bundles ranged
+  from 2 arcs to 136 — and `--cut N` overrides it; cohesion is computed over
+  *every* arc regardless, so narrowing the drawn picture never moves the
+  evidence. JSON: `{ bundle, cut, fitted, dirs, arcs, total_arcs }`. The pure
+  model underneath is `Bundle::Skeleton` — concepts folded to directories, links
+  to weighted arcs, every edge tagged with the cut it survives (a local-degree
+  sparsifier, union rule, so no linked concept is ever stranded) — and it does no
+  I/O and draws nothing: it names a cut rather than taking one, so both the graph
+  page and the CLI narrow the same emission their own way.
+- **The graph page draws links in three amounts, and opens dense on its spine.**
+  227 links over 47 concepts at degree 9.7 is unreadable because of its arrows,
+  not its dots — so links become a layer: **every** link, the **spine** (each
+  concept's strongest edge — the Skeleton's `keep_at===0` set, chosen so it
+  touches every linked concept), or **none**, with a selected concept's own links
+  always shown in full. A dense bundle now opens on its spine rather than greeting
+  the reader with the thicket; the trigger is undirected degree above a floor set
+  between a tree's ~2 and the 9.7 that drove it, and `--map` overrides to none
+  with the directories boxed. Above 800 edges the first layout runs on the spine
+  alone and the rest arrive a frame later with no re-layout — **6.25 s → 3.29 s**
+  on 414 concepts, nothing on screen moving. Proven in both render modes on a
+  committed 110-concept / 880-link fixture, the only one over both floors.
+- **Registry groups — a named, recursive set of bundles.** A group is a registry
+  slug that names a list of members (bundle *or* group slugs, so they nest) and
+  resolves recursively, path-deduped, to its bundle leaves. `okf registry group
+  <slug> <@member…>` creates one or adds to it, `ungroup` removes members (and
+  emptying a group deletes it), and `del`/`rename` now span a group slug too —
+  one name cascades across every member list, one `del` cascade-drops the slug and
+  deletes any group it empties. Groups live in their own list in the registry
+  JSON, so the first-is-default rule and the `File.directory?` guards never meet a
+  pathless entry. `okf search @backend` merges the members into one ranking and
+  `okf server @backend` mounts each (the first at `/`), both skipping a vanished
+  member with a note, exactly as `@all` does. Every single-bundle verb **refuses**
+  a `@group` (exit 2) — the same rule that refuses a second bundle, through the
+  same `resolve_registered` seam.
+- **`okf registry init`** — create a project-local `.okf-registry.json` in the
+  current directory. Once it exists, okf discovers it by walking up from the
+  working directory, and every registry operation — and every `@slug` — resolves
+  through it in place of the global `$OKF_HOME` registry, so a bare `okf server`
+  inside a repo serves that repo's bundles with no global setup. The nearest one
+  on the path wins (nested registries resolve nearest-first), `okf registry list`
+  names the local file it found, and `OKF_NO_DISCOVERY=1` forces the global one —
+  the escape hatch for a fixed-cwd caller (CI, a tool).
+- **A local registry stores portable, relative paths.** A bundle inside the
+  registry's own tree is written relative to the `.okf-registry.json`, so the file
+  can be committed and travels with the repo — a checkout on another machine, or a
+  container that mounts it, resolves the same bundles unchanged. A bundle outside
+  the tree keeps an absolute path (it cannot travel). Paths still read back
+  absolute everywhere the CLI reports them; the relative form lives only on disk,
+  and an existing absolute local entry migrates to relative on its next write. The
+  global `$OKF_HOME` registry is unchanged — it stores absolute paths as before.
+
+### Changed
+
+- **The derived `area` field is renamed `top_dir`** — the first-path-segment
+  rollup the catalog, search, `stats`, and `graph --hubs` carry. `area` was never
+  the OKF spec's word (the spec speaks only of `dir`), so the rollup now names
+  itself in the spec's vocabulary: it is the `dir` at the top level. The `--json`
+  keys move with it — catalog/search rows carry `top_dir` in place of `area`,
+  `stats` emits `top_dirs`/`by_top_dir`, and `graph --hubs` emits
+  `top_dir`/`by_top_dir`. The **deprecated `--area`/`--by area` input flags are
+  unchanged** — they still warn and map to `--dir`/`--by dir`, and now source the
+  renamed field internally. No behavior changes; the well-homed-hub numbers are
+  identical.
+
+### Fixed
+
+- **A local-registry server preserves its relative-path anchor across a
+  re-open.** The hub re-read its boot registry with `OKF::Registry.new(path)`,
+  which drops the `relative_base` a discovered `.okf-registry.json` carries — so
+  on a project-local server the Bundles panel matched each mounted bundle's
+  absolute root against the re-read entry's *relative* path, missed, and drew
+  every in-tree bundle as "folder is gone", while a browser add flattened the new
+  bundle to an absolute path, undoing the portability relative storage exists for.
+  `Registry#reopen` re-reads the same file anchored the same way, and both hub
+  re-open sites use it.
+
+## [1.11.0] - 2026-07-22
+
+### Added
+
+- **`okf dirs <dir|@slug> [--json]`** — the bundle's directories (its clusters)
+  with the number of concepts living **directly** in each, root first and the
+  total last. Every dir the tree has, including the empty intermediates that
+  exist only to connect it — a dir holding nothing but sub-directories reads
+  `0`, not a hidden rollup, so the column sums to the bundle's concept count.
+  JSON: `{ bundle, total, count, dirs: [{ dir, count, subdirs }] }`.
+- **`--depth N` on `index` and `dirs`** — how many directory levels below the
+  starting point to keep, where the starting point is the `--dir` when one is
+  given and the bundle root otherwise. Relative rather than absolute, so
+  `--dir a/b --depth 1` reads "a/b and one level under it" without first working
+  out how deep `a/b` is, and the two flags walk a tree a level at a time.
+  `--depth 0` is the starting point alone; anything but a whole number is a
+  usage error (exit 2). This is what makes `index` usable at scale — every
+  directory in it is a section, so a few hundred concepts is a map nobody reads
+  whole. On one 414-concept bundle `index --no-body` went 12.5 KB → 1.3 KB at
+  `--depth 1`, and `index --json` 313 KB → 2.8 KB with `--depth 1 --except
+  body,listing`.
+- **`--dir` on `index` and `dirs` brings the chain up to the root with 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
+  `↑`, carry `ancestor: true`, and stay out of `total`; `--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, since a lone root row would read as a partial
+  answer to a query that in fact matched nothing.
+- **`dirs` gains `--dir` (repeatable) and a `subtree` count** per row: the
+  concepts at or below that directory, defined as exactly what `--dir` on the
+  row returns, so the number and the flag can never disagree. Without it a
+  truncated listing is all zeroes at the top of a deep tree — which is where
+  "where is the mass?" is actually asked. The human table shows the column only
+  where some directory nests; `--json` always carries it.
+- **`--dir PATH`** joins the shared filter set on `search`, `catalog`, `files`,
+  `types` and `tags`, and `index` gains it as a repeatable selector. One rule:
+  a concept matches when its dir *is* the path or sits below it — so `--dir
+  platform` reaches `platform/services/api`, `--dir platform/services` narrows,
+  and `--dir .` means the root alone with no special case. `root` is the
+  unquoted spelling of `.`; matching folds case.
+- **`tags --by dir`** cuts the tag index by the whole directory path, where
+  `--by area` only ever saw the first segment.
+- **`stats` gains `dirs` and `by_dir`** (the full-path cut, direct counts), and
+  its human breakdown now reads **By dir**. Both are read off the same map `okf
+  dirs` lists and `--dir` is answered against, so the two verbs cannot report a
+  different number of directories — a directory holding nothing directly appears
+  at `0` rather than being dropped, since it is still one `--dir` addresses.
+- **Search rows carry `dir`** — the full path, `.` at the root — beside the
+  first-segment `area` they already had.
+- **`dirs` takes `--fields`/`--except`** like the other list views, over the row
+  shape it already declared.
+- **A single-bundle `okf server` answers `GET /search?q=`.** The route was the
+  hub's alone — conceived as the *cross-bundle* one — which left `okf server
+  ./docs` with a ⌘K palette that could find nothing, though one bundle is a legal
+  one-element set. `App` owns the payload and the hub calls it, so the shape is
+  defined once; a row from a single-bundle server carries no `slug`, which is how
+  it avoids answering as if it were a set. A static `okf render` still advertises
+  no endpoint: there is no server behind it to ask.
+  - **The route always answers; advertising it is the caller's call.** The page
+    resolves the endpoint *relative to the URL the reader is on*, so only whoever
+    mounted the app knows what to call it: `okf server` mounts at the root and
+    passes `search`, while `App.new(folder)` on its own advertises nothing, since
+    a default would point an app mounted at `/knowledge` back at its host's root.
+- **The search index is built once and held.** Every request used to rebuild the
+  whole corpus — measured 1.45 s per search on a 414-concept bundle, flat across
+  repeats, with the build ~95% of it. `Search.prepare` holds a corpus (documents,
+  the key→concept map, the built index) and `Search.with` queries it: **0.016 –
+  0.052 s** per search, with the 1.39 s build moved into boot, where `okf server`
+  warms it deliberately. An engine opts in by exposing `prepare`; the scan
+  declares none and is handed none, so no engine or addon had to change. The
+  trade is staleness — a corpus is a snapshot, like the graph — and the hub drops
+  its corpus on any registry write, since a held index outliving the set it was
+  built from is a wrong answer rather than a slow one.
+- **`⌥ drag` moves a cluster box**, and is listed in the `?` sheet.
+
+### Changed
+
+- **A bundle is named by its slug, everywhere it is chosen.** The ⌘K switcher,
+  the Bundles panel and the hub's `/b/` page all led with the derived
+  `parent/dir` label and left the slug in muted grey beside it — the address in
+  the name's place, when a bundle is addressed by `@okf-gem` and `/b/okf-gem/`.
+  Rows now carry `@slug` as the name and the folder as the fact under it, shown
+  only where it is not the name repeated. `/b/` drops the short label outright:
+  it only ever stood in for the full path, which is on the row already.
+- **A `.okf` directory is labelled by the project that holds it.**
+  `Bundle::Folder.label` reads `repo/.okf` as `repo`. The `parent/dir` pair
+  exists because a bundle directory's own name is rarely unique — except when it
+  is `.okf`, the conventional container, and then a registry of eight projects
+  was eight rows all saying `.okf`. This also reaches `okf registry list` and the
+  default `okf server` title. (A `.okf` with no parent to borrow keeps its own
+  name; that case used to compose into `//.okf`.)
+- **A force layout settles, then moves once.** `animate:true` reads to these
+  engines as "render every tick of the simulation" — the visible bounce, and
+  hundreds of full re-renders for one settle. It is `'end'` now: the same
+  simulation run headless, the nodes moved once into the same final positions.
+  Past 250 nodes even that transition is dropped, because at that size the move
+  itself is the jank.
+- **A cluster box is scenery, not a handle.** Its empty interior is the largest
+  drag target on the canvas, so dragging to look around dragged the *directory*
+  instead of the view — worse the bigger the cluster. It takes `grabbable:false`
+  **and** `pannable:true`: ungrabbable alone stops the box moving, but the node
+  still swallows the drag, and it is `pannable` that hands the gesture to the
+  canvas the way empty background does. `Alt`+drag gives the handle back, since
+  moving a box is a real gesture, just not the constant one — `Alt` rather than
+  `Ctrl`, which on macOS is the system secondary click. A tap still opens the
+  directory's map.
+- **`f` is no longer a shortcut.** A bare letter bound globally fires on every
+  keystroke the page did not route into an input, and fullscreen is not a mode to
+  enter by accident. The button stays and is now the only way in; the shortcut
+  sheet no longer advertises a key nothing is bound to.
+- **The skill names one first move.** It had prescribed three different ones
+  across seven places — SKILL.md, four playbooks and the CLI reference — and that
+  disagreement is the deliberation an agent pays for on every retrieval. Every
+  site now says `okf dirs` first, then `okf index --dir <branch>` to descend,
+  chosen structurally: `dirs` emits one row per *directory* where `index` emits
+  one listing row per *concept* even under `--no-body`, so the two scale with
+  different things.
+
+- **Cluster mode nests.** The graph page grouped concepts into one flat row of
+  boxes, one per *first path segment* — the same lossy projection `--area` was.
+  A cluster is a directory now, and the boxes nest as the directories do, to a
+  depth picked from a select beside the layout one. Depth **1** is the default
+  and draws exactly the old view; a flat bundle is offered no control at all.
+  At depth N every directory of depth ≤ N gets a box (intermediates that hold no
+  concepts of their own included, since they hold sub-boxes), and a concept
+  attaches to its own directory's box truncated to N. The root box still holds
+  direct-root concepts and never nests another. Box ids carry the directory
+  verbatim (`box::platform/services`, `box::.`), so a tap opens that directory's
+  map with no label to unmangle.
+- **The page speaks `dir` too**: the filter group is **Dirs**, listing every
+  directory (not just first segments) and filtering by the same
+  directory-and-below rule `--dir` uses — in the graph, catalog and tags views —
+  and the Stats panel's breakdown is **By dir**, keyed by the whole path.
+
+### Fixed
+
+- **The rail marks Index while the root map is open.** Index is a shortcut into
+  Files, so the two share one `data-view` — and the rail read only that, lighting
+  **Files** on the one screen a reader reached by clicking **Index**. The open
+  file is what distinguishes them, so it is what the rail reads; a *nested*
+  `index.md` is still Files.
+- **`--dir` accepts the label the views print.** `fold_dir` never stripped a
+  trailing slash, while `okf index` labels a row `tables/` — so pasting a printed
+  row back into the flag matched nothing and exited 0, an empty result under a
+  count that agreed with it.
+- **The `--dir` chain keeps its case.** It was walked over case-folded paths and
+  then matched against the map with `include?`, which does not fold, so every
+  ancestor of a directory spelled with a capital vanished from the chain that
+  exists to place the branch.
+- **`--area` with `--depth` or `--dir` is refused (exit 2)** instead of unioning
+  the area with what the other flag selects. The deprecated flag is exact: with
+  `--depth` it names no starting point to be relative to, and with `--dir` one
+  side is exact where the other is a prefix, so the map came back with the area
+  *and* the subtree — an answer to neither question. A deprecated flag that
+  quietly widens is worse than one that is merely old.
+- **A cleared filter no longer leaves a cluster unlaid.** The tiling runs over
+  the visible elements only (fcose throws on a node whose label went
+  `display:none` mid-run), but nothing re-tiled when a filter was later loosened —
+  so concepts hidden when clustering began came back at their pre-cluster
+  coordinates and stretched their box across the canvas. Worst case the filter
+  matched nothing, the layout returned early, and clearing it showed a view
+  nothing had laid out at all.
+- **A palette hit in a single-bundle server no longer 404s or reloads the page.**
+  A row with no `slug` was read as naming a *foreign* bundle, so the href became
+  `../undefined/`, the row rendered an "undefined" chip, and the click took the
+  page-load branch — reloading the whole index to reach a node already on screen.
+  Three sites, one absent field.
+- **A focused form field no longer zooms the page on iOS.** Safari zooms whenever
+  a focused control is under 16px and never zooms back out, so on a phone every
+  `/` left the reader pinching to recover. Keyed on `(max-width:768px)` *or*
+  `(pointer:coarse)`, because neither covers the other — a phone is narrow, a
+  tablet in landscape is not and zooms just the same.
+- **A nested cluster no longer throws when a filter empties it mid-layout.**
+  fcose measures every node it is handed, so hiding nodes while its tiling
+  animation ran threw on a label it could no longer measure. The layout is
+  handed the visible elements only — which is also the right answer, since a
+  hidden concept has no business influencing where the visible ones land.
+- **An intermediate directory box no longer takes its branch off the canvas.**
+  The empty-box rule read a compound's direct children, and a box holding only
+  sub-boxes has none, so it always counted as empty. It reads leaf descendants
+  now.
+
+### Removed
+
+- **`OKF::Server::Hub::SEARCH_LIMIT` and `Hub::SEARCH_ENGINE`.** Both moved to
+  `OKF::Server::App`, which now defines the `/search` payload both hosts answer
+  with (`App.search_payload`). The hub's copies were left behind unreferenced —
+  two constants for one cap is two places to raise it and one of them silently
+  losing. Use `OKF::Server::App::SEARCH_LIMIT` / `App::SEARCH_ENGINE`.
+
+### Deprecated
+
+- **`--area`, and `tags --by area`.** OKF's own vocabulary for grouping is
+  *directories* (`grep -ci area SPEC.md` → 0); "area" was this gem's invention,
+  and defining it as a concept id's first path segment threw away every level
+  below it. `dir` is now the only machine word — full path, `.` at the root,
+  rendered `(root)` for humans — and "cluster" stays prose for what a dir
+  groups. Both deprecated spellings keep their **old behavior exactly** and warn
+  once per run on stderr (`--json` on stdout is unaffected); they go in a later
+  release.
+
 ## [1.10.0] - 2026-07-21
 
 ### Added
@@ -930,6 +1223,7 @@ Initial release.
 
 - Runs on Ruby >= 2.4 with two runtime dependencies: rack and webrick.
 
+[1.11.0]: https://github.com/serradura/okf-gem/compare/v1.10.0...v1.11.0
 [1.10.0]: https://github.com/serradura/okf-gem/compare/v1.9.0...v1.10.0
 [1.9.0]: https://github.com/serradura/okf-gem/compare/v1.8.0...v1.9.0
 [1.8.0]: https://github.com/serradura/okf-gem/compare/v1.7.0...v1.8.0