@xmindltd/xmind-cli 0.2.1

package/skills/task-overlay/SKILL.md

@@ -0,0 +1,117 @@
+# Task Overlay
+
+Optional layer for maps that represent work to be executed: projects, OKRs,
+tasks, schedules, WBS, roadmaps, progress tracking, or team plans. Do not load
+for ordinary knowledge maps or brainstorms.
+
+## Load When
+
+Use this layer when the request mentions, or the content clearly implies:
+
+- project / OKR / task / checklist execution
+- schedule / deadline / progress / roadmap
+- owner / assignee / team / WBS
+- dependency / blocker / status tracking
+
+Equivalent terms in other languages count.
+
+## Xmind Task Model Rule
+
+Xmind has one task-extension slot per topic. It is either:
+
+- checkbox task: `{status: "todo" | "done"}`;
+- scheduled task: `{duration, progress, due?, start?}`.
+
+Do not mix `status` with `due`, `progress`, or `duration` in the same task
+extension. For deadline + completion tracking, use a visible state marker plus a
+scheduled `todo`.
+
+## Capabilities
+
+### Priority
+
+```json
+{"op": "marker", "topic": "User Research", "marker": "priority-1"}
+```
+
+P1 is highest; use `priority-1` through `priority-9`.
+
+### State
+
+| State | Marker |
+|---|---|
+| To do | `task-start` |
+| In progress | `task` |
+| Paused / blocked | `task-pause` |
+| Done | `task-done` |
+
+State markers can stack with priority markers and scheduled `todo` data.
+
+### Owner / Effort
+
+```json
+{"op": "label", "topic": "User Research", "labels": ["@Lily", "effort:3d"]}
+```
+
+Use `@Name` for owners. Effort labels follow `effort:Nd`, `effort:Nh`, or
+`effort:Nw`.
+
+### Due Date / Progress
+
+```json
+{"op": "todo", "topic": "User Research", "due": "2026-04-22", "progress": 0.4}
+```
+
+Dates must be ISO `YYYY-MM-DD`. `progress` is `0..1`. Do not add a bare checkbox
+todo to a topic that already has scheduled task data.
+
+### Dependency
+
+```json
+{"op": "relation", "from": "User Research", "to": "Prototype Design", "title": "blocks"}
+```
+
+`from` is the prerequisite; `to` is the dependent outcome.
+
+## Where To Apply
+
+Apply task metadata only to work nodes:
+
+- phase / milestone / release: owner, due, priority, dependency;
+- action / checklist item: state, due, optional owner/effort;
+- review / gate / exam / capstone: priority plus due;
+- concept / reference / explanation: no task metadata unless it is explicitly a
+  deliverable.
+
+Do not invent due dates when the map has no date signal. Use state, priority,
+owner, or effort unless the user asks for scheduling.
+
+## Overlay Quality Gate
+
+Before applying task metadata:
+
+- Each target is work to be executed, not a concept or explanatory note.
+- Owners, dates, and progress come from the user or explicit context.
+- Dependencies point from prerequisite to dependent outcome.
+- Priority marks relative urgency or importance, not visual emphasis.
+- Existing knowledge-map semantics remain readable without the overlay.
+
+## Common Composition
+
+```json
+[
+  {"op": "marker", "topic": "User Research", "marker": "priority-1"},
+  {"op": "marker", "topic": "User Research", "marker": "task"},
+  {"op": "label",  "topic": "User Research", "labels": ["@Lily", "effort:3d"]},
+  {"op": "todo",   "topic": "User Research", "due": "2026-04-22", "progress": 0.4}
+]
+```
+
+Clear metadata:
+
+```json
+{"op": "marker", "topic": "User Research", "marker": "task", "remove": true}
+{"op": "todo", "topic": "User Research", "remove": true}
+```
+
+Batch repeated metadata with `topics: [...]` when appropriate.

package/skills/template/index.json

@@ -0,0 +1 @@
+[]

package/skills/visual/SKILL.md

@@ -0,0 +1,109 @@
+# Visual
+
+Semantic visual planner. Load with `markdown-grammar` and the chosen recipe for
+rich generation.
+
+Visual does not write content. It helps the Agent declare `baseline` and
+`anchors` in the `xmind generate` spec. The CLI executes and validates.
+
+## Boundaries
+
+- Recipe owns markdown, density, and semantic signals.
+- Agent owns semantic visual judgment.
+- `xmind generate` owns route measurement, skeleton/color selection, anchor
+  execution, images, billing, downgrade, and validation.
+- `visual/layout-style` and `visual/node-style` are low-level references for
+  repair or post-generate edits.
+- Task status, owner, dates, progress, and dependencies belong to
+  `task-overlay`.
+
+## Baseline
+
+Default to:
+
+```json
+"baseline": { "skeleton": "auto", "color": "auto", "diversify": true, "seed": "<stable id>" }
+```
+
+Use explicit skeleton/color only when the user requests it or there is a strong
+recorded reason. Route fields in the spec carry the semantic intent:
+
+- `structuralType`: root relation family.
+- `structureCommitment`: required / preferred / optional.
+- `toneTag`: palette character.
+- `density`: recipe density.
+
+## Anchors
+
+Use anchors only when they render real semantics:
+
+1. `layout`: local relation at `###` or deeper.
+2. `group`: `boundary` or `summary` for contiguous siblings or synthesis.
+3. `focus`: emphasis, relation, callout, or numbering for exceptional meaning.
+4. `image`: concrete local file, stable raster URL, or Wikipedia image anchors.
+
+When there is a concrete primary subject, attach the primary image to the root
+topic by default.
+
+Most nodes stay theme-default. If many nodes need per-node styling, the content
+hierarchy or baseline is probably doing the wrong job.
+
+## Anchor Quality Gate
+
+Before writing anchors into the generate spec:
+
+- Target titles must already exist in the markdown and be specific enough to
+  find.
+- `layout` targets should have a real local relation, not just a large subtree.
+- `group` topics must be siblings under the same parent.
+- `focus` should mark rare meaning: decision, contrast, risk, turning point, or
+  takeaway.
+- `image` should attach to concrete entities, artifacts, places, products, or
+  works.
+
+If an anchor requires inventing a wrapper, revise content first or omit it.
+
+## Default Recipe Obligations
+
+For `recipe/default`, normally provide at least one real target for:
+
+```json
+{"layout": "required", "group": "required", "focus": "required", "image": "required"}
+```
+
+Reject an empty required family only when the user explicitly asks for
+text-only/no-images or the subject has no honest target. Do not invent wrappers
+or decorative anchors to satisfy the contract.
+
+## Generate Spec Anchor Shape
+
+```json
+{
+  "anchors": {
+    "layout": [
+      {"topic": "Timeline", "layout": "timeline-vertical"}
+    ],
+    "group": [
+      {"kind": "boundary", "parent": "Risks", "topics": ["Risk A", "Risk B"], "title": "Critical risks"}
+    ],
+    "focus": [
+      {"kind": "callout", "topic": "Key Takeaway", "text": "Main implication"},
+      {"kind": "relation", "from": "Cause", "to": "Effect", "title": "drives"}
+    ],
+    "image": [
+      {"topic": "Product", "wiki": "Product", "width": 320},
+      {"topic": "Logo", "url": "https://example.com/logo.png"}
+    ]
+  }
+}
+```
+
+## Final Checks
+
+- Baseline is `auto` or explicitly justified.
+- Layout targets are `###` or deeper.
+- Boundary/summary ranges are sibling groups.
+- Anchor titles are present in the markdown.
+- Focus anchors are rare and meaningful.
+- Images are concrete and attached last by `generate`.
+- Task semantics did not leak into visual anchors.

package/skills/visual/layout-style.md

@@ -0,0 +1,116 @@
+# Visual: Layout Style
+
+Op contract for `anchorPlan.layout` and `anchorPlan.group`. Load only when
+second look has non-empty `layout` or `group` items.
+
+Layout changes local structure. Boundary and summary mark sibling ranges. None
+of these are decoration.
+
+## Contract
+
+- Every op maps to an `anchorPlan.layout` or `anchorPlan.group` item.
+- `layout` targets must be `###` or deeper.
+- Layout choices must respect the chosen skeleton's structure card.
+- `boundary` and `summary` ranges must be contiguous siblings under one parent.
+- A sibling range gets either boundary or summary, not both.
+
+## Depth Rule
+
+Root (`#`) and direct children (`##`) are controlled by the root skeleton. XMind
+ignores subtree layout overrides there.
+
+When a `##` branch needs local layout, create or move content under a real `###`
+wrapper:
+
+```json
+[
+  {"op": "add", "parent": "Resources", "topic": "Resource Index"},
+  {"op": "move", "topics": ["Book A", "Book B"], "parent": "Resource Index"},
+  {"op": "layout", "topic": "Resource Index", "layout": "grid"}
+]
+```
+
+Order matters: add wrapper, move children, then apply layout.
+
+## `layout`
+
+```json
+{"op": "layout", "topic": "Chronology", "layout": "timeline-horizontal"}
+```
+
+Batch form:
+
+```json
+{"op": "layout", "topics": ["Phase 1", "Phase 2"], "layout": "timeline-horizontal"}
+```
+
+Available layouts:
+
+| Layout | Use |
+|---|---|
+| `timeline-horizontal` | ordered time sequence, roadmap, or workflow spine where left-to-right flow matters |
+| `timeline-vertical` | ordered time sequence where vertical stacking is safer |
+| `spreadsheet` | comparison across dimensions |
+| `spreadsheet-column` | comparison with column-header emphasis |
+| `grid` | equivalent resource/index/card items |
+| `tree-table` | tabular tree |
+| `logic-right` / `logic-left` | ordered process or flow |
+| `org-chart-down` / `org-chart-up` | role/team/org relation |
+| `tree-right` / `tree-left` | local hierarchy |
+| `fishbone-right` / `fishbone-left` | cause families pointing to effect |
+| `brace-right` / `brace-left` | part-whole grouping |
+
+Semantic routing:
+
+| Subtree role | Layout |
+|---|---|
+| Resources / Materials / References / Sources / Index | `grid` |
+| Phases / Weeks / Roadmap / Schedule / Chronology | `timeline-horizontal` or `timeline-vertical` |
+| Compare / Vs / Versus / Comparison / Tradeoff | `spreadsheet` |
+| Steps / Flow / Pipeline / Process | `logic-right`, or `timeline-horizontal` for a workflow spine that must read left-to-right |
+| Causes / Reasons / Root causes | `fishbone-right` |
+| Roles / Team / Org | `org-chart-down` |
+| Components / Parts / Breakdown | `brace-right` |
+
+Reject layout when the title keyword is present but the relation is not real, or
+when the structure card says the layout will disappear inside the parent texture.
+If the structure card only warns about width, treat it as a verification risk,
+not an automatic rejection. A `Workflow Spine` may intentionally use
+`timeline-horizontal` to preserve left-to-right execution flow; verify the
+rendered width before switching it to `timeline-vertical`.
+
+## `boundary`
+
+Wrap consecutive siblings in a frame.
+
+```json
+{"op": "boundary", "parent": "Findings", "topics": ["Risk A", "Risk B", "Risk C"], "title": "Critical risks"}
+```
+
+Index fallback:
+
+```json
+{"op": "boundary", "parent": "Findings", "range": [0, 2], "title": "Critical risks"}
+```
+
+Use when 3+ consecutive siblings form a real group: risks, constraints,
+exceptions, phase items, evidence cluster. Do not use as general emphasis.
+
+## `summary`
+
+Add a synthesis node over a consecutive sibling range.
+
+```json
+{"op": "summary", "parent": "Findings", "range": [0, 2], "text": "Key insights"}
+```
+
+Use summary when the synthesis is itself a concept worth a node. Use boundary
+when only a frame is needed.
+
+## Range Safety
+
+- Prefer `topics` plus `parent` for boundary when titles are unique under the
+  parent.
+- Use `range` only when title resolution is ambiguous or summary requires it.
+- `range` is `[startIndex, endIndex]`, zero-based and inclusive.
+- After any range op, run `xmind validate <file>.xmind --quiet`.

package/skills/visual/node-style.md

@@ -0,0 +1,181 @@
+# Visual: Node Style
+
+Op contract for `anchorPlan.focus`, `anchorPlan.image`, and visual overrides.
+Load only when the visual planner has a non-empty focus or image plan, or the
+user supplied brand colors / background colors.
+
+Most nodes keep the theme default. Per-node style is a semantic exception.
+
+## Contract
+
+- Every style op must map to an `anchorPlan` item or a user override.
+- Per-node emphasis must answer: "why this node and not its siblings?"
+- Image ops should be last in the batch unless explicit size is supplied.
+- Task status, priority, assignee, deadline, and dependency belong to
+  `task-overlay`.
+- Decorative markers belong to `decoration`.
+
+## `emphasis`
+
+Use for key conclusions, risks, exceptions, or interpretation-control nodes.
+Keep under about 15% of nodes.
+
+Single topic:
+
+```json
+{"op": "emphasis", "topic": "Critical Finding", "fillColor": "#E32C2D", "fontColor": "#FFFFFF", "fontWeight": "bold"}
+```
+
+Batch:
+
+```json
+{"op": "emphasis", "topics": ["Finding A", "Finding B", "Finding C"], "fillColor": "#E32C2D"}
+```
+
+Fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `topic` | string | Single target title |
+| `topics` | string[] | Multiple target titles |
+| `fillColor` | hex or null | Topic background fill |
+| `fontColor` | hex or null | Title text color |
+| `fontWeight` | `"bold"` / `"normal"` / number / null | Title weight |
+| `fontSize` | number / string / null | Title size in pt |
+| `borderColor` | hex or null | Topic border color |
+
+Unspecified fields are left untouched. Pass `null` to clear a field.
+
+Avoid emphasizing branch headers just to make the map colorful. If many nodes
+need emphasis, the baseline or hierarchy is probably wrong.
+
+## `image`
+
+Use when `anchorPlan.image` names a concrete visual topic. Images may come from
+a user-provided local file, a stable direct raster image URL, or a Wikipedia
+page image. Do not use AI-generated images in this skill.
+
+```json
+{"op": "image", "topic": "Queen", "input": "/path/to/local/image.jpg"}
+```
+
+```json
+{"op": "image", "topic": "Queen", "wiki": "Queen (band)"}
+```
+
+```json
+{"op": "image", "topic": "Logo", "url": "https://example.com/logo.png"}
+```
+
+Auto-fit happens at attach time. The long-edge budget grows with map size and
+shrinks with depth; images are never upscaled. Override only when needed:
+
+```json
+{"op": "image", "topic": "Queen", "input": "/path/to/local/image.jpg", "width": 260}
+```
+
+Remove:
+
+```json
+{"op": "image", "topic": "Queen", "remove": true}
+```
+
+Choose the simplest reliable source: `input` for user files, `wiki` for concrete
+encyclopedic entities, and `url` for known stable direct raster image URLs.
+For web-search results that need screening or may be unstable, download to the
+working directory first and attach via `input`. Prefer official, Wikimedia, or
+other stable sources when available. Avoid abstract mood images.
+
+Security: do not use SVG images. Remote image downloads reject private/local
+network targets and non-image payloads. Batch local `input` paths must live
+inside the `.xmind` directory or current working directory unless
+`xmind batch --allow-image-input` is used.
+
+Use low counts. Images compete for attention; attach the few that carry the
+subject's identity or structure.
+
+## `relation`
+
+Use for explicit cross-tree non-task associations: influence, contrast, shared
+concept, evidence-to-claim, recurring theme.
+
+```json
+{"op": "relation", "from": "Topic A", "to": "Topic B", "title": "influences"}
+```
+
+Multiple sources to one target:
+
+```json
+{"op": "relation", "from": ["User Research", "Surveys"], "to": "Prototype Design"}
+```
+
+Do not use for executable dependency. Use `task-overlay` for "blocks",
+"depends on", owner, status, due date, or priority.
+
+## `callout`
+
+Use for rare high-priority annotations that should sit beside a topic. Use
+markdown notes (`>`) when the annotation is normal explanatory content.
+
+```json
+{"op": "callout", "topic": "Risk Item", "text": "Needs architecture review"}
+```
+
+Batch:
+
+```json
+{"op": "callout", "topics": ["Risk A", "Risk B"], "text": "Pending review"}
+```
+
+Limit to 1-2 callouts in most maps.
+
+## `numbering`
+
+Use for ordered procedures, ranked lists, or stable outline references. Do not
+number unordered categories.
+
+```json
+{"op": "numbering", "topic": "Steps", "pattern": "numeral-arabic", "tiered": true}
+```
+
+Patterns:
+
+| Pattern | Use |
+|---|---|
+| `numeral-arabic` | 1, 2, 3 |
+| `numeral-roman` | I, II, III |
+| `alphabet-uppercase` | A, B, C |
+| `alphabet-lowercase` | a, b, c |
+
+`tiered: true` is for nested outlines where children need stable references.
+
+## User Override Ops
+
+Use only when the user provides explicit colors or brand constraints.
+
+Canvas background:
+
+```json
+{"op": "background", "color": "#F7F2EA"}
+```
+
+Strict theme colors:
+
+```json
+{"op": "themeColor", "branchColor": "#223A5E", "fontColor": "#FFFFFF", "lineColor": "#223A5E", "borderColor": "#223A5E"}
+```
+
+`themeColor` disables the normal rainbow palette. Use it for brand-strict maps,
+not ordinary palette selection.
+
+## Mutual Exclusion
+
+- `image` on text-dense nodes competes with notes.
+- `emphasis` plus marker on the same topic can overload.
+- Multiple `emphasis` ops on the same topic merge fields; avoid duplicates.
+- `relation` for task dependency duplicates `task-overlay`; use the task layer.
+
+## Skip Rule
+
+Skip this sub-skill when `anchorPlan.focus` and `anchorPlan.image` are empty and
+there are no visual overrides.

package/skills/visual/subtree-layout.md

@@ -0,0 +1,11 @@
+# Visual: Subtree Layout
+
+Legacy alias. Prefer:
+
+```bash
+xmind skill show visual/layout-style
+```
+
+`visual/layout-style` now owns `layout`, `boundary`, and `summary` op contracts.
+This alias is kept so older skill text that requests `visual/subtree-layout`
+does not fail.