chore(skills): add cmux skills

.agents/skills/cmux-markdown/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: cmux-markdown
+description: Open markdown files in a formatted viewer panel with live reload. Use when you need to display plans, documentation, or notes alongside the terminal with rich rendering (headings, code blocks, tables, lists).
+---
+
+# Markdown Viewer with cmux
+
+Write a `.md` file, open it in a panel, and the panel re-renders whenever the file changes on disk. Use it for agent plans and task lists alongside the terminal, documentation and changelogs while working, and notes another process updates progressively.
+
+```bash
+cmux markdown open plan.md                              # split next to the current terminal
+cmux markdown open /path/to/PLAN.md
+cmux markdown open design.md --workspace workspace:2    # also --surface, --window
+```
+
+Relative paths resolve against the caller's cwd and `~` expands; the resolved absolute path comes back in the output.
+
+## Agent usage
+
+Write the full plan file first, then open it, so the panel never shows a partially written file. After that, overwrite or append freely: each write triggers a re-render, and atomic replacement (editor saves, `sed -i`, VS Code) is handled.
+
+To instruct coding agents in a project, add to its `AGENTS.md`:
+
+```markdown
+## Plan Display
+
+When creating a plan or task list, write it to a `.md` file and open it in cmux:
+
+    cmux markdown open plan.md
+
+The panel renders markdown with rich formatting and auto-updates when the file changes.
+```
+
+## Rendering
+
+Headings h1-h6 (dividers on h1/h2), fenced code blocks in monospace, inline code with a highlighted background, tables with alternating row colors, nested ordered and unordered lists, blockquotes with a left border, bold/italic/strikethrough, clickable links, horizontal rules, and inline images. Light and dark mode both supported.
+
+## Deep-dive references
+
+| Reference | When to Use |
+|-----------|-------------|
+| [references/commands.md](references/commands.md) | Full command syntax, options, output shape, panel behavior |
+| [references/live-reload.md](references/live-reload.md) | File watching, atomic writes, unavailable-file state, performance |

.agents/skills/cmux-markdown/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "cmux Markdown Viewer"
+  short_description: "Open markdown files in a formatted panel with live reload alongside the terminal."
+  default_prompt: "Use this skill to display markdown plans, docs, or notes in a cmux panel: write to a .md file, run 'cmux markdown open <path>', and the panel auto-updates when the file changes."

.agents/skills/cmux-markdown/references/commands.md

@@ -0,0 +1,29 @@
+# Command Reference (cmux Markdown)
+
+```bash
+cmux markdown open <path>
+cmux markdown <path>          # shorthand, "open" is implicit
+cmux markdown --help
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--workspace <id\|ref\|index>` | Target workspace | `$CMUX_WORKSPACE_ID` |
+| `--surface <id\|ref\|index>` | Source surface to split from | Focused surface |
+| `--window <id\|ref>` | Target window | Current window |
+
+## Output
+
+```
+OK surface=surface:8 pane=pane:3 path=/absolute/path/to/file.md
+```
+
+`--json` returns `window_id`, `workspace_id`, `pane_id`, `surface_id`, and `path`.
+
+## Panel behavior
+
+The panel opens as a horizontal split to the right of the source surface. The tab shows the filename and a document icon; the file path appears as a breadcrumb at the top. Content is read-only with text selection enabled.
+
+Markdown panels are saved and restored across sessions and re-read the file from disk on restore. A panel is not recreated if the file no longer exists at restore time.
+
+See also [live-reload.md](live-reload.md).

.agents/skills/cmux-markdown/references/live-reload.md

@@ -0,0 +1,19 @@
+# Live Reload Behavior
+
+The panel watches the file with a kernel-level watcher (`DispatchSource` with `O_EVTONLY`) for write, extend, delete, and rename events, and re-renders on change.
+
+## Supported write patterns
+
+Direct writes (`echo >>`), editor saves, atomic replace (write temp then rename), `sed -i`, VS Code/IDE saves, and progressive agent writes all work. Most of these are atomic replace under the hood.
+
+## Atomic file replacement
+
+An atomic replace shows up as a delete event followed by a new file at the same path. The panel detects it, re-reads immediately (in case the rename already landed), waits 500 ms and checks again if the file is missing, then reconnects the watcher to the new inode.
+
+## File unavailable state
+
+If the file is deleted and does not reappear within the retry window, the panel shows a "file unavailable" state with the original path and stays open until the user closes it. It does not reconnect if the file later reappears; close and reopen the panel.
+
+## Performance
+
+Re-reads are dispatched to the main thread and run synchronously, so files over ~100KB can cause brief UI hitches during re-render; split very large documents. The watcher itself runs on a low-priority background queue with negligible CPU impact.

.agents/skills/cmux-settings/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: cmux-settings
+description: "View and edit cmux settings in ~/.config/cmux/cmux.json. Use when the user wants to change cmux preferences (appearance, sidebar, notifications, automation, browser, shortcuts), set a value by JSON path, validate the file, open it in an editor, or look up which keys cmux recognizes. Triggers on '/cmux-settings', 'change cmux setting', 'set <something> in cmux', 'cmux config', 'cmux.json', or 'rebind a cmux shortcut'."
+---
+
+# cmux-settings
+
+cmux reads user settings from `~/.config/cmux/cmux.json` (JSONC). A file watcher applies changes on save, no restart. Legacy `~/.config/cmux/settings.json` is read only as a fallback for keys absent from `cmux.json`.
+
+Schema: `https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json`. The authoritative path list is `Sources/CmuxSettingsJSONPathSupport.swift`; the installed skill carries a generated copy in `references/all-keys.md`. Settings sections are `app`, `terminal`, `notifications`, `sidebar`, `sidebarAppearance`, `workspaceColors`, `automation`, `browser`, `shortcuts`. Non-settings sections (`actions`, `ui`, `commands`, `vault`, `rightSidebar`) share the same file.
+
+## Helper script
+
+Use the bundled helper for every read/write. It strips JSONC comments, writes atomically, and validates keys against the schema.
+
+```bash
+skills/cmux-settings/scripts/cmux-settings <subcommand>            # from a cmux checkout
+~/.codex/skills/cmux-settings/scripts/cmux-settings <subcommand>   # installed Codex skill
+```
+
+The rest of this doc assumes it is on `$PATH` as `cmux-settings`; from a checkout, `export PATH="$PWD/skills/cmux-settings/scripts:$PATH"`.
+
+| Command | What it does |
+|---|---|
+| `cmux-settings path` | Print the config path. |
+| `cmux-settings dump` | Print the raw file (preserves comments). |
+| `cmux-settings dump --no-comments` | Print the parsed JSON. |
+| `cmux-settings get <a.b.c>` | Print value at dotted JSON path. |
+| `cmux-settings set <a.b.c> <value>` | Set value. `<value>` is parsed as JSON (`true`, `42`, `"text"`, `[…]`, `{…}`); unquoted plain words are stored as strings. |
+| `cmux-settings unset <a.b.c>` | Delete key, reverting to the in-app default. |
+| `cmux-settings list-supported` | List every settings JSON path the app recognizes. |
+| `cmux-settings validate` | Parse the file and flag unknown settings keys. |
+| `cmux-settings open` | Open `cmux.json` in `$EDITOR`, VS Code, Cursor, or TextEdit. |
+
+`--file <path>` overrides the target file, useful for `--file ~/.config/cmux/settings.json`.
+
+## Workflow
+
+1. Look up the key when the user named a setting in plain English:
+   ```bash
+   cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
+   ```
+2. Set it. JSON literals must be valid JSON.
+   ```bash
+   cmux-settings set sidebarAppearance.matchTerminalBackground true
+   cmux-settings set app.appearance dark
+   cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'
+   cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'
+   ```
+3. Read back and `cmux-settings validate`.
+4. Tell the user it auto-reloaded, and that `cmux-settings unset <key>` reverts it.
+
+## Quick reference
+
+- Appearance: `app.appearance` (`"system" | "light" | "dark"`), `app.appIcon`, `app.menuBarOnly`, `app.minimalMode`.
+- Sidebar tint: `sidebarAppearance.matchTerminalBackground`, `.tintColor`, `.tintOpacity` (0..1).
+- Sidebar details: `sidebar.hideAllDetails`, `.showBranchDirectory`, `.showPullRequests`, `.showPorts`, `.showLog`.
+- Notifications: `notifications.dockBadge`, `.sound` (enum including `"none"`, `"custom_file"`), `.customSoundFilePath`, `.hooks` (array).
+- Browser: `browser.defaultSearchEngine`, `.theme`, `.openTerminalLinksInCmuxBrowser`, `.hostsToOpenInEmbeddedBrowser`.
+- Automation: `automation.socketControlMode` (`off | cmuxOnly | automation | password | allowAll`), `.portBase`, `.portRange`.
+- Shortcuts: `shortcuts.bindings.<actionId>` = `"cmd+b"`, `["ctrl+b","c"]`, `null`, or `""` to unbind. Action ids in [references/shortcut-actions.md](references/shortcut-actions.md).
+
+Full list of settings, defaults, and descriptions: `cmux-settings list-supported` or [references/all-keys.md](references/all-keys.md).
+
+## Rules
+
+- Only edit `cmux.json`. Never `settings.json` unless the user explicitly asks; it is legacy and read only when a key is absent from `cmux.json`.
+- Never tell the user to restart cmux. The file watcher reloads on save.
+- Always `cmux-settings validate` after a bulk edit. Unknown keys mean the user pasted a key the app does not consume.
+- Do not blindly overwrite `actions`, `ui`, `commands`, `vault`, or `rightSidebar`; they share the file and hold hand-tuned non-settings config.
+- Shortcut action ids must match the schema enum. Look them up before binding.
+- Colors are `#RRGGBB`; opacities are `0..1`.
+- Translate app-level phrasing ("Settings > Notifications > Dock badge") to the JSON path first; `web/app/[locale]/(landing)/docs/configuration/page.tsx` mirrors the schema 1:1.

.agents/skills/cmux-settings/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "cmux Settings"
+  short_description: "Inspect, edit, validate, and reload cmux.json settings."
+  default_prompt: "Use this skill to change cmux settings safely: map user-facing preferences to cmux.json paths, edit with the bundled helper, validate recognized keys, and rely on cmux's live config reload."