@moikapy/lich 0.5.1 → 0.7.0

package/docs/user-guide/cli.md

@@ -13,19 +13,25 @@ lich tui               # interactive terminal UI (ink)
 lich gateway <plat..>  # messaging gateway (webhook|telegram|discord|twitch)
 lich config            # print a starter config template
 lich update            # install a newer npm release, if one exists
+lich mcp list          # list servers in this work dir's .lich/config.json
+lich mcp add <name>    # catalog or --command/--url; stays disabled
+lich mcp enable <name> # set enabled true
+lich mcp disable <name>
+lich mcp remove <name>
 lich --help            # usage text
-lich --version         # print 0.3.0
+lich --version         # package.json version (published package and this tree: 0.6.0)
 ```
 
-- **Bare `lich`** opens the same TUI as `lich tui`. It does not print usage. On a TTY, if neither `.lich/config.json` nor `~/.config/lich/config.json` exists and `LICH_MODEL` / `--model` is unset, a setup wizard runs first (name, provider, optional gateway env-var names, optional plugins) and writes `.lich/config.json` once. An existing `.lich/config.json` skips the wizard and is not replaced. Non-TTY stdin skips the wizard and prints guidance instead of hanging. `lich --help` still prints usage.
+- **Bare `lich`** opens the same TUI as `lich tui`. It does not print usage. On a TTY, if neither `.lich/config.json` nor `~/.config/lich/config.json` exists, a setup wizard runs first (name, provider, optional gateway env-var names, optional plugins) and writes `.lich/config.json` once. `LICH_MODEL` / `--model` prefills the model prompt; it does not skip the wizard. An existing config in that chain skips the wizard and is not replaced. Non-TTY stdin skips the wizard and prints guidance instead of hanging. `lich --help` still prints usage.
 - **`lich init`** writes that starter file without prompts, using the same writer as the wizard. Existing flags such as `--model` are written into the file and win over `LICH_MODEL`. It never overwrites an existing `.lich/config.json`. `.lich/` is gitignored.
 - **One-shot** joins all positional words into a single task, runs the agent loop, prints the final answer to stdout, and exits. Progress (turn numbers, tool results) goes to stderr.
 - **Chat** is a readline REPL over one long-lived agent: each line is a turn, memory persists across lines, and an empty line, `/exit`, or `/quit` ends the session. After each turn it prints a `[turns N | tokens M]` footer.
 - **TUI** launches the ink interface. See the [TUI guide](tui.md).
 - **Gateway** runs platform adapters (defaults to `webhook` when no platform is given). See the [Gateway guide](gateway.md). Unknown platform names are skipped with a warning; if none remain, the CLI exits `1`.
 - **Update** compares the installed version to the npm registry and, when a newer release exists, runs `npm install -g @moikapy/lich@latest`. Exit any running TUI or gateway first; npm cannot replace the package while those processes are running. A git clone is told to `git pull`. See [Updating](../getting-started.md#updating).
+- **MCP** is in this source (changelog 0.7.0, unreleased). The published 0.6.0 npm package does not include `lich mcp`. It edits only `mcp_servers` in `<work-dir>/.lich/config.json` through the same writer as `lich init` (`update` mode, so other keys stay). A missing file lists as empty; `add` creates the file if needed. New entries stay disabled until `enable`. Names must match `^[a-z][a-z0-9_]*$`. Catalog names use `optional-mcps/`; otherwise pass `--command` and repeatable `--arg`, or `--url` (loopback only), not both. Redot still needs `--project-path` for the catalog args, and the command basename must be `redot`. No prompts. See the [Redot guide](redot.md).
 
-The installed `lich` binary and `bun src/cli.ts` (from a repository clone) accept identical arguments.
+A repository clone's `bun src/cli.ts` matches that checkout. The published 0.6.0 binary does not include `lich mcp`.
 
 ## Flags
 
@@ -43,6 +49,11 @@ Flags work before or after the subcommand. Every value flag can also be set via
 | `--system-prompt <s>` | Replaces the default system prompt. | built-in concise-assistant prompt |
 | `--session-dir <path>` | Transcript directory. | `<work_dir>/.lich/sessions` |
 | `--log-level <level>` | `debug` \| `info` \| `warn` \| `error`. | `info` |
+| `--theme <name>` | Display theme loaded once at startup. `lich` is built-in; other names read `~/.lich/themes/<name>.json`. | `lich` |
+| `--command <bin>` | `lich mcp add` only: local stdio binary. | – |
+| `--arg <value>` | `lich mcp add` only: repeatable stdio arg. May start with `--`. | – |
+| `--url <url>` | `lich mcp add` only: loopback HTTP MCP URL. | – |
+| `--project-path <path>` | `lich mcp add` only: catalog `${project_path}` substitute. | – |
 
 Passing `--max-turns 0` or a non-integer fails with `--max-turns must be a positive integer`. Unknown flags fail with `unknown flag: --foo`. A flag missing its value fails with `<flag> requires a value`.
 
@@ -50,7 +61,7 @@ Passing `--max-turns 0` or a non-integer fails with `--max-turns must be a posit
 
 The effective provider for a run is decided in this order:
 
-1. If `--config <path>` was passed, that file is the whole configuration (it must exist, or the CLI fails with `config not found`).
+1. If `--config <path>` was passed, that file is the whole configuration (it must exist and be a JSON object, or the CLI fails with `cannot use config file <path>: ...`).
 2. Otherwise the discovery chain is walked: `./.lich/config.json`, then `~/.config/lich/config.json`. The first file found becomes the config. `LICH_*` env vars are *not* merged into a discovered file.
 3. If no config file exists, one is built from the environment: `--provider-kind` / `LICH_PROVIDER_KIND` (default `openai_compat`), `--model` / `LICH_MODEL` (required — without it the CLI fails with `no model configured`), `--base-url` / `LICH_BASE_URL`, and `--api-key-env` / `LICH_API_KEY_ENV`, each falling back to the per-kind defaults below.
 4. Provider override flags (`--model`, `--provider-kind`, `--base-url`, `--api-key-env`) always win over the chosen source: with a config file present they patch `providers[0]` in place; without one they seed a fresh provider from the environment.
@@ -65,7 +76,7 @@ Per-kind defaults:
 
 ## Config file reference
 
-Validated by zod (top-level unknown keys are silently stripped; extra keys inside a `providers[]` entry are passed through). Full example with every field:
+Validated by zod (top-level unknown keys are silently stripped; extra keys inside a `providers[]` entry are passed through; each `mcp_servers` entry is strict). Example:
 
 ```json
 {
@@ -95,7 +106,8 @@ Validated by zod (top-level unknown keys are silently stripped; extra keys insid
   "compress_threshold": 0.8,
   "session_dir": "/home/me/project/.lich/sessions",
   "terminal_timeout_ms": 60000,
-  "log_level": "info"
+  "log_level": "info",
+  "theme": "lich"
 }
 ```
 
@@ -111,12 +123,15 @@ Validated by zod (top-level unknown keys are silently stripped; extra keys insid
 | `providers[].timeout_ms` | positive int | none | Per-request abort deadline. |
 | `providers[].think` | boolean | – | Ollama only: request thinking mode. |
 | `providers[].keep_alive` | string | – | Ollama only: model residency (e.g. `"10m"`). |
-| `agent_name` | string | `lich` | Display name in the TUI banner. |
+| `agent_name` | string | `lich` | Wizard label. The TUI banner uses the active theme welcome string, not this field. |
+| `theme` | string | `lich` | Display theme name. See [Themes](https://github.com/Moikapy/lich/blob/main/README.md#themes). |
 | `gateway` | object | omitted | Optional. `platforms` (`webhook` \| `telegram` \| `discord` \| `twitch`) and `token_envs` (platform → env-var name). Secrets stay in the environment. |
+| `plugins` | string array | `[]` | Module paths relative to `work_dir` or absolute. Bare `lich`, one-shot, chat, tui, and gateway load them through `create_agent_with_plugins`. `run_agent` does too. `create_agent` does not. See the [plugins guide](plugins.md). |
+| `mcp_servers` | object | omitted | Optional. Closed record of named servers. Each entry is stdio `{command, args, env?}` or loopback http `{url}`. `enabled` defaults to false. Unknown keys are rejected. In this source only (0.7.0 unreleased; not in the published 0.6.0 package). See the [Redot guide](redot.md). |
 | `system_prompt` | string | built-in | Replaces the default system prompt. |
 | `max_turns` | int >= 1 | `25` | Turn budget per run. |
 | `work_dir` | string | cwd | Root for all file tools; paths outside are rejected. |
-| `tools_enabled` | `"all"` or name array | `"all"` | Restrict the registry to these builtin tools. |
+| `tools_enabled` | `"all"` or name array | `"all"` | Restrict the builtin registry to these names. `[]` drops builtins and MCP tools and does not connect to MCP servers. Plugin tools still register afterward, including the gatekeeper's `git_commit`. |
 | `temperature` | 0–2 | – | Sampling temperature. |
 | `max_tokens` | positive int | – | Completion cap. |
 | `context_budget_tokens` | positive int | `100000` | Estimated budget before compression triggers. |
@@ -166,7 +181,7 @@ jq -r 'select(.kind=="message") | "\(.message.role): \(.message.content // "(too
 
 | Code | Meaning |
 | --- | --- |
-| `0` | Success: final answer produced (also `--help`, `--version`, `config`, `init`, and a TUI that exits cleanly). |
+| `0` | Success: final answer produced (also `--help`, `--version`, `config`, `init`, a successful `mcp` action, `update` when nothing newer is installed or the install succeeds, and a TUI that exits cleanly). |
 | `1` | Any failure: unknown flag, missing model, unreadable config, provider error after failover, aborted run, budget exhaustion, non-TTY bare `lich`, or a cancelled setup wizard. |
 
 ## Log levels

package/docs/user-guide/games.md

@@ -0,0 +1,93 @@
+# Games
+
+> What you'll learn: how to treat session JSONL as a combat log, which fields the recipes read, and how a playthrough's token spend shows up after a run.
+
+lich does not replay combat from RNG seeds. The commander's choices are sampled. The JSONL transcript is the replay. Godot still drains `.lich/game/`; these recipes read `.lich/sessions/`, not the order file.
+
+Tool shapes live in [`examples/game_bridge/README.md`](https://github.com/Moikapy/lich/blob/main/examples/game_bridge/README.md). This page does not repeat them. The plugin entry is `examples/game_bridge/game_bridge.plugin.mjs`, loaded through `config.plugins` and `create_agent_with_plugins`. A per-persona HTTP front for that plugin is the [orchestrator example](https://github.com/Moikapy/lich/blob/main/examples/persona_orchestrator/README.md) — a pattern the game repo copies, not a second agent core.
+
+## Session files as combat logs
+
+Each `Agent.run` appends one `.jsonl` file under `session_dir` (default `<work_dir>/.lich/sessions`). Records are `{ts, kind: "message"|"meta", message?, meta?}`.
+
+| What you want | Where it is |
+| --- | --- |
+| What the commander saw | `kind: "message"`, `message.role: "user"` — the battle digest you posted |
+| What it chose | assistant `message.tool_calls[]` with `name`, `args` |
+| Why | `args.rationale` on `enemy_actions` |
+| What happened | `message.role: "tool"`, `content`, optional `is_error` |
+| Token spend | `kind: "meta"`, `meta.event: "run_end"`, `meta.usage` |
+
+Assistant tool calls are the internal shape `{id, name, args}`, not the provider wire format. Tool failures are `JSON.stringify({ok, output, error})` in `content`, with `is_error: true`. A plugin veto is that object with `error` starting `blocked_by_plugin:` (the meteor gate uses `blocked_by_plugin: meteor_gates_closed_until_round_3`). Non-JSON tool content is not an error for the recipes: `fromjson?` skips it.
+
+`run_end` is written for every completed loop (`stopped_reason` `final`, `budget`, or `aborted`). `usage` is `{prompt_tokens, completion_tokens, total_tokens}` and matches the `usage_total` returned to the caller. A budget stop also writes `meta.event: "budget_exhausted"` before `run_end`. Recipes that filter `kind=="message"` stay valid as meta events change. A provider throw never reaches persistence — there is no outcome to close. A failed persist logs a warning and returns `session_path: undefined`; a run missing from disk is a gap, not a zero-spend run.
+
+Filenames are `<base36-timestamp>-<counter>[-<label>].jsonl`. The timestamp prefix sorts chronologically. The gateway (and the orchestrator example) labels `gw:<platform>:<chat_id>`. With `chat_id` = run id, files for one playthrough share that label. The label slug is truncated to 40 characters.
+
+`read_session_messages(path)` in `src/session/store.ts` is the programmatic reader for a source checkout. It is not a package export. It returns messages only and skips meta. Offline analysis should use `jq` (a user tool, not a lich dependency).
+
+## Recipes
+
+`jq` is a prerequisite for these commands, not a package dependency. Paths assume you are in `work_dir`.
+
+```bash
+# (1) rationale
+jq -r 'select(.kind=="message") | select(.message.role=="assistant")
+       | .message.tool_calls[]? | select(.name=="enemy_actions")
+       | .args.rationale' .lich/sessions/*.jsonl
+```
+
+```bash
+# (2) histogram
+jq -s '[.[] | .message? | select(.role=="assistant")
+        | .tool_calls[]? | select(.name=="enemy_actions")
+        | .args.actions[]?.action]
+       | group_by(.) | map({action: .[0], uses: length}) | sort_by(-.uses)' \
+  .lich/sessions/*.jsonl
+```
+
+```bash
+# (3) veto
+jq -r 'select(.kind=="message") | select(.message.role=="tool")
+       | .message.content | fromjson? | select(.error? // "" | startswith("blocked_by_plugin"))
+       | .error' .lich/sessions/*.jsonl
+```
+
+```bash
+# (4) is_error
+jq -r 'select(.kind=="message") | select(.message.role=="tool" and .message.is_error==true)
+       | [.ts, .message.name, .message.content] | @tsv' .lich/sessions/*.jsonl
+```
+
+```bash
+# (5) pacing
+jq -r 'select(.kind=="message") | select(.message.role=="user" or .message.role=="assistant")
+       | [.ts, .message.role] | @tsv' .lich/sessions/<run>.jsonl
+```
+
+```bash
+# (usage) run_end tokens
+jq -s '[.[] | select(.kind=="meta" and .meta.event=="run_end") | .meta.usage.total_tokens] | add' \
+  .lich/sessions/*.jsonl
+```
+
+Recipe 2 counts assistant tool-call arguments, including orders a hook later vetoed. It is not the line set Godot applied. Recipe 3 is not a veto table. The only gate in the shipped plugin is meteor before round 3. Other `blocked_by_plugin:` strings, if a game plugin adds them, show up in the same query because the loop formats every veto the same way.
+
+## Do not glob a playthrough blindly
+
+A gateway conversation of N posts writes N files. `Agent.run` seeds from `history`, and `persist_session` appends all of `outcome.messages`, so each file is a superset of the previous exchange. Globbing `*.jsonl` double-counts. Take the newest file per label (names sort by timestamp prefix), or dedupe on `tool_call.id`, which stays stable when the same call is replayed into the next file.
+
+Compression can rewrite a long run in place: when estimated tokens cross `compress_threshold` of `context_budget_tokens`, older messages become one summary and the 8 most recent non-system messages stay verbatim. Early rounds may survive only as that summary. The recipes see the file on disk, not the pre-compression transcript.
+
+## Player modeling
+
+Cross-run notes are tool arguments, not a second memory agent. `dungeon_memory_write` args (`note`) and `dungeon_memory_read` results are in the JSONL. The file on disk is `.lich/game/memory.jsonl`; Godot does not drain it as orders. `MEMORY.md` is never auto-loaded and is not this paper trail.
+
+Replay `dungeon_memory_read` calls around a boss fight, then read `enemy_actions` `rationale` after them, to see which notes the commander actually used. The notes are reference data. A note in the tool result is not an instruction, and the session file does not promote it into the system prompt.
+
+```bash
+# (memory) dungeon notes
+jq -r 'select(.kind=="message") | select(.message.role=="assistant")
+       | .message.tool_calls[]? | select(.name=="dungeon_memory_write")
+       | .args.note' .lich/sessions/*.jsonl
+```

package/docs/user-guide/godot.md

@@ -4,6 +4,8 @@
 
 lich is the AI brain in a separate process. Godot speaks HTTP. This page is the recipe; the file contract and tool list live in [`examples/game_bridge/README.md`](https://github.com/Moikapy/lich/blob/main/examples/game_bridge/README.md). Plugin authoring is the [plugins guide](plugins.md). Platform setup beyond the webhook is the [gateway guide](gateway.md). A TypeScript game backend that embeds the library uses the [library guide](library.md) — Godot itself does not.
 
+Editor MCP and this page are opposite directions. An editor MCP is lich connecting to the editor to build the project — the [Redot guide](redot.md). This page is the game connecting to lich. Godot has no official MCP server. lich does not download a community addon and does not spawn one. A game master is another persona, not an editor tool. Play for both editors is still one `POST /message` per round, then drain `.lich/game/orders.jsonl`. Do not call lich per frame.
+
 ## Architecture
 
 Two tiers:
@@ -24,7 +26,7 @@ flowchart LR
     G --> H[resolve the round]
 ```
 
-A game backend may instead call `run_agent`, which loads `config.plugins`. `create_agent` does not. Godot still reaches that backend over HTTP; it does not import the package.
+A game backend may instead call `run_agent`, which loads `config.plugins`. `create_agent` does not. Godot still reaches that backend over HTTP; it does not import the package. Several personas means several agents behind that HTTP process — the pattern is [`examples/persona_orchestrator`](https://github.com/Moikapy/lich/blob/main/examples/persona_orchestrator/README.md), and the service is the game's. Session replay is the [games guide](games.md).
 
 ## Gateway contract
 

package/docs/user-guide/library.md

@@ -145,7 +145,9 @@ Listed providers form a failover chain tried in order: `rate_limit`/`network` er
 
 ## Custom tool filtering
 
-`tools_enabled` accepts `"all"` (default) or an array of builtin tool names to register; everything else stays unregistered and invisible to the model:
+`tools_enabled` accepts `"all"` (default) or an array of tool names to register; everything else stays unregistered and invisible to the model. MCP tools, when a named server is `enabled`, use the same allowlist and stay off when the list is `[]` (that empty list does not connect). The filter does not apply to plugin tools: they register afterward, including the gatekeeper's `git_commit` (fail-closed unless `LICH_ALLOW_SELF_COMMIT=1`). `[]` strips every builtin and every MCP tool and does not throw.
+
+`mcp_servers` and `catalog_client_entry` are in this source (changelog 0.7.0, unreleased). The published 0.6.0 package does not include them. See the [Redot guide](redot.md).
 
 ```ts
 const agent = create_agent({
@@ -182,6 +184,10 @@ try {
 
 When every configured provider fails, the last `ProviderError` is thrown. Tool failures are *not* exceptions: they return `{ ok: false, output, error }` into the loop as tool messages for the model to react to. Cancellation via `signal` ends the run with `stopped_reason: "aborted"` rather than throwing.
 
+## Games
+
+A Godot client does not embed the library. A game backend that does is still one `Agent` per persona, not a second loop. The pattern — factory, history cap, per-conversation queue, `POST /message` → `{reply, usage}` — is [`examples/persona_orchestrator`](https://github.com/Moikapy/lich/blob/main/examples/persona_orchestrator/README.md). The service itself is game-repo work. Session files as a combat log: [games guide](games.md).
+
 ## Session access
 
-Each `run()` appends a transcript line-by-line under `config.session_dir` (default `<work_dir>/.lich/sessions`); `result.session_path` gives the exact file. Records carry `{ts, kind: "message"|"meta", message?, meta?}`; read them with `jq` (or the `read_session_messages(path)` helper if you are working from a source checkout). Persistence is best-effort: a write failure logs a warning, returns `session_path: undefined`, and never fails the run.
+Each `run()` appends a transcript line-by-line under `config.session_dir` (default `<work_dir>/.lich/sessions`); `result.session_path` gives the exact file. Records carry `{ts, kind: "message"|"meta", message?, meta?}`. A completed run (`final`, `budget`, or `aborted` returned by the loop) closes with `{event: "run_end", stopped_reason, usage}` where `usage` equals `usage_total`. A budget stop also writes `{event: "budget_exhausted"}` before that. Provider throws do not persist. Read transcripts with `jq` (see the [games guide](games.md)) or `read_session_messages(path)` from a source checkout — it is not a package export. Persistence is best-effort: a write failure logs a warning, returns `session_path: undefined`, and never fails the run.

package/docs/user-guide/plugins.md

@@ -112,7 +112,7 @@ Failures are contained at every layer:
 
 ## Runtime notes
 
-`package.json` `engines.node` is `>=20`. The CLI loads `config.plugins` before the run. A broken entry logs one `plugin load errors` warning and the run continues without that plugin.
+`package.json` `engines.node` is `>=20`. Bare `lich`, one-shot, chat, tui, and gateway load `config.plugins` through `create_agent_with_plugins` before the run. `lich init`, `lich config`, `lich update`, and `lich mcp` do not start an agent. `create_agent` stays plugin-free; `run_agent` loads plugins. A broken entry logs one `plugin load errors` warning and the run continues without that plugin.
 
 `.mjs` and other plain JS (no type syntax) are the form that matches `engines.node` `>=20`. They load on Node and on Bun with no plugin-load warning.
 
@@ -122,7 +122,7 @@ Checked with Node 26.8.2 (`node dist/cli.js`) and Bun 1.3.14 (`bun src/cli.ts`):
 - On Node 20 and Node 22 before 22.18, a `.ts` entry still warns and the run continues without that plugin.
 - Syntax Node cannot strip (for example `enum`) warns and continues. Bun runs that same file with no plugin-load warning. A syntax error warns on both and the run continues.
 
-The combat-commander reference is `examples/game_bridge/game_bridge.plugin.mjs`. Point `config.plugins` at `./examples/game_bridge/game_bridge.plugin.mjs` (relative to `work_dir`). See `examples/game_bridge/README.md`. Embedding it beside a Godot game: [Godot guide](godot.md).
+The combat-commander reference is `examples/game_bridge/game_bridge.plugin.mjs`. Point `config.plugins` at `./examples/game_bridge/game_bridge.plugin.mjs` (relative to `work_dir`). See [`examples/game_bridge/README.md`](https://github.com/Moikapy/lich/blob/main/examples/game_bridge/README.md). Embedding it beside a Godot game: [Godot guide](godot.md).
 
 Plain JS (matches `engines.node` `>=20`):
 

package/docs/user-guide/redot.md

@@ -0,0 +1,93 @@
+# Redot guide
+
+> What you'll learn: how to add an editor MCP server, and why that is the opposite of in-game play.
+
+Editor MCP and in-game play point opposite ways. This page is lich connecting **to** an editor. NPC control, vetoes, and the game master are the game connecting **to** lich: the webhook and [`examples/game_bridge`](https://github.com/Moikapy/lich/blob/main/examples/game_bridge/README.md). That contract is the [Godot guide](godot.md). A game master is another persona, not an editor tool.
+
+The client is general, the same shape as Hermes and Claude: a named list you extend when you need a server. Redot is a catalog entry on that client, not a hard-wired spawner. lich does not ship the engine and does not download an addon.
+
+## Client
+
+`mcp_servers` is a closed record. Omit it and no MCP tools register. Each name is snake_case. Each value is either stdio or loopback HTTP. `enabled` defaults to `false`. Unknown keys are rejected.
+
+```json
+{
+  "mcp_servers": {
+    "notes": {
+      "enabled": true,
+      "command": "/usr/local/bin/notes-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+stdio is a local binary you named, plus `args`, plus optional `env`. The process is spawned with those argv, never a shell. `npx`, `npm`, `bunx`, `uvx`, `curl`, `wget`, a URL, and shell metacharacters are refused. lich does not run `npx -y` or fetch an addon. Values in `env` are passed to the process and are never logged. `lich mcp add` has no flag for `env`; set that key in the file if you need it.
+
+HTTP is `{ "url": "http://127.0.0.1:9/mcp" }`. The host must be `127.0.0.1` or `localhost`. `0.0.0.0` and any other host are refused. There is no remote MCP in v1.
+
+On connect the client sends `initialize`, then `notifications/initialized`, then `tools/list`. `tools/call` runs only when the model invokes a registered tool. Registered names are `mcp_<server>_<tool>`, so two servers cannot collide. They appear only when that server is `enabled` and `tools_enabled` is `"all"` or lists the prefixed name. `tools_enabled: []` drops them even when the server is enabled, and does not connect. Plugin tools still register, including the gatekeeper's `git_commit`. The commander persona keeps `tools_enabled: []` and the `game_bridge` plugin only — `persona_config` does not copy `mcp_servers`.
+
+This client is in this source (changelog 0.7.0, unreleased). The published npm package is 0.6.0 and does not include `lich mcp` or `mcp_servers`. From a clone, use `bun src/cli.ts mcp ...`. `lich --version` still prints `0.6.0`.
+
+## Add a server
+
+Paste an entry, call `catalog_client_entry`, or use the CLI. None of these start a process. New entries stay disabled until you enable them.
+
+```sh
+lich mcp add redot --project-path /home/me/game
+lich mcp enable redot
+lich mcp list
+lich mcp disable redot
+lich mcp remove redot
+```
+
+`lich mcp add redot --project-path /home/me/game` writes a disabled entry whose `command` is `redot` and whose args are `--headless --mcp-server --path` plus that directory. PATH lookup happens at connect, not at add.
+
+`lich mcp add notes --command /usr/local/bin/notes-mcp --arg --stdio` is a custom stdio server. `--url` must be loopback. The command writes through the existing config writer and leaves providers, plugins, and gateway untouched. `lich mcp list` reads this work dir's `.lich/config.json`. A missing `mcp_servers` prints nothing and exits 0.
+
+```ts
+import { catalog_client_entry } from "@moikapy/lich";
+
+catalog_client_entry("redot", { project_path: "/home/me/game" });
+```
+
+That returns a disabled stdio entry. Unknown names and the Godot catalog return an explanation instead of a spawn plan. Catalog files live in `optional-mcps/<name>/manifest.json`. A new server is a new manifest plus a config entry. It is not a new client.
+
+## Redot
+
+Official Redot 26.1+ only. The catalog command is the local `redot` binary. The args are exactly:
+
+```text
+redot --headless --mcp-server --path <project>
+```
+
+Basename must be `redot`. A missing binary tells you to install official Redot 26.1+ from [redotengine.org](https://redotengine.org). lich does not download a build.
+
+```json
+{
+  "mcp_servers": {
+    "redot": {
+      "enabled": true,
+      "command": "/usr/local/bin/redot",
+      "args": ["--headless", "--mcp-server", "--path", "/home/me/game"]
+    }
+  }
+}
+```
+
+`tools/list` is what registers. The official server lists five controllers. The client drops a listed tool named `execute` (`exclude_tools`). It does not hard-allowlist those five names: any other listed tool is registered. Existing `.gd` files stay normal file edits (`edit_file` / `write_file`). Scene edits go through the scene tool. Do not rewrite `.tscn` as text.
+
+| Registered name | Use it for |
+| --- | --- |
+| `mcp_redot_scene_action` | `.tscn` edits: nodes, properties, instances, signals |
+| `mcp_redot_resource_action` | `.tres` files and asset import metadata |
+| `mcp_redot_code_intel` | GDScript validation and engine docs |
+| `mcp_redot_project_config` | Input map, autoloads, settings, run and stop |
+| `mcp_redot_game_control` | Screenshots, clicks, and the live scene tree |
+
+## Play is the other direction
+
+These tools build and inspect the project. They do not queue combat orders. NPC and game-master play still use one `POST /message` per round, then drain `work_dir/.lich/game/orders.jsonl` and refresh `state.json`. Do not call lich per frame.
+
+Godot has no official MCP server. lich does not spawn a community godot-mcp and does not download an Asset Library addon. If you later point a **different** server name at a local binary you already have, that is a normal stdio entry. The catalog name `godot` writes no spawn plan. Play for both editors stays the [Godot guide](godot.md).

package/docs/user-guide/tui.md

@@ -9,22 +9,22 @@ lich         # front door: TUI, plus a first-run setup wizard when no config exi
 lich tui     # same TUI, no wizard. From a clone: bun src/cli.ts tui
 ```
 
-The TUI needs a TTY and a resolvable provider (same resolution as every mode). On startup it prints a dim header with `agent_name` (default `lich`), the version, and the first provider's model, e.g. `lich v0.3.0 — llama3.2 (ollama)`. Quit with `/exit`, `/quit`, `/q`, or Ctrl+C.
+The TUI needs a TTY and a resolvable provider (same resolution as every mode). On startup it prints a dim header from the active theme welcome string, e.g. `⚱ lich v0.6.0 — the agent that will not stay dead · llama3.2 (ollama)`. `{version}` is `LICH_VERSION` from `package.json`. That banner is the only tagline placement. Quit with `/exit`, `/quit`, `/q`, or Ctrl+C.
 
 ## Anatomy
 
 ```
-lich v0.3.0 — llama3.2 (ollama)        <- header: agent_name (default lich), version, model, kind
-you › list the files here              <- your input, echoed into the transcript
+⚱ lich v0.6.0 — the agent that will not stay dead · llama3.2 (ollama)
+mortal › list the files here           <- your input, echoed into the transcript
 ⏺ list_dir({})                        <- live tool-call row (name + args preview)
   ⏷ list_dir: ok (d src/ d test/ ...)  <- result row (ok/error + output preview)
-lich › Here is what I found ...        <- the agent's reply
-model llama3.2 · turns 2 · tokens 1,204 · [idle] · /path/.lich/sessions/...jsonl
+lich › Here is what I found ...        <- the agent's reply (`response_label`)
+model llama3.2 · turns 2 · tokens 1,204 · [dormant] · /path/.lich/sessions/...jsonl
 › ▌                                    <- input row (cursor block)
 ```
 
-- **Header** — static version/model/provider line.
-- **Transcript** — user lines (`you ›`), replies (`lich ›`), tool rows (`⏺ name(args)` with a result line), and meta notices (`· context compressed ...`, `· error: ...`). The view keeps the newest 50 blocks; older lines scroll out of the transcript (session JSONLs still hold everything — see [limitations](#known-limitations)).
+- **Header** — theme welcome string (version, model, provider kind). The tagline appears only here.
+- **Transcript** — user lines (`mortal ›` by default), replies (`lich ›`, or the theme `response_label`), tool rows (`⏺ name(args)` with a result line), and meta notices (`· context compressed — memories distilled ...`, `· error: ...`). The view keeps the newest 50 blocks; older lines scroll out of the transcript (session JSONLs still hold everything — see [limitations](#known-limitations)).
 - **Input row** — `› ` when idle, `… ` while the agent works; Enter submits, Backspace edits, pasted newlines collapse to spaces.
 - **Status bar** — see below.
 
@@ -36,7 +36,7 @@ model llama3.2 · turns 2 · tokens 1,204 · [idle] · /path/.lich/sessions/...j
 | `/model` | Show the active model and provider kind (from `providers[0]`). |
 | `/usage` | Show tokens used this session (cumulative across turns). |
 | `/clear` | Wipe the on-screen transcript. Does **not** reset agent memory — the next message still sees prior turns. |
-| `/sessions` | List the 10 newest `.jsonl` files in `session_dir` with sizes. |
+| `/sessions` | List the 10 newest `.jsonl` files in `session_dir` with sizes. The heading uses the theme sessions label (`phylacteries (n):` by default). |
 | `/exit`, `/quit`, `/q` | Exit the TUI. |
 
 Unknown commands print `· unknown command: /x (try /help)`. Slash commands are handled client-side and never invoke the model.
@@ -54,14 +54,14 @@ The bottom line shows, left to right:
 | `model <name>` | First provider's model from config. |
 | `turns N` | Turns used by the most recent run (resets each message). |
 | `tokens N` | Cumulative session token usage (prompt + completion, across all turns). |
-| `[idle]` / `[thinking]` / `[tool]` | Current phase: waiting for input, calling the model, or executing a tool. |
+| `[dormant]` / `[deliberating]` / `[casting]` | Current phase: waiting for input, calling the model, or executing a tool. Labels come from the theme. |
 | `compressed N` | How many times context compression fired this session (hidden when 0). |
 | `<session path>` | Path of the newest persisted transcript (appears after the first run). |
-| `· budget exhausted` | Red notice when a run hit the turn cap. |
+| `· budget exhausted — the ritual is spent (turn cap reached)` | Red notice when a run hit the turn cap. The keyword stays; the flavor comes from the theme. |
 
 ## Multi-turn memory
 
-The TUI keeps one conversation: every submitted message is sent together with the full prior message history, so the agent remembers earlier turns for as long as the session stays open. When estimated tokens cross `compress_threshold` of `context_budget_tokens`, older turns are replaced by an LLM-generated summary (the 8 most recent messages always stay verbatim) and a `· context compressed` notice appears. There is deliberately no per-conversation reset command — `/clear` only clears the display; start a fresh `lich tui` process for an empty context.
+The TUI keeps one conversation: every submitted message is sent together with the full prior message history, so the agent remembers earlier turns for as long as the session stays open. When estimated tokens cross `compress_threshold` of `context_budget_tokens`, older turns are replaced by an LLM-generated summary (the 8 most recent messages always stay verbatim) and a `· context compressed — memories distilled` notice appears. There is deliberately no per-conversation reset command — `/clear` only clears the display; start a fresh `lich tui` process for an empty context.
 
 ## Known limitations
 

package/examples/game_bridge/README.md

@@ -66,3 +66,5 @@ A round that does not match `state.json` is still appended. The tool output then
 ## Failures
 
 Tools return `{ok: false, error}` and do not throw. Reads skip malformed JSONL lines. The first call creates `.lich/game/` if it is missing. `memory.jsonl` grows forever; only the read is capped.
+
+Editor MCP builds the project. This plugin is the opposite direction: the game connects to lich. NPC and game-master play still drain `.lich/game/orders.jsonl` and the webhook. A game master is another persona, not an editor tool. See the [Redot guide](../../docs/user-guide/redot.md).

package/optional-mcps/godot/manifest.json

@@ -0,0 +1,6 @@
+{
+  "name": "godot",
+  "description": "Godot has no official MCP server. Do not download a community addon.",
+  "transport": "none",
+  "note": "Godot has no official MCP server. lich does not spawn a community addon. Play stays the webhook and examples/game_bridge: the game connects to lich. That is the opposite direction from editor MCP."
+}

package/optional-mcps/redot/manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "redot",
+  "description": "Official Redot 26.1 MCP server. lich does not ship the engine.",
+  "transport": "stdio",
+  "command": "redot",
+  "args": ["--headless", "--mcp-server", "--path", "${project_path}"],
+  "command_basename": "redot",
+  "args_prefix": ["--headless", "--mcp-server", "--path"],
+  "exclude_tools": ["execute"],
+  "missing_hint": "redot binary not found. Install official Redot 26.1+ from https://redotengine.org",
+  "tools": [
+    "scene_action",
+    "resource_action",
+    "code_intel",
+    "project_config",
+    "game_control"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moikapy/lich",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Lich — a TypeScript AI agent harness (library + CLI) inspired by Hermes",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,7 @@
     "!docs/.vitepress/dist",
     "!docs/.vitepress/cache",
     "examples/game_bridge",
+    "optional-mcps",
     "README.md",
     "CHANGELOG.md"
   ],

package/dist/chunk-6M6OAQGN.js

@@ -1,17 +0,0 @@
-// src/index.ts
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-function read_package_version() {
-  const pkg_path = fileURLToPath(new URL("../package.json", import.meta.url));
-  const pkg = JSON.parse(readFileSync(pkg_path, "utf8"));
-  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
-    throw new Error("package.json is missing version");
-  }
-  return pkg.version;
-}
-var LICH_VERSION = read_package_version();
-
-export {
-  LICH_VERSION
-};
-//# sourceMappingURL=chunk-6M6OAQGN.js.map

package/dist/chunk-6M6OAQGN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Public surface of the lich agent harness. Pure re-exports, plus the package version.\n */\nimport { readFileSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\n\nfunction read_package_version(): string {\n  const pkg_path = fileURLToPath(new URL(\"../package.json\", import.meta.url));\n  const pkg = JSON.parse(readFileSync(pkg_path, \"utf8\")) as { version?: unknown };\n  if (typeof pkg.version !== \"string\" || pkg.version.length === 0) {\n    throw new Error(\"package.json is missing version\");\n  }\n  return pkg.version;\n}\n\nexport const LICH_VERSION = read_package_version();\n\nexport { Agent, create_agent, run_agent, create_agent_with_plugins } from \"./agent/agent.js\";\nexport type { AgentRunOptions, AgentRunResult } from \"./agent/agent.js\";\nexport type { AgentConfig } from \"./agent/config.js\";\nexport { parse_agent_config } from \"./agent/config.js\";\nexport { AgentEmitter } from \"./agent/events.js\";\nexport type { AgentEvent, AgentEventHandler, AgentEvents } from \"./agent/events.js\";\nexport type { LoopOutcome, LoopParams } from \"./agent/loop.js\";\nexport type {\n  ChatOptions,\n  ChatResult,\n  Message,\n  ProviderConfig,\n  ToolCall,\n  ToolDefinition,\n  Usage,\n} from \"./providers/types.js\";\nexport { ProviderError } from \"./providers/types.js\";\nexport { ToolExecutor } from \"./tools/executor.js\";\nexport { ToolRegistry } from \"./tools/registry.js\";\nexport type { Tool, ToolContext, ToolResult } from \"./tools/types.js\";\nexport { register_builtin_tools } from \"./tools/builtin/index.js\";\nexport { HookedToolRunner } from \"./plugins/hooks.js\";\nexport { load_plugins, plugin_errors_summary } from \"./plugins/loader.js\";\nexport type { LoadedPlugin, PluginLoadError } from \"./plugins/loader.js\";\nexport type {\n  AfterToolCallInfo,\n  BeforeToolCallInfo,\n  BeforeToolCallResult,\n  HookContext,\n  Plugin,\n  PluginHooks,\n  RunEndInfo,\n} from \"./plugins/types.js\";"],"mappings":";AAGA,SAAS,oBAAoB;AAC7B,SAAS,qBAAqB;AAE9B,SAAS,uBAA+B;AACtC,QAAM,WAAW,cAAc,IAAI,IAAI,mBAAmB,YAAY,GAAG,CAAC;AAC1E,QAAM,MAAM,KAAK,MAAM,aAAa,UAAU,MAAM,CAAC;AACrD,MAAI,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,WAAW,GAAG;AAC/D,UAAM,IAAI,MAAM,iCAAiC;AAAA,EACnD;AACA,SAAO,IAAI;AACb;AAEO,IAAM,eAAe,qBAAqB;","names":[]}