test: harden starter experience quality contract

README.md

@@ -16,6 +16,27 @@ corepack pnpm dev
 Runtime-public settings live in `public/config.json` and are validated before
 the product tree mounts. Client secrets are forbidden.
 
+## Included starter experience
+
+The default build mounts a domain-neutral application shell with a header,
+responsive sidebar, route focus management, session integration status, and a
+persistent `system` / `light` / `dark` theme selector.
+
+| Route | Purpose |
+| --- | --- |
+| `/` | implementation readiness and starter links |
+| `/examples/ui` | buttons, fields, cards, alerts, badges, modal, and tokens |
+| `/examples/states` | loading, refresh, empty, error, auth, forbidden, and not-found states |
+| `/examples/auth` | reactive external-auth integration seam |
+| `/sample/resources` | protected, domain-neutral integration route |
+
+`AUTH_MODE=demo` is credential-free and accepted only in local/development
+environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
+owner described in
+[`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md).
+The client route policy is user experience only; server authorization remains
+authoritative.
+
 ## Architecture
 
 Dependencies point inward:
@@ -27,9 +48,11 @@ bootstrap composes concrete adapters
 contracts own cross-cutting registries
 ```
 
-See `docs/architecture/overview.md` and `docs/architecture/layers.md`. The
-removable sample slice is under `src/sample/contract-fixture`; product code is
-not allowed to import it.
+See `docs/architecture/overview.md`, `docs/architecture/layers.md`, and
+`docs/architecture/starter-experience.md`. The removable sample slice is under
+`src/sample/contract-fixture`; product code is not allowed to import it. The
+visible starter routes do not depend on that fixture and continue to build
+after it is removed.
 
 ## Verification
 
@@ -52,9 +75,17 @@ corepack pnpm drill:runbooks
 corepack pnpm check:ci
 ```
 
+Install the pinned Playwright browser engines before the first cross-browser
+run:
+
+```bash
+corepack pnpm exec playwright install --with-deps chromium firefox webkit
+```
+
 Two gates intentionally need external evidence:
 
-- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review.
+- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review
+  for all six registered routes.
 - `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
   eligible-sample threshold and 28 days of production data exist.