chore(docs): redesign homepage + merge Quick Start into Installation

[marcusrbrown]

Summary

Redesigns the docs homepage off the stock Starlight splash onto a custom, faithful three-flatland-style layout, merges the Quick Start page into Installation, and fixes the "unreleased" stats banner. Reviewed live throughout; this is the first round, with a follow-up sweep planned (banner/logo treatment).

Homepage redesign

• Custom hero, stat strip, and aligned feature grid carrying the existing OKLCH theme, replacing the stock splash + CardGrid stagger.
• Hero title scaled down to a restrained, editorial size.
• Feature cards are uniform height with a hover highlight (border + tint) and no movement.
• The redundant auto-generated h1 is hidden (kept in the DOM as the skip-link target).
• A tagline sits under "Systematic" in the header on desktop and hides gracefully on narrow screens.
• OCX is demoted from a headline feature to a single supporting line.
• All homepage CSS uses valid selectors. The prior :global() wrappers were invalid inside an MDX <style> tag and were silently dropped, which is why the auto-h1 stayed visible and an empty gap sat above the hero.

Getting started

• Quick Start is merged into a single Installation page (install steps + first-workflow walkthrough). The old /getting-started/quick-start/ URL redirects to it.

Fixes

• Stats banner "unreleased": the docs deploy used a shallow checkout, so generate-stats.ts could not resolve the version via git describe --tags. Now uses fetch-depth: 0.
• Biome lint: excludes .astro source files, which Biome cannot analyze correctly (it parses only frontmatter, not the template), so identifiers used only in markup are no longer flagged as unused. The previous !**/.astro ignore matched a directory, not the files.

Testing

• bun run typecheck clean
• bun run lint clean (no errors)
• bun scripts/content-integrity.ts clean
• bun run --cwd docs build builds 111 pages
• bun test tests/unit 927 pass / 0 fail
• Live checks: header title links home, tagline desktop-only, hero sits flush under the header (0px gap), quick-start redirect resolves

Release impact

chore(docs) / ci(docs) / build(biome) only. No published-package surface change, so no version bump. The docs site picks up the redesign on the next release or a manual deploy.

Follow-up (next round)

Re-add or transform the banner into a proper logo (the three connected dots), plus a broader consistency sweep across the other pages.

[fro-bot]

Verdict: PASS

Clean, well-scoped docs redesign. Changes are confined to the docs workspace plus two low-risk tooling tweaks (biome.json, docs.yaml). No plugin API surface (config/tool/system.transform hooks), system-prompt injection, or skill-loading code is touched, so the published-package risk is effectively zero. The three fixes are correctly reasoned and the redirect/links resolve to existing pages (guides/philosophy, guides/with-without-systematic, guides/main-loop, reference/configuration).

The items below are all non-blocking — none warrant holding the merge for a docs-only PR from a collaborator.

Blocking issues

None

Non-blocking concerns

• docs/src/components/FeatureCard.astro:16 — icon as any. This violates the repo's no-any convention. Since this PR also excludes *.astro from Biome (biome.json:9), this cast is now invisible to lint and won't be flagged in future. Prefer typing against Starlight's icon name union, e.g. import type { StarlightIcon } from '@astrojs/starlight/types' and icon as StarlightIcon, or accept the Icon component's own name prop type. Minor, but worth fixing before the convention erodes in .astro files now that they're lint-exempt.

• docs/src/content/docs/index.mdx — duplicated CSS in the <style> block. .content-panel:first-of-type { padding: 0 } and .content-panel:nth-of-type(2) { padding-top: 0 } are each declared twice, and the comment /* Make sure children stretch */ is repeated back-to-back above .feature-grid > article. Harmless but looks like a copy/paste leftover; collapsing them keeps the override block readable.

• StatsBanner — dropped components stat vs. generate-stats.ts. The banner no longer renders stats.components, but docs/scripts/generate-stats.ts still computes and writes components into stats.json (and the OCX registry count is the only consumer that's now gone). Not a bug — the generated field is simply unused — but if OCX-count display isn't coming back, consider trimming the generator + Stats type in a follow-up to avoid a dangling field. The PR notes a follow-up banner/logo sweep, so this can ride along.

• Reliance on Starlight internal DOM in index.mdx. The hero-gap fix hangs CSS off .content-panel:nth-of-type(2) and h1#_top, which are Starlight-internal structures, not public API. This is the pragmatic fix and the PR description explains why the prior :global() approach failed, but flag it as a known Starlight-upgrade fragility point — a future Starlight version could rename these and silently reintroduce the gap. Low likelihood, easy to re-spot visually.

Missing tests

None required. This is presentational MDX/CSS plus CI config; the existing build (docs build → 111 pages) and content-integrity checks are the appropriate gates, and the description confirms they pass. No unit-testable logic was added.

Risk assessment: LOW

• Regression likelihood: LOW. No runtime plugin code changed. StatsBanner now calls .toString() on stats.skills/stats.agents; both are numbers in the generated stats.json, so this is safe. Worst realistic regression is a visual gap if Starlight internals shift.
• Security exposure: NONE. No prompt injection, skill-loading, or input-handling paths touched. The hand-rolled hero anchors/SVGs are static markup with no interpolated user data.
• Blast radius: contained to the docs site. fetch-depth: 0 only affects the docs deploy job's checkout (more history, slightly slower clone — acceptable). The biome.json glob fix (!**/.astro matched a dir, !**/*.astro matches files) is correct and only relaxes linting on template files Biome can't parse anyway; it does not loosen rules on real .ts source.

---

Run Summary

Field	Value
Event	pull_request
Repository	marcusrbrown/systematic
Run ID	26672332721
Cache	hit
Session	ses_1893ab695ffelHwLpc99ZnbbtG