docs: VitePress docs site + Azure SWA deploy workflow

[mohnjiles]

What

VitePress static site scaffold for docs.lykos.ai, built from the docs/ tree (landed via #1685) with no content restructuring:

• All URLs served under /stability-matrix/ from day one — per team discussion, so the planned move to a multi-product docs repo (SM + Chat + Bench) never breaks hotlinks or SEO. The bare site root 302s to /stability-matrix/ (replaced by a product landing page at migration). README.md serves as the section index via rewrites.
• Built-in local search (Ctrl+K), "Edit this page on GitHub" links, sitemap.xml, and last-updated footers on every page. Dead-link checking stays ON so a future PR that breaks a relative link fails the build.
• A markdown hook normalizes content links targeting README (e.g. ./../README) to directory-index form. VitePress emits relative hrefs verbatim, so those links pointed at a README.html that doesn't exist in the built output — a latent 404 that the dev server masked and the dead-link checker (which resolves in source space) never flagged. The content itself is correct on GitHub and in the in-app viewer (feat: in-app documentation viewer #1677); the mismatch is purely this site's README→index rewrite, so the fix lives in the site shell rather than the content.
• docs/public/staticwebapp.config.json — root redirect + Azure SWA serves the VitePress 404 page instead of its default.
• Site tooling (package.json, lockfile, .gitignore) contained inside docs/ so the repo root stays .NET-only.
• .github/workflows/docs-site.yml — on docs/** pushes to main: npm ci + vitepress build + deploy to Azure Static Web Apps (AZURE_STATIC_WEB_APPS_API_TOKEN_DOCS secret). PRs touching docs/** get a build-check job only (no deploy). The deploy job checks out full history so last-updated dates are accurate.

Verified locally with the exact CI sequence (npm ci + vitepress build .): clean build, zero dead links, and browser-tested — search, edit links, section index at /stability-matrix/, and the README breadcrumbs all confirmed working against the built output.

Local preview: cd docs && npm install && npm run docs:dev (then open /stability-matrix/; the root redirect only exists on Azure)

Remaining runbook

1. Merge Feat: Initial Documentation #1685 (docs content) ✅ merged; main merged back into this branch, PR diff is now scaffold-only (6 files).
2. Apply infra — lykos-infra#23 (envs/docs-prod): terraform apply creates the Azure SWA (Free tier), the docs.lykos.ai Cloudflare CNAME (unproxied), and auto-wires the SWA deploy token into this repo's AZURE_STATIC_WEB_APPS_API_TOKEN_DOCS secret via ci.tf.
3. Confirm the PR build check is green, undraft, and merge this PR.
4. First deploy fires on the merge — watch the "Docs Site" workflow run, then check the SWA default hostname and https://docs.lykos.ai (custom-domain validation can lag DNS by a few minutes).
5. Smoke test: / 302s to /stability-matrix/, home page renders, Ctrl+K search finds "rocm", a deep page (e.g. /stability-matrix/advanced/hardware-support), a section-overview "back to home" breadcrumb, a garbage URL shows the VitePress 404, /sitemap.xml resolves.
6. Undraft feat: in-app documentation viewer #1677 (in-app docs viewer) — docs/ is on main now, so its "docs not available yet" state is already gone; it just needs the GUI smoke test.

Architecture note (2026-07-05, updated 2026-07-13)

Per team discussion: this site shell (.vitepress/ config + deploy workflow) is expected to migrate to a separate public multi-product docs repo (SM + Chat + Bench sections, path-prefixed: /stability-matrix/, /chat/, /crabbench/) once a second product has docs to publish — tracked on the roadmap board. With URLs prefixed from day one, that migration is a pure code move: no redirects, no SEO impact, no broken hotlinks. SM markdown content stays in this repo either way (community contributions + docs-with-code PRs); the docs repo will pull it at build time. At migration, the AZURE_STATIC_WEB_APPS_API_TOKEN_DOCS secret moves to the docs repo (one-variable change in lykos-infra envs/docs-prod), leaving no Azure secrets in this repo. Docs-only CI skip for the required build check is being handled separately.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request establishes a comprehensive documentation suite for Stability Matrix using Vitepress, adding detailed guides on installation, package management, inference, advanced configuration, and terminology. The review feedback focuses on polishing the documentation by addressing minor typographical errors, grammatical slips, and formatting inconsistencies across several markdown files.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.