v0.9.0 — launch readiness: docs front door, preview governance, preview access, opt-in dashboard #239

Problem

sprout is public today (AGPL-3.0, docs site and marketing page live, v0.8.0 shipped the agent-first docs and the GitHub reusable workflow) and a stranger still cannot get comfortable with it quickly. Four gaps:

1. The docs are structured badly. Every published page renders as a bare body with no navigation, the generated docs index is a flat list, and the marketing page links straight into leaf pages. There is no sidebar, no reading order, and no index a human can browse. The corpus itself is fine — the shell around it is the problem.
2. Nothing bounds a preview. There is no TTL, no idle teardown, no cap per repo or per gateway, and no connection budget anywhere in the codebase. Measured on our own instance: ~8 previews holding ~12 idle pool connections each exhausts a 100-slot Postgres with zero traffic (SQLSTATE 53300), and the relief was raising max_connections — headroom, not a bound.
3. A preview can only be shared by handing out a public hostname. No per-preview credential, no revocation, no scoping. The earlier external forward-auth attempt in front of previews was abandoned: there is no Cloudflare-free path from the preview edge to that service, and every Cloudflare path rewrites X-Forwarded-Host, so the gate authorised everything. A usable gate has to live in the gateway, which already sits on the preview network.
4. There is no view. What is running right now is sprout list in a terminal. A launch audience judges this kind of tool by a screenshot, and an unauthenticated page listing previews would leak every preview URL — so the view has to be opt-in and read-only.

Decision

• Rejected: a local one-command stack plus a repo-wiring generator. sprout is infrastructure an operator runs for adopting repositories, not a local development tool; "run it on your laptop in five minutes" is the wrong use case and was dropped (sprout up + sprout init: five-minute path to a first preview on your own box #240 records the reasoning). The friction worth removing is understanding what sprout is and how a preview is wired, which is a documentation problem.
• v0.9.0 therefore invests in the docs front door and navigation, bounds previews, makes previews shareable, and adds an opt-in read-only view.
• Every new capability is opt-in: no adopter has to change existing wiring, and no new always-on surface is introduced.

Children

• Docs site: grouped sidebar navigation, a browsable docs index, and a single Docs link from the marketing page #244 — Docs site: grouped sidebar navigation, a browsable docs index, and the marketing page down to two entries (Docs + the onboarding prompt)
• Preview governance: TTL, idle teardown, caps and a connection budget #241 — Preview governance: TTL, idle teardown, caps and a connection budget
• Preview access: per-preview shareable link and optional basic-auth gate, gateway-native #242 — Preview access: per-preview shareable link and optional basic-auth gate, gateway-native
• Opt-in read-only dashboard for live previews #243 — Opt-in read-only dashboard for live previews
• Preview TLS: opt-in wildcard mode — one certificate per preview suffix instead of per-PR issuance #276 — Preview TLS: opt-in wildcard mode (one certificate per preview suffix, zero per-PR ACME orders) — added 2026-10-04

All four are independent (no cross-blocking edges) and are the milestone's frontier.

Acceptance criteria

• A visitor moves marketing → Docs → any page in one click each, sees the same sidebar on every page, and can reach the whole published set from the docs index (screenshots at desktop and 375 px on Docs site: grouped sidebar navigation, a browsable docs index, and a single Docs link from the marketing page #244).
• A preview cannot outlive its configured lifetime or the gateway's cap, and the per-preview connection cost is documented with its arithmetic and enforced (evidence on Preview governance: TTL, idle teardown, caps and a connection budget #241).
• A preview can be handed to someone outside the team through a revocable, per-preview credential; with the feature off, labels, URLs and deploy behaviour are identical to v0.8.0 (Preview access: per-preview shareable link and optional basic-auth gate, gateway-native #242).
• A read-only board of live previews exists when the operator enables it and does not exist at all when they do not (Opt-in read-only dashboard for live previews #243).
• No webhook receiver, no per-preview provisioning of shared services, no adopter shell scripts: ADR-0004 and the shared-service decision stand.
• Release prep as usual: version pins bumped (package.json, Dockerfile, docs, examples, deploy/coolify), the marketing page and quickstart reflect what changed, and an existing adopter upgrades without editing .sprout.yaml.

Out of scope (post-launch, do not smuggle in)

Prod-data snapshot and column masking for seeds, preview evidence (screenshots/console capture in the PR note), forge parity beyond GitHub/GitLab, a remote/Kubernetes app-deployment backend, a metrics exporter, per-user accounts and RBAC, and any local-development stack.

Scope guard

• Public-tracker hygiene: no internal hostnames, paths, resource names or infrastructure detail in bodies, docs, screenshots or example output — use example.com placeholders and generic descriptions.
• Every child must leave the default behaviour of an existing deployment unchanged; new behaviour is enabled by manifest key, CLI flag or gateway env, never by upgrading.
• Operator/infrastructure work (Coolify apps, DNS, certificates, host firewalls) is not product work and stays out of this repo.