concept-atlas-dense-explain 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/skill/SKILL.md +37 -27
package/package.json
CHANGED
package/skill/SKILL.md
CHANGED
|
@@ -1,37 +1,39 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: concept-atlas-dense-explain
|
|
3
|
-
description:
|
|
3
|
+
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.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Concept Atlas Dense Explain
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
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`.
|
|
9
|
+
|
|
10
|
+
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.
|
|
9
11
|
|
|
10
12
|
## Workflow
|
|
11
13
|
|
|
12
|
-
1. Choose
|
|
13
|
-
2. **Learn the
|
|
14
|
+
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.
|
|
15
|
+
2. **Learn the components from the canonical guide before authoring.** Generate the guide for the chosen shell into a temporary path and read it:
|
|
14
16
|
```bash
|
|
15
|
-
npx concept-atlas-dense-explain guide --mode atlas -o concept-atlas-atlas-guide.mdx
|
|
16
|
-
npx concept-atlas-dense-explain guide --mode scroll -o concept-atlas-scroll-guide.mdx
|
|
17
|
+
npx concept-atlas-dense-explain guide --mode atlas -o ./concept-atlas-atlas-guide.mdx
|
|
18
|
+
npx concept-atlas-dense-explain guide --mode scroll -o ./concept-atlas-scroll-guide.mdx
|
|
17
19
|
```
|
|
18
|
-
|
|
19
|
-
3.
|
|
20
|
-
4. Write semantic MDX
|
|
21
|
-
5. Validate
|
|
20
|
+
It is a real, compilable MDX file demonstrating every component and its exact props. Search it for a component name to copy the correct prop shape instead of guessing. Delete it when done.
|
|
21
|
+
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.
|
|
22
|
+
4. Write the semantic MDX into the user's `.mdx` file (see Authoring rules).
|
|
23
|
+
5. Validate before rendering:
|
|
22
24
|
```bash
|
|
23
25
|
npx concept-atlas-dense-explain validate <file>.mdx --mode atlas|scroll
|
|
24
|
-
npx concept-atlas-dense-explain validate <file>.mdx --json
|
|
26
|
+
npx concept-atlas-dense-explain validate <file>.mdx --json
|
|
25
27
|
```
|
|
26
|
-
|
|
27
|
-
6. Compile
|
|
28
|
-
7. Report the
|
|
28
|
+
Every diagnostic is `CODE line:column message`. Fix all `error`s and re-run; warnings are quality signals you should also address when cheap.
|
|
29
|
+
6. Compile: `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html]`. 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.
|
|
30
|
+
7. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
|
|
29
31
|
|
|
30
32
|
## Carriers
|
|
31
33
|
|
|
32
|
-
- `atlas`: `ExplainPage` → `ConceptGraph` → `ConceptNode
|
|
33
|
-
- `scroll`: `ScrollDocument` → `ScrollHeader` + `ScrollSection` (+ `ScrollProse`, `ScrollGrid`). Shared components
|
|
34
|
-
- Never
|
|
34
|
+
- `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.
|
|
35
|
+
- `scroll`: `ScrollDocument` → `ScrollHeader` + `ScrollSection` (+ `ScrollProse`, `ScrollGrid`). Shared components live inside sections. The shell auto-builds a table of contents, reading progress, and prev/next from section titles — do not hand-build navigation.
|
|
36
|
+
- Never make one MDX file both shells. When switching shells, convert only the outer structure.
|
|
35
37
|
|
|
36
38
|
## Component families
|
|
37
39
|
|
|
@@ -43,18 +45,26 @@ Use the `concept-atlas-dense-explain` npm CLI. This skill is intentionally light
|
|
|
43
45
|
|
|
44
46
|
## Authoring rules
|
|
45
47
|
|
|
46
|
-
- Keep MDX semantic
|
|
47
|
-
- Give important
|
|
48
|
-
- Array props
|
|
49
|
-
-
|
|
50
|
-
- **
|
|
51
|
-
- **
|
|
52
|
-
- **
|
|
53
|
-
-
|
|
54
|
-
-
|
|
48
|
+
- Keep MDX semantic. Never write CSS, coordinates, SVG, or replacement application code; never invent component names or props.
|
|
49
|
+
- 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`.
|
|
50
|
+
- 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.
|
|
51
|
+
- `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`.
|
|
52
|
+
- **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`).
|
|
53
|
+
- **Chart**: `type` is `bar` | `line` | `pie`; use `data` for bar/pie and `labels` + `series={[{name, values}]}` for line. Charts follow theme colors.
|
|
54
|
+
- **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.
|
|
55
|
+
- **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.
|
|
56
|
+
- 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.
|
|
57
|
+
- Be brief about cost: KaTeX fonts and Mermaid roughly double the single-file output (~5 MB), which is normal for an offline explainer. Mention it if the user cares about file size.
|
|
55
58
|
|
|
56
59
|
## Validation diagnostics
|
|
57
60
|
|
|
58
|
-
`validate` and the build
|
|
61
|
+
`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_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`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `GRAPH_MISSING_ROOT`, `ASSET_MISSING`.
|
|
62
|
+
|
|
63
|
+
## Before you report
|
|
64
|
+
|
|
65
|
+
- All `error` diagnostics resolved (or `--no-validate` explicitly justified).
|
|
66
|
+
- All `ConceptRef`, `Relation` endpoints, and `ConceptGraph root` point at existing node ids.
|
|
67
|
+
- Every node has `title` + `summary`; every `Relation` has a `label`.
|
|
68
|
+
- The HTML file exists at the reported path.
|
|
59
69
|
|
|
60
70
|
If the CLI or npm registry is unavailable, report the blocker instead of copying the implementation into the skill.
|