concept-atlas-dense-explain 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Concept Atlas contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# concept-atlas-dense-explain
+
+Compile semantic MDX into a standalone, interactive Concept Atlas HTML page. The
+same workflow ships as an AI-agent skill, so an agent can generate, validate and
+render a "dense explainer" without hand-writing any layout.
+
+Two page shells share one component library:
+
+- `atlas` — concept graph with node navigation (`ExplainPage` → `ConceptGraph` → `ConceptNode`)
+- `scroll` — continuous document with an auto-built table of contents
+
+## CLI
+
+```bash
+# Learn the components from a real, compilable reference
+npx concept-atlas-dense-explain guide --mode atlas -o atlas-guide.mdx
+npx concept-atlas-dense-explain guide --mode scroll -o scroll-guide.mdx
+
+# Scaffold a document skeleton
+npx concept-atlas-dense-explain create topic.mdx --mode atlas
+
+# Validate structure before building
+npx concept-atlas-dense-explain validate topic.mdx --mode atlas
+
+# Compile to a standalone HTML file beside the MDX
+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
+broken build.
+
+Mermaid loads from a CDN at runtime by default (fast builds, needs network);
+`--inline-mermaid` bakes it into the HTML for a fully offline single file, and
+`--mermaid-cdn` overrides the CDN URL. Appearance defaults can be baked with
+`--skin`, `--default-mode` and `--style`; readers can still switch in the UI.
+
+Run `npx concept-atlas-dense-explain help` for the full flag list.
+
+## Links
+
+- Repository: https://github.com/wurenrumian/concept-atlas
+- Framework guide: [`docs/FRAMEWORK.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/FRAMEWORK.md)
+- Usage recipes: [`docs/USAGE.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/USAGE.md)
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -9,7 +9,7 @@ import { SKINS, normalizeSkin, COMPONENT_STYLES, normalizeStyle } from '../templ
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const templateRoot = path.join(packageRoot, 'template');
-const args = process.argv.slice(2);
+let args = process.argv.slice(2);
 let buildCounter = 0;
 
 function usage() {
@@ -20,6 +20,7 @@ function usage() {
   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('');
+  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('  --link-assets keeps figures as relative links instead of inlining them as base64.');
   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.');
@@ -45,6 +46,8 @@ function fail(message) {
 }
 
 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-mermaid', '--help', '-h', '--version', '-v']);
+const COMMAND_NAMES = ['help', 'create', 'new', 'render', 'validate', 'guide'];
 
 /** Splits argv into flags, flag values and positional arguments. */
 function parseFlags(argv) {
@@ -65,6 +68,26 @@ function parseFlags(argv) {
   return { flags, values, positional };
 }
 
+/**
+ * Finds the subcommand even when flags precede it (`--force create x.mdx`),
+ * skipping flag values so a value like `create` isn't mistaken for a command.
+ * The first non-flag token that isn't a command means `render` with inputs.
+ */
+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 (arg.startsWith('-') && arg.length > 1) continue;
+    if (COMMAND_NAMES.includes(arg)) {
+      rest.splice(i, 1);
+      return { command: arg, rest };
+    }
+    return { command: 'render', rest };
+  }
+  return { command: 'render', rest };
+}
+
 /**
  * A single input may name an output file; a batch needs a directory, because the
  * per-target file names come from the inputs.
@@ -102,7 +125,30 @@ function printDiagnostics(source, options, { json, label = null, quiet = false }
   return result;
 }
 
-const command = ['help', 'create', 'new', 'render', 'validate', 'guide'].includes(args[0]) ? args.shift() : 'render';
+const { command, rest } = extractCommand(args);
+args = rest;
+
+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);
+  process.exit(0);
+}
+
+// Typos like `--mdoe atlas` used to be accepted silently; fail fast instead.
+for (let i = 0; i < args.length; i += 1) {
+  const arg = args[i];
+  if (VALUE_FLAGS.has(arg)) {
+    if (i + 1 >= args.length || (args[i + 1].startsWith('-') && args[i + 1].length > 1)) {
+      fail(`Missing value for ${arg}`);
+    }
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith('-') && arg.length > 1 && !BOOLEAN_FLAGS.has(arg)) {
+    fail(`Unknown flag: ${arg}`);
+  }
+}
 
 if (command === 'help') { usage(); process.exit(0); }
 
@@ -114,14 +160,14 @@ if (command === 'guide') {
     console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
     process.exit(1);
   }
-  const source = path.join(templateRoot, 'guides', `${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.`);
     process.exit(1);
   }
   await mkdir(path.dirname(output), { recursive: true });
   await copyFile(source, output);
-  const assetsSource = path.join(templateRoot, 'guides', 'assets');
+  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)))) {
     await cp(assetsSource, assetsTarget, { recursive: true, force: true });
@@ -353,8 +399,31 @@ async function buildOne(job) {
         rollupOptions: { input: path.join(templateRoot, templateEntry) },
       },
     });
-    await rm(output, { force: true });
-    await rename(path.join(scratch, templateEntry), output);
+    // Swap the new build in without a window where no output exists: on
+    // POSIX rename replaces atomically; the fallback path (Windows can refuse
+    // to overwrite a locked file) moves the old output aside first and
+    // restores it if the swap fails, instead of rm-ing it up front.
+    const built = path.join(scratch, templateEntry);
+    try {
+      await rename(built, output);
+    } catch (error) {
+      if (error.code !== 'EEXIST' && error.code !== 'EPERM' && error.code !== 'EACCES') throw error;
+      const backup = `${output}.bak-${process.pid}-${Date.now()}`;
+      let hasBackup = false;
+      try {
+        await rename(output, backup);
+        hasBackup = true;
+      } catch (backupError) {
+        if (backupError.code !== 'ENOENT') throw backupError; // old output kept, swap aborted
+      }
+      try {
+        await rename(built, output);
+      } catch (swapError) {
+        if (hasBackup) await rename(backup, output);
+        throw swapError;
+      }
+      if (hasBackup) await rm(backup, { force: true });
+    }
     console.log(`Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
     return { ok: true, input, output };
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   "files": [
     "bin",
     "template",
-    "skill"
+    "packaged-skill"
   ],
   "dependencies": {
     "@mdx-js/rollup": "^3.0.1",
@@ -34,6 +34,18 @@
     "dense-explain",
     "concept-map"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wurenrumian/concept-atlas.git",
+    "directory": "packages/concept-atlas-dense-explain"
+  },
+  "homepage": "https://github.com/wurenrumian/concept-atlas#readme",
+  "bugs": {
+    "url": "https://github.com/wurenrumian/concept-atlas/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "publishConfig": {
     "access": "public"
   },

package/{skill → packaged-skill}/SKILL.md

@@ -1,21 +1,29 @@
 ---
 name: concept-atlas-dense-explain
-description: Turn a topic or an existing document into an interactive Concept Atlas explainer. Generate AI-editable MDX with the concept-atlas-dense-explain npm CLI, validate its structure, and compile standalone HTML with concept nodes, relation graphs, math (KaTeX), charts, figures, citations, and reading aids. Use when a technical explanation, concept map, layered knowledge page, dense explainer, or interactive teaching page is requested.
+description: Turn a topic or an existing document into an interactive Concept Atlas explainer. Generate AI-editable MDX with the concept-atlas-dense-explain CLI, validate its structure, and compile standalone HTML with concept nodes, relation graphs, math (KaTeX), charts, figures, citations, and reading aids. Use when a technical explanation, concept map, layered knowledge page, dense explainer, or interactive teaching page is requested.
 ---
 
 # Concept Atlas Dense Explain
 
-Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill is intentionally lightweight: do not copy implementation files from the skill directory or recreate the React/Vite app. If a command name is unclear, run `npx concept-atlas-dense-explain help`. If the user only wants the prompt/methodology and not files, still choose a shell and emit valid MDX; the CLI is needed only to compile.
+Drive everything through the `concept-atlas-dense-explain` CLI, always via `npx`. Everything you need is in this file and the bundled `references/`; do not read the framework repository or installed package files, do not copy implementation files from the skill directory, and do not recreate the React/Vite app. If a command name is unclear, run `npx concept-atlas-dense-explain help`. If the user only wants the prompt/methodology and not files, still choose a shell and emit valid MDX; the CLI is needed only to validate and compile.
+
+## Running the CLI
+
+Always invoke the CLI through `npx`, from any directory:
+
+```bash
+npx concept-atlas-dense-explain <args>
+```
+
+This is the only runner — there is nothing to look for. Do not search for a local binary, a repository checkout, or an installed copy, and do not run the framework's own `npm` scripts. The first call downloads the package from the npm registry; say so once, then continue.
 
 ## Workflow
 
 1. Choose one page shell: `atlas` (concept graph with node navigation) or `scroll` (continuous document). Recommend `atlas` when the reader drills into concepts or follows relations, `scroll` for linear argument, tutorials, and reports. The library is shared. If an `.mdx` already exists, detect its shell and work with it.
-2. **Learn the components from the canonical guide before authoring.** Generate it for the chosen shell and read it:
-   ```bash
-   npx concept-atlas-dense-explain guide --mode atlas -o ./concept-atlas-atlas-guide.mdx
-   npx concept-atlas-dense-explain guide --mode scroll -o ./concept-atlas-scroll-guide.mdx
-   ```
-   It is real, compilable MDX showing that shell's components and their exact props; search it for a component name instead of guessing. Delete it when done.
+2. **Learn the components from the bundled reference before authoring.** The only reference you need is the guide that ships with this skill:
+   - `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.
 4. Write the semantic MDX into the user's `.mdx` file (see Authoring rules).
 5. Validate before rendering:
@@ -40,7 +48,9 @@ Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill i
 
 - 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`
 - 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`), `Cite`, `References`
 
@@ -54,6 +64,9 @@ Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill i
 - **Math**: MDX parses `{ ... }` in children as expressions, so pass LaTeX with braces or backslashes through `formula`: `<Math formula="r_{\text{ann}} = (1 + r)^{12} - 1" />`, `<MathBlock formula="I(x) = -\log_2 p(x)" variables={[{symbol, description}]} />`. Brace-free children such as `<Math>\log_2 N</Math>` are fine. The validator warns (`MATH_CHILDREN_BRACES`).
 - **CodeBlock**: a general code block usable anywhere; `Implementation` is the node-bound variant. Pass the code as a string via `code` (or as children) wrapped in a template literal so MDX does not read it as expressions: `<CodeBlock language="bash" title="..." lineNumbers>{`npm run validate`}</CodeBlock>`. `language` adds the badge, `title`/`caption` add labels, `lineNumbers` and `wrap` are booleans.
 - **Chart**: `type` is `bar` | `line` | `pie`; use `data` for bar/pie and `labels` + `series={[{name, values}]}` for line. Charts follow theme colors.
+- **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.
 - **Figure**: a relative `src` (`./assets/diagram.png`) is inlined as base64 at build time so the HTML stays standalone; `http(s)` URLs stay links. Always set `alt`; add `label` and `caption` for a numbered caption. 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 size & cost**: inlining images is what makes a screenshot-heavy page large; a page with no heavy renderers otherwise lands near 250KB. When the user cares, compile with `--link-assets` to keep images as relative links (measured 1.51MB → 270KB); the output must then sit beside the MDX's `assets/`, and the CLI warns if `-o` points elsewhere — tell the user that trade-off instead of choosing silently.
 - **Cite/References**: `<Cite id="..." />` renders `[n]` from the matching item's position in `<References items={...} />`. In `scroll`, `References` can sit anywhere. In `atlas`, keep the cites and the `References` block in the same node, because node content only renders when that node is open.
@@ -70,4 +83,4 @@ Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill i
 - Every node has `title` + `summary`; every `Relation` has a `label`.
 - The HTML file exists at the reported path.
 
-If the CLI or npm registry is unavailable, report the blocker instead of copying the implementation into the skill.
+If `npx` cannot reach the registry, report the blocker. Never copy implementation files into the skill directory.

package/{template/guides → packaged-skill/references}/atlas-guide.mdx

@@ -8,7 +8,7 @@
       <LearningObjectives items={['认识全部组件家族', '理解组件之间的职责边界', '选择合适组件编写自己的 MDX']} />
       <KeyQuestion>我需要表达的是一个事实、一种关系，还是一种组织信息的结构？</KeyQuestion>
       <Callout type="success" title="展厅导航">先看“知识结构”，再看“内容语义”和“经典模型”；最后打开“可视化与布局”和“扩展能力”，就能覆盖完整能力。</Callout>
-      <Children><ConceptRef id="structure-family" /><ConceptRef id="content-family" /><ConceptRef id="verification-family" /><ConceptRef id="concept-models" /><ConceptRef id="presentation-family" /><ConceptRef id="visual-family" /><ConceptRef id="extension-family" /></Children>
+      <Children><ConceptRef id="structure-family" /><ConceptRef id="content-family" /><ConceptRef id="verification-family" /><ConceptRef id="concept-models" /><ConceptRef id="presentation-family" /><ConceptRef id="visual-family" /><ConceptRef id="extension-family" /><ConceptRef id="learning-family" /><ConceptRef id="data-family" /></Children>
     </ConceptNode>
 
     <ConceptNode id="structure-family" title="知识结构组件：搭出可下钻的概念树" level="L1" parent="showroom" summary="页面、图谱、节点、子节点和跨节点关系共同构成导航骨架。">
@@ -23,7 +23,7 @@
     </ConceptNode>
     <ConceptNode id="relation-anatomy" title="Relation：把跨分支意义显式画出来" level="L2" parent="structure-family" summary="Relation 不改变树层级，而是表达前置、因果、产出、依赖和对比。">
       <Definition>关系边使用白名单类型：prerequisite、causes、produces、uses、implements、contrasts、depends-on、exception-of、precedes。</Definition>
-      <RelationMap title="关系类型示例" items={[{from:'Definition',type:'implements',to:'ConceptNode',note:'内容具体化节点'},{from:'Evidence',type:'supports',to:'Claim',note:'由证据支撑判断'}]} />
+      <RelationMap title="关系类型示例" items={[{from:'Definition',type:'implements',to:'ConceptNode',note:'内容具体化节点'},{from:'Evidence',type:'produces',to:'Claim',note:'由证据支撑判断'}]} />
       <Boundary>不要用 Relation 表达 parent-child；父子边由 parent 和 Children 自动生成。</Boundary>
     </ConceptNode>
 
@@ -154,6 +154,31 @@ npm run build`}</CodeBlock>
       <References title="本节点引用" items={[{id:'shannon1948',authors:'Shannon, C. E.',year:'1948',title:'A Mathematical Theory of Communication',source:'Bell System Technical Journal'},{id:'tufte1983',authors:'Tufte, E. R.',year:'1983',title:'The Visual Display of Quantitative Information',source:'Graphics Press'}]} />
     </ConceptNode>
 
+    <ConceptNode id="learning-family" title="学习闭环组件：从推演到自测再到收尾" level="L1" parent="showroom" summary="WorkedExample、Quiz、KeyTakeaways 与 Confidence 把讲解补成可推演、可自检、可追溯、可收束的闭环。">
+      <Definition>LearningObjectives 和 KeyQuestion 负责开场；这一组负责中段逐步推演、即时自测、来源与置信度标注，以及结尾的压缩要点。</Definition>
+      <WorkedExample title="一次动态库加载失败的完整追踪" problem="程序编译成功却在启动时退出，需要逐步定位而不是直接猜测。">
+        <Step number="1" title="确认格式与架构" reason="格式或架构不匹配会让 loader 直接拒绝文件">file app && readelf -h app</Step>
+        <Step number="2" title="检查直接依赖" reason="排除共享库缺失这一最常见原因">ldd app</Step>
+        <Step number="3" title="核对搜索路径" reason="依赖存在但不在 loader 的搜索路径上同样会失败">echo $LD_LIBRARY_PATH</Step>
+      </WorkedExample>
+      <Quiz question="哪个阶段负责解析跨文件符号？" answer="链接阶段" tone="success">
+        链接器把目标文件中的未定义引用与其他目标文件或库中的定义匹配起来，装载阶段只做重定位。
+      </Quiz>
+      <KeyTakeaways items={['每一步都要给出理由，而不只是结果', '自测用于主动回忆，而不是装饰', '结尾要点应压缩，而不是复述正文']} />
+      <Definition>ELF 的装载语义由规范定义<Source kind="spec" label="System V ABI" href="https://refspecs.linuxfoundation.org/elf/gabi4+/contents.html" />，而不是某个实现的约定。</Definition>
+      <Confidence level="high" basis="规范定义 + 实测复现">装载阶段的不变量由 ABI 明确规定，可由 loader 行为直接验证。</Confidence>
+    </ConceptNode>
+
+    <ConceptNode id="data-family" title="数据与行为模型：表格、指标、状态、分支与回路" level="L1" parent="showroom" summary="DataTable、Metric、StateMachine、DecisionTree、FeedbackLoop 和 CodeDiff 分别表达中立数据、头条数字、状态迁移、分支决策、反馈回路与代码改动。">
+      <Definition>当线性 Flow 和二维矩阵不足以表达信息时，用这些模型补上状态、分支、回路、数据形态和代码差异。缺页<Term name="缺页异常">访问未驻留内存页时由 MMU 触发的可恢复异常</Term>属于典型的状态迁移问题。</Definition>
+      <DataTable title="三种异常对比" caption="同一现象可能来自不同层次，先分类再定位。" headers={['异常', '触发条件', '典型信号']} rows={[['缺页', '访问未驻留页', '可恢复'], ['段错误', '非法地址访问', 'SIGSEGV'], ['除零', '整数除以零', 'SIGFPE']]} />
+      <Metric label="P99 延迟" value="128" unit="ms" delta="-18%" trend="down" note="相对上一版本，来自压测环境。" />
+      <StateMachine title="进程状态" initial="new" states={[{id:'new',label:'新建'},{id:'ready',label:'就绪'},{id:'running',label:'运行'},{id:'done',label:'终止',terminal:true}]} transitions={[{from:'new',to:'ready',event:'admit'},{from:'ready',to:'running',event:'dispatch'},{from:'running',to:'ready',event:'preempt'},{from:'running',to:'done',event:'exit'}]} />
+      <DecisionTree title="先看哪一层" question="页面没有渲染，先排查哪一层？" branches={[{condition:'有构建错误',outcome:'先修构建',tone:'danger'},{condition:'构建通过',outcome:'检查运行时',branches:[{condition:'组件抛错',outcome:'看错误边界',tone:'warn'},{condition:'数据为空',outcome:'检查数据来源',tone:'info'}]}]} />
+      <FeedbackLoop title="缓存命中回路" type="reinforcing" nodes={[{label:'命中率上升',description:'更多请求由缓存服务'},{label:'后端压力下降',description:'响应更快'},{label:'体验提升',description:'更多请求进入'}]} />
+      <CodeDiff language="javascript" title="避免空值崩溃" before={`const name = user.profile.name;`} after={`const name = user?.profile?.name ?? '匿名';`} caption="可选链与空值合并把运行时错误前移为可预期的默认值。" />
+    </ConceptNode>
+
     <Relation from="structure-family" to="content-family" type="precedes" label="先搭骨架" />
     <Relation from="content-family" to="verification-family" type="uses" label="补充证据" />
     <Relation from="concept-models" to="presentation-family" type="implements" label="结构落地" />
@@ -165,5 +190,8 @@ npm run build`}</CodeBlock>
     <Relation from="pyramid-funnel-demo" to="framework-demo" type="contrasts" label="分层 vs 循环" />
     <Relation from="math-demo" to="formula-demo" type="contrasts" label="LaTeX vs 纯文本公式" />
     <Relation from="chart-demo" to="matrix-demo" type="contrasts" label="连续数据 vs 二维定位" />
+    <Relation from="verification-family" to="learning-family" type="precedes" label="证据之后自测" />
+    <Relation from="learning-family" to="data-family" type="uses" label="自测需要数据模型" />
+    <Relation from="concept-models" to="data-family" type="contrasts" label="静态模型 vs 行为模型" />
   </ConceptGraph>
 </ExplainPage>

package/{template/guides → packaged-skill/references}/scroll-guide.mdx

@@ -58,6 +58,49 @@ npm run dev`}</CodeBlock>
     </ScrollGrid>
   </ScrollSection>
 
+  <ScrollSection title="把讲解补成学习闭环">
+    <ScrollProse>讲解不应只给结论。WorkedExample 记录每一步的理由，Quiz 触发主动回忆，KeyTakeaways 在结尾压缩真正要带走的部分。</ScrollProse>
+    <WorkedExample title="一次动态库加载失败的完整追踪" problem="程序编译成功却在启动时退出，需要逐步定位而不是直接猜测。">
+      <Step number="1" title="确认格式与架构" reason="格式或架构不匹配会让 loader 直接拒绝文件">file app && readelf -h app</Step>
+      <Step number="2" title="检查直接依赖" reason="排除共享库缺失这一最常见原因">ldd app</Step>
+      <Step number="3" title="核对搜索路径" reason="依赖存在但不在 loader 搜索路径上同样会失败">echo $LD_LIBRARY_PATH</Step>
+    </WorkedExample>
+    <Quiz question="哪个阶段负责解析跨文件符号？" answer="链接阶段" tone="success">
+      链接器把目标文件中的未定义引用与其他目标文件或库中的定义匹配起来，装载阶段只做重定位。
+    </Quiz>
+    <KeyTakeaways items={['每一步都要给出理由，而不只是结果', '自测用于主动回忆，而不是装饰', '结尾要点应压缩，而不是复述正文']} />
+  </ScrollSection>
+
+  <ScrollSection title="标注来源、置信度与术语">
+    <ScrollProse>同一句话的权威性并不相同。用 Source 标出来源类型，用 Confidence 标出确信程度，用 Term 在行内解释术语，读者才能判断该信多少。</ScrollProse>
+    <Confidence level="high" basis="规范定义 + 实测复现">
+      ELF 的装载语义由规范定义<Source kind="spec" label="System V ABI" href="https://refspecs.linuxfoundation.org/elf/gabi4+/contents.html" />，而非某个实现的约定。
+    </Confidence>
+    <Confidence level="medium" basis="单次压测，样本有限">
+      缺页<Term name="缺页异常">访问未驻留内存页时由 MMU 触发的可恢复异常</Term>是延迟波动的主要来源。
+    </Confidence>
+  </ScrollSection>
+
+  <ScrollSection title="中立数据与行为模型">
+    <ScrollProse>DataTable 承载没有比较立场的数据，Metric 给出头条数字，StateMachine、DecisionTree 和 FeedbackLoop 表达状态、分支与回路这三种 Flow 覆盖不了的结构。</ScrollProse>
+    <DataTable title="三种异常对比" caption="同一现象可能来自不同层次，先分类再定位。" headers={['异常', '触发条件', '典型信号']} rows={[['缺页', '访问未驻留页', '可恢复'], ['段错误', '非法地址访问', 'SIGSEGV'], ['除零', '整数除以零', 'SIGFPE']]} />
+    <ScrollGrid columns="3">
+      <Metric label="P99 延迟" value="128" unit="ms" delta="-18%" trend="down" note="相对上一版本。" />
+      <Metric label="可用性" value="99.95" unit="%" delta="+0.02%" trend="up" note="近 30 天。" />
+      <Metric label="错误率" value="0.7" unit="%" delta="+0.3%" trend="up" note="需要关注。" />
+    </ScrollGrid>
+    <StateMachine title="进程状态" initial="new" states={[{id:'new',label:'新建'},{id:'ready',label:'就绪'},{id:'running',label:'运行'},{id:'done',label:'终止',terminal:true}]} transitions={[{from:'new',to:'ready',event:'admit'},{from:'ready',to:'running',event:'dispatch'},{from:'running',to:'ready',event:'preempt'},{from:'running',to:'done',event:'exit'}]} />
+    <ScrollGrid columns="2">
+      <DecisionTree title="先看哪一层" question="页面没有渲染，先排查哪一层？" branches={[{condition:'有构建错误',outcome:'先修构建',tone:'danger'},{condition:'构建通过',outcome:'检查运行时',branches:[{condition:'组件抛错',outcome:'看错误边界',tone:'warn'},{condition:'数据为空',outcome:'检查数据来源',tone:'info'}]}]} />
+      <FeedbackLoop title="缓存命中回路" type="reinforcing" nodes={[{label:'命中率上升',description:'更多请求由缓存服务'},{label:'后端压力下降',description:'响应更快'},{label:'体验提升',description:'更多请求进入'}]} />
+    </ScrollGrid>
+  </ScrollSection>
+
+  <ScrollSection title="展示代码改动">
+    <ScrollProse>CodeDiff 把改动前后并排呈现，适合讲解一次修复或重构；它与单块的 CodeBlock 互补。</ScrollProse>
+    <CodeDiff language="javascript" title="避免空值崩溃" before={`const name = user.profile.name;`} after={`const name = user?.profile?.name ?? '匿名';`} caption="可选链与空值合并把运行时错误前移为可预期的默认值。" />
+  </ScrollSection>
+
   <ScrollSection title="补充配图与出处">
     <ScrollProse>配图和引用让讲解从断言变成可追溯的论述<Cite id="tufte1983" />。相对路径的图片会在构建时内联，输出仍是可离线打开的单文件。</ScrollProse>
     <Figure src="./assets/sample-diagram.svg" alt="概念缩放示意" label="图 1" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />

package/template/index.html

@@ -9,8 +9,13 @@
       (function () {
         var doc = document.documentElement;
         var stored = null;
-        try { stored = JSON.parse(localStorage.getItem('concept_atlas_appearance') || 'null'); } catch (e) {}
-        var legacy = localStorage.getItem('concept_atlas_theme');
+        var legacy = null;
+        // Storage access itself can throw (private mode); never let the
+        // anti-flash script crash before first paint.
+        try {
+          stored = JSON.parse(localStorage.getItem('concept_atlas_appearance') || 'null');
+          legacy = localStorage.getItem('concept_atlas_theme');
+        } catch (e) {}
         // Placeholders are replaced at build time when --skin/--default-mode
         // (or CONCEPT_ATLAS_* env vars) are configured; otherwise the runtime
         // fallbacks below keep the carrier defaults.
@@ -20,14 +25,20 @@
         if (/^__.+__$/.test(mode)) mode = 'light';
         var style = '__ATLAS_DEFAULT_STYLE__';
         if (/^__.+__$/.test(style)) style = 'manuscript';
+        // Stored values are whitelisted so a corrupt payload can't paint a
+        // frame with an unknown skin/style before React corrects it.
+        var skins = ['aurora', 'ember', 'verdant', 'sakura', 'noir'];
+        var styles = ['manuscript', 'classic', 'shadcn', 'elastic'];
         if (stored && (stored.mode === 'light' || stored.mode === 'dark')) {
           mode = stored.mode;
         } else if (mode !== 'light' && mode !== 'dark') {
           mode = legacy === 'light' || legacy === 'dark' ? legacy : 'light';
         }
-        doc.setAttribute('data-skin', stored && stored.skin ? stored.skin : skin);
+        if (stored && skins.indexOf(stored.skin) >= 0) skin = stored.skin;
+        if (stored && styles.indexOf(stored.style) >= 0) style = stored.style;
+        doc.setAttribute('data-skin', skin);
         doc.setAttribute('data-theme', mode);
-        doc.setAttribute('data-style', stored && stored.style ? stored.style : style);
+        doc.setAttribute('data-style', style);
       })();
     </script>
     <!-- Google Fonts for Academic / Editorial Knowledge style -->

package/template/package.json

@@ -1,22 +1,5 @@
-{
-  "name": "my-concept-atlas",
-  "private": true,
-  "version": "0.1.0",
-  "type": "module",
-  "scripts": { "dev": "vite", "validate": "node scripts/validate-content.mjs", "build": "npm run validate && node scripts/build.mjs", "clean:temp": "node scripts/clean-temp.mjs" },
-  "dependencies": {
-    "@mdx-js/rollup": "^3.0.1",
-    "clsx": "^2.1.1",
-    "d3": "^7.9.0",
-    "katex": "^0.16.47",
-    "lucide-react": "^0.475.0",
-    "mermaid": "^11.17.2",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
-  },
-  "devDependencies": {
-    "@vitejs/plugin-react": "^4.3.4",
-    "vite": "^5.4.14",
-    "vite-plugin-singlefile": "^2.1.0"
-  }
-}
+{
+  "name": "my-concept-atlas",
+  "private": true,
+  "type": "module"
+}

package/template/references/assets/sample-diagram.svg

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 240" role="img" aria-label="Concept zoom levels">
+  <defs>
+    <linearGradient id="band" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#6366f1" stop-opacity="0.9"/>
+      <stop offset="1" stop-color="#06b6d4" stop-opacity="0.75"/>
+    </linearGradient>
+  </defs>
+  <rect x="0" y="0" width="720" height="240" rx="14" fill="#0f172a"/>
+  <g fill="none" stroke="#334155" stroke-width="1">
+    <line x1="40" y1="176" x2="680" y2="176"/>
+  </g>
+  <g font-family="Segoe UI, Helvetica, Arial, sans-serif" fill="#e2e8f0" font-size="13">
+    <g>
+      <rect x="48" y="60" width="152" height="86" rx="8" fill="url(#band)"/>
+      <text x="124" y="96" text-anchor="middle" font-size="15" font-weight="700">L0</text>
+      <text x="124" y="118" text-anchor="middle" font-size="12">全局主题</text>
+    </g>
+    <g>
+      <rect x="236" y="76" width="152" height="70" rx="8" fill="#1e293b" stroke="#475569"/>
+      <text x="312" y="106" text-anchor="middle" font-size="15" font-weight="700">L1</text>
+      <text x="312" y="126" text-anchor="middle" font-size="12">主要分支</text>
+    </g>
+    <g>
+      <rect x="424" y="92" width="152" height="54" rx="8" fill="#1e293b" stroke="#475569"/>
+      <text x="500" y="115" text-anchor="middle" font-size="15" font-weight="700">L2</text>
+      <text x="500" y="134" text-anchor="middle" font-size="12">局部机制</text>
+    </g>
+    <g>
+      <rect x="612" y="96" width="0" height="0"/>
+    </g>
+  </g>
+  <g fill="#94a3b8" font-family="Segoe UI, Helvetica, Arial, sans-serif" font-size="11">
+    <text x="48" y="200">L3 实现细节与 L4 边界反例继续向右下钻</text>
+  </g>
+  <g fill="none" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow)">
+  </g>
+  <defs>
+    <marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L6,3 L0,6 Z" fill="#64748b"/>
+    </marker>
+  </defs>
+  <g fill="none" stroke="#64748b" stroke-width="1.5">
+    <line x1="200" y1="103" x2="232" y2="111" marker-end="url(#arrow)"/>
+    <line x1="388" y1="111" x2="420" y2="119" marker-end="url(#arrow)"/>
+  </g>
+</svg>