spawn-cli 0.1.14__tar.gz → 0.1.16__tar.gz

{spawn_cli-0.1.14/src/spawn_cli.egg-info → spawn_cli-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.14
+Version: 0.1.16
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -217,9 +217,11 @@ That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`**
 
 ### 2. Hints in `spawn/navigation.yaml`
 
-For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+For **short, always-visible reminders** (tone, language, repo-specific habits), add **hint-only** rows under **`read-required` → `rules`** (a **`hint`** entry **without** a **`path`**). Mandatory rule files use rows with **`path`** and **`description`** only—do **not** add **`hint`** on the same row as **`path`**; if refresh finds legacy pairs, it splits them into a file row and a following hint-only row.
 
-Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+Hints from **`read-required` → `rules`** (hint-only rows) appear in skills’ **Hints** section and in the managed **`AGENTS.md`** rollup together with extension **`hints.global`**, using YAML row order within maintainer hints before dedupe (**`hint`** on **`read-contextual` → `rules`** is still **not** included there).
+
+If a **`path`** names a **`spawn/rules/…`** file that **does not** exist when navigation is refreshed, that row is **removed entirely** — fix or drop **`path`** first; **`hint`** on that same removed row is **not** downgraded to a hint-only row.
 
 Example:
 
@@ -228,7 +230,8 @@ read-required:
   - rules:
       - path: spawn/rules/team.md
         description: Team conventions.
-        hint: Prefer British spelling in user-facing copy.
+      - hint: Prefer British spelling in user-facing copy.
+      - hint: Short standalone reminder with no rule file.
 ```
 
 Then run **`spawn refresh`** so skills and entry points pick up the hint.

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/README.md

@@ -200,9 +200,11 @@ That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`**
 
 ### 2. Hints in `spawn/navigation.yaml`
 
-For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+For **short, always-visible reminders** (tone, language, repo-specific habits), add **hint-only** rows under **`read-required` → `rules`** (a **`hint`** entry **without** a **`path`**). Mandatory rule files use rows with **`path`** and **`description`** only—do **not** add **`hint`** on the same row as **`path`**; if refresh finds legacy pairs, it splits them into a file row and a following hint-only row.
 
-Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+Hints from **`read-required` → `rules`** (hint-only rows) appear in skills’ **Hints** section and in the managed **`AGENTS.md`** rollup together with extension **`hints.global`**, using YAML row order within maintainer hints before dedupe (**`hint`** on **`read-contextual` → `rules`** is still **not** included there).
+
+If a **`path`** names a **`spawn/rules/…`** file that **does not** exist when navigation is refreshed, that row is **removed entirely** — fix or drop **`path`** first; **`hint`** on that same removed row is **not** downgraded to a hint-only row.
 
 Example:
 
@@ -211,7 +213,8 @@ read-required:
   - rules:
       - path: spawn/rules/team.md
         description: Team conventions.
-        hint: Prefer British spelling in user-facing copy.
+      - hint: Prefer British spelling in user-facing copy.
+      - hint: Short standalone reminder with no rule file.
 ```
 
 Then run **`spawn refresh`** so skills and entry points pick up the hint.

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spawn-cli"
-version = "0.1.14"
+version = "0.1.16"
 description = "A minimal installable Python CLI package."
 readme = "README.md"
 requires-python = ">=3.10"

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/cli.py

@@ -8,6 +8,7 @@ from spawn_cli import __version__
 from spawn_cli.core import download as dl
 from spawn_cli.core import high_level as hl
 from spawn_cli.core import low_level as ll
+from spawn_cli.core import mcp_stdio
 from spawn_cli.core.errors import SpawnError
 from spawn_cli.ide.registry import DetectResult, detect_supported_ides
 from spawn_cli.io.lock import spawn_lock
@@ -298,6 +299,38 @@ def build_parser() -> argparse.ArgumentParser:
         help="Fallback Git revision applied when entries lack branch.",
     )
 
+    mcp_stdio_p = sub.add_parser(
+        "mcp_stdio",
+        help="Run stdio MCP for an extension server (IDE-stable wrapper)",
+        description=(
+            "Resolve the inner stdio command from installed extension MCP JSON for this OS "
+            "and relay MCP traffic on stdin/stdout. Intended as the IDE MCP entrypoint when "
+            "spawn_stdio_proxy is enabled; does not acquire the repository lock."
+        ),
+    )
+    mcp_stdio_l1 = mcp_stdio_p.add_subparsers(dest="mcp_stdio_l1", required=True)
+    mcp_stdio_ext = mcp_stdio_l1.add_parser(
+        "extension",
+        help="Pick installed extension id",
+        description="Extension directory name under spawn/.extend/ (same ids as spawn extension list).",
+    )
+    mcp_stdio_ext.add_argument(
+        "mcp_stdio_extension_id",
+        metavar="EXTENSION_ID",
+        help="Installed extension id (folder under spawn/.extend/).",
+    )
+    mcp_stdio_l2 = mcp_stdio_ext.add_subparsers(dest="mcp_stdio_l2", required=True)
+    mcp_stdio_name = mcp_stdio_l2.add_parser(
+        "name",
+        help="Pick MCP server by declared name",
+        description="Must match servers[].name in mcp/<platform>.json for the current OS.",
+    )
+    mcp_stdio_name.add_argument(
+        "mcp_stdio_server_name",
+        metavar="SERVER_NAME",
+        help="MCP server name from the extension platform MCP file.",
+    )
+
     return parser
 
 
@@ -327,6 +360,9 @@ def _dispatch(args: argparse.Namespace, target_root: Path) -> int:
 
     _require_init(target_root)
 
+    if cmd == "mcp_stdio":
+        return _dispatch_mcp_stdio(args, target_root)
+
     with spawn_lock(target_root):
         if cmd == "rules":
             return _dispatch_rules(args, target_root)
@@ -343,6 +379,12 @@ def _dispatch(args: argparse.Namespace, target_root: Path) -> int:
     return 1
 
 
+def _dispatch_mcp_stdio(args: argparse.Namespace, target_root: Path) -> int:
+    return mcp_stdio.run_mcp_stdio_proxy(
+        target_root, args.mcp_stdio_extension_id, args.mcp_stdio_server_name
+    )
+
+
 def _dispatch_rules(args: argparse.Namespace, target_root: Path) -> int:
     sub = args.rules_command
     if sub == "refresh":

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/core/high_level.py

@@ -520,6 +520,15 @@ def extension_check(path: Path, strict: bool = False) -> list[str]:
                     warnings_out.append(f"MCP file invalid ({p}): {e}")
                     name_sets = []
                     break
+                for srv in nm.servers:
+                    if srv.spawn_stdio_proxy and srv.transport.type != "stdio":
+                        msg = (
+                            f"MCP server {srv.name!r} in {p}: spawn_stdio_proxy requires "
+                            f"transport.type 'stdio' (got {srv.transport.type!r})"
+                        )
+                        if strict:
+                            raise SpawnError(msg)
+                        warnings_out.append(msg)
                 name_sets.append(frozenset(s.name for s in nm.servers))
             if name_sets and len(set(name_sets)) != 1:
                 msg = (

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/core/low_level.py

@@ -194,9 +194,12 @@ def _merge_hint_streams_ordered(streams: list[list[str]]) -> list[str]:
 
 
 def _navigation_read_required_rule_hints_ordered(target_root: Path) -> list[str]:
-    """Plain-text hints from maintainer-authored read-required ``rules`` rows only (YAML order).
+    """Plain-text hints from maintainer-authored ``read-required`` ``rules`` rows (YAML order).
 
+    Only **hint-only** rows (no non-empty stripped ``path``) contribute; ``hint`` on file-backed
+    rows is ignored here (and dropped on navigation refresh).
     Hint fields on ``read-contextual`` rules are ignored here.
+    Strips each hint; whitespace-only hints are omitted.
     """
     path = _spawn(target_root) / "navigation.yaml"
     raw = load_yaml(path)
@@ -215,9 +218,14 @@ def _navigation_read_required_rule_hints_ordered(target_root: Path) -> list[str]
         for entry in rules_raw:
             if not isinstance(entry, dict):
                 continue
+            path_val = entry.get("path")
+            if isinstance(path_val, str) and path_val.strip():
+                continue
             hint_val = entry.get("hint")
             if isinstance(hint_val, str):
-                out.append(hint_val)
+                stripped = hint_val.strip()
+                if stripped:
+                    out.append(stripped)
     return out
 
 
@@ -656,6 +664,16 @@ def _parse_mcp_env(env_raw: dict[str, Any]) -> dict[str, McpEnvVar]:
     return out
 
 
+def merged_os_environ_with_mcp_env(
+    base: dict[str, str], mcp_env: dict[str, McpEnvVar]
+) -> dict[str, str]:
+    out = dict(base)
+    for key, spec in mcp_env.items():
+        if spec.value is not None:
+            out[key] = spec.value
+    return out
+
+
 def _mcp_capabilities(raw: dict[str, Any]) -> McpCapabilities:
     c = raw.get("capabilities") or {}
     return McpCapabilities.model_validate(c) if isinstance(c, dict) else McpCapabilities()
@@ -679,6 +697,17 @@ def extension_mcp_platform_json_paths(extension_root: Path) -> tuple[Path, Path,
     return tuple(d / f"{s}.json" for s in MCP_PLATFORM_STEMS)
 
 
+def _mcp_spawn_stdio_proxy_from_server(server: dict, path: Path, server_name: str) -> bool:
+    if "spawn_stdio_proxy" not in server:
+        return False
+    v = server["spawn_stdio_proxy"]
+    if isinstance(v, bool):
+        return v
+    raise SpawnError(
+        f"spawn_stdio_proxy must be a boolean for server {server_name!r} in {path}"
+    )
+
+
 def _normalized_mcp_from_loaded(data: dict, path: Path, extension: str) -> NormalizedMcp:
     servers_out: list[McpServer] = []
     for s in data.get("servers") or []:
@@ -687,6 +716,8 @@ def _normalized_mcp_from_loaded(data: dict, path: Path, extension: str) -> Norma
         nm = s.get("name")
         if nm is None:
             raise SpawnError(f"missing MCP server name in {path}")
+        str_name = str(nm)
+        spawn_proxy = _mcp_spawn_stdio_proxy_from_server(s, path, str_name)
         tr_raw = s.get("transport") or {}
         transport = McpTransport(
             type=str(tr_raw.get("type", "stdio")),
@@ -699,9 +730,10 @@ def _normalized_mcp_from_loaded(data: dict, path: Path, extension: str) -> Norma
         env = _parse_mcp_env(env_in) if isinstance(env_in, dict) else {}
         servers_out.append(
             McpServer(
-                name=str(nm),
+                name=str_name,
                 extension=extension,
                 transport=transport,
+                spawn_stdio_proxy=spawn_proxy,
                 env=env,
                 capabilities=_mcp_capabilities(s),
             )
@@ -1178,7 +1210,64 @@ def save_rules_navigation(target_root: Path) -> None:
     def posix_norm(p: str) -> str:
         return Path(p).as_posix().replace('\\', '/')
 
-    def prune(lst: list[Any]) -> None:
+    def prune_read_required_rules(lst: list[Any]) -> None:
+        """Keep file-backed rows with existing paths (no ``hint`` on those rows); keep hint-only rows."""
+
+        out: list[Any] = []
+        for entry in lst:
+            if not isinstance(entry, dict):
+                continue
+            hint_raw = entry.get('hint')
+            hint_is_str = isinstance(hint_raw, str)
+            hint_stripped = hint_raw.strip() if hint_is_str else ''
+            path_in_entry = 'path' in entry
+            path_raw = entry.get('path')
+
+            if path_in_entry:
+                if isinstance(path_raw, str) and path_raw.strip():
+                    rk = posix_norm(path_raw.strip())
+                    exists = rk in paths_on_disk and (Path(target_root) / Path(rk)).is_file()
+                    if exists:
+                        row: dict[str, Any] = {
+                            'path': rk,
+                            'description': str(entry.get('description') or 'Local rule file.'),
+                        }
+                        out.append(row)
+                        if hint_stripped:
+                            warnings.warn(
+                                f'Moved maintainer hint from file-backed rule row to standalone '
+                                f'hint row: {rk}',
+                                SpawnWarning,
+                            )
+                            out.append({'hint': hint_stripped})
+                    else:
+                        warnings.warn(
+                            f"Removed missing rule path from navigation: {rk}",
+                            SpawnWarning,
+                        )
+                else:
+                    warnings.warn(
+                        'Removed invalid rule row from navigation (empty path field).',
+                        SpawnWarning,
+                    )
+                continue
+
+            if hint_stripped:
+                row_h: dict[str, Any] = {'hint': hint_stripped}
+                desc_raw = entry.get('description')
+                if isinstance(desc_raw, str) and desc_raw.strip():
+                    row_h['description'] = desc_raw.strip()
+                out.append(row_h)
+                continue
+
+            warnings.warn(
+                'Removed invalid rule row from navigation (no path and no hint).',
+                SpawnWarning,
+            )
+
+        lst[:] = out
+
+    def prune_contextual_rules(lst: list[Any]) -> None:
         out: list[Any] = []
         for entry in lst:
             if not isinstance(entry, dict) or 'path' not in entry:
@@ -1201,9 +1290,9 @@ def save_rules_navigation(target_root: Path) -> None:
                 )
         lst[:] = out
 
-    prune(rq_rules_list)
+    prune_read_required_rules(rq_rules_list)
     if cq_rules_list is not None:
-        prune(cq_rules_list)
+        prune_contextual_rules(cq_rules_list)
 
     raw["read-required"] = rr
     raw["read-contextual"] = rc

spawn_cli-0.1.16/src/spawn_cli/core/mcp_stdio.py

@@ -0,0 +1,67 @@
+"""Runtime stdio MCP proxy: resolve server from platform JSON and exec inner command."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from spawn_cli.core.errors import SpawnError
+from spawn_cli.core.low_level import list_extensions, list_mcp, merged_os_environ_with_mcp_env
+
+
+def run_mcp_stdio_proxy(target_root: Path, extension_id: str, server_name: str) -> int:
+    if extension_id not in list_extensions(target_root):
+        raise SpawnError(
+            f"unknown extension {extension_id!r}: install it under spawn/.extend/<id>/ "
+            f"(see: spawn extension list)."
+        )
+
+    nm = list_mcp(target_root, extension_id)
+    srv = next((s for s in nm.servers if s.name == server_name), None)
+    existing = [s.name for s in nm.servers]
+    if srv is None:
+        raise SpawnError(
+            f"unknown MCP server {server_name!r} for extension {extension_id!r}; "
+            f"declared servers: {existing}"
+        )
+
+    if not srv.spawn_stdio_proxy:
+        raise SpawnError(
+            f"MCP server {server_name!r} in extension {extension_id!r} is not enabled for "
+            f"stdio proxy: set \"spawn_stdio_proxy\": true on that server in "
+            f"extsrc/mcp/*.json (then reinstall or refresh)."
+        )
+
+    if srv.transport.type != "stdio":
+        raise SpawnError(
+            f"MCP server {server_name!r} uses transport type {srv.transport.type!r}; "
+            f"spawn mcp_stdio requires type \"stdio\"."
+        )
+
+    cmd = srv.transport.command
+    if not cmd:
+        raise SpawnError(
+            f"MCP server {server_name!r} has no transport.command; "
+            f"fix stdio transport in extension MCP JSON."
+        )
+
+    argv = [cmd, *srv.transport.args]
+    cwd_path = (target_root / srv.transport.cwd).resolve()
+    child_env = merged_os_environ_with_mcp_env(os.environ, srv.env)
+
+    try:
+        with subprocess.Popen(
+            argv,
+            cwd=str(cwd_path),
+            env=child_env,
+            stdin=sys.stdin.buffer,
+            stdout=sys.stdout.buffer,
+            stderr=None,
+            shell=False,
+            bufsize=0,
+        ) as proc:
+            return int(proc.wait())
+    except OSError as e:
+        raise SpawnError(f"failed to start MCP server {server_name!r}: {e}") from e

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/ide/__init__.py

@@ -14,6 +14,7 @@ from .codex import CodexAdapter
 from .cursor import CursorAdapter
 from .gemini_cli import GeminiCliAdapter
 from .github_copilot import GitHubCopilotAdapter
+from .mcp_stdio_argv import mcp_stdio_argv
 from .windsurf import WindsurfAdapter
 from .registry import (
     ALIASES,
@@ -55,6 +56,7 @@ __all__ = [
     "IGNORE_BLOCK_START",
     "IdeAdapter",
     "IdeCapabilities",
+    "mcp_stdio_argv",
     "SPAWN_BLOCK_END",
     "SPAWN_BLOCK_START",
     "StubAdapter",

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/ide/claude_code.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 from spawn_cli.core import low_level as ll
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.mcp_stdio_argv import mcp_stdio_argv
 from spawn_cli.ide.registry import (
     DetectResult,
     IdeAdapter,
@@ -24,7 +25,10 @@ from spawn_cli.models.skill import SkillMetadata
 def _build_generic_mcp_entry(server: McpServer) -> dict:
     transport = server.transport
     if transport.type == "stdio":
-        entry: dict = {"command": transport.command, "args": list(transport.args)}
+        if server.spawn_stdio_proxy:
+            entry = {"command": "spawn", "args": mcp_stdio_argv(server.extension, server.name)}
+        else:
+            entry = {"command": transport.command, "args": list(transport.args)}
     elif transport.type in ("streamable-http", "sse"):
         entry = {"type": transport.type, "url": transport.url}
         if transport.headers:

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/ide/codex.py

@@ -6,6 +6,7 @@ import warnings
 from pathlib import Path
 
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.mcp_stdio_argv import mcp_stdio_argv
 from spawn_cli.ide.registry import (
     DetectResult,
     IdeAdapter,
@@ -24,8 +25,12 @@ def _build_toml_server_entry(server: McpServer) -> dict:
     transport = server.transport
     entry: dict = {}
     if transport.type == "stdio":
-        entry["command"] = transport.command
-        entry["args"] = list(transport.args)
+        if server.spawn_stdio_proxy:
+            entry["command"] = "spawn"
+            entry["args"] = mcp_stdio_argv(server.extension, server.name)
+        else:
+            entry["command"] = transport.command
+            entry["args"] = list(transport.args)
     else:
         entry["url"] = transport.url
     if server.env:

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/ide/cursor.py

@@ -7,6 +7,7 @@ import warnings
 from pathlib import Path
 
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.mcp_stdio_argv import mcp_stdio_argv
 from spawn_cli.ide._helpers import (
     clear_split_agent_ignore_file,
     remove_ignore_block,
@@ -31,7 +32,10 @@ def _build_mcp_server_entry(server: McpServer) -> dict:
     """Convert McpServer to .cursor/mcp.json entry (mcpServers format)."""
     transport = server.transport
     if transport.type == "stdio":
-        entry: dict = {"command": transport.command, "args": transport.args}
+        if server.spawn_stdio_proxy:
+            entry = {"command": "spawn", "args": mcp_stdio_argv(server.extension, server.name)}
+        else:
+            entry = {"command": transport.command, "args": transport.args}
     elif transport.type in ("streamable-http", "sse"):
         entry = {"type": transport.type, "url": transport.url}
         if transport.headers:

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/ide/gemini_cli.py

@@ -7,6 +7,7 @@ import warnings
 from pathlib import Path
 
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.mcp_stdio_argv import mcp_stdio_argv
 from spawn_cli.ide._helpers import (
     clear_split_agent_ignore_file,
     remove_ignore_block,
@@ -31,8 +32,12 @@ def _build_gemini_mcp_entry(server: McpServer) -> dict:
     transport = server.transport
     entry: dict = {}
     if transport.type == "stdio":
-        entry["command"] = transport.command
-        entry["args"] = list(transport.args)
+        if server.spawn_stdio_proxy:
+            entry["command"] = "spawn"
+            entry["args"] = mcp_stdio_argv(server.extension, server.name)
+        else:
+            entry["command"] = transport.command
+            entry["args"] = list(transport.args)
     elif transport.type == "streamable-http":
         entry["httpUrl"] = transport.url or ""
         if transport.headers:

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/ide/github_copilot.py

@@ -7,6 +7,7 @@ import warnings
 from pathlib import Path
 
 from spawn_cli.ide import _vacancy as _vac
+from spawn_cli.ide.mcp_stdio_argv import mcp_stdio_argv
 from spawn_cli.ide.registry import (
     DetectResult,
     IdeAdapter,
@@ -31,8 +32,12 @@ def _build_vscode_mcp_entry(server: McpServer) -> tuple[dict, list[dict]]:
 
     if transport.type == "stdio":
         entry["type"] = "stdio"
-        entry["command"] = transport.command
-        entry["args"] = list(transport.args)
+        if server.spawn_stdio_proxy:
+            entry["command"] = "spawn"
+            entry["args"] = mcp_stdio_argv(server.extension, server.name)
+        else:
+            entry["command"] = transport.command
+            entry["args"] = list(transport.args)
     else:
         entry["type"] = transport.type
         entry["url"] = transport.url

spawn_cli-0.1.16/src/spawn_cli/ide/mcp_stdio_argv.py

@@ -0,0 +1,10 @@
+"""Shared argv list for IDE MCP configs that launch ``spawn mcp_stdio``."""
+
+from __future__ import annotations
+
+
+def mcp_stdio_argv(extension_id: str, server_name: str) -> list[str]:
+    return ["mcp_stdio", "extension", extension_id, "name", server_name]
+
+
+__all__ = ["mcp_stdio_argv"]

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/models/__init__.py

@@ -27,6 +27,7 @@ from spawn_cli.models.metadata import (
 from spawn_cli.models.navigation import (
     NavExtGroup,
     NavFile,
+    NavRuleRow,
     NavRulesGroup,
     NavigationFile,
 )
@@ -55,6 +56,7 @@ __all__ = [
     "RenderedSkillsMeta",
     "NavExtGroup",
     "NavFile",
+    "NavRuleRow",
     "NavRulesGroup",
     "NavigationFile",
     "SkillFileRef",

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli/models/mcp.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, StrictBool
 
 
 class McpEnvVar(BaseModel):
@@ -39,6 +39,7 @@ class McpServer(BaseModel):
     name: str
     extension: str
     transport: McpTransport
+    spawn_stdio_proxy: StrictBool = False
     env: dict[str, McpEnvVar] = Field(default_factory=dict)
     capabilities: McpCapabilities = Field(default_factory=McpCapabilities)
 

spawn_cli-0.1.16/src/spawn_cli/models/navigation.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class NavFile(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    path: str
+    description: str
+
+
+class NavExtGroup(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    ext: str
+    files: list[NavFile] = Field(default_factory=list)
+
+
+class NavRuleRow(BaseModel):
+    """Maintainer ``read-required`` ``rules`` row: file-backed (``path``) or hint-only (``hint``), never both."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    path: str | None = None
+    description: str | None = None
+    hint: str | None = None
+
+    @model_validator(mode='after')
+    def path_xor_hint(self) -> NavRuleRow:
+        path_ok = bool(self.path and str(self.path).strip())
+        hint_ok = bool(self.hint and str(self.hint).strip())
+        if not path_ok and not hint_ok:
+            raise ValueError('navigation rule row needs a non-empty path or a non-empty hint')
+        if path_ok and hint_ok:
+            raise ValueError(
+                'navigation rule row cannot combine path and hint; use a standalone hint-only row'
+            )
+        return self
+
+
+class NavRulesGroup(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    rules: list[NavRuleRow] = Field(default_factory=list)
+
+
+class NavigationFile(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    read_required: list[dict] = Field(default_factory=list, alias="read-required")
+    read_contextual: list[dict] = Field(default_factory=list, alias="read-contextual")

{spawn_cli-0.1.14 → spawn_cli-0.1.16/src/spawn_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.14
+Version: 0.1.16
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -217,9 +217,11 @@ That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`**
 
 ### 2. Hints in `spawn/navigation.yaml`
 
-For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+For **short, always-visible reminders** (tone, language, repo-specific habits), add **hint-only** rows under **`read-required` → `rules`** (a **`hint`** entry **without** a **`path`**). Mandatory rule files use rows with **`path`** and **`description`** only—do **not** add **`hint`** on the same row as **`path`**; if refresh finds legacy pairs, it splits them into a file row and a following hint-only row.
 
-Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+Hints from **`read-required` → `rules`** (hint-only rows) appear in skills’ **Hints** section and in the managed **`AGENTS.md`** rollup together with extension **`hints.global`**, using YAML row order within maintainer hints before dedupe (**`hint`** on **`read-contextual` → `rules`** is still **not** included there).
+
+If a **`path`** names a **`spawn/rules/…`** file that **does not** exist when navigation is refreshed, that row is **removed entirely** — fix or drop **`path`** first; **`hint`** on that same removed row is **not** downgraded to a hint-only row.
 
 Example:
 
@@ -228,7 +230,8 @@ read-required:
   - rules:
       - path: spawn/rules/team.md
         description: Team conventions.
-        hint: Prefer British spelling in user-facing copy.
+      - hint: Prefer British spelling in user-facing copy.
+      - hint: Short standalone reminder with no rule file.
 ```
 
 Then run **`spawn refresh`** so skills and entry points pick up the hint.

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/src/spawn_cli.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ src/spawn_cli/core/download.py
 src/spawn_cli/core/errors.py
 src/spawn_cli/core/high_level.py
 src/spawn_cli/core/low_level.py
+src/spawn_cli/core/mcp_stdio.py
 src/spawn_cli/core/scripts.py
 src/spawn_cli/ide/__init__.py
 src/spawn_cli/ide/_helpers.py
@@ -26,6 +27,7 @@ src/spawn_cli/ide/codex.py
 src/spawn_cli/ide/cursor.py
 src/spawn_cli/ide/gemini_cli.py
 src/spawn_cli/ide/github_copilot.py
+src/spawn_cli/ide/mcp_stdio_argv.py
 src/spawn_cli/ide/registry.py
 src/spawn_cli/ide/windsurf.py
 src/spawn_cli/io/__init__.py

{spawn_cli-0.1.14 → spawn_cli-0.1.16}/tests/test_cli.py

@@ -349,3 +349,67 @@ def test_spawn_error_exit_code(tmp_path, monkeypatch, capsys):
         assert main(["rules", "refresh"]) == 1
 
     assert "planned failure" in capsys.readouterr().err
+
+
+@contextlib.contextmanager
+def _lock_must_not_be_used(_target_root: Path):
+    raise AssertionError("spawn_lock must not be used for mcp_stdio")
+
+
+def test_spawn_mcp_stdio_parses_nested_argv_fragments(tmp_path, monkeypatch):
+    """Argv may arrive shell-fragmented; argparse still sees one token list."""
+    monkeypatch.chdir(tmp_path)
+    from spawn_cli.core import low_level as ll
+
+    ll.init(tmp_path)
+    root = tmp_path.resolve()
+    mock_run = MagicMock(return_value=0)
+    pieces = (["mcp_stdio", "extension"], ["myext"], ["name"], ["srv_name"])
+    argv = [tok for part in pieces for tok in part]
+
+    with patch("spawn_cli.cli.spawn_lock", _lock_must_not_be_used), patch(
+        "spawn_cli.cli.mcp_stdio.run_mcp_stdio_proxy", mock_run
+    ):
+        assert main(argv) == 0
+
+    mock_run.assert_called_once_with(root, "myext", "srv_name")
+
+
+def test_spawn_mcp_stdio_never_calls_spawn_lock_factory(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    from spawn_cli.core import low_level as ll
+
+    ll.init(tmp_path)
+    root = tmp_path.resolve()
+    lock_factory = MagicMock()
+    mock_run = MagicMock(return_value=0)
+    with patch("spawn_cli.cli.spawn_lock", lock_factory), patch(
+        "spawn_cli.cli.mcp_stdio.run_mcp_stdio_proxy", mock_run
+    ):
+        assert main(["mcp_stdio", "extension", "e1", "name", "n1"]) == 0
+
+    lock_factory.assert_not_called()
+    mock_run.assert_called_once_with(root, "e1", "n1")
+
+
+def test_spawn_mcp_stdio_parses_nested_argv(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "spawn").mkdir()
+    root = tmp_path.resolve()
+    mock_run = MagicMock(return_value=0)
+
+    with patch("spawn_cli.cli.spawn_lock", _lock_must_not_be_used), patch(
+        "spawn_cli.cli.mcp_stdio.run_mcp_stdio_proxy", mock_run
+    ):
+        assert main(["mcp_stdio", "extension", "myext", "name", "srv"]) == 0
+
+    mock_run.assert_called_once_with(root, "myext", "srv")
+
+
+def test_spawn_mcp_stdio_help(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["mcp_stdio", "--help"])
+    assert exc.value.code == 0
+    out = capsys.readouterr().out
+    assert "mcp_stdio" in out
+    assert "repository lock" in out.lower() or "lock" in out.lower()

spawn_cli-0.1.14/src/spawn_cli/models/navigation.py

@@ -1,30 +0,0 @@
-from __future__ import annotations
-
-from pydantic import BaseModel, ConfigDict, Field
-
-
-class NavFile(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    path: str
-    description: str
-
-
-class NavExtGroup(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    ext: str
-    files: list[NavFile] = Field(default_factory=list)
-
-
-class NavRulesGroup(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    rules: list[NavFile] = Field(default_factory=list)
-
-
-class NavigationFile(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    read_required: list[dict] = Field(default_factory=list, alias="read-required")
-    read_contextual: list[dict] = Field(default_factory=list, alias="read-contextual")