docs(install): refactor of installation guides

[rh-hemartin]

• Created new getting started flow.
• The goal of these new guides are to be as short as possible, no details and as little explanation as possible.
• Moved previous installation and github-setup files to docs/reference for future rework.

Notes:

• Sidebar ordering will be addressed in the future.
• --mint-url is required on all released versions, main has the default value.
• I dropped some permissions and APIs for GCP as they are only needed for the mint, those will be listed in the mint specific guide.

[github-actions]

Site preview

Preview: https://2263e5e1-site.fullsend-ai.workers.dev

Commit: 3ab825ae984f59f7f68483d03a390c24ef3b19df

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 2:58 PM UTC · Completed 3:08 PM UTC
Commit: 4ed6da4 · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [architectural-deviation] docs/reference/installation.md — This PR introduces a new top-level documentation directory docs/reference/ that is not covered by ADR 0023. ADR 0023 (status: Accepted, including its May 2026 revision) defines the documentation structure exclusively under docs/guides/ with audience-based subdirectories (getting-started/, infrastructure/, user/, dev/). The docs/reference/ directory is an undocumented deviation from the accepted architecture.
  Remediation: Either propose an ADR amendment that adds docs/reference/ to the accepted structure and defines its relationship to docs/guides/, or keep the comprehensive installation guides in docs/guides/.

• [scope-coherence] docs/guides/README.md:4 — The PR removes the ADR 0023 reference (Structure decided in [ADR 0023]...) without explanation or replacement. ADR 0023 is an Accepted ADR that defines the user documentation structure. Removing this reference removes traceability between the implementation and the architectural decision.
  Remediation: Retain the ADR 0023 reference unless superseding it with a new ADR that explicitly covers the structural changes.

• [test-documentation-drift] web/docs/build/markdown.test.ts:23 — Test uses docs/guides/getting-started/installation.md as the sourceFile parameter for markdownToHtml. This path affects link rewriting logic (relative links resolve based on this path). After the file moves to docs/reference/installation.md, the test still passes but validates behavior for a path that no longer exists.
  Remediation: Update test examples to use docs/reference/installation.md.

Low

• [title-convention] docs/guides/getting-started/README.md:1 — The H1 title # README is not descriptive. A title like # Getting Started would better communicate the section's purpose.

• [jsdoc-documentation-drift] web/docs/build/paths.ts:43 — JSDoc comment on filePathToRouteKey uses docs/guides/getting-started/installation.md as an illustrative example. This path is stale after the file was moved to docs/reference/installation.md.

• [capitalization-consistency] docs/guides/getting-started/configuring-github.md:1, getting-inference.md:1, org-mode.md:1, README.md:3 — The product name appears as Fullsend (capitalized) in new file titles and body text. Established convention uses lowercase fullsend in titles (e.g., "Installing fullsend", "Enabling fullsend on private repositories").

• [link-description-format] docs/guides/README.md:9 — New getting-started links lack the em-dash descriptions used by all other entries in this file (e.g., [Title](path) — Description).

• [missing-authorization] — Non-trivial structural documentation changes (4 new files, 2 file moves, 10+ cross-reference updates) without a linked issue.

• [documentation-coherence] docs/guides/getting-started/getting-inference.md — The PR creates new getting-started guides that overlap with comprehensive guides moved to docs/reference/ "for future rework", creating two parallel documentation sets covering similar topics. Clarifying the relationship between the two would help readers.

Info

• [naming-alignment] docs/guides/getting-started/org-mode.md — The filename org-mode.md may create confusion with Emacs org-mode. A name like per-org-installation.md or organization-mode.md would be more specific.

Previous run

Review

Findings

Medium

• [architectural-deviation] docs/reference/installation.md — This PR introduces a new top-level documentation directory docs/reference/ that is not covered by ADR 0023 (User documentation structure). ADR 0023 defines the structure as docs/guides/ with subdirectories. While ADR 0023 was already amended once (May 2026 revision splitting admin/ into getting-started/ and infrastructure/), the docs/reference/ directory is a new organizational concept that should be documented.
  Remediation: Add a revision section to ADR 0023 documenting the docs/reference/ directory, or write a new ADR.

• [scope-coherence] docs/guides/README.md — The PR removes the ADR 0023 reference (Structure decided in [ADR 0023]...) from docs/guides/README.md without explanation. ADR 0023 is an Accepted ADR that defines the user documentation structure. Removing its reference without updating the ADR or providing an alternative architectural reference leaves readers without guidance on why the documentation is organized the way it is.
  Remediation: Keep the ADR 0023 reference or replace with an updated architectural reference.

Low

• [logic-error] docs/guides/getting-started/org-mode.md:16 — Typo: fullsend inference provison — "provison" should be "provision".
  Remediation: Change provison to provision.

• [naming-alignment] docs/guides/getting-started/org-mode.md — The filename org-mode.md could create confusion with Emacs org-mode. In the fullsend context this means "per-organization installation mode". Consider a more specific name like per-org-installation.md or organization-mode.md.

• [missing-authorization] — This PR makes structural documentation changes (moving files, creating 3 new guides, updating cross-references) without a linked issue. Good practice for non-trivial changes is to file a tracking issue.

• [documentation-coherence] docs/guides/README.md — The PR creates new getting-started guides but moves old comprehensive guides to docs/reference/ "for future rework", creating two sets of documentation. Clarifying the intended user journey (which guides are the primary path?) would help readers.

• [stale-reference] web/docs/README.md:21 — Example URL references old path guides/getting-started/installation. After the file move, this example will not correspond to an actual file.

• [stale-reference] web/docs/build/paths.ts:43 — JSDoc comment uses old path docs/guides/getting-started/installation.md as an illustrative example.

• [stale-reference] web/docs/build/paths.test.ts:14 — Test fixtures use old path docs/guides/getting-started/installation.md. Tests still pass (string manipulation, not filesystem access) but fixture paths will be stale.

• [stale-reference] web/docs/build/markdown.test.ts:23 — Three test cases pass old path as source file parameter. Tests still pass but examples will be stale after the rename.

• [skill-documentation-drift] skills/writing-user-docs/SKILL.md:18 — The writing-user-docs skill documentation shows old directory structure (admin/ and user/ only). This PR's structural changes widen this existing drift.

[waynesun09]

Review Squad Report

Agents dispatched: 10 (3× claude-coder, 3× claude-researcher, 2× gemini-code-review, 2× cursor-code-review)
Total findings: 17 (after dedup, verification, and triage)
False positives removed: 4

---

Critical (1)

1. Wrong GCP API in getting-inference.md
docs/guides/getting-started/getting-inference.md:29
The gcloud services enable block lists iamcredentials.googleapis.com, which is a mint runtime dependency (internal/cli/mint.go:345), not an inference dependency. The required API for inference is aiplatform.googleapis.com (internal/cli/inference.go:85). Users following this guide will enable the wrong API and fullsend inference provision will fail.
Suggestion: Replace iamcredentials.googleapis.com with aiplatform.googleapis.com.
Flagged by 4/10 agents

---

High (3)

2. .github/workflow/ should be .github/workflows/ (plural)
docs/guides/getting-started/org-mode.md:73,76
Two references use .github/workflow/fullsend.yaml (singular). GitHub Actions requires .github/workflows/ (plural), confirmed by internal/layers/enrollment.go:13. Users will look for a file in the wrong directory.
Flagged by 5/10 agents

3. Missing CLI and authentication prerequisites
docs/guides/getting-started/getting-inference.md (entire file)
Neither getting-inference.md nor configuring-github.md tells users to download the fullsend CLI, authenticate gcloud via ADC, or authenticate gh. The old installation.md listed all of these. First-time users won't know where to get the CLI.
Suggestion: Add a "Prerequisites" section to getting-inference.md listing: fullsend CLI download link, gcloud CLI with ADC auth, and gh CLI auth.
Flagged by 4/10 agents

4. Stale deep-link example in web/docs/README.md
web/docs/README.md:21
The example deep link references /docs/#/guides/getting-started/installation, but this file moved to docs/reference/installation.md.
Suggestion: Update to /docs/#/reference/installation or a new getting-started page.
Flagged by 5/10 agents

---

Medium (7)

5. Typo: "provison" → "provision" — docs/guides/getting-started/org-mode.md:13 (7/10 agents)

6. Grammar: "should posts" → "should post" — docs/guides/getting-started/configuring-github.md:43 (6/10 agents)

7. Grammar: "only support" → "only supports" — docs/guides/getting-started/getting-inference.md:6 (6/10 agents)

8. Grammar: "a OIDC" → "an OIDC" — docs/guides/getting-started/getting-inference.md:8 (4/10 agents)

9. Grammar: "there a few" → "there are a few" — docs/guides/getting-started/org-mode.md:11 (3/10 agents)

10. Grammar: "that enroll" → "that enrolls" — docs/guides/getting-started/org-mode.md:67 (3/10 agents)

11. No docs/reference/README.md for new directory — docs/reference/ (directory)
Two files moved here with no index. The docs SPA auto-generates sidebar, so two orphaned files appear without context. Nothing indicates these are "pending rework."
Suggestion: Add a minimal README or deprecation notes atop each moved file pointing to the new getting-started guides. (3/10 agents)

---

Low (5)

12. "Requisites" should be "Prerequisites" — configuring-github.md:6 — all other guides use "Prerequisites" (4/10 agents)

13. README getting-started entries lack description text — docs/guides/README.md:9-11 — other entries use [Title](path) — description pattern (5/10 agents)

14. Inconsistent flag syntax between guides — configuring-github.md uses --flag "val", org-mode.md uses --flag=val (1/10 agents)

15. ADR 0023 reference removed without update — docs/guides/README.md:4 — consider keeping or updating the ADR (4/10 agents)

16. Inconsistent heading capitalization — getting-inference.md:1 uses "For" (capitalized), configuring-github.md uses "for" (lowercase) (1/10 agents)

---

Info (3)

• --mint-url omission is intentional — PR feat(#2073): default --mint-url to the hosted public mint #2081 (merged June 9) added DefaultMintURL to main. Omitting the flag from new guides is correct.
• Test fixtures reference old paths — ~20 refs across web/docs/ test files. Tests are string transforms, not file lookups — they pass. Non-blocking cleanup for a follow-up.
• No redirect for moved pages — Old bookmarks to #/guides/getting-started/installation will 404.

---

Summary

Well-intentioned docs refactor with a clean getting-started flow. 1 critical issue (wrong GCP API will cause provisioning failures), 3 high issues (wrong directory path, missing prerequisites, stale SPA route), and 7 medium issues (grammar and completeness). The critical and high findings will cause real user-facing failures and should be fixed before merge.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:16 AM UTC · Completed 6:30 AM UTC
Commit: 3ab825a · View workflow run →

[waynesun09]

All critical, high, and medium findings from the 10-agent review have been addressed in the updated PR. Re-review with 5 agents confirmed all fixes are correct — links resolve, GCP APIs match source, CLI commands are accurate, no stale references in docs or source.

Remaining items are low-severity writing polish (heading titles, comma placement, phrasing) — non-blocking.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 2:27 PM UTC · Completed 2:33 PM UTC
Commit: 3ab825a · View workflow run →

[fullsend-ai-retro]

Retro: PR #2124 — docs(install): refactor of installation guides

Timeline: Human-authored PR by rh-hemartin refactoring installation docs (16 files, +274/-36). Opened 2026-06-10T14:56Z, merged 2026-06-11T14:24Z (~23.5 hours).

1. Automated review bot (fullsend-ai-review[bot]) ran and found structural issues (ADR deviation, test drift, naming) but missed a critical factual error: wrong GCP API name (iamcredentials.googleapis.com instead of aiplatform.googleapis.com).
2. Human reviewer (waynesun09) dispatched a 10-agent review squad (3x claude-coder, 3x claude-researcher, 2x gemini, 2x cursor) which caught the critical API error plus 16 other findings including grammar issues and path errors.
3. Author fixed all critical/high/medium findings (force-pushed), re-review confirmed fixes, PR approved and merged.

What went well:

• The human-dispatched multi-agent review squad was highly effective, catching a critical factual error that would have caused real provisioning failures.
• The automated review bot correctly identified structural concerns (ADR deviation, test drift).
• Total turnaround was reasonable for a docs refactor requiring substantive review.

What could go better:

• The automated review bot's correctness sub-agent has instructions to verify "API and library behavior claims" but failed to catch the wrong GCP API. The docs-currency sub-agent only checks for code-induced staleness, not factual accuracy of new content.
• This gap is closely related to existing issues: #1480 (shallow feedback on doc PRs), #1542 (validate CLI workflows against code). One new proposal below addresses the specific cross-referencing gap not covered by those issues.
• Force-pushing obscured the review-fix cycle (only 1 commit visible despite fixes applied). Related to #1676 (detect approach regressions across revisions) — no new proposal needed.

Proposals filed

• Review agent: cross-reference external identifiers in docs against codebase (in fullsend-ai/fullsend)