docs: add onboarding how-to guide for new organizations

[rh-hemartin]

Summary

• Adds docs/onboarding.md with step-by-step instructions for installing fullsend in a new GitHub org
• Covers prerequisites, GCP service account setup, running the installer, merging enrollment PRs, and testing the pipeline
• Documents gotchas discovered during manual testing (dispatch token permissions, partial install recovery)

Closes #327

Test plan

• Review doc accuracy against current fullsend admin install flow
• Verify gcloud commands produce a valid sa-key.json

🤖 Generated with Claude Code

[github-actions]

Site preview

Preview: https://928113f9-site.fullsend-ai.workers.dev

Commit: 24de93e3e461bee9fd4fbf5a73a5fdf98d82b563

[ralphbean]

Hey Hector — I've been working on a documentation structure in #332 (ADR 0023) that splits user docs into docs/guides/admin/ (for org administrators) and docs/guides/user/ (for developers). Your onboarding guide is a great fit for the admin section.

Could you move docs/onboarding.md to docs/guides/admin/installation.md? That way both PRs land cleanly in the same structure. #332 already links to that path and has the index page set up.

[ralphbean]

Thanks for writing this — the guide is clear and well-structured. A few changes requested plus one note for later.

[rh-hemartin]

/review

[fullsend-ai-review]

Review: #328

Head SHA: 24de93e
Timestamp: 2026-04-24T00:00:00Z
Outcome: comment-only

Summary

This is a well-structured documentation PR that adds an admin installation guide at docs/guides/admin/installation.md. The guide follows the project's documentation structure (ADR 0023), uses environment variables for all sensitive values as required by CLAUDE.md, and documents real gotchas (dispatch token permissions, partial install recovery). The CLI flags in the example commands match the actual Go source in internal/cli/admin.go. No security concerns — no secrets, no code changes, no injection patterns detected. A few minor observations are noted below.

Findings

Medium / Low / Info

• [correctness] docs/guides/admin/installation.md:28 — Commented-out gh repo create line in a code block may confuse readers. It is unclear whether this is an optional step the reader should consider running or a leftover. Consider either removing it or adding a brief comment explaining when a reader would need it (e.g., "uncomment if the repo doesn't exist yet").
  Remediation: Replace # gh repo create ... with a prose note above the code block, or add an explicit inline comment like # Optional: create the repo if it doesn't exist yet.

• [intent-alignment] — Issue #327 specifically mentions documenting the gotcha that "target repos must have at least one commit before enrollment (#326)", but this guide does not include that information. This was an explicit request in the issue body.
  Remediation: Add a note (e.g., in a "Gotchas" section or as a callout in the enrollment step) that target repos must contain at least one commit before enrollment.

• [style] docs/guides/admin/installation.md:1 — The document title is "How to onboard a new organization" but the filename is installation.md and the guides README refers to it as "Installing fullsend". Minor naming inconsistency across the three references.
  Remediation: Align the title with the filename — e.g., "Installing fullsend in a new organization" — or rename the file to match the current title.

• [correctness] — The PR body states the file path as docs/onboarding.md, but the actual file is docs/guides/admin/installation.md. This is cosmetic (the correct file is committed) but the description is inaccurate.

Footer

Outcome: comment-only
This review applies to SHA 24de93e3e461bee9fd4fbf5a73a5fdf98d82b563. Any push to the PR head clears this review and requires a new evaluation.

[ralphbean]

🥳