docs: deprecate all-in-one admin, restructure reference/ into sidebar sections

[waynesun09]

Summary

Deprecates the all-in-one fullsend admin command tree in user-facing docs, eliminates docs/reference/, and creates properly scoped documentation in the correct sidebar sections.

• docs/guides/getting-started/operations.md — per-repo day-2 administration: config updates, workflow syncing, uninstall, standalone commands table, IAM matrix, status notifications. Placed in the Getting Started sidebar since it targets repo maintainers.
• docs/guides/infrastructure/advanced-setup.md — non-standard installation paths: managed-mode variants (platform-provided infra, reusing existing infra, per-repo flags), self-hosted mint deployment, custom app sets, manual WIF, OAuth scopes. Placed in the Infrastructure sidebar since self-hosted content targets platform operators.
• docs/guides/getting-started/org-mode.md — expanded with per-org day-2 operations (enrollment, sync-scaffold, github status, org uninstall) and planned deprecation note per ADR 0044
• All admin install/uninstall/analyze/enable/disable references replaced with standalone equivalents (github setup, github enroll/unenroll, github status, github uninstall, inference provision/deprovision)
• docs/reference/ directory deleted (3 files) — content split between new files and existing getting-started guides
• VitePress sidebar updated: Operations under Getting Started, Advanced Setup under Infrastructure
• Self-hosted deployment accurately reflects that mint deployment (mint deploy) and GitHub App creation are independent — no "first org bootstraps everything" model

What changed

Old path	New location
docs/reference/installation.md	Split → getting-started/operations.md + infrastructure/advanced-setup.md
docs/reference/github-setup.md	Split → getting-started/operations.md + infrastructure/advanced-setup.md
docs/reference/README.md	Deleted (index no longer needed)

Files updated (cross-references)

docs/cli/github.md, docs/cli/inference.md, docs/cli/mint.md, docs/guides/getting-started/configuring-github.md, docs/guides/getting-started/org-mode.md, docs/guides/infrastructure/mint-administration.md, docs/guides/infrastructure/infrastructure-reference.md, docs/guides/user/running-agents-locally.md, docs/guides/dev/cli-internals.md, docs/guides/README.md, docs/ADRs/0047-vendored-installs-with-vendor-flag.md, website/.vitepress/config.ts

Test plan

• hack/lint-docs-links passes (0 broken links)
• All cross-references verified against target anchors
• No remaining reference/installation or reference/github-setup paths in docs/
• Per-repo operations scoped correctly (no org-only commands like github status, enrollment)
• Per-org operations moved to org-mode.md for clean future deprecation
• Self-hosted deployment decouples mint deploy from app creation

[qodo-code-review]

PR Summary by Qodo

Docs: deprecate all-in-one admin install; move reference docs into admin guides
📝 Documentation 🕐 40+ Minutes

Description

• Deprecate all-in-one fullsend admin install  guidance, leaving a short deprecation stub.
• Replace docs/reference/ with focused admin docs for advanced setup and day-2 operations.
• Update cross-links across guides/ADRs to new admin and getting-started locations.

Diagram

graph TD
  A["docs/guides/README.md"] --> B["Admin: advanced-setup.md"] --> C["Admin: operations.md"]
  A --> D["Getting started"]
  E["Infrastructure reference"] --> C
  F["Mint administration"] --> D
  G["CLI internals"] --> B
  H["User guides"] --> D

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep `docs/reference/*` as stub “moved to …” pages

• ➕ Prevents external/bookmarked links from 404ing
• ➕ Allows gradual migration while still reorganizing content
• ➖ Slightly increases ongoing docs surface area
• ➖ Requires discipline to avoid reintroducing duplicated content

2. Add site-level redirects (if supported by the docs builder)

• ➕ Best UX: old URLs continue working seamlessly
• ➕ Avoids keeping duplicate markdown files
• ➖ Depends on the documentation tooling/deployment setup
• ➖ Redirect config can be easy to miss across versions

Recommendation: The new split into Admin (advanced setup + operations) vs Getting Started reads cleaner and reduces duplication. The main concern is backward compatibility for the removed docs/reference/installation.md and docs/reference/github-setup.md URLs; if redirects are not already in place, consider adding minimal stub pages (or redirects) to avoid breaking inbound links.

Files changed (12) +644 / -17

Documentation (12) +644 / -17

0047-vendored-installs-with-vendor-flag.mdUpdate ADR reference link to new Admin advanced setup guide +1/-1

Update ADR reference link to new Admin advanced setup guide

• Replaces the old installation guide reference under docs/reference with a pointer to the new admin advanced setup documentation.

docs/ADRs/0047-vendored-installs-with-vendor-flag.md

README.mdAdd Admin section to guides index +7/-0

Add Admin section to guides index

• Introduces an Admin section describing operator-focused workflows and links to the new Advanced setup and Operations pages.

docs/guides/README.md

README.mdCreate Admin guide index +6/-0

Create Admin guide index

• Adds an admin-focused README that frames the audience (org owners/repo admins) and links to the two new admin guides.

docs/guides/admin/README.md

advanced-setup.mdAdd advanced admin installation/setup reference (and deprecation stub) +340/-0

Add advanced admin installation/setup reference (and deprecation stub)

• Adds a comprehensive advanced setup guide covering per-repo variants, platform-provided infrastructure, key flags, custom app sets, OAuth scope reference, and manual WIF setup. Collapses the all-in-one admin install path to a short deprecated stub with pointers to preferred flows.

docs/guides/admin/advanced-setup.md

operations.mdAdd day-2 administration and standalone command guide +274/-0

Add day-2 administration and standalone command guide

• Adds an operations guide for enrollment management, configuration updates, scaffold sync, status checks, uninstall flows, and a standalone-command breakdown for split-responsibility teams.

docs/guides/admin/operations.md

cli-internals.mdRepoint internal cross-references from reference docs to Admin/Getting Started +3/-3

Repoint internal cross-references from reference docs to Admin/Getting Started

• Updates handoff and “See Also” links to reference the new Admin advanced setup and Getting Started pages instead of deleted docs/reference paths.

docs/guides/dev/cli-internals.md

infrastructure-reference.mdUpdate infrastructure guide links to new setup/operations docs +4/-4

Update infrastructure guide links to new setup/operations docs

• Replaces installation and GitHub-setup references with Getting Started and Admin Operations links, including a deep link to configuration update instructions.

docs/guides/infrastructure/infrastructure-reference.md

mint-administration.mdUpdate mint operator guide to point to Getting Started/Admin docs +4/-4

Update mint operator guide to point to Getting Started/Admin docs

• Replaces end-user setup references previously pointing to docs/reference with Getting Started and Admin advanced setup links.

docs/guides/infrastructure/mint-administration.md

private-repositories.mdUpdate private repo guide prerequisite link to Getting Started +1/-1

Update private repo guide prerequisite link to Getting Started

• Adjusts the setup prerequisite link away from the deleted installation reference page to the Getting Started guides.

docs/guides/infrastructure/private-repositories.md

bugfix-workflow.mdUpdate user workflow guide install prerequisite links +2/-2

Update user workflow guide install prerequisite links

• Repoints installation/enrollment prerequisite links from docs/reference to Getting Started while keeping the same intent for readers.

docs/guides/user/bugfix-workflow.md

customizing-agents.mdUpdate customization guide setup link to Getting Started +1/-1

Update customization guide setup link to Getting Started

• Switches the initial setup reference from the removed installation guide to the Getting Started guides.

docs/guides/user/customizing-agents.md

running-agents-locally.mdUpdate status notification reference to Admin operations guide +1/-1

Update status notification reference to Admin operations guide

• Replaces a deep-link into the removed installation doc with a deep-link to the new operations guide section covering status notifications.

docs/guides/user/running-agents-locally.md

[github-actions]

Site preview

Preview: https://f0d85dd2-site.fullsend-ai.workers.dev

Commit: 69ebef971cb987e874b92fce159cfbf4676b05b9

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 3:32 PM UTC · Ended 3:37 PM UTC
Commit: 7f5ce3c · View workflow run →

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (3)

Context used

✅ Compliance rules (platform): 51 rules

✅ Skills: writing-user-docs, writing-adrs

1. operations.md lacks prerequisites section 📜 Skill insight ✧ Quality

Description

docs/guides/admin/operations.md introduces procedural admin commands without any clearly labeled
prerequisites section. This violates the guide requirement and can cause operators to run commands
without required access/scopes/context.

Code

docs/guides/admin/operations.md[R1-12]

+# Operations
+
+Day-2 administration for fullsend: enrollment, configuration updates, status checks, uninstall, and standalone commands for split-responsibility workflows.
+
+## Managing repository enrollment
+
+After installation, you can enroll or unenroll repositories at any time.
+
+### Enable repositories
+
+To enroll specific repositories (pass repo names as arguments):
+

Relevance

⭐⭐⭐ High

Team enforces doc prerequisites sections; PR #2663 suggestion explicitly adding “Prerequisites”
before procedures was accepted.

PR-#2663

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062078 requires a clearly labeled prerequisites section before procedural steps.
In docs/guides/admin/operations.md, the document begins procedural instructions (e.g., enrolling
repos) immediately after the intro with no prerequisites section present.

docs/guides/admin/operations.md[1-12]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/guides/admin/operations.md` contains procedural guidance (commands to run) but does not include a clearly labeled prerequisites section before the procedures.

## Issue Context
Compliance requires every documentation guide with procedures to include prerequisites before step 1, so readers know required permissions, tools, and inputs.

## Fix Focus Areas
- docs/guides/admin/operations.md[1-12]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. operations.md uses prose steps 📜 Skill insight ✧ Quality

Description

docs/guides/admin/operations.md describes procedures as prose paragraphs with code blocks instead
of numbered steps. This makes operational procedures harder to follow consistently and violates the
procedural formatting requirement.

Code

docs/guides/admin/operations.md[R9-21]

+### Enable repositories
+
+To enroll specific repositories (pass repo names as arguments):
+
+```bash
+fullsend admin enable repos "$ORG_NAME" <repo-name> [repo-name...]
+```
+
+To enroll all repositories:
+
+```bash
+fullsend admin enable repos "$ORG_NAME" --all
+```

Relevance

⭐⭐⭐ High

Team prefers numbered procedural steps; PR #2663 accepted rewriting prose procedures into ordered
lists.

PR-#2663

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062079 requires procedures to use numbered steps rather than narrative prose. In
the cited section, the guide instructs actions using prose lead-ins ("To enroll...") followed by
commands, without any ordered list of steps.

docs/guides/admin/operations.md[9-21]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Procedural instructions in `docs/guides/admin/operations.md` are written as prose (e.g., "To enroll...") rather than as numbered steps.

## Issue Context
Compliance requires procedural content in guides to be expressed as numbered (ordered) lists.

## Fix Focus Areas
- docs/guides/admin/operations.md[9-33]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Dead GitHub-setup link 🐞 Bug ≡ Correctness

Description

docs/guides/getting-started/configuring-github.md still links to
../../reference/github-setup.md#setup-flags, but this PR deletes docs/reference/github-setup.md,
leaving a dead link in the Getting Started flow.

Code

docs/reference/github-setup.md[L1-10]

-# Setting up fullsend with pre-provisioned infrastructure
-
-This guide walks through configuring fullsend in a GitHub organization or repository when the GCP infrastructure (token mint and inference WIF) has already been provisioned by a GCP administrator. No GCP credentials are required.
-
-For the all-in-one setup that provisions both GCP and GitHub in a single command, see [Installing fullsend](installation.md).
-
-## Prerequisites
-
-- **GitHub access** — the required permission level depends on the setup mode:
-  - **Per-org mode** (`fullsend github setup <org>`) requires **GitHub organization owner** access. The command creates org-level variables (`FULLSEND_MINT_URL`), creates the `.fullsend` config repo, and (unless `--skip-app-setup` is passed) creates or installs GitHub Apps — all of which require the `admin:org` OAuth scope.

Relevance

⭐⭐⭐ High

Broken doc links are treated as fixes; PR #783 added link linting + fixed broken links, PR #226
fixed broken ADR links.

PR-#783
PR-#226

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The Getting Started guide still contains a markdown link targeting the now-deleted reference doc,
while the new Admin guide contains the replacement “Setup flags” section that should be linked
instead.

docs/guides/getting-started/configuring-github.md[65-70]
docs/guides/admin/advanced-setup.md[156-174]
PR-#226

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A Getting Started doc still links to `docs/reference/github-setup.md#setup-flags`, but `docs/reference/github-setup.md` is deleted in this PR. This leaves a dead link for readers and breaks the stated test plan expectation that no `reference/github-setup` references remain.

## Issue Context
The replacement content (including the setup flags table) now lives in the Admin guide.

## Fix Focus Areas
- docs/guides/getting-started/configuring-github.md[65-70]
- docs/guides/admin/advanced-setup.md[156-174]

## Suggested change
Update the stale link to point at the new location, e.g.:
- From: `../../reference/github-setup.md#setup-flags`
- To: `../admin/advanced-setup.md#setup-flags`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (1)

4. advanced-setup.md uses undefined OIDC 📜 Skill insight ✧ Quality

Description

docs/guides/admin/advanced-setup.md introduces the acronym OIDC without an inline definition or
a glossary link. This can confuse readers unfamiliar with the term and violates the
jargon-definition requirement.

Code

docs/guides/admin/advanced-setup.md[19]

+- **Mint URL** — obtain from your platform operator (for OIDC token exchange)

Relevance

⭐⭐ Medium

Mixed acronym guidance: PR #1017 accepted reducing “OOTB” acronym, but rejected removing “BYOA”
acronym usage.

PR-#1017

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062083 requires jargon to be defined on first use. The guide references OIDC
(e.g., "OIDC token exchange") without expanding it (e.g., "OpenID Connect (OIDC)") or linking to a
glossary definition.

docs/guides/admin/advanced-setup.md[17-24]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The guide uses the acronym `OIDC` without defining it inline or linking to the glossary on first use.

## Issue Context
Compliance requires jargon to be defined on first use via a glossary link or inline definition.

## Fix Focus Areas
- docs/guides/admin/advanced-setup.md[17-24]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:40 PM UTC · Completed 3:51 PM UTC
Commit: cc80ad3 · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

High

• [api-contract] docs/guides/infrastructure/advanced-setup.md:28 — --mint-project and --mint-region are documented as flags for fullsend github setup, but github setup (in internal/cli/github.go) does not define these flags. They exist only on the deprecated fullsend admin install command (internal/cli/admin.go lines 564–565). The sentence "pass --mint-project and --mint-region to github setup" will lead users to "unknown flag" errors.
  Remediation: Either remove the sentence about --mint-project/--mint-region on github setup, or add these flags to newGitHubSetupCmd() in internal/cli/github.go.

• [api-contract] docs/guides/infrastructure/mint-administration.md:385 — The multi-org "First org" example uses non-existent CLI flag/format combinations: fullsend mint status --project="$GCP_PROJECT" -o url and fullsend inference status "$FIRST_ORG" --project="$GCP_PROJECT" -o provider. mint status (in internal/cli/mint.go) only accepts --project and --region — no -o or --output flag. inference status (in internal/cli/inference.go) has --format (not -o) with valid values text, json, env — not url or provider. Users following this example will get unrecognized flag errors, and the $MINT_URL and $WIF_PROVIDER variables in the "Additional orgs" section (line ~409) will never be assigned since they depend on these invalid subshell commands. See also: [logic-error] finding at mint-administration.md:409.
  Remediation: Replace the subshell invocations with placeholder variables ($MINT_URL and $WIF_PROVIDER) and add comments explaining how to obtain these values from the prior commands' output (e.g., "copy the mint URL from mint deploy output" and "copy the WIF provider from inference provision output").

Medium

• [logic-error] docs/guides/infrastructure/mint-administration.md:409 — In the "Additional orgs" multi-org example, $MINT_URL and $WIF_PROVIDER are used in fullsend github setup but never assigned. The "First org" section attempts to derive these via subshell commands with invalid -o flags (see [api-contract] finding above), so even if a user ran the first-org section, the variables would not be set. See also: [api-contract] finding at mint-administration.md:385.
  Remediation: Add explicit variable assignments (export MINT_URL=... and export WIF_PROVIDER=...) with instructions to copy values from prior command output, or use placeholder comments before the additional-org example block.

• [logic-error] docs/guides/dev/cli-internals.md:277 — The text was changed from "admin analyze reports stale vendored assets" to "github status reports stale vendored assets", but github status (runGitHubStatus in internal/cli/github.go) does not check for stale vendored assets — it only inspects config repo presence, config.yaml validity, enrollment state, org variables, and inference secrets. The stale vendored asset reporting logic remains in admin analyze (runAnalyze in internal/cli/admin.go).
  Remediation: Revert to "admin analyze reports stale vendored assets" or, if admin analyze is being deprecated, note that this functionality is not yet available in a non-deprecated command.

Previous run

Review

Findings

High

• [api-contract] docs/guides/infrastructure/advanced-setup.md:185 — --mint-project and --mint-region are documented as flags on fullsend github setup, but github setup (in internal/cli/github.go) does not define these flags. They exist only on the deprecated fullsend admin install command (internal/cli/admin.go lines 564–565). The "Assisted installation" example fullsend github setup ... --mint-project "$PLATFORM_MINT_PROJECT" --mint-region "$PLATFORM_MINT_REGION" will fail with "unknown flag" errors.
  Remediation: Remove --mint-project and --mint-region from the github setup example. If the assisted installation workflow requires mint project discovery, either add these flags to github setup in internal/cli/github.go, or restructure the example to explain how to obtain the mint URL first (e.g., via fullsend mint status).

• [api-contract] docs/guides/infrastructure/mint-administration.md:382 — The rewritten multi-org "First org" example uses non-existent CLI flag/format combinations: fullsend mint status --project="$GCP_PROJECT" -o url and fullsend inference status "$FIRST_ORG" --project="$GCP_PROJECT" -o provider. mint status (in internal/cli/mint.go) only accepts --project and --region — no -o or --output flag. inference status (in internal/cli/inference.go) has --format (not -o) with valid values text, json, env — not url or provider. Users following this example will get unrecognized flag errors, and the $MINT_URL and $WIF_PROVIDER variables in the "Additional orgs" section (line ~410) will never be assigned since they depend on these invalid subshell commands. See also: [logic-error] finding at mint-administration.md:410.
  Remediation: Replace the subshell invocations with placeholder variables ($MINT_URL and $WIF_PROVIDER) and add comments explaining how to obtain these values from the prior commands' output (e.g., "copy the mint URL from mint status output" and "copy the WIF provider from inference status output").

Medium

• [logic-error] docs/guides/infrastructure/mint-administration.md:410 — In the "Additional orgs" multi-org example, $MINT_URL and $WIF_PROVIDER are used in fullsend github setup but never assigned. The "First org" section attempts to derive these via subshell commands with invalid -o flags (see [api-contract] finding above), so even if a user ran the first-org section, the variables would not be set. See also: [api-contract] finding at mint-administration.md:382.
  Remediation: Add explicit variable assignments (export MINT_URL=... and export WIF_PROVIDER=...) with instructions to copy values from prior command output, or use placeholder comments before the additional-org example block.

Previous run

Review

Findings

High

• [api-contract] docs/guides/admin/advanced-setup.md:185 — --mint-project and --mint-region are documented as flags on fullsend github setup, but github setup (in internal/cli/github.go) does not define these flags. They exist only on the deprecated fullsend admin install command (internal/cli/admin.go lines 564–565). The "Assisted installation" example fullsend github setup ... --mint-project "$PLATFORM_MINT_PROJECT" --mint-region "$PLATFORM_MINT_REGION" will fail with "unknown flag" errors.
  Remediation: Remove --mint-project and --mint-region from the github setup example. If the assisted installation workflow requires mint project discovery, either add these flags to github setup in internal/cli/github.go, or restructure the example to explain how to obtain the mint URL first (e.g., via fullsend mint status).

• [api-contract] docs/guides/infrastructure/mint-administration.md:382 — The rewritten multi-org "First org" example uses non-existent CLI flag/format combinations: fullsend mint status --project="$GCP_PROJECT" -o url and fullsend inference status "$FIRST_ORG" --project="$GCP_PROJECT" -o provider. mint status (in internal/cli/mint.go) only accepts --project and --region — no -o or --output flag. inference status (in internal/cli/inference.go) has --format (not -o) with valid values text, json, env — not url or provider. Users following this example will get unrecognized flag errors, and the $MINT_URL and $WIF_PROVIDER variables in the "Additional orgs" section (line ~410) will never be assigned since they depend on these invalid subshell commands. See also: [logic-error] finding at mint-administration.md:410.
  Remediation: Replace the subshell invocations with placeholder variables ($MINT_URL and $WIF_PROVIDER) and add comments explaining how to obtain these values from the prior commands' output (e.g., "copy the mint URL from mint status output" and "copy the WIF provider from inference status output").

Medium

• [logic-error] docs/guides/infrastructure/mint-administration.md:410 — In the "Additional orgs" multi-org example, $MINT_URL and $WIF_PROVIDER are used in fullsend github setup but never assigned. The "First org" section attempts to derive these via subshell commands with invalid -o flags (see [api-contract] finding above), so even if a user ran the first-org section, the variables would not be set. See also: [api-contract] finding at mint-administration.md:382.
  Remediation: Add explicit variable assignments (export MINT_URL=... and export WIF_PROVIDER=...) with instructions to copy values from prior command output, or use placeholder comments before the additional-org example block.

Previous run (2)

Review

Findings

High

• [api-contract] docs/guides/admin/advanced-setup.md:185 — The "Assisted installation" section documents --mint-project and --mint-region as flags on fullsend github setup, but github setup (in internal/cli/github.go) does not define these flags. They exist only on the deprecated fullsend admin install command (internal/cli/admin.go lines 564–565). The example fullsend github setup ... --mint-project "$PLATFORM_MINT_PROJECT" --mint-region "$PLATFORM_MINT_REGION" will fail with "unknown flag" errors.
  Remediation: Remove --mint-project and --mint-region from the github setup example. If the assisted installation workflow requires mint project discovery, either add these flags to github setup, or restructure the example to explain how to obtain the mint URL first.

• [api-contract] docs/guides/infrastructure/mint-administration.md:382 — The rewritten multi-org setup example uses non-existent CLI flag/format combinations: fullsend mint status --project="$GCP_PROJECT" -o url and fullsend inference status "$FIRST_ORG" --project="$GCP_PROJECT" -o provider. mint status (in internal/cli/mint.go) only accepts --project and --region; inference status (in internal/cli/inference.go) has --format (not -o) with valid values text, json, env — not url or provider. Users following this example will get unrecognized flag errors.
  Remediation: Replace the subshell invocations with placeholder variables ($MINT_URL and $WIF_PROVIDER) and add comments explaining how to obtain these values from the prior commands' output.

Medium

• [logic-error] docs/guides/infrastructure/mint-administration.md:400 — In the "Additional orgs" multi-org example, $MINT_URL and $WIF_PROVIDER are used in fullsend github setup but never assigned. The first-org section attempts to derive these via subshell commands with the invalid -o flags (see api-contract finding above), so even if a user ran the first-org section, the variables would not be set. See also: [api-contract] finding at this location.
  Remediation: Add explicit variable assignments (export MINT_URL=... and export WIF_PROVIDER=...) or use placeholder comments before the additional-org example block.

• [architectural-coherence] docs/guides/admin/advanced-setup.md — The "Deprecated: all-in-one admin install" section marks per-org admin install <org> as deprecated in documentation, but the CLI implementation (internal/cli/admin.go) contains no corresponding deprecation warning when users invoke fullsend admin install <org>. ADR-0044 Phase 1 lists CLI warnings and documentation updates as separate PRs.
  Remediation: Add a deprecation warning to the CLI in a companion PR, or note in the PR description that documentation intentionally ships ahead of CLI warnings with a follow-up tracked for the CLI change.

Previous run (3)

Review

Findings

High

• [api-contract] docs/guides/admin/advanced-setup.md:125 — The "Assisted installation" section documents --mint-project and --mint-region as flags on fullsend github setup, but github setup (in internal/cli/github.go) does not define these flags. They exist only on the deprecated fullsend admin install command (internal/cli/admin.go lines 564–565). The example fullsend github setup ... --mint-project "$PLATFORM_MINT_PROJECT" --mint-region "$PLATFORM_MINT_REGION" will fail with "unknown flag" errors.
  Remediation: Remove --mint-project and --mint-region from the github setup example. If the assisted installation workflow requires mint project discovery, either add these flags to github setup, or restructure the example to explain how to obtain the mint URL first.

• [api-contract] docs/guides/infrastructure/mint-administration.md — The rewritten multi-org setup example uses non-existent CLI flags: fullsend mint status --project="$GCP_PROJECT" -o url and fullsend inference status "$FIRST_ORG" --project="$GCP_PROJECT" -o provider. mint status only accepts --project and --region; inference status accepts --format text|json|env but not -o. Users following this example will get unrecognized flag errors.
  Remediation: Replace the subshell invocations with placeholder variables ($MINT_URL and $WIF_PROVIDER) and add comments explaining how to obtain these values from the prior commands' output.

Medium

• [logic-error] docs/guides/infrastructure/mint-administration.md — In the "Additional orgs" multi-org example, $MINT_URL and $WIF_PROVIDER are used but never assigned. The first-org section attempts to derive these via subshell commands with the invalid -o flags (see api-contract finding above), so even if a user ran the first-org section, the variables would not be set. See also: [api-contract] finding at this location.
  Remediation: Add explicit variable assignments (export MINT_URL=... and export WIF_PROVIDER=...) or use placeholder comments before the additional-org example block.

• [stale-reference] skills/mint-enroll/SKILL.md:85 — References deprecated fullsend admin install command at lines 85, 90, 195, 203, and 213. The PR deprecates admin install in user-facing docs in favor of standalone commands, but this skill definition still directs agents to use the deprecated command.
  Remediation: Update the referenced lines to use the standalone commands (fullsend github setup, fullsend mint deploy, etc.).

• [architectural-coherence] docs/guides/admin/advanced-setup.md:407 — The "Deprecated: all-in-one admin install" section marks per-org admin install <org> as deprecated in documentation, but the CLI implementation (internal/cli/admin.go) contains no corresponding deprecation warning when users invoke fullsend admin install <org>. ADR-0044 Phase 1 lists CLI warnings as step 1 and documentation updates as step 2, so documentation is shipping ahead of CLI warnings.
  Remediation: Add a deprecation warning to the CLI in a companion PR, or note in the PR description that documentation intentionally ships ahead of CLI warnings with a follow-up tracked for the CLI change.

• [directory-structure-coherence] docs/guides/admin/README.md:1 — The PR creates a new docs/guides/admin/ directory, but ADR-0023 Revision (2026-05) states: "The original admin/ directory was split into getting-started/ and infrastructure/ to better reflect the distinct audiences." This PR reintroduces admin/ alongside the existing directories, creating a three-way split.
  Remediation: Update ADR-0023 to document the three-way split and define clear audience boundaries, or distribute the new content into the existing directories.

Previous run (4)

Review

Findings

Medium

• [architectural-coherence] docs/guides/admin/advanced-setup.md:390 — The new "Deprecated: all-in-one admin install" section marks per-org admin install <org> as deprecated in documentation, but the CLI implementation (internal/cli/admin.go) contains no corresponding deprecation warning when users invoke fullsend admin install <org>. This creates a documentation-code mismatch: users reading docs see "Deprecated" but receive no runtime signal when using the command.
  Remediation: Add a deprecation warning to the CLI output for fullsend admin install <org>, or revise the docs to describe it as "not recommended" or "alternative" rather than "deprecated" until the CLI catches up.

Previous run (5)

Review

Findings

Medium

• [documentation-accuracy] docs/guides/README.md:9 — The updated Getting Started section lists [Mint enrollment](getting-started/README.md) as the first step with the description "Enroll your org or repo in a token mint before configuring anything else." The getting-started/README.md content explains that mint enrollment currently requires contacting the fullsend team and is not self-service. Listing it as the first step in a section aimed at users "onboarding organizations and configuring GitHub" could confuse users into thinking they should perform enrollment themselves, when this is typically a platform-operator prerequisite.
  Remediation: Clarify the entry to indicate mint enrollment is a prerequisite typically handled by a platform operator, or reorder so that user-actionable steps (Getting Inference, Configuring GitHub) appear first with mint enrollment noted as a prerequisite.

Previous run

Review

Findings

Medium

• [scope-creep] docs/guides/admin/advanced-setup.md — The new "Deprecated: all-in-one admin install" section marks fullsend admin install <org> per-org mode as deprecated, but this is a docs-only PR with no corresponding CLI deprecation warnings. Per ADR-0044, Phase 1 calls for both CLI warnings (PR 1) and documentation updates (PR 2). Publishing a deprecation notice in docs before the CLI emits warnings may confuse users who see "Deprecated" in the docs but receive no warning from the tool itself.
  Remediation: Coordinate with the CLI deprecation warnings PR, or note in the PR description that this documentation intentionally ships ahead of CLI warnings.

---

Labels: PR restructures documentation under docs/guides/ and removes docs/reference/

Previous run (6)

Review

Findings

Medium

• [documentation-accuracy] docs/guides/README.md:9 — The updated Getting Started section lists [Mint enrollment](getting-started/README.md) as the first step with the description "Enroll your org or repo in a token mint before configuring anything else." The getting-started/README.md content explains that mint enrollment currently requires contacting the fullsend team and is not self-service. Listing it as the first step in a section aimed at users "onboarding organizations and configuring GitHub" could confuse users into thinking they should perform enrollment themselves, when this is typically a platform-operator prerequisite.
  Remediation: Clarify the entry to indicate mint enrollment is a prerequisite typically handled by a platform operator, or reorder so that user-actionable steps (Getting Inference, Configuring GitHub) appear first with mint enrollment noted as a prerequisite.

Previous run (7)

Review

Findings

Medium

• [scope-creep] docs/guides/admin/advanced-setup.md — The new "Deprecated: all-in-one admin install" section marks fullsend admin install <org> per-org mode as deprecated, but this is a docs-only PR with no corresponding CLI deprecation warnings. Per ADR-0044, Phase 1 calls for both CLI warnings (PR 1) and documentation updates (PR 2). Publishing a deprecation notice in docs before the CLI emits warnings may confuse users who see "Deprecated" in the docs but receive no warning from the tool itself.
  Remediation: Coordinate with the CLI deprecation warnings PR, or note in the PR description that this documentation intentionally ships ahead of CLI warnings.

---

Labels: PR restructures documentation under docs/guides/ and removes docs/reference/

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 4:02 PM UTC · Ended 4:03 PM UTC
Commit: 7f5ce3c · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 4:06 PM UTC · Ended 4:15 PM UTC
Commit: 7f5ce3c · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:18 PM UTC · Completed 4:32 PM UTC
Commit: 69d49bb · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 7:18 PM UTC · Ended 7:23 PM UTC
Commit: 657bf48 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 7:28 PM UTC · Ended 7:30 PM UTC
Commit: 657bf48 · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 7:33 PM UTC · Ended 7:42 PM UTC
Commit: 657bf48 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:44 PM UTC · Completed 7:59 PM UTC
Commit: 69ebef9 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[high] api-contract

--mint-project and --mint-region are documented as flags for fullsend github setup, but github setup (in internal/cli/github.go) does not define these flags. They exist only on the deprecated fullsend admin install command.

Suggested fix: Either remove the sentence about --mint-project/--mint-region on github setup, or add these flags to newGitHubSetupCmd() in internal/cli/github.go.

[fullsend-ai-review]

[high] api-contract

The multi-org First org example uses non-existent CLI flags: fullsend mint status -o url and fullsend inference status -o provider. mint status has no -o flag; inference status uses --format with values text, json, env.

Suggested fix: Replace the inline subshells with placeholder variables and add comments explaining how to obtain values from prior commands output.

[fullsend-ai-review]

[medium] logic-error

In the Additional orgs example, $MINT_URL and $WIF_PROVIDER are referenced but never assigned due to the invalid subshell commands in the First org section.

Suggested fix: Add explicit variable assignments with instructions to copy values from prior command output.

[fullsend-ai-review]

[medium] logic-error

Changed from admin analyze reports stale vendored assets to github status reports stale vendored assets, but github status does not check for stale vendored assets. That functionality remains in admin analyze.

Suggested fix: Revert to admin analyze reports stale vendored assets or note that this functionality is not yet available in a non-deprecated command.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:06 PM UTC · Completed 8:15 PM UTC
Commit: 69ebef9 · View workflow run →

[fullsend-ai-retro]

Retro: PR #2698 — docs: deprecate all-in-one admin, restructure reference/

Timeline

1. June 26 15:28 — PR created by waynesun09 (single commit). Large docs restructuring: deprecating admin commands, deleting docs/reference/, creating new focused guides.
2. June 26 15:30–15:34 — qodo-code-review bot posts 4 findings (dead link, missing prerequisites, prose formatting, undefined OIDC acronym).
3. June 29 06:31 — Human reviewer rh-hemartin flags that docs/guides/admin/advanced-setup.md still references the admin install command, inconsistent with the deprecation goal.
4. June 29 14:06 — rh-hemartin flags the same pattern in operations.md: deprecated admin commands still documented.
5. June 29 17:51 — fullsend-ai-review bot posts first CHANGES_REQUESTED with 4 high/medium findings: --mint-project/--mint-region flags documented on github setup but only exist on deprecated admin install; -o flag doesn't exist on mint status/inference status; $MINT_URL/$WIF_PROVIDER variables used but never assigned.
6. June 29 17:54 — Human reviewer ralphbean approves with "LGTM" — just 3 minutes after the bot's changes-requested verdict.
7. June 29 18:16 — Review bot posts 2nd CHANGES_REQUESTED (same findings, same SHA).
8. June 29 19:06–19:34 — Fix agent runs (success), code agent runs (failure). Neither appears to have addressed the review findings.
9. June 29 19:59 — Review bot posts 3rd CHANGES_REQUESTED (same findings + new one about github status not supporting stale vendored asset checks).
10. June 29 20:01 — PR merged with 3 unresolved CHANGES_REQUESTED verdicts from the review bot.

Assessment

Review quality was strong. The review bot correctly identified that the docs claimed CLI flags (--mint-project, --mint-region, -o) exist on commands where they don't, by cross-referencing the Go source code. These are genuine correctness bugs — users following the docs would get "unknown flag" errors. The human reviewer (rh-hemartin) caught a complementary issue at a higher level of abstraction: deprecated commands were still being documented at all. Both sets of findings were valid.

The findings were never addressed. The PR was merged with incorrect CLI flag documentation. The human LGTM approval came just 3 minutes after the bot's first CHANGES_REQUESTED, suggesting the bot's findings may not have been read.

Review noise was significant. The bot posted 11 inline comments across 3 review rounds, but only ~4 were unique findings — each was repeated 3 times on the same commit SHA.

Existing issues covering observed patterns

All major improvement opportunities from this workflow are already tracked:

• #1013 — Deduplicate findings across review iterations (covers the 3× repeated findings)
• #963 — Skip review dispatch when HEAD SHA was already reviewed (covers re-reviewing the same commit)
• #1500 — Don't re-request changes for unchanged findings (covers repeated CHANGES_REQUESTED)
• #2099 — Alert when human approves with unresolved Medium+ findings (covers the LGTM over high-severity findings)
• #1201 — CHANGES_REQUESTED did not block merge of PR with known correctness bug (covers the merge-despite-objections pattern)
• #1742 — Fix agent should incorporate prior review comments (covers the fix agent not addressing review findings)

No new proposals are warranted — the existing issue backlog comprehensively covers the improvement opportunities identified in this workflow.