@bastani/atomic 0.6.5 → 0.6.6-1

package/.agents/skills/impeccable/reference/shape.md

@@ -0,0 +1,151 @@
+Shape the UX and UI for a feature before any code is written. This command produces a **design brief**: a structured artifact that guides implementation through discovery, not guesswork.
+
+**Scope**: Design planning only. This command does NOT write code. It produces the thinking that makes code good.
+
+**Output**: A design brief that can be handed off to $impeccable craft, or directly to $impeccable for freeform implementation. When visual direction probes are used, the images are supporting artifacts, not the primary output.
+
+## Philosophy
+
+Most AI-generated UIs fail not because of bad code, but because of skipped thinking. They jump to "here's a card grid" without asking "what is the user trying to accomplish?" This command inverts that: understand deeply first, so implementation is precise.
+
+## Phase 1: Discovery Interview
+
+**Do NOT write any code or make any design decisions during this phase.** Your only job is to understand the feature deeply enough to make excellent design decisions later.
+
+This is a required interaction, not optional guidance. Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.
+
+### Interview cadence
+
+Discovery must include at least one user-answer round unless PRODUCT.md, DESIGN.md, or an already-confirmed brief directly answers the needed design inputs. With a sparse prompt, do **not** synthesize a complete brief for confirmation on the first response.
+
+- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
+- Ask **2-3 questions per round**, then wait for answers.
+- Treat PRODUCT.md and DESIGN.md as anchors; they reduce repeated questions but do **not** replace shape for craft. Shape is task-specific.
+- Round 1 should clarify purpose, audience/context, and success or emotional outcome.
+- Round 2 should clarify content/data/states and scope/fidelity.
+- Round 3 should clarify visual direction, constraints, and anti-goals when still unresolved.
+
+### Purpose & Context
+- What is this feature for? What problem does it solve?
+- Who specifically will use it? (Not "users"; be specific: role, context, frequency)
+- What does success look like? How will you know this feature is working?
+- What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?)
+
+### Content & Data
+- What content or data does this feature display or collect?
+- What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items)
+- What are the edge cases? (Empty state, error state, first-time use, power user)
+- Is any content dynamic? What changes and how often?
+
+### Design Direction
+
+Force a visual decision on three fronts. Skip anything PRODUCT.md or DESIGN.md already answers; ask only what's missing.
+
+- **Color strategy for this surface.** Pick one: Restrained / Committed / Full palette / Drenched. Can override the project default if the surface earns it (e.g. a drenched hero inside an otherwise Restrained product).
+- **Theme via scene sentence.** Write one sentence of physical context for this surface — who uses it, where, under what ambient light, in what mood. The sentence forces dark vs light. If it doesn't, add detail until it does.
+- **Two or three named anchor references.** Specific products, brands, objects — not adjectives like "modern" or "clean."
+
+### Scope
+
+Always ask. Sketch quality and shipped quality are different outputs; don't guess between them.
+
+- **Fidelity.** Sketch / mid-fi / high-fi / production-ready?
+- **Breadth.** One screen / a flow / a whole surface?
+- **Interactivity.** Static visual / interactive prototype / shipped-quality component?
+- **Time intent.** Quick exploration, or polish until it ships?
+
+Scope answers are task-scoped. Don't write them to PRODUCT.md or DESIGN.md — carry them through the design brief only.
+
+### Constraints
+- Are there technical constraints? (Framework, performance budget, browser support)
+- Are there content constraints? (Localization, dynamic text length, user-generated content)
+- Mobile/responsive requirements?
+- Accessibility requirements beyond WCAG AA?
+
+### Anti-Goals
+- What should this NOT be? What would be a wrong direction?
+- What's the biggest risk of getting this wrong?
+
+## Phase 1.5: Visual Direction Probe (Capability-Gated)
+
+After the discovery interview, generate a small set of visual direction probes **before** writing the final brief when all of these are true:
+
+- The work is **net-new** or directionally ambiguous enough that visual exploration will clarify the brief.
+- The requested fidelity is **mid-fi, high-fi, or production-ready**. Skip for sketch-only planning.
+- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
+
+When those conditions are met, this step is mandatory for Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed.
+
+Use probes to explore visual lanes, not to replace the brief.
+
+Do not skip probes because the final UI will be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
+
+### What to generate
+
+Generate **2 to 4** distinct direction probes based on the discovery answers, especially:
+
+- Color strategy
+- Theme scene sentence
+- Named anchor references
+- Scope and fidelity
+
+The probes should differ in primary visual direction (hierarchy, topology, density, typographic voice, or color strategy), not just palette tweaks.
+
+### How to use the probes
+
+- Treat them as **direction tests**, not final designs.
+- Use them to pressure-test whether the brief is pointing at the right lane.
+- Ask the user which direction feels closest, what feels off, and what should carry forward.
+- If the probes reveal a mismatch, revise the brief inputs before finalizing the brief.
+
+### Important limits
+
+- Do **not** skip discovery because image generation is available.
+- Do **not** treat generated imagery as final UX specification, final copy, or final accessibility behavior.
+- Do **not** use this step for minor refinements of existing work. It's for shaping a new surface or clarifying a big directional choice.
+
+If image generation is unavailable, or the task doesn't benefit from it, skip this phase only with a one-line reason and proceed directly to the design brief.
+
+## Phase 2: Design Brief
+
+After the interview and any required probes, synthesize everything into a structured design brief. Present it to the user for explicit confirmation before considering this command complete. Stop after asking for confirmation; do not proceed to craft or implementation in the same response unless the user has already approved the brief.
+
+### Brief Structure
+
+**1. Feature Summary** (2-3 sentences)
+What this is, who it's for, what it needs to accomplish.
+
+**2. Primary User Action**
+The single most important thing a user should do or understand here.
+
+**3. Design Direction**
+Color strategy (Restrained / Committed / Full palette / Drenched) + the theme scene sentence + 2–3 named anchor references. Reference PRODUCT.md and DESIGN.md where they already answer, and note any per-surface overrides.
+
+If you ran the Visual Direction Probe step, name which probe direction won and what changed in the brief because of it.
+
+**4. Scope**
+Fidelity, breadth, interactivity, and time intent from the Scope section of the interview. Task-scoped — these don't persist beyond the brief.
+
+**5. Layout Strategy**
+High-level spatial approach: what gets emphasis, what's secondary, how information flows. Describe the visual hierarchy and rhythm, not specific CSS.
+
+**6. Key States**
+List every state the feature needs: default, empty, loading, error, success, edge cases. For each, note what the user needs to see and feel.
+
+**7. Interaction Model**
+How users interact with this feature. What happens on click, hover, scroll? What feedback do they get? What's the flow from entry to completion?
+
+**8. Content Requirements**
+What copy, labels, empty state messages, error messages, and microcopy are needed. Note any dynamic content and its realistic ranges.
+
+**9. Recommended References**
+Based on the brief, list which impeccable reference files would be most valuable during implementation (e.g., spatial-design.md for complex layouts, motion-design.md for animated features, interaction-design.md for form-heavy features).
+
+**10. Open Questions**
+Anything unresolved that the implementer should resolve during build.
+
+---
+
+STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask for explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. A shape run is incomplete until the brief is confirmed.
+
+Once confirmed, the brief is complete. The user can now hand it to $impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use $impeccable craft instead, which runs this command internally.)

package/.agents/skills/impeccable/reference/teach.md

@@ -0,0 +1,156 @@
+# Teach Flow
+
+Gathers design context for a project and writes two complementary files at the project root:
+
+- **PRODUCT.md** (strategic): register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
+- **DESIGN.md** (visual): visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
+
+Every other impeccable command reads these files before doing any work.
+
+## Step 1: Load current state
+
+Run the shared loader first so you know what already exists:
+
+```bash
+node .agents/skills/impeccable/scripts/load-context.mjs
+```
+
+The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
+
+Decision tree:
+- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
+- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 — offer to run `$impeccable document` for DESIGN.md.
+- **PRODUCT.md exists but has no `## Register` section (legacy)**: add it. Infer a hypothesis from the codebase (see Step 2), confirm with the user, write the field.
+- **Both exist**: STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask which file to refresh. Skip the one the user doesn't want changed.
+- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
+
+Never silently overwrite an existing file. Always confirm first.
+
+If teach was invoked as a setup blocker by another command, such as `$impeccable craft landing page`, pause that command here. Complete teach, re-run the loader, then resume the original command with the freshly loaded context. For craft, resume into shape next; teach creates project context, but it is not a substitute for the task-specific shape interview and confirmed design brief.
+
+## Step 2: Explore the codebase
+
+Before asking questions, thoroughly scan the project to discover what you can:
+
+- **README and docs**: Project purpose, target audience, any stated goals
+- **Package.json / config files**: Tech stack, dependencies, existing design libraries
+- **Existing components**: Current design patterns, spacing, typography in use
+- **Brand assets**: Logos, favicons, color values already defined
+- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
+- **Any style guides or brand documentation**
+
+Also form a **register hypothesis** from what you find:
+
+- Brand signals: `/`, `/about`, `/pricing`, `/blog/*`, `/docs/*`, hero sections, big typography, scroll-driven sections, landing-page-shaped content.
+- Product signals: `/app/*`, `/dashboard`, `/settings`, `/(auth)`, forms, data tables, side/top nav, app-shell components.
+
+Register is a hypothesis at this point, not a decision — Step 3 confirms it.
+
+Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
+
+## Step 3: Ask strategic questions (for PRODUCT.md)
+
+STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask only about what you couldn't infer from the codebase.
+
+### Interview mode, not confirmation mode
+
+If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
+
+- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
+- Ask **2-3 questions per round**, then wait for answers.
+- Use inferred answers as hypotheses or options, not as finished facts.
+- Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
+- Round 1 should establish register, users/purpose, and desired outcome.
+- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
+
+### Minimum viable interview
+
+Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, users and purpose, brand personality, anti-references, and accessibility needs unless each answer is directly discoverable from repo context. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
+
+### Register (ask first — it shapes everything below)
+
+Every design task is either **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboards, tools — design SERVES the product).
+
+If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface — does that match your intent, or should we treat it differently?"*
+
+If the signal is genuinely split (e.g. a product with a big marketing landing), STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
+
+### Users & Purpose
+- Who uses this? What's their context when using it?
+- What job are they trying to get done?
+- For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency)
+- For product: what workflow are they in? What's the primary task on any given screen?
+
+### Brand & Personality
+- How would you describe the brand personality in 3 words?
+- Reference sites or apps that capture the right feel? What specifically about them?
+  - For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.) — not generic "modern" adjectives.
+  - For product, push for category best-tool references (Linear, Figma, Notion, Raycast, Stripe).
+- What should this explicitly NOT look like? Any anti-references?
+
+### Accessibility & Inclusion
+- Specific accessibility requirements? (WCAG level, known user needs)
+- Considerations for reduced motion, color blindness, or other accommodations?
+
+Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here** — those belong in DESIGN.md, not PRODUCT.md.
+
+## Step 4: Write PRODUCT.md
+
+Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
+
+Synthesize into a strategic document:
+
+```markdown
+# Product
+
+## Register
+
+product
+
+## Users
+[Who they are, their context, the job to be done]
+
+## Product Purpose
+[What this product does, why it exists, what success looks like]
+
+## Brand Personality
+[Voice, tone, 3-word personality, emotional goals]
+
+## Anti-references
+[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
+
+## Design Principles
+[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "show, don't tell", "expert confidence" — NOT visual rules like "use OKLCH" or "magenta accent".]
+
+## Accessibility & Inclusion
+[WCAG level, known user needs, considerations]
+```
+
+Register is either `brand` or `product` as a bare value. No prose, no commentary.
+
+Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it — merge into that content rather than starting from scratch.
+
+## Step 5: Decide on DESIGN.md
+
+Offer `$impeccable document` either way. Two paths:
+
+- **Code exists** (CSS tokens, components, a running site): "I can generate a DESIGN.md that captures your visual system (colors, typography, components) so variants stay on-brand. Want to do that now?"
+- **Pre-implementation** (empty project): "I can seed a starter DESIGN.md from five quick questions about color strategy, type direction, motion energy, and references. You can re-run once there's code, to capture the real tokens. Want to do that now?"
+
+If the user agrees, delegate to `$impeccable document` (it auto-detects scan vs seed). Load its reference and follow that flow.
+
+If the user prefers to skip, mention they can run `$impeccable document` any time later.
+
+## Step 6: Confirm and wrap up
+
+Summarize:
+- Register captured (brand / product)
+- What was written (PRODUCT.md, DESIGN.md, or both)
+- The 3-5 strategic principles from PRODUCT.md that will guide future work
+- If DESIGN.md is pending, remind the user how to generate it later
+
+**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node .agents/skills/impeccable/scripts/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version.
+
+If teach was invoked as a blocker by another impeccable command (e.g. the user ran `$impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context.
+
+Optionally STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.

package/.agents/skills/{typeset/SKILL.md → impeccable/reference/typeset.md}

@@ -1,16 +1,12 @@
----
-name: typeset
-description: Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography.
-version: 2.1.1
-user-invocable: true
-argument-hint: "[target]"
+Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+
 ---
 
-Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+## Register
 
-## MANDATORY PREPARATION
+Brand: run the font selection procedure in [brand.md](brand.md). Pairing follows the brand's lane (display serif + sans body for editorial/luxury, one committed sans for tech, etc.). Fluid `clamp()` scale, ≥1.25 ratio between steps.
 
-Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
+Product: system fonts and familiar sans stacks are legitimate here. One well-tuned family typically carries the whole UI. Fixed `rem` scale, 1.125–1.2 ratio between more closely-spaced steps.
 
 ---
 
@@ -47,7 +43,7 @@ Analyze what's weak or generic about the current type:
 
 ## Plan Typography Improvements
 
-Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies.
+Consult the [typography reference](typography.md) for detailed guidance on scales, pairing, and loading strategies.
 
 Create a systematic plan:
 
@@ -113,4 +109,16 @@ Build a clear type scale:
 - **Performance**: Are web fonts loading efficiently without layout shift?
 - **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
 
-Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.
+Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.
+
+## Live-mode signature params
+
+Each variant MUST declare a `scale` param controlling the hierarchy ratio. Express all font sizes in the variant's scoped CSS through `calc(var(--p-scale, 1) * <base>)` or, better, scale the type ramp via `clamp(min, calc(var(--p-scale, 1) * Npx), max)`. Users slide from subdued to commanding.
+
+```json
+{"id":"scale","kind":"range","min":0.85,"max":1.3,"step":0.05,"default":1,"label":"Scale"}
+```
+
+Where the variant riffs on a specific pairing, expose the pairing choice as a `steps` param (e.g. "serif display + sans body" vs. "mono display + sans body" vs. "all-sans"). Each branch routes through `:scope[data-p-pairing="X"]` selectors in scoped CSS.
+
+See `reference/live.md` for the full params contract.

package/.agents/skills/impeccable/reference/typography.md

@@ -26,28 +26,20 @@ Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth).
 
 Use `ch` units for character-based measure (`max-width: 65ch`). Line-height scales inversely with line length—narrow columns need tighter leading, wide columns need more.
 
-**Non-obvious**: Increase line-height for light text on dark backgrounds. The perceived weight is lighter, so text needs more breathing room. Add 0.05-0.1 to your normal line-height.
+**Non-obvious**: Light text on dark backgrounds needs compensation on three axes, not just one. Bump line-height by 0.05–0.1, add a touch of letter-spacing (0.01–0.02em), and optionally step the body weight up one notch (regular → medium). The perceived weight drops across all three; fix all three.
 
-## Font Selection & Pairing
-
-### Choosing Distinctive Fonts
+**Paragraph rhythm**: Pick either space between paragraphs OR first-line indentation. Never both. Digital usually wants space; editorial/long-form can justify indent-only.
 
-**Avoid the invisible defaults**: Inter, Roboto, Open Sans, Lato, Montserrat. These are everywhere, making your design feel generic. They're fine for documentation or tools where personality isn't the goal—but if you want distinctive design, look elsewhere.
-
-**Pick the font from the brief, not from a category preset.** The most common AI typography failure is reaching for the same "tasteful" font for every editorial brief, the same "modern" font for every tech brief, the same "elegant serif" for every premium brief. Those reflexes produce monoculture across projects. The right font is one whose physical character matches *this specific* brand, audience, and moment.
+## Font Selection & Pairing
 
-A working selection process:
+The tactical selection procedure and the reflex-reject list live in [reference/brand.md](brand.md) under **Font selection procedure** and **Reflex-reject list** (loaded for brand-register tasks). The rest of this section covers the adjacent knowledge: anti-reflex corrections, system font use, and pairing rules.
 
-1. Read the brief once. Write down three concrete words for the brand voice. Not "modern" or "elegant" — those are dead categories. Try "warm and mechanical and opinionated" or "calm and clinical and careful" or "fast and dense and unimpressed" or "handmade and a little weird."
-2. Now imagine the font as a physical object the brand could ship: a typewriter ribbon, a hand-lettered shop sign, a 1970s mainframe terminal manual, a fabric label on the inside of a coat, a museum exhibit caption, a tax form, a children's book printed on cheap newsprint. Whichever physical object fits the three words is pointing at the right *kind* of typeface.
-3. Browse a font catalog (Google Fonts, Pangram Pangram, Adobe Fonts, Future Fonts, ABC Dinamo) with that physical object in mind. **Reject the first thing that "looks designy."** That's your trained-everywhere reflex. Keep looking.
-4. Avoid your defaults from previous projects. If you find yourself reaching for the same display font you used last time, make yourself pick something else.
+### Anti-reflexes worth defending against
 
-**Anti-reflexes worth defending against**:
 - A technical/utilitarian brief does NOT need a serif "for warmth." Most tech tools should look like tech tools.
 - An editorial/premium brief does NOT need the same expressive serif everyone is using right now. Premium can be Swiss-modern, can be neo-grotesque, can be a literal monospace, can be a quiet humanist sans.
 - A children's product does NOT need a rounded display font. Kids' books use real type.
-- A "modern" brief does NOT need a geometric sans. The most modern thing you can do in 2026 is not use the font everyone else is using.
+- A "modern" brief does NOT need a geometric sans. The most modern thing you can do is not use the font everyone else is using.
 
 **System fonts are underrated**: `-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui` looks native, loads instantly, and is highly readable. Consider this for apps where performance > personality.
 
@@ -91,6 +83,12 @@ body {
 
 Tools like [Fontaine](https://github.com/unjs/fontaine) calculate these overrides automatically.
 
+**`swap` vs `optional`**: `swap` shows fallback text immediately and FOUT-swaps when the web font arrives. `optional` uses the fallback if the web font misses a small load budget (~100ms) and avoids the shift entirely. Pick `optional` when zero layout shift matters more than seeing the branded font on slow networks.
+
+**Preload the critical weight only**: typically the regular-weight body font used above the fold. Preloading every weight costs more bandwidth than it saves.
+
+**Variable fonts for 3+ weights or styles**: a single variable font file is usually smaller than three static weight files, gives fractional weight control, and pairs well with `font-optical-sizing: auto`. For 1–2 weights, static is fine.
+
 ## Modern Web Typography
 
 ### Fluid Type
@@ -101,6 +99,10 @@ Fluid typography via `clamp(min, preferred, max)` scales text smoothly with the
 
 **Use fixed `rem` scales for**: App UIs, dashboards, and data-dense interfaces. No major app design system (Material, Polaris, Primer, Carbon) uses fluid type in product UI — fixed scales with optional breakpoint adjustments give the spatial predictability that container-based layouts need. Body text should also be fixed even on marketing pages, since the size difference across viewports is too small to warrant it.
 
+**Bound your clamp()**: keep `max-size ≤ ~2.5 × min-size`. Wider ratios break the browser's zoom and reflow behaviour and make large viewports feel like the page is shouting.
+
+**Scale container width and font-size together** so effective character measure stays in the 45–75ch band at every viewport. A heading that widens faster than its container drifts out of the comfortable measure at the top end.
+
 ### OpenType Features
 
 Most developers don't know these exist. Use them for polish:
@@ -124,6 +126,21 @@ body { font-kerning: normal; }
 
 Check what features your font supports at [Wakamai Fondue](https://wakamaifondue.com/).
 
+### Rendering polish
+
+```css
+/* Even out heading line lengths (browser picks better break points) */
+h1, h2, h3 { text-wrap: balance; }
+
+/* Reduce orphans and ragged endings in long prose */
+article p { text-wrap: pretty; }
+
+/* Variable fonts: pick the right optical-size master automatically */
+body { font-optical-sizing: auto; }
+```
+
+**ALL-CAPS tracking**: capitals sit too close at default spacing. Add 5–12% letter-spacing (`letter-spacing: 0.05em` to `0.12em`) to short all-caps labels, eyebrows, and small headings. Real small caps (via `font-variant-caps`) need the same treatment, slightly gentler.
+
 ## Typography System Architecture
 
 Name tokens semantically (`--text-body`, `--text-heading`), not by value (`--font-size-16`). Include font stacks, size scale, weights, line-heights, and letter-spacing in your token system.

package/.agents/skills/impeccable/scripts/cleanup-deprecated.mjs

@@ -21,14 +21,34 @@
 import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, unlinkSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
-// Skills that were renamed, merged, or folded in v2.0 and v2.1.
+// Skills that were renamed, merged, or folded in v2.0, v2.1, and v3.0.
 const DEPRECATED_NAMES = [
-  'frontend-design',    // renamed to impeccable (v2.0)
-  'teach-impeccable',   // folded into /impeccable teach (v2.0)
-  'arrange',            // renamed to layout (v2.1)
-  'normalize',          // merged into polish (v2.1)
-  'onboard',            // merged into harden (v2.1)
-  'extract',            // merged into /impeccable extract (v2.1)
+  // v2.0 renames
+  'frontend-design',    // renamed to impeccable
+  'teach-impeccable',   // folded into /impeccable teach
+  // v2.1 merges
+  'arrange',            // renamed to layout
+  'normalize',          // merged into polish
+  'onboard',            // merged into harden
+  'extract',            // merged into /impeccable extract
+  // v3.0 consolidation: all standalone skills -> /impeccable sub-commands
+  'adapt',
+  'animate',
+  'audit',
+  'bolder',
+  'clarify',
+  'colorize',
+  'critique',
+  'delight',
+  'distill',
+  'harden',
+  'layout',
+  'optimize',
+  'overdrive',
+  'polish',
+  'quieter',
+  'shape',
+  'typeset',
 ];
 
 // All known harness directories that may contain a skills/ subfolder.
@@ -37,6 +57,17 @@ const HARNESS_DIRS = [
   '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
 ];
 
+// Per-skill fingerprints for SKILL.md bodies that never mentioned
+// "impeccable" in their v2.x source. Used as a last-resort match
+// when no skills-lock.json exists and the word heuristic fails.
+// The strings are lifted verbatim from the v2.x frontmatter
+// descriptions, so collisions with hand-written user skills are
+// vanishingly unlikely.
+const SKILL_FINGERPRINTS = {
+  harden: 'Make interfaces production-ready: error handling, empty states',
+  optimize: 'Diagnoses and fixes UI performance across loading speed',
+};
+
 /**
  * Walk up from startDir until we find a directory that looks like a
  * project root (has package.json, .git, or skills-lock.json).
@@ -60,19 +91,48 @@ export function findProjectRoot(startDir = process.cwd()) {
 }
 
 /**
- * Check whether a skill directory belongs to Impeccable by reading its
- * SKILL.md and looking for the word "impeccable" (case-insensitive).
- * Returns false for non-existent paths or skills that don't match.
+ * Load skills-lock.json from the project root, or null if missing/unreadable.
  */
-export function isImpeccableSkill(skillDir) {
+export function loadLock(projectRoot) {
+  const lockPath = join(projectRoot, 'skills-lock.json');
+  if (!existsSync(lockPath)) return null;
+  try {
+    return JSON.parse(readFileSync(lockPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check whether a skill directory belongs to Impeccable. Three layered
+ * signals, in order of reliability:
+ *   1. Lock source equals "pbakaus/impeccable" (authoritative).
+ *   2. SKILL.md body contains the word "impeccable".
+ *   3. SKILL.md body contains a per-skill fingerprint (for harden and
+ *      optimize, whose v2.x SKILL.md never mentioned the pack name).
+ */
+export function isImpeccableSkill(skillDir, { skillName, lock } = {}) {
+  // 1. Authoritative: the lock file claims this skill is ours.
+  if (skillName && lock?.skills?.[skillName]?.source === 'pbakaus/impeccable') {
+    return true;
+  }
   const skillMd = join(skillDir, 'SKILL.md');
   if (!existsSync(skillMd)) return false;
+  let content;
   try {
-    const content = readFileSync(skillMd, 'utf-8');
-    return /impeccable/i.test(content);
+    content = readFileSync(skillMd, 'utf-8');
   } catch {
     return false;
   }
+  // 2. Word-level content heuristic.
+  if (/impeccable/i.test(content)) return true;
+  // 3. Per-skill fingerprint for old skills that never mentioned the pack.
+  //    Strip the i- prefix so both `harden` and `i-harden` resolve to the
+  //    same fingerprint entry.
+  const unprefixed = skillName?.startsWith('i-') ? skillName.slice(2) : skillName;
+  const fingerprint = unprefixed && SKILL_FINGERPRINTS[unprefixed];
+  if (fingerprint && content.includes(fingerprint)) return true;
+  return false;
 }
 
 /**
@@ -105,9 +165,12 @@ export function findSkillsDirs(projectRoot) {
 
 /**
  * Remove deprecated skill directories/symlinks from all harness dirs.
+ * Reads skills-lock.json so the authoritative "source" field can
+ * drive deletion even when SKILL.md never mentions impeccable.
  * Returns an array of paths that were deleted.
  */
-export function removeDeprecatedSkills(projectRoot) {
+export function removeDeprecatedSkills(projectRoot, lock) {
+  if (lock === undefined) lock = loadLock(projectRoot);
   const targets = buildTargetNames();
   const skillsDirs = findSkillsDirs(projectRoot);
   const deleted = [];
@@ -129,7 +192,9 @@ export function removeDeprecatedSkills(projectRoot) {
         // Symlink: check the target if it's alive, otherwise treat
         // dangling symlinks to deprecated names as safe to remove.
         const targetAlive = existsSync(skillPath);
-        const isMatch = targetAlive ? isImpeccableSkill(skillPath) : true;
+        const isMatch = targetAlive
+          ? isImpeccableSkill(skillPath, { skillName: name, lock })
+          : true;
         if (isMatch) {
           unlinkSync(skillPath);
           deleted.push(skillPath);
@@ -138,7 +203,7 @@ export function removeDeprecatedSkills(projectRoot) {
       }
 
       // Regular directory -- verify it belongs to impeccable
-      if (isImpeccableSkill(skillPath)) {
+      if (isImpeccableSkill(skillPath, { skillName: name, lock })) {
         rmSync(skillPath, { recursive: true, force: true });
         deleted.push(skillPath);
       }
@@ -188,10 +253,15 @@ export function cleanSkillsLock(projectRoot) {
 
 /**
  * Run the full cleanup. Returns a summary object.
+ *
+ * Order matters: read the lock and delete directories first, then
+ * strip lock entries. Otherwise the authoritative signal is gone by
+ * the time directory deletion runs.
  */
 export function cleanup(projectRoot) {
   const root = projectRoot || findProjectRoot();
-  const deletedPaths = removeDeprecatedSkills(root);
+  const lock = loadLock(root);
+  const deletedPaths = removeDeprecatedSkills(root, lock);
   const removedLockEntries = cleanSkillsLock(root);
   return { deletedPaths, removedLockEntries, projectRoot: root };
 }