@lariocpt/flawless-react 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,283 @@
+---
+name: flawless-expo
+description: Work with flawless-react's Expo / React Native mode — what --expo detects, which tasks run and which refuse, the jest-expo + @testing-library/react-native unit plane, renderRouter vs render, the native selector ladder and why a skip is a skip, and the version pairing that has to be exact. Use when generating or fixing native specs, when a native suite is red, or when deciding whether a refusal is a bug or the design.
+---
+
+# flawless-expo
+
+React Native is a **second element vocabulary**, not a Next.js variant. `<View>` is
+capitalised and imported; there is no `<form>`, no implicit ARIA role, and
+`className` is compiled away by babel before anything can observe it. Most of what
+this skill records is the consequences of those four facts.
+
+## What `--expo` detects
+
+`detectExpo(root)` reads, off disk only:
+
+| field | from | why it matters |
+|---|---|---|
+| `sdkMajor` | the project's own `expo` range, else what is installed | jest-expo's major must **match** it |
+| `routerRoot` | `app/` or `src/app/`, **only if** `expo-router` is a dependency | decides which files get the route template |
+| `reactCompiler` | `app.json` `experiments.reactCompiler`, or `babel-plugin-react-compiler` | the three `perf-static` memo rules are suppressed, with the config that proved it named in REPORT.md |
+| `nativewind` | `babel.config.js` mentioning nativewind | decides whether an unstyled host is honest to ship |
+| `webPort` | the `web` then `start` script, default **8081** | Metro's port, not 3000 |
+
+`sdkMajor` is `number | undefined` and **never guessed**. `latest`, `*`, a git url and
+a `file:` specifier all produce *unknown*, and the run says so rather than substituting
+a number — a jest-expo major that does not match the SDK fails deep inside
+`expo-modules-core` with a message that names nothing.
+
+## The version pairing, which has to be exact
+
+```
+jest-expo                       ~<the project's OWN sdk major>.0.0
+jest                            ^29.7.0
+@testing-library/react-native   ^13.3.3      <- 13, NOT 14
+react-test-renderer             19.1.0
+```
+
+Each wrong answer fails somewhere unhelpful:
+
+- **A bare `jest`** resolves to 30 while jest-expo 54's tooling is all `^29.2.1`, and the
+  mismatch surfaces as `this._moduleMocker.clearMocksOnScope is not a function` from
+  inside jest-runtime.
+- **RNTL 14** replaced `react-test-renderer` with the `test-renderer` package, and
+  expo-router 6's own testing-library is built against the former.
+
+If you are tempted to "upgrade" any of these, run the suite. That is what caught all of it.
+
+## Three spec shapes, chosen from the file
+
+**Route screen** → `renderRouter` from `expo-router/testing-library`, at its own URL.
+Not a preference: `useFocusEffect` reaches `useNavigation()`, which throws
+`Couldn't find a navigation object` outside a navigator, and `useLocalSearchParams`
+is empty. Inside a real navigator the screen is **focused**, so focus effects run and
+the spec can assert loaded state instead of the loading skeleton.
+
+**`_layout`** → its own navigator with one synthesised child. `<Tabs>` and `<Stack>`
+call `useContextKey` and throw `No filename found. This is likely a bug in expo-router`
+when rendered alone.
+
+**Everything else** → RNTL `render()`.
+
+### The context is the OBJECT form, always
+
+```tsx
+const CONTEXT = {
+  "_layout": Layout0,
+  "login": { default: LoginScreen },
+  "signup": { default: () => null },   // a stub for every literal push target
+};
+```
+
+expo-router resolves the string and `{ appDir }` forms through
+`path.resolve(process.cwd(), …)`, so a spec using either breaks the moment jest runs
+from the monorepo root instead of the app directory. The stub leaves are not
+decoration: a push to a route the context does not know lands on expo-router's
+injected `+not-found`, and the pathname assertion then fails for the wrong reason.
+
+### fireEvent in route specs, userEvent in component specs
+
+`renderRouter` calls `jest.useFakeTimers()` internally. `userEvent`'s press timing
+under fake timers is not something the emitter vouches for, so route specs use
+`fireEvent`, which has no timers in it. Do not "upgrade" one to the other.
+
+## The selector ladder
+
+```
+testID → accessibilityLabel → accessibilityRole (+name) → placeholder
+       → displayValue → text → text fragment → undefined
+```
+
+`placeholder` sits **above** text deliberately: a placeholder names *the element*,
+text names a *child*.
+
+**There is no last-resort rung, and that is a decision.** The DOM ladder bottoms out at
+`container.querySelector("button")`; the two native candidates are both unsound.
+`UNSAFE_getByType(Pressable)` compares component identity, and under NativeWind's
+`jsxImportSource` the `Pressable` the source rendered went through `cssInterop`'s
+wrapper while the one a spec imports is the bare component — so it matches zero
+elements, and `fireEvent.press` on nothing is a green test that touched nothing.
+"The first pressable in the tree" is wrong for the same reason the DOM ladder refuses
+an ambiguous bare tag, only more often, because every screen is a stack of Pressables.
+
+### A skip is not a gap in the tool
+
+`getByRole("button")` matches **nothing** on a bare `<Pressable>`: RNTL's `getRole()`
+reads the explicit `accessibilityRole` prop, else `"text"` for `Text`, else `"none"`.
+There is no implicit-role table to lean on.
+
+So a control with no `testID`, no `accessibilityLabel`, no `accessibilityRole` and no
+text under it is a `test.skip` carrying the reason **and the fix**. The icon-only
+wording wins over the ambiguous one when both apply, because one `accessibilityLabel`
+resolves both — and the same absence is what makes the control silent to a screen
+reader. **Answer a skip by adding the label to the app, not by loosening the ladder.**
+
+## What a native spec does NOT assert
+
+Three DOM assertions have no honest native equivalent and are dropped rather than faked:
+
+- the root-tag `querySelector` — `rootTag` is a capitalised element name, and the only
+  RNTL equivalents couple the spec to RN internals;
+- the `.flawless-cls` className-flow check — NativeWind compiles `className` into a
+  `style` through **babel**, so a sentinel class is unobservable in the jest-expo tree
+  *and* in the react-native-web DOM;
+- anything asserting a specific style token, for the reason the DOM emitter refuses to
+  assert a Tailwind class.
+
+## No emitted spec touches the network
+
+A module that resolves project-locally and performs `fetch()` is `jest.mock`ed. Before
+this existed the fixture suite made live HTTP calls and crashed a jest worker with
+`api_error 405` from a real server.
+
+Each stub's shape comes from the mocked function's own `Promise<T>` annotation, resolved
+through workspace barrels and zod schemas. `Promise<void>` mocks to `undefined` with no
+marker — that IS its realistic return value. Only an unresolvable shape falls back to
+`{}`, and only that one keeps a `TODO(flawless)`. The fallback matters: `const { items }
+= await listBuildings()` against `{}` binds `items` to undefined, and the next
+`buildings.length` throws into the app's own ErrorBoundary, so the screen renders
+"Something went wrong" and the failure looks like the component.
+
+Collections are emptied for the default mock, so assertions derived from the initial
+render hold. The loaded state gets its own test — see below.
+
+The mock specifier is relativised to the **spec**, not the component — `app/login.tsx`
+writes `"../lib/api"`, which from `flawless/unit/` names `flawless/lib/api`.
+
+## The loaded state gets its own test, where that is fair
+
+A separate test re-mocks ONE function to return a single row and asserts a synthesised
+witness appears. Emitted only where three things hold, each checked against the AST:
+
+1. **Mounting calls it** — reachable from a `useEffect`/`useFocusEffect` callback or the
+   component body, and not inside a branch, a `catch`, or a JSX event handler. A mutation
+   called from a submit handler is not a loader; a call behind `if (isTrustee)` does not run.
+2. **What it returns is rendered as a list** — the result reaches a `useState` setter whose
+   state variable is mapped in JSX or handed to a list as `data`. A collection read to decide
+   a permission flag changes a boolean, not the screen.
+3. **The row has a witness** — a string field THIS list's row renders as a JSX child. Not an
+   attribute value (`key={r.id}` is not displayed), and not a field rendered elsewhere in the
+   file over different data.
+
+Where any fails, the emitter writes a `test.skip` naming which. On the dogfood app 14 of 31
+screens qualify and all 14 pass.
+
+An earlier version shipped this as a blanket skip, blaming "an external store the harness
+does not reach". That was a guess and it was wrong — every cause was visible in the AST.
+
+## `router.back()` needs a history entry
+
+`renderRouter` mounts one screen at one URL with nothing behind it, so `GO_BACK` into an
+empty stack fails with *The action 'GO_BACK' was not handled by any navigator*. A route
+spec pushes its own URL once before the press. A component spec has no router to push into,
+so the handler is a skip that says so.
+
+## Colocation is impossible under `app/`
+
+expo-router's `require.context` matches every `.[tj]sx?` under the router root, so a
+colocated `app/login.flawless.test.tsx` would **register as a route**. Native specs for
+route files always go to the out dir.
+
+Related: check the app's own `test` script. A bare runner with no path filter — the
+dogfood app's was `bun test --preload ./tests/setup.ts` — sweeps the generated specs
+into the project suite and runs them under a runner they were not written for. The tool
+warns; scope the script (`bun test tests`).
+
+## The native a11y analyser (wave 5)
+
+`a11y` runs under `--expo` since wave 5, through the tool's OWN analyser
+(`src/tasks/a11yNative.ts`) rather than biome — biome structurally cannot judge RN:
+all 29 of its a11y rules are HTML/ARIA, and over 31 real RN files with 82 unlabelled
+`<Pressable>`s they returned zero while scoring 3/3 on the DOM `A11yOffender.tsx`.
+
+Six rules: `a11y/unnamed-control` (provably-textless press target with no label —
+fires only on icon-only or childless elements, never on dynamic children, which DO
+announce at runtime), `a11y/missing-role`, `a11y/textinput-unlabelled` (a placeholder
+is not a label), `a11y/icon-unhidden` (warn; a render-prop icon such as `tabBarIcon`
+stands down — its owner is invisible to the file, and React Navigation's tab button
+announces the title over it), `a11y/label-text-mismatch` (WCAG 2.5.3),
+`a11y/invalid-role` (each role attr validated against ITS OWN union — "header" is an
+accessibilityRole, "heading" is a role).
+
+Three contracts to rely on:
+
+- **The denominator.** The summary and `reports/a11y.json` always say how many press
+  targets / text inputs / icons were examined and how many rules ran. A zero without a
+  denominator is a bug, not a clean bill.
+- **Presence-not-value stands rules down.** `accessibilityLabel={t("back")}` is recorded
+  as dynamic and never flagged. A missing finding on a dynamic attr is the design.
+- **Skip ⇔ finding agreement.** An icon-only control with no handle is BOTH the unit
+  plane's `test.skip` and an `a11y/unnamed-control` finding — same retained element,
+  one `accessibilityLabel` retires both. Deliberate asymmetries: a `testID`-only
+  control is addressable to a spec but still flagged (a testID is not a name), and a
+  dynamic-text control is a ladder skip but NOT flagged.
+
+## Route e2e against Expo web (wave 6)
+
+`e2e` runs under `--expo` since wave 6: one Playwright spec per expo-router route,
+against `expo start --web`. The Next.js flavour's machinery carries over
+(params.json ids, write-once global-setup with the hand-work tally, `landing`
+overrides, `GET <route>` describe titles for `--changed` narrowing); the Expo facts
+baked in, each measured first (`docs/archive/2026-09-expo-probes.md`):
+
+- Metro's statuses are REAL — unknown routes 404, per-route rendered HTML — so the
+  status assertion keeps teeth on a dev server.
+- Auth is a **cookie on the API origin** (the app stores no token on web); the setup
+  stub's request-context login + storageState example is the whole job. Set
+  `EXPO_PUBLIC_API_URL` first — Metro inlines it, and the unset fallback is whatever
+  the source hardcodes.
+- **Two auth-wall faces, three assertions.** A client redirect fails the landing
+  assertion; a wall rendered IN PLACE fails the console assertion (the API's 401s)
+  and the **copy witness** — a third test asserting the screen's longest
+  analysis-proven literal renders, the claim that cannot be true of a wall.
+- An app whose cold start always lands on `/login` (no session hydration) is a
+  `landing` override in params.json — recorded truth, never a spec edit.
+
+## API-only load pipes (wave 7)
+
+`load` runs under `--expo` since wave 7, API-only — an Expo app has no
+server-rendered page routes, so the pipes are the GET endpoints the screens hit.
+The harvest is the new part: a React Native screen never has a bare `fetch()`
+(`extractFetchCalls` finds 0 on the whole app), so the endpoint is read ONE hop
+through the app's own fetch wrapper — screen calls `listBuildings()` →
+`apiFetch("/api/buildings")`. The wrapper is detected structurally (its single
+`fetch()` addresses one of its own parameters), never by name. A store-mediated
+call, a non-literal URL, or a wrapper two modules deep is dropped — a missing
+endpoint costs a pipe, a wrong one measures a URL the app never sends. Retained
+at analysis time on `ComponentInfo.apiCalls` (native-only), judged at task time.
+
+The pipe/params/env/merge machinery is the Next flavour's, reused verbatim. The
+one difference: `routes.setup.ts` probes a parameterless GET endpoint and fails
+on a **401**, because an API endpoint answers 401 at the same URL rather than
+redirecting to a login page — so the Next flavour's redirect probe would pass on
+a dead session. Mutations are excluded (a POST load-test writes junk into the DB).
+
+## Tasks that refuse, and why that is the design
+
+`perf-harness`
+refuses as **measured-and-declined, not deferred**: on an expo-router app the
+population is route screens, which the browser host cannot mount (navigator hooks;
+renderRouter is jest-bound), so the measured ceiling on the dogfood app was ~0 of
+32 components — the refusal points at `docs/archive/backlog-completed-2026-10.md` B-16 and the probes
+ledger, and the revisit condition is an adopter with a real `components/` directory
+of non-route components. And one runner reads differently rather than refusing:
+
+- **`perf-static` suppresses its memo rules under the React Compiler.** On a project
+  with `experiments.reactCompiler: true`, 136 of 168 findings were
+  `perf/unstable-child-prop`, `perf/missing-memo-leaf` and
+  `perf/no-memoisation-with-children` — work the compiler already performs, so the
+  three are suppressed and REPORT.md names `app.json experiments.reactCompiler` as
+  the evidence. The hook-dependency, effect and `set-state-in-render` rules are
+  unaffected: the compiler relies on correct dependency arrays rather than
+  repairing wrong ones.
+
+## Never
+
+- Never drop `--expo` to make a task run. It will emit DOM artefacts for a React Native
+  project: a suite that runs, passes and tests nothing.
+- Never mock `react-native`. That is exactly why an app whose own setup does it cannot
+  test screens; jest-expo exists so you do not have to.
+- Never add a row to `NATIVE_TAG_TO_ROLE` unless the element's own React Native source
+  sets the role unconditionally. A fuller table means queries that match nothing.
+- Never satisfy a skip by relaxing the selector ladder. Add the `accessibilityLabel`.

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

@@ -0,0 +1,116 @@
+---
+name: flawless-findings
+description: Triage the findings flawless-react reports — REPORT.md's accounting, the reports/ JSON and sidecars, which findings are worth a commit versus a suppression, the cross-config trap that makes a `biome-ignore` read as unused, and the counts ledger across runs. Use after a run when working through a findings list, when a suppression shows up as "unused" in the project's own biome, or before quoting any coverage number from REPORT.md. For the rules themselves see flawless-perf-static, flawless-a11y and flawless-react-rules; for runtime numbers see flawless-perf-harness.
+---
+
+# triaging flawless findings
+
+```bash
+bunx @lariocpt/flawless-react "src/**/*.tsx" --tasks perf-static,a11y,react-rules
+```
+
+Three tasks scaffold nothing to run and only report: `perf-static` (the tool's own
+rules), `a11y` (a biome sweep on web, the tool's native analyser under `--expo`) and
+`react-rules` (a biome sweep with a curated rule set). Each has its own skill for the
+rule-level detail — flawless-perf-static, flawless-a11y, flawless-react-rules. This
+one is for reading a run and spending effort in the right order.
+
+## Where a finding lives
+
+Findings print as `file:line:col rule message` and land in `flawless/reports/*.json`:
+the two biome sweeps write **one aggregate each** (`react-rules.json`,
+`a11y.json`), while `perf-static` writes **one file per component that owns
+findings** (`<Component>.perf-static.json`). A `<Component>.flawless.json` sidecar
+lands beside each analysed source unless `--no-inline-summary`; its paths are
+relative to the sidecar, and its `a11y` and `reactRules` entries name the run's
+single aggregate rather than a per-component file.
+
+Per-component files only appear for components with findings, so **stale
+per-component reports from earlier runs linger in `reports/`.** Count from the task
+summary or REPORT.md, never from a glob over the directory.
+
+## Reading REPORT.md
+
+Regenerated every run: it describes the **last run**, not the suite on disk.
+
+- The components table accounts for every component in exactly one render-mode row
+  (client / rsc / compound-part / document-root / null), split by mountable or not.
+- "Not covered, and why" names each gap. **A file count is not coverage.**
+- "Imports that will not resolve" appears only on a run that wrote specs, and only
+  when an analysed import names a package nothing on disk answers for. It is why
+  those files fail at collect: **a file that never collected reports no tests.**
+- The task table records what that run wrote, with a Status column saying where
+  perf-harness sat in the suite lifecycle (generated / refreshed / kept).
+- Its hand-work table names the files only you can finish — `e2e/global-setup.ts`
+  while still the emitted stub, `e2e/params.json` while an id is blank.
+
+## Triage order
+
+Ordered by how much the tool trusts its own finding, not by count.
+
+1. **`perf/set-state-in-render`** (error) — always real, fix first.
+2. **`useHookAtTopLevel`** — a hook behind an early return breaks hook order at
+   runtime. Same class of defect.
+3. **Hook-dependency findings** — see flawless-perf-static: `hook-extraneous-dependency`
+   usually means the dep is never read (remove it, or make the read real);
+   `hook-missing-dependency` wants `useCallback` plus the dep, not a suppression.
+4. **a11y errors** — a control that is silent to a screen reader. `useAltText`,
+   `useButtonType`, `missing-role`, `unnamed-control`, `textinput-unlabelled`: each
+   message names the one attribute that retires it.
+5. **`perf/unstable-child-prop`** — a real win when the receiving child is memoised
+   or heavy; leave inline arrows to plain DOM elements alone.
+6. **`noArrayIndexKey`** — real for editable lists (a client-side id at creation,
+   stripped at submit); a reasoned suppression for server-static lists or where the
+   index *is* the domain identity.
+7. **The advisory tail** — `no-memoisation-with-children`, `missing-memo-leaf`,
+   `noExplicitAny`, `noDoubleEquals`. Fix where profiling agrees
+   (`flawless-perf-harness`), or where the value is obvious. Do not chase to zero.
+8. **`perf/unresolved-prop` is not on this ladder at all** — it is not a finding and
+   nothing here suppresses it. It is bucketed per component under REPORT.md's
+   `## Spec quality`, and its fix is `--props '{"name":1}'` or that spec's `DEFAULTS`,
+   never a suppression.
+
+On a project with the React Compiler on, item 5 and both memo rules in item 7 are
+suppressed by `perf-static` itself: the compiler memoises props and JSX at the call
+site, and REPORT.md names the config that proved the flag. That ladder then starts at
+item 6 for those rules — and a zero from them is the compiler's doing, not a clean
+bill. See flawless-perf-static for the three states and what each prints.
+
+## Suppressing honestly
+
+A suppression is an **answer**, so it carries its reason:
+
+```tsx
+// biome-ignore lint/a11y/noLabelWithoutControl: generic wrapper — every call site associates the control
+```
+
+Placement matters: biome attaches the comment to the next line's diagnostic. For a
+multi-line JSX element whose finding anchors on the `key=` attribute, put the comment
+inside the tag directly above that attribute, not above the element.
+
+**The cross-config trap.** The tool's sweeps run a scratch config containing only
+their own rules, and your project's biome has a different set. A rule enabled in only
+one of the two makes the suppression "unused" in the other. The tool's side is
+handled — its sweeps drop `suppressions/*` diagnostics entirely, since reporting them
+would punish you for answering another config's finding. **Your side is not:** if the
+project config doesn't enable the rule you're suppressing, the project's own `biome
+ci` flags the comment. The clean resolution is to enable the rule in the project
+config — usually free, because the suppressed site was the only finding — so both
+runs agree the suppression is legitimate, and to say that in the commit.
+
+## Counts, not colors
+
+Keep a ledger across runs (e.g. perf-static 246 / a11y 1 / react-rules 10) and
+explain every delta. A burn-down commit should be able to say "a11y 1→0, react-rules
+10→0" with one cause per line. **New findings after a regen are usually the analyser
+seeing new components, not regressions** — check the components count in REPORT.md
+before treating a rising total as a fall.
+
+## Never
+
+- Never suppress without a reason clause, and never to make a batch green.
+- Never chase the advisory clusters to zero — that is churn, not performance.
+- Never diff the reports/ directory to count findings; stale per-component files from
+  earlier runs survive. Use the task summaries or REPORT.md.
+- Never quote REPORT.md's file counts as coverage of a suite you have not run since
+  the last change — the report is the last run's.

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

@@ -0,0 +1,112 @@
+---
+name: flawless-load
+description: Run and maintain the crust load pipes flawless-react generates — routes.pipes, LOAD_BASE pointing at a production build, LOAD_AUTH as a header line, routes.setup.ts seeding LOAD_<PARAM> ids and proving the session, last-/baseline-<name>.json gating, and the anti-vacuous probes that decide whether a p95 describes a route or a login page. Use right before running `flawless:load`, when pipes report suspiciously fast p95s, when a run exits on the auth probe, or when a baseline needs arming. For route specs and the e2e login see flawless-e2e.
+---
+
+# flawless load pipes
+
+```bash
+bunx @lariocpt/flawless-react "src/app/**/page.tsx" --nextjs . --tasks load
+```
+
+`load` writes `flawless/load/routes.pipes` — crust pipelines for the analysed page
+routes plus the GET endpoints the page's components actually fetch (mutations are
+excluded on purpose). Crust runs them; nothing in this repo does.
+
+Measuring anything but the real, production app is fiction, and every vacuous pass
+in this plane comes from forgetting that: an unauthenticated dashboard request 302s
+to a login page that answers **200**, so every pipe passes.
+
+## Run it
+
+```bash
+bun run build:web && PORT=3001 bunx next start &         # PROD build on :3001
+SESSION=$(jq -r '.cookies[] | select(.name=="session").value' flawless/e2e/.auth.json)
+export LOAD_BASE=http://localhost:3001
+export LOAD_AUTH="cookie: session=$SESSION"
+bun run flawless:load    # routes.setup.ts seeds the ids and proves the auth
+```
+
+- **`LOAD_BASE` must be a production build.** `next dev` compiles routes on demand,
+  so the first request to each route measures the compiler. Check the server banner
+  says `next start`. If the app's `start` script has no port flag, the default :3000
+  may collide with something else on the box — `PORT=3001` wins.
+- **`LOAD_AUTH` is a header line** — for a cookie session, `cookie:
+  session=<value>` taken from the e2e run's `flawless/e2e/.auth.json`, not a Bearer
+  token. The e2e run is the cheapest way to get a real one: see flawless-e2e.
+
+## `routes.setup.ts`: the module that refuses
+
+You no longer source `env.sh`. `flawless/load/routes.setup.ts` runs first (crust
+awaits a pipes file's sibling setup module), seeds every `LOAD_<PARAM>` from
+`flawless/e2e/params.json`, and throws if it seeded none. The shell version needed
+`jq` and, without it, exported nothing *silently* while 2/3 of the pipes measured
+the 404 handler. The module has one failure mode and it is loud.
+
+The same module probes every static route and **throws if one lands somewhere
+else** — an expired cookie redirects to a login page that answers 200, so `expect
+200` passes and the whole file reports healthy percentiles for a login form.
+Measured, before the probe existed: 20/20 status 200, p50 19.7ms, exit 0, every
+request served /login. A by-design redirect goes under `landing` in params.json.
+
+The module is **write-once** — replace it with a check that knows your app and
+nothing will overwrite yours.
+
+## The probes, before you trust a number
+
+A load pipe carries no landing assertion of its own (an e2e spec does) and crust
+will happily report a fast, green p95 for 500 redirects.
+
+```bash
+echo "$LOAD_ID"                                   # must be non-empty
+curl -s -H "$LOAD_AUTH" "$LOAD_BASE/dashboard/buildings/$LOAD_ID" | grep -ci "login"
+```
+
+The curl must return real page HTML (tens of KB) and the grep must find no login
+form. The same trap wears a second face **after** the run: a pipe whose p95 is
+suspiciously fast is measuring the 404 handler or a redirect, not the route. Real
+SSR routes on a dev box sit around 10–15 ms p95, not 2 ms.
+
+## Baselines
+
+Each pipe gates p95 against `baseline-<name>.json`; a missing baseline is a pass by
+design — the first run arms it. Arm one by copying a good `last-<name>.json`; after
+that, a run fails when p95 doubles.
+
+Refresh a baseline only when you can explain the shift in the commit body, and never
+refresh a batch of them to make a red run green.
+
+## Regenerating
+
+`--force` **merges** `flawless/load/routes.pipes` rather than overwriting: edited
+rates, hand-added flows, and pipes you commented out yourself all survive. A pipe
+whose ids are unfilled is emitted **commented out**, above a line naming which key
+in `flawless/e2e/params.json` to fill — a blank segment measures the app's 404
+handler. The task summary reports live versus commented counts, so REPORT.md cannot
+call a gated pipe covered.
+
+## Under `--expo`
+
+`load` RUNS under `--expo` since wave 7 — **API pipes only**. An Expo app has no
+server-rendered page routes, so the pipes are the GET endpoints the screens hit,
+harvested ONE hop through the app's fetch wrapper (screen → `listBuildings()` →
+`apiFetch("/api/buildings")`; a bare `fetch()` never exists in a screen, so the
+direct harvest finds 0).
+
+- `LOAD_BASE` points at the **API**, not Metro — Metro serves the UI, not the
+  endpoints.
+- `LOAD_AUTH` is a bearer or cookie header for that API.
+- The write-once `routes.setup.ts` here probes a parameterless GET endpoint and
+  fails on a **401**, not on a redirect: an API 401 keeps the URL, so the
+  page-route redirect probe would pass vacuously on a dead session.
+
+Mutations are excluded by default here too. See flawless-expo for the native plane's
+other differences.
+
+## Never
+
+- Never run pipes against `next dev`, or without the curl probe.
+- Never read "N pipes pass" as meaning anything until `$LOAD_ID` was proven
+  non-empty and the probe returned authed content.
+- Never refresh a baseline without explaining the shift where the next reader will
+  find it.