jig-ui 0.4.0 → 0.6.0

package/dist/index.js

@@ -2,9 +2,9 @@
 
 // src/index.ts
 import { Command } from "commander";
-import { readFileSync as readFileSync16 } from "fs";
+import { readFileSync as readFileSync19 } from "fs";
 import { homedir } from "os";
-import { join as join21 } from "path";
+import { join as join24 } from "path";
 
 // src/paths.ts
 import { existsSync } from "fs";
@@ -42,16 +42,16 @@ function isPublishedBuild(packageRoot2) {
 }
 
 // src/commands/install.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname4, join as join6 } 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);
+  const isAbsolute2 = relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath);
   const hasDotDotSegment = relPath.split(/[\\/]/).includes("..");
-  if (isAbsolute || hasDotDotSegment) {
+  if (isAbsolute2 || hasDotDotSegment) {
     throw new Error(`Adapter '${adapterName}' produced an unsafe relPath: ${relPath}`);
   }
 }
@@ -477,6 +477,10 @@ function upsertBlock(existing, block) {
   return `${text.slice(0, insertAt)}${block}${text.slice(insertAt)}`;
 }
 
+// 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;
@@ -490,23 +494,36 @@ function matchLineEndings(content, existing) {
   return target === "\n" ? normalized : normalized.replace(/\n/g, "\r\n");
 }
 
-// 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
 function relKey(...parts) {
   return parts.join("/");
 }
-function writeFile(root, key, content, files) {
-  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);
-  writeFileSync3(abs, toWrite, "utf8");
-  files[key] = checksum(toWrite);
+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();
 }
+
+// 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 = readFileSync3(join6(packageRoot2, "templates", "SKILL.md.tmpl"), "utf8");
+  const template = readFileSync4(join7(packageRoot2, "templates", "SKILL.md.tmpl"), "utf8");
   const metadata = JSON.parse(
-    readFileSync3(join6(packageRoot2, "templates", "command-metadata.json"), "utf8")
+    readFileSync4(join7(packageRoot2, "templates", "command-metadata.json"), "utf8")
   );
   return render(template, {
     command_prefix: "/jig ",
@@ -523,13 +540,13 @@ function buildSkillBody(packageRoot2, rulesPath, version2) {
 }
 function buildCommandBody(packageRoot2, rulesPath, version2, argsPlaceholder) {
   const metadata = JSON.parse(
-    readFileSync3(join6(packageRoot2, "templates", "command-metadata.json"), "utf8")
+    readFileSync4(join7(packageRoot2, "templates", "command-metadata.json"), "utf8")
   );
   const subcommands = Object.entries(metadata).filter(([, meta]) => meta.status === "available").map(([name]) => name).sort();
-  const templatePath = join6(packageRoot2, "templates", "COMMAND.md.tmpl");
-  if (!existsSync4(templatePath)) return { body: "", subcommands };
-  const template = readFileSync3(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(/\{\{rules_path\}\}/g, rulesPath);
+  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) {
@@ -562,9 +579,9 @@ function install(opts) {
     existingManifest = null;
   }
   const planned = [];
-  const rulesDir = join6(opts.packageRoot, "rules");
-  for (const file of readdirSync2(rulesDir).filter((f) => f.endsWith(".md")).sort()) {
-    const body = readFileSync3(join6(rulesDir, 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(referenceDir, "rules", file),
       content: vendorHeader(file, opts.version, "html", licencePathFor(`rules/${file}`)) + body,
@@ -580,13 +597,13 @@ function install(opts) {
   }
   planned.push({
     key: relKey(referenceDir, "rules.index.json"),
-    content: readFileSync3(join6(opts.packageRoot, "rules.index.json"), "utf8"),
+    content: readFileSync4(join7(opts.packageRoot, "rules.index.json"), "utf8"),
     checkable: true
   });
   for (const src of ["LICENSE", "NOTICE"]) {
     planned.push({
       key: relKey(referenceDir, src),
-      content: readFileSync3(join6(opts.packageRoot, src), "utf8"),
+      content: readFileSync4(join7(opts.packageRoot, src), "utf8"),
       checkable: false
     });
   }
@@ -608,12 +625,13 @@ function install(opts) {
   });
   for (const file of skillFiles) {
     const key = file.relPath;
-    const abs = join6(installRoot, ...key.split("/"));
+    const abs = join7(installRoot, ...key.split("/"));
     const isBlockFile = file.content.includes(BLOCK_START);
-    const content = isBlockFile && existsSync4(abs) ? upsertBlock(readFileSync3(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) {
@@ -623,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 = {
@@ -639,8 +657,8 @@ function install(opts) {
 }
 
 // src/commands/update.ts
-import { dirname as dirname6, join as join9 } from "path";
-import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync6, readdirSync as readdirSync4, writeFileSync as writeFileSync5 } 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";
@@ -683,14 +701,14 @@ function resolveAllInstalled(projectRoot, homeDir) {
 }
 
 // src/init/state.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4 } from "fs";
-import { dirname as dirname5, join as join7 } from "path";
-var INIT_MANIFEST_REL = join7(".jig", "state.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 = join7(projectRoot, INIT_MANIFEST_REL);
-  if (!existsSync5(path)) return null;
+  const path = join8(projectRoot, INIT_MANIFEST_REL);
+  if (!existsSync6(path)) return null;
   try {
-    const raw = JSON.parse(readFileSync4(path, "utf8"));
+    const raw = JSON.parse(readFileSync5(path, "utf8"));
     if (typeof raw !== "object" || raw === null) return null;
     const { files, version: version2, modes } = raw;
     if (typeof files !== "object" || files === null) return null;
@@ -705,7 +723,7 @@ function readInitManifest(projectRoot) {
 }
 var MERGE_ATTEMPTS2 = 5;
 function writeInitManifest(projectRoot, m) {
-  const path = join7(projectRoot, INIT_MANIFEST_REL);
+  const path = join8(projectRoot, INIT_MANIFEST_REL);
   mkdirSync4(dirname5(path), { recursive: true });
   for (let attempt = 0; attempt < MERGE_ATTEMPTS2; attempt++) {
     const onDisk = readInitManifest(projectRoot);
@@ -726,15 +744,15 @@ function isInitFileModified(projectRoot, relPath, m) {
 }
 
 // src/init/migrate.ts
-import { existsSync as existsSync6, readFileSync as readFileSync5, readdirSync as readdirSync3, rmSync } from "fs";
-import { join as join8 } from "path";
+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(readFileSync5(join8(dirAbs, "manifest.json"), "utf8"));
+    const raw = JSON.parse(readFileSync6(join9(dirAbs, "manifest.json"), "utf8"));
     if (raw && typeof raw === "object" && typeof raw.files === "object") {
       return raw;
     }
@@ -746,8 +764,8 @@ function classify(projectRoot, relPath, legacyManifest) {
   return legacyManifest && relPath in legacyManifest.files ? isModified(projectRoot, relPath, legacyManifest) : "unknown";
 }
 function detectLegacyRules(projectRoot) {
-  const jigDir = join8(projectRoot, ".jig");
-  if (!existsSync6(jigDir)) return { present: false, files: [] };
+  const jigDir = join9(projectRoot, ".jig");
+  if (!existsSync7(jigDir)) return { present: false, files: [] };
   const legacyManifest = readLegacyManifest(jigDir);
   let entries;
   try {
@@ -763,12 +781,12 @@ function detectLegacyRules(projectRoot) {
 }
 function detectLegacyCursorRules(projectRoot) {
   const bundleDirRel = ".cursor/rules/jig";
-  const bundleDir = join8(projectRoot, ...bundleDirRel.split("/"));
+  const bundleDir = join9(projectRoot, ...bundleDirRel.split("/"));
   const mdcRel = ".cursor/rules/jig.mdc";
-  const mdcAbs = join8(projectRoot, ...mdcRel.split("/"));
+  const mdcAbs = join9(projectRoot, ...mdcRel.split("/"));
   const legacyManifest = readLegacyManifest(bundleDir);
   const files = [];
-  if (existsSync6(mdcAbs)) {
+  if (existsSync7(mdcAbs)) {
     files.push({ relPath: mdcRel, modified: classify(projectRoot, mdcRel, legacyManifest) });
   }
   let entries;
@@ -822,7 +840,7 @@ function removableLegacyFiles(report) {
 function removeLegacyFiles(projectRoot, relPaths) {
   for (const relPath of relPaths) {
     try {
-      rmSync(join8(projectRoot, ...relPath.split("/")), { force: true });
+      rmSync(join9(projectRoot, ...relPath.split("/")), { force: true });
     } catch {
     }
   }
@@ -868,24 +886,19 @@ function updateTarget(opts, 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 = join9(installRoot, ...key.split("/"));
-    mkdirSync5(dirname6(abs), { recursive: true });
-    const existing2 = existsSync7(abs) ? readFileSync6(abs, "utf8") : void 0;
-    const toWrite = matchLineEndings(content, existing2);
-    writeFileSync5(abs, toWrite, "utf8");
-    files[key] = checksum(toWrite);
-    updated.push(key);
+    updated.push(writer.write(key, content));
   };
-  const rulesDir = join9(opts.packageRoot, "rules");
-  for (const file of readdirSync4(rulesDir).filter((f) => f.endsWith(".md")).sort()) {
+  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, "html", licencePathFor(`rules/${file}`)) + readFileSync6(join9(rulesDir, file), "utf8"));
+    write(key, vendorHeader(file, opts.version, "html", licencePathFor(`rules/${file}`)) + readFileSync7(join10(rulesDir, file), "utf8"));
   }
   for (const ref of referenceFiles(opts.packageRoot)) {
     const key = relKey(referenceDir, ...ref.relPath.split("/"));
@@ -899,7 +912,7 @@ function updateTarget(opts, resolved) {
   if (isModified(installRoot, indexKey, existing)) {
     skipped.push(indexKey);
   } else {
-    write(indexKey, readFileSync6(join9(opts.packageRoot, "rules.index.json"), "utf8"));
+    write(indexKey, readFileSync7(join10(opts.packageRoot, "rules.index.json"), "utf8"));
   }
   const rulesPath = rulesPathFor(referenceDir, discoveredScope);
   const skillBody = buildSkillBody(opts.packageRoot, rulesPath, opts.version);
@@ -921,8 +934,8 @@ function updateTarget(opts, resolved) {
     const key = file.relPath;
     const isBlockFile = file.content.includes(BLOCK_START);
     if (isBlockFile) {
-      const abs = join9(installRoot, ...key.split("/"));
-      const current = existsSync7(abs) ? readFileSync6(abs, "utf8") : "";
+      const abs = join10(installRoot, ...key.split("/"));
+      const current = existsSync8(abs) ? readFileSync7(abs, "utf8") : "";
       write(key, upsertBlock(current, file.content));
       continue;
     }
@@ -933,7 +946,7 @@ function updateTarget(opts, resolved) {
     write(key, file.content);
   }
   for (const src of ["LICENSE", "NOTICE"]) {
-    write(relKey(referenceDir, src), readFileSync6(join9(opts.packageRoot, src), "utf8"));
+    write(relKey(referenceDir, src), readFileSync7(join10(opts.packageRoot, src), "utf8"));
   }
   const manifest = {
     ...existing,
@@ -948,37 +961,35 @@ function updateTarget(opts, resolved) {
 function updateInitFiles(opts) {
   const updated = [];
   const skipped = [];
-  const tokensDir = join9(opts.packageRoot, "tokens");
+  const tokensDir = join10(opts.packageRoot, "tokens");
   const initManifest = readInitManifest(opts.projectRoot);
   if (initManifest) {
     const initFiles = { ...initManifest.files };
     let initChanged = false;
-    for (const file of readdirSync4(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", null) + readFileSync6(join9(tokensDir, file), "utf8");
-      const abs = join9(opts.projectRoot, ...key.split("/"));
-      mkdirSync5(dirname6(abs), { recursive: true });
-      writeFileSync5(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);
     }
+    Object.assign(initFiles, writer.files);
     if (initChanged) writeInitManifest(opts.projectRoot, { ...initManifest, version: opts.version, files: initFiles });
   }
   return { updated, skipped };
 }
 
 // src/commands/explain.ts
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 
 // src/rules/load.ts
-import { readFileSync as readFileSync7, readdirSync as readdirSync5 } from "fs";
-import { join as join10 } from "path";
+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*$/;
@@ -1050,12 +1061,12 @@ function validateIndex(entries) {
 
 // src/rules/load.ts
 function loadRules(rulesDir, indexPath) {
-  const files = readdirSync5(rulesDir).filter((f) => f.endsWith(".md")).sort();
+  const files = readdirSync4(rulesDir).filter((f) => f.endsWith(".md")).sort();
   const parsed = [];
   for (const file of files) {
-    parsed.push(...parseRules(readFileSync7(join10(rulesDir, file), "utf8"), file));
+    parsed.push(...parseRules(readFileSync8(join11(rulesDir, file), "utf8"), file));
   }
-  const entries = validateIndex(JSON.parse(readFileSync7(indexPath, "utf8")));
+  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) {
@@ -1077,8 +1088,8 @@ function loadRules(rulesDir, indexPath) {
 }
 
 // src/rules/specs.ts
-import { readFileSync as readFileSync8, readdirSync as readdirSync6 } from "fs";
-import { join as join11 } from "path";
+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");
@@ -1110,68 +1121,121 @@ function parseSpecs(markdown, sourceFile) {
 }
 function loadSpecs(rulesDir) {
   const specs = [];
-  for (const file of readdirSync6(rulesDir).filter((f) => f.endsWith(".md")).sort()) {
-    specs.push(...parseSpecs(readFileSync8(join11(rulesDir, file), "utf8"), file));
+  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 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) {
+  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(
-      `'${opts.ruleId.trim()}' is not a rule id. Ids look like 'C-19' or 'P-02' \u2014 a section letter, a hyphen, and a number.`
+      siblings.length > 0 ? `No rule '${id}'. Section ${shape[1]} has: ${siblings.join(", ")}.` : `No rule '${id}', and no section '${shape[1]}' exists.`
     );
   }
-  const root = opts.packageRoot ?? assetRoot();
-  const rulesDir = join12(root, "rules");
-  const rules = loadRules(rulesDir, join12(root, "rules.index.json"));
-  const rule = rules.find((r) => r.id === raw);
-  if (rule) {
-    const lines = [
-      `${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}`
-    ];
-    return lines.join("\n");
+  if (raw === "") {
+    throw new Error(
+      `Nothing to explain. Give a rule id ('C-19'), a word to search for ('contrast'), or --list.`
+    );
   }
-  const spec = loadSpecs(rulesDir).find((s) => s.id === raw);
-  if (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");
+  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.`
+    );
   }
-  const section = shape[1];
-  const siblings = [
-    ...rules.filter((r) => r.id.startsWith(`${section}-`)).map((r) => r.id),
-    ...loadSpecs(rulesDir).filter((s) => s.id.startsWith(`${section}-`)).map((s) => s.id)
-  ].sort((a, b) => Number(a.split("-")[1]) - Number(b.split("-")[1]));
-  throw new Error(
-    siblings.length > 0 ? `No rule '${raw}'. Section ${section} has: ${siblings.join(", ")}.` : `No rule '${raw}', and no section '${section}' exists.`
-  );
+  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 existsSync9, readFileSync as readFileSync11 } from "fs";
-import { join as join16 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync14 } from "fs";
+import { join as join19 } from "path";
 
 // src/check/files.ts
 import { execFileSync } from "child_process";
-import { readdirSync as readdirSync7, realpathSync, statSync } from "fs";
-import { join as join13, 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",
@@ -1230,13 +1294,13 @@ function isExcluded(relPath) {
 function walk(root, dir, out, seen) {
   let entries;
   try {
-    entries = readdirSync7(dir, { withFileTypes: true });
+    entries = readdirSync6(dir, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
     if (EXCLUDE_DIRS.has(entry.name)) continue;
-    const abs = join13(dir, entry.name);
+    const abs = join14(dir, entry.name);
     let isDir = entry.isDirectory();
     let isFile = entry.isFile();
     if (entry.isSymbolicLink()) {
@@ -1363,6 +1427,17 @@ function formatReport(findings, meta) {
   const rulesFired = new Set(findings.map((f) => f.ruleId)).size;
   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.exemptPatterns && meta.exemptPatterns.length > 0) {
+    const n = meta.exempt?.length ?? 0;
+    lines.push(`  ${n} file(s) exempt via jig.config.json and not scanned:`);
+    for (const { pattern, count, tooBroad } of meta.exemptPatterns) {
+      const note = count === 0 ? "matches nothing \u2014 check the path" : tooBroad ? `${count} files \u2014 likely too broad, review it` : `${count} file${count > 1 ? "s" : ""}`;
+      lines.push(`    ${pattern}  (${note})`);
+    }
+    if (n > 0) {
+      lines.push(`    ${meta.exempt.slice(0, 8).join(", ")}${n > 8 ? `, and ${n - 8} more` : ""}`);
+    }
+  }
   if (meta.unscanned && meta.unscanned.count > 0) {
     const exts = meta.unscanned.extensions.join(", ");
     lines.push("");
@@ -1473,8 +1548,8 @@ function isStyleBearing(file) {
 }
 
 // src/check/run.ts
-import { readFileSync as readFileSync9 } from "fs";
-import { join as join14 } from "path";
+import { readFileSync as readFileSync10 } from "fs";
+import { join as join15 } from "path";
 
 // src/check/css.ts
 function maskComments(source) {
@@ -1523,7 +1598,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();
@@ -1531,7 +1611,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;
@@ -2377,13 +2458,38 @@ var COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\b|(?:rgb|hsl)a?\([^)]*\)/;
 var PX_RE = /(-?\d*\.?\d+)px/g;
 var EXCLUDED_PX = /* @__PURE__ */ new Set([0, 1, 2]);
 var KEYFRAME_STEP_RE = /^(from|to|\d+(\.\d+)?%)$/i;
+var PRIMITIVE_RE = /var\(\s*(--(?:brand|error|warning|success|info)-(?:h|s|l|fill-a))\s*[,)]/g;
+var TOKEN_LAYER_RE = /(^|\/)(\.jig\/tokens|jig)\/[^/]+\.css$/;
+function primitiveConsumption(source, file, ctx) {
+  if (TOKEN_LAYER_RE.test(file)) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of source.matchAll(PRIMITIVE_RE)) {
+    const token = m[1];
+    const line = source.slice(0, m.index ?? 0).split("\n").length;
+    const key = `${token}:${line}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(
+      mkFinding(
+        ctx,
+        "hardcoded-value",
+        file,
+        line,
+        `${token} is a raw channel input, not a semantic role \u2014 consuming it bypasses the theme overrides, which remap \`--color-*\` and never the channels. Use the semantic token for what this is (\`--color-text-*\`, \`--color-fill-*\`, \`--color-stroke-*\`).`,
+        sourceLine(source, line)
+      )
+    );
+  }
+  return out;
+}
 var hardcodedValue = {
   name: "hardcoded-value",
   appliesTo: (file) => isStyleBearing(file),
   run(source, file, ctx) {
+    const findings = primitiveConsumption(source, file, ctx);
     const participates = isStyleHost(file) ? ctx.projectParticipates : participatesInTokenLayer(source, ctx.tokens);
-    if (!participates) return [];
-    const findings = [];
+    if (!participates) return findings;
     for (const block of leafBlocks(source)) {
       if (KEYFRAME_STEP_RE.test(block.selector.trim())) continue;
       DECL_RE2.lastIndex = 0;
@@ -2514,7 +2620,7 @@ function runChecks(projectRoot, files, index, tokens, bucketFilter, projectParti
     if (applicable.length === 0) continue;
     let raw;
     try {
-      raw = readFileSync9(join14(projectRoot, file), "utf8");
+      raw = readFileSync10(join15(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -2528,38 +2634,261 @@ function runChecks(projectRoot, files, index, tokens, bucketFilter, projectParti
 }
 
 // src/check/tokens.ts
-import { existsSync as existsSync8, readdirSync as readdirSync8, readFileSync as readFileSync10 } from "fs";
-import { join as join15 } from "path";
-function loadTokenMap(projectRoot) {
-  const tokensDir = join15(projectRoot, ".jig", "tokens");
-  const tokens = {};
-  if (!existsSync8(tokensDir)) return tokens;
-  const files = readdirSync8(tokensDir).filter((f) => f.endsWith(".css")).sort();
+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/check/exempt.ts
+import { existsSync as existsSync10, readFileSync as readFileSync12 } from "fs";
+import { join as join17 } from "path";
+function globToRegExp(glob) {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        out += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++;
+      } else {
+        out += "[^/]*";
+      }
+    } else if (c === "?") out += "[^/]";
+    else out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+function readExemptions(projectRoot) {
+  const configPath = join17(projectRoot, "jig.config.json");
+  if (!existsSync10(configPath)) return [];
+  let declared;
+  try {
+    declared = JSON.parse(readFileSync12(configPath, "utf8")).exempt;
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(declared)) return [];
+  return declared.filter(
+    (p) => typeof p === "string" && p.trim() !== "" && !p.startsWith("/") && !p.split("/").includes("..")
+  );
+}
+var LIKELY_TOO_BROAD = 3;
+function applyExemptions(files, patterns) {
+  if (patterns.length === 0) return { scanned: files, exempt: [], byPattern: [] };
+  const compiled = patterns.map((pattern) => ({ pattern, re: globToRegExp(pattern), count: 0 }));
+  const scanned = [];
+  const exempt = [];
   for (const file of files) {
-    const source = readFileSync10(join15(tokensDir, file), "utf8");
+    const matches2 = compiled.filter((c) => c.re.test(file));
+    for (const m of matches2) m.count++;
+    (matches2.length > 0 ? exempt : scanned).push(file);
+  }
+  return {
+    scanned,
+    exempt,
+    byPattern: compiled.map(({ pattern, count }) => ({
+      pattern,
+      count,
+      tooBroad: count > LIKELY_TOO_BROAD
+    }))
+  };
+}
+
+// src/check/token-audit.ts
+import { existsSync as existsSync11, readdirSync as readdirSync8, readFileSync as readFileSync13 } from "fs";
+import { join as join18 } from "path";
+var TEXT_FLOOR = 4.5;
+var UI_FLOOR = 3;
+var FOREGROUNDS = [
+  { prefix: "--color-text-", floor: TEXT_FLOOR },
+  { prefix: "--color-stroke-", floor: UI_FLOOR },
+  { prefix: "--color-focus", floor: UI_FLOOR }
+];
+var SURFACES = ["--color-bg-base", "--color-bg-raised", "--color-bg-overlay", "--color-fill"];
+var NUMERIC_FLOORS = [
+  { token: "--text-prose", min: 18, why: "sustained reading (B-75)" },
+  { token: "--size-touch-target", min: 48, why: "hit area, unchanged in every mode" }
+];
+function composite(fg, alpha, bg) {
+  return {
+    r: Math.round(fg.r * alpha + bg.r * (1 - alpha)),
+    g: Math.round(fg.g * alpha + bg.g * (1 - alpha)),
+    b: Math.round(fg.b * alpha + bg.b * (1 - alpha))
+  };
+}
+function isDarkBlock(selector, atRuleDepth) {
+  return /data-theme\s*=\s*["']?dark/.test(selector) || atRuleDepth > 0;
+}
+function collectScopes(files) {
+  const light = {};
+  const darkOverrides = {};
+  for (const { path, source } of files) {
     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();
+      if (!/^:root/.test(block.selector.trim())) continue;
+      const target = isDarkBlock(block.selector, block.atRuleDepth) ? darkOverrides : light;
+      for (const m of block.body.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
+        const offsetInBody = m.index ?? 0;
+        target[m[1]] = {
+          value: m[2].trim(),
+          file: path,
+          // `bodyStartLine` is where the block's body begins; add the newlines
+          // before this declaration inside it.
+          line: block.bodyStartLine + block.body.slice(0, offsetInBody).split("\n").length - 1
+        };
       }
     }
   }
-  return tokens;
+  return { light, dark: { ...light, ...darkOverrides } };
+}
+var asTokenMap = (scope) => Object.fromEntries(Object.entries(scope).map(([k, v]) => [k.replace(/^--/, ""), v.value]));
+function floorFor(token) {
+  if (/^--color-stroke-.*-weak$/.test(token) || token === "--color-stroke-weak") return null;
+  for (const { prefix, floor } of FOREGROUNDS) {
+    if (token.startsWith(prefix)) return floor;
+  }
+  return null;
+}
+function tokenFiles(projectRoot) {
+  const read = (rel) => {
+    try {
+      return readFileSync13(join18(projectRoot, ...rel.split("/")), "utf8");
+    } catch {
+      return null;
+    }
+  };
+  const statePath = join18(projectRoot, ".jig", "state.json");
+  if (existsSync11(statePath)) {
+    try {
+      const state = JSON.parse(readFileSync13(statePath, "utf8"));
+      const recorded = Object.keys(state.files ?? {}).filter((f) => f.endsWith(".css")).sort();
+      const out = recorded.map((path) => ({ path, source: read(path) })).filter((f) => f.source !== null);
+      if (out.length > 0) return out;
+    } catch {
+    }
+  }
+  const legacy = join18(projectRoot, ".jig", "tokens");
+  if (!existsSync11(legacy)) return [];
+  return readdirSync8(legacy).filter((f) => f.endsWith(".css")).sort().map((f) => ({ path: `.jig/tokens/${f}`, source: readFileSync13(join18(legacy, f), "utf8") }));
+}
+function auditTokenLayer(projectRoot) {
+  const files = tokenFiles(projectRoot);
+  if (files.length === 0) return [];
+  const scopes = collectScopes(files);
+  const problems = [];
+  for (const theme of ["light", "dark"]) {
+    const scope = scopes[theme];
+    const map = asTokenMap(scope);
+    const base = extractColorComponents(scope["--color-bg-base"]?.value ?? "", map);
+    const surfaces = [];
+    for (const name of SURFACES) {
+      const decl = scope[name];
+      if (!decl) continue;
+      const c = extractColorComponents(decl.value, map);
+      if (!c) continue;
+      if (c.alpha >= 0.999) surfaces.push({ name, rgb: c.rgb });
+      else if (base && base.alpha >= 0.999) {
+        surfaces.push({ name, rgb: composite(c.rgb, c.alpha, base.rgb) });
+      }
+    }
+    if (surfaces.length === 0) continue;
+    for (const [token, decl] of Object.entries(scope)) {
+      const floor = floorFor(token);
+      if (floor === null) continue;
+      const fg = extractColorComponents(decl.value, map);
+      if (!fg) continue;
+      const failures = surfaces.map((surface) => {
+        const solid = fg.alpha >= 0.999 ? fg.rgb : composite(fg.rgb, fg.alpha, surface.rgb);
+        return { surface: surface.name, ratio: contrastRatio(solid, surface.rgb) };
+      }).filter((f) => f.ratio < floor).sort((a, b) => a.ratio - b.ratio);
+      if (failures.length === 0) continue;
+      const worst = failures[0];
+      const others = failures.length - 1;
+      problems.push({
+        token,
+        surface: worst.surface,
+        theme,
+        ratio: Math.round(worst.ratio * 100) / 100,
+        floor,
+        file: decl.file,
+        line: decl.line,
+        message: `${token} is ${worst.ratio.toFixed(2)}:1 against ${worst.surface} in ${theme} mode, below the ${floor}:1 floor the token layer states for this role` + (others > 0 ? ` (and below it on ${others} other surface${others > 1 ? "s" : ""})` : "") + "."
+      });
+    }
+    for (const { token, min, why } of NUMERIC_FLOORS) {
+      const decl = scope[token];
+      if (!decl) continue;
+      const px = /^([\d.]+)px$/.exec(decl.value.trim());
+      if (!px) continue;
+      const value = Number(px[1]);
+      if (value >= min) continue;
+      problems.push({
+        token,
+        theme,
+        value,
+        floor: min,
+        file: decl.file,
+        line: decl.line,
+        message: `${token} is ${value}px, below the ${min}px floor for ${why}. This is an accessibility limit, not a density setting.`
+      });
+    }
+  }
+  return problems;
 }
 
 // src/commands/check.ts
-var LEGACY_INDEX_REL = join16(".jig", "rules.index.json");
+var LEGACY_INDEX_REL = join19(".jig", "rules.index.json");
 function resolveIndexPath(projectRoot) {
-  const legacy = join16(projectRoot, LEGACY_INDEX_REL);
-  if (existsSync9(legacy)) return legacy;
-  return join16(assetRoot(), "rules.index.json");
+  const legacy = join19(projectRoot, LEGACY_INDEX_REL);
+  if (existsSync12(legacy)) return legacy;
+  return join19(assetRoot(), "rules.index.json");
 }
 function resolveMode(projectRoot) {
   try {
-    const config = JSON.parse(readFileSync11(join16(projectRoot, "jig.config.json"), "utf8"));
+    const config = JSON.parse(readFileSync14(join19(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";
@@ -2576,28 +2905,46 @@ function summariseUnscanned(files) {
 }
 function countSpecs() {
   try {
-    return loadSpecs(join16(assetRoot(), "rules")).length;
+    return loadSpecs(join19(assetRoot(), "rules")).length;
   } catch {
     return 0;
   }
 }
 function check(opts) {
   const indexPath = resolveIndexPath(opts.projectRoot);
-  const index = validateIndex(JSON.parse(readFileSync11(indexPath, "utf8")));
-  const tokens = loadTokenMap(opts.projectRoot);
+  const index = validateIndex(JSON.parse(readFileSync14(indexPath, "utf8")));
   const selection = selectFiles(opts.projectRoot, opts.all);
-  const { files } = selection;
+  const exemptions = readExemptions(opts.projectRoot);
+  const { scanned: files, exempt, byPattern } = applyExemptions(selection.files, exemptions);
   const bucketFilter = opts.ci ? (b) => b === "mechanical" : void 0;
   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(readFileSync11(join16(opts.projectRoot, f), "utf8"), tokens);
+      return participatesInTokenLayer(readFileSync14(join19(opts.projectRoot, f), "utf8"), tokens);
     } catch {
       return false;
     }
   });
   const findings = runChecks(opts.projectRoot, files, index, tokens, bucketFilter, projectParticipates);
+  const TOKEN_RULE = {
+    "--text-prose": "B-75",
+    "--size-touch-target": "E-51"
+  };
+  for (const problem of auditTokenLayer(opts.projectRoot)) {
+    const ruleId = TOKEN_RULE[problem.token] ?? "C-19";
+    const entry = index.find((e) => e.id === ruleId);
+    findings.push({
+      ruleId,
+      detector: "token-layer",
+      bucket: entry?.bucket ?? "mechanical",
+      severity: entry?.severity ?? "error",
+      file: problem.file,
+      line: problem.line,
+      message: problem.message
+    });
+  }
   const hasError = findings.some((f) => f.bucket === "mechanical" && f.severity === "error");
   const cssFiles = files.filter((f) => /\.(css|scss|less)$/i.test(f));
   const noTokenLayer = (
@@ -2605,7 +2952,7 @@ function check(opts) {
     // told to add a token @import it has nowhere to put.
     cssFiles.length > 0 && cssFiles.every((f) => {
       try {
-        return !participatesInTokenLayer(readFileSync11(join16(opts.projectRoot, f), "utf8"), tokens);
+        return !participatesInTokenLayer(readFileSync14(join19(opts.projectRoot, f), "utf8"), tokens);
       } catch {
         return true;
       }
@@ -2620,18 +2967,20 @@ function check(opts) {
     version: opts.version,
     noTokenLayer,
     mode: resolveMode(opts.projectRoot),
-    unscanned: summariseUnscanned(files)
+    unscanned: summariseUnscanned(files),
+    exempt,
+    exemptPatterns: byPattern
   });
   return { findings, report, hasError };
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync15, writeFileSync as writeFileSync6 } from "fs";
-import { dirname as dirname7, join as join20 } from "path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync5, readdirSync as readdirSync9, readFileSync as readFileSync18, writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname6, isAbsolute, join as join23, resolve as resolve2, sep as sep3 } from "path";
 
 // src/init/detect.ts
-import { readFileSync as readFileSync12 } from "fs";
-import { join as join17 } from "path";
+import { readFileSync as readFileSync15 } from "fs";
+import { join as join20 } 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/;
@@ -2648,7 +2997,7 @@ var FRAMEWORK_DEPS = [
 function detectFramework(projectRoot) {
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync12(join17(projectRoot, "package.json"), "utf8"));
+    pkg = JSON.parse(readFileSync15(join20(projectRoot, "package.json"), "utf8"));
   } catch {
     return void 0;
   }
@@ -2666,7 +3015,7 @@ function detect(projectRoot) {
   for (const f of cssFiles) {
     let source;
     try {
-      source = readFileSync12(join17(projectRoot, f), "utf8");
+      source = readFileSync15(join20(projectRoot, f), "utf8");
     } catch {
       continue;
     }
@@ -2701,8 +3050,8 @@ function isIgnored(projectRoot, relPath) {
 }
 
 // src/init/derive.ts
-import { readFileSync as readFileSync13 } from "fs";
-import { join as join18 } from "path";
+import { readFileSync as readFileSync16 } from "fs";
+import { join as join21 } from "path";
 var DEFAULT_PROPOSAL = {
   h: 264,
   s: 0,
@@ -2735,7 +3084,7 @@ function fromCssCustomProperties(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync13(join18(projectRoot, file), "utf8");
+      source = readFileSync16(join21(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -2784,7 +3133,7 @@ function balancedBraceBody(source, openIdx) {
 function fromTailwindConfig(projectRoot, tailwindConfigFile) {
   let source;
   try {
-    source = readFileSync13(join18(projectRoot, tailwindConfigFile), "utf8");
+    source = readFileSync16(join21(projectRoot, tailwindConfigFile), "utf8");
   } catch {
     return null;
   }
@@ -2840,7 +3189,7 @@ function fromLiteralFrequency(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync13(join18(projectRoot, file), "utf8");
+      source = readFileSync16(join21(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -3000,8 +3349,8 @@ function relativeImportPath(fromAbsDir, toAbsFile) {
 }
 
 // src/init/project-name.ts
-import { readFileSync as readFileSync14 } from "fs";
-import { basename, join as join19 } from "path";
+import { readFileSync as readFileSync17 } from "fs";
+import { basename, join as join22 } from "path";
 function slugify(name) {
   const withoutScope = name.replace(/^@[^/]+\//, "");
   const slug = withoutScope.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -3009,7 +3358,7 @@ function slugify(name) {
 }
 function deriveProjectSlug(projectRoot) {
   try {
-    const pkg = JSON.parse(readFileSync14(join19(projectRoot, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync17(join22(projectRoot, "package.json"), "utf8"));
     if (typeof pkg.name === "string" && pkg.name.trim()) return slugify(pkg.name);
   } catch {
   }
@@ -3075,7 +3424,7 @@ function parseSurfaces(answer, fallback) {
   return parsed.length > 0 ? parsed : fallback;
 }
 function fileState(projectRoot, absPath, relPath, initManifest) {
-  const existsOnDisk = existsSync10(absPath);
+  const existsOnDisk = existsSync13(absPath);
   const tracked = !!initManifest && relPath in initManifest.files;
   const modified = tracked && isInitFileModified(projectRoot, relPath, initManifest);
   return { existsOnDisk, tracked, modified };
@@ -3086,11 +3435,11 @@ function isValidSurfaceArray(v) {
   );
 }
 function loadEffectiveConfig(projectRoot, configAbsPath, fallbackBrand, fallbackSurfaces) {
-  if (!existsSync10(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
+  if (!existsSync13(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
   try {
-    const parsed = JSON.parse(readFileSync15(configAbsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync18(configAbsPath, "utf8"));
     const brandCandidate = typeof parsed.brand === "string" && parsed.brand ? parsed.brand : void 0;
-    const brandResolves = brandCandidate ? existsSync10(join20(projectRoot, ...brandCandidate.split("/"))) : false;
+    const brandResolves = brandCandidate ? existsSync13(join23(projectRoot, ...brandCandidate.split("/"))) : false;
     return {
       brand: brandResolves ? brandCandidate : fallbackBrand,
       surfaces: isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : fallbackSurfaces
@@ -3099,12 +3448,61 @@ function loadEffectiveConfig(projectRoot, configAbsPath, fallbackBrand, fallback
     return { brand: fallbackBrand, surfaces: fallbackSurfaces };
   }
 }
+function configuredBrandPath(projectRoot, configAbsPath) {
+  if (!existsSync13(configAbsPath)) return { path: null };
+  let declared;
+  try {
+    declared = JSON.parse(readFileSync18(configAbsPath, "utf8")).brand;
+  } catch {
+    return { path: null };
+  }
+  if (typeof declared !== "string" || !declared.trim()) return { path: null };
+  const rel = declared.trim().replace(/\\/g, "/");
+  const abs = resolve2(projectRoot, rel);
+  const root = resolve2(projectRoot);
+  if (isAbsolute(rel) || abs !== root && !abs.startsWith(root + sep3)) {
+    return { path: null, refused: rel };
+  }
+  if (!/\.css$/i.test(rel)) return { path: null, refused: rel };
+  return { path: rel };
+}
+function defaultTokenDir(detection) {
+  const target = findWireTarget(detection);
+  if (target) return [...target.split("/").slice(0, -1), "jig"];
+  const candidates = detection.cssFiles.filter((f) => !isCssModule(f) && !isTokenLayerFile(f));
+  if (candidates.length > 1) {
+    const dirs = new Set(candidates.map((f) => f.split("/").slice(0, -1).join("/")));
+    if (dirs.size === 1) {
+      const only = [...dirs][0];
+      return only ? [...only.split("/"), "jig"] : ["jig"];
+    }
+  }
+  return ["jig"];
+}
+function readConfiguredSurfaces(configAbsPath) {
+  if (!existsSync13(configAbsPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync18(configAbsPath, "utf8"));
+    return isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : null;
+  } catch {
+    return null;
+  }
+}
 function isCssModule(path) {
   return /\.module\.(css|scss)$/i.test(path);
 }
+function legacyBrandFile(projectRoot) {
+  const dir = join23(projectRoot, ".jig", "tokens");
+  if (!existsSync13(dir)) return void 0;
+  const found = readdirSync9(dir).find((f) => /^brand\.[\w.-]+\.css$/.test(f));
+  return found ? relKey(".jig", "tokens", found) : void 0;
+}
+function isTokenLayerFile(f) {
+  return /(^|\/)(\.jig\/tokens|jig)\/[^/]+\.css$/.test(f);
+}
 function findWireTarget(d) {
   if (d.cssSystem === "tailwind-v4" && d.tailwindV4EntryFile) return d.tailwindV4EntryFile;
-  const candidates = d.cssFiles.filter((f) => !isCssModule(f));
+  const candidates = d.cssFiles.filter((f) => !isCssModule(f) && !isTokenLayerFile(f));
   if (candidates.length === 1) return candidates[0];
   return null;
 }
@@ -3115,45 +3513,35 @@ function insertAfterCharset(content, insertion) {
   const charsetLen = m ? m[0].length : 0;
   return content.slice(0, charsetLen) + insertion + content.slice(charsetLen);
 }
-function wireImport(absPath, brandImport, modeImport, mode) {
-  const content = existsSync10(absPath) ? readFileSync15(absPath, "utf8") : "";
-  const brandImportLine = `@import "${brandImport}";`;
-  const modeImportLine = `@import "${modeImport}";`;
-  const brandPresent = content.includes(brandImportLine);
-  const existingModeMatch = MODE_IMPORT_RE.exec(content);
-  if (brandPresent) {
-    if (existingModeMatch && existingModeMatch[0].trim() === modeImportLine) {
-      return { status: "already-present" };
-    }
-    if (existingModeMatch) {
-      const previousMode = existingModeMatch[2];
-      const next3 = content.slice(0, existingModeMatch.index) + `${modeImportLine}
-` + content.slice(existingModeMatch.index + existingModeMatch[0].length);
-      writeFileSync6(absPath, next3, "utf8");
-      return { status: "rewired", detail: `rewired mode: ${previousMode} \u2192 ${mode}` };
-    }
-    const brandIdx = content.indexOf(brandImportLine);
-    let insertAt = brandIdx + brandImportLine.length;
-    if (content[insertAt] === "\r") insertAt++;
-    if (content[insertAt] === "\n") insertAt++;
-    const next2 = content.slice(0, insertAt) + modeImportLine + "\n" + content.slice(insertAt);
-    writeFileSync6(absPath, next2, "utf8");
-    return { status: "rewired", detail: `added missing mode import: ${mode}` };
-  }
-  const lines = `${brandImportLine}
-${modeImportLine}
+function barrelBody(fileName, brandFile, mode, version2) {
+  return vendorHeader(fileName, version2, "css", null) + `/* The token layer for one surface, in one import.
+   Brand declares the options; the mode selects from them. */
+@import "./${brandFile}";
+@import "./mode.${mode}.css";
 `;
-  const tailwindImportMatch = /@import\s+["']tailwindcss["'];?\r?\n?/.exec(content);
-  let next;
-  if (tailwindImportMatch) {
-    const idx = tailwindImportMatch.index + tailwindImportMatch[0].length;
-    next = content.slice(0, idx) + lines + content.slice(idx);
-  } else {
-    next = insertAfterCharset(content, content ? `${lines}
-` : lines);
-  }
-  mkdirSync6(dirname7(absPath), { recursive: true });
-  writeFileSync6(absPath, next, "utf8");
+}
+var LEGACY_PAIR_RE = new RegExp(
+  `@import\\s+["'][^"']*brand\\.[\\w.-]+\\.css["'];?\\r?\\n?\\s*@import\\s+["'][^"']*mode\\.(?:${MODES.join("|")})\\.css["'];?\\r?\\n?`
+);
+function wireBarrel(absPath, barrelImport) {
+  const content = existsSync13(absPath) ? readFileSync18(absPath, "utf8") : "";
+  const line = `@import "${barrelImport}";`;
+  if (content.includes(line)) return { status: "already-present" };
+  const legacy = LEGACY_PAIR_RE.exec(content);
+  if (legacy) {
+    const next2 = content.slice(0, legacy.index) + `${line}
+` + content.slice(legacy.index + legacy[0].length);
+    writeFileSync4(absPath, next2, "utf8");
+    return { status: "rewired", detail: "replaced the separate brand and mode imports with the barrel" };
+  }
+  const tailwind = /@import\s+["']tailwindcss["'];?\r?\n?/.exec(content);
+  const next = tailwind ? content.slice(0, tailwind.index + tailwind[0].length) + `${line}
+` + content.slice(tailwind.index + tailwind[0].length) : insertAfterCharset(content, content ? `${line}
+
+` : `${line}
+`);
+  mkdirSync5(dirname6(absPath), { recursive: true });
+  writeFileSync4(next === content ? absPath : absPath, next, "utf8");
   return { status: "wired" };
 }
 async function init(opts) {
@@ -3219,8 +3607,11 @@ async function init(opts) {
     }
   }
   if (opts.yes) {
+    const declared = readConfiguredSurfaces(join23(opts.projectRoot, "jig.config.json"));
+    const inEffect = declared ?? surfaces;
+    const map = inEffect.map((x) => `'${x.match}' \u2192 ${x.mode}`).join(", ");
     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("/")}).`
+      declared ? `Surface \u2192 mode: ${map} \u2014 from jig.config.json. Mode sets density, type scale and control sizes, and it outranks an agent's own reading of the project.` : `Surface \u2192 mode: ${map} \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) {
@@ -3234,11 +3625,30 @@ 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 = join20(opts.projectRoot, ".jig", "tokens", brandFileName(projectSlug));
   const configRelPath = "jig.config.json";
-  const configAbsPath = join20(opts.projectRoot, configRelPath);
-  const initManifest = readInitManifest(opts.projectRoot);
+  const configAbsPath = join23(opts.projectRoot, configRelPath);
+  const configuredBrand = configuredBrandPath(opts.projectRoot, configAbsPath);
+  if (configuredBrand.refused) {
+    log(
+      `jig.config.json names brand '${configuredBrand.refused}', which is outside the project or is not a .css file \u2014 ignoring it and using the default location.`
+    );
+  }
+  const priorManifest = readInitManifest(opts.projectRoot);
+  const priorBrand = Object.keys(priorManifest?.files ?? {}).find((f) => /(^|\/)brand\.[\w.-]+\.css$/.test(f)) ?? // Also honour a brand file that is simply THERE. A project may hold one
+  // init never recorded — written by hand, or by a version that predates the
+  // sidecar — and writing a second one somewhere else would leave two token
+  // layers, which is worse than either location.
+  detection.cssFiles.find((f) => isTokenLayerFile(f) && /(^|\/)brand\./.test(f)) ?? // `.jig/` is a dotdir, so detection never walks into it. Probe it directly:
+  // a project holding a legacy token layer must keep it rather than gain a
+  // second one somewhere else.
+  legacyBrandFile(opts.projectRoot);
+  const brandRelPath = configuredBrand.path ?? priorBrand ?? relKey(...defaultTokenDir(detection), brandFileName(projectSlug));
+  const brandAbsPath = join23(opts.projectRoot, ...brandRelPath.split("/"));
+  const tokensRelDir = brandRelPath.split("/").slice(0, -1);
+  log(
+    `Token layer: ${tokensRelDir.join("/") || "."}/ \u2014 ` + (configuredBrand.path ? "from jig.config.json." : priorBrand ? "the layout this project already had. Set `brand` in jig.config.json to move it." : findWireTarget(detection) ? "beside the stylesheet being wired. Set `brand` in jig.config.json to put it elsewhere." : "no stylesheet found to follow, so the project root. Set `brand` in jig.config.json to move it.")
+  );
+  const initManifest = priorManifest;
   const files = { ...initManifest?.files ?? {} };
   const brandState = fileState(opts.projectRoot, brandAbsPath, brandRelPath, initManifest);
   const configState = fileState(opts.projectRoot, configAbsPath, configRelPath, initManifest);
@@ -3266,72 +3676,94 @@ ${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 = readFileSync15(join20(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
+    const defaultCssRaw = readFileSync18(join23(opts.packageRoot, "tokens", "brand.default.css"), "utf8");
     const content = renderBrandFile(defaultCssRaw, projectSlug, opts.version, proposal);
-    mkdirSync6(dirname7(brandAbsPath), { recursive: true });
-    writeFileSync6(brandAbsPath, content, "utf8");
+    mkdirSync5(dirname6(brandAbsPath), { recursive: true });
+    writeFileSync4(brandAbsPath, content, "utf8");
     files[brandRelPath] = checksum(content);
   }
   if (configAction === "written") {
     const config = { brand: brandRelPath, surfaces };
     const content = `${JSON.stringify(config, null, 2)}
 `;
-    writeFileSync6(configAbsPath, content, "utf8");
+    writeFileSync4(configAbsPath, content, "utf8");
     files[configRelPath] = checksum(content);
   } else if (configAction === "merged") {
     let existing = {};
     try {
-      existing = JSON.parse(readFileSync15(configAbsPath, "utf8"));
+      existing = JSON.parse(readFileSync18(configAbsPath, "utf8"));
     } catch {
       existing = {};
     }
     const existingBrand = typeof existing.brand === "string" ? existing.brand : void 0;
-    const brandStillResolves = existingBrand ? existsSync10(join20(opts.projectRoot, ...existingBrand.split("/"))) : false;
+    const brandStillResolves = existingBrand ? existsSync13(join23(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)}
 `;
-    writeFileSync6(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 = join20(opts.projectRoot, ...effectiveConfig.brand.split("/"));
+  const wiringBrandAbsPath = join23(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 = join20(opts.projectRoot, ".jig", "tokens", modeFileName);
+    const modeAbsPath2 = join23(opts.projectRoot, ...tokensRelDir, modeFileName);
     modeAbsPaths[mode] = modeAbsPath2;
-    const modeRelPath = relKey(".jig", "tokens", modeFileName);
+    const modeRelPath = relKey(...tokensRelDir, modeFileName);
     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 = readFileSync15(join20(opts.packageRoot, "tokens", modeFileName), "utf8");
+      const modeSourceRaw = readFileSync18(join23(opts.packageRoot, "tokens", modeFileName), "utf8");
       const content = vendorHeader(modeFileName, opts.version, "css", null) + modeSourceRaw;
-      mkdirSync6(dirname7(modeAbsPath2), { recursive: true });
-      writeFileSync6(modeAbsPath2, content, "utf8");
+      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).`);
     }
   }
   const modeAbsPath = modeAbsPaths[primaryMode];
+  const brandFileOnly = brandRelPath.split("/").pop();
+  const barrelFor = (mode) => mode === primaryMode ? "theme.css" : `theme.${mode}.css`;
+  for (const mode of declaredModes) {
+    const rel = relKey(...tokensRelDir, barrelFor(mode));
+    const abs = join23(opts.projectRoot, ...tokensRelDir, barrelFor(mode));
+    const state = fileState(opts.projectRoot, abs, rel, initManifest);
+    if (state.existsOnDisk && (!state.tracked || state.modified)) {
+      log(`  ${rel} exists and is not jig-tracked (or has been edited) \u2014 leaving it alone.`);
+      continue;
+    }
+    const content = barrelBody(barrelFor(mode), brandFileOnly, mode, opts.version);
+    mkdirSync5(dirname6(abs), { recursive: true });
+    writeFileSync4(abs, content, "utf8");
+    files[rel] = checksum(content);
+  }
+  if (declaredModes.length > 1) {
+    log("\nOne barrel per surface. Import each at that route's entry point:");
+    for (const surface of effectiveConfig.surfaces) {
+      log(`  '${surface.match}' \u2192 ${relKey(...tokensRelDir, barrelFor(surface.mode))}`);
+    }
+  }
   writeInitManifest(opts.projectRoot, { version: opts.version, modes: declaredModes, files });
   const wireTarget = findWireTarget(detection);
   let wiring;
   if (wireTarget) {
-    const targetAbsDir = dirname7(join20(opts.projectRoot, wireTarget));
-    const brandImport = relativeImportPath(targetAbsDir, wiringBrandAbsPath);
-    const modeImport = relativeImportPath(targetAbsDir, modeAbsPath);
-    const snippet = `@import "${brandImport}";
-@import "${modeImport}";`;
+    const targetAbsDir = dirname6(join23(opts.projectRoot, wireTarget));
+    const barrelImport = relativeImportPath(
+      targetAbsDir,
+      join23(opts.projectRoot, ...tokensRelDir, "theme.css")
+    );
+    const snippet = `@import "${barrelImport}";`;
     try {
-      const outcome = wireImport(join20(opts.projectRoot, wireTarget), brandImport, modeImport, primaryMode);
+      const outcome = wireBarrel(join23(opts.projectRoot, wireTarget), barrelImport);
       wiring = { target: wireTarget, status: outcome.status, snippet };
       const verb = outcome.status === "wired" ? "Wired" : outcome.status === "rewired" ? "Rewired" : "Already present in";
       log(`
@@ -3356,7 +3788,7 @@ Could not write to ${wireTarget}: ${err.message}`);
     if (pasteTargets.length > 0) {
       log("Paste the block for whichever of these is your global stylesheet:");
       for (const target of pasteTargets) {
-        const dir = dirname7(join20(opts.projectRoot, target));
+        const dir = dirname6(join23(opts.projectRoot, target));
         const forTarget = `@import "${relativeImportPath(dir, wiringBrandAbsPath)}";
 @import "${relativeImportPath(dir, modeAbsPath)}";`;
         log(`
@@ -3397,7 +3829,7 @@ Could not write to ${wireTarget}: ${err.message}`);
 
 // src/index.ts
 var packageRoot = getPackageRoot();
-var { version } = JSON.parse(readFileSync16(join21(packageRoot, "package.json"), "utf8"));
+var { version } = JSON.parse(readFileSync19(join24(packageRoot, "package.json"), "utf8"));
 function warnIfUnpublishedPin() {
   if (isPublishedBuild(packageRoot)) return;
   console.warn(
@@ -3434,9 +3866,9 @@ program.command("install").description("Install Jig rules and the agent skill fi
     process.exit(1);
   }
 });
-program.command("explain").description("Print a rule's full text, its correction, and the version it was introduced in.").argument("<rule-id>", "a rule id, e.g. 'C-19' or 'P-02'").action((ruleId) => {
+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, version }));
+    console.log(explain({ ruleId: query ?? "", version, list: options.list }));
   } catch (err) {
     console.error(err.message);
     process.exit(1);