@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/enhance-email-deliverability/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: enhance-email-deliverability
+description: >
+  Audit and fix email deliverability: SPF, DKIM, DMARC, reputation, bounces
+  and complaints, list hygiene, unsubscribe compliance. Use when "emails go to
+  spam", "set up SPF/DKIM", or "check deliverability". Templates →
+  design-email.
+license: MIT
+---
+
+# enhance-email-deliverability — Inbox placement & lawful send
+
+**Degree of freedom: MIXED.** Scoring auth/hygiene
+`[HIGH freedom]`; DNS/config apply `[LOW freedom — after approval]`.
+Audit-and-fix. Templates stay on `design-email`.
+
+Close the gap between "the email sends" and "the email arrives". A beautiful
+transactional template in spam is a broken signup flow.
+
+Deliverability = authentication + reputation + hygiene + compliance. Miss any
+one and placement collapses.
+
+**Audit first. Apply DNS/config on approval.** Template markup stays on
+`design-email`.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **enhance-email-deliverability** (this) | SPF/DKIM/DMARC, bounces, complaints, unsubscribe headers |
+| `design-email` | Template markup, copy, React Email / MJML |
+| `plan-privacy-compliance` | Consent to collect; this owns consent *to send* |
+| `audit-analytics` | Whether open/click events fire (not inbox placement) |
+
+"Build a welcome email" alone → `design-email`; this skill owns inbox placement, not templates.
+
+## How to reason
+
+1. **Observe** — SPF/DKIM/DMARC records and a real message's Authentication-Results
+2. **Interpret** — pass raw SPF/DKIM but fail alignment? `+all`? DNS-only DKIM?
+3. **Classify** — auth fail / hygiene hole / compliance miss / template (hand off)
+4. **Severity** — no DMARC or `+all` blocks inbox placement
+
+## Worked example
+
+> **Observe:** one SPF with `+all`; DKIM TXT present; no DMARC; marketing and
+> password-resets share `example.com`.
+> **Interpret:** anyone can spoof; Gmail/Yahoo bulk will fail; a campaign
+> complaint can sink transactional mail.
+> **Classify:** auth fail + domain mixing.
+> **Fix:** SPF `-all` (or `~all` while warming), DMARC `p=none`+`rua` then
+> tighten, split transactional vs marketing domains — apply DNS only after approval.
+
+---
+
+## Phase 0 — Detect sending setup  [HIGH freedom]
+
+- Provider: Resend / Postmark / SES / SendGrid / Mailgun / SMTP
+- Sending domain(s) and DNS host
+- Transactional vs marketing — **they should not share a domain**
+- Where templates live (hand content issues to `design-email`)
+
+---
+
+## Phase 1 — Authentication (pass/fail gate)  [HIGH freedom; headers not DNS-only]
+
+**SPF** — Authorizes the provider. Exactly one record. Under 10 DNS lookups.
+Not `+all`.
+
+**DKIM** — Signing on at the provider; public key in DNS; **real message
+headers** signed (not DNS-only). 2048-bit keys.
+
+**DMARC** — Record present. `p=none` (monitor) vs `quarantine` / `reject`.
+`rua` reporting address. Gmail/Yahoo require DMARC for bulk senders.
+**Alignment:** visible From domain matches SPF/DKIM domains. Misalignment
+passes raw SPF/DKIM and still fails DMARC.
+
+**PTR / dedicated IP** — if self-hosted or dedicated: PTR set, warmed, not
+blocklisted.
+
+---
+
+## Phase 2 — Reputation & hygiene  [HIGH freedom]
+
+**Bounces** — Hard bounces via webhook → suppression list honored on every send.
+
+**Complaints** — Feedback loops / provider webhooks → immediate suppress.
+
+**List hygiene (marketing)** — Opted-in only (cross-check
+`plan-privacy-compliance`). No purchased lists. Inactive addresses removed.
+
+**Sending patterns** — Warm new domains. Separate transactional vs marketing
+so a campaign complaint does not sink password resets.
+
+**Content flags** — Image-only, spammy phrasing, broken links, missing
+plain-text → `design-email`.
+
+---
+
+## Phase 3 — Compliance footer  [HIGH freedom]
+
+- Marketing: functional unsubscribe **and** one-click `List-Unsubscribe`
+  headers (Gmail/Yahoo bulk). Transactional is exempt only if it is genuinely
+  transactional.
+- Physical address + sender ID — CAN-SPAM (US) and Japan 特定電子メール法
+  for advertising mail.
+- Unsubscribes honored on the *next* send.
+
+---
+
+## Definition of Done
+
+- [ ] Streams identified and separated
+- [ ] SPF / DKIM (real headers) / DMARC + alignment scored
+- [ ] Bounce + complaint → suppression list
+- [ ] Consent + inactive policy noted
+- [ ] Warming addressed if cold
+- [ ] One-click unsubscribe on marketing; legal footer present
+- [ ] Template flags handed to `design-email`
+- [ ] DNS/config applied only after approval
+
+## Self-critique before applying DNS  [LOW freedom — do not skip]
+
+1. **Real headers** — DKIM scored from a sent message, not DNS-only
+2. **Alignment** — From domain matches SPF/DKIM domains
+3. **Streams split** — marketing must not share the transactional domain
+4. **Right owner** — markup/copy → `design-email`
+5. **Apply only on approval**
+
+## Output format
+
+1. **Auth table** — SPF / DKIM / DMARC / alignment — pass/fail + exact fix
+2. **Hygiene** — bounce / complaint / list / warming
+3. **Compliance** — unsubscribe / footer / law
+4. **Fix plan** — auth first, then hygiene, then compliance
+5. Apply approved DNS/config; templates → `design-email`
+
+## Related
+
+- `design-email` — markup and copy
+- `plan-privacy-compliance` — consent to collect / to mail
+- `audit-analytics` — open/click instrumentation
+- `backend-patterns` — webhook + suppression store

package/skills/enhance-growth-loops/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: enhance-growth-loops
+description: >
+  Add growth loops to a live product: a "powered by" badge, shareable
+  artifacts, invites and referral credit, each with K-factor events. Use when
+  "referral program", "viral loop", "powered by badge", or "get users to
+  invite".
+license: MIT
+---
+
+# enhance-growth-loops — Output that recruits the next user
+
+**Degree of freedom: MIXED.** Which loop fits the product `[HIGH freedom]`;
+consent for invites, badge rules, event names, and per-loop measurement
+`[LOW freedom — run exactly]`.
+
+Apply-now. A funnel spends acquisition; a loop reinvests it — the output of
+one user (a shared artifact, a badge on their site, an invite) becomes the
+input for the next. Build one or two loops, measure each separately, and stop
+calling a funnel step a loop.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **enhance-growth-loops** (this) | Badge, share, invite, referral mechanics and their events |
+| `enhance-web-conversion` | Landing/pricing copy and upgrade prompts |
+| `enhance-onboarding` | Getting the *invited* user to value (loop closes there) |
+| `backend-patterns` | Referral credit ledger, idempotent reward grants |
+| `audit-analytics` | Taxonomy the loop events must fit |
+| `plan-gtm` | Chose the loop in its channel plan |
+
+Do **not** fire for "write the referral email" alone → `design-email`.
+
+## How to reason
+
+1. **Loop** — what user output can carry the product to a stranger, and who sees it?
+2. **Exposure** — how many strangers per active user per month, realistically?
+3. **Conversion** — of those, how many can reach value without talking to anyone?
+4. **Reinvest** — what does the new user produce that feeds the same loop?
+5. **Measure** — K = exposures × conversion per user; one K per loop, never blended
+
+## Worked example
+
+> **Loop:** a photo-pairing app produces a shared result page per session.
+> **Exposure:** ~3 recipients per session view the page; "Made with …" footer.
+> **Conversion:** page has a one-tap "try it" that opens the product ungated → value before signup.
+> **Reinvest:** the recipient's first session produces another shared page.
+> **Measure:** `share_created`, `share_viewed { referrer }`, `loop_signup { loop: "share" }`; K ≈ 3 × 0.04 = 0.12 per session.
+
+## Self-critique before reporting
+
+- **One K per loop** — badge, share, and invite each have their own exposure and conversion events
+- **Consent** — invites are user-initiated, single-send, with the recipient's opt-out; no contact-list scraping
+- **Badge honest** — removable on paid plans; links to a page that says what the product did
+- **Value before signup** — the landing side of every loop shows the artifact before asking for an account
+- **Right owner** — copy → `enhance-web-conversion`; reward ledger → `backend-patterns`
+
+---
+
+## Loop catalogue  [HIGH freedom — choose one or two]
+
+| Loop | Mechanism | Numbers to expect | Build notes |
+|---|---|---|---|
+| **Powered-by badge** | free plan shows "Made with X" on public output | 0.5–3% conversion, near-total exposure of every viewer | removable on paid; links to a "what this is" page with the artifact visible |
+| **Shareable artifact** | result page / export / public dashboard | exposure = recipients per share | ungated view; one-tap "try with your own"; OG image of the artifact |
+| **Templates & galleries** | users publish templates others clone | slow start, compounding | attribution to creator; clone = activation event |
+| **Invite / collaboration** | product is better with a teammate | warm invites convert 10–25% | invite flow inside the value moment; invitee lands on the shared object |
+| **Referral credit** | both sides get credit, storage, or a month | SaaS referral rate ~4.75%, referred conversion ~7.9%, top quartile 12%+ | idempotent grant on the *referred user's activation*, not signup; fraud cap per referrer |
+| **Public changelog / build in public** | releases as content | content loop, not viral | pairs with `docs-launch-kit` |
+
+Value before signup lifts referred conversion 2–5× — every loop's landing
+side shows the artifact first.
+
+## Procedure
+
+### 1. Pick and size  [HIGH freedom]
+Estimate exposure and conversion per active user from current data (or write
+**unmeasured**). A loop with K < 0.05 is a nice touch, not a channel; say so.
+
+### 2. Build the artifact side  [HIGH freedom]
+Public route renders the artifact without auth; OG tags carry a real
+screenshot (`enhance-web-seo` for meta); one primary "try it" action that
+lands the stranger in the product's ungated path (`enhance-onboarding`).
+
+### 3. Build the ask  [LOW freedom — rules]
+- Badge: on free-plan output only; removable for paid; alt text says what the product is.
+- Invite: user types or picks recipients; one email per recipient per invite; recipient can opt out of future invites; no address-book import without explicit per-send confirmation.
+- Referral: unique link or code; reward granted once, idempotently, when the referred user hits `activated`; per-referrer cap; terms visible.
+
+### 4. Events  [LOW freedom — names]
+
+```
+badge_viewed { host } · badge_clicked
+share_created { kind } · share_viewed { referrer } · share_cta_clicked
+invite_sent { count } · invite_accepted
+referral_link_created · referral_signup · referral_activated · referral_reward_granted
+loop_signup { loop }
+```
+
+Consent-gated; no recipient PII in properties. Reconcile with `audit-analytics`.
+
+### 5. Verify
+- Public artifact renders logged-out; OG preview shows the artifact
+- Invite sends once per recipient; opt-out honored (test with a second inbox)
+- Referral reward granted exactly once on activation; cap enforced
+- K per loop computed from events after 7 days (or **unmeasured** with the date it will be)
+
+## Guardrails
+
+- **No dark patterns** — no pre-checked "invite all", no fake "3 friends joined", no unremovable badge on paid.
+- **Anti-spam** — rate limits on invites and shares; report/opt-out link on every invite.
+- **Rewards on activation, not signup** — signup rewards get farmed.
+- **One K per loop** — never blend loops into one "viral coefficient".
+
+## Chains with
+
+- **`plan-gtm`** → the loop named in the channel plan.
+- **`enhance-onboarding`** → the invitee's path to value.
+- **`backend-patterns`** → credit ledger, idempotency, rate limits.
+- **`enhance-web-seo`** → OG and meta on public artifact routes.
+- **`test-playwright`** → logged-out artifact view and invite path.

package/skills/enhance-lifecycle-email/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: enhance-lifecycle-email
+description: >
+  Lifecycle email from product events: activation nudges, trial expiry by
+  activated vs stalled, limit-reached upgrades, win-back, with exits and
+  consent. Use when "onboarding emails", "drip sequence", or "win-back
+  email". Templates → design-email.
+license: MIT
+---
+
+# enhance-lifecycle-email — Emails that arrive because something happened
+
+**Degree of freedom: MIXED.** Sequence content and cadence `[HIGH freedom]`;
+trigger-before-timer rule, exit conditions, consent, idempotent sends, and
+event names `[LOW freedom — run exactly]`.
+
+Apply-now. Behavior-triggered sends are the primary path; timers are the
+fallback for users who produce no signal. Every email is gated on a product
+event, exits the moment the user does the thing, and reports its own
+open/click/conversion. Templates come from `design-email`; inbox placement
+from `enhance-email-deliverability`.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **enhance-lifecycle-email** (this) | Which email fires on which event, exits, cadence, measurement |
+| `design-email` | Template design and copy craft for each message |
+| `enhance-email-deliverability` | SPF/DKIM/DMARC, bounces, list hygiene |
+| `enhance-onboarding` | The in-app path the emails point back to |
+| `data-pipeline` | Idempotent scheduling / cron correctness for sends |
+| `plan-privacy-compliance` | Consent basis and retention for marketing mail |
+
+Do **not** fire for "design the welcome email" alone → `design-email`.
+
+## How to reason
+
+1. **Signal** — which product event (or its absence for N hours) says this user needs this email?
+2. **Exit** — which event ends the sequence because the goal was reached?
+3. **Track** — activated vs stalled users get different messages at the same calendar point
+4. **Cadence** — spacing follows the product's time-to-value, not a default day-0/3/7
+5. **Measure** — each send has delivered / opened / clicked / converted events tied to the trigger
+
+## Worked example
+
+> **Signal:** `signup_completed` with no `activated` after 24 h → "the one thing to try" email with a deep link to the sample-data path.
+> **Exit:** `activated` fires → the activation track stops; the habit track starts.
+> **Track:** trial day 11 — activated users get "here is what you built and what happens to it"; stalled users get "let us set it up with you" — no discount for an empty account.
+> **Cadence:** TTV median for this product is ~2 h, so the fallback nudge is at 24 h, not day 3.
+> **Measure:** `email_sent { sequence, step, trigger }` … `email_converted { goal }`; activation nudge → 14% of stalled users activate within 48 h.
+
+## Self-critique before reporting
+
+- **Trigger first** — every email names its product-event trigger; timers appear only as "no signal after N h" fallbacks
+- **Exits present** — every sequence lists the event that stops it
+- **Two tracks at expiry** — activated and stalled users receive different messages
+- **Consent and unsubscribe** — transactional vs marketing classification stated; one-click unsubscribe on marketing; suppression list respected
+- **Idempotent** — a retried job cannot send twice (`data-pipeline` pattern)
+- **Right owner** — template craft → `design-email`; deliverability → `enhance-email-deliverability`
+
+---
+
+## Sequences  [HIGH freedom — choose; each row optional]
+
+| Sequence | Trigger | Exit | Notes |
+|---|---|---|---|
+| **Welcome** | `signup_completed` | — | one email; the single next action, not a feature tour |
+| **Activation nudge** | no `activated` within TTV × 3 (fallback ≈ 24 h) | `activated` | deep link to the shortest path; users without the core action in 48 h are the highest churn risk |
+| **Setup stall** | `setup_started` without `setup_completed` for 24 h | `setup_completed` | name the exact step left |
+| **Habit** | `activated` | `habit_reached` | day-3 / day-7 value reminders keyed to what they created |
+| **Trial expiry** | `trial_ends_at − 3d`, `−1d`, `0`, `+3d` | `checkout_completed` | **split by `activated`**: activated → what you built and what happens to it, price, one CTA; stalled → help to value, no discount |
+| **Limit reached** | `limit_reached { resource }` | `checkout_completed` | what unlocks, price, one-click; mirrors the in-app prompt |
+| **Win-back** | no session for 30 d (activated users only) | any session | one email, then stop; new-feature framing |
+| **Dunning** | `payment_failed` | `payment_succeeded` | day 0 / 3 / 7; transactional |
+
+Behavior-triggered sequences report roughly 3× the click-through and
+markedly higher conversion than calendar drips (vendor-reported; treat as a
+reason to test, not a board number). Late-trial emails matter: most trial
+conversions happen in the second half — do not stop the sequence on day 7.
+
+## Procedure
+
+### 1. Map events  [LOW freedom]
+Confirm the product emits `signup_completed`, `setup_completed`, `activated`,
+`habit_reached`, `limit_reached`, `trial_ends_at`, `checkout_completed`,
+`payment_failed` (or their equivalents). Missing ones → `enhance-onboarding`
+/ `audit-analytics` first; an email on an unmeasured trigger is a timer in
+disguise.
+
+### 2. Design the tracks  [HIGH freedom]
+Pick sequences from the table; write trigger, exit, audience, message goal,
+and CTA for each step. Cadence from the measured TTV. Hand the copy brief to
+`design-email`.
+
+### 3. Wire  [LOW freedom — rules]
+- Provider: the one already in the repo (Resend, Postmark, SES, Customer.io, Loops); no second ESP.
+- Each send keyed by `(user_id, sequence, step)` — idempotent; retries cannot double-send.
+- Classification per email: transactional (dunning, expiry-day facts) vs marketing (nudges, win-back); marketing carries one-click unsubscribe and honors the suppression list; consent basis recorded (`plan-privacy-compliance` if unclear).
+- Exits evaluated at send time, not enqueue time.
+- Quiet hours and per-user daily cap (≤ 1 marketing email per day).
+
+### 4. Events  [LOW freedom — names]
+
+```
+email_sent { sequence, step, trigger }
+email_delivered · email_opened · email_clicked { link }
+email_converted { sequence, goal_event }
+email_unsubscribed { sequence }
+```
+
+### 5. Verify
+- Test user: trigger → email within the window; performing the exit event stops the next step (observe no send)
+- Retry the job: exactly one send per `(user, sequence, step)`
+- Unsubscribe → no further marketing mail; transactional still delivered
+- Report: sequences, triggers, exits, first-week `email_converted` by sequence (or **unmeasured** with date)
+
+## Guardrails
+
+- **No timers as the default.** A calendar drip is the fallback for silence.
+- **No discount for an empty account.** Stalled users get help, not a coupon.
+- **Consent and classification stated per email.** Marketing without an unsubscribe does not ship.
+- **One ESP.** Do not add a second provider to get a feature.
+
+## Chains with
+
+- **`enhance-onboarding`** → the events and the in-app path every email links to.
+- **`design-email`** → templates and copy.
+- **`enhance-email-deliverability`** → before the first sequence goes live.
+- **`data-pipeline`** → idempotent scheduling.
+- **`iterate-gtm-weekly`** → reads `email_converted` by sequence.

package/skills/enhance-motion/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: enhance-motion
+description: >
+  Audit an existing app's motion, then apply one coherent, performant,
+  reduced-motion-safe pass. Use when "motion pass", "animate the app", or "add
+  micro-interactions across the app". One new animation → design-motion.
+license: MIT
+---
+
+# enhance-motion — Coherent Motion for an Existing App
+
+**Degree of freedom: MIXED.** Tier and token judgment `[HIGH freedom]`; reduced-motion, GPU-only, and verify `[LOW freedom — run exactly]`.
+
+Add motion to an app that already exists, without fragmenting its visual language.
+The failure mode this prevents: bolting on one hero animation, three different easing
+curves, and a heavyweight library where a CSS class would do — motion that fights the
+design system instead of reinforcing it.
+
+> **Motion must be coherent, purposeful, reduced-motion-safe, and 60fps.** Pick the
+> **lightest tool that fits** each interaction. Every animation gets its timing and
+> easing from a **motion-token SSOT**, not ad-hoc magic numbers.
+
+This skill **applies** motion and verifies it. For a from-scratch motion cookbook (no
+existing system to respect), use `design-motion`. For pure animation-perf triage, use
+`audit-performance`.
+
+**Before any browser interaction, read `protocol-browser-anti-stall` and apply it.**
+
+## How to reason
+
+1. **Inventory** — libraries, easings, durations, reduced-motion coverage
+2. **Right-size** — lightest tier that fits; prefer what's already installed
+3. **Tokenize** — one motion-token SSOT; no magic numbers
+4. **Gate** — reduced-motion degrades; transform/opacity only; 60fps
+
+## Worked example
+
+> **Inventory:** Tailwind `duration-300` + one `framer-motion` modal; no reduced-motion; four easings.
+> **Right-size:** buttons stay CSS; lists get Auto-Animate; modal stays Motion; no GSAP.
+> **Tokenize:** `--motion-fast/base/slow` + three easings in the theme file.
+> **Gate:** `motion-reduce:` zeros travel; layout props not animated; modal 60fps.
+
+## Self-critique before reporting
+
+- **Coherent** — same interaction shares one duration/easing
+- **Reduced-motion** — spatial movement drops; essential opacity stays
+- **GPU-only** — no width/height/top/left animation
+- **Right owner** — one isolated new animation → `design-motion`; perf-only triage → `audit-performance`
+
+---
+
+## Phase 0 — Detect the design system and current motion  [HIGH freedom]
+
+### 0a. Applicability gate
+
+This skill targets **web / React (or Vue/Svelte) UI**. If the repo is a CLI, library,
+backend, or non-visual target, **bow out** and say so.
+
+### 0b. Inventory the design system + motion state
+
+Reuse the `audit-uiux-design-system` detection, then focus on motion:
+
+```bash
+# Libraries already present
+cat package.json | grep -iE "motion|framer|gsap|auto-animate|tw-animate|animate.css|react-spring"
+# Existing CSS motion + Tailwind config
+rg -n "@keyframes|animation:|transition:" -g "*.css"
+rg -n "animate-|transition-|duration-|ease-" -g "*.{tsx,jsx,vue,svelte}" -c
+# Existing JS motion
+rg -n "motion\.|useSpring|AnimatePresence|useScroll|gsap|autoAnimate" -g "*.{tsx,jsx}" -c
+# Reduced-motion support (critical)
+rg -n "prefers-reduced-motion|motion-safe|motion-reduce|useReducedMotion" -g "*.{tsx,jsx,css}"
+```
+
+### 0c. Record discovery
+
+```
+STACK: framework=<...> · CSS=<Tailwind v3/v4 / CSS Modules / ...> · UI lib=<...>
+MOTION TODAY: libraries=<...> · easings in use=<list> · durations in use=<list>
+REDUCED MOTION: honored? <yes/no — where>
+INCOHERENCE FOUND: <e.g. 4 easing curves, 3 durations for the same interaction>
+```
+
+---
+
+## Phase 1 — Choose the tier + define the motion-token SSOT  [HIGH freedom]
+
+### 1a. Research (current)
+
+Follow the `/research` protocol: Context7 for the chosen library's current API, Firecrawl
+for current patterns dated to now. Anchor to versions actually installed. Motion (formerly
+Framer Motion) is `motion` on npm.
+
+### 1b. Right-size the library per interaction
+
+Do **not** add every library. Pick the lightest tool that fits, and prefer what the repo
+already uses if it's adequate:
+
+| Tier | Tool | Use for |
+|---|---|---|
+| 1 — CSS utility | `tw-animate-css` (Tailwind v4 successor to `tailwindcss-animate`; shadcn's default) or existing Tailwind keyframes | fades, accordions, enter/exit utility classes, simple hovers |
+| 2 — zero-config layout | `@formkit/auto-animate` | list/table add·remove·reorder, expanding sections — no config |
+| 3 — component transitions | `motion` (motion.dev) — scoped to **component transitions, `AnimatePresence`, gestures, spring hovers** | modals, tabs, toasts, presence, drag |
+| 4 — complex timelines | `gsap` — **only** when Tier 3 cannot express it | scroll narratives, sequenced SVG, scrubbed timelines |
+| Reference | Kinetics (kinetics.colorion.co) | curated copy-paste pattern **source** — adapt to tokens; not a dependency |
+
+State the chosen tier(s) and why. Keep the dependency footprint minimal.
+
+### 1c. Define the motion-token SSOT
+
+Motion values are tokens, coherent with the existing scale (collapse the incoherence found
+in 0c into one set). Add to the token source (Tailwind theme / CSS variables):
+
+```css
+/* durations */ --motion-fast: 120ms; --motion-base: 200ms; --motion-slow: 320ms;
+/* easings   */ --ease-standard: cubic-bezier(0.2,0,0,1);   /* enter/state */
+                --ease-emphasized: cubic-bezier(0.3,0,0,1);  /* prominent   */
+                --ease-exit: cubic-bezier(0.4,0,1,1);        /* exit        */
+/* distance  */ --motion-shift: 8px;
+```
+
+All animations reference these — no inline magic numbers. Micro-interactions ≤ ~150ms,
+entrances ~200–320ms, exits faster than entrances.
+
+---
+
+## Phase 2 — Apply motion, tier by tier  [HIGH freedom]
+
+Work interaction-by-interaction; prefer mechanical, token-driven edits. For each element,
+use the lightest fitting tier from 1b.
+
+- **Buttons / links / cards:** Tier 1 CSS — `hover`, `active` (scale 0.98), `focus-visible`
+  ring, using tokens. Distinct response per element type.
+- **Lists / grids / expandable sections:** Tier 2 Auto-Animate — wrap the parent; items
+  animate on add/remove/reorder with zero per-item code.
+- **Modals / dialogs / toasts / tabs / dropdowns:** Tier 3 Motion — `AnimatePresence` for
+  exit, backdrop fade + content scale/slide, tab indicator slide. Gestures (`drag`,
+  `whileHover`, `whileTap`) where they add feel.
+- **Page/route transitions:** template/layout-level fade+shift, kept subtle (respect the
+  "component transitions only" scope — no heavyweight route choreography by default).
+- **Scroll narratives / hero timelines:** Tier 4 GSAP only if genuinely needed.
+
+Preserve all existing functionality and states — motion is additive. Never remove a
+handler or state to "simplify."
+
+---
+
+## Phase 3 — Accessibility & performance gates  [LOW freedom — run exactly]
+
+- **Reduced motion:** every animation degrades under `prefers-reduced-motion: reduce`.
+  Use `useReducedMotion()` (Motion), `motion-safe:`/`motion-reduce:` (Tailwind), or a CSS
+  media query that drops durations to ~0. Essential feedback stays (opacity), spatial
+  movement is removed.
+- **GPU-only:** animate `transform` / `opacity` only. No animating `width/height/top/left`.
+- **No CLS:** transitions must not shift layout unexpectedly; reserve space.
+- **Interruptibility:** enter/exit must not trap state if toggled rapidly.
+
+```bash
+rg -n "animate\[.*(width|height|top|left|margin)" -g "*.{tsx,css}"   # flag layout-triggering
+rg -n "prefers-reduced-motion|useReducedMotion|motion-reduce" -g "*.{tsx,css}"  # confirm coverage
+```
+
+---
+
+## Phase 4 — Verify and report  [LOW freedom — do not skip]
+
+- **playwright-cli:** navigate touched routes, capture before/after screenshots to
+  `.playwright-mcp/`, check `console` for errors, confirm animations run
+  and reduced-motion drops them (toggle emulation).
+- **60fps:** spot-check in DevTools Performance for any Tier 3/4 animation.
+- **Build/typecheck:** run the repo's commands; fix anything introduced.
+
+```markdown
+## Motion Enhancement — report
+**Stack:** [..]  **Tiers used:** CSS/tw-animate-css · Auto-Animate · Motion · (GSAP: y/n)
+**Motion tokens:** durations [..] · easings [..] — single source in [file]
+**Coherence fixed:** collapsed [N] easings → 3, [N] durations → 3
+**Applied to:** buttons/cards (CSS), lists (Auto-Animate), modals/tabs/toasts (Motion), ...
+**A11y:** prefers-reduced-motion honored across [N] components (evidence)
+**Perf:** transform/opacity only; [component] verified 60fps; no CLS
+**Verification:** build ✓ · console clean ✓ · before/after screenshots [paths]
+```
+
+---
+
+## Related
+
+- `design-motion` — from-scratch motion cookbook (Framer/Motion/GSAP/CSS patterns)
+- `audit-uiux-design-system` — the broader visual coherency audit this builds on
+- `audit-performance` — animation performance / Core Web Vitals triage
+- `audit-accessibility` — reduced-motion and focus-order verification
+- `housekeep-design` — if motion incoherence is part of wider design drift, consolidate first
+- `protocol-browser-anti-stall` — required for the browser verification step