jig-ui 0.3.0 → 0.5.0

package/dist/index.js

@@ -2,9 +2,9 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { readFileSync as readFileSync12 } from "fs";
+import { readFileSync as readFileSync17 } from "fs";
 import { homedir } from "os";
-import { join as join14 } from "path";
+import { join as join22 } from "path";
 
 // src/paths.ts
 import { existsSync } from "fs";
@@ -37,12 +37,16 @@ function assetRoot(startDir = getPackageRoot()) {
     current = dirname(current);
   }
 }
+function isPublishedBuild(packageRoot2) {
+  return packageRoot2.split(/[\\/]/).includes("node_modules");
+}
 
 // src/commands/install.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join3 } from "path";
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join7 } from "path";
 
 // src/adapters/types.ts
+var COMMAND_DESCRIPTION = "Run a Jig design-system command: set the project up, review the UI against the rules, or refresh the install.";
 var SKILL_DESCRIPTION = "Design system rules for generating and reviewing UI. Load before building any interface.";
 function assertSafeRelPath(relPath, adapterName) {
   const isAbsolute = relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath);
@@ -56,92 +60,172 @@ function quoteYamlString(value) {
 }
 var BLOCK_START = "<!-- jig:start -->";
 var BLOCK_END = "<!-- jig:end -->";
-function agentsBlock(skillBody) {
-  return [BLOCK_START, "", "# Jig \u2014 UI rules", "", skillBody, "", BLOCK_END, ""].join("\n");
+function agentsPointer(skillPath) {
+  return [
+    BLOCK_START,
+    "",
+    "# Jig \u2014 UI rules",
+    "",
+    `This project uses Jig, a design system for generating and reviewing UI.`,
+    `Before building or reviewing any interface, read \`${skillPath}\` and follow it.`,
+    "It is short, and it tells you which rule files to load for the task at hand.",
+    "",
+    BLOCK_END,
+    ""
+  ].join("\n");
 }
 
-// src/adapters/claude.ts
-var claude = {
-  name: "claude",
-  displayName: "Claude Code",
-  supportsScope: () => true,
-  skillFiles(ctx) {
-    const content = [
-      "---",
-      "name: jig",
-      `description: ${quoteYamlString(SKILL_DESCRIPTION)}`,
-      "user-invocable: true",
-      "---",
-      "",
-      ctx.skillBody,
-      ""
-    ].join("\n");
-    return [{ relPath: ".claude/skills/jig/SKILL.md", content }];
-  }
-};
-
 // src/adapters/codex.ts
 var codex = {
   name: "codex",
   displayName: "Codex",
-  supportsScope: () => true,
   skillFiles(ctx) {
-    const relPath = ctx.scope === "global" ? ".codex/AGENTS.md" : "AGENTS.md";
-    return [{ relPath, content: agentsBlock(ctx.skillBody) }];
-  }
-};
-
-// src/adapters/cursor.ts
-var cursor = {
-  name: "cursor",
-  displayName: "Cursor",
-  supportsScope: (scope) => scope === "project",
-  skillFiles(ctx) {
-    const content = [
-      "---",
-      `description: ${quoteYamlString(SKILL_DESCRIPTION)}`,
-      "alwaysApply: false",
-      "---",
-      "",
-      ctx.skillBody,
-      ""
-    ].join("\n");
-    return [{ relPath: ".cursor/rules/jig.mdc", content }];
-  }
-};
-
-// src/adapters/opencode.ts
-var opencode = {
-  name: "opencode",
-  displayName: "opencode",
-  supportsScope: () => true,
-  skillFiles(ctx) {
-    const content = [
-      "---",
-      "name: jig",
-      `description: ${quoteYamlString(SKILL_DESCRIPTION)}`,
-      "---",
-      "",
-      ctx.skillBody,
-      ""
-    ].join("\n");
-    const relPath = ctx.scope === "global" ? ".config/opencode/skills/jig/SKILL.md" : ".opencode/skills/jig/SKILL.md";
-    return [{ relPath, content }];
-  }
+    const skillPath = ".agents/skills/jig/SKILL.md";
+    const files = [{ relPath: skillPath, content: ctx.skillBody }];
+    const agentsPath = ctx.scope === "global" ? ".codex/AGENTS.md" : "AGENTS.md";
+    files.push({ relPath: agentsPath, content: agentsPointer(skillPath) });
+    if (ctx.commandBody && ctx.scope === "global") {
+      files.push({ relPath: ".codex/prompts/jig.md", content: `${ctx.commandBody}
+` });
+    }
+    return files;
+  },
+  /**
+   * codex has no skill directory: AGENTS.md is a plain file (project root, or
+   * `.codex/` for a global install). Reference material lives under `.codex/`
+   * at BOTH scopes.
+   *
+   * Project scope used to be a bare `.jig`, which put Jig's rules, index,
+   * licence and manifest into the one directory 0.4.0 reserves for the
+   * project's own material — the brand file, the mode copies, `state.json`.
+   * That cost more than tidiness:
+   *
+   * - `detectLegacyRules` scans `.jig/` for install artifacts and offers to
+   *   remove them. Under the old layout a *live* codex install looked exactly
+   *   like the legacy one, so the migration path could offer to delete the
+   *   install just made.
+   * - One directory holding two manifests is what let a stale
+   *   `.jig/manifest.json` hijack `update` and resurrect the vendored layout.
+   *
+   * Mirroring the global path keeps codex's own convention and leaves `.jig/`
+   * unambiguously the project's.
+   */
+  /**
+   * Beside the skill, like every other harness — the rules are what `SKILL.md`
+   * tells the agent to read, so they belong next to it. This used to be
+   * `.codex/.jig`, and before that a bare `.jig`, which put Jig's property in
+   * the one directory the project owns.
+   */
+  referenceDir: () => ".agents/skills/jig",
+  argsPlaceholder: "$ARGUMENTS"
 };
 
-// src/adapters/generic.ts
-var generic = {
-  name: "generic",
-  displayName: "Generic (AGENTS.md)",
-  supportsScope: (scope) => scope === "project",
-  skillFiles(ctx) {
-    return [{ relPath: "AGENTS.md", content: agentsBlock(ctx.skillBody) }];
+// src/adapters/skill-dir.ts
+var SKILL_DIR_HARNESSES = [
+  {
+    name: "claude",
+    dir: ".claude",
+    displayName: "Claude Code",
+    extraFrontmatter: ["user-invocable: true"],
+    // `commands/<name>.md`, YAML frontmatter, `$ARGUMENTS` in the body —
+    // verified against the shipped command files under
+    // ~/.claude/plugins/marketplaces/*/plugins/*/commands/.
+    commands: { dir: "commands", format: "md" }
+  },
+  { name: "cursor", dir: ".cursor", displayName: "Cursor", commands: { dir: "commands", format: "md" } },
+  {
+    name: "opencode",
+    dir: ".opencode",
+    globalDir: ".config/opencode",
+    displayName: "opencode",
+    // Singular `command/`, unlike everyone else's `commands/`.
+    commands: { dir: "command", format: "md" }
+  },
+  // No slash-command mechanism of its own — `.agents` is a skills convention
+  // rather than a harness, so there is nothing to write a command file for.
+  { name: "generic", dir: ".agents", displayName: "Generic (.agents/skills)" },
+  // Proves the table design: this row is the entire diff needed to support
+  // a sixth harness. Gemini CLI, Copilot CLI and others read `.agents/skills`
+  // too, but Gemini also has its own `.gemini` skill directory.
+  {
+    name: "gemini",
+    dir: ".gemini",
+    displayName: "Gemini CLI",
+    // Gemini reads TOML, with `{{args}}` where the others use `$ARGUMENTS`.
+    commands: { dir: "commands", format: "toml" }
   }
-};
+];
+function dirFor(h, scope) {
+  return scope === "global" && h.globalDir ? h.globalDir : h.dir;
+}
+function skillDirAdapter(h) {
+  return {
+    name: h.name,
+    displayName: h.displayName,
+    skillFiles(ctx) {
+      const content = [
+        "---",
+        "name: jig",
+        `description: ${quoteYamlString(SKILL_DESCRIPTION)}`,
+        ...h.extraFrontmatter ?? [],
+        "---",
+        "",
+        ctx.skillBody,
+        ""
+      ].join("\n");
+      const files = [
+        { relPath: `${dirFor(h, ctx.scope)}/skills/jig/SKILL.md`, content }
+      ];
+      if (h.commands && ctx.commandBody) {
+        files.push({
+          relPath: `${dirFor(h, ctx.scope)}/${h.commands.dir}/jig.${h.commands.format}`,
+          content: h.commands.format === "toml" ? tomlCommand(ctx.commandBody) : markdownCommand(ctx.commandBody, ctx.subcommands ?? [])
+        });
+      }
+      return files;
+    },
+    referenceDir(scope) {
+      return `${dirFor(h, scope)}/skills/jig`;
+    },
+    argsPlaceholder: h.commands?.format === "toml" ? "{{args}}" : "$ARGUMENTS"
+  };
+}
+function markdownCommand(body, subcommands) {
+  return [
+    "---",
+    `description: ${quoteYamlString(COMMAND_DESCRIPTION)}`,
+    `argument-hint: ${subcommands.join("|")} [flags]`,
+    "---",
+    "",
+    body,
+    ""
+  ].join("\n");
+}
+var TOML_DELIM = "'''";
+function tomlCommand(body) {
+  const safe = body.split(TOML_DELIM).join('"""');
+  return [
+    `description = ${JSON.stringify(COMMAND_DESCRIPTION)}`,
+    `prompt = ${TOML_DELIM}`,
+    safe,
+    TOML_DELIM,
+    ""
+  ].join("\n");
+}
+var SKILL_DIR_ADAPTERS = SKILL_DIR_HARNESSES.map(skillDirAdapter);
 
 // src/adapters/registry.ts
-var ADAPTERS = [claude, codex, cursor, opencode, generic];
+var ADAPTERS = [codex, ...SKILL_DIR_ADAPTERS];
+function referenceDirFor(adapter, scope) {
+  const dir = adapter.referenceDir(scope);
+  assertSafeRelPath(dir, adapter.name);
+  return dir;
+}
+for (const adapter of ADAPTERS) {
+  for (const scope of ["project", "global"]) {
+    assertSafeRelPath(adapter.referenceDir(scope), adapter.name);
+  }
+}
 function adapterNames() {
   return ADAPTERS.map((a) => a.name);
 }
@@ -160,12 +244,59 @@ function skillFilesFor(adapter, ctx) {
   return files;
 }
 
+// src/install/references.ts
+import { existsSync as existsSync2, readFileSync, readdirSync } from "fs";
+import { join as join2, posix } from "path";
+function referenceFiles(packageRoot2) {
+  const root = join2(packageRoot2, "references");
+  if (!existsSync2(root)) return [];
+  const found = [];
+  const walk2 = (dir, prefix) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort(
+      (a, b) => a.name.localeCompare(b.name)
+    )) {
+      const child = join2(dir, entry.name);
+      const rel = prefix ? posix.join(prefix, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        walk2(child, rel);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        found.push({ relPath: rel, content: readFileSync(child, "utf8") });
+      }
+    }
+  };
+  walk2(root, "");
+  return found;
+}
+
 // src/install/manifest.ts
 import { createHash } from "crypto";
-import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-var MANIFEST_REL = join2(".jig", "manifest.json");
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname3, join as join4 } from "path";
+
+// src/install/atomic.ts
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+function writeFileAtomic(path, content) {
+  const dir = dirname2(path);
+  mkdirSync(dir, { recursive: true });
+  const tmp = join3(dir, `.${process.pid}-${Date.now()}.tmp`);
+  try {
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+
+// src/install/manifest.ts
 var REGENERATE_HINT = "Re-run 'jig install --agent <name>' to fix it.";
+function manifestPath(root, manifestDir) {
+  return join4(root, ...manifestDir.split("/"), "manifest.json");
+}
 function checksum(content) {
   const normalized = content.replace(/\r\n/g, "\n");
   return `sha256:${createHash("sha256").update(normalized, "utf8").digest("hex")}`;
@@ -200,29 +331,45 @@ function validateManifest(raw, path) {
     files
   };
 }
-function readManifest(projectRoot) {
-  const path = join2(projectRoot, MANIFEST_REL);
-  if (!existsSync2(path)) return null;
+function readManifest(root, manifestDir = ".jig") {
+  const path = manifestPath(root, manifestDir);
+  if (!existsSync3(path)) return null;
   let raw;
   try {
-    raw = JSON.parse(readFileSync(path, "utf8"));
+    raw = JSON.parse(readFileSync2(path, "utf8"));
   } catch {
     throw new Error(`Jig's manifest at ${path} is not valid JSON. ${REGENERATE_HINT}`);
   }
   return validateManifest(raw, path);
 }
-function writeManifest(projectRoot, m) {
-  const path = join2(projectRoot, MANIFEST_REL);
-  mkdirSync(dirname2(path), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(m, null, 2)}
-`, "utf8");
+var MERGE_ATTEMPTS = 5;
+function writeManifest(root, m, manifestDir = ".jig") {
+  const path = manifestPath(root, manifestDir);
+  mkdirSync2(dirname3(path), { recursive: true });
+  for (let attempt = 0; attempt < MERGE_ATTEMPTS; attempt++) {
+    const onDisk = readManifestQuietly(path);
+    const merged = { ...m, files: { ...onDisk?.files ?? {}, ...m.files } };
+    writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}
+`);
+    const after = readManifestQuietly(path);
+    if (after && Object.keys(merged.files).every((k) => k in after.files)) return;
+  }
+}
+function readManifestQuietly(path) {
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.files)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
 }
 function isModified(projectRoot, relPath, m) {
   const recorded = m.files[relPath];
   if (!recorded) return false;
-  const abs = join2(projectRoot, relPath);
-  if (!existsSync2(abs)) return false;
-  return checksum(readFileSync(abs, "utf8")) !== recorded;
+  const abs = join4(projectRoot, relPath);
+  if (!existsSync3(abs)) return false;
+  return checksum(readFileSync2(abs, "utf8")) !== recorded;
 }
 
 // src/template/render.ts
@@ -250,15 +397,22 @@ function renderCommandTable(metadata) {
 }
 
 // src/install/vendor.ts
+import { posix as posix2 } from "path";
+var { join: join5 } = posix2;
 var DELIMITERS = {
   html: ["<!--", "-->"],
   css: ["/*", "*/"]
 };
-function vendorHeader(file, version2, style = "html") {
+function licencePathFor(relPath) {
+  const depth = relPath.split("/").length - 1;
+  return depth === 0 ? "." : Array(depth).fill("..").join("/");
+}
+function vendorHeader(file, version2, style = "html", licencePath = ".") {
   const [open, close] = DELIMITERS[style];
+  const attribution = licencePath === null ? "     Licensed Apache-2.0. LICENSE and NOTICE ship beside the jig skill." : `     Licensed Apache-2.0. See ${join5(licencePath, "LICENSE")} and ${join5(licencePath, "NOTICE")}.`;
   return [
     `${open} ${file} \u2014 vendored from Jig v${version2}.`,
-    "     Licensed Apache-2.0. See .jig/LICENSE and .jig/NOTICE.",
+    attribution,
     `     Edit freely: \`jig update\` will not overwrite a file you have changed. ${close}`,
     "",
     ""
@@ -301,16 +455,16 @@ function stripMarkerRegions(existing) {
     return { text: existing, insertAt: existing.length, removed: false };
   }
   let text = "";
-  let cursor2 = 0;
+  let cursor = 0;
   let insertAt = -1;
   regions.forEach((region, i) => {
-    let chunk = existing.slice(cursor2, region.start);
+    let chunk = existing.slice(cursor, region.start);
     if (i > 0) chunk = chunk.replace(/^\n/, "");
     text += chunk;
     if (insertAt === -1) insertAt = text.length;
-    cursor2 = region.end;
+    cursor = region.end;
   });
-  const tail = existing.slice(cursor2).replace(/^\n/, "");
+  const tail = existing.slice(cursor).replace(/^\n/, "");
   text += tail;
   return { text, insertAt, removed: true };
 }
@@ -323,85 +477,161 @@ function upsertBlock(existing, block) {
   return `${text.slice(0, insertAt)}${block}${text.slice(insertAt)}`;
 }
 
-// src/commands/install.ts
-var ASK_INSTRUCTION = "Ask the user directly in chat, one question at a time, and wait for an answer before continuing.";
+// src/install/writer.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
+import { dirname as dirname4, join as join6 } from "path";
+
+// src/install/line-endings.ts
+function dominantEnding(existing) {
+  const crlf = (existing.match(/\r\n/g) ?? []).length;
+  const lf = (existing.match(/(?<!\r)\n/g) ?? []).length;
+  if (crlf === 0 && lf === 0) return "\n";
+  return crlf >= lf ? "\r\n" : "\n";
+}
+function matchLineEndings(content, existing) {
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const target = existing === void 0 ? "\n" : dominantEnding(existing);
+  return target === "\n" ? normalized : normalized.replace(/\n/g, "\r\n");
+}
+
+// src/install/writer.ts
 function relKey(...parts) {
   return parts.join("/");
 }
-function writeFile(root, key, content, files) {
-  const abs = join3(root, ...key.split("/"));
-  mkdirSync2(dirname3(abs), { recursive: true });
-  writeFileSync2(abs, content, "utf8");
-  files[key] = checksum(content);
+function createWriter(root, seed = {}) {
+  const files = { ...seed };
+  return {
+    files,
+    write(key, content) {
+      const abs = join6(root, ...key.split("/"));
+      mkdirSync3(dirname4(abs), { recursive: true });
+      const existing = existsSync4(abs) ? readFileSync3(abs, "utf8") : void 0;
+      const toWrite = matchLineEndings(content, existing);
+      writeFileAtomic(abs, toWrite);
+      files[key] = checksum(toWrite);
+      return key;
+    }
+  };
+}
+function bundleFiles(packageRoot2, dir) {
+  const ext = dir === "rules" ? ".md" : ".css";
+  return readdirSync2(join6(packageRoot2, dir)).filter((f) => f.endsWith(ext)).sort();
 }
-function buildSkillBody(packageRoot2, scope) {
-  const template = readFileSync2(join3(packageRoot2, "templates", "SKILL.md.tmpl"), "utf8");
+
+// src/commands/install.ts
+var ASK_INSTRUCTION = "Ask the user directly in chat, one question at a time, and wait for an answer before continuing.";
+function buildSkillBody(packageRoot2, rulesPath, version2) {
+  const template = readFileSync4(join7(packageRoot2, "templates", "SKILL.md.tmpl"), "utf8");
   const metadata = JSON.parse(
-    readFileSync2(join3(packageRoot2, "templates", "command-metadata.json"), "utf8")
+    readFileSync4(join7(packageRoot2, "templates", "command-metadata.json"), "utf8")
   );
   return render(template, {
     command_prefix: "/jig ",
-    scripts_path: "npx jig-ui",
+    scripts_path: version2 ? `npx jig-ui@${version2}` : "npx jig-ui",
+    // `update` must NOT carry the pin. Pinned, it refreshes to the version
+    // already installed — reporting "Updated Jig → <same version>" for a no-op
+    // — so a reader following the skill could never upgrade.
+    update_path: "npx jig-ui@latest",
     ask_instruction: ASK_INSTRUCTION,
     available_commands: renderCommandTable(metadata),
     config_file: "jig.config.json",
-    rules_path: scope === "global" ? "~/.jig" : ".jig"
+    rules_path: rulesPath
   });
 }
+function buildCommandBody(packageRoot2, rulesPath, version2, argsPlaceholder) {
+  const metadata = JSON.parse(
+    readFileSync4(join7(packageRoot2, "templates", "command-metadata.json"), "utf8")
+  );
+  const subcommands = Object.entries(metadata).filter(([, meta]) => meta.status === "available").map(([name]) => name).sort();
+  const templatePath = join7(packageRoot2, "templates", "COMMAND.md.tmpl");
+  if (!existsSync5(templatePath)) return { body: "", subcommands };
+  const template = readFileSync4(templatePath, "utf8");
+  const body = template.replace(/\{\{command_prefix\}\}/g, "/jig ").replace(/\{\{args_placeholder\}\}/g, argsPlaceholder).replace(/\{\{subcommand_list\}\}/g, subcommands.join(", ")).replace(/\{\{scripts_path\}\}/g, `npx jig-ui@${version2}`).replace(/\{\{update_path\}\}/g, "npx jig-ui@latest").replace(/\{\{rules_path\}\}/g, rulesPath);
+  return { body, subcommands };
+}
+function rulesPathFor(referenceDir, scope) {
+  return scope === "global" ? `~/${referenceDir}/rules` : `${referenceDir}/rules`;
+}
 function install(opts) {
   const adapter = getAdapter(opts.agent);
-  if (!adapter.supportsScope(opts.scope)) {
-    throw new Error(`Adapter '${adapter.name}' does not support ${opts.scope} scope.`);
+  if (opts.scope === "project") {
+    const globalReferenceDir = referenceDirFor(adapter, "global");
+    let globalManifest;
+    try {
+      globalManifest = readManifest(opts.homeDir, globalReferenceDir);
+    } catch {
+      globalManifest = null;
+    }
+    if (globalManifest) {
+      return {
+        written: [],
+        skipped: [],
+        warning: `Jig is already installed globally for '${opts.agent}' (${globalReferenceDir} under your home directory). Installing again at project scope would leave two contradicting '${opts.agent}' skills. Run 'jig update' to refresh the global install instead, or choose a different --agent for this project.`
+      };
+    }
   }
   const installRoot = opts.scope === "global" ? opts.homeDir : opts.projectRoot;
+  const referenceDir = referenceDirFor(adapter, opts.scope);
   let existingManifest;
   try {
-    existingManifest = readManifest(installRoot);
+    existingManifest = readManifest(installRoot, referenceDir);
   } catch {
     existingManifest = null;
   }
   const planned = [];
-  const rulesDir = join3(opts.packageRoot, "rules");
-  for (const file of readdirSync(rulesDir).filter((f) => f.endsWith(".md")).sort()) {
-    const body = readFileSync2(join3(rulesDir, file), "utf8");
-    planned.push({ key: relKey(".jig", file), content: vendorHeader(file, opts.version) + body, checkable: true });
-  }
-  const tokensDir = join3(opts.packageRoot, "tokens");
-  for (const file of readdirSync(tokensDir).filter((f) => f.endsWith(".css")).sort()) {
-    const body = readFileSync2(join3(tokensDir, file), "utf8");
+  const rulesDir = join7(opts.packageRoot, "rules");
+  for (const file of bundleFiles(opts.packageRoot, "rules")) {
+    const body = readFileSync4(join7(rulesDir, file), "utf8");
     planned.push({
-      key: relKey(".jig", "tokens", file),
-      content: vendorHeader(file, opts.version, "css") + body,
+      key: relKey(referenceDir, "rules", file),
+      content: vendorHeader(file, opts.version, "html", licencePathFor(`rules/${file}`)) + body,
+      checkable: true
+    });
+  }
+  for (const ref of referenceFiles(opts.packageRoot)) {
+    planned.push({
+      key: relKey(referenceDir, ...ref.relPath.split("/")),
+      content: vendorHeader(ref.relPath, opts.version, "html", licencePathFor(ref.relPath)) + ref.content,
       checkable: true
     });
   }
   planned.push({
-    key: relKey(".jig", "rules.index.json"),
-    content: readFileSync2(join3(opts.packageRoot, "rules.index.json"), "utf8"),
+    key: relKey(referenceDir, "rules.index.json"),
+    content: readFileSync4(join7(opts.packageRoot, "rules.index.json"), "utf8"),
     checkable: true
   });
   for (const src of ["LICENSE", "NOTICE"]) {
     planned.push({
-      key: relKey(".jig", src),
-      content: readFileSync2(join3(opts.packageRoot, src), "utf8"),
+      key: relKey(referenceDir, src),
+      content: readFileSync4(join7(opts.packageRoot, src), "utf8"),
       checkable: false
     });
   }
-  const skillBody = buildSkillBody(opts.packageRoot, opts.scope);
+  const rulesPath = rulesPathFor(referenceDir, opts.scope);
+  const skillBody = buildSkillBody(opts.packageRoot, rulesPath, opts.version);
+  const { body: commandBody, subcommands } = buildCommandBody(
+    opts.packageRoot,
+    rulesPath,
+    opts.version,
+    adapter.argsPlaceholder ?? "$ARGUMENTS"
+  );
+  const command = { commandBody, subcommands };
   const skillFiles = skillFilesFor(adapter, {
     version: opts.version,
     scope: opts.scope,
     skillBody,
-    commandPrefix: "/jig "
+    commandPrefix: "/jig ",
+    ...command
   });
   for (const file of skillFiles) {
     const key = file.relPath;
-    const abs = join3(installRoot, ...key.split("/"));
+    const abs = join7(installRoot, ...key.split("/"));
     const isBlockFile = file.content.includes(BLOCK_START);
-    const content = isBlockFile && existsSync3(abs) ? upsertBlock(readFileSync2(abs, "utf8"), file.content) : file.content;
+    const content = isBlockFile && existsSync5(abs) ? upsertBlock(readFileSync4(abs, "utf8"), file.content) : file.content;
     planned.push({ key, content, checkable: !isBlockFile });
   }
-  const files = {};
+  const writer = createWriter(installRoot);
+  const files = writer.files;
   const written = [];
   const skipped = [];
   for (const { key, content, checkable } of planned) {
@@ -411,7 +641,7 @@ function install(opts) {
       if (recorded) files[key] = recorded;
       continue;
     }
-    writeFile(installRoot, key, content, files);
+    writer.write(key, content);
     written.push(key);
   }
   const manifest = {
@@ -421,118 +651,291 @@ function install(opts) {
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     files
   };
-  writeManifest(installRoot, manifest);
-  written.push(relKey(".jig", "manifest.json"));
+  writeManifest(installRoot, manifest, referenceDir);
+  written.push(relKey(referenceDir, "manifest.json"));
   return { written, skipped };
 }
 
 // src/commands/update.ts
-import { basename, dirname as dirname5, join as join5 } from "path";
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, readdirSync as readdirSync2, writeFileSync as writeFileSync4 } from "fs";
+import { join as join10 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
 
 // src/install/target.ts
 import { resolve } from "path";
-function resolveInstalled(projectRoot, homeDir) {
-  const projectManifest = readManifest(projectRoot);
-  const existing = projectManifest ?? readManifest(homeDir);
-  if (!existing) return null;
+function resolveAllInstalled(projectRoot, homeDir) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
   const sameRoot = resolve(projectRoot) === resolve(homeDir);
-  const scope = !projectManifest ? "global" : sameRoot ? existing.scope : "project";
-  const installRoot = scope === "global" ? homeDir : projectRoot;
-  return { installRoot, scope, manifest: existing };
+  for (const adapter of ADAPTERS) {
+    const referenceDir = referenceDirFor(adapter, "project");
+    const manifest = readManifest(projectRoot, referenceDir);
+    if (manifest && manifest.agent !== adapter.name) {
+      getAdapter(manifest.agent);
+    }
+    if (manifest && manifest.agent === adapter.name) {
+      const collides = sameRoot && referenceDirFor(adapter, "global") === referenceDir;
+      const scope = collides ? manifest.scope : "project";
+      const installRoot = scope === "global" ? homeDir : projectRoot;
+      const key = `${resolve(installRoot)}\0${referenceDir}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        found.push({ installRoot, scope, manifest, referenceDir });
+      }
+    }
+  }
+  for (const adapter of ADAPTERS) {
+    const referenceDir = referenceDirFor(adapter, "global");
+    const manifest = readManifest(homeDir, referenceDir);
+    if (manifest && manifest.agent !== adapter.name) {
+      getAdapter(manifest.agent);
+    }
+    if (manifest && manifest.agent === adapter.name) {
+      const key = `${resolve(homeDir)}\0${referenceDir}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        found.push({ installRoot: homeDir, scope: "global", manifest, referenceDir });
+      }
+    }
+  }
+  return found;
 }
 
 // src/init/state.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname4, join as join4 } from "path";
-var INIT_MANIFEST_REL = join4(".jig", "init-manifest.json");
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync5 } from "fs";
+import { dirname as dirname5, join as join8 } from "path";
+var INIT_MANIFEST_REL = join8(".jig", "state.json");
 function readInitManifest(projectRoot) {
-  const path = join4(projectRoot, INIT_MANIFEST_REL);
-  if (!existsSync4(path)) return null;
+  const path = join8(projectRoot, INIT_MANIFEST_REL);
+  if (!existsSync6(path)) return null;
   try {
-    const raw = JSON.parse(readFileSync3(path, "utf8"));
+    const raw = JSON.parse(readFileSync5(path, "utf8"));
     if (typeof raw !== "object" || raw === null) return null;
-    const files = raw.files;
+    const { files, version: version2, modes } = raw;
     if (typeof files !== "object" || files === null) return null;
-    return { files };
+    return {
+      files,
+      version: typeof version2 === "string" ? version2 : void 0,
+      modes: Array.isArray(modes) && modes.every((m) => typeof m === "string") ? modes : void 0
+    };
   } catch {
     return null;
   }
 }
+var MERGE_ATTEMPTS2 = 5;
 function writeInitManifest(projectRoot, m) {
-  const path = join4(projectRoot, INIT_MANIFEST_REL);
-  mkdirSync3(dirname4(path), { recursive: true });
-  writeFileSync3(path, `${JSON.stringify(m, null, 2)}
-`, "utf8");
+  const path = join8(projectRoot, INIT_MANIFEST_REL);
+  mkdirSync4(dirname5(path), { recursive: true });
+  for (let attempt = 0; attempt < MERGE_ATTEMPTS2; attempt++) {
+    const onDisk = readInitManifest(projectRoot);
+    const merged = {
+      ...m,
+      modes: [.../* @__PURE__ */ new Set([...onDisk?.modes ?? [], ...m.modes ?? []])],
+      files: { ...onDisk?.files ?? {}, ...m.files }
+    };
+    writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}
+`);
+    const after = readInitManifest(projectRoot);
+    if (after && Object.keys(merged.files).every((k) => k in after.files)) return;
+  }
 }
 function isInitFileModified(projectRoot, relPath, m) {
   const asManifest = { version: "", agent: "", scope: "project", installedAt: "", files: m.files };
   return isModified(projectRoot, relPath, asManifest);
 }
 
+// src/init/migrate.ts
+import { existsSync as existsSync7, readFileSync as readFileSync6, readdirSync as readdirSync3, rmSync } from "fs";
+import { join as join9 } from "path";
+var LEGACY_RULE_RE = /^\d{2}-.*\.md$/;
+function isLegacyInstallArtifact(name) {
+  return LEGACY_RULE_RE.test(name) || name === "rules.index.json" || name === "LICENSE" || name === "NOTICE" || name === "manifest.json";
+}
+function readLegacyManifest(dirAbs) {
+  try {
+    const raw = JSON.parse(readFileSync6(join9(dirAbs, "manifest.json"), "utf8"));
+    if (raw && typeof raw === "object" && typeof raw.files === "object") {
+      return raw;
+    }
+  } catch {
+  }
+  return null;
+}
+function classify(projectRoot, relPath, legacyManifest) {
+  return legacyManifest && relPath in legacyManifest.files ? isModified(projectRoot, relPath, legacyManifest) : "unknown";
+}
+function detectLegacyRules(projectRoot) {
+  const jigDir = join9(projectRoot, ".jig");
+  if (!existsSync7(jigDir)) return { present: false, files: [] };
+  const legacyManifest = readLegacyManifest(jigDir);
+  let entries;
+  try {
+    entries = readdirSync3(jigDir);
+  } catch {
+    entries = [];
+  }
+  const files = entries.filter(isLegacyInstallArtifact).sort().map((name) => {
+    const relPath = `.jig/${name}`;
+    return { relPath, modified: classify(projectRoot, relPath, legacyManifest) };
+  });
+  return { present: files.length > 0, files };
+}
+function detectLegacyCursorRules(projectRoot) {
+  const bundleDirRel = ".cursor/rules/jig";
+  const bundleDir = join9(projectRoot, ...bundleDirRel.split("/"));
+  const mdcRel = ".cursor/rules/jig.mdc";
+  const mdcAbs = join9(projectRoot, ...mdcRel.split("/"));
+  const legacyManifest = readLegacyManifest(bundleDir);
+  const files = [];
+  if (existsSync7(mdcAbs)) {
+    files.push({ relPath: mdcRel, modified: classify(projectRoot, mdcRel, legacyManifest) });
+  }
+  let entries;
+  try {
+    entries = readdirSync3(bundleDir);
+  } catch {
+    entries = [];
+  }
+  for (const name of entries.filter(isLegacyInstallArtifact).sort()) {
+    const relPath = `${bundleDirRel}/${name}`;
+    files.push({ relPath, modified: classify(projectRoot, relPath, legacyManifest) });
+  }
+  return { present: files.length > 0, files };
+}
+function describeLegacyFiles(report, headerLine, subheaderLine) {
+  if (!report.present) return [];
+  const lines = [];
+  lines.push(`
+${headerLine}`);
+  lines.push(subheaderLine);
+  for (const f of report.files) lines.push(`    ${f.relPath}`);
+  const edited = report.files.filter((f) => f.modified === true).map((f) => f.relPath);
+  const unknown = report.files.filter((f) => f.modified === "unknown").map((f) => f.relPath);
+  if (edited.length) {
+    lines.push("  Edited since install \u2014 kept, never removed automatically:");
+    for (const relPath of edited) lines.push(`    ${relPath}`);
+  }
+  if (unknown.length) {
+    lines.push("  No install record to verify against \u2014 kept; remove manually if you are sure they are untouched:");
+    for (const relPath of unknown) lines.push(`    ${relPath}`);
+  }
+  return lines;
+}
+function describeLegacyReport(report) {
+  return describeLegacyFiles(
+    report,
+    `Found a pre-0.4.0 Jig install in .jig/ (${report.files.length} file(s)). These are no longer used \u2014`,
+    "  since 0.4.0 the skill and its rules live in your agent's skill directory, not the project:"
+  );
+}
+function describeLegacyCursorReport(report) {
+  return describeLegacyFiles(
+    report,
+    `Found a legacy Cursor install (${report.files.length} file(s)). Cursor's skill has moved \u2014`,
+    "  from .cursor/rules/jig.mdc to .cursor/skills/jig/SKILL.md; these are no longer read:"
+  );
+}
+function removableLegacyFiles(report) {
+  return report.files.filter((f) => f.modified === false).map((f) => f.relPath);
+}
+function removeLegacyFiles(projectRoot, relPaths) {
+  for (const relPath of relPaths) {
+    try {
+      rmSync(join9(projectRoot, ...relPath.split("/")), { force: true });
+    } catch {
+    }
+  }
+}
+
 // src/commands/update.ts
-var ALWAYS_REPLACE = [relKey(".jig", "LICENSE"), relKey(".jig", "NOTICE")];
 function update(opts) {
-  const resolved = resolveInstalled(opts.projectRoot, opts.homeDir);
-  if (!resolved) {
+  const resolved = resolveAllInstalled(opts.projectRoot, opts.homeDir);
+  if (resolved.length === 0) {
+    const legacy = detectLegacyRules(opts.projectRoot);
+    const hint = legacy.present ? ` A pre-0.4.0 bundle is still in .jig/ (${legacy.files.length} file(s)); since 0.4.0 the skill and its rules live beside your agent's skill file instead, so that copy is no longer read. Re-run install, then 'jig init' will report the leftovers \u2014 it never removes a file you have edited.` : "";
     throw new Error(
-      `Jig is not installed in ${opts.projectRoot}. Run 'jig install --agent <name>' first.`
+      `Jig is not installed in ${opts.projectRoot}. Run 'jig install --agent <name>' first.${hint}`
     );
   }
-  const { installRoot, scope: discoveredScope, manifest: existing } = resolved;
-  const adapter = getAdapter(existing.agent);
-  if (!adapter.supportsScope(discoveredScope)) {
-    throw new Error(
-      `Jig's manifest at ${installRoot} records agent '${existing.agent}', which does not support ${discoveredScope} scope. Re-run 'jig install --agent <name>' to fix it.`
-    );
+  const updated = [];
+  const skipped = [];
+  const targets = [];
+  for (const target of resolved) {
+    const one = updateTarget(opts, target);
+    updated.push(...one.updated);
+    skipped.push(...one.skipped);
+    targets.push({
+      agent: target.manifest.agent,
+      scope: target.scope,
+      referenceDir: target.referenceDir,
+      fromVersion: target.manifest.version
+    });
   }
+  const initResult = updateInitFiles(opts);
+  updated.push(...initResult.updated);
+  skipped.push(...initResult.skipped);
+  return {
+    updated,
+    skipped,
+    fromVersion: resolved[0].manifest.version,
+    toVersion: opts.version,
+    targets
+  };
+}
+function updateTarget(opts, resolved) {
+  const { installRoot, scope: discoveredScope, manifest: existing, referenceDir } = resolved;
+  const adapter = getAdapter(existing.agent);
   const updated = [];
   const skipped = [];
-  const files = { ...existing.files };
+  const writer = createWriter(installRoot, existing.files);
+  const files = writer.files;
   const write = (key, content) => {
-    const abs = join5(installRoot, ...key.split("/"));
-    mkdirSync4(dirname5(abs), { recursive: true });
-    writeFileSync4(abs, content, "utf8");
-    files[key] = checksum(content);
-    updated.push(key);
+    updated.push(writer.write(key, content));
   };
-  const rulesDir = join5(opts.packageRoot, "rules");
-  for (const file of readdirSync2(rulesDir).filter((f) => f.endsWith(".md")).sort()) {
-    const key = relKey(".jig", file);
+  const rulesDir = join10(opts.packageRoot, "rules");
+  for (const file of bundleFiles(opts.packageRoot, "rules")) {
+    const key = relKey(referenceDir, "rules", file);
     if (isModified(installRoot, key, existing)) {
       skipped.push(key);
       continue;
     }
-    write(key, vendorHeader(file, opts.version) + readFileSync4(join5(rulesDir, file), "utf8"));
+    write(key, vendorHeader(file, opts.version, "html", licencePathFor(`rules/${file}`)) + readFileSync7(join10(rulesDir, file), "utf8"));
   }
-  const tokensDir = join5(opts.packageRoot, "tokens");
-  for (const file of readdirSync2(tokensDir).filter((f) => f.endsWith(".css")).sort()) {
-    const key = relKey(".jig", "tokens", file);
+  for (const ref of referenceFiles(opts.packageRoot)) {
+    const key = relKey(referenceDir, ...ref.relPath.split("/"));
     if (isModified(installRoot, key, existing)) {
       skipped.push(key);
       continue;
     }
-    write(key, vendorHeader(file, opts.version, "css") + readFileSync4(join5(tokensDir, file), "utf8"));
+    write(key, vendorHeader(ref.relPath, opts.version, "html", licencePathFor(ref.relPath)) + ref.content);
   }
-  const indexKey = relKey(".jig", "rules.index.json");
+  const indexKey = relKey(referenceDir, "rules.index.json");
   if (isModified(installRoot, indexKey, existing)) {
     skipped.push(indexKey);
   } else {
-    write(indexKey, readFileSync4(join5(opts.packageRoot, "rules.index.json"), "utf8"));
-  }
-  const skillBody = buildSkillBody(opts.packageRoot, discoveredScope);
+    write(indexKey, readFileSync7(join10(opts.packageRoot, "rules.index.json"), "utf8"));
+  }
+  const rulesPath = rulesPathFor(referenceDir, discoveredScope);
+  const skillBody = buildSkillBody(opts.packageRoot, rulesPath, opts.version);
+  const { body: commandBody, subcommands } = buildCommandBody(
+    opts.packageRoot,
+    rulesPath,
+    opts.version,
+    adapter.argsPlaceholder ?? "$ARGUMENTS"
+  );
+  const command = { commandBody, subcommands };
   const skillFiles = skillFilesFor(adapter, {
     version: opts.version,
     scope: discoveredScope,
     skillBody,
-    commandPrefix: "/jig "
+    commandPrefix: "/jig ",
+    ...command
   });
   for (const file of skillFiles) {
     const key = file.relPath;
     const isBlockFile = file.content.includes(BLOCK_START);
     if (isBlockFile) {
-      const abs = join5(installRoot, ...key.split("/"));
-      const current = existsSync5(abs) ? readFileSync4(abs, "utf8") : "";
+      const abs = join10(installRoot, ...key.split("/"));
+      const current = existsSync8(abs) ? readFileSync7(abs, "utf8") : "";
       write(key, upsertBlock(current, file.content));
       continue;
     }
@@ -542,44 +945,88 @@ function update(opts) {
     }
     write(key, file.content);
   }
-  for (const key of ALWAYS_REPLACE) {
-    write(key, readFileSync4(join5(opts.packageRoot, basename(key)), "utf8"));
+  for (const src of ["LICENSE", "NOTICE"]) {
+    write(relKey(referenceDir, src), readFileSync7(join10(opts.packageRoot, src), "utf8"));
   }
+  const manifest = {
+    ...existing,
+    scope: discoveredScope,
+    version: opts.version,
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files
+  };
+  writeManifest(installRoot, manifest, referenceDir);
+  return { updated, skipped };
+}
+function updateInitFiles(opts) {
+  const updated = [];
+  const skipped = [];
+  const tokensDir = join10(opts.packageRoot, "tokens");
   const initManifest = readInitManifest(opts.projectRoot);
   if (initManifest) {
     const initFiles = { ...initManifest.files };
     let initChanged = false;
-    for (const file of readdirSync2(tokensDir).filter((f) => f.endsWith(".css")).sort()) {
+    const writer = createWriter(opts.projectRoot, initFiles);
+    for (const file of bundleFiles(opts.packageRoot, "tokens")) {
       const key = relKey(".jig", "tokens", file);
       if (!(key in initManifest.files)) continue;
       if (isInitFileModified(opts.projectRoot, key, initManifest)) {
         skipped.push(key);
         continue;
       }
-      const content = vendorHeader(file, opts.version, "css") + readFileSync4(join5(tokensDir, file), "utf8");
-      const abs = join5(opts.projectRoot, ...key.split("/"));
-      mkdirSync4(dirname5(abs), { recursive: true });
-      writeFileSync4(abs, content, "utf8");
-      initFiles[key] = checksum(content);
+      const content = vendorHeader(file, opts.version, "css", null) + readFileSync7(join10(tokensDir, file), "utf8");
+      updated.push(writer.write(key, content));
       initChanged = true;
-      updated.push(key);
     }
-    if (initChanged) writeInitManifest(opts.projectRoot, { files: initFiles });
+    Object.assign(initFiles, writer.files);
+    if (initChanged) writeInitManifest(opts.projectRoot, { ...initManifest, version: opts.version, files: initFiles });
   }
-  const manifest = {
-    ...existing,
-    scope: discoveredScope,
-    version: opts.version,
-    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    files
-  };
-  writeManifest(installRoot, manifest);
-  return { updated, skipped, fromVersion: existing.version, toVersion: opts.version };
+  return { updated, skipped };
 }
 
-// src/commands/check.ts
-import { readFileSync as readFileSync7 } from "fs";
-import { join as join9 } from "path";
+// src/commands/explain.ts
+import { join as join13 } from "path";
+
+// src/rules/load.ts
+import { readFileSync as readFileSync8, readdirSync as readdirSync4 } from "fs";
+import { join as join11 } from "path";
+
+// src/rules/parse.ts
+var HEADING = /^###\s+([A-Z])-(\d+)\s+(.+?)\s*$/;
+function parseRules(markdown, sourceFile) {
+  const lines = markdown.split("\n");
+  const rules = [];
+  let current = null;
+  const push = () => {
+    if (current) rules.push(current);
+  };
+  for (const line of lines) {
+    const heading = HEADING.exec(line);
+    if (heading) {
+      push();
+      const [, section, num, title] = heading;
+      const id = `${section}-${num}`;
+      current = {
+        id,
+        section,
+        number: Number(num),
+        title,
+        wrong: "",
+        correction: "",
+        source: `${sourceFile}#${id.toLowerCase()}`
+      };
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("\u274C") && !current.wrong) {
+      current.wrong = line.slice(1).trim();
+    } else if (line.startsWith("\u2705") && !current.correction) {
+      current.correction = line.slice(1).trim();
+    }
+  }
+  push();
+  return rules;
+}
 
 // src/rules/schema.ts
 var BUCKETS = ["mechanical", "judgment", "hybrid"];
@@ -612,10 +1059,183 @@ function validateIndex(entries) {
   });
 }
 
+// src/rules/load.ts
+function loadRules(rulesDir, indexPath) {
+  const files = readdirSync4(rulesDir).filter((f) => f.endsWith(".md")).sort();
+  const parsed = [];
+  for (const file of files) {
+    parsed.push(...parseRules(readFileSync8(join11(rulesDir, file), "utf8"), file));
+  }
+  const entries = validateIndex(JSON.parse(readFileSync8(indexPath, "utf8")));
+  const byId = new Map(entries.map((e) => [e.id, e]));
+  const missing = parsed.filter((r) => !byId.has(r.id)).map((r) => r.id);
+  if (missing.length) {
+    throw new Error(
+      `Rules present in markdown but missing from rules.index.json: ${missing.join(", ")}`
+    );
+  }
+  const parsedIds = new Set(parsed.map((r) => r.id));
+  const orphans = entries.filter((e) => !parsedIds.has(e.id)).map((e) => e.id);
+  if (orphans.length) {
+    throw new Error(
+      `Entries in rules.index.json with no matching rule: ${orphans.join(", ")}`
+    );
+  }
+  return parsed.map((r) => {
+    const { id: _id, ...meta } = byId.get(r.id);
+    return { ...r, ...meta };
+  });
+}
+
+// src/rules/specs.ts
+import { readFileSync as readFileSync9, readdirSync as readdirSync5 } from "fs";
+import { join as join12 } from "path";
+var HEADING2 = /^##\s+([PM]-\d+)\s*(?:·\s*)?(.*?)\s*$/;
+function parseSpecs(markdown, sourceFile) {
+  const lines = markdown.split("\n");
+  const specs = [];
+  let current = null;
+  const body = [];
+  const push = () => {
+    if (!current) return;
+    specs.push({ ...current, body: body.join("\n").replace(/\n{3,}/g, "\n\n").trim() });
+    body.length = 0;
+  };
+  for (const line of lines) {
+    const heading = HEADING2.exec(line);
+    if (heading) {
+      push();
+      const [, id, title] = heading;
+      current = { id, title, body: "", source: `${sourceFile}#${id.toLowerCase()}` };
+      continue;
+    }
+    if (current && /^##\s/.test(line)) {
+      push();
+      current = null;
+      continue;
+    }
+    if (current) body.push(line);
+  }
+  push();
+  return specs;
+}
+function loadSpecs(rulesDir) {
+  const specs = [];
+  for (const file of readdirSync5(rulesDir).filter((f) => f.endsWith(".md")).sort()) {
+    specs.push(...parseSpecs(readFileSync9(join12(rulesDir, file), "utf8"), file));
+  }
+  return specs;
+}
+
+// src/commands/explain.ts
+var ID_SHAPE = /^([A-Z])-?(\d+)$/;
+var SECTION_SHAPE = /^([A-Z])$/;
+var matches = (haystack, needle) => haystack.toLowerCase().includes(needle.toLowerCase());
+var byNumber = (a, b) => {
+  const [as, an] = a.split("-");
+  const [bs, bn] = b.split("-");
+  return as === bs ? Number(an) - Number(bn) : as.localeCompare(bs);
+};
+function renderRule(rule) {
+  return [
+    `${rule.id}  ${rule.title}`,
+    "",
+    `\u274C ${rule.wrong}`,
+    `\u2705 ${rule.correction}`,
+    "",
+    `   ${rule.bucket} \xB7 ${rule.severity}${rule.detector ? ` \xB7 detector: ${rule.detector}` : ""}`,
+    `   since ${rule.since} \xB7 ${rule.source}`
+  ].join("\n");
+}
+function renderSpec(spec) {
+  return [
+    `${spec.id}  ${spec.title}`,
+    "",
+    spec.body,
+    "",
+    `   specification \u2014 component anatomy and behaviour, not a single rule,`,
+    `   so it carries no \u274C/\u2705 pair and no detector.`,
+    `   ${spec.source}`
+  ].join("\n");
+}
+function explain(opts) {
+  const raw = opts.ruleId.trim().toUpperCase();
+  const root = opts.packageRoot ?? assetRoot();
+  const rulesDir = join13(root, "rules");
+  const rules = loadRules(rulesDir, join13(root, "rules.index.json"));
+  const specs = loadSpecs(rulesDir);
+  const entries = [
+    ...rules.map((r) => ({ id: r.id, title: r.title, text: `${r.wrong}
+${r.correction}` })),
+    ...specs.map((s) => ({ id: s.id, title: s.title, text: s.body }))
+  ];
+  if (opts.list) {
+    const section = SECTION_SHAPE.exec(raw)?.[1];
+    const shown = entries.filter((e) => !section || e.id.startsWith(`${section}-`)).sort((a, b) => byNumber(a.id, b.id));
+    if (shown.length === 0) {
+      throw new Error(`No section '${raw}'. Sections: ${sectionsOf(entries).join(", ")}.`);
+    }
+    return [
+      section ? `Section ${section} \u2014 ${shown.length} entries` : `${shown.length} rules and specs`,
+      "",
+      ...shown.map((e) => `${e.id.padEnd(6)} ${e.title}`)
+    ].join("\n");
+  }
+  const shape = ID_SHAPE.exec(raw);
+  if (shape) {
+    const id = `${shape[1]}-${shape[2]}`;
+    const rule = rules.find((r) => r.id === id);
+    if (rule) return renderRule(rule);
+    const spec = specs.find((s) => s.id === id);
+    if (spec) return renderSpec(spec);
+    const siblings = entries.filter((e) => e.id.startsWith(`${shape[1]}-`)).map((e) => e.id).sort(byNumber);
+    throw new Error(
+      siblings.length > 0 ? `No rule '${id}'. Section ${shape[1]} has: ${siblings.join(", ")}.` : `No rule '${id}', and no section '${shape[1]}' exists.`
+    );
+  }
+  if (raw === "") {
+    throw new Error(
+      `Nothing to explain. Give a rule id ('C-19'), a word to search for ('contrast'), or --list.`
+    );
+  }
+  const needle = opts.ruleId.trim();
+  const inTitle = entries.filter((e) => matches(e.title, needle) || matches(e.id, needle));
+  const inBody = entries.filter((e) => !inTitle.includes(e) && matches(e.text, needle));
+  const hits = [
+    ...inTitle.sort((a, b) => byNumber(a.id, b.id)),
+    ...inBody.sort((a, b) => byNumber(a.id, b.id))
+  ];
+  if (hits.length === 0) {
+    throw new Error(
+      `No rule matches '${needle}'. Try --list to see every id, or a broader word.`
+    );
+  }
+  if (hits.length === 1) {
+    const rule = rules.find((r) => r.id === hits[0].id);
+    return rule ? renderRule(rule) : renderSpec(specs.find((s) => s.id === hits[0].id));
+  }
+  return [
+    // Title matches lead, so the list is ranked rather than sorted. Say so:
+    // otherwise C-19 sitting above A-02 reads as a sorting bug.
+    `${hits.length} entries match '${needle}' \u2014 title matches first:`,
+    "",
+    ...hits.map((e) => `${e.id.padEnd(6)} ${e.title}`),
+    "",
+    `Run 'jig explain <id>' for any of them.`
+  ].join("\n");
+}
+function sectionsOf(entries) {
+  return [...new Set(entries.map((e) => e.id.split("-")[0]))].sort();
+}
+
+// src/commands/check.ts
+import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
+import { join as join17 } from "path";
+
 // src/check/files.ts
 import { execFileSync } from "child_process";
-import { readdirSync as readdirSync3 } from "fs";
-import { join as join6, relative, sep } from "path";
+import { readdirSync as readdirSync6, realpathSync, statSync } from "fs";
+import { join as join14, relative, sep } from "path";
 var EXCLUDE_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
   "dist",
@@ -671,19 +1291,38 @@ function gitChangedFiles(root) {
 function isExcluded(relPath) {
   return relPath.split("/").some((segment) => EXCLUDE_DIRS.has(segment));
 }
-function walk(root, dir, out) {
+function walk(root, dir, out, seen) {
   let entries;
   try {
-    entries = readdirSync3(dir, { withFileTypes: true });
+    entries = readdirSync6(dir, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
     if (EXCLUDE_DIRS.has(entry.name)) continue;
-    const abs = join6(dir, entry.name);
-    if (entry.isDirectory()) {
-      walk(root, abs, out);
-    } else if (entry.isFile()) {
+    const abs = join14(dir, entry.name);
+    let isDir = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        const target = statSync(abs);
+        isDir = target.isDirectory();
+        isFile = target.isFile();
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
+      let real;
+      try {
+        real = realpathSync(abs);
+      } catch {
+        continue;
+      }
+      if (seen.has(real)) continue;
+      seen.add(real);
+      walk(root, abs, out, seen);
+    } else if (isFile) {
       out.push(relative(root, abs).split(sep).join("/"));
     }
   }
@@ -712,9 +1351,16 @@ function filterGitIgnored(root, files) {
     return files;
   }
 }
+function safeRealpath(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
 function wholeRepoFiles(root) {
   const out = [];
-  walk(root, root, out);
+  walk(root, root, out, /* @__PURE__ */ new Set([safeRealpath(root)]));
   return isGitRepo(root) ? filterGitIgnored(root, out) : out;
 }
 function selectFiles(root, all) {
@@ -738,7 +1384,7 @@ function formatReport(findings, meta) {
     const loc = `${f.file}:${f.line}`;
     const firstOccurrence = !seenRule.has(f.ruleId);
     seenRule.add(f.ruleId);
-    const hint = firstOccurrence ? `  (see .jig/00-anti-patterns.md#${f.ruleId.toLowerCase()})` : "";
+    const hint = firstOccurrence ? `  (see rule ${f.ruleId} in your installed jig skill's rules/)` : "";
     return { symbol, ruleId: f.ruleId, message: f.message, loc, fileOnly: f.file, bucket: f.bucket, hint };
   });
   if (rows.length > 0) {
@@ -768,9 +1414,7 @@ function formatReport(findings, meta) {
     lines.push("");
     if (meta.noTokenLayer) {
       lines.push("  No file references a Jig token, so H-47 (hard-coded values) was not run.");
-      lines.push("  Import a brand and a mode file to bring your CSS under the token layer:");
-      lines.push('    @import ".jig/tokens/brand.default.css";');
-      lines.push('    @import ".jig/tokens/mode.product.css";');
+      lines.push("  Run 'jig init' to generate a brand file and wire it (with a mode file) into your CSS.");
       lines.push("");
     }
   }
@@ -781,16 +1425,28 @@ function formatReport(findings, meta) {
   if (warnings > 0) summaryParts.push(plural(warnings, "warning"));
   if (notes > 0) summaryParts.push(plural(notes, "note"));
   const rulesFired = new Set(findings.map((f) => f.ruleId)).size;
-  lines.push(`  ${summaryParts.join(", ")} \xB7 ${meta.totalRules} rules, ${rulesFired} fired`);
+  const scope = meta.totalSpecs ? `${meta.totalRules} rules (+ ${meta.totalSpecs} pattern and mode specs)` : `${meta.totalRules} rules`;
+  lines.push(`  ${summaryParts.join(", ")} \xB7 ${scope}, ${rulesFired} fired`);
+  if (meta.unscanned && meta.unscanned.count > 0) {
+    const exts = meta.unscanned.extensions.join(", ");
+    lines.push("");
+    lines.push(
+      `  ${meta.unscanned.count} file(s) were not scanned (${exts}) \u2014 no style extraction exists for them, so any CSS they carry is invisible to this check and a clean result above does not cover it.`
+    );
+  }
   const mechanicalErrors = findings.filter((f) => f.bucket === "mechanical" && f.severity === "error").length;
   const mechStatus = `${mechanicalErrors > 0 ? "fail" : "pass"}:${mechanicalErrors}`;
-  lines.push(`  JIG_CHECK: version=${meta.version} mechanical=${mechStatus} judgment=not-run`);
+  lines.push(
+    `  JIG_CHECK: version=${meta.version} mode=${meta.mode ?? "unknown"} mechanical=${mechStatus} judgment=not-run`
+  );
   return lines.join("\n");
 }
 
 // src/check/token-layer.ts
 var IMPORT_RE = /@import\s+(?:url\()?["']?[^"')]*\.jig\/tokens\/[^"')]+\.css["']?\)?/i;
 var VAR_RE = /var\(\s*--([\w-]+)/g;
+var THEME_DECL_RE = /@theme\b[^{]*\{([\s\S]*?)\}/gi;
+var CUSTOM_PROP_RE = /--([\w-]+)\s*:/g;
 function participatesInTokenLayer(source, tokens) {
   if (IMPORT_RE.test(source)) return true;
   VAR_RE.lastIndex = 0;
@@ -798,12 +1454,91 @@ function participatesInTokenLayer(source, tokens) {
   while (m = VAR_RE.exec(source)) {
     if (Object.prototype.hasOwnProperty.call(tokens, m[1])) return true;
   }
+  THEME_DECL_RE.lastIndex = 0;
+  let theme;
+  while (theme = THEME_DECL_RE.exec(source)) {
+    if (IMPORT_RE.test(theme[1])) return true;
+    CUSTOM_PROP_RE.lastIndex = 0;
+    let prop;
+    while (prop = CUSTOM_PROP_RE.exec(theme[1])) {
+      if (Object.prototype.hasOwnProperty.call(tokens, prop[1])) return true;
+    }
+  }
   return false;
 }
 
+// src/check/ext.ts
+var CSS_EXTENSIONS = [".css", ".scss", ".less"];
+function hasExtension(file, exts) {
+  const lower = file.toLowerCase();
+  return exts.some((e) => lower.endsWith(e));
+}
+var STYLE_HOST_EXTENSIONS = [
+  ".html",
+  ".htm",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".jsx",
+  ".tsx",
+  ".js",
+  ".ts",
+  ".mjs",
+  ".cjs",
+  ".mts",
+  ".cts",
+  ".php",
+  ".erb",
+  ".twig",
+  ".hbs",
+  ".mdx",
+  // Server-rendered markup. Every one of these is HTML with a template syntax
+  // threaded through it, so its `<style>` blocks and `style` attributes are the
+  // same constructs already handled — the template tags sit outside the style
+  // regions and are blanked with the rest of the markup.
+  ".asp",
+  ".aspx",
+  ".ascx",
+  ".master",
+  // Classic ASP, ASP.NET
+  ".cshtml",
+  ".vbhtml",
+  ".razor",
+  // Razor
+  ".jsp",
+  ".jspx",
+  // Java
+  ".eex",
+  ".heex",
+  ".leex",
+  // Phoenix
+  ".ejs",
+  ".njk",
+  ".liquid",
+  ".mustache",
+  // Node/Jinja-family engines
+  ".vm",
+  ".ftl",
+  // Velocity, FreeMarker
+  ".jinja",
+  ".jinja2",
+  ".j2",
+  // Jinja
+  // Indentation-delimited templates. These carry no HTML-shaped constructs at
+  // all — their style regions are found by their own block markers and
+  // attribute syntax instead. See `INDENTED_SYNTAXES` in styles.ts.
+  ".pug",
+  ".jade",
+  ".haml",
+  ".slim"
+];
+function isStyleBearing(file) {
+  return hasExtension(file, CSS_EXTENSIONS) || hasExtension(file, STYLE_HOST_EXTENSIONS);
+}
+
 // src/check/run.ts
-import { readFileSync as readFileSync5 } from "fs";
-import { join as join7 } from "path";
+import { readFileSync as readFileSync10 } from "fs";
+import { join as join15 } from "path";
 
 // src/check/css.ts
 function maskComments(source) {
@@ -852,7 +1587,12 @@ function splitRuleBlocks(source) {
     const ch = source[i];
     if (ch === "\n") line++;
     if (ch === "{") {
-      stack.push({ selectorStart: lastBoundary, bodyStart: i + 1, bodyStartLine: line });
+      stack.push({
+        selectorStart: lastBoundary,
+        bodyStart: i + 1,
+        bodyStartLine: line,
+        isAtRule: cleanSelector(source.slice(lastBoundary, i)).startsWith("@")
+      });
       lastBoundary = i + 1;
     } else if (ch === "}") {
       const top = stack.pop();
@@ -860,7 +1600,8 @@ function splitRuleBlocks(source) {
         blocks.push({
           selector: cleanSelector(source.slice(top.selectorStart, top.bodyStart - 1)),
           body: source.slice(top.bodyStart, i),
-          bodyStartLine: top.bodyStartLine
+          bodyStartLine: top.bodyStartLine,
+          atRuleDepth: stack.filter((f) => f.isAtRule).length
         });
       }
       lastBoundary = i + 1;
@@ -870,7 +1611,7 @@ function splitRuleBlocks(source) {
 }
 function blankNested(body) {
   const out = body.split("");
-  const blank = (from, to) => {
+  const blank2 = (from, to) => {
     for (let j = from; j < to; j++) if (out[j] !== "\n") out[j] = " ";
   };
   let depth = 0;
@@ -878,7 +1619,7 @@ function blankNested(body) {
   for (let i = 0; i < body.length; i++) {
     const ch = body[i];
     if (ch === "{") {
-      if (depth === 0) blank(segmentStart, i);
+      if (depth === 0) blank2(segmentStart, i);
       depth++;
       out[i] = " ";
     } else if (ch === "}") {
@@ -929,11 +1670,221 @@ function sourceLine(source, line) {
   return (lines[line - 1] ?? "").trim();
 }
 
-// src/check/ext.ts
-var CSS_EXTENSIONS = [".css", ".scss", ".less"];
-function hasExtension(file, exts) {
+// src/check/styles.ts
+function isStyleHost(file) {
+  return hasExtension(file, STYLE_HOST_EXTENSIONS);
+}
+function isMarkupHost(file) {
+  return hasExtension(file, MARKUP_HOSTS);
+}
+var MARKUP_HOSTS = [
+  ".html",
+  ".htm",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".php",
+  ".erb",
+  ".twig",
+  ".hbs",
+  ".mdx",
+  ".jsx",
+  ".tsx",
+  ".asp",
+  ".aspx",
+  ".ascx",
+  ".master",
+  ".cshtml",
+  ".vbhtml",
+  ".razor",
+  ".jsp",
+  ".jspx",
+  ".eex",
+  ".heex",
+  ".leex",
+  ".ejs",
+  ".njk",
+  ".liquid",
+  ".mustache",
+  ".vm",
+  ".ftl",
+  ".jinja",
+  ".jinja2",
+  ".j2"
+];
+var INDENTED_SYNTAXES = {
+  ".pug": { blockMarker: /^(\s*)style\.?\s*$/, attr: /\bstyle\s*=\s*(["'])([\s\S]*?)\1/g },
+  ".jade": { blockMarker: /^(\s*)style\.?\s*$/, attr: /\bstyle\s*=\s*(["'])([\s\S]*?)\1/g },
+  ".haml": {
+    blockMarker: /^(\s*)(?::css|%style)\s*$/,
+    attr: /(?::style\s*=>|\bstyle\s*:)\s*(["'])([\s\S]*?)\1/g
+  },
+  ".slim": {
+    blockMarker: /^(\s*)(?:css:|style:)\s*$/,
+    attr: /\bstyle\s*=\s*(["'])([\s\S]*?)\1/g
+  }
+};
+function indentedSyntaxFor(file) {
   const lower = file.toLowerCase();
-  return exts.some((e) => lower.endsWith(e));
+  const ext = Object.keys(INDENTED_SYNTAXES).find((e) => lower.endsWith(e));
+  return ext ? INDENTED_SYNTAXES[ext] : void 0;
+}
+function indentedSpans(source, syntax) {
+  const spans = [];
+  const lines = source.split("\n");
+  const offsets = [];
+  let at = 0;
+  for (const line of lines) {
+    offsets.push(at);
+    at += line.length + 1;
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const marker = syntax.blockMarker.exec(lines[i]);
+    if (!marker) continue;
+    const markerIndent = marker[1].length;
+    let end = i;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (lines[j].trim() === "") {
+        end = j;
+        continue;
+      }
+      const indent = lines[j].length - lines[j].trimStart().length;
+      if (indent <= markerIndent) break;
+      end = j;
+    }
+    if (end === i) continue;
+    const start = offsets[i + 1];
+    const last = offsets[end] + lines[end].length;
+    spans.push({ start, end: last });
+    i = end;
+  }
+  return spans;
+}
+var STYLE_BLOCK = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
+var STYLE_ATTR = /\bstyle\s*=\s*(["'])([\s\S]*?)\1/gi;
+var CSS_TAG = /\b(?:styled(?:\.\w+|\([^)]*\))(?:\s*\.\w+\([^)]*\))*|css|createGlobalStyle|keyframes|injectGlobal)\s*`/g;
+function readTemplate(source, openBacktick) {
+  let i = openBacktick + 1;
+  const start = i;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === "`") return { start, end: i };
+    if (ch === "$" && source[i + 1] === "{") {
+      let depth = 1;
+      i += 2;
+      while (i < source.length && depth > 0) {
+        if (source[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (source[i] === "{") depth++;
+        else if (source[i] === "}") depth--;
+        else if (source[i] === "`") {
+          const inner = readTemplate(source, i);
+          if (!inner) return null;
+          i = inner.end;
+        }
+        i++;
+      }
+      continue;
+    }
+    i++;
+  }
+  return null;
+}
+var STYLE_OBJECT = /\bstyle\s*=\s*\{\{/g;
+function readObject(source, open) {
+  let depth = 0;
+  let i = open + 1;
+  const start = open + 2;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      i++;
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === "\\") i++;
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return { start, end: i };
+    }
+    i++;
+  }
+  return null;
+}
+function styleObjectToCss(body) {
+  let out = "";
+  for (const ch of body) {
+    if (ch === '"' || ch === "'" || ch === "`") out += " ";
+    else if (ch === ",") out += ";";
+    else out += ch;
+  }
+  return out;
+}
+function maskNonStyleRegions(source, file) {
+  if (hasExtension(file, CSS_EXTENSIONS)) return source;
+  if (!isStyleHost(file)) return blank(source);
+  const spans = [];
+  const indented = indentedSyntaxFor(file);
+  if (indented) {
+    spans.push(...indentedSpans(source, indented));
+    for (const m of source.matchAll(indented.attr)) {
+      const valueStart = m.index + m[0].indexOf(m[1]) + 1;
+      spans.push({ start: valueStart, end: valueStart + m[2].length, braced: true });
+    }
+    return applySpans(source, spans);
+  }
+  if (hasExtension(file, MARKUP_HOSTS)) {
+    for (const m of source.matchAll(STYLE_BLOCK)) {
+      const bodyStart = m.index + m[0].indexOf(">") + 1;
+      spans.push({ start: bodyStart, end: bodyStart + m[1].length });
+    }
+    for (const m of source.matchAll(STYLE_ATTR)) {
+      const valueStart = m.index + m[0].indexOf(m[1]) + 1;
+      spans.push({ start: valueStart, end: valueStart + m[2].length, braced: true });
+    }
+  }
+  for (const m of source.matchAll(CSS_TAG)) {
+    const backtick = m.index + m[0].length - 1;
+    const span = readTemplate(source, backtick);
+    if (span) spans.push({ ...span, braced: true });
+  }
+  for (const m of source.matchAll(STYLE_OBJECT)) {
+    const span = readObject(source, m.index + m[0].length - 2);
+    if (span) spans.push({ ...span, transform: styleObjectToCss, braced: true });
+  }
+  return applySpans(source, spans);
+}
+function applySpans(source, spans) {
+  if (spans.length === 0) return blank(source);
+  const out = blank(source).split("");
+  for (const span of spans) {
+    const text = source.slice(span.start, span.end);
+    const rendered = span.transform ? span.transform(text) : text;
+    for (let i = 0; i < rendered.length; i++) {
+      out[span.start + i] = rendered[i];
+    }
+    if (span.braced && span.start > 0 && span.end < out.length) {
+      out[span.start - 1] = "{";
+      out[span.end] = "}";
+    }
+  }
+  return out.join("");
+}
+function blank(source) {
+  let out = "";
+  for (const ch of source) out += ch === "\n" ? "\n" : " ";
+  return out;
 }
 
 // src/check/finding.ts
@@ -955,7 +1906,7 @@ var CLIP_RE = /(?:-webkit-)?background-clip\s*:\s*text\b/i;
 var GRADIENT_RE = /(?:background|background-image)\s*:[^;]*(?:linear|radial|conic)-gradient\s*\(/i;
 var gradientText = {
   name: "gradient-text",
-  appliesTo: (file) => hasExtension(file, CSS_EXTENSIONS),
+  appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
     const findings = [];
     for (const block of leafBlocks(source)) {
@@ -1184,7 +2135,7 @@ function hasTranslucentBackground(body, tokens) {
 }
 var backdropBlur = {
   name: "backdrop-blur",
-  appliesTo: (file) => hasExtension(file, CSS_EXTENSIONS),
+  appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
     const findings = [];
     for (const block of leafBlocks(source)) {
@@ -1215,7 +2166,7 @@ function isPure(rgb, target) {
 }
 var pureBlackWhite = {
   name: "pure-black-white",
-  appliesTo: (file) => hasExtension(file, CSS_EXTENSIONS),
+  appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
     const findings = [];
     for (const block of leafBlocks(source)) {
@@ -1250,6 +2201,104 @@ var pureBlackWhite = {
   }
 };
 
+// src/check/tailwind.ts
+var CLASS_ATTR = /\b(?:class|className)\s*=\s*/g;
+function readBraced(source, open) {
+  let depth = 0;
+  for (let i = open; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      i++;
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === "\\") i++;
+        i++;
+      }
+      continue;
+    }
+    if (ch === "{") depth++;
+    else if (ch === "}" && --depth === 0) return source.slice(open + 1, i);
+  }
+  return null;
+}
+function classAttributeValues(source) {
+  const out = [];
+  const lineAt = (offset) => source.slice(0, offset).split("\n").length;
+  for (const m of source.matchAll(CLASS_ATTR)) {
+    const at = m.index + m[0].length;
+    const opener = source[at];
+    if (opener === '"' || opener === "'") {
+      const end = source.indexOf(opener, at + 1);
+      if (end !== -1) out.push({ classes: source.slice(at + 1, end), line: lineAt(at) });
+      continue;
+    }
+    if (opener !== "{") continue;
+    const raw = readBraced(source, at);
+    if (raw === null) continue;
+    const literals = [...raw.matchAll(/(["'`])([\s\S]*?)\1/g)].map(
+      (q) => q[2].replace(/\$\{[\s\S]*?\}/g, " ")
+    );
+    if (literals.length > 0) out.push({ classes: literals.join(" ").trim(), line: lineAt(at) });
+  }
+  return out;
+}
+var ARBITRARY = /(?:^|\s)(?:[\w-]+:)*([a-z][\w-]*)-\[([^\]\s]+)\]/gi;
+var COLOUR = /^(?:#[0-9a-f]{3,8}|(?:rgba?|hsla?|oklch|oklab|lab|lch|color)\()/i;
+var LENGTH = /^-?\d*\.?\d+(?:px|rem|em|pt|vh|vw|vmin|vmax|ch|ex)$/i;
+function arbitraryValues(classes) {
+  const out = [];
+  for (const m of classes.matchAll(ARBITRARY)) {
+    const [, utility, rawValue] = m;
+    const value = rawValue.replace(/_/g, " ");
+    if (/var\(|--/.test(value)) continue;
+    if (COLOUR.test(value)) out.push({ utility, value, kind: "colour" });
+    else if (LENGTH.test(value)) out.push({ utility, value, kind: "length" });
+  }
+  return out;
+}
+var PALETTE = {
+  white: "#ffffff",
+  black: "#000000",
+  "gray-50": "#f9fafb",
+  "gray-100": "#f3f4f6",
+  "gray-200": "#e5e7eb",
+  "gray-300": "#d1d5db",
+  "gray-400": "#9ca3af",
+  "gray-500": "#6b7280",
+  "gray-600": "#4b5563",
+  "gray-700": "#374151",
+  "gray-800": "#1f2937",
+  "gray-900": "#111827",
+  "gray-950": "#030712",
+  "slate-50": "#f8fafc",
+  "slate-400": "#94a3b8",
+  "slate-500": "#64748b",
+  "slate-800": "#1e293b",
+  "slate-900": "#0f172a",
+  "slate-950": "#020617",
+  "zinc-400": "#a1a1aa",
+  "zinc-500": "#71717a",
+  "zinc-900": "#18181b",
+  "neutral-400": "#a3a3a3",
+  "neutral-500": "#737373",
+  "neutral-900": "#171717",
+  "stone-400": "#a8a29e",
+  "stone-500": "#78716c",
+  "stone-900": "#1c1917"
+};
+function palettePairs(classes) {
+  let background;
+  let foreground;
+  for (const token of classes.split(/\s+/)) {
+    const bare = token.replace(/^(?:[\w-]+:)*/, "");
+    const bg = /^bg-(.+)$/.exec(bare);
+    const fg = /^text-(.+)$/.exec(bare);
+    if (bg && PALETTE[bg[1]]) background = PALETTE[bg[1]];
+    if (fg && PALETTE[fg[1]]) foreground = PALETTE[fg[1]];
+  }
+  return background && foreground ? [{ background, foreground }] : [];
+}
+
 // src/check/detectors/contrast-floor.ts
 var FLOOR = 4.5;
 var LARGE_FLOOR = 3;
@@ -1274,7 +2323,7 @@ function resolveFloor(body) {
 var DECL_RE = /(?<![-\w])(color|background(?:-color)?)\s*:\s*([^;]+)(?:;|$)/gi;
 var contrastFloor = {
   name: "contrast-floor",
-  appliesTo: (file) => hasExtension(file, CSS_EXTENSIONS),
+  appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
     const findings = [];
     for (const block of leafBlocks(source)) {
@@ -1311,6 +2360,25 @@ var contrastFloor = {
         )
       );
     }
+    for (const attr of isMarkupHost(file) ? classAttributeValues(ctx.raw) : []) {
+      for (const pair of palettePairs(attr.classes)) {
+        const fg = resolveOpaqueColor(pair.foreground, ctx.tokens);
+        const bg = resolveOpaqueColor(pair.background, ctx.tokens);
+        if (!fg || !bg) continue;
+        const ratio = contrastRatio(fg, bg);
+        if (ratio >= 4.5) continue;
+        findings.push(
+          mkFinding(
+            ctx,
+            "contrast-floor",
+            file,
+            attr.line,
+            `Foreground/background contrast is ${ratio.toFixed(2)}:1, below the 4.5:1 floor (${pair.foreground} on ${pair.background})`,
+            sourceLine(ctx.raw, attr.line)
+          )
+        );
+      }
+    }
     return findings;
   }
 };
@@ -1320,7 +2388,7 @@ var OUTLINE_NONE_RE = /(?<![-\w])outline\s*:\s*(none|0(?:px)?)\s*(?:!important)?
 var FOCUS_VISIBLE_RE = /:focus-visible\b/i;
 var focusRemoved = {
   name: "focus-removed",
-  appliesTo: (file) => hasExtension(file, CSS_EXTENSIONS),
+  appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
     if (FOCUS_VISIBLE_RE.test(source)) return [];
     const findings = [];
@@ -1381,9 +2449,10 @@ var EXCLUDED_PX = /* @__PURE__ */ new Set([0, 1, 2]);
 var KEYFRAME_STEP_RE = /^(from|to|\d+(\.\d+)?%)$/i;
 var hardcodedValue = {
   name: "hardcoded-value",
-  appliesTo: (file) => hasExtension(file, CSS_EXTENSIONS),
+  appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
-    if (!participatesInTokenLayer(source, ctx.tokens)) return [];
+    const participates = isStyleHost(file) ? ctx.projectParticipates : participatesInTokenLayer(source, ctx.tokens);
+    if (!participates) return [];
     const findings = [];
     for (const block of leafBlocks(source)) {
       if (KEYFRAME_STEP_RE.test(block.selector.trim())) continue;
@@ -1433,6 +2502,20 @@ var hardcodedValue = {
         }
       }
     }
+    for (const attr of isMarkupHost(file) ? classAttributeValues(ctx.raw) : []) {
+      for (const found of arbitraryValues(attr.classes)) {
+        findings.push(
+          mkFinding(
+            ctx,
+            "hardcoded-value",
+            file,
+            attr.line,
+            found.kind === "colour" ? `Hard-coded colour \`${found.value}\` past the token layer (${found.utility}-[\u2026])` : `Hard-coded \`${found.value}\` past the token layer (${found.utility}-[\u2026])`,
+            attr.classes.length > 80 ? `${attr.classes.slice(0, 77)}\u2026` : attr.classes
+          )
+        );
+      }
+    }
     return findings;
   }
 };
@@ -1446,7 +2529,7 @@ var MIN_LIGHTNESS = 8;
 var MAX_LIGHTNESS = 92;
 var violetBandHue = {
   name: "violet-band-hue",
-  appliesTo: (file) => hasExtension(file, CSS_EXTENSIONS),
+  appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
     const findings = [];
     const starts = buildLineIndex(source);
@@ -1489,7 +2572,7 @@ function getDetector(name) {
 }
 
 // src/check/run.ts
-function runChecks(projectRoot, files, index, tokens, bucketFilter) {
+function runChecks(projectRoot, files, index, tokens, bucketFilter, projectParticipates = false) {
   const findings = [];
   const active = index.filter(
     (e) => !!e.detector && !!getDetector(e.detector)
@@ -1501,13 +2584,13 @@ function runChecks(projectRoot, files, index, tokens, bucketFilter) {
     if (applicable.length === 0) continue;
     let raw;
     try {
-      raw = readFileSync5(join7(projectRoot, file), "utf8");
+      raw = readFileSync10(join15(projectRoot, file), "utf8");
     } catch {
       continue;
     }
-    const source = maskComments(raw);
+    const source = maskComments(maskNonStyleRegions(raw, file));
     for (const { entry, detector } of applicable) {
-      const ctx = { ruleId: entry.id, bucket: entry.bucket, severity: entry.severity, tokens };
+      const ctx = { ruleId: entry.id, bucket: entry.bucket, severity: entry.severity, tokens, projectParticipates, raw };
       findings.push(...detector.run(source, file, ctx));
     }
   }
@@ -1515,40 +2598,101 @@ function runChecks(projectRoot, files, index, tokens, bucketFilter) {
 }
 
 // src/check/tokens.ts
-import { existsSync as existsSync6, readdirSync as readdirSync4, readFileSync as readFileSync6 } from "fs";
-import { join as join8 } from "path";
-function loadTokenMap(installRoot) {
-  const tokensDir = join8(installRoot, ".jig", "tokens");
-  const tokens = {};
-  if (!existsSync6(tokensDir)) return tokens;
-  const files = readdirSync4(tokensDir).filter((f) => f.endsWith(".css")).sort();
-  for (const file of files) {
-    const source = readFileSync6(join8(tokensDir, file), "utf8");
-    for (const block of splitRuleBlocks(source)) {
-      if (block.body.includes("{")) continue;
-      if (block.selector.trim() !== ":root") continue;
-      const re = /--([\w-]+)\s*:\s*([^;]+);/g;
-      let m;
-      while (m = re.exec(block.body)) {
-        tokens[m[1]] = m[2].trim();
-      }
+import { existsSync as existsSync9, readdirSync as readdirSync7, readFileSync as readFileSync11 } from "fs";
+import { join as join16 } from "path";
+function rootDeclarations(source) {
+  const out = {};
+  for (const block of splitRuleBlocks(source)) {
+    if (block.atRuleDepth !== 0) continue;
+    if (block.body.includes("{")) continue;
+    if (block.selector.trim() !== ":root") continue;
+    const re = /--([\w-]+)\s*:\s*([^;]+);/g;
+    let m;
+    while (m = re.exec(block.body)) out[m[1]] = m[2].trim();
+  }
+  return out;
+}
+function loadTokenMap(projectRoot, consumerFiles = []) {
+  const jig = {};
+  const tokensDir = join16(projectRoot, ".jig", "tokens");
+  if (existsSync9(tokensDir)) {
+    for (const file of readdirSync7(tokensDir).filter((f) => f.endsWith(".css")).sort()) {
+      Object.assign(jig, rootDeclarations(readFileSync11(join16(tokensDir, file), "utf8")));
     }
   }
+  const consumer = {};
+  const ambiguous = /* @__PURE__ */ new Set();
+  const vendored = join16(".jig", "tokens");
+  for (const file of consumerFiles) {
+    if (file.includes(vendored)) continue;
+    let source;
+    try {
+      source = readFileSync11(join16(projectRoot, file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const [name, value] of Object.entries(rootDeclarations(maskNonStyleRegions(source, file)))) {
+      if (name in consumer && consumer[name] !== value) ambiguous.add(name);
+      consumer[name] = value;
+    }
+  }
+  const tokens = { ...consumer };
+  for (const [name, value] of Object.entries(jig)) {
+    if (name in consumer && consumer[name] !== value) ambiguous.add(name);
+    tokens[name] = value;
+  }
+  for (const name of ambiguous) delete tokens[name];
   return tokens;
 }
 
 // src/commands/check.ts
+var LEGACY_INDEX_REL = join17(".jig", "rules.index.json");
+function resolveIndexPath(projectRoot) {
+  const legacy = join17(projectRoot, LEGACY_INDEX_REL);
+  if (existsSync10(legacy)) return legacy;
+  return join17(assetRoot(), "rules.index.json");
+}
+function resolveMode(projectRoot) {
+  try {
+    const config = JSON.parse(readFileSync12(join17(projectRoot, "jig.config.json"), "utf8"));
+    const modes = [...new Set((config.surfaces ?? []).map((s) => s.mode).filter(Boolean))];
+    if (modes.length === 1) return modes[0];
+    return modes.length > 1 ? "mixed" : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+var UNSUPPORTED_STYLE_HOSTS = [".elm", ".rs", ".templ", ".gohtml"];
+function summariseUnscanned(files) {
+  const hit = files.filter((f) => !isStyleBearing(f) && hasExtension(f, UNSUPPORTED_STYLE_HOSTS));
+  if (hit.length === 0) return void 0;
+  const extensions = [...new Set(hit.map((f) => f.slice(f.lastIndexOf(".")).toLowerCase()))].sort();
+  return { count: hit.length, extensions };
+}
+function countSpecs() {
+  try {
+    return loadSpecs(join17(assetRoot(), "rules")).length;
+  } catch {
+    return 0;
+  }
+}
 function check(opts) {
-  const target = resolveInstalled(opts.projectRoot, opts.homeDir);
-  if (!target) {
-    throw new Error(`Jig is not installed in ${opts.projectRoot}. Run 'jig install --agent <name>' first.`);
-  }
-  const indexPath = join9(target.installRoot, ".jig", "rules.index.json");
-  const index = validateIndex(JSON.parse(readFileSync7(indexPath, "utf8")));
-  const tokens = loadTokenMap(target.installRoot);
-  const { files } = selectFiles(opts.projectRoot, opts.all);
+  const indexPath = resolveIndexPath(opts.projectRoot);
+  const index = validateIndex(JSON.parse(readFileSync12(indexPath, "utf8")));
+  const selection = selectFiles(opts.projectRoot, opts.all);
+  const { files } = selection;
   const bucketFilter = opts.ci ? (b) => b === "mechanical" : void 0;
-  const findings = runChecks(opts.projectRoot, files, index, tokens, bucketFilter);
+  const stylesheets = selection.mode === "all" ? files : selectFiles(opts.projectRoot, true).files;
+  const tokens = loadTokenMap(opts.projectRoot, stylesheets);
+  const projectParticipates = stylesheets.some((f) => {
+    if (!hasExtension(f, CSS_EXTENSIONS)) return false;
+    try {
+      return participatesInTokenLayer(readFileSync12(join17(opts.projectRoot, f), "utf8"), tokens);
+    } catch {
+      return false;
+    }
+  });
+  const findings = runChecks(opts.projectRoot, files, index, tokens, bucketFilter, projectParticipates);
   const hasError = findings.some((f) => f.bucket === "mechanical" && f.severity === "error");
   const cssFiles = files.filter((f) => /\.(css|scss|less)$/i.test(f));
   const noTokenLayer = (
@@ -1556,7 +2700,7 @@ function check(opts) {
     // told to add a token @import it has nowhere to put.
     cssFiles.length > 0 && cssFiles.every((f) => {
       try {
-        return !participatesInTokenLayer(readFileSync7(join9(opts.projectRoot, f), "utf8"), tokens);
+        return !participatesInTokenLayer(readFileSync12(join17(opts.projectRoot, f), "utf8"), tokens);
       } catch {
         return true;
       }
@@ -1564,19 +2708,25 @@ function check(opts) {
   );
   const report = formatReport(findings, {
     totalRules: index.length,
+    // From the CLI's own bundle, like `explain` — the spec count describes the
+    // system, not whatever a project happens to have vendored. A legacy project
+    // copy may have no `rules/` directory at all.
+    totalSpecs: countSpecs(),
     version: opts.version,
-    noTokenLayer
+    noTokenLayer,
+    mode: resolveMode(opts.projectRoot),
+    unscanned: summariseUnscanned(files)
   });
   return { findings, report, hasError };
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync11, writeFileSync as writeFileSync5 } from "fs";
-import { dirname as dirname6, join as join13 } from "path";
+import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync16, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname6, join as join21 } from "path";
 
 // src/init/detect.ts
-import { readFileSync as readFileSync8 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync13 } from "fs";
+import { join as join18 } from "path";
 var TAILWIND_CONFIG_RE = /^tailwind\.config\.(js|ts|mjs|cjs)$/;
 var TAILWIND_V4_IMPORT_RE = /@import\s+["']tailwindcss["']/;
 var TAILWIND_V4_THEME_RE = /@theme\b/;
@@ -1593,7 +2743,7 @@ var FRAMEWORK_DEPS = [
 function detectFramework(projectRoot) {
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync8(join10(projectRoot, "package.json"), "utf8"));
+    pkg = JSON.parse(readFileSync13(join18(projectRoot, "package.json"), "utf8"));
   } catch {
     return void 0;
   }
@@ -1611,7 +2761,7 @@ function detect(projectRoot) {
   for (const f of cssFiles) {
     let source;
     try {
-      source = readFileSync8(join10(projectRoot, f), "utf8");
+      source = readFileSync13(join18(projectRoot, f), "utf8");
     } catch {
       continue;
     }
@@ -1628,9 +2778,26 @@ function detect(projectRoot) {
   return { cssSystem, cssFiles, tailwindConfigFile, tailwindV4EntryFile, framework: detectFramework(projectRoot) };
 }
 
+// src/init/gitignore.ts
+import { execFileSync as execFileSync2 } from "child_process";
+function isIgnored(projectRoot, relPath) {
+  const candidates = relPath.endsWith("/") ? [relPath] : [relPath, `${relPath}/`];
+  return candidates.some((path) => {
+    try {
+      execFileSync2("git", ["check-ignore", "-q", "--", path], {
+        cwd: projectRoot,
+        stdio: ["ignore", "ignore", "ignore"]
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
 // src/init/derive.ts
-import { readFileSync as readFileSync9 } from "fs";
-import { join as join11 } from "path";
+import { readFileSync as readFileSync14 } from "fs";
+import { join as join19 } from "path";
 var DEFAULT_PROPOSAL = {
   h: 264,
   s: 0,
@@ -1663,7 +2830,7 @@ function fromCssCustomProperties(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync9(join11(projectRoot, file), "utf8");
+      source = readFileSync14(join19(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -1712,7 +2879,7 @@ function balancedBraceBody(source, openIdx) {
 function fromTailwindConfig(projectRoot, tailwindConfigFile) {
   let source;
   try {
-    source = readFileSync9(join11(projectRoot, tailwindConfigFile), "utf8");
+    source = readFileSync14(join19(projectRoot, tailwindConfigFile), "utf8");
   } catch {
     return null;
   }
@@ -1768,7 +2935,7 @@ function fromLiteralFrequency(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync9(join11(projectRoot, file), "utf8");
+      source = readFileSync14(join19(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -1818,6 +2985,20 @@ function worstRatio(h, s, l) {
   const vsFill = contrastRatio(rgb, FILL_COMPOSITED);
   return { vsRaised, vsFill, worst: Math.min(vsRaised, vsFill) };
 }
+var DARK_BRAND_L = 88;
+var DARK_SURFACE_S = 6;
+var DARK_RAISED_L = 15;
+var DARK_BASE_L = 10;
+var DARK_FILL_ALPHA = 0.06;
+function darkWorstRatio(h, s) {
+  const brand = toRgb(h, s, DARK_BRAND_L);
+  const raised = toRgb(h, DARK_SURFACE_S, DARK_RAISED_L);
+  const base = toRgb(h, DARK_SURFACE_S, DARK_BASE_L);
+  const fill = compositeOver({ r: 255, g: 255, b: 255 }, DARK_FILL_ALPHA, base);
+  const vsRaised = contrastRatio(brand, raised);
+  const vsFill = contrastRatio(brand, fill);
+  return { vsRaised, vsFill, worst: Math.min(vsRaised, vsFill) };
+}
 function nearestPassingLightness(h, s, l) {
   if (worstRatio(h, s, l).worst >= CONTRAST_FLOOR) return l;
   for (let delta = 1; delta <= 100; delta++) {
@@ -1847,11 +3028,19 @@ function systemCollision(h, s, l) {
   return null;
 }
 function validateBrandColor(h, s, l) {
-  const { vsRaised, vsFill, worst } = worstRatio(h, s, l);
+  const light = worstRatio(h, s, l);
+  const dark = darkWorstRatio(h, s);
+  const worst = Math.min(light.worst, dark.worst);
   const passesContrast = worst >= CONTRAST_FLOOR;
   return {
-    ratioVsRaised: vsRaised,
-    ratioVsFill: vsFill,
+    ratioVsRaised: light.vsRaised,
+    ratioVsFill: light.vsFill,
+    lightRatioVsRaised: light.vsRaised,
+    lightRatioVsFill: light.vsFill,
+    lightWorstRatio: light.worst,
+    darkRatioVsRaised: dark.vsRaised,
+    darkRatioVsFill: dark.vsFill,
+    darkWorstRatio: dark.worst,
     worstRatio: worst,
     passesContrast,
     nearestPassingLightness: passesContrast ? void 0 : nearestPassingLightness(h, s, l) ?? void 0,
@@ -1868,7 +3057,7 @@ function round2(n) {
 }
 function renderBrandFile(defaultCssRaw, projectSlug, version2, proposal) {
   const fileName = `brand.${projectSlug}.css`;
-  const header = vendorHeader(fileName, version2, "css");
+  const header = vendorHeader(fileName, version2, "css", null);
   if (!defaultCssRaw.includes(TOP_COMMENT_FIRST_LINE) || !defaultCssRaw.includes(TOP_COMMENT_LAST_LINE)) {
     throw new Error(
       `brand-file: tokens/brand.default.css does not match the expected shape \u2014 ${TOP_COMMENT_FIRST_LINE} / ${TOP_COMMENT_LAST_LINE} not found.`
@@ -1906,8 +3095,8 @@ function relativeImportPath(fromAbsDir, toAbsFile) {
 }
 
 // src/init/project-name.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { basename as basename2, join as join12 } from "path";
+import { readFileSync as readFileSync15 } from "fs";
+import { basename, join as join20 } from "path";
 function slugify(name) {
   const withoutScope = name.replace(/^@[^/]+\//, "");
   const slug = withoutScope.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -1915,11 +3104,11 @@ function slugify(name) {
 }
 function deriveProjectSlug(projectRoot) {
   try {
-    const pkg = JSON.parse(readFileSync10(join12(projectRoot, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync15(join20(projectRoot, "package.json"), "utf8"));
     if (typeof pkg.name === "string" && pkg.name.trim()) return slugify(pkg.name);
   } catch {
   }
-  return slugify(basename2(projectRoot));
+  return slugify(basename(projectRoot));
 }
 
 // src/commands/init.ts
@@ -1939,13 +3128,15 @@ function validateRounded(p) {
 }
 function describeValidation(v) {
   const lines = [];
+  const modes = `light ${v.lightWorstRatio.toFixed(2)}:1, dark ${v.darkWorstRatio.toFixed(2)}:1`;
   if (v.passesContrast) {
     lines.push(
-      `  contrast OK \u2014 ${v.ratioVsRaised.toFixed(2)}:1 vs --color-bg-raised, ${v.ratioVsFill.toFixed(2)}:1 vs --color-fill (floor 4.5:1)`
+      `  contrast OK \u2014 ${modes} (floor 4.5:1; light is ${v.ratioVsRaised.toFixed(2)} vs --color-bg-raised and ${v.ratioVsFill.toFixed(2)} vs --color-fill)`
     );
   } else {
+    const failing = v.lightWorstRatio < v.darkWorstRatio ? "light" : "dark";
     lines.push(
-      `  contrast FAILS \u2014 worst is ${v.worstRatio.toFixed(2)}:1 against the 4.5:1 floor (${v.ratioVsRaised.toFixed(2)}:1 vs --color-bg-raised, ${v.ratioVsFill.toFixed(2)}:1 vs --color-fill)`
+      `  contrast FAILS in ${failing} mode \u2014 worst is ${v.worstRatio.toFixed(2)}:1 against the 4.5:1 floor (${modes})`
     );
     if (v.nearestPassingLightness !== void 0) {
       lines.push(`  nearest passing lightness at the same hue/saturation: ${v.nearestPassingLightness}%`);
@@ -1979,7 +3170,7 @@ function parseSurfaces(answer, fallback) {
   return parsed.length > 0 ? parsed : fallback;
 }
 function fileState(projectRoot, absPath, relPath, initManifest) {
-  const existsOnDisk = existsSync7(absPath);
+  const existsOnDisk = existsSync11(absPath);
   const tracked = !!initManifest && relPath in initManifest.files;
   const modified = tracked && isInitFileModified(projectRoot, relPath, initManifest);
   return { existsOnDisk, tracked, modified };
@@ -1990,11 +3181,11 @@ function isValidSurfaceArray(v) {
   );
 }
 function loadEffectiveConfig(projectRoot, configAbsPath, fallbackBrand, fallbackSurfaces) {
-  if (!existsSync7(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
+  if (!existsSync11(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
   try {
-    const parsed = JSON.parse(readFileSync11(configAbsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync16(configAbsPath, "utf8"));
     const brandCandidate = typeof parsed.brand === "string" && parsed.brand ? parsed.brand : void 0;
-    const brandResolves = brandCandidate ? existsSync7(join13(projectRoot, ...brandCandidate.split("/"))) : false;
+    const brandResolves = brandCandidate ? existsSync11(join21(projectRoot, ...brandCandidate.split("/"))) : false;
     return {
       brand: brandResolves ? brandCandidate : fallbackBrand,
       surfaces: isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : fallbackSurfaces
@@ -2020,7 +3211,7 @@ function insertAfterCharset(content, insertion) {
   return content.slice(0, charsetLen) + insertion + content.slice(charsetLen);
 }
 function wireImport(absPath, brandImport, modeImport, mode) {
-  const content = existsSync7(absPath) ? readFileSync11(absPath, "utf8") : "";
+  const content = existsSync11(absPath) ? readFileSync16(absPath, "utf8") : "";
   const brandImportLine = `@import "${brandImport}";`;
   const modeImportLine = `@import "${modeImport}";`;
   const brandPresent = content.includes(brandImportLine);
@@ -2033,7 +3224,7 @@ function wireImport(absPath, brandImport, modeImport, mode) {
       const previousMode = existingModeMatch[2];
       const next3 = content.slice(0, existingModeMatch.index) + `${modeImportLine}
 ` + content.slice(existingModeMatch.index + existingModeMatch[0].length);
-      writeFileSync5(absPath, next3, "utf8");
+      writeFileSync4(absPath, next3, "utf8");
       return { status: "rewired", detail: `rewired mode: ${previousMode} \u2192 ${mode}` };
     }
     const brandIdx = content.indexOf(brandImportLine);
@@ -2041,7 +3232,7 @@ function wireImport(absPath, brandImport, modeImport, mode) {
     if (content[insertAt] === "\r") insertAt++;
     if (content[insertAt] === "\n") insertAt++;
     const next2 = content.slice(0, insertAt) + modeImportLine + "\n" + content.slice(insertAt);
-    writeFileSync5(absPath, next2, "utf8");
+    writeFileSync4(absPath, next2, "utf8");
     return { status: "rewired", detail: `added missing mode import: ${mode}` };
   }
   const lines = `${brandImportLine}
@@ -2057,16 +3248,31 @@ ${modeImportLine}
 ` : lines);
   }
   mkdirSync5(dirname6(absPath), { recursive: true });
-  writeFileSync5(absPath, next, "utf8");
+  writeFileSync4(absPath, next, "utf8");
   return { status: "wired" };
 }
 async function init(opts) {
   const log = opts.log ?? ((line) => console.log(line));
   const prompt = opts.prompt ?? defaultPrompt;
-  const resolved = resolveInstalled(opts.projectRoot, opts.homeDir);
-  if (!resolved) {
-    throw new Error(`Jig is not installed in ${opts.projectRoot}. Run 'jig install --agent <name>' first.`);
-  }
+  const migrateLegacy = async (report, describe) => {
+    if (!report.present) return;
+    for (const line of describe(report)) log(line);
+    const removable = removableLegacyFiles(report);
+    if (removable.length === 0) return;
+    if (opts.yes) {
+      log("  Re-run without --yes to be prompted for removal, or delete them yourself.");
+      return;
+    }
+    const answer = (await prompt(`  Remove these ${removable.length} unedited legacy file(s)? [y/N]: `)).toLowerCase();
+    if (answer === "y" || answer === "yes") {
+      removeLegacyFiles(opts.projectRoot, removable);
+      log(`  Removed ${removable.length} file(s).`);
+    } else {
+      log("  Left them in place.");
+    }
+  };
+  await migrateLegacy(detectLegacyRules(opts.projectRoot), describeLegacyReport);
+  await migrateLegacy(detectLegacyCursorRules(opts.projectRoot), describeLegacyCursorReport);
   const detection = detect(opts.projectRoot);
   log(`Detected: ${detection.cssSystem}${detection.framework ? ` (${detection.framework})` : ""}`);
   if (detection.cssFiles.length === 0) {
@@ -2107,6 +3313,11 @@ async function init(opts) {
       );
     }
   }
+  if (opts.yes) {
+    log(
+      `Surface \u2192 mode: ${surfaces.map((s) => `'${s.match}' \u2192 ${s.mode}`).join(", ")} \u2014 the default, not inferred from this project. Mode sets density, type scale and control sizes, and it wins over an agent's own inference, so change it in jig.config.json if another mode fits (${MODES.join("/")}).`
+    );
+  }
   if (!validation.passesContrast && validation.nearestPassingLightness !== void 0) {
     const originalL = proposal.l;
     proposal = { ...proposal, l: validation.nearestPassingLightness };
@@ -2119,9 +3330,9 @@ Brand colour adjusted to clear the 4.5:1 contrast floor: l:${originalL}% \u2192
   const finalColor = { h: proposal.h, s: proposal.s, l: proposal.l };
   const projectSlug = deriveProjectSlug(opts.projectRoot);
   const brandRelPath = relKey(".jig", "tokens", brandFileName(projectSlug));
-  const brandAbsPath = join13(opts.projectRoot, ".jig", "tokens", brandFileName(projectSlug));
+  const brandAbsPath = join21(opts.projectRoot, ".jig", "tokens", brandFileName(projectSlug));
   const configRelPath = "jig.config.json";
-  const configAbsPath = join13(opts.projectRoot, configRelPath);
+  const configAbsPath = join21(opts.projectRoot, configRelPath);
   const initManifest = readInitManifest(opts.projectRoot);
   const files = { ...initManifest?.files ?? {} };
   const brandState = fileState(opts.projectRoot, brandAbsPath, brandRelPath, initManifest);
@@ -2150,68 +3361,72 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     if (configAction !== "written") log(`  ${configRelPath} exists and is not jig-tracked \u2014 leaving it alone (re-run without --yes to refresh).`);
   }
   if (brandAction === "written") {
-    const defaultCssRaw = readFileSync11(join13(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
+    const defaultCssRaw = readFileSync16(join21(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
     const content = renderBrandFile(defaultCssRaw, projectSlug, opts.version, proposal);
     mkdirSync5(dirname6(brandAbsPath), { recursive: true });
-    writeFileSync5(brandAbsPath, content, "utf8");
+    writeFileSync4(brandAbsPath, content, "utf8");
     files[brandRelPath] = checksum(content);
   }
   if (configAction === "written") {
     const config = { brand: brandRelPath, surfaces };
     const content = `${JSON.stringify(config, null, 2)}
 `;
-    writeFileSync5(configAbsPath, content, "utf8");
+    writeFileSync4(configAbsPath, content, "utf8");
     files[configRelPath] = checksum(content);
   } else if (configAction === "merged") {
     let existing = {};
     try {
-      existing = JSON.parse(readFileSync11(configAbsPath, "utf8"));
+      existing = JSON.parse(readFileSync16(configAbsPath, "utf8"));
     } catch {
       existing = {};
     }
     const existingBrand = typeof existing.brand === "string" ? existing.brand : void 0;
-    const brandStillResolves = existingBrand ? existsSync7(join13(opts.projectRoot, ...existingBrand.split("/"))) : false;
+    const brandStillResolves = existingBrand ? existsSync11(join21(opts.projectRoot, ...existingBrand.split("/"))) : false;
     const merged = {
       brand: brandStillResolves ? existingBrand : brandRelPath,
       surfaces: Array.isArray(existing.surfaces) && existing.surfaces.length > 0 ? existing.surfaces : surfaces
     };
     const content = `${JSON.stringify(merged, null, 2)}
 `;
-    writeFileSync5(configAbsPath, content, "utf8");
+    writeFileSync4(configAbsPath, content, "utf8");
     files[configRelPath] = checksum(content);
   }
   const effectiveConfig = loadEffectiveConfig(opts.projectRoot, configAbsPath, brandRelPath, surfaces);
   const primaryMode = effectiveConfig.surfaces[0]?.mode ?? "product";
-  const wiringBrandAbsPath = join13(opts.projectRoot, ...effectiveConfig.brand.split("/"));
-  const modeFileName = `mode.${primaryMode}.css`;
-  const modeAbsPath = join13(opts.projectRoot, ".jig", "tokens", modeFileName);
-  if (resolved.scope === "global") {
+  const wiringBrandAbsPath = join21(opts.projectRoot, ...effectiveConfig.brand.split("/"));
+  const declaredModes = [...new Set(effectiveConfig.surfaces.map((s) => s.mode))];
+  const modeAbsPaths = {};
+  for (const mode of declaredModes) {
+    const modeFileName = `mode.${mode}.css`;
+    const modeAbsPath2 = join21(opts.projectRoot, ".jig", "tokens", modeFileName);
+    modeAbsPaths[mode] = modeAbsPath2;
     const modeRelPath = relKey(".jig", "tokens", modeFileName);
-    const modeState = fileState(opts.projectRoot, modeAbsPath, modeRelPath, initManifest);
+    const modeState = fileState(opts.projectRoot, modeAbsPath2, modeRelPath, initManifest);
     let modeAction = "written";
     if (modeState.existsOnDisk && !modeState.tracked) modeAction = "skipped-untracked";
     else if (modeState.modified) modeAction = "skipped-edited";
     if (modeAction === "written") {
-      const modeSourceRaw = readFileSync11(join13(opts.packageRoot, "tokens", modeFileName), "utf8");
-      const content = vendorHeader(modeFileName, opts.version, "css") + modeSourceRaw;
-      mkdirSync5(dirname6(modeAbsPath), { recursive: true });
-      writeFileSync5(modeAbsPath, content, "utf8");
+      const modeSourceRaw = readFileSync16(join21(opts.packageRoot, "tokens", modeFileName), "utf8");
+      const content = vendorHeader(modeFileName, opts.version, "css", null) + modeSourceRaw;
+      mkdirSync5(dirname6(modeAbsPath2), { recursive: true });
+      writeFileSync4(modeAbsPath2, content, "utf8");
       files[modeRelPath] = checksum(content);
     } else {
       log(`  ${modeRelPath} exists and is not jig-tracked (or has been edited) \u2014 leaving it alone (re-run 'jig update' to refresh it).`);
     }
   }
-  writeInitManifest(opts.projectRoot, { files });
+  const modeAbsPath = modeAbsPaths[primaryMode];
+  writeInitManifest(opts.projectRoot, { version: opts.version, modes: declaredModes, files });
   const wireTarget = findWireTarget(detection);
   let wiring;
   if (wireTarget) {
-    const targetAbsDir = dirname6(join13(opts.projectRoot, wireTarget));
+    const targetAbsDir = dirname6(join21(opts.projectRoot, wireTarget));
     const brandImport = relativeImportPath(targetAbsDir, wiringBrandAbsPath);
     const modeImport = relativeImportPath(targetAbsDir, modeAbsPath);
     const snippet = `@import "${brandImport}";
 @import "${modeImport}";`;
     try {
-      const outcome = wireImport(join13(opts.projectRoot, wireTarget), brandImport, modeImport, primaryMode);
+      const outcome = wireImport(join21(opts.projectRoot, wireTarget), brandImport, modeImport, primaryMode);
       wiring = { target: wireTarget, status: outcome.status, snippet };
       const verb = outcome.status === "wired" ? "Wired" : outcome.status === "rewired" ? "Rewired" : "Already present in";
       log(`
@@ -2231,11 +3446,29 @@ Could not write to ${wireTarget}: ${err.message}`);
     const snippet = `@import "${brandImport}";
 @import "${modeImport}";`;
     wiring = { target: null, status: "print-only", snippet };
+    log("\nCould not find a single unambiguous stylesheet to wire the import into.");
+    const pasteTargets = detection.cssFiles.filter((f) => !isCssModule(f));
+    if (pasteTargets.length > 0) {
+      log("Paste the block for whichever of these is your global stylesheet:");
+      for (const target of pasteTargets) {
+        const dir = dirname6(join21(opts.projectRoot, target));
+        const forTarget = `@import "${relativeImportPath(dir, wiringBrandAbsPath)}";
+@import "${relativeImportPath(dir, modeAbsPath)}";`;
+        log(`
+  ${target}:`);
+        log(`    ${forTarget.split("\n").join("\n    ")}`);
+      }
+    } else {
+      log(
+        "Add this near the top of your global stylesheet. A CSS @import resolves relative to the file it sits in, so these project-root paths need a ../ per directory of depth:"
+      );
+      log(`  ${snippet.split("\n").join("\n  ")}`);
+    }
+  }
+  if (isIgnored(opts.projectRoot, ".jig")) {
     log(
-      `
-Could not find a single unambiguous stylesheet to wire the import into. Add this near the top of your global stylesheet (paths shown relative to the project root \u2014 adjust to wherever you paste them):`
+      "\n  WARNING: .jig/ is gitignored, but it holds this project's tokens \u2014 the files your stylesheet @imports. Committed, teammates and CI get the same design system; ignored, their builds break on a missing import. Remove the .jig/ rule from .gitignore, or commit the directory explicitly."
     );
-    log(`  ${snippet.split("\n").join("\n  ")}`);
   }
   const baselineResult = check({ projectRoot: opts.projectRoot, homeDir: opts.homeDir, version: opts.version, all: true, ci: false });
   log("\nBaseline:");
@@ -2259,7 +3492,13 @@ Could not find a single unambiguous stylesheet to wire the import into. Add this
 
 // src/index.ts
 var packageRoot = getPackageRoot();
-var { version } = JSON.parse(readFileSync12(join14(packageRoot, "package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync17(join22(packageRoot, "package.json"), "utf8"));
+function warnIfUnpublishedPin() {
+  if (isPublishedBuild(packageRoot)) return;
+  console.warn(
+    `Note: this is a source build, so the skill pins 'npx jig-ui@${version}' \u2014 a version that may not be published. Agents reading it will not be able to run the CLI until it is. Re-run install or update from a published build to correct the pin.`
+  );
+}
 var program = new Command();
 program.name("jig").description("A design system for coding agents.").version(version);
 program.command("install").description("Install Jig rules and the agent skill file into a repository.").requiredOption("--agent <name>", `target agent (${adapterNames().join(", ")})`).option("--scope <scope>", "project or global", "project").action((opts) => {
@@ -2277,7 +3516,12 @@ program.command("install").description("Install Jig rules and the agent skill fi
       version,
       homeDir: homedir()
     });
+    if (result.warning) {
+      console.warn(result.warning);
+      return;
+    }
     console.log(`Installed Jig v${version} for ${opts.agent} (${opts.scope} scope)`);
+    warnIfUnpublishedPin();
     for (const f of result.written) console.log(`  + ${f}`);
     for (const f of result.skipped) console.log(`  \xB7 ${f} (edited locally, left alone)`);
   } catch (err) {
@@ -2285,6 +3529,14 @@ program.command("install").description("Install Jig rules and the agent skill fi
     process.exit(1);
   }
 });
+program.command("explain").description("Explain a rule, or find the rules you cannot name.").argument("[query]", "a rule id ('C-19'), a word to search for ('contrast'), or a section letter with --list").option("--list", "list every rule id and title, or one section with a section letter").action((query, options) => {
+  try {
+    console.log(explain({ ruleId: query ?? "", version, list: options.list }));
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+});
 program.command("update").description("Update vendored Jig rules, skipping files you have edited.").action(() => {
   const projectRoot = findProjectRoot(process.cwd());
   try {
@@ -2296,7 +3548,11 @@ program.command("update").description("Update vendored Jig rules, skipping files
       version,
       homeDir: homedir()
     });
-    console.log(`Updated Jig ${result.fromVersion} \u2192 ${result.toVersion}`);
+    const label = result.targets.map((t) => `${t.agent} (${t.scope}, ${t.fromVersion})`).join(", ");
+    warnIfUnpublishedPin();
+    console.log(
+      `Updated Jig \u2192 ${result.toVersion} in ${result.targets.length} harness${result.targets.length === 1 ? "" : "es"}: ${label}`
+    );
     for (const f of result.updated) console.log(`  ~ ${f}`);
     for (const f of result.skipped) console.log(`  \xB7 ${f} (edited locally, left alone)`);
   } catch (err) {