specguard-mcp 0.1.11 → 0.1.13

package/dist/src/tools/list-repositories.js

@@ -1,4 +1,5 @@
-import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js";
+import { getJsonObject, requireUserOrAgentApiConfig } from "../support/specguard-api.js";
+import { optionalString } from "./args.js";
 /**
  * `GET /api/v1/repositories` as a tool — shipped today in the platform
  * (`specguard/config/routes.rb`, `Api::V1::UserRepositoriesController#index`).
@@ -8,9 +9,9 @@ import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js
  * Every other tool here answers about ONE repository the caller has already
  * named — and a bridge that can only answer about a repository you can already
  * name cannot tell an agent which repositories there ARE. `get_repository_overview`
- * does not take a repository: its `sgk_` key IS the repository, so the question
- * "what may I ask about" has no answer anywhere in this server. This is that
- * answer, and it is the whole of what this tool does.
+ * without `repository` does not take a repository: its `sgk_` key IS the repository,
+ * so the question "what may I ask about" has no answer anywhere in this server. This
+ * is that answer, and it is the whole of what this tool does.
  *
  * It is also the tool that proves the second credential slot works end to end,
  * which is why it shipped alone. It no longer IS alone: `add_repository`
@@ -33,20 +34,60 @@ import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js
  * `Api::BaseController` decides which credential table to consult from the
  * token's PREFIX, before any table is read, and answers 401 on a mismatch
  * without a lookup — so this endpoint refuses the `sgk_` key
- * `get_repository_overview` uses, and that one refuses this key. Hence
- * `requireUserApiConfig` rather than `requireApiConfig`: the two are the same
- * function over different variables, and the `Credential` each carries is what
- * makes a 401 or an unset variable name the one the OPERATOR of this tool has
- * to go and fix. See `config.ts`.
+ * `get_repository_overview` uses, and that one refuses this key. Hence a
+ * `require*` helper rather than a raw key: the `Credential` carried on the
+ * resolved config is what makes a 401 or an unset variable name the one the
+ * OPERATOR of this tool has to go and fix. See `config.ts`.
  *
- * == No arguments, because the credential is the whole question
+ * Since SPGD-953 it is `requireUserOrAgentApiConfig`, because SPGD-952 made the
+ * endpoint answer to BOTH key kinds — the person's `accessible_by` set for an
+ * `sgu_` key, the agent key's own granted set for an `sga_` one — and an agent
+ * holding only the agent credential must still be able to ask "what may I ask
+ * about". When both variables are set the agent key wins, so the listing names
+ * the same set every other agent-keyed tool answers inside; the precedence and
+ * its reasoning live on the helper.
  *
- * The endpoint takes no parameters: the person the `sgu_` key speaks for is the
- * entire scope of the answer, and `Repository.accessible_by` — owned UNION
- * shared-through-a-membership — is the platform's read-side boundary rather
- * than a filter this bridge could widen or narrow. A repository the person
- * neither owns nor is a member of never enters the response, so there is
- * nothing here for a parameter to select and nothing an argument could reach.
+ * == The credential is the SCOPE, and the arguments narrow WITHIN it
+ *
+ * This file first shipped argument-less on a premise that has since rotted: it
+ * said "the endpoint takes no parameters", because the credential behind the
+ * key was the entire scope of the answer. That stopped being true on
+ * 2026-09-05, when specguard `ef6236d` (SPGD-940, #941) grew
+ * `GET /api/v1/repositories` three narrowing asks through the shared
+ * `RepositoryNarrowing` concern — `?q=` (case-insensitive substring on
+ * `github_full_name`, with the LIKE wildcards escaped server-side, so a
+ * literal `org/my_repo` does not widen into a pattern match), `?role=owned`
+ * and `?role=shared` (the exact partition of the accessible set into owned and
+ * shared halves), and `?sort=stale` (never-ingested repositories first, then
+ * least-recently-ingested, `github_full_name` breaking ties so the order is
+ * deterministic). The concern's own comment says the endpoint reads them "for
+ * a machine" — and this bridge IS that machine, so they are forwarded here
+ * rather than re-invented.
+ *
+ * What has NOT changed is which side of the boundary the asks sit on. WHICH
+ * boundary answered follows the credential — `Repository.accessible_by` (owned
+ * UNION shared-through-a-membership) for an `sgu_` key, `AgentApiKey#repositories`
+ * (the mint-time granted set) for an `sga_` one — and either way it is the
+ * platform's read-side rule, not a filter this bridge could widen or narrow:
+ * the controller chains every ask onto the relation that boundary already
+ * admitted (`narrow_repositories(authorized_repositories, …)`), so a
+ * repository the credential does not admit never ENTERS the relation and no
+ * argument here widens the answer — it can only narrow, or re-order, what the
+ * credential already admits. Out-of-vocabulary values are the server's to
+ * clamp, not ours: an unknown `role` or `sort` settles to the no-ask, never a
+ * 400, which is also why a value that reaches the wire is passed through
+ * verbatim rather than validated against a second vocabulary here. Under the
+ * agent key the `?role=` ask clamps to the no-ask outright — ownership is a
+ * person fact and the key speaks for nobody, so there is no owned/shared line
+ * to draw (`UserRepositoriesController#requested_role` is where the server
+ * writes that rule, beside `#credential_role`'s `role: "agent"`).
+ *
+ * Blank is no ask, and so is undefined: `optionalString` returns `undefined`
+ * for a blank value and `getJson` omits an `undefined` query entry, so
+ * declining an ask and omitting the argument are the same wire request — the
+ * established spelling in this codebase (`repository-overview.ts` states it
+ * as build-don't-stringify), and the reason the no-ask request below is
+ * byte-identical to the one this tool made before it had arguments at all.
  *
  * == The response is passed through, not re-modelled
  *
@@ -58,50 +99,144 @@ import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js
  * `repository` block, so a client that has read one knows how to read the other.
  * Renaming or flattening anything here would spend that parity on the last hop.
  *
- * `role` is the field this surface adds — `"owner"` or `"member"` — because the
- * list MIXES repositories the person owns with repositories somebody shared
- * with them and no other field separates the two. An agent that will later
- * register keys or change settings needs to know which of these it may expect
- * to administer, so the value is named in the description rather than left to be
- * discovered from the data.
+ * `role` is the field this surface adds, and its value depends on WHICH
+ * credential answered — three values, one per credential kind, and all three
+ * are named rather than left to be discovered from the data, because an agent
+ * that will later register keys or change settings needs to know which of these
+ * entries it may expect to administer. Under the `sgu_` PERSON key it is
+ * `"owner"` or `"member"`: the list MIXES repositories the person owns with
+ * repositories somebody shared with them, and no other field separates the two.
+ * Under the `sga_` AGENT key every entry is `"agent"` — the key is NOBODY, so
+ * the owner/member question does not apply, and a client branching on
+ * owner/member reads false for both, which is the correct reading rather than a
+ * gap (`Api::V1::UserRepositoriesController#credential_role` is where the
+ * server writes that rule down, beside the `?role=` clamp that exists for the
+ * same reason). One value per kind also means the field identifies WHICH
+ * credential served the list — worth knowing when both variables are set and
+ * the agent key wins.
  *
  * The order is `full_name` ascending, which the controller picks as the only
  * column a client can page or diff against without SpecGuard promising an id
- * ordering it has not designed. It is stated here for the same reason the other
- * tool states its orders: a list whose order is a coincidence and a list whose
- * order is a contract look identical in a response body.
+ * ordering it has not designed — and `?sort=stale` re-sequences exactly that
+ * loaded set rather than issuing a different query, so the entries never
+ * change, only their order does. It is stated here for the same reason the
+ * other tool states its orders: a list whose order is a coincidence and a list
+ * whose order is a contract look identical in a response body.
  */
 const listRepositories = {
     name: "list_repositories",
     title: "List repositories",
-    description: "Lists the SpecGuard repositories the person behind this server's user API key may open — " +
-        "the answer to \"what can I ask about\", which no other tool here can give, because every " +
-        "other tool is already scoped to one repository by its key. " +
+    description: "Lists the SpecGuard repositories this server's key may open — the answer to \"what can I " +
+        "ask about\", which no other tool here can give, because every other tool is already scoped " +
+        "to one repository by its key. " +
         "Each entry carries `id`, `full_name` (`org/repo`, and the handle every other surface names " +
         "a repository by), `name`, `registered_at` and `role`. " +
-        "`role` is `owner` or `member`: the list mixes repositories this person owns with " +
-        "repositories somebody shared with them, and nothing else distinguishes the two — read it " +
+        "`role` has one value per credential kind. Under a PERSON key (`sgu_…`) it is `owner` or " +
+        "`member`: the list mixes repositories this person owns with repositories somebody shared " +
+        "with them, and nothing else distinguishes the two. Under an AGENT key (`sga_…`) every " +
+        "entry is `agent` — the value that says the ownership question does not apply because the " +
+        "key speaks for nobody; branching on owner/member correctly reads false for both. Read it " +
         "before assuming a repository is yours to administer. " +
-        "Ordered by `full_name` ascending, which is stable across calls. " +
-        "The set is exactly what this person may see — a repository they neither own nor were given " +
-        "access to is absent rather than filtered, so an empty list means no access, never an error. " +
-        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), which is a DIFFERENT credential from the " +
-        "sgk_… repository key get_repository_overview reads; SpecGuard refuses each in the other's " +
-        "place.",
+        "Three optional asks narrow WITHIN that set — none of them can widen it — all optional, " +
+        "composable on one call: `q` (case-insensitive substring on `full_name`), " +
+        "`role: \"owned\"` or `\"shared\"` (one half of the owned/shared mix — note the ask is " +
+        "spelled `owned`, not the response field's `owner`; under the AGENT key this ask settles " +
+        "to the no-ask, because ownership is a person fact and the key speaks for nobody), and " +
+        "`sort: \"stale\"` (repositories " +
+        "CI has never ingested a run for first, then least-recently-ingested, `full_name` " +
+        "breaking ties). Omit them all and the request is the plain full list. " +
+        "Ordered by `full_name` ascending unless `sort` asks otherwise, and stable across calls " +
+        "either way. " +
+        "The set is exactly what the key behind it may see — a repository outside the credential's " +
+        "own boundary is absent rather than filtered, so an empty list means no access, never an " +
+        "error. " +
+        "It authenticates with EITHER of this server's two list-scoped credentials, whichever is " +
+        "set: SPECGUARD_AGENT_API_KEY (an sga_… key — the answer is the repository set granted onto " +
+        "that key at mint time, the same set every other agent-keyed tool here answers inside) and, " +
+        "when that is not set, SPECGUARD_USER_API_KEY (an sgu_… key — the answer is what that person " +
+        "may open). With both set the agent key wins, so discovery stays inside the set the other " +
+        "tools can actually reach. " +
+        "Either way it is a DIFFERENT credential from the sgk_… repository key " +
+        "get_repository_overview reads; SpecGuard refuses each in the other's place.",
     inputSchema: {
         type: "object",
-        // No properties, deliberately — see this file's header. Still CLOSED rather
-        // than merely empty: `additionalProperties: false` is advertised in
-        // `tools/list`, so a client that honours the schema REJECTS an invented
+        properties: {
+            q: {
+                type: "string",
+                description: "Keep only the repositories whose `github_full_name` (`org/repo`) CONTAINS this " +
+                    "substring, case-insensitively — the same ask the deployment's web grid reads. " +
+                    "A plain substring, not a pattern: the server matches with `ILIKE '%…%'` and escapes " +
+                    "the LIKE wildcards (`%`, `_`, `\\`) first, so `org/my_repo` matches itself rather " +
+                    "than widening into `my-repo` and `myxrepo`. " +
+                    "It narrows the SAME set the plain call serves — a repository the credential does not " +
+                    "admit never enters the response, so no `q` can make one appear — and an ask that " +
+                    "matches nothing is an empty list with a 200, the same answer as having no access, " +
+                    "not an error. " +
+                    "Blank (or null) is no ask: the request is then byte-identical to omitting the " +
+                    "argument.",
+            },
+            role: {
+                type: "string",
+                enum: ["owned", "shared"],
+                description: "Keep only ONE half of the list's mix: `owned` keeps the repositories this person " +
+                    "owns, `shared` keeps the ones somebody shared with them. The two partition the " +
+                    "accessible set exactly — a repository owned AND shared cannot exist by construction, " +
+                    "so nothing is lost by asking for one half — and both chain onto the credential " +
+                    "boundary, so neither half can be wider than the plain call's answer. " +
+                    "THE ASK VALUES ARE SPELLED DIFFERENTLY FROM THE RESPONSE FIELD: an entry's `role` is " +
+                    "`\"owner\"`/`\"member\"` under the PERSON key and `\"agent\"` under the AGENT one (the " +
+                    "key speaks for nobody), but the ask is `owned`/`shared` — send `role: " +
+                    "\"owner\"` and you are not asking for anything. A client that honours this schema " +
+                    "cannot send it (the enum refuses it before the call); a client that bypasses the " +
+                    "schema gets the server's clamp, where any value outside `owned`/`shared` settles to " +
+                    "the no-ask and the full list is served — never an error — and under the AGENT key " +
+                    "the ask settles to the no-ask for EVERY value, because ownership is a person fact " +
+                    "and the key speaks for nobody. " +
+                    "Blank (or null) is no ask: byte-identical to omitting the argument.",
+            },
+            sort: {
+                type: "string",
+                enum: ["stale"],
+                description: "Re-order the list stalest-first. The default order is `full_name` ascending, which " +
+                    "is stable across calls but says nothing about what needs attention; `stale` puts " +
+                    "the repositories CI has NEVER ingested a run for FIRST (never-ingested is the " +
+                    "stalest state on this list, not a zero), then least-recently-ingested, newest last, " +
+                    "with `github_full_name` breaking ties so two calls with the same data agree element " +
+                    "for element. " +
+                    "It re-sequences the loaded set rather than issuing a different query: the same " +
+                    "entries, a different order. `stale` is the only ordering the endpoint names — there " +
+                    "is deliberately no word for the default, because omitting the argument already " +
+                    "means it. " +
+                    "Any other value a schema-bypassing client sends settles to the server's no-ask clamp " +
+                    "(default order, no error); blank (or null) is no ask, byte-identical to omitting the " +
+                    "argument.",
+            },
+        },
+        // Still CLOSED rather than open: `additionalProperties: false` is advertised
+        // in `tools/list`, so a client that honours the schema REJECTS an invented
         // argument before the call is made. Nothing on this side refuses it —
-        // `server.ts` forwards `arguments` unvalidated and `run` ignores them — so
-        // an open schema would have the argument silently dropped and the call
-        // answered as if it had been honoured.
+        // `server.ts` forwards `arguments` unvalidated — so an open schema would
+        // have the argument silently dropped and the call answered as if it had
+        // been honoured. The enum vocabularies above are the server's own accepted
+        // values (`RepositoryNarrowing`'s ROLES and SORTS), not a second list this
+        // bridge keeps in step by hand.
         additionalProperties: false,
     },
-    async run(_args, context) {
-        const api = requireUserApiConfig(context.config);
-        const listing = await getJsonObject(api, "/api/v1/repositories", {}, context.fetch);
+    async run(args, context) {
+        const q = optionalString(args["q"], "q");
+        const role = optionalString(args["role"], "role");
+        const sort = optionalString(args["sort"], "sort");
+        // EITHER credential the endpoint serves — agent key preferred, user key as
+        // the fallback, both named in the refusal when neither is set. The
+        // precedence and its scope argument live on the helper in `config.ts`.
+        const api = requireUserOrAgentApiConfig(context.config);
+        // Built, not stringified — the established rule for a query object
+        // (`repository-overview.ts`): `getJson` omits an `undefined` entry and sets
+        // everything else verbatim, so an ask declined (blank), omitted, or never
+        // defined all compose to the ONE request the caller meant, and with no asks
+        // at all the object is `{}` — the byte-identical request this tool made
+        // before it had arguments.
+        const listing = await getJsonObject(api, "/api/v1/repositories", { q, role, sort }, context.fetch);
         return {
             text: JSON.stringify(listing, null, 2),
             structured: listing,

package/dist/src/tools/list-repositories.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-repositories.js","sourceRoot":"","sources":["../../../src/tools/list-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,gBAAgB,GAAmB;IACvC,IAAI,EAAE,mBAAmB;IACzB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,2FAA2F;QAC3F,2FAA2F;QAC3F,6DAA6D;QAC7D,6FAA6F;QAC7F,wDAAwD;QACxD,mFAAmF;QACnF,2FAA2F;QAC3F,uDAAuD;QACvD,kEAAkE;QAClE,6FAA6F;QAC7F,8FAA8F;QAC9F,wFAAwF;QACxF,4FAA4F;QAC5F,QAAQ;IACV,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,oEAAoE;QACpE,wEAAwE;QACxE,sEAAsE;QACtE,2EAA2E;QAC3E,uEAAuE;QACvE,uCAAuC;QACvC,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,sBAAsB,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAEpF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"list-repositories.js","sourceRoot":"","sources":["../../../src/tools/list-repositories.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/list-repository-members.js

@@ -46,8 +46,9 @@ const listRepositoryMembers = {
         "`members.manage` is refused 403 in SpecGuard's own words. " +
         "Takes `repository_id` — the numeric id `list_repositories` reports, not the `org/repo` " +
         "handle. " +
-        "Needs SPECGUARD_USER_API_KEY (an sgu_… key), the same credential `list_repositories` " +
-        "reads and a DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
+        "Needs SPECGUARD_USER_API_KEY (an sgu_… key) — a PERSON key, which `list_repositories` " +
+        "also accepts but does not require — and a DIFFERENT one from the sgk_… repository key " +
+        "`get_repository_overview` uses.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/src/tools/list-repository-members.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-repository-members.js","sourceRoot":"","sources":["../../../src/tools/list-repository-members.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,qBAAqB,GAAmB;IAC5C,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,yBAAyB;IAChC,WAAW,EACT,0FAA0F;QAC1F,6FAA6F;QAC7F,iGAAiG;QACjG,2FAA2F;QAC3F,2FAA2F;QAC3F,4DAA4D;QAC5D,wFAAwF;QACxF,4FAA4F;QAC5F,4DAA4D;QAC5D,yFAAyF;QACzF,UAAU;QACV,uFAAuF;QACvF,yFAAyF;IAC3F,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6EAA6E;oBAC7E,qEAAqE;aACxE;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,CAAC;QAC3B,qEAAqE;QACrE,6EAA6E;QAC7E,uBAAuB;QACvB,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,CAAC;QAE3E,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,UAAU,EAClE,EAAE,EACF,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,2EAA2E;QAC3E,0EAA0E;QAC1E,wEAAwE;QACxE,oDAAoD;QACpD,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"list-repository-members.js","sourceRoot":"","sources":["../../../src/tools/list-repository-members.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,qBAAqB,GAAmB;IAC5C,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,yBAAyB;IAChC,WAAW,EACT,0FAA0F;QAC1F,6FAA6F;QAC7F,iGAAiG;QACjG,2FAA2F;QAC3F,2FAA2F;QAC3F,4DAA4D;QAC5D,wFAAwF;QACxF,4FAA4F;QAC5F,4DAA4D;QAC5D,yFAAyF;QACzF,UAAU;QACV,wFAAwF;QACxF,wFAAwF;QACxF,iCAAiC;IACnC,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,aAAa,EAAE;gBACb,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,6EAA6E;oBAC7E,qEAAqE;aACxE;SACF;QACD,QAAQ,EAAE,CAAC,eAAe,CAAC;QAC3B,qEAAqE;QACrE,6EAA6E;QAC7E,uBAAuB;QACvB,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC,CAAC;QAE3E,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,GAAG,EACH,wBAAwB,kBAAkB,CAAC,YAAY,CAAC,UAAU,EAClE,EAAE,EACF,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,2EAA2E;QAC3E,0EAA0E;QAC1E,wEAAwE;QACxE,oDAAoD;QACpD,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,qBAAqB,CAAC"}

package/dist/src/tools/near-duplicate-clusters.d.ts

@@ -26,15 +26,27 @@ import type { ToolDefinition } from "./types.js";
  * The server reads only whether the parameter is PRESENT
  * (`RequestedNearDuplicatesParam`): `?near_duplicates=false` opens the block
  * exactly as `=true` does, and a non-String shape is read as no ask at all.
- * There is no "off" value for a client to send, so this tool has no arguments
- * — nothing about the census is choosable from here, which is also why the
- * schema is CLOSED rather than merely empty: `server.ts` forwards `arguments`
- * unvalidated, and an open schema would let an invented argument ride through
- * and be silently dropped (see `registrable-repositories.ts` for the same
- * call). `near_duplicates: "true"` is built rather than stringified for the
- * same reason `repository-overview.ts` builds its `unannotated_examples` key:
+ * There is no "off" value for a client to send, so nothing about the CENSUS is
+ * choosable from here — the clusters are the repository's, computed over every
+ * run, and one call returns them all. What IS choosable, since SPGD-953, is
+ * WHICH REPOSITORY is censused: an optional `repository` argument (a numeric id
+ * from `list_repositories`) moves the call to the plural endpoint
+ * `GET /api/v1/repositories/:id` under the AGENT key, same body (minus the
+ * `api_key` block, which is ABSENT on that surface rather than nulled — see
+ * `repository-overview.ts` for why the omission is the server's, deliberately),
+ * same ask, same cost gate. Without it the request is byte-for-byte the singular,
+ * `sgk_`-bound one this tool has always made — and the cost argument above is
+ * exactly why the argument is OPTIONAL rather than required: an agent that has
+ * only ever had one reachable repository should not be asked to learn a second
+ * credential to keep reading it.
+ *
+ * `near_duplicates: "true"` is built rather than stringified for the same
+ * reason `repository-overview.ts` builds its `unannotated_examples` key:
  * `getJson` omits only `undefined`, so a conditional send is the only honest
- * way to spell "always" here.
+ * way to spell "always" here. The schema stays CLOSED around the one argument:
+ * `server.ts` forwards `arguments` unvalidated, and an open schema would let an
+ * invented argument ride through and be silently dropped (see
+ * `registrable-repositories.ts` for the same call).
  *
  * == The response is passed through, not re-modelled
  *

package/dist/src/tools/near-duplicate-clusters.js

@@ -1,5 +1,6 @@
-import { requireApiConfig } from "../config.js";
+import { requireAgentApiConfig, requireApiConfig } from "../config.js";
 import { getJsonObject } from "../support/specguard-api.js";
+import { optionalString } from "./args.js";
 /**
  * `GET /api/v1/repository?near_duplicates=` as a tool — shipped in the
  * platform by SPGD-703 (`specguard` `c43dc19`, 2026-08-28), which added the
@@ -27,15 +28,27 @@ import { getJsonObject } from "../support/specguard-api.js";
  * The server reads only whether the parameter is PRESENT
  * (`RequestedNearDuplicatesParam`): `?near_duplicates=false` opens the block
  * exactly as `=true` does, and a non-String shape is read as no ask at all.
- * There is no "off" value for a client to send, so this tool has no arguments
- * — nothing about the census is choosable from here, which is also why the
- * schema is CLOSED rather than merely empty: `server.ts` forwards `arguments`
- * unvalidated, and an open schema would let an invented argument ride through
- * and be silently dropped (see `registrable-repositories.ts` for the same
- * call). `near_duplicates: "true"` is built rather than stringified for the
- * same reason `repository-overview.ts` builds its `unannotated_examples` key:
+ * There is no "off" value for a client to send, so nothing about the CENSUS is
+ * choosable from here — the clusters are the repository's, computed over every
+ * run, and one call returns them all. What IS choosable, since SPGD-953, is
+ * WHICH REPOSITORY is censused: an optional `repository` argument (a numeric id
+ * from `list_repositories`) moves the call to the plural endpoint
+ * `GET /api/v1/repositories/:id` under the AGENT key, same body (minus the
+ * `api_key` block, which is ABSENT on that surface rather than nulled — see
+ * `repository-overview.ts` for why the omission is the server's, deliberately),
+ * same ask, same cost gate. Without it the request is byte-for-byte the singular,
+ * `sgk_`-bound one this tool has always made — and the cost argument above is
+ * exactly why the argument is OPTIONAL rather than required: an agent that has
+ * only ever had one reachable repository should not be asked to learn a second
+ * credential to keep reading it.
+ *
+ * `near_duplicates: "true"` is built rather than stringified for the same
+ * reason `repository-overview.ts` builds its `unannotated_examples` key:
  * `getJson` omits only `undefined`, so a conditional send is the only honest
- * way to spell "always" here.
+ * way to spell "always" here. The schema stays CLOSED around the one argument:
+ * `server.ts` forwards `arguments` unvalidated, and an open schema would let an
+ * invented argument ride through and be silently dropped (see
+ * `registrable-repositories.ts` for the same call).
  *
  * == The response is passed through, not re-modelled
  *
@@ -65,9 +78,12 @@ const nearDuplicateClusters = {
         "THIS IS THE EXPENSIVE READ ON THIS BRIDGE: the census is linear but measured in seconds — seven " +
         "queries at every size, tens of seconds extrapolated at the 20,000-test design point — which is " +
         "exactly why the server serves it only to a client that asks (`?near_duplicates=`) and answers " +
-        "`near_duplicates: null` on the plain overview. Calling this tool IS the ask; it takes no " +
-        "arguments because nothing about the census is choosable — the clusters are the repository's, " +
-        "computed over every run, and one call returns them all. " +
+        "`near_duplicates: null` on the plain overview. Calling this tool IS the ask; nothing about the " +
+        "census is choosable — the clusters are the repository's, computed over every run, and one call " +
+        "returns them all. WHICH repository is censused is the one choice there is: pass `repository` " +
+        "(a numeric id from `list_repositories`) to census that named repository under the agent key, " +
+        "or omit it to census the repository the configured sgk_… key resolves to, exactly as before " +
+        "the argument existed. " +
         "READ THE DISCLOSURE KEYS BEFORE THE COUNT: `similarity_floor` and `similarity_basis` sit FIRST " +
         "in the block and qualify every cluster below them — a cluster count without what 'similar' " +
         "meant is a figure you cannot act on. `truncated: true` means the cluster list was cut at the " +
@@ -86,21 +102,52 @@ const nearDuplicateClusters = {
         "success state (nothing reads alike), and the three silences — nothing ingested " +
         "(`recorded_count: 0`), nothing embedded (`identity_count: 0`), nothing alike — are kept " +
         "distinguishable by those counts rather than collapsed into one empty list. " +
-        "Same credential and endpoint as `get_repository_overview` (an `sgk_` repository key on " +
-        "`GET /api/v1/repository`); the response is that endpoint's full body with the `near_duplicates` " +
-        "block OPENED, passed through unmodified.",
+        "Same endpoints and credentials as `get_repository_overview`: without `repository`, an " +
+        "`sgk_` repository key on `GET /api/v1/repository`; with `repository`, an `sga_` agent key " +
+        "(SPECGUARD_AGENT_API_KEY) on `GET /api/v1/repositories/:id`, whose answer the key's own " +
+        "granted repository set bounds. SpecGuard refuses each credential in the other's place, so " +
+        "a `repository` ask without the agent key set is refused HERE, by name, before any request " +
+        "is made. " +
+        "The response is the endpoint's full body with the `near_duplicates` block OPENED, passed " +
+        "through unmodified — with the one surface difference `get_repository_overview` documents " +
+        "for its own `repository` ask: on that plural path the `api_key` block is ABSENT from the " +
+        "body rather than nulled (it describes the credential that made the request, and an agent " +
+        "key is not a repository key), so an absent `api_key` there is the surface's shape, never " +
+        "a dropped block.",
     inputSchema: {
         type: "object",
-        // No properties, deliberately — see this file's header. Still CLOSED rather
-        // than merely empty, for the reason `registrable-repositories.ts` gives
-        // inline: `server.ts` forwards `arguments` unvalidated and `run` ignores
-        // them, so an open schema would have an invented argument silently dropped
-        // and the call answered as if it had been honoured.
+        properties: {
+            repository: {
+                type: "string",
+                description: "Census THIS repository instead of the one the configured sgk_… key resolves to. The " +
+                    "value is the repository's NUMERIC ID, exactly as served in `list_repositories` " +
+                    "entries' `id` — not the `org/repo` handle. " +
+                    "The credential changes with it, because SpecGuard refuses each key kind in the " +
+                    "other's place: the call authenticates with SPECGUARD_AGENT_API_KEY (an sga_… agent " +
+                    "key) instead of SPECGUARD_API_KEY, and the key's granted repository set is the " +
+                    "boundary the id is resolved inside — a repository outside the set answers 404, " +
+                    "indistinguishable from one that does not exist. The census itself is identical on " +
+                    "either path: same block, same caps, same disclosure keys. " +
+                    "Omit it — or pass a blank — and the call is byte-for-byte the singular one under " +
+                    "SPECGUARD_API_KEY, exactly as before this argument existed.",
+            },
+        },
         additionalProperties: false,
     },
-    async run(_args, context) {
-        const api = requireApiConfig(context.config);
-        const overview = await getJsonObject(api, "/api/v1/repository", {
+    async run(args, context) {
+        const repository = optionalString(args["repository"], "repository");
+        // WHICH ENDPOINT AND WHICH CREDENTIAL is one branch point over the one ask,
+        // for the reason `repository-overview.ts` states at its own call site: the
+        // pair (path, credential) must not be mixable, because either mixed pairing
+        // is a 401 at the deployment by design and both are refused here, legibly,
+        // instead.
+        const api = repository === undefined
+            ? requireApiConfig(context.config)
+            : requireAgentApiConfig(context.config);
+        const path = repository === undefined
+            ? "/api/v1/repository"
+            : `/api/v1/repositories/${encodeURIComponent(repository)}`;
+        const overview = await getJsonObject(api, path, {
             // Always sent, always `"true"` — the server reads only that the key is
             // present (`?near_duplicates=false` opens the block too), and this
             // tool exists to open it. See this file's header.

package/dist/src/tools/near-duplicate-clusters.js.map

@@ -1 +1 @@
-{"version":3,"file":"near-duplicate-clusters.js","sourceRoot":"","sources":["../../../src/tools/near-duplicate-clusters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,qBAAqB,GAAmB;IAC5C,IAAI,EAAE,yBAAyB;IAE/B,KAAK,EAAE,yBAAyB;IAEhC,WAAW,EACT,2FAA2F;QAC3F,gGAAgG;QAChG,gGAAgG;QAChG,gCAAgC;QAChC,kGAAkG;QAClG,iGAAiG;QACjG,gGAAgG;QAChG,2FAA2F;QAC3F,+FAA+F;QAC/F,0DAA0D;QAC1D,iGAAiG;QACjG,6FAA6F;QAC7F,+FAA+F;QAC/F,gGAAgG;QAChG,8DAA8D;QAC9D,iGAAiG;QACjG,8FAA8F;QAC9F,iGAAiG;QACjG,iGAAiG;QACjG,oGAAoG;QACpG,2FAA2F;QAC3F,mGAAmG;QACnG,8FAA8F;QAC9F,2BAA2B;QAC3B,6FAA6F;QAC7F,iFAAiF;QACjF,0FAA0F;QAC1F,6EAA6E;QAC7E,yFAAyF;QACzF,kGAAkG;QAClG,0CAA0C;IAE5C,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,wEAAwE;QACxE,yEAAyE;QACzE,2EAA2E;QAC3E,oDAAoD;QACpD,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAE7C,MAAM,QAAQ,GAAG,MAAM,aAAa,CAClC,GAAG,EACH,oBAAoB,EACpB;YACE,uEAAuE;YACvE,mEAAmE;YACnE,kDAAkD;YAClD,eAAe,EAAE,MAAM;SACxB,EACD,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,UAAU,EAAE,QAAQ;SACrB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"near-duplicate-clusters.js","sourceRoot":"","sources":["../../../src/tools/near-duplicate-clusters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,qBAAqB,GAAmB;IAC5C,IAAI,EAAE,yBAAyB;IAE/B,KAAK,EAAE,yBAAyB;IAEhC,WAAW,EACT,2FAA2F;QAC3F,gGAAgG;QAChG,gGAAgG;QAChG,gCAAgC;QAChC,kGAAkG;QAClG,iGAAiG;QACjG,gGAAgG;QAChG,iGAAiG;QACjG,iGAAiG;QACjG,+FAA+F;QAC/F,+FAA+F;QAC/F,8FAA8F;QAC9F,wBAAwB;QACxB,iGAAiG;QACjG,6FAA6F;QAC7F,+FAA+F;QAC/F,gGAAgG;QAChG,8DAA8D;QAC9D,iGAAiG;QACjG,8FAA8F;QAC9F,iGAAiG;QACjG,iGAAiG;QACjG,oGAAoG;QACpG,2FAA2F;QAC3F,mGAAmG;QACnG,8FAA8F;QAC9F,2BAA2B;QAC3B,6FAA6F;QAC7F,iFAAiF;QACjF,0FAA0F;QAC1F,6EAA6E;QAC7E,wFAAwF;QACxF,4FAA4F;QAC5F,0FAA0F;QAC1F,4FAA4F;QAC5F,4FAA4F;QAC5F,WAAW;QACX,2FAA2F;QAC3F,2FAA2F;QAC3F,2FAA2F;QAC3F,2FAA2F;QAC3F,2FAA2F;QAC3F,kBAAkB;IAEpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,UAAU,EAAE;gBACV,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,sFAAsF;oBACtF,iFAAiF;oBACjF,6CAA6C;oBAC7C,iFAAiF;oBACjF,qFAAqF;oBACrF,iFAAiF;oBACjF,iFAAiF;oBACjF,oFAAoF;oBACpF,4DAA4D;oBAC5D,mFAAmF;oBACnF,6DAA6D;aAChE;SACF;QACD,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO;QACrB,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,CAAC;QACpE,4EAA4E;QAC5E,2EAA2E;QAC3E,4EAA4E;QAC5E,2EAA2E;QAC3E,WAAW;QACX,MAAM,GAAG,GACP,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC;YAClC,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,IAAI,GACR,UAAU,KAAK,SAAS;YACtB,CAAC,CAAC,oBAAoB;YACtB,CAAC,CAAC,wBAAwB,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;QAE/D,MAAM,QAAQ,GAAG,MAAM,aAAa,CAClC,GAAG,EACH,IAAI,EACJ;YACE,uEAAuE;YACvE,mEAAmE;YACnE,kDAAkD;YAClD,eAAe,EAAE,MAAM;SACxB,EACD,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,UAAU,EAAE,QAAQ;SACrB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,qBAAqB,CAAC"}

package/dist/src/tools/registrable-repositories.d.ts

@@ -42,10 +42,15 @@ import type { ToolDefinition } from "./types.js";
  * ago" is a different fact from "you never had one", and the tool description
  * is where an agent learns to branch on it.
  *
- * == No arguments, for the same reason `list_repositories` has none
+ * == No arguments, for the same reason `list_repositories` used to have none
  *
  * The credential is the whole of the scope. The endpoint takes no parameters,
- * and nothing an argument could select reaches this answer.
+ * and nothing an argument could select reaches this answer. (`list_repositories`
+ * argued the same way and argued it the same amount — until its endpoint grew
+ * the SPGD-940 narrowing asks and the tool grew the arguments that forward
+ * them. This endpoint has grown no asks, so the argument-less shape here is
+ * still the honest one, and the sentence above keeps saying so rather than
+ * inheriting a reason that moved.)
  */
 declare const registrableRepositories: ToolDefinition;
 export default registrableRepositories;

package/dist/src/tools/registrable-repositories.js

@@ -42,10 +42,15 @@ import { getJsonObject, requireUserApiConfig } from "../support/specguard-api.js
  * ago" is a different fact from "you never had one", and the tool description
  * is where an agent learns to branch on it.
  *
- * == No arguments, for the same reason `list_repositories` has none
+ * == No arguments, for the same reason `list_repositories` used to have none
  *
  * The credential is the whole of the scope. The endpoint takes no parameters,
- * and nothing an argument could select reaches this answer.
+ * and nothing an argument could select reaches this answer. (`list_repositories`
+ * argued the same way and argued it the same amount — until its endpoint grew
+ * the SPGD-940 narrowing asks and the tool grew the arguments that forward
+ * them. This endpoint has grown no asks, so the argument-less shape here is
+ * still the honest one, and the sentence above keeps saying so rather than
+ * inheriting a reason that moved.)
  */
 const registrableRepositories = {
     name: "registrable_repositories",
@@ -68,8 +73,8 @@ const registrableRepositories = {
         "telling the person what to do. A name appearing in the list is not a promise the write " +
         "will succeed: someone may register it between this read and the POST. Ordered by " +
         "`full_name` ascending, which is stable across calls. Needs SPECGUARD_USER_API_KEY (an " +
-        "sgu_… key), the same credential `list_repositories` and `add_repository` read and a " +
-        "DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
+        "sgu_… key) — a PERSON key, which `list_repositories` also accepts but does not require — " +
+        "and a DIFFERENT one from the sgk_… repository key `get_repository_overview` uses.",
     inputSchema: {
         type: "object",
         // No properties, deliberately — see this file's header. Still CLOSED rather

package/dist/src/tools/registrable-repositories.js.map

@@ -1 +1 @@
-{"version":3,"file":"registrable-repositories.js","sourceRoot":"","sources":["../../../src/tools/registrable-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,uBAAuB,GAAmB;IAC9C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,0BAA0B;IACjC,WAAW,EACT,4FAA4F;QAC5F,2FAA2F;QAC3F,sFAAsF;QACtF,6FAA6F;QAC7F,qFAAqF;QACrF,6FAA6F;QAC7F,yFAAyF;QACzF,mFAAmF;QACnF,8FAA8F;QAC9F,yFAAyF;QACzF,8FAA8F;QAC9F,4FAA4F;QAC5F,6FAA6F;QAC7F,wFAAwF;QACxF,4FAA4F;QAC5F,yFAAyF;QACzF,mFAAmF;QACnF,wFAAwF;QACxF,sFAAsF;QACtF,6EAA6E;IAC/E,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,yEAAyE;QACzE,0EAA0E;QAC1E,0EAA0E;QAC1E,4CAA4C;QAC5C,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,GAAG,EACH,kCAAkC,EAClC,EAAE,EACF,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,uBAAuB,CAAC"}
+{"version":3,"file":"registrable-repositories.js","sourceRoot":"","sources":["../../../src/tools/registrable-repositories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,uBAAuB,GAAmB;IAC9C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,0BAA0B;IACjC,WAAW,EACT,4FAA4F;QAC5F,2FAA2F;QAC3F,sFAAsF;QACtF,6FAA6F;QAC7F,qFAAqF;QACrF,6FAA6F;QAC7F,yFAAyF;QACzF,mFAAmF;QACnF,8FAA8F;QAC9F,yFAAyF;QACzF,8FAA8F;QAC9F,4FAA4F;QAC5F,6FAA6F;QAC7F,wFAAwF;QACxF,4FAA4F;QAC5F,yFAAyF;QACzF,mFAAmF;QACnF,wFAAwF;QACxF,2FAA2F;QAC3F,mFAAmF;IACrF,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,4EAA4E;QAC5E,yEAAyE;QACzE,0EAA0E;QAC1E,0EAA0E;QAC1E,4CAA4C;QAC5C,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO;QACtB,MAAM,GAAG,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,GAAG,EACH,kCAAkC,EAClC,EAAE,EACF,OAAO,CAAC,KAAK,CACd,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACtC,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,eAAe,uBAAuB,CAAC"}

package/dist/src/tools/repository-overview.d.ts

@@ -18,6 +18,41 @@ import type { ToolDefinition } from "./types.js";
  * has grown — so the tool is described in those terms rather than as "get
  * repository", which is not a question anybody asks.
  *
+ * == `repository` chooses WHICH REPOSITORY, and the credential changes with it
+ *
+ * Everything above answers about the one repository the configured `sgk_` key
+ * RESOLVES TO — with five repositories in play, four of them are invisible to
+ * every agent holding a single-repository key. `repository` is the ask that
+ * fixes that: name one by its numeric id (the id `list_repositories` reports,
+ * not the `org/repo` handle — the plural endpoint looks the id up inside the
+ * calling credential's own read boundary) and the tool calls the PLURAL
+ * endpoint, `GET /api/v1/repositories/:id`, which serves the same
+ * `RepositoryOverview` body with every parameter below honoured exactly as the
+ * singular one serves it — with ONE DELIBERATE OMISSION this branch owns:
+ * `api_key` is ABSENT from the plural body, not null. That block describes the
+ * credential that made the REQUEST, and the singular controller is the only
+ * caller that has one to describe (`RepositoriesController#show` passes
+ * `api_key_block: serialized_api_key`; `UserRepositoriesController#show`
+ * passes none and says why at length: a block of nulls would be a sentence
+ * about a credential that does not exist, because this request was made with
+ * an agent or person key, and the repository's own `sgk_` keys are not the
+ * caller's to describe). So the `api_key.last_used_at` paragraph below is
+ * about the SINGULAR response; under `repository` the key is simply not there,
+ * and its absence is the plural surface's shape — never this bridge dropping
+ * a key. The two health blocks come from `RepositoryOverview` itself and DO
+ * travel. The ladder moves; the subject moves; `api_key` does not.
+ *
+ * THE CREDENTIAL MOVES WITH IT, because the endpoints refuse each other's
+ * tokens before any table is read: the singular path still authenticates with
+ * `SPECGUARD_API_KEY` (`sgk_`, one repository), the plural path with
+ * `SPECGUARD_AGENT_API_KEY` (`sga_`, the agent credential minted for exactly
+ * this — one key, many repositories, each read bounded by the key's own
+ * granted set server-side). Omitting `repository` is byte-for-byte today's
+ * request, and an operator who never sets the agent variable never sees this
+ * half of the tool exist — the blank-is-no-ask rule every argument here follows
+ * covers `repository` too, so a blank value falls back to the singular path
+ * rather than sending a guaranteed-404 id.
+ *
  * == The response is passed through, not re-modelled
  *
  * Every figure in that body is annotated in the controller with the reason for
@@ -359,7 +394,12 @@ import type { ToolDefinition } from "./types.js";
  * timestamp beside its stalest run, and the controller answers that with
  * `acceptance_reported_by` / `rotation_reported_by` naming the keys that answer
  * what it cannot. Naming the correction and not the claim would have been half a
- * sentence. And the truncation contract, which is NOT the uniform family it looks like from the
+ * sentence. (The claim itself is served by the SINGULAR body only — the plural
+ * one under `repository` omits the whole `api_key` block, the deliberate
+ * omission documented at the branch above — so the correction paragraph in the
+ * description says which surface the instruction applies to rather than sending
+ * a plural-path reader hunting for a key that is not there.) And the truncation
+ * contract, which is NOT the uniform family it looks like from the
  * key names: only eight lists have a `*_window` sibling at all, MOST lists under `latest_run`
  * carry an inline `limit` beside `rows` instead, four of those windows serve no bound of their
  * own, `rejections_window` serves a bound and no order, and the lists this census found carrying