Expand cmux customization skill surfaces

docs/internal/skills-customization-ideas.md

@@ -0,0 +1,55 @@
+# Skills and Customization Ideas
+
+This is an internal planning note for cmux skills and customization surfaces. Keep public end-user skills in the cmux repo when they teach repeatable user workflows. Keep release, debug, and company operations skills in `cmuxterm-hq`.
+
+## Current Public Skills
+
+- `cmux`: core CLI control for windows, workspaces, panes, surfaces, focus, and routing.
+- `cmux-workspace`: current-workspace automation, sidebar metadata, input, and helper surfaces.
+- `cmux-settings`: safe reads, writes, validation, and editor open for `~/.config/cmux/cmux.json`.
+- `cmux-customization`: user-facing config across actions, plus button, tab bar buttons, workspace layouts, Dock controls, settings, notifications, browser routing, and Ghostty config boundaries.
+- `cmux-diagnostics`: support-safe health checks for CLI, socket, hooks, session restore, settings, and agent binaries.
+- `cmux-browser`: browser automation inside cmux webview surfaces.
+- `cmux-markdown`: formatted markdown panels beside terminals.
+
+## Current Customization Surfaces
+
+- `actions` in `cmux.json`: reusable action IDs for Command Palette, shortcuts, tab bar buttons, and plus-button menus.
+- `ui.newWorkspace.action`: replaces the plus-button click.
+- `ui.newWorkspace.contextMenu`: controls the plus-button right-click menu. `ui.newWorkspace.rightClick` is accepted as an alias, but public examples should use `contextMenu`.
+- `ui.surfaceTabBar.buttons`: replaces the visible tab bar button list. Built-ins must be included explicitly if they should remain visible.
+- `commands`: reusable shell commands and workspace layouts for worktrees, multiple checkouts, local services, browser previews, and SSH setups.
+- `.cmux/dock.json` and `~/.config/cmux/dock.json`: right-sidebar Dock controls for TUIs, logs, tests, queues, dev servers, and `cmux feed tui --opentui`.
+- `cmux-settings` paths: appearance, sidebar behavior, app icon, menu-bar mode, notifications, browser routing, automation, shortcuts, and new-workspace placement.
+- cmux CLI workspace metadata: workspace names, descriptions, colors, read/unread state, progress, status pills, and logs.
+- Notification hooks in `cmux.json`: filter, rewrite, suppress, or augment notification behavior.
+- Ghostty config: terminal fonts, themes, cursor, copy-on-select, shell integration, terminal keybindings, and rendering.
+
+## Skill Candidates
+
+- `cmux-dock`: create `.cmux/dock.json` or global Dock controls after inspecting project scripts, logs, services, and TUIs. This should become a separate skill if Dock setup gets enough schema, trust, and validation detail to make `cmux-customization` too broad.
+- `cmux-feed`: diagnose and configure Feed hooks, Feed TUI Dock controls, notification categories, and event stream checks. Keep it separate from diagnostics only if it gains repeatable setup/edit flows beyond read-only health checks.
+- `cmux-sidebar`: manage sidebar metadata, workspace descriptions, colors, pinned state, read state, and project conventions. This is useful when sidebar metadata becomes a common integration target for agents and scripts.
+- `cmux-ssh`: set up remote workspaces, SSH URL launches, remote browser routing, reconnect behavior, and remote agent notifications.
+- `cmux-cloud-vm`: operate Cloud VM create, attach, exec, SSH endpoint, billing, provider, and smoke-test workflows.
+- `cmux-vault`: manage vault-backed agent configuration, credential references, and restore behavior without leaking secrets into prompts.
+
+## Distribution Notes
+
+- Vercel `skills` expects each skill in a folder with `SKILL.md` frontmatter containing `name` and `description`. Keep optional `scripts`, `references`, `assets`, and `agents/openai.yaml` next to the skill.
+- Standard install is `npx skills add manaflow-ai/cmux -g -y`. Omit `--skill` to install all cmux skills. Use repeated `--skill <name>` flags to install selected skills. Do not use `--all` to mean all skills, because that flag installs to every supported agent.
+- Keep end-user cmux skills in the cmux repo for now. A dedicated skills repo only helps if clone/install time becomes painful, or if the skills need a release cadence that should not track the app repo.
+- Timing check from this worktree, with `skills@latest` warm in npm cache: local single-skill install took 3.37s, local all-skills install took 4.07s, and remote GitHub single-skill install took 10.91s. These numbers are small enough that a separate repo is not justified yet.
+
+## Product Customization Ideas
+
+- Feed customization: default filter, default decision buttons, feed-to-Dock presets, feed event retention, and per-agent display grouping.
+- Dock customization: control groups, reusable presets, default heights, collapsed state, and project templates.
+- Sidebar customization: visible fields, metadata row order, workspace grouping, badge policy, color defaults, and per-project sidebar conventions.
+- Tab bar customization: button groups, per-surface button sets, icon packs, overflow behavior, and action-specific tooltips.
+- Plus-button customization: starter templates for worktrees, multi-checkout setups, SSH launchers, and paired agent layouts.
+- Command Palette customization: action categories, keywords, project-local aliases, and discoverability hints for inherited actions.
+
+## Promotion Rule
+
+Create a new skill when the workflow has real commands, validation, and safety rules that an agent would otherwise rediscover. Keep an idea in docs when it is just product positioning or a list of possible settings. Do not publish private debug windows, release automation, production operations, or company-specific workflows as end-user cmux skills.

skills/cmux-customization/SKILL.md

@@ -1,16 +1,29 @@
 ---
 name: cmux-customization
-description: "Customize cmux for an end user. Use when changing cmux.json actions, custom commands, workspace layouts, Command Palette entries, surface toolbar buttons, shortcuts, notifications, browser routing, appearance, or Ghostty-backed terminal preferences."
+description: "Customize cmux for an end user. Use when changing cmux.json actions, custom commands, workspace layouts, plus-button behavior, surface tab bar buttons, Command Palette entries, Dock controls, sidebar and app settings, shortcuts, notifications, browser routing, or Ghostty-backed terminal preferences."
 ---
 
 # cmux Customization
 
 Use this skill for user-facing cmux customization. Keep the user's config intact, prefer schema-backed edits, and validate before reporting completion.
 
+## What Can Be Customized
+
+- Custom actions: define reusable `actions` in `cmux.json`. Actions can appear in Cmd+Shift+P, surface tab bars, shortcuts, and the plus-button right-click menu.
+- New workspace button: set `ui.newWorkspace.action` to replace the normal plus-button click, and `ui.newWorkspace.contextMenu` to control right-click actions. `ui.newWorkspace.rightClick` is accepted as an alias, but new examples should use `contextMenu`.
+- Surface tab bar buttons: set `ui.surfaceTabBar.buttons` to replace the default tab bar buttons. Include built-in IDs such as `cmux.newTerminal`, `cmux.newBrowser`, `cmux.splitRight`, and `cmux.splitDown` only when they should stay visible.
+- Workflows and layouts: use `commands` with workspace definitions to open a worktree, multiple checkouts, local services, browser previews, or SSH sessions in a deliberate split layout.
+- Dock controls: create `.cmux/dock.json` or `~/.config/cmux/dock.json` for right-sidebar terminal controls such as logs, test watchers, git TUIs, dev servers, queues, or `cmux feed tui --opentui`.
+- Sidebar and app behavior: use `cmux-settings` for supported settings such as appearance, sidebar display, notification behavior, browser routing, automation, shortcuts, and new-workspace placement.
+- Workspace metadata: use the cmux CLI or `cmux-workspace` for workspace names, descriptions, colors, read state, and sidebar metadata updates.
+- Feed and notifications: use `cmux hooks setup` for Feed event sources, notification settings for delivery behavior, and notification hooks in `cmux.json` for filtering or post-processing banners.
+- Terminal behavior: use Ghostty config for fonts, themes, cursor style, copy-on-select, shell integration, terminal keybindings, and terminal rendering.
+
 ## Choose the Right Surface
 
 - cmux app preferences: use `cmux-settings` for `~/.config/cmux/cmux.json` settings such as appearance, sidebar, notifications, browser behavior, automation, and shortcuts.
-- Custom actions, workspace layouts, toolbar buttons, plus-button behavior, and Command Palette entries: edit `~/.config/cmux/cmux.json` globally or `.cmux/cmux.json` in the project.
+- Custom actions, workspace layouts, tab bar buttons, plus-button behavior, and Command Palette entries: edit `~/.config/cmux/cmux.json` globally or `.cmux/cmux.json` in the project.
+- Dock controls: edit `.cmux/dock.json` in the project or `~/.config/cmux/dock.json` globally. Run `cmux docs dock` when available.
 - Terminal rendering and terminal keybindings: use Ghostty config, usually `~/.config/ghostty/config`. This includes fonts, cursor style, copy-on-select, shell integration, themes, and terminal keybindings.
 - Project-specific behavior: prefer `.cmux/cmux.json` in the project so the customization travels with the repo.
 
@@ -35,7 +48,7 @@ If a request can be handled by Ghostty config, say that and use Ghostty config i
    ```
 
    If the user installed with `skills.sh`, use `~/.codex/skills/cmux-settings/scripts/cmux-settings` instead.
-4. For actions and workspace layouts, edit JSONC carefully. Preserve unrelated sections such as `vault`, `rightSidebar`, `commands`, `actions`, `ui`, and `notifications`.
+4. For actions, UI wiring, workspace layouts, notification hooks, and Dock controls, edit JSONC or JSON carefully. Preserve unrelated sections such as `vault`, `rightSidebar`, `commands`, `actions`, `ui`, and `notifications`.
 5. Reload config after successful edits:
 
    ```bash
@@ -46,7 +59,7 @@ If a request can be handled by Ghostty config, say that and use Ghostty config i
 
 ## Common Patterns
 
-Add a Command Palette action that opens Codex in a new tab:
+Add a Command Palette action that opens Codex in a new tab. It will appear in Cmd+Shift+P unless `palette` is false:
 
 ```json
 {
@@ -63,29 +76,88 @@ Add a Command Palette action that opens Codex in a new tab:
 }
 ```
 
+Replace the plus-button click and define the plus-button right-click menu.
+This is the pattern for "bring your own worktree, multiple checkouts, or SSH
+setup". The `workspaceCommand` action ID is `worktree-agents`, and its
+`commandName` must match a command named `Worktree Agents` in the same config:
+
+```json
+{
+  "actions": {
+    "worktree-agents": {
+      "type": "workspaceCommand",
+      "title": "Worktree Agents",
+      "commandName": "Worktree Agents",
+      "icon": { "type": "symbol", "name": "folder.badge.plus" }
+    }
+  },
+  "ui": {
+    "newWorkspace": {
+      "action": "worktree-agents",
+      "contextMenu": [
+        { "action": "worktree-agents", "title": "Worktree Agents" },
+        { "type": "separator" },
+        { "action": "cmux.newTerminal", "title": "New Terminal" },
+        { "action": "cmux.newBrowser", "title": "New Browser" }
+      ]
+    }
+  },
+  "commands": [
+    {
+      "name": "Worktree Agents",
+      "description": "Create a worktree and open agents inside it",
+      "workspace": {
+        "name": "Worktree Agents",
+        "cwd": "../worktrees/my-feature",
+        "layout": {
+          "direction": "horizontal",
+          "children": [
+            {
+              "pane": {
+                "surfaces": [
+                  { "type": "terminal", "name": "Codex", "command": "codex" }
+                ]
+              }
+            },
+            {
+              "pane": {
+                "surfaces": [
+                  { "type": "terminal", "name": "SSH", "command": "ssh devbox" }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
 Add a project workspace layout:
 
 ```json
 {
   "commands": [
     {
       "name": "dev",
-      "type": "workspace",
-      "cwd": ".",
-      "layout": {
-        "type": "split",
-        "direction": "horizontal",
-        "children": [
-          { "type": "pane", "surfaces": [{ "type": "terminal", "command": "bun dev" }] },
-          { "type": "pane", "surfaces": [{ "type": "browser", "url": "http://localhost:3000" }] }
-        ]
+      "workspace": {
+        "name": "Dev",
+        "cwd": ".",
+        "layout": {
+          "direction": "horizontal",
+          "children": [
+            { "pane": { "surfaces": [{ "type": "terminal", "command": "bun dev" }] } },
+            { "pane": { "surfaces": [{ "type": "browser", "url": "http://localhost:3000" }] } }
+          ]
+        }
       }
     }
   ]
 }
 ```
 
-Add surface toolbar buttons:
+Replace surface tab bar buttons:
 
 ```json
 {
@@ -105,12 +177,35 @@ Add surface toolbar buttons:
 }
 ```
 
+Add project Dock controls:
+
+```json
+{
+  "controls": [
+    {
+      "id": "git",
+      "title": "Git",
+      "command": "lazygit",
+      "cwd": ".",
+      "height": 300
+    },
+    {
+      "id": "feed",
+      "title": "Feed",
+      "command": "cmux feed tui --opentui",
+      "height": 260
+    }
+  ]
+}
+```
+
 ## Validation
 
 - App settings: run `cmux-settings validate`.
 - JSONC shape: keep valid JSONC and avoid duplicate keys.
+- Dock JSON: parse `.cmux/dock.json` or `~/.config/cmux/dock.json` with a JSON parser before reporting completion.
 - Runtime reload: run `cmux reload-config` when the CLI is available.
-- User-facing action: confirm the action title, shortcut, or toolbar placement the user asked for.
+- User-facing action: confirm the action title, shortcut, plus-button behavior, context-menu entry, or tab bar placement the user asked for.
 
 ## Rules
 

skills/cmux-customization/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "cmux Customization"
-  short_description: "Customize cmux actions, settings, and layouts."
-  default_prompt: "Use $cmux-customization to add a project-specific cmux action and validate the config."
+  short_description: "Customize cmux actions, UI, and layouts."
+  default_prompt: "Use $cmux-customization to replace my plus-button action and tab bar buttons, then validate the cmux config."

web/app/[locale]/docs/skills/page.tsx

@@ -160,7 +160,7 @@ export default function SkillsPage() {
         })}
       </p>
       <CodeBlock title={t("installWithVercel")} lang="bash">{`# Install all cmux skills
-npx skills add manaflow-ai/cmux --all -g -y
+npx skills add manaflow-ai/cmux -g -y
 
 # Or install just diagnostics
 npx skills add manaflow-ai/cmux --skill cmux-diagnostics -g -y`}</CodeBlock>

web/messages/en.json

@@ -808,8 +808,8 @@
       "settingsDescription": "Inspects, edits, validates, and opens ~/.config/cmux/cmux.json with a bundled helper script.",
       "settingsUse": "Use it when changing appearance, sidebar, notification, browser, automation, or shortcut settings by JSON path.",
       "customizationName": "cmux Customization",
-      "customizationDescription": "Customizes cmux.json actions, workspace layouts, toolbar buttons, Command Palette entries, shortcuts, and Ghostty-owned terminal preferences.",
-      "customizationUse": "Use it for multi-part workflow customization that spans actions, layouts, shortcuts, or app preferences.",
+      "customizationDescription": "Customizes cmux.json actions, plus-button behavior, tab bar buttons, workspace layouts, Dock controls, Feed hooks, sidebar settings, Command Palette entries, shortcuts, and Ghostty-owned terminal preferences.",
+      "customizationUse": "Use it to make cmux open a user's worktrees, multiple checkouts, SSH sessions, dev tools, or project layout from the exact UI entrypoints they want.",
       "diagnosticsName": "cmux Diagnostics",
       "diagnosticsDescription": "Runs support-safe checks for cmux CLI health, socket access, hooks, session restore, settings, and agent binaries.",
       "diagnosticsUse": "Use it when notifications, hooks, restore, or automation are not behaving as expected.",
@@ -829,8 +829,8 @@
       "workspaceReferences": "Workspace command reference covering context, windows, workspaces, panes, surfaces, input, sidebar state, notifications, docs, and tagged reloads.",
       "settingsScope": "cmux.json settings reads and writes, key lookup, JSONC parsing, safe atomic updates, validation, editor opening, and shortcut binding edits.",
       "settingsReferences": "Generated settings key list, shortcut action ids, schema URL, supported path detection, and the bundled cmux-settings helper.",
-      "customizationScope": "End-user customization across cmux.json settings, actions, commands, workspace layouts, toolbar buttons, Command Palette entries, shortcuts, and Ghostty config boundaries.",
-      "customizationReferences": "Config-surface selection, global versus project-local scope, action examples, workspace layout examples, reload steps, validation rules, and safety constraints.",
+      "customizationScope": "End-user customization across cmux.json settings, actions, commands, workspace layouts, plus-button click and right-click menus, surface tab bar buttons, Dock controls, Feed and notification hooks, sidebar metadata, Command Palette entries, shortcuts, and Ghostty config boundaries.",
+      "customizationReferences": "Config-surface selection, what can be customized, global versus project-local scope, action examples, plus-button wiring, tab bar button examples, Dock examples, Feed hooks, workspace layout examples, reload steps, validation rules, and safety constraints.",
       "diagnosticsScope": "Read-only health checks for CLI reachability, socket access, cmux environment, settings validation, hook installation markers, session stores, auto-resume settings, and supported agent binaries.",
       "diagnosticsReferences": "Bundled support-safe diagnostic script, hook setup commands, session restore interpretation, notification checks, and rules for redacting sensitive files.",
       "browserScope": "Browser automation inside cmux webview surfaces, including navigation, DOM actions, waits, state capture, screenshots, and snapshots.",