@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/image-gen/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: image-gen
+description: >
+  Generate images using the brand's visual identity and Gemini API. Reads
+  brand/creative-kit.md for visual style, crafts narrative prompts, and produces
+  images via Nano Banana Pro (gemini-3-pro-image-preview). Supports on-brand
+  and freestyle modes. Use when the user needs a blog header, social graphic,
+  product shot, hero image, banner, thumbnail, or any generated image. Also use
+  proactively when building content that would benefit from visuals. Triggers on
+  "generate image", "create image", "make me an image", "blog header", "social
+  graphic", "product shot", "hero image", "banner", "thumbnail", "I need an
+  image", "visual for", or any request for generated artwork. Even if they just
+  say "image" or "picture for this" — this is the skill.
+reads:
+  - brand/voice-profile.md
+  - brand/positioning.md
+  - brand/creative-kit.md
+  - brand/landscape.md
+writes:
+  - brand/assets.md
+depends-on: []
+triggers:
+  - generate image
+  - create image
+  - blog header
+  - social graphic
+  - product shot
+  - need an image
+  - make me an image
+  - visual for
+  - hero image
+  - banner
+  - thumbnail
+allowed-tools:
+  - Bash(python3 *)
+---
+
+# /image-gen — On-Brand Image Generation
+
+Describe what you need. Get an image that looks like your brand made it.
+
+This skill reads your visual brand identity from `brand/creative-kit.md`, crafts a narrative prompt that bakes in your style constraints, and generates the image via Gemini API. No brand style defined yet? It still works — just at a lower enhancement level. Run `/visual-style` first for the best results.
+
+---
+
+## On Activation
+
+1. Check `GEMINI_API_KEY` environment variable.
+   - If missing: "Image generation requires a Gemini API key. Set GEMINI_API_KEY in your environment. Get one at ai.google.dev."
+   - Do not proceed without it.
+
+2. Read brand files in priority order:
+   - `brand/creative-kit.md` — look for `## Visual Brand Style` section
+   - `brand/voice-profile.md` — personality informs image tone
+   - `brand/positioning.md` — angles inform visual metaphors
+   - `brand/landscape.md` — Claims Blacklist (don't generate imagery that visually implies blacklisted claims)
+
+3. Determine enhancement level:
+
+| Level | Context available | Image quality |
+|-------|------------------|---------------|
+| L0 | No brand files | Good generic images — uses discovery questions + prompt craft |
+| L1 | voice-profile.md | Personality-aligned — playful brand gets warm/bright images |
+| L2 | + creative-kit.md colors/typography | Color-constrained — palette woven into prompts |
+| L3 | + Visual Brand Style section | Fully on-brand — style anchors, lighting, mood, composition all applied |
+
+---
+
+## Phase 1: Discovery
+
+Use AskUserQuestion. Ask one at a time. Skip questions the user already answered in their request.
+
+**Question 1: Purpose**
+"What's this image for?"
+- Blog header / article illustration
+- Social media post (which platform?)
+- Product shot / marketing asset
+- Hero image / landing page
+- Presentation / slide deck
+- Something else (describe it)
+
+This determines aspect ratio:
+
+| Use case | Default ratio | Resolution |
+|----------|---------------|------------|
+| Blog header | 16:9 | 2K |
+| Social square | 1:1 | 2K |
+| Social story | 9:16 | 2K |
+| Hero / banner | 21:9 | 2K |
+| Product shot | 4:3 | 4K |
+| Thumbnail | 16:9 | 1K |
+
+**Question 2: Feeling**
+"What should someone feel when they see this?"
+(Free text — this drives the prompt's emotional anchor)
+
+**Question 3: Style override** (only if L3 brand style exists)
+"Use your on-brand style, or something different?"
+- On-brand (default) — applies Visual Brand Style from creative-kit.md
+- Different — describe the style you want instead
+
+If user picks "different," their description overrides the brand style for this image only.
+
+**Skip discovery when:** The user's request is specific enough. "Generate a 16:9 blog header showing a glowing terminal on a dark background, warm rim lighting" — don't ask what they want, they just told you.
+
+---
+
+## Phase 2: Prompt Crafting (Nano Banana Prompt Engineering)
+
+You are an expert Nano Banana prompt engineer. Your job is to turn the user's brief into a single, high-quality prompt for Nano Banana 2 (or Pro), a "thinking" image model used for professional asset production.
+
+**Core principle: brief a senior art director, don't list keywords.** Write natural language in full sentences. Never use "tag soup" like "dog, park, 4k, realistic."
+
+### The 10 Rules
+
+**1. General style.** Be specific and descriptive about subject, setting, composition, camera/viewpoint, lighting, mood, materials, and textures. Full sentences, not comma lists.
+
+**2. Context and purpose.** Always encode the purpose and audience (YouTube thumbnail, app icon, hero banner, tweet graphic, 4K wallpaper). Let purpose guide style, polish level, and framing.
+
+**3. Text and infographics.** If text must appear, put it clearly in quotes in the prompt. Ask for legible, clean typography and specify style (bold sans-serif, monospace, handwritten). For data, ask the model to compress into infographics, diagrams, or whiteboards.
+
+**4. Character and brand consistency.** When reference images exist, explicitly refer to them: "Keep the person's facial features exactly the same as Image 1." Allow changes in pose, expression, angle while preserving identity.
+
+**5. Grounding and realism.** For real data, locations, or products, tell the model to rely on up-to-date factual knowledge. Encourage coherent details consistent with physics.
+
+**6. Editing and restoration.** For edits to existing images, give semantic instructions: "remove," "replace," "add," "restore," "change the season." Maintain original structure, only change what's intended.
+
+**7. Dimensional and structural control.** For floor plans, schematics, wireframes, grids, tell the model to follow that layout closely. For 2D↔3D, describe how the new representation should look while preserving key relationships.
+
+**8. Resolution, detail, and format.** Specify resolution ("high detail suitable for 4K wallpaper," "clean 16:9 thumbnail"). Call out micro details and textures when needed (brushed steel, cracked paint, mossy stone).
+
+**9. Narrative and sequences.** For multiple images, describe the story arc, emotional beats, what stays consistent across images. Specify count, format, and identity/style consistency.
+
+**10. Output rules.** Do not ask follow-up questions about the prompt. Resolve small ambiguities with sensible professional defaults. Output a single flowing narrative prompt.
+
+### Prompt Structure
+
+Build the narrative in this order, woven into flowing prose:
+
+1. **Purpose and format** — what this is for, aspect ratio, resolution
+2. **Scene** — what's happening, where, environment
+3. **Subject** — detailed description with textures, materials, poses
+4. **Composition** — framing, focal point, depth of field, negative space
+5. **Lighting** — source, quality, color temperature, interaction with materials
+6. **Mood** — emotional tone, atmosphere
+7. **Text** — any text in quotes with typography specification
+8. **Technical** — camera/lens for photorealistic, style reference for illustrated
+
+### Brand Constraints (L3)
+
+When Visual Brand Style exists, weave constraints INTO the narrative — don't add as a separate block:
+
+- Primary Aesthetic → sets overall style direction
+- Lighting → overrides generic lighting with brand-specific lighting
+- Backgrounds → constrains background treatment
+- Composition → constrains layout/framing
+- Mood → anchors emotional tone
+- Avoid → explicit exclusions baked into prompt
+- Reference Prompts → use as structural templates, adapting subject matter
+
+See [references/prompt-patterns.md](references/prompt-patterns.md) for proven patterns.
+See [references/visual-metaphors.md](references/visual-metaphors.md) for concept-to-metaphor mapping.
+
+---
+
+## Phase 3: Generate
+
+### Gemini API Call
+
+```python
+import os
+from google import genai
+from google.genai import types
+
+client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
+
+response = client.models.generate_content(
+    model="gemini-3.1-flash-image-preview",
+    contents=["<narrative prompt>"],
+    config=types.GenerateContentConfig(
+        response_modalities=['TEXT', 'IMAGE'],
+        image_config=types.ImageConfig(
+            aspect_ratio="<ratio>",
+            image_size="<resolution>",
+        ),
+    ),
+)
+
+for part in response.parts:
+    if part.text:
+        print(part.text)
+    elif part.inline_data:
+        image = part.as_image()
+        image.save("output.png")
+```
+
+**Default to `gemini-3.1-flash-image-preview` (Nano Banana 2).** Launched Feb 26, 2026. Pro quality at Flash speed/pricing. 4K support, up to 14 reference images for style consistency. Use `gemini-3-pro-image-preview` (Nano Banana Pro) only when text-heavy infographics or premium quality justify the higher cost.
+
+### Save and Log
+
+1. Save image to project directory (e.g., `images/`, `assets/`, or wherever the project keeps visuals)
+2. Append to `brand/assets.md`:
+   ```
+   | <date> | image | <file-path> | image-gen | <1-line description of what was generated> |
+   ```
+
+---
+
+## Phase 4: Iterate
+
+After generating, show the image and offer:
+
+"Image generated. Want me to:"
+1. Adjust the lighting or mood
+2. Change the composition or framing
+3. Try a completely different approach
+4. Generate more variations
+5. Ship it
+
+For adjustments, use Gemini's multi-turn chat API for iterative refinement — pass the previous image + adjustment prompt.
+
+```python
+chat = client.chats.create(model="gemini-3-pro-image-preview")
+response = chat.send_message("Make the lighting warmer and add more negative space on the left for text")
+```
+
+---
+
+## Image Editing
+
+When the user provides an existing image to modify:
+
+```python
+from PIL import Image
+
+img = Image.open("input.png")
+response = client.models.generate_content(
+    model="gemini-3-pro-image-preview",
+    contents=["<edit instruction>", img],
+    config=types.GenerateContentConfig(
+        response_modalities=['TEXT', 'IMAGE'],
+    ),
+)
+```
+
+Supports: style transfer, background replacement, object removal, color grading, text overlay.
+
+---
+
+## Claims Blacklist Awareness
+
+If `brand/landscape.md` exists, check the Claims Blacklist before generating:
+- Don't generate imagery that visually implies "the only X" if that claim is blacklisted
+- Don't generate competitor comparisons that misrepresent the competitive landscape
+- When in doubt, describe the concept to the user and ask if it implies a blacklisted claim
+
+---
+
+## Anti-Patterns
+
+| Anti-pattern | Why it fails | Instead |
+|-------------|-------------|---------|
+| Listing comma-separated keywords | "professional, modern, tech, blue, minimal" produces generic AI art | Write a narrative: "A single glowing terminal on a dark slate desk, soft amber rim lighting catching the screen edges" |
+| Ignoring aspect ratio | Generating 1:1 for a blog header means the user has to crop, losing composition | Always ask where the image goes FIRST — ratio determines everything |
+| Overriding brand style silently | User defined a visual brand identity for consistency — ignoring it defeats the purpose | Default to brand style. Only override when user explicitly asks for something different |
+| Generating without purpose | "A nice image" produces nothing distinctive | Every image needs a purpose (blog header, social, hero) and a feeling (trust, excitement, calm) |
+| Saving as JPEG when PNG needed | Gemini returns JPEG by default — transparency and quality loss | Always convert to PNG with `image.save("output.png", format="PNG")` |
+| Skipping the assets log | Future agents won't know what images exist, leading to duplicate generation | Always append to brand/assets.md after generating |
+
+---
+
+## Related Skills
+
+- **/visual-style** — builds the Visual Brand Style section this skill reads
+- **/creative** — produces multi-mode creative briefs (not pixels). Route here for ad concepts and video scripts
+- **/paper-marketing** — designs in Paper MCP. Route here for carousels, slideshows, and social graphics designed as HTML
+- **/app-store-screenshots** — specialized screenshot generator for App Store listings

package/skills/image-gen/references/prompt-patterns.md

@@ -0,0 +1,114 @@
+# Proven Prompt Patterns
+
+> Reference for /image-gen. Load when crafting prompts to select the right structural pattern for the use case.
+
+## Pattern 1: Photorealistic Scene
+
+For product shots, lifestyle imagery, and realistic environments.
+
+```
+A photorealistic [shot type] of [subject], [action/expression], set in [environment].
+Illuminated by [lighting], creating a [mood] atmosphere. Captured with a [camera/lens],
+emphasizing [textures/details]. [Aspect ratio].
+```
+
+**When to use:** Product marketing, hero images, lifestyle content.
+**Key lever:** Camera/lens specificity. "85mm at f/2.0" vs "a camera" is the difference between a portrait and a snapshot.
+
+## Pattern 2: Stylized Illustration
+
+For brand graphics, icons, and non-photographic assets.
+
+```
+A [style] illustration of [subject], featuring [characteristics] in a [color palette].
+The design has [line style] and [shading]. [Background specification].
+```
+
+**When to use:** Blog headers, social graphics, brand assets.
+**Key lever:** Naming the art style explicitly (isometric, flat, hand-drawn, watercolor).
+
+## Pattern 3: Text in Image
+
+For quote cards, announcement graphics, and branded text visuals.
+
+```
+Create a [image type] with the text "[exact text]" in a [font style].
+The design is [style], with [color scheme]. Text positioned [placement].
+```
+
+**When to use:** Social announcements, quote cards, feature callouts.
+**Key lever:** Nano Banana Pro excels at text rendering. Be explicit about font style, size, and placement.
+
+## Pattern 4: Product/Commercial
+
+For e-commerce, app screenshots, and polished commercial imagery.
+
+```
+A studio-lit product shot of [product] on [surface]. [Lighting setup] to highlight [feature].
+Camera angle [angle] to showcase [detail]. Sharp focus on [element]. [Aspect ratio].
+```
+
+**When to use:** Landing pages, App Store assets, ad creative.
+**Key lever:** Material descriptions. "Frosted glass with fine matte texture" vs "glass."
+
+## Pattern 5: Minimalist/Negative Space
+
+For blog headers, hero sections, and images that need text overlay space.
+
+```
+A minimalist composition featuring [subject] positioned in the [area] of the frame.
+Background is [color/texture], creating generous negative space for [purpose].
+Soft lighting. [Aspect ratio].
+```
+
+**When to use:** Blog headers (leave room for title), hero sections, presentation slides.
+**Key lever:** Explicitly say WHERE the negative space should be and WHY.
+
+## Pattern 6: Abstract/Conceptual
+
+For thought leadership, brand mood, and emotional visuals.
+
+```
+[Visual metaphor description] representing [concept]. The mood is [feeling].
+Colors are [palette]. The composition [arrangement]. Lighting creates [effect]. [Aspect ratio].
+```
+
+**When to use:** Abstract concepts (innovation, growth, transformation), mood pieces.
+**Key lever:** The visual metaphor. See visual-metaphors.md for the mapping table.
+
+## Pattern 7: Hyper-Detailed Portrait
+
+For personal brands, team photos, and character-driven visuals.
+
+```
+age: [range]
+vibe: "[a specific scenario that captures the person's energy]"
+pose: [exact body position]
+expression: [micro-expression details]
+clothing: [specific items with textures]
+```
+
+**When to use:** Founder photos, team pages, personal brand imagery.
+**Key lever:** The "vibe" line. "Cape Town art dealer at 4 AM after closing a million-dollar sale" gives the model more to work with than "confident professional."
+
+## Pattern 8: Era-Specific
+
+For nostalgia, retro aesthetics, and deliberate imperfection.
+
+```
+A low-resolution [era] photo taken on a [specific camera/device].
+[Era-specific artifacts: flash, grain, color cast, date stamp].
+[Subject and scene]. [Specific imperfections that sell the era].
+```
+
+**When to use:** Throwback content, retro brand aesthetics, authenticity.
+**Key lever:** Name the EXACT camera and year. The artifacts follow from that specificity.
+
+## Craft Tips
+
+- **Describe, don't list.** Flowing narrative > comma-separated keywords.
+- **Be tactile.** Name textures: "paper-like", "matte", "wet sheen", "weathered."
+- **Degrees matter.** "Chin tilted 3 degrees upward" > "chin up."
+- **Light as character.** "Split lighting: half Caravaggio warmth, half cold morning truth."
+- **Vibe > adjectives.** Bad: "confident woman." Good: "art dealer at 4 AM, still high on adrenaline and red wine."
+- **Imperfections sell realism.** "Faint stain," "one lock falling across cheekbone," "date stamp in corner."

package/skills/image-gen/references/visual-metaphors.md

@@ -0,0 +1,51 @@
+# Visual Metaphors Library
+
+> Reference for /image-gen. When the user needs an image for a concept, this table maps abstract ideas to concrete visual representations.
+
+## Concept-to-Metaphor Mapping
+
+| Concept | Visual Metaphors |
+|---------|-----------------|
+| Learning | Knowledge assembling, paths lighting up, fog clearing, lightbulb filament glowing |
+| Speed | Light trails, motion blur, things in flight, wind-swept elements |
+| AI / Agents | Warm glowing orbs, friendly terminals, elegant interfaces, constellation patterns |
+| Simplicity | Chaos dissolving into clean lines, knots untying, clutter compressing into a gem |
+| Power | Light breaking through, energy radiating, standing on a summit |
+| Creation | Things crystallizing, assembling from particles, emerging from raw material |
+| Connection | Threads linking, bridges forming, signals flowing between nodes |
+| Security | Shields with warm glow, locks with precision, protective barriers |
+| Launch | Rockets, doors opening wide, sunrise over horizon, first light |
+| Tools | Glowing terminals, elegant dashboards, precision instruments on a clean desk |
+| Growth | Plants breaking through concrete, charts ascending, seeds splitting open |
+| Transformation | Cocoon to butterfly, raw ore to polished metal, chaos becoming order |
+| Focus | Spotlight in darkness, magnifying glass, single subject against empty backdrop |
+| Community | Circles overlapping, hands building together, campfire gathering |
+| Trust | Handshake, open door, clear glass, visible foundations |
+| Innovation | Light in unexpected places, bridges to nowhere becoming bridges to somewhere |
+| Scale | Ant and skyscraper, droplet and ocean, seed and forest |
+| Quality | Diamond facets, Swiss watch internals, master craftsman's tools |
+| Time | Hourglass, clock hands, sunrise-to-sunset transition, seasons in one frame |
+| Data | Flowing rivers of light, star maps, organized crystal structures |
+
+## Usage Notes
+
+- **Pick ONE metaphor per image.** Multiple metaphors in one composition creates visual noise.
+- **The metaphor should be recognizable but not cliched.** "Lightbulb for idea" is tired. "Fog clearing to reveal a path" is the same concept, freshly rendered.
+- **Adapt to brand style.** A "warm tech minimalism" brand renders "creation" as particles assembling in warm light. A "bold and energetic" brand renders it as an explosion of color solidifying into form.
+- **When the concept isn't in the table,** ask: "What does this concept LOOK like if you freeze it mid-action?" The answer is usually the metaphor.
+
+## Anti-Metaphors (Kill on Sight)
+
+These metaphors appear in every AI-generated marketing image. Avoid them:
+
+- Floating 3D cubes or blocks (for any concept)
+- Blue/purple grid backgrounds (for "tech")
+- Human silhouette with glowing brain (for "AI")
+- Gears meshing (for "integration" or "process")
+- Puzzle pieces connecting (for "teamwork" or "solutions")
+- Rocket ship (for "launch" — unless the product literally launches rockets)
+- Handshake (for "partnership" — unless the visual is genuinely distinctive)
+- Light at the end of a tunnel (for "solutions")
+- Iceberg (for "hidden complexity")
+
+If you catch yourself reaching for one of these, stop and find a fresh metaphor from the table above.

package/skills/impeccable/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: impeccable
+description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
+version: 4.0.4
+user-invocable: true
+argument-hint: "[shape · audit|critique · animate|bolder|colorize|delight|layout|overdrive|quieter|typeset · adapt|clarify|distill · harden|onboard|optimize|polish · init|document|extract|live] [target]"
+license: Apache 2.0
+allowed-tools:
+  - Bash(npx impeccable *)
+  - Bash(node .claude/skills/impeccable/scripts/*)
+---
+
+This skill gives you the tools and permission to create design that earns to be called out-of-distribution craft: Whereas before, your design work would have been safe, timid and measured, you now approach every design task as a award-winning design director with impeccable understanding for what makes exceptional design work: production-grade code, peak creativity, a clear POV, deep understanding of the needs of the client and users, and exceptional craft.
+
+Core principles:
+- Go all out. No hedging, no shortcuts. The deliverable must be complete (except assets the user must provide).
+- Dream big and bold. Distinct, beautiful, outstanding and highly inspiring work.
+- Verify in bounded passes, not a loop, and the ceiling covers the whole cycle: screenshots, defect scans, micro-edits, and rebuilds alike. Build fully, inspect once with a batched round (desktop and mobile together), fix everything it shows in one batch, confirm with at most one more round, and stop polishing. Open-ended self-QA burns the user's money doing worse what the finish handoffs do better.
+
+## Setup
+
+1. Run `node .claude/skills/impeccable/scripts/context.mjs` once per session (if the runtime shows this skill's loaded base directory, run `node <skill-base-dir>/scripts/context.mjs`; keep cwd at the user's project). Pass a named source file or route as `--target <path>`. It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance when applicable; follow its directives and do not rerun it.
+2. Before acting, load the one playbook that owns the request: the Commands table's reference for an explicit or clearly implied sub-command, or [reference/new-work.md](reference/new-work.md) for a new surface or replacement visual world. Then inspect the target and at least one representative source of incumbent visual truth (tokens, theme, CSS, component, or asset) before editing.
+3. After analysis and direction are resolved, load [reference/craft-floor.md](reference/craft-floor.md) immediately before editing UI. It carries the quality floor, the absolute bans, and the reflexes no detector catches. Do not load it for planning-only work.
+
+## How to design
+
+- **The brief wins.** Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning. Redirecting a clear brief toward your taste is failure.
+- **Refinement preserves; redesign replaces.** Refinement keeps the incumbent identity, behavior, copy, and everything outside scope. Ask before replacing factual copy or adding claims. Redesign keeps product truth, content, function, native affordances, and constraints, but treats the old look as evidence and anti-reference; choose a replacement world in new-work and replace DESIGN.md. Never split the difference into polish on the discarded look.
+- **Visual authority is evidence, not a filename.** Missing DESIGN.md alone does not make a project greenfield; new-work decides whether to preserve, expand, or replace the incumbent world.
+
+## Modes
+
+The mode names what the visitor's success looks like on this surface.
+
+- **Persuade:** the visitor decides and acts; design is the product. Landing pages, marketing, campaigns, pricing. Earn attention and action. Ship real imagery when the brief needs it; follow the committed world, not category habit.
+- **Operate:** the visitor completes a task. App UI, dashboards, editors, admin, settings, tools. Scanability, consistency, native expectations, and the real usage scene outrank expression. Brand lives in precise details.
+- **Read:** the visitor understands something. Docs, articles, guides, help, changelogs. Structure for comprehension, then make the reading experience worth staying in.
+- **Experience:** the visitor is inside the work itself. Portfolios, galleries, showcases. Let the artifact lead from the first viewport; the interface recedes.
+
+Choose the mode from the requested surface, not the product, and persist it only in that surface brief. A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade. See [new-work.md](reference/new-work.md) for new surfaces and [operate.md](reference/operate.md) for deeper Operate/Read guidance.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `craft [feature]` | Build | Deprecated alias for an ordinary new-work request | [reference/craft.md](reference/craft.md) |
+| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
+| `init` | Build | Capture durable product context in PRODUCT.md | [reference/init.md](reference/init.md) |
+| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
+| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
+| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
+| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) · native: [reference/audit.native.md](reference/audit.native.md) |
+| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
+| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
+| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
+| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
+| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
+| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
+| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
+| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
+| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
+| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
+| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
+| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
+| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
+| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) · native: [reference/adapt.native.md](reference/adapt.native.md) |
+| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
+| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
+
+Routing:
+
+- **No argument:** read [routing.md](reference/routing.md) and present its context-aware menu; never auto-run a command.
+- **Explicit or clearly implied command:** load its reference (native variant on native platforms) and follow it. Ask once if two commands fit.
+- **Otherwise:** treat the request as general design work. Missing PRODUCT.md routes a new surface or replacement world through init, then new-work; a narrow refinement of existing code proceeds on the incumbent implementation as context.mjs directs, offering init afterward rather than blocking on it.
+- `teach` aliases `init`. `craft` is a deprecated alias for ordinary new-work and adds nothing. `shape` owns task discovery, then enters new-work only for visual-world and surface-concept decisions.
+
+After init writes PRODUCT.md, resume without rerunning `context.mjs`; init loads the native platform reference itself when the platform it recorded is `ios`, `android`, or `adaptive`.
+
+**Pin / Unpin:** `node .claude/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>` creates or removes a standalone `/<command>` shortcut. Report the script's result concisely; relay stderr verbatim on error.
+
+**Hooks:** `/impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>` manages the design detector hook for this project (auto-runs the detector after UI file edits and surfaces findings). Load [reference/hooks.md](reference/hooks.md) when the user invokes it with any argument.
+
+**Doctor:** `/impeccable doctor` reports and repairs drift between this project's Impeccable artifacts (PRODUCT.md, DESIGN.md and its sidecar, config, surface briefs, the hook) and what this version reads. Load [reference/doctor.md](reference/doctor.md) when the user invokes it, or when they ask what is out of date, stale, or needs refreshing. A `CONTEXT_STALE` directive in Setup's output is the cheap subset of the same report; act on it there per its own instructions rather than running doctor unasked.
+
+**Never repair drift as a side effect of a design task.** A `CONTEXT_STALE` finding is reported, not acted on, unless the user asks. The one exception is a finding marked `auto`, which the next write to that file performs anyway.