@ericrisco/rsc 0.1.44 → 0.1.46

package/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: "Use when something is broken and the impulse is to start patching — a bug, a failing or flaky test, a crash, an exception, a wrong result, a regression, or behavior nobody can explain — and you want the root cause found BEFORE any fix is proposed. The on-demand rsc-sdd diagnosis discipline, callable from inside implement (or any phase) the moment a check fails for a reason you don't understand. Triggers: 'debug this', 'why is this failing', 'this test is flaky', 'find the root cause', 'it works locally but not in CI', 'this used to work', 'track down this bug', 'the fix didn't stick', 'figure out why', 'NullPointer/segfault/500 out of nowhere', 'intermittent failure'. Fixes the ONE confirmed cause, then hands back. NOT writing a planned feature (that is `implement`), NOT the lint/test gate (that is `verify`), NOT adversarial diff reading (that is `review`). Honors the harness accompaniment dial."
+description: "Use when something is broken — a failing or flaky test, crash, wrong result or regression — and the root cause must be reproduced and proven before any fix. On-demand; callable mid-`implement`. NOT a feature to spec or build (that is `specify`/`implement`), NOT the lint/test gate (that is `verify`), NOT adversarial diff reading (that is `review`)."
 tags: [debug, bug, troubleshoot]
 recommends: []
 profiles: [core, full]
@@ -20,31 +20,9 @@ The one rule everything else serves: **no fix before a reproduced, isolated, con
 you cannot make the bug happen on demand, you cannot know you fixed it — you can only know the
 symptom stopped showing, which is not the same thing.
 
-This is a process skill. It does not own the test runner, the debugger, or the profiler — the
-**stack skills do** (`../fastapi/SKILL.md`, `../go/SKILL.md`, `../nextjs/SKILL.md`,
-`../flutter/SKILL.md`; data-layer issues `../postgresdb/SKILL.md`; security-shaped failures
-`../secure-coding/SKILL.md`). `debug` owns the *method*; it pulls the *mechanics* from whichever
-stack the failure lives in.
-
-## When to use / when not to
-
-Use when:
-
-- A test fails (or flakes) for a reason you don't fully understand, mid-`implement` or after.
-- A crash, exception, 500, segfault, or wrong output appears and nobody can yet say why.
-- A regression shows up ("this used to work") and you need the commit/change that caused it.
-- A fix was applied and the symptom came back, or a "fix" didn't actually stick.
-- The behavior differs between environments ("works locally, fails in CI").
-
-Do NOT use when:
-
-- You're writing a *planned* feature task and its expected failing test — that's `implement`'s
-  red→green→refactor; no mystery yet.
-- You're running the lint/type/test gate to confirm "done" — that's `verify` (it *reports* failures
-  and hands them here; it doesn't diagnose).
-- You're reading a clean diff adversarially for smells a test can't catch — that's `review`.
-- The "bug" is actually an unclear requirement or contradictory spec — that's `clarify`/`analyze`,
-  not a code defect.
+This is a process skill: it owns the *method*, never the instruments. The test runner, debugger,
+race detector and profiler belong to whichever stack the failure lives in — pull them from the
+delegation table below.
 
 ## Model tier — `heavy` (opt-in routing)
 
@@ -53,7 +31,9 @@ This phase's default model tier is **`heavy`** — root-cause diagnosis is deep
 ## Read the room first (accompaniment dial)
 
 Before diagnosing, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment
-level and match it. The *method* never changes with the dial — the volume does.
+level and match it; with no profile yet, assume non-technical — narrate the reasoning plainly and
+never apply a behavior-changing fix without a quick confirm. The *method* never changes with the
+dial — the volume does.
 
 | Level | While diagnosing you show… | Questions you ask |
 | --- | --- | --- |
@@ -62,10 +42,7 @@ level and match it. The *method* never changes with the dial — the volume does
 | **L2** decisions | each step's finding (repro, the half that isolated it, the cause) | confirm before a fix that changes behavior beyond the bug |
 | **L3** full | narrate the whole loop, teach the binary-search reasoning aloud | ask to contextualize the environment, recent changes, expectations |
 
-No profile yet → assume non-technical, narrate the reasoning plainly, and never apply a
-behavior-changing fix without a quick confirm.
-
-## The loop — five steps, in order
+## The loop — five steps, never skipped, never reordered
 
 ```text
 REPRODUCE   → make the bug happen on demand. A reliable repro (or a quantified flake rate) is the
@@ -84,11 +61,6 @@ VERIFY      → re-run the repro: symptom gone. Re-run the new test: green. Re-r
               dropped to zero. Only now is it fixed.
 ```
 
-Never skip a step and never reorder. **Reproduce before isolate** — you can't bisect a bug you can't
-trigger. **Hypothesize before fix** — an edit with no stated cause is a guess wearing a commit
-message. **Verify before "fixed"** — the word *fixed* is a claim about the repro no longer firing
-and the test being green, nothing less.
-
 ### Reproduce — the entry ticket
 
 A bug you cannot reproduce is not a bug you can fix; it's a rumor. Pin it down:
@@ -169,9 +141,9 @@ Why missed — what let it through, so the class of bug doesn't recur
 
 Skip the trivial ones (a typo'd variable). Log the cause a future debugger would pay to know.
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Why it fails |
 | --- | --- |
 | "I see the likely line — let me just change it and see." | That's guess-and-patch. Reproduce first; a fix to an untriggered bug proves nothing. |
 | "It's intermittent, you can't really reproduce it." | "Intermittent" is a rate to measure (k/N), not an excuse. Flakes have causes: state, order, races, time. |
@@ -185,8 +157,6 @@ Skip the trivial ones (a typo'd variable). Log the cause a future debugger would
 
 ## Red flags — stop and re-route
 
-- **You're editing code and you can't yet reproduce the bug** → stop; you're guessing. Get a repro
-  (or a measured flake rate) first.
 - **The "bug" is a spec contradiction or unclear requirement**, not a defect → route to
   `clarify` / `analyze`; debugging won't fix an ambiguity.
 - **The fix grows past the cause** (you're refactoring "while you're here") → split it out; keep the
@@ -210,15 +180,6 @@ Skip the trivial ones (a typo'd variable). Log the cause a future debugger would
 - [ ] Handed the whole-gate re-run back to verify; resumed implement where the failure interrupted it
 ```
 
-## What this skill is NOT
-
-- **Not the feature builder.** Once the cause is fixed and verified, planned work resumes in
-  `implement` (its red→green→refactor for the *next* task, not this bug).
-- **Not the quality gate.** The lint/type/full-suite/audit run that licenses "done" is `verify`'s
-  job; `debug` proves the one bug dead and hands the gate back.
-- **Not a refactor pass.** Keep the fix minimal; broader cleanups are `implement`/`review` territory,
-  not smuggled into a bugfix.
-
 ## Where you are in the chain
 
 `debug` is **on-demand**, callable from any phase — most often pulled in mid-`implement` when a test

package/skills/deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deployment
-description: "Use when containerizing an app, writing a Dockerfile, setting up GitHub Actions CI/CD, choosing a deploy target, or deploying to Coolify, Vercel, or a Hetzner VPS — multi-stage builds (FastAPI/uv, Go/distroless, Next.js standalone, Flutter web, Postgres), BuildKit build secrets, image scanning (trivy/hadolint), OIDC to registries (no long-lived secrets), least-privilege GITHUB_TOKEN, zero-downtime/rolling deploys, env/secrets flow GitHub→Coolify, healthchecks, rollback, and a hosting decision matrix (Vercel vs Hetzner+Coolify vs a third option). Trigger phrases: 'dockerize', 'write a Dockerfile', 'CI pipeline', 'GitHub Actions', 'deploy', 'ship it', 'where should I host this', 'Coolify', 'Vercel', 'Hetzner', 'VPS', 'docker-compose for local dev'."
+description: "Use when taking an app from source to live: choosing the deploy target from requirements (Hetzner+Coolify vs Vercel vs a third), then wiring container → CI → registry → host with build secrets, healthchecks and rollback. NOT one platform's mechanics (that is `coolify`, `vercel`, `railway`, `render`), NOT the Dockerfile alone (that is `docker`)."
 tags: [deploy, docker, ci, github-actions, coolify]
 recommends: [secure-coding]
 origin: risco
@@ -10,10 +10,6 @@ origin: risco
 
 Take any app in this repo from source → hardened container → green CI/CD → live on the right
 host, with secrets that never leak into image layers or logs, and a defined rollback path.
-The default self-hosted target is **Coolify** (covered in depth); for the *where to host*
-question, this skill also covers **Vercel** (zero-ops serverless/edge, ideal Next.js) and
-**Hetzner** (cheapest control; run Coolify on it for a self-hosted PaaS), plus a decision
-matrix and an "always 3 options" framework — see `references/hosting-targets.md`.
 
 ```text
 source → Dockerfile (multi-stage) → CI (lint·test·build·scan) → registry (ghcr) → target (Coolify·Vercel·Hetzner, rolling) → live + rollback
@@ -21,22 +17,10 @@ source → Dockerfile (multi-stage) → CI (lint·test·build·scan) → registr
                                                               choose via references/hosting-targets.md
 ```
 
-## When to use / When NOT to use
-
-**When to use:**
-
-- Authoring or auditing a `Dockerfile`, `.dockerignore`, or `compose.yaml`.
-- Writing or hardening `.github/workflows/*.yml` (build, test, scan, release, deploy).
-- Wiring a service onto Coolify: build-pack choice, env/secrets, domains, healthcheck, auto-deploy, previews, rollback.
-- Designing the secrets flow GitHub → registry → Coolify, or choosing rolling vs blue-green.
-- **Choosing where to host** (Vercel vs Hetzner+Coolify vs a third option) from real requirements — see `references/hosting-targets.md`.
-
-**When NOT to use:**
-
-- Kubernetes / Helm / ECS / Nomad orchestration → out of scope (this skill targets Docker + GHA, and hosting on Coolify/Vercel/Hetzner-class targets). Say so and stop.
-- Application runtime code, DB schema/migration logic, or business logic → wrong skill (see the per-stack skills below).
-- Cloud IaC (Terraform, Pulumi, CloudFormation) → out of scope; only the GHA↔cloud **OIDC handshake** is covered, not provisioning.
-- Pure local dev with no container ambition → likely overkill; mention the `compose.yaml` option and defer.
+**Out of scope — say so and stop:** Kubernetes / Helm / ECS / Nomad orchestration; cloud IaC
+(Terraform, Pulumi, CloudFormation — only the GHA↔cloud **OIDC handshake** is covered, not
+provisioning); application runtime code and DB schema/migration logic (the per-stack skills at the
+bottom own what runs *inside* the container).
 
 ## Decision rules
 
@@ -81,21 +65,10 @@ Consult these first. They settle 90% of choices before you write a line.
 | Runtime secret | Coolify env (Is Secret) / GHA `secrets` |
 | Cloud auth | OIDC — never a stored key |
 
-## Core principles
-
-1. Multi-stage always: a fat builder, a minimal runtime — never ship the toolchain.
-2. Pin digests (`FROM img@sha256:…`) on prod base images so a moved tag can't change your runtime.
-3. Non-root + read-only rootfs + `cap_drop: ALL`; add back only `NET_BIND_SERVICE` if you must bind <1024.
-4. One process per container. No supervisord-managed bundles; let the orchestrator scale.
-5. Write `.dockerignore` before the first build — it shrinks context, speeds builds, and keeps secrets out.
-6. Secrets never in layers, logs, or `ARG`; use BuildKit `--mount=type=secret` at build, env injection at runtime.
-7. Copy the lockfile and install deps **before** copying source, so source edits don't bust the dependency cache.
-8. `HEALTHCHECK` hits a real readiness path (`/healthz`), not `/` — it gates the rolling swap.
-9. 12-factor config: env only, validated at boot, fail-fast. No `.env` baked into images.
-10. Least-privilege `GITHUB_TOKEN` (`permissions:` default-deny, escalate per job) and every pipeline runs `scripts/verify.sh`.
-
 ## Docker — the canonical multi-stage shape
 
+One process per container: no supervisord-managed bundles, let the orchestrator scale.
+
 ```dockerfile
 # syntax=docker/dockerfile:1
 # ---- builder: full toolchain, deps cached before source ----
@@ -146,7 +119,8 @@ README.md
 DOCKER_BUILDKIT=1 docker build --secret id=npm_token,env=NPM_TOKEN -t app:dev .
 ```
 
-→ full per-stack Dockerfiles: `references/dockerfiles-by-stack.md`
+→ full per-stack Dockerfiles: `references/dockerfiles-by-stack.md` · image-authoring depth
+(shrinking, base-image choice, cache busting): `../docker/SKILL.md`
 
 ## docker-compose for local dev + Postgres
 
@@ -258,7 +232,8 @@ jobs:
 - BAD: blanket `permissions: write-all` — any compromised step can push images or mint tokens.
 - GOOD: third-party actions pinned to a full commit SHA with a version comment (`@<sha> # v0.35.0`). In the March 2026 `trivy-action` supply-chain incident ([GHSA-69fq-xp46-6x23](https://github.com/aquasecurity/trivy/security/advisories/GHSA-69fq-xp46-6x23) / CVE-2026-33634), 76 of 77 tags were force-pushed to credential-stealing malware; the advisory's named known-safe ref is `v0.35.0` (commit `57a97c7e7821a5776cebc9bb87c984fa69cba8f1`), the one clean tag still pointing at the real `master` HEAD. A moving tag would have pulled the malware; this SHA pin does not. Let Dependabot bump the SHA once upstream re-tags cleanly.
 
-→ matrix, reusable workflows, OIDC-to-cloud, environments/approvals, releases: `references/github-actions.md`
+→ matrix, reusable workflows, OIDC-to-cloud, environments/approvals, releases: `references/github-actions.md` ·
+workflow-syntax depth: `../github-actions/SKILL.md`
 
 ## Choosing a deploy target (3 options)
 
@@ -282,17 +257,15 @@ escape hatch — start on Vercel, move to Hetzner+Coolify when the bill grows, s
 
 → deep coverage (limits, regions, pricing, decision matrix, worked examples): `references/hosting-targets.md`
 
-## Coolify — deploy target
+## Coolify — wiring the chosen target
+
+Only the parts that touch the pipeline; the platform walkthrough lives elsewhere.
 
 - Pick the **Dockerfile** build pack when a Dockerfile exists — same artifact CI builds, full control, prod/CI parity.
 - Set **Ports Exposes** to the container port your app listens on (e.g. `8000`); Traefik routes the domain to it.
-- Mark sensitive env vars **Is Secret** — encrypted at rest, masked in logs and UI.
 - Set the **Health Check** path/port → this is what gates the rolling swap to the new container.
-- Attach **persistent storage** (volume/bind/file mount) for any stateful path; container FS is ephemeral.
-- Bind a **custom domain** → automatic Let's Encrypt cert + **Force HTTPS**; point DNS A/AAAA at the server.
+- Mark sensitive env vars **Is Secret** — encrypted at rest, masked in logs and UI.
 - Enable **GitHub App auto-deploy** on push, OR call the deploy webhook from CI (one or the other, not both).
-- Turn on **preview deployments** per PR (`{{pr_id}}.{{domain}}`) with non-prod secrets; auto-teardown on PR close.
-- Set **CPU/memory limits + reservations** per resource to prevent noisy-neighbor OOM.
 - **Rollback** = redeploy a previously stored image in one click; pair with backward-compatible migrations.
 
 ```bash
@@ -301,7 +274,8 @@ curl --fail -X POST \
   "https://coolify.example.com/api/v1/deploy?uuid=$APP_UUID&force=false"
 ```
 
-→ full Coolify walkthrough: `references/coolify.md`
+→ persistent storage, custom domains + Let's Encrypt, per-PR previews, CPU/memory limits, blue-green:
+`references/coolify.md` and `../coolify/SKILL.md`
 
 ## Secrets flow (GitHub → registry → Coolify)
 
@@ -321,35 +295,12 @@ GitHub secrets / OIDC ──mint short-lived creds──▶ build pushes to ghcr
 
 ## 12-factor config & observability
 
-Config from env, validated at boot, fail-fast — a bad config crashes on startup, never at request time.
-
-```python
-from pydantic import PostgresDsn
-from pydantic_settings import BaseSettings, SettingsConfigDict
+Config from env, validated at boot, fail-fast — a bad config crashes on startup, never at request
+time. Idiom per stack: pydantic-settings `BaseSettings` (raises at import), zod `envSchema.parse(process.env)`
+(throws at boot), `env.Must(env.ParseAs[Config]())` for Go (exits at boot).
 
-class Settings(BaseSettings):
-    database_url: PostgresDsn
-    model_config = SettingsConfigDict(env_file=".env")
-
-settings = Settings()  # raises at import → fail-fast
-```
-
-```typescript
-import { z } from "zod";
-const envSchema = z.object({ DATABASE_URL: z.string().url(), PORT: z.coerce.number().default(3000) });
-export const env = envSchema.parse(process.env); // throws at boot → fail-fast
-```
-
-```go
-import "github.com/caarlos0/env/v11"
-type Config struct {
-	DatabaseURL string `env:"DATABASE_URL,required"`
-	Port        int    `env:"PORT" envDefault:"8080"`
-}
-cfg := env.Must(env.ParseAs[Config]()) // exits at boot if invalid → fail-fast
-```
-
-- Log JSON to stdout (slog for Go, structlog/uvicorn JSON for FastAPI, pino for Next.js); never log secrets; expose `/healthz` (liveness, no deps) + `/readyz` (checks deps).
+Log JSON to stdout (slog for Go, structlog/uvicorn JSON for FastAPI, pino for Next.js); never log
+secrets; expose `/healthz` (liveness, no deps) + `/readyz` (checks deps).
 
 ```python
 # FastAPI: liveness is dependency-free; readiness probes the DB so a node that
@@ -368,11 +319,11 @@ async def readyz() -> dict[str, str]:
 
 | Rationalization | STOP — do this instead |
 | --- | --- |
-| `:latest` is fine for now | Pin tag+digest; `:latest` breaks reproducibility and rollback |
+| `:latest` is fine for now | Pin tag+digest (`FROM img@sha256:…`); `:latest` breaks reproducibility and rollback |
 | I'll pass the token as `ARG` | BuildKit `--mount=type=secret`; `ARG` persists in `docker history` |
 | `permissions: write-all` is simpler | Default-deny; grant per job (`packages: write`, `id-token: write`) |
 | Store a registry password in GHA secrets | Use OIDC / `GITHUB_TOKEN`; no long-lived key |
-| Run as root, it's just a container | Non-root UID + read-only rootfs + `cap_drop: ALL` |
+| Run as root, it's just a container | Non-root UID + read-only rootfs + `cap_drop: ALL` (add back only `NET_BIND_SERVICE` to bind <1024) |
 | Skip the healthcheck, the app boots fast | No healthcheck = no rolling gate = downtime / bad version live |
 | Copy the whole repo then `RUN install` | Copy the lockfile first; cache the deps layer |
 | Nixpacks is easier than my Dockerfile | If a Dockerfile exists, use it — CI/prod parity |
@@ -389,7 +340,7 @@ async def readyz() -> dict[str, str]:
 | Scan image | `trivy image --severity HIGH,CRITICAL --exit-code 1 IMG` |
 | Lint Dockerfile | `hadolint Dockerfile` |
 | Lint workflows | `actionlint` |
-| Run verify gate | `bash scripts/verify.sh` |
+| Run verify gate | `bash scripts/verify.sh` (hadolint+actionlint+trivy+build smoke, local and CI) |
 | Local up | `docker compose up --watch` |
 | Trigger Coolify deploy | `curl --fail -X POST …/api/v1/deploy?uuid=…&force=false` |
 | Roll back | Coolify → redeploy prior image |
@@ -405,33 +356,19 @@ async def readyz() -> dict[str, str]:
 - [ ] trivy clean (no HIGH/CRITICAL)
 - [ ] Rollback path known
 
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's deploy decisions there and index them in `02-DOCS/wiki/index.md`, so the next
-agent inherits the conventions instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/deployment.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — the base-image/container choices, the CI pipeline, the Coolify/target config, the secrets flow, and the rollback strategy —
-   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it).
-3. **Read it first on every use** and stay consistent; when a convention changes, update the
-   article (bump its `Updated` date) in the same change.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
-brand study, technical conventions are *recorded, not gated* — never block the task on this.
-
-## See Also
+## Project grounding (02-DOCS)
 
-- `../harness/SKILL.md` — 01-TOOLS provider creds (Stripe, Postgres, OAuth…) that become Coolify runtime env.
-- `../secure-coding/SKILL.md` — input validation, authn/z, and secret-handling that this skill assumes the app already does.
-- `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`, `../postgresdb/SKILL.md` — runtime code for the stacks you containerize here. This skill stops at the container boundary; those skills own the application code that runs inside it.
-- `references/dockerfiles-by-stack.md`, `references/github-actions.md`, `references/coolify.md`, `references/hosting-targets.md`, and `scripts/verify.sh`.
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), read
+`02-DOCS/wiki/stack/deployment.md` first and stay consistent with it. Create or update it with this
+project's real choices — base-image/container choices, the CI pipeline, the target config, the
+secrets flow, the rollback strategy — index it in `02-DOCS/wiki/index.md` (the Knowledge map root
+`CLAUDE.md` points to), and bump its `Updated` date in the same change. No `02-DOCS/` layer? Skip
+silently (optionally suggest `harness`) — technical conventions are *recorded, not gated*; never
+block the task on this.
 
-## References
+## Hand off
 
-- `references/dockerfiles-by-stack.md` — complete runnable Dockerfile + .dockerignore per stack.
-- `references/github-actions.md` — least-privilege workflows, OIDC, matrix, releases, deploy.
-- `references/coolify.md` — build packs, secrets, volumes, SSL, previews, rolling, blue-green, rollback.
-- `references/hosting-targets.md` — Vercel, Hetzner (+Coolify), Fly.io/Railway/managed-cloud; decision matrix and the "always 3 options" framework with worked examples.
-- `scripts/verify.sh` — the hadolint+actionlint+trivy+build-smoke gate (runs locally and in CI).
+- Platform mechanics once the target is chosen: `../coolify/SKILL.md`, `../vercel/SKILL.md`, `../railway/SKILL.md`, `../render/SKILL.md`, `../fly-io/SKILL.md`, `../hetzner/SKILL.md`.
+- `../secure-coding/SKILL.md` — input validation, authn/z, and secret-handling this skill assumes the app already does.
+- `../harness/SKILL.md` — 01-TOOLS provider creds (Stripe, Postgres, OAuth…) that become runtime env on the target.
+- `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`, `../postgresdb/SKILL.md` — the application code that runs inside the container; this skill stops at that boundary.

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: "Use when designing a modern UI, building/writing a high-converting landing page or web page, refreshing a hero, choosing type/color/spacing/motion, or making an interface feel premium instead of generic/AI-templated. Brand-grounded: reads the project's 02-DOCS brand study first and STOPS to interview the user if it is missing or incomplete. Research-first: studies award-winning current work (Awwwards, Godly, Land-book, Refactoring UI, Linear/Stripe/Vercel/Resend-tier) and pulls current 2026 trends with citations before prescribing. Ships Tailwind v4 + Next.js 15 + React 19 patterns with correctly-stated WCAG 2.2 AA and Core Web Vitals (LCP/INP/CLS) as hard design constraints; ties to 'marketing' for the words and 'nextjs' for the build. Triggers: 'design a landing page', 'build a web page', 'make this look premium', 'pick a color palette', 'this UI feels generic', 'bento section', 'design review', 'modern UI'."
+description: "Use when designing or refreshing a web UI or landing page — visual concept, type/color/spacing/motion tokens, composition, rescuing a UI that reads AI-generic, or a graded design review. Brand-grounded and research-first; ships Tailwind v4 + Next.js 15 under WCAG 2.2 AA and Core Web Vitals budgets. NOT the words on the page (that is `marketing`), NOT the App Router build (that is `nextjs`)."
 tags: [design, ux, ui, landing, conversion]
 recommends: [nextjs, marketing]
 origin: risco
@@ -10,64 +10,25 @@ origin: risco
 
 *Research the best current work, then ship a premium, accessible, fast, high-converting interface.*
 
-## When to use / When NOT to use
+> **SDD gate.** If this fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, hand off to `../specify/SKILL.md` first — it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build straight from here only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
 
-> **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
+**Hand-offs.** The WORDS are `../marketing/SKILL.md`'s: it co-owns the `02-DOCS/wiki/brand/` study (the words dimensions there, the visual ones here), and deep keyword research, GEO, or a technical SEO audit belongs to it — this skill only enforces SEO-aware *structure* in markup. The BUILD (App Router / React 19) is `../nextjs/SKILL.md`'s. Mirroring the brand tokens into a Flutter app is `../flutter/SKILL.md`'s. Pure backend/data/infra with no UI surface: decline — there is nothing to design. Three references live outside this repo and are named for direction only, not invocable here: *frontend-design-direction* for dense internal tooling used daily (never paint a marketing skin on a tool that needs repeated daily use — fold its judgment in via the DIRECTION BRIEF); *liquid-glass-design* for native iOS 26 SwiftUI Liquid Glass (this skill ships the *web* glass approximation only); *motion-ui* / *motion-foundations* for motion-code mechanics (springs, `AnimatePresence` internals, layout animations — this skill sets motion *intent + budget*).
 
-Use when:
+## Brand grounding — before you design anything
 
-- Building a new landing or marketing page.
-- Doing a redesign or a polish pass on an existing surface.
-- Writing hero, value-prop, pricing, or FAQ copy.
-- Choosing a visual system: type, color, spacing, radius, shadow, motion.
-- Rescuing a UI that "feels generic / AI-slop".
-- Running pre-launch design QA.
-
-Do NOT use when (delegate or decline):
-
-- Pure backend/data/infra work with no UI surface → decline; there is nothing to design.
-- Dense internal operational tooling used daily (not a sales page) → apply product-domain judgment and do NOT force a landing composition (the *frontend-design-direction* lens, an external reference — not a repo skill).
-- Native iOS/SwiftUI Liquid Glass material → the *liquid-glass-design* reference (external; this skill ships the *web* glass approximation only).
-- Deep motion code mechanics (springs, `AnimatePresence` internals, layout animations) → the *motion-ui* / *motion-foundations* references (external; this skill sets motion *intent + budget*).
-- Deep keyword research, GEO, or a technical SEO audit → the `../marketing/SKILL.md` sibling (it owns SEO-aware structure + keyword/intent; this skill only enforces SEO-aware *structure* in markup).
-
-**Tool vs. landing page:** A SaaS operations tool should be dense, quiet, and scannable — never paint a marketing skin on a tool that needs repeated daily use.
-
-## Brand grounding (read this first)
-
-Before producing ANY landing / web-page / marketing output, ground in the project's brand study. A design with no brand behind it is a guess, and a guess defaults to your AI-generic prior. This step is mandatory and self-reinforcing: **an incomplete brand study is a hard stop, not a warning.**
+A design with no brand behind it is a guess, and a guess defaults to your AI-generic prior. That is why this gate is a hard stop rather than a warning: **an incomplete brand study blocks the work.**
 
 Follow the harness 02-DOCS convention (brand study = wiki articles under `02-DOCS/wiki/brand/`, raw inputs under `02-DOCS/raw/brand/`, linked from root `CLAUDE.md`):
 
 1. **Locate the brand study.** Read the project root `CLAUDE.md` and look for a `## Brand & voice` section pointing into `02-DOCS/wiki/brand/...`. If present, read those articles.
-2. **If the link is MISSING, or the brand study is ABSENT or INCOMPLETE** (any checklist dimension empty), STOP. Do not design yet. Instead:
-   - Ask the user the targeted question script — **ONE focused batch at a time**, not a wall of questions — until every dimension in the completeness checklist is filled. (→ `references/brand-grounding.md`)
-   - Write/update the brand study into `02-DOCS/wiki/brand/` (and paste any raw inputs the user gives — screenshots, existing palettes, competitor lists — into `02-DOCS/raw/brand/`), following the wiki article format, and update `wiki/index.md` + `wiki/log.md`.
-   - Add/update a `## Brand & voice` section in the root `CLAUDE.md` linking to it (create `CLAUDE.md` if absent).
+2. **If the link is MISSING, or the brand study is ABSENT or INCOMPLETE** (any checklist dimension empty), STOP. Do not design yet. Ask the user the targeted question script — **ONE focused batch at a time**, not a wall of questions — until every dimension in the completeness checklist is filled (→ `references/brand-grounding.md`). Write/update the brand study into `02-DOCS/wiki/brand/` (and paste any raw inputs the user gives — screenshots, existing palettes, competitor lists — into `02-DOCS/raw/brand/`), following the wiki article format, update `wiki/index.md` + `wiki/log.md`, and add/update a `## Brand & voice` section in the root `CLAUDE.md` linking to it (create `CLAUDE.md` if absent).
 3. **Only once the brand study exists and is sufficient, proceed** — and cite which brand articles drove which decisions in your output (e.g. "palette from `02-DOCS/wiki/brand/visual-identity.md`").
 
 The completeness checklist spans visual identity (OKLCH color system, type pairing & scale, logo, imagery/illustration mood, density, radius/shadow/motion personality), reference/inspiration sites the user loves, layout preferences, dark-mode stance, accessibility & performance constraints, and brand voice/positioning (so copy and design agree). Full checklist + exact question script → `references/brand-grounding.md`.
 
-The order is: **brand grounding → trend research → build.** If the brand study lacks aesthetic direction, or the user asks for "modern" / "2026" / "premium", run the research-first protocol (below) and fold current, cited findings into the output.
+The order is: **brand grounding → trend research → build.**
 
-## The non-negotiables
-
-These are constraints, not preferences. Violating any one is a defect, not a style choice.
-
-1. **Ground in the brand study before you design.** No `02-DOCS/wiki/brand/` study, or an incomplete one → STOP and complete it. (→ "Brand grounding" above, `references/brand-grounding.md`)
-2. **Research before you prescribe.** Run the research protocol; never ship from stale memory — your default taste skews AI-generic. Pull current 2026 trends with citations + dates. (→ `references/research-method.md`, `references/trends-2026.md`)
-3. **5-second value prop.** What it is, who it's for, and why it's better must be legible above the fold in 5 seconds.
-4. **One `<h1>` per page;** semantic landmarks (`header`/`nav`/`main`/`section`/`footer`).
-5. **Core Web Vitals are design constraints:** LCP < 2.5s, INP < 200ms, CLS < 0.1. (INP replaced FID in March 2024 — measure INP.)
-6. **WCAG 2.2 AA:** 4.5:1 text contrast (3:1 large text / UI), visible focus, `prefers-reduced-motion` honored. Target size: 24×24px is the AA floor (SC 2.5.8 Target Size (Minimum)); 44×44px is the recommended quality bar (Apple HIG / pointer comfort) — aim for 44, never ship below 24.
-7. **Design tokens, never magic numbers.** Tailwind v4 `@theme` → CSS vars.
-8. **Spacing on a 4/8px scale; type on a modular scale; color allocated 60-30-10.**
-9. **Motion must guide attention, communicate state, or preserve continuity** — else delete it.
-10. **Copy is benefit-led and specific.** No hype; the ban-list is enforced. (→ `references/copywriting-frameworks.md`)
-11. **Match the product domain.** Density and composition follow the audience and the job, not a template.
-12. **Commit to a visual concept and one signature element.** A page with no point of view defaults to AI-generic. Name the concept in one sentence; manufacture the ONE distinctive idea (not a gradient); force scale contrast and section rhythm; run the senior-designer crit before shipping. (→ "From competent to premium" below, `references/signature-and-craft.md`)
-
-## Decision rules (pick a direction first)
+## Pick a direction first
 
 Fill the direction brief before you write a single line of markup:
 
@@ -80,7 +41,7 @@ DIRECTION BRIEF (fill before coding)
 5. Constraints ...... framework, a11y, perf budget, existing design system/tokens
 ```
 
-Then map the project type to composition, density, and motion budget:
+Then map the project type to composition, density, and motion budget. Density and composition follow the audience and the job, not a template — a SaaS operations tool should be dense, quiet, and scannable.
 
 | Project type | Composition | Density | Motion budget |
 | --- | --- | --- | --- |
@@ -93,7 +54,7 @@ Then map the project type to composition, density, and motion budget:
 
 ## Research-first protocol
 
-Trends churn quarterly and your built-in aesthetic prior is the median of every AI template ever scraped. Counter it with a loop:
+Trends churn quarterly and your built-in aesthetic prior is the median of every AI template ever scraped. Never prescribe from stale memory; counter it with a loop:
 
 1. Define 2–3 reference archetypes from the DIRECTION BRIEF (e.g. "Linear-grade dev tool, dark, type-led").
 2. WebSearch award galleries and tier-1 product sites: `awwwards.com`, `godly.website`, `land-book.com`, `mobbin.com`, Refactoring UI, and the tier-1 sites (Linear, Stripe, Vercel, Cursor, Resend).
@@ -102,46 +63,24 @@ Trends churn quarterly and your built-in aesthetic prior is the median of every
 5. Synthesize a one-paragraph DESIGN DIRECTION with citations (which URL contributed what).
 6. Only THEN build; re-check the result against the references in QA.
 
-Re-research per project — trends churn, competitors moved, and the domain dictates the reference set. Do not rely on stale memory: whenever the brand study lacks aesthetic direction or the user asks for "modern" / "2026" / "premium", WebSearch/WebFetch current trends (award sites, Linear/Stripe/Vercel/Resend-tier, current type/color/motion/layout moves), fold the findings into the output **with citations + dates**, and refresh `references/trends-2026.md`. Full loop, source map, and synthesis template → `references/research-method.md`. Current snapshot (dated, cited) → `references/trends-2026.md`.
+Re-research per project — trends churn, competitors moved, and the domain dictates the reference set. Whenever the brand study lacks aesthetic direction or the user asks for "modern" / "2026" / "premium", run this loop, fold the findings into the output **with citations + dates**, and refresh `references/trends-2026.md`. Full loop, source map, and synthesis template → `references/research-method.md`. Current snapshot (dated, cited) → `references/trends-2026.md`.
 
 ## From competent to premium (the part that earns the score)
 
-Obeying every non-negotiable gets you to *competent* — a page that ships and passes review. It does NOT
-get you to premium, because every constraint catches an *absence* (no missing `<h1>`, contrast passes),
-while premium is a *presence*: a point of view. Competent-but-generic is the default failure mode of
-under-specified design output. Close it with four deliberate moves, in order, before and during the build:
-
-1. **Choose a visual concept.** One sentence the whole page answers to — `[feeling] + [structural metaphor]
-   for [audience doing job]` (e.g. "quiet instrument-panel precision for ops engineers"). Drawn from the
-   brand study + research exemplars, never your prior. If you cannot name what makes this surface different
-   from the median SaaS page, you have no concept yet, and the output will default to generic.
-2. **Manufacture the ONE signature element** the brief asks for — the thing you'd describe first to a
-   friend. Pick exactly one from a real vocabulary, biased by domain: a hero that *demonstrates not
-   describes* (live terminal / real chart / actual diff), an owned type moment, a structural signature
-   (asymmetric split, horizontal feature rail, editorial index), a material signature (hairline grid, one
-   grain pass, duotone), a motion signature, or a real-number/proof signature. Never default to "a
-   gradient". It must be true to the product, and cite the research exemplar that inspired it.
-3. **Force scale contrast.** Generic pages are tonally flat — headline, titles, body all within ~1.5×.
-   Make the hero dominant **3–5× the body**, demote eyebrows/labels/metadata smaller and quieter than
-   feels comfortable, and allow **one focal point per viewport**. If a section feels flat, add contrast,
-   not elements.
-4. **Give the page rhythm.** Ten identical `py-24` white card-grid sections read as one stripe. Vary
-   format (full-bleed vs. contained, alternate media sides), background (a dark section between light ones
-   anchors a CTA), density (a breathing statement after a dense grid), and container idiom (not everything
-   is a bordered card). Inter-section gap > intra-section gap, padding stepping on the scale.
-
-Then, **before claiming done, run the senior-designer crit** and make at least one concrete change as a
-result: What is the one idea here (name it in a sentence)? Would this place on Awwwards/Godly or just pass
-review? What is the single most generic element right now — and replace it. Where does the eye land first,
-and is that what should win? If the logo were removed, would anyone know whose product this is? Does every
-section earn its place, or is one there out of habit (cut it)?
-
-Full method — concept formula, signature vocabulary, scale/rhythm rules, the crit, and a worked
-generic→signature dev-tool hero — → `references/signature-and-craft.md`.
+Obeying every constraint gets you to *competent* — a page that ships and passes review. It does NOT get you to premium, because every constraint catches an *absence* (no missing `<h1>`, contrast passes), while premium is a *presence*: a point of view. Competent-but-generic is the default failure mode of under-specified design output. Close it with four deliberate moves, in order, before and during the build:
+
+1. **Choose a visual concept.** One sentence the whole page answers to — `[feeling] + [structural metaphor] for [audience doing job]` (e.g. "quiet instrument-panel precision for ops engineers"). Drawn from the brand study + research exemplars, never your prior. If you cannot name what makes this surface different from the median SaaS page, you have no concept yet, and the output will default to generic.
+2. **Manufacture the ONE signature element** the brief asks for — the thing you'd describe first to a friend. Pick exactly one from a real vocabulary, biased by domain: a hero that *demonstrates not describes* (live terminal / real chart / actual diff), an owned type moment, a structural signature (asymmetric split, horizontal feature rail, editorial index), a material signature (hairline grid, one grain pass, duotone), a motion signature, or a real-number/proof signature. Never default to "a gradient". It must be true to the product, and cite the research exemplar that inspired it.
+3. **Force scale contrast.** Generic pages are tonally flat — headline, titles, body all within ~1.5×. Make the hero dominant **3–5× the body**, demote eyebrows/labels/metadata smaller and quieter than feels comfortable, and allow **one focal point per viewport**. If a section feels flat, add contrast, not elements.
+4. **Give the page rhythm.** Ten identical `py-24` white card-grid sections read as one stripe. Vary format (full-bleed vs. contained, alternate media sides), background (a dark section between light ones anchors a CTA), density (a breathing statement after a dense grid), and container idiom (not everything is a bordered card). Inter-section gap > intra-section gap, padding stepping on the scale.
+
+Then, **before claiming done, run the senior-designer crit** and make at least one concrete change as a result: What is the one idea here (name it in a sentence)? Would this place on Awwwards/Godly or just pass review? What is the single most generic element right now — and replace it. Where does the eye land first, and is that what should win? If the logo were removed, would anyone know whose product this is? Does every section earn its place, or is one there out of habit (cut it)?
+
+Concept formula, signature vocabulary, scale/rhythm rules, the crit, and a worked generic→signature dev-tool hero → `references/signature-and-craft.md`.
 
 ## Visual system in 90 seconds
 
-Copy-pasteable foundation. Tokens once, consume everywhere.
+Copy-pasteable foundation. Tokens once, consume everywhere — design tokens, never magic numbers.
 
 - Tailwind v4 `@theme` block (OKLCH): tokens become CSS vars and utilities automatically — no `tailwind.config.js`.
 - Type scale via `next/font` (one display + one text face) plus a fluid `clamp()` ladder.
@@ -227,7 +166,9 @@ Full section-by-section anatomy, CTA cadence, pricing psychology, JSON-LD → `r
 
 ## Conversion copy in one pass
 
-- The 5s value-prop test: a stranger reads the hero and can say what it is, who it's for, why it's better.
+Copy is benefit-led and specific, or the page has no value prop. One `<h1>` per page; semantic landmarks (`header`/`nav`/`main`/`section`/`footer`).
+
+- The 5s value-prop test: a stranger reads the hero and can say what it is, who it's for, why it's better — legible above the fold in 5 seconds.
 - Headline formula slots: outcome + timeframe; "X without Y"; the job-to-be-done.
 - Framework picker: PAS for pain-aware cold traffic; AIDA for broad / top-of-funnel; FAB/JTBD for feature → benefit translation.
 - CTA: put the value on the button ("Start free", "Get my estimate"), never "Submit".
@@ -243,7 +184,7 @@ Frameworks, value-prop canvas, Bad→Good rewrites, VOICE block → `references/
 
 ## Motion & interaction budget
 
-- Purposeful-only: motion must guide attention, communicate state, or preserve continuity.
+- Purposeful-only: motion must guide attention, communicate state, or preserve continuity — else delete it.
 - Timing defaults: enter 200–350ms, exit ~150ms, press `scale(0.97)`.
 - Never `transition: all` — it animates layout props and janks.
 - Compositor-only properties: `transform`, `opacity`, `filter`.
@@ -293,7 +234,7 @@ img  { outline: 1px solid oklch(0 0 0 / 0.1); outline-offset: -1px; }
 
 Depth recipes, glass, noise, concentric math → `references/visual-system.md`.
 
-## Anti-patterns / rationalizations → STOP
+## Anti-patterns
 
 | Rationalization | Reality / Fix |
 | --- | --- |
@@ -309,6 +250,8 @@ Depth recipes, glass, noise, concentric math → `references/visual-system.md`.
 
 ## Quick reference
 
+Accessibility and Core Web Vitals are **design constraints, not post-launch tuning** — violating one is a defect, not a style choice. **WCAG 2.2 AA:** 4.5:1 text contrast (3:1 large text / UI), visible focus, `prefers-reduced-motion` honored. Target size: 24×24px is the AA floor (SC 2.5.8 Target Size (Minimum)); 44×44px is the recommended quality bar (Apple HIG / pointer comfort) — aim for 44, never ship below 24. **Core Web Vitals:** LCP < 2.5s, INP < 200ms, CLS < 0.1. (INP replaced FID in March 2024 — measure INP.)
+
 | Lever | Default | Token / where |
 | --- | --- | --- |
 | Type scale ratio | 1.25 | modular scale |
@@ -366,36 +309,11 @@ The checklist above is pass/fail. When the user asks for a *design review*, a *c
 
 Score = Σ(dimension × weight), max 115 (normalize to /100 by ×100/115 if you want a percentage). **Bands (on the /115 raw total):** < 69 ships generic — redo; 69–91 competent but improvable — name the lowest two and fix; 92–108 premium; 109+ award-tier. (These are the prior 60/80/95-per-100 cutoffs rescaled to 115.) A surface that scores well on every constraint dimension but low on #1–2 is the classic "competent but generic" result — fix concept and signature first, it has the most leverage. For each dimension below 8, give one concrete, actionable fix (not "improve spacing" but "section padding jumps 48→96px with no 64px step — add `py-16` on mobile"). Cite the brand article or trend source that sets the bar where relevant.
 
-## Project grounding (02-DOCS + CLAUDE.md)
-
-This skill's 02-DOCS record has two parts, both indexed in `02-DOCS/wiki/index.md` (the Knowledge
-map index; root `CLAUDE.md` points to it):
-
-- The **brand study** at `02-DOCS/wiki/brand/` — a hard gate (see "Brand grounding" above): if
-  missing or incomplete, ask until complete before designing.
-- The **design-system decisions** at `02-DOCS/wiki/stack/design.md` — the chosen tokens
-  (color/OKLCH, type scale, spacing, radius, shadow, motion), the 2026 direction picked, and the
-  reference sites. Recorded, not gated.
-
-Create/update both as decisions are made and index them in `02-DOCS/wiki/index.md` (the Knowledge map;
-root `CLAUDE.md` keeps only a short pointer to it). Read them first on every use and
-keep outputs consistent with them.
-
-## See Also
-
-**Sibling skills in this repo** (these resolve to real skills you can invoke):
-
-- `../marketing/SKILL.md` — the WORDS: value prop, hero/section copy, microcopy, launch, and SEO-aware copy structure + keyword/intent capture. Co-owns the `02-DOCS/wiki/brand/` study (it owns the words dimensions; this skill owns the visual ones). Hand off deep keyword/SEO/GEO work here.
-- `../nextjs/SKILL.md` — the BUILD: App Router / React 19 stack implementation.
-- `../flutter/SKILL.md` — mirror the brand tokens into a Flutter app.
-- `../harness/SKILL.md` — the `02-DOCS` wiki protocol the brand study follows.
+## Recording the decisions (02-DOCS)
 
-**External / inspiration references** (NOT skills in this repo — names of well-known craft references and external skill ecosystems, cited for direction, not invocable here):
+Two records, both indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it), both read first on every use so outputs stay consistent with them:
 
-- *frontend-design-direction* — product-domain design direction (e.g. dense internal tools vs sales pages); fold its judgment in via the DIRECTION BRIEF rather than expecting a sibling skill.
-- *make-interfaces-feel-better* — polish-pass micro-detail thinking; this skill's "Premium details that compound" table covers the same ground in-repo.
-- *motion-ui* / *motion-foundations* — deep motion-code mechanics (spring config, `AnimatePresence` internals, layout animations); this skill sets motion *intent + budget* and defers mechanics outward.
-- *product-lens* — validating the "why" before you build.
-- *liquid-glass-design* — native iOS 26 Liquid Glass material (this skill ships the *web* glass approximation only).
+- The **brand study** at `02-DOCS/wiki/brand/` — the hard gate above: missing or incomplete → ask until complete before designing.
+- The **design-system decisions** at `02-DOCS/wiki/stack/design.md` — the chosen tokens (color/OKLCH, type scale, spacing, radius, shadow, motion), the 2026 direction picked, and the reference sites. Recorded, not gated; create/update it as decisions are made.
 
-- References (in this skill): `references/brand-grounding.md`, `references/research-method.md`, `references/trends-2026.md`, `references/signature-and-craft.md`, `references/visual-system.md`, `references/landing-anatomy-and-cro.md`, `references/copywriting-frameworks.md`, `references/motion-and-interaction.md`.
+The wiki article protocol both follow is `../harness/SKILL.md`'s.