Rework docs prose, onboarding, team guidance, and QA

[alexanderaidun-a8c]

What changed

The current docs lead new readers through the CLI, bury team and browser paths, and repeat the same page-promise opening across much of the authored corpus. This change makes those paths visible and states key facts earlier.

• Give new readers a route that fits them. The homepage and Quickstart now surface dashboard Drop before CLI installation: drag a folder, .zip, or index.html to publish without an install or account. The homepage also links directly to the glossary and Teams. Quickstart points collaborators to invitations and team access defaults. The domain setup steps separate CLI and dashboard instructions into tabs instead of mixing them in one paragraph.
• Explain the product model at the point of need. A new 12-term glossary defines Space, version, live, Drop, grant, Team, Zero, and other recurring terms and is linked from the homepage and Reference navigation. Teams now explains shared ownership, member publishing and rollback, role boundaries, and default access before the management instructions. Database names the Zero setup prerequisite before teaching queries. Publishing guidance puts the prebuilt-versus-source-build choice, Git connection terminology, and repository requirement for WordPress data sources earlier. Troubleshooting starts with the Space Overview diagnostic path. The MCP server reference points readers who want one-click setup back to the Claude guides; anonymous claiming links to agent permissions.
• Revise the authored corpus, not the generated contracts. Across 78 existing authored MDX pages in Docs, Agents, CLI, API, and Platforms, 65 opening paragraphs changed to state a useful fact or action instead of promising what a page will cover. The body pass split or trimmed long chained sentences across 62 pages, followed by checks for repeated openings and duplicated description/body text. Examples now lead with the rollback mechanism, cron configuration and publish timing, variable precedence, cache refresh, and what traffic stats count. The generated CLI, API, errors, and setup snapshot is unchanged.
• Make the writing standard reviewable. STYLE_GUIDE.md explains the existing Vale rules, Spacefast voice, concision, and worked before/after examples. AGENTS.md now points contributors to it and lists the docs test gate.
• Add QA and regression coverage. The branch adds reports for reader paths, command accuracy, agent answers, and writing, plus a repeatable writing-audit script. Twelve new checks read the built docs for the changed entry paths and first-page facts. test:docs runs these with the 14 existing corpus, LLM-index, and audit tests through Node's test runner; CI now runs that suite after the build. Four ambiguous or stale agent-eval questions were corrected.

Review notes

This PR changes authored docs, contributor guidance, tests, and CI, but no product implementation or generated-reference snapshot in this repository. Please review the entry paths, the new team and glossary explanations, and whether the revised leads preserve the detail readers need below them. Some leads move a key fact from a later paragraph to the top: anonymous key loss, default hostname permanence, MCP delegation, and Functions runtime detection are examples. Two pre-existing gaps remain for separate fixes: no verified support contact path, and inconsistent API-key preset guidance between the authored page and producer-owned CLI example.

Verification

With Bun 1.3.11 and Node 24, generated-snapshot and command-example verification, type check, strict link validation, production build, 26 docs tests, composed-site audit, route verification, public-safety, Vale, and git diff --check pass. The built site contains 1,531 pages; no generated snapshot was edited. The Website dependency declarations are unchanged.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[indent]

Issues

All clear! No issues remaining. 🎉

10 issues already resolved

• The opener says crawler traffic is "deliberately left out" of a Space's stats, but the page body says requests counts every HTTP request including bots and unique visitors ignore the crawler and status filters. Only views filters crawlers. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The opener claims every file in a published Space gets one of two Cache-Control headers. The same page lists private, no-store and no-store responses (protected Spaces, share-link URLs, non-GET requests, conditional routing rules) and verbatim _headers overrides. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The opener says that when two rules overlap the first match always wins, and lists response headers in the same sentence. The page says header blocks accumulate, _headers wins over a config rule for the same header, and rewrite/404 rules skip themselves when a real file exists. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The opener says there is "exactly one copy" of the key and no way to get it back if the publish folder is lost. The CLI also prints the key in the claim link, --show-secret prints it, and the API returns it at creation and on rotation. A user who kept the claim link is told the Space is unrecoverable. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The opener says "Every account gets Zero for free", but usage.mdx bills Zero CPU per active CPU-second and Zero invocations past 1 million, with fixed Free allowances. The old body only said Zero is on for every account, which is about availability, not price. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The opener says "Your client never actually holds a Spacefast API token", but the local stdio runtime on the same page uses your CLI login or a SPACEFAST_TOKEN bearer token. The Hosted section's remaining sentence ("That delegation token lives five minutes…") now refers back to a sentence several sections above. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The quickstart, homepage (content/index.mdx:46) and Teams page tell readers to invite members, but billing.mdx says Free and Go allow one editor and usage.mdx says the member quota blocks on Free with 409 team_member_quota_exceeded. The quickstart also says to "claim your Space to a team", which only applies to anonymous publishes. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The note says to declare kind: "zero" in sf.jsonc, but zero-runtime.mdx says the runtime block also needs a server entry. A reader who adds only kind gets a failed publish. (fixed by commit c5dcff2)
  _{Found by Indent Review Agent}
• The opener says API keys and agent credentials cannot manage invitations or membership, but the rest of the page (~lines 196-335) presents sf teams invitations add/resend/cancel and sf teams members rm as working commands with success output and no 403 caveat. content/(concepts)/teams.mdx:74 also still recommends the CLI invitation command. (fixed by commit b43b34c)
  _{Found by Indent Review Agent}
• The pagination eval in evals.yaml asks for the default and maximum page sizes on list endpoints and expects "default 20", but the rewritten /api/pagination says defaults vary by endpoint (storage objects default to 50) and some lists don't paginate. (fixed by commit b43b34c)
  _{Found by Indent Review Agent}

CI Checks

All required CI checks passed on b43b34c.

Review agents

Select any unchecked box below to run or rerun that agent.

Passed (1)

• Indent Review Agent · Both open findings are fixed in b43b34c; no dangling references or new issues found.

Full results

Indent Review Agent

• Summary: Both open findings are fixed in b43b34c; no dangling references or new issues found.
• Last ran on commit: b43b34cc
• Latest result

  {
    "summary": "Both open findings are fixed in b43b34cc; no dangling references or new issues found.",
    "findings": []
  }

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 04a06fbc-9265-4a82-8d0d-7adbcd04208c

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[f]

🚀