@litfamily/litmuse 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.1 — 2026-10-26
+
+- The README studio's HyperFrames and Remotion cover templates pin newer `hono` and `fast-uri` in their lockfiles, picking up upstream fixes. A fresh template setup installs these versions.
+- Both READMEs are rewritten with real Muse Code captures of the LIT card, the handoff and a short demo, plus tables for how LitMuse adds to the host, the session lifecycle and the skills. The six captures ship in the package, so the npm page shows them too.
+- The hook code is the same as 0.1.0, so hook approvals carry over. `muse plugins update` asks you to approve the LitMuse agents again; `npx @litfamily/litmuse install` lists them and asks once.
+
+## 0.1.0 — 2026-10-22
+
+First release of LitMuse, the LitFamily member for Meta's Muse Code (built and probed against Muse Code 1.4.10).
+
+- Muse plugin `litmuse`: 39 skills, 4 commands (`/lit`, `/lit-korean`, `/lit-status`, `/lit-hud`), 10 hooks and 11 agents.
+- Bare `lit` activation through the UserPromptSubmit hook; SessionStart context steers lit routes to LitMuse skills when Muse also loads personal rules and skills from other tools.
+- lit-plan gate: PreToolUse keeps write_file, edit_file, apply_patch (including patch targets and moves) and delete_file inside `plans/` and `.litmuse/` after resolving `..` and symlinks, allows only provably read-only shell commands, lets only read-only LitMuse agents be spawned (workflows, schedules and image generation wait), and Stop holds the turn once until `plans/<slug>.md` exists. A negation-cluster guard counts only the negations a write adds to Markdown and stays off on the lit-humanizer route. A session ledger of tool events lives under `.litmuse/ledger/`.
+- `/lit <route>` and `/litmuse:lit` activate routes like a bare `lit` prompt.
+- `lit` re-entry: the first `lit` of a session sends the full activation; a later `lit` while the same route is active sends a note under 600 bytes without the skill re-read line and keeps the route state (so the lit-plan gate does not restart); `lit <other route>` switches with a full activation; a bare `lit` or `lit continue` resumes a plan already started with start-work; `lit new` and `lit restart` start over; a bare `lit` with nothing active or resumable asks what to run. Unreadable state falls back to the full activation.
+- During lit-plan every tool goes through an allowlist (read-only tools; plans/ writes; one plain read-only shell command with per-program flag lists; read-only `litmuse/*` children); MCP and unknown tools are refused. Route state lives outside the workspace under `$XDG_STATE_HOME/litmuse/`, with a journal so a missing or damaged state file keeps a planning limit on.
+- Each hook's declared command carries a digest of its code (`--digest`); a hook whose code differs refuses to run, and an update that changes a hook makes Muse ask for approval again.
+- `npx @litfamily/litmuse install` stages an owned bundle, backs up the Muse files it changes, installs at user scope, lists the 21 hook and agent approvals and asks once; `--dry-run`, `--yes` and `--approve` cover previews and scripts. Symlinked, foreign or edited destinations (bundle, backups, receipt, update cache) stop the install before its first write, with the exact command to move them aside; `uninstall --discard-modified` clears an edited bundle. An install that finds LitMuse registered from another path explains it instead of updating that copy.
+- `doctor` reports every approval, skill enrollment, catalog bytes against the 32 KB cap, overlaps with personal skills, and missing runtimes for the document and tooling skills. `models` lists the host catalog. `uninstall` removes the plugin and the bundle.
+- Every skill ships at full family depth with its own references, scripts, templates and data inside its folder: the slide and document engines (shared `plugin/lib/` office runtime), the diagram engine with 61 types, the interface design corpus with its contract validator and browser probe, the humanizer rules and scanners, per-language code references, and research, conference and wiki modes. New skills: `lit-brainstorm` (divergent ideation that scores a shortlist and hands off to deep-interview or lit-plan), `lit-team`, `autoconference`, `rules`, `lit-burnoff-file`, `lsp` and `lsp-setup` (checker CLIs, since Muse has no LSP tool). `review-work` runs plan review or work review, picked from what exists and forceable; `litgoal` sets and keeps the finish line on Muse's native goal while lit-loop and start-work run toward it.
+- Pinned engines (`office`, `diagram`, `readme`, `sciviz`) install on first use into `$XDG_DATA_HOME/litmuse/runtime/<name>` only; `npx @litfamily/litmuse runtime status|install <name|all>` checks or pre-warms them, and `doctor` lists each with its pre-warm command. The Python environments (office, sciviz and the motion audio tier) build from the newest `python3.X` between 3.10 and 3.14 on PATH, so a newer `python3` that the pinned wheels do not cover yet is passed over; `LITMUSE_OFFICE_PYTHON`, `LITMUSE_SCIVIZ_PYTHON` and `LITMUSE_MOTION_PYTHON` name one interpreter instead.
+- Continuation and resilience hooks: Stop keeps start-work going while plan rows (including F1–F4) are open and litgoal while criteria are open, at most 3 holds in a row without progress, released by a pause word or a BLOCKED/PAUSED/CANCELLED ledger note and never on an unapproved plan; PreCompact writes a redacted `.litmuse/handoff/latest.md` and SessionStart re-injects it once after compaction (Muse gives hooks no context percentage, so there is no percent trigger). PreToolUse refuses a write that adds a hedge cluster to Markdown or text prose; PostToolUse passes added whole-line comments to comment-checker and runs an advisory lit-humanizer check on written prose. The hooks keep a live stage record (route, plan rows, running child agents, goal) shown by `/lit-status` and `litmuse status --card`; `litmuse style eli5|asd-ste100|off` adds an answer style through SessionStart, since Muse rejects plugin output styles.
+- `lit-typographic-motion`: a film director that writes a treatment, then renders through the bundled deterministic stage renderer (HTML/SVG/Canvas/WebGL pages, 16:9 or 9:16) or the WebGL2 type engine (kinetic type, lyric and quote videos, title sequences), with a generated sound bed, look rounds on the rendered frames and a QA gate (flash audit, legibility, determinism, sound). Cover mode makes a silent, seamless README loop: one `renderFrame(t)` page with a loop kit that refuses clocks and entropy during capture, 2x capture, animated WebP, and a gate on the decoded file (G0–G6, flash, seek order, base-art SSIM) whose `--strict` TARGET includes 2 MiB; three recipes with pinned gate rows, four slide-like negatives that must keep failing, a timestamped defect log with window re-renders, and an asset list that stops on a missing file. `lit motion|film|video|영상` and film-making tasks route to it; PostToolUse records renders and the images `read_file` opened, and Stop holds the turn until the skill's done-check passes. Its `motion` engine installs only from a terminal (`npx @litfamily/litmuse runtime install motion`); `doctor` adds ffmpeg and libwebp rows.
+- `/hud` preset documented in `docs/hud-preset.md`.
+- README cover: the seven-member LitFamily motion film with LitMuse in the sixth bay, plus a still for reduced motion.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LitMuse contributors
+
+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

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="./docs/assets/cover-motion-still.webp" /><img src="./docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: seven armored robots power on one by one, the LitMuse robot in the sixth bay wakes with a lime visor and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">LitMuse</h1>
+<p align="center"><strong>Keep the work lit.</strong></p>
+
+<p align="center">LitMuse gives Meta's Muse Code the habit of planning before it edits, checking what it built, and leaving a handoff, so the next session starts where this one stopped. One npm command installs it as a Muse plugin.</p>
+
+<p align="center">
+<a href="https://www.npmjs.com/package/@litfamily/litmuse"><img src="https://img.shields.io/npm/v/@litfamily/litmuse?color=FF6337&amp;label=npm" alt="npm version" /></a>
+<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" /></a>
+<a href="https://github.com/wjgoarxiv/litmuse/stargazers"><img src="https://img.shields.io/github/stars/wjgoarxiv/litmuse?style=flat" alt="GitHub stars" /></a>
+</p>
+
+<p align="center"><a href="#install">Install</a> &nbsp; <a href="#quick-start">Quick start</a> &nbsp; <a href="#the-status-card">Status card</a> &nbsp; <a href="#automatic-handoff">Handoff</a> &nbsp; <a href="#safety-and-uninstall">Safety</a> &nbsp; <a href="./README_ko-KR.md">한국어</a></p>
+
+## What a session looks like
+
+<p align="center"><img src="./docs/assets/readme/demo.webp" width="960" alt="Terminal capture of three real commands on this Mac. muse --version prints Muse Code 1.4.11. litmuse status --card shows the lit-plan route active with plan 0 of 2 and the next open row. litmuse models lists the muse-spark models from the host catalog." /></p>
+
+Stripped to three lines, a planning session goes like this:
+
+```text
+you type    lit plan a tiny todo app
+it does     loads lit-plan, reads the repo, writes plans/todo-app.md with ordered rows
+it ends     "Plan saved. Run /start-work when you are happy with it."
+```
+
+LitMuse suits people who run Muse Code on real projects and want two things from it: proof before done, and sessions that pick up where the last one stopped. It helps most on work that runs longer than one sitting: a feature with tests, a refactor, a research question. It also builds slides and Word reports and cleans up stiff Korean or English prose.
+
+Muse runs the session while lit adds the routine around it.
+
+| The host | What lit adds |
+| --- | --- |
+| Takes a line and gets to work | Pins the goal and writes the failing test first |
+| Fills its context over a long session | Writes the handoff before compaction, reads it back after |
+| Opens the next session blank | `lit recap` reads the handoff and names the next step |
+| Calls it done when the model says so | Checks the plan with tests and real-surface proof |
+
+## Why LitMuse
+
+Muse Code starts fast: you type a line in the terminal and it gets to work. The trouble shows up later. A long session fills its context, the next session begins without what the last one learned, and "done" often means the model said so. You end up re-explaining where you were and checking by hand what really works.
+
+LitMuse gives each session a routine. Start a prompt with `lit` and the plugin's prompt hook tells Muse which LitMuse skill to load before it touches anything. A bigger change gets a written plan in `plans/` first. The work is checked against that plan with tests and a look at the real surface, and anything nobody could check is marked as unverified. Before you stop, a handoff in `.litmuse/handoff/` records what was built, how it was checked and what is left.
+
+Muse still runs the session and picks the model. LitMuse adds the way of working, and it lives in plain files you can read.
+
+## Install
+
+You need Node.js 20 or newer and Muse Code, signed in once. In a terminal, run:
+
+```bash
+npx @litfamily/litmuse install
+```
+
+The installer shows every destination first. It copies the plugin to `~/.local/share/litmuse/bundle`, backs up the Muse files it is about to change, and runs `muse plugins install` at user scope, so LitMuse is available in every project. Skills and commands work right away.
+
+Muse runs a plugin's hooks and agents only after you approve them. The installer lists the 21 capabilities (10 hooks, 11 agents) and asks you once whether to approve them all. Say no and it prints the `muse plugins approve ...` lines for later. Muse re-arms the agent approvals whenever the plugin is updated, so after an update the installer asks once more for those. Then check the result:
+
+```bash
+npx @litfamily/litmuse doctor
+```
+
+`doctor` ends with `LitMuse doctor: PASS` when everything is in place. Each capability that still waits for approval appears as `APPROVAL NEEDED` together with the exact command.
+
+To update, run the install command again. To remove everything, see Safety and uninstall below.
+
+The lifecycle runs through this table.
+
+| Task | Command |
+| --- | --- |
+| Install | `npx @litfamily/litmuse install` |
+| Preview first | `npx @litfamily/litmuse install --dry-run` |
+| Update | `npx @litfamily/litmuse install` |
+| Check | `npx @litfamily/litmuse doctor` |
+| Remove | `npx @litfamily/litmuse uninstall` |
+
+Useful switches: `--dry-run` previews and writes nothing; `--yes` lets an agent or CI shell install (a shell without a terminal otherwise only previews); `--approve` approves the capabilities without the question, for scripts; `--scope project` installs for one project.
+
+### Let a coding agent install it
+
+Paste this into a coding agent opened in any folder:
+
+```text
+Install LitMuse, the LitFamily plugin for Meta's Muse Code.
+Use only the official npm package @litfamily/litmuse. Show me your plan and wait for my yes before changing anything.
+1. Check that Node.js 20+ and muse are on PATH (`muse --version`).
+2. Preview: npx @litfamily/litmuse install --dry-run
+3. Install: npx @litfamily/litmuse install --yes
+   This installs the plugin and prints 21 approval commands. Ask me before approving; on my yes run
+   npx @litfamily/litmuse install --yes --approve
+4. Verify: npx @litfamily/litmuse doctor and report its last line.
+5. Tell me what was written (the installer prints a "Written:" list) and anything it refused.
+```
+
+## Quick start
+
+1. Open Muse in a project: `muse`. Type `/skills` to see the LitMuse skills and `/plugins` to see the plugin.
+2. Start a prompt with `lit`. Plain `lit` runs lit-loop; a word after it picks the route: `lit plan`, `lit review`, `lit research`, `lit debug`, `lit handoff`, `lit recap`, `lit korean`.
+3. Approve a plan, then type `/start-work` to build it row by row with tests.
+4. Before you stop, `lit handoff`. Next time, `lit recap` reads where you were.
+
+Headless runs work the same way: `muse exec --json "lit plan a tiny todo app" < /dev/null`.
+
+## The status card
+
+Muse's `/hud` is a fixed list of on/off fields, so plugins add nothing to it. LitMuse keeps its own live record instead: the route, the plan progress, and the child agents running right now. `/lit-status` and `litmuse status --card` show that record. For the terminal chrome around the card, the recommended `/hud` and theme preset lives in [docs/hud-preset.md](./docs/hud-preset.md).
+
+Read the card from top to bottom. The first line names the workflow and how long it has run, or says no route is active in this workspace. A second line names the plan file with ticked and total rows and the next open row. A lanes line names each running tool with its elapsed time, then each finished lane.
+
+At rest the card reports no active route:
+
+<p align="center"><img src="./docs/assets/card/idle.webp" width="960" alt="The status card with no active route in this workspace." /></p>
+
+While a plan runs, the card names the route, the plan file, and the next open row:
+
+<p align="center"><img src="./docs/assets/card/working.webp" width="960" alt="The status card while the lit-plan route is active, naming the plan file with 0 of 2 rows ticked and the next open row." /></p>
+
+Ticking a row moves the count and the next-row pointer:
+
+<p align="center"><img src="./docs/assets/card/after.webp" width="960" alt="The same card after the first row is ticked: 1 of 2 with the second row named next." /></p>
+
+The card reads the hook-kept state under `~/.local/state/litmuse/`, outside the project.
+
+## Automatic handoff
+
+A long session fills the model's context, and when Muse compacts it, detail drops out of the summary. Before the compaction, the PreCompact hook writes a handoff file; after it, SessionStart reads the fresh file back into the conversation. Two commands put this to work: `lit handoff` before you stop, `lit recap` when you return. The packet names what was built, how it was checked, and what is left.
+
+The hook answers with one recorded line:
+
+<p align="center"><img src="./docs/assets/handoff/saved.webp" width="960" alt="The PreCompact hook output line recording that it saved .litmuse/handoff/latest.md." /></p>
+
+The snapshot names the trigger, the session, the route, the plan with its open rows, and recent ledger lines:
+
+<p align="center"><img src="./docs/assets/handoff/latest.webp" width="960" alt="The handoff snapshot: trigger, session, the lit-plan route, the plan with 0 ticked and 2 open rows, and recent ledger lines." /></p>
+
+## What you get
+
+**39 skills**, each a dense Muse skill loaded on demand, with the references, scripts, templates and engines it needs inside its own folder. The catalog only holds their short descriptions, about 3.7 KB in total, so they keep their place even next to a large personal skill collection.
+
+Every skill below ships in its own folder and loads on demand. Find the row that matches the task at hand.
+
+| Area | Skills | Role |
+| --- | --- | --- |
+| Work loop | lit-loop, litgoal, litwork | Goal pinned, failing test first, record left |
+| Plan and build | lit-plan, start-work, lit-code, debugging, refactor, lit-commit, lsp, lsp-setup | Written plan, then row-by-row build |
+| Ideas first | lit-brainstorm, deep-interview, lit-crucible | Diverge, clarify, pressure-test |
+| Review and cleanup | review-work, visual-qa, comment-checker, lit-burnoff, lit-burnoff-file | Second look, then residue stripped |
+| Research | litresearch, autoresearch, autoconference, wikify, lit-comprehend | Parallel searchers, traced claims |
+| Teams | lit-team | Child agents behind one packet |
+| Prose | lit-humanizer | Korean and English cleanup, facts kept |
+| Continuity | lit-recap, lit-handoff, lit-init, rules | Handoffs, recaps, orientation |
+| Interface and docs | frontend-ui-ux, readme-studio | Accessible UI, fact-checked READMEs |
+| Documents and figures | lit-docx, lit-pptx, lit-scientific-visualization, lit-diagram-drawer | Decks, styled docs, plots, diagrams |
+| Film and covers | lit-typographic-motion | Short films and cover loops, gated on decoded output |
+| Tools | structural-search, browser-drive | Syntax-shaped search, live pages |
+
+The document, diagram, README-cover and figure skills ship pinned engines (`office`, `diagram`, `readme`, `sciviz`). Each installs on first use into `~/.local/share/litmuse/runtime/<name>` and nowhere else; inside Muse's proxy-only sandbox that first install can be refused, so pre-warm them from a terminal with `npx @litfamily/litmuse runtime install all` (`runtime status` shows each one). The motion skill's engine (`motion`: its font set and type-engine package) installs from a terminal only, so `runtime install motion` (or `all`) is the way it gets there. They also call programs already on your machine: Python 3.10 to 3.14 (a newer `python3` is passed over for the newest `python3.X` in that range), LibreOffice, pandoc, Poppler, Chrome or Chromium, ffmpeg, libwebp (`img2webp`, `dwebp`), ast-grep and the language checkers the `lsp` skill drives. `doctor` lists what is missing and the command that installs it; LitMuse installs nothing globally.
+
+**4 commands**: `/lit <route> <task>`, `/lit-korean <file or text>`, `/lit-status`, `/lit-hud`.
+
+**10 hooks**: SessionStart (LitMuse context and routes; after a compaction it re-injects the saved handoff once, and it adds the answer style you chose with `litmuse style`), UserPromptSubmit (`lit` activation; a later `lit` while its route is active continues it, `lit <other route>` switches, a bare `lit` resumes a started plan, `lit new` or `lit restart` starts over), PreToolUse (during lit-plan: writes through write_file, edit_file, apply_patch or delete_file stay inside `plans/` and `.litmuse/`, shell commands are read-only, and only read-only LitMuse agents may be spawned; on every route: guards against clustered negations and clustered hedges that a write adds to Markdown or text prose), PostToolUse (the tool ledger, plus the whole-line comments an edit added for comment-checker and an advisory lit-humanizer check on written prose; on the motion route it also notes each render and each image `read_file` opened), PostToolUseFailure (ledger), Stop (a lit-plan turn ends after its plan file exists; a motion turn ends when the skill's done-check passes on the last render, or after two holds with a plain not-done notice; start-work keeps going while plan rows are open and litgoal while criteria are open, each at most 3 holds in a row without progress), PreCompact (writes `.litmuse/handoff/latest.md` before Muse compacts), SubagentStart (the return format for child agents), SubagentStop and SessionEnd (ledger lines). The hooks also keep a live record of the route, plan progress and running child agents, which `/lit-status` and `npx @litfamily/litmuse status --card` show, because Muse's `/hud` shows fixed fields only.
+
+**11 agents**, spawned as `litmuse/<name>`: lit-planner, lit-executor, lit-verifier, qa-runner, quality-reviewer, librarian-researcher, and five Korean prose agents. Reviewers and the Korean agents get read and search tools only.
+
+**Models**: `npx @litfamily/litmuse models` lists the models and effort tiers your Muse install offers, read from Muse's own catalog. A model Meta adds later shows up there with no LitMuse update.
+
+## What a planning turn may do
+
+`lit plan` turns are planning only, and the PreToolUse hook holds that line with an allowlist. Anything unlisted is refused, including MCP tools and tools a later Muse release adds.
+
+- Read-only tools: `read_file`, `search`, `read_skill`, `web_search`, `web_fetch`, `read_memory`, `work_status`, `work_list`, `subagent_status`, `subagent_wait`, `subagent_read_result`, `subagent_cancel`, `request_user_input`, `get_goal`, `cron_list`.
+- File writes (`write_file`, `edit_file`, `apply_patch`, `delete_file`) only inside `plans/` and `.litmuse/`, after `..` and symlinks are resolved.
+- Shell (`bash`, `exec_command`, `shell`) only for one plain command from `ls`, `cat`, `head`, `tail`, `wc`, `rg` or `git log|status|diff|show`, with listed flags and no `;`, `&`, `|`, `<`, `>`, backticks, `$` or line breaks. `bash_input` is refused.
+- Child agents only as read-only `litmuse/*` agents (lit-planner, librarian-researcher, lit-verifier, quality-reviewer and the Korean prose agents).
+
+Route state lives outside the project, under `~/.local/state/litmuse/`, so no tool in a planning turn reaches it. If that state goes missing or breaks during a plan turn, the limit stays on. Each hook's declared command carries a digest of its code, so when an update changes a hook, Muse asks you to approve it again.
+
+## Living next to other tools
+
+Muse also reads personal rules and skills written for other coding tools, such as a user rules file or a personal skills folder. LitMuse leaves that on, because those rules are yours. Its session context asks Muse to use the LitMuse skill for every lit route, and `doctor` warns when a personal skill shares a name with a LitMuse skill or comes from another tool's plugin folder. For a clean run, switch off "Personal rules fallback" and "Personal skills fallback" in `/settings`; a headless run takes `muse exec --no-foreign-personal-context` (the interactive `muse` rejects that flag on 1.4.11).
+
+## Safety and uninstall
+
+- The installer writes to `~/.local/share/litmuse/` and, through the `muse` CLI, to Muse's own plugin store and settings. It backs up `~/.config/muse/settings.json` and Muse's `installed.json` first, and it reads Muse's credential file in no step.
+- It refuses to replace a bundle directory that is a symbolic link, holds someone else's files, or was edited after install.
+- It writes nothing under `~/.claude` or `~/.codex`; a test pins that.
+- Hooks fail open: if one breaks, your session continues.
+- Engine caches live under `~/.local/share/litmuse/runtime/`; `npx @litfamily/litmuse runtime status` shows what is installed. `uninstall` keeps them, so delete that folder to free the space.
+- Remove everything with `npx @litfamily/litmuse uninstall` (add `--dry-run` to preview). Plans and `.litmuse/` folders in your projects stay where they are.
+
+## Family
+
+LitMuse is one of the seven LitFamily packages, and the seven armored robots on the cover stand for them. Each package brings the same way of working to one coding agent and installs and runs on its own, so you only need the one for the agent you use.
+
+## License
+
+MIT, © LitMuse contributors. LitMuse is an independent community project and is not affiliated with or endorsed by Meta.

package/README_ko-KR.md

@@ -0,0 +1,197 @@
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="./docs/assets/cover-motion-still.webp" /><img src="./docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 일곱 로봇 패널이 차례로 켜지고, 여섯 번째 칸의 LitMuse 로봇이 라임색 바이저와 테두리를 밝힌 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+
+<h1 align="center">LitMuse</h1>
+<p align="center"><strong>Keep the work lit.</strong></p>
+
+<p align="center">LitMuse는 Meta의 Muse Code에 일하는 습관을 붙여 줍니다. 고치기 전에 계획하고, 만든 것을 확인하고, 끝낼 때 인계 메모를 남깁니다. 그래서 다음 세션이 이번 세션이 멈춘 자리에서 바로 이어집니다. npm 명령 하나로 Muse 플러그인으로 설치됩니다.</p>
+
+<p align="center">
+<a href="https://www.npmjs.com/package/@litfamily/litmuse"><img src="https://img.shields.io/npm/v/@litfamily/litmuse?color=FF6337&amp;label=npm" alt="npm version" /></a>
+<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" /></a>
+<a href="https://github.com/wjgoarxiv/litmuse/stargazers"><img src="https://img.shields.io/github/stars/wjgoarxiv/litmuse?style=flat" alt="GitHub stars" /></a>
+</p>
+
+<p align="center"><a href="#설치">설치</a> &nbsp; <a href="#빠른-시작">빠른 시작</a> &nbsp; <a href="#상태-카드">상태 카드</a> &nbsp; <a href="#자동-핸드오프">핸드오프</a> &nbsp; <a href="#안전과-제거">안전</a> &nbsp; <a href="./README.md">English</a></p>
+
+## 세션은 이렇게 돌아갑니다
+
+<p align="center"><img src="./docs/assets/readme/demo.webp" width="960" alt="이 Mac에서 실행한 실제 명령 세 개의 터미널 캡처. muse --version은 Muse Code 1.4.11을 출력합니다. litmuse status --card는 lit-plan 경로가 활성 상태이며 계획이 0/2이고 다음 행을 가리킵니다. litmuse models는 호스트 카탈로그의 muse-spark 모델을 보여 줍니다." /></p>
+
+세 줄로 줄이면 계획 세션은 이렇게 흘러갑니다.
+
+```text
+입력      lit plan a tiny todo app
+동작      lit-plan을 불러와 저장소를 읽고, 작업 순서와 확인 기준을 plans/todo-app.md에 씀
+마무리    "계획을 저장했습니다. 괜찮으면 /start-work를 실행하세요."
+```
+
+LitMuse는 실제 프로젝트에서 Muse Code를 쓰는 사람에게 맞습니다. 원하는 것은 두 가지입니다. 끝났다는 말보다 먼저 확인한 증거, 그리고 지난번에 멈춘 자리에서 이어지는 세션입니다. 한 번에 끝나지 않는 일에서 가장 쓸모가 있습니다. 테스트를 곁들인 기능, 리팩터, 조사 질문이 그런 일입니다. 발표 슬라이드와 Word 보고서도 만들고, 굳은 한국어와 영어 글도 다듬습니다.
+
+Muse가 세션을 돌리고 lit이 주변 순서를 더합니다.
+
+| 호스트 | lit이 더하는 것 |
+| --- | --- |
+| 한 줄을 받고 바로 일을 시작합니다 | 목표를 고정하고 떨어지는 테스트를 먼저 씁니다 |
+| 긴 세션에서 컨텍스트가 찹니다 | 컴팩션 전에 인계를 쓰고 뒤에 다시 읽습니다 |
+| 다음 세션은 빈자리에서 시작합니다 | `lit recap`이 인계를 읽고 다음 일을 가리킵니다 |
+| 모델이 끝났다고 하면 끝납니다 | 계획에 맞춰 테스트와 실제 확인으로 검증합니다 |
+
+## 왜 LitMuse인가
+
+Muse Code는 시작이 빠릅니다. 터미널에 한 줄 적으면 바로 일을 시작합니다. 문제는 그다음에 옵니다. 세션이 길어지면 컨텍스트가 차고, 다음 세션은 지난 세션이 알던 것을 모른 채 시작합니다. "끝났다"는 말도 모델이 그렇게 말했다는 뜻일 때가 많습니다. 결국 어디까지 했는지 다시 설명하고, 무엇이 실제로 돌아가는지 손으로 확인하게 됩니다.
+
+LitMuse는 세션마다 따라갈 순서를 줍니다. 프롬프트를 `lit`으로 시작하면 플러그인의 프롬프트 훅이 어떤 LitMuse 스킬을 먼저 불러올지 Muse에 알려 줍니다. 큰 변경은 먼저 `plans/`에 계획으로 적습니다. 작업은 그 계획에 맞춰 테스트와 실제 화면 확인으로 검증하고, 확인하지 못한 부분은 미확인으로 표시합니다. 끝내기 전에는 `.litmuse/handoff/`에 무엇을 만들었고 어떻게 확인했고 무엇이 남았는지 기록합니다.
+
+세션을 돌리고 모델을 고르는 것은 여전히 Muse입니다. LitMuse는 일하는 방식을 더하고, 그 방식은 직접 읽을 수 있는 평범한 파일로 남습니다.
+
+## 설치
+
+Node.js 20 이상과, 한 번 로그인해 둔 Muse Code가 필요합니다. 터미널에서 실행하세요.
+
+```bash
+npx @litfamily/litmuse install
+```
+
+설치기는 먼저 쓸 위치를 모두 보여 줍니다. 그다음 플러그인을 `~/.local/share/litmuse/bundle`에 복사하고, 바꿀 Muse 파일을 백업한 뒤, `muse plugins install`을 user 범위로 실행합니다. 그래서 모든 프로젝트에서 LitMuse를 쓸 수 있습니다. 스킬과 명령은 설치 직후부터 동작합니다.
+
+Muse는 플러그인의 훅과 에이전트를 사용자가 승인한 뒤에만 실행합니다. 설치기는 승인할 21개(훅 10, 에이전트 11)를 보여 주고 한 번에 승인할지 딱 한 번 묻습니다. 아니라고 답하면 나중에 실행할 `muse plugins approve ...` 줄을 출력합니다. Muse는 플러그인이 업데이트될 때마다 에이전트 승인을 다시 요구하므로, 업데이트 뒤에는 설치기가 그 부분만 한 번 더 묻습니다. 그다음 결과를 확인합니다.
+
+```bash
+npx @litfamily/litmuse doctor
+```
+
+모두 갖춰지면 `doctor`의 마지막 줄이 `LitMuse doctor: PASS`입니다. 아직 승인을 기다리는 항목은 `APPROVAL NEEDED`와 실행할 명령으로 표시됩니다.
+
+업데이트하려면 설치 명령을 다시 실행하세요. 전부 지우려면 아래 안전과 제거를 보세요.
+
+설치부터 제거까지 이 표의 명령으로 처리합니다.
+
+| 작업 | 명령 |
+| --- | --- |
+| 설치 | `npx @litfamily/litmuse install` |
+| 미리 보기 | `npx @litfamily/litmuse install --dry-run` |
+| 업데이트 | `npx @litfamily/litmuse install` |
+| 확인 | `npx @litfamily/litmuse doctor` |
+| 제거 | `npx @litfamily/litmuse uninstall` |
+
+자주 쓰는 옵션: `--dry-run`은 미리 보기만 하고 아무것도 쓰지 않습니다. `--yes`는 터미널이 붙지 않은 에이전트나 CI 셸에서 설치를 허용합니다(그런 셸에서는 기본으로 미리 보기만 합니다). `--approve`는 질문 없이 승인까지 진행하는 스크립트용입니다. `--scope project`는 한 프로젝트에만 설치합니다.
+
+### 코딩 에이전트에게 설치 맡기기
+
+아무 폴더에서 연 코딩 에이전트에 아래를 붙여 넣으세요.
+
+```text
+Meta Muse Code용 LitFamily 플러그인인 LitMuse를 설치해 줘.
+공식 npm 패키지 @litfamily/litmuse만 써. 무엇이든 바꾸기 전에 계획을 보여 주고 내 승인을 기다려.
+1. Node.js 20 이상과 muse가 PATH에 있는지 확인해 (`muse --version`).
+2. 미리 보기: npx @litfamily/litmuse install --dry-run
+3. 설치: npx @litfamily/litmuse install --yes
+   플러그인이 설치되고 승인 명령 21줄이 출력돼. 승인하기 전에 나에게 묻고, 내가 좋다고 하면
+   npx @litfamily/litmuse install --yes --approve 를 실행해.
+4. 확인: npx @litfamily/litmuse doctor 를 실행하고 마지막 줄을 알려 줘.
+5. 무엇이 쓰였는지("Written:" 목록)와 설치기가 거부한 것이 있으면 알려 줘.
+```
+
+## 빠른 시작
+
+1. 프로젝트에서 Muse를 엽니다: `muse`. `/skills`로 LitMuse 스킬을, `/plugins`로 플러그인을 확인합니다.
+2. 프롬프트를 `lit`으로 시작합니다. `lit`만 쓰면 lit-loop가 돌고, 뒤에 붙는 낱말이 경로를 고릅니다: `lit plan`, `lit review`, `lit research`, `lit debug`, `lit handoff`, `lit recap`, `lit korean`.
+3. 계획이 마음에 들면 `/start-work`로 한 줄씩 테스트와 함께 구현합니다.
+4. 끝내기 전에 `lit handoff`. 다음에는 `lit recap`이 어디까지 왔는지 읽어 줍니다.
+
+헤드리스 실행도 같습니다: `muse exec --json "lit plan a tiny todo app" < /dev/null`.
+
+## 상태 카드
+
+Muse의 `/hud`는 켜고 끄는 고정 항목 목록이라서 플러그인 글은 올릴 수 없고, LitMuse는 자체 실시간 기록을 둡니다. 경로, 계획 진행, 지금 돌고 있는 자식 에이전트가 그 기록입니다. `/lit-status`와 `litmuse status --card`로 봅니다. 카드 주변 터미널 모양의 추천 `/hud`와 테마 프리셋은 [docs/hud-preset.md](./docs/hud-preset.md)에 있습니다.
+
+카드는 위에서 아래로 읽습니다. 첫 줄은 워크플로 이름과 실행 시간을 적고, 활성 경로가 없으면 없다고 적습니다. 둘째 줄은 계획 파일 이름과 체크한 행 수, 전체 행 수, 다음으로 풀 행을 적습니다. 레인 줄은 실행 중인 도구와 경과 시간, 끝난 레인을 적습니다.
+
+쉴 때 카드는 활성 경로가 없다고 알립니다.
+
+<p align="center"><img src="./docs/assets/card/idle.webp" width="960" alt="활성 경로가 없는 상태의 상태 카드." /></p>
+
+계획이 돌 때 카드는 경로와 계획 파일, 다음 행을 보여 줍니다.
+
+<p align="center"><img src="./docs/assets/card/working.webp" width="960" alt="lit-plan 경로가 활성 상태인 카드. 계획 파일의 0/2행과 다음으로 풀 행을 가리킵니다." /></p>
+
+행에 체크하면 개수와 다음 행 표시가 바뀝니다.
+
+<p align="center"><img src="./docs/assets/card/after.webp" width="960" alt="첫 행을 체크한 뒤의 같은 카드. 1/2이며 두 번째 행을 다음으로 가리킵니다." /></p>
+
+카드는 프로젝트 밖에 있는 `~/.local/state/litmuse/` 아래 훅 기록을 읽습니다.
+
+## 자동 핸드오프
+
+긴 세션은 모델 컨텍스트를 채우고, Muse가 컴팩션하면 요약에서 세부 사항이 떨어져 나갑니다. 컴팩션 전에 PreCompact 훅이 인계 파일을 쓰고, 컴팩션 뒤에 SessionStart가 새 파일을 대화로 다시 읽어들입니다. 두 명령으로 씁니다. 멈추기 전에 `lit handoff`, 돌아오면 `lit recap`. 패킷에는 만든 것, 확인한 방법, 남은 일이 들어갑니다.
+
+훅은 기록 한 줄로 답합니다.
+
+<p align="center"><img src="./docs/assets/handoff/saved.webp" width="960" alt="PreCompact 훅의 출력 한 줄. .litmuse/handoff/latest.md를 저장했다고 기록합니다." /></p>
+
+스냅샷에는 실행 계기, 세션, 경로, 열린 행이 있는 계획, 최근 기록 줄이 들어갑니다.
+
+<p align="center"><img src="./docs/assets/handoff/latest.webp" width="960" alt="인계 스냅샷. 실행 계기와 세션, lit-plan 경로, 0개 체크와 2개 열린 행의 계획, 최근 기록 줄을 보여 줍니다." /></p>
+
+## 들어 있는 것
+
+**스킬 39개.** 필요할 때 불러오는 밀도 높은 Muse 스킬이며, 각 스킬에 필요한 참고 문서, 스크립트, 템플릿, 엔진이 그 스킬 폴더 안에 함께 들어 있습니다. 카탈로그에는 짧은 설명만 올라가며, 모두 합쳐 약 3.7 KB라서 개인 스킬이 많은 환경에서도 자리를 지킵니다.
+
+아래 모든 스킬은 각자 폴더에 들어 있으며 필요할 때 불러옵니다. 하려는 일에 맞는 행을 찾으세요.
+
+| 분야 | 스킬 | 역할 |
+| --- | --- | --- |
+| 작업 고리 | lit-loop, litgoal, litwork | 목표 고정, 떨어지는 테스트 먼저, 기록 남기기 |
+| 계획과 구현 | lit-plan, start-work, lit-code, debugging, refactor, lit-commit, lsp, lsp-setup | 계획서 작성, 행별 구현 |
+| 아이디어 다지기 | lit-brainstorm, deep-interview, lit-crucible | 넓히기, 묻기, 압박 테스트 |
+| 검토와 정리 | review-work, visual-qa, comment-checker, lit-burnoff, lit-burnoff-file | 다시 보기, 잔재 지우기 |
+| 조사 | litresearch, autoresearch, autoconference, wikify, lit-comprehend | 병렬 탐색, 근거 추적 |
+| 팀 | lit-team | 하나의 패킷 뒤 자식 에이전트 |
+| 글 | lit-humanizer | 한국어와 영어 다듬기, 사실 유지 |
+| 이어 가기 | lit-recap, lit-handoff, lit-init, rules | 인계, 회고, 길잡이 |
+| 화면과 문서 | frontend-ui-ux, readme-studio | 접근 쉬운 화면, 사실 확인된 README |
+| 문서와 그림 | lit-docx, lit-pptx, lit-scientific-visualization, lit-diagram-drawer | 데크, 꾸민 문서, 그래프, 다이어그램 |
+| 영상과 표지 | lit-typographic-motion | 짧은 영상과 표지 고리, 인코딩본 검사 |
+| 도구 | structural-search, browser-drive | 코드 모양 검색, 살아 있는 페이지 |
+
+문서, 다이어그램, README 표지, 그림 스킬은 버전이 고정된 엔진(`office`, `diagram`, `readme`, `sciviz`)을 함께 씁니다. 엔진은 처음 쓸 때 `~/.local/share/litmuse/runtime/<이름>`에만 설치됩니다. Muse의 프록시 전용 샌드박스에서는 이 첫 설치가 막힐 수 있으니 터미널에서 `npx @litfamily/litmuse runtime install all`로 미리 설치해 두세요(`runtime status`로 상태를 봅니다). 모션 스킬의 엔진(`motion`: 글꼴 묶음과 타입 엔진 패키지)은 터미널에서만 설치되므로, `runtime install motion`(또는 `all`)으로 들입니다. 이 스킬들은 내 컴퓨터에 이미 있는 프로그램도 씁니다: Python 3.10~3.14(더 새로운 `python3`는 건너뛰고 이 범위에서 가장 새로운 `python3.X`를 씀), LibreOffice, pandoc, Poppler, Chrome 또는 Chromium, ffmpeg, libwebp(`img2webp`, `dwebp`), ast-grep, 그리고 `lsp` 스킬이 부르는 언어 검사 도구. 빠진 것과 설치 명령은 `doctor`가 알려 주며, LitMuse가 전역으로 무언가를 설치하는 일은 없습니다.
+
+**명령 4개**: `/lit <경로> <작업>`, `/lit-korean <파일 또는 글>`, `/lit-status`, `/lit-hud`.
+
+**훅 10개**: SessionStart(LitMuse 컨텍스트와 경로 표. 컴팩션 뒤에는 저장해 둔 인계 메모를 한 번 다시 넣고, `litmuse style`로 고른 답변 스타일도 더함), UserPromptSubmit(맨 앞의 `lit` 활성화. 같은 경로가 이미 켜져 있으면 이어서 진행, 다른 경로면 전환, 맨 `lit`은 시작한 계획을 재개, `lit new`·`lit restart`는 새로 시작), PreToolUse(lit-plan 동안 write_file·edit_file·apply_patch·delete_file 쓰기는 `plans/`와 `.litmuse/` 안으로 제한하고 셸 명령은 읽기 전용만 허용, 자식 에이전트는 읽기 전용 LitMuse 에이전트만 허용, 모든 경로에서 쓰기가 Markdown이나 텍스트 글에 새로 더하는 부정문 몰림과 얼버무림 몰림 검사), PostToolUse(도구 기록, 편집이 새로 더한 한 줄 주석을 comment-checker에 넘기고 쓴 글에는 lit-humanizer 참고 검사. 모션 경로에서는 렌더 실행과 `read_file`로 연 이미지도 기록), PostToolUseFailure(기록), Stop(lit-plan 턴은 계획 파일이 생긴 뒤 끝남. 모션 턴은 마지막 렌더가 스킬의 완료 검사를 통과하면 끝나고, 두 번 붙잡은 뒤에는 아직 끝나지 않았다고 분명히 말하게 함. start-work는 계획 행이, litgoal은 기준이 남아 있으면 이어 가되 진전 없이 연속 3번까지만 붙잡음), PreCompact(Muse가 컴팩션하기 전에 `.litmuse/handoff/latest.md`를 씀), SubagentStart(자식 에이전트의 보고 형식), SubagentStop·SessionEnd(기록 줄). 훅은 경로, 계획 진행, 실행 중인 자식 에이전트도 실시간 기록으로 남기며, Muse의 `/hud`는 고정 항목만 보여 주므로 이 기록은 `/lit-status`와 `npx @litfamily/litmuse status --card`로 봅니다.
+
+**에이전트 11개**, `litmuse/<이름>`으로 띄웁니다: lit-planner, lit-executor, lit-verifier, qa-runner, quality-reviewer, librarian-researcher, 그리고 한국어 글 에이전트 다섯. 리뷰어와 한국어 에이전트는 읽기와 검색 도구만 씁니다.
+
+**모델**: `npx @litfamily/litmuse models`는 내 Muse가 제공하는 모델과 추론 단계를 Muse 자체 카탈로그에서 읽어 보여 줍니다. Meta가 나중에 추가하는 모델도 LitMuse 업데이트 없이 그대로 나타납니다.
+
+## 계획 턴에서 할 수 있는 일
+
+`lit plan` 턴은 계획 전용이며, PreToolUse 훅이 허용 목록으로 이를 지킵니다. 목록에 없는 도구는 MCP 도구와 나중에 Muse에 추가되는 도구까지 모두 거부됩니다.
+
+- 읽기 도구: `read_file`, `search`, `read_skill`, `web_search`, `web_fetch`, `read_memory`, `work_status`, `work_list`, `subagent_status`, `subagent_wait`, `subagent_read_result`, `subagent_cancel`, `request_user_input`, `get_goal`, `cron_list`.
+- 파일 쓰기(`write_file`, `edit_file`, `apply_patch`, `delete_file`)는 `..`와 심볼릭 링크를 풀어 본 뒤 `plans/`와 `.litmuse/` 안에서만 허용합니다.
+- 셸(`bash`, `exec_command`, `shell`)은 `ls`, `cat`, `head`, `tail`, `wc`, `rg`, `git log|status|diff|show` 중 하나를 허용된 플래그로만 쓴 단일 명령일 때 통과합니다. `;`, `&`, `|`, `<`, `>`, 백틱, `$`, 줄바꿈이 들어가면 거부되고, `bash_input`도 거부됩니다.
+- 자식 에이전트는 읽기 전용 `litmuse/*` 에이전트(lit-planner, librarian-researcher, lit-verifier, quality-reviewer, 한국어 글 에이전트)만 띄울 수 있습니다.
+
+경로 상태는 프로젝트 밖 `~/.local/state/litmuse/`에 두어 계획 턴의 어떤 도구도 닿지 못합니다. 계획 턴 중에 이 상태가 사라지거나 깨져도 제한은 그대로 유지됩니다. 훅마다 선언된 명령에 코드 digest가 들어 있어서, 업데이트로 훅이 바뀌면 Muse가 승인을 다시 묻습니다.
+
+## 다른 도구와 함께 쓰기
+
+Muse는 다른 코딩 도구용으로 써 둔 개인 규칙과 개인 스킬도 함께 읽습니다(사용자 규칙 파일, 개인 스킬 폴더 등). 그 규칙은 사용자 것이므로 LitMuse는 이 동작을 그대로 둡니다. 대신 세션 컨텍스트로 lit 경로마다 LitMuse 스킬을 쓰도록 안내하고, 개인 스킬 이름이 LitMuse 스킬과 같거나 다른 도구의 플러그인 폴더에서 왔으면 `doctor`가 경고합니다. 깨끗한 실행이 필요하면 `/settings`에서 "Personal rules fallback"과 "Personal skills fallback"을 끄세요. 헤드리스 실행은 `muse exec --no-foreign-personal-context`를 쓰면 됩니다(1.4.11의 대화형 `muse`는 이 플래그를 받지 않습니다).
+
+## 안전과 제거
+
+- 설치기는 `~/.local/share/litmuse/`에 쓰고, `muse` CLI를 거쳐 Muse의 플러그인 저장소와 설정에 씁니다. 그 전에 `~/.config/muse/settings.json`과 Muse의 `installed.json`을 백업하며, Muse 인증 파일은 열어 보지 않습니다.
+- 번들 폴더가 심볼릭 링크이거나, 다른 사람의 파일이 들어 있거나, 설치 후 수정되었으면 교체를 거부합니다.
+- `~/.claude`와 `~/.codex` 아래에는 아무것도 쓰지 않으며, 테스트가 이를 고정합니다.
+- 훅은 실패해도 세션을 막지 않고 그대로 통과시킵니다.
+- 엔진 캐시는 `~/.local/share/litmuse/runtime/` 아래에 있고, 설치 상태는 `npx @litfamily/litmuse runtime status`로 봅니다. `uninstall`은 캐시를 남기므로 공간을 비우려면 그 폴더를 지우세요.
+- 전부 지우려면 `npx @litfamily/litmuse uninstall`(미리 보려면 `--dry-run`). 프로젝트 안의 계획과 `.litmuse/` 폴더는 그대로 남습니다.
+
+## 패밀리
+
+LitMuse는 LitFamily 패키지 일곱 개 가운데 하나이고, 표지의 로봇 일곱이 그 일곱 패키지입니다. 패키지마다 코딩 에이전트 하나에 같은 작업 방식을 들여오며 각자 따로 설치되어 동작하므로, 쓰는 에이전트에 맞는 하나만 설치하면 됩니다.
+
+## 라이선스
+
+MIT, © LitMuse contributors. LitMuse는 독립 커뮤니티 프로젝트이며 Meta와 제휴하거나 Meta의 보증을 받은 프로젝트가 아닙니다.

package/bin/litmuse.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { install } from '../lib/install.mjs';
+import { uninstall } from '../lib/uninstall.mjs';
+import { doctor } from '../lib/doctor.mjs';
+import { models } from '../lib/models.mjs';
+import { packageVersion, PACKAGE_ROOT, stageState } from '../lib/bundle.mjs';
+import { paths } from '../lib/paths.mjs';
+import { installedPlugin, museVersion } from '../lib/muse.mjs';
+import { checkUpdate } from '../lib/update-check.mjs';
+import { runtime } from '../lib/runtime.mjs';
+import { buildCard, renderCard } from '../lib/stage-card.mjs';
+import { styleCommand } from '../lib/style.mjs';
+
+const HELP = `LitMuse ${packageVersion()}: LitFamily workflows for Meta's Muse Code
+
+Usage: litmuse <command> [options]
+
+Commands
+  install      Stage the plugin, install it into Muse at user scope, and offer the approvals
+  doctor       Check install state, every approval, skill enrollment, catalog bytes and overlaps
+  status       Short version of doctor plus an update check; --card shows the live LIT card for this folder
+  models       List the models and effort tiers your Muse catalog offers
+  hud          Show the recommended /hud and /theme preset
+  style        eli5 | asd-ste100 | off | status: the answer style LitMuse adds to every session
+  runtime      status [name] | install <name|all>: the pinned engine runtimes, cached under the LitMuse data dir
+  uninstall    Remove the plugin from Muse and the staged bundle
+  help         This text
+
+Options
+  --dry-run    Show every destination and command; write nothing
+  --yes, -y    Allow writes from a shell without a terminal (agents, CI)
+  --approve    Approve the hooks and agents without asking (for scripts)
+  --scope <s>  Muse install scope: user (default) or project
+  --json       Machine-readable output (doctor, models)
+  --offline    Skip the npm update check
+  --discard-modified  uninstall: also remove a bundle edited after install
+  --version    Print the version`;
+
+function parse(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--yes' || a === '-y') flags.yes = true;
+    else if (a === '--approve') flags.approve = true;
+    else if (a === '--json') flags.json = true;
+    else if (a === '--offline') flags.offline = true;
+    else if (a === '--discard-modified') flags.discardModified = true;
+    else if (a === '--card') flags.card = true;
+    else if (a === '--scope') flags.scope = argv[++i];
+    else if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--version' || a === '-v') flags.version = true;
+    else rest.push(a);
+  }
+  return { command: rest[0] ?? 'help', args: rest.slice(1), flags };
+}
+
+async function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^y(es)?$/i.test((await rl.question(question)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  const { command, args, flags } = parse(process.argv.slice(2));
+  const env = process.env;
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !env.CI);
+  const print = (line) => process.stdout.write(`${line}\n`);
+  if (flags.version) {
+    print(packageVersion());
+    return 0;
+  }
+  if (flags.help || command === 'help') {
+    print(HELP);
+    return 0;
+  }
+  if (flags.scope && !['user', 'project'].includes(flags.scope)) {
+    print('--scope takes user or project');
+    return 2;
+  }
+  switch (command) {
+    case 'install':
+    case 'update':
+      return install({ env, flags, interactive, ask, print });
+    case 'uninstall':
+      return uninstall({ env, flags, interactive, print });
+    case 'doctor':
+      return doctor({ env, flags, print });
+    case 'models':
+      return models({ env, flags, print });
+    case 'runtime':
+      return runtime({ env, flags, args, print });
+    case 'hud':
+      print(readFileSync(join(PACKAGE_ROOT, 'docs', 'hud-preset.md'), 'utf8'));
+      return 0;
+    case 'style':
+      return styleCommand(args, env, print);
+    case 'status': {
+      if (flags.card) {
+        const card = buildCard({ cwd: process.cwd(), env });
+        print(flags.json ? JSON.stringify(card, null, 2) : renderCard(card));
+        return 0;
+      }
+      const st = stageState(paths(env));
+      const plugin = installedPlugin(env);
+      print(`LitMuse ${packageVersion()} · host ${museVersion(env) ?? 'muse not found'}`);
+      print(`bundle ${st.state}${st.version ? ` (${st.version})` : ''} · Muse plugin ${plugin ? `installed ${plugin.version ?? ''}`.trim() : 'not installed'}`);
+      if (!flags.offline) {
+        const u = await checkUpdate(env);
+        if (u.latest && u.latest !== packageVersion()) print(`update: ${u.latest} available (npx @litfamily/litmuse@latest install)`);
+      }
+      print('Run `npx @litfamily/litmuse doctor` for every check.');
+      return 0;
+    }
+    default:
+      print(`Unknown command: ${command}\n\n${HELP}`);
+      return 2;
+  }
+}
+
+main().then((code) => { process.exitCode = code ?? 0; }, (err) => {
+  process.stderr.write(`litmuse: ${err.message}\n`);
+  process.exitCode = 1;
+});