taiwanmd

CLI for Taiwan.md — the open-source, AI-native knowledge base about Taiwan.

Search, read, and explore 900+ curated articles about Taiwan from your terminal.

Install

npm install -g taiwanmd

Or run without installing:

npx taiwanmd search 珍珠奶茶

Commands

taiwanmd search <query>

Search articles with fuzzy matching (supports Chinese and English).

taiwanmd search 珍珠奶茶
taiwanmd search semiconductor --limit 3
taiwanmd search 原住民 --json          # JSON output for piping

taiwanmd read <slug>

Read an article directly in the terminal with formatted rendering.

taiwanmd read 珍珠奶茶                # Terminal-rendered markdown
taiwanmd read 珍珠奶茶 --raw          # Raw markdown (ideal for LLM/RAG)
taiwanmd read 珍珠奶茶 --en           # English version
taiwanmd read 珍珠奶茶 --web          # Open in browser

taiwanmd list [category]

Browse articles by category.

taiwanmd list --categories             # Show all 13 categories
taiwanmd list food                     # List food articles
taiwanmd list people --sort words      # Sort by word count
taiwanmd list --reviewed               # Only human-reviewed articles
taiwanmd list --featured               # Only featured articles
taiwanmd list economy --json           # JSON output

Categories: history, geography, culture, food, art, music, technology, nature, people, society, economy, lifestyle, about.

taiwanmd random

Discover a random article about Taiwan.

taiwanmd random                        # Any category
taiwanmd random --category nature      # Random nature article

taiwanmd stats

Show project statistics and organism health scores.

taiwanmd stats                         # Formatted display
taiwanmd stats --json                  # JSON output

taiwanmd audit <slug> 🧬 v0.6

Run Stage 3.5 Hallucination Audit locally — enforces MANIFESTO §10 幻覺鐵律 before PR. Detects 5 hallucination patterns: award claims, names+precise numbers, location displacement, fabricated direct quotes, co-creator omission.

taiwanmd audit 王新仁                  # Run audit on article
taiwanmd audit 珍珠奶茶 --json         # Structured output for CI
taiwanmd audit 台積電 --strict         # Treat warnings as failures

Exit code 1 on HIGH-severity flags (blocks merge in CI).

taiwanmd inbox 📥 v0.6

Read/manage ARTICLE-INBOX.md (pending / in-progress / blocked articles).

taiwanmd inbox                         # All states grouped
taiwanmd inbox --state pending
taiwanmd inbox claim <slug>            # [scaffold] lock as in-progress
taiwanmd inbox release <slug>          # [scaffold] release lock
taiwanmd inbox done <slug>             # [scaffold] move to DONE-LOG

taiwanmd spore 🌱 v0.6

社群孢子 pipeline — SPORE-LOG reader + draft/harvest scaffold.

taiwanmd spore                         # Summary (total/published/by-platform)
taiwanmd spore log                     # Recent spores
taiwanmd spore log --platform X        # Filter X only
taiwanmd spore log --json
taiwanmd spore new <slug>              # [scaffold] generate draft
taiwanmd spore harvest <id>            # [scaffold] pull d+N engagement

taiwanmd organs 🧬 v0.6

Show Semiont vital signs (8 organ health scores from dashboard-organism.json).

taiwanmd organs                        # Colored bar chart
taiwanmd organs --lang en              # English labels
taiwanmd organs --json

taiwanmd supporters 💚 v0.6

Show Portaly supporter stats (PII-scrubbed by default).

taiwanmd supporters                    # Totals + recent
taiwanmd supporters --since 2026-04-01
taiwanmd supporters --limit 20 --json

taiwanmd sense 👁️ v0.6

Show sense data: GA4 pageviews / Search Console queries / Cloudflare traffic. Named after Semiont's §感知器官 (perception organs).

taiwanmd sense                         # 7d snapshot, all sources
taiwanmd sense --range 24h             # 24h window
taiwanmd sense --source sc             # Filter to Search Console only
taiwanmd sense --limit 5               # Top 5 per section

taiwanmd cite <query> 📎 v0.6

Anti-hallucination primitive — return verified claims + source URLs instead of generated sentences. Complements rag (full body) with surgical per-claim attribution.

taiwanmd cite "王新仁 Art Blocks"       # Top 3 cited claims
taiwanmd cite "台灣高鐵" --limit 5
taiwanmd cite "Good Vibrations" --json

Only returns claims that have [^N] footnote attached in the source article.

taiwanmd mcp 🔌 v0.6.1

Model Context Protocol server — Claude Desktop / Cursor / Warp integration.

taiwanmd mcp install                   # Print Claude Desktop config snippet
taiwanmd mcp install --client cursor
taiwanmd mcp serve                     # Start MCP server on stdio (for Claude Desktop)

Exposed MCP tools (6):

• taiwanmd_search — full-text search
• taiwanmd_read — fetch an article by slug
• taiwanmd_rag — prompt-ready RAG context for a query
• taiwanmd_cite — citation-backed verified claims (anti-hallucination)
• taiwanmd_organs — 8 organ vital signs
• taiwanmd_stats — project summary stats

After installing, add the config snippet to Claude Desktop and reload. Taiwan.md becomes queryable from inside Claude conversations.

taiwanmd sync

Sync the knowledge base locally for offline access.

taiwanmd sync                          # Initial sync or update
taiwanmd sync --force                  # Force re-sync

Syncs to ~/.taiwanmd/knowledge/ via git sparse-checkout.

taiwanmd rag <query>

Retrieve top articles and output them in a prompt-ready format for piping to LLMs (Retrieval-Augmented Generation).

taiwanmd rag 珍珠奶茶                         # Top 3 articles as context
taiwanmd rag "半導體產業" | llm "summarize"   # Pipe directly to an LLM
taiwanmd rag "台灣經濟" --limit 1             # Retrieve only 1 article
taiwanmd rag "原住民文化" --no-prompt         # Skip the trailing question line
taiwanmd rag "台灣歷史" --json               # Structured JSON output

Output format (default):

# Taiwan Knowledge Context

## 1. {title} ({category})
{full article body}

---
Based on the above context about Taiwan, answer the following question:
{query}

Options:

• -l, --limit <n> — Number of articles to retrieve (default: 3)
• --no-prompt — Omit the trailing question line (useful for custom prompts)
• --json — Return structured JSON: { query, articles: [{ title, category, slug, body }] }

taiwanmd contribute <topic>

Interactive guided workflow for creating a new article.

taiwanmd contribute "珍珠奶茶的起源"

The wizard will:

1. Show the 13 categories and ask you to pick one
2. Auto-generate a frontmatter template
3. Create an article skeleton with standard sections (概述, 歷史背景, 當代發展, 國際比較, 參考資料)
4. Write the file to knowledge/{Category}/{slug}.md (in-repo) or ~/.taiwanmd/drafts/{slug}.md (standalone)
5. Print the file path and next steps

taiwanmd validate <slug>

Quality-check a single article and output a detailed score card.

taiwanmd validate 珍珠奶茶             # Human-readable score card
taiwanmd validate 台灣小吃 --json      # JSON output for CI/scripting
taiwanmd validate 台積電 --fix         # Show suggested fixes

Checks:

| Check | Criteria | Points | | ---------------- | --------------------------------------------------------------- | ------ | | Frontmatter 完整 | All 5 fields present (title, description, date, tags, category) | 20 | | 字數充足 | ≥ 800 words | 20 | | 標題數充足 | ≥ 3 ## headings | 20 | | 參考資料 | ≥ 2 Markdown reference links | 20 | | AI 空洞句式 | No hollow phrases like "扮演著重要角色" | 10 | | 描述長度 | 50–200 characters | 10 |

Score tiers: 🟢 優秀 (90+) / 🟡 需要改善 (70–89) / 🔴 需要大幅改善 (<70)

For AI/LLM Integration

The --raw, --json, and rag commands make it easy to pipe Taiwan knowledge into AI workflows:

# RAG: retrieve context and pipe to LLM
taiwanmd rag "台灣半導體" | llm "Explain Taiwan's role in global chip supply"

# Feed an article into an LLM prompt
taiwanmd read 半導體產業 --raw | llm "Summarize this article"

# Export search results as JSON
taiwanmd search "台灣經濟" --json | jq '.[].title'

# Build a RAG corpus
taiwanmd list --json | jq -r '.[].slug' | while read slug; do
  taiwanmd read "$slug" --raw > "corpus/$slug.md"
done

For Contributors

Want to add or improve an article? Follow this workflow:

1. Create a draft

taiwanmd contribute "你想貢獻的主題"

The wizard creates a properly structured article template.

2. Edit the article

Open the file (path shown after contribute) and fill in:

• Replace placeholder text with real, well-sourced content
• Add at least 3 ## headings
• Include at least 2 reference links
• Keep the description between 50–200 characters

3. Validate quality

taiwanmd validate <slug>
taiwanmd validate <slug> --fix   # See suggested improvements

Aim for 90+/100 before submitting.

4. Submit a Pull Request

git add knowledge/{Category}/{slug}.md
git commit -m "feat(knowledge): add article on {topic}"
git push origin your-branch
# Then open a PR at https://github.com/frank890417/taiwan-md

Article Quality Guidelines

• Minimum 800 words — give readers something substantial
• Cite your sources — at least 2 Markdown links to reputable references
• Avoid AI hollow phrases — "扮演著重要角色", "不可或缺的一環", etc.
• Standard sections: 概述 → 歷史背景 → 當代發展 → 國際比較 → 參考資料

Development

# Run from the repo
cd cli && npm install
node src/index.js search 珍珠奶茶

# Link for local development
cd cli && npm link
taiwanmd --help

Claude Code Skills

This project includes Claude Code skills in .claude/skills/:

• /taiwanmd-search — Search the knowledge base from within Claude Code
• /taiwanmd-validate — Validate article quality and frontmatter

Links

• Website: taiwan.md
• Dashboard: taiwan.md/dashboard
• GitHub: frank890417/taiwan-md
• npm: npmjs.com/package/taiwanmd