okf-mcp 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16fa224a5cb1c83ae561094458afe95726a3f04c94a35e56db94b260a2a213bc
-  data.tar.gz: 06027d6762f7f35510d22fc124ecd8e473249bb492baea09238fcd23dafd01a1
+  metadata.gz: 6f19f69227417cc91ee456e6fca9f517ae1d8f4d571bb7423c7d76d4e38df238
+  data.tar.gz: dcd1b33fb97cb5eb47bbf01681b2b291d26b035c33d9dc5585422edd3f00e165
 SHA512:
-  metadata.gz: 7e37dd09203d6ace0e2a6394a3efdc8551bc3f74bd0e53c7e30c27795cbb7f9fa3975bb9d5697bc4afdcabbef075300386362a0f4f7f79d7ec863beb638f31bb
-  data.tar.gz: 4c82c6fdf6fe68a04cc109d4ed3187606f6e276cdfc0cbf0368680d36cd2e2f67c05062304e3698cd473c739de5ac7089c2856c612c742718f5a9e0c251636e6
+  metadata.gz: 1821ef4c6684ec3ca30d3368f1c4ee07c308f24693278b38866e91f2ad1b12b8f742d45cc42c02d002c5f75bd9cd007e64aec155de439c1f2a47d9c12bedc0f8
+  data.tar.gz: 399fdd6c71fad193ce28256b5982d6de87fe547ac818aa4813a72981f8afe8733488f91a420c0232dc58221bcd29dd31f2a8fa318ffc584af521fd8d1d9d0279

data/CHANGELOG.md

@@ -5,6 +5,84 @@ 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.1.0] - 2026-08-14
+
+### Added
+
+- **`tags`, `types` and `stats` — the CLI's remaining read views, as tools.** `tags`
+  ships with the `by: "dir" | "type"` curation view — the kernel's
+  `Bundle#tag_groups`, extracted so the within-group-beside-total counting
+  has one home — and `stats` reads the kernel's new `Bundle#stats`, whose
+  `by_dir` keeps the honest zero a directory holding nothing directly
+  reports. `files` is deliberately not a tool: `index`'s per-directory
+  listing and `catalog`'s projection already carry its whole answer, and
+  tool-list weight is a real cost on hosts.
+- **`lint` takes `today`** — the CLI's `--today`, in the same deliberately
+  narrow calendar-day grammar (a reinterpretable `20260101` or a
+  `2026-02-30` is refused by name), so an `expired` report is reproducible
+  and citable. The wall clock stays the default.
+- **`fields`/`except` projection on `search`, and `except` on `catalog`** —
+  the row-key vocabulary is checked either way, so a typo is refused by
+  name even when a query matches nothing; the pair is mutually exclusive.
+- **`references`, the eleventh tool** — the kernel's §6.3 inventory over MCP,
+  and the one lens that sees a bundle's non-markdown files: every
+  `references/` entry with the concepts citing it through the §6.2
+  path-valued fields, plus every pointer that resolves to nothing (a bare
+  `references/…` from a subdirectory is the classic miss; the dangling entry
+  names the leading-slash fix). Advisory like every read tool — dangling
+  pointers are data, never a tool error.
+- **`graph`'s traffic view takes `cut`** — the CLI's `--cut N`, so a client
+  can widen past the fitted threshold or narrow below it. Outside
+  `view: "traffic"` it is refused: a half-honored argument is the
+  silent-wrong-answer shape.
+
+### Changed
+
+- **`search` narrows by `status` and `trust`**, the two filters `catalog` and
+  `okf search` already took. An agent that learned the vocabulary from either
+  one and brought it here got an invalid-argument error. They resolve through
+  the catalog rather than the engine's rows — a search row carries what the
+  engine matched on, and the §5 families are not among it.
+
+- **`lint`'s `stale_after` takes the kernel's cutoff grammar** — a
+  `YYYY-MM-DD` date or a full timestamp — rather than everything
+  `Date.iso8601` parses. `20260101` and `2026-W01-1` are now tool errors
+  naming the accepted shapes; a `generated.at`-shaped timestamp is accepted,
+  as before, and reduced to its date. They were accepted before
+  and silently reinterpreted — `okf lint --stale-after 20260101` exits 2, so
+  the shell and its own CLI answered differently about one bundle's staleness.
+
+- **The okf floor must move to okf's v0.2 release number in the release that
+  ships this** — the shell now reads v0.2 surfaces (the trust catalog column,
+  `Concept.effective_status`/`fold_tier`, the linter's clock contract), none
+  of which exist in published okf 1.13.0; the gemspec carries the same
+  RELEASE OBLIGATION note, and the floor cannot move sooner because the
+  monorepo resolves against the path-sourced okf still versioned 1.13.0.
+  `rake release` now refuses while the floor still admits 1.13.0 (the guard
+  hangs off `release:guard_clean`, ahead of both pushes, and deliberately not
+  off `build` — `rake install` depends on that), so the obligation stops a
+  release rather than riding inside one.
+- The catalog tool speaks v0.2: `CATALOG_FIELDS` matches the new row
+  (`timestamp` is gone — the vocabulary refuses it by name), `status` narrows
+  on the effective value through the kernel's own fold, and a `trust` filter
+  lands beside it. `lint` supplies the clock the `expired` check needs, the
+  way the CLI does, and the client-visible descriptions and prompts cite
+  v0.2's chapter numbers.
+
+### Fixed
+
+- **`search`'s declared output schema now carries `skipped`** — the field the
+  tool emits when `"*"` forgives a vanished bundle. A host typing its
+  structured-content handling off `outputSchema` dropped it, and the SDK's
+  result validation (on in the test suite) failed a payload the tool
+  genuinely produces; slugs, not rows, and never required.
+- **An out-of-range `--port` or unresolvable `--bind` is a usage error.** The
+  socket layer raises `SocketError` (Socket::ResolutionError on newer
+  Rubies), which the boot rescue did not name, so a typo came back as a
+  backtrace and exit 1 instead of the one readable line and exit 2 every
+  other boot failure earns.
+
+
 ## [1.0.0] - 2026-08-07
 
 The first functional release: an MCP server over the okf kernel, judged by
@@ -213,5 +291,6 @@ rather than pretending to be changes somebody could have seen.
 
 The name reservation on RubyGems: an empty gem, no functionality.
 
+[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
 [0.0.0]: https://rubygems.org/gems/okf-mcp/versions/0.0.0

data/README.md

@@ -91,27 +91,38 @@ to pin the set instead.
 
 ## Tools
 
-Ten read-only tools. Every list answer is bounded and names the full count it
-was cut from — the rows the request matched, before any `limit`:
+Fourteen read-only tools. Every list answer is bounded and names the full
+count it was cut from — the rows the request matched, before any `limit`:
 
 | Tool | What it answers |
 |---|---|
 | `list_bundles` | what exists: slug, title, root, concept count, type/tag rollups, the default, the groups, the backend |
 | `dirs` | the shape — one row per directory with direct and subtree counts; **the first move** |
 | `index` | the index map: authored index bodies, rollups, listings, one directory at a time (depth 1 by default) |
-| `search` | pointed questions: ANDed terms, scored rows carrying the fields they matched, across several bundles at once |
+| `search` | pointed questions: ANDed terms, scored rows carrying the fields they matched, across several bundles at once; narrows by `type`, `dir`, `tag`, `status`, `trust`; `fields`/`except` project the rows |
 | `read_concept` | one concept's file, verbatim and live from disk; ids are exact |
-| `catalog` | per-concept metadata with link degrees; filters, paging, field projection |
+| `catalog` | per-concept metadata with link degrees; the same five filters, paging, `fields`/`except` projection |
 | `log` | every `log.md`, root first, live — the newest 3 dated entries per file, each answer held to a byte budget `limit` scales; a cut says `truncated` |
-| `validate` | the spec §9 conformance verdict |
-| `lint` | the curation-quality report; `group: "folder"` lists the unlinked files by folder |
-| `graph` | the knowledge graph in three bounded views: minimal, hubs, traffic — never with bodies |
+| `validate` | the spec §11 conformance verdict |
+| `lint` | the curation-quality report; `group: "folder"` lists the unlinked files by folder; `today` pins the clock for a reproducible `expired` report |
+| `graph` | the knowledge graph in three bounded views: minimal, hubs, traffic (`cut` widens or narrows the arcs) — never with bodies |
+| `references` | the §6.3 inventory: every `references/` file — `.py` attesters and `.sql` computations included — with its citing concepts, and the pointers that resolve to nothing |
+| `tags` | the tag index by count; `by: "dir"` or `"type"` regroups for vocabulary curation, within-group counts beside cross-bundle totals |
+| `types` | the type index by count — how you learn what a producer meant by its open §4.1 vocabulary |
+| `stats` | the sizing rollup: concepts, dirs, cross-links, distinct tags, and the by_type/by_dir/by_top_dir distributions |
 
 Each returns its JSON twice: as text, and as `structuredContent` against a
 declared `outputSchema`, so a host consumes a result without parsing a blob and
 guessing at its shape. `read_concept` is the exception — markdown has no object
 shape to declare.
 
+The `status` and `trust` filters answer with the §5 families' vocabulary
+(`draft | stable | deprecated`; `unverified | machine-confirmed |
+human-reviewed`, either spelling). On `search` they narrow through the
+catalog rather than the engine's rows — a search row carries what the engine
+matched on, and the §5 families are not among it — so a `trust` that narrows
+`catalog` narrows `search` identically.
+
 ## Prompts
 
 Two prompts, the consuming pair: `okf-search` — retrieval as progressive

data/lib/okf/mcp/cli.rb

@@ -62,7 +62,7 @@ module OKF
           server = Server.build(registry, engine: engine)
           announce(registry, engine)
           prepare_http(server) if @http
-        rescue Error, OKF::Error, OptionParser::ParseError, SystemCallError => e
+        rescue Error, OKF::Error, OptionParser::ParseError, SystemCallError, SocketError => e
           say("okf-mcp: #{e.message}")
           say(USAGE)
           return 2

data/lib/okf/mcp/filters.rb

@@ -10,13 +10,18 @@ module OKF
     # reported an empty bundle root while `search` and `dirs` answered for it.
     # Two copies of a rule is two answers waiting to disagree, so there is one.
     #
-    # There are genuinely **two** rules here, and the distinction is not drift:
+    # There are genuinely **two** rules here, and the distinction is not drift.
+    # Only one of them still lives in this file:
     #
-    #   #under_dir?  filters *concepts*. A dir names itself and everything
-    #                beneath it; `.` is a prefix of nothing, so the root
+    #   concepts     are filtered by `Bundle::RowFilter`, the kernel's one
+    #                catalog-row predicate — a dir names itself and everything
+    #                beneath it, and `.` is a prefix of nothing, so the root
     #                selects only what lives directly in it (the CLI's `--dir`).
+    #                This module's job there is #normalize_dir, the spelling
+    #                fold the kernel deliberately does not do.
     #   #within?     scopes a *tree* of directory rows, where the root is the
-    #                ancestor of every row (`dirs`/`index` walking down).
+    #                ancestor of every row (`dirs`/`index` walking down). The
+    #                kernel has no view of a directory tree, so this one stays.
     module Filters
       module_function
 
@@ -48,13 +53,6 @@ module OKF
         folded.empty? || folded == "." ? "." : folded
       end
 
-      # Concept filtering: `dir` names itself and everything beneath it.
-      def under_dir?(entry_dir, wanted)
-        entry = fold(entry_dir)
-        path = normalize_dir(wanted)
-        entry == path || entry.start_with?("#{path}/")
-      end
-
       # Tree scoping: the root is the ancestor of every row, so `.` selects
       # the whole tree rather than only what sits directly in it.
       def within?(entry_dir, base)

data/lib/okf/mcp/memory_backend.rb

@@ -10,7 +10,7 @@ module OKF
     # deliberately no disk cache here — the process is the cache; disk-side
     # state is okf-sqlite3's territory.
     class MemoryBackend
-      FILTER_KEYS = %i[type tag dir status].freeze
+      FILTER_KEYS = %i[type tag dir status trust].freeze
 
       # How many prepared corpora to hold at once, most-recently-used first.
       # It used to be unbounded, keyed on the queried subset — a long-lived
@@ -168,17 +168,21 @@ module OKF
         end
       end
 
+      # The kernel's one row predicate (Bundle::RowFilter), not a local copy:
+      # this seam diverged three recorded times, and the fix each time was to
+      # share the rule. This layer keeps only its own argument spelling —
+      # blanks mean "no filter" (an MCP client filling every optional property
+      # with "" is routine), and ""/"/" fold onto the root before the shared
+      # dir rule sees them.
       def matches?(row, filters)
-        FILTER_KEYS.all? do |key|
+        wants = {}
+        FILTER_KEYS.each do |key|
           wanted = filters[key]
-          next true if OKF.blank?(wanted)
+          next if OKF.blank?(wanted)
 
-          case key
-          when :tag then Array(row[:tags]).map { |tag| Filters.fold(tag) }.include?(Filters.fold(wanted))
-          when :dir then Filters.under_dir?(row[:dir], wanted)
-          else Filters.fold(row[key]) == Filters.fold(wanted)
-          end
+          wants[key] = key == :dir ? Filters.normalize_dir(wanted) : wanted
         end
+        Bundle::RowFilter.matches?(row, **wants)
       end
 
       # What the residency cache watches: every markdown file with its mtime

data/lib/okf/mcp/output_schemas.rb

@@ -62,7 +62,12 @@ module OKF
             bundles: ROWS,
             total: COUNT,
             results: ROWS,
-            unparseable: UNPARSEABLE
+            unparseable: UNPARSEABLE,
+            # Present only when "*" or a group forgave a vanished bundle —
+            # conditional, so never required; slugs, not rows. Omitting it
+            # entirely is how a real field failed result validation the first
+            # time it appeared.
+            skipped: { type: "array", items: SLUG }
           },
           required: %w[query engine bundles total results]
         },
@@ -70,6 +75,13 @@ module OKF
           properties: { bundle: SLUG, total: COUNT, concepts: ROWS, unparseable: UNPARSEABLE },
           required: %w[bundle total concepts]
         },
+        # `dangling` is always present (empty when nothing misses): an absent
+        # list would read as "not checked", which is the one thing an
+        # inventory must never say by accident.
+        "references" => {
+          properties: { bundle: SLUG, total: COUNT, references: ROWS, dangling: ROWS, unparseable: UNPARSEABLE },
+          required: %w[bundle total references dangling]
+        },
         # `total` is entries across every log file and `files` how many files
         # they came from — two different counts, both named, because one
         # standing for the other is what let an unbounded 119 KB answer read
@@ -78,6 +90,30 @@ module OKF
           properties: { bundle: SLUG, total: COUNT, files: COUNT, logs: ROWS },
           required: %w[bundle total files logs]
         },
+        # Two shapes, like lint's: the plain inverted index (`tags`) and the
+        # `by` regrouping (`groups`). Only what both carry is required.
+        "tags" => {
+          properties: {
+            bundle: SLUG, total: COUNT, tags: ROWS,
+            by: { type: "string" }, groups: ROWS,
+            unparseable: UNPARSEABLE
+          },
+          required: %w[bundle total]
+        },
+        "types" => {
+          properties: { bundle: SLUG, total: COUNT, types: ROWS, unparseable: UNPARSEABLE },
+          required: %w[bundle total types]
+        },
+        "stats" => {
+          properties: {
+            bundle: SLUG,
+            concepts: COUNT, dirs: COUNT, top_dirs: COUNT, concept_types: COUNT,
+            cross_links: COUNT, distinct_tags: COUNT,
+            by_type: { type: "object" }, by_dir: { type: "object" }, by_top_dir: { type: "object" },
+            unparseable: UNPARSEABLE
+          },
+          required: %w[bundle concepts dirs top_dirs concept_types cross_links distinct_tags by_type by_dir by_top_dir]
+        },
         "validate" => {
           properties: {
             bundle: SLUG,

data/lib/okf/mcp/prompts/search.md

@@ -1,7 +1,7 @@
 # Prompt: search — retrieve knowledge without paying for the whole bundle
 
 Retrieval matters as much as curation: a bundle nobody can query cheaply is
-dead weight. The discipline is progressive disclosure (spec §6): every step
+dead weight. The discipline is progressive disclosure (spec §8): every step
 pays a few hundred bytes to decide what the next step reads, and full bodies
 are read last, and only the winners.
 
@@ -49,7 +49,7 @@ are read last, and only the winners.
    an id home.
 4. **Read only the winners.** `read_concept` takes a result row's exact `id`
    and returns the file verbatim — that concept, not its folder, never the
-   whole tree. Follow its links (§5) one hop at a time; check `log` when
+   whole tree. Follow its links (§6) one hop at a time; check `log` when
    freshness matters.
 5. **Answer, then surface the friction.** Cite the concept ids you used. This
    server never writes — if the answer was missing, stale, or needlessly hard

data/lib/okf/mcp/server.rb

@@ -33,6 +33,16 @@ module OKF
       ROLLUP_LIMIT = 25
 
       SEARCH_LIMIT = 20
+
+      # The two concept dimensions `tags` regroups by (§4.1's `type`, the
+      # file's directory) — the same pair the CLI's `--by` offers, minus its
+      # deprecated `area` spelling, which a new surface does not inherit.
+      TAG_DIMENSIONS = %w[type dir].freeze
+
+      # The keys a search result row carries — the vocabulary `fields`/`except`
+      # project against, declared so a typo is refused by name even when a
+      # query happens to match nothing.
+      SEARCH_ROW_FIELDS = %w[bundle id title type tags matched score snippet].freeze
       CATALOG_LIMIT = 200
 
       # Date-grouped entries returned per log.md. A log is the one file in a
@@ -44,7 +54,7 @@ module OKF
       # for more.
       LOG_LIMIT = 3
 
-      # A §7 log is "a flat list of date-grouped entries, newest first", so a
+      # A §9 log is "a flat list of date-grouped entries, newest first", so a
       # `## ` heading at column 0 is the entry boundary. Split kept here rather
       # than pushed into the kernel because bounding for a context window is
       # this surface's problem alone: the graph page's Log panel wants the
@@ -63,7 +73,8 @@ module OKF
       LOG_BUDGET = 4_500
 
       # The catalog row, the projection vocabulary `fields` selects from.
-      CATALOG_FIELDS = %w[id title type description tags timestamp status backlog_ref dir top_dir links_out links_in].freeze
+      CATALOG_FIELDS = %w[id title type description tags generated_at generated_by generated trust status
+                          stale_after sources backlog_ref dir top_dir links_out links_in].freeze
 
       GRAPH_VIEWS = %w[minimal hubs traffic].freeze
       LINT_GROUPS = %w[check folder].freeze
@@ -228,10 +239,98 @@ module OKF
             log_tool(context),
             validate_tool(context),
             lint_tool(context),
-            graph_tool(context)
+            graph_tool(context),
+            references_tool(context),
+            tags_tool(context),
+            types_tool(context),
+            stats_tool(context)
           ]
         end
 
+        # tags' plain view is the inverted index; `by` is the curation view —
+        # the kernel's Bundle#tag_groups, so a within-group count beside its
+        # cross-bundle total reads identically here and on the CLI.
+        def tags_tool(context)
+          define_tool(
+            name: "tags",
+            description: "The tag index: every tag with its count and concepts, ordered by count. " \
+                         "`by: \"dir\"` or `by: \"type\"` regroups per concept dimension for vocabulary " \
+                         "curation — each tag then carries `count` (within the group) beside `total` " \
+                         "(across the bundle), so a tag local to one group and one scattered across " \
+                         "several read differently at a glance.",
+            input_schema: {
+              properties: {
+                bundle: { type: "string", description: "A bundle slug from list_bundles." },
+                by: { type: "string", enum: TAG_DIMENSIONS,
+                      description: "Regroup per concept dimension: #{TAG_DIMENSIONS.join(" | ")}." }
+              },
+              required: [ "bundle" ]
+            }
+          ) do |bundle:, by: nil|
+            folder = context.folder(bundle)
+            if by
+              groups = folder.tag_groups(by: by.to_sym)
+              distinct = groups.flat_map { |_, rows| rows.map { |row| row[:tag] } }.uniq.length
+              rows = groups.map { |key, tag_rows| { by.to_sym => key, count: tag_rows.length, tags: tag_rows } }
+              respond_json(with_unparseable(folder,
+                bundle: slug_of(context, bundle), total: distinct, by: by, groups: rows))
+            else
+              rows = inverted_rows(folder.graph(minimal: true).tag_index, :tag)
+              respond_json(with_unparseable(folder,
+                bundle: slug_of(context, bundle), total: rows.length, tags: rows))
+            end
+          end
+        end
+
+        def types_tool(context)
+          define_tool(
+            name: "types",
+            description: "The type index: every type with its count and concepts, ordered by count. " \
+                         "§4.1's vocabulary is open — this is how you learn what a bundle's producer " \
+                         "meant by its types before filtering the catalog on one.",
+            input_schema: {
+              properties: {
+                bundle: { type: "string", description: "A bundle slug from list_bundles." }
+              },
+              required: [ "bundle" ]
+            }
+          ) do |bundle:|
+            folder = context.folder(bundle)
+            rows = inverted_rows(folder.graph(minimal: true).type_index, :type)
+            respond_json(with_unparseable(folder,
+              bundle: slug_of(context, bundle), total: rows.length, types: rows))
+          end
+        end
+
+        # The sizing rollup — the kernel's Bundle#stats, whose by_dir keeps the
+        # zero a directory holding nothing directly honestly reports. The two
+        # dir keys deliberately speak two languages: by_dir is the disk,
+        # by_top_dir rolls up the id (the recorded identity-vs-physical split).
+        def stats_tool(context)
+          define_tool(
+            name: "stats",
+            description: "Bundle rollups in one answer: concepts, dirs, types, cross-links, distinct " \
+                         "tags, and the by_type/by_dir/by_top_dir distributions — \"how big is what I am " \
+                         "about to read\". by_dir counts the file's directory (a dir holding nothing " \
+                         "directly reports 0); by_top_dir rolls up the concept id's first segment.",
+            input_schema: {
+              properties: {
+                bundle: { type: "string", description: "A bundle slug from list_bundles." }
+              },
+              required: [ "bundle" ]
+            }
+          ) do |bundle:|
+            folder = context.folder(bundle)
+            rollup = folder.stats
+            respond_json(with_unparseable(folder,
+              bundle: slug_of(context, bundle),
+              concepts: rollup[:concepts], dirs: rollup[:dirs], top_dirs: rollup[:top_dirs],
+              concept_types: rollup[:types], cross_links: rollup[:cross_links],
+              distinct_tags: rollup[:tags],
+              by_type: rollup[:by_type], by_dir: rollup[:by_dir], by_top_dir: rollup[:by_top_dir]))
+          end
+        end
+
         # The consuming prompts, and only those — this gem's own text, written
         # against the tools above rather than the CLI. The skill's playbooks
         # were served here verbatim once, all eight, on the argument that a
@@ -392,7 +491,15 @@ module OKF
                 type: { type: "string", description: "Only concepts of this type." },
                 dir: { type: "string", description: "Only concepts in this directory or below it (\".\" for the bundle root)." },
                 tag: { type: "string", description: "Only concepts carrying this tag." },
-                limit: { type: "integer", minimum: 1, description: "Maximum rows to return (default #{SEARCH_LIMIT}); `total` is the count before the cut." }
+                status: { type: "string",
+                          description: "Only concepts at this effective lifecycle status " \
+                                       "(absent reads stable — draft | stable | deprecated, or any declared value)." },
+                trust: { type: "string", description: "Only concepts at this trust tier (unverified | machine-confirmed | human-reviewed; either spelling)." },
+                limit: { type: "integer", minimum: 1, description: "Maximum rows to return (default #{SEARCH_LIMIT}); `total` is the count before the cut." },
+                fields: { type: "array", items: { type: "string" },
+                          description: "Emit only these result-row keys (#{SEARCH_ROW_FIELDS.join(", ")})." },
+                except: { type: "array", items: { type: "string" },
+                          description: "Emit every result-row key but these (mutually exclusive with fields)." }
               },
               required: [ "terms" ]
             }
@@ -440,7 +547,8 @@ module OKF
             name: "catalog",
             description: "Per-concept metadata for a whole bundle — #{CATALOG_FIELDS.join(", ")} — " \
                          "filterable by type, dir (prefix: a dir names itself and everything beneath " \
-                         "it), tag, and status. Use it for inventories and rollups; use search when you " \
+                         "it), tag, status (effective: absent reads stable) and trust tier. Use it for " \
+                         "inventories and rollups; use search when you " \
                          "have terms. Returns `limit` rows (default #{CATALOG_LIMIT}) from `offset`; `total` is the " \
                          "full count before slicing. `fields` projects each row down to the named keys.",
             input_schema: {
@@ -449,23 +557,27 @@ module OKF
                 type: { type: "string", description: "Only concepts of this type." },
                 dir: { type: "string", description: "Only concepts in this directory or below it (\".\" for the bundle root)." },
                 tag: { type: "string", description: "Only concepts carrying this tag." },
-                status: { type: "string", description: "Only concepts with this frontmatter status." },
+                status: { type: "string",
+                          description: "Only concepts at this effective lifecycle status " \
+                                       "(absent reads stable — draft | stable | deprecated, or any declared value)." },
+                trust: { type: "string", description: "Only concepts at this trust tier (unverified | machine-confirmed | human-reviewed; either spelling)." },
                 fields: { type: "array", items: { type: "string" }, description: "Emit only these row keys (#{CATALOG_FIELDS.join(", ")})." },
+                except: { type: "array", items: { type: "string" }, description: "Emit every row key but these (mutually exclusive with fields)." },
                 limit: { type: "integer", minimum: 1, description: "Maximum concepts to return (default #{CATALOG_LIMIT})." },
                 offset: { type: "integer", minimum: 0, description: "Skip this many concepts first (default 0)." }
               },
               required: [ "bundle" ]
             }
-          ) do |bundle:, type: nil, dir: nil, tag: nil, status: nil, fields: nil, limit: CATALOG_LIMIT, offset: 0|
+          ) do |bundle:, type: nil, dir: nil, tag: nil, status: nil, trust: nil, fields: nil, except: nil, limit: CATALOG_LIMIT, offset: 0|
             root = context.root!(bundle)
-            projection = check_fields(fields)
+            keep, drop = check_projection(fields, except)
             # One folder, held: the `dir` check and the unparseable count both
             # want it, and asking the residency layer twice walks the tree twice.
             folder = context.memory.folder(root)
             check_dir!(context, [ [ slug_of(context, bundle), root ] ], dir)
-            rows = context.engine.catalog(root, { type: type, dir: dir, tag: tag, status: status })
+            rows = context.engine.catalog(root, { type: type, dir: dir, tag: tag, status: status, trust: trust })
             sliced = rows[offset, limit] || []
-            sliced = sliced.map { |row| row.select { |key, _| projection.include?(key.to_s) } } if projection
+            sliced = project_rows(sliced, keep, drop)
             respond_json(with_unparseable(folder,
               bundle: slug_of(context, bundle), total: rows.length, concepts: sliced))
           end
@@ -499,7 +611,7 @@ module OKF
         def validate_tool(context)
           define_tool(
             name: "validate",
-            description: "The spec §9 conformance verdict: `conformant` (hard errors empty), every error " \
+            description: "The spec §11 conformance verdict: `conformant` (hard errors empty), every error " \
                          "and soft warning with its file and why — unopenable files included. Read-only: " \
                          "you may flag what it finds; fixing it belongs to the okf skill and CLI. " \
                          "Curation quality is lint's question, kept deliberately separate.",
@@ -525,10 +637,11 @@ module OKF
           define_tool(
             name: "lint",
             description: "The curation-quality report — reachability, backlog, completeness, freshness, " \
-                         "provenance, hygiene — as warnings and infos that never reject (conformance is " \
-                         "validate's question). `only`/`except` select by check id " \
-                         "(#{Bundle::Linter::CHECKS.join(", ")}). `stale_after` turns on freshness: a " \
-                         "duration like 90d or 12w, or an ISO date. `group: \"folder\"` answers \"which " \
+                         "provenance, attestation, migration, hygiene — as warnings and infos that never " \
+                         "reject (conformance is validate's question). `only`/`except` select by check id " \
+                         "(#{Bundle::Linter::CHECKS.join(", ")}). `stale_after` turns on the age cutoff: a " \
+                         "duration like 90d or 12w, or an ISO date (declared expiries — `expired` — report " \
+                         "out of the box). `group: \"folder\"` answers \"which " \
                          "files float in the graph?\" instead — the unlinked concepts grouped by folder. " \
                          "Noticing rot is yours; fixing it belongs to the okf skill and CLI.",
             input_schema: {
@@ -539,12 +652,15 @@ module OKF
                 stale_after: { type: "string", description: "Flag concepts older than this: 90d, 12w, or an ISO date like 2026-01-01." },
                 only: { type: "array", items: { type: "string" }, description: "Run only these checks (by check id)." },
                 except: { type: "array", items: { type: "string" }, description: "Run every check but these (by check id)." },
-                group: { type: "string", enum: LINT_GROUPS, description: "\"check\" (default) or \"folder\" — the unlinked files grouped by folder." }
+                group: { type: "string", enum: LINT_GROUPS, description: "\"check\" (default) or \"folder\" — the unlinked files grouped by folder." },
+                today: { type: "string",
+                         description: "The calendar day `expired` compares stale_after against, YYYY-MM-DD " \
+                                      "(default: today) — pin it for a reproducible, citable report." }
               },
               required: [ "bundle" ]
             }
-          ) do |bundle:, min_body: nil, stale_after: nil, only: nil, except: nil, group: "check"|
-            lint_call(context, bundle, min_body, stale_after, only, except, group)
+          ) do |bundle:, min_body: nil, stale_after: nil, only: nil, except: nil, group: "check", today: nil|
+            lint_call(context, bundle, min_body, stale_after, only, except, group, today)
           end
         end
 
@@ -560,12 +676,40 @@ module OKF
             input_schema: {
               properties: {
                 bundle: { type: "string", description: "A bundle slug from list_bundles." },
-                view: { type: "string", enum: GRAPH_VIEWS, description: "One of #{GRAPH_VIEWS.join(", ")} (default minimal)." }
+                view: { type: "string", enum: GRAPH_VIEWS, description: "One of #{GRAPH_VIEWS.join(", ")} (default minimal)." },
+                cut: { type: "integer", minimum: 1,
+                       description: "traffic only: least arc weight to draw (default: fitted to the bundle)." }
+              },
+              required: [ "bundle" ]
+            }
+          ) do |bundle:, view: "minimal", cut: nil|
+            graph_call(context, bundle, view, cut)
+          end
+        end
+
+        # The kernel's §6.3 inventory as a tool: the one lens that sees the
+        # non-markdown files a bundle carries. Advisory like every read here —
+        # a dangling pointer is data for the caller, never a tool error.
+        def references_tool(context)
+          define_tool(
+            name: "references",
+            description: "Inventory the bundle's references/ tree (§6.3): every file — the .py attesters " \
+                         "and .sql computations no other tool can see included — with the concepts citing " \
+                         "each through the §6.2 path-valued fields (resource, sources[].resource, " \
+                         "computation, executor.resource, attester.resource), plus every pointer into " \
+                         "references/ that resolves to nothing. A bare `references/…` written from a " \
+                         "subdirectory is the classic miss, and the dangling entry names the " \
+                         "leading-slash fix. Check it before trusting an attested computation's contract.",
+            input_schema: {
+              properties: {
+                bundle: { type: "string", description: "A bundle slug from list_bundles." }
               },
               required: [ "bundle" ]
             }
-          ) do |bundle:, view: "minimal"|
-            graph_call(context, bundle, view)
+          ) do |bundle:|
+            refs = context.folder(bundle).references
+            respond_json(bundle: slug_of(context, bundle), total: refs.entries.length,
+              references: refs.entries, dangling: refs.dangling)
           end
         end
 
@@ -588,6 +732,8 @@ module OKF
           check_dir!(context, pairs, options[:dir])
           rows = engine_rows(context, pairs, terms, fields, regexp, fuzzy, engine)
           rows = filter_rows(rows, options)
+          rows = narrow_by_catalog(rows, pairs, context, options)
+          keep, drop = check_projection(options[:fields], options[:except], allowed: SEARCH_ROW_FIELDS)
           limit = options[:limit] || SEARCH_LIMIT
 
           payload = {
@@ -599,12 +745,12 @@ module OKF
             # difference decides whether a miss means "absent" or "the
             # tokenizer shattered the identifier".
             engine: fuzzy || engine.to_s == "index" ? "index" : "scan",
-            # §9 best-effort, surfaced per bundle: a corpus built from a folder
+            # §11 best-effort, surfaced per bundle: a corpus built from a folder
             # that skipped unusable files must say so, or a term living only in
             # an unreadable file reads back as "this bundle does not mention it".
             bundles: pairs.map { |slug, root| bundle_head_row(context, slug, root) },
             total: rows.length,
-            results: rows.first(limit).map { |row| search_row(row, pairs) }
+            results: project_rows(rows.first(limit).map { |row| search_row(row, pairs) }, keep, drop)
           }
           payload[:skipped] = skipped unless skipped.empty?
           respond_json(payload)
@@ -690,13 +836,38 @@ module OKF
         # MCP client that fills every declared optional property with an empty
         # default (routine model behaviour) was handing `search` a filter that
         # matched nothing — while `catalog`, one tool over, read the same ""
-        # as "no filter" and answered for the whole bundle.
+        # as "no filter" and answered for the whole bundle. The row rules
+        # themselves are the kernel's one predicate (Bundle::RowFilter).
         def filter_rows(rows, options)
-          rows.select do |row|
-            (OKF.blank?(options[:type]) || Filters.fold(row[:type]) == Filters.fold(options[:type])) &&
-              (OKF.blank?(options[:dir]) || Filters.under_dir?(row[:dir], options[:dir])) &&
-              (OKF.blank?(options[:tag]) || Array(row[:tags]).any? { |tag| Filters.fold(tag) == Filters.fold(options[:tag]) })
+          wants = {}
+          %i[type dir tag].each do |key|
+            wanted = options[key]
+            next if OKF.blank?(wanted)
+
+            wants[key] = key == :dir ? Filters.normalize_dir(wanted) : wanted
           end
+          rows.select { |row| Bundle::RowFilter.matches?(row, **wants) }
+        end
+
+        # `status` and `trust` narrow through the catalog rather than through
+        # #filter_rows, because a search row carries what the engine matched on
+        # and the §5 families are not among it — handed to RowFilter they would
+        # read as absent and match nothing, which is worse than not offering
+        # the filter. So they resolve the way `okf search --status/--trust`
+        # resolves them: ask the catalog which ids qualify, per bundle, and
+        # keep the rows that survive. Same predicate underneath, so a `trust`
+        # that narrows `catalog` narrows `search` identically.
+        def narrow_by_catalog(rows, pairs, context, options)
+          wants = {}
+          %i[status trust].each do |key|
+            wants[key] = options[key] unless OKF.blank?(options[key])
+          end
+          return rows if wants.empty?
+
+          allowed = {}
+          pairs.each { |slug, root| allowed[slug] = context.engine.catalog(root, wants).to_set { |row| row[:id] } }
+          only = pairs.length == 1 ? pairs.first.first : nil
+          rows.select { |row| allowed[row[:slug] || only]&.include?(row[:id]) }
         end
 
         # The protocol row: `bundle` leads (identity first), the head already
@@ -715,7 +886,7 @@ module OKF
           }
         end
 
-        def lint_call(context, bundle, min_body, stale_after, only, except, group)
+        def lint_call(context, bundle, min_body, stale_after, only, except, group, today = nil)
           folder = context.folder(bundle)
           if group == "folder"
             # The folder lens *is* the unlinked check, so the check-selection
@@ -723,7 +894,7 @@ module OKF
             # while silently dropping them let a caller read the full listing
             # as though its filter had been applied — and skipped the check-id
             # vocabulary check, so a typo'd id passed here and errored there.
-            offered = { only: only, except: except, min_body: min_body, stale_after: stale_after }
+            offered = { only: only, except: except, min_body: min_body, stale_after: stale_after, today: today }
             given = offered.reject { |_, value| OKF.blank?(value) }.keys
             unless given.empty?
               raise Error, "group \"folder\" is the unlinked lens and takes no #{given.join("/")} — " \
@@ -744,6 +915,14 @@ module OKF
           opts = checks
           opts[:min_body] = min_body unless min_body.nil?
           opts[:stale_before] = parse_stale(stale_after) unless OKF.blank?(stale_after)
+          # The shell owns clock resolution (see parse_stale): the pure linter
+          # runs no `expired` check unless handed a day, the CLI passes
+          # Date.today, and this layer must too — without it, a bundle full of
+          # passed expiries linted healthy through MCP while the CLI reported
+          # every one. `today` pins the day instead — the CLI's --today, the
+          # reproducible-report lever — in the same deliberately narrow
+          # calendar-day grammar.
+          opts[:today] = parse_today(today)
           report = folder.lint(**opts)
           respond_json(
             bundle: slug_of(context, bundle),
@@ -773,7 +952,12 @@ module OKF
           with_unparseable(context.memory.folder(root), row)
         end
 
-        def graph_call(context, bundle, view)
+        def graph_call(context, bundle, view, cut = nil)
+          # A cut outside traffic would be accepted and ignored — the
+          # half-honored argument is the silent-wrong-answer shape, so it
+          # refuses instead. The schema already floors it at 1.
+          raise Error, "cut applies to view: \"traffic\" only (got view: #{view.inspect})" if cut && view != "traffic"
+
           folder = context.folder(bundle)
           payload = with_unparseable(folder, bundle: slug_of(context, bundle), view: view)
           case view
@@ -785,7 +969,7 @@ module OKF
             hubs = folder.hubs
             payload.merge!(total: hubs.length, hubs: hubs)
           when "traffic"
-            payload.merge!(traffic_payload(folder.skeleton))
+            payload.merge!(traffic_payload(folder.skeleton, cut))
           end
           respond_json(payload)
         end
@@ -794,8 +978,8 @@ module OKF
         # arcs above the fitted cut — the CLI's `graph --traffic`, as data. The
         # cohesion is measured over every arc; the cut only decides which arcs
         # are worth returning.
-        def traffic_payload(skeleton)
-          cut = skeleton.suggested_cut
+        def traffic_payload(skeleton, cut = nil)
+          cut ||= skeleton.suggested_cut
           out = Hash.new(0)
           into = Hash.new(0)
           skeleton.arcs.each do |arc|
@@ -896,7 +1080,7 @@ module OKF
         # ("# Runbooks Log") and costs a line.
         #
         # A log the split cannot divide is one indivisible entry, because that
-        # is what content with no boundary is — §7 fixes no heading level, so
+        # is what content with no boundary is — §9 fixes no heading level, so
         # `###` date groups are conformant and `LOG_ENTRY` cannot see them.
         # But a *bare title* is not content: a scaffolded "# Update Log" with
         # no entries yet holds zero, and counting it as one told an agent
@@ -949,7 +1133,7 @@ module OKF
           row
         end
 
-        # §9 best-effort, surfaced: a payload built from a folder that skipped
+        # §11 best-effort, surfaced: a payload built from a folder that skipped
         # unusable files says so, and validate names each file and why.
         def with_unparseable(folder, payload)
           count = folder.bundle.unparseable.length
@@ -1002,15 +1186,83 @@ module OKF
           asked
         end
 
+        # The fields/except pair, checked as one ask: mutually exclusive, both
+        # against the same vocabulary, so a typo'd except is refused by name
+        # exactly the way a typo'd fields always was.
+        def check_projection(fields, except, allowed: CATALOG_FIELDS)
+          if !OKF.blank?(fields) && !OKF.blank?(except)
+            raise Error, "fields and except are mutually exclusive — name what to keep or what to drop, not both"
+          end
+
+          [ check_asked(fields, allowed), check_asked(except, allowed) ]
+        end
+
+        def check_asked(asked, allowed)
+          return nil if OKF.blank?(asked)
+
+          names = Array(asked).map { |field| field.to_s.downcase }
+          unknown = names - allowed
+          raise Error, "unknown field(s): #{unknown.join(", ")} (row keys: #{allowed.join(", ")})" unless unknown.empty?
+
+          names
+        end
+
+        # keep (allowlist) or drop (denylist) per row; both nil passes through.
+        def project_rows(rows, keep, drop)
+          return rows if keep.nil? && drop.nil?
+
+          rows.map do |row|
+            keep ? row.select { |key, _| keep.include?(key.to_s) } : row.reject { |key, _| drop.include?(key.to_s) }
+          end
+        end
+
+        # An inverted index ({ value => [id, …] }) as rows ordered by count
+        # then value — the same order the CLI's index views print.
+        def inverted_rows(index, key)
+          index.map { |value, ids| { key => value, count: ids.length, concepts: ids } }
+               .sort_by { |row| [ -row[:count], row[key] ] }
+        end
+
+        # The calendar day `expired` compares against — wall clock unless the
+        # caller pins one. Not stale_after's grammar: this names a day, not a
+        # moment, and both refuse the basic/week ISO spellings Date.iso8601
+        # would silently reinterpret (20260101, 2026-W01-1) — plus the
+        # digit-shaped day that never existed (2026-02-30).
+        def parse_today(value)
+          return Date.today if OKF.blank?(value)
+
+          text = value.to_s
+          raise Error, today_error(text) unless text.match?(OKF::Concept::ISO_DATE)
+
+          begin
+            Date.iso8601(text)
+          rescue ArgumentError
+            raise Error, today_error(text)
+          end
+        end
+
+        def today_error(text)
+          "today takes a calendar day, YYYY-MM-DD — got #{text.inspect}"
+        end
+
         # A stale_after ask (90d, 12w, or an ISO date) into the absolute Time
         # the pure Linter compares against — the CLI's resolution, kept here in
         # the shell so the linter never reads the clock.
         def parse_stale(value)
-          if (match = value.to_s.match(/\A(\d+)([dw])\z/))
+          text = value.to_s
+          if (match = text.match(/\A(\d+)([dw])\z/))
             days = match[1].to_i * (match[2] == "w" ? 7 : 1)
             Time.now - (days * 86_400)
+          elsif text.match?(Concept::ISO_CUTOFF)
+            # The kernel's cutoff grammar, which is also `okf lint
+            # --stale-after`'s: a date or a full timestamp (what a caller gets
+            # by reading a concept's `generated.at`), never the basic or week
+            # spellings Date.iso8601 would silently reinterpret — this shell
+            # would otherwise answer about one bundle's staleness from a value
+            # its own CLI exits 2 on.
+            Date.iso8601(text).to_time
           else
-            Date.iso8601(value.to_s).to_time
+            raise Error, "invalid stale_after #{value.inspect} — use 90d, 12w, or an ISO date like 2026-01-01"
           end
         rescue ArgumentError
           raise Error, "invalid stale_after #{value.inspect} — use 90d, 12w, or an ISO date like 2026-01-01"

data/lib/okf/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module OKF
   module MCP
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-mcp
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -29,14 +29,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 description: |
   OKF::MCP is a thin Model Context Protocol shell over the okf kernel: it maps
   MCP tool calls onto okf's pure library API so any MCP-capable agent host can