@prestyj/cli 5.28.1 → 5.29.0

package/assets/skills/durable/references/backups-and-runtime.md

@@ -1,6 +1,8 @@
 # Durable — backups, recovery & runtime data safety
 
-Load for any backup, recovery, or runtime finding. `SNAPSHOT` = sourced 17 August 2026 — provider tiers and defaults change often; verify before asserting.
+Load for any backup, recovery, or runtime finding. `SNAPSHOT` = sourced 3 October 2026 — provider tiers and defaults change often; verify before asserting.
+
+Contents: Part 1 — RPO/RTO, tiers, provider snapshot, restore drill, uploads. Part 2 — idempotency/outbox, poolers, SQLite, atomic files.
 
 ## Part 1 — Backups & recovery
 
@@ -20,19 +22,24 @@ Pick both consciously; they dictate the tier. An app where users type for hours
 
 **3-2-1 floor**: at least 3 copies, 2 different media/systems, 1 off-site (different provider or account is fine). A dump cron writing to the same VPS is one disk failure from zero.
 
-### Managed-provider baselines (`SNAPSHOT` 17 Aug 2026 — verify tiers/retention before quoting)
+### Managed-provider baselines (`SNAPSHOT` 3 Oct 2026 — verify the project's actual settings before quoting)
 
-| Provider | What you get by default/on paid tiers |
+| Provider | What the docs say |
 |---|---|
-| Supabase | Pro: 7-day PITR included; daily logical backups; restore lands a new project |
-| Neon | Continuous WAL archive; PITR up to 30 days on higher tiers; branching doubles as time-travel |
-| AWS RDS | Automated backups 1–35 days (PITR); manual snapshots on demand |
-| Crunchy Bridge | 14-day PITR by default; longer via S3 archive |
-| MongoDB Atlas | Continuous backup / cloud snapshots by tier |
+| Supabase | Daily backups: Pro 7 days, Team 14, Enterprise up to 30. PITR is a paid **add-on** (Pro+, needs at least Small compute). Backups exclude Storage objects — restoring does not bring back deleted files. Custom-role passwords not in daily backups |
+| Neon | Restore window (WAL history) powers instant restore, time travel, and branching from the past: Free capped at 6 hours (1 GB); Launch default 1 day, max 7; Scale default 1 day, max 30 |
+| PlanetScale Postgres | Scheduled + on-demand backups and PITR via WAL archiving; check the branch's schedule |
+| AWS RDS | Retention 0–35 days; default 1 day via API/CLI, 7 days via console. 0 disables automated backups and PITR |
+| Cloudflare D1 | Time Travel always on: restore to any minute in the last 30 days |
+| Turso | PITR: Free 24 hours; Developer 10, Scaler 30, Pro 90 days; deleted DBs restorable up to 5 days on paid plans |
+| Firestore | Without PITR, version retention is 1 hour; enabling PITR gives 7 days. Scheduled exports for longer history |
+| MongoDB Atlas | Cloud backups / continuous backup by cluster tier — not verified this snapshot; check the cluster's backup policy |
+
+Not re-verified this snapshot (removed): Crunchy Bridge numbers. Aurora: same 1–35 day continuous backup model as RDS — confirm per cluster.
 
 The recurring failure: the free tier's weekly backup or none at all, assumed to be PITR because the marketing page said "backups". Check the project's actual settings, not the provider's homepage.
 
-**Self-hosted Postgres**: pgBackRest, Barman, or WAL-G → S3-compatible storage. **Self-hosted/embedded SQLite**: Litestream (continuous WAL replication to object storage, near-zero RPO) or restic/borg on a schedule as the weaker floor. **Firestore/DynamoDB-style**: scheduled exports to storage — PITR is a paid or absent feature; check the project's state.
+**Self-hosted Postgres**: pgBackRest, Barman, or WAL-G → S3-compatible storage. **Self-hosted/embedded SQLite**: Litestream (continuous replication to object storage). The 2025 rewrite (v0.5.x, `SNAPSHOT`) stores changes as LTX files (sorted page changesets that compact), giving faster point-in-time restores, and uses compare-and-swap leases on object storage to avoid two primaries; configs from 0.3.x need review on upgrade. Weaker floor: `sqlite3 .backup` / `VACUUM INTO` on a schedule, shipped off-machine with restic/borg. **Firestore/DynamoDB-style**: scheduled exports to storage — PITR is a paid or absent feature; check the project's state.
 
 ### The restore drill (the only proof)
 
@@ -42,7 +49,7 @@ The recurring failure: the free tier's weekly backup or none at all, assumed to
 4. Verify the canary is absent. Time the whole operation — that measured duration is the real RTO; write it down.
 5. Repeat on a schedule (quarterly is the common bar); the drill doc itself is the runbook you'll follow at 3am.
 
-**File uploads need their own answer** — DB backups don't cover a disk of user uploads unless the backup includes the volume or the uploads live in object storage with versioning (S3 versioning or equivalent preserves deleted/overwritten objects — turn it on and state the retention). DB row + orphaned-file mismatch is a finding: cleanup discipline (delete file then row, in that order, with the row's file path recorded for resweep) or accept orphans.
+**File uploads need their own answer** — DB backups don't cover a disk of user uploads unless the backup includes the volume or the uploads live in object storage with versioning (S3 versioning or equivalent preserves deleted/overwritten objects — turn it on and add a lifecycle rule for noncurrent versions). For ransomware-grade or compliance retention, S3 Object Lock (requires versioning) stores objects write-once-read-many; use governance mode unless you truly need compliance mode, which nobody — including you — can shorten. A credential that can delete the bucket can delete its backups: keep backup copies in a different account. DB row + orphaned-file mismatch is a finding: cleanup discipline (delete file then row, in that order, with the row's file path recorded for resweep) or accept orphans.
 
 ### What a backup must exclude/include
 
@@ -63,7 +70,7 @@ Check-then-act without a constraint (`if not exists: insert`) is a bug that just
 
 ### Connection & session pitfalls (correctness, not speed)
 
-- **Transaction-mode poolers** (PgBouncer/Supavisor, Neon pooler, RDS Proxy defaults): each transaction may run on a different connection — session state breaks. Casualties: session-level `SET`/`prepared statements` (named ones), advisory locks, `LISTEN/NOTIFY`, temp tables, `COPY`. Patterns: keep per-transaction state in SQL (`SET LOCAL`), use `pg_advisory_xact_lock` (transaction-scoped), or route state-needing work to a direct/session connection.
+- **Transaction-mode poolers** (PgBouncer, Supabase port 6543 — Supavisor on the shared pooler, PgBouncer on the dedicated one; port 5432 is direct or session mode — Neon's `-pooler` endpoint which runs PgBouncer, RDS Proxy): each transaction may run on a different connection — session state breaks. Protocol-level named prepared statements work through PgBouncer ≥ 1.21 when `max_prepared_statements` is non-zero (on by default, 200, since PgBouncer 1.24; SQL-level `PREPARE` still breaks). Self-hosted PgBouncer: run ≥ 1.26.0 (23 Sep 2026), which fixes pre-auth crash/hang CVEs (CVE-2026-19888, CVE-2026-6668) and CVE-2026-6669 (`SNAPSHOT`). Run migrations over a **direct/session** connection, not the transaction pooler. Other casualties: session-level `SET`, advisory locks, `LISTEN/NOTIFY`, temp tables, `COPY`. Patterns: keep per-transaction state in SQL (`SET LOCAL`), use `pg_advisory_xact_lock` (transaction-scoped), or route state-needing work to a direct/session connection.
 - **Serverless functions**: one pool per *instance* (module scope), never per request; assume the process freezes between invocations — no in-memory "it'll flush later".
 - **Postgres connections are processes** — exhausting them fails every new client; the fix is a pooler, not a bigger `max_connections`. (Sizing the pool for throughput is lean's lane.)
 - **Always release/close in `finally`** — a leaked connection per request is a slow outage and a durability finding.
@@ -83,4 +90,4 @@ Check-then-act without a constraint (`if not exists: insert`) is a bug that just
 
 ---
 
-**Provenance:** snapshot 17 August 2026. Sources: Postgres WAL/PITR documentation and pgBackRest/Barman/WAL-G docs, Litestream documentation (SQLite WAL replication), provider documentation for Supabase/Neon/RDS/Crunchy/MongoDB Atlas backup tiers (tier specifics are `SNAPSHOT` — they change often), PgBouncer documentation (transaction-mode feature matrix), SQLite documentation (WAL, busy_timeout, foreign_keys pragma, VACUUM INTO), current disaster-recovery practice guides (3-2-1, RPO/RTO, restore drills). Provider tiers and defaults decay fastest — re-verify before asserting.
+**Provenance:** snapshot 3 October 2026. Accessed 3 Oct 2026: https://supabase.com/docs/guides/platform/backups ; https://neon.com/docs/introduction/restore-window ; https://planetscale.com/docs/postgres/backups ; https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithAutomatedBackups.BackupRetention.html ; https://developers.cloudflare.com/d1/reference/time-travel/ ; https://docs.turso.tech/features/point-in-time-recovery ; https://cloud.google.com/firestore/native/docs/use-pitr ; https://fly.io/blog/litestream-revamped/ ; https://litestream.io/ ; https://www.pgbouncer.org/config.html ; https://www.pgbouncer.org/changelog.html ; https://neon.com/docs/connect/connection-pooling ; https://supabase.com/docs/guides/database/connecting-to-postgres ; https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html . Earlier sources: Postgres WAL/PITR documentation and pgBackRest/Barman/WAL-G docs, Litestream documentation (SQLite WAL replication), provider documentation for Supabase/Neon/RDS/Crunchy/MongoDB Atlas backup tiers (tier specifics are `SNAPSHOT` — they change often), PgBouncer documentation (transaction-mode feature matrix), SQLite documentation (WAL, busy_timeout, foreign_keys pragma, VACUUM INTO), current disaster-recovery practice guides (3-2-1, RPO/RTO, restore drills). Provider tiers and defaults decay fastest — re-verify before asserting.

package/assets/skills/durable/references/migrations-and-schema.md

@@ -1,6 +1,6 @@
 # Durable — migrations & schema
 
-Load for any migration or schema finding. Postgres examples dominate because it is the default; MySQL and SQLite divergences are called out. `SNAPSHOT` = sourced 17 August 2026 — version behaviors decay, verify before asserting.
+Load for any migration or schema finding. Postgres examples dominate because it is the default; MySQL and SQLite divergences are called out. `SNAPSHOT` = sourced 3 October 2026 — version behaviours decay, verify before asserting. Run every migration on a branch or copy first, and obey SKILL.md's agent gate before applying anything to a database that may hold real data.
 
 ## The one rule that prevents most downtime
 
@@ -22,18 +22,24 @@ Rollback at any point is "flip back to the old path", not "restore the database"
 
 ## Lock-safety table (Postgres)
 
-What common DDL actually does to a live table (`SNAPSHOT` — verify per version):
+What common DDL actually does to a live table (`SNAPSHOT` — verify per version).
+
+**Always set `SET lock_timeout = '5s'` (and a `statement_timeout`) before DDL on a live table.** An `ALTER` queued behind a long transaction blocks every query behind it; the timeout turns that outage into a retryable failure. `CONCURRENTLY` operations cannot run inside a transaction block — keep them in their own migration (many ORMs wrap migrations in a transaction by default).
 
 | Operation | Behavior | Safe pattern |
 |---|---|---|
 | `ADD COLUMN` (no default) | Fast, brief lock | Fine as-is |
 | `ADD COLUMN ... NOT NULL DEFAULT x` | Fast since Postgres 11 (default not backfilled); table rewrite before 11 | Fine on ≥11; otherwise add nullable → backfill → `SET NOT NULL` |
-| `SET NOT NULL` on existing column | Full-table scan under lock | Backfill first, then set; or add a `CHECK` constraint `NOT VALID` then `VALIDATE`, then switch |
+| `SET NOT NULL` on existing column | Full-table scan under lock | Backfill first. Postgres 18: `ADD CONSTRAINT … NOT NULL col NOT VALID`, then `VALIDATE CONSTRAINT`. Older: `CHECK (col IS NOT NULL) NOT VALID` → `VALIDATE` → `SET NOT NULL` (uses the valid check, skipping the scan) → drop the check |
 | `CREATE INDEX` | Blocks writes for the whole build | `CREATE INDEX CONCURRENTLY` (drop with `DROP INDEX CONCURRENTLY`); slower, non-transactional — if it fails, drop the invalid index and retry |
 | `ADD FOREIGN KEY` | Locks while validating all rows | Two-step: `ADD CONSTRAINT ... NOT VALID` then `VALIDATE CONSTRAINT` (weaker lock) |
 | One giant `UPDATE`/`DELETE` | Locks rows, bloats the table, stalls replication | Batch: keyset-select N rows → update → sleep → repeat, resumable from last key |
 | `DROP COLUMN` | Fast (metadata) — but data is gone | Only in the contract phase, after dual-write is verified dead |
 
+**Postgres 18 notes** (`SNAPSHOT`, released 25 Sep 2025): `uuidv7()` built in; generated columns are now **virtual by default** (computed on read — say `STORED` if you need it materialised or indexed); `pg_upgrade` keeps planner statistics (not extended statistics), so post-upgrade slow plans are less likely; new clusters get data checksums by default and `pg_upgrade` needs matching checksum settings (`initdb --no-data-checksums` for old non-checksum clusters); asynchronous I/O via `io_method`. **Postgres 13 reached end of life on 13 November 2025** — no more security or data-corruption fixes; flag any project on ≤13 as High.
+
+**Tools that automate expand/contract** (`SNAPSHOT`, verify maturity before recommending): pgroll (Xata; serves old and new schema versions via views during a migration), Reshape (same idea, less active), and migration linters — Squawk (Postgres SQL lint), `strong_migrations` (Rails), `django-pg-zero-downtime-migrations` / `django-migration-linter` (Django). For Laravel, no equivalent gem is verified here — review SQL with `php artisan migrate --pretend`.
+
 MySQL has no `CONCURRENTLY`: use `ALGORITHM=INSTANT/INPLACE` where the version supports it, `gh-ost` or `pt-online-schema-change` for big tables (`SNAPSHOT` — both maintained; verify current). Postgres big-table rebuilds (PK change, deep bloat, partitioning): `pg_repack`, which rebuilds online with minimal locking and needs ~2x disk temporarily.
 
 ## Resumable backfill skeleton
@@ -54,8 +60,9 @@ From application code the same shape applies: select batch by `id > last`, write
 ## Migration tooling discipline
 
 - **Versioned, checked-in migrations from the first table** — Alembic (Python), Flyway/Liquibase (JVM), golang-migrate (Go), sqlx/Diesel (Rust), Drizzle Kit / Prisma Migrate (TS). Hand-run SQL files and "schema.sql we run sometimes" are how drift starts.
-- **Review generated SQL before it touches anything real.** ORM migration generators emit what the schema diff implies: renaming a column in the schema file becomes `DROP COLUMN` + `ADD COLUMN` — the data is dropped. Prisma flow: `migrate dev --create-only`, read the SQL, fix it to a safe expand-contract, then apply. Drizzle: generate, then read the SQL before `migrate`. This review is the single highest-value habit in this file.
-- **`db push`/sync-style commands are for throwaway dev databases only.** They bypass migration history; on a database with data they can apply destructive diffs without review. If a deploy script or CI contains `db push` against anything shared or persistent, that is a finding.
+- **Review generated SQL before it touches anything real.** ORM migration generators emit what the schema diff implies: renaming a column in the schema file becomes `DROP COLUMN` + `ADD COLUMN` — the data is dropped. Prisma flow: `migrate dev --create-only`, read the SQL, fix it to a safe expand-contract, then apply. Drizzle: `drizzle-kit generate`, read the SQL, then `drizzle-kit migrate`. This review is the single highest-value habit in this file.
+- **Prisma 7** (`SNAPSHOT`, Nov 2025): Rust-free TypeScript client via the `prisma-client` generator with a required `output`, driver adapters required, config in `prisma.config.ts`, and automatic seeding after migrate removed. Migration semantics are unchanged: `migrate dev` (dev only, may prompt to reset), `migrate deploy` (production, applies pending only), `migrate reset` (drops everything — agent-gated, see SKILL.md). Upgrading v6→v7 is a client/config change; it should not create a migration — if a diff appears, read it.
+- **`db push` / `drizzle-kit push` / sync-style commands are for throwaway dev databases only** (Drizzle documents push as its rapid-prototyping path). They bypass migration history; on a database with data they can apply destructive diffs without review. If a deploy script or CI contains `db push` against anything shared or persistent, that is a finding.
 - **Never edit an applied migration.** The hash changes, history diverges, teammates' databases desync. Corrections are new migrations.
 - **Forward-only in production.** Down migrations cannot faithfully reverse a migration that touched data (you cannot un-drop a column). "Rollback" is a new forward migration that reverses the change, written and tested like any other. Down migrations are a dev convenience at most.
 - **Apply migrations as a distinct step before the new code rolls out** (deploy script step or pre-deploy Job), never lazily on first request, never concurrently from every replica. One applier, ordered, recorded.
@@ -76,4 +83,4 @@ From application code the same shape applies: select batch by `id > last`, write
 
 ---
 
-**Provenance:** snapshot 17 August 2026. Sources: Postgres documentation (DDL locking behavior, `CONCURRENTLY`, `NOT VALID`/`VALIDATE`, ADD COLUMN default fast-path), current zero-downtime migration practice guides (expand-contract/parallel-change, batched keyset backfill, forward-only production, pre-deploy application), Prisma/Drizzle documentation (create-only review workflow, `db push` scope), MySQL online-schema-change tooling (gh-ost, pt-online-schema-change) public docs. Version-specific lock behavior decays fastest — re-verify against the running version before asserting.
+**Provenance:** snapshot 3 October 2026. Accessed 3 Oct 2026: PostgreSQL 18 release notes https://www.postgresql.org/docs/18/release-18.html and announcement https://www.postgresql.org/about/news/postgresql-18-released-3142/ ; versioning policy (13 EOL) https://www.postgresql.org/support/versioning/ ; Prisma 7 https://www.prisma.io/blog/announcing-prisma-orm-7-0-0 and https://www.prisma.io/docs/guides/upgrade-prisma-orm/v7 ; Drizzle push https://orm.drizzle.team/docs/drizzle-kit-push . Earlier sources: Postgres documentation (DDL locking behavior, `CONCURRENTLY`, `NOT VALID`/`VALIDATE`, ADD COLUMN default fast-path), current zero-downtime migration practice guides (expand-contract/parallel-change, batched keyset backfill, forward-only production, pre-deploy application), Prisma/Drizzle documentation (create-only review workflow, `db push` scope), MySQL online-schema-change tooling (gh-ost, pt-online-schema-change) public docs. Version-specific lock behavior decays fastest — re-verify against the running version before asserting.

package/assets/skills/evidence-led-ui/SKILL.md

@@ -1,158 +1,100 @@
 ---
 name: evidence-led-ui
-description: Use for web/mobile UI creation, redesign, visual polish, accessibility work, and UI review, including small styling fixes and changes to focus, control states, borders, or dropdown icons. Use the small-edit path for narrow changes. Exclude behavior-only wiring unrelated to visual states, copy-only changes, database/API schemas, CLI output, standalone image/SVG generation, and description-only tasks.
+description: Use when building or changing web/mobile UI: net-new screens or pages, redesigns, design systems, visual polish, UI review, and mid-build edits touching colour, type, spacing, icons, focus/hover/selected states, borders, dropdown icons, motion, or UI copy layout. Also use when output looks generic or AI-made. Small styling fixes take the small-edit path. Do NOT use for behavior-only wiring with no visual state, copy-only text changes, database/API schemas, CLI output, or standalone image generation; speed/bundle work is lean, legal/privacy review of public pages is compliance-guard.
 license: See LICENSES.md
-compatibility: Full review requires filesystem inspection and rendered screenshots; web research and browser/device tooling are optional and unavailable checks must be reported honestly.
+compatibility: Full review requires filesystem inspection and rendered screenshots (deferred `screenshot` tool); web research and device tooling are optional and unavailable checks must be reported as unverified.
 ---
 
 # Evidence-Led UI
 
-Use this skill for web or mobile interface creation, redesign, implementation, styling, and review.
+Pick your mode, then follow only that section:
 
-## Small-edit path
-
-For a narrow styling or control-state fix, skip the broad design workflow, not verification:
-
-1. Read the shared primitive, tokens, state rules, and affected callers. Reproduce the reported sequence before editing.
-2. For focus, borders, glass effects, or dropdown icons, read `references/craft-rulings.md` § Control icon insets and § No sticky pointer focus. Identify the rule drawing the defect before adding an override.
-3. Fix the shared owner, not each screen. Check affected variants and remove superseded local treatments within scope. Any supporting copy added or changed must pass § Copy must earn its space in `references/craft-rulings.md`; small edits must not accumulate redundant descriptions.
-4. Run the applicable interaction regression matrix in the craft rulings using the project's browser checks or manual browser verification. Screenshots alone cannot pass interaction checks. Report actual evidence and any unverified platform.
-
-## Governing rule
-
-Inspect before inventing. Preserve the project's visual language unless the user explicitly requests a redesign. Treat corpus findings as conditional observations, not official brand truth, universal rules, or a house style.
-
-Aesthetic distinction is contextual. Semantic structure, operability, responsive stability, performance, honest content, accessibility, and user trust are the non-negotiable floor.
-
-## Binding craft defaults
-
-Apply these on every UI task. Read `references/craft-rulings.md` when implementing or reviewing their details.
-
-- **No emoji UI:** Never use emoji as icons, bullets, status marks, or decoration unless explicitly requested. Reuse the project icon system; otherwise use one coherent icon package.
-- **Uniform geometry:** Align containers, columns, section edges, baselines, dividers, control heights, and repeated component anatomy. Break alignment only for a clear content reason.
-- **One shared content rail:** Default navigation, header, main content, footer, and adjacent sections to the same max-width, inline gutters, and breakpoint padding. Full-bleed backgrounds may differ, but their inner content edges must align. Any different width or offset needs an explicit user or content reason, never one-off margin or padding.
-- **No edge-hugging control icons:** Select, dropdown, and combobox chevrons and other trailing icons need a deliberate inline-end inset plus enough reserved text padding for the icon and gap. They must never touch the control edge or overlap content; use logical properties so the anatomy also works in RTL.
-- **Reuse first:** Search for existing components, variants, tokens, utilities, icon wrappers, focus rings, and motion curves before creating new ones.
-- **Purposeful feedback:** Relevant hover, focus, press, selected, expanded, loading, success, and error states need clear feedback. Avoid abrupt changes when a short transition improves continuity.
-- **No soft semantic tint-on-tint:** Do not default badges, buttons, toasts, cards, selected states, or icon medallions to a low-opacity semantic-color background with saturated same-hue text or icons, with or without a matching border. Unless the user explicitly requests that treatment or an established system must be preserved, choose a product-specific alternative rather than imposing one universal replacement style.
-- **Focus is not selection or decoration:** Diagnose the actual painted layer before changing it. Reuse one shared focus treatment, separate from glass borders/reflections and selected, expanded, or error states. Do not stack local rings on it. Prevent stale pointer-originated highlights without blurring controls, suppressing keyboard focus, or removing legitimate state cues. Prefer native `:focus-visible` behavior; custom modality handling requires a reproduced platform defect and the regression matrix in `references/craft-rulings.md`.
-- **No generic hover lift:** Do not default to `translateY`, bobbing, floating, or scale-up on hover. Prefer color, border, underline, icon fill, opacity, or restrained shadow changes.
-- **No `transition: all`:** Name transition properties, reuse duration/easing tokens, and provide a reduced-motion path.
-- **Intentional type:** Reuse the existing type system. For net-new web work, select an appropriate modern family or pairing; do not use Arial, Helvetica, or bare `system-ui` as the aesthetic direction.
-- **WCAG 2.2 Level AA is the accessibility floor:** Every web UI and complete user flow must meet every applicable Level A and Level AA success criterion, not a hand-picked subset. Native apps apply WCAG2ICT where relevant plus current platform accessibility requirements. Stricter project, contract, platform, or jurisdiction rules win; accessibility cannot be traded for aesthetics, scope, delivery speed, or a higher rubric score.
-- **No unsupported accessibility claims:** Treat ADA as an equal-access legal obligation, not a badge earned by Lighthouse, axe, or another scanner. Never label a UI `ADA compliant` or `WCAG conformant` from source review or automated checks alone; a claim requires a defined scope, per-criterion evidence, manual keyboard and assistive-technology testing, and qualified legal or product-owner review when legal compliance is asserted.
-- **Measured contrast:** Meet WCAG 2.2 contrast for text, controls, icons, focus, and meaningful graphics. Muted text must remain readable.
-- **Consistent flow:** Repeated navigation and actions keep the same order, labels, icons, placement, and behavior across sections and pages.
-- **Copy must earn its space:** Start with clear labels, controls, and relevant status, not automatic subtitles, helper paragraphs, or footer notes. Supporting text must add information needed here that the interface does not already communicate. Remove repetition, show state-specific guidance when needed, and move optional detail into contextual help. Keep essential instructions and consequences visible before action. Reduce unnecessary copy before compressing layout; verify reading effort in the rendered UI. See `references/craft-rulings.md` § Copy must earn its space.
-- **No generated em dashes:** Do not write em dashes in user-facing UI copy unless explicitly requested or exact supplied source text must remain unchanged.
-
-## Reference map
-
-Resolve every path from the installed skill root. Load only what the task needs:
-
-- `references/craft-rulings.md`: implementation detail for the binding defaults above.
-- `references/ui-libraries.md`: real Bklit/Kokonut component discovery/adoption and Motion APIs. Read for relevant React UI creation after checking existing project UI; use deferred `ui_registry` and `ui_adopt` rather than inventing a library lookalike.
-- `references/production-contract.md`: binding pass/fail semantics, WCAG/ADA accessibility, forms, performance, resilience, platform, trust, AI, media, theme, and release checks. Read its accessibility sections for every implemented or reviewed UI; read the full contract for broad features, behavior changes, forms, navigation, data/AI interfaces, native work, performance work, or release review.
-- `references/archetypes.md`: surface-specific direction and relevant source slugs. Read for net-new UI, redesigns, or unresolved visual direction.
-- `references/observed-patterns.md`: measured corpus observations. Read only sections that answer a real design question.
-- `references/anti-defaults.md`: transferable AI-generated patterns to challenge. Read for broad visual work or generic-looking output.
-- `references/quality-rubric.md`: rendered scoring and revision gate. Read before critiquing broad output.
-- `references/methodology.md`: extraction method, denominators, and limitations. Read only to audit evidence.
-- `references/provenance.md` and `LICENSES.md`: sources, licenses, standards status, and Refero boundaries.
-
-Do not load `data/observations.json` or the raw corpus by default. Open a raw source only to audit one claim or inspect one selected exemplar. Never load the full corpus into context.
-
-## Workflow
+| Situation | Mode | Go to |
+| --- | --- | --- |
+| One control, state, border, icon inset, focus bug, or token tweak | Small edit | § Small-edit path |
+| New screen/page/component, redesign, or "make it look less generic" | Build | § Build loop |
+| "Review this UI", audit screens or flows, pre-ship look | Review | § Review mode |
 
-### 1. Inspect the project
+Every mode obeys § Binding defaults. Preserve the project's visual language unless the user asked for a redesign.
 
-Inspect the nearest relevant routes, real content, shared components, semantic controls, tokens, theme, typography, icons, motion, screenshots, tests, responsive conventions, and existing states.
-
-Reuse the local system. Do not add a design library merely to obtain a look. For a net-new project with no neighbors, derive direction from the brief and matching archetype rather than choosing a fashionable default.
-
-### 2. Write a design read
-
-Resolve:
-
-- **Surface:** marketing, application UI, dashboard/data-dense, commerce/marketplace, editorial/content, documentation/developer tool, mobile/native, or one named hybrid with a clear leader.
-- **Audience:** user, expertise, environment, and access needs.
-- **Single job:** the one outcome this screen must make easiest.
-- **Task and risk:** frequency, decision cost, error cost, and time pressure.
-- **Content:** real hierarchy, density, variability, media, data, and longest plausible values.
-- **Platform:** viewport/window, input modes, support policy, navigation behavior, and framework conventions.
-- **Constraints:** existing tokens/assets, redesign scope, performance limits, and required tone.
-
-Infer missing facts from the project and state the inference. Ask only when code cannot resolve a genuine product or taste decision.
-
-### 3. Select evidence only when it helps
-
-For broad net-new work or a redesign, read the matching archetype and usually choose two aligned source slugs plus one contrast. Record why each applies.
-
-For a small change in an established system, local components and tokens may be sufficient. A frequency can support investigation, not automatically become a recommendation. Prefer local product evidence, then archetype evidence, then corpus-wide frequency.
-
-Refero is optional. Use it only through an authorized Refero MCP or user-provided authorized export. Do not scrape Refero, call undocumented endpoints, or access disallowed routes.
-
-### 4. Form one design thesis
-
-State one compact direction:
-
-- semantic color/type/icon/spacing/grid/motion roles and a reuse map;
-- first glance, second glance, primary action, and supporting evidence;
-- composition and uniform alignment rules;
-- reasons for borders, surfaces, shadows, blur, gradients, or imagery;
-- feedback, duration/easing, resting behavior, and reduced-motion equivalent;
-- one memorable device grounded in the subject, content, or interaction.
-
-One thesis leads. Do not combine several aesthetic directions into a mood-board compromise.
+## Small-edit path
 
-### 5. Run the anti-default check
+Skip the design workflow, not verification:
 
-For broad visual work, read `references/anti-defaults.md`. Flag emoji UI, mixed icon families, arbitrary misalignment, duplicated local styling, abrupt interaction, generic hover lift, soft semantic tint-on-tint treatments, generic type, generated em dashes, centered gradient heroes, glass cards, equal card grids, decorative eyebrows, random metric blocks, ubiquitous pills, dark-premium assumptions, fake terminals, floating screenshots, bento layouts, ambient motion, icon medallions, and invented proof.
+1. Read the shared primitive, tokens, state rules, and callers. Reproduce the reported sequence before editing.
+2. Focus, borders, glass, or dropdown icons: read `references/craft-rulings.md` § Control icon insets and § No sticky pointer focus. Find the rule that paints the defect before adding an override.
+3. Fix the shared owner, not each screen. Check variants; remove superseded local treatments in scope. Added copy must pass § Copy must earn its space.
+4. Run the applicable interaction regression matrix in `references/craft-rulings.md` via browser checks. Screenshots alone cannot pass interaction checks. Report actual evidence and unverified platforms.
 
-Keep a flagged pattern only after completing: **“This belongs because…”** with a product-specific reason. Replace choices that could survive unchanged in an unrelated product.
+## Build loop
 
-### 6. Plan the complete task flow
+One design thesis, one author. Do not blend directions.
 
-Plan only relevant states, but include the complete primary path and recovery:
+1. **Inspect.** Read nearest routes, components, tokens, type, icons, motion, and states. Reuse the local system; add no library just for a look. React and nothing local fits: read `references/ui-libraries.md` and use `ui_registry`/`ui_adopt` (via `tool_search`) for real Bklit/Kokonut source, never a lookalike.
+2. **Content first.** Write real headline, labels, section copy, and realistic data (longest, empty, 0/1/many) before layout. Rank it. Delete sections with nothing true to say. Never invent metrics, testimonials, logos, or ratings; label fixtures. Details: `references/direction.md` § 1.
+3. **Read the job.** Surface type, audience, single job, risk, platform, constraints. Infer from the project and state the inference; ask only for genuine taste or product decisions. Net-new or redesign: read the matching section of `references/archetypes.md`.
+4. **Write the thesis** using the template in `references/direction.md` § 2: signature, type roles, OKLCH colour tokens with intended contrast pairs, spacing/density, radius/material, imagery, motion, rejected defaults. Broad work goes in `DESIGN.md`.
+5. **Slop check the thesis** against `references/anti-defaults.md`. Every tell is replaced or justified with "This belongs because…". Run the neighbour test (§ 7 there).
+6. **Plan states:** loading, empty, error, retry, success, disabled, destructive; hover, focus-visible, press, selected, expanded, pending; keyboard order, overlays, narrow/wide, reduced motion, zoom/reflow, long and localized text. Apply the accessibility sections of `references/production-contract.md`; the full contract for forms, navigation, data/AI, native, or release work.
+7. **Implement** the complete flow with real content. Decision-critical information and the primary action stay visible or one obvious action away on desktop and mobile.
+8. **Verify rendered output** (§ Rendered verification loop).
 
-- loading, empty, error, retry, offline, success, disabled, and destructive outcomes;
-- hover, focus-visible, press, selected, expanded, and pending feedback;
-- keyboard order, accessible names/status, overlay focus, and drag alternatives;
-- pointer-versus-keyboard focus behavior, including native popup dismissal and clicks onto non-focusable space;
-- narrow, intermediate, desktop, wide/resizable, pointer, touch, and no-hover behavior;
-- reduced motion, forced colors, zoom/reflow, long/localized/RTL text, missing media, and realistic data extremes;
-- text alternatives and media equivalents, landmarks/headings, language, labels/instructions/errors, status announcements, timing, flashing, and sensory-independent instructions where applicable.
+## Rendered verification loop
 
-For every UI, read and apply the accessibility sections of `references/production-contract.md`. For broad behavior, forms, navigation, native, data/AI, performance, or release work, apply the full contract. A visual score cannot compensate for a relevant contract failure.
+1. Load `screenshot` via `tool_search`. Capture desktop (~1440 px) and mobile (~390 px), plus key states.
+2. Compare each capture against the written thesis line by line, then against `references/anti-defaults.md`.
+3. Score with `references/quality-rubric.md`. Measure contrast of real rendered pairs; record pass/fail/unverified for applicable contract checks.
+4. Fix the weakest criterion and every contract failure. Remove one decorative idea that does not serve the job. Re-capture.
+5. Stop after one revision unless the gate still fails. Gate: **20/24 or higher**, no zero in accessibility, consistency and flow, responsive behaviour, state completeness, or content authenticity, and no applicable WCAG A/AA failure. Small components: 2 on every applicable floor criterion.
 
-### 7. Document broad work
+No screenshot tool or browser available: say so, mark visual checks unverified, never claim the look was verified.
 
-For a broad page, multi-screen feature, or redesign, create or update `DESIGN.md` with the design read, evidence, thesis, semantic tokens, reused primitives, craft system, components/states, responsive behavior, and applicable production checks. Keep a small component plan in work notes instead.
+## Review mode
 
-### 8. Implement the product
+Inspect code and rendered output. Return findings ordered by impact, each with screenshot or file:line evidence, label (`RUNTIME` observed, `CODE` read in source, `DEDUCED`, `SNAPSHOT` dated source), and the fix. Separate floor defects (accessibility, states, broken layout) from aesthetic opportunities (slop tells). Recommend one resolved direction.
 
-Use real project content and data. Label fixtures honestly. Never invent testimonials, customer logos, ratings, metrics, or claims as fact.
+## Binding defaults
 
-Reuse dependencies and primitives. Use one coherent icon system. Meet every applicable WCAG 2.2 Level A and AA criterion across the complete flow, including its states and responsive variants. Maintain semantic controls, visible keyboard focus, keyboard operation, assistive-technology output, measured contrast, readable line lengths, stable adaptive layout, and reduced-motion support. Pointer interaction must not leave a false focus, active, or selected-looking highlight behind. Implement the complete planned flow, not only its first screenshot.
+Details and fixes: `references/craft-rulings.md`.
 
-The representative initial state must keep decision-critical information and the primary action visible or one obvious action away on desktop and mobile. Preserve selected context through master-detail recomposition. Keep demo, debug, and state-switching controls subordinate and non-obscuring.
+- **No emoji UI.** One coherent icon family; reuse the project's.
+- **Uniform geometry and one content rail.** Shared max-width, gutters, and breakpoint padding for nav, header, main, footer. Break alignment only for a stated content reason.
+- **Control icon insets.** Chevrons and trailing icons get a deliberate inline-end inset plus reserved text padding; never touch the edge or overlap text; logical properties for RTL.
+- **Reuse first.** Existing components, variants, tokens, focus rings, motion curves before new ones.
+- **Focus is not selection or decoration.** Diagnose the painted layer; one shared focus treatment separate from borders, glass, selected, expanded, error. No stacked rings. Prefer native `:focus-visible`; custom modality handling needs a reproduced defect and the regression matrix.
+- **No soft semantic tint-on-tint** unless requested or required by an existing variant.
+- **Motion:** no generic hover lift, no `transition: all`, named properties, tokens, reduced-motion path.
+- **Intentional type and colour:** see `references/direction.md`. Not Inter/violet-gradient by default on brand surfaces.
+- **Copy must earn its space.** No automatic subtitles, helper paragraphs, or footer notes; supporting text adds information the interface lacks. Named-outcome CTAs.
+- **No em dashes in UI copy** unless requested or exact supplied copy.
+- **WCAG 2.2 Level AA is the accessibility floor** for every applicable A/AA criterion across complete flows; native apps add WCAG2ICT and platform rules. Stricter project or legal rules win. Accessibility is never traded for aesthetics or speed.
+- **No unsupported accessibility claims.** Never say `ADA compliant`, `WCAG conformant`, or "accessible" from source review or scanners; that needs a defined scope, per-criterion evidence, manual keyboard and assistive-technology testing, and owner/legal review. Dated legal context: `references/production-contract.md` § 2.
 
-### 9. Critique rendered output once
+## Scaling: one agent or several
 
-Capture representative desktop and narrow/mobile output. Score broad work with `references/quality-rubric.md`, record applicable production checks as pass/fail/unverified, remove one unnecessary decorative idea, revise the weakest criterion and any contract failure, then re-capture.
+| Situation | Policy |
+| --- | --- |
+| Small edit, build, redesign | Main thread only. One thesis, one author; never split a design across children. |
+| Review of one or two flows you can render and read yourself | Main thread only. |
+| Review of many screens/flows, or several apps | Build a ledger: rows = flows/screens × {slop tells, states, accessibility contract, responsive}. Fan out read-only general-purpose children (they have the `skill` tool), one per disjoint flow, all in ONE `spawn_agent` call, ≤ 6 per wave. |
+| A dated legal or platform claim needs checking | One `researcher` child. |
 
-Default to one critique-and-revision cycle. Run another only when evidence still fails the score or production gate. If a check is unavailable, report it as unverified instead of looping or substituting more polish.
+Each child brief contains: the absolute skill root path (the `Skill root directory` shown when this skill loaded), files to read (`references/anti-defaults.md`, `references/quality-rubric.md`, the accessibility sections of `references/production-contract.md`), the flow's routes and how to run the app, the ledger rows it owns, the instruction to capture desktop and mobile screenshots with the `screenshot` tool, the evidence labels, and the output schema: findings (screen, screenshot or file:line, label, severity, fix) plus explicit `checked` and `not checked` lists. Children do not edit.
 
-Broad work is complete at **20/24 or higher**, with no zero in accessibility, consistency and flow, responsive behavior, state completeness, or content authenticity, and only after applicable production checks pass. Any applicable WCAG Level A or AA failure blocks completion regardless of score. A small component must score 2 on every applicable quality-floor criterion and pass its accessibility contract checks.
+Merge: a failed, timed-out, or silent row is `not checked`, never clean. Re-open each reported file:line or re-capture before reporting it. Large pre-ship reviews get one fresh verifier child that tries to disprove the findings. Fixes stay on the main thread (or `bee` children on strictly disjoint files) against the single thesis; run checks once after merging.
 
-## Review-only mode
+## Reference map
 
-Inspect the project and rendered output. Return findings ordered by impact, cite screenshot/code evidence, name the matching archetype when relevant, and recommend one resolved direction. Distinguish quality-floor defects from aesthetic opportunities.
+Load only what the task needs; resolve paths from the skill root.
 
-## Evidence discipline
+- `references/direction.md`: content-first, thesis template, type, OKLCH colour, spacing, imagery, motion, verified Baseline features, INP practice.
+- `references/anti-defaults.md`: slop tells with replacement moves and the neighbour test.
+- `references/craft-rulings.md`: icons, geometry, insets, focus vs selection, regression matrix, type loading, contrast, copy rules.
+- `references/production-contract.md`: pass/fail semantics, WCAG/ADA/EAA context, forms, performance, platform, trust, AI, release evidence.
+- `references/quality-rubric.md`: rendered scoring gate.
+- `references/ui-libraries.md`: Bklit/Kokonut adoption and Motion APIs.
+- `references/archetypes.md`: surface-specific direction and corpus source slugs.
+- `references/observed-patterns.md`: measured corpus observations; read only the section that answers a question; keep numerator/denominator with any claim.
+- `references/methodology.md`, `references/provenance.md`, `LICENSES.md`: method, sources, standards status, licences, Refero boundary.
 
-- Keep a numerator/denominator or numeric sample count with every corpus claim.
-- Treat source slugs as observations of selected public surfaces, not official systems or permission to reproduce a brand.
-- Never recommend a color, font, radius, theme, or layout solely because it is frequent.
-- State corpus gaps plainly. Mobile/native has zero direct documents in this snapshot; use platform guidance and device testing.
-- If local evidence conflicts with corpus evidence, follow the product and record why.
+Never load `data/observations.json` or the raw `corpus/` into context; open one raw source only to audit one claim. Corpus frequencies are observations of public surfaces, not brand truth or a reason to pick a colour, font, or layout. Mobile/native has no corpus documents; use platform guidance. Refero only through an authorized MCP or user export.