@heytherevibin/skillforge 0.10.0 → 0.11.7

package/python/app/main.py

@@ -32,7 +32,14 @@ from app.project_index import (
     retrieve_project_context_items,
 )
 from app.redaction import redaction_enabled, redact_secret_patterns, sanitize_context_items
+from app.router_llm import (
+    AnthropicRouterLLM,
+    OpenAIRouterLLM,
+    resolve_openai_router_defaults,
+    transport_is_mcp,
+)
 from app.feedback_meta import build_feedback_effect
+from app.pick_diversify import diversify_picked_names
 from app.route_policies import (
     build_routing_overlay_payload,
     load_route_policies_config,
@@ -43,16 +50,28 @@ from app.route_policies import (
 from app.route_quality import build_route_quality, coerce_route_float
 from app.routing_signals import (
     build_route_query_text,
+    host_pick_max_candidates,
     host_pick_shortlist_lines,
     keyword_overlap_scores,
     normalize_minmax,
     skill_routing_card,
     tokenize_skills_query,
 )
+from app.router_mode import normalise_skillforge_router_mode
+from app.skill_manifest import skill_manifest_strict_exclusion, validate_skill_manifest
 
 # ---------- Config (env-driven so the Node wrapper controls paths) ----------
-BUNDLED_SKILLS = Path(os.getenv("SKILLFORGE_BUNDLED_SKILLS", "./skills"))
-USER_SKILLS = Path(os.getenv("SKILLFORGE_USER_SKILLS", str(Path.home() / ".skillforge" / "skills")))
+
+
+def bundled_skills_dir() -> Path:
+    raw = os.getenv("SKILLFORGE_BUNDLED_SKILLS", "./skills").strip() or "./skills"
+    return Path(raw).expanduser().resolve()
+
+
+def user_skills_dir() -> Path:
+    fallback = str(Path.home() / ".skillforge" / "skills")
+    raw = os.getenv("SKILLFORGE_USER_SKILLS", fallback).strip() or fallback
+    return Path(raw).expanduser()
 
 
 DB_PATH = global_db_path()
@@ -63,8 +82,8 @@ ROUTER_MODEL = os.getenv("SKILLFORGE_ROUTER_MODEL", "claude-haiku-4-5-20251001")
 TOP_K_CANDIDATES = int(os.getenv("SKILLFORGE_TOP_K", "15"))
 MAX_ACTIVE_SKILLS = int(os.getenv("SKILLFORGE_MAX_ACTIVE", "7"))
 REROUTE_THRESHOLD = float(os.getenv("SKILLFORGE_REROUTE_THRESHOLD", "0.4"))
-# "" | "full" | "embedding" | "host" — embedding skips Haiku; host skips in-process pick (MCP must pass picked_names).
-SKILLFORGE_ROUTER_MODE = os.getenv("SKILLFORGE_ROUTER_MODE", "").strip().lower()
+# "" | "full" | "embedding" | "host" — "" means auto (Haiku when ANTHROPIC_API_KEY set). Unset env → default host.
+SKILLFORGE_ROUTER_MODE = normalise_skillforge_router_mode(os.getenv("SKILLFORGE_ROUTER_MODE", "host"))
 # chunks: RAG-style line-bounded chunks from picked skills. full_body: inject entire SKILL.md per pick (legacy).
 SKILLFORGE_CONTEXT_MODE = os.getenv("SKILLFORGE_CONTEXT_MODE", "chunks").strip().lower()
 ROUTE_MAX_CONTEXT_CHARS = int(os.getenv("SKILLFORGE_ROUTE_MAX_CHARS", "60000"))
@@ -104,48 +123,76 @@ def build_router_and_skills(
     log: bool = True,
     log_prefix: str = "[skillforge]",
 ) -> tuple[Router, dict[str, Skill]]:
-    """Load embedding model, skill catalog, and Router (shared by MCP and ``skillforge route`` CLI)."""
+    """Load embedding model, skill catalog, and Router (shared by MCP and ``skillforge route`` CLI).
+
+    When ``SKILLFORGE_TRANSPORT=mcp`` (stdio MCP), router LLM is Anthropic-only when a key backs the
+    mode — legacy semantics. Standalone subprocesses omit that env and may set
+    ``SKILLFORGE_ROUTER_LLM_BACKEND=openai_compatible``.
+    """
     if log:
         print(f"{log_prefix} Loading skills...", file=sys.stderr)
-    skills = load_all_skills()
+    skills = load_all_skills(manifest_log_prefix=log_prefix)
     embed_model = SentenceTransformer(os.getenv("SKILLFORGE_EMBED_MODEL", "all-MiniLM-L6-v2"))
     key = os.getenv("ANTHROPIC_API_KEY", "").strip()
     mode = SKILLFORGE_ROUTER_MODE
+    compat_backend_raw = os.getenv("SKILLFORGE_ROUTER_LLM_BACKEND", "").strip().lower()
+    mcp_t = transport_is_mcp()
+
+    anth_legacy = None
     if mode == "embedding":
-        anthropic = None
-        router_note = "embedding-only (SKILLFORGE_ROUTER_MODE=embedding)"
+        router_note_llm = "embedding-only (SKILLFORGE_ROUTER_MODE=embedding)"
     elif mode == "host":
-        anthropic = None
-        router_note = (
+        router_note_llm = (
             "host-pick (SKILLFORGE_ROUTER_MODE=host): no in-process router LLM; "
             "first route_skills call returns a shortlist — call again with picked_names"
         )
     elif mode == "full":
         if key:
-            anthropic = AsyncAnthropic()
-            router_note = "full Haiku router (SKILLFORGE_ROUTER_MODE=full)"
+            anth_legacy = AsyncAnthropic()
+            router_note_llm = "full Haiku router (SKILLFORGE_ROUTER_MODE=full)"
         else:
-            anthropic = None
-            router_note = (
+            router_note_llm = (
                 "embedding-only (SKILLFORGE_ROUTER_MODE=full but no ANTHROPIC_API_KEY — "
                 "Haiku routing skipped)"
             )
     elif key:
-        anthropic = AsyncAnthropic()
-        router_note = "full Haiku router (default; ANTHROPIC_API_KEY set)"
+        anth_legacy = AsyncAnthropic()
+        router_note_llm = "full Haiku router (default; ANTHROPIC_API_KEY set)"
     else:
-        anthropic = None
-        router_note = (
+        router_note_llm = (
             "embedding-only (no ANTHROPIC_API_KEY — keyless. "
             "Set ANTHROPIC_API_KEY for Haiku routing.)"
         )
+
+    router_llm: AnthropicRouterLLM | OpenAIRouterLLM | None = None
+    if mode == "embedding":
+        router_note = router_note_llm
+        router_llm = None
+    elif mcp_t:
+        router_note = router_note_llm
+        router_llm = AnthropicRouterLLM(anth_legacy) if anth_legacy else None
+    elif compat_backend_raw == "openai_compatible":
+        b, rk, om = resolve_openai_router_defaults()
+        try:
+            router_llm = OpenAIRouterLLM(api_key=rk, base_url=b, default_model=om)
+            router_note = f"standalone openai_compatible router ({b}, model={om})"
+        except Exception as e:
+            router_llm = AnthropicRouterLLM(anth_legacy) if anth_legacy else None
+            router_note = (
+                f"{router_note_llm} — openai_compatible init failed ({e}); "
+                f"fallback to anthropic/embed-only wiring"
+            )
+    else:
+        router_note = router_note_llm
+        router_llm = AnthropicRouterLLM(anth_legacy) if anth_legacy else None
+
     if log:
         print(f"{log_prefix} {router_note}", file=sys.stderr)
         print(
-            f"{log_prefix} Loaded {len(skills)} skills from bundled={BUNDLED_SKILLS} user={USER_SKILLS}",
+            f"{log_prefix} Loaded {len(skills)} skills from bundled={bundled_skills_dir()} user={user_skills_dir()}",
             file=sys.stderr,
         )
-    router = Router(skills, embed_model, anthropic)
+    router = Router(skills, embed_model, router_llm)
     skmap = {s.name: s for s in skills}
     return router, skmap
 
@@ -230,23 +277,35 @@ def parse_skill_md(path: Path, source: str) -> Skill | None:
     )
 
 
-def load_all_skills() -> list[Skill]:
+def load_all_skills(*, manifest_log_prefix: str = "[skillforge]") -> list[Skill]:
     """Load from bundled dir first, then user dir (user overrides bundled by name)."""
     by_name: dict[str, Skill] = {}
-    for src_dir, label in [(BUNDLED_SKILLS, "bundled"), (USER_SKILLS, "user")]:
+    strict_manifest = skill_manifest_strict_exclusion()
+    for src_dir, label in [(bundled_skills_dir(), "bundled"), (user_skills_dir(), "user")]:
         if not src_dir.exists():
             continue
         for skill_md in sorted(src_dir.glob("*/SKILL.md")):
             s = parse_skill_md(skill_md, label)
-            if s:
-                by_name[s.name] = s  # later sources override
+            if not s:
+                print(f"{manifest_log_prefix} SKIP unreadable SKILL.md: {skill_md}", file=sys.stderr)
+                continue
+            errs, warns = validate_skill_manifest(s, skill_md)
+            for w in warns:
+                print(f"{manifest_log_prefix} manifest [{label}/{s.name}] warning: {w}", file=sys.stderr)
+            if errs:
+                for e in errs:
+                    suf = "(excluded from catalog)" if strict_manifest else "(loaded anyway)"
+                    print(f"{manifest_log_prefix} manifest [{label}/{s.name}] error: {e} {suf}", file=sys.stderr)
+                if strict_manifest:
+                    continue
+            by_name[s.name] = s  # later sources override
     return list(by_name.values())
 
 
 def iter_skill_md_paths() -> list[Path]:
     """All discovered SKILL.md paths in load order (bundled, then user overrides)."""
     paths: list[Path] = []
-    for src_dir in (BUNDLED_SKILLS, USER_SKILLS):
+    for src_dir in (bundled_skills_dir(), user_skills_dir()):
         if not src_dir.exists():
             continue
         for skill_md in sorted(src_dir.glob("*/SKILL.md")):
@@ -369,14 +428,20 @@ def set_skill_disabled(con, name, disabled: bool, user_id=""):
 
 # ---------- Router ----------
 class Router:
-    def __init__(self, skills, embed_model, anthropic: Optional[AsyncAnthropic]):
+    def __init__(
+        self,
+        skills,
+        embed_model,
+        router_llm: AnthropicRouterLLM | OpenAIRouterLLM | None,
+    ):
         self.skills = skills
         self.embed_model = embed_model
-        self.anthropic = anthropic
-        self.context_mode = SKILLFORGE_CONTEXT_MODE if SKILLFORGE_CONTEXT_MODE in (
-            "chunks",
-            "full_body",
-        ) else "chunks"
+        self.router_llm = router_llm
+        self.context_mode = (
+            SKILLFORGE_CONTEXT_MODE
+            if SKILLFORGE_CONTEXT_MODE in ("chunks", "full_body")
+            else "chunks"
+        )
         self._by_name: dict[str, Skill] = {s.name: s for s in skills}
         self._hybrid_mode = ROUTER_HYBRID_MODE
         self._hybrid_alpha = ROUTER_HYBRID_ALPHA
@@ -436,6 +501,21 @@ class Router:
                 file=sys.stderr,
             )
 
+    def _pick_router_llm_model(self, *, rerank: bool) -> str:
+        if isinstance(self.router_llm, OpenAIRouterLLM):
+            return self.router_llm.default_model
+        rerank_override = os.getenv("SKILLFORGE_HAIKU_RERANK_MODEL", "").strip()
+        if rerank and rerank_override:
+            return rerank_override
+        return ROUTER_MODEL
+
+    @property
+    def anthropic(self) -> Optional[AsyncAnthropic]:
+        """AsyncAnthropic client when the active router backend is Anthropic (MCP reload path)."""
+        if isinstance(self.router_llm, AnthropicRouterLLM):
+            return self.router_llm.client
+        return None
+
     def _sparse_scores(self, route_query: str) -> np.ndarray:
         if not _hybrid_mode_active(self._hybrid_mode):
             return np.zeros(len(self.skills), dtype=np.float64)
@@ -736,7 +816,7 @@ class Router:
     ) -> list[tuple[Skill, float]]:
         if (
             not candidates
-            or self.anthropic is None
+            or self.router_llm is None
             or not _env_truthy("SKILLFORGE_HAIKU_RERANK", "0")
         ):
             return candidates
@@ -772,14 +852,14 @@ class Router:
             f"Routing focus:\n{route_query}{hist}\n\nCandidates:\n" + "\n".join(lines)
         )
         try:
-            rerank_model = os.getenv("SKILLFORGE_HAIKU_RERANK_MODEL", "").strip() or ROUTER_MODEL
-            resp = await self.anthropic.messages.create(
-                model=rerank_model,
-                max_tokens=500,
+            rerank_model = self._pick_router_llm_model(rerank=True)
+            assert self.router_llm is not None
+            text = await self.router_llm.complete(
                 system=sys,
-                messages=[{"role": "user", "content": user}],
+                user=user,
+                max_tokens=500,
+                model=rerank_model,
             )
-            text = resp.content[0].text.strip()
             if text.startswith("```"):
                 text = text.split("```")[1]
                 if text.startswith("json"):
@@ -816,7 +896,7 @@ class Router:
         route_query: str | None = None,
     ):
         rq = (route_query if route_query is not None else prompt) or ""
-        if self.anthropic is None:
+        if self.router_llm is None:
             return self.pick_final_embedding_only(candidates)
         if not candidates:
             return [], "no candidates available"
@@ -849,13 +929,14 @@ class Router:
             f"\n\nCandidate skills:\n{catalog}"
         )
         try:
-            resp = await self.anthropic.messages.create(
-                model=ROUTER_MODEL,
-                max_tokens=400,
+            pick_model = self._pick_router_llm_model(rerank=False)
+            assert self.router_llm is not None
+            text = await self.router_llm.complete(
                 system=sys,
-                messages=[{"role": "user", "content": user}],
+                user=user,
+                max_tokens=400,
+                model=pick_model,
             )
-            text = resp.content[0].text.strip()
             if text.startswith("```"):
                 text = text.split("```")[1]
                 if text.startswith("json"):
@@ -962,7 +1043,7 @@ async def run_route_turn(
     host_router = SKILLFORGE_ROUTER_MODE == "host"
 
     if host_router and not picked_names_from_host_supplied:
-        k = max(3, min(TOP_K_CANDIDATES, int(os.getenv("SKILLFORGE_HOST_PICK_MAX", "12"))))
+        k = host_pick_max_candidates(top_k_cap=TOP_K_CANDIDATES)
         facets = router.shortlist_with_facets(
             route_query,
             con,
@@ -1066,7 +1147,7 @@ async def run_route_turn(
     else:
         names_before = [s.name for s, _ in candidates]
         rerank_eligible = bool(
-            candidates and router.anthropic is not None and _env_truthy("SKILLFORGE_HAIKU_RERANK", "0")
+            candidates and router.router_llm is not None and _env_truthy("SKILLFORGE_HAIKU_RERANK", "0")
         )
         candidates = await router.rerank_candidates_haiku(route_query, conversation, candidates)
         names_after = [s.name for s, _ in candidates]
@@ -1074,6 +1155,7 @@ async def run_route_turn(
         picked_names, reasoning = await router.pick_final(
             prompt, conversation, candidates, route_query=route_query
         )
+    picked_names, pick_diversify_meta = diversify_picked_names(picked_names, router._by_name)
     picked_names, policy_audit = merge_policy_includes(
         prompt,
         picked_names,
@@ -1190,10 +1272,10 @@ async def run_route_turn(
 
     if picked_names_from_host_supplied:
         pick_path = "host_picked"
-    elif router.anthropic is None or SKILLFORGE_ROUTER_MODE == "embedding":
+    elif router.router_llm is None or SKILLFORGE_ROUTER_MODE == "embedding":
         pick_path = "embedding_top"
     else:
-        pick_path = "haiku_pick"
+        pick_path = "llm_pick"
 
     rules_list = policies_cfg.get("rules") if isinstance(policies_cfg.get("rules"), list) else []
     route_quality = build_route_quality(
@@ -1209,6 +1291,7 @@ async def run_route_turn(
         host_shortlist_only=False,
         haiku_rerank_applied=haiku_rerank_applied,
         pick_path=pick_path,
+        pick_diversify=pick_diversify_meta,
     )
 
     reasoning_out = reasoning

package/python/app/materialize.py

@@ -1,14 +1,85 @@
 """Write project-local Skillforge bootstrap files (.cursor, .claude/commands, PRD, CLAUDE.md)."""
 from __future__ import annotations
 
+import os
 import re
 from pathlib import Path
-from typing import Any
+from typing import Any, Mapping
 
 MARKER_START = "<!-- skillforge:auto:start -->"
 MARKER_END = "<!-- skillforge:auto:end -->"
 
 
+def normalize_materialize_hosts(raw: str | None) -> str:
+    """Normalize MCP ``hosts`` argument: ``both`` | ``cursor`` | ``claude_code``."""
+    s = (raw or "both").strip().lower().replace("-", "_")
+    if s in ("both", "all", "*", ""):
+        return "both"
+    if s in ("cursor",):
+        return "cursor"
+    if s in ("claude_code", "claude"):
+        return "claude_code"
+    raise ValueError(f"hosts must be both, cursor, or claude_code — got {raw!r}")
+
+
+def infer_materialize_hosts_from_mcp_client(
+    client_name: str,
+    client_title: str = "",
+    *,
+    environ: Mapping[str, str] | None = None,
+) -> str:
+    """Best-effort host set from MCP ``initialize.params.clientInfo`` (and Cursor env hints)."""
+    env = environ if environ is not None else os.environ
+    blob = f"{client_name} {client_title}".lower()
+    if "cursor" in blob:
+        return "cursor"
+    if "claude" in blob:
+        return "claude_code"
+    if env.get("CURSOR_TRACE_ID") or env.get("CURSOR_AGENT"):
+        return "cursor"
+    return "both"
+
+
+def resolve_materialize_hosts_argument(
+    raw: str | None,
+    *,
+    client_name: str = "",
+    client_title: str = "",
+    environ: Mapping[str, str] | None = None,
+) -> tuple[str, dict[str, Any]]:
+    """Resolve MCP ``hosts``: explicit modes, or ``auto`` / omit → env then client inference."""
+    envmap = environ if environ is not None else os.environ
+    if raw is None:
+        hosts_requested = ""
+        rr = ""
+    else:
+        hosts_requested = str(raw).strip()
+        rr = hosts_requested.lower().replace("-", "_")
+
+    meta: dict[str, Any] = {
+        "hosts_requested": hosts_requested,
+        "mcp_client_name": client_name.strip(),
+        "mcp_client_title": client_title.strip(),
+    }
+
+    if rr and rr != "auto":
+        mode = normalize_materialize_hosts(hosts_requested)
+        meta["hosts_resolution"] = "explicit"
+        return mode, meta
+
+    env_hosts = envmap.get("SKILLFORGE_MATERIALIZE_HOSTS", "").strip()
+    if env_hosts:
+        mode = normalize_materialize_hosts(env_hosts)
+        meta["hosts_resolution"] = "environment"
+        return mode, meta
+
+    mode = infer_materialize_hosts_from_mcp_client(
+        client_name, client_title, environ=envmap
+    )
+    meta["hosts_resolution"] = "inferred"
+    return mode, meta
+
+
 def _safe_root(raw: str) -> Path:
     root = Path(raw).expanduser().resolve()
     if not root.is_dir():
@@ -29,26 +100,36 @@ def materialize_project_files(
     skill_descriptions: dict[str, str],
     *,
     merge: bool = True,
+    hosts: str = "both",
 ) -> dict[str, Any]:
-    """Create or update Cursor rule + command, Claude Code command, PRD stub, and CLAUDE.md section.
+    """Create or update Cursor and/or Claude Code project stubs, docs, optional CLAUDE.md section.
 
-    merge=False skips overwriting existing `.cursor/rules/skillforge.mdc`,
-    `.cursor/commands/skillforge.md`, and `.claude/commands/skillforge.md` if they already exist
-    (other files still update).
+    ``hosts``:
+      - ``both`` (default) — Cursor rules/commands, Claude ``/skillforge``, ``docs/…``, ``CLAUDE.md``.
+      - ``cursor`` — only ``.cursor/`` tree + docs (no ``.claude/``, no ``CLAUDE.md``).
+      - ``claude_code`` — ``.claude/commands/``, ``docs/``, ``CLAUDE.md`` (no ``.cursor/``).
+
+    merge=False skips overwriting existing host-specific command/rule files targeted by this run
+    if they already exist (other destinations still update per ``hosts``).
     """
+    mode = normalize_materialize_hosts(hosts)
     root = _safe_root(project_root)
     written: list[str] = []
 
+    write_cursor = mode in ("both", "cursor")
+    write_claude = mode in ("both", "claude_code")
+
     summaries = [
         f"- `{n}`: {(skill_descriptions.get(n) or '')[:160]}"
         for n in skill_names
     ]
     skills_md = "\n".join(summaries) if summaries else "_No skills listed._"
 
-    cursor_rule = root / ".cursor" / "rules" / "skillforge.mdc"
-    _assert_under(root, cursor_rule)
-    cursor_rule.parent.mkdir(parents=True, exist_ok=True)
-    mdc_body = f"""---
+    if write_cursor:
+        cursor_rule = root / ".cursor" / "rules" / "skillforge.mdc"
+        _assert_under(root, cursor_rule)
+        cursor_rule.parent.mkdir(parents=True, exist_ok=True)
+        mdc_body = f"""---
 description: Use Skillforge MCP to route SKILL.md context for this repo
 globs: []
 alwaysApply: false
@@ -60,7 +141,7 @@ When the user invokes **Skillforge**, types **`/skillforge`** (Cursor or **Claud
 
 1. Call **route_skills** with **`project_root`** set to this workspace root (so learning and SQLite live in **`.skillforge/`** here), the user's task, and optional **session_id** (reuse within a thread for reroute stats). If the host sets **`SKILLFORGE_PROJECT_ROOT`**, you can omit **project_root** on each call.
 
-   If **`SKILLFORGE_ROUTER_MODE=host`**: first **`route_skills`** without **`picked_names`** (shortlist only); then call again with **`picked_names`** for the chosen catalog ids before continuing.
+   If **`host`** routing (default when **`SKILLFORGE_ROUTER_MODE`** is unset): first **`route_skills`** without **`picked_names`** (shortlist only); then call again with **`picked_names`** for the chosen catalog ids before continuing.
 2. Inject the returned skill bodies into context before continuing.
 3. To refresh project files, call **materialize_project** with **project_root** set to this workspace root and **skill_names** from the last **route_skills** result.
 
@@ -68,16 +149,18 @@ When the user invokes **Skillforge**, types **`/skillforge`** (Cursor or **Claud
 
 {skills_md}
 """
-    if cursor_rule.exists() and not merge:
-        pass
-    else:
-        cursor_rule.write_text(mdc_body, encoding="utf-8")
-        written.append(str(cursor_rule.relative_to(root)))
+        if not (cursor_rule.exists() and not merge):
+            cursor_rule.write_text(mdc_body, encoding="utf-8")
+            written.append(str(cursor_rule.relative_to(root)))
+
+        cursor_cmd = root / ".cursor" / "commands" / "skillforge.md"
+        _assert_under(root, cursor_cmd)
+        cursor_cmd.parent.mkdir(parents=True, exist_ok=True)
+        cmd_body = f"""---
+description: Route SKILL.md context via Skillforge MCP for this workspace (/skillforge). Use skillforge MCP route_skills.
+---
 
-    cursor_cmd = root / ".cursor" / "commands" / "skillforge.md"
-    _assert_under(root, cursor_cmd)
-    cursor_cmd.parent.mkdir(parents=True, exist_ok=True)
-    cmd_body = f"""# Skillforge — route SKILL.md context (MCP)
+# Skillforge — route SKILL.md context (MCP)
 
 The user chose the **`/skillforge`** project command. Use the **skillforge** MCP server.
 
@@ -85,27 +168,26 @@ The user chose the **`/skillforge`** project command. Use the **skillforge** MCP
 
 1. **`route_skills`**: pass **`project_root`** as this workspace root (absolute path) so SQLite lives in **`.skillforge/`** here. Pass the **current user task** as **`prompt`**. Reuse **`session_id`** across turns in the same thread when the MCP returns one.
 
-   - **`SKILLFORGE_ROUTER_MODE=host`**: call once **without** **`picked_names`** (shortlist in the response); then call again with **`picked_names`** (exact catalog ids) to load skill context.
+   - **`host`** routing (default when **`SKILLFORGE_ROUTER_MODE`** is unset): call once **without** **`picked_names`** (shortlist in the response); then call again with **`picked_names`** (exact catalog ids) to load skill context.
    - Optional: pass **`conversation`** when recent turns should influence routing.
 
 2. **Use the returned skill text** in your answer (summarize or follow the SKILL.md guidance as appropriate).
 
-3. Optionally **`materialize_project`** with the same **`project_root`** and **`skill_names`** from **`route_skills`** to refresh **`.cursor/rules`**, **`.cursor/commands`**, **`.claude/commands`**, and **docs/SKILLFORGE-PRD.md**.
+3. Optionally **`materialize_project`** with the same **`project_root`** and **`skill_names`** from **`route_skills`** — use **`hosts: \"auto\"`** (default via MCP), **`\"cursor\"`**, **`\"claude_code\"`**, or **`\"both\"`** so only relevant IDE files refresh.
 
 ## Skills last materialized for this project
 
 {skills_md}
 """
-    if cursor_cmd.exists() and not merge:
-        pass
-    else:
-        cursor_cmd.write_text(cmd_body, encoding="utf-8")
-        written.append(str(cursor_cmd.relative_to(root)))
-
-    claude_cmd = root / ".claude" / "commands" / "skillforge.md"
-    _assert_under(root, claude_cmd)
-    claude_cmd.parent.mkdir(parents=True, exist_ok=True)
-    cc_body = f"""---
+        if not (cursor_cmd.exists() and not merge):
+            cursor_cmd.write_text(cmd_body, encoding="utf-8")
+            written.append(str(cursor_cmd.relative_to(root)))
+
+    if write_claude:
+        claude_cmd = root / ".claude" / "commands" / "skillforge.md"
+        _assert_under(root, claude_cmd)
+        claude_cmd.parent.mkdir(parents=True, exist_ok=True)
+        cc_body = f"""---
 description: Use Skillforge MCP route_skills for this repo. Invoke when the user runs /skillforge or needs routed SKILL.md context.
 ---
 
@@ -117,27 +199,26 @@ Project-local **`/skillforge`** for **Claude Code**. Use the **skillforge** MCP
 
 1. **`route_skills`**: pass **`project_root`** as this workspace root (absolute path). Pass the **current user task** as **`prompt`**. Reuse **`session_id`** when returned.
 
-   - **`SKILLFORGE_ROUTER_MODE=host`**: shortlist first, then **`picked_names`**.
+   - **`host`** routing (default when **`SKILLFORGE_ROUTER_MODE`** is unset): shortlist first, then **`picked_names`**.
 
 2. **Use the returned skill text** in your answer.
 
-3. Optionally **`materialize_project`** to refresh this file and **`.cursor`** files.
+3. Optionally **`materialize_project`** (**`hosts: \"auto\"`** (MCP default), **`\"claude_code\"`**, or **`\"both\"`**) to refresh this file.
 
 ## Skills last materialized for this project
 
 {skills_md}
 """
-    if claude_cmd.exists() and not merge:
-        pass
-    else:
-        claude_cmd.write_text(cc_body, encoding="utf-8")
-        written.append(str(claude_cmd.relative_to(root)))
+        if not (claude_cmd.exists() and not merge):
+            claude_cmd.write_text(cc_body, encoding="utf-8")
+            written.append(str(claude_cmd.relative_to(root)))
 
-    docs_dir = root / "docs"
-    docs_dir.mkdir(parents=True, exist_ok=True)
-    prd = docs_dir / "SKILLFORGE-PRD.md"
-    _assert_under(root, prd)
-    prd_body = f"""# Skillforge — project PRD (auto-generated stub)
+    if write_cursor or write_claude:
+        docs_dir = root / "docs"
+        docs_dir.mkdir(parents=True, exist_ok=True)
+        prd = docs_dir / "SKILLFORGE-PRD.md"
+        _assert_under(root, prd)
+        prd_body = f"""# Skillforge — project PRD (auto-generated stub)
 
 Scaffold for goals and milestones. Re-run **materialize_project** after major routing or pack changes.
 
@@ -148,8 +229,8 @@ Scaffold for goals and milestones. Re-run **materialize_project** after major ro
 ## How to run Skillforge here
 
 - **MCP**: configure the `skillforge` server (e.g. `npx -y @heytherevibin/skillforge mcp`). No API key required for embedding-only routing.
-- **Cursor**: use **`/skillforge`** (**`.cursor/commands/skillforge.md`**) to steer the agent through **route_skills** for this workspace.
-- **Claude Code**: use **`/skillforge`** (**`.claude/commands/skillforge.md`**) the same way.
+- **Cursor**: use **`/skillforge`** (**`.cursor/commands/skillforge.md`**) after **materialize_project** with **`hosts: \"auto\"`**, **`\"cursor\"`**, or **`\"both\"`**.
+- **Claude Code**: use **`/skillforge`** (**`.claude/commands/skillforge.md`**) after **materialize_project** with **`hosts: \"auto\"`**, **`\"claude_code\"`**, or **`\"both\"`**.
 - **session_id**: reuse the same value across **route_skills** calls in one conversation thread.
 - Re-bootstrap this project after new skills: **materialize_project** again.
 
@@ -165,12 +246,13 @@ Scaffold for goals and milestones. Re-run **materialize_project** after major ro
 
 - [ ] (edit me)
 """
-    prd.write_text(prd_body, encoding="utf-8")
-    written.append(str(prd.relative_to(root)))
+        prd.write_text(prd_body, encoding="utf-8")
+        written.append(str(prd.relative_to(root)))
 
-    claude_md = root / "CLAUDE.md"
-    skill_list = ", ".join(f"`{n}`" for n in skill_names) or "_(none)_"
-    block = f"""{MARKER_START}
+    if write_claude:
+        claude_md = root / "CLAUDE.md"
+        skill_list = ", ".join(f"`{n}`" for n in skill_names) or "_(none)_"
+        block = f"""{MARKER_START}
 
 ## Skillforge (project bootstrap)
 
@@ -184,23 +266,23 @@ Use [Skillforge](https://www.npmjs.com/package/@heytherevibin/skillforge) for **
 
 {MARKER_END}
 """
-    _assert_under(root, claude_md)
-    if claude_md.exists():
-        text = claude_md.read_text(encoding="utf-8")
-        if MARKER_START in text and MARKER_END in text:
-            pattern = re.compile(
-                re.escape(MARKER_START) + r".*?" + re.escape(MARKER_END),
-                re.DOTALL,
-            )
-            text = pattern.sub(block.strip(), text)
+        _assert_under(root, claude_md)
+        if claude_md.exists():
+            text = claude_md.read_text(encoding="utf-8")
+            if MARKER_START in text and MARKER_END in text:
+                pattern = re.compile(
+                    re.escape(MARKER_START) + r".*?" + re.escape(MARKER_END),
+                    re.DOTALL,
+                )
+                text = pattern.sub(block.strip(), text)
+            else:
+                text = text.rstrip() + "\n\n" + block
+            claude_md.write_text(text, encoding="utf-8")
         else:
-            text = text.rstrip() + "\n\n" + block
-        claude_md.write_text(text, encoding="utf-8")
-    else:
-        claude_md.write_text(
-            f"# CLAUDE.md\n\n{block}\n",
-            encoding="utf-8",
-        )
-    written.append(str(claude_md.relative_to(root)))
+            claude_md.write_text(
+                f"# CLAUDE.md\n\n{block}\n",
+                encoding="utf-8",
+            )
+        written.append(str(claude_md.relative_to(root)))
 
-    return {"written": written, "project_root": str(root), "skill_names": list(skill_names)}
+    return {"written": written, "project_root": str(root), "skill_names": list(skill_names), "hosts": mode}