mastermind-md 0.1.0

package/.claude/skills/master/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: master
+description: Alias of /mastermind for opening a file in Mastermind. `/master <file>` is equivalent to `/mastermind <file>` — translate the file into both reading languages, then open it.
+---
+
+# master — alias of /mastermind
+
+Treat `/master $ARGUMENTS` exactly as `/mastermind $ARGUMENTS`: run the Mastermind **Visualize
+flow** (translate the file into both reading languages first via `mastermind translate-blocks`,
+then `mastermind open`). See the `mastermind` skill for the full protocol.

package/.claude/skills/mastermind/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: mastermind
+description: Visualize and review a Markdown file in Mastermind — configure preferences (/mastermind setup), run the bilingual demo (/mastermind demo), or open any .md (/mastermind <file>, or bare = the most recent .md from this chat). Always pre-translates the doc into both reading languages first. Use whenever the user wants to open, visualize, or review a doc in Mastermind.
+---
+
+# Mastermind
+
+Mastermind shows one `.md` as a reviewable document whose reading-language toggle flips
+between the user's **Preferred** (`langPair.a`) and **Secondary** (`langPair.b`) languages.
+**You are the translator** — there is no API key. The rule for every path below: **translate
+first, then open**, so the toggle is warm the instant the page loads.
+
+Dispatch on `$ARGUMENTS`:
+
+## `/mastermind setup`
+Configure the five defaults. Pull the option lists from the CLI, then ask the user with your
+native question UI (one round, multiple-choice where possible):
+
+```sh
+mastermind browsers --json    # installed browsers → "Preferred browser"
+mastermind themes --json      # color themes → "Color theme"
+mastermind typefaces --json   # type sets → "Font theme"
+```
+
+Ask for: **Preferred language**, **Secondary language**, **Preferred browser**, **Color
+theme**, **Font theme**. Apply in one call (a = Preferred, b = Secondary):
+
+```sh
+mastermind config set langPair.a="<Preferred>" langPair.b="<Secondary>" \
+  browser="<app or empty>" theme="<themeId>" typeSet="<typeSetId>"
+```
+
+Numeric/unknown keys are rejected with exit 2 — surface the message if a set fails. Confirm
+what you set.
+
+## `/mastermind demo`
+Localize the showcase template in `reference/demo.md` **into the Preferred language** (keep
+every CriticMarkup mark intact), write it to `./mastermind-demo.md`, then run the **Visualize
+flow** on it. The toggle reveals the Secondary-language version.
+
+## `/mastermind <file>`  (bare `/mastermind` → most recent `.md` you wrote this chat)
+Run the **Visualize flow** on the given file. With no argument, use the most recent `.md` you
+created or edited in this conversation; if there is none, ask which file.
+
+## Visualize flow — ALWAYS TRANSLATE FIRST
+1. `mastermind translate-blocks <file>` → prints `{ "targetLang", "cachePath", "blocks":[{"hash","text"}] }`.
+   - If `blocks` is empty, the cache is already warm — skip to step 4.
+   - If it errors that `langPair` is unset, tell the user to run `/mastermind setup` first.
+2. Translate each block's `text` into `targetLang`. **Preserve all Markdown + CriticMarkup
+   syntax exactly** (`{++ ++}`, `{-- --}`, `{~~ ~> ~~}`, `{== ==}`, `{>> <<}`); translate only
+   human-readable text; leave `@name:` author tags untranslated.
+3. Write them to the cache via stdin:
+   ```sh
+   printf '%s' '[{"hash":"…","text":"<translated>"},…]' | mastermind translate-blocks <file> --save
+   ```
+   It reports how many cached (and skips stale-hash / CriticMarkup-mismatch entries).
+4. Open it: `mastermind open <file>` (uses the configured browser; toggle is warm).
+   - **Plan you want reviewed?** Use `mastermind open --wait <file>` instead, then follow the
+     plan-review protocol: when it returns, re-read the file, apply/argue each CriticMarkup
+     mark and comment, remove the resolved marks + the `mastermind:summary` block, and re-open
+     for the next round until approved.

package/.claude/skills/mastermind/reference/demo.md

@@ -0,0 +1,35 @@
+# Welcome to Mastermind
+
+This is a demo document. Mastermind renders Markdown **and** CriticMarkup review marks,
+and the language toggle (top bar) flips it between your two reading languages.
+
+## What you're looking at
+
+The file on disk is the single source of truth — no database, no cloud. An agent writes
+a plan here; you review it {++with inline edits++} and comments; it reads the same file back.
+
+> Marks flow one direction only: the agent proposes, you accept. Nothing reaches disk
+> until you approve it.
+
+## The five review marks
+
+- Insertion — adds {++a few words++} to the text.
+- Deletion — removes {--an outdated phrase--}.
+- Substitution — swaps {~~old wording~>clearer wording~~}.
+- Highlight — calls out {==a passage worth a second look==}.
+- Comment — leaves a margin note. {>> Try clicking the language toggle above. <<}
+
+## A small table and some code
+
+| Surface | Purpose      |
+| ------- | ------------ |
+| Reading | review marks |
+| Source  | raw markdown |
+
+```ts
+function greet(name: string): string {
+  return `Hello, ${name}`
+}
+```
+
+Toggle the language to see this same document in your secondary language.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Ding
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+```
+█▀▄▀█ ▄▀█ █▀ ▀█▀ █▀▀ █▀█ █▀▄▀█ █ █▄░█ █▀▄
+█░▀░█ █▀█ ▄█ ░█░ ██▄ █▀▄ █░▀░█ █ █░▀█ █▄▀
+```
+
+**Review markdown with your coding agent — local-first, the file is the only channel.**
+
+An agent writes a plan or doc as `.md`; you read and mark it up in the browser with
+[CriticMarkup](https://github.com/CriticMarkup/CriticMarkup-toolkit); you hand it back; the agent
+re-reads the same file. No database, no accounts, no cloud — just localhost and the file on disk.
+Mastermind also renders any doc **bilingually**: your agent translates it into your two reading
+languages, toggled live.
+
+![Mastermind Reading view](https://raw.githubusercontent.com/Jingquank/Mastermind/main/assets/screenshots/reading.png)
+
+*The Reading view — rendered Markdown with the heading outline on the left.*
+
+## Requirements
+
+- Node 20+ and a desktop browser (macOS is the tested platform).
+- A coding agent (Claude Code, Cursor, Gemini, …) — it drives the review loop and does translation.
+
+## Install
+
+```sh
+npm i -g mastermind-md        # installs the `mastermind` command
+mastermind install-agents     # add the /mastermind + /master skills to your agent(s)
+```
+
+<details>
+<summary>Install from source</summary>
+
+```sh
+git clone https://github.com/Jingquank/Mastermind.git
+cd Mastermind
+npm install
+npm run build
+npm link                      # puts `mastermind` on your PATH
+mastermind install-agents
+```
+</details>
+
+`install-agents` writes the skills for every coding agent it finds (`~/.claude`, `~/.cursor`,
+`~/.gemini`) and, where it can, a one-line rule so finished plans open in Mastermind automatically.
+Undo any time with `mastermind uninstall-agents`.
+
+## How it works
+
+- **The file is the protocol.** Open a `.md` and Mastermind serves it at `127.0.0.1:5173`. Your
+  edits, comments, and accept/reject decisions round-trip through that one file as CriticMarkup —
+  nothing else, nowhere else.
+- **The review loop.** An agent writes a plan → you review and mark it up → **Save & hand back** →
+  the agent re-reads the file and revises. Repeat until you approve. Suggestions flow one direction
+  only (the agent proposes, you accept); nothing reaches disk until you do.
+- **Bilingual, no API key.** Your coding agent *is* the translator. Mastermind shows the doc in your
+  Preferred and Secondary languages (default English ⇄ 简体中文), toggled live, cached on disk
+  (`.mastermind/translations/`) so the toggle is instant and keeps working offline once warmed.
+
+![The same document toggled to Simplified Chinese](https://raw.githubusercontent.com/Jingquank/Mastermind/main/assets/screenshots/bilingual.png)
+
+*One click flips the whole doc to your second language; code and inline literals stay put.*
+
+## The `/mastermind` skills
+
+After `install-agents`, type these in your agent:
+
+| Command | What it does |
+| --- | --- |
+| `/mastermind setup` | Pick your two reading languages, preferred browser, and color / font theme. |
+| `/mastermind demo` | Open a bilingual demo doc — see the marks and the language toggle in action. |
+| `/mastermind <file>` | Translate any `.md` into both languages and open it. Bare `/mastermind` uses the most recent `.md` from the chat. |
+| `/master <file>` | Shorthand for `/mastermind <file>`. |
+
+Every open **translates first**, so the language toggle is warm the instant the page loads. With the
+global rule installed, finished plans (in plan mode) open in Mastermind automatically, in both
+languages.
+
+## Reviewing
+
+Three views over the same file (`Cmd+E` cycles, `Cmd+S` saves):
+
+- **Reading** — rendered markdown with CriticMarkup as a visual diff: green insertions, struck
+  deletions, paired substitutions, gold highlights, and comment threads in a margin rail. Select
+  text → Comment / Suggest deletion / Highlight. Hover a suggestion → Accept / Reject (`Cmd+Z`
+  undoes review actions). Task-list checkboxes are live.
+- **Editing** — WYSIWYG; opening a file and saving it unchanged produces a byte-identical file.
+- **Source** — raw markdown with CriticMarkup highlighting.
+
+All five marks work inline anywhere: `{++ins++}`, `{--del--}`, `{~~old~>new~~}`, `{==highlight==}`,
+`{>>comment<<}`. A highlight directly followed by a comment anchors it to that span; consecutive
+comments form a thread; comments carry `@author:` tags.
+
+![CriticMarkup review marks](https://raw.githubusercontent.com/Jingquank/Mastermind/main/assets/screenshots/review-marks.png)
+
+*An insertion, a substitution, a struck deletion, a highlight, and a margin comment — all CriticMarkup.*
+
+The **language toggle** (top bar) flips the whole document between your two languages, block by
+block. `Cmd+F` is a mark-aware find (filter by comments / edits / highlights); `Cmd+P` prints
+ink-on-white with comments as numbered footnotes. Reviews are **multi-round**: when the agent
+rewrites the open file, a banner offers a reload so you pick up the new version in place.
+
+## Settings & themes
+
+Open Settings (the gear, bottom-right) to choose your **color theme** (seven ship — **Grid**, the
+Swiss-red default, plus Mint, Sepia, Carbon, Slate, Cobalt, Rose), **typeface** and **code font**, an
+optional **code-color scheme**, your **reading languages** (Preferred + Secondary), and the
+**browser** Mastermind opens in. Everything persists to `~/.config/mastermind/config.json` and is
+scriptable:
+
+```sh
+mastermind config set langPair.a=English langPair.b=Japanese theme=sepia browser="Google Chrome"
+```
+
+Themes are just data — drop a `themes/<id>/{theme.json,tokens.css}` folder in and it shows up in Settings.
+
+![Settings panel](https://raw.githubusercontent.com/Jingquank/Mastermind/main/assets/screenshots/settings.png)
+
+*Themes, typeface, code font, code-color scheme, and your two reading languages — all in Settings.*
+
+## Commands
+
+```sh
+mastermind open <file>             # open a file for review
+mastermind open --wait <file>      # block until "Save & hand back" (the agent loop)
+mastermind new                     # start a blank draft
+mastermind workspace .             # browse a directory as a file tree (alias: ws)
+mastermind config get | set …      # read / write preferences
+mastermind translate-blocks <file> # pre-translate a doc into both languages (the skills use this)
+mastermind install-agents          # install the skills + global rule (undo: uninstall-agents)
+mastermind status | stop           # daemon status / shutdown
+```
+
+---
+
+More: **[AGENT_SETUP.md](AGENT_SETUP.md)** — the agent protocol, assist channel, and exit-code contract.

package/assets/agent/global.md

@@ -0,0 +1,12 @@
+## Mastermind: always visualize bilingually
+
+Whenever you open, visualize, or review any Markdown file or plan in Mastermind, you MUST
+**translate it into both reading languages first, then open it** — so the reading-language
+toggle is warm. Use the `mastermind` skill's Visualize flow: `mastermind translate-blocks
+<file>` → translate the emitted blocks (preserving Markdown + CriticMarkup) → pipe them to
+`mastermind translate-blocks <file> --save` → `mastermind open <file>`.
+
+After you finish making a plan, write it to a `.md` file and run that same flow — preparing
+both the chat-language version and the secondary-language translation — using `mastermind open
+--wait <file>` when you want the user to review and hand it back. Set the language pair once
+with `/mastermind setup`.

package/bin/mastermind.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const entry = path.join(here, '..', 'dist', 'cli', 'index.js')
+
+if (!existsSync(entry)) {
+  console.error(
+    'mastermind: build output missing.\n' +
+      'Run `npm install && npm run build` in the mastermind repo, then try again.',
+  )
+  process.exit(1)
+}
+
+await import(entry)