docs: add comprehensive documentation for AI agents, chezmoi workflow, shell setup, desktop configuration, terminal multiplexers, and developer tools

docs/ai/index.mdx

@@ -0,0 +1,65 @@
+---
+title: AI agents
+description: Claude Code, omp, and the shared agent skill library that both read from.
+sidebar:
+  label: Overview
+---
+
+The repo manages configuration for two coding agents and a skill library they share. Neither agent binary is installed by chezmoi: `.chezmoidata/packages.yaml` lists no agent CLIs, so install Claude Code and omp yourself. topgrade runs `omp update` as a custom command.
+
+<CardGroup cols={3}>
+  <Card title="Claude Code" href="/ai/claude-code" icon="terminal">
+    Settings, hooks, plugins, slash commands, and skill links under `~/.claude`.
+  </Card>
+  <Card title="omp" href="/ai/omp" icon="cpu">
+    Config, keybindings, MCP servers, theme, commands, and scheduled research loops under `~/.omp`.
+  </Card>
+  <Card title="Skills" href="/ai/skills" icon="library">
+    The `~/.agents/skills` library, its lock file, and the symlinks that expose it to Claude Code.
+  </Card>
+</CardGroup>
+
+## Pages
+
+| Page | Source in repo | Target in `$HOME` | Covers |
+| --- | --- | --- | --- |
+| [Claude Code](/ai/claude-code) | `dot_claude/` | `~/.claude/` | `settings.json`, hook scripts, `/commands`, empty `CLAUDE.md`, skill symlinks |
+| [omp](/ai/omp) | `dot_omp/` | `~/.omp/` | `agent/config.yml`, `keybindings.yml`, `mcp.json`, cyberdream theme, commands, loops |
+| [Skills](/ai/skills) | `dot_agents/` | `~/.agents/` | `.skill-lock.json` and every skill directory |
+
+## Layout
+
+<FileTree>
+
+- dot_claude/
+  - settings.json
+  - empty_CLAUDE.md
+  - commands/
+  - hooks/
+    - executable_cmem-to-obsidian.py
+    - executable_herdr-agent-state.sh
+    - gitnexus/
+  - skills/
+- dot_omp/
+  - private_agent/
+    - private_config.yml
+    - keybindings.yml
+    - private_mcp.json
+    - themes/
+    - commands/
+  - loops/
+    - bin/
+    - goals/
+- dot_agents/
+  - dot_skill-lock.json
+  - skills/
+
+</FileTree>
+
+None of these files are role-gated: `.chezmoiignore.tmpl` applies them on every machine role (desktop, laptop, mac, server).
+
+## Shell entry points
+
+- `ai` (fish function) opens a `gum choose` picker over `claude`, `opencode`, `codex`, `hermes`, and `fractal`. Picking `claude` runs `claude --dangerously-skip-permissions`; the others run the binary of the same name. See [fish](/shell/fish).
+- <kbd>Ctrl</kbd> <kbd>A</kbd> launches `omp` from the fish and zsh prompts.
+- `launch_omp_livediff_overlay` and `lc-elir` are omp helpers in `~/.local/bin`; see [omp](/ai/omp#shell-integration) and [scripts](/shell/scripts).