feat(config): named profiles in ~/.lich/profiles

[Moikapy]

Part of #117. This is PR C, covering Phase 2: named profiles. It builds on the global config work in #170 and #171. With it, every acceptance criterion in #117 is met.

Behavior

• Files: ~/.lich/profiles/<name>.json holds any config keys. An optional ~/.lich/profiles/<name>.md (the soul file) becomes the profile's system_prompt when it isn't blank, replacing any system_prompt in the JSON. A profile can also be just the .md file.
• Layers: global, then profile, then project. Each later layer wins per key, and each step uses the same merge as feat(config): global ~/.lich/config.json merged under the project config #170 (a later providers drops the earlier models unless that layer sets its own). A profile ignores work_dir and session_dir, and its relative plugin paths resolve against ~/.lich/profiles/.
• Selection: --profile <name>, then LICH_PROFILE, then a profile key in the project config, then the default profile (a profile key in ~/.lich/config.json). The profile key is removed from the merged config.
• Errors: a missing profile reports profile not found: <name>. Names must match ^[a-z0-9][a-z0-9_-]*$, so ../x is rejected. --profile together with --config is an error.
• Wizard: when --profile or LICH_PROFILE is set, bare lich skips the first-run wizard.
• lich profile (new src/cli_profile.ts):
  • list: * marks the default, (soul) marks a profile that has a .md file.
  • show <name>: prints the JSON and the soul file's path and length.
  • create <name>: runs the setup wizard into the profile file. It needs a TTY and never overwrites, and it doesn't pick up project plugins.
  • use <name>: sets profile in ~/.lich/config.json through the atomic update writer, keeping the file's other keys.
• Guard: file tools refuse .lich/profiles/ for both reads and writes. This adds a read block alongside the existing .lich write rule. When work_dir is the home directory, these are the global identity files.

A related fix

lich tui, chat, serve and gateway used to replace every config error with "no model configured". That would have turned profile not found into a misleading hint. Now only the missing-model error gets the hint; any other error passes through as lich <mode>: <message>.

Decisions (asked before implementing)

• A profile merges over the global config rather than replacing it.
• The default profile is stored as a profile key in ~/.lich/config.json.
• create is included.

Not included: showing the active profile in the TUI banner, which #117 lists as an optional follow-up.

Tests

• cli_config.test.ts:
  • layer order and the resolution of profile plugin paths;
  • the soul file against the JSON system_prompt and the project system_prompt, and a blank soul file being ignored;
  • selection precedence (flag, env, project key, global key);
  • errors for a missing profile and a bad name.
• first_run.test.ts (each test uses an empty HOME, with LICH_PROFILE cleared):
  • profile create through the wizard, plus a refused second create;
  • profile use keeping the other global keys, the profile list output, and use of an unknown name;
  • --profile skipping the wizard and loading the profile;
  • --profile with --config rejected;
  • lich tui: profile not found: ghost.
• tools.test.ts: read_file and write_file on .lich/profiles/ are refused.
• The first_run mock of write_lich_config now passes the update argument through. It used to drop it.
• Mutation check: I removed the guard rule, the wizard skip, the error passthrough and the soul injection in turn, and a test failed each time.

Checks

• tsc --noEmit: clean.
• vitest: 697/699 pass. The two failures happen only in this container: serve_transport "accepts ::1 clients" (no IPv6) and tools_review_shouldfix S-6 (process-group zombies).
• vitepress build docs: passes. There's a new guide, docs/user-guide/profiles.md, added to the sidebar; docs/user-guide/cli.md and the CHANGELOG are updated.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LHQAfXHofy6QkAgmfmJava

---

Generated by Claude Code

[cursor]

Stale comment

PR #172 — Risk: HIGH (new public CLI: lich profile, --profile, LICH_PROFILE; trust-boundary change in assert_file_tool_access; 463 additions / 11 files, not a docs-only patch)
Findings: Critical 0 / Warning 2 / Suggestion 2 (src/cli_config.ts:152 merge profile over the home config; src/cli_config.ts:110 and src/cli_profile.ts:81 drop absolute paths; src/cli.ts:422 reject LICH_PROFILE with --config; src/tools/guard.ts:82 list_dir / disk_usage skip the new deny)
Regressions of settled findings: none
Not reviewed: CI conclusions (typecheck_and_test 20/22 and ossuary were still running). Static review of the 11-file diff only; tests were not run.
Action: escalated to @Moikapy. Auto-merge left off. needs-review added. Not merged.
Log: 2026-10-05T02:30:34Z, escalated, HIGH public CLI plus file-tool guard, two warnings (home-dir profile merge, absolute paths in new errors). Also a merge blocker: commits on this branch are authored by Claude, not @Moikapy, and this run has no approved-bot list.

  

_{Sent by Cursor Automation: PR REVIEW}

[cursor]

Stale comment

PR #172 — Risk: HIGH (public CLI lich profile, --profile, and LICH_PROFILE; file-tool deny for .lich/profiles; 510 additions)
Findings: Critical 0 / Warning 2 / Suggestion 0 (src/cli_config.ts:154 legacy config dropped when work_dir is home and ~/.lich/config.json is absent; src/tools/builtin/disk_usage.ts:71 parent disk_usage still measures forbidden children)
Regressions of settled findings: none. Home profile-over-global, profile not found / already exists without paths are fixed. LICH_PROFILE with --config stays ignored, as decided.
Not reviewed: none
Action: escalated to @Moikapy
Log: 2026-10-05T02:40:00Z, escalated, HIGH after the fix commit; two warnings in eaadb017..ae7e9d84. Auto-merge left off. needs-review already present. Not merged. CI green (typecheck 20/22, ossuary, wiki_lint). Head commit author claude. Static review only.

  

_{Sent by Cursor Automation: PR REVIEW}

[cursor]

PR #172 — Risk: HIGH (public CLI lich profile, --profile, and LICH_PROFILE; file-tool deny for .lich/profiles; 536 additions)
Findings: Critical 0 / Warning 0 / Suggestion 0
Regressions of settled findings: none. With work_dir = home, a legacy ~/.config/lich/config.json stays the base when ~/.lich/config.json is absent, and the profile still merges over that file when it exists. disk_usage of .lich skips denied children (profiles, config.json) and leaves them out of TOTAL.
Not reviewed: CI conclusions for typecheck_and_test (20) and (22), still in progress. Static review of ae7e9d84..2d64bbf only; tests were not run.
Action: escalated to @Moikapy
Log: 2026-10-05T02:39:06Z, escalated, HIGH after the fix commit; prior warnings are fixed and not regressed. Auto-merge left off. needs-review already present. Not merged. Head commit author claude (outside the example approved-bot set). Static review only.

  

_{Sent by Cursor Automation: PR REVIEW}