okf-mcp 1.2.0 → 1.3.0

data/.okf/structure/http-bridge.md

@@ -0,0 +1,56 @@
+---
+type: Component
+title: The HTTP bridge
+description: WEBrick to Rack in one file — buffered responses, the streaming adapter that parks a handler thread until the SDK ends a stream, and the teardown order that stops it hanging.
+tags: [mcp, http, webrick, streaming, teardown]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/http.rb
+---
+
+# The file
+
+| file | what it owns |
+| ---- | ------------ |
+| `lib/okf/mcp/http.rb` | `OKF::MCP::HTTP` — `prepare`, `stop`, `app_for`, `build`, `handle`, and the two stream classes `Stream` and `Streams` |
+
+This is the only file that knows WEBrick exists. `--http` goes through it;
+`OKF::MCP.app` under a Rack 3 server does not, which is why the streaming
+subtleties below are scoped to this bridge and not to the gem.
+
+# The subtlety the whole file is shaped around
+
+`subscriptions/listen` is answered by the SDK with a **Rack streaming body
+whose callable returns immediately**. WEBrick ends a proc-body response when
+the proc returns. Composed naively, every listen would close the instant it
+opened.
+
+So `Stream#wait` parks the handler thread until the SDK ends the stream, and
+`Streams` is the bounded set of live ones. Three consequences are load-bearing,
+and `test/integration/http_listen_test.rb` pins each:
+
+- **Teardown closes the transport before WEBrick.** `HTTP.stop` does them in
+  that order because WEBrick's shutdown joins its connection threads and hangs
+  on any open stream.
+- **The signal trap hands teardown to a thread.** A mutex in trap context is a
+  `ThreadError` on 2.7, which is the floor.
+- **Listens are capped at 32, on this bridge only.** Each holds a WEBrick
+  thread and a connection token. That is not true under a Rack server, where
+  the SDK's own default stands, so the cap belongs here rather than in the
+  server definition.
+
+**`EPIPE` must propagate.** A dead peer is noticed by `EPIPE` raising out of a
+keepalive write, and that propagation *is* the SDK's cleanup signal. An adapter
+that rescues it leaks the stream instead of closing it — so the rescue that
+looks defensive is the bug.
+
+# Host and origin checking
+
+`allowed_hosts_for` and `local_hosts` derive the default allowlist from the
+bind address. `app_for` is where `allowed_hosts` and `allowed_origins` reach
+the transport, and it is called from [`App`](doors.md) rather than duplicated —
+one construction site, so a new option cannot land on half the callers.
+
+`read_body` bounds the request body and `oversized` is its refusal;
+`not_found` answers anything off the MCP path.

data/.okf/structure/index.md

@@ -0,0 +1,13 @@
+# Structure
+
+Every file under `lib/`, grouped by the layer that owns it. One concept owns
+each file, and `test/unit/bundle_catalog_test.rb` fails if that stops being
+true in either direction — a file no concept names, or a concept naming a file
+that is gone.
+
+Read them bottom-up: each layer depends only on the one below it.
+
+* [The doors](doors.md) - `lib/okf/mcp.rb`, `lib/okf/plugin.rb`, `lib/okf/mcp/cli.rb`, `lib/okf/mcp/app.rb`, `lib/okf/mcp/version.rb` — the three ways in, and the load contract that keeps a bare require cheap.
+* [The served set](served-set.md) - `lib/okf/mcp/registry.rb`, `filters.rb`, `backend.rb`, `memory_backend.rb` — which bundles exist, and the cache in front of them.
+* [The server definition](server-definition.md) - `lib/okf/mcp/server.rb`, `output_schemas.rb`, `resources.rb` — the fourteen tools, their declared shapes, and concepts as resources.
+* [The HTTP bridge](http-bridge.md) - `lib/okf/mcp/http.rb` — WEBrick to Rack, and the streaming adapter that the rest of the gem does not need to know about.

data/.okf/structure/served-set.md

@@ -0,0 +1,58 @@
+---
+type: Component
+title: The served set, and the cache in front of it
+description: Which bundles this server will answer about — resolved once at boot as the tools' allowlist — plus the folder cache, the engine detection and the one place the `dir` vocabulary lives.
+tags: [mcp, registry, cache, backend, filters]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/registry.rb
+---
+
+# The files
+
+| file | what it owns |
+| ---- | ------------ |
+| `lib/okf/mcp/registry.rb` | `OKF::MCP::Registry` — the served set: argv refs (dirs and `@slug`s) or the kernel registry, resolved once at boot |
+| `lib/okf/mcp/filters.rb` | `OKF::MCP::Filters` — the `dir` vocabulary: folding, normalizing, containment, depth |
+| `lib/okf/mcp/backend.rb` | `OKF::MCP::Backend` — engine detection: the in-memory backend, or `okf-sqlite3` when it is installed and suitable |
+| `lib/okf/mcp/memory_backend.rb` | `OKF::MCP::MemoryBackend` — the always-present folder cache: residency, fingerprints, catalog rows, search pairs |
+
+# The registry is an allowlist, not a lookup
+
+`Registry.from_argv` and `Registry.from_kernel` resolve **once, at boot**. After
+that the entry list is fixed, and `#root!` is the only way a tool turns a bundle
+name into a path — it raises for anything not in the set.
+
+That is the containment property the whole server rests on: a host cannot ask
+this process to read a bundle nobody served it. `#refresh!` re-reads the same
+sources; it does not widen the set.
+
+Identity comes from the kernel's registry, never minted here when a kernel slug
+exists — `resolve_arg`, `ref_entry` and `group_roots` all defer to it, so
+`@handbook` means the same bundle to `okf lint` and to a host. Groups expand to
+their member roots, recursively, at resolve time.
+
+# The `dir` vocabulary lives in exactly one file
+
+`Filters` exists because it did not. The folding, normalizing and containment
+rules lived in two places and **the two copies disagreed about the root** —
+one treated `""` as "everything", the other as "the root directory only". Every
+tool that takes a `dir` now reads them from here.
+
+`normalize_dir`, `within?`, `dir_depth` and `known_dir?` are the whole surface.
+A new tool taking a `dir` uses them rather than writing a third opinion.
+
+# The cache is per-root and fingerprinted
+
+`MemoryBackend#folder` caches an `OKF::Bundle::Folder` per root;
+`#fingerprint` is what decides whether a cached one is still good. `#retain`
+prunes roots that are no longer served, and `#during_request` memoizes
+fingerprints for the span of one request so a single frame does not stat the
+same tree repeatedly.
+
+`Backend.detect` is the seam for a faster engine: if `okf-sqlite3` is installed
+and `suitable?`, it is used; otherwise the memory backend, which is always
+present. Nothing above this layer knows which one answered:
+[the server definition](server-definition.md) asks the backend, never the
+engine.

data/.okf/structure/server-definition.md

@@ -0,0 +1,72 @@
+---
+type: Component
+title: The server definition
+description: The MCP::Server subclass, the fourteen tool builders and the private helpers they share, one declared output shape per tool, and concepts as resources with a URI parser the SDK's matcher cannot supply.
+tags: [mcp, server, tools, schemas, resources]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# The files
+
+| file | what it owns |
+| ---- | ------------ |
+| `lib/okf/mcp/server.rb` | `OKF::MCP::Server` — `Server::Definition < ::MCP::Server`, `Server.build`, the fourteen `*_tool` builders, the two prompts, and the shared private helpers |
+| `lib/okf/mcp/output_schemas.rb` | `OKF::MCP::OutputSchemas` — one declared result shape per tool, looked up by name |
+| `lib/okf/mcp/resources.rb` | `OKF::MCP::Resources` — bundles and concepts as MCP resources, and the URI grammar |
+
+# server.rb is one file on purpose, in three bands
+
+At ~1,300 lines it is the largest file in the gem, and splitting it has been
+considered and declined: the fourteen builders are near-identical in shape, and
+what makes them safe is that they sit next to each other where a divergence is
+visible. Read it as three bands.
+
+**`Server.build` and `Definition`.** `build` assembles the definition from a
+registry and an engine. `Definition` subclasses the SDK's server and adds the
+per-request wrap: `#in_request` memoizes fingerprints and `#retain_served`
+prunes cache residency, so a frame's repeated reads cost one stat. `#handle`
+and `#handle_json` are what the tests drive — real JSON-RPC frames, no
+transport involved.
+
+**The fourteen builders**, one per tool: `tags_tool`, `types_tool`,
+`stats_tool`, `list_bundles_tool`, `dirs_tool`, `index_tool`, `search_tool`,
+`read_concept_tool`, `catalog_tool`, `log_tool`, `validate_tool`, `lint_tool`,
+`graph_tool`, `references_tool`. Each is a `define_tool` call and a body that
+calls the kernel. The [tool catalog](../capabilities/tools.md) is the reader's
+map of them.
+
+**The shared helpers**, which are where the contracts actually live:
+`define_tool` (the one place `readOnlyHint`, `title` and the output-schema
+lookup are attached — which is why a tool cannot forget them), `respond_json`
+and `respond_error`, the projection and validation helpers (`check_fields`,
+`check_projection`, `check_asked`, `project_rows`), the bounded-log arithmetic
+(`bounded_log`, `sized_log`), and `check_dir!`, which is the refusal every
+`dir`-taking tool shares.
+
+# One declared shape per tool, looked up by name
+
+`OutputSchemas[name]` is a lookup, not a registry a tool writes into. An
+omission is therefore deliberate and visible: `read_concept` has no shape,
+because it answers markdown rather than a structured row, and that is the only
+one. `test/integration/output_schema_test.rb` walks the wire and checks the
+declared shape against the answer actually sent.
+
+# Resources own the URI grammar because the SDK cannot
+
+`Resources.parse` exists for one reason worth knowing before touching it: **OKF
+concept ids carry slashes** (`capabilities/graph-server.md`), and the SDK's
+resource-template matcher stops at `[^/]+`. So a templated match would truncate
+every nested id. This file parses the URI itself.
+
+`list`, `templates`, `read` and `complete` are the surface; `concept_ids` and
+`prefixed` back the completion. `test/integration/resources_test.rb` and
+`completions_test.rb` drive them.
+
+# The prompts are read at get-time
+
+`Server::PROMPTS` names two markdown files shipped in `lib/okf/mcp/prompts/`,
+and `Server.prompt_text` reads one when a host asks for it. Booting never pays
+for prompt bodies, and editing a prompt does not need a code change.

data/.okf/testing/adding-a-tool.md

@@ -0,0 +1,65 @@
+---
+type: Playbook
+title: Adding a tool, end to end
+description: The walk a fifteenth tool owes — the question to answer before writing it, where the code goes, the four files that gain a test, and the three pins that will refuse it if a step is skipped.
+tags: [testing, tools, playbook, contribution]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/mcp/server.rb
+---
+
+# First, the question that usually ends it
+
+**Do the [fourteen](../capabilities/tools.md) already compose to this?**
+`dirs` + `index` + `search` answer most retrieval between them, and tool-list
+weight is a real cost on every host that connects. A tool that duplicates a
+composition is a permanent tax for a one-time convenience.
+
+Second question: **could the kernel answer it?** If it could, it should — see
+[kernel-first](../design/kernel-first.md). A kernel method serves the CLI, the
+graph server, the TUI and this shell; a tool here serves one.
+
+If both answers are no, the walk is below.
+
+# The walk
+
+1. **Write the failing test first**, in the folder that matches how the bundle
+   is named — `test/integration/by_dir/<tool>_test.rb` at minimum, and
+   `by_registry/` and `across_bundles/` if the tool takes a bundle ref or
+   several. Drive real JSON-RPC through `handle_json`. Run it: it must fail
+   because the tool does not exist, not because a fixture is missing.
+2. **Add the kernel call**, if the analysis is not already there. That is a
+   change to `okf`, with its own test, landing first.
+3. **Add the builder** — `<name>_tool(context)` in `lib/okf/mcp/server.rb`,
+   beside its neighbours, and list it in `tools_for`. Use `define_tool`, which
+   is what attaches `readOnlyHint`, the `title` and the output-schema lookup;
+   nothing else may construct a tool.
+4. **Declare the output shape** in `lib/okf/mcp/output_schemas.rb`, keyed by
+   the tool's name. Omit it only for a markdown answer, and expect to defend
+   the omission — `read_concept` is the only one today.
+5. **Carry `total`** if the answer is a list: how many rows matched *before*
+   any `limit`. No silent truncation, ever.
+6. **Reuse the `dir` vocabulary** from `lib/okf/mcp/filters.rb` if the tool
+   takes a `dir`, and `check_dir!` for the refusal. Do not write a third
+   opinion about what the root means — that bug has already happened once.
+7. **Update [the catalog](../capabilities/tools.md)** with the tool's row.
+8. **Run the suite.** The same test from step 1 passes, unedited.
+
+# The three pins that refuse a skipped step
+
+- `test/integration/capabilities_test.rb` reads the wire and fails a tool
+  missing `readOnlyHint` or `title`.
+- `test/integration/output_schema_test.rb` checks each declared shape against
+  the answer actually sent.
+- `test/unit/bundle_catalog_test.rb` fails when the catalog and `server.rb`
+  disagree about which tools exist — so step 7 is not optional, and forgetting
+  it is a red suite rather than a stale document.
+
+# Adding a file, not a tool
+
+A new file under `lib/` needs a line in whichever
+[structure](../structure/) concept owns its layer — or a concept of its own if
+it is a new layer. `bundle_catalog_test.rb` fails on an unowned file, which is
+the point: the Map used to live in `AGENTS.md` where nothing checked it, and it
+went stale silently.

data/.okf/testing/index.md

@@ -0,0 +1,9 @@
+# Testing
+
+How this gem is tested, and what a change owes before it lands. The root
+`AGENTS.md`'s rule applies here as written — a change starts with a failing
+test, red for the reason you predicted, then the code, then the same test green
+and unedited — and what follows is that rule's shape for this gem's surfaces.
+
+* [The layers](layers.md) - What each layer of the suite proves, and the claims it deliberately does not spend a process on.
+* [Adding a tool](adding-a-tool.md) - The walk a new tool owes: where the code goes, which files gain a test, and what the pins will refuse.

data/.okf/testing/layers.md

@@ -0,0 +1,56 @@
+---
+type: Constraint
+title: What each test layer proves
+description: Integration-first over real JSON-RPC frames, with process-spawning confined to the two files that prove the process — plus the wire-reading rules the SSE tests cannot be written without.
+tags: [testing, integration, http, sse]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: test/integration
+---
+
+# The layers
+
+| layer | proves | files |
+| ----- | ------ | ----- |
+| tool integration | a tool's real answer, driven as JSON-RPC through `handle_json` | `test/integration/{by_dir,by_registry,across_bundles}/` |
+| protocol surface | capabilities, output schemas, resources, completions, prompts | `capabilities_test.rb`, `output_schema_test.rb`, `resources_test.rb`, `completions_test.rb`, `prompts_test.rb` |
+| the process | `okf mcp` spawned for real, WEBrick on a real socket | `cli_plugin_test.rb`, `http_test.rb`, `http_modern_test.rb`, `http_listen_test.rb` |
+| the argv shell | flags and exit codes, in-process, spawning nothing | `cli_test.rb` |
+| units | the pieces with contracts of their own | `test/unit/` |
+
+The three tool directories mirror the kernel's own — the three ways a bundle is
+named: by directory, through the registry, and several at once.
+
+# One claim, one place
+
+A claim about **argv** is proven once, cheaply, in `cli_test.rb`, which drives
+the shell in-process and deliberately spawns nothing. A claim about **the
+process** is proven once, in the spawning files. The split is deliberate: every
+spawn is seconds, and a suite that spawns for argv claims spends minutes
+proving something a method call already settled.
+
+The three HTTP files share one harness, `test/integration/http_harness.rb`, so
+they cannot drift in how they compose the bridge — the same reason
+[`App`](../structure/doors.md) is a single construction site in `lib/`.
+
+# Reading the wire, which is where SSE tests go wrong
+
+Two rules, both learned the hard way, and neither optional:
+
+**Use a raw `TCPSocket`, not `Net::HTTP`.** Net::HTTP holds a chunked body
+until EOF, so a stream that stays open — which is the whole point of
+`subscriptions/listen` — reads as a hang rather than as a passing test.
+
+**Thread `read_until`'s returned buffer back in.** One `readpartial` can carry
+the next frame along with the awaited one, so a sequential read that starts
+from an empty buffer drops a frame and then blocks waiting for it.
+
+# The bundle is pinned too
+
+`test/unit/bundle_catalog_test.rb` checks this bundle against the tree: every
+`.rb` under `lib/` named by exactly one concept in
+[`structure/`](../structure/), every path a concept names still present, and
+the [tool catalog](../capabilities/tools.md) agreeing with the tools
+`server.rb` defines. Structural documentation is code-derived, so it is pinned
+like code rather than trusted like prose.

data/CHANGELOG.md

@@ -5,7 +5,92 @@ 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).
 
-## [Unreleased]
+## [1.3.0] - 2026-08-22
+
+### Fixed
+
+- **A long-running server now sees writes inside a *linked* registry.** okf gained
+  `okf registry link`, which folds another registry file's bundles into the served
+  set; the freshness stamp still watched only this server's own registry file, so
+  an `okf registry set` in the linked file never moved it and the server kept
+  answering about the set it booted with. The stamp now covers every file the
+  registry reads. The link list comes from the kernel, so adding or dropping a
+  link moves the first path's stamp and the next pass watches the new set.
+
+  The two kinds of file keep different rules. This server's own registry going
+  unreadable still answers `nil` and holds the last good set — a file caught
+  mid-write must not empty what is being served. A linked file is a pointer's
+  target, and okf already reports a missing one as resolving to nothing, so a
+  vanished target drops its bundles instead of freezing them.
+
+### Changed
+
+- **The `mcp` floor moves to `~> 1.3`.** `Gemfile.lock` is not committed, so the
+  suite resolves the newest SDK the requirement admits and proves itself against
+  that one; the floor tracks what the suite proves, and 1.3.0 shipped. Nothing in
+  this gem changed for it — all 324 tests pass against 1.3.0 — but a floor that
+  admits an SDK the suite never ran against is the claim the floor test exists to
+  refuse.
+
+- **The `okf` floor moves to 2.2.0**, the kernel that ships `registry link` and
+  `Registry#links_listing`. The stamp reads that method, and against 2.1.1 every
+  refresh would raise NoMethodError straight past the SystemCallError rescue.
+  `rake verify_okf_floor` gates `release` on exactly this and now passes.
+
+- `list_bundles` groups now carry a `link` key — `null` for a group this registry
+  owns, the link's name for one that arrived through a link (okf ≥ 2.2). Linked
+  groups were already resolvable as a `bundle` argument and are now listed too.
+
+## [1.2.1] - 2026-08-20
+
+### Fixed
+
+- **The package metadata follows the `gems/` move and the repository rename.**
+  Two URLs on the package page were about to be wrong at once. `changelog_uri`
+  named `blob/main/okf-mcp/CHANGELOG.md`, a path that stopped existing when the
+  four gems moved under `gems/`; `homepage` named `serradura/okf-gem`, and the
+  repository is now **`serradura/okf`** — the name the command has had all
+  along. rubygems.org serves whatever the last release published, so neither
+  corrects itself: only a release republishes metadata, and this is that
+  release. Both land in one round rather than two, which is the whole reason
+  the rename waited for the paths to stop moving.
+
+  `homepage_uri`, `source_code_uri` and `changelog_uri` are all derived from
+  `homepage`, so one line moves four pieces of this gem's metadata. GitHub
+  redirects the old URLs permanently, so anything already published keeps
+  resolving.
+
+### Added
+
+- **The gem ships its own knowledge bundle.** `.okf/` is in `spec.files`, so an
+  installed okf-mcp carries a real bundle — its own — that a host can read
+  through the very tools it serves. It documents the gem's structure: every
+  file under `lib/` grouped by the layer that owns it, the catalog of the
+  fourteen tools, the four design rules, and how to add a tool or a test.
+  `AGENTS.md` now relies on it rather than restating it, and
+  `test/unit/bundle_catalog_test.rb` fails when the two disagree with the tree
+  — a file no concept names, a concept naming a file that is gone, or a tool
+  catalog out of step with `server.rb`.
+
+### Fixed
+
+- **`rake test` on the 2.7 floor.** The Rakefile set
+  `Bundler::GemHelper#tag_prefix=` unguarded, and that accessor arrived in
+  Bundler 2.2 — Ruby 2.7, this gem's floor, ships 2.1.4. Loading the Rakefile
+  there raised `NoMethodError` and took the whole task down before a single
+  test ran. CI never saw it, because `ruby/setup-ruby` installs the newest
+  Bundler each Ruby accepts; only a floor run against the stock image
+  surfaces it. okf-tui and okf-pro have carried the `respond_to?` guard since
+  they were cut, and this gem now does too — on a Bundler without the
+  accessor, `release` aborts rather than pushing a bare `vX.Y.Z` that would
+  trigger the okf image build.
+
+### Changed
+
+- **The okf floor moves to `>= 2.1.1, < 3`** — the kernel this shell develops
+  against released 2.1.1, and `test/unit/gemspec_test.rb` holds the floor to the
+  version the suite actually resolves against. It may lead the kernel; it may
+  never lag. The ceiling is unchanged.
 
 ## [1.2.0] - 2026-08-18
 
@@ -344,7 +429,8 @@ rather than pretending to be changes somebody could have seen.
 
 The name reservation on RubyGems: an empty gem, no functionality.
 
-[1.2.0]: https://github.com/serradura/okf-gem/compare/okf-mcp/v1.1.0...okf-mcp/v1.2.0
-[1.1.0]: https://github.com/serradura/okf-gem/compare/okf-mcp/v1.0.0...okf-mcp/v1.1.0
-[1.0.0]: https://github.com/serradura/okf-gem/releases/tag/okf-mcp/v1.0.0
+[1.2.1]: https://github.com/serradura/okf/compare/okf-mcp/v1.2.0...okf-mcp/v1.2.1
+[1.2.0]: https://github.com/serradura/okf/compare/okf-mcp/v1.1.0...okf-mcp/v1.2.0
+[1.1.0]: https://github.com/serradura/okf/compare/okf-mcp/v1.0.0...okf-mcp/v1.1.0
+[1.0.0]: https://github.com/serradura/okf/releases/tag/okf-mcp/v1.0.0
 [0.0.0]: https://rubygems.org/gems/okf-mcp/versions/0.0.0

data/README.md

@@ -77,8 +77,9 @@ bundles only when the registry itself is what is being served.
 
 With no arguments the registry *is* what is served, so it is followed rather
 than snapshotted: `okf registry set`, `rename` or `del` in another terminal
-shows up on the next tool call, without a restart. The file is re-read only
-when its fingerprint moves, so the cost is a `stat`. Bundle contents are never
+shows up on the next tool call, without a restart. A write inside a registry the
+first one *links* counts too. The files are re-read only when a fingerprint
+moves, so the cost is a `stat` each. Bundle contents are never
 snapshotted either — bodies are read live, and a bundle is re-parsed whenever
 one of its files changes.
 
@@ -206,6 +207,16 @@ bundle exec rake                   # tests + RuboCop — what CI runs
 bundle exec rake test:integration  # the critical layer alone + coverage/integration/
 ```
 
+The gem carries its own OKF bundle in `.okf/` — what each file under `lib/`
+does, the catalog of the fourteen tools, the design rules, and how to add a
+tool. It ships inside the gem, so it is there after `gem install` too, and the
+quickest way to read it is through this server:
+
+```bash
+okf mcp .okf        # serve okf-mcp's own knowledge, over MCP
+okf server .okf     # or read it as a graph
+```
+
 ## License
 
 Apache-2.0, see [LICENSE.txt](LICENSE.txt).

data/lib/okf/mcp/registry.rb

@@ -15,7 +15,7 @@ module OKF
     # names a registered bundle or group, whose slug is reserved before any
     # plain-dir basename is deduped — the server verb's rule). No argv means
     # the active kernel registry, resolved exactly as the CLI resolves it:
-    # a project-local .okf-registry.json discovered from cwd, else
+    # a project-local .okf.json discovered from cwd, else
     # $OKF_HOME/registry.json, OKF_NO_DISCOVERY=1 forcing global.
     class Registry
       # One served bundle: the +slug+ tools name it by, its absolute +root+ on
@@ -297,10 +297,34 @@ module OKF
       # mtime *and* size, the pair the residency layer already uses: a second
       # write inside one filesystem timestamp tick moves the size when it does
       # not move the clock.
+      #
+      # Every file the registry reads, not just its own. A link puts bundles in a
+      # second file, and watching only the first meant a `registry set` over there
+      # was never seen: this server would keep answering about the set it booted
+      # with, which is the one failure a stamp exists to prevent. The link list
+      # itself comes from the kernel, so adding or dropping a link moves the first
+      # entry and the next pass watches the new set.
+      # The two files are watched under different rules, and the asymmetry is the
+      # point. This server's *own* registry going unreadable answers nil, which
+      # holds the last good set — a file caught mid-write must not empty what is
+      # being served. A *linked* file is only a pointer's target, and the kernel
+      # already treats a missing one as "resolves to nothing, reported", so its
+      # absence is a state change to follow rather than an error to ride out.
       def registry_stamp
         return nil if @kernel.nil?
 
-        stat = ::File.stat(@kernel.path)
+        own = file_stamp(@kernel.path)
+        return nil if own.nil?
+
+        [ own ] + @kernel.links_listing.map { |row| file_stamp(row[:registry]) }
+      rescue OKF::Error, SystemCallError
+        nil
+      end
+
+      # nil for a file that is not there — a state in its own right for a link, so
+      # a target appearing or vanishing moves the stamp exactly as an edit does.
+      def file_stamp(path)
+        stat = ::File.stat(path)
         [ stat.mtime.to_f, stat.size ]
       rescue SystemCallError
         nil

data/lib/okf/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module OKF
   module MCP
-    VERSION = "1.2.0"
+    VERSION = "1.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-mcp
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -15,21 +15,21 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.2'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: okf
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 2.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -39,7 +39,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 2.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -56,6 +56,27 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".okf/capabilities/index.md"
+- ".okf/capabilities/resources-and-prompts.md"
+- ".okf/capabilities/tools.md"
+- ".okf/capabilities/transports.md"
+- ".okf/design/index.md"
+- ".okf/design/kernel-first.md"
+- ".okf/design/one-entry-point.md"
+- ".okf/design/ruby-floor.md"
+- ".okf/design/runtime-dependencies.md"
+- ".okf/design/the-tool-set.md"
+- ".okf/index.md"
+- ".okf/log.md"
+- ".okf/overview.md"
+- ".okf/structure/doors.md"
+- ".okf/structure/http-bridge.md"
+- ".okf/structure/index.md"
+- ".okf/structure/served-set.md"
+- ".okf/structure/server-definition.md"
+- ".okf/testing/adding-a-tool.md"
+- ".okf/testing/index.md"
+- ".okf/testing/layers.md"
 - CHANGELOG.md
 - LICENSE.txt
 - NOTICE
@@ -75,14 +96,14 @@ files:
 - lib/okf/mcp/server.rb
 - lib/okf/mcp/version.rb
 - lib/okf/plugin.rb
-homepage: https://github.com/serradura/okf-gem
+homepage: https://github.com/serradura/okf
 licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/serradura/okf-gem
-  source_code_uri: https://github.com/serradura/okf-gem
-  changelog_uri: https://github.com/serradura/okf-gem/blob/main/okf-mcp/CHANGELOG.md
+  homepage_uri: https://github.com/serradura/okf
+  source_code_uri: https://github.com/serradura/okf
+  changelog_uri: https://github.com/serradura/okf/blob/main/gems/okf-mcp/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: