@litfamily/litmuse 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.6 — 2026-11-01
+
+- `lit-typographic-motion` can lay real keyed footage over a stage film. A stage declares chroma-keyed clips in `stage/clips/clips.json` (an id, a folder, a frame count and a rate), the frames are 8-bit RGBA PNGs with real transparency, and the page registers each clip once with `LitStage.clip` and calls the returned function from `render(t)`; the frame shown is a plain function of film time, so a cue is `start = cue - (N - 1) / fps` and the flash audit and determinism replay see the final pixels. A declared clip is held to its own caps (12 clips, 360 frames in one and 1500 in all, 40 MB in one and 128 MB in all, 720 px on the long side, 30 fps) and no longer trips the flipbook rule; an undeclared frame folder is still refused with exit 17. Cover mode takes no clips. The manifest and the report list each clip.
+
+## 0.1.5 — 2026-10-31
+
+- `lit-adhd` counts the other sessions and herdr agents at work before it offers this session's own next step. Before, the session that had started them was still told to type `lit continue` (a paused workflow) or `go` (its own start-work run) while they worked, and its own card showed `lit continue`. Now it says to wait for them and keeps `go` silent; a pending approval is still offered, and `lit continue` typed by hand still works.
+- LitMuse can now leave a short block of ground rules in Muse's own user rules file, `~/.config/muse/AGENTS.md`, which Muse loads at the start of every session. The hooks keep carrying the full guidance; the block only says that `lit` is LitMuse's activation word, where plans and handoffs live, that nothing is pushed, published, tagged or version-bumped without a yes, and that work counts as done after its tests pass and the changed surface was checked. It is yours to decide: an interactive install asks once (a No is remembered), `--yes` adds it, an install with no terminal and no `--yes` never writes it, `--no-agent-file` skips one run, and `litmuse config agentFile off|on` removes or restores it at once. Only the marked lines are LitMuse's; your text stays byte for byte, removing the block (or `uninstall`) returns the file as it was, and a copy of your file is saved the first time. A symbolic link, a non-UTF-8 file, a damaged marker pair or a file past Muse's 32,000-byte load limit is left alone and reported. `doctor` and `status` show the state.
+- `lit-adhd` no longer tells you to type `go` while other sessions or herdr agents are still working in this repo: it says to wait for them, or to answer the one waiting on you, and ends with "Do not type `go` until they finish." It offers `go` only for a step `go` actually runs and only for this session's own work, so an approval step or another session's run never carries it. Its handoff suggestion skips items already marked done and reads the newest handoff file. A `go` typed after the brief first checks that the step still holds, and starts nothing if it does not.
+- The hook code changed, so Muse asks you to approve the LitMuse hooks again after the update.
+- A new `ci.yml` workflow checks every push and pull request to `main`: the tests, the version, hook-digest and legacy-token checks, and the packed file list, on Node 22 and 24 with no `muse` on the runner. One `lit-adhd` test no longer fails when it runs inside a herdr pane.
+
 ## 0.1.4 — 2026-10-28
 
 - The interface check now starts its headless Chrome with a stand-in keychain, so macOS no longer pops up "keychain not found" while it runs.

package/README.md

@@ -199,14 +199,22 @@ Route state lives outside the project, under `~/.local/state/litmuse/`, so no to
 
 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).
 
+## A short block in Muse's own rules file
+
+Muse keeps one user rules file of its own, `~/.config/muse/AGENTS.md` (`$XDG_CONFIG_HOME/muse/AGENTS.md` when that is set), and loads it as user-scope rules at the start of every session, trusted workspace or not. LitMuse's hooks already carry the full guidance, so the file gets only a short block of ground rules: `lit` is LitMuse's activation word, where plans and handoffs live, never push, publish, tag or bump a version without a yes, and call work done only after the tests pass and the changed surface was checked.
+
+You decide whether it goes in. An interactive install asks once (the default is yes; a No is remembered), `--yes` adds it, and an install without a terminal and without `--yes` never writes it. `--no-agent-file` skips it for one run. `npx @litfamily/litmuse config agentFile off` removes the block at once and keeps it off; `config agentFile on` puts it back.
+
+Only the lines between `<!-- litfamily:litmuse:start … -->` and `<!-- litfamily:litmuse:end -->` are LitMuse's. Your own text stays byte for byte: removing the block returns the file exactly as it was (a file the block created is deleted again), Windows line endings are kept, and a copy of your file goes to `~/.local/share/litmuse/backups/` the first time the block goes in. A symbolic link, a non-UTF-8 file or a damaged marker pair is left alone and reported. Muse cuts a rules file after 32,000 bytes, so on a file that long the installer writes nothing and `doctor` says the block would never be read. `doctor` and `status` show the state as `present`, `stale`, `absent`, `malformed` or `off`. If you run `/rules import` in Muse and choose to overwrite the file, the block goes with it; `install` puts it back.
+
 ## 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.
+- 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. The one file it edits outside those is Muse's user rules file, and only inside its own marked block (see above).
 - 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.
+- Remove everything with `npx @litfamily/litmuse uninstall` (add `--dry-run` to preview); it takes the rules-file block out too. Plans and `.litmuse/` folders in your projects stay where they are.
 
 ## Family
 

package/README_ko-KR.md

@@ -199,14 +199,22 @@ Muse의 `/hud`는 켜고 끄는 고정 항목 목록이라서 플러그인 글
 
 Muse는 다른 코딩 도구용으로 써 둔 개인 규칙과 개인 스킬도 함께 읽습니다(사용자 규칙 파일, 개인 스킬 폴더 등). 그 규칙은 사용자 것이므로 LitMuse는 이 동작을 그대로 둡니다. 대신 세션 컨텍스트로 lit 경로마다 LitMuse 스킬을 쓰도록 안내하고, 개인 스킬 이름이 LitMuse 스킬과 같거나 다른 도구의 플러그인 폴더에서 왔으면 `doctor`가 경고합니다. 깨끗한 실행이 필요하면 `/settings`에서 "Personal rules fallback"과 "Personal skills fallback"을 끄세요. 헤드리스 실행은 `muse exec --no-foreign-personal-context`를 쓰면 됩니다(1.4.11의 대화형 `muse`는 이 플래그를 받지 않습니다).
 
+## Muse 자체 규칙 파일의 짧은 블록
+
+Muse에는 자기만의 사용자 규칙 파일 `~/.config/muse/AGENTS.md`(`$XDG_CONFIG_HOME`이 있으면 `$XDG_CONFIG_HOME/muse/AGENTS.md`)가 있고, 신뢰하는 작업 폴더인지와 상관없이 세션이 시작될 때마다 사용자 범위 규칙으로 읽습니다. 자세한 안내는 이미 LitMuse 훅이 싣고 있으므로 이 파일에는 기본 원칙만 짧은 블록으로 넣습니다. `lit`는 LitMuse의 활성화 단어라는 것, 계획과 핸드오프가 있는 곳, 사용자의 명시적인 동의 없이는 push·publish·tag·버전 올리기를 하지 않는다는 것, 테스트가 통과하고 바뀐 화면이나 동작을 실제로 확인한 뒤에만 끝났다고 말한다는 것입니다.
+
+넣을지는 사용자가 정합니다. 터미널에서 설치하면 한 번 묻고(기본값은 예, 아니요는 기억합니다), `--yes`를 주면 넣고, 터미널이 없고 `--yes`도 없는 설치는 절대 쓰지 않습니다. `--no-agent-file`은 이번 실행만 건너뜁니다. `npx @litfamily/litmuse config agentFile off`는 블록을 바로 지우고 꺼 둔 상태로 두며, `config agentFile on`은 다시 넣습니다.
+
+`<!-- litfamily:litmuse:start … -->`와 `<!-- litfamily:litmuse:end -->` 사이의 줄만 LitMuse의 것입니다. 나머지 내용은 바이트 그대로 남습니다. 블록을 지우면 파일이 원래대로 돌아오고(블록 때문에 새로 만든 파일이면 파일도 지웁니다), Windows 줄바꿈은 유지되며, 블록을 처음 넣을 때 원본 사본이 `~/.local/share/litmuse/backups/`에 한 부 저장됩니다. 심볼릭 링크, UTF-8이 아닌 파일, 짝이 맞지 않는 마커는 건드리지 않고 알려 줍니다. Muse는 규칙 파일을 32,000바이트에서 잘라 읽으므로, 그 이상 긴 파일에는 설치기가 아무것도 쓰지 않고 `doctor`가 블록이 읽히지 않는다고 알려 줍니다. `doctor`와 `status`는 상태를 `present`, `stale`, `absent`, `malformed`, `off` 중 하나로 보여 줍니다. Muse에서 `/rules import`로 파일을 덮어쓰면 블록도 함께 사라지는데, `install`을 다시 실행하면 돌아옵니다.
+
 ## 안전과 제거
 
-- 설치기는 `~/.local/share/litmuse/`에 쓰고, `muse` CLI를 거쳐 Muse의 플러그인 저장소와 설정에 씁니다. 그 전에 `~/.config/muse/settings.json`과 Muse의 `installed.json`을 백업하며, Muse 인증 파일은 열어 보지 않습니다.
+- 설치기는 `~/.local/share/litmuse/`에 쓰고, `muse` CLI를 거쳐 Muse의 플러그인 저장소와 설정에 씁니다. 그 전에 `~/.config/muse/settings.json`과 Muse의 `installed.json`을 백업하며, Muse 인증 파일은 열어 보지 않습니다. 이 밖에 손대는 파일은 Muse의 사용자 규칙 파일 하나뿐이고, 그것도 표시된 자기 블록 안에서만 씁니다(위 참고).
 - 번들 폴더가 심볼릭 링크이거나, 다른 사람의 파일이 들어 있거나, 설치 후 수정되었으면 교체를 거부합니다.
 - `~/.claude`와 `~/.codex` 아래에는 아무것도 쓰지 않으며, 테스트가 이를 고정합니다.
 - 훅은 실패해도 세션을 막지 않고 그대로 통과시킵니다.
 - 엔진 캐시는 `~/.local/share/litmuse/runtime/` 아래에 있고, 설치 상태는 `npx @litfamily/litmuse runtime status`로 봅니다. `uninstall`은 캐시를 남기므로 공간을 비우려면 그 폴더를 지우세요.
-- 전부 지우려면 `npx @litfamily/litmuse uninstall`(미리 보려면 `--dry-run`). 프로젝트 안의 계획과 `.litmuse/` 폴더는 그대로 남습니다.
+- 전부 지우려면 `npx @litfamily/litmuse uninstall`(미리 보려면 `--dry-run`). 규칙 파일의 블록도 함께 빠집니다. 프로젝트 안의 계획과 `.litmuse/` 폴더는 그대로 남습니다.
 
 ## 패밀리
 

package/bin/litmuse.mjs

@@ -11,6 +11,7 @@ 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 { agentFileState, configCommand, readAgentFileSetting } from '../lib/agent-file.mjs';
 import { buildCard, renderCard } from '../lib/stage-card.mjs';
 import { styleCommand } from '../lib/style.mjs';
 import { runRewindCli } from '../plugin/lib/rewind/collect.mjs';
@@ -25,6 +26,7 @@ Commands
   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
+  config       agentFile on|off: the short LitFamily block in Muse's user rules file (acts at once)
   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
   rewind       Cross-session brief records [--json] [--here] [--since 7d] [--max 12] [--session <id>]
@@ -37,6 +39,7 @@ Options
   --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)
+  --no-agent-file  install: leave Muse's user rules file alone for this run
   --offline    Skip the npm update check
   --discard-modified  uninstall: also remove a bundle edited after install
   --version    Print the version`;
@@ -51,6 +54,7 @@ function parse(argv) {
     else if (a === '--approve') flags.approve = true;
     else if (a === '--json') flags.json = true;
     else if (a === '--offline') flags.offline = true;
+    else if (a === '--no-agent-file') flags.noAgentFile = true;
     else if (a === '--discard-modified') flags.discardModified = true;
     else if (a === '--card') flags.card = true;
     else if (a === '--scope') flags.scope = argv[++i];
@@ -61,10 +65,11 @@ function parse(argv) {
   return { command: rest[0] ?? 'help', args: rest.slice(1), flags };
 }
 
-async function ask(question) {
+async function ask(question, { defaultYes = false } = {}) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    return /^y(es)?$/i.test((await rl.question(question)).trim());
+    const answer = (await rl.question(question)).trim();
+    return defaultYes ? !/^n/i.test(answer) : /^y(es)?$/i.test(answer);
   } finally {
     rl.close();
   }
@@ -104,6 +109,8 @@ async function main() {
     case 'hud':
       print(readFileSync(join(PACKAGE_ROOT, 'docs', 'hud-preset.md'), 'utf8'));
       return 0;
+    case 'config':
+      return configCommand(args, env, print);
     case 'style':
       return styleCommand(args, env, print);
     case 'status': {
@@ -120,6 +127,7 @@ async function main() {
         const u = await checkUpdate(env);
         if (u.latest && u.latest !== packageVersion()) print(`update: ${u.latest} available (npx @litfamily/litmuse@latest install)`);
       }
+      print(`agent file ${readAgentFileSetting(env).mode === 'off' ? 'off' : agentFileState({ path: paths(env).museRules, version: packageVersion() })}`);
       print('Run `npx @litfamily/litmuse doctor` for every check.');
       return 0;
     }

package/lib/agent-file-block.md

@@ -0,0 +1,11 @@
+## LitFamily · LitMuse
+
+LitMuse adds the lit workflows to Muse Code (lit plan, lit review, lit research, lit handoff). Its
+hooks load the full rules each session, so this block only sets the ground rules.
+
+- `lit` at the start of a prompt is LitMuse's activation word, not the Lit web library.
+- Plans live in `plans/`, handoffs in `.litmuse/handoff/latest.md`, run state in `.litmuse/`. Read them
+  before resuming work in a repo.
+- Never push, publish, tag or bump a version without the user's explicit yes for that action.
+- Call work done only after its tests pass and the changed surface was checked for real.
+- Turn this block off with `npx @litfamily/litmuse config agentFile off`.

package/lib/agent-file.mjs

@@ -0,0 +1,247 @@
+import { chmodSync, lstatSync, readdirSync, readFileSync, statSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { paths } from './paths.mjs';
+import { packageVersion } from './bundle.mjs';
+import { writeFileAtomic, copyFileAtomic } from './safe-write.mjs';
+import { inspectBlock, ManagedBlockError, removeBlock, upsertBlock } from './managed-block.mjs';
+
+// The short LitFamily block in Muse's own user rules file, `$XDG_CONFIG_HOME/muse/AGENTS.md`. Muse loads that
+// file as user-scope rules in every session (probed on 1.4.14), so it is the one place a global ground rule
+// can live without writing into another tool's home. The on/off choice is `agentFile` in LitMuse's own
+// config.json; LITMUSE_AGENT_FILE overrides it for a run.
+
+export const AGENT_FILE_ID = 'litmuse';
+export const AGENT_FILE_MODES = Object.freeze(['on', 'off']);
+// The block is read at the start of every session, so it stays small.
+export const AGENT_FILE_MAX_BYTES = 1200;
+// Muse cuts a rules file after this many bytes (its startup context limit), so a block past it is never read.
+export const MUSE_LOAD_LIMIT = 32000;
+
+const BLOCK_FILE = join(dirname(fileURLToPath(import.meta.url)), 'agent-file-block.md');
+const CONFIG_CMD = 'npx @litfamily/litmuse config agentFile';
+const QUESTION = 'Add the short LitFamily block to your Muse user rules file? Your own text stays as it is. [Y/n] ';
+
+export const agentFileBody = () => readFileSync(BLOCK_FILE, 'utf8');
+
+function readConfig(env) {
+  try {
+    const file = paths(env).config;
+    if (lstatSync(file).isSymbolicLink()) return {};
+    return JSON.parse(readFileSync(file, 'utf8')) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/** `{mode, stored}`: `mode` is what acts (LITMUSE_AGENT_FILE, else the stored value, else on); `stored` is only what the user chose. */
+export function readAgentFileSetting(env = process.env) {
+  const stored = readConfig(env).agentFile;
+  const choice = AGENT_FILE_MODES.includes(stored) ? stored : undefined;
+  const override = String(env.LITMUSE_AGENT_FILE ?? '').trim().toLowerCase();
+  return { mode: AGENT_FILE_MODES.includes(override) ? override : (choice ?? 'on'), stored: choice };
+}
+
+export function writeAgentFileSetting(env, mode) {
+  if (!AGENT_FILE_MODES.includes(mode)) throw new Error(`agentFile takes one of: ${AGENT_FILE_MODES.join(', ')}`);
+  writeFileAtomic(paths(env).config, `${JSON.stringify({ ...readConfig(env), agentFile: mode }, null, 2)}\n`);
+}
+
+// 'missing', 'file', 'symlink' or 'other', without following a link.
+function entryKind(path) {
+  try {
+    const st = lstatSync(path);
+    return st.isSymbolicLink() ? 'symlink' : st.isFile() ? 'file' : 'other';
+  } catch (e) {
+    if (e.code === 'ENOENT') return 'missing';
+    throw e;
+  }
+}
+
+// The file's text, or null when it is not UTF-8 (UTF-16 from a Windows editor, Latin-1): rewriting those would
+// corrupt the user's bytes outside the markers.
+function readUtf8(path) {
+  const bytes = readFileSync(path);
+  if (bytes.includes(0) || (bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff)) return null;
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
+const reaches = (text, end) => Buffer.byteLength(text.slice(0, end));
+
+/**
+ * Installs or removes the block in `path`. Returns `{status, path, backup?, preview?, error?}` with status
+ * created | updated | unchanged | removed | absent | dry-run | refused-symlink | refused-not-file |
+ * refused-not-utf8 | refused-malformed | refused-too-large | refused-io. The user's file is copied into
+ * `backupDir` when the block first goes in, unless an identical copy is already there.
+ */
+export function applyAgentFile({ path, id = AGENT_FILE_ID, version, body = agentFileBody(), action, dryRun = false, now = new Date(), backupDir }) {
+  try {
+    const kind = entryKind(path);
+    if (kind === 'symlink') return { status: 'refused-symlink', path };
+    if (kind === 'other') return { status: 'refused-not-file', path };
+    const text = kind === 'file' ? readUtf8(path) : '';
+    if (text === null) return { status: 'refused-not-utf8', path };
+    let next;
+    try {
+      next = action === 'uninstall' ? removeBlock(text, id) : upsertBlock(text, { id, version, body }, { created: kind === 'missing' });
+    } catch (e) {
+      if (e instanceof ManagedBlockError) return { status: 'refused-malformed', path };
+      throw e;
+    }
+    if (!next.changed) return { status: action === 'uninstall' ? 'absent' : 'unchanged', path };
+    if (action !== 'uninstall' && reaches(next.text, inspectBlock(next.text, id).end) > MUSE_LOAD_LIMIT) return { status: 'refused-too-large', path };
+    if (dryRun) return { status: 'dry-run', path, preview: next.text };
+    if (action === 'uninstall') {
+      if (next.text === '' && next.created) unlinkSync(path);
+      else rewrite(path, next.text);
+      return { status: 'removed', path };
+    }
+    let backup;
+    if (backupDir && kind === 'file' && inspectBlock(text, id).state === 'absent' && !alreadySaved(backupDir, text)) {
+      backup = join(backupDir, `AGENTS.md.${now.toISOString().replace(/[:.]/g, '-')}.bak`);
+      copyFileAtomic(path, backup);
+    }
+    rewrite(path, next.text);
+    return { status: kind === 'file' ? 'updated' : 'created', path, ...(backup ? { backup } : {}) };
+  } catch (e) {
+    return { status: 'refused-io', path, error: e?.code ?? e?.message };
+  }
+}
+
+// True when `backupDir` already holds a copy of exactly this text, so turning the block off and on again
+// does not pile up identical copies.
+function alreadySaved(backupDir, text) {
+  try {
+    return readdirSync(backupDir).some((name) => /^AGENTS\.md\..*\.bak$/u.test(name) && readUtf8(join(backupDir, name)) === text);
+  } catch {
+    return false;
+  }
+}
+
+// Replaces the file through a temporary one and keeps its permissions.
+function rewrite(path, text) {
+  let mode = null;
+  try {
+    mode = statSync(path).mode & 0o7777;
+  } catch {
+    // A new file takes the default mode.
+  }
+  writeFileAtomic(path, text);
+  if (mode !== null) chmodSync(path, mode);
+}
+
+/**
+ * `present v=<x>` (current), `stale v=<x>` (an older install's block), `truncated v=<x>` (the block sits past
+ * Muse's load limit), `absent`, `malformed`, or `symlink` / `not-file` / `not-utf8` for a file LitMuse will not write.
+ */
+export function agentFileState({ path, id = AGENT_FILE_ID, version }) {
+  const kind = entryKind(path);
+  if (kind === 'missing') return 'absent';
+  if (kind === 'symlink') return 'symlink';
+  if (kind === 'other') return 'not-file';
+  const text = readUtf8(path);
+  if (text === null) return 'not-utf8';
+  const found = inspectBlock(text, id);
+  if (found.state !== 'present') return found.state;
+  if (reaches(text, found.end) > MUSE_LOAD_LIMIT) return `truncated v=${found.version}`;
+  return `${found.version === version ? 'present' : 'stale'} v=${found.version}`;
+}
+
+export const agentFileLine = (r) => `AGENT_FILE: ${r.status} ${r.path}${r.backup ? ` (backup: ${r.backup})` : ''}${r.error ? ` (${r.error})` : ''}`;
+
+/** The install plan line for the block, shown before anything is written. */
+export function agentFilePlan({ env, flags }) {
+  const path = paths(env).museRules;
+  if (flags.noAgentFile || readAgentFileSetting(env).mode === 'off') return `off (${path} left as it is)`;
+  return `Would add the LitFamily block to ${path} (asks first; --yes adds it, --no-agent-file skips)`;
+}
+
+/** The install step: adds or refreshes the block when the setting and the user's answer allow it. Returns the paths it wrote. */
+export async function installAgentFile({ env, flags, interactive, ask, print, version, backupDir }) {
+  const path = paths(env).museRules;
+  const { mode, stored } = readAgentFileSetting(env);
+  if (flags.noAgentFile) {
+    print(`AGENT_FILE: skipped (this run only; ${path} left as it is)`);
+    return [];
+  }
+  if (mode === 'off') {
+    print(`AGENT_FILE: off (${path} left as it is; turn on: ${CONFIG_CMD} on)`);
+    return [];
+  }
+  const state = agentFileState({ path, version });
+  // A linked, non-file or non-UTF-8 rules file is never written, so asking about it would only mislead.
+  if (['symlink', 'not-file', 'not-utf8'].includes(state)) {
+    print(`AGENT_FILE: ${state} ${path}; left as it is`);
+    return [];
+  }
+  if (state === 'absent' && !flags.yes && stored !== 'on') {
+    if (!interactive || !ask) {
+      print(`AGENT_FILE: skipped (add the LitFamily block to ${path}: ${CONFIG_CMD} on)`);
+      return [];
+    }
+    if (!(await ask(QUESTION, { defaultYes: true }))) {
+      writeAgentFileSetting(env, 'off');
+      print(`AGENT_FILE: off (turn on later: ${CONFIG_CMD} on)`);
+      return [];
+    }
+  }
+  const result = applyAgentFile({ path, version, action: 'install', backupDir });
+  print(agentFileLine(result));
+  return ['created', 'updated'].includes(result.status) ? [path] : [];
+}
+
+/** The doctor row for the block. */
+export function agentFileRow({ env, version }) {
+  const path = paths(env).museRules;
+  const { mode } = readAgentFileSetting(env);
+  const label = 'agent file';
+  if (mode === 'off') return { status: 'INFO', label, detail: `off (${path} left as it is)`, fix: `${CONFIG_CMD} on` };
+  const state = agentFileState({ path, version });
+  if (state.startsWith('present')) return { status: 'PASS', label, detail: `${state} (${path})` };
+  if (state.startsWith('stale')) return { status: 'WARN', label, detail: `${state} (${path}); run npx @litfamily/litmuse install to refresh it` };
+  if (state.startsWith('truncated')) return { status: 'WARN', label, detail: `${state} (${path}); Muse cuts a rules file after ${MUSE_LOAD_LIMIT} bytes, so Muse never reads the block; trim the file above it` };
+  if (state === 'absent') return { status: 'INFO', label, detail: `absent (${path})`, fix: `${CONFIG_CMD} on` };
+  return { status: 'WARN', label, detail: `${state} (${path}); LitMuse leaves the file as it is` };
+}
+
+/** `litmuse config [agentFile on|off]`; returns the exit code. */
+export function configCommand(args, env = process.env, print = console.log) {
+  const [key, value, ...extra] = args;
+  const p = paths(env);
+  const version = packageVersion();
+  if (!key) {
+    print(`agentFile ${readAgentFileSetting(env).mode.padEnd(3)} (${AGENT_FILE_MODES.join(', ')})`);
+    print(`Change it with: litmuse config agentFile <${AGENT_FILE_MODES.join('|')}>. It acts at once on ${p.museRules}.`);
+    return 0;
+  }
+  if (key !== 'agentFile') {
+    print(`Unknown option: ${key}. Options: agentFile`);
+    return 2;
+  }
+  const mode = String(value ?? '').trim().toLowerCase();
+  if (!AGENT_FILE_MODES.includes(mode) || extra.length) {
+    print(`agentFile takes one of: ${AGENT_FILE_MODES.join(', ')}`);
+    return 2;
+  }
+  try {
+    writeAgentFileSetting(env, mode);
+  } catch (e) {
+    print(`litmuse: could not save the setting: ${e.message}`);
+    return 1;
+  }
+  const result = applyAgentFile({ path: p.museRules, version, action: mode === 'off' ? 'uninstall' : 'install', backupDir: p.backups });
+  print(`AGENT_FILE: ${mode}`);
+  print(agentFileLine(result));
+  return result.status.startsWith('refused') ? 1 : 0;
+}
+
+/** Removes the block for `uninstall`; returns the line to print. */
+export function removeAgentFile({ env, version, dryRun }) {
+  const path = paths(env).museRules;
+  const result = applyAgentFile({ path, version, action: 'uninstall', dryRun });
+  return result.status === 'dry-run' ? `Would remove the LitFamily block from ${path} (your own text stays)` : agentFileLine(result);
+}

package/lib/doctor.mjs

@@ -8,6 +8,7 @@ import { stageState, packageVersion, PLUGIN_DIR } from './bundle.mjs';
 import { approvalStates } from './approvals.mjs';
 import { checkUpdate } from './update-check.mjs';
 import { runtimeModules, callRuntime } from './runtime.mjs';
+import { agentFileRow } from './agent-file.mjs';
 
 const CATALOG_CAP = 32 * 1024;
 
@@ -120,6 +121,9 @@ export async function doctor({ env = process.env, flags = {}, print = console.lo
     }
   }
 
+  const rules = agentFileRow({ env, version: packageVersion() });
+  add(rules.status, rules.label, rules.detail, rules.fix);
+
   if (existsSync(p.foreignRules)) {
     add('INFO', 'foreign rules', '~/.claude/CLAUDE.md is loaded by Muse as personal rules (Muse setting "Personal rules fallback"); LitMuse leaves it on and steers lit routes through its SessionStart context');
   }

package/lib/install.mjs

@@ -5,6 +5,7 @@ import { preflightDestinations, writeFileAtomic, copyFileAtomic } from './safe-w
 import { muse, museVersion, installedPlugin } from './muse.mjs';
 import { stageState, stageBundle, packageVersion } from './bundle.mjs';
 import { expectedApprovals, approvalStates } from './approvals.mjs';
+import { agentFilePlan, installAgentFile } from './agent-file.mjs';
 
 function remedy(state, detail, p) {
   const saved = `${p.stage}.saved-${new Date().toISOString().slice(0, 10)}`;
@@ -80,6 +81,7 @@ export async function install({ env = process.env, flags = {}, interactive = fal
   print(`  bundle      ${p.stage}${st.state === 'owned' ? ` (replaces LitMuse ${st.version})` : ''}`);
   print(`  backups     ${p.backups} (Muse settings.json and installed.json, when present)`);
   print(`  receipt     ${p.receipt}`);
+  print(`  rules file  ${agentFilePlan({ env, flags })}`);
   print(`  muse        muse ${installArgs.join(' ')}`);
   print(`  approvals   up to ${approvals.length} capabilities may need your approval in Muse (hooks and agents):`);
   for (const a of approvals) print(`    ${a.id}`);
@@ -150,6 +152,9 @@ export async function install({ env = process.env, flags = {}, interactive = fal
     }
   }
 
+  print('');
+  written.push(...await installAgentFile({ env, flags, interactive, ask, print, version, backupDir: p.backups }));
+
   const left = states.filter((s) => s.status !== 'trusted_enabled').length;
   writeFileAtomic(p.receipt, `${JSON.stringify({
     product: 'litmuse', version, scope, installedAt: new Date().toISOString(), host: mv,

package/lib/managed-block.mjs

@@ -0,0 +1,78 @@
+// A LitFamily block inside a file the user owns: the lines from `<!-- litfamily:<id>:start v=<version> -->`
+// to `<!-- litfamily:<id>:end -->`. Only those lines are written; everything before and after stays byte for
+// byte. The start marker also records what was put in front of the block (`pre=`, hex) and whether the
+// file was made for the block (`new=1`), so removal takes back exactly that and add-then-remove restores
+// the original bytes under either line ending. A start without its end, or a repeated marker, is
+// malformed: it is reported and refused, never repaired by guesswork.
+
+export class ManagedBlockError extends Error {}
+
+const startPrefix = (id) => `<!-- litfamily:${id}:start`;
+const endMarker = (id) => `<!-- litfamily:${id}:end -->`;
+const START_LINE = /^<!-- litfamily:[^:\s]+:start v=(\S+)((?: [a-z]+=[0-9a-f]*)*) -->/u;
+
+function indexesOf(text, needle) {
+  const at = [];
+  for (let i = text.indexOf(needle); i !== -1; i = text.indexOf(needle, i + needle.length)) at.push(i);
+  return at;
+}
+
+// The block's span `[start, end)` with its recorded attributes, or null when the file has none.
+function locate(text, id) {
+  const starts = indexesOf(text, startPrefix(id));
+  const ends = indexesOf(text, endMarker(id));
+  if (!starts.length && !ends.length) return null;
+  if (starts.length !== 1 || ends.length !== 1 || ends[0] < starts[0]) {
+    throw new ManagedBlockError(`malformed LitFamily ${id} block: expected one start and one end marker`);
+  }
+  const head = START_LINE.exec(text.slice(starts[0]));
+  if (!head) throw new ManagedBlockError(`malformed LitFamily ${id} block: unreadable start marker`);
+  const attrs = Object.fromEntries(head[2].trim().split(' ').filter(Boolean).map((pair) => pair.split('=')));
+  return {
+    start: starts[0],
+    end: ends[0] + endMarker(id).length,
+    version: head[1],
+    pre: attrs.pre ? Buffer.from(attrs.pre, 'hex').toString('utf8') : '',
+    created: attrs.new === '1',
+  };
+}
+
+function render({ id, version, body }, eol, { pre, created }) {
+  const attrs = `${pre ? ` pre=${Buffer.from(pre, 'utf8').toString('hex')}` : ''}${created ? ' new=1' : ''}`;
+  const lines = String(body).replace(/\r?\n$/u, '').split(/\r?\n/u);
+  return [`${startPrefix(id)} v=${version}${attrs} -->`, ...lines, endMarker(id)].join(eol);
+}
+
+/** `{state: 'absent' | 'present' | 'malformed', version, created, end}` for block `id` in `text`; `end` is the index just past its end marker. */
+export function inspectBlock(text, id) {
+  try {
+    const span = locate(text, id);
+    return span ? { state: 'present', version: span.version, created: span.created, end: span.end } : { state: 'absent', version: null, created: false, end: null };
+  } catch {
+    return { state: 'malformed', version: null, created: false, end: null };
+  }
+}
+
+/** Adds block `block` or replaces the one there; `created` marks a file made for it. Returns `{text, changed}`. */
+export function upsertBlock(text, block, { created = false } = {}) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const span = locate(text, block.id);
+  if (span) {
+    const next = `${text.slice(0, span.start)}${render(block, eol, span)}${text.slice(span.end)}`;
+    return { text: next, changed: next !== text };
+  }
+  const pre = text === '' ? '' : `${text.endsWith('\n') ? '' : eol}${eol}`;
+  return { text: `${text}${pre}${render(block, eol, { pre, created })}${eol}`, changed: true };
+}
+
+/** Removes block `id`, the line ending after it and whatever was put before it. `created` comes from its marker. */
+export function removeBlock(text, id) {
+  const span = locate(text, id);
+  if (!span) return { text, changed: false, created: false };
+  let before = text.slice(0, span.start);
+  let after = text.slice(span.end);
+  const eol = after.startsWith('\r\n') ? '\r\n' : after.startsWith('\n') ? '\n' : '';
+  after = after.slice(eol.length);
+  if (span.pre && before.endsWith(span.pre)) before = before.slice(0, -span.pre.length);
+  return { text: `${before}${after}`, changed: true, created: span.created };
+}

package/lib/paths.mjs

@@ -14,7 +14,9 @@ export function paths(env = process.env) {
     backups: join(data, 'backups'),
     receipt: join(data, 'receipt.json'),
     updateCache: join(data, 'update-check.json'),
+    config: join(data, 'config.json'),
     museSettings: join(configHome, 'muse', 'settings.json'),
+    museRules: join(configHome, 'muse', 'AGENTS.md'),
     museInstalled: join(dataHome, 'muse', 'plugins', 'installed.json'),
     museCatalogDir: join(dataHome, 'muse', 'model-catalog'),
     foreignRules: join(home, '.claude', 'CLAUDE.md'),

package/lib/safe-write.mjs

@@ -21,7 +21,7 @@ function realExistingAncestor(p) {
 export function preflightDestinations(p) {
   const checks = [
     [p.data, 'directory'], [p.stage, 'directory'], [p.backups, 'directory'],
-    [p.receipt, 'file'], [p.updateCache, 'file'],
+    [p.receipt, 'file'], [p.updateCache, 'file'], [p.config, 'file'],
   ];
   for (const [target, kind] of checks) {
     const st = lstatOrNull(target);

package/lib/uninstall.mjs

@@ -3,6 +3,8 @@ import { paths } from './paths.mjs';
 import { muse, installedPlugin } from './muse.mjs';
 import { stageState } from './bundle.mjs';
 import { assertSafeWritePath } from './guard.mjs';
+import { removeAgentFile } from './agent-file.mjs';
+import { packageVersion } from './bundle.mjs';
 
 export async function uninstall({ env = process.env, flags = {}, interactive = false, print = console.log }) {
   const p = paths(env);
@@ -18,6 +20,7 @@ export async function uninstall({ env = process.env, flags = {}, interactive = f
   if (st.state === 'modified' && !discard) print('  hint          add --discard-modified to remove the edited bundle too');
   print(`  kept          ${p.backups} and ${p.receipt}`);
   if (flags.dryRun) {
+    print(removeAgentFile({ env, version: packageVersion(), dryRun: true }));
     print('Dry run: nothing removed.');
     return 0;
   }
@@ -37,6 +40,7 @@ export async function uninstall({ env = process.env, flags = {}, interactive = f
     rmSync(assertSafeWritePath(p.stage), { recursive: true, force: true });
     print(`Removed ${p.stage}.`);
   }
+  print(removeAgentFile({ env, version: packageVersion() }));
   print('Project files LitMuse sessions wrote (plans/, .litmuse/) stay in each project.');
   return 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litmuse",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Installer for LitMuse: skills, hooks and agents that help Meta's Muse Code plan, build, check and hand off work.",
   "keywords": [
     "muse",

package/plugin/.muse-plugin/plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "name": "litmuse",
   "displayName": "LitMuse",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "LitFamily workflows for Muse Code: bare lit activation, planning, evidence-bound execution, review, research, handoff and Korean prose care.",
   "compat": {
     "source": "native",
@@ -262,7 +262,7 @@
           "node",
           "hooks/user-prompt-submit.mjs",
           "--digest",
-          "17cbcfe331b17df6"
+          "dbfd31cd0446cd80"
         ],
         "timeoutMs": 5000,
         "statusMessage": "LitMuse route check"