docs(mint): add the App permission rollout runbook and the contributor rule

docs/.vitepress/config.ts

@@ -327,6 +327,10 @@ export default defineConfig({
               link: "/guides/infrastructure/infrastructure-reference",
             },
             { text: "Mint Administration", link: "/guides/infrastructure/mint-administration" },
+            {
+              text: "App Permission Rollout",
+              link: "/guides/infrastructure/app-permission-rollout",
+            },
             { text: "Standalone Mint", link: "/guides/infrastructure/standalone-mint" },
             { text: "Private Repositories", link: "/guides/infrastructure/private-repositories" },
             { text: "Tracing Reference", link: "/guides/infrastructure/distributed-tracing" },

docs/contributing/mintcore.md

@@ -252,6 +252,56 @@ boundary.
 Each load site constructs the appropriate accessor and passes it to
 `NewHandler`. Tests can pass any `PEMAccessor` implementation.
 
+## Adding a permission to a role
+
+A role's GitHub App permissions are declared in three places that must change
+together in one PR:
+
+| Declaration | File | Note |
+|-------------|------|------|
+| Mint role map | `canonicalRolePermissions` in `internal/mintcore/github.go` | What the mint requests when minting a token |
+| GCF embed copy | `internal/dispatch/gcf/mintsrc/mintcore/github.go.embed` | Byte-identical copy; `hack/lint-mint-embed-sync` enforces it |
+| App manifest | `AgentAppConfig` in `internal/forge/github/types.go` | What `fullsend github setup` asks GitHub to create the App with |
+
+The parity tests in `internal/forge/github/types_test.go`
+(`TestAgentAppConfig_CoderMatchesMintcorePermissions` and its siblings — today
+`e2e`, `scribe`, `coder` and `fix` have one) fail if the manifest and the mint
+role map disagree, so the edits land together or CI is red. If the role you are
+changing has no parity test yet, add one in the same PR.
+
+### The backward-compatibility rule
+
+A permission that existing installations have not granted **must** be added to
+`optionalRolePermissions` in the same PR. GitHub rejects the entire
+installation-token request with `422` when any requested permission is
+ungranted — there is no partial downscope — so without the optional entry every
+mint for that role fails on the day the mint deploys, for every installation
+that has not accepted the App update yet.
+
+`effectiveInstallationPermissions` applies the distinction just before the token
+POST: it compares the requested map with the installation's granted map, drops
+ungranted permissions listed in `optionalRolePermissions` (logging
+`installation permissions not granted: … dropped=…`), and returns
+`ErrRequiredPermissionsMissing` for any other ungranted permission, which the
+handler surfaces as `422`. When the installation lookup carries no `permissions`
+map at all (or an empty one), the full requested set is sent and GitHub validates it.
+
+The optional entry is **temporary**. Once the mint logs stop showing drops for
+the permission, remove it in a follow-up PR; the permission then behaves like
+every other one in the role's map. The entry stays keyed by role — today
+`optionalRolePermissions` has entries for `coder` and `fix`, both for
+`packages`.
+
+### Commit conventions
+
+Adding a permission is a `BREAKING CHANGE` for users: App owners must update the
+App registration before installations can grant it. The commit subject and PR
+title carry the `!` suffix (see `COMMITS.md` at the repository root).
+
+The operator side of the change — updating the App registration, deploying the
+mint, chasing installation owners to accept — is
+[Rolling out a GitHub App permission](../guides/infrastructure/app-permission-rollout.md).
+
 ## Interfaces vs accessors
 
 Mintcore uses two patterns for dependency injection:

docs/guides/README.md

@@ -24,6 +24,7 @@ Guides for organization owners and repository administrators who manage fullsend
 Advanced guides for platform operators who deploy and manage the GCP-side infrastructure (token mint, WIF, secrets).
 
 - [Mint service administration](infrastructure/mint-administration.md) — Deploying and managing the token mint (GCP or Cloudflare)
+- [Rolling out a GitHub App permission](infrastructure/app-permission-rollout.md) — Adding a permission to a mint role without breaking installations that have not accepted it yet
 - [Standalone mint](infrastructure/standalone-mint.md) — Running the token mint as a standalone HTTP server without GCP
 - [Infrastructure reference](infrastructure/infrastructure-reference.md) — Token mint, WIF, and secrets deployment details
 - [Enabling fullsend on private repositories](infrastructure/private-repositories.md) — Additional guardrails and configuration for private repos

docs/guides/getting-started/operations.md

@@ -26,6 +26,7 @@ fullsend github set "$OWNER/$REPO" FULLSEND_GCP_REGION global
 | `FULLSEND_GCP_PROJECT_ID` | Repo secret | GCP project ID where Agent Platform is enabled | `my-gcp-project` |
 | `FULLSEND_GCP_WIF_PROVIDER` | Repo secret | Full WIF provider resource name for OIDC authentication | `projects/123456789/locations/global/...` |
 
+
 ### GitLab
 
 For GitLab repos, re-run `repos install` with updated values to converge configuration:
@@ -41,6 +42,12 @@ fullsend repos install -f repos.yaml "$OWNER/$REPO" \
 | `FULLSEND_GCP_PROJECT_ID` | CI/CD secret | GCP project ID for inference | `my-gcp-project` |
 | `FULLSEND_GCP_WIF_PROVIDER` | CI/CD secret | WIF provider resource name for inference | `projects/123456789/locations/global/...` |
 
+## Accepting a GitHub App permission update
+
+GitHub emails organization owners when a fullsend App requests updated permissions — for example when the coder App starts asking for `packages:read`. Go to your org → **Settings** → **Third-party Access** → **GitHub Apps** (`https://github.com/organizations/<org>/settings/installations`), click **Configure** on the App, and use the **Review request** banner to accept. Only org **owners** see the banner; members see nothing.
+
+Agents keep working while the request is pending: during a rollout the mint mints tokens without the pending permission and logs the gap, so nothing breaks before you accept — accepting is what unlocks the capability the permission covers. See [the installation-owner step](../infrastructure/app-permission-rollout.md#installation-owner-accept-the-update) of the rollout runbook.
+
 ## Syncing workflow templates
 
 After upgrading the fullsend CLI, re-run `github setup` to update the workflow file for a single repo: