@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/.agents/skills/flawless-a11y/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: flawless-a11y
+description: Run and act on flawless-react's a11y task — biome's a11y rule group over a web tree, or the tool's own React Native analyser (six `a11y/*` rules with a denominator) under `--expo`, both writing one aggregate `reports/a11y.json`. Use when triaging accessibility findings, when the native run reports zero and you need to know whether it looked, when biome is not found, when a `biome-ignore` comment is flagged as unused, or when deciding what an icon-only control needs. For the suppression rules across tasks see flawless-findings.
+---
+
+# flawless a11y
+
+```bash
+bunx @lariocpt/flawless-react "src/**/*.tsx" --tasks a11y
+```
+
+One task, two engines, one aggregate report (`flawless/reports/a11y.json`). Which
+engine runs is decided by `--expo`, and the two are not interchangeable: biome's
+rules are HTML/ARIA, the native rules are `accessibilityLabel`/`accessibilityRole`.
+
+## Web: a biome sweep
+
+The task runs biome with a **scratch config** — `recommended: false` plus only the
+`a11y` group — so your project's `biome.json` is bypassed and a finding here is not
+an invitation to reconfigure your lint. Findings print as
+`file:line:col lint/a11y/<rule> message`.
+
+Severities are mixed and mean what they say: `useAltText`, `useButtonType`,
+`useHtmlLang`, `useAnchorContent`, `useHeadingContent`, `noRedundantRoles` are
+errors; `noAutofocus`, `noLabelWithoutControl`, `noNoninteractiveTabindex`,
+`noPositiveTabindex`, `noRedundantAlt`, `useFocusableInteractive` are warnings.
+Errors are defects; warnings on a component that composes its label elsewhere (a
+generic `Field` wrapper) are usually correct code.
+
+**biome is a prerequisite on this path only.** The resolver looks in the target
+package's `node_modules`, every ancestor (so a hoisted workspace root counts) and
+`PATH`; when it finds nothing the task fails naming all of them. From the compiled
+binary the message is explicit: install `@biomejs/biome` in the project you are
+scanning, or put biome on `PATH`.
+
+**And it has to be biome 2.** The sweep writes a biome 2 linter config and parses
+its JSON reporter, so a candidate whose `--version` names another major is walked
+past in favour of one that can read it — which is how a repo that hoists a 1.x
+still gets a sweep from a 2 on `PATH` — and if none can, the task fails naming the
+version and path it refused. A 1.x biome does answer, and what it prints is a
+different document (`location.path` is an object, `message` an array of markup
+runs), so its output cannot be read as findings. A source or npm install answers
+with its own pinned 2 first and never sees the repo's biome: only the compiled
+binary resolves into the scanned project.
+
+## Native: the analyser, and its denominator
+
+Biome's a11y rules are all HTML/ARIA. Over 31 React Native files carrying 82
+unlabelled `<Pressable>`s they returned **zero**, while the same config finds 3/3 on
+this repo's own DOM offender fixture — so the native path is the tool's own engine,
+six rules:
+
+| rule | severity | what it catches |
+| --- | --- | --- |
+| `a11y/unnamed-control` | error | a pressable whose children are provably textless with no `accessibilityLabel` |
+| `a11y/missing-role` | error | a pressable with no `accessibilityRole` — RN has no implicit roles |
+| `a11y/textinput-unlabelled` | error | a `TextInput` with no label; a `placeholder` alone does not count |
+| `a11y/icon-unhidden` | warn | an icon from a known vector family exposed to the a11y tree with nothing to announce |
+| `a11y/label-text-mismatch` | error | an `accessibilityLabel` that does not contain the visible text |
+| `a11y/invalid-role` | error | an `accessibilityRole` value RN does not know |
+
+Two things to read off every native run:
+
+- **The summary always carries a denominator:** `N press target(s), N text input(s),
+  N icon(s) examined, 6 native rules`. **A native zero without that denominator is a
+  bug, not a clean bill.**
+- **Files in DOM dialect are not swept.** A component whose host dialect is not
+  native (a `react-native-web` surface, a web-only screen inside an Expo tree) is
+  counted, not judged: the summary appends `N dom-dialect file(s) NOT swept — run
+  without --expo for those`, and the report carries them under
+  `domDialectFilesNotSwept`.
+
+The engine is restrained on purpose, and that restraint is why its errors are
+trustworthy: `unnamed-control` fires only on the **provably** nameless case —
+children that are absent or all textless. A pressable rendering `{building.name}`
+announces at runtime, so label-absence there is not a finding. The same for
+`dynamicLabel` / `dynamicRole`: a label built by code is not a finding.
+
+One freebie worth knowing: RN's own `<Button>` is exempt from `missing-role`,
+because it has exactly one implicit role and the analyser injects it.
+
+## What neither engine sees
+
+Static a11y is name-and-role analysis. It does not check contrast, focus order,
+reading order, motion, or whether a `role` is semantically right for the widget; the
+web engine cannot see a label supplied by a wrapper it does not analyse, and the
+native engine cannot see what a screen reader assembles at run time. Zero findings
+means "no provably silent control", not "accessible".
+
+## Suppressing
+
+```tsx
+// biome-ignore lint/a11y/noLabelWithoutControl: generic wrapper — every call site associates the control
+```
+
+Biome attaches the comment to the **next line's** diagnostic; for a multi-line JSX
+element whose finding anchors on an attribute, put the comment inside the tag
+directly above that attribute. Native findings have **no suppression mechanism** —
+deliberately: each message names the one prop that retires it
+(`accessibilityLabel`, `accessibilityRole`, `aria-hidden`), so either add it or the
+finding is wrong and belongs in an issue.
+
+The cross-config trap that makes a biome suppression report as `unused`, and the fix
+for it, is in flawless-findings.
+
+## Never
+
+- Never read a native zero as a pass without its denominator.
+- Never enable one of these rules in a project's biome config purely to silence the
+  project's `biome ci` about the suppression — enable it because the suppressed site
+  was the only finding, which is usually true, and say so in the commit.
+- Never add `accessibilityRole` or `aria-*` to satisfy a sweep where the message's
+  actual ask (`accessibilityLabel`, `aria-hidden`) is the fix.

package/.agents/skills/flawless-api/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: flawless-api
+description: Use flawless-react programmatically — runFlawless/runCore options and results, exit-code and error contracts, the analyse()/ComponentTree surface for custom reporting, the tasks registry, and the --ci JSON contract. Use when scripting suite generation (CI, sandboxes, agents), building custom reports on the analysis, or embedding the tool in another workflow.
+---
+
+# flawless programmatic API
+
+> **`expo` is a `CoreOptions` field beside `nextjs`**, and the two are mutually
+> exclusive — `runCore` throws a `UsageError` for the pair, because it is a public API a
+> programmatic caller reaches without `parseArgs`. `RunContext` carries
+> `expo?: ExpoContext`; ask `platformOf(ctx)` rather than testing `ctx.expo` yourself, so
+> widening the rule later happens in one place. An unported task returns a **failed
+> `TaskResult`**, not a throw, so a refusal is readable from `results[]` and the `--ci`
+> blob.
+
+```ts
+import { runFlawless } from "flawless-react";
+
+const { exitCode, outDir, results, trees } = await runFlawless({
+  entry: "src/components/Widget.tsx",   // path or glob; optional in Next.js mode
+  nextjs: ".",                          // enables Next.js mode, "." = cwd
+  tasks: ["unit-browser", "perf-static"],
+  colocate: true,
+});
+```
+
+`runFlawless` is the friendly wrapper (`entry`/`tasks`/`out`); `runCore` from
+`core.ts` is the same engine with CLI-shaped names (`pattern`/`taskIds`/
+`outDir`) plus `changed` and `heaps`. Everything else — `runTests`, `force`,
+`report`, `log`, `quiet` — is on **both**.
+
+Two output flags, and they answer different questions:
+
+- **`log`** — may this run write to **stdout**? Off by default programmatically.
+  It gates the progress narration *and* the per-file findings listing. `--json`
+  turns it off because stdout must parse whole.
+- **`quiet`** — should `runCore`'s own diagnostics on **stderr** be suppressed?
+  Off by default, so the warnings **do** speak, even when `log` is off. Pass
+  `quiet: true` only if you route them yourself.
+
+One flag for both is how `--ci` became the mode that lost its warnings.
+`quiet` is deliberately narrow: it silences `runCore`'s `warn()` lines, not
+stderr as a whole — the suite runner's output is routed by a different flag,
+and task-level `console.warn`s have no gate. Redirect fd 2 if you need silence.
+
+## Contracts
+
+- **Never calls `process.exit`.** Bad input throws `UsageError` (exported from
+  the package and from `types.ts`); everything else is a plain error.
+- **CLI exit codes:** 0 clean · 1 a task failed, a `--run-tests`/`--changed`
+  suite run failed (suite outcomes fold into the exit code), or a non-task
+  failure such as a broken Next.js emit · 2 usage error. The code alone does not
+  say which — `results`, `testRun` and `errors` do.
+- **`--ci`** = `--no-interactive --json`: stdout is exactly one JSON blob
+  `{ exitCode, outDir, results, keptScripts, testRun, errors? }` and nothing
+  else. Progress goes away entirely; parse the whole stdout, not a line of it.
+  **stderr still carries diagnostics** — skipped files, an unparseable spec,
+  script collisions, a failed Next.js emit. Capture it: those lines are the only
+  account of work the run quietly dropped.
+- **Never read exit 0 as "the suites passed."** Read `testRun`. The invariant:
+  `mode: "none"` **if and only if** zero suites executed, so `green` never
+  appears on a phase that ran nothing.
+  - `{ mode: "generated" | "affected", green }` → suites really RAN; `green` is
+    what folded into `exitCode`;
+  - `{ mode: "none", reason }` → **nothing ran**, and `reason` says which of the
+    three causes it was: no selected task generates a suite `--run-tests`
+    executes (only `perf-harness`, `unit-browser` and `e2e` do — `load` emits
+    pipes you run with `bun run flawless:load`), nothing was affected, or the
+    selected tasks plan no run for the work that was;
+  - absent → the run never REACHED the test-run phase. That is NOT "no run was
+    asked for": a request blocked by a failed task is also absent, exits 1, and
+    is explained by `results`. Read absent as "look elsewhere" (FR-046).
+- **`errors`** carries failures belonging to no task, so `results` cannot show
+  them — a Next.js emit that threw sets `exitCode: 1` with every task `ok: true`.
+  Omitted on a clean run, so branch on its presence.
+- `results` is `TaskResult[]`: `{ id, ok, outputs, findings, summary, error?,
+  status? }` — `ok: false` with `error` set is a real task failure.
+  `status` ("generated" | "refreshed" | "kept", perf-harness only for now)
+  says where the run sat in the suite lifecycle: a re-run over an existing
+  suite is ok:true + "refreshed", and a `--changed` run keeps the harness
+  (ok:true, "kept", outputs empty) rather than regenerating it.
+- `reproCommand` semantics: REPORT.md's repro line is rebuilt from options,
+  relative paths only, defaults omitted — two identical runs produce the same
+  line byte-for-byte, so run from the project root with relative inputs if you
+  care about a stable REPORT.md.
+
+## Running from a checkout
+
+`bun src/bin.ts <args>` and `bun src/cli.ts <args>` both work (cli.ts has an
+`import.meta.main` guard), as does the compiled `bin/flawless-react`. In
+sandboxed or scripted contexts still prefer the programmatic API with evidence
+written to files — stdout may be captured, truncated, or lost, and the
+flawless-regen skill's run-proof discipline applies.
+
+Cwd matters in Next.js mode: `nextjs: "."` resolves against the process cwd,
+and the run merges `flawless:*` scripts into THAT root's `package.json`.
+`process.chdir(appRoot)` first, or pass absolute paths deliberately.
+The merge never clobbers a user-customised `flawless:*` value: only the
+tool's own recognised spellings upgrade; kept keys surface in
+`CoreResult.keptScripts`, the `--ci` blob, and REPORT.md.
+
+## The analysis surface
+
+```ts
+import { analyse } from "flawless-react";
+
+const tree = await analyse({ entry: "src/Nav.tsx", depth: 3, includeChildren: true });
+// tree: ComponentTree — entry: ComponentInfo (propsShape, variants, hooks,
+// interactions, dataDeps, unresolvedProps/unresolvedTypes), children: ComponentTree[]
+// A dataDep whose usage inference came up empty may carry inferredReturn
+// (a fixture value from its Promise<T> annotation, provenance "annotation")
+// or wrapsFetch (method+path for the emit-time OpenAPI join); a server-action
+// moduleImport may carry serverActionReturns (module-side name -> literal).
+```
+
+`analyse()` is pure static analysis — no files written — and is the right base
+for custom reporting. The honesty contract worth preserving in anything you
+build on it: an extraction that fails is RECORDED (`unresolvedProps`,
+`unresolvedTypes`, `uncertain` on data deps), never silently empty; treat an
+empty shape with empty unresolved records as a bug to report, not a component
+with no props.
+
+Tasks are a registry: `findTask(id).run(ctx)` with
+`ctx: { trees, outDir, force, … }` returning a `TaskResult`. A custom task is
+a new entry in `src/tasks/index.ts` honouring one rule — write findings and
+outputs, throw only for genuine failure, and make `ok` mean what it says.
+
+## The MCP server — the same contracts for a host
+
+`flawless-react mcp` serves this tool over the Model Context Protocol on stdio:
+eight tools, and **no new API surface to learn**. `flawless_run` answers with the
+child's exit line plus the same `--ci` blob documented above, so every contract in
+this file — `testRun` as the only proof suites ran, `errors` belonging to no task,
+`absent` meaning "look elsewhere" (FR-046) — is how to read what an agent gets
+back. It spawns a `flawless-react` child per run call (a suite runner inherits
+stdout; in-process would write vitest's report into a JSON-RPC frame), so nothing
+is held between calls. The six `flawless_*` read tools parse in-process and write
+nothing; unknown arguments are rejected, not ignored; `flawless_findings` is the
+static engine only, so zero findings is not "accessible and lint-clean". List the
+tools from the binary rather than from memory:
+
+```bash
+flawless-react mcp
+flawless-react mcp --help
+```
+
+The two planes, the arguments and the honest limits: `docs/mcp.md`.
+
+## Never
+
+- Never scrape the human console output — use `--ci` or the API's `results`.
+- Never run Next.js mode from an arbitrary cwd without pinning it: the
+  package.json merge follows the resolved root, wherever that is.
+- Never treat `exitCode: 1` as "the tool crashed". Two distinct causes: a
+  task failed (`results[].error` names it) or a `--run-tests`/`--changed`
+  suite run went red — in the suite case every `results[]` entry is `ok:true`
+  and the outcome lives in `exitCode` and `CoreResult.testRun` ({mode:
+  "affected"|"generated", green}), not in any error field. A re-run over an
+  existing suite is not a failure: it refreshes the harness and exits 0.

package/.agents/skills/flawless-api-fixtures/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: flawless-api-fixtures
+description: Give flawless-react real API data — `--api` with an OpenAPI/Swagger file, `--swagger-url` against a live docs endpoint (including the automatic `--nextjs` probe and `--swagger-url=off`), the MSW handlers and `swagger.json` it writes and which of them survive a re-run, how a body is synthesised when the spec has no example, and the four fetch cases every generated spec carries. Use when generated fixtures are empty `{}`, when a component's fetch is not matched by a handler, when a spec should assert loading or empty-state copy, or when deciding between mocking in specs and running a real backend. For the programmatic API (`runFlawless`, `analyse`) see flawless-api.
+---
+
+# flawless API fixtures
+
+Two different things live in this repo's vocabulary and mixing them up wastes an
+hour: **MSW handlers** (`flawless/mocks/`), which intercept `fetch` inside the unit
+and browser planes, and the **mock server** (`flawless/mock/`), a Bun server you can
+point an app at. Both are derived from the same source: your OpenAPI spec, when the
+tool can get one.
+
+## Getting a spec
+
+```bash
+bunx @lariocpt/flawless-react "src/app/dashboard/page.tsx" --nextjs . --api openapi.json --swagger-url=off
+```
+
+- **`--api <file>`** — a spec on disk. The value is required and must be a path.
+- **`--swagger-url <url>`** — fetch it from a running app (the docs help names
+  `http://localhost:3000/api/docs` from `next-swagger-doc`). A spec obtained this way
+  is **preferred over static AST inference**.
+- In `--nextjs` mode that URL is **probed automatically**, with a 1.5 s timeout, so a
+  docs-enabled app needs no flag at all. The probe never throws: a non-2xx, a
+  non-JSON content type, or a dead port is reported and the run continues on inferred
+  routes. `--swagger-url` forces a different URL; `--swagger-url=off` skips the probe
+  — do that when the app under test is slow to boot, or when a *different* app's docs
+  endpoint is listening on 3000.
+- **With no spec at all**, the tool walks `app/**/api/**/route.ts` and derives routes
+  from it — useless for a catch-all API (Hono, tRPC), which is exactly the case
+  `--api` exists for.
+
+A spec obtained by either route is written **verbatim** to `flawless/swagger.json`;
+without one, that file is **derived from the inferred routes and rewritten every
+run**.
+
+## What is written, and what survives a re-run
+
+| file | refresh behaviour |
+| --- | --- |
+| `flawless/swagger.json` | rewritten every run |
+| `flawless/mocks/handlers.ts` | **written once, never overwritten — not by `--force` either** |
+| `mocks/browser.ts`, `mocks/node.ts`, `mocks/README.md` | written once, refreshed by `--force` |
+| `flawless/mock/server.ts` | only with `--api`: rewritten each run |
+| `flawless/mock/routes.ts` | only with `--api`: written once (hand-tuned bodies can't be rebuilt from the spec) |
+
+The handlers file is the one you edit. Its header says so, and it is the reason a
+spec with a `{}` body can be fixed once and stay fixed.
+
+How the three MSW entry points wire up:
+
+- **Vitest** — `setupServer` from `mocks/node.ts`, started in `flawless/setup.ts`, so
+  a component's `fetch` hits your mock responses in jsdom.
+- **Browser specs and the perf host** — `host/main.tsx` calls `startMockWorker()`
+  from `mocks/browser.ts` before mounting; a service worker intercepts page `fetch`.
+- **Server components, server actions, SSR** — not covered by either. When you run
+  against a real Next dev server, wire your own instrumentation to import
+  `mocks/node.ts`. The honest reason `e2e` runs against the real app: MSW cannot
+  intercept a server component's direct database access, and mocking that would be a
+  lie (flawless-e2e).
+
+## Where a fixture body comes from
+
+Per response media type, in order: `example`, then the first `examples[*].value`,
+then a body **synthesised from the schema**. Synthesis is literal and worth knowing,
+because it explains most empty-looking specs:
+
+- `object` → every property, recursively; `array` → **exactly one item**;
+- `string` → `""`, except `format: date-time` → `1970-01-01T00:00:00.000Z`;
+- `integer`/`number` → `0`; `boolean` → `false`; `enum` → its **first** member;
+- `allOf` → the branches merged into one object;
+- `$ref` → resolved **only for local `#/…` refs**; a cycle or an external ref yields
+  `null` for that property.
+- Response selection prefers a coded status; a `default` response is used last and
+  counted as 200.
+
+So `{ id: 0, createdAt: "1970-01-01T00:00:00.000Z", items: [ … ] }` is not a bug — it
+is a spec with no examples. The fix is `examples` in the spec, or hand-editing
+`mocks/handlers.ts` (which nothing will overwrite), or both.
+
+When a component's endpoint has no derivable body, the generated spec says so in
+place:
+
+```
+// TODO(flawless): no example found in the API spec — replace {} with a realistic fixture.
+```
+
+## What every fetch generates
+
+One `describe("<Component> GET /api/items")` per detected fetch, with four cases:
+
+1. **success** — `server.use(http.get(URL, …))` returning `FIXTURE`, plus a call
+   counter so the spec can prove the request happened;
+2. **loading** — the same handler behind `delay(150)`, ending in
+   `TODO(flawless): assert the loading indicator while the response is pending.`;
+3. **error** — `new HttpResponse(null, { status: 500 })`, asserting the component
+   survives;
+4. **empty** — `FIXTURE` with **the envelope preserved and every array member
+   emptied** (`{ items: [] }`, not `[]`), ending in `TODO(flawless): assert the
+   empty-state copy.`
+
+The loading and empty assertions are the intended hardening work: the harness proves
+the state is reachable, you say what the state looks like.
+
+Path parameters are handled before any of that. A URL hole that corresponds to a
+**prop** is filled with `test-<hole>` at render time, because the prop's synthesised
+default is `""` and `/api/x//y` never matches a `:param` handler — the request would
+silently miss every handler in the file.
+
+Handler matching is **param-name-agnostic**: `/api/x/{id}/y`, `/api/x/:id/y` and
+`/api/x/:buildingId/y` are the same shape. So a spec that asks for
+`:buildingId` is satisfied by a route declared `{id}`.
+
+## The mock server
+
+With `--api` (a file, not a live probe — `--swagger-url` enriches routes and
+`swagger.json` but scaffolds no server), `flawless/mock/` is scaffolded too: `bun
+mock/server.ts` serves on `127.0.0.1:${MOCK_PORT:-5174}` (default 5174), compiling
+OpenAPI templates (`/users/{id}`) into matchers, and answering anything it does not
+know with
+
+```json
+{ "error": "not mocked", "method": "POST", "path": "/api/orders" }
+```
+
+That 404 body is the diagnostic: a run that behaves oddly against the mock and
+correctly against the real API is missing routes in `mock/routes.ts`, not broken
+components. Two limits to keep in view: **`routes.ts` is never rewritten** (your
+hand-tuned bodies are yours), and **the response body is static** — a path parameter
+is captured but does not change the answer, so `/users/1` and `/users/2` return the
+same document. Anything where the id must change the response belongs in a handler
+you write, or in a real backend.
+
+## Never
+
+- Never read a `{}` fixture as "the tool generated nothing": it means the spec had no
+  example. Add `examples`, or fill the handler.
+- Never rely on MSW in the unit plane to prove what a server component renders —
+  server-side data access is not interceptable there.
+- Never let the loading and empty-state TODOs stand while claiming the fetch path is
+  covered: the states are reached, not asserted.
+- Never treat the mock server as contract validation. For violation reporting, put
+  crust's validating proxy in front of the real app (flawless-e2e).

package/.agents/skills/flawless-e2e/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: flawless-e2e
+description: Run and maintain flawless-react's route e2e specs against a real dev server — seeded-DB prerequisites, the global-setup login and storageState, params.json ids and `landing` overrides, FLAWLESS_E2E_BASEURL, the auth wall that 404s or serves the login page at a real path, and the landing assertion that decides whether a green e2e run tested a route. Use right before running `flawless:e2e`, when e2e fails at global setup, when every route 404s, or when a suite passes suspiciously cheaply. For load pipes and their baselines see flawless-load.
+---
+
+# flawless route e2e
+
+Everything here runs against the **real app**: MSW cannot intercept a server
+component's direct database access, so mocking it would be a lie. That realism is
+also where every vacuous pass hides — a green route spec is only worth what its
+landing assertion is worth.
+
+```bash
+bunx @lariocpt/flawless-react "src/app/**/page.tsx" --nextjs . --tasks e2e
+```
+
+## Prerequisites, in order
+
+```bash
+bun run db:up && bun run db:migrate && bun run db:seed   # Postgres + seed users
+bun run dev:web                                          # app on :3001
+bun run flawless:e2e
+```
+
+From the suite dir, with the plane's own config and its own copy of Playwright:
+
+```bash
+node node_modules/@playwright/test/cli.js test --config e2e/playwright.config.ts
+```
+
+Running it from the app root instead is how `test.describe() called here` /
+`No tests found` appear: two `@playwright/test` copies (app root + suite) and the
+run picks up the wrong one.
+
+## Signing in
+
+`flawless/e2e/global-setup.ts` is where you sign in as the seeded user and persist
+`storageState` to `e2e/.auth.json`. **What the tool emits is a stub** that writes an
+empty state (so the config's `storageState` always resolves) plus a worked example.
+It is write-once — never overwritten, `--force` included, because it is yours the
+moment you touch it.
+
+A filled setup should **throw if login lands back on /login**. That throw is an
+anti-vacuous guard, not a bug: when it fires the seed drifted (wrong user, wrong
+password, unseeded DB). Fix the seed, never the guard.
+
+You are not relying on remembering that, though. **Every emitted route spec asserts
+it landed on the route it asked for** — both the render test and the interaction
+test — so an unauthenticated suite fails naming its escapes instead of quietly
+testing the login screen. Until the hook is filled, REPORT.md's hand-work table
+says so; the check is byte-identity against the stub, so it clears the moment you
+edit the file.
+
+**What that assertion does and does not catch**, because an overclaim here is the
+same bug wearing a different hat. It catches redirects that CHANGE THE URL and have
+landed by the time the spec looks — a server 3xx, and a client-side navigation that
+completes before `networkidle` settles. It does **not** catch a middleware *rewrite*
+that serves the login page at the requested path, a 401 body, or a redirect that
+fires later than the spec waited. A 401 usually still reds the spec, but through the
+console-error check, not this one.
+
+## The auth wall, in its three shapes
+
+The same cause — the app's own middleware (`auth.protect()`, a Clerk/next-auth
+guard) with placeholder or missing credentials — surfaces one stage earlier each
+time you chase it:
+
+1. **`Timed out waiting …ms from config.webServer`, no spec ran.** Playwright calls
+   a server up only on `200 ≤ status < 404` from the readiness URL, which is the app
+   root; behind the wall the root 404s and Playwright retries the whole timeout
+   (`[WebServer] GET / 404` repeating in the log).
+2. **Every route 404s while `/` loads in a browser.** The guard is per-route and the
+   root is public.
+3. **Specs pass on a login page.** A rewrite keeps the path and returns 200.
+
+There is no tool-side fix for placeholder keys. Either put real credentials in
+`e2e/global-setup.ts`, or set `FLAWLESS_E2E_BASEURL` to a server you started
+yourself (the emitted config drops its own `webServer` block for that — useful when
+the app is already running, or when you want the wall up and provably authenticated
+past), or do not claim those routes.
+
+## ids and landings: `flawless/e2e/params.json`
+
+Write-once and merge-kept, so `--force` never touches what you fill in. An
+unresolvable id never fabricates a URL: the spec emits a `test.skip` naming the file
+to fill (`no id fixture for /posts/[id] — fill flawless/e2e/params.json`), so an
+unfilled route is a visible skip, not a 404 measured as a pass. On the load side the
+same hole is `routes.setup.ts`, which refuses the run instead of measuring the 404
+handler — see flawless-load.
+
+The resolver (`e2e/params.ts`) tries four things, in order:
+
+1. `FLAWLESS_E2E_<PARAM>` — per-parameter environment override, uppercased;
+2. `routes[<route>][<param>]` in params.json — for a route that needs a
+   **consistent set** (a building and one of its floors);
+3. `defaults[<param>]` — the usual case, one seeded record;
+4. `FLAWLESS_E2E_ID` — the legacy single-id escape hatch.
+
+`landing` records a route that redirects **on purpose** (a default sub-tab, a locale
+landing) so its spec asserts the real destination instead of failing forever:
+
+  ```json
+  { "landing": { "/dash": "/dash/overview" } }
+  ```
+
+Both belong in `params.json`, not in the spec: `--force` regenerates specs and
+leaves this file alone.
+
+## Contract-checked runs (optional)
+
+Put crust's validating proxy in front and assert no response violated the OpenAPI
+spec:
+
+```bash
+crust -c 'mock-server --swagger openapi.json --port 4747 --proxy http://localhost:3001' &
+FLAWLESS_E2E_BASEURL=http://localhost:4747 bun run flawless:e2e
+crust -c 'GET :4747/__crust/violations | (v => v.violations.filter(x => x.direction === "response")) | assert (a => a.length === 0)'
+```
+
+The filter to `direction === "response"` matters: request-direction violations are
+usually the app talking to itself with fields the spec never described, and they
+will drown the ones that mean the app's own output is off-contract.
+
+## Under `--expo`
+
+`e2e` RUNS under `--expo` since wave 6 — expo-router routes against
+`expo start --web` (Metro's webPort, default 8081), authenticated against the API
+origin with a **cookie** via the setup stub's request-context login + storageState
+(the app short-circuits `expo-secure-store` on web and sends `credentials:
+"include"`). Three differences to know:
+
+- Set `EXPO_PUBLIC_API_URL` before running. Metro bakes it into the bundle; unset,
+  the app falls back to whatever its source hardcodes — on one dogfooded LAN, a
+  production container.
+- Metro's statuses are REAL (unknown routes 404, per-route HTML — measured in
+  `docs/archive/2026-09-expo-probes.md`), so a 404 is a routing bug, not harness
+  noise.
+- Each spec carries a third test, the **copy witness** (`getByText` on the screen's
+  longest analysis-proven literal), because an auth wall rendered in place keeps the
+  URL and a clean-ish console. The witness is the claim that cannot be true of a
+  wall.
+
+A cold start that always lands on the login screen is a `landing` override in
+params.json, not a spec edit. See flawless-expo for the rest of the native plane.
+
+## Never
+
+- Never weaken or delete global-setup's throw-on-/login guard.
+- Never "fix" a params.json syntax error by deleting the file: an invalid file fails
+  the run with `is not valid JSON — fix or delete it and re-run` precisely because a
+  hand-edited file's contents are yours; repair the JSON.
+- Never read "N routes pass" as meaning anything until the spec's landing assertion
+  was real (a filled `params.json`, a storageState that is not the empty stub).
+- Never add a `landing` override to make a red spec green without checking what it
+  lands on: that is how a wall becomes permanent coverage of the login page.