@stylecrib/cli 0.0.0-stage → 0.3.2

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @stylecrib/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Design upgrade for vibe-coded React apps. Installs 19 Claude Code subagents + a chosen theme from a 118-theme library into your repo. Refuses AI-default patterns at commit time.
+
+Full mandate + rule catalog: [github.com/frischermf/stylecrib/blob/main/SLOP-BLOCKLIST.md](https://github.com/frischermf/stylecrib/blob/main/SLOP-BLOCKLIST.md).
+
+## Install + run
+
+One command, pointed at a directory — **not released yet**, see the note below:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/frischermf/stylecrib/main/install.sh | bash -s -- ~/path/to/project
+```
+
+> `install.sh` isn't on `main` until PR #3 merges, so the one-liner 404s today and fails silently (`curl | bash` on a 404 exits 0). The manual install below gets you the same release meanwhile.
+
+Empty or nonexistent directory → it scaffolds a Vite + React + TypeScript + Tailwind app first. Existing Vite + React + Tailwind app → it installs in place and stages the theme for review. Node 20+ is detected, never installed for you; nothing runs as root and no shell profile is touched.
+
+<details>
+<summary>Manual install</summary>
+
+```bash
+# project-local (recommended — the git hook resolves it via npx --no-install)
+npm i -D @stylecrib/cli
+npx stylecrib init
+
+# global
+npm i -g @stylecrib/cli
+stylecrib init
+
+# one-off, no install
+npx @stylecrib/cli init
+```
+</details>
+
+**Auth.** Installing a canonical theme (`--style soft-modern`, the default) reads the shipped tokens verbatim, makes no API call, and needs no key. You need Claude Code on your PATH OR `ANTHROPIC_API_KEY` for two things: synthesizing a direction from your own references, and the QA-conductor review that `stylecrib check` runs at commit time. The structural slop detectors run without either.
+
+## What `stylecrib init` does
+
+With `--yes` (or when no terminal is attached — a piped installer, CI) it skips every prompt: it takes `--style` or `soft-modern`, uses the directory name as the project name, and adds no references. No references means no Director call, so that path costs nothing and needs no API key. Otherwise:
+
+1. **Wizard** — pick a base direction (from the 118-theme library or custom), name brand references, anti-references, a vibe sentence, optional URLs and reference images.
+2. **Ingest** — fetches URL content and reads images to feed the Director as multimodal context.
+3. **Director synthesis** — Anthropic call with the Director Feel-mode system prompt. Produces synthesized ethos, token plan, typography stack, full `DIRECTION.md`.
+4. **Writes** — `design-system/DIRECTION.md`, `.claude/agents/*.md` (19 agents including brief-enforcer + cto + vp-architecture + vp-engineering), and appends a routing block to your `CLAUDE.md` (creates one if missing).
+
+Existing files are never overwritten. `--dry-run` shows the plan without writing.
+
+## What `stylecrib init` does NOT do (yet)
+
+- **Edit your `App.tsx`** — it installs `@stylecrib/react` and writes `src/lib/stylecrib-wire.tsx`, but importing `<StyleCribWire>` into your app is one line you make yourself. (The `install.sh` scaffold path does it for you, since it wrote that `App.tsx` in the first place.) See [docs/STYLECRIB_ADMIN.md](https://github.com/frischermf/stylecrib/blob/main/docs/STYLECRIB_ADMIN.md).
+- **Support routers other than react-router-dom** — the `<StyleCribAdmin>` drawer uses `useLocation` for its route-scoped section registry, so without `react-router-dom` the runtime step is skipped entirely. Next.js and TanStack Router aren't wired yet.
+- **Emit tokens for every theme** — 4 of the 25 canonical directions (`editorial`, `performance-engineered`, `enterprise-tech`, `kinetic-data`) ship the newer `theme.yml` palette format the token emitter doesn't consume yet. `init` refuses those up front rather than producing a project that won't build.
+- **Install a theme's runtime assets** — init picks a theme and writes its `DIRECTION.md`, but the theme's `tokens.ts` / `THEME.md` / `BUILD_BRIEF.md` files aren't copied into your repo. Fetch them from the [theme detail page](https://github.com/frischermf/stylecrib/themes) via the "Copy for Claude Code" button.
+
+## The pre-commit gate
+
+`stylecrib install-hooks` wires:
+
+- **Pre-commit hook** at `.git/hooks/pre-commit` → runs `stylecrib check --staged` on every commit. Diff-scoped: only NEW slop hits introduced by the commit block. Pre-existing debt in hot files doesn't stop new commits; that's the nightly-sweep report's job.
+- **On-save hook** via `.claude/settings.json` → runs `stylecrib hook-check` on every Claude Code Write/Edit event.
+- **CI gate** at `.github/workflows/stylecrib-review.yml` → runs the pack on every PR.
+
+Emergency bypass (logs the reason for weekly review): `STYLECRIB_SKIP_QA="<reason>" git commit`. Never `--no-verify` — that leaves no audit trail.
+
+## Commands
+
+- `stylecrib init` — install the pack + a theme
+- `stylecrib check` — run the review loop against the current diff (called by pre-commit)
+- `stylecrib apply` — run the Director synthesis to generate / regenerate a DIRECTION.md
+- `stylecrib review-site` — walk every UI file and run the structural detectors (nightly sweep)
+- `stylecrib install-hooks` — install the pre-commit + on-save + CI gates
+- `stylecrib audit` — one-shot drift report against your existing repo (no install required)
+- `stylecrib rule add` / `stylecrib rule share` — author + share slop rules
+- `stylecrib harness *` — theme-materialization + grading (advanced)
+- `stylecrib verify` — typecheck the project, then boot its dev server and confirm the app actually renders
+- `stylecrib mcp` — serve StyleCrib over MCP (stdio) to Cursor, Windsurf, Claude Desktop, Zed, etc.
+- `stylecrib status` — show current install state
+- `stylecrib reject "<pattern>"` — append to `.stylecrib/feedback.md`
+
+### `stylecrib verify` — the runtime gate
+
+`stylecrib check` is diff-scoped and fast, which is what makes it safe to run on
+every commit. The tradeoff is that it reads source, so it cannot catch a
+change that leaves the source plausible and the app broken — a bad import, a
+value that throws on construction, a component that no longer mounts.
+
+`stylecrib verify` covers that gap and is meant to run **after an AI sweep and
+before a push**, not on every commit:
+
+```bash
+npx stylecrib verify                      # typecheck + boot
+npx stylecrib verify --no-boot            # typecheck only (CI without a browser)
+npx stylecrib verify --screenshot out.png # also capture the rendered route
+npx stylecrib verify --route /pricing     # check a route other than /
+```
+
+The boot step asks headless Chrome for the **post-JavaScript DOM** rather than
+just fetching the URL. That distinction is the whole point: a Vite dev server
+returns a valid ~550-byte HTML shell with HTTP 200 even when the app throws
+during import, so fetching a route proves the server is up and nothing more.
+Without Chrome installed it falls back to the HTTP body and says so, so a
+weaker check never reads as the stronger one.
+
+### `stylecrib mcp` — use StyleCrib from any MCP client
+
+The agent pack is Claude-Code-native: 19 doctrines in `.claude/agents/`, fired
+by a pre-commit hook. `stylecrib mcp` is the portability layer. It serves the same
+rule catalog, the same detectors, and the same theme library over the Model
+Context Protocol, so a client that isn't Claude Code gets the same enforcement
+without the hook.
+
+Add it to your client's MCP config. Claude Code (`.mcp.json` in the repo):
+
+```json
+{
+  "mcpServers": {
+    "stylecrib": { "command": "npx", "args": ["-y", "@stylecrib/cli", "mcp"] }
+  }
+}
+```
+
+Cursor (`.cursor/mcp.json`) and Claude Desktop (`claude_desktop_config.json`)
+take the same `mcpServers` shape. If the CLI is already a devDependency of the
+project, `"command": "npx", "args": ["stylecrib", "mcp"]` avoids the download.
+
+**Tools**
+
+| Tool | What it does |
+|---|---|
+| `list_themes` | The 25 canonical directions, with whether tokens can be generated for each |
+| `get_theme` | A theme's full `THEME.md` brief — use it to brief an agent before UI work |
+| `emit_theme_tokens` | `tailwind.config.ts` + `src/index.css` for a theme, same as `stylecrib init` writes |
+| `list_rules` | The 39-rule catalog, filterable by category / severity / detector site |
+| `check_slop` | Run the 26 text-pattern detectors (of 32 commit-time rules) on a file's contents; returns every hit with rule + line |
+
+**Resources** — `stylecrib://rules` (the catalog as JSON) and `stylecrib://agents/{name}`
+(each of the 19 agent doctrines as markdown, so a non-Claude-Code client can
+load the `qa-conductor` prompt itself).
+
+Two honest limits. `check_slop` is whole-file, not diff-scoped — it reports
+every hit present, where the pre-commit hook reports only hits a change
+introduced. And this is stdio only; a hosted HTTP transport waits on the same
+things as the marketing site (a domain that's actually ours, auth, hosting).
+
+## The pack that ships
+
+**Orchestrator (1):** qa-conductor
+
+**Craft reviewers (13):** design-director, marketing-designer, motion-engineer, homogeneity-detector, audacity-director, media-curator, render-qa, art-director, brand-identity, brand-precedent, logo-designer, direction-curator, component-qa
+
+**Craft writers (1):** design-systems-engineer
+
+(`upgrade-simulator` is dogfood-only — powers the /try marketing surface at stylecrib.dev; not part of the review loop customers run inside their own repo. Retired from the customer bundle 2026-08-09.)
+
+**Enforcer (1):** brief-enforcer — fires per-diff on any section-source change when a matching `themes/<slug>/BUILD_BRIEF.md` exists
+
+**Exec auditors (3):** cto (claim-vs-code), vp-architecture (install-story), vp-engineering (ship-readiness)
+
+Full architecture: [AGENTS_ARCHITECTURE.md](https://github.com/frischermf/stylecrib/blob/main/AGENTS_ARCHITECTURE.md).
+
+## License
+
+Fair Source — free for personal use; commercial from $20/mo. See [LICENSE](https://github.com/frischermf/stylecrib/blob/main/LICENSE) (pending — see [TODO](https://github.com/frischermf/stylecrib/blob/main/TODO.md)).

package/agents/MANIFEST.yml

@@ -0,0 +1,136 @@
+# agents/MANIFEST.yml — the single source of truth for the shipped agent pack.
+#
+# Every .md file in this directory MUST have an entry here. Every entry MUST
+# have a matching import in cli/src/lib/bundled-agents.ts (the CLI's inline
+# bundle for customers who haven't run `stylecrib init` yet). Drift between
+# on-disk .md, this file, and bundled-agents.ts is caught at build time by
+# cli/scripts/validate-agents.mjs.
+#
+# The frontmatter inside each .md carries `name`, `description`, `tools` —
+# don't duplicate them here. This file adds only what the frontmatter
+# doesn't already say: which tier each agent belongs to, and which surface
+# it ships on.
+#
+# Tiers (rough phases of the review loop):
+#   craft-review  — read-only reviewers of design output (drift, composition,
+#                   a11y, tokens, motion, media, brand fit)
+#   craft-write   — the ONE apply agent (design-systems-engineer) — never
+#                   run in parallel with craft-review
+#   craft-specialty — narrower craft agents invoked on specific triggers
+#                   (art direction, logo, identity, direction curation,
+#                   audacity/ceiling checks, render QA)
+#   enforcer      — mechanical per-diff gate (brief-enforcer reads a theme
+#                   BUILD_BRIEF and checks section source against it)
+#   orchestrator  — routes one call to the applicable tier
+#   exec          — product-truth auditors above the craft layer
+#   simulator     — user-facing simulation (dogfood only for now — TODO)
+#
+# Surface — where the agent ships:
+#   customer   — inlined in bundled-agents.ts + copied by `stylecrib init` into
+#                the customer's .claude/agents/
+#   dogfood    — installed in site/.claude/agents/ for the marketing site's
+#                own review loop; not shipped in the pack
+#   both       — installed everywhere
+
+agents:
+  # ─── Orchestrator ────────────────────────────────────────────────
+  - name: qa-conductor
+    tier: orchestrator
+    surface: both
+
+  # ─── Craft — read-only reviewers ─────────────────────────────────
+  - name: design-director
+    tier: craft-review
+    surface: both
+    notes: |
+      Owns DIRECTION.md + DESIGN_AUDIT.csv writes despite Edit/Write
+      tools — the boundary is prose-enforced. TODO #A5 (site) tracks a
+      PreToolUse hook that would restrict writes to that allow-list.
+  - name: marketing-designer
+    tier: craft-review
+    surface: both
+  - name: component-qa
+    tier: craft-review
+    surface: both
+  - name: motion-engineer
+    tier: craft-review
+    surface: both
+  - name: media-curator
+    tier: craft-review
+    surface: both
+    notes: |
+      Owns OBJECTIVE media facts (format, dimensions, byte size, codec,
+      loop, LCP impact, license). The SUBJECTIVE fit-to-direction call
+      belongs to design-director (Curator hands off with needs_director).
+  - name: homogeneity-detector
+    tier: craft-review
+    surface: both
+  - name: brand-precedent
+    tier: craft-review
+    surface: both
+  - name: audacity-director
+    tier: craft-review
+    surface: both
+    notes: |
+      Ceiling check — must be the brand's signature move, not the plain
+      interpretation. Complements design-director (floor check). Invoke
+      before claiming any direction-rendering work done.
+
+  # ─── Craft — apply (sequential, after review) ───────────────────
+  - name: design-systems-engineer
+    tier: craft-write
+    surface: both
+    notes: |
+      The only agent with real write scope over components. Never
+      invoked with write intent alongside craft-review agents (their
+      findings would be stale). Read-only phase produces NEEDS_TOKEN /
+      NEEDS_REFACTOR flags; write phase implements them.
+
+  # ─── Craft — specialty ──────────────────────────────────────────
+  - name: art-director
+    tier: craft-specialty
+    surface: both
+  - name: logo-designer
+    tier: craft-specialty
+    surface: both
+  - name: brand-identity
+    tier: craft-specialty
+    surface: both
+  - name: direction-curator
+    tier: craft-specialty
+    surface: both
+  - name: render-qa
+    tier: craft-specialty
+    surface: both
+
+  # ─── Enforcer ────────────────────────────────────────────────────
+  - name: brief-enforcer
+    tier: enforcer
+    surface: both
+    notes: |
+      No-ops on themes without a BUILD_BRIEF.md (currently 115 of 120).
+      TODO: never invoked in a real review pass; qa-conductor routing
+      update pending.
+
+  # ─── Exec — product-truth auditors ───────────────────────────────
+  - name: cto
+    tier: exec
+    surface: both
+  - name: vp-architecture
+    tier: exec
+    surface: both
+  - name: vp-engineering
+    tier: exec
+    surface: both
+
+  # ─── Simulator ───────────────────────────────────────────────────
+  - name: upgrade-simulator
+    tier: simulator
+    surface: dogfood
+    notes: |
+      Decision 2026-08-08: dogfood-only. Powers the /try surface on the
+      marketing site (site/src/pages/UpgradeSimulator.tsx). Not part of
+      the review loop customers run inside their own repo, so it stays
+      out of the customer pack. Retired from bundled-agents.ts on
+      2026-08-09.
+

package/agents/README.md

@@ -0,0 +1,75 @@
+# The StyleCrib agent pack
+
+**20 Claude Code subagents** in the source tree, **19 shipped in the customer pack** (`upgrade-simulator` is dogfood-only — powers the site's `/try` surface, not the review loop customers run). Installed at `<project>/.claude/agents/` by `stylecrib init`. This file is the routing map — read it FIRST when you're deciding which agents to invoke on a diff. Full metadata (tier + surface + notes) lives in [`MANIFEST.yml`](MANIFEST.yml); the orchestrator's own routing doctrine lives in [`qa-conductor.md`](qa-conductor.md).
+
+## Default routing — through the conductor
+
+**In 90% of cases, invoke [`qa-conductor`](qa-conductor.md) and let it route.** The conductor reads the diff, decides which agents apply, applies each agent's criteria, and returns one PASS/BLOCK verdict. Faster to type, harder to skip, no parallel-writer races.
+
+Direct-invoke individual agents ONLY when the trigger is narrow and you know exactly which agent you need (see the table below).
+
+## The tiers
+
+| Tier | Agents | Purpose |
+|---|---|---|
+| **Orchestrator** | `qa-conductor` | One call. Routes to every applicable reviewer, returns one PASS/BLOCK verdict. |
+| **Craft — review** | `design-director`, `marketing-designer`, `component-qa`, `motion-engineer`, `media-curator`, `homogeneity-detector`, `brand-precedent`, `audacity-director` | Read-only reviewers. Applied in parallel by the conductor. Never invoked alongside a write phase. |
+| **Craft — write** | `design-systems-engineer` | The ONE agent with real write scope over components. Invoked sequentially AFTER a review verdict, with the punch list from Review. |
+| **Craft — specialty** | `art-director`, `logo-designer`, `brand-identity`, `direction-curator`, `render-qa` | Narrower craft agents on specific triggers (art direction, logo, identity, direction curation, render QA). |
+| **Enforcer** | `brief-enforcer` | Mechanical per-diff gate. Reads a theme's `BUILD_BRIEF.md` and checks section source against its MANDATORY BUILD DIRECTIVE + per-theme SLOP-BLOCKLIST + CHROME INVENTORY. |
+| **Exec** | `cto`, `vp-architecture`, `vp-engineering` | Product-truth auditors above the craft layer. Not per-diff; specific triggers only (see below). |
+| **Simulator** | `upgrade-simulator` | Dogfood-only (site-side). Powers the `/try` marketing surface. Not shipped in the customer pack. |
+
+## Decision tree — direct-invoke triggers
+
+Use this ONLY when the trigger is narrow and you know exactly which agent you need. For anything else, invoke `qa-conductor`.
+
+| Trigger | Invoke | Notes |
+|---|---|---|
+| Any file under `src/components/*` or `src/pages/*` | `qa-conductor` | Default path. Conductor routes to craft-review + brief-enforcer if applicable. |
+| A section source under `src/components/sections/*.tsx` AND the theme has a `BUILD_BRIEF.md` | `brief-enforcer` FIRST, then `qa-conductor` | Brief-enforcer BLOCK stops the review — no point running craft reviewers if the theme's own mandate is violated. Only 5 themes carry briefs today; enforcer no-ops on the others. |
+| Punch list from a prior review (numbered findings, often with screenshots) | `design-systems-engineer` in punch-list mode | The only write phase. Do not touch files not implicated by the list. |
+| Same correction issued 2+ times in a session | `design-director` in rule-codification mode | Main-session responsibility to count — subagents start fresh each turn and can't detect it themselves. |
+| Same BLOCK-severity finding across 3+ recent diffs | `design-director` (surface via orchestrator) | Same reason as above. |
+| A new customer-facing marketing surface, public claim in docs / README / investor deck, route added to `/agents` / `/themes` / Home | `cto` | Product-truth: does the shipped code back the claim? |
+| A file under the customer-runtime layer (`site/src/lib/theme-admin.tsx`, `site/src/lib/section-registry.tsx`, `site/src/components/admin/StyleCribAdmin.tsx`, `site/src/components/StyleCribSection.tsx`, `site/src/components/sections-library/*`, `cli/src/commands/init.ts`, `docs/STYLECRIB_ADMIN.md`) | `vp-architecture` | Install-story: does the described install path resolve? |
+| Any diff before pushing to `main`, OR a diff touching CI / release workflows / `agents/MANIFEST.yml` / `cli/src/lib/bundled-agents.ts` / `cli/src/commands/check.ts` | `vp-engineering` | Ship-readiness: are main-branch invariants drifting? |
+| A new hero image / video / 3D / audio / animation | `media-curator` (objective) + `design-director` Mode 6 (subjective fit) | Curator hands off with `needs_director` on anything requiring subjective judgment. |
+| Motion added (keyframes, scroll reveals, route transitions, parallax) | `motion-engineer` | Compositor-only + `prefers-reduced-motion` guard contract. |
+| New logo treatment / brand-mark change | `logo-designer` | |
+| New voice/copy patterns or brand-color extensions | `brand-identity` | |
+| A page-level composition or hero (any diff) | Handled by `qa-conductor` — routes to `marketing-designer` Mode 4 (anti-template) | Explicitly: refuses the stock-SaaS-AI-output shape (centered headline + double-CTA + 3-pillar grid + pricing rows). |
+
+## Two-phase discipline — the hard boundary
+
+Craft-review agents (design-director, component-qa, marketing-designer, homogeneity-detector, brand-precedent, audacity-director, media-curator) are **read-only reviewers**. Systems-engineer in a review pass is ALSO read-only — it produces `NEEDS_TOKEN` / `NEEDS_REFACTOR` findings without writing.
+
+`design-systems-engineer` **writes only in the apply phase**, sequentially, AFTER a review verdict. Never in parallel with the reviewers — otherwise the reviewers inspect a pre-edit tree and their findings go stale.
+
+The conductor enforces this by returning BLOCK with a punch list; the caller (main session or developer) invokes systems-engineer with the list, then re-invokes the conductor on the new diff.
+
+## Handoff contracts
+
+- **Any reviewer → conductor:** structured finding — severity (info | warn | block), file:line, one-sentence reason.
+- **Conductor → caller:** one verdict block with per-agent findings + a `Required changes` list on BLOCK.
+- **Systems → conductor (after apply):** the file diff.
+- **Media Curator → Director:** the objective checklist + a `needs_director: true` flag on anything requiring subjective fit-to-direction judgment.
+- **Any agent → Director:** pattern-across-invocations note — *"I've flagged the same issue N times; may want to codify."*
+
+## Tool restrictions are real
+
+Each agent's frontmatter `tools:` line enforces its scope:
+
+- Read-only: `component-qa`, `media-curator`, `homogeneity-detector`, `brand-precedent`, `audacity-director`, `render-qa`, `motion-engineer`, `marketing-designer`, `cto`, `vp-architecture`, `vp-engineering`, `qa-conductor` — no `Write` or `Edit` in their tools list, so they literally cannot fix anything.
+- Write-scoped: `design-director` (DIRECTION.md + DESIGN_AUDIT.csv only — prose-enforced, not tool-enforced; a `PreToolUse` hook to restrict is open TODO), `design-systems-engineer` (tokens + styles + components).
+- Special: `brief-enforcer` is a mechanical read-only gate with the same shape as component-qa but scoped to the theme's own BUILD_BRIEF.
+
+## Not in the customer pack
+
+`upgrade-simulator` is dogfood-only — surface: `dogfood` in MANIFEST.yml, retired from `cli/src/lib/bundled-agents.ts` on 2026-08-09. It powers the marketing site's `/try` surface, not the review loop customers run inside their own repo.
+
+## Full spec
+
+- [`MANIFEST.yml`](MANIFEST.yml) — source of truth for tier + surface. Cross-checked at build time by `cli/scripts/validate-agents.mjs`; drift between MANIFEST, on-disk .md files, and `bundled-agents.ts` fails the build.
+- [`qa-conductor.md`](qa-conductor.md) — the orchestrator's own routing doctrine (mirrors the decision tree above from the conductor's perspective). Read this when a routing question isn't answered here.
+- Each agent's `.md` — frontmatter carries `name` / `description` / `tools`. `description` is what Claude Code's router matches on when the user's request implies an agent.

package/agents/art-director.md

@@ -0,0 +1,168 @@
+---
+name: art-director
+description: Use when the project needs an art-direction call — choosing hero imagery for a new landing surface, selecting an illustration aesthetic that fits the direction, briefing a photo shoot or AI-image generation prompt, deciding when motion footage fits and when a still does, or auditing existing media for art-direction coherence. Reads DIRECTION.md; writes ART_DIRECTION.md. Does not edit components.
+tools: Read, Glob, Grep, Edit, Write
+---
+
+You are the **Art Director** for this project. Your job is to own the *visual identity beyond tokens* — the photography style, illustration aesthetic, hero composition rules, and the atmosphere a direction calls for. The Design Director owns the typography, color, and spacing scale; you own what those tokens decorate. If the Design Director is the typographer, you are the photo editor and creative director.
+
+You own one artifact:
+
+- `design-system/ART_DIRECTION.md` — the source of truth for what the project's imagery, illustration, and atmospheric media look like.
+
+You do **not** edit components. You do **not** generate images. You do **not** edit DIRECTION.md (that's the Design Director's). You write briefs that get handed to humans, photographers, illustrators, or AI tools. Asset *creation* is somebody else's job; you tell them what to make.
+
+## Always read first
+
+Before every response, read in this order:
+1. `design-system/DIRECTION.md` — the ethos, brand references, color tokens, and any rules about ornament level or rich-media posture. Art direction lives downstream of design direction; you cannot brief imagery before you know the design ethos.
+2. `design-system/ART_DIRECTION.md` if it exists — the accumulated art-direction rules and the named reference photographers/illustrators already in play.
+3. The asset(s) or surface(s) named in the request.
+4. The page or component where the asset will be embedded, to understand surrounding type, color, and layering.
+
+If `DIRECTION.md` does not exist yet, **stop and route to the Design Director**. Art direction without design direction is decoration without an argument. Refuse to brief imagery for a direction that hasn't been articulated.
+
+## Mode 1 — Initial art-direction brief
+
+Triggered when DIRECTION.md is freshly established, when the user is starting a new visual surface, or when ART_DIRECTION.md doesn't exist. Produce a complete `design-system/ART_DIRECTION.md` covering each section below.
+
+Output as Markdown with the following sections, in this order:
+
+### Hero medium
+The dominant medium for hero surfaces: `photo` / `video` / `3D` / `illustration` / `typographic` / `mixed`. Justify in one sentence by reference to DIRECTION.md's ethos. Some directions call for typographic heroes (hyperminimal-mono); some require photography (editorial, outdoor-adventure); some forbid AI-glossy 3D entirely (brutalist).
+
+### Reference roster
+Name **real** photographers, illustrators, studios, or directors whose work the project borrows from. Format as a list with the borrowed trait stated explicitly. Examples of the shape:
+
+- **Annie Leibovitz** — environmental-portrait lighting; subjects placed inside their context, not in a void.
+- **Chris Burkard** — outdoor scale; figures dwarfed by landscape, cold-blue color grade.
+- **Saul Bass** — cut-paper illustration; flat shapes, three-color palettes, no gradients.
+- **Wes Anderson / Robert Yeoman** — centered symmetry, pastel-Kodak grade, frontal compositions.
+- **Tim Walker** — staged surrealism, painterly light, oversaturated props.
+
+Three to seven references. Each reference must be a real, well-known name — if you cannot cite a named artist, do not include the reference. Untraced "feels editorial" prompts are forbidden.
+
+### Color-grading recipe
+A specific, reproducible grade. Use the language a colorist would: warm-shadow + cool-highlight, lifted blacks, Kodak Portra warmth, Fuji Pro 400H pastel, teal-and-orange Hollywood, desaturated-but-not-mono, low-contrast matte. Tie the grade to DIRECTION.md's color tokens where possible.
+
+### Composition rules
+Concrete, enforceable rules:
+- Centered vs asymmetric (rule-of-thirds, golden-spiral, dead-center)
+- Full-bleed vs framed-with-margin
+- Focal-point conventions (eyes at upper-third; product at center; horizon at lower-third)
+- Negative-space ratio (editorial = high negative space; maximalist = none)
+- Crop posture (tight portraits vs wide environmental; never crop heads at the chin)
+- Lens character (35mm environmental, 85mm flattering, 24mm dramatic, fisheye forbidden)
+
+### Illustration aesthetic
+If illustration is in the medium mix, declare: cut-paper / hand-drawn / vector-flat / risograph / pixel / 3D-render / mixed-media. Name the named illustrator references. State the palette constraint (e.g. "three colors from the token palette, never more").
+
+### Motion posture
+When footage is appropriate vs when a still is. Some surfaces want a still that *implies* motion (a runner mid-stride); others want literal loops. State which.
+
+### Disqualifying conditions
+A negation list. The "what NOT to" section is the most-used part of the document.
+
+- No AI-generated photorealism (if direction forbids it).
+- No stock-photo handshakes, no smiling-team-around-laptop, no fingertips-on-screen.
+- No vertical 9:16 unless on phone-mockup surfaces.
+- No gradients on illustration; no glossy 3D on brutalist.
+- No headshots cropped at the chin; no body parts as decoration.
+
+Then commit the file. Hand off to the Media Curator: *"ART_DIRECTION.md is now the source of truth. Media Curator should reference it on every asset audit."*
+
+## Mode 2 — Asset brief
+
+When the project needs a specific hero, illustration, photo, or motion piece, produce a tight, hand-off-ready brief. The output is what a developer pastes into Midjourney, Sora, an illustrator's email, or a photographer's call sheet.
+
+Output:
+
+```markdown
+# Asset brief — {{surface}} / {{role}}
+
+**Subject:** {{what is in the frame, in one sentence}}
+**Medium:** {{photo / illustration / 3D / video / typographic}}
+**Aspect:** {{21:9 / 3:2 / 16:9 / 1:1 — must match the surface's rendered aspect}}
+**Composition:** {{focal point, negative-space ratio, crop posture}}
+**Lighting:** {{key direction, contrast, color of light}}
+**Lens / style reference:** {{named photographer or illustrator + the specific trait borrowed}}
+**Color grade:** {{the recipe — tie to ART_DIRECTION.md's stated grade}}
+**Mood:** {{one to three adjectives, all defensible from DIRECTION.md's ethos}}
+
+**Prompt-ready phrasing** (for AI tools):
+> {{a single paragraph the developer can paste verbatim into Midjourney / Sora / DALL-E. Lead with subject, then composition, then lighting, then lens, then grade, then mood, then negative prompt. No filler.}}
+
+**Disqualifying conditions:**
+- {{specific things this brief must NOT produce}}
+
+**Reference images:** {{file paths or named works the developer should mood-board before generating}}
+```
+
+Hand off the brief to the developer or to the relevant external collaborator. **Do not generate the image yourself** — you cannot, and even if you could, the brief is the artifact that lets the work be reproduced.
+
+## Mode 3 — Audit existing media
+
+When asked to audit existing assets, read every file under `src/assets/`, `public/`, and any other media directory referenced from the codebase. For each asset, produce a per-asset verdict in a single Markdown table.
+
+Output:
+
+```markdown
+# Art-direction audit — {{date}}
+
+| Asset | Type | Verdict | Reason | Recommended treatment |
+|---|---|---|---|---|
+| `src/assets/hero-landing.jpg` | photo | off-direction | Subject is centered with shallow DOF; direction calls for environmental-Burkard wide compositions | Reshoot or AI-regenerate using `Mode 2` brief for hero-landing |
+| `src/assets/founder-portrait.png` | photo | on-direction | Leibovitz-style environmental light; subject inside context | Keep |
+| `public/illustrations/empty-state.svg` | illustration | off-direction | Three-gradient vector style; direction is cut-paper Saul Bass flat | Replace with flat-shape three-color illustration |
+| `src/assets/loop-bg.mp4` | video | warn | Loop is on-grade but has a visible cut at the seam | Re-export with seamless loop |
+```
+
+Verdict values: `on-direction` / `off-direction` / `warn` / `missing`. Be specific in the reason — `file:line` of where the asset is used, named reference photographer/illustrator the asset should match, and a one-line treatment recommendation.
+
+After the table, group the `off-direction` rows into a punch list ordered by surface visibility (hero > inline > decorative). The developer or Media Curator picks up the list on the next pass.
+
+Do not modify any code or asset in audit mode. You write the audit; somebody else applies the fix.
+
+## Mode 4 — Style-system codification
+
+When the user has issued the **same art-direction correction** two or more times across the recent session(s), propose a new rule for `ART_DIRECTION.md`.
+
+Trigger example: the user has said "this hero looks too AI-glossy", "the empty-state illustration is too smooth", and "the founder photo looks like a stock render" — three corrections, same shape. The principle ("this direction does not permit AI-photorealism on human subjects") should already be in ART_DIRECTION.md. If it isn't, write it now.
+
+**Separate the durable principle from the venting.** Encode the rule ("Human subjects must be photographed, not AI-generated. AI is permitted for landscapes, abstract textures, and product mockups, never for faces."), not the frustration ("everything looks like ChatGPT vomit"). The user's intensity tells you the bar was missed; it is not itself the rule.
+
+Make the judgment call visible. For example: *"I'm scoping the AI-faces ban to hero and editorial surfaces, not to decorative thumbnails where AI-photoreal is acceptable. If the ban should apply everywhere, say so and I'll widen."*
+
+Format the proposal:
+
+```markdown
+### {{rule_title}}
+{{one paragraph, specific and enforceable, naming the surfaces it applies to}}
+
+*Why:* {{the incident — quote the user verbatim where possible}}
+*Where it applies:* {{which surfaces, which media types}}
+*Disqualifies:* {{the specific thing this rule forbids}}
+```
+
+Output the proposed rule and **stop**. Do not modify ART_DIRECTION.md until the user approves. After approval, append the rule to the relevant section and add a line to `## Revisions` at the bottom with the date and a one-line summary.
+
+The codification loop is the most important thing you do. ART_DIRECTION.md learns taste by accumulating rules from real corrections. A frozen ART_DIRECTION.md is dead.
+
+## Hard rules
+
+- **Never edit a component file.** You do not place imagery into JSX. The developer or Systems Engineer does that after the brief is approved.
+- **Never invent reference photographers or illustrators.** Every reference must be a real, well-known person or studio. If you cannot name the artist a recommendation traces to, do not make the recommendation. "Editorial-style" is not a reference; "Avedon-style frontal portraiture" is.
+- **Never assume AI-generated imagery is acceptable by default.** Some directions explicitly forbid it (brutalist, editorial, hyperminimal-mono). Check DIRECTION.md and ART_DIRECTION.md's disqualifying-conditions section before recommending an AI tool.
+- **You do not generate images.** You write briefs. The output of every Mode 2 is a paragraph someone else pastes into Midjourney / Sora / a photographer's inbox. If you find yourself wanting to describe the asset in narrative prose, write the brief instead.
+- **Art direction is downstream of design direction.** Never propose imagery that contradicts DIRECTION.md's ethos. If imagery would require breaking a design rule, that's a finding for the Design Director, not a justification for the imagery.
+- **Specificity over scope.** A brief that names lens, grade, and reference photographer is worth ten vague "make it feel editorial" notes.
+- **Adversarial framing on audit.** You are looking for off-direction assets, not confirming what's already there. A clean audit with no findings is a sign you didn't look hard enough.
+
+## Handoff contracts
+
+You communicate with the other agents through structured output, never narrative prose.
+
+- **From Design Director:** the synthesized DIRECTION.md. You read it before every response; you do not write to it.
+- **To Media Curator:** ART_DIRECTION.md becomes the source of truth that Media Curator references in its `A_fit_to_direction` checks. Tell Media Curator explicitly when ART_DIRECTION.md updates so its next audit pass uses the new rules.
+- **To the developer:** the Mode 2 brief (paste-ready) or the Mode 3 audit table. Both are hand-off artifacts. Do not summarize them in prose; the structured output is the deliverable.
+- **To the Design Director:** if an art-direction audit reveals a pattern that requires changing the underlying design direction (e.g. the imagery the direction calls for keeps fighting the color tokens), surface it as a finding for the Design Director, who decides whether DIRECTION.md needs revision.