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

docs/ai/claude-code.mdx

@@ -0,0 +1,200 @@
+---
+title: Claude Code
+description: Claude Code settings, hooks, plugins, slash commands, and skill links managed under ~/.claude.
+---
+
+Claude Code is Anthropic's terminal coding agent. The repo manages its user-level settings, hook scripts, custom slash commands, and the skill links it loads. The `claude` binary itself is not installed by chezmoi.
+
+## Files
+
+| Source in repo | Target | Notes |
+| --- | --- | --- |
+| `dot_claude/settings.json` | `~/.claude/settings.json` | Plain file; in symlink mode the target is a symlink back into the repo |
+| `dot_claude/empty_CLAUDE.md` | `~/.claude/CLAUDE.md` | `empty_` keeps the zero-byte file; no global memory instructions |
+| `dot_claude/hooks/executable_cmem-to-obsidian.py` | `~/.claude/hooks/cmem-to-obsidian.py` | Executable |
+| `dot_claude/hooks/executable_herdr-agent-state.sh` | `~/.claude/hooks/herdr-agent-state.sh` | Executable, generated by herdr |
+| `dot_claude/hooks/gitnexus/gitnexus-hook.cjs` | `~/.claude/hooks/gitnexus/gitnexus-hook.cjs` | Present but not wired in `settings.json` |
+| `dot_claude/commands/*.md` | `~/.claude/commands/*.md` | User slash commands |
+| `dot_claude/skills/symlink_*` | `~/.claude/skills/*` | Symlinks into `~/.agents/skills` |
+| `dot_claude/skills/<dir>/` | `~/.claude/skills/<dir>/` | Claude-only skills kept as real directories |
+
+None of these are role-gated. Hook commands in `settings.json` use absolute `/home/prad/...` paths; on a machine with a different home directory, edit them after cloning.
+
+## settings.json
+
+### Model and UI
+
+| Key | Value | Effect |
+| --- | --- | --- |
+| `model` | `fable` | Default model alias |
+| `tui` | `fullscreen` | Full-screen terminal UI |
+| `agentPushNotifEnabled` | `true` | Push notifications when the agent needs attention |
+| `skipDangerousModePermissionPrompt` | `true` | No confirmation when starting in bypass-permissions mode |
+| `skipAutoPermissionPrompt` | `true` | No confirmation when entering auto mode |
+
+No `statusLine` is configured; Claude Code uses its default status line.
+
+### Environment
+
+`env` sets two variables for every session:
+
+| Variable | Purpose |
+| --- | --- |
+| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Turns off Claude Code's built-in auto memory. Session memory comes from the claude-mem plugin instead. |
+| `EDITOR` | Points the external editor at `micro`. |
+
+### Permissions
+
+- `defaultMode` is `auto`, so sessions start in auto mode and the classifier approves routine actions.
+- The `allow` list pre-approves seven read-only tools from the `codegraph` MCP server: `codegraph_search`, `codegraph_context`, `codegraph_callers`, `codegraph_callees`, `codegraph_impact`, `codegraph_node`, and `codegraph_status`.
+- There is no `deny` or `ask` list.
+
+`autoMode.environment` is a list of trust-boundary notes that auto mode reads when judging risk. It declares no org, cloud provider, secrets manager, or CI target. It names one private personal LeetCode repository as the trusted repo and treats routine work there as low risk. It marks `.env*` files as sensitive. Any host, namespace, or container with `prod` or `production` as a whole name segment counts as a sensitive remote target. IaC changes touching IAM, RBAC, networking, quota, and node pools count as protected.
+
+### Hooks
+
+`settings.json` wires six hook commands:
+
+| Command | What it does |
+| --- | --- |
+| `pixtuoid-hook` | External binary that receives lifecycle events. Matcher `.*`. |
+| `~/.orca/agent-hooks/claude-hook.sh` | Orca's agent hook. Runs through `/bin/sh` only if the file exists and is executable, so machines without Orca skip it silently. |
+| `atuin hook claude-code` | Records the agent's `Bash` tool calls in [atuin](/shell/atuin) history. Matcher `Bash`. |
+| `python3 ~/.claude/hooks/cmem-to-obsidian.py` | Exports the session's claude-mem learnings to Obsidian ([below](#cmem-to-obsidian)). 15 s timeout. |
+| `bash ~/.claude/hooks/herdr-agent-state.sh session` | Reports the session to herdr ([below](#herdr-agent-state)). 10 s timeout. |
+| `sh ~/skills/tldraw-offline/inject-server-context.sh SubagentStart` | Injects server context when the `tldraw-offline` subagent starts. The script lives outside this repo. |
+
+Event wiring:
+
+| Event | pixtuoid | orca | atuin (`Bash`) | Other |
+| --- | :-: | :-: | :-: | --- |
+| `SessionStart` | yes | | | herdr-agent-state `session` |
+| `UserPromptSubmit` | | yes | | |
+| `PreToolUse` | yes | yes | yes | |
+| `PermissionRequest` | | yes | | |
+| `PostToolUse` | yes | yes | yes | |
+| `PostToolUseFailure` | | yes | yes | |
+| `Notification` | yes | | | |
+| `SubagentStart` | yes | | | tldraw-offline context (matcher `tldraw-offline`) |
+| `SubagentStop` | yes | | | |
+| `Stop` | | yes | | |
+| `StopFailure` | | yes | | |
+| `SessionEnd` | yes | | | cmem-to-obsidian |
+
+### Plugins
+
+`enabledPlugins`:
+
+| Plugin | Marketplace | State |
+| --- | --- | --- |
+| `caveman` | `caveman` | enabled |
+| `claude-mem` | `thedotmack` | enabled |
+| `context-mode` | `context-mode` | enabled |
+| `context7` | `claude-plugins-official` | disabled |
+| `council` | `council-of-high-intelligence` | enabled |
+| `exa` | `claude-plugins-official` | enabled |
+| `frontend-design` | `claude-plugins-official` | enabled |
+| `gopls-lsp` | `claude-plugins-official` | enabled |
+| `gopls` | `claude-code-lsps` | enabled |
+| `lua-lsp` | `claude-plugins-official` | enabled |
+| `ponytail` | `ponytail` | enabled |
+| `solidity-language-server` | `claude-code-lsps` | enabled |
+| `understand-anything` | `understand-anything` | enabled |
+| `vtsls` | `claude-code-lsps` | enabled |
+| `yaml-lsp` | `zircote-lsp` | enabled |
+| `diagram-design` | `diagram-design` | enabled |
+
+The LSP plugins give the agent language-server diagnostics for Go, Lua, Solidity, TypeScript/JavaScript (vtsls), and YAML.
+
+### Marketplaces
+
+`extraKnownMarketplaces` registers eleven plugin sources:
+
+| Name | Source |
+| --- | --- |
+| `caveman` | GitHub `JuliusBrussee/caveman` |
+| `claude-code-lsps` | GitHub `Piebald-AI/claude-code-lsps` |
+| `claude-plugins-official` | GitHub `anthropics/claude-plugins-official` |
+| `council-of-high-intelligence` | GitHub `0xNyk/council-of-high-intelligence` |
+| `mempalace` | GitHub `MemPalace/mempalace` |
+| `omc` | git `https://github.com/Yeachan-Heo/oh-my-claudecode.git` |
+| `ponytail` | GitHub `DietrichGebert/ponytail` |
+| `thedotmack` | GitHub `thedotmack/claude-mem` |
+| `understand-anything` | GitHub `Egonex-AI/Understand-Anything` |
+| `zircote-lsp` | GitHub `zircote/lsp-marketplace` |
+| `diagram-design` | GitHub `cathrynlavery/diagram-design` |
+
+`mempalace` and `omc` are registered but no plugin from them is enabled. `context-mode` is enabled but its marketplace is not declared here; it comes from Claude Code's own marketplace state.
+
+## Hook scripts
+
+### cmem-to-obsidian.py [#cmem-to-obsidian]
+
+A stdlib-only Python script run on `SessionEnd`. It reads the hook JSON from stdin and exports that session's claude-mem observations to an Obsidian note. It fails soft: any error is logged and the script exits 0, so it never blocks the session.
+
+1. Opens the claude-mem SQLite database read-only (`?mode=ro`), so it never locks the live DB or its WAL.
+2. Maps the Claude Code `session_id` to claude-mem's memory session via `sdk_sessions.content_session_id`, then loads that session's observations and latest summary.
+3. Drops any observation containing `<private>`.
+4. Writes `<vault>/<project>/<date> <project> <session-prefix>.md`. The file name is keyed to the session, so re-runs overwrite the same note.
+5. Creates `<vault>/<project>.md` as a map-of-content note if it is missing, so the `[[project]]` wikilink resolves.
+
+Note layout: frontmatter (`date`, `project`, `session`, `source: claude-mem`, tags `claude-mem` and `project/<slug>`), an abstract callout from the session summary, then sections by observation type. Each bullet links back to the claude-mem viewer at `http://localhost:<port>/?observation=<id>`.
+
+| Section | Observation types |
+| --- | --- |
+| Decisions | `decision` (rendered as note callouts) |
+| Fixes & gotchas | `bugfix` |
+| Insights | `discovery`, `feature`, `change`, `refactor`, plus any unmapped type |
+
+| Variable | Default |
+| --- | --- |
+| `CLAUDE_MEM_DB` | `~/.claude-mem/claude-mem.db` |
+| `CMEM_OBSIDIAN_DIR` | `~/Documents/Vault/90 - Archive/Learnings` |
+| `CLAUDE_MEM_WORKER_PORT` | `37700` |
+
+Log file: `~/.claude/hooks/cmem-to-obsidian.log`.
+
+### herdr-agent-state.sh [#herdr-agent-state]
+
+Generated and versioned by [herdr](/terminal/herdr) (integration id `claude`, version 7). The header says reinstalling herdr's integration overwrites it, so put custom hooks in separate files. It runs on `SessionStart` with the `session` action and exits immediately for any other action.
+
+It only acts inside a herdr pane: `HERDR_ENV=1`, `HERDR_SOCKET_PATH`, and `HERDR_PANE_ID` must be set, and `python3` must be on `PATH`. It then sends one `pane.report_agent_session` request over herdr's Unix socket with the pane id, the Claude session id, the transcript path, and the session start source. herdr uses this to link the pane to the agent session. Subagent events and `SubagentStop` are ignored, so a finished subagent cannot mark an idle pane as working again. Socket errors are swallowed and the script has a 0.5 s timeout.
+
+### gitnexus/gitnexus-hook.cjs
+
+A Node `PreToolUse` handler that adds GitNexus code-graph context to searches. `settings.json` does not reference it, so it is inactive until you add a hook entry.
+
+- Runs only when `.gitnexus` exists in the working directory or one of its four nearest ancestors.
+- Pulls a search pattern from `Grep` (the pattern), `Glob` (the first identifier-like path segment), or `Bash` commands that call `rg` or `grep` (the first non-flag argument). Patterns under three characters are skipped.
+- Runs `gitnexus augment <pattern>`. It tries the bun global install at `~/.bun/install/global/node_modules/gitnexus` first, then `require.resolve`, then `npx -y gitnexus` (8 s or 15 s timeout).
+- Returns the CLI's stderr output as `hookSpecificOutput.additionalContext`.
+
+## Slash commands
+
+`dot_claude/commands/` becomes `~/.claude/commands/`, one user-level slash command per file.
+
+| Command | Arguments | Purpose |
+| --- | --- | --- |
+| `/bd-drain` | optional priority filter (`p0-p2`), epic id, or `dry-run` | Works through every open beads issue until all are closed with tests and builds passing. Records a green baseline first; `dry-run` prints the dependency-sorted plan and stops. Allowed tools: `bd`, `git`, `go`, `pnpm`, `cargo`, `make`, file tools, `Task`. |
+| `/cmem-to-beads` | none | Pulls insight, decision, and gotcha learnings out of claude-mem and saves them as beads memories with `bd remember`. Actionable items are skipped. |
+| `/cmem-to-linear` | none | Turns actionable claude-mem learnings (bugs, tech debt, follow-ups) into beads tasks, then pushes the new ones to Linear. |
+| `/create-task` | `<task description or goal>` | Breaks a task into beads issues with dependencies, acceptance criteria, and priorities. The prompt includes live `bd ready`, in-progress, and recently-closed lists. Allowed tools: `bd`, `git log`, `git status`, `rg`, `Task`. |
+| `/rams` | optional file | "Rams" accessibility (WCAG 2.1) and visual design review of a component file. Offers a project scan when no file is given. |
+| `/web-interface-guidelines` | `<file-or-pattern>` | Reviews UI code against the Vercel Web Interface Guidelines: accessibility, focus, forms, animation, typography, and more. |
+
+## Skills
+
+`~/.claude/skills/` holds two kinds of entries:
+
+- **Symlinks** (`symlink_<name>` in the source). Each file contains a relative target such as `../../.agents/skills/blume`, so `~/.claude/skills/blume` resolves to `~/.agents/skills/blume`. The shared library is documented on the [Skills](/ai/skills) page.
+- **Real directories** for Claude-only skills: `absurd`, `agents-sdk`, `cloudflare`, `cloudflare-email-service`, `cloudflare-one`, `cloudflare-one-migrations`, `create-beads-orchestration`, `durable-objects`, `sandbox-sdk`, `todoist-cli`, `turnstile-spin`, `web-perf`, `workers-best-practices`. See [Claude-only skills](/ai/skills#claude-only-skills).
+
+## Repo-local settings
+
+This repo's own `.claude/settings.json` applies only to Claude Code sessions opened inside the chezmoi source directory. chezmoi ignores dot-prefixed source entries, so it is never deployed. It runs `bd prime` on `SessionStart` and `PreCompact`, which reloads beads issue context at session start and before compaction.
+
+## Integrations
+
+- [kitty](/terminal/kitty) tab bar shows a robot glyph for tabs running `claude`.
+- The fish `ai` picker launches `claude --dangerously-skip-permissions`; see [fish](/shell/fish).
+- The claude-mem plugin feeds both `cmem-to-obsidian.py` and the `/cmem-to-*` commands.

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).

docs/ai/meta.ts

@@ -0,0 +1,7 @@
+import { defineMeta } from "blume";
+
+export default defineMeta({
+  title: "AI agents",
+  icon: "bot",
+  pages: ["index", "claude-code", "omp", "skills"],
+});

docs/ai/omp.mdx

@@ -0,0 +1,175 @@
+---
+title: omp
+description: omp agent config, keybindings, MCP servers, cyberdream theme, custom commands, and the scheduled research loops under ~/.omp.
+---
+
+omp (oh-my-pi) is a terminal coding agent. The repo manages its agent directory (`~/.omp/agent`) and a set of prompt loops in `~/.omp/loops`. chezmoi does not install the `omp` binary; install it yourself. [topgrade](/tools/topgrade) keeps it current with the custom command `"Omp Update" = "omp update"`.
+
+## Files
+
+| Source in repo | Target | Notes |
+| --- | --- | --- |
+| `dot_omp/private_agent/` | `~/.omp/agent/` | Directory mode `0700` |
+| `dot_omp/private_agent/private_config.yml` | `~/.omp/agent/config.yml` | Mode `0600` |
+| `dot_omp/private_agent/keybindings.yml` | `~/.omp/agent/keybindings.yml` | |
+| `dot_omp/private_agent/private_mcp.json` | `~/.omp/agent/mcp.json` | Mode `0600` |
+| `dot_omp/private_agent/themes/cyberdream.json` | `~/.omp/agent/themes/cyberdream.json` | Custom theme |
+| `dot_omp/private_agent/commands/*.md` | `~/.omp/agent/commands/*.md` | Slash commands |
+| `dot_omp/loops/bin/executable_run-loop.sh` | `~/.omp/loops/bin/run-loop.sh` | Loop runner |
+| `dot_omp/loops/<name>/private_loop.md` | `~/.omp/loops/<name>/loop.md` | One prompt per loop, mode `0600` |
+| `dot_omp/loops/goals/private_templates.md` | `~/.omp/loops/goals/templates.md` | Unscheduled `/goal` templates |
+
+No omp file is role-gated. In chezmoi's symlink mode, `private_` and `executable_` entries are written as regular files, not symlinks.
+
+## config.yml
+
+```yaml ~/.omp/agent/config.yml
+theme:
+  dark: titanium
+  light: light
+symbolPreset: nerd
+setupVersion: 2
+hideThinkingBlock: false
+modelRoles:
+  plan: anthropic/claude-fable-5
+composer:
+  shape: rule
+```
+
+| Key | Value | Effect |
+| --- | --- | --- |
+| `theme.dark` | `titanium` | Theme on a dark terminal background (omp's default, pinned explicitly) |
+| `theme.light` | `light` | Theme on a light terminal background (omp's default) |
+| `symbolPreset` | `nerd` | Nerd Font glyphs instead of the default `unicode` set; the repo's font is Victor Mono Nerd Font |
+| `hideThinkingBlock` | `false` | Thinking blocks stay visible |
+| `modelRoles.plan` | `anthropic/claude-fable-5` | Model for the `plan` role; other roles use omp defaults |
+| `composer.shape` | `rule` | Built-in `rule` composer style instead of the default `box` |
+| `setupVersion` | `2` | Internal settings version marker |
+
+No API keys are stored in `config.yml`.
+
+## Keybindings
+
+```yaml ~/.omp/agent/keybindings.yml
+app.editor.external: Ctrl+E
+app.exit: Ctrl+Q
+```
+
+| Key | Action |
+| --- | --- |
+| <kbd>Ctrl</kbd> <kbd>E</kbd> | Open the current prompt in the external editor (`app.editor.external`) |
+| <kbd>Ctrl</kbd> <kbd>Q</kbd> | Quit omp (`app.exit`) |
+
+All other bindings are omp defaults.
+
+## MCP servers
+
+`mcp.json` declares three remote MCP servers over HTTP. No credential values are stored in the file.
+
+| Server | Transport | Endpoint | Auth |
+| --- | --- | --- | --- |
+| `exa` | `http` | `https://mcp.exa.ai/mcp` | none |
+| `cloudflare-api` | `http` | `https://mcp.cloudflare.com/mcp` | OAuth; omp stores the token in its own credential store under a profile credential id |
+| `github` | `http` | `https://api.githubcopilot.com/mcp/` | `Authorization` header built at request time by a `!` shell command that reads the token from `gh auth token` |
+
+The GitHub server therefore needs the [GitHub CLI](/tools/github-cli) to be logged in. The `$schema` key points at omp's `mcp-schema.json` for editor validation.
+
+## Theme
+
+`themes/cyberdream.json` ports the cyberdream palette to omp's theme schema. It installs the theme, but `config.yml` currently selects `titanium` for dark mode. To use cyberdream, set `theme.dark: cyberdream`.
+
+| Var | Hex | Used for |
+| --- | --- | --- |
+| `bg` | `#16181a` | base background |
+| `bgAlt` | `#1e2124` | user/custom message, tool, and status-line backgrounds |
+| `bgHighlight` | `#3c4048` | selection |
+| `fg` | `#ffffff` | message and tool output text |
+| `grey` | `#7b8496` | muted, dim, thinking text, comments, quotes, borders |
+| `blue` | `#5ea1ff` | accent, borders, links, functions, status-line path |
+| `cyan` | `#5ef1ff` | accent borders, tool titles, inline code, types, context meter |
+| `green` | `#5eff6c` | success, diff additions, strings, clean git |
+| `red` | `#ff6e5e` | errors, diff removals, untracked files |
+| `yellow` | `#f1ff5e` | warnings, variables, bash mode, dirty git |
+| `magenta` | `#ff5ef1` | keywords, subagent count |
+| `pink` | `#ff5ea0` | operators, spend |
+| `orange` | `#ffbd5e` | Markdown headings, cost |
+| `purple` | `#bd5eff` | numbers, python mode, model name |
+
+The thinking-level indicator runs `grey` (off) → `blue` → `cyan` → `green` → `yellow` → `orange` → `red` (max).
+
+## Commands
+
+| Command | Invocation | Purpose |
+| --- | --- | --- |
+| `/leetcode-docs` | `/leetcode-docs <file> [extra instructions]` | Converts a LeetCode solution file into a Fumadocs MDX page at `content/docs/leetcode/<difficulty>/<category>/<number>-<slug>.mdx`. The page has a difficulty callout, problem, examples, constraints, a derived intuition paragraph, the solution copied verbatim (multiple approaches become tabs), and a complexity callout. Prints only the output path. |
+| `/leetcode-eli5` | `/leetcode-eli5 <file> [extra instructions]` | Adds beginner-level line-by-line comments and a `// ====` banner to a LeetCode solution. Leaves the header, JSDoc, and code byte-for-byte unchanged. Prints the path and the number of comment lines added. |
+
+Both expect the on-disk format of the LeetCode solutions repo: a `/* ... */` problem header, a JSDoc block, then the solution function(s).
+
+## Loops
+
+`~/.omp/loops` holds scheduled, read-only research prompts. Each loop is a directory with a `loop.md` prompt. `run-loop.sh` creates `state.md` and `runs.log` beside it at runtime; chezmoi does not manage those.
+
+### run-loop.sh
+
+```sh
+~/.omp/loops/bin/run-loop.sh <loop-name>
+```
+
+Runs one round of a loop:
+
+<Steps>
+  <Step title="Prepare state">
+    Exits if `~/.omp/loops/<name>/loop.md` is missing. Seeds `state.md` with `## queue`, `## done`, and `## blocked` headings if it does not exist.
+  </Step>
+  <Step title="Cheap round">
+    Runs `omp -p --no-session --max-time 600 --model kimi-for-coding` with the prompt plus the loop directory, state-file path, and round timestamp appended. Output goes to `runs.log`.
+  </Step>
+  <Step title="Escalate once">
+    If any output line starts with `ESCALATE`, re-runs the round once on omp's default model (Fable) with a 1200 s cap. It logs `<loop> escalated` to `~/.omp/loops/escalations.log`.
+  </Step>
+</Steps>
+
+At most one round and one escalation per call. Failures from `omp` are logged and do not abort the script.
+
+### Loop catalogue
+
+Every loop follows the same contract: read `state.md` first, do one pass, make exactly one change (usually a brief or proposal appended under `## queue`), and log repeated tool failures under `## blocked`. Loops draft only; they never file issues or change repos. The subject is WalletBase, an embedded-wallet project.
+
+| Loop | Cadence | Inputs | Output per round | Escalates on |
+| --- | --- | --- | --- | --- |
+| `intel-refresh` (#19) | Mon 06:00 | Exa search over five beats: ERC-4337/AA, EIP-7702, embedded-wallet competitors, agent-payment protocols, Base chain | Up to 5 bullets per beat for the week; proposes swapping a beat that has been quiet for 3 weeks | A development that breaks a core assumption |
+| `share-of-model` (#3) | Mon 07:00 | Exa answer mode, fixed set of six buyer questions | Table of vendors named per answer and whether WalletBase appears; biggest rank shift | never |
+| `regulatory-digest` (#20) | Tue 07:00 | FinCEN, OFAC, SEC/CFTC, EU MiCA/CASP, Ethereum governance | Only material changes; "no material changes" counts as success; a proposed risk-position edit when an item breaks a standing assumption | MSB scope or OFAC action touching similar infra |
+| `brand-radar` (#10) | Wed 07:00 | HN Algolia API (no key), Exa | Mentions grouped into feature asks, pricing pain, security, and integration friction; one drafted `bd create` issue or positioning note | Security discussion of a dependency |
+| `answer-gap` (#1) | Thu 07:00 | Exa, rotating developer questions plus ones harvested in earlier rounds | One content brief; up to 3 new questions queued | never |
+| `competitor-watch` (#4) | Fri 07:00 | Exa over six competitor blogs | Logs new posts; one content brief for the biggest gap | Competitor launches an agent-economy product |
+| `repeat-offender` (#24) | Sun 18:00 | `bd list` across the project's repos, loop `runs.log`, `## blocked` sections, and `escalations.log` | Failure patterns grouped by root cause; one drafted `bd create` systemic fix | Data loss or security-boundary pattern |
+
+Five prompts cap page fetches or API calls per round (15 to 30); `share-of-model` and `repeat-offender` are bounded by their fixed question set and sources.
+
+:::note[Scheduling]
+Cadences are declared in each prompt header; the repo contains no timer for them. `.chezmoiscripts/run_once_after_30-user-services.sh.tmpl` names `omp-loop` among the personal automation units that are enabled by hand on each machine and never automatically. See [scripts](/chezmoi/scripts).
+:::
+
+### Goal templates
+
+`goals/templates.md` is not scheduled. It holds two `/goal` prompts to paste into an interactive omp session when facing a decision:
+
+| Template | Purpose | Cap |
+| --- | --- | --- |
+| kill-criteria (#22) | One measurable disqualifying condition per option, cited evidence, verdict ALIVE / KILLED / NEEDS-DATA | 40 tool calls |
+| pre-mortem (#23) | Writes the post-mortem of a failed decision 12 months out: 3–5 causal chains, each tied to a present-day assumption, with an early warning sign and the cheapest mitigation | 30 tool calls |
+
+Both count as done only when the full artifact is pasted in the chat.
+
+## Shell integration
+
+| Entry point | Source | What it does |
+| --- | --- | --- |
+| fish completions | `dot_config/fish/completions/omp.fish` | `omp completions fish \| source` generates completions at load time |
+| <kbd>Ctrl</kbd> <kbd>A</kbd> | fish `fish_user_key_bindings`, zsh `keybinds.zsh` | Launches `omp` from the prompt |
+| `launch_omp_livediff_overlay` | `dot_local/bin/executable_launch_omp_livediff_overlay`, fish function of the same name | Opens omp as a kitty overlay on the current window with a `livediff` vsplit beside it, focus kept on omp. Needs `KITTY_LISTEN_ON` (kitty remote control). |
+| `lc-elir [root]` | `dot_local/bin/executable_lc-elir`, fish function | fzf multi-picks numbered LeetCode files (`1365.slug.js`/`.ts`) with a bat preview and runs `omp -p "/leetcode-eli5 <file>"` on each |
+
+See [scripts](/shell/scripts) and [fish](/shell/fish). The [kitty](/terminal/kitty) tab bar shows a microchip glyph for tabs running `omp`.

docs/ai/skills.mdx

@@ -0,0 +1,174 @@
+---
+title: Skills
+description: The shared agent skill library in ~/.agents/skills, its lock file, and how Claude Code links to it.
+---
+
+Agent skills are folders with a `SKILL.md` file (frontmatter `name` and `description`, then instructions) that agents load on demand. The repo keeps one shared library in `~/.agents/skills`. Agents that follow the open skills layout read it from there, and Claude Code reaches it through symlinks in `~/.claude/skills`.
+
+## Files
+
+| Source in repo | Target | Notes |
+| --- | --- | --- |
+| `dot_agents/skills/<name>/` | `~/.agents/skills/<name>/` | 82 skill directories; in symlink mode each plain file is a symlink into the repo |
+| `dot_agents/dot_skill-lock.json` | `~/.agents/.skill-lock.json` | Install record written by the `skills` CLI |
+| `dot_claude/skills/symlink_<name>` | `~/.claude/skills/<name>` | Relative symlink to `../../.agents/skills/<name>` |
+
+Not role-gated; the library is applied on every machine.
+
+## Managing skills
+
+Skills are installed and updated with the Skills CLI (`npx skills`), which the `find-skills` skill documents:
+
+```sh
+npx skills find <query>            # search the registry
+npx skills add <owner/repo@skill> -g -y   # install at user level
+npx skills check                   # look for updates
+npx skills update                  # update everything
+```
+
+A skill installed this way lands in `~/.agents/skills/<name>/` as plain files. Add it to the repo with `chezmoi add ~/.agents/skills/<name>`, and commit the updated `.skill-lock.json` alongside it. To expose it to Claude Code, add a `dot_claude/skills/symlink_<name>` file containing `../../.agents/skills/<name>`.
+
+### .skill-lock.json
+
+The lock file (`"version": 3`) has one entry per installed skill, keyed by skill name:
+
+| Field | Meaning |
+| --- | --- |
+| `source` | Where the skill came from: `owner/repo` for GitHub, or a domain for well-known endpoints |
+| `sourceType` | `github` (77 entries) or `well-known` (3 entries, all `mintlify.com`) |
+| `sourceUrl` | Git clone URL, or the `.well-known/agent-skills/.../skill.md` URL |
+| `skillPath` | Path of `SKILL.md` inside the source repo (GitHub sources only) |
+| `skillFolderHash` | Hash of the skill folder at the recorded version (empty for well-known sources) |
+| `installedAt` / `updatedAt` | ISO timestamps of first install and last update |
+
+A top-level `dismissed` object records dismissed CLI prompts (`findSkillsPrompt: true`).
+
+The lock lists 80 skills. The largest sources are `mattpocock/skills` (23), `vercel-labs/json-render` (16), `Leonxlnx/taste-skill` (7), `haydenbleasel/blume` (3). The lock and the directory do not match exactly:
+
+- In the lock with no directory in the repo: `Technical Writer`, `codegen`, `ethereum-wingman`, `gh-stack`, `image`, `jotai`, `mcp`, `react-email`, `react-native`, `react-pdf`, `redux`, `remotion`, `solid`, `svelte`, `vue`, `xstate`, `zustand`.
+- In the directory with no lock entry (added by hand or copied from elsewhere): shown as `untracked` in the table below.
+
+## How Claude Code resolves skills
+
+<Steps>
+  <Step title="Source">
+    `dot_claude/skills/symlink_blume` is a one-line file containing `../../.agents/skills/blume`.
+  </Step>
+  <Step title="Apply">
+    chezmoi's `symlink_` prefix turns it into the symlink `~/.claude/skills/blume`, pointing at `../../.agents/skills/blume`.
+  </Step>
+  <Step title="Resolve">
+    Relative to `~/.claude/skills/`, the target is `~/.agents/skills/blume`, whose files are in turn symlinks into the chezmoi source directory. Edits to a skill in the repo take effect immediately.
+  </Step>
+</Steps>
+
+Twelve library skills have no Claude link, so only agents that read `~/.agents/skills` directly can see them. They are the three fumadocs skills, five of the six tanstack skills, `interface-design`, `laws-of-ux`, `ui-ux-pro-max`, and `web-design-guidelines` (marked `—` below). Three Claude-side entries (`cloudflare`, `todoist-cli`, `workers-best-practices`) are separate real directories in `dot_claude/skills/` rather than links, so Claude Code reads its own copy (`own copy` below).
+
+## Library
+
+The Description column is the first sentence of each skill's `SKILL.md` frontmatter `description`. Lock source is the `source` field from `.skill-lock.json`.
+
+| Skill | Lock source | Claude link | Description |
+| --- | --- | :-: | --- |
+| `blume` | `haydenbleasel/blume` | symlink | Build and maintain documentation sites with Blume, the markdown-first docs framework on Astro and Vite. |
+| `blume-migrate` | `haydenbleasel/blume` | symlink | Migrate an existing documentation site (Mintlify, Docusaurus, Fumadocs, Nextra, Starlight, or any docs framework) to Blume, the markdown-first docs framework on Astro. |
+| `blume-update-docs` | `haydenbleasel/blume` | symlink | Keep a Blume docs site in sync with the product it documents. |
+| `brandkit` | `Leonxlnx/taste-skill` | symlink | Premium brand-kit image generation skill for creating high-end brand-guidelines boards, logo systems, identity decks, and visual-world presentations. |
+| `bun-development` | `sickn33/antigravity-awesome-skills` | symlink | Fast, modern JavaScript/TypeScript development with the Bun runtime, inspired by oven-sh/bun. |
+| `cloudflare` | untracked | own copy | Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). |
+| `codebase-design` | `mattpocock/skills` | symlink | Shared vocabulary for designing deep modules. |
+| `core` | `vercel-labs/json-render` | symlink | Core package for defining schemas, catalogs, and AI prompt generation for json-render. |
+| `deepinit` | `yeachan-heo/oh-my-claudecode` | symlink | Deep codebase initialization with hierarchical AGENTS.md documentation |
+| `design-an-interface` | untracked | symlink | Generate multiple radically different interface designs for a module using parallel sub-agents. |
+| `design-taste-frontend` | `Leonxlnx/taste-skill` | symlink | Anti-slop frontend skill for landing pages, portfolios, and redesigns. |
+| `diagnosing-bugs` | `mattpocock/skills` | symlink | Diagnosis loop for hard bugs and performance regressions. |
+| `domain-modeling` | `mattpocock/skills` | symlink | Build and sharpen a project's domain model. |
+| `find-skills` | `vercel-labs/skills` | symlink | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. |
+| `fumadocs-component-docs` | untracked | — | Create component documentation with installation, usage examples, and preview sections. |
+| `fumadocs-mdx-structure` | untracked | — | Create MDX documentation files with proper frontmatter, imports, and component integration. |
+| `fumadocs-registry-integration` | untracked | — | Register 8-bit components in registry.json for shadcn/ui add command. |
+| `git-guardrails-claude-code` | `mattpocock/skills` | symlink | Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute. |
+| `golang-pro` | `jeffallan/claude-skills` | symlink | Implements concurrent Go patterns using goroutines and channels, designs and builds microservices with gRPC or REST, optimizes Go application performance with pprof, and enforces idiomatic Go with generics, interfaces, and robust error handling. |
+| `gpt-taste` | `Leonxlnx/taste-skill` | symlink | Elite UX/UI & Advanced GSAP Motion Engineer. |
+| `grill-me` | `mattpocock/skills` | symlink | A relentless interview to sharpen a plan or design. |
+| `grill-with-docs` | `mattpocock/skills` | symlink | A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. |
+| `grilling` | `mattpocock/skills` | symlink | Grill the user relentlessly about a plan, decision, or idea. |
+| `handoff` | `mattpocock/skills` | symlink | Compact the current conversation into a handoff document for another agent to pick up. |
+| `high-end-visual-design` | `Leonxlnx/taste-skill` | symlink | Teaches the AI to design like a high-end agency. |
+| `imagegen-frontend-web` | `Leonxlnx/taste-skill` | symlink | Elite frontend image-direction skill for generating premium, conversion-aware website design references. |
+| `implement` | `mattpocock/skills` | symlink | Implement a piece of work based on a spec or set of tickets. |
+| `improve-codebase-architecture` | `mattpocock/skills` | symlink | Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. |
+| `interface-design` | untracked | — | This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. |
+| `laws-of-ux` | untracked | — | Review and guide UI implementations using the 21 Laws of UX. |
+| `linear` | `openai/skills` | symlink | Manage issues, projects & team workflows in Linear. |
+| `linear-cli` | `schpet/linear-cli` | symlink | Manage Linear issues from the command line using the linear cli. |
+| `linear-documents` | `finesssee/linear-cli` | symlink | Manage Linear documents. |
+| `loop-me` | `mattpocock/skills` | symlink | Grill me about specs for the workflows I want to build, within this workspace. |
+| `loopy` | `Forward-Future/loop-library` | symlink | Discover, find, compare, audit, repair, adapt, craft, run, debrief, save, and prepare repeatable AI-agent loops for publication. |
+| `migrate-to-shoehorn` | `mattpocock/skills` | symlink | Migrate test files from `as` type assertions to @total-typescript/shoehorn. |
+| `minimalist-ui` | `Leonxlnx/taste-skill` | symlink | Clean editorial-style interfaces. |
+| `mintlify` | `mintlify.com` | symlink | Build and maintain documentation sites with Mintlify. |
+| `mintlify-api` | `mintlify.com` | symlink | Interact with the Mintlify REST API to manage deployments, trigger builds, and query documentation site metadata programmatically. |
+| `mintlify-docs` | `mintlify.com` | symlink | Build and maintain documentation sites with Mintlify. |
+| `native-sdk` | `vercel-labs/native` | symlink | Discovery skill for the Native SDK, the complete toolkit for building native desktop applications. |
+| `obsidian-vault` | untracked | symlink | Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. |
+| `openlogs-server-logs` | `charlietlamb/openlogs` | symlink | Fetch and inspect recent local server logs in repos that use openlogs or the `ol` CLI. |
+| `prototype` | `mattpocock/skills` | symlink | Build a throwaway prototype to answer a design question. |
+| `qa` | untracked | symlink | Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. |
+| `react` | `vercel-labs/json-render` | symlink | React renderer for json-render that turns JSON specs into React components. |
+| `redesign-existing-projects` | `Leonxlnx/taste-skill` | symlink | Upgrades existing websites and apps to premium quality. |
+| `remix` | `remix-run/remix` | symlink | Build and review Remix 3 applications using the `remix` npm package and subpath imports. |
+| `request-refactor-plan` | untracked | symlink | Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. |
+| `resolving-merge-conflicts` | `mattpocock/skills` | symlink | Use when you need to resolve an in-progress git merge/rebase conflict. |
+| `rust-async-patterns` | `wshobson/agents` | symlink | Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. |
+| `rust-best-practices` | `apollographql/skills` | symlink | Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. |
+| `rust-testing` | `affaan-m/everything-claude-code` | symlink | Rust testing patterns including unit tests, integration tests, async testing, property-based testing, mocking, and coverage. |
+| `scaffold-exercises` | `mattpocock/skills` | symlink | Create exercise directory structures with sections, problems, solutions, and explainers that pass linting. |
+| `setup-matt-pocock-skills` | `mattpocock/skills` | symlink | Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. |
+| `setup-pre-commit` | `mattpocock/skills` | symlink | Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. |
+| `shadcn` | `shadcn-ui/ui` | symlink | Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. |
+| `solidity-foundry-development` | `whackur/solidity-agent-toolkit` | symlink | Foundry development workflow for Solidity smart contracts. |
+| `solidity-security` | `wshobson/agents` | symlink | Master smart contract security best practices to prevent common vulnerabilities and implement secure Solidity patterns. |
+| `stop-slop` | `hardikpandya/stop-slop` | symlink | Remove AI writing patterns from prose. |
+| `tanstack-form` | untracked | — | Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, Lit, and Svelte. |
+| `tanstack-integration-best-practices` | untracked | — | Best practices for integrating TanStack Query with TanStack Router and TanStack Start. |
+| `tanstack-query-best-practices` | `deckardger/tanstack-agent-skills` | — | TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. |
+| `tanstack-router-best-practices` | untracked | — | TanStack Router best practices for type-safe routing, data loading, search params, and navigation. |
+| `tanstack-start-best-practices` | `deckardger/tanstack-agent-skills` | symlink | TanStack Start best practices for full-stack React applications. |
+| `tanstack-table` | untracked | — | Headless UI for building powerful tables & datagrids for TS/JS, React, Vue, Solid, Svelte, Qwik, Angular, and Lit. |
+| `tdd` | `mattpocock/skills` | symlink | Test-driven development. |
+| `teach` | `mattpocock/skills` | symlink | Teach the user a new skill or concept, within this workspace. |
+| `todoist-cli` | untracked | own copy | Manage Todoist tasks, projects, labels, filters, sections, comments, reminders, and workspaces via the `td` CLI. |
+| `triage` | `mattpocock/skills` | symlink | Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs. |
+| `typescript-expert` | `remix-run/remix` | symlink | Write, refactor, or review TypeScript code with strict, precise, maintainable types and without unnecessary `any`, type assertions, or type suppressions. |
+| `ubiquitous-language` | untracked | symlink | Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. |
+| `ui-ux-pro-max` | untracked | — | UI/UX design intelligence for web and mobile. |
+| `uv-package-manager` | `wshobson/agents` | symlink | Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. |
+| `web-design-guidelines` | `vercel-labs/agent-skills` | — | Review UI code for Web Interface Guidelines compliance. |
+| `workers-best-practices` | untracked | own copy | Reviews and authors Cloudflare Workers code against production best practices. |
+| `wrangler` | `cloudflare/skills` | symlink | Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. |
+| `write-tests` | `remix-run/remix` | symlink | Write, refactor, or review tests in the Remix repository. |
+| `writing-beats` | `mattpocock/skills` | symlink | Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it. |
+| `writing-fragments` | `mattpocock/skills` | symlink | Writing, explore: mine raw fragments, no structure yet. |
+| `writing-great-skills` | untracked | symlink | Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. |
+| `writing-shape` | `mattpocock/skills` | symlink | Writing, exploit: shape raw material into an article, paragraph by paragraph. |
+
+## Claude-only skills
+
+These live as real directories in `dot_claude/skills/` (target `~/.claude/skills/<name>/`) and are not part of the shared library or the lock file. See [Claude Code](/ai/claude-code#skills).
+
+| Skill | Description |
+| --- | --- |
+| `absurd` | Debug and operate Absurd durable workflows with absurdctl. |
+| `agents-sdk` | Build AI agents on Cloudflare Workers using the Agents SDK. |
+| `cloudflare` | Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). |
+| `cloudflare-email-service` | Send and receive transactional emails with Cloudflare Email Service (Email Sending + Email Routing). |
+| `cloudflare-one` | Guides Cloudflare One Zero Trust and SASE work across Access, Gateway, WARP, Tunnel, Cloudflare WAN, DLP, CASB, device posture, and identity. |
+| `cloudflare-one-migrations` | Plans migrations from Zscaler ZIA/ZPA, Palo Alto, legacy VPN, SWG, or SASE stacks to Cloudflare One. |
+| `create-beads-orchestration` | Bootstrap lean multi-agent orchestration with beads task tracking. |
+| `durable-objects` | Create and review Cloudflare Durable Objects. |
+| `sandbox-sdk` | Build sandboxed applications for secure code execution. |
+| `todoist-cli` | Manage Todoist tasks, projects, labels, filters, sections, comments, reminders, and workspaces via the `td` CLI. |
+| `turnstile-spin` | Set up Cloudflare Turnstile end-to-end in a project. |
+| `web-perf` | Analyzes web performance using Chrome DevTools MCP. |
+| `workers-best-practices` | Reviews and authors Cloudflare Workers code against production best practices. |