okf 1.9.0 → 1.10.0

data/lib/okf/skill/SKILL.md

@@ -13,7 +13,7 @@ description: >-
   working in a repo that already carries an OKF bundle — a `.okf/` directory or a
   root `index.md` carrying `okf_version`.
 user-invocable: true
-argument-hint: "[search|produce|migrate|maintain|consume|curate|doctor|<okf-cli-verb>] [dir|@slug] [--flags]"
+argument-hint: "[search|produce|migrate|maintain|refine|consume|curate|doctor|<okf-cli-verb>] [dir|@slug] [--flags]"
 allowed-tools: Read Write Edit Grep Glob Bash
 ---
 
@@ -123,10 +123,12 @@ when you need chapter and verse.
 
 **No subcommand?** Infer intent: "document this / capture X" → `produce`;
 "convert / migrate / OKFy these existing docs into a bundle" → `migrate`; "the
-code changed, update the docs" → `maintain`; "what do we know about X / where
-is X documented" → `search`; a repo already carrying a bundle plus a task
-needing its knowledge → `consume`; "check / graph / preview it" → run the
-matching CLI verb and interpret the result. When genuinely ambiguous, ask.
+code changed, update the docs" → `maintain`; "restructure / rebalance the
+bundle / is the structure right / get more out of it" → `refine`; "what do we
+know about X / where is X documented" → `search`; a repo already carrying a
+bundle plus a task needing its knowledge → `consume`; "check / graph / preview
+it" → run the matching CLI verb and interpret the result. When genuinely
+ambiguous, ask.
 
 **Which target?** A leading `@` is a *registry ref*, not a path: `@slug` names a
 bundle registered with `okf registry set`, bare `@` the default — route it
@@ -158,15 +160,17 @@ Read the referenced playbook before executing — it *is* the procedure.
 | `produce`  | Author | create or extend a bundle | [playbooks/produce.md](playbooks/produce.md) |
 | `migrate`  | Author | convert existing docs in place: frontmatter + reserved files, bodies verbatim | [playbooks/migrate.md](playbooks/migrate.md) |
 | `maintain` | Author | sync the bundle's content with reality after a change | [playbooks/maintain.md](playbooks/maintain.md) |
+| `refine`   | Author | optimize the bundle's structure: evidence-driven, cohesion-first; proposes, never auto-applies | [playbooks/refine.md](playbooks/refine.md) |
 | `consume`  | Use    | use the bundle as context for a task | [playbooks/consume.md](playbooks/consume.md) |
 | `curate`   | Curate | structural upkeep as it stands: validate + lint + loose | [playbooks/curate.md](playbooks/curate.md) |
 | `doctor`   | Setup  | install and verify the CLI, then doctor the bundle | [playbooks/doctor.md](playbooks/doctor.md) |
-| `<okf-cli-verb>` | Read | validate, lint, loose, index, catalog, files, tags, types, stats, graph, server, render, registry, skill | `okf <verb> --help` + [reference/cli.md](reference/cli.md) |
+| `<okf-cli-verb>` | Read | validate, lint, loose, index, catalog, files, tags, types, stats, graph, server, render, registry, skill — **plus any verb an installed extension adds** (`okf help` is authoritative, this list is not) | `okf <verb> --help` + [reference/cli.md](reference/cli.md) |
 
-Two boundaries worth keeping sharp: `curate` is structural upkeep only — when
-the *content* no longer matches reality, that is `maintain` — and `doctor` is
-the one playbook that does not assume the CLI is installed. In Claude Code with
-the okf plugin, `/okf:gem` routes these same verbs.
+Three boundaries worth keeping sharp: `curate` is structural upkeep only — when
+the *content* no longer matches reality, that is `maintain`, and when the
+content is right but the *shape* underserves retrieval, that is `refine` — and
+`doctor` is the one playbook that does not assume the CLI is installed. In
+Claude Code with the okf plugin, `/okf:gem` routes these same verbs.
 
 ## The lifecycle is a flywheel, not phases
 

data/lib/okf/skill/playbooks/curate.md

@@ -9,7 +9,9 @@ reachability, backlog, completeness, hygiene. It is not `maintain`, the
 skill's workflow for when the project changed and the bundle's *content*
 must catch up with reality; reach for that one when what is written stopped
 being true. Curating can surface semantic staleness, and when it does,
-switch to `maintain` for those concepts.
+switch to `maintain` for those concepts. And it never moves knowledge: when
+the content is right but the shape underserves retrieval — fat areas,
+mis-homed hubs, an uncurated tag layer — that is [refine](refine.md).
 
 1. Locate the bundle: the directory you were given, if any; otherwise a
    `.okf/` directory or a root `index.md` whose frontmatter carries

data/lib/okf/skill/playbooks/maintain.md

@@ -1,8 +1,9 @@
 # Playbook: maintain — keep a bundle in sync with reality
 
 Reach for this when the project changed and the bundle's *content* must catch
-up. The modelling craft behind steps 3 and 7 lives in
-[authoring.md](../reference/authoring.md).
+up. Restructuring the bundle itself — moving concepts, adding areas — is
+[refine](refine.md), not maintain. The modelling craft behind steps 3 and 7
+lives in [authoring.md](../reference/authoring.md).
 
 1. **Orient before hunting.** Run `okf index <dir>` (the §6 map — every directory's
    index body, rollups, and listings), read `log.md` (the §7 baseline: what changed

data/lib/okf/skill/playbooks/menu.md

@@ -33,6 +33,11 @@ is the lede.
      the working tree has uncommitted changes to the code the bundle describes
      (`git status`), prefer **`maintain`**: that is exactly the drift it exists
      to close.
+   - **clean, but the shape strains** — one area dwarfing the rest in
+     `okf stats`, tags spread thin across areas in `okf tags --by area`, hubs
+     whose inbound links are mostly foreign in `okf graph --hubs` → offer
+     **`refine`** (evidence-driven restructuring; it proposes before it
+     touches anything).
 4. **Freshness is off by default.** If the bundle carries timestamps, note that a
    plain `lint` said nothing about staleness and `okf lint <root> --stale-after
    90d` is the check that would.

data/lib/okf/skill/playbooks/refine.md

@@ -0,0 +1,92 @@
+# Playbook: refine — restructure a bundle to get the most from OKF
+
+Reach for this when the bundle's *content* is right but its *shape* may not be:
+areas grown fat by additive passes, hubs homed by history, a tag layer that
+never became the second index. Refine optimizes the projection — the same
+knowledge, arranged to serve progressive disclosure, the emergent graph,
+cross-cutting tags, and capture-once-link-many. It is not [curate](curate.md)
+(upkeep of the structure as it stands) and not [maintain](maintain.md) (content
+catching up with reality): refine changes where knowledge lives, never what it
+says. Its permitted edits are structural — move a concept, extract a duplicated
+fact to one home, section an index, retag, relink, and write the connective
+sentence a link lives in; summarizing, updating, or correcting a body is
+maintain's job, reached by switching verbs, not by stretching this one.
+
+The frame that governs every move: the directory tree is a **lossy projection
+of the link graph**. A tree gives each concept one parent, so the tree encodes
+only the single dominant decomposition; every genuinely many-to-many
+relationship rides links and tags, never new directories. And cohesion outranks
+balance — a move has semantic cost, so balance is a tiebreaker and a fatness
+alarm, never the objective. <!-- rule:okf-cohesion-over-balance -->
+
+1. **Orient.** `okf index <dir|@slug> --no-body` (areas, fan-out, depth),
+   `log.md` (how the bundle grew), `okf stats` (totals). Additive growth
+   optimizes each pass locally, never the whole — that is the drift this
+   playbook corrects.
+2. **Measure — the CLI is the evidence.** Baseline `validate` / `lint
+   --stale-after` / `loose` first: refine assumes a sound bundle, and hard
+   errors are [curate](curate.md)'s job. Then the two structural reads:
+   - `okf tags <dir> --by area` — each row carries `count/total`, so a tag's
+     **locality** reads directly: a tag wholly inside one area names a *domain*
+     (the directories are right); one spread across areas names a *concern*.
+   - `okf graph <dir> --hubs` — concepts ranked by inbound links, each with
+     the areas those links come from: the **origin test** for every hub.
+3. **Diagnose — you are the judgment.** The measurements are evidence, never
+   verdicts:
+   - **Concerns never become containers.** A directory built around a spread
+     tag ("everything async") prunes nothing — most needs would enter it.
+     The cross-cut stays a tag. <!-- rule:okf-concern-not-container -->
+   - **A directory must prune.** The positive test for any area, existing or
+     proposed: does knowing "it's in there" eliminate a large, even slice? A
+     good node splits its parent into chunks that are nameable, mutually
+     exclusive, and roughly comparable in size. And small is not merge-worthy
+     on its own — a two-concept area that is a genuinely distinct domain
+     stays. <!-- rule:okf-directory-prunes -->
+   - **The hub origin test.** Inbound majority from the hub's own area:
+     well-homed, leave it. A dominant *foreign* area: that area is the better
+     home. Foreign majority with *no* dominant area: a shared primitive — the
+     only admission ticket into a shared-core area (without that test, a
+     `foundation/` rots into a `misc/`). Two comparable strong ties, one of
+     them home: stay and carry the other as a tag — moving trades one
+     imbalance for another. And in a design bundle expect the central
+     decisions to fail this test wholesale: that is centrality, not
+     mis-homing.
+   - **Fatness alarm, not fatness rule.** A fat area (≳20–25 concepts) wants
+     **heading sections inside its `index.md`** first — the same prune as
+     sub-directories, for zero extra hops and no new enumeration to keep
+     sound. Directory nesting pays only at hundreds of concepts, and only
+     where the index's own headings already form separable, nameable
+     sub-groups — fatness alone never justifies depth; the sections that
+     formed are the evidence the split exists.
+   - **Duplication.** Read the area overviews for a fact re-explained in
+     several (drifting tables are the tell); capture-once-link-many says
+     extract it into one concept and link from the rest. Extraction is the one
+     refine move that touches bodies, and it redistributes rather than
+     rewrites: assemble the canonical concept from the copies, keep every
+     copy's unique domain-specific detail (in the extract, or in the one-line
+     note left beside each link), and where the copies *disagree*, which is
+     true is a [maintain](maintain.md) question — verify against reality or
+     flag the conflict in the proposal, never silently pick a winner while
+     merging. <!-- rule:okf-extract-not-rewrite -->
+   - **Vocabulary twins.** The [maintain](maintain.md) tag-curation recipe
+     (twins, echoes, singletons) applies to `type` too — `okf types <dir>`.
+4. **Plan — tier by leverage ÷ churn, free levers first.** Tag curation,
+   index heading-sectioning, and extraction before any file move; a move only
+   when the origin test demands one, and each gated by **do-nothing**: skip it
+   unless its value beats its churn. Record what you *declined* and why — the
+   decline list is what stops the next pass from re-proposing it.
+5. **Propose — never auto-apply.** Refine's output is a short report (the
+   evidence, the tiers, the declines) plus a ready-to-run execution prompt the
+   user can hand back later: a scope line, the governing principles above, the
+   explicit prohibitions, the closeout gate as acceptance. Analysis and
+   execution are separate on purpose — the judgment is spent once, frozen, and
+   then executed without re-derivation. <!-- rule:okf-refine-proposes -->
+6. **Execute only on approval**, then walk the
+   [Closeout gate](../reference/authoring.md#closeout--the-finishing-gate):
+   every touched `index.md` re-enumerated, links absolute bundle-relative so
+   they survived the moves, a dated `log.md` entry carrying the *why*,
+   validate/lint/loose clean, and a before/after of step 2's evidence.
+
+Two traps: never split a cohesive cluster (a deliberately paired mirror flow)
+to hit a size band, and never tag a concept with its own directory's name — a
+group-name echo adds no edge.

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

@@ -20,6 +20,12 @@ The surface is self-describing — `okf --help` maps every verb, `okf <verb> --h
 its flags. Ask the tool for what exists; this file carries only what `--help`
 cannot: each verb's semantics, its traps, and its JSON shape.
 
+**The verb list is open, not closed.** An installed extension gem adds verbs of
+its own, listed under `installed extensions:` in `okf help`. So a verb that
+`--help` shows and this file does not document is **normal, not a documentation
+error** — ask `okf <verb> --help` for it, and expect nothing here about its
+semantics or JSON. Everything below documents the built-ins only.
+
 **`--json` is compact by design.** Every emitting verb prints single-line JSON —
 the token-efficient substrate you consume; `--pretty` (which implies `--json`)
 indents it for a human. The bytes differ, the JSON is identical, so parse either.
@@ -296,10 +302,14 @@ in/out link degree). Add `--json` to any for a machine substrate.
 - **`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
-  dimension with **within-group** counts (a tag spanning groups appears in each) —
-  the substrate for tag curation; the judgment recipe lives in the
-  [maintain playbook](../playbooks/maintain.md). JSON: `{ bundle, count, by,
-  groups: [{ <dim>, count, tags: […] }] }`.
+  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
+  count = wholly local; `2/7` = a cross-cutting spread). The substrate for tag
+  curation and for [refine](../playbooks/refine.md)'s domain-vs-concern read;
+  the judgment recipes live in the [maintain playbook](../playbooks/maintain.md)
+  and the [refine playbook](../playbooks/refine.md). JSON: `{ bundle, count, by,
+  groups: [{ <dim>, count, tags: [{ tag, count, total, concepts }] }] }`.
 - **`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, …] }] }`.
@@ -427,3 +437,11 @@ drops each node's body, and `--minimal` ships only `id`/`title` plus the type/ta
 indexes — the lean shape the `server` page boots from. Reach for the full dump
 only when the task truly consumes every body; for one question, the
 [search verb](#search--ranked-text-retrieval-metadata--body) is orders cheaper.
+
+`--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
+[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;
+`--minimal`/`--no-body` shape node payloads and change nothing here.

data/lib/okf/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -86,6 +86,22 @@ files:
 - 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/files.rb
+- lib/okf/cli/graph.rb
+- lib/okf/cli/index.rb
+- lib/okf/cli/lint.rb
+- lib/okf/cli/loose.rb
+- lib/okf/cli/registry.rb
+- lib/okf/cli/render.rb
+- lib/okf/cli/search.rb
+- lib/okf/cli/server.rb
+- lib/okf/cli/skill.rb
+- lib/okf/cli/stats.rb
+- lib/okf/cli/tags.rb
+- lib/okf/cli/types.rb
+- lib/okf/cli/validate.rb
 - lib/okf/concept.rb
 - lib/okf/concept/file.rb
 - lib/okf/markdown/citations.rb
@@ -97,6 +113,7 @@ files:
 - lib/okf/render/graph/template.html.erb
 - lib/okf/server/app.rb
 - lib/okf/server/hub.rb
+- lib/okf/server/hub/not_found.rb
 - lib/okf/server/runner.rb
 - lib/okf/skill.rb
 - lib/okf/skill/SKILL.md
@@ -107,6 +124,7 @@ files:
 - lib/okf/skill/playbooks/menu.md
 - lib/okf/skill/playbooks/migrate.md
 - lib/okf/skill/playbooks/produce.md
+- lib/okf/skill/playbooks/refine.md
 - lib/okf/skill/playbooks/search.md
 - lib/okf/skill/reference/APACHE-2.0.txt
 - lib/okf/skill/reference/SPEC.md