README down to what a user needs; the rest into docs/

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>

docs/bar-widget.md

@@ -0,0 +1,117 @@
+# The Omarchy bar widget
+
+An icon in the Omarchy top bar showing which provider the next `claude` launch
+will use, and a panel that switches it — and edits presets — without a terminal.
+
+```bash
+bash omarchy/install.sh
+omarchy restart shell
+```
+
+The installer copies the plugin to `~/.config/omarchy/plugins/smoido.claude-mode/`
+and adds its id to the bar layout in `~/.config/omarchy/shell.json` (backed up
+first). Placement is `right`, before `omarchy.agents`; `CM_BAR_SECTION` and
+`CM_BAR_BEFORE` override that at install, and `omarchy bar move
+smoido.claude-mode --section <section>` moves it later.
+
+**Restart the shell after installing or upgrading.** The shell does reload a
+plugin whose files change, but it clears Qt's component cache while the old
+widget is still alive, so the old compiled panel survives the reload —
+`omarchy-shell shell rescanPlugins` does not shift it either.
+
+## The icon
+
+The icon is the mode, drawn as the provider's own mark: the Claude burst, the
+OpenRouter arrow, the Z.AI Z, the LM Studio mark, the Ollama llama, and `< >` for
+a custom endpoint. Anything other than Anthropic takes the theme accent, so the
+bar stays quiet exactly when nothing unusual is configured. A dot on it means a
+session needs repair ([live sessions](live-sessions.md#the-bar-notices-for-you));
+it is a dot rather than a colour change, because recolouring the mark would
+misreport the mode.
+
+### The marks
+
+They are vector paths drawn with `QtQuick.Shapes`, not font glyphs — most have
+no Nerd Font pictograph at all, and paths take the bar's foreground colour and
+follow the theme. They come from [simple-icons](https://simpleicons.org) (Claude,
+OpenRouter, LM Studio, Ollama) and [lobe-icons](https://github.com/lobehub/lobe-icons)
+(Z.AI); the `< >` is drawn here. Trademarks belong to their owners.
+
+Each provider's mark and its `logoScale` live in `providers.json`, which reaches
+the widget through `health.json`; `Modes.js` keeps only Anthropic's and a
+fallback for an older `health.json`. The scale corrects apparent size, because
+equal nominal size is not equal apparent size: LM Studio's filled container
+covers 69% of its box against ~38% for most others, and Z.AI and OpenRouter are
+wide-but-short marks whose ink spans only ~84% of the box height. A scale starts
+from the geometric mean of the two corrections and is then settled by eye; the
+Ollama and custom marks were also held to 1.0 or less of their box, since both
+already fill its height.
+
+Three details keep them from looking ragged in a 13px slot, which is what every
+stock glyph in this bar measures:
+
+- **No layer.** A layer rasterises the Shape at its own size and then scales the
+  *texture*. Without one, the scale is a transform on the geometry and
+  rasterisation happens once, at final resolution.
+- **`Shape.CurveRenderer`** (Qt 6.6+) rasterises curves analytically instead of
+  tessellating them into antialiased triangles.
+- **An odd `iconSize`.** The marks are radially symmetric, so their arms sit on the
+  centre line — a pixel *centre* at an odd size, the seam between two pixels at an
+  even one, where each arm greys out. Even values are rounded up.
+
+## The panel
+
+**Click** the icon: current mode, every mode with the active one ticked, and the
+model map behind a gateway. Picking a gateway unfolds its presets rather than
+switching blind; picking a preset starts the switch. Each provider's list ends in
+**New … preset…**.
+
+Choosing a target does not switch immediately. It runs the same two checks the
+CLI does, and both can stop it:
+
+1. **Preflight.** If the mode has not been set up, has no key, has no models, has
+   no address, or its server is not answering, the panel says which and offers the
+   fix: *Set up …* opens a terminal and runs the first-run flow there (a bar popup
+   can host neither a hidden key prompt nor a filter-select list), *Store the
+   key…* opens a terminal for just the prompt, *Edit preset…* opens the editor,
+   *Server settings…* opens the server form, and *Check again* re-runs the
+   preflight.
+2. **Running sessions.** If any are running, the panel lists them by terminal and
+   directory, marks any that are mid-request, and asks: *Switch and restart*,
+   *Switch and close*, *Switch only*, or *Cancel*. The session action runs
+   strictly **after** the write — restarting first would bring them back up on
+   the provider being left.
+
+**The gear** on a preset row opens the preset editor: its four tiers, each with
+the model it maps to. Clicking a tier opens one field that filters the provider's
+models as you type (every word must match; ↓/↑ and Enter work), listed with
+context length and price. The list is the [model cache](providers.md#the-model-cache),
+so the panel never touches the network on its own; *Fetch models* / *Refresh
+list* runs `models --refresh`. Any id can also be typed by hand. The editor also
+has **Make default** / **Clear default**, **Duplicate…**, **Rename…** and
+**Delete…** (greyed out, with the reason, on the preset in use), and — for a
+server provider — **Server settings…**: the base URL, *Use local default* where
+the provider has one, and whether that server needs an API key.
+
+Editing the preset in use applies it at once; [providers.md](providers.md#editing-the-preset-in-use)
+says why that does not ask about running sessions.
+
+- **Esc** closes the panel. While it is open the panel holds the keyboard, as
+  every other shell panel does, so its text fields can be typed into.
+- **Right-click** switches straight back to Anthropic.
+- **Middle-click** re-reads state.
+- **Hover** for mode, preset, and the opus/sonnet mapping.
+
+A failed action — a preset whose key was never stored is the common one —
+surfaces the CLI's own error in the panel rather than looking like a click that
+did nothing.
+
+## Settings
+
+Per instance, in the widget's entry in `~/.config/omarchy/shell.json`:
+
+| key | default | meaning |
+|---|---|---|
+| `showLabel` | `false` | show the preset name beside the icon |
+| `iconSize` | `13` | mark size in px; rounded up to odd |
+| `root` | `~/.claude-mode` | where claude-mode is installed |