concept-atlas-dense-explain 2.0.0 → 3.0.0

package/README.md

@@ -26,9 +26,9 @@ npx concept-atlas-dense-explain validate topic.mdx --mode atlas
 npx concept-atlas-dense-explain topic.mdx --mode atlas
 ```
 
-`guide` and `create` refuse to overwrite an existing file unless `--force` is
-passed. Use `-o` to choose the output path (a directory when passing several
-inputs). Validation errors abort the build; `--no-validate` forces a knowingly
+Existing outputs are overwritten; `--force` is accepted for compatibility and is
+a no-op. `--mode` defaults to `scroll`. Use `-o` to choose the output path (a
+directory when passing several inputs). Validation errors abort the build; `--no-validate` forces a knowingly
 broken build.
 
 Mermaid loads from a CDN at runtime by default (fast builds, needs network);

package/bin/cli.mjs

@@ -1,11 +1,31 @@
 #!/usr/bin/env node
-import { access, constants, copyFile, cp, mkdir, readFile, rm, rename, writeFile } from 'node:fs/promises';
+import {
+  access,
+  constants,
+  copyFile,
+  cp,
+  mkdir,
+  readFile,
+  rm,
+  rename,
+  writeFile
+} from 'node:fs/promises';
 import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { build } from 'vite';
 import { fileURLToPath } from 'node:url';
-import { validateMdxSource, countBySeverity, detectFeatures, extractPageTitle } from '../template/src/model/validate-content.js';
-import { SKINS, normalizeSkin, COMPONENT_STYLES, normalizeStyle } from '../template/src/model/skins.js';
+import {
+  validateMdxSource,
+  countBySeverity,
+  detectFeatures,
+  extractPageTitle
+} from '../template/src/model/validate-content.js';
+import {
+  SKINS,
+  normalizeSkin,
+  COMPONENT_STYLES,
+  normalizeStyle
+} from '../template/src/model/skins.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const templateRoot = path.join(packageRoot, 'template');
@@ -14,26 +34,50 @@ let buildCounter = 0;
 
 function usage() {
   console.log('Usage:');
-  console.log('  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [-o output.html|dir] [--force] [--concurrency N] [--inline-assets] [--inline-mermaid] [--mermaid-cdn <url>] [--json] [--no-validate]');
+  console.log(
+    '  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [-o output.html|dir] [--concurrency N] [--inline-assets] [--inline-mermaid] [--mermaid-cdn <url>] [--json] [--no-validate]'
+  );
   console.log('  npx concept-atlas-dense-explain render <input.mdx>... [-o output.html|dir]');
-  console.log('  npx concept-atlas-dense-explain validate <input.mdx> [--mode atlas|scroll] [--strict] [--json]');
-  console.log('  npx concept-atlas-dense-explain create <output.mdx> [--mode atlas|scroll] [--force]');
-  console.log('  npx concept-atlas-dense-explain guide [--mode atlas|scroll] [-o output.mdx] [--force]');
+  console.log(
+    '  npx concept-atlas-dense-explain validate <input.mdx> [--mode atlas|scroll] [--strict] [--json]'
+  );
+  console.log('  npx concept-atlas-dense-explain create <output.mdx> [--mode atlas|scroll]');
+  console.log('  npx concept-atlas-dense-explain guide [--mode atlas|scroll] [-o output.mdx]');
   console.log('');
+  console.log(
+    '  --mode defaults to scroll. Existing outputs are overwritten; --force is accepted for compatibility and is a no-op.'
+  );
   console.log('  --help shows this text; --version prints the package version.');
-  console.log('  Multiple inputs build in parallel (default 2 at a time, cap 4); -o is then a directory.');
-  console.log('  Figures are kept as relative links by default (small HTML; ship the assets/ dir beside it). --inline-assets bakes every local image into the HTML as base64 instead; a per-tag inline={true|false} on <Figure> overrides that for one image. --link-assets is kept as an explicit alias for the default.');
-  console.log('  Mermaid diagrams load from a CDN at runtime by default (fast builds, needs network); --inline-mermaid bakes Mermaid into the HTML for a fully offline single file; --mermaid-cdn overrides the CDN URL.');
-  console.log(`  --skin bakes a default palette (${SKINS.map(skin => skin.id).join(', ')}); --default-mode bakes a default dark/light mode; --style bakes a default component style (${COMPONENT_STYLES.map(style => style.id).join(', ')}). Readers can still switch in the UI.`);
+  console.log(
+    '  Multiple inputs build in parallel (default 2 at a time, cap 4); -o is then a directory.'
+  );
+  console.log(
+    '  Figures are kept as relative links by default (small HTML; ship the assets/ dir beside it). --inline-assets bakes every local image into the HTML as base64 instead; a per-tag inline={true|false} on <Figure> overrides that for one image. --link-assets is kept as an explicit alias for the default.'
+  );
+  console.log(
+    '  Mermaid diagrams load from a CDN at runtime by default (fast builds, needs network); --inline-mermaid bakes Mermaid into the HTML for a fully offline single file; --mermaid-cdn overrides the CDN URL.'
+  );
+  console.log(
+    `  --skin bakes a default palette (${SKINS.map(skin => skin.id).join(', ')}); --default-mode bakes a default dark/light mode; --style bakes a default component style (${COMPONENT_STYLES.map(style => style.id).join(', ')}). Readers can still switch in the UI.`
+  );
 }
 
 async function exists(filePath) {
-  try { await access(filePath, constants.F_OK); return true; } catch { return false; }
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 /** Byte size of an asset, or null when it does not exist. */
 function assetByteSize(filePath) {
-  try { return statSync(filePath).size; } catch { return null; }
+  try {
+    return statSync(filePath).size;
+  } catch {
+    return null;
+  }
 }
 
 function flagValue(flags, names) {
@@ -50,8 +94,29 @@ function fail(message) {
   process.exit(1);
 }
 
-const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style', '--mermaid-cdn']);
-const BOOLEAN_FLAGS = new Set(['--force', '--json', '--strict', '--no-validate', '--link-assets', '--inline-assets', '--inline-mermaid', '--help', '-h', '--version', '-v']);
+const VALUE_FLAGS = new Set([
+  '--mode',
+  '-o',
+  '--output',
+  '--concurrency',
+  '--skin',
+  '--default-mode',
+  '--style',
+  '--mermaid-cdn'
+]);
+const BOOLEAN_FLAGS = new Set([
+  '--force',
+  '--json',
+  '--strict',
+  '--no-validate',
+  '--link-assets',
+  '--inline-assets',
+  '--inline-mermaid',
+  '--help',
+  '-h',
+  '--version',
+  '-v'
+]);
 const COMMAND_NAMES = ['help', 'create', 'new', 'render', 'validate', 'guide'];
 
 /** Splits argv into flags, flag values and positional arguments. */
@@ -82,7 +147,10 @@ function extractCommand(argv) {
   const rest = [...argv];
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
-    if (VALUE_FLAGS.has(arg)) { i += 1; continue; }
+    if (VALUE_FLAGS.has(arg)) {
+      i += 1;
+      continue;
+    }
     if (arg.startsWith('-') && arg.length > 1) continue;
     if (COMMAND_NAMES.includes(arg)) {
       rest.splice(i, 1);
@@ -105,7 +173,9 @@ function resolveOutputs(inputs, explicit) {
   if (path.extname(target).toLowerCase() === '.html') {
     fail('`-o` must be a directory when building more than one input.');
   }
-  return inputs.map(input => path.join(target, `${path.basename(input, path.extname(input))}.html`));
+  return inputs.map(input =>
+    path.join(target, `${path.basename(input, path.extname(input))}.html`)
+  );
 }
 
 function printDiagnostics(source, options, { json, label = null, quiet = false }) {
@@ -123,7 +193,9 @@ function printDiagnostics(source, options, { json, label = null, quiet = false }
     console.error(`${severity} ${where}  ${item.code}  ${item.message}`);
   }
   const { error, warning } = countBySeverity(diagnostics);
-  const scope = carrier ? `${carrier} · ${stats.nodes} 节点 / ${stats.relations} 关系` : '未识别载体';
+  const scope = carrier
+    ? `${carrier} · ${stats.nodes} 节点 / ${stats.relations} 关系`
+    : '未识别载体';
   if (error) console.error(`校验失败：${error} 个错误，${warning} 个警告（${scope}）`);
   else if (warning) console.error(`校验通过：${warning} 个警告（${scope}）`);
   else console.error(`校验通过：无问题（${scope}）`);
@@ -133,7 +205,10 @@ function printDiagnostics(source, options, { json, label = null, quiet = false }
 const { command, rest } = extractCommand(args);
 args = rest;
 
-if (args.includes('--help') || args.includes('-h')) { usage(); process.exit(0); }
+if (args.includes('--help') || args.includes('-h')) {
+  usage();
+  process.exit(0);
+}
 if (args.includes('--version') || args.includes('-v')) {
   const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
   console.log(pkg.version);
@@ -155,16 +230,17 @@ for (let i = 0; i < args.length; i += 1) {
   }
 }
 
-if (command === 'help') { usage(); process.exit(0); }
+if (command === 'help') {
+  usage();
+  process.exit(0);
+}
 
 if (command === 'guide') {
-  const mode = flagValue(args, ['--mode']) || 'atlas';
+  const mode = flagValue(args, ['--mode']) || 'scroll';
   if (!['atlas', 'scroll'].includes(mode)) fail(`Unknown mode: ${mode}`);
-  const output = path.resolve(flagValue(args, ['-o', '--output']) || `concept-atlas-${mode}-guide.mdx`);
-  if (await exists(output) && !args.includes('--force')) {
-    console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
-    process.exit(1);
-  }
+  const output = path.resolve(
+    flagValue(args, ['-o', '--output']) || `concept-atlas-${mode}-guide.mdx`
+  );
   const source = path.join(templateRoot, 'references', `${mode}-guide.mdx`);
   if (!(await exists(source))) {
     console.error(`Guide for mode "${mode}" is missing from the package.`);
@@ -174,7 +250,7 @@ if (command === 'guide') {
   await copyFile(source, output);
   const assetsSource = path.join(templateRoot, 'references', 'assets');
   const assetsTarget = path.join(path.dirname(output), 'assets');
-  if (await exists(assetsSource) && path.resolve(assetsSource) !== path.resolve(assetsTarget) && (args.includes('--force') || !(await exists(assetsTarget)))) {
+  if ((await exists(assetsSource)) && path.resolve(assetsSource) !== path.resolve(assetsTarget)) {
     await cp(assetsSource, assetsTarget, { recursive: true, force: true });
     console.log(`Copied guide assets to ${assetsTarget}`);
   }
@@ -185,17 +261,19 @@ if (command === 'guide') {
 
 if (command === 'create' || command === 'new') {
   const output = args[0] ? path.resolve(args[0]) : null;
-  const mode = flagValue(args, ['--mode']) || 'atlas';
-  if (!output || path.extname(output).toLowerCase() !== '.mdx' || !['atlas', 'scroll'].includes(mode)) {
+  const mode = flagValue(args, ['--mode']) || 'scroll';
+  if (
+    !output ||
+    path.extname(output).toLowerCase() !== '.mdx' ||
+    !['atlas', 'scroll'].includes(mode)
+  ) {
     usage();
     process.exit(1);
   }
-  if (await exists(output) && !args.includes('--force')) {
-    console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
-    process.exit(1);
-  }
   await mkdir(path.dirname(output), { recursive: true });
-  const template = mode === 'atlas' ? `\
+  const template =
+    mode === 'atlas'
+      ? `\
 {/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ExplainPage id="topic-id" title="主题名称" summary="用一句话说明这个主题解决什么问题。">
   <ConceptGraph root="root-node">
@@ -221,7 +299,8 @@ if (command === 'create' || command === 'new') {
     <Relation from="first-branch" to="second-branch" type="depends-on" label="依赖" />
   </ConceptGraph>
 </ExplainPage>
-` : `\
+`
+      : `\
 {/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ScrollDocument>
   <ScrollHeader title="主题名称">用一两句话说明主题、背景和读者应该带走的判断。</ScrollHeader>
@@ -247,7 +326,9 @@ if (command === 'create' || command === 'new') {
 `;
   await writeFile(output, template, 'utf8');
   console.log(`Created ${mode} MDX template: ${output}`);
-  console.log(`Tip: run "npx concept-atlas-dense-explain guide --mode ${mode}" for a full component reference.`);
+  console.log(
+    `Tip: run "npx concept-atlas-dense-explain guide --mode ${mode}" for a full component reference.`
+  );
   process.exit(0);
 }
 
@@ -255,7 +336,6 @@ const parsed = parseFlags(args);
 const json = parsed.flags.has('--json');
 const strict = parsed.flags.has('--strict');
 const skipValidate = parsed.flags.has('--no-validate');
-const force = parsed.flags.has('--force');
 const linkAssets = parsed.flags.has('--link-assets');
 const inlineAssets = parsed.flags.has('--inline-assets');
 if (linkAssets && inlineAssets) {
@@ -270,18 +350,25 @@ const modeFlag = parsed.values.get('--mode') || null;
 let skinFlag = null;
 if (parsed.values.has('--skin')) {
   skinFlag = normalizeSkin(parsed.values.get('--skin'));
-  if (!skinFlag) fail(`Unknown skin: ${parsed.values.get('--skin')} (available: ${SKINS.map(skin => skin.id).join(', ')})`);
+  if (!skinFlag)
+    fail(
+      `Unknown skin: ${parsed.values.get('--skin')} (available: ${SKINS.map(skin => skin.id).join(', ')})`
+    );
 }
 let defaultModeFlag = null;
 if (parsed.values.has('--default-mode')) {
   const raw = parsed.values.get('--default-mode');
-  if (!['dark', 'light', 'system'].includes(raw)) fail(`Invalid --default-mode: ${raw} (use dark, light or system)`);
+  if (!['dark', 'light', 'system'].includes(raw))
+    fail(`Invalid --default-mode: ${raw} (use dark, light or system)`);
   defaultModeFlag = raw;
 }
 let styleFlag = null;
 if (parsed.values.has('--style')) {
   styleFlag = normalizeStyle(parsed.values.get('--style'));
-  if (!styleFlag) fail(`Unknown component style: ${parsed.values.get('--style')} (available: ${COMPONENT_STYLES.map(style => style.id).join(', ')})`);
+  if (!styleFlag)
+    fail(
+      `Unknown component style: ${parsed.values.get('--style')} (available: ${COMPONENT_STYLES.map(style => style.id).join(', ')})`
+    );
 }
 
 if (command === 'validate') {
@@ -290,21 +377,26 @@ if (command === 'validate') {
     fail('Provide an existing .mdx file to validate.');
   }
   const source = await readFile(target, 'utf8');
-  const result = printDiagnostics(source, {
-    filePath: target,
-    mode: modeFlag,
-    strict,
-    inlineAssets,
-    assetExists: spec => existsSync(path.resolve(path.dirname(target), spec)),
-    assetSize: spec => assetByteSize(path.resolve(path.dirname(target), spec)),
-  }, { json });
+  const result = printDiagnostics(
+    source,
+    {
+      filePath: target,
+      mode: modeFlag,
+      strict,
+      inlineAssets,
+      assetExists: spec => existsSync(path.resolve(path.dirname(target), spec)),
+      assetSize: spec => assetByteSize(path.resolve(path.dirname(target), spec))
+    },
+    { json }
+  );
   process.exit(countBySeverity(result.diagnostics).error ? 1 : 0);
 }
 
 // `render` is the default command, so it may still appear as a leading token.
-const positional = parsed.positional[0] && parsed.positional[0].toLowerCase() === 'render'
-  ? parsed.positional.slice(1)
-  : parsed.positional;
+const positional =
+  parsed.positional[0] && parsed.positional[0].toLowerCase() === 'render'
+    ? parsed.positional.slice(1)
+    : parsed.positional;
 const inputs = positional.map(entry => path.resolve(entry));
 
 if (!inputs.length) {
@@ -321,28 +413,25 @@ for (const input of inputs) {
 
 const outputs = resolveOutputs(inputs, parsed.values.get('-o') || parsed.values.get('--output'));
 
-for (const output of outputs) {
-  if (await exists(output) && !force) {
-    console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
-    process.exit(1);
-  }
-}
-
 const multi = inputs.length > 1;
 const sources = await Promise.all(inputs.map(input => readFile(input, 'utf8')));
 
 // Validate every document before building any of them: a batch should fail as a
 // batch rather than leaving half the targets rendered.
-const validations = sources.map((source, index) => printDiagnostics(source, {
-  filePath: inputs[index],
-  mode: modeFlag,
-  strict,
-  inlineAssets,
-  assetExists: spec => existsSync(path.resolve(path.dirname(inputs[index]), spec)),
-  assetSize: spec => assetByteSize(path.resolve(path.dirname(inputs[index]), spec)),
-}, json
-  ? { json: false, quiet: true }
-  : { json: false, label: multi ? inputs[index] : null }));
+const validations = sources.map((source, index) =>
+  printDiagnostics(
+    source,
+    {
+      filePath: inputs[index],
+      mode: modeFlag,
+      strict,
+      inlineAssets,
+      assetExists: spec => existsSync(path.resolve(path.dirname(inputs[index]), spec)),
+      assetSize: spec => assetByteSize(path.resolve(path.dirname(inputs[index]), spec))
+    },
+    json ? { json: false, quiet: true } : { json: false, label: multi ? inputs[index] : null }
+  )
+);
 
 if (json) {
   const payload = multi
@@ -351,7 +440,10 @@ if (json) {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
 
-const errorCount = validations.reduce((sum, result) => sum + countBySeverity(result.diagnostics).error, 0);
+const errorCount = validations.reduce(
+  (sum, result) => sum + countBySeverity(result.diagnostics).error,
+  0
+);
 if (errorCount && !skipValidate) {
   console.error('内容校验未通过，已停止构建。修复后重试，或用 --no-validate 强制构建。');
   process.exit(1);
@@ -360,27 +452,47 @@ if (errorCount && !skipValidate) {
 const jobs = inputs.map((input, index) => {
   const mode = modeFlag || validations[index].carrier;
   if (!mode || !['atlas', 'scroll'].includes(mode)) {
-    console.error(`Could not detect the MDX carrier for ${input}; choose --mode atlas or --mode scroll.`);
+    console.error(
+      `Could not detect the MDX carrier for ${input}; choose --mode atlas or --mode scroll.`
+    );
     process.exit(1);
   }
   // Figures link by default. If the HTML is written outside the MDX's directory
   // its relative image paths no longer resolve, so warn unless --inline-assets
   // bakes them in.
-  if (!inlineAssets && path.resolve(path.dirname(outputs[index])) !== path.resolve(path.dirname(input))) {
-    console.error(`警告：默认外链图片，但 ${outputs[index]} 不在 ${path.dirname(input)} 内，相对图片路径会失效；请用 --inline-assets，或把 assets/ 一并放到输出目录。`);
+  if (
+    !inlineAssets &&
+    path.resolve(path.dirname(outputs[index])) !== path.resolve(path.dirname(input))
+  ) {
+    console.error(
+      `警告：默认外链图片，但 ${outputs[index]} 不在 ${path.dirname(input)} 内，相对图片路径会失效；请用 --inline-assets，或把 assets/ 一并放到输出目录。`
+    );
   }
-  return { input, output: outputs[index], mode, title: extractPageTitle(sources[index]), features: detectFeatures(sources[index]), inlineAssets };
+  return {
+    input,
+    output: outputs[index],
+    mode,
+    title: extractPageTitle(sources[index]),
+    features: detectFeatures(sources[index]),
+    inlineAssets
+  };
 });
 
 const limit = clampConcurrency(parsed.values.get('--concurrency'), jobs.length);
 const started = Date.now();
-const results = await runPool(jobs.map(job => () => buildOne(job)), limit);
+const results = await runPool(
+  jobs.map(job => () => buildOne(job)),
+  limit
+);
 
 const failures = results.filter(result => !result.ok);
 const saved = summarizeFeatures(jobs, results);
-console.log(`Built ${results.length - failures.length}/${results.length} page(s) with concurrency ${limit} in ${((Date.now() - started) / 1000).toFixed(1)}s${saved ? ` (${saved})` : ''}.`);
+console.log(
+  `Built ${results.length - failures.length}/${results.length} page(s) with concurrency ${limit} in ${((Date.now() - started) / 1000).toFixed(1)}s${saved ? ` (${saved})` : ''}.`
+);
 if (failures.length) {
-  for (const failure of failures) console.error(`Build failed for ${failure.input}:`, failure.error);
+  for (const failure of failures)
+    console.error(`Build failed for ${failure.input}:`, failure.error);
   process.exit(1);
 }
 
@@ -390,7 +502,10 @@ async function buildOne(job) {
   // Each build gets its own scratch outDir: the template always writes
   // `index.html`/`scroll.html`, so concurrent builds sharing a directory would
   // overwrite each other before the rename.
-  const scratch = path.join(path.dirname(output), `.concept-atlas-${process.pid}-${(buildCounter += 1)}`);
+  const scratch = path.join(
+    path.dirname(output),
+    `.concept-atlas-${process.pid}-${(buildCounter += 1)}`
+  );
   await mkdir(path.dirname(output), { recursive: true });
   await mkdir(scratch, { recursive: true });
   const define = { __ATLAS_FEATURES__: JSON.stringify(features) };
@@ -413,8 +528,8 @@ async function buildOne(job) {
       build: {
         outDir: scratch,
         emptyOutDir: false,
-        rollupOptions: { input: path.join(templateRoot, templateEntry) },
-      },
+        rollupOptions: { input: path.join(templateRoot, templateEntry) }
+      }
     });
     // Swap the new build in without a window where no output exists: on
     // POSIX rename replaces atomically; the fallback path (Windows can refuse
@@ -441,7 +556,9 @@ async function buildOne(job) {
       }
       if (hasBackup) await rm(backup, { force: true });
     }
-    console.log(`Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${inline ? '  [figures inlined]' : '  [figures linked]'}`);
+    console.log(
+      `Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${inline ? '  [figures inlined]' : '  [figures linked]'}`
+    );
     return { ok: true, input, output };
   } catch (error) {
     return { ok: false, input, output, error };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {

package/packaged-skill/SKILL.md

@@ -24,7 +24,7 @@ This is the only runner — there is nothing to look for. Do not search for a lo
    - `references/atlas-guide.mdx` (atlas) or `references/scroll-guide.mdx` (scroll)
    It is real, compilable MDX showing that shell's components and their exact props; search it for a component name instead of guessing, and do not look for component documentation anywhere else. Do not run `guide` for this.
    Run `npx concept-atlas-dense-explain guide --mode <mode> -o <file>` only when you specifically need a project-local copy to compile beside the page, and delete that copy when done.
-3. Start from a skeleton when useful: `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll`. `create` and `guide` refuse to overwrite an existing file unless `--force` is passed.
+3. Start from a skeleton when useful: `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll` (`--mode` defaults to `scroll`). `create` and `guide` overwrite their output, so never point them at a file you want to keep.
 4. Write the semantic MDX into the user's `.mdx` file (see Authoring rules).
 5. Validate before rendering:
    ```bash
@@ -34,7 +34,7 @@ This is the only runner — there is nothing to look for. Do not search for a lo
    Diagnostics are `CODE line:column message`. Fix all `error`s and re-run; address warnings when cheap.
 6. Compile: `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [--mermaid-cdn <url>]`. Output is a standalone HTML beside the MDX unless `-o` is given. Validation errors abort the build (`--no-validate` forces a knowingly broken build). **Mermaid stays on its runtime CDN by default — do not pass `--inline-mermaid` on your own.** Only add `--inline-mermaid` when the user explicitly asks for a fully offline single file, since it bloats the HTML with the whole Mermaid bundle.
 7. **Appearance (optional)**: pages ship a reader-facing appearance menu — palette (`aurora` indigo, `ember` gold, `verdant` forest, `sakura` pink-plum, `noir` ink), a dark/light toggle, and a component style pack (`manuscript` editorial marginalia, `classic` boxed cards, `shadcn` hairline-bordered minimal UI, `elastic` bordered observability panels). The shipped default is aurora × manuscript × light; choices persist in localStorage across both carriers. Bake different compile-time defaults with `--skin ember --default-mode dark --style classic` (or `CONCEPT_ATLAS_SKIN` / `CONCEPT_ATLAS_DEFAULT_MODE` / `CONCEPT_ATLAS_STYLE` on the repo build); `--default-mode` honors `dark`/`light` and resolves `system` to the carrier default (`light`). Bake a default only when the user asks for one — content MDX never sets appearance.
-8. For several documents, pass them all in one call: `npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist --force [--concurrency 3]` (`-o` is then a directory; everything validates first, then builds in parallel). Builds bundle only the heavy renderers the content uses: no `<Math>` skips KaTeX's ~1.4MB inlined fonts, and Mermaid stays on a CDN. Never add dummy `<Math>`/`<Mermaid>` nodes to "enable" them.
+8. For several documents, pass them all in one call: `npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist [--concurrency 3]` (`-o` is then a directory; everything validates first, then builds in parallel). Builds bundle only the heavy renderers the content uses: no `<Math>` skips KaTeX's ~1.4MB inlined fonts, and Mermaid stays on a CDN. Never add dummy `<Math>`/`<Mermaid>` nodes to "enable" them.
 9. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
 
 ## Carriers
@@ -47,12 +47,12 @@ This is the only runner — there is nothing to look for. Do not search for a lo
 ## Component families
 
 - Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `CodeBlock`, `Boundary`, `Example`, `Counterexample`, `Prerequisite`, `Input`, `Output`, `Glossary`
-- Argument and evidence: `Evidence`, `Invariant`, `FailureMode`, `Tradeoff`, `LearningObjectives`, `KeyQuestion`
-- Learning loop and provenance: `WorkedExample` + `Step`, `Quiz`, `KeyTakeaways`, `Source`, `Confidence`, `Term`
+- Argument and evidence: `Evidence`, `Invariant`, `FailureMode`, `Tradeoff`, `Checklist`, `LearningObjectives`, `KeyQuestion`
+- Learning loop and provenance: `WorkedExample` + `Step`, `Quiz`, `KeyTakeaways`, `Source`, `Confidence`, `LastReviewed`, `Term`
 - Information models: `Flow`, `Timeline`, `Compare`, `DecisionMatrix`, `FrameworkModel`, `MatrixModel`, `FormulaModel`, `PyramidModel`, `FunnelModel`
-- Data and behaviour: `DataTable`, `Metric`, `StateMachine`, `DecisionTree`, `FeedbackLoop`, `CodeDiff`
-- Reading and layout: `Insight`, `Callout`, `Details`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`, `ScrollPair`, `ScrollToc`
-- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `Figure` (alias `Image`), `FigureRef`, `Cite`, `References`
+- Data and behaviour: `DataTable`, `Metric`, `PropertyList`, `TreeView`, `StateMachine`, `DecisionTree`, `FeedbackLoop`, `CodeDiff`
+- Reading and layout: `Insight`, `Callout`, `Details`, `Quote`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`, `ScrollPair`, `ScrollToc`
+- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `CodeTabs`, `AnnotatedCode`, `Figure` (alias `Image`), `FigureRef`, `Cite`, `References`
 
 ## Authoring rules
 
@@ -67,6 +67,7 @@ This is the only runner — there is nothing to look for. Do not search for a lo
 - **Learning loop**: `WorkedExample` holds `Step` children; give each step a `reason` (the justification) so it teaches reasoning, not just the result. `Quiz question answer` reveals the answer on click with children as the explanation. `KeyTakeaways items={[...]}` closes a section.
 - **Provenance**: `Source kind="spec|rfc|implementation|experiment|experience" label href` marks one claim's origin inline; `Confidence level="high|medium|low" basis` wraps a claim with how strongly it is established; `Term name` (or children as the definition) gives an inline hover definition.
 - **Data and behaviour**: `DataTable headers={[...]} rows={[[...]]}` is the neutral table (no comparative stance). `Metric label value unit delta trend note` is one headline number — compose several with `Grid`/`ScrollGrid`. `StateMachine states={[{id,label,terminal}]} transitions={[{from,to,event,guard}]}` expresses cycles and guards. `DecisionTree branches={[{condition,outcome,tone,branches}]}` nests branches. `FeedbackLoop type="reinforcing|balancing" nodes={[{label,description}]}` closes a loop. `CodeDiff before after language` shows a change.
+- **Structure and code extensions**: `Quote author source href` attributes a quotation. `Checklist title items={[{text,status:'pass'|'fail'|'unknown'|'todo',note}]}` is a verification list. `PropertyList title items={[{name,value,note}]}` is a name/value spec ledger. `TreeView title items={[{label,description,children:[…]}]}` nests a hierarchy. `CodeTabs items={[{label,language,code}]} title caption lineNumbers` gives one collapsible listing per variant. `AnnotatedCode code language title notes={[{line,text}]}` numbers a listing and calls out specific lines. `LastReviewed date by note` is a review stamp.
 - **Figure**: a relative `src` (`./assets/diagram.png`) stays a relative link by default; compile with `--inline-assets` to bake every local image in as base64, or set `inline={true}` / `inline={false}` on one figure to override (precedence: per-figure prop > global flag > link). `http(s)` URLs stay links and warn (`ASSET_REMOTE`). Always set `alt`; a missing relative file warns (`ASSET_MISSING`) and shows a placeholder. Readers can click a figure to open it full-screen (zoom, drag, `Esc`) — mention it for diagram-heavy pages.
 - **Figure numbering**: give a figure an `id` and reference it with `<FigureRef id="..." />` to render "图 N". Numbering follows document order (per node in `atlas`, whole document in `scroll`) and reflows automatically, so never hand-write "图 1"; an explicit `label` still wins. A ref with no matching `id` warns (`FIGURE_REF_UNRESOLVED`).
 - **Figure size & cost**: linking keeps the HTML small but requires the output to sit beside the MDX's `assets/` (the CLI warns when `-o` points elsewhere). Inlining is what makes a screenshot-heavy page large (a page with no heavy renderers otherwise lands near 250KB), and an inlined asset over 512KB warns (`ASSET_LARGE`). Decide the trade-off with the user instead of choosing silently.

package/packaged-skill/references/scroll-guide.mdx

@@ -175,6 +175,20 @@ npm run dev`}</CodeBlock>
     </ScrollGrid>
   </ScrollSection>
 
+  <ScrollSection title="扩展组件：引用、清单、规格与结构">
+    <ScrollProse>以下组件补齐了引用、验证清单、规格表、显式层级与代码注解的表达缺口。</ScrollProse>
+    <Quote author="Donald Knuth" source="Literate Programming">程序首先是写给人读的，只是顺便让机器执行。</Quote>
+    <LastReviewed date="2026-09-29" by="架构组" note="随 ABI 变更重审" />
+    <Checklist title="上线前验证" items={[{text:'依赖已锁定',status:'pass'},{text:'压测通过',status:'fail',note:'P99 仍超标 12%'},{text:'回滚脚本演练',status:'todo'},{text:'灰度范围确认',status:'unknown'}]} />
+    <ScrollGrid columns="2">
+      <TreeView title="模块结构" items={[{label:'core',description:'内核',children:[{label:'scheduler'},{label:'memory',children:[{label:'allocator'}]}]}]} />
+      <PropertyList title="运行时参数" items={[{name:'heap',value:'4Gi',note:'按峰值负载预留'},{name:'gc',value:'zgc'},{name:'timeout',value:'30s'}]} />
+    </ScrollGrid>
+    <CodeTabs title="同一逻辑的两种写法" items={[{label:'JavaScript',language:'javascript',code:'const sum = ns.reduce((a, n) => a + n, 0);'},{label:'Rust',language:'rust',code:'let sum: i64 = ns.iter().sum();'}]} />
+    <AnnotatedCode language="bash" title="定位动态链接问题" code={`ldd app
+readelf -d app | head`} notes={[{line:1,text:'列出动态依赖，缺失项会显示 not found'},{line:2,text:'确认 .dynamic 段与 SONAME'}]} />
+  </ScrollSection>
+
   <ScrollSection title="参考文献">
     <References title="本页引用" items={[{id:'tufte1983',authors:'Tufte, E. R.',year:'1983',title:'The Visual Display of Quantitative Information',source:'Graphics Press',note:'关于以图形压缩与呈现证据的经典论述。'}]} />
   </ScrollSection>

package/template/references/scroll-guide.mdx

@@ -175,6 +175,20 @@ npm run dev`}</CodeBlock>
     </ScrollGrid>
   </ScrollSection>
 
+  <ScrollSection title="扩展组件：引用、清单、规格与结构">
+    <ScrollProse>以下组件补齐了引用、验证清单、规格表、显式层级与代码注解的表达缺口。</ScrollProse>
+    <Quote author="Donald Knuth" source="Literate Programming">程序首先是写给人读的，只是顺便让机器执行。</Quote>
+    <LastReviewed date="2026-09-29" by="架构组" note="随 ABI 变更重审" />
+    <Checklist title="上线前验证" items={[{text:'依赖已锁定',status:'pass'},{text:'压测通过',status:'fail',note:'P99 仍超标 12%'},{text:'回滚脚本演练',status:'todo'},{text:'灰度范围确认',status:'unknown'}]} />
+    <ScrollGrid columns="2">
+      <TreeView title="模块结构" items={[{label:'core',description:'内核',children:[{label:'scheduler'},{label:'memory',children:[{label:'allocator'}]}]}]} />
+      <PropertyList title="运行时参数" items={[{name:'heap',value:'4Gi',note:'按峰值负载预留'},{name:'gc',value:'zgc'},{name:'timeout',value:'30s'}]} />
+    </ScrollGrid>
+    <CodeTabs title="同一逻辑的两种写法" items={[{label:'JavaScript',language:'javascript',code:'const sum = ns.reduce((a, n) => a + n, 0);'},{label:'Rust',language:'rust',code:'let sum: i64 = ns.iter().sum();'}]} />
+    <AnnotatedCode language="bash" title="定位动态链接问题" code={`ldd app
+readelf -d app | head`} notes={[{line:1,text:'列出动态依赖，缺失项会显示 not found'},{line:2,text:'确认 .dynamic 段与 SONAME'}]} />
+  </ScrollSection>
+
   <ScrollSection title="参考文献">
     <References title="本页引用" items={[{id:'tufte1983',authors:'Tufte, E. R.',year:'1983',title:'The Visual Display of Quantitative Information',source:'Graphics Press',note:'关于以图形压缩与呈现证据的经典论述。'}]} />
   </ScrollSection>