The README had grown to 1,010 lines of user docs and design notes in one file,
and had gone stale: it still showed the old numbered menu, set up only three
providers, and listed preflight checks and a file layout that predate the last
three releases. It now carries install, first run, the full command
reference, the providers at a glance, troubleshooting and a docs index.
docs/:
- providers.md presets, defaults, the model cache, context windows, each
provider (OpenRouter's cost guard and guardrail check are
written up for the first time), adding a provider
- live-sessions.md what a switch does to running sessions, and repair
- design.md why settings.json, why keys stay out of it (and the vault
per platform), the preflight checks as they are now
- bar-widget.md the widget as it is now: providers from health.json, every
server provider's settings, the restart after an upgrade
- architecture.md the pieces, every file on disk and who writes it, the
contracts between them, where to change what
- development.md running the tests, the conventions the code follows,
working on the widget, releasing
CONTRIBUTING.md points at it.
Also:
- The per-project session listing used awk, which the CLI avoids because it
is missing from minimal images; it uses the script's own TSV helpers now,
and tests/static.sh fails on any awk in the CLI.
- tests/static.sh checks every relative Markdown link and #anchor.
- A unit test pins the managed env keys between cm-json.py and
claude-mode.ps1, which only a comment kept in step before.
- test_sessions covers the per-project listing, which nothing ran.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A test suite with no dependencies beyond bash and the Python standard
library, run by one command:
scripts/test.sh (or: make test)
scripts/test.sh --windows [host] adds the PowerShell suite over SSH
- tests/static.sh: script syntax, JSON validity, VERSION against the widget
manifest and CHANGELOG, providers.json against the kinds, probes and checks
the code implements (and ids that would shadow a command), qmllint and
shellcheck when installed.
- tests/python: unit tests for cm-json.py - providers and the column contract
bash depends on, the original three scaffolds byte for byte, every
catalogue parser and the cache, session scan/dismiss/repair, rename,
defaults, health, the cost guard.
- tests/cli: the CLI in a sandbox with its own HOME, CM_ROOT,
CLAUDE_CONFIG_DIR and a file-only vault, against fake Ollama, LM Studio,
keyed-gateway and proxy servers - preflight, presets, models, doctor, a real
switch, sessions, and the key helper under a rename race.
- tests/windows: the same idea on a Windows host, with USERPROFILE pointed at
a temp folder so the real install is never touched.
Also: MIT licence, CHANGELOG.md reconstructed from history, .editorconfig and
.gitattributes pinning LF everywhere (what the tree already is), and
scripts/bump-version.sh, since the version lives in two files and drifted
once before.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
