` outer element with the marker comments tucked inside. Drop the variants block above into the "Variants: insert below this line" comment and the source stays valid TSX.
+
+### 7. Parameters (composition-sized, 0–4 per variant)
+
+Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
+
+**What “optional” does not mean.** Parameters are not nice-to-have decoration on large work. The word meant “omit controls that are redundant or cosmetic,” not “default to zero because three variants were enough work.”
+
+**When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
+
+**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
+
+**Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
+
+- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
+- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
+- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
+- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
+
+**When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
+
+**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
+
+**How to declare.** Put a JSON manifest on the variant wrapper:
+
+```html
+
+ ...variant content...
+
+```
+
+**Three kinds:**
+
+- `range`: smooth slider. Drives a CSS custom property `--p-
` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
+- `steps`: segmented radio. Drives a data attribute `data-p-` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
+- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
+
+**Signature params per action.** For named sub-commands, read that action’s `reference/.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
+
+**Reset on variant switch.** User dials density on v1, flips to v2, v2 starts at v2's declared defaults. Known limitation; preservation across variants may land later.
+
+**On accept**, the browser sends the user's current values in the accept event. `live-accept.mjs` writes them as a sibling comment:
+
+```html
+
+```
+
+The carbonize cleanup step (see below) reads that comment and bakes the chosen values into the final CSS. For `steps`/`toggle` attribute selectors: keep only the branch matching the chosen value, drop the others, collapse `:scope[data-p-density="packed"] .grid` to a semantic class rule. For `range` vars: either substitute the literal or keep the var with the chosen value as its new default.
+
+### 8. Signal done
+
+```bash
+node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
+```
+
+`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
+
+Then run `live-poll.mjs` again immediately.
+
+### Aborting an in-flight session
+
+If wrap or generation fails after the browser has flipped to GENERATING (e.g. wrap landed on the wrong source branch and you've already reverted it, or generation hit an unrecoverable error), tell the **browser** so its bar resets to PICKING:
+
+```bash
+node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
+```
+
+Don't run `live-accept --discard` for this; that's a pure file mutator, the browser doesn't see it, and the bar gets stuck on the GENERATING dots forever (the user has to refresh). `--discard` is only correct when the **browser** initiated the discard (user clicked ✕ during CYCLING) and the agent is just running source-side cleanup the browser already triggered.
+
+## Handle fallback
+
+When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
+
+The goal is the same: give the user three variants to choose from AND persist the accepted one in a place the next build won't wipe. The difference is that you have to pick the right source file yourself.
+
+### Step 1: Identify where the element actually lives
+
+Use the error payload:
+
+- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
+- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
+- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
+
+Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
+
+### Step 2: Show three variants in the DOM for preview
+
+The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
+
+1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `…
`.
+2. Insert your three variant divs inside it, same shape as the deterministic path.
+3. Signal done with `--reply EVENT_ID done --file `. The browser's no-HMR fallback will fetch and inject.
+
+This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
+
+### Step 3: On accept, write to true source
+
+When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
+
+- Structural change → edit the template / component source.
+- Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `' : ''));
+ if (paramValues && Object.keys(paramValues).length > 0) {
+ // Preserve the user's knob positions for the carbonize-cleanup agent
+ // to bake into the final CSS when it collapses scoped rules.
+ replacement.push(indent + commentSyntax.open + ' impeccable-param-values ' + id + ': ' + JSON.stringify(paramValues) + ' ' + commentSyntax.close);
+ }
+ replacement.push(indent + commentSyntax.open + ' impeccable-carbonize-end ' + id + ' ' + commentSyntax.close);
+ }
+
+ // Keep the `@scope ([data-impeccable-variant="N"])` selectors in the
+ // carbonize CSS block working visually by re-wrapping the accepted content
+ // in a data-impeccable-variant="N" div with `display: contents` (so layout
+ // isn't affected). The carbonize agent strips this attribute + wrapper when
+ // it moves the CSS to a proper stylesheet.
+ //
+ // Style attribute syntax has to follow the host file's flavor — JSX files
+ // need the object form, otherwise React 19 throws "Failed to set indexed
+ // property [0] on CSSStyleDeclaration" while parsing the string char-by-char.
+ if (cssContent) {
+ const styleAttr = isJsx ? "style={{ display: 'contents' }}" : 'style="display: contents"';
+ replacement.push(indent + '');
+ replacement.push(...restored);
+ replacement.push(indent + '
');
+ } else {
+ replacement.push(...restored);
+ }
+
+ const newLines = [
+ ...lines.slice(0, replaceRange.start),
+ ...replacement,
+ ...lines.slice(replaceRange.end + 1),
+ ];
+ fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+
+ return { carbonize: needsCarbonize, acceptedOriginalText: originalContent.join('\n') };
+}
+
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the start/end marker lines for a session.
+ * Returns { start, end } (0-indexed line numbers) or null.
+ */
+function findMarkerBlock(id, lines) {
+ let start = -1;
+ let end = -1;
+ const startPattern = 'impeccable-variants-start ' + id;
+ const endPattern = 'impeccable-variants-end ' + id;
+
+ for (let i = 0; i < lines.length; i++) {
+ if (start === -1 && lines[i].includes(startPattern)) start = i;
+ if (lines[i].includes(endPattern)) { end = i; break; }
+ }
+
+ return (start !== -1 && end !== -1) ? { start, end, id } : null;
+}
+
+/**
+ * Compute the line range to REPLACE (vs. just the marker range to extract
+ * from). For JSX/TSX wrappers, live-wrap places the marker comments INSIDE
+ * the `` outer wrapper so the picked
+ * element's JSX slot keeps a single child — a Fragment `<>` would have
+ * solved the multi-sibling case but failed inside `asChild` / cloneElement
+ * parents with "Invalid prop supplied to React.Fragment".
+ *
+ * That means the marker block is enclosed by the wrapper `
` opener
+ * (with `data-impeccable-variants="ID"`) and its matching `
`. We
+ * walk back to the opener and forward to the closer so accept/discard
+ * remove the entire scaffold, not just the inner markers.
+ *
+ * Marker lines themselves stay where they were so extractOriginal /
+ * extractVariant / extractCss continue to walk the same range.
+ */
+function expandReplaceRange(block, lines, isJsx) {
+ if (!isJsx) return { start: block.start, end: block.end };
+
+ let { start, end } = block;
+
+ // Walk back for the wrapper `
= 0; i--) {
+ if (isVariantEndMarkerLine(lines[i], block.id)) break;
+ if (hasVariantWrapperAttr(lines[i], block.id)) {
+ let opener = i;
+ while (opener > 0 && !/
` by div-depth tracking from the
+ // wrapper opener. Operate on JOINED text instead of per-line: a
+ // multi-line self-closing JSX `` would
+ // fool per-line regex tracking (the `` line never matches selfCloseRe since it needs `` orphaned after accept/discard. Single regex with
+ // `[^>]*?` (which spans newlines in JS) handles either form correctly.
+ const joined = lines.slice(start).join('\n');
+ // Match either `` (self-close, group 1 is `/`), ``
+ // (open, group 1 is empty), or `
`.
+ const tagRe = /]*?(\/?)>|<\/div\s*>/g;
+ let depth = 0;
+ let m;
+ while ((m = tagRe.exec(joined)) !== null) {
+ const isClose = m[0].startsWith('= end) {
+ end = candidateEnd;
+ break;
+ }
+ }
+ }
+
+ return { start, end };
+}
+
+function escapeRegExp(value) {
+ return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function isVariantEndMarkerLine(line, id) {
+ return new RegExp('impeccable-variants-end\\s+' + escapeRegExp(id) + '(?:\\s|--|\\*/|$)').test(line);
+}
+
+function hasVariantWrapperAttr(line, id) {
+ const escaped = escapeRegExp(id);
+ return new RegExp(`data-impeccable-variants\\s*=\\s*(?:"${escaped}"|'${escaped}'|\\{["']${escaped}["']\\})`).test(line);
+}
+
+/**
+ * Join wrapper lines into a single string with `` to close on)
+ * - Same-line `` blocks
+ * - Multi-line `` blocks
+ */
+function stripStyleAndJoin(lines, block) {
+ const out = [];
+ let inStyle = false;
+ for (let i = block.start; i <= block.end; i++) {
+ let line = lines[i];
+
+ if (!inStyle) {
+ // Strip any complete .
+ const closeIdx = line.search(/<\/style\s*>/);
+ if (closeIdx !== -1) {
+ inStyle = false;
+ out.push(line.slice(closeIdx).replace(/<\/style\s*>/, ''));
+ }
+ // else: skip line entirely
+ }
+ }
+ return out.join('\n');
+}
+
+/**
+ * Find the inner content of `…` inside `text`,
+ * handling nested same-tag elements via depth counting. `attrMatch` is a
+ * regex source fragment that must appear inside the opener tag.
+ * Returns the inner string (may be empty), or null if not found.
+ */
+function extractInnerByAttr(text, attrMatch) {
+ const openerRe = new RegExp('<([A-Za-z][A-Za-z0-9]*)\\b[^>]*' + attrMatch + '[^>]*>');
+ const openMatch = text.match(openerRe);
+ if (!openMatch) return null;
+
+ const tagName = openMatch[1];
+ const innerStart = openMatch.index + openMatch[0].length;
+
+ // Match any opener or closer of this tag name after innerStart.
+ // (Does not match self-closing , which doesn't contribute to depth.)
+ const tagRe = new RegExp('<(?:/)?' + tagName + '\\b[^>]*>', 'g');
+ tagRe.lastIndex = innerStart;
+
+ let depth = 1;
+ let m;
+ while ((m = tagRe.exec(text))) {
+ const isClose = m[0].startsWith('$/.test(m[0]);
+ if (isClose) {
+ depth--;
+ if (depth === 0) return text.slice(innerStart, m.index);
+ } else if (!isSelfClose) {
+ depth++;
+ }
+ }
+ return null;
+}
+
+/**
+ * Extract the original element content from within the variant wrapper.
+ * Returns an array of lines.
+ */
+function extractOriginal(lines, block) {
+ const text = stripStyleAndJoin(lines, block);
+ const inner = extractInnerByAttr(text, 'data-impeccable-variant="original"');
+ if (inner === null) return [];
+ return inner.split('\n');
+}
+
+/**
+ * Extract a specific variant's inner content (stripping the wrapper div).
+ * Returns an array of lines, or null if not found.
+ */
+function extractVariant(lines, block, variantNum) {
+ const text = stripStyleAndJoin(lines, block);
+ const inner = extractInnerByAttr(text, 'data-impeccable-variant="' + variantNum + '"');
+ if (inner === null) return null;
+ const result = inner.split('\n');
+ // Collapse a lone empty leading/trailing line (common after string splice).
+ while (result.length > 1 && result[0].trim() === '') result.shift();
+ while (result.length > 1 && result[result.length - 1].trim() === '') result.pop();
+ return result.length > 0 ? result : null;
+}
+
+/**
+ * Extract the colocated ` — return the inner content.
+ * 3. Multi-line: `` on a later line — return
+ * the lines between them.
+ */
+function extractCss(lines, block, id) {
+ const styleAttr = 'data-impeccable-css="' + id + '"';
+ let inStyle = false;
+ const content = [];
+
+ for (let i = block.start; i <= block.end; i++) {
+ const line = lines[i];
+
+ if (!inStyle && line.includes(styleAttr)) {
+ // Self-closing: nothing to carbonize.
+ if (/]*\/\s*>/.test(line)) return null;
+ // Same-line open + close: extract inner text.
+ const sameLine = line.match(/]*>([\s\S]*?)<\/style\s*>/);
+ if (sameLine) {
+ const inner = stripJsxTemplateWrap(sameLine[1]);
+ return inner.length > 0 ? inner.split('\n') : null;
+ }
+ inStyle = true;
+ continue; // skip the anywhere on the line — JSX template-literal closes
+ // (`}`) put the close mid-line, and we don't want to absorb the
+ // template-literal punctuation as CSS content.
+ const closeIdx = line.indexOf('');
+ if (closeIdx !== -1) break;
+ content.push(line);
+ }
+ }
+
+ if (content.length === 0) return null;
+ return stripJsxTemplateLines(content);
+}
+
+/**
+ * Strip a JSX template-literal wrap (`{` … `}`) from CSS extracted out of a
+ * ` close.',
+ 'Prefix every preview selector with the matching [data-impeccable-variant="N"] selector.',
+ 'Keep selectors anchored to the generated variant wrapper; do not rely on component CSS scoping for preview rules.',
+ ],
+ forbidden: [
+ 'Do not use @scope for this styleMode.',
+ 'Do not wrap style content in a JSX/TSX template literal ({` ... `}); that syntax is for .tsx/.jsx only.',
+ 'Do not put { immediately after the style opening tag; Astro parses { as expression syntax.',
+ ],
+ };
+ }
+ return {
+ mode: styleMode.mode,
+ styleTag: styleMode.styleTag,
+ strategy: 'scope-rule',
+ rulePattern: '@scope ([data-impeccable-variant="N"]) { :scope > .variant-class { ... } }',
+ selectorExamples: variantNumbers.map((n) => `@scope ([data-impeccable-variant="${n}"]) { :scope > .variant-class { ... } }`),
+ requirements: [
+ 'Use @scope blocks keyed to each [data-impeccable-variant="N"] wrapper.',
+ 'Inside each @scope block, make :scope rules step into the replacement element with a descendant combinator.',
+ 'Use the styleTag exactly; do not add framework-specific style attributes unless this object says to.',
+ ],
+ forbidden: [
+ 'Do not use global [data-impeccable-variant="N"] selector prefixes for this styleMode.',
+ 'Do not add is:inline to the style tag for this styleMode.',
+ ],
+ };
+}
+
+/**
+ * Search project files for the query string (class name, ID, etc.)
+ * Returns the first matching file path, or null.
+ */
+function findFileWithQuery(query, cwd, genOpts = {}) {
+ const searchDirs = ['src', 'app', 'pages', 'components', 'public', 'views', 'templates', '.'];
+ const seen = new Set();
+
+ for (const dir of searchDirs) {
+ const absDir = path.join(cwd, dir);
+ if (!fs.existsSync(absDir)) continue;
+ const result = searchDir(absDir, query, seen, 0, genOpts);
+ if (result) return result;
+ }
+ return null;
+}
+
+function searchDir(dir, query, seen, depth, genOpts) {
+ if (depth > 5) return null; // don't go too deep
+ const realDir = fs.realpathSync(dir);
+ if (seen.has(realDir)) return null;
+ seen.add(realDir);
+
+ let entries;
+ try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+ catch { return null; }
+
+ // Check files first
+ for (const entry of entries) {
+ if (!entry.isFile()) continue;
+ const ext = path.extname(entry.name).toLowerCase();
+ if (!EXTENSIONS.includes(ext)) continue;
+
+ const filePath = path.join(dir, entry.name);
+ if (!genOpts.includeGenerated && isGeneratedFile(filePath, genOpts)) continue;
+ try {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ if (content.includes(query)) return filePath;
+ } catch { /* skip unreadable files */ }
+ }
+
+ // Then recurse into directories. Always skip node_modules and .git (never
+ // project content). dist/build/out are left to the isGeneratedFile guard so
+ // the includeGenerated second-pass can still find the element there and
+ // report `generatedMatch`.
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ if (entry.name === 'node_modules' || entry.name === '.git') continue;
+ const result = searchDir(path.join(dir, entry.name), query, seen, depth + 1, genOpts);
+ if (result) return result;
+ }
+
+ return null;
+}
+
+/**
+ * Regex that matches a tag opener on a line. Allows the tag name to be
+ * followed by whitespace, `>`, `/`, or end-of-line so that multi-line JSX
+ * openers (e.g. ``) are recognised.
+ */
+const OPENER_RE = /<([A-Za-z][A-Za-z0-9]*)(?=[\s/>]|$)/;
+
+/**
+ * Find the element's start and end line in the file.
+ *
+ * `query` is a class name, attribute fragment (`class="..."`, `className="..."`,
+ * `id="..."`), or a raw text snippet. Because a query can appear on a
+ * continuation line of a multi-line tag (e.g. the `className="..."` row of a
+ * `` JSX tag), we walk backward from the match
+ * line to find the actual tag opener. When `tag` is provided, opener candidates
+ * must match that tag name.
+ */
+/**
+ * Return the smallest leading-whitespace count across a set of lines,
+ * ignoring blank lines (whose indent isn't load-bearing). Used to compute
+ * the common base indent of a multi-line picked element so reindenting
+ * under the wrapper preserves the relative depth between lines.
+ */
+function minLeadingSpaces(lines) {
+ let min = Infinity;
+ for (const l of lines) {
+ if (l.trim() === '') continue;
+ const m = l.match(/^(\s*)/);
+ if (m && m[1].length < min) min = m[1].length;
+ }
+ return min === Infinity ? 0 : min;
+}
+
+function findElement(lines, query, tag = null) {
+ // Iterate all matches — the first substring hit isn't always the right one.
+ for (let i = 0; i < lines.length; i++) {
+ if (!lines[i].includes(query)) continue;
+
+ const stripped = lines[i].trim();
+ if (stripped.startsWith('';
+
+/**
+ * Walk up from startDir to find a project root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+ let dir = resolve(startDir);
+ while (dir !== '/') {
+ if (
+ existsSync(join(dir, 'package.json')) ||
+ existsSync(join(dir, '.git')) ||
+ existsSync(join(dir, 'skills-lock.json'))
+ ) {
+ return dir;
+ }
+ const parent = resolve(dir, '..');
+ if (parent === dir) break;
+ dir = parent;
+ }
+ return resolve(startDir);
+}
+
+/**
+ * Find harness skill directories that have an impeccable skill installed.
+ */
+function findHarnessDirs(projectRoot) {
+ const dirs = [];
+ for (const harness of HARNESS_DIRS) {
+ const skillsDir = join(projectRoot, harness, 'skills');
+ // Only pin in harness dirs that already have impeccable installed
+ const impeccableDir = join(skillsDir, 'impeccable');
+ if (existsSync(impeccableDir) || existsSync(join(skillsDir, 'i-impeccable'))) {
+ dirs.push(skillsDir);
+ }
+ }
+ return dirs;
+}
+
+/**
+ * Load command metadata (descriptions for pinned skills).
+ */
+function loadCommandMetadata() {
+ const metadataPath = join(__dirname, 'command-metadata.json');
+ if (existsSync(metadataPath)) {
+ return JSON.parse(readFileSync(metadataPath, 'utf-8'));
+ }
+ return {};
+}
+
+/**
+ * Generate a pinned skill's SKILL.md content.
+ */
+function generatePinnedSkill(command, metadata) {
+ const desc = metadata[command]?.description || `Shortcut for /impeccable ${command}.`;
+ const hint = metadata[command]?.argumentHint || '[target]';
+
+ return `---
+name: ${command}
+description: "${desc}"
+argument-hint: "${hint}"
+user-invocable: true
+---
+
+${PIN_MARKER}
+
+This is a pinned shortcut for \`{{command_prefix}}impeccable ${command}\`.
+
+Invoke {{command_prefix}}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
+`;
+}
+
+/**
+ * Pin a command: create shortcut skill in all harness dirs.
+ */
+function pin(command, projectRoot) {
+ const metadata = loadCommandMetadata();
+ const harnessDirs = findHarnessDirs(projectRoot);
+
+ if (harnessDirs.length === 0) {
+ console.log('No harness directories with impeccable installed found.');
+ return false;
+ }
+
+ const content = generatePinnedSkill(command, metadata);
+ let created = 0;
+
+ for (const skillsDir of harnessDirs) {
+ // Check if skill already exists (and isn't a pin)
+ const skillDir = join(skillsDir, command);
+ if (existsSync(skillDir)) {
+ const existingMd = join(skillDir, 'SKILL.md');
+ if (existsSync(existingMd)) {
+ const existing = readFileSync(existingMd, 'utf-8');
+ if (!existing.includes(PIN_MARKER)) {
+ console.log(` SKIP: ${skillDir} (non-pinned skill already exists)`);
+ continue;
+ }
+ }
+ }
+
+ mkdirSync(skillDir, { recursive: true });
+ writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+ console.log(` + ${skillDir}`);
+ created++;
+ }
+
+ if (created > 0) {
+ console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
+ console.log(`You can now use /${command} directly.`);
+ }
+
+ return created > 0;
+}
+
+/**
+ * Unpin a command: remove shortcut skill from all harness dirs.
+ */
+function unpin(command, projectRoot) {
+ const harnessDirs = findHarnessDirs(projectRoot);
+ let removed = 0;
+
+ for (const skillsDir of harnessDirs) {
+ const skillDir = join(skillsDir, command);
+ if (!existsSync(skillDir)) continue;
+
+ const skillMd = join(skillDir, 'SKILL.md');
+ if (!existsSync(skillMd)) continue;
+
+ // Safety: only remove if it's a pinned skill
+ const content = readFileSync(skillMd, 'utf-8');
+ if (!content.includes(PIN_MARKER)) {
+ console.log(` SKIP: ${skillDir} (not a pinned skill)`);
+ continue;
+ }
+
+ rmSync(skillDir, { recursive: true, force: true });
+ console.log(` - ${skillDir}`);
+ removed++;
+ }
+
+ if (removed > 0) {
+ console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
+ console.log(`Use /impeccable ${command} to access it.`);
+ } else {
+ console.log(`No pinned '${command}' shortcut found.`);
+ }
+
+ return removed > 0;
+}
+
+// --- CLI ---
+const [,, action, command] = process.argv;
+
+if (!action || !command) {
+ console.log('Usage: node pin.mjs ');
+ console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
+ process.exit(1);
+}
+
+if (action !== 'pin' && action !== 'unpin') {
+ console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
+ process.exit(1);
+}
+
+if (!VALID_COMMANDS.includes(command)) {
+ console.error(`Unknown command: ${command}`);
+ console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
+ process.exit(1);
+}
+
+const root = findProjectRoot();
+
+if (action === 'pin') {
+ pin(command, root);
+} else {
+ unpin(command, root);
+}
diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
index cdce94c..86534e3 100644
--- a/.beads/issues.jsonl
+++ b/.beads/issues.jsonl
@@ -24,6 +24,7 @@
{"_type":"issue","id":"islandflow-ayo","title":"Drop stale backlog events from live fanout","description":"Follow-up to live freshness rollout: /ws/live was still fanning out stale backlog events for freshness-gated channels, which kept tape panes in Live feed behind despite active synthetic ingest. Gate fanout and cache ingest by freshness for options/nbbo/equities/flow.","status":"closed","priority":1,"issue_type":"bug","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:26:39Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:26:44Z","started_at":"2026-04-28T21:26:44Z","closed_at":"2026-04-28T21:26:44Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"islandflow-0v6","title":"Fix tape freshness, NBBO coverage, pause controls, and filter popup","description":"Implement the tape fixes requested for synthetic options notional sizing, strict live freshness, live-mode pause/resume behavior, stronger NBBO snapshot coverage, and moving flow filters behind a popup. Includes server-side live cache changes, web terminal state/UI changes, and tests for synthetic pricing, live snapshot freshness/NBBO retention, and live pause/filter interactions.","status":"closed","priority":1,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T21:02:52Z","created_by":"dirtydishes","updated_at":"2026-04-28T21:13:38Z","started_at":"2026-04-28T21:02:57Z","closed_at":"2026-04-28T21:13:38Z","close_reason":"Completed","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"islandflow-e4r","title":"Implement smart-money flow filtering and synthetic firehose modes","description":"Implement the approved multi-surface plan for named synthetic market profiles, options raw-vs-signal filtering, live/API filter contracts, Tape page client-side flow filters, firehose-readiness improvements, tests, and README updates.","status":"closed","priority":1,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-04-28T20:10:49Z","created_by":"dirtydishes","updated_at":"2026-04-28T20:29:29Z","started_at":"2026-04-28T20:10:53Z","closed_at":"2026-04-28T20:29:29Z","close_reason":"Implemented synthetic market profiles, options signal-path filtering, signal-aware API/replay contracts, Tape page filters, tests, and README updates. Follow-up tracked in islandflow-biq.","dependency_count":0,"dependent_count":0,"comment_count":0}
+{"_type":"issue","id":"islandflow-9en","title":"Install Impeccable skill for Codex","description":"Install the Impeccable skill in the Codex-compatible project locations after the upstream installer selected unused harness folders.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-29T07:59:10Z","created_by":"dirtydishes","updated_at":"2026-05-29T07:59:22Z","started_at":"2026-05-29T07:59:18Z","closed_at":"2026-05-29T07:59:22Z","close_reason":"Installed Impeccable into .agents and mirrored it into .codex/skills for Codex use.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"islandflow-444","title":"Add typecheck to Forgejo CI","description":"Forgejo CI already validates PRs and pushes to main, but it does not run the new repository-wide typecheck gate. Add bun run typecheck before tests so type drift fails early in CI.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-29T06:27:47Z","created_by":"dirtydishes","updated_at":"2026-05-29T06:29:33Z","started_at":"2026-05-29T06:27:49Z","closed_at":"2026-05-29T06:29:33Z","close_reason":"Added repository typecheck to the Forgejo PR/main CI workflow.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"islandflow-wvz","title":"Add repository typecheck command","description":"The repository has TypeScript tsconfig files across apps, services, and packages, but no root command that runs typechecking consistently. Add a Bun-first typecheck entry point and validate it.","status":"closed","priority":2,"issue_type":"task","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-29T06:11:57Z","created_by":"dirtydishes","updated_at":"2026-05-29T06:19:09Z","started_at":"2026-05-29T06:12:02Z","closed_at":"2026-05-29T06:19:09Z","close_reason":"Added and validated a repository-wide Bun typecheck command.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"islandflow-ddm","title":"Redesign home as command deck","description":"Implement the mock1-inspired production command deck on / while preserving focused /options and /news workspaces plus existing legacy redirects. Scope includes apps/web terminal layout, production command-deck CSS, validation, turn documentation, and Forgejo publish.","notes":"Scope: redesign / as a mock1-inspired production command deck using live useTerminal state and existing panes; preserve /options, /news, /mock1, and current legacy redirects. Leave unrelated apps/web/next-env.d.ts and piolium/ changes untouched.","status":"closed","priority":2,"issue_type":"feature","assignee":"dirtydishes","owner":"dishes@dpdrm.com","created_at":"2026-05-28T08:59:14Z","created_by":"dirtydishes","updated_at":"2026-05-28T09:09:43Z","started_at":"2026-05-28T08:59:29Z","closed_at":"2026-05-28T09:09:43Z","close_reason":"Implemented / as a mock1-inspired production command deck using live terminal state, preserved focused /options and /news routes plus legacy redirects, validated tests/build/screenshots, and documented the turn.","dependency_count":0,"dependent_count":0,"comment_count":0}
diff --git a/.codex/skills/impeccable/SKILL.md b/.codex/skills/impeccable/SKILL.md
new file mode 100644
index 0000000..ad618f6
--- /dev/null
+++ b/.codex/skills/impeccable/SKILL.md
@@ -0,0 +1,182 @@
+---
+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.
+---
+
+Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
+
+## Setup
+
+You MUST do these steps before proceeding:
+
+1. Run `node .agents/skills/impeccable/scripts/context.mjs` once per session. If you've already seen its output in this conversation, do not re-run it. The script either prints the project's PRODUCT.md (and DESIGN.md when present) as a markdown block, or tells you it's missing. Follow whatever it prints. **If it reports `NO_PRODUCT_MD`, stop and follow `reference/init.md` before doing anything else.** If the output ends with an `UPDATE_AVAILABLE` directive, follow it (ask the user once about updating, then continue). It never blocks the current task.
+2. If the user invoked a sub-command (`craft`, `shape`, `audit`, `polish`, ...), you MUST read `reference/.md` next. Non-optional. The reference defines the command's flow; without it you will skip steps the user expects.
+3. Familiarize yourself with any existing design system, conventions, and components in the code. Read at least one project file (CSS / tokens / theme / a representative component or page). **Required even when you've loaded a sub-command reference in step 2.** Don't reinvent the wheel; use what's there when it works, branch out when the UX wins.
+4. Read the matching register reference. **This is non-optional; skipping it produces generic output.** If the project is marketing, a landing page, a campaign, long-form content, or a portfolio (design IS the product), read `reference/brand.md`. If it is app UI, admin, a dashboard, or a tool (design SERVES the product), read `reference/product.md`. Pick by first match: (1) task cue ("landing page" vs "dashboard"); (2) surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md.
+5. **If the project is brand-new (no existing CSS tokens / theme / committed brand colors found in step 3)**, run `node .agents/skills/impeccable/scripts/palette.mjs` to receive a brand seed color and composition guidance. This is the anchor for your primary brand color. Compose the rest of the palette (bg, surface, ink, accent, muted) around it per the script's instructions. Use OKLCH throughout. **Skip this step only if step 3 found committed brand colors in existing tokens; in that case identity-preservation wins.**
+
+## Design guidance
+
+Produce ready-to-ship, production-grade code, not prototypes or starting points. Take no shortcuts unless the user asks for them (when in doubt, ask). Don't stop until arriving at a complete implementation (beautiful, responsive, fast, precise, bug-free, on brand). You take attention to detail seriously: every page, section or component crafted is battle tested using the tools available to you (browser screenshotting, computer use, etc). GPT is capable of extraordinary work. Don't hold back.
+
+### General rules
+
+#### Color
+
+- **Verify contrast.** Body text must hit ≥4.5:1 against its background; large text (≥18px or bold ≥14px) needs ≥3:1. Placeholder text needs the same 4.5:1, not the muted-gray default. The most common failure: muted gray body text on a tinted near-white. If the contrast is even close, bump the body color toward the ink end of the ramp; light gray "for elegance" is the single biggest reason AI designs feel hard to read.
+- Gray text on a colored background looks washed out. Use a darker shade of the background's own hue, or a transparency of the text color.
+
+#### Typography
+
+- Cap body line length at 65–75ch.
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
+- Cap font-family count at 3 (display + body + optional mono). More than 3 reads as indecision, not richness. One well-tuned family with weight contrast usually beats three competing typefaces.
+- Don't pair fonts that are similar but not identical (two geometric sans-serifs, two humanist sans-serifs). Pair on a contrast axis (serif + sans, geometric + humanist) or use one family in multiple weights.
+- No all-caps body copy. Reserve uppercase for short labels (≤4 words), section eyebrows (used sparingly per the Absolute bans), and badges. Sentences in ALL CAPS are unreadable at body sizes.
+- Hero / display heading ceiling: clamp() max ≤ 6rem (~96px). Above that the page is shouting, not designing.
+- Display heading letter-spacing floor: ≥ -0.04em. Anything tighter and letters touch; cramped, not "designed".
+- Use `text-wrap: balance` on h1–h3 for even line lengths; `text-wrap: pretty` on long prose to reduce orphans.
+
+Two hard typographic ceilings you currently miss:
+- Hero clamp() max ≤ 6rem. 8–11rem (128–176px) reads as comically loud, not bold.
+- Display letter-spacing ≥ -0.04em. Your default of -0.05 to -0.085em on display H1s makes the letters touch and reads as cramped. -0.02 to -0.03em is plenty for tight grotesque display; -0.04em is the floor.
+
+#### Layout
+
+- Vary spacing for rhythm.
+- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
+- Flexbox for 1D, Grid for 2D. Don't default to Grid when `flex-wrap` would be simpler.
+- For responsive grids without breakpoints: `repeat(auto-fit, minmax(280px, 1fr))`.
+- Build a semantic z-index scale (dropdown → sticky → modal-backdrop → modal → toast → tooltip). Never arbitrary values like 999 or 9999.
+
+#### Motion
+- Motion should be intentional, and not be an afterthought. consider it as part of the build.
+- Don't animate CSS layout properties unless truly needed.
+- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.
+- Use libraries for more advanced motion needs (e.g. motion, gsap, anime.js, lenis etc)
+- Reduced motion is not optional. Every animation needs a `@media (prefers-reduced-motion: reduce)` alternative: typically a crossfade or instant transition.
+- Staggering the items within one list is legitimate. The tell is the uniform reflex (one identical entrance applied to every section), not motion itself; each reveal should fit what it reveals. Suppressing the reflex is never a reason to ship a page with no motion at all.
+- Reveal animations must enhance an already-visible default. Don't gate content visibility on a class-triggered transition; transitions pause on hidden tabs and headless renderers, so the reveal never fires and the section ships blank.
+- Premium motion materials are not just transform/opacity. Blur, backdrop-filter, clip-path, mask, and shadow/glow are part of the palette when they materially improve the effect and stay smooth.
+
+#### Interaction
+
+- Dropdowns rendered with `position: absolute` inside an `overflow: hidden` or `overflow: auto` container will be clipped. Use the native `