concept-atlas-dense-explain 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.7.0",
+  "version": "0.8.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,17 +23,17 @@ 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
@@ -50,19 +48,19 @@ 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`).
 - **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/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/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);
   });

package/template/src/model/node-kinds.js

@@ -0,0 +1,68 @@
+/**
+ * Knowledge node kinds.
+ *
+ * `level` (L0–L4) answers "how deep in the zoom hierarchy is this node".
+ * `kind` answers "what role does this node play in the explanation" — a
+ * failure, a decision, a mechanism. The two axes are independent: an L2 node
+ * can be a mechanism or a boundary. Kinds let the graph, the validator and the
+ * inspector talk about knowledge type instead of only depth.
+ *
+ * The registry is the single source of truth: the validator checks against it,
+ * the graph filters by it, and the UI reads labels/tones from it. `tone` must
+ * resolve to a CSS variable defined in `tokens.css` for both themes.
+ */
+export const NODE_KINDS = {
+  system: {
+    label: '系统',
+    description: '整体系统、产品或问题域的全貌',
+    tone: 'var(--kind-system)',
+  },
+  stage: {
+    label: '阶段',
+    description: '生命周期阶段、处理步骤或子系统',
+    tone: 'var(--kind-stage)',
+  },
+  mechanism: {
+    label: '机制',
+    description: '可解释、可验证的工作机制',
+    tone: 'var(--kind-mechanism)',
+  },
+  artifact: {
+    label: '产物',
+    description: '阶段产出的实体、数据或文件',
+    tone: 'var(--kind-artifact)',
+  },
+  failure: {
+    label: '故障',
+    description: '失败模式、异常与边界情况',
+    tone: 'var(--kind-failure)',
+  },
+  tool: {
+    label: '工具',
+    description: '使用的工具、库或外部依赖',
+    tone: 'var(--kind-tool)',
+  },
+  boundary: {
+    label: '边界',
+    description: '约束、前提、限制与非目标',
+    tone: 'var(--kind-boundary)',
+  },
+  decision: {
+    label: '决策',
+    description: '设计取舍与选择点',
+    tone: 'var(--kind-decision)',
+  },
+};
+
+export const NODE_KIND_NAMES = Object.keys(NODE_KINDS);
+export const NODE_KIND_SET = new Set(NODE_KIND_NAMES);
+
+/** Coerce an arbitrary value to a registered kind id, or null. */
+export function normalizeKind(value) {
+  return typeof value === 'string' && NODE_KIND_SET.has(value) ? value : null;
+}
+
+/** Registry entry for a kind id, or null when unset/unknown. */
+export function kindInfo(kind) {
+  return kind ? NODE_KINDS[kind] || null : null;
+}

package/template/src/model/normalize-content.js

@@ -103,6 +103,7 @@ function parseConceptNode(nodeElement) {
     id: props.id,
     title: props.title || props.id,
     level: props.level || 'L2',
+    kind: props.kind || null,
     parent: props.parent !== undefined ? props.parent : null,
     children: [],
     summary: props.summary || '',
@@ -117,7 +118,13 @@ function parseConceptNode(nodeElement) {
     counterexamples: [],
     boundaries: [],
     glossary: [],
-    customSections: []
+    customSections: [],
+    learningObjectives: [],
+    keyQuestions: [],
+    evidence: [],
+    invariants: [],
+    failureModes: [],
+    tradeoffs: [],
   };
 
   Children.forEach(props.children, child => {
@@ -195,6 +202,51 @@ function parseConceptNode(nodeElement) {
           node.children.push(child.props.id);
         }
         break;
+      // Argument / evidence components are stored twice on purpose: as
+      // structured data for the graph, search and validator, and as the
+      // original element in customSections so existing rendering is unchanged.
+      case 'LearningObjectives':
+        node.learningObjectives.push(
+          ...(Array.isArray(child.props.items) ? child.props.items.filter(Boolean) : []),
+        );
+        node.customSections.push(child);
+        break;
+      case 'KeyQuestion':
+        node.keyQuestions.push({ content: child.props.children });
+        node.customSections.push(child);
+        break;
+      case 'Evidence':
+        node.evidence.push({
+          command: child.props.command || '',
+          observes: child.props.observes || '',
+          content: child.props.children,
+        });
+        node.customSections.push(child);
+        break;
+      case 'Invariant':
+        node.invariants.push({
+          title: child.props.title || '不变量',
+          content: child.props.children,
+        });
+        node.customSections.push(child);
+        break;
+      case 'FailureMode':
+        node.failureModes.push({
+          symptom: child.props.symptom || '',
+          cause: child.props.cause || '',
+          evidence: child.props.evidence || '',
+          remedy: child.props.remedy || '',
+          content: child.props.children,
+        });
+        node.customSections.push(child);
+        break;
+      case 'Tradeoff':
+        node.tradeoffs.push({
+          title: child.props.title || '工程权衡',
+          options: Array.isArray(child.props.options) ? child.props.options : [],
+        });
+        node.customSections.push(child);
+        break;
       default:
         // Semantic presentation components inside node
         node.customSections.push(child);

package/template/src/model/validate-content.js

@@ -1,4 +1,5 @@
 import { RELATION_TYPES, LEVEL_DEFS } from './relation-types.js';
+import { NODE_KIND_NAMES, NODE_KIND_SET } from './node-kinds.js';
 
 /**
  * Single source of truth for the semantic component registry.
@@ -365,6 +366,7 @@ export function validateMdxSource(source, options = {}) {
         id: attrValue(map, 'id'),
         title: attrValue(map, 'title'),
         level: attrValue(map, 'level') || 'L2',
+        kind: attrValue(map, 'kind'),
         parent: attrValue(map, 'parent'),
         summary: attrValue(map, 'summary'),
         offset: tag.start,
@@ -489,12 +491,23 @@ export function validateMdxSource(source, options = {}) {
     if (!LEVEL_SET.has(node.level)) {
       add('warning', 'UNKNOWN_LEVEL', `节点 ${label} 的 level 无效：${node.level}`, node.offset, node.id);
     }
+    if (node.kind && !NODE_KIND_SET.has(node.kind)) {
+      add('warning', 'UNKNOWN_KIND', `节点 ${label} 的 kind 无效：${node.kind}（可选：${NODE_KIND_NAMES.join('、')}）`, node.offset, node.id);
+    }
     if (node.parent && !nodesById.has(node.parent)) {
       add('error', 'MISSING_PARENT', `节点 ${label} 的 parent 不存在：${node.parent}`, node.offset, node.id);
     }
     if (node.body && ![...CORE_CONTENT_COMPONENTS].some(name => new RegExp(`<${name}\\b`).test(node.body))) {
       add('warning', 'NODE_NO_CORE_CONTENT', `节点 ${label} 缺少核心内容组件（Definition/Mechanism/Example/Boundary 等）`, node.offset, node.id);
     }
+    // Opt-in knowledge-kind contracts. They only fire once an author declares
+    // `kind`, so the existing corpus keeps validating clean.
+    if (node.kind === 'mechanism' && node.body && !/<(Invariant|Evidence)\b/.test(node.body)) {
+      add(strict ? 'error' : 'warning', 'MECHANISM_KIND_UNVERIFIED', `机制节点 ${label} 建议至少包含一个 <Invariant> 或 <Evidence>`, node.offset, node.id);
+    }
+    if (node.kind === 'failure' && node.body && !/<FailureMode\b/.test(node.body)) {
+      add(strict ? 'error' : 'warning', 'FAILURE_KIND_UNSTRUCTURED', `故障节点 ${label} 建议使用 <FailureMode> 描述现象、原因、证据与建议`, node.offset, node.id);
+    }
   }
 
   const l0 = nodes.filter(node => node.level === 'L0');
@@ -542,6 +555,17 @@ export function validateMdxSource(source, options = {}) {
     }
   }
 
+  // A self-closing <FailureMode /> with no fields carries no information; an
+  // open tag with children is left to the author.
+  for (const tag of tags) {
+    if (tag.name !== 'FailureMode' || tag.kind !== 'self') continue;
+    const map = attrsToMap(tag.attrs);
+    const hasField = ['symptom', 'cause', 'evidence', 'remedy'].some(field => attrValue(map, field));
+    if (!hasField) {
+      add('warning', 'FAILURE_MODE_EMPTY', 'FailureMode 缺少 symptom/cause/evidence/remedy，也没有子内容', tag.start, 'FailureMode');
+    }
+  }
+
   // Array-prop sanity: catches `steps="foo"` and `steps={obj}` early.
   for (const tag of tags) {
     const props = ARRAY_PROPS[tag.name];

package/template/src/styles/core.css

@@ -478,6 +478,9 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   cursor: pointer;
   color: var(--text-secondary);
   font-size: 13px;
+  font-family: inherit;
+  text-align: left;
+  width: 100%;
   transition: all 0.15s ease;
   background: transparent;
   border: 1px solid transparent;
@@ -787,6 +790,20 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   border: 1px solid var(--border-accent);
 }
 
+/* Knowledge kind: orthogonal to level, so it reads as a small pill next to it.
+   Color comes from --kind-* via the registry and is applied inline. */
+.kind-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 2px 8px;
+  border: 1px solid currentColor;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  opacity: 0.92;
+}
+
 .hero-title {
   font-size: 32px;
   font-weight: 800;
@@ -1377,7 +1394,10 @@ button.flow-box {
   left: 20px;
   display: flex;
   align-items: center;
+  flex-wrap: wrap;
   gap: 14px;
+  row-gap: 6px;
+  max-width: min(80%, 980px);
   background: var(--bg-surface);
   backdrop-filter: blur(12px);
   border: 1px solid var(--border-medium);
@@ -1412,6 +1432,17 @@ button.flow-box {
   border-radius: 50%;
 }
 
+/* Kind uses a ring (matching the graph's kind ring) instead of a fill. */
+.legend-ring {
+  background: transparent;
+  border: 2px solid var(--rel-default);
+}
+
+.legend-kinds {
+  padding-left: 14px;
+  border-left: 1px solid var(--border-medium);
+}
+
 .graph-svg {
   width: 100%;
   height: 100%;
@@ -2170,6 +2201,13 @@ button.flow-box {
   gap: 16px;
 }
 
+.panel-badges {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+
 .panel-badge {
   font-size: 11px;
   font-weight: 800;
@@ -2177,6 +2215,21 @@ button.flow-box {
   letter-spacing: 0.06em;
 }
 
+/* Structured argument/evidence counts, derived from the node model. */
+.panel-verified {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  font-size: 11px;
+  color: var(--text-dim);
+}
+
+.panel-verified span {
+  border: 1px solid var(--border-medium);
+  border-radius: 999px;
+  padding: 2px 8px;
+}
+
 .panel-node-title {
   font-size: 22px;
   font-weight: 800;

package/template/src/styles/tokens.css

@@ -105,6 +105,17 @@
   --level-l3: #fbbf24;
   --level-l4: #f87171;
 
+  /* Knowledge kind accents (orthogonal to level; consumed by kind badges,
+     graph rings and legends). Keep in sync with model/node-kinds.js */
+  --kind-system: #818cf8;
+  --kind-stage: #38bdf8;
+  --kind-mechanism: #34d399;
+  --kind-artifact: #fbbf24;
+  --kind-failure: #f87171;
+  --kind-tool: #c084fc;
+  --kind-boundary: #94a3b8;
+  --kind-decision: #2dd4bf;
+
   /* Graph background grids */
   --graph-grid: radial-gradient(circle, rgba(255, 255, 255, 0.06) 1px, transparent 1px);
   --explorer-grid:
@@ -215,6 +226,16 @@
   --level-l3: #d97706;
   --level-l4: #dc2626;
 
+  /* Knowledge kind accents (see dark block above) */
+  --kind-system: #6366f1;
+  --kind-stage: #0284c7;
+  --kind-mechanism: #059669;
+  --kind-artifact: #d97706;
+  --kind-failure: #dc2626;
+  --kind-tool: #9333ea;
+  --kind-boundary: #64748b;
+  --kind-decision: #0d9488;
+
   /* Graph background grids */
   --graph-grid: radial-gradient(circle, rgba(0, 0, 0, 0.07) 1px, transparent 1px);
   --explorer-grid:

package/template/src/views/NodeExplorer.jsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { ChevronRight, ArrowUpRight, CornerDownRight, ArrowLeft, Network, CornerLeftUp, ZoomIn, ZoomOut, RotateCcw, Link as LinkIcon } from 'lucide-react';
 import { getAncestorPath, getSiblingNodes } from '../model/concept-schema.js';
 import { LEVEL_DEFS } from '../model/relation-types.js';
+import { NODE_KINDS } from '../model/node-kinds.js';
 
 export function NodeExplorer({
   graph,
@@ -133,6 +134,7 @@ export function NodeExplorer({
 
   // Level definition
   const levelInfo = LEVEL_DEFS[currentNode.level] || { name: currentNode.level, tag: currentNode.level, color: 'var(--level-l0)' };
+  const kindDef = currentNode.kind ? NODE_KINDS[currentNode.kind] || null : null;
 
   return (
     <div className="node-explorer-layout">
@@ -144,18 +146,20 @@ export function NodeExplorer({
             {ancestorPath.map((node, index) => {
               const isCurrent = node.id === currentNode.id;
               return (
-                <div
+                <button
+                  type="button"
                   key={node.id}
                   className={`breadcrumb-node ${isCurrent ? 'active' : ''}`}
                   onClick={() => onSelectNode(node.id)}
                   title={node.title}
+                  aria-current={isCurrent ? 'page' : undefined}
                 >
                   <span className="bc-level-pill" style={{ borderColor: LEVEL_DEFS[node.level]?.color }}>
                     {node.level}
                   </span>
                   <span className="bc-title">{node.title}</span>
                   {index < ancestorPath.length - 1 && <ChevronRight size={14} className="bc-arrow" />}
-                </div>
+                </button>
               );
             })}
           </div>
@@ -263,6 +267,15 @@ export function NodeExplorer({
           <article className="concept-hero-card">
             <div className="hero-level-banner" style={{ color: levelInfo.color }}>
               <span className="badge">{levelInfo.tag}</span>
+              {kindDef && (
+                <span
+                  className="kind-badge"
+                  style={{ color: kindDef.tone, borderColor: kindDef.tone }}
+                  title={kindDef.description}
+                >
+                  {kindDef.label}
+                </span>
+              )}
               <span className="desc">{levelInfo.desc}</span>
             </div>
 
@@ -286,6 +299,24 @@ export function NodeExplorer({
                   <span className="chip-value">{currentNode.output}</span>
                 </div>
               )}
+              {currentNode.invariants.length > 0 && (
+                <div className="meta-chip">
+                  <span className="chip-label">不变量</span>
+                  <span className="chip-value">{currentNode.invariants.length}</span>
+                </div>
+              )}
+              {currentNode.evidence.length > 0 && (
+                <div className="meta-chip">
+                  <span className="chip-label">证据</span>
+                  <span className="chip-value">{currentNode.evidence.length}</span>
+                </div>
+              )}
+              {currentNode.failureModes.length > 0 && (
+                <div className="meta-chip">
+                  <span className="chip-label">故障模式</span>
+                  <span className="chip-value">{currentNode.failureModes.length}</span>
+                </div>
+              )}
               <div className="meta-chip">
                 <span className="chip-label">完整路径</span>
                 <span className="chip-value">{ancestorPath.map(n => n.title).join(' / ')}</span>

package/template/src/views/RelationGraph.jsx

@@ -12,8 +12,9 @@ import {
   hierarchy,
   tree as treeLayout,
 } from 'd3';
-import { Search, Filter, ZoomIn, ZoomOut, RotateCcw, ArrowRight, Layers, Eye } from 'lucide-react';
+import { Search, ArrowRight, Eye } from 'lucide-react';
 import { RELATION_TYPES, LEVEL_DEFS } from '../model/relation-types.js';
+import { NODE_KINDS, NODE_KIND_NAMES } from '../model/node-kinds.js';
 
 export function RelationGraph({
   graph,
@@ -24,20 +25,36 @@ export function RelationGraph({
   const { nodes, relations } = graph;
   const svgRef = useRef(null);
   const containerRef = useRef(null);
+  // The D3 layout owns the simulation; selection styling is applied by a
+  // separate effect so changing the focused node never rebuilds the layout.
+  const nodesSelectionRef = useRef(null);
+  const nodeHaloRef = useRef(null);
+  const nodeLabelRef = useRef(null);
+  const zoomBehaviorRef = useRef(null);
+  const positionedNodesRef = useRef([]);
+  const selectedNodeIdRef = useRef(null);
 
   // States
   const [selectedNodeId, setSelectedNodeId] = useState(currentNodeId || graph.meta.rootId);
   const [searchQuery, setSearchQuery] = useState('');
   const [filterLevel, setFilterLevel] = useState('ALL');
+  const [filterKind, setFilterKind] = useState('ALL');
   const [filterRelationType, setFilterRelationType] = useState('ALL');
-  const [highlightNeighbors, setHighlightNeighbors] = useState(true);
   const [graphMode, setGraphMode] = useState('hierarchy');
+  selectedNodeIdRef.current = selectedNodeId;
 
   // Convert nodes map to array
   const allNodes = useMemo(() => Array.from(nodes.values()), [nodes]);
 
+  // Kinds actually present in this document, for the filter and the legend.
+  const presentKinds = useMemo(
+    () => NODE_KIND_NAMES.filter(kind => allNodes.some(node => node.kind === kind)),
+    [allNodes],
+  );
+
   // Active focused node details
   const focusedNode = nodes.get(selectedNodeId) || null;
+  const focusedKind = focusedNode?.kind ? NODE_KINDS[focusedNode.kind] || null : null;
 
   useEffect(() => {
     if (currentNodeId && nodes.has(currentNodeId)) {
@@ -53,6 +70,12 @@ export function RelationGraph({
       filteredNodes = filteredNodes.filter(n => n.level === filterLevel);
     }
 
+    if (filterKind !== 'ALL') {
+      filteredNodes = filterKind === 'NONE'
+        ? filteredNodes.filter(n => !n.kind)
+        : filteredNodes.filter(n => n.kind === filterKind);
+    }
+
     if (searchQuery.trim()) {
       const q = searchQuery.toLowerCase();
       filteredNodes = filteredNodes.filter(n =>
@@ -115,7 +138,7 @@ export function RelationGraph({
       graphNodes: filteredNodes.map(n => ({ ...n })),
       graphLinks: links
     };
-  }, [allNodes, nodes, relations, filterLevel, filterRelationType, searchQuery]);
+  }, [allNodes, nodes, relations, filterLevel, filterKind, filterRelationType, searchQuery]);
 
   // Neighbors of focused node
   const { connectedNodeIds, directRelations } = useMemo(() => {
@@ -143,6 +166,10 @@ export function RelationGraph({
 
   // Setup D3 Force Simulation
   useEffect(() => {
+    nodesSelectionRef.current = null;
+    nodeHaloRef.current = null;
+    nodeLabelRef.current = null;
+    positionedNodesRef.current = [];
     if (!svgRef.current || !containerRef.current) return;
 
     const width = containerRef.current.clientWidth || 900;
@@ -183,6 +210,7 @@ export function RelationGraph({
       });
 
     svg.call(zoomBehavior);
+    zoomBehaviorRef.current = zoomBehavior;
 
     // Plain wheel scrolls the canvas vertically; Ctrl/Cmd + wheel zooms.
     const handleWheelPan = (event) => {
@@ -212,6 +240,7 @@ export function RelationGraph({
         }))
       : layoutTree(graphNodes, width, height);
     const nodeById = new Map(positionedNodes.map(node => [node.id, node]));
+    positionedNodesRef.current = positionedNodes;
     const positionedLinks = decorateParallelLinks(visibleGraphLinks
       .map(link => ({
         ...link,
@@ -278,12 +307,20 @@ export function RelationGraph({
       .data(positionedNodes)
       .enter()
       .append('g')
-      .attr('class', d => `node-item ${d.id === selectedNodeId ? 'selected' : ''}`)
+      .attr('class', d => `node-item ${d.id === selectedNodeIdRef.current ? 'selected' : ''}`)
       .on('click', (event, d) => {
         event.stopPropagation();
         setSelectedNodeId(d.id);
         onSelectNode(d.id);
       });
+    nodesSelectionRef.current = nodesSelection;
+
+    // Native SVG tooltip: level is always shown; kind is appended when set.
+    nodesSelection.append('title')
+      .text(d => {
+        const kind = d.kind && NODE_KINDS[d.kind] ? ` · ${NODE_KINDS[d.kind].label}` : '';
+        return `${d.title} · ${d.level}${kind}`;
+      });
 
     if (isConceptMode) {
       nodesSelection.call(drag()
@@ -304,13 +341,16 @@ export function RelationGraph({
       );
     }
 
-    // Outer glow for selected or level
-    nodesSelection.append('circle')
+    // Outer glow for selected or level. When a knowledge kind is declared its
+    // tone recolours the ring, so level (fill) and kind (ring) read together.
+    nodeHaloRef.current = nodesSelection.append('circle')
       .attr('r', d => (d.level === 'L0' ? 24 : d.level === 'L1' ? 20 : 16))
       .style('fill', d => LEVEL_DEFS[d.level]?.color || 'var(--level-l0)')
       .attr('fill-opacity', 0.2)
-      .style('stroke', d => LEVEL_DEFS[d.level]?.color || 'var(--level-l0)')
-      .attr('stroke-width', d => d.id === selectedNodeId ? 3 : 1.5);
+      .style('stroke', d => (d.kind && NODE_KINDS[d.kind]
+        ? NODE_KINDS[d.kind].tone
+        : (LEVEL_DEFS[d.level]?.color || 'var(--level-l0)')))
+      .attr('stroke-width', d => d.id === selectedNodeIdRef.current ? 3 : 1.5);
 
     // Inner center dot
     nodesSelection.append('circle')
@@ -318,13 +358,13 @@ export function RelationGraph({
       .style('fill', d => LEVEL_DEFS[d.level]?.color || 'var(--level-l0)');
 
     // Node Title Label
-    nodesSelection.append('text')
+    nodeLabelRef.current = nodesSelection.append('text')
       .attr('dy', d => (d.level === 'L0' ? 38 : 30))
       .attr('text-anchor', 'middle')
       .style('fill', 'var(--text-primary)')
       .attr('font-size', '12px')
       .attr('font-family', labelFont)
-      .attr('font-weight', d => d.id === selectedNodeId ? '700' : '500')
+      .attr('font-weight', d => d.id === selectedNodeIdRef.current ? '700' : '500')
       .text(d => d.title);
 
     // Node Level Pill
@@ -351,23 +391,34 @@ export function RelationGraph({
       renderPositions();
     }
 
-    // Auto-focus selected node center
-    if (!isConceptMode && selectedNodeId) {
-      const targetNode = positionedNodes.find(n => n.id === selectedNodeId);
-      if (targetNode) {
-        const transform = zoomIdentity
-          .translate(width / 2 - targetNode.x, height / 2 - targetNode.y)
-          .scale(1.1);
-        svg.transition().duration(500).call(zoomBehavior.transform, transform);
-      }
-    }
-
     return () => {
       simulation?.stop();
       svg.on('wheel.pan', null);
       svg.on('.zoom', null);
     };
-  }, [graphNodes, graphLinks, selectedNodeId, graphMode]);
+  }, [graphNodes, graphLinks, graphMode]);
+
+  // Selection styling lives outside the layout effect: clicking a node updates
+  // its class/stroke and re-centres the canvas without rebuilding the
+  // simulation or resetting drag positions.
+  useEffect(() => {
+    const nodesSelection = nodesSelectionRef.current;
+    if (!nodesSelection) return;
+
+    nodesSelection.attr('class', d => `node-item ${d.id === selectedNodeId ? 'selected' : ''}`);
+    nodeHaloRef.current?.attr('stroke-width', d => (d.id === selectedNodeId ? 3 : 1.5));
+    nodeLabelRef.current?.attr('font-weight', d => (d.id === selectedNodeId ? '700' : '500'));
+
+    if (graphMode === 'concept' || !selectedNodeId || !svgRef.current || !containerRef.current || !zoomBehaviorRef.current) return;
+    const targetNode = positionedNodesRef.current.find(node => node.id === selectedNodeId);
+    if (!targetNode) return;
+    const width = containerRef.current.clientWidth || 900;
+    const height = containerRef.current.clientHeight || 650;
+    const transform = zoomIdentity
+      .translate(width / 2 - targetNode.x, height / 2 - targetNode.y)
+      .scale(1.1);
+    select(svgRef.current).transition().duration(500).call(zoomBehaviorRef.current.transform, transform);
+  }, [selectedNodeId, graphNodes, graphMode]);
 
   return (
     <div className="relation-graph-layout">
@@ -413,6 +464,19 @@ export function RelationGraph({
             </select>
           </div>
 
+          {presentKinds.length > 0 && (
+            <div className="filter-group">
+              <span className="filter-label">知识类型:</span>
+              <select value={filterKind} onChange={e => setFilterKind(e.target.value)}>
+                <option value="ALL">全部类型</option>
+                {presentKinds.map(kindId => (
+                  <option key={kindId} value={kindId}>{NODE_KINDS[kindId].label} ({kindId})</option>
+                ))}
+                {allNodes.some(node => !node.kind) && <option value="NONE">未分类</option>}
+              </select>
+            </div>
+          )}
+
           <div className="filter-group">
             <span className="filter-label">关系类型:</span>
             <select value={filterRelationType} onChange={e => setFilterRelationType(e.target.value)}>
@@ -435,6 +499,17 @@ export function RelationGraph({
               </div>
             ))}
           </div>
+          {presentKinds.length > 0 && (
+            <div className="legend-items legend-kinds">
+              <div className="legend-title">知识类型:</div>
+              {presentKinds.map(kindId => (
+                <div key={kindId} className="legend-item">
+                  <span className="legend-dot legend-ring" style={{ borderColor: NODE_KINDS[kindId].tone }} />
+                  <span>{NODE_KINDS[kindId].label}</span>
+                </div>
+              ))}
+            </div>
+          )}
         </div>
 
         {/* SVG Container */}
@@ -445,12 +520,31 @@ export function RelationGraph({
       <aside className="graph-side-panel">
         {focusedNode ? (
           <div className="graph-inspector">
-            <div className="panel-badge" style={{ color: LEVEL_DEFS[focusedNode.level]?.color }}>
-              {LEVEL_DEFS[focusedNode.level]?.tag || focusedNode.level}
+            <div className="panel-badges">
+              <div className="panel-badge" style={{ color: LEVEL_DEFS[focusedNode.level]?.color }}>
+                {LEVEL_DEFS[focusedNode.level]?.tag || focusedNode.level}
+              </div>
+              {focusedKind && (
+                <span
+                  className="kind-badge"
+                  style={{ color: focusedKind.tone, borderColor: focusedKind.tone }}
+                  title={focusedKind.description}
+                >
+                  {focusedKind.label}
+                </span>
+              )}
             </div>
             <h2 className="panel-node-title">{focusedNode.title}</h2>
             <p className="panel-summary">{focusedNode.summary || '暂无一句话概览'}</p>
 
+            {(focusedNode.invariants.length > 0 || focusedNode.failureModes.length > 0 || focusedNode.evidence.length > 0) && (
+              <div className="panel-verified">
+                {focusedNode.invariants.length > 0 && <span>不变量 {focusedNode.invariants.length}</span>}
+                {focusedNode.evidence.length > 0 && <span>证据 {focusedNode.evidence.length}</span>}
+                {focusedNode.failureModes.length > 0 && <span>故障模式 {focusedNode.failureModes.length}</span>}
+              </div>
+            )}
+
             {/* Jump to Node Explorer Button */}
             <button
               className="jump-explorer-btn"