docs: update and fmt

Author: ammario

.github/actions/setup-cmux/action.yml

@@ -1,7 +1,7 @@
-name: 'Setup Cmux'
-description: 'Setup Bun and install dependencies with caching'
+name: "Setup Cmux"
+description: "Setup Bun and install dependencies with caching"
 runs:
-  using: 'composite'
+  using: "composite"
   steps:
     - name: Setup Bun
       uses: oven-sh/setup-bun@v2
@@ -18,4 +18,4 @@ runs:
 
     - name: Install dependencies
       shell: bash
-      run: bun install --frozen-lockfile
+      run: bun install --frozen-lockfile

.github/workflows/release.yml

@@ -5,7 +5,7 @@ on:
     types: [published]
 
 permissions:
-  contents: write  # Required for electron-builder to upload release assets
+  contents: write # Required for electron-builder to upload release assets
 
 jobs:
   build-macos:

README.md

@@ -44,6 +44,10 @@ like [opportunistic compaction](https://cmux.io/context-management.html) and [mo
 
 ## Quick Install
 
+> [!WARNING]  
+> cmux is in a Preview state. You will encounter bugs and performance issues.
+> It's still possible to be highly productive. We are using it almost exclusively for our own development.
+
 Download pre-built binaries from [the releases page](https://github.com/coder/cmux/releases):
 
 - **macOS**: Signed and notarized DMG (separate builds for Intel/Apple Silicon)

docs/SUMMARY.md

@@ -1,15 +1,27 @@
 # Summary
 
+# Introduction
+
 - [Introduction](./intro.md)
 - [Install](./install.md)
 - [Why Parallelize?](./why-parallelize.md)
+
+# Features
+
 - [Models](./models.md)
 - [Keyboard Shortcuts](./keybinds.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)
+
+# Advanced
+
+- [Prompting Tips](./prompting-tips.md)
+- [System Prompt](./system-prompt.md)
+
+# Development
+
 - [Terminal Benchmarking](./benchmarking.md)
 - [AGENTS](./AGENTS.md)

docs/prompting-tips.md

@@ -0,0 +1,60 @@
+# Prompting Tips
+
+> Some tips and tricks from the cmux developers on getting the most out of your agents.
+
+## Persist lessons
+
+When you notice agents make the same class of mistake repeatedly, ask them to modify their `AGENTS.md`
+to prevent the mistake from happening again. We have found this pattern is most effective when:
+
+- You specify the size of the change
+  - LLMs love fluff — always specify a size constraint like "change at most two sentences"
+- Ask the agent to focus on the general lesson, not the specific mistake
+
+Codebases often have "watering hole" type files that are read in the course of
+certain types of changes. For example, you may have a central file defining an API interface. When
+the lesson is only relevant to a particular type of change it's often better to persist lessons as
+source comments in such files vs. expanding the global `AGENTS.md`.
+
+## Define the loop
+
+Agents thrive on TDD. Try to define their task in terms of what checks need to pass before they
+can claim success.
+
+For cmux development, we have a [`wait_pr_checks.sh`](https://github.com/coder/cmux/blob/main/scripts/wait_pr_checks.sh) script
+that polls GitHub and ensures that:
+
+- There are no dirty changes
+- All checks pass
+- All review comments are resolved
+- There are no merge conflicts
+
+Create a similar script for your project and try asking your agent to work persistently until it
+passes.
+
+## Aggressively prune context
+
+Even though Sonnet 4.5 has up to 1M in potential context, we experience a noticeable improvement in
+quality when kept <100k tokens. We suggest running `/compact -c "<what you want next>"`
+often to keep context small. The `-c` flag will automatically send a follow up message post-compaction
+to keep the session flowing.
+
+## Keeping code clean
+
+Some prompts that help you keep the codebase clean:
+
+Elevate the fix to design level:
+
+- We keep seeing this class of bug in component X, fix this at a design level
+- There's bug X, provide a fix that solves the whole class of bugs
+
+At the end of a long session before compaction, try asking:
+
+- How can the code/architecture be improved to make similar changes easier?
+- What notes in AGENTS.md would make this change easier for future Assistants?
+
+At end of long session (ideally after compaction), try asking:
+
+- DRY your work
+- Strive for net LoC reduction
+- Review in depth, simplify

docs/theme/custom.css

@@ -23,6 +23,7 @@
   --color-interrupted: hsl(38 92% 50%);
 
   /* Docs-specific tokens */
+  --color-code: hsl(214.52deg 100% 71.11%);
   --link-color: var(--color-plan-mode);
   --link-hover: var(--color-plan-mode-hover);
   --content-max-width: 78ch;
@@ -48,6 +49,7 @@
   --sidebar-fg: var(--color-text) !important;
   --icons: var(--color-text-secondary) !important;
   --table-alternate-bg: var(--color-background-secondary) !important;
+  --line-height: 1.6;
 }
 
 /* Base layout and typography */
@@ -63,14 +65,15 @@ body {
 
 .content .page,
 .content {
+  line-height: var(--line-height);
   background: var(--color-background) !important;
 }
 
 .content .chapter {
   max-width: var(--content-max-width);
   margin: 0 auto;
   padding: 2rem 2.25rem;
-  line-height: 1.65;
+  line-height: var(--line-height);
   letter-spacing: 0.01em;
 }
 
@@ -142,6 +145,10 @@ a:focus-visible {
   background: var(--sidebar-bg) !important;
   border-right: 1px solid var(--color-border) !important;
 }
+.sidebar .part-title {
+  color: color-mix(in srgb, var(--color-text), white 20%) !important;
+  font-weight: 700;
+}
 .sidebar .chapter li.chapter-item a {
   color: var(--color-text) !important;
 }
@@ -150,8 +157,8 @@ a:focus-visible {
   background: transparent !important;
 }
 .sidebar .chapter li.chapter-item a:hover {
-  color: var(--color-text) !important;
-  background: color-mix(in srgb, var(--color-background-secondary), white 2%);
+  color: var(--link-hover) !important;
+  background: color-mix(in srgb, var(--color-background-secondary), white 8%);
 }
 .sidebar-resize-handle {
   background: var(--color-background-secondary) !important;
@@ -205,16 +212,25 @@ a:focus-visible {
 }
 
 .content ul {
-  line-height: 2;
+  margin-block-start: 0;
+  line-height: 1.6;
+}
+
+.content p {
+  line-height: var(--line-height);
+}
+
+/* Remove margin between p and following list */
+p:has(+ ul),
+p:has(+ ol) {
+  margin-block-end: 0.5em;
 }
 
 /* Inline code */
 :not(pre) > code {
   background: var(--color-background-secondary) !important;
-  color: var(--color-edit-mode) !important;
-  border-radius: var(--radius-xs);
+  color: var(--color-code) !important;
   padding: 2px 6px;
-  border: 1px solid var(--color-border);
   font-family: var(--font-monospace);
   font-size: 0.92em;
 }
@@ -223,14 +239,13 @@ a:focus-visible {
 pre {
   background: var(--color-background-secondary) !important;
   border: 1px solid var(--color-border) !important;
-  border-radius: var(--radius-md);
   box-shadow: var(--shadow-1);
   overflow: auto;
   margin: 1rem 0;
 }
 pre > code {
   background: transparent !important;
-  color: var(--color-text) !important;
+  color: var(--color-code) !important;
   display: block;
   padding: 0.9rem 1rem;
   font-family: var(--font-monospace);
@@ -251,7 +266,7 @@ table {
   border-radius: var(--radius-md);
 }
 table thead {
-  background: color-mix(in srgb, var(--color-background-secondary), black 5%);
+  background: color-mix(in srgb, var(--color-background-secondary), white 8%);
   border-bottom: 2px solid var(--color-border) !important;
 }
 table th,
@@ -262,26 +277,28 @@ table td {
   color: var(--color-text) !important;
 }
 table th {
-  font-weight: 600;
+  font-weight: 700;
+  font-size: 1.05em;
+  color: color-mix(in srgb, var(--color-text), white 10%) !important;
 }
 table tbody tr:hover {
   background: color-mix(in srgb, var(--color-background-secondary), white 2%) !important;
 }
 table code {
   background: var(--color-background) !important;
-  color: var(--color-interrupted) !important;
+  color: var(--color-code) !important;
   font-family: var(--font-monospace);
   font-size: 0.9em;
 }
 
 /* Blockquotes (callout style) */
 blockquote {
+  border: 1px solid var(--color-border) !important;
   border-left: 4px solid var(--color-plan-mode) !important;
   background: color-mix(in srgb, var(--color-background-secondary), white 1.5%) !important;
-  padding: 1rem 1.2rem;
+  padding: 0.5rem 0.6rem;
   margin: 1.2rem 0;
   color: color-mix(in srgb, var(--color-text), white 6%) !important;
-  border-radius: 0 var(--radius-md) var(--radius-md) 0;
 }
 blockquote strong {
   color: var(--color-plan-mode) !important;

playwright.config.ts

@@ -11,10 +11,7 @@ export default defineConfig({
   fullyParallel: true,
   forbidOnly: isCI,
   retries: isCI ? 1 : 0,
-  reporter: [
-    ["list"],
-    ["html", { outputFolder: "artifacts/playwright-report", open: "never" }],
-  ],
+  reporter: [["list"], ["html", { outputFolder: "artifacts/playwright-report", open: "never" }]],
   use: {
     trace: isCI ? "on-first-retry" : "retain-on-failure",
     screenshot: "only-on-failure",

scripts/lint.sh

@@ -9,7 +9,7 @@ cd "$PROJECT_ROOT"
 
 # Check for PNG files in docs - suggest WebP instead
 echo "Checking for PNG files in docs..."
-PNG_FILES=$(find docs -name "*.png" 2>/dev/null || true)
+PNG_FILES=$(git ls-files 'docs/*.png' 'docs/**/*.png' 2>/dev/null || true)
 if [ -n "$PNG_FILES" ]; then
   echo "❌ Error: PNG files found in docs directory. Please use WebP format instead:"
   echo "$PNG_FILES"

src/utils/main/README.md

@@ -1,13 +1,13 @@
 # utils/main
 
-**Main process utilities only.** 
+**Main process utilities only.**
 
-This directory contains utilities that depend on Node.js APIs (fs, path, os, etc.) 
+This directory contains utilities that depend on Node.js APIs (fs, path, os, etc.)
 and can only be used in the main Electron process.
 
 ## Architecture Boundary
 
-An ESLint rule prevents renderer code (components, hooks, contexts) from importing 
+An ESLint rule prevents renderer code (components, hooks, contexts) from importing
 from this directory. This ensures:
 
 - No Node.js APIs leak into the browser bundle
@@ -17,13 +17,15 @@ from this directory. This ensures:
 ## When to Add Code Here
 
 Place utilities here if they:
+
 - Use Node.js filesystem APIs (fs, fs/promises)
 - Access OS-level information (os module)
 - Perform system-level operations (child_process, etc.)
 
 ## When NOT to Use
 
 If your utility:
+
 - Works with pure data transformations → `src/utils/`
 - Needs to be shared with renderer → `src/utils/` or use IPC
 - Is frontend-specific → `src/utils/` or component helpers