concept-atlas-dense-explain 0.7.0 → 0.9.0

package/bin/cli.mjs

@@ -156,12 +156,13 @@ if (command === 'create' || command === 'new') {
       <Children><ConceptRef id="first-branch" /><ConceptRef id="second-branch" /></Children>
     </ConceptNode>
 
-    <ConceptNode id="first-branch" title="第一条关键分支" level="L1" parent="root-node">
+    <ConceptNode id="first-branch" title="第一条关键分支" level="L1" parent="root-node" summary="第一条关键分支解决什么问题，以及它为什么值得先理解。">
       <Overview>解释第一个重要组成部分。</Overview>
       <Example title="典型例子">填写一个具体例子，帮助读者验证理解。</Example>
+      <CodeBlock language="bash" title="验证方式" code="npm run validate" lineNumbers />
     </ConceptNode>
 
-    <ConceptNode id="second-branch" title="第二条关键分支" level="L1" parent="root-node">
+    <ConceptNode id="second-branch" title="第二条关键分支" level="L1" parent="root-node" summary="第二条关键分支解决什么问题，以及它和第一条分支如何配合。">
       <Overview>解释第二个重要组成部分。</Overview>
       <Boundary>填写它的边界、代价或常见误区。</Boundary>
     </ConceptNode>
@@ -182,6 +183,7 @@ if (command === 'create' || command === 'new') {
   <ScrollSection title="解释关键机制">
     <ScrollProse>按输入、步骤、输出的顺序解释过程，不要只罗列名词。</ScrollProse>
     <Flow title="处理流程" steps={[{title:'输入',description:'原始条件或数据'},{title:'处理',description:'关键变化或判断'},{title:'输出',description:'结果与可观察证据'}]} />
+    <CodeBlock language="bash" title="实践命令" code="npm run validate" caption="通用代码块可以放在任意章节；需要逐行讲解时加 lineNumbers。" />
   </ScrollSection>
 
   <ScrollSection title="边界与实践">

package/package.json

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

package/skill/SKILL.md

@@ -1,23 +1,21 @@
 ---
 name: concept-atlas-dense-explain
-description: Turn a topic or an existing document into an interactive Concept Atlas explainer. Use the concept-atlas-dense-explain npm CLI to generate AI-editable MDX, 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 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.
 ---
 
 # 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 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 compile.
+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.
 
 ## Workflow
 
-1. Choose one page shell: `atlas` (concept graph with node navigation) or `scroll` (continuous document). Recommend `atlas` when the reader needs to drill into concepts or see relations; recommend `scroll` for linear argument, tutorials, and reports. The component library is shared. If the user already has an `.mdx` file, detect its shell and work with it.
-2. **Learn the components from the canonical guide before authoring.** Generate the guide for the chosen shell into a temporary path and read it:
+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 a real, compilable MDX file that demonstrates the components for that shell and their exact props. Search it for a component name to copy the correct prop shape instead of guessing. Delete it when done.
+   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.
 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:
@@ -25,22 +23,22 @@ If the user only wants the prompt/methodology and not files, still choose a shel
    npx concept-atlas-dense-explain validate <file>.mdx --mode atlas|scroll
    npx concept-atlas-dense-explain validate <file>.mdx --json
    ```
-   Every diagnostic is `CODE line:column message`. Fix all `error`s and re-run; warnings are quality signals you should also address 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>] [--inline-mermaid] [--mermaid-cdn <url>]`. Output is a standalone HTML beside the MDX unless `-o` is given. Validation errors abort the build; use `--no-validate` only to force a knowingly broken build. Mermaid loads from a CDN at runtime by default (fast build, small HTML, needs network); pass `--inline-mermaid` when the user needs a fully offline single file.
-7. **Appearance (optional)**: pages ship with a reader-facing appearance menu — palette (`aurora` cool indigo, `ember` warm gold, `verdant` forest green, `sakura` pink-plum, `noir` achromatic 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. You can bake different compile-time defaults: `--skin ember --default-mode dark --style classic` (or env `CONCEPT_ATLAS_SKIN` / `CONCEPT_ATLAS_DEFAULT_MODE` / `CONCEPT_ATLAS_STYLE` on the repo build). `--default-mode` only honors `dark`/`light`; `system` is accepted by the CLI but resolves to the carrier default (`light`). Bake a default only when the user asks for one. Content MDX never sets appearance — it is carrier/tooling territory, not content.
-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. The batch validates everything first and builds in parallel. Builds only bundle the heavy renderers the content uses: a page with no `<Math>` skips KaTeX (its ~1.4MB inlined fonts), and Mermaid is served from a CDN by default rather than bundled. Do not add dummy `<Math>`/`<Mermaid>` nodes to "enable" them — write the components only when the content needs them. Add `--link-assets` when the page carries many screenshots and size matters.
+   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>] [--inline-mermaid] [--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 loads from a CDN at runtime by default (needs network); pass `--inline-mermaid` for a fully offline single file.
+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.
 9. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
 
 ## Carriers
 
-- `atlas`: `ExplainPage` → `ConceptGraph` → `ConceptNode`, plus `Children`/`ConceptRef` and cross-branch `Relation`s. Exactly one `L0` root, several `L1` branches, depth to `L3`/`L4`. Shared components live inside nodes.
+- `atlas`: `ExplainPage` → `ConceptGraph` → `ConceptNode`, plus `Children`/`ConceptRef` and cross-branch `Relation`s. Exactly one `L0` root, several `L1` branches, depth to `L3`/`L4`. Shared components live inside nodes. `ConceptNode` also takes an optional `kind` (see Authoring rules) that labels a node's knowledge role independently of its level.
 - `scroll`: `ScrollDocument` → `ScrollHeader` + `ScrollSection` (+ `ScrollProse`, `ScrollGrid`). Shared components live inside sections. The shell auto-builds a table of contents and reading progress from section titles — do not hand-build navigation.
-- The browser tab comes from the shell, not the build flags: `ExplainPage title="..."` (atlas) or `ScrollHeader title="..."` (scroll) becomes the `<title>`, so give it a real, specific document name — never leave a placeholder like "主题名称". The favicon is a fixed 📃 document emoji on every generated page.
+- The browser tab comes from the shell, not the build flags: `ExplainPage title` (atlas) or `ScrollHeader title` (scroll) becomes the `<title>`, so give it a real, specific name — never a placeholder like "主题名称". Every page uses a fixed 📃 favicon.
 - Never make one MDX file both shells. When switching shells, convert only the outer structure.
 
 ## Component families
 
-- Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `Boundary`, `Example`, `Counterexample`, `Prerequisite`, `Input`, `Output`, `Glossary`
+- Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `CodeBlock`, `Boundary`, `Example`, `Counterexample`, `Prerequisite`, `Input`, `Output`, `Glossary`
 - Argument and evidence: `Evidence`, `Invariant`, `FailureMode`, `Tradeoff`, `LearningObjectives`, `KeyQuestion`
 - Information models: `Flow`, `Timeline`, `Compare`, `DecisionMatrix`, `FrameworkModel`, `MatrixModel`, `FormulaModel`, `PyramidModel`, `FunnelModel`
 - Reading and layout: `Insight`, `Callout`, `Details`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`, `ScrollPair`, `ScrollToc`
@@ -50,19 +48,20 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 
 - Keep MDX semantic. Never write CSS, coordinates, SVG, or replacement application code; never invent component names or props.
 - Give each important node a claim-like title, a one-sentence `summary`, and real substance (`Definition`, `Mechanism`, `Example`, `Boundary`, `Evidence`, a model, a chart, or math). Do not restate the same text across `Overview`, `Definition`, and `Insight`.
+- **`kind` (optional, atlas)**: tag a node's knowledge role independently of `level`. One of `system`, `stage`, `mechanism`, `artifact`, `failure`, `tool`, `boundary`, `decision`. It powers the graph's "知识类型" filter and a node badge, so use it where the role is clear rather than on every node. Two opt-in contracts fire once you declare one: `kind="mechanism"` should contain an `Invariant` or `Evidence`, and `kind="failure"` should contain a `FailureMode` (with `symptom`/`cause`/`evidence`/`remedy`).
 - Array props are arrays of objects: `Flow steps={[{title, description}]}`, `Timeline events={[{label, content}]}`, `MatrixModel cells={[{title, description, tone}]}`, `DecisionMatrix headers={[...]} rows={[[...]]}`, `Chart data={[{label, value}]}`, `References items={[{id, authors, year, title, url, source}]}`. The validator warns (`PROP_EXPECTS_ARRAY`) when an array prop gets a string or non-array.
 - `Relation type` must be one of `prerequisite`, `causes`, `produces`, `uses`, `implements`, `contrasts`, `depends-on`, `exception-of`, `precedes`, and each `Relation` needs a `label`. Parent/child hierarchy is implicit (via `parent` and `Children`/`ConceptRef`) — do not express it with a `Relation`.
 - **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.
-- **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 produces an `ASSET_MISSING` warning and a placeholder. Readers can click any figure to open it full-screen (wheel/`+`/`−` zoom, drag to pan, double-click for 1x/2x, `Esc` to close) — mention this when a page carries dense diagrams.
-- **Figure size**: inlining is what makes a screenshot-heavy page large. When a document carries many images and the user cares about size, compile with `--link-assets` to keep them as relative links (measured: 1.51MB → 270KB on one page). The output then has to live beside the MDX's `assets/` directory, and the CLI warns if `-o` points elsewhere — tell the user that trade-off instead of choosing silently.
+- **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.
 - Continuous reading is configured on the shell, not with manual CSS: `spacing="compact|comfortable|airy"` for rhythm, `fontSize="compact|normal|large|xlarge"` (or numeric `scale`/`lineHeight`) for text size.
-- Be brief about cost: the build only bundles the heavy optional renderers the document actually uses, so a page with no `<Math>`/`<Mermaid>` comes out around 250KB. Inlined figures are usually the largest remaining cost — a page with a dozen screenshots lands near 1–2MB, which is normal for an offline explainer. Mention it if the user cares about file size.
 
 ## Validation diagnostics
 
-`validate` and the build print `CODE line:column message`. Fix these `error`s before building: `UNKNOWN_COMPONENT`, `CARRIER_MISSING`, `CARRIER_CONFLICT`, `CARRIER_MODE_MISMATCH`, `NODE_MISSING_ID`, `DUPLICATE_NODE_ID`, `NODE_MISSING_TITLE`, `MISSING_PARENT`, `GRAPH_ROOT_UNRESOLVED`, `REF_MISSING_ID`, `REF_UNRESOLVED`, `RELATION_FROM_UNRESOLVED`, `RELATION_TO_UNRESOLVED`. Warnings worth fixing: `NODE_MISSING_SUMMARY`, `NODE_NO_CORE_CONTENT`, `UNKNOWN_LEVEL`, `UNKNOWN_RELATION_TYPE`, `RELATION_MISSING_LABEL`, `RELATION_SELF`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `PROSE_EXPRESSION`, `FRONTMATTER_UNSUPPORTED`, `GRAPH_MISSING_ROOT`, `FIGURE_MISSING_SRC`, `ASSET_MISSING`, `REF_SELF`; `NO_ROOT_LEVEL` and `MULTIPLE_ROOT_LEVEL` are warnings that `--strict` promotes to errors.
+`validate` and the build print `CODE line:column message`. Fix these `error`s before building: `UNKNOWN_COMPONENT`, `CARRIER_MISSING`, `CARRIER_CONFLICT`, `CARRIER_MODE_MISMATCH`, `NODE_MISSING_ID`, `DUPLICATE_NODE_ID`, `NODE_MISSING_TITLE`, `MISSING_PARENT`, `GRAPH_ROOT_UNRESOLVED`, `REF_MISSING_ID`, `REF_UNRESOLVED`, `RELATION_FROM_UNRESOLVED`, `RELATION_TO_UNRESOLVED`. Warnings worth fixing: `NODE_MISSING_SUMMARY`, `NODE_NO_CORE_CONTENT`, `UNKNOWN_LEVEL`, `UNKNOWN_KIND`, `MECHANISM_KIND_UNVERIFIED`, `FAILURE_KIND_UNSTRUCTURED`, `FAILURE_MODE_EMPTY`, `UNKNOWN_RELATION_TYPE`, `RELATION_MISSING_LABEL`, `RELATION_SELF`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `PROSE_EXPRESSION`, `FRONTMATTER_UNSUPPORTED`, `GRAPH_MISSING_ROOT`, `FIGURE_MISSING_SRC`, `ASSET_MISSING`, `REF_SELF`; `NO_ROOT_LEVEL`, `MULTIPLE_ROOT_LEVEL`, `MECHANISM_KIND_UNVERIFIED` and `FAILURE_KIND_UNSTRUCTURED` are warnings that `--strict` promotes to errors.
 
 ## Before you report
 

package/template/guides/atlas-guide.mdx

@@ -114,9 +114,9 @@
       <RelationMap title="可视化摘要" items={[{from:'MDX',type:'produces',to:'Graph',note:'生成关系图'},{from:'Node',type:'uses',to:'Mermaid',note:'展示局部流程'}]} />
     </ConceptNode>
 
-    <ConceptNode id="extension-family" title="扩展能力：公式、图表、图片与引用" level="L1" parent="showroom" summary="数学公式、数据图表、配图题注和参考文献四项能力，让讲解可以带上推导、数据与出处。">
-      <Definition>扩展组件把文本之外的证据接进页面：Math/MathBlock 渲染数学、Chart 绘制数据、Figure 承载配图、Cite/References 保留出处。</Definition>
-      <Children><ConceptRef id="math-demo" /><ConceptRef id="chart-demo" /><ConceptRef id="figure-demo" /><ConceptRef id="citation-demo" /></Children>
+    <ConceptNode id="extension-family" title="扩展能力：公式、图表、图片、代码与引用" level="L1" parent="showroom" summary="数学公式、数据图表、配图题注、代码块和参考文献五项能力，让讲解可以带上推导、数据、实现与出处。">
+      <Definition>扩展组件把文本之外的证据接进页面：Math/MathBlock 渲染数学、Chart 绘制数据、Figure 承载配图、CodeBlock 展示代码或命令、Cite/References 保留出处。</Definition>
+      <Children><ConceptRef id="math-demo" /><ConceptRef id="chart-demo" /><ConceptRef id="figure-demo" /><ConceptRef id="code-demo" /><ConceptRef id="citation-demo" /></Children>
     </ConceptNode>
 
     <ConceptNode id="math-demo" title="Math 与 MathBlock：把推导写进正文" level="L2" parent="extension-family" summary="Math 用于行内符号，MathBlock 用于独立公式并支持变量说明。">
@@ -138,6 +138,15 @@
       <Boundary>大图会显著增大单文件 HTML；截图类内容建议控制尺寸。</Boundary>
     </ConceptNode>
 
+    <ConceptNode id="code-demo" title="CodeBlock：把命令、配置或伪代码放进正文" level="L2" parent="extension-family" summary="与绑定节点的 Implementation 不同，CodeBlock 可以出现在任何位置，并支持标题、题注、换行和行号。">
+      <Definition>CodeBlock 通过 code（或子内容）接收字符串，language 决定语言标记，title 与 caption 提供说明，lineNumbers 和 wrap 控制逐行讲解与长行折行。</Definition>
+      <CodeBlock language="bash" title="校验与构建" caption="命令行、伪代码或配置都可以用它承载，不依附于某个概念节点。" lineNumbers>{`npm run validate
+npm run sync
+npm run build`}</CodeBlock>
+      <CodeBlock language="javascript" title="语义优先" wrap>{`const explain = concept => concept.mechanism ?? concept.definition ?? concept.overview;`}</CodeBlock>
+      <Boundary>代码里的反引号、花括号请放在模板字符串中传入，避免被 MDX 当作表达式解析。</Boundary>
+    </ConceptNode>
+
     <ConceptNode id="citation-demo" title="Cite 与 References：让结论可以追溯" level="L2" parent="extension-family" summary="行内用 Cite 标记引用，文末用 References 列出完整出处，编号自动对应。">
       <Definition>Cite 的 id 与 References 条目的 id 对应，渲染时显示条目在列表中的序号，并链接到该条目。</Definition>
       <Overview>信息密度的价值在于可验证性<Cite id="shannon1948" />，而可验证性依赖清晰的出处<Cite id="tufte1983" />。</Overview>

package/template/guides/scroll-guide.mdx

@@ -42,6 +42,14 @@
     <Chart title="四周留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]},{name:'活跃度',values:[100,64,52,40]}]} />
   </ScrollSection>
 
+  <ScrollSection title="把命令与代码放进正文">
+    <ScrollProse>CodeBlock 承载命令行、配置或伪代码。它不依附于某个概念节点，可以出现在任何章节；需要逐行讲解时打开行号，长行过多时可以折行。</ScrollProse>
+    <CodeBlock language="bash" title="本地校验与预览" caption="CodeBlock 复用模板的代码表面，因此自动跟随当前皮肤与组件风格。" lineNumbers>{`npm run validate
+npm run sync
+npm run dev`}</CodeBlock>
+    <CodeBlock language="javascript" title="语义优先" wrap>{`const explain = concept => concept.mechanism ?? concept.definition ?? concept.overview;`}</CodeBlock>
+  </ScrollSection>
+
   <ScrollSection title="组织证据，再收敛到行动">
     <ScrollGrid columns="3">
       <PyramidModel title="论证层级" levels={[{title:'结论',description:'读者需要带走的判断'},{title:'理由',description:'支撑判断的关键分组'},{title:'证据',description:'事实、数据与案例'}]} />

package/template/src/app/App.jsx

@@ -3,11 +3,19 @@ import { Network, Compass, Sun, Moon, Search, X, Link as LinkIcon } from 'lucide
 import { buildGraphModel } from '../model/concept-schema.js';
 import { extractConceptData } from '../model/normalize-content.js';
 import { useAppearance } from './use-appearance.js';
+import { pushNode, stepHistory, syncFromLocation } from './navigation.js';
+import { searchNodes } from './search.js';
+import { NODE_KINDS } from '../model/node-kinds.js';
 import { SkinPicker } from '../components/SkinPicker.jsx';
 import { NodeExplorer } from '../views/NodeExplorer.jsx';
 import { RelationGraph } from '../views/RelationGraph.jsx';
 import '../styles/concept-explain.css';
 
+function readNodeFromHash() {
+  if (typeof window === 'undefined') return null;
+  return new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
+}
+
 export function App({ mdxContent, initialData }) {
   // Extract graph model from MDX JSX Element or raw data
   const [graph] = useState(() => {
@@ -28,54 +36,41 @@ export function App({ mdxContent, initialData }) {
 
   // Global shared state
   const [currentView, setCurrentView] = useState('explore'); // 'explore' | 'graph'
-  const [currentNodeId, setCurrentNodeId] = useState(() => {
-    const hashNode = new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
-    return hashNode && graph.nodes.has(hashNode) ? hashNode : (graph.meta.rootId || '');
-  });
+  const initialHashNode = (() => {
+    const hashNode = readNodeFromHash();
+    return hashNode && graph.nodes.has(hashNode) ? hashNode : null;
+  })();
+
+  const [currentNodeId, setCurrentNodeId] = useState(
+    () => initialHashNode || graph.meta.rootId || '',
+  );
   const [selectedLevel, setSelectedLevel] = useState(null);
-  const [history, setHistory] = useState(() => {
-    const initial = new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
-    return initial && graph.nodes.has(initial) ? [initial] : [graph.meta.rootId].filter(Boolean);
-  });
-  const [historyIndex, setHistoryIndex] = useState(0);
+  const [nav, setNav] = useState(() => ({
+    entries: (initialHashNode ? [initialHashNode] : [graph.meta.rootId]).filter(Boolean),
+    index: 0,
+  }));
   const [globalQuery, setGlobalQuery] = useState('');
   const [linkCopied, setLinkCopied] = useState(false);
 
-  const searchResults = useMemo(() => {
-    const query = globalQuery.trim().toLowerCase();
-    if (!query) return [];
-    return Array.from(graph.nodes.values()).map(node => {
-      const searchable = [
-        node.title, node.id, node.summary, node.definition, node.overview,
-        node.mechanism, node.input, node.output,
-        ...(node.examples || []).flatMap(item => [item.title, item.content]),
-        ...(node.glossary || []).flatMap(item => [item.term, item.definition]),
-        ...(node.boundaries || []).flatMap(item => [item.title, item.content]),
-      ].filter(value => typeof value === 'string').join(' ').toLowerCase();
-      return searchable.includes(query) ? node : null;
-    }).filter(Boolean).slice(0, 8);
-  }, [globalQuery, graph.nodes]);
+  const searchResults = useMemo(
+    () => searchNodes(Array.from(graph.nodes.values()), globalQuery),
+    [globalQuery, graph.nodes],
+  );
 
   const navigateToNode = (nodeId, { replace = false } = {}) => {
     if (!nodeId || !graph.nodes.has(nodeId)) return;
     setCurrentNodeId(nodeId);
-    setHistory(previous => {
-      const base = previous.slice(0, historyIndex + 1);
-      if (base[base.length - 1] === nodeId) return previous;
-      const next = [...base, nodeId];
-      setHistoryIndex(next.length - 1);
-      return next;
-    });
+    setNav(previous => pushNode(previous, nodeId));
     const nextHash = `#node=${encodeURIComponent(nodeId)}`;
     if (replace) window.history.replaceState({}, '', nextHash);
     else window.history.pushState({}, '', nextHash);
   };
 
   const moveHistory = (direction) => {
-    const nextIndex = Math.max(0, Math.min(history.length - 1, historyIndex + direction));
-    if (nextIndex === historyIndex) return;
-    setHistoryIndex(nextIndex);
-    const nodeId = history[nextIndex];
+    const next = stepHistory(nav, direction);
+    if (!next) return;
+    setNav(next);
+    const nodeId = next.entries[next.index];
     setCurrentNodeId(nodeId);
     window.history.pushState({}, '', `#node=${encodeURIComponent(nodeId)}`);
   };
@@ -83,10 +78,26 @@ export function App({ mdxContent, initialData }) {
   // Keyboard navigation shortcuts
   useEffect(() => {
     const handleKeyDown = (e) => {
-      // Toggle views with 1 and 2 or 'g' and 'e' if not focused on input
-      if (e.isComposing || e.metaKey || e.ctrlKey || e.altKey || ['INPUT', 'TEXTAREA', 'SELECT'].includes(document.activeElement?.tagName) || document.activeElement?.isContentEditable) {
+      if (e.isComposing) return;
+
+      // Alt + arrows move through browsing history. Handled before the modifier
+      // guard below, otherwise the altKey short-circuit makes them unreachable.
+      if (e.altKey && e.key === 'ArrowLeft') {
+        e.preventDefault();
+        moveHistory(-1);
         return;
       }
+      if (e.altKey && e.key === 'ArrowRight') {
+        e.preventDefault();
+        moveHistory(1);
+        return;
+      }
+
+      // Toggle views with 1 and 2 or 'g' and 'e' if not focused on input.
+      const target = document.activeElement;
+      const typing = ['INPUT', 'TEXTAREA', 'SELECT'].includes(target?.tagName) || target?.isContentEditable;
+      if (e.metaKey || e.ctrlKey || e.altKey || typing) return;
+
       const key = e.key.toLowerCase();
       if (e.key === '1' || key === 'e') {
         setCurrentView('explore');
@@ -95,18 +106,7 @@ export function App({ mdxContent, initialData }) {
       } else if (key === 't') {
         toggleTheme();
       } else if (e.key === 'Escape') {
-        // Alt + arrows move through browsing history.
-        if (e.altKey && e.key === 'ArrowLeft') {
-          e.preventDefault();
-          moveHistory(-1);
-          return;
-        }
-        if (e.altKey && e.key === 'ArrowRight') {
-          e.preventDefault();
-          moveHistory(1);
-          return;
-        }
-        // Return to root or parent
+        // Return to the parent node.
         const curr = graph.nodes.get(currentNodeId);
         if (curr && curr.parent) {
           navigateToNode(curr.parent);
@@ -116,23 +116,14 @@ export function App({ mdxContent, initialData }) {
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [graph, currentNodeId, historyIndex, history]);
+  }, [graph, currentNodeId, nav]);
 
   useEffect(() => {
     const handlePopState = () => {
-      const nodeId = new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
+      const nodeId = readNodeFromHash();
       if (!nodeId || !graph.nodes.has(nodeId)) return;
       setCurrentNodeId(nodeId);
-      setHistory(previous => {
-        const index = previous.lastIndexOf(nodeId);
-        if (index >= 0) {
-          setHistoryIndex(index);
-          return previous;
-        }
-        const next = [...previous, nodeId];
-        setHistoryIndex(next.length - 1);
-        return next;
-      });
+      setNav(previous => syncFromLocation(previous, nodeId));
     };
     window.addEventListener('popstate', handlePopState);
     return () => window.removeEventListener('popstate', handlePopState);
@@ -176,7 +167,7 @@ export function App({ mdxContent, initialData }) {
               <div className="global-search-results" role="listbox">
                 {searchResults.map(node => (
                   <button type="button" key={node.id} onClick={() => { navigateToNode(node.id); setGlobalQuery(''); }} role="option">
-                    <span>{node.title}</span><small>{node.level} · {node.summary || node.id}</small>
+                    <span>{node.title}</span><small>{node.level}{node.kind && NODE_KINDS[node.kind] ? ` · ${NODE_KINDS[node.kind].label}` : ''} · {node.summary || node.id}</small>
                   </button>
                 ))}
               </div>

package/template/src/app/navigation.js

@@ -0,0 +1,41 @@
+/**
+ * Pure browsing-history helpers for the atlas carrier.
+ *
+ * History is a single `{ entries, index }` value instead of two separate
+ * `useState` calls. Keeping them together removes the side effect that used to
+ * live inside the `setHistory` updater (which React StrictMode can double
+ * invoke) and makes the whole navigation model trivially unit-testable.
+ */
+
+/**
+ * Push a node onto the history, truncating any forward entries.
+ * Returns the same object when `nodeId` is already the current entry so React
+ * can bail out of the state update.
+ */
+export function pushNode(state, nodeId) {
+  const base = state.entries.slice(0, state.index + 1);
+  if (base[base.length - 1] === nodeId) return state;
+  const entries = [...base, nodeId];
+  return { entries, index: entries.length - 1 };
+}
+
+/**
+ * Move one step through the history. Returns `null` when the move would leave
+ * the bounds, so the caller can avoid a redundant re-render.
+ */
+export function stepHistory(state, direction) {
+  const nextIndex = Math.max(0, Math.min(state.entries.length - 1, state.index + direction));
+  if (nextIndex === state.index) return null;
+  return { entries: state.entries, index: nextIndex };
+}
+
+/**
+ * Resolve a node id arriving from a `popstate` event (browser back/forward).
+ * Reuses an existing entry when present so the back stack stays consistent.
+ */
+export function syncFromLocation(state, nodeId) {
+  const existing = state.entries.lastIndexOf(nodeId);
+  if (existing >= 0) return { entries: state.entries, index: existing };
+  const entries = [...state.entries, nodeId];
+  return { entries, index: entries.length - 1 };
+}

package/template/src/app/search.js

@@ -0,0 +1,84 @@
+import React from 'react';
+import { NODE_KINDS } from '../model/node-kinds.js';
+
+const MAX_DEPTH = 6;
+const MAX_LENGTH = 4000;
+
+/**
+ * Flatten whatever an MDX component renders — strings, React elements, arrays
+ * and prop objects — into searchable plain text. Bounded in depth and length so
+ * a pathological tree cannot stall the search box.
+ */
+export function collectText(value, depth = 0) {
+  if (depth > MAX_DEPTH || value === null || value === undefined || typeof value === 'boolean') return '';
+  if (typeof value === 'string' || typeof value === 'number') return String(value);
+  if (Array.isArray(value)) {
+    return value.map(item => collectText(item, depth + 1)).join(' ');
+  }
+  if (React.isValidElement(value)) {
+    const props = value.props || {};
+    const parts = [];
+    for (const [key, prop] of Object.entries(props)) {
+      // `components` is the MDX component registry, never content.
+      if (key === 'children' || key === 'components') continue;
+      if (typeof prop === 'string' || typeof prop === 'number') parts.push(String(prop));
+      else if (prop && typeof prop === 'object') parts.push(collectText(prop, depth + 1));
+    }
+    parts.push(collectText(props.children, depth + 1));
+    return parts.join(' ');
+  }
+  if (typeof value === 'object') {
+    return Object.values(value).map(item => collectText(item, depth + 1)).join(' ');
+  }
+  return '';
+}
+
+/**
+ * Build one lowercase haystack per node. Includes the semantic content fields,
+ * the structured argument/evidence records (Evidence, Invariant, FailureMode,
+ * Tradeoff, …) and the free-form `customSections` that the same components also
+ * render through. The kind id and its label are indexed too, so "故障" finds
+ * `kind="failure"` nodes.
+ */
+export function nodeSearchText(node) {
+  if (!node) return '';
+  const kind = node.kind ? NODE_KINDS[node.kind] : null;
+  const parts = [
+    node.title,
+    node.id,
+    node.kind,
+    kind ? kind.label : '',
+    node.summary,
+    node.overview,
+    node.definition,
+    node.mechanism,
+    node.input,
+    node.output,
+    node.implementation,
+    node.prerequisites,
+    node.examples,
+    node.counterexamples,
+    node.boundaries,
+    node.glossary,
+    node.learningObjectives,
+    node.keyQuestions,
+    node.evidence,
+    node.invariants,
+    node.failureModes,
+    node.tradeoffs,
+    node.customSections,
+  ];
+  return parts.map(part => collectText(part)).join(' ').slice(0, MAX_LENGTH).toLowerCase();
+}
+
+/** Rank-free substring search returning at most `limit` nodes. */
+export function searchNodes(nodes, query, limit = 8) {
+  const needle = String(query || '').trim().toLowerCase();
+  if (!needle) return [];
+  const results = [];
+  for (const node of nodes) {
+    if (nodeSearchText(node).includes(needle)) results.push(node);
+    if (results.length >= limit) break;
+  }
+  return results;
+}

package/template/src/components/MDXComponents.jsx

@@ -180,6 +180,38 @@ export function Implementation({ language = 'text', title = '实现代码', chil
 }
 Implementation.displayName = 'Implementation';
 
+/**
+ * Generic code block for any carrier. `Implementation` is bound to a node's
+ * implementation section; `CodeBlock` is meant for shell commands, config,
+ * output, prompts and pseudocode that live anywhere in a document.
+ * Pass the code as a string through `code` (or as children) so MDX parsing and
+ * the validator never confuse code with markup.
+ */
+export function CodeBlock({ code, language = 'text', title, caption, lineNumbers = false, wrap = false, children }) {
+  const raw = typeof code === 'string' ? code : childrenToText(children);
+  const text = typeof raw === 'string' ? raw.replace(/^\n+|\s+$/g, '') : '';
+  if (!text) return null;
+  const showLanguage = Boolean(language) && language !== 'text';
+  const showHead = Boolean(title) || showLanguage;
+  return (
+    <figure className="semantic-code" data-language={language}>
+      {showHead && (
+        <div className="semantic-code-head">
+          {title && <span className="semantic-code-title">{title}</span>}
+          {showLanguage && <span className="lang-badge">{language}</span>}
+        </div>
+      )}
+      <pre className={`code-block${lineNumbers ? ' code-block-numbered' : ''}${wrap ? ' code-block-wrap' : ''}`}>
+        {lineNumbers
+          ? <code>{text.split('\n').map((line, index) => <span className="code-line" key={index}>{line}</span>)}</code>
+          : <code>{text}</code>}
+      </pre>
+      {caption && <figcaption className="semantic-code-caption">{caption}</figcaption>}
+    </figure>
+  );
+}
+CodeBlock.displayName = 'CodeBlock';
+
 export function Boundary({ title = '边界与约束', children }) {
   return (
     <div className="semantic-boundary">

package/template/src/model/concept-schema.js

@@ -1,5 +1,6 @@
 import React from 'react';
 import { RELATION_TYPES, LEVEL_DEFS } from './relation-types.js';
+import { NODE_KIND_SET, normalizeKind } from './node-kinds.js';
 
 /**
  * Creates an empty Concept Knowledge Graph structure
@@ -26,6 +27,7 @@ export function normalizeNode(raw) {
     id,
     title: raw.title || id,
     level: raw.level || 'L2',
+    kind: normalizeKind(raw.kind),
     parent: raw.parent || null,
     children: Array.isArray(raw.children) ? raw.children : [],
     
@@ -43,6 +45,16 @@ export function normalizeNode(raw) {
     boundaries: raw.boundaries || [],
     glossary: raw.glossary || [],
     customSections: raw.customSections || [],
+
+    // Structured argument / evidence content. These mirror the matching
+    // customSections (which still render), but as data the graph, search and
+    // validator can reason about.
+    learningObjectives: Array.isArray(raw.learningObjectives) ? raw.learningObjectives : [],
+    keyQuestions: Array.isArray(raw.keyQuestions) ? raw.keyQuestions : [],
+    evidence: Array.isArray(raw.evidence) ? raw.evidence : [],
+    invariants: Array.isArray(raw.invariants) ? raw.invariants : [],
+    failureModes: Array.isArray(raw.failureModes) ? raw.failureModes : [],
+    tradeoffs: Array.isArray(raw.tradeoffs) ? raw.tradeoffs : [],
   };
 }
 
@@ -58,6 +70,9 @@ export function buildGraphModel(rawGraph) {
   // Register all nodes
   rawNodes.forEach(n => {
     const node = normalizeNode(n);
+    if (n.kind && !NODE_KIND_SET.has(n.kind)) {
+      diagnostics.push({ level: 'warning', code: 'UNKNOWN_KIND', nodeId: node.id, kind: n.kind });
+    }
     if (nodes.has(node.id)) diagnostics.push({ level: 'error', code: 'DUPLICATE_NODE_ID', nodeId: node.id });
     nodes.set(node.id, node);
   });