Documentation site

Context

Developer docs are the product's front door for integrators. Serve them with the framework's docs tooling (bunpress via @stacksjs/docs, buddy dev docs / buddy build docs) from this repo's docs/.

Scope

• Quickstart: account -> project -> first event via curl -> first auto-report, in under five minutes, every command copy-pasteable and tested.
• Ingestion reference: publish docs/ingest.md (#6) - wire contract, limits, error semantics, idempotency guidance.
• Event taxonomy reference: docs/events.md (#6) rendered as browsable reference - every reserved event name, required/optional properties, which auto-report templates (#14) each feeds.
• Integration guides: Stacks package (#7) and Laravel package (#8) - install, config, custom observer registration, sampling, self-test ("send a test event") instructions.
• Report builder guide: blocks, measures, dimensions, filters, comparisons - written from the shared validation schema (#9) so terms match the UI exactly.
• Sharing/embeds guide (#16) and schedules/exports guide (#15).
• Limits + billing doc: publish docs/limits.md (#18) including the overage policy, verbatim from the enforcement config.
• Self-hosting guide: run ReportsHQ yourself (SQLite/Postgres, STRIPE_* unset = everything free, ingest hygiene) - loghq's self-hostable posture applies here too.
• API reference: buddy generate:openapi output published; bearer-auth examples for the read/query APIs (#6, #10).
• Docs nav/sidebar structured per the above; docs share the #3 token family (bunpress theme configured accordingly, within what config/docs.ts supports).

Acceptance

• buddy build docs succeeds in CI; every code sample is executed by a test or script (no rotting samples); quickstart verified end-to-end against a fresh dev instance.

Depends on #6, #7, #8, #12, #15, #16, #18. Part of #1 (M7 Launch). Ground rules: see #1.

Documentation site is in. buddy build docs succeeds and produces 13 pages.

The starting point was that the docs site was still the framework scaffold's: the homepage advertised Stacks.js, the sidebar was a bootcamp for building Stacks applications, and the marketing site links straight into it. Anyone following "Documentation" from reportshq.org landed in another product's manual.

Written: quickstart, report builder, sharing and embeds, schedules and exports, self-hosting, API. Plus the two SDK guides (Stacks, Laravel) that went in with #19. The existing ingest, events, limits and design-brief pages are kept.

Removed the framework's own docs from docs/ (guide, bootcamp, packages, basics, features, testing, project, marketing, diagrams, release notes, contribution guide). All of it describes Stacks, not ReportsHQ, and it remains in git history and upstream.

The builder guide takes its vocabulary from app/Reports/schema.ts, and tests/feature/docs-site.test.ts asserts it lists exactly the measures, operators, grains and block kinds the schema accepts, so a term cannot appear in the product without appearing in the guide. The same suite checks the sidebar reaches every page and points at no missing one, that every internal link in the prose resolves, and that every JSON sample parses. That last check found an elided response body in ingest.md that could not be copied and pasted, now expanded.

Two corrections worth flagging.

The API page's first draft claimed there was no bearer-authenticated read API. That was wrong: app/Middleware/Auth.ts does accept bearer tokens, so ingest.md was accurate and the draft was not. The page now documents what exists, along with the real gap: there is no way to mint a standalone API token, so the only token that works is the one behind the session cookie, and the read endpoints should be treated as internal until per-project revocable tokens exist. That is worth its own issue.

The scope asks for buddy generate:openapi output published as the API reference. I did not do that, and would rather not: the generated spec has 688 paths, nearly all of them routes the framework mounts by default rather than part of this product, and several that are not mounted at all. A reader cannot tell which is which, and a reference that cannot be trusted is worse than none. The API page says so explicitly and states what a real reference would need first. Happy to publish it anyway if you would rather.

Not done: the quickstart is verified by tests against the documented contract, but not yet executed end to end against a fresh dev instance in CI. That belongs with #22.