docs: document required IAM roles for standalone mint and inference commands

[waynesun09]

Summary

• Add required GCP IAM roles and API names to CLI --help text for all standalone inference and mint commands (provision, deprovision, status, deploy, enroll, unenroll)
• Add a per-command IAM role breakdown table to installation.md so users of the split-responsibility workflow know exactly which roles to request
• Restructure docs/guides/admin/ into getting-started/ (end-user onboarding) and infrastructure/ (platform operator guides)
• Add mint-administration.md — a dedicated guide for deploying and managing the token mint Cloud Function
• Scope github-setup.md to its target audience (GitHub maintainers), removing GCP admin details that belong in other guides
• Add 3 missing user guides to docs/guides/README.md
• Update stale guides/admin/ references across web/docs test fixtures

Motivation

A user ran fullsend inference provision on their GCP project and hit a 403 for iam.workloadIdentityPools.create. The required IAM roles were only documented for fullsend admin install — users running standalone commands had no way to know which roles or APIs to request. The guide restructuring separates content by audience so each persona finds only what they need.

Test plan

• go build ./cmd/fullsend/ passes
• go test ./internal/cli/ passes
• go vet ./... passes
• make lint passes (including markdown link validation)
• fullsend inference provision --help / inference status --help show required roles
• fullsend mint deploy --help / mint status --help show required roles
• CI: build, test, web, e2e, commit-lint, DCO all green

[github-actions]

Site preview

Preview: https://07bd9f62-site.fullsend-ai.workers.dev

Commit: eab15171233cde70cd26be8fa840ec9282fcb533

[fullsend-ai-review]

Review

Findings

No findings.

The PR adds IAM role and API documentation to CLI --help text for all standalone inference and mint commands, restructures docs/guides/admin/ into getting-started/ and infrastructure/ directories, and adds a dedicated mint-administration.md guide. All IAM roles are internally consistent across CLI help text, installation.md, mint-administration.md, and cli-internals.md. Cross-references between docs are updated correctly — all renamed files have their inbound links updated, and the 3 newly-linked user guides exist. Web/docs test fixtures are updated to match the new directory structure. The Go changes are help-text-only with no logic changes. Historical design documents under docs/superpowers/ retain the original admin/ path examples, which is appropriate since those are timestamped design records.

Previous run

Review

Findings

Low

• [style] web/docs/src/lib/DocTreeNav.svelte:15, web/docs/src/lib/manifestDirs.ts:3 — JSDoc comments still reference guides/admin as example paths. These are cosmetic but inconsistent with the rename to getting-started/ and infrastructure/.
  Remediation: Update the example paths in the JSDoc comments to use guides/getting-started.

Previous run (2)

Review

Findings

Medium

• [correctness] web/docs/src/lib/hashRoute.test.ts:19 — Test expectation not updated after input change. The test input was changed from #/guides/admin/ to #/guides/getting-started/, but the expected dirPath on line 19 still reads "guides/admin" instead of "guides/getting-started". parseDocHash strips the leading / and trailing / from the input, so parsing #/guides/getting-started/ returns dirPath: "guides/getting-started", not "guides/admin". This test will fail.
  Remediation: Change dirPath: "guides/admin" to dirPath: "guides/getting-started" on line 19.

Low

• [style] web/docs/src/lib/DocTreeNav.svelte:15, web/docs/src/lib/manifestDirs.ts:3 — JSDoc comments still reference guides/admin as example paths. These are cosmetic but inconsistent with the rename to getting-started/ and infrastructure/.
  Remediation: Update the example paths in the JSDoc comments to use guides/getting-started.

Previous run (3)

Review

Findings

Medium

• [correctness] web/docs/src/lib/hashRoute.test.ts:19 — Test expectation not updated after input change. The test input was changed from #/guides/admin/ to #/guides/getting-started/, but the expected dirPath on line 19 still reads "guides/admin" instead of "guides/getting-started". parseDocHash strips the leading / and trailing / from the input, so parsing #/guides/getting-started/ returns dirPath: "guides/getting-started", not "guides/admin". This test will fail.
  Remediation: Change dirPath: "guides/admin" to dirPath: "guides/getting-started" on line 19.

Low

• [style] web/docs/src/lib/DocTreeNav.svelte:15, web/docs/src/lib/manifestDirs.ts:3 — JSDoc comments still reference guides/admin as example paths. These are cosmetic but inconsistent with the rename to getting-started/ and infrastructure/.
  Remediation: Update the example paths in the JSDoc comments to use guides/getting-started.

Previous run (4)

Review

Findings

Medium

• [correctness] web/docs/src/lib/hashRoute.test.ts:19 — Test expectation not updated after input change. The test input was changed from #/guides/admin/ to #/guides/getting-started/, but the expected dirPath on line 19 still reads "guides/admin" instead of "guides/getting-started". parseDocHash strips the leading / and trailing / from the input, so parsing #/guides/getting-started/ returns dirPath: "guides/getting-started", not "guides/admin". This test will fail.
  Remediation: Change dirPath: "guides/admin" to dirPath: "guides/getting-started" on line 19.

Low

• [style] web/docs/src/lib/DocTreeNav.svelte:15, web/docs/src/lib/manifestDirs.ts:3 — JSDoc comments still reference guides/admin as example paths. These are cosmetic but inconsistent with the rename to getting-started/ and infrastructure/.
  Remediation: Update the example paths in the JSDoc comments to use guides/getting-started.

Previous run (5)

Review

Findings

Low

• [documentation-currency] web/docs/build/paths.ts:43 — JSDoc comment uses docs/guides/admin/installation.md as an illustrative example; this path no longer exists after the admin/ → getting-started/ + infrastructure/ rename. Same stale example paths appear in web/docs/build/paths.test.ts (lines 14, 21, 27), web/docs/build/markdown.test.ts (lines 23, 41, 58), and web/docs/README.md (line 21). No functional breakage — these are string-manipulation tests and documentation examples, not filesystem lookups — but the examples will be misleading after merge.
  Remediation: Update the example paths in JSDoc comments, test assertions, and the docs README to use getting-started/installation (or another valid path) for consistency.

Previous run (6)

Review

Findings

Low

• [correctness] internal/cli/mint.go:762 — The mint deploy --pem-dir help text describes roles/resourcemanager.projectIamAdmin as needed to "grant roles/aiplatform.user to WIF principals," but --pem-dir bootstraps PEM secrets — granting roles/aiplatform.user is the job of inference provision. If the deploy code path with --pem-dir does not actually call SetProjectIAMBinding for aiplatform, this description is misleading.
  Remediation: Verify whether mint deploy --pem-dir grants roles/aiplatform.user. If not, update the parenthetical to describe the actual reason projectIamAdmin is needed (e.g., "set IAM policy on service account").

• [style/conventions] internal/cli/inference.go, internal/cli/mint.go — The inference status and mint status commands are the only ones without IAM role documentation in their --help text. While status commands use viewer-level access (less likely to cause 403s), adding the required roles for completeness would make the documentation pattern consistent across all subcommands.
  Remediation: Add a "Required IAM roles" block to inference status (roles/iam.workloadIdentityPoolViewer, roles/browser) and mint status (roles/cloudfunctions.viewer, roles/secretmanager.viewer) help text in a follow-up.

• [documentation-currency] docs/guides/admin/github-setup.md:5 — The opening paragraph says "For the all-in-one setup that provisions both GCP and GitHub in a single command, see Installing fullsend" but installation.md now leads with the end-user setup path. The link works but the description no longer reflects the page's primary content.
  Remediation: Update to something like "For end-user setup or the all-in-one admin install, see Installing fullsend."

Previous run (7)

Review

Findings

No findings.

All seven review dimensions evaluated:

1. Correctness — IAM roles documented in CLI help text and markdown tables verified against the actual GCP API calls in internal/dispatch/gcf/. Every role maps correctly to the permissions required by the provisioner operations (WIF pool/provider CRUD, service account creation, Cloud Function deployment, Secret Manager access, Cloud Run IAM policy, project IAM bindings). Conditional role requirements (--pem-dir for mint deploy, per-repo mode for mint enroll) match the code paths that invoke those APIs. The per-command IAM breakdown table in installation.md is accurate, including footnotes for edge cases.

2. Intent alignment — The PR adds required IAM role documentation to standalone commands, motivated by a user hitting a 403 on inference provision. Changes are scoped to help text strings in Go files and three markdown documentation files. No behavior changes.

3. Platform security — No RBAC, authentication, or privilege changes. Documentation-only.

4. Content security — No user content handling changes.

5. Injection defense — PR body and commit messages inspected; no injection patterns or non-rendering Unicode detected.

6. Style/conventions — Help text formatting is consistent across commands (indented lists with "Required GCP APIs" and "Required IAM roles" sections). Markdown tables follow existing conventions. Footnote system (*, **, †, ***) in installation.md is clear and properly referenced.

7. Documentation currency — This PR is the documentation update. No existing docs are made stale by these changes. The inference status and mint status commands did not receive help text updates (only the write commands did), but their roles are documented in the markdown tables — a reasonable scoping choice.

Previous run (8)

Review

Reason: stale-head

The review agent reviewed commit ec21828efec1bb3aaffd46cfa5fcd6d69dbc37ff but the PR HEAD is now 6946d3490b06d03aeaa706dc0505f3f29bfc6682. This review was discarded to avoid approving unreviewed code.

Previous run (9)

Review

Findings

No findings.

Previous run (10)

Review

Reason: stale-head

The review agent reviewed commit 7a677e510c691ddb80c1462e52900c679ca867de but the PR HEAD is now 651c3bb991a2eab10480cd8e3b2eec80d4a1ac33. This review was discarded to avoid approving unreviewed code.

Previous run (11)

Review

Findings

No findings.

Previous run (12)

Review

Findings

No findings.