diff --git a/README.md b/README.md
index 00db935..5f8608e 100644
--- a/README.md
+++ b/README.md
@@ -7,53 +7,94 @@
[](https://www.npmjs.com/package/@xmindltd/xmind-cli)
[](LICENSE)
-**Create local Xmind mind maps with AI agents.**
+**Turn complex information into clear, native, and fully editable Xmind files with AI agents.**
-`xmind-cli` gives agents a reliable local-file workflow for `.xmind` maps:
-generate structured maps, inspect and validate files, apply edits, attach
-images, and report Xmind credits used by premium features.
+Xmind CLI gives agents the core capabilities to work with local `.xmind` files. The official Xmind Skill teaches them how to organize content, choose the right structure, design the visual hierarchy, and check the result.
-## Install
+## Getting Started
+
+Give this repository to an agent that supports Skills and terminal commands, then ask:
+
+> Install Xmind Skill & CLI and verify that it is ready to use.
+
+The agent can handle the setup. If sign-in is required, approve the browser authorization when prompted; the CLI stores the session locally.
+
+### Instructions for the installing agent
+
+Install both the CLI and the Skill:
```bash
npm install -g @xmindltd/xmind-cli
npx skills add xmindltd/xmind-cli -y
```
-The skill install command adds the `xmind-file` skill to supported agent skill
-directories. Verify the CLI and available guidance:
+Verify the CLI and authentication status:
```bash
-xmind skill list
+xmind --version
xmind auth status
```
-If needed, sign in once:
+If sign-in is required:
```bash
xmind auth login
```
-## Quick Start
+Ask the user to complete authorization in the browser, then run `xmind auth status`
+again. Once authenticated, verify the available guidance:
+
+```bash
+xmind skill list
+```
+
+Do not ask the user to run the installation commands manually unless the
+environment prevents you from doing so.
+
+### Create your first map
+
+Once setup is complete, ask your agent:
+
+> Create an editable Xmind map from this document and save it as `overview.xmind`.
-Ask your agent:
+You can also provide a topic, webpage, PDF, set of notes, or other source material available to your agent.
-> Create a local Xmind mind map about Apollo 11.
+## Xmind Skill and CLI
-The agent uses the `xmind-file` skill to choose a recipe, draft the map, build a
-generate spec, run `xmind generate`, validate the `.xmind`, and summarize the
-result.
+Xmind is more than a way to arrange text in a tree. It is a visual thinking system for presenting hierarchy, sequence, comparison, time, cause and effect, and actionable work.
-## What It Can Do
+| | Role |
+|---|---|
+| **Xmind CLI** | Creates, reads, edits, enriches, and validates native `.xmind` files. |
+| **Xmind Skill** | Guides the agent in content organization, structure selection, visual design, and quality review. |
-- Generate rich local `.xmind` files from semantic specs.
+> **The CLI lets an agent use Xmind. The Skill teaches it to use Xmind well.**
+
+## What You Can Create
+
+You do not need to organize everything first. If your agent can access them, local files, PDFs, images, webpages, and connected sources can all become source material.
+
+| Give your agent | Get an editable Xmind |
+|---|---|
+| An article, webpage, report, or PDF | **A clear overview** of the main ideas, conclusions, and structure |
+| Papers, books, course material, notes, and research sources | **A knowledge map** connecting concepts, evidence, claims, and sources |
+| Meeting notes, task lists, plans, and project material | **An execution map** showing decisions, priorities, risks, and next steps |
+| Product information, spreadsheets, designs, and user feedback | **A comparison or decision map** built around consistent criteria and trade-offs |
+| Source code, repositories, issues, pull requests, documentation, and logs | **A system map** showing module boundaries, runtime flow, and change impact |
+
+## Core Capabilities
+
+- Generate rich local `.xmind` files from semantic specifications.
- Create quick maps from Markdown.
-- Read, describe, and validate existing `.xmind` files.
-- Edit maps with add/update/delete/theme/layout/marker/label/batch commands.
+- Read and describe existing maps so they can become context for further work.
+- Add, update, delete, and batch-edit topics.
+- Apply structures, themes, layouts, markers, labels, links, and other visual elements.
- Attach local images, stable public raster image URLs, or Wikipedia images.
-- Report actual billing as Xmind credits when premium features are used.
+- Check generation specifications and validate completed `.xmind` files.
+- Report the selected route, applied visual enhancements, fallback behavior, and Xmind credits used.
-Core commands:
+
+Command reference
```bash
xmind generate --spec generate.json -o output.xmind
@@ -62,51 +103,68 @@ xmind create --from-markdown draft.md -o output.xmind
xmind read output.xmind
xmind describe output.xmind
xmind validate output.xmind --quiet
-xmind batch output.xmind
+xmind batch output.xmind --input operations.json
xmind image output.xmind --topic "Topic" --wiki "Apollo 11"
```
-## How Generation Works
+
+
+## How It Works
+
+The agent provides semantic judgment; the CLI provides reliable execution.
+
+1. The agent understands the goal, audience, and source material.
+2. The Skill helps it choose an appropriate content method, structure, theme, and visual strategy.
+3. The agent prepares the content and generation specification.
+4. The CLI builds the native `.xmind`, applies visual enhancements and images, and validates the file.
+5. The agent reviews the result, makes any necessary edits, and delivers the finished file.
+
+This is not a one-shot conversion. The same map can be read, refined, and updated as the work develops.
+
+
+Execution details
+
+CLI JSON output records execution facts such as `route.skeletonReason`, `route.colorReason`, `anchors.applied`, `billing.consumed`, `billing.balance`, `billing.unit`, and `downgraded`.
+
+
+
+## Beyond One-Shot Mind Map Generation
+
+| | One-shot generation workflow | Xmind Skill & CLI |
+|---|---|---|
+| **Xmind capabilities** | Produces a topic hierarchy with initial styling | Works with native Xmind structures, styling, editing, images, links, and validation |
+| **Structure and visual design** | Applies structure and styling during the initial generation | Selects structures and visual treatments according to the content and task |
+| **Workflow** | Produces an initial result | Supports generation, inspection, validation, editing, and continued refinement |
+| **Deliverable** | May require conversion or recreation for continued editing | A native local `.xmind` file ready for further editing and delivery |
-The agent supplies semantic judgment. The CLI handles mechanical execution.
+## Current Scope
-1. The agent chooses a recipe for the user goal.
-2. The agent drafts Markdown with titles, hierarchy, and notes.
-3. The agent writes a generate spec with route intent, visual anchors, and image
- targets.
-4. `xmind generate` selects the final structure/color, applies anchors and
- images, validates the file, and returns JSON.
-5. The agent reports the output path, validation result, key design choices, and
- any Xmind credits consumed.
+The currently published `xmind-file` Skill focuses on local-file workflows:
-The JSON output includes execution facts such as `route.skeletonReason`,
-`route.colorReason`, `anchors.applied`, `billing.consumed`, `billing.balance`,
-`billing.unit`, and `downgraded`.
+- It creates and edits local `.xmind` files; it does not provide real-time cloud collaboration.
+- It can attach existing local or web images, but it does not generate AI images within this Skill.
+- It requires an agent environment that can install Skills and run local commands.
-## Billing
+## Xmind Credits
-Some premium structures, themes, or recipe skills may consume Xmind credits.
-The CLI reports billing in JSON. Treat `billing.unit` as authoritative; these
-are **Xmind credits**, not OpenAI, Codex, model, or token credits.
+Some premium structures, themes, or recipe skills may consume Xmind credits. The CLI reports actual usage and the remaining balance. These are **Xmind credits**, not OpenAI, Codex, model, or token credits.
-If credits are unavailable, the CLI may downgrade to a free fallback unless the
-agent uses `--no-downgrade`.
+If credits are unavailable, the CLI may use a free fallback unless `--no-downgrade` is set.
## This Repo
-This repository distributes the public agent skill entry point:
+This public repository distributes the agent Skill entry point:
- [`skills/xmind-file/SKILL.md`](skills/xmind-file/SKILL.md)
- [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)
-The CLI binary ships separately on npm as
-[`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli).
+The CLI is published separately on npm as [`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli).
## Links
-- [Xmind](https://xmind.com) — apps that read `.xmind` files
-- [`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli)
-- [Agent Skills spec](https://github.com/anthropics/skills)
+- [Xmind](https://xmind.com) — open and continue editing `.xmind` files
+- [`@xmindltd/xmind-cli`](https://www.npmjs.com/package/@xmindltd/xmind-cli) — install the CLI
+- [Agent Skills specification](https://github.com/anthropics/skills)
## License
diff --git a/skills/xmind-file/SKILL.md b/skills/xmind-file/SKILL.md
index 6518efa..efa2704 100644
--- a/skills/xmind-file/SKILL.md
+++ b/skills/xmind-file/SKILL.md
@@ -42,19 +42,18 @@ File commands require login.
## Recipe Choice
-Choose recipe before drafting.
+Run `xmind skill list` before drafting and treat its recipe catalog and triggers
+as the source of truth. Do not maintain a recipe inventory in this skill.
-Ask the user to choose before creating a new map when the request is broad and
-two or more recipes would produce meaningfully different artifacts. Offer 2-4
-domain-specific choices, for example:
+Choose directly when the user names a recipe or you have high confidence that
+one recipe best fits the requested artifact. Otherwise, recommend the best
+match, present 2-4 relevant catalog choices with a short description of how each
+would shape the artifact, and wait for the user to choose before drafting. When
+confidence is not high, bias toward user choice.
-- Quick overview: compact, `recipe/quick-map`, free-first.
-- Timeline narrative: sequence/history, `recipe/timeline-narrative`.
-- Deep knowledge map: concepts/tradeoffs, `recipe/default`.
-- Focused analysis: `recipe/swot`, `recipe/comparison-decision`, or
- `recipe/process-playbook` only when the topic naturally matches.
-
-Do not use `quick-map` as an implicit fallback only because it is fast or free.
+This does not override CLI/server fallback. If `xmind skill show` returns
+`effective: "quick-map"` because premium recipe access or Xmind credits are not
+available, follow the effective recipe and explain the fallback plainly.
## Context Loading
@@ -117,17 +116,8 @@ For rich generation, write a semantic spec and let the CLI compile it.
}
```
-Anchor families:
-
-- `layout`: local relation layouts on `###` or deeper nodes.
-- `group`: `boundary` / `summary` over sibling groups.
-- `focus`: `emphasis`, `callout`, `numbering`, or `relation`.
-- `image`: local file, stable raster URL, or Wikipedia image. Generate attaches
- images last.
-
-Use `"auto"` baseline unless the user gave an override or you have a recorded
-reason. The Agent decides anchors semantically; do not invent decorative anchors
-only to satisfy a checklist.
+Follow Visual for baseline selection, anchor-family semantics, target selection,
+and its anchor quality gate.
## Semantic Quality Gate
@@ -158,21 +148,10 @@ validation cannot detect a shallow or semantically fake map.
Follow recipe density, shape, semantic signals, notes posture, and self-check.
First draft the visible heading skeleton, then add selective notes and anchor
- candidates. For `recipe/default`, density is normally `deep`. Write pure
- CommonMark to `/tmp/xmind-draft-.md`.
-
-3. Write `/tmp/xmind-generate-.json`.
-
- The route fields are semantic declarations:
+ candidates. Write pure CommonMark to `/tmp/xmind-draft-.md`.
- - `structuralType`: root relation family.
- - `structureCommitment`: how strongly that root relation is required.
- - `toneTag`: palette character.
- - `density`: recipe density, not a skeleton choice.
-
- For default maps, normally provide at least one real target in `layout`,
- `group`, `focus`, and `image`, unless the user asked for text-only/no-images
- or the subject has no useful concrete image anchor.
+3. Write `/tmp/xmind-generate-.json` using the route and baseline semantics
+ defined by Visual.
4. Preflight and optionally dry-run:
@@ -214,15 +193,9 @@ Use when the chosen recipe is `quick-map`.
xmind skill show markdown-grammar recipe/quick-map --json
```
-2. Draft compact markdown, usually `light` or `standard`.
-
-3. Pick a free baseline directly:
+2. Draft compact markdown according to the effective recipe.
- - overview/resource: `MindMap-1`
- - triage/checklist: `Matrix-1`
- - quick-plan/simple-process: `LogicChart-1`
- - simple-timeline: `Timeline-1` or `Timeline-3`
- - hierarchy: `OrgChart-1` or `TreeChart-1`
+3. Choose the mode and free skeleton from the effective recipe's mode table.
4. Create and validate:
@@ -234,6 +207,12 @@ Use when the chosen recipe is `quick-map`.
Run `read`/`describe` only if validation fails, the user asks, or a small
repair is clearly needed.
+5. Communicate the boundary.
+
+ Tell the user this is a quick overview, not the full rich-map path. Offer to
+ regenerate with a fuller recipe if they want deeper titles/notes, visual
+ anchors, images, or premium-capable structure.
+
## Flow B: Edit Existing Map
1. Load `edit/guide`; load `visual` only if the edit changes visual treatment.
@@ -268,6 +247,27 @@ xmind image .xmind --topic "" --url ""
xmind image .xmind --topic "" --wiki ""
```
+## Links
+
+Use `link` for a single topic. Local paths are resolved to absolute `file:///`
+URIs and URL-encoded in the same form written by Xmind Desktop:
+
+```bash
+xmind link