jig-ui 0.4.0 → 0.5.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 readFileSync17 } from "fs";
 import { homedir } from "os";
-import { join as join21 } from "path";
+import { join as join22 } from "path";
 
 // src/paths.ts
 import { existsSync } from "fs";
@@ -42,8 +42,8 @@ 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.";
@@ -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 existsSync10, readFileSync as readFileSync12 } from "fs";
+import { join as join17 } 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()) {
@@ -1473,8 +1537,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 +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();
@@ -1531,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;
@@ -2514,7 +2584,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 +2598,63 @@ 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();
-  for (const file of files) {
-    const source = readFileSync10(join15(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 = join16(".jig", "rules.index.json");
+var LEGACY_INDEX_REL = join17(".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 = join17(projectRoot, LEGACY_INDEX_REL);
+  if (existsSync10(legacy)) return legacy;
+  return join17(assetRoot(), "rules.index.json");
 }
 function resolveMode(projectRoot) {
   try {
-    const config = JSON.parse(readFileSync11(join16(projectRoot, "jig.config.json"), "utf8"));
+    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";
@@ -2576,23 +2671,23 @@ function summariseUnscanned(files) {
 }
 function countSpecs() {
   try {
-    return loadSpecs(join16(assetRoot(), "rules")).length;
+    return loadSpecs(join17(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(readFileSync12(indexPath, "utf8")));
   const selection = selectFiles(opts.projectRoot, opts.all);
   const { files } = selection;
   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(readFileSync12(join17(opts.projectRoot, f), "utf8"), tokens);
     } catch {
       return false;
     }
@@ -2605,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(readFileSync11(join16(opts.projectRoot, f), "utf8"), tokens);
+        return !participatesInTokenLayer(readFileSync12(join17(opts.projectRoot, f), "utf8"), tokens);
       } catch {
         return true;
       }
@@ -2626,12 +2721,12 @@ function check(opts) {
 }
 
 // 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 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 readFileSync12 } from "fs";
-import { join as join17 } 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/;
@@ -2648,7 +2743,7 @@ var FRAMEWORK_DEPS = [
 function detectFramework(projectRoot) {
   let pkg;
   try {
-    pkg = JSON.parse(readFileSync12(join17(projectRoot, "package.json"), "utf8"));
+    pkg = JSON.parse(readFileSync13(join18(projectRoot, "package.json"), "utf8"));
   } catch {
     return void 0;
   }
@@ -2666,7 +2761,7 @@ function detect(projectRoot) {
   for (const f of cssFiles) {
     let source;
     try {
-      source = readFileSync12(join17(projectRoot, f), "utf8");
+      source = readFileSync13(join18(projectRoot, f), "utf8");
     } catch {
       continue;
     }
@@ -2701,8 +2796,8 @@ function isIgnored(projectRoot, relPath) {
 }
 
 // src/init/derive.ts
-import { readFileSync as readFileSync13 } from "fs";
-import { join as join18 } from "path";
+import { readFileSync as readFileSync14 } from "fs";
+import { join as join19 } from "path";
 var DEFAULT_PROPOSAL = {
   h: 264,
   s: 0,
@@ -2735,7 +2830,7 @@ function fromCssCustomProperties(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync13(join18(projectRoot, file), "utf8");
+      source = readFileSync14(join19(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -2784,7 +2879,7 @@ function balancedBraceBody(source, openIdx) {
 function fromTailwindConfig(projectRoot, tailwindConfigFile) {
   let source;
   try {
-    source = readFileSync13(join18(projectRoot, tailwindConfigFile), "utf8");
+    source = readFileSync14(join19(projectRoot, tailwindConfigFile), "utf8");
   } catch {
     return null;
   }
@@ -2840,7 +2935,7 @@ function fromLiteralFrequency(projectRoot, cssFiles) {
   for (const file of cssFiles) {
     let source;
     try {
-      source = readFileSync13(join18(projectRoot, file), "utf8");
+      source = readFileSync14(join19(projectRoot, file), "utf8");
     } catch {
       continue;
     }
@@ -3000,8 +3095,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 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, "");
@@ -3009,7 +3104,7 @@ function slugify(name) {
 }
 function deriveProjectSlug(projectRoot) {
   try {
-    const pkg = JSON.parse(readFileSync14(join19(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 {
   }
@@ -3075,7 +3170,7 @@ function parseSurfaces(answer, fallback) {
   return parsed.length > 0 ? parsed : fallback;
 }
 function fileState(projectRoot, absPath, relPath, initManifest) {
-  const existsOnDisk = existsSync10(absPath);
+  const existsOnDisk = existsSync11(absPath);
   const tracked = !!initManifest && relPath in initManifest.files;
   const modified = tracked && isInitFileModified(projectRoot, relPath, initManifest);
   return { existsOnDisk, tracked, modified };
@@ -3086,11 +3181,11 @@ function isValidSurfaceArray(v) {
   );
 }
 function loadEffectiveConfig(projectRoot, configAbsPath, fallbackBrand, fallbackSurfaces) {
-  if (!existsSync10(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
+  if (!existsSync11(configAbsPath)) return { brand: fallbackBrand, surfaces: fallbackSurfaces };
   try {
-    const parsed = JSON.parse(readFileSync15(configAbsPath, "utf8"));
+    const parsed = JSON.parse(readFileSync16(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 ? existsSync11(join21(projectRoot, ...brandCandidate.split("/"))) : false;
     return {
       brand: brandResolves ? brandCandidate : fallbackBrand,
       surfaces: isValidSurfaceArray(parsed.surfaces) ? parsed.surfaces : fallbackSurfaces
@@ -3116,7 +3211,7 @@ function insertAfterCharset(content, insertion) {
   return content.slice(0, charsetLen) + insertion + content.slice(charsetLen);
 }
 function wireImport(absPath, brandImport, modeImport, mode) {
-  const content = existsSync10(absPath) ? readFileSync15(absPath, "utf8") : "";
+  const content = existsSync11(absPath) ? readFileSync16(absPath, "utf8") : "";
   const brandImportLine = `@import "${brandImport}";`;
   const modeImportLine = `@import "${modeImport}";`;
   const brandPresent = content.includes(brandImportLine);
@@ -3129,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);
-      writeFileSync6(absPath, next3, "utf8");
+      writeFileSync4(absPath, next3, "utf8");
       return { status: "rewired", detail: `rewired mode: ${previousMode} \u2192 ${mode}` };
     }
     const brandIdx = content.indexOf(brandImportLine);
@@ -3137,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);
-    writeFileSync6(absPath, next2, "utf8");
+    writeFileSync4(absPath, next2, "utf8");
     return { status: "rewired", detail: `added missing mode import: ${mode}` };
   }
   const lines = `${brandImportLine}
@@ -3152,8 +3247,8 @@ ${modeImportLine}
     next = insertAfterCharset(content, content ? `${lines}
 ` : lines);
   }
-  mkdirSync6(dirname7(absPath), { recursive: true });
-  writeFileSync6(absPath, next, "utf8");
+  mkdirSync5(dirname6(absPath), { recursive: true });
+  writeFileSync4(absPath, next, "utf8");
   return { status: "wired" };
 }
 async function init(opts) {
@@ -3235,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 = join20(opts.projectRoot, ".jig", "tokens", brandFileName(projectSlug));
+  const brandAbsPath = join21(opts.projectRoot, ".jig", "tokens", brandFileName(projectSlug));
   const configRelPath = "jig.config.json";
-  const configAbsPath = join20(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);
@@ -3266,44 +3361,44 @@ ${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 = readFileSync16(join21(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(readFileSync16(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 ? 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)}
 `;
-    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 = 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 = join20(opts.projectRoot, ".jig", "tokens", modeFileName);
+    const modeAbsPath2 = join21(opts.projectRoot, ".jig", "tokens", modeFileName);
     modeAbsPaths[mode] = modeAbsPath2;
     const modeRelPath = relKey(".jig", "tokens", modeFileName);
     const modeState = fileState(opts.projectRoot, modeAbsPath2, modeRelPath, initManifest);
@@ -3311,10 +3406,10 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
     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 = readFileSync16(join21(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).`);
@@ -3325,13 +3420,13 @@ ${configRelPath} already exists and was not created by 'jig init' (or has been e
   const wireTarget = findWireTarget(detection);
   let wiring;
   if (wireTarget) {
-    const targetAbsDir = dirname7(join20(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(join20(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(`
@@ -3356,7 +3451,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(join21(opts.projectRoot, target));
         const forTarget = `@import "${relativeImportPath(dir, wiringBrandAbsPath)}";
 @import "${relativeImportPath(dir, modeAbsPath)}";`;
         log(`
@@ -3397,7 +3492,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(readFileSync17(join22(packageRoot, "package.json"), "utf8"));
 function warnIfUnpublishedPin() {
   if (isPublishedBuild(packageRoot)) return;
   console.warn(
@@ -3434,9 +3529,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);