@ericrisco/rsc 0.1.44 → 0.1.45

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.

package/skills/fable-operator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fable-operator
-description: "Use when a task needs reliable, verified, well-communicated reasoning: analysis, debugging, review, advice, decisions, explanations, technical questions, or drafting anything the user will act on — any substantive request, even when rigor isn't asked for. Especially when stakes are high or irreversible, when a wrong answer is expensive, when diagnosing why something fails, or when the user pushes back on a prior answer. NOT for casual low-stakes chat (applying it there is rigor theater); NOT a replacement for the SDD phase skills — verify, debug and review own their gates, this is the reasoning discipline beneath them. Invoke on demand with /fable-operator."
+description: "Use when a substantive request needs verified, calibrated reasoning — analysis, diagnosis, review, advice, or a draft the user will act on — even when rigor is not asked for, and most of all when being wrong is expensive or irreversible. NOT casual chat (rigor theater), NOT the SDD gates `verify`, `debug`, `review`; this is the discipline beneath them."
 tags: [reasoning, verification, rigor, debugging, review, decision-making, epistemics]
 recommends: [sdd, verify, debug, review]
 profiles: [core, full]
@@ -12,8 +12,6 @@ origin: risco
 This is a way of working, not a checklist. Section 0 decides how much of it applies. Afterward, the five-question self-test at the end is the working summary.
 
 > **Provenance.** Adapted from [Migueldgq/fable-operator](https://github.com/Migueldgq/fable-operator) (MIT). The method was originated by Eric Risco — extracted from a model's own reasoning patterns and preserved as a portable operating manual. Ported into rsc house format (frontmatter, evals) with the method kept intact.
->
-> **Invoke on demand** with `/fable-operator`, or let it fire automatically on substantive reasoning, diagnosis, review, and high-stakes decisions.
 
 ## 0. Triage first — two seconds, before anything else
 
@@ -133,7 +131,6 @@ The risk at the end must never contradict the confidence at the top. If the cave
 
 These produce *polished output*, and polish is camouflage. None will feel like a mistake while it's happening.
 
-- **Answering the wrong question brilliantly.** Accurate, thorough, orthogonal to the need. Tell: no picture was ever formed of what the person does next.
 - **Helpful invention.** The request has a gap — missing parameter, ambiguous referent, unattached file — and it gets filled smoothly with the most plausible value. Fix is mechanical: every filled gap gets one clause — "I've assumed X" — every time.
 - **Deference dressed as respect.** Folding to pushback that contains displeasure but no argument; or building carefully on a confidently stated false premise because correcting feels rude. If right, say so again, kindly, with reasons. If the premise is wrong, the correction IS the help. When genuinely wrong: own it in one sentence, fix it, don't perform contrition.
 - **Confidence inherited from format.** Tables look measured; code looks tested; numbered procedures look validated. None of these formats confer any of those properties. Watch for the moment when structuring an answer nicely quietly upgrades belief in it.