First pass on updates for Quattro

manual/13-ai.md

@@ -1,21 +1,38 @@
 # AI
 
-Omarchy ships with [OpenCode](https://opencode.ai/) and [Claude Code](https://code.claude.com/docs/en/overview) as the default agent harnesses for programmers. OpenCode lets you use models from all the major commercial providers as well as the rapidly improving open-weight models.
+Omarchy treats AI coding agents as first-class citizens, but it doesn't pick a favorite for you. Instead, every major coding-agent CLI comes pre-wired as a lazy-loaded launcher. The launchers are tiny [mise](https://mise.jdx.dev/)-managed stubs in `~/.local/bin/`, so nothing is downloaded until the first time you actually run one. Invoke any of these and authenticate when prompted:
 
-The best way to use OpenCode is by going to the directory you're going to work on in the terminal, then invoke the `c` alias to start OpenCode within that directory. Claude Code let's you use Anthropic's models with their proprietary subscriptions, and can be started in danger mode using the `cx` alias.
+| Command    | Agent                                                            |
+|------------|------------------------------------------------------------------|
+| `claude`   | [Claude Code](https://code.claude.com/docs/en/overview)          |
+| `codex`    | [OpenAI Codex](https://github.com/openai/codex)                  |
+| `opencode` | [OpenCode](https://opencode.ai/)                                 |
+| `gemini`   | [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) |
+| `copilot`  | [GitHub Copilot CLI](https://github.com/github/copilot-cli)      |
+| `crush`    | [Crush](https://github.com/charmbracelet/crush)                  |
+| `grok`     | Grok CLI from xAI                                                |
+| `pi`       | [Mario Zechner's Pi](https://github.com/badlogic/pi-mono)        |
+| `omp`      | [Oh My Pi](https://github.com/can1357/oh-my-pi)                  |
 
-### Alternative agent CLIs
+To wrap an additional CLI the same way, run `omarchy-mise-install <package> [command-name]`. The stubs are kept current along with everything else mise manages when you run `omarchy update` (or the `mup` alias).
 
-Beyond the default `c` (OpenCode) and `cx` (Claude Code) aliases, Omarchy ships pre-wired lazy-loaded launchers for every major coding-agent CLI. The launchers themselves are tiny shell stubs in `~/.local/bin/`, so on first run, each one fetches its npm package through npx against a mise-managed node@latest, so nothing is downloaded until you actually invoke it. Run any of these and authenticate when prompted:
+### The default agent
 
-| Command  | Package                       | Provider                              |
-|----------|-------------------------------|---------------------------------------|
-| `codex`    | @openai/codex                 | [OpenAI Codex](https://github.com/openai/codex) |
-| `gemini`   | @google/gemini-cli            | [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) |
-| `copilot`  | @github/copilot               | [GitHub Copilot CLI](https://github.com/github/copilot-cli) |
-| `pi`       | @mariozechner/pi-coding-agent | [Mario Zechner's Pi](https://github.com/badlogic/pi-mono) |
+Pick your default agent with `omarchy default agent <name>` or under _Setup > Defaults > Agent_ in the Omarchy Menu (`Super + Space`). If the agent isn't installed yet, picking it installs it first. A fresh Omarchy will invite you to make this choice with a one-time notification.
 
-To wrap an additional npm-published CLI the same way, run `omarchy-npx-install <package> [command-name]`.
+Once you've chosen, `Super + Shift + Ctrl + A` launches the default agent in a dedicated terminal window (or brings up the picker if you haven't chosen yet). You can also launch it straight into a task with `omarchy agent prompt "Review this project"`. Agents launched this way run unattended in their respective don't-stop-to-ask modes, so be ready for them to actually do things! And since agents refuse to remember trust for your home directory, launches from `$HOME` start in `~/Work` instead.
+
+There are terminal shortcuts too: `a` runs the default agent inline in the current terminal, while `c`, `cx`, and `cy` start OpenCode, Claude Code, and Codex directly (again in their auto-approving modes). Theme changes sync to the agents as well: Claude Code, Pi, and OpenCode all follow along when you switch the Omarchy theme.
+
+### The agents panel
+
+The top bar grows an agents icon the first time Omarchy finds AI coding usage on the machine (and stays out of the way until then). The panel behind it tracks every subscription in one place: your plan, the percentage used of the 5-hour session and weekly limits (or the remaining prepaid balance), and token usage by day and by model. Claude Code, Codex, and Fireworks are covered out of the box.
+
+Left-click the bar icon for the panel, right-click to launch your default agent. The usage records behind it are regenerated every 15 minutes by `omarchy agent usage-update`, and the panel can even merge usage from your other machines via a synced folder. See the README under `$OMARCHY_PATH/shell/plugins/agents/` for the full settings.
+
+### Crash diagnosis
+
+Omarchy watches systemd-coredump for process crashes. When something segfaults, you'll get a "Process crashed" notification — click it, and the crash is handed to your default agent along with Omarchy's diagnose-crash skill, which walks the agent through establishing the facts from the core dump and deciding whether the crash is worth reporting upstream. You can also run it by hand against any PID from `coredumpctl list` with `omarchy agent crash <pid>`.
 
 ### Local LLMs
 
@@ -23,6 +40,6 @@ Omarchy recommends two ways of running local LLM models: LM Studio and Ollama. L
 
 ### The Omarchy Skill
 
-Agent skills help AI use specific tools in a specific way, and Omarchy ships with a default skill for tailoring the system. Like making changes to waybar or even creating a new theme from scratch. It's automatically configured in OpenCode (and Claude Code and any other harness that supports `~/.claude/skills`).
+Agent skills help AI use specific tools in a specific way, and Omarchy ships with a default skill for tailoring the system. Like tweaking your Hyprland config, adjusting the bar, or even creating a new theme from scratch. It's symlinked into the skill directories for Claude Code (`~/.claude/skills`), Codex (`~/.codex/skills`), Pi (`~/.pi/agent/skills`), and the generic `~/.agents/skills` location, so most harnesses pick it up automatically.
 
 But you should treat this skill as experimental. Different models will use it to different effect. It's best to run in plan mode first, so you have an idea of what the agent would like to change. And then be ready to rollback changes or even invoking `omarchy reinstall configs`, if the agent makes a mess of everything.