ac-framework 1.9.5 → 1.9.7

package/framework/mobile_development/.codebuddy/commands/opsx/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.continue/prompts/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.cospec/openspec/commands/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.crush/commands/opsx/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.cursor/commands/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.factory/commands/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY

package/framework/mobile_development/.gemini/commands/opsx/ac.md

@@ -93,6 +93,46 @@ The AC Framework includes a persistent memory system that agents must use proact
 
 **User communication:** `Memory saved: [brief description]`
 
+### SynapseGrid Collaborative MCP Protocol (Optional)
+
+If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
+
+**Session-start requirement when collaboration is enabled:**
+1. Prefer the available SynapseGrid MCP tools for collaborative session control before falling back to direct CLI.
+2. Use shared session state and transcript as the source of truth for role-by-role collaboration.
+3. If collaborative MCP is unavailable, use CLI fallback commands and keep behavior equivalent.
+
+**How to use SynapseGrid collaboration:**
+```text
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
+Fallback: use AC Framework agents CLI commands directly.
+```
+```bash
+# Install/update collaborative MCP server integrations
+acfm agents install-mcps
+
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
+
+# Resume/list/export operations
+acfm agents resume
+acfm agents list
+acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
+```
+
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ## SynapseGrid Collaborative MCP Protocol (Optional)
 
 If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborative MCP server automatically for detected assistants.
@@ -104,22 +144,35 @@ If SynapseGrid is enabled in `acfm init`, AC Framework installs the collaborativ
 
 **How to use SynapseGrid collaboration:**
 ```text
-Preferred: use SynapseGrid MCP tools (ac-framework-collab) for session start/status/step/stop.
+Preferred: use SynapseGrid MCP tools (ac-framework-collab) for start/status/step/resume/stop.
 Fallback: use AC Framework agents CLI commands directly.
 ```
 ```bash
-# Optional install/reinstall of collaborative MCP servers
+# Install/update collaborative MCP server integrations
 acfm agents install-mcps
 
-# Start collaborative runtime manually
-acfm agents start --task "design and implement feature X"
+# Start collaborative runtime with visible 4-pane tmux war-room
+acfm agents start --task "design and implement feature X" --attach --model-coder provider/model
+
+# If already running in background, attach to panes and inspect logs
+acfm agents live
+acfm agents logs --role all --lines 120
 
 # Resume/list/export operations
 acfm agents resume
 acfm agents list
 acfm agents export --format md --out synapse-session.md
+
+# Fast diagnostics for OpenCode resolution errors
+acfm agents setup
 ```
 
+**Troubleshooting notes:**
+- If transcript shows `Agent failed: spawn opencode ENOENT`, run `acfm agents setup` and restart/resume session.
+- If session exists but panes are not visible, use `acfm agents live` (or `acfm agents attach`) or `tmux attach -t <session-name>`.
+- For MCP-first flows, ensure session start enables worker spawning so tmux panes are created.
+- Per-role models can be set at start (`--model-planner`, `--model-critic`, `--model-coder`, `--model-reviewer`) or persisted via `acfm agents model set`.
+
 ---
 
 ## CRITICAL: How to Use Skills - ZERO SKIP POLICY