@prestyj/cli 5.11.0 → 5.13.0

package/assets/skills/compliance-guard/references/us.md

@@ -0,0 +1,164 @@
+# United States
+
+Snapshot **11 Aug 2026**. Markers: **[V]** verified against a primary/first-tier source · **[S]** snapshot, re-verify · **[U]** contested or fast-moving.
+
+**PRA** = private right of action. This is the field that matters most for a small company: regulator-only laws are a compliance project, PRA laws are a lawsuit.
+
+---
+
+## 0. Scoping reality for a tiny startup
+
+Most **comprehensive state privacy laws will not apply** to a pre-scale product — they need tens of thousands of residents' data or large revenue. But four categories apply **at any size**:
+
+1. FTC Act §5 and state unfair-and-deceptive-practices analogues (most state UDAPs *do* have a PRA).
+2. Breach-notification statutes in every state.
+3. Sector laws: COPPA, HIPAA, GLBA, TCPA, BIPA, consumer-health-data laws.
+4. No-threshold plaintiff statutes: CIPA, BIPA, MHMDA, TCPA, VPPA.
+
+Also note **Texas and Nebraska have no revenue or volume threshold** — they apply to anyone doing business in-state who is not an SBA "small business", and even exempt small businesses may not sell sensitive personal data without consent **[V]**.
+
+**Practical answer:** a US indie app under ~25k users in any single state usually falls outside the comprehensive laws — and is still fully exposed to everything in categories 1–4.
+
+---
+
+## 1. State comprehensive privacy laws
+
+**In force in 2026: 20 states** (CA, VA, CO, CT, UT, TX, OR, MT, IA, DE, NE, NH, NJ, TN, MN, MD, IN, KY, RI, and Florida's narrower law which applies only above $1B revenue) **[V]**. Enforcement is AG-only; penalties commonly $7,500–$10,000 per violation **[V]**. Cure periods are expiring across states **[S]**.
+
+Thresholds range from 25,000 consumers (Montana) to 175,000 (Tennessee); 10,000 consumers where a share of revenue comes from selling data (RI, DE, NH, MD); Maryland pairs a 35,000-consumer threshold with the strictest data-minimisation and sensitive-data rules, and bans the sale of sensitive data outright **[V]**.
+
+**Universal opt-out / Global Privacy Control — the cheapest high-value engineering task.** As of 1 Jan 2026, twelve states require honouring it (CA, CO, CT, DE, MD, MN, MT, NE, NH, NJ, OR, TX); Virginia-template states do not **[V]**.
+
+```
+Read the Sec-GPC: 1 request header and navigator.globalPrivacyControl.
+Treat as an opt-out of sale/share + targeted advertising.
+Apply BEFORE firing any ad pixel. Persist server-side against the user/device.
+Disclose signal handling in the privacy notice.
+```
+Honouring GPC for **every** visitor is the safe default: it satisfies the strictest state and violates none **[V]**.
+
+**Why an ordinary ad pixel triggers everything.** "Sale" requires no money — any disclosure for other valuable consideration counts — and "sharing" expressly covers cross-context behavioural advertising **[V]**. Meta Pixel, GA4 with ad features, TikTok, Reddit and LinkedIn tags are a sale/share/targeted ad in nearly every state. Build: a tag inventory, consent-gated loading, and an opt-out that actually severs the pixel rather than filing a form.
+
+**Sensitive data requires opt-in** in Virginia-model states (precise geolocation, race, religion, health, sex life/orientation, immigration status, biometrics, genetic data, children's data) **[V]**. California instead grants a right to limit use.
+
+**Minors:** opt-in for targeted ads, sale, and profiling for known 13–16 year-olds; Maryland extends to under-18 on a "should have known" standard **[V]**.
+
+**Rights and timing:** access, delete, correct, portability, opt-out, non-discrimination. **45 days, extendable by 45** **[V]**. Virginia-model states require an **appeal** mechanism. California requires two intake methods. Never identity-verify an opt-out — verification is for access/deletion.
+
+**Notice content:** categories collected/sources/purposes/recipients, sensitive-data uses, **retention periods per category** (California), rights and how to exercise them, opt-out-signal handling, appeal process, contact, and a last-updated date with an annual refresh **[V]**.
+
+**Assessments:** written data-protection assessments required in most Virginia-model states for targeted advertising, sale, sensitive data, and risky profiling; retained and producible to the AG **[V]**.
+
+---
+
+## 2. California specifics
+
+**Applicability:** for-profit doing business in CA meeting any one of — annual gross revenue over ~$26.6M (CPI-adjusted), buying/selling/sharing PI of 100,000+ CA consumers or households a year, or 50%+ of revenue from selling/sharing PI **[V]**. Penalties per violation with a higher tier for intentional violations or those involving minors. **Consumers may sue only over certain breaches** ($107–$799 per consumer per incident) — there is no general PRA for policy or opt-out-link failures **[V]**.
+
+**2026 regulations package (effective 1 Jan 2026)** **[V]**:
+- *Risk assessments* — begin 1 Jan 2026, complete for ongoing activities by 31 Dec 2027, first certified reports 1 Apr 2028. Triggered by sensitive PI, targeted ads to minors, ADMT for significant decisions, or training ADMT.
+- *ADMT* — pre-use notice, access, and opt-out for automated decision-making about significant decisions (including employees, contractors, applicants). **Compliance deadline 1 Jan 2027.**
+- *Cyber audits* — only above revenue plus scale thresholds; first certifications from 2028. A pre-revenue startup is out of scope.
+
+**Delete Act / DROP** — if you sell PI of consumers you have no direct relationship with, you are a data broker. **No revenue threshold.** Registration plus, **from 1 Aug 2026**, processing consumer deletion requests through the state mechanism every 45 days with downstream deletion directives; per-day penalties apply whether or not you registered **[V]**. Enforcement has already hit companies of exactly this size. Ask at design review: *do we sell PI of people who never used us?*
+
+**Breach notice (SB 446)** — since 1 Jan 2026, notify affected California residents within **30 calendar days** of discovery, and report to the AG within **15 calendar days** of notifying individuals **[V]**.
+
+**AI transparency (SB 942 as amended by AB 853)** — covered providers are generative-AI systems with **over 1M monthly users**; duties operative 2 Aug 2026, with hosting-platform duties from 1 Jan 2027 **[V]**. Most small devs are out of scope, but the hosting-platform duty catches anyone distributing GenAI systems.
+
+**AB 2013 training-data transparency** — **no size threshold**. Developers of generative AI systems made available to Californians must publish training-data documentation; compliance required from 1 Jan 2026 and on substantial modification **[V]**. Catches small fine-tuners, not mere API consumers.
+
+**SB 243 companion chatbots — the highest-risk new law for small AI apps.** Effective 1 Jan 2026. Applies to chatbots sustaining a relationship or human-like emotional engagement (excludes customer-service bots, limited game NPCs, voice assistants). Requires non-human disclosure, mental-health crisis protocols, and minor protections including blocking sexual content and enforcing breaks. **PRA: YES** — minimum $1,000 damages plus fees, and UCL pairing can reach individuals personally **[V]**.
+
+**Employment ADS regulations** under state anti-discrimination law add notice and recordkeeping duties for automated decision systems **[S]**.
+
+---
+
+## 3. Children and teens
+
+**COPPA amended Rule — full compliance date 22 Apr 2026** **[V]**. Trigger: a child-directed service, or actual knowledge of collecting personal information from under-13s. Mixed-audience services may age-screen. Concrete changes:
+
+- **Separate** verifiable parental consent for disclosing children's data to third parties (including for targeted advertising).
+- New **data-retention limits** and a **published written retention policy** — indefinite retention is prohibited.
+- Broader definition of personal information now expressly including **biometric identifiers** (face templates, fingerprints, voiceprints), government identifiers, phone numbers, audio recordings, and certain geolocation.
+- A written children's information security programme with vendor due diligence.
+- Parent review/deletion flows must cover biometric data.
+
+**App Store Accountability Acts (TX, UT, LA, AL, CA)** — these impose duties on **app developers**, not just the stores **[V]**. Texas SB 2420 is in effect after appellate and Supreme Court refusals to freeze it (which is not a ruling on constitutionality) **[V]**; Utah developer requirements from 6 May 2026; Louisiana 1 July 2026; California 1 Jan 2027 **[V]**. Build: consume the store's age-signal API, branch features on age category, store only a category flag, re-request consent on significant app changes. Some states allow private suits.
+
+**NY SAFE for Kids** — final rules July 2026, effective **25 Jan 2027**, targeting platforms with addictive feeds **[V]**.
+
+**Adult content age verification** — 26 states with live laws following the 2025 Supreme Court decision upholding Texas's law **[V]**. Typical trigger is ≥1/3 sexual material harmful to minors, a few with no threshold. Use a third-party verifier returning a boolean; retain nothing reconstructable; geo-route per state. Several states allow private suits.
+
+**TAKE IT DOWN Act §3 (NCII) — enforced from 19 May 2026, and it reaches tiny platforms** **[V]**. Any site, app or service that hosts user content must publish a plain-language notice-and-removal process usable by **users and non-users**, and remove reported non-consensual intimate imagery — including AI-generated — plus known identical copies **within 48 hours**. Non-compliance is trivially detectable: a regulator just checks whether the notice exists. Build `/report/ncii`, an acknowledgement + 48h SLA timer, hash-based re-upload suppression, and a footer link.
+
+**CSAM reporting** — providers must report apparent child sexual abuse material to the national tipline as soon as reasonably possible after obtaining actual knowledge, with a **one-year preservation** duty; there is no general proactive monitoring mandate **[V]**. Register a point of contact, define an escalation path, and never re-transmit the material except to the tipline or law enforcement.
+
+---
+
+## 4. Health, biometric, genetic, location
+
+**HIPAA usually does *not* cover a direct-to-consumer wellness app** — it reaches covered entities and their business associates. You become a business associate the moment you handle PHI *on behalf of* a covered entity, which requires a BAA, Security Rule compliance, and 60-day breach notice **[V]**. If you are not HIPAA, you are in the consumer-health-data regime below.
+
+**Washington My Health My Data Act — the top small-company landmine.** **No revenue or volume threshold**, in effect since 2024 **[V]**. "Consumer health data" is defined broadly enough to include precise location that could indicate seeking health services. Requires a **standalone** consumer-health-data privacy policy at its own link, **separate consent for collection**, **separate consent for sharing**, and a **distinct signed authorisation to sell**, plus a geofencing prohibition and processor contracts. **PRA: YES**, via the state consumer-protection act, up to $7,500 per violation **[V]**. The first class action targeted an ordinary ad SDK collecting location. Any period tracker, fitness, mental-health, or symptom app — or anything collecting precise location — is squarely in scope. Nevada has a similar regime without a PRA **[V]**.
+
+**Illinois BIPA** — see `lawsuit-vectors.md` §3. Required **before first capture**: written notice of collection and specific purpose, notice of the retention schedule and destruction guidelines, a **written release**, a publicly available retention/destruction policy, no profiting from biometrics, and reasonable-care storage **[V]**. Texas and Washington have AG-enforced analogues.
+
+**Genetic data** — roughly 14 states require separate express consent per purpose and per disclosure; some allow private suits **[S]**. Treat raw DNA as opt-in-per-purpose and get counsel.
+
+**Precise geolocation** — sensitive/opt-in in every Virginia-model state, and health-linked location is consumer health data **[V]**. Request coarse location by default; never ship precise location to ad SDKs.
+
+**FTC Health Breach Notification Rule** — applies to non-HIPAA health apps that can draw data from multiple sources (e.g. platform health data plus user input). Critically, a "breach" includes an **unauthorised disclosure** — firing a health event to an ad pixel is itself reportable **[V]**. 500+ affected means notifying the regulator within 60 days.
+
+---
+
+## 5. AI laws
+
+- **Colorado** — the original AI Act was delayed and then repealed/replaced with a narrower automated-decision framework; assume a scaled-back regime effective **1 Jan 2027** and verify the enrolled text before building **[U]**.
+- **Texas TRAIGA** — effective 1 Jan 2026, reaching out-of-state developers whose AI is accessible to Texas users. Intent-based liability for AI that promotes self-harm, facilitates crime, discriminates, or produces prohibited deepfakes. AG-only with a 60-day cure; **safe harbour for documented NIST AI RMF-aligned compliance** **[V]**. Practical step for a small dev: a one-page RMF-aligned policy plus retained prompt/eval logs.
+- **Illinois HB 3773** — from 1 Jan 2026, using AI with a discriminatory *effect* in employment violates the state human-rights act; intent is no defence **[V]**.
+- **NYC Local Law 144** — annual independent bias audit plus published summary and candidate notice for automated employment decision tools used for NYC roles **[V]**.
+- **Mental-health AI** — Illinois bans AI delivering mental-health treatment or clinical decisions outright; Nevada, Utah and Tennessee restrict or require disclosure; treat "AI therapist" as a **hard gate** **[V]**.
+- **Companion chatbots** — California (PRA), New York (AG-only), Oregon (PRA, from 2027), Washington (from 2027) **[V]**. **Baseline build for any consumer LLM chat:** persistent non-human disclosure, self-harm detection with a crisis interstitial, minor-mode content restrictions and break reminders, retained incident logs.
+- **Frontier-model laws** target training compute far beyond any small developer **[V]**.
+- **Federal posture** — a December 2025 executive order seeks to weaken state AI regulation via litigation and funding conditions, with a DOJ task force operating from January 2026 **[V]**. Do **not** advise a user to ignore state AI law on this basis; the laws remain in force unless and until enjoined.
+
+---
+
+## 6. Cross-cutting federal
+
+- **FTC Act §5** — any statement in your privacy policy, marketing page, app-store listing or in-app copy that is not literally true of your code is deception. Dark patterns in consent and cancellation flows are deception/unfairness; failure to maintain reasonable security is unfairness **[V]**. No federal PRA, but most state UDAP analogues have one.
+- **Consumer Reviews and Testimonials Rule** — prohibits fake, incentivised-by-sentiment, and undisclosed insider reviews, with civil penalties in the tens of thousands per violation; enforcement is active **[V]**.
+- **Negative option / click-to-cancel** — the federal rule was vacated in 2025 and a new rulemaking is under way **[V]**. Do not tell a user they are safe: ROSCA and ~25 state auto-renewal laws still govern, and California's amended law broadened liability **[V]**.
+- **TCPA** — see `lawsuit-vectors.md` §4. Consent records, revocation handling on any channel, quiet hours in the recipient's timezone, DNC scrubbing, carrier campaign registration **[V]**. Exact effective dates of the universal-revocation mandate are reported inconsistently **[U]**.
+- **CAN-SPAM** — accurate headers and subject, advertising identification, **valid physical postal address**, working opt-out honoured within **10 business days** and functional for 30 days after send; you are liable for your sending platform and affiliates **[V]**.
+- **State breach notification** — all states; deadlines and AG-notice thresholds vary; several sector rules add shorter clocks **[V]**.
+- **ADA accessibility** — Title II has fixed rule deadlines for public entities; Title III private-business exposure is driven by private litigation rather than a technical rule **[V]**. WCAG 2.1 AA is the practical benchmark.
+- **GLBA Safeguards Rule** — "financial institution" is far broader than banks and catches many fintech, lending, tax-prep and advisory products: written InfoSec programme, a named qualified individual, MFA, encryption, vendor oversight, and 30-day regulator notice for larger incidents **[V]**.
+- **FCRA** — if you assemble or use consumer reports for employment, tenant, credit or insurance decisions: permissible purpose, **standalone** disclosure plus authorisation, pre-adverse-action packet with a waiting period, adverse-action notice. **PRA: YES**, with heavy class-action volume over standalone-disclosure defects **[V]**.
+- **ECOA/Reg B and FHA** — adverse-action notices with **specific principal reasons** within 30 days. A black-box model that cannot articulate reasons is itself the violation **[V]**. **PRA: YES.**
+
+---
+
+## 7. PRA ranking — what actually produces suits against small companies
+
+1. California CIPA (trackers, pixels, chat widgets, session replay) — $5,000 per violation, no threshold **[V]**
+2. ADA Title III accessibility (plus state statutory damages) **[V]**
+3. TCPA/SMS — $500–$1,500 per message, uncapped **[V]**
+4. Illinois BIPA — per-person statutory damages, a single in-state user suffices **[V]**
+5. Washington MHMDA — up to $7,500 per violation, extremely broad health-data definition **[V]**
+6. Auto-renewal claims via state consumer statutes **[V]**
+7. CCPA breach claims — $107–$799 per consumer, filed reflexively after AG breach reports **[V]**
+8. California SB 243 companion chatbots — new, untested, minimum $1,000 plus fees **[V]**
+9. VPPA — video plus ad pixel, $2,500 per person, circuit split **[U]**
+10. FCRA — standalone-disclosure defects **[V]**
+11. State wiretap analogues beyond California **[U]** on the exact state list
+12. AI employment discrimination — low volume today, rising **[S]**
+
+**Regulator-only (no PRA):** every state comprehensive privacy law except California's breach claim, COPPA, TAKE IT DOWN, TRAIGA, frontier-model laws, SB 942, NYC LL144, Nevada health law, the Delete Act, GLBA, CAN-SPAM, and FTC rules.
+
+---
+
+## 8. Verify before relying
+
+Colorado's replacement AI law text and date · Vermont and Nebraska children's-code dates · the TCPA universal-revocation effective date · VPPA scope · state mini-TCPA and mini-wiretap lists · genetic-privacy specifics per state · SaaS sales-tax nexus.

package/assets/skills/durable/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: durable
+description: Use when user data must not be lost or corrupted — creating the first database/table/schema, writing migrations, backfilling or importing data, any destructive operation (delete, drop, truncate, overwrite), setting up backups or recovery, or moving data between systems; and for "is my data safe", "will I lose my data", "back up my app" checks on existing projects. Any store — SQL (Postgres, MySQL, SQLite), document (Mongo, Firestore), serverless (Supabase, Neon, Turso), files, queues. Do NOT use for query speed or connection-pool sizing (that is lean), access control over data (that is bulletproof), or privacy/legal deletion regimes (that is compliance-guard).
+license: Data-durability engineering guidance, not a DBA certification. Sources and snapshot date are recorded at the foot of each reference file.
+compatibility: Snapshot dated 17 August 2026. Version behaviors (fast-path ALTERs, pooler modes, tool flags) decay — re-verify with web access before asserting them as current.
+---
+
+# Durable
+
+Make user data survive everything: bad migrations, crashed writes, retried webhooks, full disks, dead servers, and the 3am `DELETE` without a `WHERE`. Built for the reality that users forgive slow and ugly; they do not forgive gone.
+
+**This skill is on from the first table.** The default mode is the inline gate below — every schema change, import, and destructive path gets the durable treatment as it is written. The full pass is for existing projects and "is my data safe" checks.
+
+## Governing rules
+
+1. **The database is the last line of defense, not the app.** Constraints, foreign keys, uniqueness, and NOT NULL live in the store where enforcement cannot be bypassed. App-level validation is UX, not integrity — a bug, a script, or a direct SQL session walks right past it.
+2. **Destructive operations are guilty until proven guarded.** Any `DROP`, `TRUNCATE`, `DELETE`, `UPDATE` without a `WHERE`, or overwrite of a column/file gets: a guard (`WHERE` + `LIMIT`), a dry-run count first, a backup or snapshot when anything of value exists, and an undo path (soft delete, staging table, or copy) for user-facing data.
+3. **Migrations are code that runs on data you cannot recreate.** Checked in from day one, reviewed as SQL before applying (ORM-generated SQL included — generators will happily emit `DROP COLUMN` for a rename), never edited once applied, forward-only in production. `db push`-style sync is for throwaway dev databases only.
+4. **One logical change, one transaction.** Multi-step writes either all land or none do. Anything a retry can hit twice (webhooks, queue jobs, imports, payment callbacks) is idempotent — a dedup key or upsert, not hope.
+5. **Backups you have not restored are fiction.** Automated, off-platform (or at least off-instance), on anything with real user data — and the restore is exercised, timed, and recorded. RPO (how much loss is acceptable) and RTO (how long recovery takes) are stated numbers, not vibes.
+6. **Fail loudly, not corruptly.** Partial imports, half-applied backfills, and crashed jobs leave the system in a state the next run can detect and resume — keyset-resumable batches, recorded checkpoints, no silent skips.
+7. **Respect the writer.** SQLite has one writer; Postgres connections are processes; serverless poolers multiplex transactions and break session state. Designing against the store's real concurrency model is durability work, not just performance work.
+8. **Numbers or silence.** A backup claim without a timed restore run is unverified. Label every claim `RUNTIME` (observed), `CODE` (read in source), `DEDUCED` (inferred), `SNAPSHOT` (dated source). Never claim data is "safe" — say what loss is survivable and what is not.
+9. **Proportionality.** A prototype with test rows needs migrations and little else. The first real user row raises the floor: backups, then tested restore, then PITR-class recovery as the product matters.
+
+## Two modes
+
+**Inline gate** — while writing anything that touches stored data: the first table, a schema change, a backfill or import script, a delete/edit endpoint, a webhook that writes, a backup cron. Apply the binding defaults below, say one line about the guard you built, move on. Do not stop the build to lecture, and do not ship the unguarded version intending to "add safety later".
+
+**Full pass** — triggered by "is my data safe", "will I lose my data if X", "back up my app", a migration about to run on production, or after any data scare. Run the workflow below. Migration and schema detail lives in `references/migrations-and-schema.md`; backups, recovery, and runtime data-safety detail lives in `references/backups-and-runtime.md`.
+
+## Binding defaults (build mode)
+
+Apply on every data-touching change, every store:
+
+- **Migration tooling from the first table** — checked-in versioned migrations, generated with `--create-only`-style review when the ORM supports it, reviewed as SQL, applied via the tool's deploy path. Never hand-edit an applied migration; write a new one that corrects it.
+- **Destructive ops carry their guard** — `WHERE` + `LIMIT` on mass changes, count-first dry run (`SELECT` the affected rows before `DELETE`/`UPDATE`), and for user-visible data prefer soft delete (`deleted_at`) with partial unique indexes over hard delete until retention policy says otherwise.
+- **Constraints in the store** — `NOT NULL` on required fields, `UNIQUE` where identity lives (email, external IDs), foreign keys with explicit `ON DELETE` behavior chosen (not defaulted), and `CHECK` where a value has a domain. Orphaned rows and duplicate emails are app bugs the DB should have refused.
+- **Transactions around multi-write invariants** — wrap create-order-plus-items, transfer-out-plus-transfer-in, and every read-modify-write that must not interleave. Where the store lacks multi-document transactions, the default is a single-document design or an outbox pattern, never "should be fine".
+- **Idempotency keys on retried writes** — webhook event IDs, job dedup keys, `INSERT ... ON CONFLICT` upserts. Rule of thumb: if it can run twice, assume it will.
+- **Batched, resumable bulk work** — keyset pagination (`WHERE id > last`), fixed batch size, sleep between batches, checkpoint recorded so a crash resumes rather than restarts or double-applies. Never one unbounded `UPDATE` over a production table.
+- **Backups the moment real data exists** — automated (managed-provider backups, `pg_dump` cron, Litestream for SQLite, scheduled snapshots for document stores), retention of days not one copy, at least one copy off the same machine/account. State RPO/RTO in a comment where the backup is configured.
+- **Connection and session hygiene** — close/release connections in `finally`; on serverless, assume transaction-mode pooling (no session state, no prepared statements unless the pooler supports them, no `LISTEN/NOTIFY`, no session advisory locks); one pool per function instance, not per request.
+- **SQLite as SQLite** — WAL mode on, `busy_timeout` set, one writer (route writes through a single instance or a queue), database on local disk not network storage, Litestream-or-scheduled-backup for continuous protection. Do not pretend it is a client-server DB.
+
+## Full-pass workflow
+
+### 1. Profile the data from the code
+
+Before asking anything: store type(s) and version, where data files live, ORM/migration tooling present or absent, what writes exist (endpoints, jobs, webhooks, imports), what deletes exist, whether backups are configured anywhere (deploy config, cron, provider settings), and — decisive — whether real user data exists. A repo with seed scripts only is a different engagement than one with a production URL.
+
+### 2. Establish what loss would mean
+
+From the code, answer: what is recreated (cache, derived data), what is user-entered and unrecoverable (posts, uploads, messages, payments), and what links out (files on disk referenced by rows, rows referencing deleted files). The unrecoverable set defines backup urgency; the links define cleanup discipline.
+
+### 3. Sweep the six areas
+
+In order of how often each actually loses data. Detection specifics and commands: the two reference files.
+
+| # | Area | What you are hunting |
+|---|---|---|
+| 1 | **Backups & recovery** | No backups at all; backups only on the same machine/account; no retention; never-restored backups (the norm); no stated RPO/RTO; single copy of file uploads; managed backups assumed but not enabled |
+| 2 | **Destructive paths** | `DELETE`/`UPDATE` without `WHERE` or `LIMIT`; cascade deletes that sweep further than intended (user → everything they own, intended or not); truncate/drop in scripts; no undo for user-facing deletes; `db push` or sync-style schema changes anywhere near production config |
+| 3 | **Migrations health** | No migration tooling (schema by hand/script); applied migrations edited; pending destructive migration; generated SQL never reviewed; migrations untested against prod-shaped data; drift between schema files and the live DB |
+| 4 | **Transactions & idempotency** | Multi-step writes without a transaction; webhook/job handlers that double-apply on retry; check-then-act races (read, decide, write without a constraint); imports that restart from zero |
+| 5 | **Schema integrity** | Foreign keys absent or off (MySQL engines, SQLite `PRAGMA foreign_keys`); duplicate-prone columns without unique constraints; orphaned rows; `NOT NULL`-in-spirit columns that are nullable in fact; money/IDs stored in lossy types (float money, int IDs near overflow) |
+| 6 | **Runtime data safety** | Transaction-pooled connections using session features; SQLite without WAL/busy_timeout or with concurrent writers across instances; files written non-atomically (no temp-then-rename); jobs that mutate state with no record of having run; queues with no dead-letter path |
+
+### 4. Rank by survivability
+
+| Severity | Meaning |
+|---|---|
+| **Critical** | Loss is certain or one common failure away: real user data with no backups; destructive path unguarded; pending migration that drops data; double-charge/double-apply on retry |
+| **High** | Loss on a plausible bad day: backups exist but never restored; single copy on one machine/account; cascade deletes broader than intended; multi-write flows without transactions |
+| **Medium** | Fragility that bites at scale or during recovery: missing constraints, schema drift, non-idempotent jobs, non-atomic file writes |
+| **Low** | Hygiene: naming, unused staging tables, comments. Do these when adjacent to a real fix. |
+
+Fix Critical and High first; three to five fixes, each verified. A backup you set up is finished only when a restore from it has run and been timed.
+
+### 5. Verify
+
+- **Restore drill for any backup fix**: snapshot state, note the time, make a recognizable change, restore to the noted time into a separate location, verify the change is absent, record the wall-clock duration — that number is the real RTO. `RUNTIME` label or it did not happen.
+- **Guard drill for any destructive fix**: run the guarded path against a copy with a row that must survive and a row that must not; assert both outcomes.
+- **Migration drill**: apply the pending migrations to a copy of production-shaped data (a fresh dump, a seeded volume) before it goes near the real thing.
+- Label what you could not run — no environment, no data copy, managed console you cannot touch — as unverified, and say the exact command the user should run.
+
+### 6. Leave a guard behind
+
+A tested restore cron'd into a weekly job; a CI step that applies migrations to a throwaway DB before merge; a test that a retried webhook applies once; a constraint added to the store; `--create-only` review in the project's migration docs. One mechanical check beats a README paragraph.
+
+### 7. Report
+
+- Lead with the survivability statement in plain words: "if this server dies right now, you lose everything after [backup point]" — the RPO the user actually has, not the one they think they have.
+- Then findings ranked, each with file/line and the fix.
+- Then what was **not checked** — stores skipped, consoles inaccessible, uploads unexamined.
+- Then what you fixed (with verification labels) vs. what needs the user (provider settings, paid tiers, their call on retention).
+- Label every claim `RUNTIME` / `CODE` / `DEDUCED` / `SNAPSHOT`.
+
+## Honesty rules
+
+- Never state or imply data is "safe" or "backed up" without an observed, timed restore. "Backups are configured" is a `CODE` claim; "recoverable" requires a `RUNTIME` one.
+- Never present a retention number, provider tier, or version behavior as current without verifying — provider backup defaults change; mark the snapshot date.
+- Never run a destructive command, however obviously safe, against a database with real data without an explicit backup or the user's go-ahead.
+- "I could not verify this" is a legitimate output. A fabricated restore test is the worst lie this skill could tell.
+
+## Reference map
+
+Resolve every path from the installed skill root. Load only what the profile triggered.
+
+- `references/migrations-and-schema.md` — the migration discipline: expand-contract with concrete lock behavior, batched resumable backfills, index and FK lock-safety, ORM-specific traps (Prisma, Drizzle, and friends), forward-only production, CI and deploy-time application, and schema integrity checks. Read for any migration or schema finding.
+- `references/backups-and-runtime.md` — backup tiers and the restore drill, RPO/RTO, 2026 managed-provider baselines (Supabase, Neon, RDS, Crunchy), self-hosted tooling (pgBackRest, WAL-G, Litestream, restic), file-upload protection, idempotency and outbox patterns, pooling and serverless session-state pitfalls, SQLite runtime rules, and atomic file writes. Read for any backup, recovery, or runtime finding.

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

@@ -0,0 +1,86 @@
+# 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.
+
+## Part 1 — Backups & recovery
+
+### RPO/RTO first
+
+- **RPO** (Recovery Point Objective): how much data loss is acceptable — "5 minutes" vs "a day".
+- **RTO** (Recovery Time Objective): how long until you are back up.
+
+Pick both consciously; they dictate the tier. An app where users type for hours wants an RPO near zero; a read-mostly catalog may accept a day. Stating them where the backup is configured turns "we have backups" into an actual contract.
+
+### The tiers, best to weakest
+
+1. **PITR (point-in-time recovery)** — base backup + continuous write-ahead-log archive; restore to any second in the retention window. RPO of seconds-to-minutes. Gold standard for transactional data.
+2. **Scheduled logical dumps** (`pg_dump`, `mongodump`, Firestore export) — portable, cheap, easy to verify by inspection; but restore time scales with size and everything after the dump starts is lost. Fine as the archive layer or the only layer for small apps.
+3. **Storage/block snapshots** — fast, near-zero impact; restoring a running DB from a raw snapshot leaves crash recovery to do the rest. Good for staging clones; for disaster recovery prefer PITR.
+4. **Nothing / a copy on the same machine** — the default state of most small projects, and the finding most often reported after it stops mattering.
+
+**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)
+
+| Provider | What you get by default/on paid tiers |
+|---|---|
+| 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 |
+
+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.
+
+### The restore drill (the only proof)
+
+1. Note the current time / snapshot point of a known state.
+2. Make a recognizable change (insert a canary row).
+3. Restore to the noted point into a *separate* location — never over the live DB.
+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.
+
+### What a backup must exclude/include
+
+Include: the data, schema history (migrations), and anything unrecreatable (uploads, generated-but-expensive artifacts). Exclude/rotate: secrets in plaintext dumps (a dump with PII inherits compliance-guard's storage rules — encrypt at rest, restrict access), logs, caches. Test that the restore includes what you think: a backup that skips a table because of a wrong flag is the most humiliating restore failure.
+
+## Part 2 — Runtime data safety
+
+### Idempotency & exactly-once writes
+
+Anything retried — webhooks, queue jobs, mobile clients on flaky networks, imports — **will** run twice. Patterns, in order of preference:
+
+- **Store-side dedup**: unique constraint on the natural key (webhook event ID, job ID + attempt) and `INSERT ... ON CONFLICT DO NOTHING` returning whether it inserted. The store is the arbiter; no race can beat it.
+- **Upsert by natural key**: `ON CONFLICT ... DO UPDATE` with a deterministic outcome, so replay converges instead of duplicating.
+- **Compare-and-set / optimistic concurrency**: `UPDATE ... WHERE version = :expected`, check affected count — the guard for read-modify-write races (balance updates, seat claims, counter increments).
+- **Outbox pattern**: state changes and the events they trigger written in one transaction to an outbox table, published by a separate relay — eliminates "DB updated but email/queue lost" (and its evil twin, "email sent but DB rolled back"). The default answer where a store lacks cross-service transactions.
+
+Check-then-act without a constraint (`if not exists: insert`) is a bug that just hasn't raced yet.
+
+### 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.
+- **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.
+
+### SQLite runtime rules
+
+- **WAL mode on** (`PRAGMA journal_mode=WAL`) — readers don't block the writer; the default rollback journal serializes everything.
+- **`busy_timeout` set** (e.g. 5000ms) — without it, concurrent access returns `SQLITE_BUSY` instantly instead of waiting.
+- **`PRAGMA foreign_keys = ON` on every connection** — it is per-connection and off by default; constraints silently unenforced is a schema-integrity finding wearing runtime clothes.
+- **One writer** — route writes through a single instance or a write queue; multiple app instances writing one SQLite file on shared/network storage corrupts. Local disk (NVMe), not NFS.
+- **Backup without Litestream**: `VACUUM INTO 'backup.db'` or the `sqlite3 .backup` command — never copy the file mid-write; the WAL file and the checkpoint state are part of the database.
+
+### Atomic file writes and cleanup
+
+- **Temp-then-rename** for any file a reader may open: write to `path.tmp`, `fsync`, then `rename` over the target. Atomic on POSIX; a crash mid-write never leaves a truncated JSON the app will happily parse.
+- **Delete in dependency order and resweep**: child rows then parent; file after the row referencing it is gone (or record orphans for a sweep job). Reversible orderings first: soft-delete the row, mark the file, sweep files later — undoability beats tidiness.
+
+---
+
+**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.

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

@@ -0,0 +1,79 @@
+# 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.
+
+## The one rule that prevents most downtime
+
+**Never deploy a schema change and the code that depends on it in the same step.** Old code must keep working against the new schema, and new code must keep working against the old schema, for at least one deploy cycle. That is what expand-contract buys.
+
+## Expand-contract (parallel change)
+
+Every breaking change is two or three separately-deployed steps, each leaving the system fully functional:
+
+1. **Expand** — add the new column/table/index (nullable, no constraints yet). Old code ignores it; nothing breaks.
+2. **Backfill + dual-write** — copy old data to new in batches; code writes both; code reads new with fallback to old. Deploy, watch, wait.
+3. **Contract** — after the old path is provably dead (feature flag flipped, traffic at zero), remove the old column and the dual-write.
+
+Rollback at any point is "flip back to the old path", not "restore the database".
+
+**Rename a column** — never `RENAME COLUMN` on a live system (breaks all in-flight code): add `email`, backfill from `email_addr`, dual-write, switch reads, drop `email_addr` in a later deploy.
+
+**Change a type or split a column** — add the new column, backfill with transformation in batches, cut writes over, drop old. Same shape, always.
+
+## Lock-safety table (Postgres)
+
+What common DDL actually does to a live table (`SNAPSHOT` — verify per version):
+
+| 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 |
+| `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 |
+
+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
+
+```sql
+-- keyset, not OFFSET: stable order, restartable from last processed id
+UPDATE users
+SET status = 'active'
+WHERE id IN (
+  SELECT id FROM users WHERE id > :last_id AND status IS NULL
+  ORDER BY id LIMIT 5000
+)
+RETURNING id;   -- record max(id) as the checkpoint; sleep between batches
+```
+
+From application code the same shape applies: select batch by `id > last`, write, record checkpoint durably (a checkpoint table or job state), sleep. A crashed backfill resumes at the checkpoint instead of restarting or double-writing. On stores without `RETURNING`, select the batch first, update by primary key, checkpoint the max selected id.
+
+## 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.
+- **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.
+
+## CI and testing
+
+- A CI job that applies all migrations to a throwaway database (a fresh dump or seed of production shape) on every PR — catches broken SQL and lock surprises before merge, and keeps prod-shaped test data honest.
+- Migration + dependent code in one PR is fine; shipping them as one *deploy step* is not — expand and contract are separate deploys even when they merge as one review.
+
+## Schema integrity sweep
+
+- **Foreign keys enforced?** MySQL: check the engine (InnoDB enforces, MyISAM does not). SQLite: `PRAGMA foreign_keys = ON` per connection — it is OFF by default and every connection must set it. Postgres: on by default; hunt instead for `ON DELETE` behavior nobody chose — cascade on a `users` delete that sweeps orders, messages, and uploads is a mass-delete path wearing a constraint's clothing.
+- **Unique constraints where identity lives** — email, username, external IDs (`stripe_customer_id`), webhook event IDs. Without the constraint, every race produces a duplicate; with it, the race becomes a retryable error. Partial unique indexes for soft delete: `CREATE UNIQUE INDEX ... ON users(email) WHERE deleted_at IS NULL` — the live rows stay unique, the deleted ones don't collide.
+- **Nullable-in-fact columns** — every column the code treats as required should be `NOT NULL`, or the store will accept what the code never imagined.
+- **Lossy types** — money in floating point (use integer cents or `NUMERIC`), IDs in 32-bit ints near overflow (YouTube hit this), timestamps without timezone when the product is multi-timezone, enums-as-free-text where a `CHECK` or lookup table belongs.
+- **Orphan check** — rows referencing deleted parents (FKs added late don't clean history): count them before adding the constraint, and expect `VALIDATE` to fail if history is dirty. Decide: clean, archive, or keep the constraint `NOT VALID` deliberately and document why.
+- **Drift** — schema file vs live DB: most ORMs can diff (`prisma migrate diff`, `drizzle-kit check`). Drift on production means migrations were bypassed at some point — a process finding, not just a schema one.
+
+---
+
+**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.

package/assets/skills/lean/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: lean
+description: Use when speed or resource efficiency matters — slow loading or startup, janky interaction, high CPU, memory leaks or RAM that grows over time, zombie/orphan processes, bundle bloat, dead code and dead styles, Core Web Vitals; while building anything that should stay fast and light, running a performance pass over an existing project, or pre-ship "will this run smoothly" checks. Any stack — web, backend/API/CLI, desktop (Electron, Tauri), mobile, native, game, ML pipeline. Do NOT use for copy/docs-only changes, design-direction or aesthetic work (that is evidence-led-ui; this skill's styling scope is payload and consistency), or when the user explicitly deprioritizes performance.
+license: Performance engineering guidance, not a benchmark certification. Sources and snapshot date are recorded at the foot of each reference file.
+compatibility: Snapshot dated 17 August 2026. Thresholds, tool names, and defaults decay — re-verify with web access before asserting them as current. Claims sourced to that date carry a SNAPSHOT marker.
+---
+
+# Lean
+
+Make software fast, light, and smooth — loads quick, responds instantly, holds memory flat, leaves nothing running behind it. Built for the reality that users rarely ask for performance: they ask for a feature, then quietly leave when it eats RAM or takes five seconds to open.
+
+**This skill is on from the first line of code.** The default mode is the inline gate below — build the lean version while writing the feature, in the main thread. The full pass is for existing projects and pre-ship checks.
+
+## Governing rules
+
+1. **Measure, then cut.** In a pass, never optimize from vibes: baseline, find the bottleneck, fix it, re-measure. Guessing produces premature optimization — complexity without user-visible gain. In build mode the binding defaults below are pre-paid by platform evidence: apply them without benchmarking.
+2. **Fix the shared cause once.** The N+1 belongs in the query layer, not a memo at each call site. Check every caller of the slow path before patching where it hurt.
+3. **Optimize user time, not machine time.** What users wait on: startup, first paint, navigation, hot interactions, the nightly job. Micro-tuning code nobody waits for is last, always.
+4. **Memory should be flat.** After N cycles of the core loop, committed memory should look like after 1. Sustained growth is a leak until proven otherwise; a sawtooth that returns to baseline is GC, not a leak.
+5. **Nothing outlives its job.** Timers, listeners, observers, subscriptions, watchers, child processes, temp files, locks — everything with a lifetime needs an owner that ends it, on the success path *and* every failure path.
+6. **Bounded by default.** If it can grow — cache, queue, buffer, retry, log, list render — it gets a cap and an eviction policy at creation, not after the incident.
+7. **Small is fast.** Dead code, unused dependencies, and duplicate styles are parsed, shipped, and paid for. Removing is the cheapest optimization there is.
+8. **Numbers or silence.** Verify with before/after on the same machine and data, cold and warm. "Feels faster" is not a result, and never claim "optimized", "leak-free", or "fast" — say what moved, from X to Y, and what you could not measure.
+9. **No perf theater.** Complexity must pay for itself in measured user time; otherwise revert. Caching that introduces staleness bugs for an unmeasured gain is a regression wearing a costume.
+10. **Label evidence** on every claim: `RUNTIME` (you measured it), `CODE` (you read it), `DEDUCED` (inferred), `SNAPSHOT` (dated source claim). Never present what you read as what you ran.
+
+## Two modes
+
+**Inline gate** — while writing any feature, apply the binding defaults below. One line in the reply about what you did and why it matters, then move on. Do not stop the build to lecture, and do not ship the heavy version intending to "optimize later" — later never comes.
+
+**Full pass** — triggered by "make it faster", "why is it slow / eating RAM / lagging", "will this run smoothly", a suspected regression, or a pre-ship check. Run the workflow below. Per-stack sweeps and measurement commands live in `references/playbooks.md`; the memory-leak catalog and process/zombie lifecycle detail live in `references/memory-and-processes.md`.
+
+## Binding defaults (build mode)
+
+Apply on every feature, every stack. These are the habits that prevent the pass from ever being needed:
+
+- **Teardown ships with the feature.** Whatever you start — timer, listener, observer, subscription, child process, watcher — is torn down in the same module that started it, on success and error paths. Prefer one cleanup handle per owner (an `AbortController` for all of a component's fetches and listeners; a destructor/dispose method; a `finally` block) over scattered manual removes.
+- **Cap every accumulation.** LRU/TTL cache, bounded queue, paginated query, virtualized list, capped retries with backoff, rotating logs. Unbounded is a bug with a delay.
+- **Never block the interactive thread.** Chunk, defer, or offload work that can exceed a frame (web main thread long task threshold: 50ms) — web workers, background threads, task queues, utility processes. I/O stays async on the hot path; no sync fs/crypto/CPU spikes inside request handlers or UI code.
+- **Lazy by default, eager only for the first screen.** Below-the-fold media, rare routes, heavy editors, optional services: load on demand (dynamic `import()`, deferred `require`, on-demand plugin init). Preload/preconnect only what the critical path demonstrably needs.
+- **Right-size media.** AVIF/WebP with JPEG fallback, explicit `width`/`height` (also kills layout shift), `srcset`/`sizes` for density, decode thumbnails instead of full images.
+- **Stream, don't hoard.** Stream files and large responses, paginate/cursor DB queries, chunk large jobs. Loading a whole dataset into memory to process it item by item is the classic hog.
+- **Timeout everything external.** Network calls, subprocesses, locks, queues — no unbounded waits, and teardown on timeout.
+- **Price a dependency before adopting it** in anything user-facing: its load cost is your load cost (`node --cpu-prof --heap-prof -e "require('mod')"` for Node-side; bundle impact for client-side). The most-downloaded module is not the lightest.
+- **Batch I/O and reads-then-writes.** One query for N rows, not N queries; group DOM reads before writes; coalesce events (debounce/throttle) when handlers are expensive.
+
+## Full-pass workflow
+
+### 1. Profile the target from the code
+
+Before asking the user anything: shape (web app, API, CLI, desktop, mobile, library, game, ML pipeline — read manifests, lockfiles, build and CI configs), the surfaces users wait on (startup, first screen, navigation, hot interactions, batch jobs), scale (data sizes, traffic, session length), and platform constraints (low-end devices matter more than the dev machine).
+
+### 2. Baseline, or say you cannot
+
+Runtime numbers when the project runs: load time, startup time, p50/p99 latency, bundle sizes, RSS/heap at rest and after repeated cycles. Exact commands per stack are in `references/playbooks.md`. If you cannot run it (no environment, no data, no time), do a `CODE`-labeled static pass and say plainly in the report that nothing was measured — do not fabricate a baseline.
+
+### 3. Sweep the six areas
+
+Work this list in order — it reflects where user-perceived damage concentrates, not what is most interesting to engineer. Detection specifics per stack: `references/playbooks.md`; areas 3–4: `references/memory-and-processes.md`.
+
+| # | Area | What you are hunting |
+|---|---|---|
+| 1 | **Loading & startup** | Slow first paint/open, render-blocking resources, giant bundles, eager imports of rarely-used code, waterfall requests, unoptimized media and fonts, cold-start work that could be deferred |
+| 2 | **Runtime responsiveness** | Long tasks blocking input, layout thrash, expensive re-renders, N+1 queries, sync work on hot paths, missing pagination, unvirtualized long lists, GC pressure from allocation churn |
+| 3 | **Memory** | Growth over time (leaks): forgotten timers/listeners/observers, detached DOM held alive, unbounded caches and maps, closures capturing large scope, cycles in non-GC runtimes, undecoded-or-full-size media, whole-file loads where streaming would do |
+| 4 | **Processes & lifecycle** | Zombie children (spawned, never reaped), orphans surviving parent exit (killed the node, not the tree), missing signal handling and graceful shutdown, leaked ports/fds/locks/temp files, no startup sweep for crash leftovers |
+| 5 | **Payload & dead weight** | Unused dependencies, dead code and dead exports, dead/duplicate CSS, two libraries doing one job (two icon sets, two date libs, two CSS systems), ship-weight of debug/symbol payloads, tree-shaking blockers |
+| 6 | **Styling consistency** | Same visual thing built three ways — repeated rule blocks, one-off spacing/color literals that duplicate tokens, framework utilities fighting handwritten CSS. Consistency here is payload: one way to do X is the only way that stays small. (Design direction itself is evidence-led-ui's call.) |
+
+### 4. Rank by user impact, fix the top, not all
+
+| Severity | Meaning |
+|---|---|
+| **Critical** | Blocks or breaks: startup counted in tens of seconds, OOM crashes, multi-second UI freezes, a leak that kills a session in minutes |
+| **High** | User-perceivable degradation: sluggish interactions, fan-spinning idle CPU, RAM that climbs over a workday, zombie processes accumulating across runs, slowest paths 2–10× slower than they should be |
+| **Medium** | Waste with symptoms at scale: bundle bloat, N+1 under load, unbounded caches, missing pagination, duplicate dependencies |
+| **Low** | Hygiene without a measured symptom: dead code, dead styles, micro-tuning. Do these when adjacent to a real fix, never instead of one. |
+
+Fix the few that measurement actually implicates — three to five, rarely more. Each fix records its baseline number first. Prefer removing work over hiding it (delete the eager import beats code-splitting it beats deferring it), and prefer the platform primitive over a hand-rolled one.
+
+### 5. Verify the fix
+
+Re-measure exactly how you baselined, same machine, same data, cold and warm. A fix you did not measure is a hypothesis. For memory: cycle the changed path many times, force GC where the runtime allows (`--expose-gc`, DevTools), and compare committed memory — flat wins, sawtooth is fine, climbing is not fixed. If the number did not move, revert and say so; a change that adds complexity without moving the number is a regression.
+
+### 6. Leave a guard behind
+
+One check so it cannot silently return: bundle-size budget in CI, Lighthouse CI or `size-limit` for web, a slow-query threshold, a repeated-cycle memory assertion where feasible, a test that fails if the eager import returns. One gate beats good intentions.
+
+### 7. Report
+
+- Lead with numbers: what moved, X → Y, on which machine/data/date.
+- Then remaining findings, ranked, each with file/line and the fix.
+- Then what was **not checked** — unmeasured areas, stacks skipped, environments unavailable. A report that silently skips the mobile client or the batch job reads as complete coverage.
+- Then what you changed vs. what you recommend and did not do.
+- Label every claim `RUNTIME` / `CODE` / `DEDUCED` / `SNAPSHOT`. Include your false positives — candidates you investigated and dropped — so the survivor list is not hiding its noise.
+
+## Honesty rules
+
+- Never state or imply the software is "fast", "optimized", or "leak-free". State what was measured, fixed, and left unchecked.
+- Never present a lint rule, bundle analyzer, or profiler as proof of the absence of problems; tools find a minority of what matters.
+- Never invent a number, threshold, or version. If the claim is date-sensitive and unverified, mark it `SNAPSHOT` or say "verify this".
+- "I could not measure this" is a legitimate and useful output. A fabricated confirmation is not.
+- If the project is a prototype with no users and no load, say that proportionality applies — five real fixes beat forty ignored ones — and stop early.
+
+## Reference map
+
+Resolve every path from the installed skill root. Load only what the profile triggered.
+
+- `references/playbooks.md` — per-stack sweeps and measurement commands: web frontend (Core Web Vitals with official thresholds), Node/backend/API, Electron, Tauri, mobile, native/compiled (Rust, C/C++, Go, JVM), Python, data & queries, and the payload/dead-weight/styling-consistency tooling. Read the sections the profile triggered.
+- `references/memory-and-processes.md` — the leak catalog by pattern, detection technique per runtime (three-snapshot, allocation timeline, heap dumps, pprof, valgrind, Instruments, LeakCanary), component-framework leak rules, and the process lifecycle playbook: zombies, orphans, signal handling, process-tree kills, container PID 1, startup sweeps, leaked fds/ports/temp files. Read for any memory or process finding.