docs: self-hosting deep dive — fix pitfalls and add missing guidance

[simple-agent-manager]

Summary

Deep dive into the self-hosting experience. Identified and fixed ~12 issues that would trip up a potential self-hoster.

What changed

Bug fixes:

• Go version requirement: docs said 1.22+ but go.mod requires 1.25+ — build would fail
• your-org placeholder URLs → actual repo URL (raphaeltm/simple-agent-manager)
• VITE_BASE_DOMAIN in web .env.example defaulted to simple-agent-manager.org — misleading for self-hosters
• Manual wrangler.toml section was missing: observability D1 database, all 9 DO bindings, Workers AI binding, 3 of 4 cron triggers, and DO migration tags — manual deployers would get runtime errors
• CORS example referenced simple-agent-manager.org instead of example.com
• Cost estimation was missing Workers AI and Durable Objects
• VITE_PUBLIC_WEBSITE_URL was never passed through the deploy workflow — self-hosters' login page would link to simple-agent-manager.org

New documentation:

• "Common Pitfalls" section — top 9 mistakes self-hosters make (GH_ vs GITHUB_ naming, GitHub App OAuth checkbox, missing 2nd D1 database, Go version, first-user-is-superadmin, API token permissions, DNS prerequisite, workers.dev subdomain, R2 dual-token requirement)
• "Post-Deployment Setup" section — first-user/superadmin flow, REQUIRE_APPROVAL mode, agent types + credential requirements per agent, public website URL config, smoke test tokens
• New troubleshooting entry for Pages custom domain verification timeout
• Note about enabling Actions on forks (disabled by default)

Audit findings (no code changes needed)

The codebase is well-designed for self-hosting at the infrastructure level:

• All domains derived from BASE_DOMAIN — no hardcoded production domains in runtime code
• All resource names derived from domain hash or RESOURCE_PREFIX
• All external service URLs (OpenAI, Google, Cloudflare) are configurable via env vars with sensible defaults
• Pulumi handles all infrastructure provisioning idempotently
• configure-secrets.sh correctly maps GH_* → GITHUB_* secrets

The only hardcoded simple-agent-manager.org in runtime code was the VITE_PUBLIC_WEBSITE_URL fallback in Landing.tsx, which is now overridable via the deploy workflow.

Test plan

• Review the self-hosting guide for completeness and clarity
• Verify the manual wrangler.toml example matches the actual top-level config
• Confirm the deploy workflow change (VITE_PUBLIC_WEBSITE_URL) doesn't break existing deploys (empty string = falls back to default)

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[simple-agent-manager]

Triage Note (2026-04-30)

This PR is still in draft status. The self-hosting documentation improvements here are valuable (Common Pitfalls section, Post-Deployment Setup, manual wrangler.toml fixes).

Current state:

• Mergeable (no conflicts)
• All CI checks pass except Preflight Evidence (missing block in PR body)
• Draft — not marked as ready for review

Action: Leaving as draft per triage policy. When ready to merge, the PR will need:

1. Mark as ready for review
2. Add preflight evidence block to PR body
3. Re-run CI to confirm all checks pass
4. Verify the deploy workflow change (VITE_PUBLIC_WEBSITE_URL) doesn't break existing deploys

No changes made. @raphaeltm — let me know if you'd like this finalized and merged.