docs: more content

Author: ammario

README.md

@@ -13,26 +13,32 @@
 
 A cross-platform desktop application for parallel agentic development.
 
-## Features
+<details>
+<summary>Why parallelize?</summary>
+
+Here are some specific use cases we enable:
 
-The overall experience should be familiar to Claude Code power users, we strive for parity with the best parts of Claude Code:
+- **Contextual continuity between relevant changes**:
+  - e.g. create a workspace for `code-review`, `refactor`, and `new-feature`
+- **GPT-5-Pro**: use the slow but powerful GPT-5-Pro for complex issues
+  - Run in the background for hours on end
+  - The stream will automatically resume after restarts or intermittent connection issues. If the model completes early we will show an indicator.
+- **A/B testing**: run multiple workspaces in parallel on the same problem but different approaches,
+  abandon the bad ones.
+- **Tangent exploration**: launch tangents in `cmux` away from main work
 
-- Plan/Exec modes
-- `/compact` based manual compaction
-- vim mode in input box
+</details>
+
+## Features
 
-But, the agentic loop is custom. Our goal is to create an experience that is as immersive and rich as an IDE. In fact, we think
-of cmux as the IDE of the future. We go beyond Claude Code with:
+- Isolated workspaces with central view on git status updates
+- Multi-model (`sonnet-4-*`, `gpt-5-*`, `opus-4-*`)
+- Supporting UI and keybinds for efficiently managing a suite of agents
+- Rich markdown outputs (mermaid diagrams, LaTeX, etc.)
 
-- Live git status updates for each workspace
-- Workspace isolation
-  - Worktrees today, Docker containers / remote compute tomorrow
-- [More compaction control](https://cmux.io/context-management.html)
-- Automatic resumption after app restart
-- Rich markdown rendering of plans and assistant messages
-  - Mermaid diagrams
-  - LaTeX
-  - Toggles!
+`cmux` has a custom agent loop, but, we are heavily inspired by Claude Code in our
+UX. You'll find familiar features like Plan/Exec mode, VIM inputs, `/compact` and new ones
+like [opportunistic compaction](https://cmux.io/context-management.html) and [mode prompts](https://cmux.io/instruction-files.html#mode-prompts).
 
 📚 **[Read the full documentation →](https://cmux.io)**
 

docs/SUMMARY.md

@@ -2,10 +2,13 @@
 
 - [Introduction](./intro.md)
 - [Install](./install.md)
+- [Why Parallelize?](./why-parallelize.md)
+- [Models](./models.md)
 - [Keyboard Shortcuts](./keybinds.md)
-- [Vim Mode](./vim-mode.md)
+  - [Vim Mode](./vim-mode.md)
 - [Context Management](./context-management.md)
+- [System Prompt](./system-prompt.md)
 - [Instruction Files](./instruction-files.md)
 - [Project Secrets](./project-secrets.md)
-- [Agentic Git Identity](./agentic-git-identity.md)
+  - [Agentic Git Identity](./agentic-git-identity.md)
 - [AGENTS](./AGENTS.md)

docs/instruction-files.md

@@ -9,9 +9,11 @@ cmux layers instructions from two locations:
 
 Priority within each location: `AGENTS.md` → `AGENT.md` → `CLAUDE.md` (first match wins). If the base file is found, cmux also appends `AGENTS.local.md` from the same directory when present.
 
-## Mode-specific sections (no separate files)
+## Mode Prompts
 
-Instead of separate files like `PLAN.md`, cmux reads mode context from sections inside your instruction files. Add a heading titled:
+> Use mode-specific sections to optimize context and customize the behavior specific modes.
+
+cmux reads mode context from sections inside your instruction files. Add a heading titled:
 
 - `Mode: <mode>` (case-insensitive), at any heading level (`#` .. `######`)
 

docs/models.md

@@ -0,0 +1,20 @@
+## Models
+
+See also:
+
+- [System Prompt](./system-prompt.md)
+
+Currently we support the Sonnet 4 models and GPT-5 family of models:
+
+- `anthropic:claude-sonnet-4-5`
+- `anthropic:claude-opus-4-1`
+- `openai:gpt-5`
+- `openai:gpt-5-pro`
+- `openai:gpt-5-codex`
+
+And we intend to always support the models used by 90% of the community.
+
+Anthropic models are better supported than GPT-5 class models due to an outstanding issue in the
+Vercel AI SDK.
+
+TODO: add issue link here.

docs/system-prompt.md

@@ -0,0 +1,48 @@
+# System Prompt
+
+`cmux` is interested in supporting a variety of models at different levels of performance.
+
+To that end, we're built on the [Vercel AI SDK](https://ai-sdk.dev/providers/ai-sdk-providers) which does most of the heavy lifting in creating a unified API for all models.
+
+Even with consistent support at the protocol layer, we have found that different models react very differently to the same set of tools and instructions. So, **we strive to minimize the system prompt and let users figure out the prompting trade-offs**.
+
+Here's a snippet from `src/services/systemMessage.ts` which is our shared system prompt (minus tools).
+
+<!-- keep this in sync with the code above -->
+
+```typescript
+// The PRELUDE is intentionally minimal to not conflict with the user's instructions.
+// cmux is designed to be model agnostic, and models have shown large inconsistency in how they
+// follow instructions.
+const PRELUDE = `
+<prelude>
+You are a coding agent.
+  
+<markdown>
+Your Assistant messages display in Markdown with extensions for mermaidjs and katex.
+
+When creating mermaid diagrams:
+- Avoid side-by-side subgraphs (they display too wide)
+- For comparisons, use separate diagram blocks or single graph with visual separation
+- When using custom fill colors, include contrasting color property (e.g., "style note fill:#ff6b6b,color:#fff")
+- Make good use of visual space: e.g. use inline commentary
+- Wrap node labels containing brackets or special characters in quotes (e.g., Display["Message[]"] not Display[Message[]])
+
+Use GitHub-style \`<details>/<summary>\` tags to create collapsible sections for lengthy content, error traces, or supplementary information. Toggles help keep responses scannable while preserving detail.
+</markdown>
+</prelude>
+`;
+
+function buildEnvironmentContext(workspacePath: string): string {
+  return `
+<environment>
+You are in a git worktree at ${workspacePath}
+
+- This IS a git repository - run git commands directly (no cd needed)
+- Tools run here automatically
+- Do not modify or visit other worktrees (especially the main project) without explicit user intent
+- You are meant to do your work isolated from the user and other agents
+</environment>
+`;
+}
+```

docs/why-parallelize.md

@@ -0,0 +1,13 @@
+# Why Parallelize?
+
+Here are some specific use cases we enable:
+
+- **Contextual continuity between relevant changes**:
+  - e.g. create a workspace for `code-review`, `refactor`, and `new-feature`
+- **GPT-5-Pro**: use the slow but powerful GPT-5-Pro for complex issues
+  - Run in the background for hours on end
+  - The stream will automatically resume after restarts or intermittent connection issues. We show
+    a subtle indicator when the model completes.
+- **A/B testing**: test a variety of approaches to the same problem,
+  abandon the bad ones.
+- **Tangent management**: launch tangents in `cmux` away from main work

src/services/systemMessage.ts

@@ -4,10 +4,12 @@ import type { WorkspaceMetadata } from "@/types/workspace";
 import { gatherInstructionSets, readInstructionSet } from "@/utils/main/instructionFiles";
 import { extractModeSection } from "@/utils/main/markdown";
 
+// NOTE: keep this in sync with the docs/models.md file
+
 // The PRELUDE is intentionally minimal to not conflict with the user's instructions.
 // cmux is designed to be model agnostic, and models have shown large inconsistency in how they
 // follow instructions.
-const PRELUDE = `
+const PRELUDE = ` 
 <prelude>
 You are a coding agent.