docs: tighten Clawdie Studio Zed integration guardrails

docs/CLAWDIE-STUDIO-PROPOSAL.md

@@ -66,8 +66,7 @@ colibri-daemon
 This gives the all-in-one feel without making the editor responsible for
 supervision. The daemon runs even when the editor is closed.
 
-**Implementation:** Zed extension that renders a Colibri sidebar panel,
-consuming the socket API via `colibri-client`.
+**Implementation:** start with Zed tasks/terminal commands and MCP. A native Zed sidebar can come later, but the exact extension API/socket constraints must be verified on the target Zed build before assuming an extension can link `colibri-client` or open the Unix socket directly.
 
 ### Level 2 — Mid-term: MCP Integration (highest leverage)
 
@@ -141,15 +140,28 @@ clawdie-studio (the package)
 
 Phase 1 MCP tools (minimal viable set):
 
-| Tool | Description |
-|------|-------------|
-| `colibri_status` | Daemon status (agents, sessions, host) |
-| `colibri_snapshot` | Glasspane snapshot (all pane states) |
-| `colibri_list_tasks` | Tasks by status (queued/claimed/done/failed) |
-| `colibri_create_task` | Create a task from current context |
-| `colibri_intake_task` | Submit intake task with capabilities |
-| `colibri_agent_state` | Current agent state for a pane |
-| `colibri_set_cost_mode` | Switch cost mode (fast/smart/max) |
+| Tool | Description | Default |
+|------|-------------|---------|
+| `colibri_status` | Daemon status (agents, sessions, host, paths, cost mode) | read-only |
+| `colibri_snapshot` | Glasspane snapshot (all pane states) | read-only |
+| `colibri_list_tasks` | Tasks by status (queued/claimed/done/failed) | read-only |
+| `colibri_agent_state` | Current agent state for a pane | read-only |
+| `colibri_create_task` | Create a task from current context | write-gated |
+| `colibri_intake_task` | Submit intake task with capabilities | write-gated |
+| `colibri_set_cost_mode` | Acknowledge requested mode; runtime-only/status-intent until live config exists | write-gated |
+
+Default ISO posture should be **read-only**. Mutating tools require:
+
+```sh
+COLIBRI_MCP_WRITE=1
+```
+
+Agent spawn/kill tools are stronger than normal writes and should require a separate guard plus allowlist:
+
+```sh
+COLIBRI_MCP_SPAWN=1
+COLIBRI_MCP_SPAWN_ALLOWLIST=/usr/local/bin/pi,/usr/local/bin/colibri-smoke-agent
+```
 
 Phase 2 MCP tools (after basics proven):
 
@@ -173,8 +185,29 @@ colibri-mcp        ← NEW: thin MCP bridge using colibri-client
 colibri-studio     ← NEW: launcher binary (thin wrapper)
 ```
 
-No existing crates change. Two new thin binaries wrap existing
-infrastructure.
+No existing crates need architectural changes. Two new thin binaries wrap existing infrastructure. The MCP binary should default its socket path from `COLIBRI_DAEMON_SOCKET`, then `/var/run/colibri/colibri.sock`.
+
+## Zed task fallback
+
+Before MCP/native UI exists, Zed can still be Colibri-aware through project tasks or terminal commands:
+
+```sh
+colibri status
+colibri snapshot
+colibri list-tasks --status queued
+colibri intake-task --title "review current project" --capability freebsd
+```
+
+This is sufficient for the next ISO if Zed is present but the integration bridge is not yet packaged.
+
+## Implementation guardrails
+
+- Colibri remains service-owned and headless-safe; Zed never becomes required for boot or supervision.
+- MCP is the first real editor bridge because it avoids forking Zed and can serve other MCP-capable clients.
+- Native Zed extension/panel is a later UX layer, not the protocol source of truth.
+- Write tools are opt-in; spawn tools are separately guarded and allowlisted.
+- `set-cost-mode` remains runtime-only acknowledgement until a real mutable config model is implemented.
+- No arbitrary shell command tool in MCP.
 
 ## Decision Points