specsmith 0.20.1.dev748__tar.gz → 0.20.1.dev751__tar.gz

{specsmith-0.20.1.dev748/src/specsmith.egg-info → specsmith-0.20.1.dev751}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.20.1.dev748
+Version: 0.20.1.dev751
 Summary: AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider.
 Author: Layer1Labs Silicon, Inc.
 License-Expression: MIT
@@ -357,6 +357,20 @@ specsmith audit                          # full governance health check
 > Every utterance is preflighted automatically. Use `/why` to see the governance trace.
 > For the multi-agent DAG dispatcher, see `specsmith dispatch run "<task>"`.
 
+### Standalone CLI (no AI agent)
+
+All governance commands work without any AI agent or IDE integration:
+
+```bash
+specsmith audit                     # governance health check
+specsmith preflight "<intent>" --json  # gate a change
+specsmith verify                    # check equilibrium after changes
+specsmith save                      # ESDB backup + commit + push
+specsmith kill-session              # clean shutdown
+```
+
+For the full standalone session workflow, Nexus REPL usage, multi-agent dispatcher, and CI integration: **[Standalone CLI docs →](https://specsmith.readthedocs.io/en/stable/standalone-cli/)**
+
 ---
 
 ## Machine State Sync + YAML Governance
@@ -1155,6 +1169,121 @@ oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save
 
 ---
 
+## Agent Integrations
+
+Run `specsmith integrate <tool>` once in your project root — specsmith writes the governance file your AI client reads automatically.
+
+| Tool | Command | Generated file | MCP support |
+|---|---|---|---|
+| **Warp** | `specsmith integrate warp` | `.warp/specsmith-mcp.json` + `.warp/launch_configs/` | ✓ Native |
+| **Claude Code** | `specsmith integrate claude-code` | `CLAUDE.md` | ✓ via `.mcp.json` |
+| **Cursor** | `specsmith integrate cursor` | `.cursor/rules/governance.mdc` | ✓ via `.cursor/mcp.json` |
+| **Windsurf** | `specsmith integrate windsurf` | `.windsurfrules` | ✓ via Settings → MCP |
+| **Gemini CLI** | `specsmith integrate gemini` | `GEMINI.md` | — |
+| **Aider** | `specsmith integrate aider` | `.aider.conf.yml` | — |
+| **Copilot** | `specsmith integrate copilot` | `.github/copilot-instructions.md` | — |
+
+All generated files embed the same core content: governance rules, the mandatory session protocol, preflight requirements, and AGENTS.md as the primary governance source.
+
+### Mandatory session protocol (all tools)
+
+```bash
+# Session start
+specsmith kill-session 2>/dev/null || true
+specsmith audit --project-dir .
+specsmith sync  --project-dir .
+specsmith checkpoint --project-dir .   # output GOVERNANCE ANCHOR verbatim
+
+# Before every code change
+specsmith preflight "<describe the change>" --json
+# decision == "accepted"           → proceed with work_item_id in scope
+# decision == "needs_clarification" → surface instruction to user first
+
+# Every 8–10 turns
+specsmith checkpoint --project-dir .
+
+# Session end
+specsmith save && specsmith kill-session
+```
+
+### Claude Code
+
+```bash
+specsmith integrate claude-code   # writes CLAUDE.md
+```
+
+To enable native MCP tool calls, add to `.mcp.json` (project root) or `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "specsmith-governance": {
+      "command": "specsmith",
+      "args": ["mcp", "serve", "--project-dir", "."]
+    }
+  }
+}
+```
+
+Or run `specsmith mcp install-claude-code` to print the snippet. With MCP configured, Claude calls governance tools natively — no shell roundtrip.
+
+### Cursor
+
+```bash
+specsmith integrate cursor   # writes .cursor/rules/governance.mdc
+```
+
+Add to `.cursor/mcp.json` to enable MCP:
+
+```json
+{
+  "specsmith-governance": {
+    "command": "specsmith",
+    "args": ["mcp", "serve", "--project-dir", "${workspaceFolder}"]
+  }
+}
+```
+
+### Windsurf
+
+```bash
+specsmith integrate windsurf   # writes .windsurfrules
+```
+
+MCP: **Settings → MCP Servers** → `{ "specsmith-governance": { "command": "specsmith", "args": ["mcp", "serve"] } }`
+
+### Gemini CLI
+
+```bash
+specsmith integrate gemini   # writes GEMINI.md (read automatically by the gemini CLI)
+```
+
+### Aider
+
+```bash
+specsmith integrate aider   # writes .aider.conf.yml
+```
+
+For full governance, use `--no-auto-commits` and commit via `specsmith save`:
+
+```bash
+aider --no-auto-commits --read AGENTS.md --read .agents/skills/specsmith-session-governance/SKILL.md
+```
+
+Run `specsmith preflight` in a separate terminal before each change; run `specsmith save` after aider finishes.
+
+### GitHub Copilot
+
+```bash
+specsmith integrate copilot   # writes .github/copilot-instructions.md
+```
+
+Copilot reads `.github/copilot-instructions.md` for all workspace interactions. MCP not yet natively supported; governance is enforced through the instructions file and `AGENTS.md`.
+
+Full per-tool setup: **[Agent Integrations docs →](https://specsmith.readthedocs.io/en/stable/agent-integrations/)**
+
+---
+
 ## Warp Terminal Integration
 
 specsmith ships first-class integration with [Warp](https://www.warp.dev) terminal: a
@@ -1212,6 +1341,20 @@ oz agent run --mcp '{"specsmith-governance": {"command": "specsmith", "args": ["
 | `governance_req_list` | All requirements with status + test coverage, filterable |
 | `governance_trace_seal` | Create a cryptographic trace vault seal |
 
+### Third-party CLI agent toolbar
+
+For **specsmith** and **aider** (not yet natively supported by Warp), add this regex once in **Warp → Settings → Agents → Third party CLI agents → Commands that enable the toolbar**:
+
+```
+specsmith\s+run|aider
+```
+
+`claude`, `codex`, `gemini`, and `cursor` are already natively supported — no regex needed.
+
+Once set, the toolbelt (Rich Input, attach code, File Explorer, Tab Configs, Remote Control) appears whenever `specsmith run` or `aider` is running. `specsmith run` also emits an OSC 9 desktop notification on session start — intercepted automatically by Warp, iTerm2, and Windows Terminal.
+
+Run `specsmith integrate warp` to regenerate `.warp/SETUP.md` with the full per-REPL setup guide.
+
 ### Repository Workflows (Ctrl+Shift+R)
 
 Clone this repo and open it in Warp — seven governance workflows appear automatically in

{specsmith-0.20.1.dev748 → specsmith-0.20.1.dev751}/README.md

@@ -279,6 +279,20 @@ specsmith audit                          # full governance health check
 > Every utterance is preflighted automatically. Use `/why` to see the governance trace.
 > For the multi-agent DAG dispatcher, see `specsmith dispatch run "<task>"`.
 
+### Standalone CLI (no AI agent)
+
+All governance commands work without any AI agent or IDE integration:
+
+```bash
+specsmith audit                     # governance health check
+specsmith preflight "<intent>" --json  # gate a change
+specsmith verify                    # check equilibrium after changes
+specsmith save                      # ESDB backup + commit + push
+specsmith kill-session              # clean shutdown
+```
+
+For the full standalone session workflow, Nexus REPL usage, multi-agent dispatcher, and CI integration: **[Standalone CLI docs →](https://specsmith.readthedocs.io/en/stable/standalone-cli/)**
+
 ---
 
 ## Machine State Sync + YAML Governance
@@ -1077,6 +1091,121 @@ oz agent run-cloud --skill "layer1labs/specsmith:specsmith-save" --prompt "save
 
 ---
 
+## Agent Integrations
+
+Run `specsmith integrate <tool>` once in your project root — specsmith writes the governance file your AI client reads automatically.
+
+| Tool | Command | Generated file | MCP support |
+|---|---|---|---|
+| **Warp** | `specsmith integrate warp` | `.warp/specsmith-mcp.json` + `.warp/launch_configs/` | ✓ Native |
+| **Claude Code** | `specsmith integrate claude-code` | `CLAUDE.md` | ✓ via `.mcp.json` |
+| **Cursor** | `specsmith integrate cursor` | `.cursor/rules/governance.mdc` | ✓ via `.cursor/mcp.json` |
+| **Windsurf** | `specsmith integrate windsurf` | `.windsurfrules` | ✓ via Settings → MCP |
+| **Gemini CLI** | `specsmith integrate gemini` | `GEMINI.md` | — |
+| **Aider** | `specsmith integrate aider` | `.aider.conf.yml` | — |
+| **Copilot** | `specsmith integrate copilot` | `.github/copilot-instructions.md` | — |
+
+All generated files embed the same core content: governance rules, the mandatory session protocol, preflight requirements, and AGENTS.md as the primary governance source.
+
+### Mandatory session protocol (all tools)
+
+```bash
+# Session start
+specsmith kill-session 2>/dev/null || true
+specsmith audit --project-dir .
+specsmith sync  --project-dir .
+specsmith checkpoint --project-dir .   # output GOVERNANCE ANCHOR verbatim
+
+# Before every code change
+specsmith preflight "<describe the change>" --json
+# decision == "accepted"           → proceed with work_item_id in scope
+# decision == "needs_clarification" → surface instruction to user first
+
+# Every 8–10 turns
+specsmith checkpoint --project-dir .
+
+# Session end
+specsmith save && specsmith kill-session
+```
+
+### Claude Code
+
+```bash
+specsmith integrate claude-code   # writes CLAUDE.md
+```
+
+To enable native MCP tool calls, add to `.mcp.json` (project root) or `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "specsmith-governance": {
+      "command": "specsmith",
+      "args": ["mcp", "serve", "--project-dir", "."]
+    }
+  }
+}
+```
+
+Or run `specsmith mcp install-claude-code` to print the snippet. With MCP configured, Claude calls governance tools natively — no shell roundtrip.
+
+### Cursor
+
+```bash
+specsmith integrate cursor   # writes .cursor/rules/governance.mdc
+```
+
+Add to `.cursor/mcp.json` to enable MCP:
+
+```json
+{
+  "specsmith-governance": {
+    "command": "specsmith",
+    "args": ["mcp", "serve", "--project-dir", "${workspaceFolder}"]
+  }
+}
+```
+
+### Windsurf
+
+```bash
+specsmith integrate windsurf   # writes .windsurfrules
+```
+
+MCP: **Settings → MCP Servers** → `{ "specsmith-governance": { "command": "specsmith", "args": ["mcp", "serve"] } }`
+
+### Gemini CLI
+
+```bash
+specsmith integrate gemini   # writes GEMINI.md (read automatically by the gemini CLI)
+```
+
+### Aider
+
+```bash
+specsmith integrate aider   # writes .aider.conf.yml
+```
+
+For full governance, use `--no-auto-commits` and commit via `specsmith save`:
+
+```bash
+aider --no-auto-commits --read AGENTS.md --read .agents/skills/specsmith-session-governance/SKILL.md
+```
+
+Run `specsmith preflight` in a separate terminal before each change; run `specsmith save` after aider finishes.
+
+### GitHub Copilot
+
+```bash
+specsmith integrate copilot   # writes .github/copilot-instructions.md
+```
+
+Copilot reads `.github/copilot-instructions.md` for all workspace interactions. MCP not yet natively supported; governance is enforced through the instructions file and `AGENTS.md`.
+
+Full per-tool setup: **[Agent Integrations docs →](https://specsmith.readthedocs.io/en/stable/agent-integrations/)**
+
+---
+
 ## Warp Terminal Integration
 
 specsmith ships first-class integration with [Warp](https://www.warp.dev) terminal: a
@@ -1134,6 +1263,20 @@ oz agent run --mcp '{"specsmith-governance": {"command": "specsmith", "args": ["
 | `governance_req_list` | All requirements with status + test coverage, filterable |
 | `governance_trace_seal` | Create a cryptographic trace vault seal |
 
+### Third-party CLI agent toolbar
+
+For **specsmith** and **aider** (not yet natively supported by Warp), add this regex once in **Warp → Settings → Agents → Third party CLI agents → Commands that enable the toolbar**:
+
+```
+specsmith\s+run|aider
+```
+
+`claude`, `codex`, `gemini`, and `cursor` are already natively supported — no regex needed.
+
+Once set, the toolbelt (Rich Input, attach code, File Explorer, Tab Configs, Remote Control) appears whenever `specsmith run` or `aider` is running. `specsmith run` also emits an OSC 9 desktop notification on session start — intercepted automatically by Warp, iTerm2, and Windows Terminal.
+
+Run `specsmith integrate warp` to regenerate `.warp/SETUP.md` with the full per-REPL setup guide.
+
 ### Repository Workflows (Ctrl+Shift+R)
 
 Clone this repo and open it in Warp — seven governance workflows appear automatically in

{specsmith-0.20.1.dev748 → specsmith-0.20.1.dev751}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.20.1.dev748"
+version = "0.20.1.dev751"
 description = "AEE governance toolkit for AI-assisted development — session preflight gates, multi-agent dispatch, requirements↔test traceability, ESDB persistence, MCP server, and skills for Warp, Cursor, Claude Code, Copilot, Windsurf, and Aider."
 readme = "README.md"
 license = "MIT"

{specsmith-0.20.1.dev748 → specsmith-0.20.1.dev751}/src/specsmith/agent/runner.py

@@ -306,6 +306,13 @@ class AgentRunner:
 
         # Host-terminal detection (REQ-444): when running inside Warp the
         # banner/ready frame advertises native integration. Read-only.
+        # Set SPECSMITH_RUN_ACTIVE so any child specsmith command (audit,
+        # preflight, checkpoint, etc.) can detect they are running inside
+        # the Nexus REPL and report context-aware governance notifications.
+        import os as _os_init
+
+        _os_init.environ.setdefault("SPECSMITH_RUN_ACTIVE", "1")
+
         from specsmith.agent.terminal_env import detect_terminal
 
         self.terminal = detect_terminal()
@@ -395,6 +402,11 @@ class AgentRunner:
             if self.terminal.is_warp:
                 ver = f" {self.terminal.version}" if self.terminal.version else ""
                 lines.insert(3, f"  terminal: Warp{ver} \u2014 native integration active")
+                # Emit OSC 9 desktop notification so Warp surfaces a popup.
+                from specsmith.agent.terminal_env import emit_warp_notification
+
+                proj = Path(self.project_dir).name
+                emit_warp_notification(f"specsmith run | {proj} | governance active")
             for s in statuses:
                 if s.available:
                     lines.append(

specsmith-0.20.1.dev751/src/specsmith/agent/terminal_env.py

@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. All rights reserved.
+"""Terminal-environment detection for specsmith (REQ-444).
+
+Lets the interactive REPL (``specsmith run``) and standalone CLI commands
+detect when they are running inside Warp and which CLI agent REPL is active.
+Detection is based on:
+  * ``TERM_PROGRAM=WarpTerminal`` / any ``WARP_*`` env var — Warp host
+  * ``SPECSMITH_RUN_ACTIVE=1``     — set by ``specsmith run`` on REPL start
+  * ``AIDER_MODEL`` / ``AIDER_CONFIG``  — set by aider at session start
+  * ``CLAUDE_CODE_ENTRYPOINT``     — set by Claude Code CLI
+  * ``CODEX_CLI_SESSION``          — set by OpenAI Codex CLI
+  * ``GEMINI_CLI``                 — set by Gemini CLI
+  * ``CURSOR_TRACE_ID``            — set by Cursor CLI
+
+All detection is read-only and purely best-effort.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import asdict, dataclass
+from typing import TextIO
+
+# ---------------------------------------------------------------------------
+# Known CLI-agent env-var signals.
+# Keys are canonical agent IDs; values are lists of env vars that
+# confirm the agent is (or recently was) active in this shell session.
+# Warp natively supports: claude, codex, gemini, cursor.
+# specsmith and aider are NOT natively supported — users add them via the
+# custom toolbar regex in Warp Settings → Agents → Third party CLI agents.
+# ---------------------------------------------------------------------------
+_AGENT_ENV_SIGNALS: dict[str, list[str]] = {
+    "specsmith": ["SPECSMITH_RUN_ACTIVE"],
+    "aider": ["AIDER_MODEL", "AIDER_CONFIG", "AIDER_CHAT_LANGUAGE"],
+    "claude": ["CLAUDE_CODE_ENTRYPOINT", "ANTHROPIC_CLAUDE_CODE_SESSION"],
+    "codex": ["CODEX_CLI_SESSION", "OPENAI_CODEX_CLI"],
+    "gemini": ["GEMINI_CLI", "GEMINI_CLI_SESSION"],
+    "cursor": ["CURSOR_TRACE_ID", "CURSOR_SESSION_ID"],
+    "copilot": ["GITHUB_COPILOT_CLI", "GH_COPILOT_SESSION"],
+    "windsurf": ["WINDSURF_SESSION", "CODEIUM_SESSION"],
+}
+
+
+@dataclass(frozen=True)
+class TerminalInfo:
+    """Information about the host terminal and active CLI agent REPL."""
+
+    is_warp: bool
+    program: str
+    version: str
+    #: Canonical agent ID when a known CLI agent REPL is detected, else "".
+    #: Examples: ``"specsmith"``, ``"aider"``, ``"claude"``, ``"codex"``.
+    active_agent: str = ""
+
+    def as_dict(self) -> dict[str, object]:
+        """Return a flat dict suitable for the ``ready`` event frame."""
+        return asdict(self)
+
+
+def detect_terminal(env: dict[str, str] | None = None) -> TerminalInfo:
+    """Detect the host terminal and active CLI agent from environment variables.
+
+    Warp sets ``TERM_PROGRAM=WarpTerminal`` (and ``TERM_PROGRAM_VERSION``).
+    As a fallback we also treat the presence of any ``WARP_*`` variable as a
+    Warp signal.  Pass *env* to override ``os.environ`` (used by tests).
+    """
+    source = os.environ if env is None else env
+    program = (source.get("TERM_PROGRAM") or "").strip()
+    version = (source.get("TERM_PROGRAM_VERSION") or "").strip()
+    is_warp = program == "WarpTerminal" or any(k.startswith("WARP_") for k in source)
+    if is_warp and not program:
+        program = "WarpTerminal"
+
+    # Detect the active CLI-agent REPL by checking known signal env vars.
+    # First match wins; order matters (specsmith checked before generic agents).
+    active_agent = ""
+    for agent, signals in _AGENT_ENV_SIGNALS.items():
+        if any(source.get(sig) for sig in signals):
+            active_agent = agent
+            break
+
+    return TerminalInfo(
+        is_warp=is_warp,
+        program=program,
+        version=version,
+        active_agent=active_agent,
+    )
+
+
+# ---------------------------------------------------------------------------
+# OSC 9 terminal notification (Warp, iTerm2, Windows Terminal)
+# ---------------------------------------------------------------------------
+
+
+def emit_warp_notification(message: str, *, stream: TextIO | None = None) -> None:
+    """Emit an OSC 9 terminal notification that Warp (and compatible terminals)
+    surfaces as a desktop notification.
+
+    The escape sequence ``ESC ] 9 ; <message> BEL`` is the standard notification
+    protocol supported by Warp, iTerm2, and Windows Terminal.  When *stream* is
+    ``None`` (the default), the function skips silently if stdout is not a TTY
+    (e.g. captured in tests or CI).  Pass an explicit *stream* to override.
+
+    This is always safe to call — it is a no-op outside Warp and raises no
+    exceptions.
+    """
+    out = stream if stream is not None else sys.stdout
+    try:
+        # When using the default stdout and it's not a tty, skip silently
+        # to avoid polluting captured output in tests or piped commands.
+        if stream is None and hasattr(out, "isatty") and not out.isatty():
+            return
+        out.write(f"\033]9;{message}\007")
+        if hasattr(out, "flush"):
+            out.flush()
+    except Exception:  # noqa: BLE001  # intentional: notification is best-effort
+        pass

specsmith-0.20.1.dev751/src/specsmith/integrations/warp.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. All rights reserved.
+"""Warp integration adapter (REQ-444).
+
+Generates Warp-native artifacts so Warp's agent is governed by specsmith:
+
+  * ``.warp/specsmith-mcp.json``                      — governance MCP server config
+  * ``.warp/launch_configs/specsmith-governed.yaml``  — launch config for a governed session
+  * ``.agents/skills/SKILL.md``                       — governance skill (shared with agent-skill)
+
+``AGENTS.md`` is already the governance hub Warp reads as project Rules, so the
+adapter does not duplicate it.
+
+This adapter supersedes the pre-0.5.0 ``warp`` name that previously aliased to
+the generic ``agent-skill`` adapter; the skill is still emitted here (by reusing
+``AgentSkillAdapter``), so existing setups keep their ``.agents/skills/SKILL.md``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from specsmith.config import ProjectConfig
+from specsmith.integrations.agent_skill import AgentSkillAdapter
+from specsmith.integrations.base import AgentAdapter
+
+
+class WarpAdapter(AgentAdapter):
+    """Generate Warp-native governance integration files."""
+
+    @property
+    def name(self) -> str:
+        return "warp"
+
+    @property
+    def description(self) -> str:
+        return "Warp native integration (MCP server config, launch config, governance skill)"
+
+    def generate(self, config: ProjectConfig, target: Path) -> list[Path]:
+        created: list[Path] = []
+        warp_dir = target / ".warp"
+        warp_dir.mkdir(parents=True, exist_ok=True)
+
+        # 1. MCP governance server config (shared builder with `mcp install-warp`).
+        from specsmith.mcp_server import build_warp_mcp_config
+
+        mcp_path = warp_dir / "specsmith-mcp.json"
+        mcp_path.write_text(
+            json.dumps(build_warp_mcp_config(), indent=2) + "\n",
+            encoding="utf-8",
+        )
+        created.append(mcp_path)
+
+        # 2. Launch config for a governed `specsmith run` session.
+        launch_dir = warp_dir / "launch_configs"
+        launch_dir.mkdir(parents=True, exist_ok=True)
+        launch_path = launch_dir / "specsmith-governed.yaml"
+        launch_path.write_text(self._render_launch_config(config, target), encoding="utf-8")
+        created.append(launch_path)
+
+        # 3. Governance skill (reuse the agent-skill adapter; .agents/skills/SKILL.md).
+        created.extend(AgentSkillAdapter().generate(config, target))
+
+        # 4. Third-party CLI agent toolbar setup guide.
+        setup_path = warp_dir / "SETUP.md"
+        setup_path.write_text(self._render_setup_guide(config), encoding="utf-8")
+        created.append(setup_path)
+
+        # Print the single most-important instruction so it appears immediately
+        # after `specsmith integrate warp` completes.
+        import sys
+
+        print(
+            "\n  ↳ Warp toolbar (one-time, per machine):\n"
+            "    Settings → Agents → Third party CLI agents\n"
+            "    Commands that enable the toolbar → add regex:\n"
+            "      specsmith\\s+run|aider\n"
+            "    (claude, codex, gemini, cursor — already natively supported)\n"
+            "\n"
+            "    Full setup guide: .warp/SETUP.md",
+            file=sys.stdout,
+            flush=True,
+        )
+
+        return created
+
+    def _render_setup_guide(self, config: ProjectConfig) -> str:  # noqa: ARG002
+        """Render the .warp/SETUP.md toolbar + notification setup guide."""
+        return """\
+# Warp — specsmith governance integration
+
+## Third-party CLI agent toolbar (one-time setup per machine)
+
+Warp natively supports the toolbar for: **claude**, **codex**, **gemini**, **cursor**.
+For **specsmith** and **aider** (not yet natively supported), add the following
+regex to Warp → Settings → Agents → Third party CLI agents → Commands that enable the toolbar:
+
+```
+specsmith\\s+run|aider
+```
+
+Once saved, the Warp toolbelt appears automatically when either `specsmith run` or
+`aider` is active in any pane, providing Rich Input (Ctrl+G), attach code as context,
+File Explorer, Tab Configs, and Remote Control.
+
+## Desktop notifications
+
+`specsmith run` emits OSC 9 desktop notifications when running inside Warp
+(or any OSC-9-compatible terminal such as iTerm2 or Windows Terminal).
+No extra setup is needed — Warp intercepts the escape sequence automatically.
+
+Notification events:
+- Session start: `specsmith run | <project> | governance active`
+
+## MCP governance server
+
+Add `.warp/specsmith-mcp.json` to Warp → Settings → Agents → MCP servers so
+Warp's Oz agent can call governance tools natively (preflight, audit, checkpoint,
+req_list, phase, trace_seal) without shell roundtrips.
+
+Paste the contents of `.warp/specsmith-mcp.json` or run:
+```bash
+specsmith mcp install-warp
+```
+
+## Launch configuration
+
+`.warp/launch_configs/specsmith-governed.yaml` opens a governed `specsmith run`
+session. Copy it to your Warp launch configurations directory:
+- macOS/Linux: `~/.warp/launch_configurations/`
+- Windows: `%APPDATA%/warp/Warp/data/launch_configurations/`
+
+## Supported REPLs and their Warp status
+
+| REPL | Toolbar | How |
+|---|---|---|
+| `specsmith run` | Custom regex | Add `specsmith\\s+run` to toolbar regex |
+| `aider` | Custom regex | Add `aider` to toolbar regex |
+| `claude` | Native | Built into Warp — no setup needed |
+| `codex` | Native | Built into Warp — no setup needed |
+| `gemini` | Native | Built into Warp — no setup needed |
+| `cursor` | Native | Built into Warp — no setup needed |
+
+## Session protocol (all REPLs)
+
+```bash
+# Session start
+specsmith kill-session 2>/dev/null || true
+specsmith audit --project-dir .
+specsmith sync  --project-dir .
+specsmith checkpoint --project-dir .   # output GOVERNANCE ANCHOR verbatim
+
+# Before every code change
+specsmith preflight "<describe the change>" --json
+
+# Session end
+specsmith save && specsmith kill-session
+```
+"""
+
+    def _render_launch_config(self, config: ProjectConfig, target: Path) -> str:
+        cwd = str(target).replace("\\", "/")
+        return f"""\
+# specsmith governed session — Warp launch configuration.
+# Copy to your Warp launch configurations directory to use it:
+#   macOS/Linux: ~/.warp/launch_configurations/
+#   Windows:     %APPDATA%/warp/Warp/data/launch_configurations/
+# The governance MCP server config lives in .warp/specsmith-mcp.json — add it
+# under Warp Settings -> Agents -> MCP servers so Warp's agent is governed.
+name: {config.name} — specsmith governed
+windows:
+  - tabs:
+      - title: specsmith
+        layout:
+          cwd: "{cwd}"
+          commands:
+            - exec: specsmith run
+"""