Conductor Documentation Audit
Conductor's docs are fresh (changelog updated the day before this audit), well-structured, and agent-friendly on the surface — llms.txt, llms-full.txt, and markdown exports everywhere — but the product has outgrown them: a hosted cloud offering is threaded through settings, shortcuts, and caveats without a single page documenting it, the machine-readable export silently drops key content, and keyboard shortcuts contradict each other across pages.
1. Conductor Cloud is promoted everywhere and documented nowhere (critical)
Location: https://www.conductor.build/cloud, /docs/reference/environment-variables, /docs/reference/settings/reference, /docs/reference/security-and-permissions, /docs/concepts/agent-modes
Problem: Every docs page carries an "Introducing Conductor Cloud →" banner linking to /cloud ("Run Conductor workspaces in the cloud. Create hosted workspaces for coding agents"). Cloud workspaces are load-bearing across the reference docs: CONDUCTOR_IS_LOCAL is "1 in local workspaces, 0 in cloud workspaces", run scripts take available_in = ["local", "cloud"], settings include environment_variables.cloud and ssh_key_path ("Path to the SSH private key used for cloud workspaces"), the keyboard cheatsheet has "⌘ + ⌥ + O Open cloud workspace remotely in app", and pages repeat caveats like "Files to copy currently runs for local Mac workspaces" and "Cloud workspaces do not support goals yet." Yet there is no docs page about cloud workspaces at all — nothing in llms.txt, nothing in sitemap.xml (/cloud itself is absent from the sitemap), no page explaining how to create one, what runs in it, or how it's secured. Worse, /docs/reference/security-and-permissions still asserts the opposite architecture: "Conductor is a Mac app, not a hosted IDE. Your workspaces, chats, and repository files are stored locally" — while the site's own privacy notice separately discusses data handling in a Conductor-managed cloud environment.
Consequence: Developers hit cloud-only settings keys, a cloud-remote shortcut, and "does not work in cloud workspaces" caveats with no way to learn what a cloud workspace is, how to get one, or what data leaves their machine. Anyone evaluating security reads a "stored locally" guarantee that the product's own hosted offering contradicts. Agents consuming llms.txt can't even discover the feature exists.
The fix: Add a "Cloud workspaces" concept + reference section (creation flow, requirements, SSH key usage, feature parity table for Files to copy/goals/Spotlight), add /cloud to the sitemap and llms.txt, and rewrite the security page's "stored locally" claim to distinguish local and cloud execution.
2. llms-full.txt silently drops critical page content and leaks JSX artifacts (critical)
Location: https://www.conductor.build/llms-full.txt (entries for /docs/reference/keyboard-shortcuts, /docs/configure-your-project, /docs/reference/settings)
Problem: The site advertises llms-full.txt as "All site markdown", but the export is lossy exactly where structure matters. The keyboard-shortcuts entry contains only "Use the keyboard shortcuts dialog for the current in-app list. Open it with Command + /." — the entire multi-section cheatsheet table visible on the live page (General, View, Navigation, Workspace, Chat, Code review, Terminal) is missing. The configure-your-project entry drops the full embedded "ask Conductor" setup prompt that the live page's Quick start card exposes via "Copy prompt / View prompt". And the settings page export contains raw JSX artifacts: "Your overrides for one project in{" "}\n.conductor/settings.local.toml." with the precedence list rendered as bare digits.
Consequence: Conductor's primary users are AI-agent power users, and agents reading the advertised markdown surface get an empty shortcuts page, a quick-start section whose actual prompt is missing, and template garbage inside the settings precedence explanation. The docs' best agent-integration feature quietly serves less content than the HTML.
The fix: Fix the markdown export pipeline to render component-backed content (tables, embedded prompts, styled lists) into the llms-full.txt output, and add a CI check that diffs exported text length against rendered page text.
3. ⌘⇧T means three different things depending on which page you read (significant)
Location: /docs/reference/big-terminal-mode vs /docs/reference/keyboard-shortcuts
Problem: The Big Terminal Mode page says "Open Big Terminal Mode with Command + Shift + T." The keyboard cheatsheet assigns ⌘ + ⇧ + T to "Reopen closed tab" (Navigation, Default context) and also to "New terminal tab" (Terminal, Default context) — and never lists Big Terminal Mode. The cheatsheet also lists ⌘ + O twice in the Workspace section with different actions ("Open repository in default app" and "Open in app"), both in "Default context".
Consequence: A developer cannot determine what ⌘⇧T actually does from the docs — the reference contradicts the feature page and itself. Duplicate bindings with identical "Works when" contexts make the cheatsheet unreliable as a reference.
The fix: Reconcile the shortcut table with the feature pages (add Big Terminal Mode's binding, or correct it), and disambiguate duplicate rows with accurate context conditions.
4. Troubleshooting sends users to Settings -> Storage for a setting every other page puts under Harnesses (significant)
Location: /docs/troubleshooting/issues ("Claude Code or Codex cannot find a command")
Problem: The troubleshooting fix says: "1. Open Settings -> Storage. 2. Find the Claude Code executable path or Codex executable path setting." Everywhere else, harness configuration lives in Settings -> Harnesses: the harness pages ("Claude Code auth status appears in Settings -> Harnesses"), the providers guide ("Configure harness auth in Settings -> Harnesses"), the FAQ, and the install page all point there. No other page mentions a Storage section for executable paths.
Consequence: A user debugging a broken agent — the worst moment to give wrong directions — is sent to a settings section that either doesn't exist or is the one place the rest of the docs never mention, and gives up or files a support ticket.
The fix: Verify where the executable-path setting actually lives in the current app and use one consistent path (Settings -> Harnesses or Storage) across all pages.
5. Managed settings switch to camelCase keys in an otherwise snake_case TOML surface (significant)
Location: /docs/reference/settings/managed, /docs/reference/settings/reference
Problem: Repository and user settings are uniformly snake_case: environment_variables, environment_variables.local, environment_variables.cloud, enterprise_data_privacy. The managed settings example and key table switch the same concept to camelCase: [environmentVariables.local], [environmentVariables.cloud] — in the same file that keeps enterprise_data_privacy and claude_code_executable_path snake_case. The managed schema URL is also the odd one out: repo files use settings.repo.schema.json, user files use settings.schema.json, but managed files use settings.toml.json.
Consequence: Admins (and agents) writing a managed file by analogy with the documented repository format will write environment_variables.local and, per the settings reference's described behavior of ignoring unrecognized managed keys, get silently dropped configuration. Mixed casing within a single example file reads like a typo, so nobody knows which spelling is authoritative.
The fix: Either align managed keys to snake_case in the product, or add an explicit callout ("managed files use environmentVariables, not environment_variables") plus a validation error instead of silent ignoring; give the managed schema a consistent name.
6. The "Quick start: ask Conductor" card says shared settings, its prompt writes local overrides (significant)
Location: /docs/configure-your-project ("Quick start: ask Conductor")
Problem: The card text says: "Open Conductor with the shared settings.toml setup prompt pre-filled." The prompt it pre-fills instructs the opposite: "create or update the .conductor/settings.local.toml file in the repo root… Inspect .conductor/settings.toml if it exists, but treat it as inherited shared defaults. Do not edit or duplicate shared settings." The page around it is explicitly about creating shared team settings ("Create .conductor/settings.toml at the root of your repository when the settings should be shared").
Consequence: A developer following the page's recommended path ("For most projects, start by asking Conductor") expects committed team settings and instead gets a gitignored machine-local file — the config silently never reaches teammates.
The fix: Make the card text match the prompt's target file (or offer two prompts: one for settings.toml, one for settings.local.toml) and state clearly which file the quick start produces.
7. "How does Conductor make money? Right now we don't" coexists with a hosted Cloud offering and an Enterprise page (minor)
Location: /docs/faq, /docs/reference/harnesses, https://www.conductor.build/cloud
Problem: The FAQ says "Right now we don't [make money]… for now we're focused on making Conductor an amazing free tool," and the harnesses overview says "Conductor is free to use." Meanwhile every docs page banners Conductor Cloud — a hosted-workspaces offering ("Create hosted workspaces for coding agents") — and the site nav on every docs page links an Enterprise page.
Consequence: Teams budgeting for Conductor get contradictory signals about pricing and commercial posture; the FAQ reads as stale the moment a reader sees the Cloud banner at the top of the same page.
The fix: Update the FAQ monetization answer to reflect Cloud/Enterprise, or scope the "free" claims to the local Mac app explicitly.
8. Workspace-creation shortcut is ⌘N on concept pages and ⌘⇧N in the guides (minor)
Location: /docs/concepts/parallel-agents, /docs/guides/git-worktrees/* vs /docs/first-workspace, /docs/guides/parallel-agents/*
Problem: Concept pages say "Create a new workspace with Command + N when work should have its own branch," while the parallel-agents guides say "Create a workspace with Command + Shift + N or the ... button next to New workspace" for the same create-one-workspace-per-task step. Per the live cheatsheet these are different commands: ⌘N is "Create new workspace" and ⌘⇧N is "Create new workspace from PR, branch, or issue."
Consequence: Two pages describing the identical action name different shortcuts without explaining the distinction, so readers (and agents summarizing the docs) conflate the plain-create and create-from flows.
The fix: Standardize on ⌘N for plain creation, and only cite ⌘⇧N where the step genuinely starts from a PR, branch, or issue — with a one-line note on the difference.
9. Bedrock example mixes bare model aliases with a fully versioned model ID (minor)
Location: /docs/guides/providers ("Bedrock")
Problem: One code block sets ANTHROPIC_DEFAULT_OPUS_MODEL=us.anthropic.claude-opus-4-7 and ANTHROPIC_DEFAULT_SONNET_MODEL=us.anthropic.claude-sonnet-4-6 (no version suffix) next to ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0 (full Bedrock inference-profile ID with date and version).
Consequence: Bedrock model identifiers are exact strings; a developer copy-pasting this block can't tell whether the short aliases are valid or whether the Haiku line's format is what Bedrock actually requires, turning a config example into a guessing game.
The fix: Use the same, verified ID format for all three variables and note where to look up current Bedrock model IDs.
10. The docs disagree on whether OpenCode is "bundled" (minor)
Location: /docs/reference/harnesses vs /docs/faq
Problem: The harnesses overview says "Claude Code, Codex, and OpenCode come bundled in Conductor. You do not need to install them separately." The FAQ answers the direct question "Which versions of Claude Code, Codex, and OpenCode does Conductor use?" with "Conductor comes bundled with its own installation of Claude Code and Codex" at ~/Library/Application Support/com.conductor.app/bin — and describes OpenCode only as "Conductor's managed OpenCode integration," never as bundled or present at that path.
Consequence: Users trying to locate, pin, or debug the OpenCode binary get two different stories about whether it ships with the app, right where the FAQ promises version specifics.
The fix: State in both places exactly which binaries ship in the app bundle, where each lives on disk, and what "managed integration" means for OpenCode.
What they do well
- First-class machine-readable surface: llms.txt, a 307 KB llms-full.txt, markdown changelog, and published TOML JSON schemas — the plumbing agents want is all there.
- External references are healthy: every probed outbound link (Anthropic, OpenAI, Cursor, OpenCode, MCP, AWS, schema URLs) returned 200.
- The docs are genuinely current — the changelog's latest release is one day old, and reference pages document exact runtime behavior (SIGHUP → 200ms → SIGKILL, 10-port allocation per workspace).
Top 3 recommendations
- Document Conductor Cloud: a concept page, a reference page, and a corrected security/privacy story — before more cloud-only keys and caveats accumulate.
- Fix the llms-full.txt export so component-backed content (shortcut tables, embedded prompts) survives, and diff exported vs rendered text in CI.
- Do a single consistency pass on UI paths and shortcuts (Settings -> Storage vs Harnesses, ⌘⇧T, ⌘N vs ⌘⇧N) driven by the actual app.