okf 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 047d30628ab36abdfe517a2722753dc8f4a6eb60cea9a41d6015508d64784af6
-  data.tar.gz: 637ce26fbb8375b9c4d0daeab6ef6bdc8b8cee0258838e73151944b772445c47
+  metadata.gz: 0aee1cdfc7b13016c423050f98de4994431fa68ae4afe3869b5555b5408c3315
+  data.tar.gz: '058369e3e6131e6af6de0b3e599bdc7716e3296f0ff1caacd59f905088e5c4ce'
 SHA512:
-  metadata.gz: e30d74c10e269546cd81a433ff91b8f4f662540a81de9010de03c5e245d59eae3f7fff2743519379bbc2de53319501b2e517a6d7c613bf24d7e21a9ab447dd5d
-  data.tar.gz: 862d1454d20f6ff1f51e0f17829676becdf1503df42f2d6ca5bf9b0004437ba43e65f6db381bba14b0126f2f40bb3704a6f29c8e12bafc237d405612604610a8
+  metadata.gz: 7d91fe567c067d175cfa3274773e984720384315d2eb8fb790da247ee256706b48e079ba4a4d9e5b909a4e6f480f968574d4526e6d6b80b4e443b57785d9ac36
+  data.tar.gz: e075baf062df84f4567200cfe4d375280dcf5cd9b76aad7d9802d1ae28cc00245982c6604e7e5fea080b15c47cee0644c5f75b7e2468379fc386de985ad1fe45

data/.okf/capabilities/agent-skill.md

@@ -0,0 +1,112 @@
+---
+type: Capability
+title: Companion agent skill (skill)
+description: A SKILL.md plus references and templates, shipped inside the gem, that teaches an agent to author OKF.
+resource: gems/okf/lib/okf/skill.rb
+tags: [agent, install]
+generated:
+  by: human:maintainer
+  at: 2026-08-17T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/skill.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/skill.rb
+  - title: gems/okf/lib/okf/skill/SKILL.md
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/skill/SKILL.md
+  - title: gems/okf/test/plugin/sync_test.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/test/plugin/sync_test.rb
+---
+
+# Overview
+
+The gem carries the **OKF agent skill** — a `SKILL.md` with reference and
+template files that teach a coding agent to *produce*, *migrate*, *maintain*,
+*refine*, *consume*, *search*, *curate*, and *doctor* OKF (`@okf-eco format/okf-format`) bundles
+and to drive the [CLI](../cli.md). The authoring judgment the executable can't encode lives here;
+the executable handles the mechanics. Each verb routes to its own playbook
+(`playbooks/`); the search playbook is progressive disclosure end to end —
+ingest the index map, decide where to look, cut across with
+[`okf search`](search.md), read only the winning bodies — and pointed questions
+route to it first from the menu and consume playbooks. The two authoring
+on-ramps stay distinct: `produce` distills sources into new concepts, while
+`migrate` adopts existing documentation in place — frontmatter and reserved
+files added, bodies kept **verbatim**, with `okf validate --json` as the
+worklist — so a document survives conversion recognizably itself. Three more verbs
+bound that loop rather than drive it: `curate` is structural upkeep as the bundle
+*stands* — `validate` + `lint` + `loose` — and hands off to `maintain` the moment
+the finding is that the *content*, not the structure, has drifted; `refine` is the
+inverse hand-off — the content is right but the *shape* underserves retrieval —
+and restructures for cohesion over the evidence the [read views](read-views.md)
+compute (tag locality via `tags --by`, the hub origin test via `graph --hubs`),
+always proposing before it applies; `doctor` is the
+one playbook that assumes nothing, installing and verifying the [CLI](../cli.md)
+before it examines the bundle. A no-argument run is a verb of its own — the menu
+reads the signals and names the highest-value move without running one.
+
+**Every playbook names the same first move**, and that took a correction. The
+skill had prescribed one in seven places — bare `okf index`, `index --no-body`,
+`dirs --depth 1` — across SKILL.md, four playbooks and the CLI reference, and
+that disagreement *is* the deliberation an agent pays for on every retrieval. A
+lookup table added to SKILL.md to pre-decide it made things worse: it duplicated
+guidance already in the reference, contradicted the file it sat in, and carried
+payload figures measured on one private bundle. It was reverted for the
+subtraction it should have been. Every site now says `okf dirs` first, then
+`okf index --dir <branch>` to descend — chosen structurally, because `dirs` emits
+one row per directory where `index` emits one per concept even under `--no-body`,
+so the two scale with different things. The reason is in the skill; the numbers
+are not.
+
+# `okf skill <dest>` installs it
+
+`OKF::Skill.install` copies the skill into a destination you name — Claude Code's
+`.claude`, an agent-agnostic `.agents`, wherever your agent looks. The rules are
+deliberate:
+
+- the **destination is required** — no magic default — so a user always decides
+  where the skill lands;
+- it lands in a **`skills/okf/` folder** by default (`.claude` →
+  `.claude/skills/okf`), because an agent discovers a skill as
+  `<skills-dir>/<name>/SKILL.md` — so the skill settles in its own folder, not
+  loose among the others. A `<dest>` already ending in `skills` only gains the
+  `okf/` leaf; one already named `okf` is used as-is (idempotent); `--here`
+  pastes straight into `<dest>`, wherever it is;
+- the resolved directory must be **empty unless `--force`**, so a customized
+  skill is never clobbered.
+
+# One canonical copy, versioned with the gem
+
+The skill ships **only** from `okf/lib/okf/skill/**` — that tree is the single source,
+and `install` copies from it. Because the skill rides inside the gem, installing
+the gem already puts the skill on the machine, and the skill's CLI reference can
+**never drift** from the executable it was released with. Local installs
+elsewhere are gitignored so they never masquerade as the source.
+
+# Two more channels: the Claude Code plugin, and `skills/`
+
+The repository doubles as a plugin marketplace, and the plugin carries a
+**generated** copy of the same skill (`plugin/skills/okf`) — `rake skill:sync`
+regenerates it after any skill edit or version bump, and a test fails the build
+on drift, so the canonical-copy rule survives the second channel. Around the
+skill the plugin adds a front-door command (`/okf:gem`) that is deliberately a
+**pass-through shim**: it hands its arguments to the skill unchanged, so
+`SKILL.md` stays the single router for every channel — the Commands table, the
+intent inference, and the not-a-bundle `migrate` suggestion live only there,
+where the drift test guards them, instead of in a second copy the test never
+sees. The plugin also carries a PostToolUse hook that runs `okf validate` +
+`okf lint` after every edit inside a bundle and hands the relevant findings
+back as context. Nothing under `plugin/` ships in the gem.
+
+The third channel is the generic one. A skill installer walks a repository's
+`skills/` directory, so `skills/okf` is the same generated copy under the name
+every such tool already looks for — `npx skills add serradura/okf` installs
+it into any of the agents that tool supports, no gem and no Claude Code
+required. It costs one line in `GENERATED_SKILL_COPIES` rather than a second
+task, which is the point: **one canonical tree with N destinations is one
+obligation, and a second task to remember is a second task to forget.** The
+guard scales with it — `rake skill:verify` compares file lists and SHA-256
+checksums for every destination and `build` depends on it, so a copy cannot be
+released stale, whatever channel it feeds.
+
+The channels are not equivalent, and the difference is the version they carry.
+The gem's copy is the release's, pinned to the executable beside it; the plugin's
+follows the marketplace; `skills/` tracks this repository's default branch. A
+consumer who needs the skill and the CLI to agree should take the gem's.

data/.okf/capabilities/bundles-manager.md

@@ -0,0 +1,144 @@
+---
+type: Capability
+title: Bundles list (the hub's /b/ page)
+description: The hub's /b/ page — every bundle it knows about with its size, health and default marker — and the four POST routes that change the registry, which the graph page's Bundles panel drives.
+resource: gems/okf/lib/okf/server/hub.rb
+tags: [server, registry, hub, ui]
+generated:
+  by: human:maintainer
+  at: 2026-07-21T16:00:00Z
+sources:
+  - title: gems/okf/lib/okf/server/hub.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/server/hub.rb
+  - title: gems/okf/lib/okf/cli/server.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/cli/server.rb
+  - title: gems/okf/lib/okf/registry.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/registry.rb
+---
+
+# Why it exists
+
+The [registry](../registry.md) has always been a terminal thing: `okf registry
+set`, `del`, `default`, `rename`. That is the right surface for the people who
+write the bundles, and the wrong one for the people who read them. A meeting with
+non-technical readers settled it — the registry needed a point-and-click
+surface, and the [server](graph-server.md) was already most of the way there.
+
+The `/b/` page used to be a bare list of links. It became the browser
+counterpart of the TUI's bundles view — every fact needed to choose between
+bundles, and forms to change the set.
+
+Then the [graph page](graph-server.md) grew a **Bundles panel** behind the rail's
+⚙, and for a while both surfaces carried the same four verbs. Two
+implementations of one contract is the thing that drifts, so the forms came out
+of `/b/` and the routes stayed. The split that survives is a clean one: `/b/`
+answers *which bundles are there*, from a page you can land on with no bundle
+open at all, and the panel answers *change this one* where the reader already
+is. Managing a set is something you do while reading it, not on a detour to a
+page you had to know existed.
+
+# What a row says
+
+One row per bundle the server *knows about*, which is deliberately not the same
+as one per bundle it *hosts*. A registry entry whose folder was deleted cannot be
+served, and leaving it off the page answers "where did my bundle go?" with
+silence; it shows, muted, with `folder is gone` and no link.
+
+Each row carries the title, the `@slug` you would type at the CLI, the folder,
+the concept count, and a **health verdict** — `ok`, `warn`, `error` — drawn as a
+3px rule on the row's left edge. That rule is the accent bar under the page's own
+heading, stood on end and put to work; colour only reinforces it, and the word
+beside it is the message, so nothing on the page depends on being able to see
+red. The verdict keeps the [validate/lint separation](validator.md): a curation
+finding is a warning and the bundle stays open, and only a non-conformant bundle
+reads as broken.
+
+A bundle that arrived through a registry [link](../registry.md) is listed,
+mounted and served like any other, and is **read-only**: the file that owns it is
+another registry, so the model refuses `rename`, `remove` and `default` against
+it. The page carries that in both halves, because one without the other is a
+worse page than neither. The row shows `via @onm` and **offers no actions menu** —
+three buttons that can only fail are not a menu — and the request is refused
+anyway if it arrives, since the guard lives in `Registry` rather than here. That
+is the same "hiding a button is a UI, refusing the request is the boundary" split
+the read-only gate above keeps, reached from the other direction: there the
+server declines to write at all, here one row does.
+
+Rows are matched to entries by **directory**, not by slug. A rename changes the
+slug and nothing else, and a row that lost its identity over a rename is the bug
+that avoids.
+
+# Writes, and the four locks on them
+
+Four routes change anything — `POST /registry/default | rename | remove | add` —
+and each passes four gates before it runs. They are the only non-GET routes the
+server has:
+
+1. **Is this server writable at all?** A loopback bind is, without a flag: the
+   audience this page was built for should not need a command line to use the
+   page they were pointed at, and `okf server --read-only` is how they decline it.
+   Any other address is refused outright, with no flag that opens it: `--bind
+   0.0.0.0` is how a personal tool becomes a public one, and a write surface does
+   not follow it there at all. A read-only server offers no controls *and*
+   refuses the request that skipped them — hiding a button is a UI, refusing the
+   request is the boundary.
+2. **Is there a registry to write to?** An ephemeral hub (`okf server ./a ./b`)
+   is serving directories somebody typed and has no list to edit — `409`, and the
+   page says so rather than leaving the missing controls a mystery.
+3. **Is the verb one of the four?** The path is user input, and "call whatever
+   method the path names" is how a router becomes an `eval`. A frozen list, not
+   a lookup.
+4. **Did this come from this page?** Same-origin *and* a per-boot token. Neither
+   alone is enough: the token lives in a page, and a page is a thing another
+   site can get a reader to submit; Origin alone would trust every
+   tab the browser has open on this host. An unstated origin is refused rather
+   than assumed. Per-boot rather than per-session because the hub has no sessions
+   and wants none — a cookie jar is a subsystem to defend for a page four people
+   see.
+
+A success writes the file, **rebuilds the hub's bundles and apps from disk**, and
+answers with the outcome. The rebuild is the part that is easy to skip and
+impossible to skip safely: a write that leaves the running server on the old set
+is a lie the next click believes.
+
+Every answer is JSON, and Accept decides nothing. It used to be one of two
+renderings — a `303` back to `/b/` for the forms, so a reload never re-posted,
+and JSON for the panel's `fetch()`. With the forms gone there is one caller, so
+there is one shape; asking for HTML does not resurrect a page-shaped answer that
+nothing would read. The refusal messages are the core's own — a reserved slug, a
+collision, a slug nothing carries all raise `OKF::Error` with a sentence written
+for a person, and repeating that judgement in the server is how the two come to
+disagree.
+
+# The page carries no script, and nothing to post
+
+No JavaScript, no build step, and now no forms and no token either: a page with
+nothing to post has no business holding the credential. What is left is what only
+this page can be — the list, the place `/` redirects from when no bundle is
+named, the way back from the [404](graph-server.md), and the **empty state**. That
+last one is why it cannot simply be deleted along with its forms: a hub with zero
+bundles serves no graph page, so there is no page for the panel to live on, and
+something still has to say what happened and how to fix it.
+
+**There is no Add anywhere**, on either surface. A browser cannot hand over a
+filesystem path — the File System Access API yields an opaque handle, never a
+path, and is Chromium-only besides — and registering is the agent's act. The
+route is still there because `okf registry set` is not the only caller that could
+want it, but nothing in the UI reaches it.
+
+# Verification
+
+`okf/test/integration/server/hub_writes_test.rb` is the critical layer: every verb's
+happy path, every refusal, and each of the four gates, asserting both that the
+registry file changed *and* that the live hub reflects it without a restart.
+`okf/test/browser/specs/bundles-panel.spec.js` drives the same verbs in Chromium
+through the panel, against a registry-backed server with its own `$OKF_HOME` —
+serial, and each spec puts back what it changed, because they share one live
+registry.
+<!-- rule:okf-prove-the-write-lands -->
+
+A browser pass over these writes earned its place immediately, back when they
+were forms: it caught an HTML `pattern` attribute whose character class was valid
+as a Ruby regexp and invalid under the `v` flag a browser compiles it with, so
+every keystroke in the rename field threw a `SyntaxError` no integration
+assertion could see.