Establish an exact public documentation allowlist

.ai/rules/astro-starlight-site.md

@@ -0,0 +1,65 @@
+---
+applyTo: "web/**/*.{js,mjs,ts,astro,json,md,mdx}"
+paths:
+  - "web/**"
+---
+
+# Astro/Starlight exact public-surface rules
+
+The deployed cratis.io site is an exact projection, not a broad documentation
+crawl.
+
+## Publication source
+
+- `web/public-surface.json` owns the admitted route, source repository/path,
+  reviewed revision, SHA-256, claim IDs, sitemap flag, and exact static files.
+- `web/scripts/sync-public-content.mjs` validates and materializes only that
+  manifest. Unknown routes, source/hash drift, Draft content, CLM-010 matrix
+  wording, symlink escapes, search/machine output, and policy differences fail.
+- `web/src/content/docs/`, `web/src/generated/`, and `web/.public-approved/` are
+  disposable outputs. Never edit or commit them.
+- Site-owned source lives in `web/src/public-pages/`; product source stays in the
+  owning product repository.
+- `npm run sync:authoring` is broad, nondeployable authoring only.
+
+## Native Markdown and MDX contract
+
+Exact-production source is copied byte-for-byte. It does not receive the legacy
+DocFX conversion pipeline.
+
+Every admitted page must therefore:
+
+- use Starlight frontmatter with at least `title` and a bounded `description`;
+- omit a body H1 because Starlight renders the frontmatter title;
+- start body sections at H2;
+- use native Starlight aside syntax and root-relative trailing-slash links;
+- use `.mdx` when importing Starlight or custom components;
+- avoid DocFX alerts, xrefs, includes, `.md` URL suffixes, and relative product
+  assets; and
+- keep every component-emitted link inside the manifest route set.
+
+## Product landing pages
+
+Product overviews use the tour pattern where it helps readers:
+
+- `TopicHero` for exact product identity and one bounded reader job;
+- Starlight `CardGrid`, `Card`, `LinkCard`, and `Steps`;
+- `SimpleCard` only with page-supplied wording and admitted links;
+- `FullStackTabs` only for source-verified paired examples.
+
+Do not use `RotatingHero`, `StackJourney`, `StackDiagram`, or Storybook embeds in
+the current eight-route manifest. They own excluded claims/routes/artifacts.
+
+## Build and deployment
+
+- `npm ci && npm run check` is the authoritative local and CI gate.
+- Astro/Starlight is the authoritative MDX parser and component resolver.
+- Rendered-link validation catches links emitted from MDX components.
+- Pagefind, llms files, page actions, raw Markdown mirrors, Storybooks, and API
+  sites remain disabled until separately admitted.
+- Pull requests validate reviewed product revisions with read-only credentials.
+- Main deployment checks product `main` bytes and fails on hash drift.
+- Pages/OIDC permissions exist only in the main-only deploy job.
+
+Never weaken a route, claim, hash, artifact, or deployment check merely to make a
+build green.

.ai/rules/documentation-rendering-and-qa.md

@@ -0,0 +1,60 @@
+---
+applyTo: "web/**/*.{astro,css,md,mdx,js,mjs,ts}"
+paths:
+  - "web/**"
+---
+
+# Documentation rendering and visual QA
+
+A successful build proves syntax and route integrity, not a professional reader
+experience. Review rendered output for every changed admitted route.
+
+## Required rendered checks
+
+1. Run the exact production build:
+
+   ```bash
+   cd web
+   npm ci
+   npm run check
+   ```
+
+2. Serve the built site with `npm run preview`.
+3. Capture every admitted route in light and dark mode.
+4. Capture `/`, each product landing, and `/404.html` at a mobile width.
+5. Verify keyboard traversal, visible focus, heading order, descriptive links,
+   table/code overflow, diagram readability, and no image-dependent meaning.
+6. Verify reduced-motion mode and no carousel/ambient motion requirement.
+7. Check first load for font/image/layout shift.
+
+Use `web/scripts/screenshot.mjs` for reproducible screenshots when available.
+Screenshots are local review evidence and are not committed unless their exact
+public asset/provenance path is separately admitted.
+
+## Preserve current rendering safeguards
+
+- Keep the custom `Head.astro` font preload and `font-display: optional` behavior.
+- Keep Mermaid build-time rendering and `autoTheme: false`; light/dark colors are
+  handled by CSS variables.
+- Keep the theme-adaptive Cratis marks and an empty alt only when the mark is
+  decorative and equivalent text is present.
+- Keep product pages useful without JavaScript.
+
+## MDX component review
+
+- `TopicHero` and `SimpleCard` are render-only and safe when all text/links come
+  from the page.
+- Starlight `Card`, `CardGrid`, `LinkCard`, `Steps`, `Tabs`, and `Aside` are
+  preferred for native behavior.
+- Validate icon names during Astro build.
+- Inspect component output in final HTML; source-only Markdown link scans are not
+  sufficient.
+- Do not hide claim text, links, or product relationships inside imported
+  components that are not included in the manifest review.
+
+## Failure handling
+
+Block the candidate on broken layout, unreadable contrast, inaccessible focus,
+mobile overflow, missing content without JavaScript, diagram failure, unexpected
+route/link output, or material layout shift. Fix the source or component; do not
+waive the public-surface gate.