@liduchuan/atlas-loop 0.1.0 → 0.1.1

package/README.md

@@ -1,12 +1,12 @@
-# AtlasLoop (`@liduchuan/atlas-loop`)
+# Atlas Loop (`@liduchuan/atlas-loop`)
 
 A universal recursive learning-map Agent Skill that dissects **any unfamiliar subject**—a scientific concept, craft, business model, book, software tool, or codebase—into a **standalone, zero-CDN offline interactive HTML atlas**, complete with per-node `?` follow-up and recursive sub-atlas prompts.
 
-## Why AtlasLoop
+## Why Atlas Loop
 
 Learners tackling an unfamiliar topic usually hit two walls: **getting lost in flat walls of detail before grasping the big picture**, and **not knowing what to ask next once the basics make sense**.
 
-`AtlasLoop` closes both gaps in one repeatable loop:
+`Atlas Loop` closes both gaps in one repeatable loop:
 
 1. **L0 Overview → Inline Detail Drill-Down**: Renders causal streams and a recommended learning path on an `@xyflow/react` + `Dagre` auto-layout canvas. Complex nodes encapsulate an internal `detailGraph` that expands and re-layouts dynamically without overlapping neighbors.
 2. **Per-Node `?` Loop Prompts**: Every stream and core node carries an isolated `?` badge (hover to preview nuances, click to open one-click copyable prompts):
@@ -18,7 +18,7 @@ Learners tackling an unfamiliar topic usually hit two walls: **getting lost in f
 
 ## What You Can Dissect
 
-`AtlasLoop` imposes no domain lock-in:
+`Atlas Loop` imposes no domain lock-in:
 
 - **Disciplines, Mental Models & Crafts**: e.g., *Espresso Extraction Physics*, *Macroeconomic Rate Transmission*, *Raft Consensus*
 - **Books & Long-Form Papers**: Core theses, chapter-by-chapter argument structure, key mental models, and counterexamples
@@ -27,8 +27,6 @@ Learners tackling an unfamiliar topic usually hit two walls: **getting lost in f
 
 ## Installation
 
-### Via `skills` CLI or `npx`
-
 ```bash
 # Install with the universal Agent Skills CLI
 npx skills add @liduchuan/atlas-loop
@@ -40,24 +38,38 @@ npx @liduchuan/atlas-loop install
 npx @liduchuan/atlas-loop install --dir /path/to/skills
 ```
 
-### Via Git
-
-```bash
-git clone https://github.com/liduchuan/Atlas-Loop.git ~/.agents/skills/atlas-loop
-```
-
 ## Example Prompts
 
 - **L0 Overview**:
-  - `Use AtlasLoop to map out the core argument structure of Thinking, Fast and Slow`
-  - `Use AtlasLoop to explain how Kubernetes Pod networking works`
-  - `Use AtlasLoop to generate an interactive learning map for this project`
+  - `Use Atlas Loop to map out the core argument structure of Thinking, Fast and Slow`
+  - `Use Atlas Loop to explain how Kubernetes Pod networking works`
+  - `Use Atlas Loop to generate an interactive learning map for this project`
 - **L1+ Recursive Deep Dive**:
-  - Open the generated `.html` file → click `?` on any core node → switch to **Recursive Sub-Atlas Prompt**, copy, and send it to your agent to generate a linked child atlas.
+  - Open the generated `.html` file → click `?` on any core node → switch to **Recursive Sub-Atlas**, copy, and send it to your agent to generate a linked child atlas.
+
+## Local Template Runtime (Style & UI Debugging)
+
+`template/` contains the unminified React source (`app.jsx`), stylesheet (`styles.css`), sample dataset (`sample-data.json`), and a live-reload preview server for iterating on visual design:
+
+```bash
+# 1. Install dev dependencies once
+npm install
+
+# 2. Start the live-reload preview server at http://localhost:5179
+#    - Editing template/styles.css hot-swaps CSS in place without losing canvas state
+#    - Editing template/app.jsx or sample-data.json rebuilds and reloads automatically
+npm run dev
+
+# Optional: preview with your own AtlasGraphData JSON file or custom port
+node template/dev-server.mjs --data /path/to/graph-data.json --port 5180
+
+# 3. Bake your template changes into assets/viewer-shell.html
+npm run build:shell
+```
 
 ## CLI Usage
 
-The agent invokes the bundled synthesis and verification tools automatically inside `/tmp` without touching your working tree. You can also run them directly via `npx`:
+The agent invokes the bundled synthesis and verification tools automatically inside `/tmp` without touching your working tree. You can also run them directly:
 
 ```bash
 # 1. Validate AtlasGraphData JSON and synthesize a standalone offline HTML file
@@ -71,16 +83,22 @@ Canvas semantics enforced by verification:
 
 - **Fit View**: Adjusts viewport pan/zoom only—preserves user-dragged node positions and active stream filters.
 - **Reset**: Dedicated button that restores initial Dagre coordinates, initial viewport, collapsed defaults, and all-streams view while clearing search and modals.
-- **Lock Nodes**: Prevents accidental node dragging while keeping pan, zoom, node inspection, and `?` prompt copying active.
+- **Lock**: Prevents accidental node dragging while keeping pan, zoom, node inspection, and `?` prompt copying active.
 
 ## Repository Layout
 
 ```text
 Atlas-Loop/
-├── package.json              # @liduchuan/atlas-loop package manifest
+├── package.json              # @liduchuan/atlas-loop manifest & dev scripts
 ├── bin/
-│   └── atlas-loop.mjs        # npx CLI (install, build, verify)
+│   └── atlas-loop.mjs        # CLI (install, dev, build, verify)
 ├── SKILL.md                  # Trigger rules, language sniffing, grounding rules, and execution workflow
+├── template/
+│   ├── app.jsx               # Unminified React + @xyflow/react UI source
+│   ├── styles.css            # Design tokens & restrained monochrome stylesheet
+│   ├── sample-data.json      # Rich sample dataset for local preview
+│   ├── dev-server.mjs        # Live-reload HTTP server (CSS hot-swap + JS rebuild)
+│   └── build-shell.mjs       # Compiles template into assets/viewer-shell.html
 ├── references/
 │   └── schema.md             # AtlasGraphData v2 JSON schema and polymorphic anchor specification
 ├── assets/

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: atlas-loop
-description: Dissect any unfamiliar subject—a discipline, mental model, craft, book, software tool, protocol, business model, or local project—into a standalone offline interactive HTML learning map (AtlasLoop) with overview-to-detail drill-down and per-node "?" deep-dive & recursive sub-atlas prompts. Trigger whenever the user wants to learn, break down, map out, or recursively explore any topic or codebase as an interactive visual map.
+description: Dissect any unfamiliar subject—a discipline, mental model, craft, book, software tool, protocol, business model, or local project—into a standalone offline interactive HTML learning map (Atlas Loop) with overview-to-detail drill-down and per-node "?" deep-dive & recursive sub-atlas prompts. Trigger whenever the user wants to learn, break down, map out, or recursively explore any topic or codebase as an interactive visual map.
 ---
 
-# AtlasLoop
+# Atlas Loop
 
 Turn any subject worth learning into a single-file, zero-CDN interactive `@xyflow/react` HTML atlas that pairs **big-picture causal structure** with **drill-down internals**, **verifiable anchors**, and **per-node `?` recursive inquiry prompts**.
 
@@ -14,8 +14,8 @@ Turn any subject worth learning into a single-file, zero-CDN interactive `@xyflo
    - Otherwise, sniff the dominant language of the user's prompt and target material; when they align, use that language for all explanations and UI labels while keeping technical identifiers, proper nouns, commands, and original filenames intact.
    - **Ask When Ambiguous**: If the user's request language conflicts with the target material or is too terse to tell, ask the user which output language they prefer before generating.
 2. **Unrestricted Subject Matter**:
-   - Never restrict targets to codebases. A target can be any new thing: a scientific concept, craft, historical event, book, paper, CLI/software workflow, architecture, or local file/code project.
-   - Ignore Git metadata completely—do not inspect branches, commit hashes, or working-tree status, and do not put Git state in titles or filenames.
+   - A target can be any unfamiliar subject: a scientific concept, craft, historical event, book, paper, CLI/software workflow, system architecture, or local project.
+   - Focus strictly on the subject's domain concepts, causal mechanisms, and primary source materials—never collect or mention version-control repository state.
 3. **Determine Recursion Level (`L0` vs `L1+`)**:
    - **L0 Overview** (no `drillDownTarget`): Map the subject's primary streams end-to-end (`entry → core mechanisms → branches/trade-offs → foundations/context → outcomes`), including important failure modes, counterexamples, or exceptions. List omitted areas honestly in `meta.uncoveredScopes`.
    - **L1+ Focused Sub-Atlas** (`drillDownTarget` specified): Root the entire map on that specific node or sub-topic, unpacking its internal states, edge cases, step-by-step mechanics, and boundary contracts. Set `meta.level` (`1`, `2`, ...) and `meta.parentMapHtml` (if known) so the header renders a clickable back-link to the parent atlas.
@@ -25,8 +25,8 @@ Turn any subject worth learning into a single-file, zero-CDN interactive `@xyflo
 Read [`references/schema.md`](references/schema.md) for exact field rules before writing JSON.
 
 1. **Ground Every Claim**:
-   - Inspect primary evidence first (actual files/code when local files exist; authoritative docs/text/principles otherwise).
-   - Mark solidly supported nodes `"confidence": "verified"`. Whenever a relationship, runtime binding, version nuance, or cross-chapter inference cannot be 100% confirmed from available evidence, set `"confidence": "unverified"`, populate `unverifiedReason`, and summarize in `meta.unverifiedNotes`. Never fabricate paths, line numbers, citations, or URLs.
+   - Inspect primary evidence first (actual files when local files exist; authoritative docs, text, or domain principles otherwise).
+   - Mark solidly supported nodes `"confidence": "verified"`. Whenever a relationship, runtime binding, edition nuance, or cross-chapter inference cannot be 100% confirmed from available evidence, set `"confidence": "unverified"`, populate `unverifiedReason`, and summarize in `meta.unverifiedNotes`. Never fabricate paths, line numbers, citations, or URLs.
    - Attach polymorphic `anchors` only as appropriate to the subject: `snippet` (formulas, commands, checklists), `source` (citations, chapters), `link` (reference URLs), or `editor` (verified local `absPath` + `line` for `vscode` or `zed`, never plain `file://`).
 2. **Design Two-Layer Clarity**:
    - Keep the overview readable by grouping flows into `streams` with an ordered `learningOrder`.
@@ -55,5 +55,7 @@ Run all intermediate files in `/tmp/atlas-loop-<timestamp>/` so the user's worki
    ```
    - Must pass all checks: zero `pageerror`, non-zero bounding boxes, zero severe node overlaps, zoom/pan, lock/unlock drag protection, `detailGraph` expand/collapse, `?` tooltip + dual-tab prompt copy, and strict separation between **Fit View** (viewport-only) and **Reset** (full restore to initial positions, filters, and collapsed state).
 3. **Clean Up & Deliver**:
-   - Remove the temporary `/tmp/atlas-loop-<ts>/` folder (keep `/tmp/atlas-loop-verifier` cache if helpful, or clean intermediate JSON).
+   - Remove the temporary `/tmp/atlas-loop-<ts>/` folder.
    - Deliver the generated `.html` file and report concisely: output path, language & level (`L0` or `L1+`), active model, covered streams, representative `?` deep-dive directions, Playwright verification result (if `editor` anchors were generated without desktop launch testing, note that OS editor launch itself was not desktop-tested), and any `uncoveredScopes` or `unverifiedNotes`.
+
+*(For UI customization or stylesheet debugging on the canvas template itself, run `node <skill_dir>/template/dev-server.mjs` for live reload and `node <skill_dir>/template/build-shell.mjs` to rebuild `assets/viewer-shell.html`.)*