@litfamily/litmuse 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 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,128 @@
-# 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="#install">Install</a> &nbsp; <a href="#what-you-get">Skills</a> &nbsp; <a href="./docs/hud-preset.md">/hud preset</a> &nbsp; <a href="#safety-and-uninstall">Safety</a> &nbsp; <a href="./README_ko-KR.md">한국어</a></p>
+
+## 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.
+
+```text
+you type    lit plan a tiny todo app
+it does     loads lit-plan, reads the repo, writes plans/todo-app.md with ordered tasks and checks
+it ends     "Plan saved. Run /start-work when you are happy with it."
+```
+
+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.
+
+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`.
+
+## 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:
+
+- Loop and goals: lit-loop, litgoal, litwork
+- Ideas and planning: lit-brainstorm, deep-interview, lit-crucible, lit-plan
+- Building: start-work, lit-code, debugging, refactor, lit-commit, lsp, lsp-setup
+- Review and cleanup: review-work (plan review and work review), visual-qa, comment-checker, lit-burnoff, lit-burnoff-file
+- Research and knowledge: litresearch, autoresearch, autoconference, wikify, lit-comprehend
+- Teams: lit-team
+- Prose: lit-humanizer (Korean and English)
+- Continuity and guidance: lit-recap, lit-handoff, lit-init, rules
+- Interface and docs: frontend-ui-ux, readme-studio
+- Documents and figures: lit-docx, lit-pptx, lit-scientific-visualization, lit-diagram-drawer
+- Film and covers: lit-typographic-motion (short films, kinetic type, lyric videos and seamless README cover loops, each rendered, gated on the decoded file and looked at frame by frame)
+- Tools: structural-search, browser-drive
+
+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) never installs from a session at all, so `runtime install motion` (or `all`) from a terminal is the only 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 never installs software 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 must be 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` cannot show plugin text.
+
+**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.
+
+**Status bar**: Muse's `/hud` is a list of on/off fields. The recommended preset and theme are in [docs/hud-preset.md](./docs/hud-preset.md).
+
+## What a planning turn may do
+
+`lit plan` turns are planning only, and the PreToolUse hook enforces that 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 can reach it. If that state goes missing or is damaged while a plan turn is active, 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. To keep a run clean, 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 never reads Muse's credential file.
+- 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,128 @@
+<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="#설치">설치</a> &nbsp; <a href="#들어-있는-것">스킬</a> &nbsp; <a href="./docs/hud-preset.md">/hud 프리셋</a> &nbsp; <a href="#안전과-제거">안전</a> &nbsp; <a href="./README.md">English</a></p>
+
+## 왜 LitMuse인가
+
+Muse Code는 시작이 빠릅니다. 터미널에 한 줄 적으면 바로 일을 시작합니다. 문제는 그다음에 옵니다. 세션이 길어지면 컨텍스트가 차고, 다음 세션은 지난 세션이 알던 것을 모른 채 시작합니다. "끝났다"는 말도 모델이 그렇게 말했다는 뜻일 때가 많습니다. 결국 어디까지 했는지 다시 설명하고, 무엇이 실제로 돌아가는지 손으로 확인하게 됩니다.
+
+LitMuse는 세션마다 따라갈 순서를 줍니다. 프롬프트를 `lit`으로 시작하면 플러그인의 프롬프트 훅이 어떤 LitMuse 스킬을 먼저 불러올지 Muse에 알려 줍니다. 큰 변경은 먼저 `plans/`에 계획으로 적습니다. 작업은 그 계획에 맞춰 테스트와 실제 화면 확인으로 검증하고, 확인하지 못한 부분은 미확인으로 표시합니다. 끝내기 전에는 `.litmuse/handoff/`에 무엇을 만들었고 어떻게 확인했고 무엇이 남았는지 기록합니다.
+
+```text
+입력      lit plan a tiny todo app
+동작      lit-plan을 불러와 저장소를 읽고, 작업 순서와 확인 기준을 plans/todo-app.md에 씀
+마무리    "계획을 저장했습니다. 괜찮으면 /start-work를 실행하세요."
+```
+
+세션을 돌리고 모델을 고르는 것은 여전히 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`와 실행할 명령으로 표시됩니다.
+
+자주 쓰는 옵션: `--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
+   플러그인이 설치되고 승인 명령 20줄이 출력돼. 승인하기 전에 나에게 묻고, 내가 좋다고 하면
+   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`.
+
+## 들어 있는 것
+
+**스킬 39개.** 필요할 때 불러오는 밀도 높은 Muse 스킬이며, 각 스킬에 필요한 참고 문서, 스크립트, 템플릿, 엔진이 그 스킬 폴더 안에 함께 들어 있습니다. 카탈로그에는 짧은 설명만 올라가며, 모두 합쳐 약 3.7 KB라서 개인 스킬이 많은 환경에서도 자리를 지킵니다.
+
+- 루프와 목표: lit-loop, litgoal, litwork
+- 아이디어와 계획: lit-brainstorm, deep-interview, lit-crucible, lit-plan
+- 구현: start-work, lit-code, debugging, refactor, lit-commit, lsp, lsp-setup
+- 리뷰와 정리: 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
+- 문서와 그림: lit-docx, lit-pptx, lit-scientific-visualization, lit-diagram-drawer
+- 영상과 표지: lit-typographic-motion (짧은 영상, 키네틱 타이포, 가사 영상, 끊김 없이 도는 README 표지. 렌더한 뒤 인코딩된 파일을 그대로 검사하고 프레임을 직접 열어 봄)
+- 도구: 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 업데이트 없이 그대로 나타납니다.
+
+**상태 표시줄**: Muse의 `/hud`는 켜고 끄는 항목 목록입니다. 추천 프리셋과 테마는 [docs/hud-preset.md](./docs/hud-preset.md)에 있습니다.
+
+## 계획 턴에서 할 수 있는 일
+
+`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;
+});

package/docs/hud-preset.md

@@ -0,0 +1,34 @@
+# LitMuse /hud preset
+
+Muse Code draws its own status bar at the bottom of the screen. In Muse Code 1.4.10 the bar is a fixed list of
+nine fields that you switch on or off with `/hud`, and `/theme` picks one of seventeen color themes. Plugins
+cannot add fields or text to the bar, so LitMuse ships this preset as a recommendation that you apply by hand.
+While a lit route runs, LitMuse tells the model about it through the session context instead.
+
+<!-- TODO(cover): preview image of the bar with this preset, made by the art task -->
+
+## The preset
+
+| Field | LitMuse preset | Why |
+|---|---|---|
+| Model | on | You see which model ran the lit route. |
+| Effort | on | Reasoning effort changes cost and depth; lit-loop and lit-plan read better at medium or high. |
+| Context | on | Long lit loops fill context; the bar warns you before compaction. |
+| Branch | on | lit-commit and start-work act on the current branch. |
+| Quota | on | Shows the current usage window and week, so a long autoresearch budget stays visible. |
+| Tokens | on | Session tokens including finished subagents, useful when review-work fans out. |
+| Path | off | The prompt line already shows the workspace. |
+| Permissions | off | Muse keeps YOLO visible on its own. |
+| Cost | off | Turn it on if you pay per use and want the estimate. |
+
+Compact variant: Model, Effort and Context on, everything else off. Full variant: every field on.
+
+Theme: **Tokyo Night** on a dark terminal, **Default** on a light one. Leave "Terminal background" on auto.
+
+## Apply it
+
+1. In Muse, type `/hud`. Move with the arrow keys, press space or enter on a field to switch it, type to filter, and press esc when the list matches the table.
+2. Type `/theme`, choose the theme, and press enter to save.
+3. Inside a session you can also type `/lit-hud` to see this preset again.
+
+Muse saves both choices in its own settings. The LitMuse installer leaves those settings alone.

package/lib/approvals.mjs

@@ -0,0 +1,31 @@
+import { readManifest, agentNames, PLUGIN_DIR } from './bundle.mjs';
+
+// Id forms proven on Muse Code 1.4.10: `<plugin>:hook:<id>` and `<plugin>:agent_definition:<plugin>/<name>`.
+export function expectedApprovals(dir = PLUGIN_DIR) {
+  const hooks = readManifest(dir).capabilities.hooks.map((h) => ({
+    id: `litmuse:hook:${h.id}`, label: `hook:${h.id}`, kind: 'hook', name: h.id, what: `${h.event} hook`,
+  }));
+  const agents = agentNames(dir).map((a) => ({
+    id: `litmuse:agent_definition:litmuse/${a}`, label: `agent:${a}`, kind: 'agent', name: a, what: `agent litmuse/${a}`,
+  }));
+  return [...hooks, ...agents];
+}
+
+export function expectedApprovalIds(dir = PLUGIN_DIR) {
+  return expectedApprovals(dir).map((a) => a.id);
+}
+
+// Maps `muse plugins inspect litmuse --json` runtime capabilities onto the expected approval list.
+export function approvalStates(inspectJson, dir = PLUGIN_DIR) {
+  const caps = Array.isArray(inspectJson?.runtime_capabilities) ? inspectJson.runtime_capabilities : [];
+  const byKey = new Map();
+  for (const cap of caps) {
+    const c = cap.candidate ?? {};
+    if (c.kind === 'hook' && c.capability_id) byKey.set(`hook:${c.capability_id}`, cap);
+    if (c.scoped_definition_id) byKey.set(`agent:${String(c.scoped_definition_id).replace(/^litmuse\//, '')}`, cap);
+  }
+  return expectedApprovals(dir).map((a) => {
+    const cap = byKey.get(`${a.kind}:${a.name}`);
+    return { ...a, status: cap ? cap.status : 'missing', diagnostic: cap?.diagnostic ?? null };
+  });
+}