From 24598863e3ac92d3551b97d9a233f44e4e1b9bb3 Mon Sep 17 00:00:00 2001 From: "clagentic-builder[bot]" Date: Thu, 30 Jul 2026 09:52:45 -0400 Subject: [PATCH 1/2] docs(readme): name loadout as reference consumer of the mint path (lr-de6c5c) Gatekeeper README references loadout zero times while loadout's README names gatekeeper three times with the seam framing already in place. Add a 'Composes with' section mirroring loadout's own vocabulary: loadout is the reference consumer via its TokenProvider seam, the integration is optional in both directions, and neither project imports the other. Extend docs/ROLES.md's returned-identity section with a one-line reference-consumer pointer rather than restating the mechanism. No product code changes. --- README.md | 26 ++++++++++++++++++++++++++ docs/ROLES.md | 7 +++++++ 2 files changed, 33 insertions(+) diff --git a/README.md b/README.md index a6b06d2..c5c414b 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,32 @@ The App private keys never touch the agent. Gatekeeper reads them from a pluggab - It is **not** coupled to any specific set of agents. Agent→role mapping lives in the consumer, not here. - It does **not** store long-lived secrets. The broker does. +## Composes with + +Gatekeeper serves **any** consumer that can call its mint path — nothing here +imports or assumes a particular caller. [clagentic: loadout](https://github.com/clagentic/clagentic-loadout) +is the reference **consumer**: its `TokenProvider` seam treats Gatekeeper as +one interchangeable minting provider among several (a static token, a +bring-your-own minting command, or no provider at all all work equally well +there). Neither project imports the other. + +Concretely, the seam works like this: Gatekeeper mints a scoped, short-lived +GitHub App installation token for a role (see "Usage" below); a consumer +calls `gatekeeper mint --role ` and uses the returned token for the +git/API operations that role permits. `--json` mode additionally returns the +broker-verified App slug alongside the token (see "Structured output" below +and [`docs/ROLES.md`](docs/ROLES.md#returned-identity-the-verified-app-slug-travels-with-the-token)) +so a consumer that needs to know which App/bot identity a role maps to can +adopt that value instead of separately declaring it. + +This is optional in both directions. A Gatekeeper user who never touches +loadout loses nothing — Gatekeeper's entire contract is the CLI/JSON output +documented in this README, usable by any caller that can shell out or read +JSON. A loadout user who never touches Gatekeeper loses nothing either — the +Forgejo path works fully standalone with a static token, and GitHub's +App-token path accepts any `TokenProvider` implementation, not only +Gatekeeper's. + ## Attestation substrate for agent-to-agent (A2A) callers Gatekeeper's attestation layer (`internal/attestation`) resolves *who is diff --git a/docs/ROLES.md b/docs/ROLES.md index f950357..a4df4f1 100644 --- a/docs/ROLES.md +++ b/docs/ROLES.md @@ -161,6 +161,13 @@ as before this field existed. A Go caller reading only `Token.Value` is equally unaffected. `--json` and `AppSlug` are additive — nothing about existing behavior changes for a consumer that does not opt in. +**Reference consumer:** [clagentic: loadout](https://github.com/clagentic/clagentic-loadout) +is the reference consumer of this mechanism via its `TokenProvider` seam — +Gatekeeper is one interchangeable provider among several it supports, never +a required one. See the root [README's "Composes with"](../README.md#composes-with) +section for the optionality statement in both directions; this document +states the mechanism only, and that statement is not repeated here. + **Not built here:** a numeric App/bot user id alongside the slug (the value that would unlock a GitHub commit-author bot-badge binding, `+[bot]@users.noreply.github.com`) is intentionally out of scope From be6fbceddfc5debb0c176aa7380191645ba0233f Mon Sep 17 00:00:00 2001 From: "clagentic-builder[bot]" Date: Thu, 30 Jul 2026 09:57:18 -0400 Subject: [PATCH 2/2] fix(readme): correct doubled word in composes-with section (lr-de6c5c) PEACHES review on PR #28 flagged a doubled 'all' in the 'or no provider at all all work equally well' sentence. Fixed to 'or no provider at all each work equally well', which agrees with the distributive sense over the three-item list (a static token, a bring-your-own minting command, or no provider at all each work equally well as a TokenProvider). --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c5c414b..b0d8e9a 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Gatekeeper serves **any** consumer that can call its mint path — nothing here imports or assumes a particular caller. [clagentic: loadout](https://github.com/clagentic/clagentic-loadout) is the reference **consumer**: its `TokenProvider` seam treats Gatekeeper as one interchangeable minting provider among several (a static token, a -bring-your-own minting command, or no provider at all all work equally well +bring-your-own minting command, or no provider at all each work equally well there). Neither project imports the other. Concretely, the seam works like this: Gatekeeper mints a scoped, short-lived