docs: deployment requirements and validated scale

Andrew Dunnrequested to merge
docs/requirements-and-scale into main

What

Adds the deployment-model and validated-scale facts a maturity audit flagged as missing: who runs manifold, and how far scale has been validated. Enrichment lands on two existing pages, since both facts already had a partial home there.

getting-started/deploy.astro: new "Who runs this" section between Prerequisites and Step 1. States the customer runs manifold inside their own network against their own instance (no database access, no agent, nothing leaves the network), the rendered dashboard is a static artifact the customer chooses to share, and the customer's own GitLab administrator holds the admin Personal Access Token (PAT) as a masked CI/CD variable. A vendor Customer Success Manager (CSM) sends the pipeline file and instructions and never sees the token.

guides/large-instances.astro: the runtime table was labeled "illustrative estimates, not measured benchmarks... unsourced back-of-envelope numbers". I replaced the 1,000-user row with the measured June 2026 lab benchmark and marked the larger rows as linear extrapolations from that single point. Added a "before you run it on a large instance" checklist, and documented the collector's rate-limit handling, connection-pool tuning, and watermark-based incremental collection in the existing tuning list.

guides/index.astro: one-line blurb update to match.

The admin pre-check and non-admin-token behavior were already accurate on reference/configuration.astro and this page's own Prerequisites section, so those stay as they were.

Why

Verified against code before writing:

  • Admin PAT requirement and non-admin silent undercount. internal/collector/orchestrator.go's admin pre-check calls CheckAdmin in internal/collector/roster.go, which fetches GET /api/v4/user and errors when !u.IsAdmin: a non-admin token gets HTTP 200 with truncated data, not a 403. cmd/manifold/collect.go wires --skip-admin-check to collector.Config.SkipAdminCheck.
  • 1,000 users, June 2026 lab run. collect 8.1 min, 7,147 API requests, 0 errors (26,800 events, 3,625 merge requests, 3,069 issues, 2,955 pipelines); analyze under 1 second. GitLab 19.1.1-ee Omnibus on Google Compute Engine, from the project's own lab record; the instance was torn down after the run.
  • Rate limits, connection pooling, incremental collection. internal/client/client.go retries on 429 and 5xx with backoff and throttles proactively once the remaining rate-limit budget drops below 10 percent (throttleThreshold). WithConcurrency sizes MaxIdleConnsPerHost to the worker count, landed 2026-06-28 in 487884f. Incremental collection reads a watermark and applies a 24-hour overlap (IncrementalOverlap in internal/collector/collector.go, internal/collector/watermark.go).

Test plan

  • cd site && npm ci && npm run build succeeds; matches the repo's build-docs CI job exactly.
  • Checked the rendered HTML output for both touched pages.
  • CHANGELOG.md and the security page's supported-versions table are unchanged.

Merge request reports