Mindmap Studio Skill

Mindmap Studio is a source-aware Codex skill that turns topics, notes, web pages, Markdown, PDF, DOCX, PPTX, and images into editable offline mind maps.

It keeps durable JSON and Markdown sources beside the generated HTML, preserves source locators when available, and validates the output before delivery.

Current release target: v0.1.0

The current editor shell is Chinese-first; map titles, topics, notes, and source content support Unicode.

Real-World Case Study

The repository includes a source-aware study map for Thirty Years of Modern Chinese Literature (1917-1949). It contains 139 nodes across fiction, poetry, prose, and drama; 125 explanatory notes; 56 art/literary terms; and licensed Lucide visual markers.

• Reproducible spec: examples/chinese-modern-literature/spec.json
• Complete four-file bundle: examples/chinese-modern-literature/output/
• Prepared GitHub Pages entry: index.html

The public case preserves short source locators but does not redistribute the author's private course files. After GitHub Pages is enabled for the main branch and repository root, the interactive map is available at:

https://lazythecat.github.io/Mindmap-Studio-skill/

The searchable catalog browser is available at:

https://lazythecat.github.io/Mindmap-Studio-skill/docs/library.html

To publish both pages, open the repository's Settings > Pages, choose Deploy from a branch, then select main and /(root). The root deployment is required because the catalog browser loads licensed files directly from asset-library/.

What It Produces

Each build creates four files:

• <slug>.mindmap.json: editable structured source.
• <slug>.mindmap.md: portable outline.
• <slug>.html: offline Mind Elixir editor.
• <slug>.ATTRIBUTION.txt: source and asset provenance.

The generated HTML embeds its editor runtime and opens directly in a browser.

Highlights

• Source extraction with stable locators for text, HTML, DOCX, PPTX, PDF, and OCR.
• Semantic templates for study maps, comparisons, chronologies, decisions, systems, investigations, biographies, projects, and source synthesis.
• Progressive disclosure for dense maps: click a topic to open or close its branch.
• One-command structural validation and optional real Edge interaction checks.
• Deterministic SVG charts: bar, donut, timeline, funnel, and matrix.
• A bundled catalog of 6,518 redistribution-approved visual assets with per-file provenance, license metadata, and SHA-256 hashes.
• Deterministic asset enrichment with hash and redistribution checks.
• No cloud service or build step is required for the final HTML.

Requirements

Core generation:

• Python 3.10 or newer. Tested with Python 3.13.

Automated browser interaction checks:

• Node.js 22 or newer.
• Microsoft Edge, or EDGE_PATH pointing to msedge.exe.

Optional source extraction:

• pdftotext from Poppler for PDF files.
• Tesseract plus the requested language data for image OCR.

The core no-external-asset workflow uses only the Python standard library.

Install With Codex

Paste this prompt into Codex:

Install Mindmap Studio from https://github.com/LazyTheCat/Mindmap-Studio-skill.
Clone the repository, run install.ps1 with the default full installation, and
install both the mindmap-studio Skill and its licensed asset catalog into the
current CODEX_HOME. Do not overwrite an existing installation without asking.
Validate the installed Skill, confirm that the asset manifest contains 6,518
entries, then tell me the exact installed paths and whether I need to restart
Codex.

中文提示词：

请从 https://github.com/LazyTheCat/Mindmap-Studio-skill 安装 Mindmap Studio。
克隆仓库并运行 install.ps1 的默认完整安装，将 mindmap-studio Skill 和授权
素材库一起安装到当前 CODEX_HOME。发现已有安装时先询问，不要直接覆盖。
安装后验证 Skill，并确认素材 manifest 包含 6518 项，最后告诉我准确安装路径
以及是否需要重启 Codex。

Codex can complete the filesystem work, but the explicit checks above make the result reproducible across different machines and prevent accidental overwrite.

Install Manually

Clone the repository and run the installer from the repository root:

git clone https://github.com/LazyTheCat/Mindmap-Studio-skill.git
Set-Location .\Mindmap-Studio-skill
powershell -ExecutionPolicy Bypass -File .\install.ps1

The default full installation copies:

• skills/mindmap-studio to <CODEX_HOME>/skills/mindmap-studio.
• asset-library to <CODEX_HOME>/asset-library.

Use -CoreOnly for the smaller text/chart-only installation. Use -Force only when you intentionally want to replace an existing Mindmap Studio installation:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -CoreOnly
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Force

Restart Codex after installation, then ask for a mind map, knowledge tree, comparison tree, chronology, argument map, or project breakdown.

Copy Only The Skill

Copy skills/mindmap-studio into your Codex skills directory:

Copy-Item -Recurse .\skills\mindmap-studio "$env:USERPROFILE\.codex\skills\mindmap-studio"

This core-only copy does not install the visual catalog.

Build The Example

From the repository root:

python .\skills\mindmap-studio\scripts\run_mindmap_workflow.py `
  --spec .\examples\basic-study-map\spec.json `
  --output-dir .\examples\basic-study-map\output

Use --skip-browser-check only when Node or Edge is unavailable. The command still runs structural and offline-resource validation.

Run Tests

python -m unittest discover `
  -s .\skills\mindmap-studio\tests `
  -p "test_*.py" -v

Validate the Skill metadata with the Codex skill-creator helper when it is available:

python "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py" `
  .\skills\mindmap-studio

Core And Enriched Modes

The repository includes the redistribution-approved asset catalog, while the Skill remains usable without it.

• Core mode: build text, charts, JSON, Markdown, and editable offline HTML.
• Enriched mode: use the bundled licensed asset catalog and run enrich_mindmap_assets.py before building.

Every bundled asset retains its own provenance, license, redistribution state, and SHA-256 hash in asset-library/manifest.json. The catalog currently contains 4,492 MIT Tabler icons, 2,007 ISC Lucide icons, and 19 CC0 works from The Met. The third-party assets keep their original licenses; the repository MIT license does not replace them.

Repository Layout

skills/mindmap-studio/   Codex skill, scripts, references, templates, runtime
asset-library/           Licensed visual catalog and per-asset manifest
examples/                Reproducible examples and real-world case studies
.github/workflows/       Cross-platform unit and metadata checks

中文简介

这是一个面向 Codex 的可编辑思维导图 Skill。它不仅生成最终 HTML，还保留 JSON、Markdown 和来源说明，并通过结构检查与 Edge 浏览器交互检查验证结果。 公开版本附带逐项验证过许可与哈希的素材库；即使使用 CoreOnly 安装、不部署 外部素材，文字、图表和离线编辑流程仍可完整运行。

License

The original Mindmap Studio code and documentation are released under the MIT License. The vendored Mind Elixir runtime remains under its own MIT license; see NOTICE.md and skills/mindmap-studio/assets/vendor/mind-elixir/LICENSE.