@litfamily/litclaude 1.0.21 → 1.0.22

package/bin/icon-font.mjs

@@ -0,0 +1,264 @@
+// Opt-in icon font for the LIT band: the symbols-only Nerd Font (Symbols Nerd Font Mono, MIT), so the
+// band can draw its rounded pill caps (U+E0B6, U+E0B4) and icons while the person keeps their own
+// terminal font. The font is not bundled: install downloads one pinned official release archive,
+// refuses it unless its SHA-256 matches, takes the two pinned files out of it (each checked again),
+// and writes them into the per-user font folder only. A manifest of what was written lets
+// uninstall remove exactly those files and leave any copy the person installed alone.
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { linkSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+export const ICON_FONT = Object.freeze({
+  family: "Symbols Nerd Font Mono",
+  release: "v3.5.1",
+  url: "https://github.com/ryanoasis/nerd-fonts/releases/download/v3.5.1/NerdFontsSymbolsOnly.zip",
+  archiveSha256: "fdca3682534f6f65e1ccb2345b0362ccf67d9b8eca7c8025330946e93e2473bc",
+  archiveMaxBytes: 8 * 1024 * 1024,
+  files: Object.freeze([
+    Object.freeze({ entry: "SymbolsNerdFontMono-Regular.ttf", name: "SymbolsNerdFontMono-Regular.ttf", sha256: "fe471e538392f51910faab985fa8e192a39dd3426125edd15b71b3680df0e749", kind: "font" }),
+    Object.freeze({ entry: "LICENSE", name: "SymbolsNerdFontMono-LICENSE.txt", sha256: "84a7a98c82140fb12c37fe42b93805baa16024cb3e5acc599b7ffe612c55d847", kind: "license" }),
+  ]),
+});
+
+// Font file names the LIT band treats as "the icon font is installed": this one, and the
+// proportional symbols font a person may have installed some other way.
+export const ICON_FONT_FILE_NAMES = Object.freeze(["SymbolsNerdFontMono-Regular.ttf", "SymbolsNerdFont-Regular.ttf"]);
+
+export const ICON_FONT_QUESTION = "Install the icon font for LitClaude's status band? (y/N) ";
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+export class IconFontError extends Error {}
+
+/** The per-user font folder, or null where installing one safely is not supported (Windows). */
+export const iconFontDir = ({ platform = process.platform, env = process.env, home }) => {
+  if (platform === "darwin") return join(home, "Library", "Fonts");
+  if (platform === "win32") return null;
+  return join(env.XDG_DATA_HOME?.trim() || join(home, ".local", "share"), "fonts");
+};
+
+export const iconFontManifestPath = (litHome) => join(litHome, "icon-font", "manifest.json");
+
+export const parseYesNo = (answer) => /^\s*y(?:es)?\s*$/iu.test(String(answer ?? ""));
+
+const readU16 = (buffer, offset) => buffer.readUInt16LE(offset);
+const readU32 = (buffer, offset) => buffer.readUInt32LE(offset);
+
+/**
+ * Reads the named entries out of a zip archive held in memory (stored or deflated, no zip64), by
+ * its central directory. Returns a Map of entry name to bytes; a missing entry is simply absent.
+ */
+export const extractZipEntries = (archive, names) => {
+  const wanted = new Set(names);
+  const found = new Map();
+  let end = -1;
+  for (let offset = archive.length - 22; offset >= Math.max(0, archive.length - 22 - 65_535); offset -= 1) {
+    if (readU32(archive, offset) === 0x06054b50) {
+      end = offset;
+      break;
+    }
+  }
+  if (end < 0) throw new IconFontError("the archive is not a zip file");
+  const count = readU16(archive, end + 10);
+  let offset = readU32(archive, end + 16);
+  for (let index = 0; index < count; index += 1) {
+    if (readU32(archive, offset) !== 0x02014b50) throw new IconFontError("the archive's directory is damaged");
+    const method = readU16(archive, offset + 10);
+    const compressedSize = readU32(archive, offset + 20);
+    const nameLength = readU16(archive, offset + 28);
+    const extraLength = readU16(archive, offset + 30);
+    const commentLength = readU16(archive, offset + 32);
+    const localOffset = readU32(archive, offset + 42);
+    const name = archive.subarray(offset + 46, offset + 46 + nameLength).toString("utf8");
+    offset += 46 + nameLength + extraLength + commentLength;
+    if (!wanted.has(name)) continue;
+    if (readU32(archive, localOffset) !== 0x04034b50) throw new IconFontError(`the archive entry ${name} is damaged`);
+    const dataStart = localOffset + 30 + readU16(archive, localOffset + 26) + readU16(archive, localOffset + 28);
+    const data = archive.subarray(dataStart, dataStart + compressedSize);
+    if (method === 0) found.set(name, Buffer.from(data));
+    else if (method === 8) found.set(name, inflateRawSync(data));
+    else throw new IconFontError(`the archive entry ${name} uses an unsupported compression method`);
+  }
+  return found;
+};
+
+/**
+ * The pinned archive's bytes: a local copy named by LITCLAUDE_ICON_FONT_SOURCE (for offline
+ * installs), else the official release download. Either way it is refused unless its size is
+ * under the cap and its SHA-256 is the pinned one.
+ */
+export const loadIconFontArchive = async ({ env = process.env, pins = ICON_FONT, fetchImpl = globalThis.fetch } = {}) => {
+  let bytes;
+  const local = env.LITCLAUDE_ICON_FONT_SOURCE?.trim();
+  if (local) {
+    const stat = lstatSync(local);
+    if (!stat.isFile() || stat.size > pins.archiveMaxBytes) throw new IconFontError(`${local} is not a regular file under ${pins.archiveMaxBytes} bytes`);
+    bytes = readFileSync(local);
+  } else {
+    if (typeof fetchImpl !== "function") throw new IconFontError("this Node.js has no fetch; download the archive and set LITCLAUDE_ICON_FONT_SOURCE");
+    const response = await fetchImpl(pins.url, { redirect: "follow", signal: AbortSignal.timeout(60_000) });
+    if (!response.ok) throw new IconFontError(`the download answered HTTP ${response.status}`);
+    const declared = Number(response.headers?.get?.("content-length") ?? 0);
+    if (declared > pins.archiveMaxBytes) throw new IconFontError("the download is larger than the pinned archive");
+    bytes = Buffer.from(await response.arrayBuffer());
+  }
+  if (bytes.length > pins.archiveMaxBytes) throw new IconFontError("the archive is larger than the pinned archive");
+  const actual = sha256(bytes);
+  if (actual !== pins.archiveSha256) throw new IconFontError(`the archive's SHA-256 is ${actual}, not the pinned ${pins.archiveSha256}; nothing was installed`);
+  return bytes;
+};
+
+const lstatOrNull = (path) => {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+};
+
+// What sits at a destination now: nothing, the exact pinned file, a different file, or something
+// that is not a regular file (a link, a folder), which is never written through or over.
+const destinationState = (path, expectedSha) => {
+  const stat = lstatOrNull(path);
+  if (!stat) return "absent";
+  if (stat.isSymbolicLink() || !stat.isFile()) return "not-a-file";
+  return sha256(readFileSync(path)) === expectedSha ? "same" : "different";
+};
+
+export const planIconFontInstall = ({ platform = process.platform, env = process.env, home, pins = ICON_FONT }) => {
+  const dir = iconFontDir({ platform, env, home });
+  if (!dir) return { supported: false, dir: null, files: [] };
+  return {
+    supported: true,
+    dir,
+    files: pins.files.map((file) => {
+      const path = join(dir, file.name);
+      return { ...file, path, state: destinationState(path, file.sha256) };
+    }),
+  };
+};
+
+const readManifest = (litHome) => {
+  try {
+    const manifest = JSON.parse(readFileSync(iconFontManifestPath(litHome), "utf8"));
+    return Array.isArray(manifest?.files) ? manifest : null;
+  } catch {
+    return null;
+  }
+};
+
+const writeManifest = (litHome, manifest) => {
+  const path = iconFontManifestPath(litHome);
+  mkdirSync(dirname(path), { recursive: true });
+  const staging = `${path}.${process.pid}.tmp`;
+  writeFileSync(staging, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  renameSync(staging, path);
+};
+
+// Writes a new file without ever replacing one: the bytes go to a fresh temporary name in the same
+// folder, then a hard link claims the destination, which fails if anything appeared there.
+const writeNewFile = (path, bytes) => {
+  const staging = `${path}.litclaude-${process.pid}.tmp`;
+  writeFileSync(staging, bytes, { flag: "wx", mode: 0o644 });
+  try {
+    linkSync(staging, path);
+  } finally {
+    unlinkSync(staging);
+  }
+};
+
+/**
+ * Installs the pinned files from a verified archive into the per-user font folder. A destination
+ * that already holds the pinned bytes is left as it is (and recorded as LitClaude's only if an
+ * earlier LitClaude install wrote it); a different file or a link is never overwritten.
+ */
+export const installIconFont = ({ archive, platform = process.platform, env = process.env, home, litHome, pins = ICON_FONT, spawn = spawnSync, now = () => new Date() }) => {
+  const plan = planIconFontInstall({ platform, env, home, pins });
+  if (!plan.supported) return { status: "unsupported", installed: [], present: [], skipped: [] };
+  const entries = extractZipEntries(archive, pins.files.map(({ entry }) => entry));
+  const previous = readManifest(litHome)?.files ?? [];
+  const owned = [];
+  const installed = [];
+  const present = [];
+  const skipped = [];
+  for (const file of plan.files) {
+    const bytes = entries.get(file.entry);
+    if (!bytes) throw new IconFontError(`the archive has no ${file.entry}; nothing was installed`);
+    if (sha256(bytes) !== file.sha256) throw new IconFontError(`${file.entry} in the archive does not match its pinned SHA-256; nothing was installed`);
+  }
+  mkdirSync(plan.dir, { recursive: true });
+  for (const file of plan.files) {
+    if (file.state === "absent") {
+      writeNewFile(file.path, entries.get(file.entry));
+      installed.push(file.path);
+      owned.push({ path: file.path, sha256: file.sha256, kind: file.kind });
+    } else if (file.state === "same") {
+      present.push(file.path);
+      if (previous.some((entry) => entry.path === file.path && entry.sha256 === file.sha256)) owned.push({ path: file.path, sha256: file.sha256, kind: file.kind });
+    } else {
+      skipped.push({ path: file.path, reason: file.state === "different" ? "a different file is already there" : "something other than a regular file is there" });
+    }
+  }
+  if (owned.length > 0) writeManifest(litHome, { family: pins.family, release: pins.release, installedAt: now().toISOString(), files: owned });
+  let fontCache = null;
+  if (platform !== "darwin" && installed.length > 0) {
+    const result = spawn("fc-cache", ["-f", plan.dir], { encoding: "utf8", timeout: 60_000 });
+    fontCache = result.error?.code === "ENOENT" ? "fc-cache not found" : result.status === 0 ? "refreshed" : "fc-cache failed";
+  }
+  return { status: installed.length > 0 ? "installed" : skipped.length > 0 && present.length === 0 ? "skipped" : "present", dir: plan.dir, installed, present, skipped, fontCache };
+};
+
+/** Removes only the files the manifest records, and only while they still hold the recorded bytes. */
+export const uninstallIconFont = ({ litHome, dryRun = false }) => {
+  const manifest = readManifest(litHome);
+  if (!manifest) return { removed: [], kept: [] };
+  const removed = [];
+  const kept = [];
+  for (const file of manifest.files) {
+    const state = destinationState(file.path, file.sha256);
+    if (state === "same") {
+      if (!dryRun) rmSync(file.path, { force: true });
+      removed.push(file.path);
+    } else if (state !== "absent") {
+      kept.push({ path: file.path, reason: state === "different" ? "its bytes changed since LitClaude wrote it" : "it is no longer a regular file" });
+    }
+  }
+  if (!dryRun) rmSync(dirname(iconFontManifestPath(litHome)), { recursive: true, force: true });
+  return { removed, kept };
+};
+
+/** Whether the icon font is installed for this user, and whether LitClaude wrote it. */
+export const iconFontStatus = ({ platform = process.platform, env = process.env, home, litHome }) => {
+  const dir = iconFontDir({ platform, env, home });
+  if (!dir) return { supported: false, present: false, path: null, managed: false };
+  const managedPaths = new Set((readManifest(litHome)?.files ?? []).map(({ path }) => path));
+  for (const name of ICON_FONT_FILE_NAMES) {
+    const path = join(dir, name);
+    const stat = lstatOrNull(path);
+    if (stat?.isFile()) return { supported: true, present: true, path, managed: managedPaths.has(path) };
+  }
+  return { supported: true, present: false, path: join(dir, ICON_FONT.files[0].name), managed: false };
+};
+
+/**
+ * One line on pointing the terminal at the font, for the terminal named by TERM_PROGRAM (kitty by
+ * TERM). It is only needed when the terminal's own fallback does not pick the font up; nothing here
+ * changes a terminal's settings.
+ */
+export const terminalFontHint = (env = process.env, family = ICON_FONT.family) => {
+  const program = env.TERM_PROGRAM ?? "";
+  if (program === "iTerm.app") return `iTerm2: only if icons show as boxes, set Settings > Profiles > Text > Non-ASCII Font to ${family}.`;
+  if (program === "Apple_Terminal") return `Terminal.app: macOS font fallback usually finds ${family}; if icons show as boxes, pick a Nerd Font in Settings > Profiles > Text.`;
+  if (program === "vscode") return `VS Code: only if icons show as boxes, add it to terminal.integrated.fontFamily, for example "Menlo, '${family}'".`;
+  if (program === "ghostty") return `Ghostty: Nerd Font symbols are built in; if icons still show as boxes, add font-family = ${family} after your font in its config.`;
+  if (program === "WezTerm") return `WezTerm: Nerd Font symbols are built in; if icons still show as boxes, add '${family}' to config.font = wezterm.font_with_fallback { ... }.`;
+  if (env.TERM === "xterm-kitty" || env.KITTY_WINDOW_ID) return `kitty: only if icons show as boxes, add "symbol_map U+E000-U+F8FF ${family}" to kitty.conf.`;
+  return `Terminal: only if icons show as boxes, add ${family} as a fallback font in your terminal's font settings.`;
+};
+
+/** What to tell a Windows user, where LitClaude does not register fonts itself. */
+export const windowsIconFontInstructions = (pins = ICON_FONT) =>
+  `Windows: LitClaude does not register fonts itself. Download ${pins.url}, check its SHA-256 is ${pins.archiveSha256}, then right-click SymbolsNerdFontMono-Regular.ttf and choose "Install for me".`;

package/bin/litclaude-ai.js

@@ -46,6 +46,18 @@ import { resolveProjectStateRoot } from "../plugins/litclaude/lib/project-state-
 import { runUpdateNotifier } from "./update-notifier.mjs";
 import { assertInstallPath, assertOwnedTree, assertCurrentPointer, assertOwnedRegistrations, migrateLegacyVendorPaths, planModifiedLegacySkill, preserveModifiedLegacySkill, registeredPluginInstallation, writeOwnershipReceipt, removeEmptyDirectory } from "./install-ownership.mjs";
 import { banner, lockup, colorMode, supportsBlocks, terminalRows } from "./litfamily-banner.mjs";
+import {
+  ICON_FONT,
+  ICON_FONT_QUESTION,
+  iconFontStatus,
+  installIconFont,
+  loadIconFontArchive,
+  parseYesNo,
+  planIconFontInstall,
+  terminalFontHint,
+  uninstallIconFont,
+  windowsIconFontInstructions,
+} from "./icon-font.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
@@ -105,13 +117,32 @@ Install options:
                 safeguards are never weakened.
   --yolo        Shorthand for --permission-mode yolo.
   --yes         Accept today's shipped defaults for every question (HUD accent,
-                output style) and run without prompts. Model selection stays
-                host-owned: Claude Code picks its own models, so the installer
-                never asks for a model or reasoning effort.
+                output style, no icon font) and run without prompts. Model
+                selection stays host-owned: Claude Code picks its own models, so
+                the installer never asks for a model or reasoning effort.
+  --icon-font   Also install the symbols-only Nerd Font (Symbols Nerd Font Mono,
+                MIT) into your user font folder, so the LIT band can draw its
+                rounded pills and icons. Downloaded from the pinned Nerd Fonts
+                release and refused unless its SHA-256 matches; an offline copy
+                of that archive can be named with LITCLAUDE_ICON_FONT_SOURCE.
+                An interactive install asks instead (default No).
 
 Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit \`ca251e3\`.
 `;
 
+const dryRunAfterCommand = new Set(["install", "update", "uninstall", "doctor"]);
+const dryRunTrueValues = new Set(["true", "1", "yes"]);
+
+// `--dry-run` and `--dry-run=true` mean a dry run. Any other value is refused here, before any
+// command runs: a mistyped dry run must never fall through to the real action.
+const isDryRunFlag = (arg) => {
+  if (arg === "--dry-run") return true;
+  if (typeof arg !== "string" || !arg.startsWith("--dry-run=")) return false;
+  if (dryRunTrueValues.has(arg.slice("--dry-run=".length).toLowerCase())) return true;
+  process.stderr.write(`Unsupported value in ${arg}: use --dry-run (or --dry-run=true) for a dry run, or leave the flag out to run for real\n`);
+  process.exit(64);
+};
+
 const parseArgs = (argv) => {
   const args = [];
   let noAutoUpdate = false;
@@ -128,9 +159,15 @@ const parseArgs = (argv) => {
   }
   const wantsVersion = args[0] === "--version" || args[0] === "-v";
   if (wantsVersion) return { dryRun: false, command: "version", rest: [], noAutoUpdate, invalidOption };
-  const dryRun = args[0] === "--dry-run";
+  let dryRun = isDryRunFlag(args[0]);
   if (dryRun) args.shift();
-  return { dryRun, command: args[0], rest: args.slice(1), noAutoUpdate, invalidOption };
+  let rest = args.slice(1);
+  // The managed commands also take --dry-run after the subcommand (`install --dry-run`).
+  if (dryRunAfterCommand.has(args[0]) && rest.some(isDryRunFlag)) {
+    dryRun = true;
+    rest = rest.filter((arg) => !isDryRunFlag(arg));
+  }
+  return { dryRun, command: args[0], rest, noAutoUpdate, invalidOption };
 };
 
 const litHome = () => resolve(process.env.LITCLAUDE_HOME ?? join(homedir(), ".litclaude"));
@@ -185,6 +222,7 @@ const parseInstallOptions = (rest, existingPermissionMode = "safe") => {
   let permissionMode = parsePermissionMode(process.env.LITCLAUDE_PERMISSION_MODE || preservedMode);
   let permissionExplicit = Boolean(process.env.LITCLAUDE_PERMISSION_MODE);
   let assumeYes = false;
+  let iconFont = false;
 
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index];
@@ -212,10 +250,14 @@ const parseInstallOptions = (rest, existingPermissionMode = "safe") => {
       assumeYes = true;
       continue;
     }
+    if (arg === "--icon-font") {
+      iconFont = true;
+      continue;
+    }
     fail(`Unknown install option: ${arg}`, 64);
   }
 
-  return { permissionMode, permissionExplicit, assumeYes };
+  return { permissionMode, permissionExplicit, assumeYes, iconFont };
 };
 
 const permissionProfile = (mode) => {
@@ -257,6 +299,19 @@ const fail = (message, status = 1) => {
   process.exit(status);
 };
 
+// A piped stdout is asynchronous on macOS, so process.exit() straight after a large write drops
+// the queued tail (a 400 KB report arrived as 64 KiB). Exit once both streams have flushed.
+const exitAfterFlush = (status) => {
+  process.exitCode = status;
+  let pending = 2;
+  const flushed = () => {
+    pending -= 1;
+    if (pending === 0) process.exit(status);
+  };
+  process.stdout.write("", flushed);
+  process.stderr.write("", flushed);
+};
+
 const shouldAnimateInstall = () => {
   if (process.env.LITCLAUDE_SPINNER === "1") return true;
   if (process.env.LITCLAUDE_SPINNER === "0") return false;
@@ -284,6 +339,8 @@ const formatInstallStep = (label) => {
 // Shared LitFamily banner frame (plans/references/installer-choice-contract.md):
 // the canonical Ignition B mark plus the existing install plan frame.
 const FAMILY_RULE = `  ${"━".repeat(46)}`;
+// The banner keeps its short tagline; package.json carries the longer npm search description.
+const BANNER_TAGLINE = "Claude Code-native workflow distribution.";
 const trueColorSupported = () => /truecolor|24bit/iu.test(process.env.COLORTERM ?? "");
 const brandOrange = (text, color = shouldColorInstall()) => {
   if (!color) return text;
@@ -311,7 +368,7 @@ const familyBanner = ({ color = shouldColorInstall() } = {}) => [
   brandOrange(FAMILY_RULE, color),
   "",
   ...renderLitClaudeWordmark({ color }),
-  `       ${packageJson.description}`,
+  `       ${BANNER_TAGLINE}`,
   "",
   brandOrange(FAMILY_RULE, color),
   "  ╭─ INSTALL PLAN",
@@ -453,7 +510,7 @@ const hudAccentPreview = (theme) => {
       ? `\x1b[${ansi16CodeForAccent(theme.name)}m`
       : `\x1b[38;5;${theme.code}m`;
   const mark = `${accent}▌${accent ? "\x1b[0m" : ""}`;
-  const metrics = ` | O4.8 │ ctx [${mark}░░] 18%/1000k │ 5h [▏░] 4%`;
+  const metrics = ` | O4.8 │ ctx [${mark}░░] 18%/1m │ 5h [▏░]4%`;
   return `${brand}${metrics}`;
 };
 
@@ -536,6 +593,53 @@ const chooseOutputStyle = async (existingChoice = "off") => {
   }
 };
 
+const shouldPromptIconFont = () => {
+  if (process.env.LITCLAUDE_ICON_FONT_PROMPT === "1") return true;
+  if (process.env.LITCLAUDE_ICON_FONT_PROMPT === "0") return false;
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY && !Object.hasOwn(process.env, "CI"));
+};
+
+// The icon font is opt-in: the flag, or a Yes to the one question an interactive install asks.
+// --yes keeps the shipped default, which is No.
+const chooseIconFont = async ({ iconFont, assumeYes }) => {
+  if (iconFont) return true;
+  if (assumeYes || !shouldPromptIconFont()) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: shouldColorInstall() });
+  try {
+    return parseYesNo(await rl.question(ICON_FONT_QUESTION));
+  } finally {
+    rl.close();
+  }
+};
+
+const iconFontPaths = () => ({ platform: process.platform, env: process.env, home: homedir(), litHome: litHome() });
+
+const runIconFontInstall = async () => {
+  const where = iconFontPaths();
+  if (!planIconFontInstall(where).supported) {
+    process.stdout.write(`ICON_FONT_SKIPPED: ${windowsIconFontInstructions()}\n`);
+    return;
+  }
+  try {
+    const archive = await loadIconFontArchive({ env: process.env });
+    const result = installIconFont({ ...where, archive });
+    for (const path of result.installed) process.stdout.write(`ICON_FONT_INSTALLED: ${path}\n`);
+    for (const path of result.present) process.stdout.write(`ICON_FONT_PRESENT: ${path}\n`);
+    for (const { path, reason } of result.skipped) process.stdout.write(`ICON_FONT_LEFT_ALONE: ${path} (${reason})\n`);
+    if (result.fontCache) process.stdout.write(`ICON_FONT_CACHE: ${result.fontCache}\n`);
+    process.stdout.write(`ICON_FONT_HINT: ${terminalFontHint(process.env)}\n`);
+  } catch (error) {
+    process.stderr.write(`ICON_FONT_FAILED: ${error.message}\n`);
+  }
+};
+
+const iconFontDoctorLine = () => {
+  const status = iconFontStatus(iconFontPaths());
+  if (!status.supported) return "ICON_FONT: not managed on this platform (optional; see litclaude-ai install --help)";
+  if (status.present) return `ICON_FONT: present (${status.path}, ${status.managed ? "installed by LitClaude" : "not installed by LitClaude"})`;
+  return "ICON_FONT: not installed (optional; litclaude-ai install --icon-font)";
+};
+
 const hudCommandForPlugin = (pluginPath, accent = "cyan") =>
   `LITCLAUDE_HUD_ACCENT=${normalizeHudAccent(accent)} node "${join(pluginPath, "bin", "litclaude-hud.js")}"`;
 
@@ -1030,6 +1134,8 @@ const verifyInstalledPayload = ({ home, litClaudeHome, targetPlugin }) => {
   for (const relativePath of [
     ".claude-plugin/plugin.json",
     "hooks/hooks.json",
+    "hooks/lit-mod.mjs",
+    "hooks/lit-band-client.mjs",
     "bin/litclaude-hook.js",
     "lib/start-work-lifecycle.mjs",
     "lib/start-work-cli.mjs",
@@ -1135,7 +1241,7 @@ const install = async ({ dryRun, rest }) => {
   const home = claudeHome();
   const litClaudeHome = litHome();
   const existingLitClaude = readClaudeSettings(home)[litClaudeSettingsKey] ?? {};
-  const { permissionMode, permissionExplicit, assumeYes } = parseInstallOptions(rest, existingLitClaude.permissionMode);
+  const { permissionMode, permissionExplicit, assumeYes, iconFont } = parseInstallOptions(rest, existingLitClaude.permissionMode);
   const existingHudAccent = normalizeHudAccent(existingLitClaude.hudAccent);
   const existingOutputStyle = existingLitClaude.outputStyleChoice ?? "off";
   const requestedHudAccent = process.env.LITCLAUDE_HUD_ACCENT
@@ -1160,6 +1266,16 @@ const install = async ({ dryRun, rest }) => {
     process.stdout.write(`Would mutate global Claude settings permissions.allow/deny: ${permissionMode} (${permissionSource})\n`);
     process.stdout.write(`Permission profile: ${permissionProfile(permissionMode).description}\n`);
     process.stdout.write("Would pre-warm the lit-typographic-motion runtime: litclaude-ai motion-runtime install\n");
+    const fontPlan = planIconFontInstall(iconFontPaths());
+    if (iconFont) {
+      process.stdout.write(fontPlan.supported
+        ? `Would install icon font: ${ICON_FONT.family} ${ICON_FONT.release} into ${fontPlan.dir} from ${ICON_FONT.url} (SHA-256 ${ICON_FONT.archiveSha256})\n`
+        : `Would skip icon font: ${windowsIconFontInstructions()}\n`);
+    } else if (!assumeYes && shouldPromptIconFont()) {
+      process.stdout.write(`Would ask: ${ICON_FONT_QUESTION.trim()}\n`);
+    } else {
+      process.stdout.write("Icon font: not requested (pass --icon-font)\n");
+    }
     process.stdout.write("Launch with: claude\n");
     return;
   }
@@ -1174,6 +1290,7 @@ const install = async ({ dryRun, rest }) => {
   const outputStyleChoice = assumeYes
     ? normalizeOutputStyle(process.env.LITCLAUDE_OUTPUT_STYLE ?? existingOutputStyle)
     : await chooseOutputStyle(existingOutputStyle);
+  const wantsIconFont = await chooseIconFont({ iconFont, assumeYes });
   const preservation = preflightInstallOwnership({ preserveModifiedSkill: true });
   const preservedPath = preserveModifiedLegacySkill(preservation, litClaudeHome);
   const targetCompatibility = versionRoot(litClaudeHome);
@@ -1268,6 +1385,7 @@ const install = async ({ dryRun, rest }) => {
   process.stdout.write(hudManaged ? `HUD: LitClaude statusLine installed (${hudAccent})\n` : "HUD: user statusLine setting preserved\n");
   process.stdout.write(`Global Claude settings permissions.allow/deny: ${permissionMode} — ${permissionProfile(permissionMode).description}\n`);
   process.stdout.write(`${prewarmMotionRuntime()}\n`);
+  if (wantsIconFont) await runIconFontInstall();
   process.stdout.write("Launch with: claude\n");
   if (preservedPath) process.stderr.write(`INSTALL_WARNING: PRESERVED_MODIFIED_SKILL lit-korean at ${preservedPath}\n`);
 };
@@ -1295,6 +1413,7 @@ const doctor = ({ dryRun }) => {
     process.stdout.write("Would verify exact canonical frontend corpus bytes, legal companions, no extras, and three canonical runtime closures\n");
     process.stdout.write(`${jevStatusLine(process.env)}\n`);
     writeAutoHandoffDoctorLines();
+    process.stdout.write(`${iconFontDoctorLine()}\n`);
     return;
   }
 
@@ -1307,6 +1426,8 @@ const doctor = ({ dryRun }) => {
     ".mcp.json",
     ".lsp.json",
     "hooks/hooks.json",
+    "hooks/lit-mod.mjs",
+    "hooks/lit-band-client.mjs",
     "bin/litclaude-hook.js",
     "bin/litclaude-mcp.js",
     "lib/start-work-lifecycle.mjs",
@@ -1383,6 +1504,7 @@ const doctor = ({ dryRun }) => {
   }
   process.stdout.write(`${jevStatusLine(process.env)}\n`);
   writeAutoHandoffDoctorLines();
+  process.stdout.write(`${iconFontDoctorLine()}\n`);
 
   // lit-typographic-motion: the five readiness probes, every run. Read-only and never fatal; a
   // missing pre-warm names the command that fixes it.
@@ -1484,7 +1606,7 @@ const runClaude = ({ dryRun, rest }) => {
 
   const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
   if (result.error) fail(`failed to start claude: ${result.error.message}`);
-  process.exit(result.status ?? 1);
+  exitAfterFlush(result.status ?? 1);
 };
 
 const uninstall = ({ dryRun }) => {
@@ -1493,8 +1615,15 @@ const uninstall = ({ dryRun }) => {
   const updateNotifierRoot = dirname(updateNotifierCachePath(home));
   if (dryRun) {
     process.stdout.write(`DRY_RUN: remove checked ${versionRoot(home)}, ${currentRoot(home)}, ${marketplaceRoot(home)}, ${claudePluginRoot()}, ${pluginKey}, and its marketplace/settings entries; preserve unrelated versions/cache entries and nonempty ${updateNotifierRoot}\n`);
+    const fonts = uninstallIconFont({ litHome: home, dryRun: true });
+    for (const path of fonts.removed) process.stdout.write(`Would remove icon font file: ${path}\n`);
+    for (const { path, reason } of fonts.kept) process.stdout.write(`Would keep icon font file: ${path} (${reason})\n`);
     return;
   }
+  // Before the LitClaude home goes: the manifest there says which font files LitClaude wrote.
+  const fonts = uninstallIconFont({ litHome: home });
+  for (const path of fonts.removed) process.stdout.write(`ICON_FONT_REMOVED: ${path}\n`);
+  for (const { path, reason } of fonts.kept) process.stdout.write(`ICON_FONT_KEPT: ${path} (${reason})\n`);
   rmSync(currentRoot(home), { recursive: true, force: true });
   rmSync(versionRoot(home), { recursive: true, force: true });
   removeEmptyDirectory(join(home, "litclaude-ai"));
@@ -1560,7 +1689,8 @@ const main = async () => {
 
   if (!command) {
     printUsage();
-    process.exit(64);
+    exitAfterFlush(64);
+    return;
   }
   if (parsed.invalidOption) fail(`Unknown update option: ${parsed.invalidOption}`, 64);
 
@@ -1570,6 +1700,13 @@ const main = async () => {
     return;
   }
 
+  // Unknown flags on the managed commands stop here, before the ownership preflight, the
+  // automatic update or the command itself can change anything.
+  if (command === "install" || command === "update") parseInstallOptions(parsed.rest);
+  if ((command === "uninstall" || command === "doctor") && parsed.rest.length > 0) {
+    fail(`Unknown ${command} option: ${parsed.rest[0]}`, 64);
+  }
+
   if (!parsed.dryRun && ["install", "update", "uninstall"].includes(command)) {
     preflightInstallOwnership({ preserveModifiedSkill: ["install", "update"].includes(parsed.command) });
   }
@@ -1603,26 +1740,26 @@ const main = async () => {
       runClaude(parsed);
       break;
     case "litgoal":
-      process.exit(runLitgoalCli(parsed.rest));
+      exitAfterFlush(runLitgoalCli(parsed.rest));
       break;
     case "wikify":
-      process.exit(runWikifyKnowledgeCli(parsed.rest, undefined, process.cwd()));
+      exitAfterFlush(runWikifyKnowledgeCli(parsed.rest, undefined, process.cwd()));
       break;
     case "workflow-check":
-      process.exit(runWorkflowCheckCli(root, version, parsed.rest));
+      exitAfterFlush(runWorkflowCheckCli(root, version, parsed.rest));
       break;
     case "public-read":
-      process.exit(await runPublicRead(parsed));
+      exitAfterFlush(await runPublicRead(parsed));
       break;
     case "start-work-next":
-      process.exit(runStartWorkContinuationCli(root, parsed.rest));
+      exitAfterFlush(runStartWorkContinuationCli(root, parsed.rest));
       break;
     case "start-work":
-      process.exit(runStartWorkCli(parsed.rest, undefined, process.cwd()));
+      exitAfterFlush(runStartWorkCli(parsed.rest, undefined, process.cwd()));
       break;
     case "motion-runtime": {
       const { main: motionRuntime } = await import(pathToFileURL(join(motionSkillScripts, "motion-runtime.mjs")).href);
-      process.exit(await motionRuntime(parsed.rest));
+      exitAfterFlush(await motionRuntime(parsed.rest));
       break;
     }
     case "uninstall":

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.21"><title>release: 1.0.21</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.21</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.22"><title>release: 1.0.22</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.22</text></g></svg>