@xmindltd/xmind-cli 0.2.1

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@xmindltd/xmind-cli",
+  "version": "0.2.1",
+  "description": "XMind CLI — Create and edit .xmind files for AI Agents",
+  "author": "Xmind Ltd.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/xmindltd/xmind-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xmindltd/xmind-cli.git"
+  },
+  "keywords": [
+    "xmind",
+    "mindmap",
+    "cli",
+    "ai",
+    "agent",
+    "claude-code",
+    "cursor",
+    "codex"
+  ],
+  "type": "commonjs",
+  "bin": {
+    "xmind": "dist/cli.mjs"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "build:gated": "XMIND_CLI_GATE_PREMIUM=1 node build.mjs",
+    "build:release": "XMIND_CLI_RELEASE=1 node build.mjs && node verify-release-package.mjs",
+    "release:prepare": "npm test && npm run pack:release",
+    "build:tsup": "tsup",
+    "build:tsc": "tsc",
+    "dev": "tsc --watch",
+    "dev:skill": "node build.mjs && rm -f xmind-file-cli.skill && zip xmind-file-cli.skill SKILL.md && echo '✓ xmind-file-cli.skill rebuilt'",
+    "pack:release": "npm run build:release && npm pack",
+    "pack:skill:file": "XMIND_CLI_GATE_PREMIUM=1 node build.mjs && rm -rf xmind-cli-*.tgz xmind-file.skill && npm pack && zip -j xmind-file.skill ../../skills/xmind-file/SKILL.md xmind-cli-*.tgz && rm -f xmind-cli-*.tgz && echo '✓ xmind-file.skill packed'",
+    "pack:skill": "npm run pack:skill:file",
+    "pack:skill:offline": "node pack-offline-skill.mjs",
+    "prepublishOnly": "node verify-release-package.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node build.mjs --test-index && node --test"
+  },
+  "dependencies": {
+    "open": "^10.0.0",
+    "undici": "^6.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^9.0.0",
+    "@xmindltd/mindmap-tools": "workspace:*",
+    "@xmindltd/snowdust": "*",
+    "commander": "^12.0.0",
+    "esbuild": "^0.27.4",
+    "javascript-obfuscator": "^5.4.3",
+    "jszip": "^3.10.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.3",
+    "uuid": "^9.0.0"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "skills"
+  ]
+}

package/skills/decoration/SKILL.md

@@ -0,0 +1,47 @@
+# Decoration
+
+Optional layer. Non-semantic visual sugar: iconic markers and vibe labels.
+
+**Default behavior**: do not decorate. CLI fills in sensible defaults for most decoration concerns. Load this skill only when the user explicitly asks for decorative elements or when the content has a strong visual vibe requirement.
+
+## Iconic markers
+
+Decorative icons. Categories include:
+
+- `smiley-*` (smile, laugh, cry, etc.)
+- `celebration` (party, gift)
+- `people-*` (different roles)
+- `flag-*` (red, green, blue)
+- `star-*` (red, blue)
+- `symbol-*` (plus, minus, question, exclam)
+
+```json
+{"op": "marker", "topic": "Launch", "marker": "celebration"}
+```
+
+### Important
+
+Do NOT use `flag-*` or `star-*` for status semantics (e.g., `flag-red` for "blocked"). Use `task-overlay` priority / state markers instead. `flag-*` and `star-*` are vibe only.
+
+## Vibe labels
+
+Free-text labels for non-structural tagging.
+
+```json
+{"op": "label", "topic": "Idea Pool", "labels": ["brainstorm", "v1"]}
+```
+
+Same `label` op as task-overlay assignee, but used for vibe rather than ownership.
+
+## What decoration does not own
+
+Numbering belongs to `visual`, not decoration. Use numbering when sequence,
+rank, or stable outline references help the reader navigate the map. Do not
+use numbering as visual sugar.
+
+## Avoid double decoration
+
+- A node already has emphasis (color/font) → don't add iconic marker too
+- A node already has priority/state marker → don't add flag/star too
+
+If unsure whether decoration adds value, skip it.

package/skills/edit/guide.md

@@ -0,0 +1,160 @@
+# Edit Guide
+
+Guide for editing **content and structure** of an existing mindmap. Visual
+restyling (skeleton / color / layout / emphasis) is **not** covered here —
+for that, load `visual/SKILL.md` and walk its pattern catalog on the existing
+content.
+
+This guide assumes you have an existing `.xmind` file. To work on a fresh
+generation, use `recipe/<chosen> + visual` instead.
+
+---
+
+## Two separate concerns
+
+| Concern | Scope | Skill |
+|---|---|---|
+| **Content / structure edit** | titles, notes, links, hierarchy, missing branches, depth | this guide |
+| **Visual restyle** | skeleton, color, layout, emphasis, boundary, callout, user-provided local image | `visual/SKILL.md` |
+
+These are independent — an edit pass may not need any restyle, and a restyle
+may not need any content change. Load only what the user asked for.
+
+---
+
+## Style matching (applies to every dimension)
+
+Before changing anything, examine 3-5 existing sibling topics:
+
+- Length: short phrases? complete sentences? parenthesized augments?
+- Language: match the user's language; do not switch
+- Format: any examples, data, explanations?
+
+**All additions and edits must match existing style.** Do not introduce
+new naming conventions mid-edit.
+
+---
+
+## 4 content / structure dimensions
+
+### 1. Completeness (Review)
+
+Find missing dimensions and shallow branches.
+
+**Method:**
+1. Read the whole document; understand the covered domain
+2. Compare against domain common sense: which dimensions are missing? which are shallow? are proportions balanced?
+3. If specialized knowledge helps, optionally load: `xmind skill show recipe/<name>`
+
+**Output format:**
+
+```
+Coverage analysis:
+  ✓ [dimension] — sufficient
+  △ [dimension] — shallow
+  ✗ [dimension] — missing
+```
+
+**Ops:** `add` to fill missing content, `marker` with `flag-green` to mark
+the newly-added nodes for user review.
+
+### 2. Depth (Expand)
+
+Fill in concrete detail on shallow branches. Depth follows the content
+itself — no artificial cap.
+
+**Method:**
+1. Identify branches obviously shallower than their siblings
+2. Expand by the content's natural hierarchy — as many levels as the concept warrants
+3. Use `notes` op to attach blockquote-style detail to an existing node
+   (instead of always nesting deeper)
+
+**Constraint:** Do not modify existing nodes; preserve all current content.
+
+**Ops:** `add` for new children, `notes` for inline elaboration on existing nodes.
+
+### 3. Expression (Refine)
+
+Unify naming style; improve phrasing.
+
+**Method:**
+1. Identify the style used by the **majority** of nodes as the standard
+2. Correct the minority that deviates: shorten over-long titles, expand
+   over-short ones, make vague titles concrete
+
+**Constraint:** Do not change meaning, do not add or remove nodes; unify
+to the majority style.
+
+**Ops:** `update` for title edits, `notes` for refining explanations.
+
+### 4. Structure (Restructure)
+
+Reorganize the hierarchy.
+
+**Method:**
+1. Identify problems:
+   - Too flat (8+ siblings under one parent) → group via a wrapper
+   - Misplaced node → move to correct parent
+   - Duplicate / overlap → merge or delete
+2. **Wrapper insertion** (common pattern):
+   - `add` a wrapper node as child of the over-flat parent
+   - `move` existing siblings into the wrapper
+3. Single batch ≤ 20 ops; split into multiple batches if larger.
+
+**Constraint:** Preserve all content; do not delete or rename unless the
+existing label is clearly wrong.
+
+**Ops:** `add`, `move`, `delete` (rare), `update` for rename.
+
+---
+
+## Analysis template
+
+Before editing, output a short analysis (≤ 8 lines):
+
+```
+[content]    ✓ sufficient / △ missing X / ✗ missing Y
+[depth]      ✓ balanced / △ branch X is shallow
+[expression] ✓ unified style / △ partial inconsistency
+[structure]  ✓ reasonable / △ branch X too flat / over-deep / misplaced
+```
+
+Then apply all changes in one batch.
+
+---
+
+## Execute
+
+```bash
+cat <<'BATCH' | xmind batch <file>
+[
+  {"op": "add",    "parent": "Old Parent",          "topic": "New Wrapper"},
+  {"op": "move",   "topics": ["Child A", "Child B"], "parent": "New Wrapper"},
+  {"op": "update", "topic":  "Vague Title",         "title":  "Concrete Title"},
+  {"op": "notes",  "topic":  "Concept X",           "notes":  "Explanation paragraph"},
+  {"op": "href",   "topic":  "External Reference",  "href":   "https://example.com"},
+  {"op": "delete", "topic":  "Obsolete Node"},
+  {"op": "marker", "topic":  "Newly Added",         "marker": "flag-green"}
+]
+BATCH
+```
+
+### Content / structure ops palette
+
+| Op | Effect |
+|---|---|
+| `add` | Add a new child under `parent` |
+| `update` | Rename a topic (change `title`) |
+| `delete` | Remove a topic (and its subtree) |
+| `move` | Reparent a topic; supports `topics: [...]` batch |
+| `notes` | Set / clear blockquote notes (`notes: null` clears) |
+| `href` | Set / clear topic link (`href: null` clears) |
+| `label` | Add labels (tags) on a topic |
+| `todo` | Mark a topic as todo (with optional `due` ISO date) |
+| `marker` | Add a marker (priority / state / iconic icon) |
+
+For whole-map theme changes, use the standalone command:
+`xmind theme <file> --skeleton X --color Y`.
+
+For visual restyling beyond theme (layout / emphasis / boundary / relation /
+local image attachment / etc.), load `visual/SKILL.md` and follow its planner.

package/skills/manifest.json

@@ -0,0 +1,63 @@
+{
+  "version": "3",
+  "recipe": [
+    {
+      "name": "default",
+      "trigger": "General content, no specialized domain. Fallback when no other recipe fits."
+    },
+    {
+      "name": "comparison-decision",
+      "trigger": "Option comparison, versus analysis, product/tool selection, buying decisions, vendor evaluation, tradeoff review."
+    },
+    {
+      "name": "lesson-plan",
+      "trigger": "Course design, learning path, lesson plan, training program, curriculum."
+    },
+    {
+      "name": "quick-map",
+      "trigger": "Fast free-first maps: quick topic overviews, lightweight summaries, checklists, meeting notes, idea inboxes, bug triage, audit lists, quick plans, sorted notes, small resource lists, and short schedules."
+    },
+    {
+      "name": "process-playbook",
+      "trigger": "SOPs, workflows, operating manuals, runbooks, troubleshooting flows, onboarding procedures, how-to guidance."
+    },
+    {
+      "name": "swot",
+      "trigger": "SWOT analysis, competitive analysis, strategic assessment, four-quadrant framework."
+    },
+    {
+      "name": "timeline-narrative",
+      "trigger": "Time-dominant narratives where order explains change: biographies, company histories, product or technology evolution, historical narratives, incident histories, past-to-present timelines."
+    }
+  ],
+  "visual": [
+    {
+      "name": "visual",
+      "trigger": "Visual core: route result, structure card, second look, and anchor planning. Always loaded alongside a recipe."
+    }
+  ],
+  "task-overlay": [
+    {
+      "name": "task-overlay",
+      "trigger": "Project planning, OKR, task management, scheduling, team work breakdown, roadmap, progress tracking. Load when the map represents work to be executed, not just content."
+    }
+  ],
+  "decoration": [
+    {
+      "name": "decoration",
+      "trigger": "Non-semantic visual sugar: iconic markers and vibe labels. Rarely loaded — CLI defaults handle most cases."
+    }
+  ],
+  "edit": [
+    {
+      "name": "guide",
+      "trigger": "Edit, optimize, improve, review, expand, restructure, refine, restyle any existing .xmind."
+    }
+  ],
+  "shared": [
+    {
+      "name": "markdown-grammar",
+      "trigger": "Force-loaded by every entry skill before recipe / visual selection. Markdown ↔ XMind mapping reference."
+    }
+  ]
+}

package/skills/markdown-grammar.md

@@ -0,0 +1,60 @@
+# Markdown Grammar Reference
+
+This is the shared markdown reference for skills that produce or consume XMind
+content. It is loaded before recipe / visual selection.
+
+Recipes write content as markdown. Visual / Task-overlay / Decoration changes
+are emitted separately as ops; never encode those semantics in markdown titles.
+
+## Standard CommonMark mapping
+
+| Markdown | XMind rendering | Notes |
+|---|---|---|
+| `# Topic` | Root topic | One root per sheet |
+| `## ### ####` | Sub-topic hierarchy | Depth determines tree level |
+| `- leaf` | Leaf topic (no children) | Use sparingly; prefer `####` if it has notes |
+| `> notes` | Topic notes | One or more lines, attached to nearest preceding topic |
+| `**bold**` `*italic*` | Inline strong / emphasis | Renders in notes; in titles may be stripped depending on theme |
+| `[text](url)` | Topic href / link | Whole-title link if title is the link |
+| `![](path)` | Inline image | Use only for user-provided local files; different from a Visual `image` op |
+| `- [ ]` `- [x]` | Task list checkbox | CommonMark checkbox; executable task semantics should use `task-overlay` ops |
+| ``` ``` | Code block | Only valid inside notes (not in title) |
+| `$$...$$` | LaTeX math | Only valid inside notes |
+
+## Root Notes
+
+Root notes are valid CommonMark mapping, but generated maps should avoid them by
+default. The root topic is the visual center, and notes there often reduce scan
+quality. Put scope, assumptions, and sources in first-level branches such as
+`Scope` or `Sources` unless the user explicitly asks for root notes or an
+existing map already has them.
+
+## Example
+
+```markdown
+# Quantum Mechanics Intro Course
+
+## Week 1: Wave-Particle Duality
+### Double-slit experiment
+> Demo + small group discussion.
+> Focus: how observation alters the experimental outcome.
+
+### Historical background
+> From Young's experiment to Davisson-Germer.
+
+## Week 2: Uncertainty Principle
+### Thought experiment comparison
+- Heisenberg microscope
+- Bohr's response
+```
+
+## Boundaries
+
+- Recipe emits markdown only: titles, hierarchy, notes, links, and inline
+  content.
+- Visual emits ops: skeleton choice, color choice, layout, emphasis, relation,
+  boundary, callout, summary, numbering, and image attachment.
+- Task-overlay emits ops: priority, owner, due date, todo state, dependency.
+- Decoration emits ops: non-semantic markers and labels.
+- Entry skills own delivery commands such as `xmind create --stdin` and
+  `xmind batch`.

package/skills/recipe/index.json

@@ -0,0 +1,30 @@
+[
+  {
+    "name": "default",
+    "trigger": "General content, no specialized domain"
+  },
+  {
+    "name": "comparison-decision",
+    "trigger": "Option comparison, versus analysis, product/tool selection, decision support"
+  },
+  {
+    "name": "lesson-plan",
+    "trigger": "Course design, learning path, lesson plan, training program"
+  },
+  {
+    "name": "quick-map",
+    "trigger": "Fast free-first maps: quick topic overviews, lightweight summaries, checklists, meeting notes, idea inboxes, bug triage, audit lists, quick plans, sorted notes, small resource lists, and short schedules"
+  },
+  {
+    "name": "process-playbook",
+    "trigger": "SOPs, workflows, operating manuals, runbooks, troubleshooting flows, how-to procedures"
+  },
+  {
+    "name": "swot",
+    "trigger": "SWOT analysis, competitive analysis, strategic assessment"
+  },
+  {
+    "name": "timeline-narrative",
+    "trigger": "Time-dominant narratives: biographies, histories, product/company/technology evolution, incident histories, past-to-present change"
+  }
+]

package/skills/recipe/quick-map/SKILL.md

@@ -0,0 +1,85 @@
+# Recipe: Quick Map
+
+Fast, free-first recipe for quick overviews, lightweight summaries, checklists,
+meeting notes, idea inboxes, bug triage, audits, quick plans, sorted notes,
+small resource lists, and short schedules.
+
+Do not use for deep analysis, formal visual showcases, decision support,
+SOP/runbook-level procedures, full lesson plans, or chronology-dominant stories.
+
+## Profile
+
+```json
+{
+  "recipe": "quick-map",
+  "archetype": "overview|triage|checklist|memo|quick-plan|simple-process|simple-timeline|resource|hierarchy",
+  "density": "light|standard",
+  "baselinePolicy": "free-first",
+  "anchorObligations": {
+    "layout": "optional",
+    "group": "optional",
+    "focus": "optional",
+    "image": "none"
+  }
+}
+```
+
+## Density
+
+- `light`: 8-25 nodes, depth 1-2.
+- `standard`: 25-45 nodes, depth 2-3.
+
+Preserve user-supplied items. Do not expand to default deep floors.
+
+## Modes
+
+| Mode | Use When | Structural Type | Free Skeleton |
+|---|---|---|---|
+| overview | quick topic map | radial_overview | MindMap-1 |
+| triage | sort ideas/issues | matrix_board | Matrix-1 |
+| checklist | verify/prepare/audit | matrix_board or radial_overview | Matrix-1 or MindMap-1 |
+| quick-plan | simple action sequence | procedural_flow | LogicChart-1 |
+| simple-process | short how-to | procedural_flow | LogicChart-1 |
+| simple-timeline | short chronology | temporal_axis | Timeline-1 or Timeline-3 |
+| resource | small catalog | radial_overview | MindMap-1 |
+| hierarchy | taxonomy/org outline | hierarchy_tree | OrgChart-1 or TreeChart-1 |
+
+For short generic requests, default to overview.
+
+## Fast Path
+
+- Load only `markdown-grammar` and `recipe/quick-map` by default.
+- Choose the free skeleton from the mode table.
+- Use `Dawn-#ffffff-MULTI_LINE_COLORS` unless the user gives a theme.
+- Create in one pass and run `xmind validate --quiet`.
+- Skip image search, route cards, skeleton cards, and post-create anchors unless
+  validation fails or the user asks.
+
+## Structure Rules
+
+- 3-7 root branches.
+- Usually 2-5 children per branch.
+- Prefer visible nodes and concise titles over notes for short facts.
+- Notes are optional and should carry context, caveats, blocked reasons,
+  acceptance criteria, or key synthesis.
+- One node = one item, idea, step, or decision.
+- Do not add wrappers only for visual anchors.
+
+## Quick Quality Gate
+
+Before create, check that the map is intentionally compact:
+
+- It answers the user request without pretending to be a deep analysis.
+- Branches are easy to scan and do not exceed the light/standard density target.
+- User-supplied items are preserved.
+- Any notes are useful context, not hidden structure.
+
+## Overlay Handoff
+
+No task overlay by default. Load `task-overlay` when the user asks for owner,
+deadline, progress, priority, dependency, status, roadmap tracking, or assignee.
+
+## Markdown Contract
+
+Pure CommonMark only. Match the user's language. No visual or task metadata in
+markdown.

package/skills/recipe-contract.md

@@ -0,0 +1,65 @@
+# Recipe Contract
+
+Shared frame for every `recipe/<name>`. Force-loaded with `markdown-grammar` and
+the chosen recipe during generation. Each recipe fills in its own archetype,
+density, structure rules, semantic signals, anchor seeds, and self-check items;
+this file owns the parts that are identical across recipes so they stay
+consistent instead of drifting per recipe.
+
+## Output Profile
+
+Every recipe declares an output profile, kept mentally or in scratch — it is not
+map content. The profile guides drafting and self-checking. Only `structuralType`,
+`toneTag`, and `density` are ever passed to `advise`; the rest is planning state.
+
+The chosen recipe defines the profile's values: `recipe`, `archetype` (or
+`rootShape` / `structuralType`), `density`, `semanticSignals`, and, when the
+recipe uses anchors, `anchorObligations`.
+
+## Drafting Discipline
+
+- Density floors and planning ranges are drafting aids, not caps. Expand real
+  facets, not filler.
+- After a draft passes the route quality gate, do not shrink, trim, or re-note it
+  only to match a first-pass planning target. Revise only for real filler,
+  duplication, missing required anchor seeds, an explicit user brevity request,
+  or a content hierarchy that stays broken after trying viable skeleton
+  alternatives.
+- If the recipe's self-check fails, revise the markdown before route advise.
+- A local signal is not the root shape: a timeline branch inside a mixed map does
+  not make the root `temporal_axis`, and a resource index inside a lesson does
+  not make it `mixed_modular`. Root branches decide the root shape.
+
+## Anchor Seeds
+
+When a recipe declares `anchorObligations`, the draft must contain a real seed for
+every required family before route advise. If a family has no honest target,
+revise the draft — do not add empty wrapper branches just to satisfy the
+contract. Each recipe's seed table names its family-specific targets.
+
+## Overlay Handoff Frame
+
+Every recipe emits only markdown; task metadata is never written into markdown.
+After the baseline is created, the chosen recipe's Overlay Handoff decides whether
+to load `task-overlay`:
+
+- `none`: descriptive or analytical content with no execution tracking.
+- `recommended`: many actionable leaves, or content semantics that imply tracking
+  (deadlines, owners, dependencies) even without an explicit request.
+- `required`: the user asks for owners, deadlines, priority, progress, status,
+  dependencies, scheduling, roadmap, or task tracking.
+
+If `recommended` or `required`, first consider whether a more task-shaped recipe
+fits the request; if the current recipe still fits, create the baseline first,
+then load `task-overlay`. Each recipe's Overlay Handoff adds only its own trigger
+specifics and where to place task metadata.
+
+## Markdown Contract
+
+- Standard CommonMark only.
+- Output language matches the user.
+- No skeleton, color, layout, emphasis, image, relation, boundary, summary, task
+  metadata, or batch ops in the markdown — those are emitted later as ops.
+
+A recipe may add structural conventions (which heading level holds items, etc.)
+in its own Structure Rules, but never op semantics.