master-skill 0.10.1 → 0.12.0

package/README_EN.md

@@ -17,6 +17,10 @@
   <img src="https://img.shields.io/badge/AgentSkills-Standard-orange.svg" alt="AgentSkills Standard">
 </p>
 
+<p align="center">
+  <sub><em>Secured by SHA-pinned GitHub Actions · npm provenance · OIDC Trusted Publishing · CodeQL · cargo-audit · pip-audit — see <a href="SECURITY.md">SECURITY.md</a>.</em></sub>
+</p>
+
 <p align="center">
   Opening the 100-fascicle Yogācārabhūmi-śāstra — not knowing where to begin?<br>
   Want to study Chan, but unsure which patriarch to approach?<br>
@@ -55,8 +59,8 @@ On the AI Q&A page, open the **"法师模式"** (Master Mode) dropdown in the bo
 
 - No install, no signup
 - Three teaching modes available: `/compare-masters` (side-by-side comparison), `/master-debate` (4-round dialectic), `/master-curriculum` (time-sequenced study path) — all cross-tradition
-- Live citation retrieval backed by FoJin's 503 sources and 678K+ semantic embeddings
-- Every answer carries an authoritative source ID (CBETA for 汉传, BDRC for 藏传, SuttaCentral for 南传)
+- Live citation retrieval backed by FoJin's 10K+ texts and 678K+ semantic embeddings
+- Answers cite sources in each master's declared format: mostly CBETA IDs for 汉传, Toh / BDRC numbers for 藏传, PTS / SuttaCentral references for 南传 (Theravāda and some Tibetan sources have no per-passage ID, and the citation contract says so)
 
 **Not sure which master to ask?** Start here:
 
@@ -81,50 +85,56 @@ On the AI Q&A page, open the **"法师模式"** (Master Mode) dropdown in the bo
 
 ## What It Looks Like
 
-A real `/master-huineng` (Master Huineng, the Sixth Patriarch of Chan) exchange. Note that **every doctrinal claim carries a CBETA citation**, and the voice matches the master himself — direct, plain-spoken, fond of metaphor:
+A real `/master-huineng` answer, **reproduced unedited** (line-wrapped for display) from the 2026-08-31 full run — model `deepseek-v4-flash`, commit [`06b8142`](https://github.com/xr843/Master-skill/commit/06b814204082b3e4738185cf3eefa44ed149f9f0), index 1 of `master-huineng` in the [stored report](eval/reports/0.11.0-06b8142-deepseek.json). It graded PASS, and all five citations carry a CBETA ID that the repository's offline citation audit resolved to Huineng's declared sources (T48n2008 *Platform Sutra*, T08n0235 *Diamond Sutra*). Masters answer in Chinese; below is our English translation, with every citation kept exactly as the model wrote it:
 
 ```text
-You: I want to practice Chan, but I can't sit still and my mind is too busy.
+You: What is the difference between sudden awakening and gradual cultivation?
 
 Master Huineng:
-You say you "can't sit still" — you have mistaken the posture for Chan.
-You say your mind is "too busy" — you have made your thoughts the enemy.
-Neither of these is Chan.
-
-What is "sitting in meditation"? When, amid all conditions good and bad,
-no thought arises in the mind — that is "sitting". When you inwardly see
-the self-nature unmoved — that is "Chan". Sitting is not a matter of the
-legs; it is the mind not grasping at objects.
-  【Platform Sutra · Sitting Meditation】→ https://fojin.app/texts/58
-
-Do not fear arising thoughts. "Amid all objects the mind is unstained —
-this is called no-thought." It does not mean having no thoughts; it means
-a thought arises yet you do not chase it, do not let it stick. Like a
-cloud crossing the sky — the sky has never moved.
-  【Platform Sutra · Concentration and Wisdom】→ https://fojin.app/texts/58
+
+Tell me: are sudden and gradual really two different teachings?
+
+The Dharma itself is neither sudden nor gradual; people differ in
+sharpness and dullness. The sutra says, "Unawakened, a buddha is a
+sentient being; in one moment of awakening, a sentient being is a
+buddha" — delusion and awakening lie in a single thought, hence the name
+"sudden". It also says, "The previous thought deluded is an ordinary
+person; the next thought awakened is a buddha" — turning delusion into
+awakening needs nothing sought outside
+【《六祖坛经·般若品》，T48n2008】→ https://fojin.app/texts/58
+
+Shenxiu of the Northern School wrote the verse: "The body is the bodhi
+tree, the mind a bright mirror stand; wipe it diligently at all times,
+and let no dust alight." — an expedient for gradually sweeping away
+defilement. The Sixth Patriarch answered: "Bodhi has no tree, the bright
+mirror is no stand. Originally there is not a single thing — where could
+dust alight?" — directly revealing that self-nature is empty at root,
+with nothing that can stain it
+【《六祖坛经·行由品》，T48n2008】→ https://fojin.app/texts/58. One deliberately
+applies antidotes; the other takes it up right here. These two verses
+mark exactly where sudden and gradual part ways.
+
+Yet sudden and gradual are not two. Even concentration and wisdom are
+one — "concentration is the substance of wisdom, wisdom the function of
+concentration; at the moment of wisdom, concentration is in wisdom; at
+the moment of concentration, wisdom is in concentration"
+【《六祖坛经·定慧品》，T48n2008】→ https://fojin.app/texts/58 — so how could sudden
+and gradual be two kinds? The deluded cultivate gradually, the awakened
+accord at once; the medicine is given for the illness, and the Dharma
+has no high or low 【《六祖坛经·定慧品》，T48n2008】→ https://fojin.app/texts/58.
+
+Know too that the Sixth Patriarch saw his own nature on hearing "give
+rise to a mind that abides nowhere"
+【《金刚经》，T08n0235】→ https://fojin.app/texts/7. Sudden awakening is not
+mindlessness; it is not abiding in objects. Gradual cultivation is not
+dead sitting; it is awareness in thought after thought. In the end there
+is only one question: turning the light around in a single thought — has
+the original mind appeared yet?
 
 For further study, consult the original texts at FoJin (fojin.app).
 ```
 
-> ⚠️ The above is **AI-synthesized content**, generated from the *Platform Sutra*; it does not represent Master Huineng's actual spoken teachings. Masters currently answer in Classical/Modern Chinese — the English here is an illustrative translation. Try the multi-master `/compare-masters` mode directly at [fojin.app/chat](https://fojin.app/chat).
-
----
-
-> **v0.6 Update (2026-05-02)**: Slash command namespace cleanup — all 14 master slash commands prefixed with `master-`. `/master-zhiyi`, `/master-huineng`, etc.
-> - **Why**: Claude Code users typically have 50+ skills installed; bare-word slash commands like `/atisha` get scattered. Prefixing clusters all 14 masters under `/m<tab>` for fast discovery.
-> - **Unaffected**: `compare-masters` and `create-master` meta-skills keep their existing names (avoiding `/master-compare-masters` doublespeak). `fojin.app/chat` web-side dropdown is decoupled — its master IDs stay bare (`atisha`, `huineng`, etc.); backend `master_profiles.py` unchanged.
-> - **NPX installer**: both `npx master-skill install zhiyi` (short) and `install master-zhiyi` (full) work; install destination is always `~/.claude/skills/master-<slug>/`.
-> - See [CHANGELOG.md §0.6.0](CHANGELOG.md#060--2026-05-02) for full details.
->
-> **v0.5 Update (2026-05-02)**: Second cross-tradition expansion — Tibetan and Theravāda each grow from 1 master to 3. Total **14 masters**.
-> - 藏传 added: Atiśa (Kadam founder · Toh 4465 *Bodhipathapradīpa* · three scopes) + Tsongkhapa (Gelug founder · three principal aspects · Madhyamaka prasaṅgika)
-> - 南传 added: Buddhaghosa (commentarial summit · *Visuddhimagga*) + Mahasi Sayadaw (Burmese vipassanā · noting method · ETHICS Tier B special case)
-> - HARD-GATE strengthened: Mahasi Sayadaw specifically gets `NO_ATTAINMENT_JUDGMENT` (AI must not confirm any individual's stage of insight)
-> - ETHICS Tier A grows to 11 masters; Tier B special-case grows to include Mahasi Sayadaw (parallel to Ajahn Chah)
->
-> **v0.4 Update (2026-05-02)**: First cross-tradition expansion — added Tibetan **Milarepa** (Kagyu / Mahāmudrā) and Theravāda **Ajahn Chah** (Thai Forest Tradition). Citation system extended to support BDRC and SuttaCentral. HARD-GATE adds `no_esoteric_instruction` and `no_fabricated_quotes`.
->
-> **v0.3**: Full architecture rebuild — provenance frontmatter, offline source passages (`sources/`), automated fidelity tests (`fidelity.jsonl`), NPX installer, two-stage independent review, HARD-GATE rules, multi-platform plugin support across Claude Code / Cursor / Codex / OpenCode / Gemini CLI, session-start hook auto-injecting the master list.
+> ⚠️ The above is **AI-synthesized content**, generated from the *Platform Sutra* and *Diamond Sutra*; it does not represent Master Huineng's actual spoken teachings. The Chinese original is in [README.md](README.md#效果示例). Try the multi-master `/compare-masters` mode directly at [fojin.app/chat](https://fojin.app/chat).
 
 ---
 
@@ -140,17 +150,17 @@ This project is built out of respect for Buddhist traditions. All content is gen
 
 ## Features
 
-- **15 pre-built masters across four traditions**: 1 印度 (Madhyamaka · Nāgārjuna) + 8 汉传 (Yogācāra, Madhyamaka, Chan, Tiantai, Huayan, Pure Land, cross-tradition) + 3 藏传 (Kadam · Atiśa; Gelug · Tsongkhapa; Kagyu · Milarepa) + 3 南传 (Theravāda commentator · Buddhaghosa; Burmese vipassanā · Mahasi Sayadaw; Thai Forest · Ajahn Chah) — plus a `compare-masters` multi-master comparison meta-skill, ready to use out of the box
+- **15 pre-built masters across four traditions**: 1 印度 (Madhyamaka · Nāgārjuna) + 8 汉传 (Yogācāra, Madhyamaka, Chan, Tiantai, Huayan, Pure Land, cross-tradition) + 3 藏传 (Kadam · Atiśa; Gelug · Tsongkhapa; Kagyu · Milarepa) + 3 南传 (Theravāda commentator · Buddhaghosa; Burmese vipassanā · Mahasi Sayadaw; Thai Forest · Ajahn Chah) — plus 4 teaching modes (`/compare-masters` side-by-side, `/master-debate` multi-round dialectic, `/master-curriculum` study path, `/master-help` who-to-ask) and the `/create-master` generator
 - **Provenance enforcement**: Every master ships with declared source IDs (CBETA / BDRC / Toh / SuttaCentral / PTS / compliant compiled teachings); live retrieval adds a FoJin locator only when a real `text_id` is returned, and every doctrinal claim must carry a source citation
 - **Offline source passages**: `sources/` captures key passages from each master's core canon, so citations still work when FoJin is unreachable
 - **Progressive disclosure**: SKILL.md is a decision tree + quick reference; `references/` and `sources/` are loaded on demand to keep context lean
 - **HARD-GATE discipline**: Both `/create-master` and every prebuilt master require doctrinal claims, practice guidance, and text interpretation to cite that persona's declared sources (CBETA / BDRC / Toh / SuttaCentral / PTS / compliant compiled teachings); fabricated source IDs and fictional personas are forbidden
 - **Two-stage independent review**: The generation pipeline forces a "doctrinal accuracy → voice consistency" review before write; FAIL triggers up to 2 rounds of automatic repair
-- **Automated fidelity tests**: Each master's `tests/fidelity.jsonl` holds 10+ Q&A samples (the `compare-masters` meta-skill holds 18) validating citations and keyword coverage; CI runs a dry-run on every push
+- **Automated fidelity tests**: 211 fixtures (10+ per master, 18 for the `compare-masters` meta-skill) check keyword and citation coverage, and every graded answer also goes through the offline citation audit; CI runs a structural dry-run on every PR and on `main`; graded runs support Anthropic / DeepSeek / Gemini (`--provider`) with the matching API key, as a manual local/pre-release step — the latest full run and its case-by-case adjudication are [below](#fidelity-evaluation-current-data)
 - **Unified multi-platform plugin**: Claude Code, Cursor, Codex CLI, OpenCode, and Gemini CLI share one `prebuilt/` tree, with a session-start hook injecting the master list on every platform
 - **NPX one-shot install**: `npx master-skill install master-zhiyi` drops skills straight into Claude Code
 - **Offline toolchain**: `scripts/cite.py` (CBETA lookup), `scripts/query.py` (offline semantic search), `scripts/validate.py` (frontmatter linter)
-- **FoJin data bridge**: Connected to [fojin.app](https://fojin.app) with 503 data sources, 10K+ texts, 678K+ semantic embeddings, and a 31K-entity knowledge graph
+- **FoJin data bridge**: Connected to [fojin.app](https://fojin.app) — 10K+ texts, 678K+ semantic embeddings, a knowledge graph of 110K+ entities, and 600+ registered data sources
 - **AgentSkills standard**: Compliant with [Anthropic Agent Skills](https://github.com/anthropics/skills) — progressive disclosure, decision trees, black-box script pattern
 
 ## Framework Positioning
@@ -161,142 +171,58 @@ Master-skill is not a prompt pack. It is a verifiable Buddhist AI persona framew
 |---|---|
 | Source-grounded | `sources[]`, offline excerpts, FoJin live fallback, and citation self-audits per master |
 | Boundary-aware | `ETHICS.md`, per-master Layer 0 HARD-GATE rules, copyright tiers, and boundary violation reporting |
-| Fidelity-tested | `tests/fidelity.jsonl`, persona-fidelity schema, and promptfoo RAW / SPE / CUS evals |
+| Fidelity-tested | `tests/fidelity.jsonl`, persona-fidelity schema, promptfoo RAW / SPE / CUS evals (currently for 3 masters: Huineng, Tsongkhapa, Ajahn Chah), [current data below](#fidelity-evaluation-current-data) |
 | Runtime-ready | `prebuilt/master-*` AgentSkills, npm CLI, multi-platform hooks, and a FoJin runtime contract |
 
 The v1.0 track prioritizes framework stability over adding more masters. See [docs/v1-framework-roadmap.md](docs/v1-framework-roadmap.md) and [docs/fojin-runtime-contract.md](docs/fojin-runtime-contract.md).
 
----
-
-## Developer Installation
-
-> 👤 **Just want to try it?** Use [fojin.app/chat](https://fojin.app/chat) in your browser and skip this section entirely.
-> 🛠️ **This section is for**: Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI users who want to invoke `/master-xuanzang`, `/master-huineng`, etc. directly as terminal AgentSkills.
+### Fidelity evaluation (current data)
 
-### Installation
+The 211 fixtures (`prebuilt/*/tests/fidelity.jsonl`) run mechanical checks against real model answers: do the expected keywords and citations appear, and do the forbidden ones stay out. Every graded answer also goes through the offline citation audit. Read each number together with the model and the grading method that produced it:
 
-**NPX (recommended, no global state)**
+| | Value | Basis |
+|---|---|---|
+| Latest full run | **199 / 211 graded** (94.3%) | DeepSeek `deepseek-v4-flash`, commit [`06b8142`](https://github.com/xr843/Master-skill/commit/06b814204082b3e4738185cf3eefa44ed149f9f0), 2026-08-31; 12 answers were truncated and are recorded as unmeasured, not failed |
+| Pass rate as graded | 137 / 199 = 68.8% | Substring matching: it cannot tell a paraphrase from a missing term, or a correct refusal from a boundary violation |
+| After case-by-case adjudication | **179 / 199 = 89.9%** | doctrine 94.3% · boundary 85.9% · citation-under-pressure 83.3%. 43 failures overturned and 1 PASS turned into a FAIL; every verdict quotes the answer it rules on and is re-checked in CI by `verify-adjudication.py` |
+| Citation audit coverage | **569 / 619 = 92%**, 0 known fabrications | The same stored answers re-audited offline with the current auditor, across the CBETA, BDRC / Toh, PTS / SuttaCentral, and compiled-teaching families |
+| Meta-skill targeted re-run | compare-masters **0% → 90%** | 2026-09-13, 34 fixtures. After their output templates were fixed, `compare-masters` citations went from 0% to 90% checkable and `master-curriculum` from 0% to 100%; `master-debate` used to write sutra IDs in parentheses the audit could not see at all, and is now at 100% |
 
-`npx master-skill install --all` installs all 19 skills: 15 personas, 3 teaching modes, and the `create-master` generator. The generator is copied as a self-contained runtime, so it remains usable after the transient npx package directory is removed; reinstall and `update --all` refresh the runtime while preserving user-generated personas under `create-master/masters/`.
+**This column cannot advance the v1.0 gate.** The gate is defined on the Anthropic (`claude-sonnet-4-6`) column; two models are two instruments and are never pooled. That column still holds only one partial run, from 2026-08-18 (84 / 211, stopped when the account ran out of credit), whose "zero fabricated citations" was retracted on 2026-08-31 — the audit had not actually run on a single case.
 
-```bash
-# Install individual public skills
-npx master-skill install master-zhiyi
-npx master-skill install compare-masters
-npx master-skill install create-master
-
-# Install or list the complete 19-skill catalog
-npx master-skill install --all
-npx master-skill list
-```
+These are **keyword and citation-string coverage checks, not doctrinal correctness and not LLM-judged answer quality**. Details: [BASELINE-deepseek.md](eval/reports/BASELINE-deepseek.md) (the full run), [ADJUDICATION.md](eval/reports/ADJUDICATION.md) (case-by-case rulings), [BASELINE.md](eval/reports/BASELINE.md) (the Anthropic partial run and its retraction), and the [meta-skill re-run report](eval/reports/0.11.0-e97ded0-deepseek-metaskills.json).
 
-**Global install (frequent use / offline-friendly)**
+---
 
-```bash
-npm install -g master-skill            # Adds the binary to $PATH
-master-skill install master-zhiyi      # No more npx prefix
-master-skill list
-npm update -g master-skill             # Pull next minor / patch
-```
+## Developer Installation
 
-**Claude Code**
+> 👤 **Just want to try it?** Use [fojin.app/chat](https://fojin.app/chat) — no install needed.
+> 🛠️ **This section is for** Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI users.
 
 ```bash
-git clone https://github.com/xr843/Master-skill ~/Master-skill
-cd ~/Master-skill && pip install -r requirements.txt
-for d in prebuilt/master-*/; do ln -sf "$(pwd)/$d" ~/.claude/skills/"$(basename $d)"; done
-ln -sf "$(pwd)/prebuilt/compare" ~/.claude/skills/compare-masters
-ln -sf "$(pwd)" ~/.claude/skills/create-master
-```
-
-**Cursor** — Clone the repo; Cursor auto-detects `.cursor-plugin/plugin.json`.
-
-**OpenCode** — Add to `opencode.json`:
-
-```json
-{"plugin": ["master-skill@git+https://github.com/xr843/Master-skill.git"]}
-```
-
-**Codex CLI** — See [.codex/INSTALL.md](.codex/INSTALL.md)
-
-**Gemini CLI** — Auto-discovered via `gemini-extension.json` and `GEMINI.md`.
-
-### Use a Pre-built Master
-
-In any AgentSkills-compatible environment (Claude Code / Cursor / Codex CLI / OpenCode / Gemini CLI):
-
-```
-# 印度 (Indian)
-/master-nagarjuna      — Nāgārjuna (Indian · Madhyamaka | root of the eight schools)
-
-# 汉传 (Chinese)
-/master-xuanzang       — Master Xuanzang (Yogacara)
-/master-kumarajiva     — Kumarajiva (Madhyamaka / Sanlun)
-/master-huineng        — Master Huineng (Chan, Sixth Patriarch)
-/master-zhiyi          — Master Zhiyi (Tiantai)
-/master-fazang         — Master Fazang (Huayan)
-/master-yinguang       — Master Yinguang (Pure Land)
-/master-ouyi           — Master Ouyi (Tiantai / Pure Land, cross-tradition)
-/master-xuyun          — Master Xuyun (Chan, Five Houses)
-
-# 藏传 (Tibetan)
-/master-atisha         — Atiśa Dīpaṃkara (Kadam founder · three scopes · 982-1054)
-/master-tsongkhapa     — Tsongkhapa (Gelug founder · three principal aspects · prasaṅgika · 1357-1419)
-/master-milarepa       — Milarepa (Kagyu · Mahāmudrā · Naro Chodruk · 1052-1135)
-
-# 南传 (Theravāda)
-/master-buddhaghosa    — Buddhaghosa (commentarial summit · Visuddhimagga · 5th century)
-/master-mahasi-sayadaw — Mahasi Sayadaw (Burmese vipassanā · noting method · 1904-1982)
-/master-ajahn-chah     — Ajahn Chah (Thai Forest Tradition · Wat Pah Pong · 1918-1992)
-```
-
-### Teaching Modes (v0.7)
-
-- **`/compare-masters`** — multiple masters answer the same question side-by-side (horizontal, single-turn)
-- **`/master-debate`** — masters from different traditions engage in a 4-round adversarial dialectic (claim → rebut → respond → synthesize + remaining disagreements)
-- **`/master-curriculum`** — given your target tradition and current level (L0-L3), get a time-sequenced study path (foundation → intermediate → advanced + likely blind spots)
-
-**`/compare-masters` usage examples:**
-
-```
-# Auto-pick relevant masters
-/compare-masters what is emptiness
-
-# Manually pick masters (recommended for precise results)
-/compare-masters how to read the Heart Sutra --masters master-xuanzang,master-huineng,master-zhiyi
-
-# Natural-language triggers
-compare Huineng and Yinguang on nianfo
-how do Chan and Pure Land differ on practice
+npx master-skill install --all          # all 20 skills at once
+npx master-skill install master-huineng # or just one
+npx master-skill list                   # see everything installable
+npx master-skill recommend "how do I actually practice nianfo"   # not sure who to ask?
+npx master-skill doctor                 # check the local install and runtime paths
+npx master-skill update --all           # upgrade: reinstall everything, clearing stale files
 ```
 
-**Selection logic**: the command first tries to extract keywords from the question and match them against each master's core concepts; if nothing matches strongly, it falls back to topic mapping (nianfo / meditation / Yogacara-Madhyamaka / classification, etc.). **If the auto-pick feels off, use `--masters` to override.**
+Once installed, invoke `/master-huineng`, `/compare-masters`, etc. directly in chat.
 
-### Generate a Custom Master
-
-```
-/create-master Hongyi
-```
-
-Or use natural language:
-
-```
-Create a persona for Master Hongyi
-```
-
-The system will guide you through a three-step intake, then automatically collect data from FoJin and generate the doctrinal analysis and style files.
-
----
+> Per-platform setup (Claude Code plugin / Cursor / OpenCode / Codex CLI / Gemini CLI),
+> global install, teaching-mode usage, and `/create-master`
+> → **[docs/install.en.md](docs/install.en.md)**
 
 ## Desktop Manager
 
-A native desktop console (pure Rust, egui, single binary, no Electron) that unifies management of installation status, fidelity evaluation coverage, run tracing, and the quality gate across all 17 master skills:
+A native desktop console (pure Rust, egui, single binary, no Electron) that unifies management of installation status, fidelity evaluation coverage, run tracing, and the quality gate across 18 skills (the 15 masters plus `master-debate`, `master-curriculum` and `master-help`):
 
-![Master-skill Desktop Manager](https://raw.githubusercontent.com/xr843/Master-skill/master/docs/assets/desktop-manager.png)
+![Master-skill Desktop Manager](https://raw.githubusercontent.com/xr843/Master-skill/main/docs/assets/desktop-manager.png)
 
-**Download**: [Releases](https://github.com/xr843/Master-skill/releases) provides pre-built binaries for Linux / Windows / macOS — download and run directly (execute from the repository root; requires a local clone of this repo). On Linux/macOS you'll need to `chmod +x` the downloaded binary first; on macOS it's unsigned, so the first run needs right-click → Open, or `xattr -d com.apple.quarantine <file>` to clear the quarantine flag.
+**Download**: [Releases](https://github.com/xr843/Master-skill/releases) provides pre-built binaries for Linux / Windows / macOS; run them from the root of a local clone (they call the repository's `scripts/` and `bin/`). On Linux/macOS, prefer the matching `.tar.gz`, which keeps the executable bit when extracted; the raw binaries remain for compatibility and need `chmod +x`. Each release carries `SHA256SUMS` — check a download with `sha256sum --check --ignore-missing SHA256SUMS` — and build-provenance attestations, verifiable with `gh attestation verify <file> --repo xr843/Master-skill`. **Windows binaries before v0.12.0 cannot launch Python or npm**; from v0.12.0 they resolve them per platform, but CI does not yet run the desktop manager on a Windows host, so if it fails to find them, set `MASTER_SKILL_PYTHON` / `MASTER_SKILL_NPM`. The macOS binary is unsigned, so first launch still requires right-click → Open or `xattr -d com.apple.quarantine <file>`.
 
-**Build from source**:
+**Build from source** (Rust 1.95+):
 
 ```bash
 cd desktop && cargo build --release
@@ -308,156 +234,37 @@ cd desktop && cargo build --release
 
 ## Pre-built Masters
 
-### Nāgārjuna (c. 150-250) — Indian · Madhyamaka
-
-The founder of Mahāyāna Madhyamaka, revered in Chinese Buddhism as the **common patriarch of the eight schools** — Sanlun, Tiantai, Pure Land, Huayan, and Chan all trace their lineage back to him, and the Tibetan prasaṅgika Madhyamaka takes him as its root authority. He used the **eightfold negation of the middle way** to dismantle all conceptual proliferation, opened up dependent origination as emptiness with "whatever arises through conditions, that I declare to be emptiness," taught by way of the **two truths** while resolving into ultimate emptiness and the quiescence of proliferation, and distinguished the **easy and difficult paths** of practice. His *Mūlamadhyamakakārikā* is the root treatise of all later Madhyamaka study, and his *Mahāprajñāpāramitā-śāstra* is an encyclopedia of the Prajñāpāramitā teachings.
-Primary sources: CBETA — Mūlamadhyamakakārikā (T30n1564), Mahāprajñāpāramitā-śāstra (T25n1509), Dvādaśanikāya-śāstra (T30n1568), Vigrahavyāvartanī (T32n1631), Daśabhūmika-vibhāṣā (T26n1521).
-Invoke: `/master-nagarjuna`
-
-### Master Xuanzang (602-664)
-
-The greatest translator in Chinese Buddhist history. Traveled to India for 17 years, translated 75 texts in 1,335 fascicles. Founded the Yogacara (Faxiang) school in China. Known for precise, rigorous translation methodology and the "Five Categories of Non-Translation" principle.
-Primary sources: CBETA — Mahaprajnaparamita Sutra, Yogacarabhumi-sastra, Cheng Weishi Lun, Heart Sutra.
-Invoke: `/master-xuanzang`
-
-### Kumarajiva (344-413)
-
-One of the four great translators of Chinese Buddhism. Born in Kucha, translated in Chang'an. His translations are celebrated for literary elegance — the Lotus Sutra, Diamond Sutra, Vimalakirti Sutra, and Mulamadhyamakakarika remain the most widely used versions today. Established the foundation of the Sanlun (Madhyamaka) school in China.
-Primary sources: CBETA — Lotus Sutra, Diamond Sutra, Vimalakirti Sutra, Mulamadhyamakakarika, Mahaprajnaparamita-sastra.
-Invoke: `/master-kumarajiva`
-
-### Master Huineng (638-713)
-
-The Sixth Patriarch of Chan Buddhism, founder of the Southern School. An illiterate woodcutter who attained enlightenment upon hearing the Diamond Sutra. His Platform Sutra is the only Chinese-authored text honored with the title "sutra." Advocated "directly pointing to the mind, seeing one's nature to become Buddha."
-Primary sources: CBETA — Platform Sutra (T48n2008).
-Invoke: `/master-huineng`
-
-### Master Zhiyi (538-597)
-
-Founder of the Tiantai school, honored as "the Little Shakyamuni of the East." Established the first comprehensive doctrinal classification system in Chinese Buddhism (Five Periods, Eight Teachings). Authored the Three Great Works of Tiantai. Core teachings: three thousand realms in a single thought-moment, perfect interfusion of the three truths, dual cultivation of samatha and vipasyana.
-Primary sources: CBETA — Mohe Zhiguan (T46n1911), Fahua Xuanyi (T33n1718).
-Invoke: `/master-zhiyi`
-
-### Master Fazang (643-712)
-
-Third Patriarch and true systematizer of the Huayan school. National Preceptor under Empress Wu Zetian. Used the Golden Lion treatise to explain Huayan philosophy. Core teachings: dharmadhatu dependent origination, four dharma-realms, ten mysterious gates, six characteristics in perfect harmony.
-Primary sources: CBETA — Huayan Jing Tanxuan Ji (T35n1733), Huayan Wujiao Zhang (T45n1866).
-Invoke: `/master-fazang`
-
-### Master Yinguang (1861-1940)
-
-13th Patriarch of the Chinese Pure Land school. Central figure in the modern Pure Land revival. His writing is sincere and straightforward; he guided countless practitioners through correspondence, collected in the three volumes of the Yinguang Fashi Wenchao.
-Primary sources: CBETA — Wenchao volumes and the three Pure Land sutras.
-Invoke: `/master-yinguang`
-
-### Master Ouyi (1599-1655)
-
-One of the Four Great Masters of Late Ming Buddhism, 9th Patriarch of Pure Land. His motto: "Doctrine follows Tiantai, practice returns to Pure Land." The most important cross-tradition synthesizer in Chinese Buddhist history. His commentary on the Amitabha Sutra was praised by Master Yinguang as unsurpassable.
-Primary sources: CBETA — Amituo Jing Yaojie (T37n1762), Jiaoguan Gangzong.
-Invoke: `/master-ouyi`
-
-### Master Xuyun (1840-1959)
-
-Modern Chan patriarch who lived to 119 years. Unprecedented in Buddhist history for holding dharma transmission in all five houses of Chan (Linji, Caodong, Guiyang, Yunmen, Fayan). Restored six major ancestral monasteries. Advocated hua-tou investigation, honest practice, and harmonizing Chan with Pure Land.
-Primary sources: CBETA — Shurangama Sutra, Diamond Sutra, Platform Sutra.
-Invoke: `/master-xuyun`
-
-### Atiśa Dīpaṃkara (982-1054) — Tibetan · Kadam · Indo-Tibetan bridge
-
-Royal-born Indian master from the Sahor kingdom (modern Bangladesh). Studied Madhyamaka, Yogācāra and tantra at Vikramaśīla; received the bodhicitta lineage from Dharmakīrti of Suvarṇadvīpa (Sumatra). Invited to Tibet in 1042 by King Yeshe Ö to reform a tradition where Vinaya had decayed and tantra had become disconnected from sūtra foundations. His *Bodhipathapradīpa* (Toh 4465) became the source text for all later Tibetan *lamrim* literature. His chief disciple Dromtönpa founded Reting Monastery, originating the **Kadam school** — later succeeded by Tsongkhapa's "New Kadam" (Gelug). All four Tibetan schools recognize him as a root teacher.
-Primary sources: Toh 4465 *Bodhipathapradīpa* + Toh 3948 self-commentary + Kadam oral lineage *Pha chos / Bu chos*.
-Invoke: `/master-atisha`
-
-### Tsongkhapa (1357-1419) — Tibetan · Gelug founder
-
-Founder of the **Gelug school** (dGe lugs pa, "the way of virtue"; popularly known as the "Yellow Hat school") — basis of the Dalai Lama and Panchen Lama lineages. Born in Tsongkha (Qinghai). Studied with masters across all major schools, particularly the Sakya scholar Rendawa for prasaṅgika Madhyamaka. Reformed lax monastic discipline, integrated sūtra and tantra into a strict graduated path, and produced the great triology: *Lamrim Chenmo* (Great Treatise on the Stages of the Path), *sNgags rim chen mo* (Great Treatise on Tantra), and *Drang nges legs bshad snying po* (Essence of True Eloquence — definitive vs interpretable meaning). Founded Ganden Monastery (1409) — the seat of the school.
-Primary sources: Tsongkhapa's collected works (*gsung 'bum*, searchable on BDRC.io). Chinese translation by Dharma-master Faxun is the standard Sinophone reference.
-Invoke: `/master-tsongkhapa`
-
-> ⚠️ Tantric practice steps, empowerment liturgy, generation- and completion-stage details, deity mantras, and channels-and-drops practice are introduced **only at the level of name and historical context — concrete practice instructions are never given**.
-
-### Milarepa (1052-1135) — Tibetan · Kagyu
-
-Spiritual ancestor of the Tibetan Kagyu lineage and the paradigm of the "yogi tradition" (no monastery, mountain retreat, teaching through song). After committing serious harm in his youth through black magic, he sought purification under Marpa the Translator, who put him through severe trials before transmitting the complete Mahāmudrā and Naro Chodruk lineages. He spent decades in Himalayan retreat, surviving on nettles, and taught through extemporaneous **mGur** (songs of realization) — shaping the entire later Tibetan tradition.
-Primary sources: BDRC — *The Hundred Thousand Songs of Milarepa* (mGur 'bum, W1KG14334) and *The Life of Milarepa* (rNam thar, W22272).
-Invoke: `/master-milarepa`
-
-> ⚠️ Naro Chodruk (Six Yogas), tummo, generation/completion stages and other esoteric practices are introduced **only at the level of name and historical context — concrete practice instructions are never given**. Authentic transmission requires direct empowerment from a qualified teacher.
-
-### Buddhaghosa (5th century) — Theravāda · commentarial summit
-
-The most influential commentator and śāstra master in Theravāda history. Born a brahmin scholar in southern India, he travelled to the Mahāvihāra in Anurādhapura (Sri Lanka) to translate the old Sinhala commentaries (*Sīhaḷa-aṭṭhakathā*) into Pali. To prove his competence, he first composed the *Visuddhimagga* — a 23-chapter encyclopedia of Theravāda meditation and doctrine organized around the threefold training of **sīla, samādhi, paññā**. He then translated the four Nikāya commentaries, the Vinaya commentary *Samantapāsādikā*, and the Abhidhamma commentaries. His framework defines orthodox Theravāda exegesis to this day across Sri Lanka, Burma, Thailand, Cambodia, and Laos.
-Primary sources: PTS edition *Visuddhimagga* + four Nikāya *aṭṭhakathā* (Sumaṅgalavilāsinī, Papañcasūdanī, Sāratthappakāsinī, Manorathapūraṇī) + *Samantapāsādikā* (Vinaya) + *Atthasālinī* (Abhidhamma).
-Invoke: `/master-buddhaghosa`
-
-### Mahāsi Sayādaw U Sobhana (1904-1982) — Theravāda · Burmese vipassanā
-
-One of the most internationally influential meditation masters of modern Burma. Recognized as a *Pariyatti Sāsanahita* — the highest scriptural qualification in Burmese monasticism — by age 27. Studied four-foundations vipassanā with U Nārada (Mingun Sayadaw) from 1932. Established the **Mahasi Sasana Yeiktha** retreat center in Yangon in 1947, formalizing the **noting method** (rising-falling at the abdomen as primary object) tied to Visuddhimagga's seven purifications and sixteen insight knowledges. Served as *Final Editor* of the Sixth Buddhist Council (1954-1956) — the largest modern revision of the Pali Canon. His lineage profoundly shaped the founders of America's Insight Meditation Society (Goldstein, Salzberg, Kornfield).
-Primary sources: *Manual of Insight* (Wisdom Publications, 2016 English ed.), *The Progress of Insight* (BPS Sri Lanka Wheel No. 280), *Practical Vipassanā Meditation Exercises* (Mahasi Sasana Yeiktha).
-Invoke: `/master-mahasi-sayadaw`
-
-> ⚠️ **The AI must never confirm any individual's stage of insight or attainment of fruition.** Verification requires face-to-face interview with a qualified teacher. This is the strictest guardrail in this skill — the Mahasi tradition's "fruition is attainable" framing is famous for inducing self-attainment delusions, and the AI is forbidden from playing that role.
-
-### Ajahn Chah Subhaddo (1918-1992) — Theravāda · Thai Forest
-
-One of the most internationally influential masters of the Thai Forest Tradition. Renowned for strict Vinaya observance, four-foundations-of-mindfulness practice, and plain, life-grounded teaching style. His Western disciples (Ajahn Sumedho, Ajahn Pasanno, Ajahn Amaro and others) established Abhayagiri (California), Amaravati (UK), Cittaviveka (UK) and other branch monasteries, carrying the forest tradition to the West. Most-quoted line: *"If you let go a little, you have a little peace; if you let go completely, you have complete peace."*
-Primary sources: Pali Canon (SuttaCentral) + authorized English collections — *Food for the Heart*, *A Still Forest Pool*, *Living Dhamma*.
-Invoke: `/master-ajahn-chah`
-
----
+Fifteen masters across four traditions. The command *is* the skill name — invoke it directly once installed.
+
+| Command | Master | Tradition · School | Dates |
+|---|---|---|---|
+| `/master-nagarjuna` | Nāgārjuna | Indian · Madhyamaka | c. 150-250 |
+| `/master-kumarajiva` | Kumārajīva | Chinese · Sanlun / Madhyamaka | 344-413 |
+| `/master-zhiyi` | Zhiyi | Chinese · Tiantai | 538-597 |
+| `/master-xuanzang` | Xuanzang | Chinese · Yogācāra | 602-664 |
+| `/master-huineng` | Huineng | Chinese · Chan (Sixth Patriarch) | 638-713 |
+| `/master-fazang` | Fazang | Chinese · Huayan | 643-712 |
+| `/master-ouyi` | Ouyi | Chinese · Tiantai / Pure Land | 1599-1655 |
+| `/master-xuyun` | Xuyun | Chinese · Chan (all five houses) | 1840-1959 |
+| `/master-yinguang` | Yinguang | Chinese · Pure Land | 1861-1940 |
+| `/master-atisha` | Atiśa Dīpaṃkara | Tibetan · Kadam (lamrim) | 982-1054 |
+| `/master-milarepa` | Milarepa | Tibetan · Kagyu (Mahāmudrā) | 1052-1135 |
+| `/master-tsongkhapa` | Tsongkhapa | Tibetan · Gelug (Prāsaṅgika) | 1357-1419 |
+| `/master-buddhaghosa` | Buddhaghosa | Theravāda · commentarial | 5th c. |
+| `/master-mahasi-sayadaw` | Mahāsi Sayādaw | Theravāda · Burmese vipassanā | 1904-1982 |
+| `/master-ajahn-chah` | Ajahn Chah | Theravāda · Thai Forest | 1918-1992 |
+
+**Teaching modes**: `/compare-masters` · `/master-debate` · `/master-curriculum` · `/master-help` · **Generator**: `/create-master`
+
+> Life, doctrine, and declared sources for each → **[docs/masters.en.md](docs/masters.en.md)**
 
 ## Architecture
 
-```
-User request
-    |
-    v
-session-start hook ──> auto-injects master list (5 platforms, unified)
-    |
-    v
-SKILL.md (AgentSkills entry: decision tree + quick reference)
-    |
-    +-- Pre-built masters --> prebuilt/{slug}/
-    |                           +-- SKILL.md          (decision tree + <HARD-GATE>)
-    |                           +-- meta.json         (version / lineage / provenance)
-    |                           +-- references/       (loaded on demand)
-    |                           |   +-- teaching.md
-    |                           |   +-- voice.md
-    |                           +-- sources/          (offline declared-source passages)
-    |                           |   +-- *.md
-    |                           +-- tests/
-    |                               +-- fidelity.jsonl  (CI dry-run samples)
-    |
-    +-- Offline toolchain
-    |   +-- scripts/validate.py         (frontmatter linter)
-    |   +-- scripts/cite.py             (CBETA lookup)
-    |   +-- scripts/query.py            (offline semantic search)
-    |   +-- scripts/test-fidelity.py    (fidelity runner)
-    |   +-- scripts/validate-fidelity.py
-    |   +-- bin/cli.mjs                 (NPX installer)
-    |
-    +-- Custom generation (/create-master, HARD-GATE enforced)
-          +-- Step 1-2  prompts/intake.md → tools/sutra_collector.py
-          |             └─> FoJin API (KG + semantic search + text)
-          +-- Step 3    prompts/{sutra,voice}_analyzer.md → two-stage analysis
-          +-- Step 3.5  two-stage independent review ──┬─ prompts/doctrine_reviewer.md
-          |                                            └─ prompts/voice_reviewer.md
-          +-- Step 4-5  tools/master_builder.py → tools/skill_writer.py
-                        └─> tools/verify_sources.py (final pre-write check)
-
-Unified multi-platform manifests:
-  .claude-plugin/      → Claude Code    (hooks/run-hook.cmd → session-start)
-  .cursor-plugin/      → Cursor         (hooks/hooks-cursor.json)
-  .codex/              → Codex CLI      (.codex/INSTALL.md)
-  .opencode/           → OpenCode       (referenced from opencode.json)
-  gemini-extension.json → Gemini CLI    (auto-loaded with GEMINI.md)
-```
-
----
+Directory layout and data flow → **[docs/architecture.en.md](docs/architecture.en.md)**
 
 ## Relationship to FoJin
 
-[FoJin](https://fojin.app) is a Buddhist text aggregation platform integrating 503 data sources, 10K+ texts, 678K+ semantic vector embeddings, and a knowledge graph of 31K entities. It covers major corpora including CBETA Chinese Buddhist Canon, SuttaCentral Pali Canon and translations, and 84000 Tibetan Buddhist translations.
+[FoJin](https://fojin.app) is a Buddhist text aggregation platform holding 10K+ texts (about 9K of them in full text), 678K+ semantic vector embeddings, and a knowledge graph of 110K+ entities. It registers 600+ data sources, but **only four supply full text** — the CBETA Chinese Buddhist Canon, the SuttaCentral Pali Canon and translations, 84000's Tibetan Buddhist translations, and the GRETIL Sanskrit library; the rest are metadata records.
 
 Master-skill connects to the FoJin API via `tools/fojin_bridge.py` to enable:
 
@@ -491,33 +298,13 @@ Every citation must resolve to the persona's declared source ID. A FoJin locator
 
 ## Troubleshooting
 
-**Q: Does it still work when the FoJin API is unreachable?**
-
-Yes. Each prebuilt master ships with `prebuilt/<name>/sources/` — key passages from that master's core canon, stored offline. When FoJin is down, the master degrades to offline mode and declares "currently running on offline passages" in the reply. The `/create-master` pipeline asks the user to switch to manual-input mode when the API fails, so you can paste source text and continue.
-
-**Q: What does a valid CBETA citation look like, and how are sources verified?**
-
-CBETA citations use a `Txxn####` identifier (for example, the Lotus Sutra is `T09n0262`); Tibetan, Pali, and compiled-teaching personas use the BDRC / Toh, SuttaCentral / PTS, or teaching IDs declared in `meta.json.sources[]`. `scripts/validate-citation-contract.py` and `tools/verify_sources.py --check-links/--final-check` validate source families, identifier shapes, declared membership, and contract consistency offline. They do not parse free-text citations or guarantee HTTP reachability. The legacy online `verify_sources.py --fix` audit covers CBETA / FoJin links only.
-
-**Q: `npx master-skill install` fails with ENOTEMPTY or a permission error — what now?**
-
-Clean up any leftover `~/.claude/skills/master-<name>/` directories before retrying. For npm-cache weirdness, run `npm cache clean --force` and rerun NPX. Windows users should execute from Git Bash or WSL to avoid cmd.exe path-escaping issues.
-
-**Q: The generated master says things that don't match the historical record — how do I correct it?**
-
-Just tell the master in-chat: "he wouldn't phrase it like that" or "he should sound more stern." The `/create-master` correction mode classifies the fix (doctrinal → appended to `teaching.md`; stylistic → appended to `voice.md`), writes it as a `## Correction` block with timestamp, and bumps the patch version. Correction blocks take priority over analysis-generated content at runtime.
-
-**Q: How do I contribute a new prebuilt master?**
-
-See "Contributing" below. The short version: follow the v0.3 layout under `prebuilt/<name>/`, pass `scripts/validate.py --strict` with zero errors, ship at least 5 fidelity Q&A samples in `tests/fidelity.jsonl`, then open a PR.
-
----
+Common install, invocation, and retrieval questions → **[docs/troubleshooting.en.md](docs/troubleshooting.en.md)**
 
 ## Contributing
 
 Contributions are welcome: new prebuilt masters, corrections to source attributions, offline passage additions, or toolchain improvements.
 
-New masters must follow the v0.3 layout: `prebuilt/<name>/` containing SKILL.md (with provenance routing and a decision tree), `meta.json` (declared sources plus citation contract), `references/teaching.md` and `references/voice.md` (loaded on demand), `sources/*.md` (offline declared-source passages), and `tests/fidelity.jsonl` (5+ Q&A fidelity samples). Run `python3 scripts/validate.py --strict` and `python3 scripts/validate-citation-contract.py` for zero errors, and make sure the CI fidelity dry-run passes before opening a PR.
+New masters must follow the v0.3 layout: `prebuilt/<name>/` containing SKILL.md (with provenance routing and a decision tree), `meta.json` (declared sources plus citation contract), `references/teaching.md` and `references/voice.md` (loaded on demand), `sources/*.md` (offline declared-source passages), and `tests/fidelity.jsonl` (5+ Q&A fidelity samples, at least one of them a boundary case). Run `python3 scripts/validate.py --strict`, `python3 scripts/validate-fidelity.py` and `python3 scripts/validate-citation-contract.py` for zero errors, and make sure the CI fidelity dry-run passes before opening a PR.
 
 Before submitting, verify that every source resolves to the persona's declared source family, content is faithful to historical documents, and no sectarian bias is introduced.