[dh] docs: add troubleshooting sections to harness docs

docs/SKILLS_FOR_HOST_AGENTS.md

@@ -127,6 +127,19 @@ Before guessing about Coast behavior, explore the docs:
   coast docs --path concepts_and_terminology/BUILDS.md
   coast search-docs "your question here"         # semantic search
 
+## Troubleshooting
+
+If you run into issues with harness configuration (e.g. worktrees not being
+found, `coast lookup` not matching), read the troubleshooting section of the
+relevant harness doc:
+
+  coast docs --path harnesses/CLAUDE_CODE.md
+  coast docs --path harnesses/CODEX.md
+  coast docs --path harnesses/CONDUCTOR.md
+  coast docs --path harnesses/CURSOR.md
+  coast docs --path harnesses/T3_CODE.md
+  coast docs --path harnesses/SHEP.md
+
 ## Rules
 
 - Always run `coast lookup` before your first runtime command in a session.

docs/harnesses/CLAUDE_CODE.md

@@ -131,6 +131,13 @@ api = "hot"
 - `.claude/worktrees/` — Claude Code worktrees
 - `~/.codex/worktrees/` — Codex worktrees if you also use Codex in this repo
 
+## Troubleshooting
+
+- **Worktree not found** — If Coasts expects a worktree to exist but cannot
+  find it, verify that the Coastfile's `worktree_dir` includes
+  `.claude/worktrees`. See [Worktree Directories](../coastfiles/WORKTREE_DIR.md)
+  for syntax and path types.
+
 ## Limitations
 
 - If you duplicate the same `/coasts` workflow across `CLAUDE.md`,

docs/harnesses/CODEX.md

@@ -121,6 +121,13 @@ api = "hot"
 - `.claude/worktrees/` -- Claude Code (local, no special handling)
 - `~/.codex/worktrees/` -- Codex (external, bind-mounted)
 
+## Troubleshooting
+
+- **Worktree not found** — If Coasts expects a worktree to exist but cannot
+  find it, verify that the Coastfile's `worktree_dir` includes
+  `~/.codex/worktrees`. See [Worktree Directories](../coastfiles/WORKTREE_DIR.md)
+  for syntax and path types.
+
 ## Limitations
 
 - Codex may clean up worktrees at any time. The orphan detection in Coasts

docs/harnesses/CONDUCTOR.md

@@ -31,6 +31,8 @@ worktree_dir = [".worktrees", "~/conductor/workspaces/my-app"]
 
 Conductor allows you to configure the workspaces path per-repository, so the default `~/conductor/workspaces` may not match your setup. Check your Conductor repository settings to find the actual path and adjust accordingly — the principle is the same regardless of where the directory lives.
 
+If you have more than one Conductor project configured for the same repository, each project creates workspaces under its own subdirectory (e.g. `~/conductor/workspaces/my-app-frontend`, `~/conductor/workspaces/my-app-backend`). The `worktree_dir` entry must match the directory name Conductor actually creates, so you may need multiple entries or need to update the path when switching between projects.
+
 Coasts expands `~` at runtime and treats any path starting with `~/` or `/` as
 external. See [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for
 details.
@@ -99,6 +101,21 @@ api = "hot"
 
 - `~/conductor/workspaces/my-app/` — Conductor (external, bind-mounted; replace `my-app` with your repo folder name)
 
+## Troubleshooting
+
+- **Worktree not found** — If Coasts expects a worktree to exist but cannot
+  find it, verify that the Coastfile's `worktree_dir` includes the correct
+  `~/conductor/workspaces/<project-name>` path. The `<project-name>` segment
+  must match the actual folder name Conductor creates under
+  `~/conductor/workspaces/`. See
+  [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and path
+  types.
+- **Multiple projects for the same repo** — If more than one Conductor project
+  is configured for the same repository, each project creates workspaces under
+  a different subdirectory. The `worktree_dir` must be updated to match the
+  directory Conductor dynamically creates for the active project. If you switch
+  between projects, the path changes and the Coastfile needs to reflect that.
+
 ## Conductor Env Vars
 
 - Avoid relying on Conductor-specific environment variables (e.g.,

docs/harnesses/CURSOR.md

@@ -170,6 +170,15 @@ api = "hot"
 - `~/.codex/worktrees/` — Codex worktrees
 - `~/.cursor/worktrees/my-app/` — Cursor Parallel Agent worktrees
 
+## Troubleshooting
+
+- **Worktree not found** — If Coasts expects a worktree to exist but cannot
+  find it, verify that the Coastfile's `worktree_dir` includes
+  `~/.cursor/worktrees/<project-name>` and that `<project-name>` matches the
+  actual folder name under `~/.cursor/worktrees/`. See
+  [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and path
+  types.
+
 ## Limitations
 
 - If you are not using Cursor Parallel Agents, do not add

docs/harnesses/SHEP.md

@@ -115,3 +115,11 @@ Key points:
 - Different repos = different hashes
 - Path separators are normalized to `/` before hashing
 - The hash can be found via `shep feat show <feature-id>` or `ls ~/.shep/repos`
+
+## Troubleshooting
+
+- **Worktree not found** — If Coasts expects a worktree to exist but cannot
+  find it, verify that the Coastfile's `worktree_dir` includes
+  `~/.shep/repos/*/wt`. The glob pattern must match Shep's directory structure.
+  See [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and
+  path types.

docs/harnesses/T3_CODE.md

@@ -106,6 +106,15 @@ api = "hot"
 - `~/.codex/worktrees/` — Codex (external, bind-mounted)
 - `~/.t3/worktrees/my-app/` — T3 Code (external, bind-mounted; replace `my-app` with your repo folder name)
 
+## Troubleshooting
+
+- **Worktree not found** — If Coasts expects a worktree to exist but cannot
+  find it, verify that the Coastfile's `worktree_dir` includes
+  `~/.t3/worktrees/<project-name>` and that `<project-name>` matches the
+  actual folder name under `~/.t3/worktrees/`. See
+  [Worktree Directories](../coastfiles/WORKTREE_DIR.md) for syntax and path
+  types.
+
 ## Limitations
 
 - Avoid relying on T3 Code-specific environment variables for runtime

docs/skills_prompt.txt

@@ -81,6 +81,19 @@ Before guessing about Coast behavior, explore the docs:
   coast docs --path concepts_and_terminology/BUILDS.md
   coast search-docs "your question here"         # semantic search
 
+## Troubleshooting
+
+If you run into issues with harness configuration (e.g. worktrees not being
+found, `coast lookup` not matching), read the troubleshooting section of the
+relevant harness doc:
+
+  coast docs --path harnesses/CLAUDE_CODE.md
+  coast docs --path harnesses/CODEX.md
+  coast docs --path harnesses/CONDUCTOR.md
+  coast docs --path harnesses/CURSOR.md
+  coast docs --path harnesses/T3_CODE.md
+  coast docs --path harnesses/SHEP.md
+
 ## Rules
 
 - Always run `coast lookup` before your first runtime command in a session.