@blxzer/cursor-trellis 0.4.2 → 0.4.3

package/dist/templates/cursor/rules/retrieval-routing.mdc

@@ -1,78 +0,0 @@
----
-description: "Trellis codebase retrieval on Cursor — follow router-derived plans; Rules are the primary injection channel (not sessionStart hooks)"
-alwaysApply: true
----
-
-# Codebase retrieval routing (Cursor)
-
-Before answering **code-location / architecture / caller-chain / config-schema** questions in this repo, use the retrieval layer deliberately. On Cursor, **`.cursor/rules` is the reliable per-turn policy channel**; the **`beforeSubmitPrompt`** hook (`.cursor/hooks/inject-retrieval-plan.py`) runs **telemetry-only** — it does **not** inject `## 代码库检索计划` blocks. Generate a plan via `route_codebase_retrieval.py --instructions` when needed, or follow the default tool order below. Do **not** depend on end-of-turn retrieval-pack hooks for plans.
-
-## Prefer / Adapt / Own (code intelligence)
-
-**Three surfaces (do not conflate):** (1) **IDE Editor** — full extension LSP; (2) **Agents Window (Glass)** — staff-reported partial LSP vs Editor ([forum](https://forum.cursor.com/t/cursor-agents-window-lsp-not-working-with-typescript/156772)); (3) **Agent autonomous tools** — [official list](https://cursor.com/docs/agent/overview.md) is search/read/edit/shell/web — **no** `GO_TO_DEFINITION` / raw LSP tool. Trellis routes **Agent tool table** only. See `retrieval-daily-guide.md` § Prefer/Adapt/Own evidence (2026-08-05 smart-search + Native probe).
-
-| Need | **Prefer** (Cursor native, Agent-reachable) | **Adapt** (route by intent / `cursorEnv`) | **Own** (codegraph / MCP) |
-| --- | --- | --- | --- |
-| Exact literal / path | **Grep** | — | — |
-| Named-symbol definition (known identifier) | **Grep → Read** | Path hints from semantic when file unknown | codegraph when cross-package trap, overload ambiguity, or blast context needed |
-| Agent-session diagnostics | **ReadLints** (when in tool table) | — | — |
-| Conceptual / how does X work | **Native:** built-in `@codebase` / semantic search (index embeddings; ≠ LSP) | **BYOK:** **fast_context_search** (fast-context MCP). Plans show `cursorEnv`. | — |
-| Caller chain / blast radius | Grep for imports/callbacks (gap-fill) | — | **codegraph_callers** / **codegraph_explore** |
-| Cross-package trap / extension symbol | Grep scoped by package or `extensions/` | — | **codegraph_search** / **codegraph_explore** |
-| Raw LSP / GO_TO_DEFINITION **as Agent tool** | **Not in Agent tool table** (official docs + Native probe 2026-08-05) | IDE Editor has LSP; Agents Window may lack parity — human UI, not Agent routing | codegraph when Grep+Read insufficient |
-
-**Rollback:** revert this rule + `retrieval-daily-guide.md` Prefer rows to the pre-P1 codegraph-first definition wording; keep codegraph MCP enabled.
-
-## When a retrieval plan block is present
-
-If the user message or Trellis context contains a block starting with `## 代码库检索计划` or `## Codebase retrieval plan`:
-
-1. Execute steps **in order** before stating file paths or behavior claims.
-2. Treat each step as mandatory tooling (not suggestions).
-3. Finish with **Read** verification on cited sources (definition jumps: **Grep → Read** first; **codegraph** when the plan lists structural/trap routes or Grep is ambiguous).
-
-Generate a fresh plan when needed:
-
-```powershell
-python ./.cstl/scripts/route_codebase_retrieval.py "<question>" --instructions
-```
-
-JSON (includes `agentInstructions`):
-
-```powershell
-python ./.cstl/scripts/route_codebase_retrieval.py "<question>" --json
-```
-
-## Default tool order (no plan block)
-
-| Need | Tool (Cursor) |
-| --- | --- |
-| Exact string / path | **Grep** (Instant Grep) |
-| Named-symbol definition | **Grep** → **Read** (Prefer native); **codegraph_explore** / **codegraph_search** when trap, overload, or blast context needed |
-| IDE diagnostics | **ReadLints** on touched or cited files |
-| Who calls / blast radius | **codegraph_callers** / **codegraph_explore** → Grep for imports/callbacks |
-| Same name across packages (trap) | **codegraph_search** / **codegraph_explore** → Grep |
-| Extension symbols | **codegraph_search** under `extensions/` |
-| Conceptual / how does X work | **Native:** built-in `@codebase` / semantic search. **BYOK:** **fast_context_search** (fast-context MCP). Plans show `cursorEnv`. |
-| Policy / architecture / boundaries / storage rules | **Grep** on `AGENTS.md`, `**/AGENTS.md`, `.cstl/spec/**`, `README.md` (router `policy-docs-rg`) before implementation modules |
-| Wide cross-cutting explore | **Native:** DEEP_SEARCH or Explore subagent. **BYOK:** **Task explore** subagent, then Grep/codegraph/Read |
-
-## Semantic on Cursor (`platform-semantic`)
-
-- **cursorEnv native:** built-in codebase semantic search (`platformNative`). Do **not** use fast-context MCP for semantic Primary.
-- **cursorEnv byok:** **fast-context MCP** is **required** for concept retrieval; built-in `@codebase` is not available in the agent tool list.
-- Override detection: `TRELLIS_CURSOR_BYOK=0|1` or `~/.ccursor/routes.json` `byokMode`.
-
-## Result-layer ranking (B / E / D)
-
-When the plan block includes **结果层排序**, apply it **after** collecting path candidates and **before** stating Top-1 / Top-5: caller concrete sites over assembly files; trap demotion; env scripts/e2e/bench over generic `src/auth`/`paths`. Offline reorder: `rank_retrieval_candidates.py`.
-
-## codegraph-only value (Own layer)
-
-Use codegraph for **call chains**, **cross-package trap disambiguation**, **extension symbol resolution**, **impact/blast radius**, and **definition/reference when native Grep+Read is ambiguous** — not for pure literal search (Grep), simple single-package definition jump (Grep+Read), BYOK concept Primary (use fast-context), Agent diagnostics (ReadLints), or **replacing IDE Editor LSP** (human surface).
-
-**Re-probe gate:** Before elevating raw LSP to Prefer, verify Agent tool table + `retrieval-daily-guide.md` evidence notes; if external docs add LSP tools but Native probe fails, **keep fallback** and document the gap.
-
-## External facts
-
-Web/current events: **smart-search** first per `.cstl/framework/retrieval-daily-guide.md` (see **External-knowledge gate** for search-or-not).

package/dist/templates/trellis/local/README.md

@@ -1,85 +0,0 @@
-# Cursor++ Local Bundle
-
-> **Native Cursor users:** safe to ignore or delete this directory unless using **Cursor++ BYOK** on **this repo**.
-
-**Coexistence:** Native and BYOK can run on the same machine across different projects. This bundle is **per-repo** (`cstl init --cursor --cursor2plus`); sibling repos may use `cstl init --cursor` only. Full guide: cursor-trellis `docs/cursor.md` — section *Native and BYOK coexistence (not either/or)*.
-
-**Who needs this:** Cursor IDE with [Cursor++](https://ccursor.cometix.dev) (BYOK proxy). Method 2.5 patches the Cursor++ task model resolver (historically located via `WPeLc8` in verified builds) so Trellis Task subagents get per-role BYOK slugs instead of inheriting the parent model. **After any Cursor or Cursor++ upgrade**, run `python patch_wpelc8.py --check-compat` before re-applying.
-
-## Bundle files
-
-| File | Purpose |
-|------|---------|
-| `patch_wpelc8.py` | Operator CLI: dry-run map, compat check, apply (with `--approve`), revert |
-| `smoke.py` | Health smoke: env, patch status, configured roles (no secret reads) |
-| `trellis_task_models_config.py` | JSON5 + providers catalog resolver (used by patch) |
-| `config.local.json.example` | Optional paths (`extensionJs`, `ccursorHome`, …) |
-| `config.local.json` | Your local paths (gitignored; never commit secrets) |
-
-User-wide model doc: `~/.ccursor/trellis-task-models.json5` (see `../trellis-task-models.json5.example`). Project override: `../subagent-models.json` (optional).
-
-## Compatibility window
-
-- **Verified:** Cursor **3.7.27** / Cursor++ **v0.0.11** (see `.cstl/framework/cursor-subagent-policy.md`, 2026-06-18)
-- **Re-verify** after any Cursor or Cursor++ upgrade: `python patch_wpelc8.py --check-compat`
-- If `--check-compat` reports `fail` or `unknown`, treat the patch as stale until you re-apply or revert
-
-## Method 2.5 workflow
-
-1. **Dry-run map** — `python patch_wpelc8.py --print-map` (no file writes)
-2. **Operator approval** — review map and compat output; decide to proceed
-3. **Apply** — `python patch_wpelc8.py --apply --approve` (writes `extension.js`)
-4. **Reload Cursor** — Developer: Reload Window (once per apply/revert)
-5. **A ≠ B probe** — parent chat model must differ from a patched subagent map target; dispatch a `cstl-*` Task and confirm the subagent self-reports the **map target** slug/model, not the parent
-6. **Revert if needed** — `python patch_wpelc8.py --revert` then Reload Window
-
-Agent-led setup: run skill **`cstl-cursor2plus-setup`** in Cursor Agent (lists models, writes JSON5, runs patch steps).
-
-## Revert recipe
-
-```bash
-cd .cstl/local/cursor2plus
-python patch_wpelc8.py --revert
-```
-
-Then **Developer: Reload Window**. Subagents return to **inherit parent** BYOK model. Re-apply only after `--check-compat` is `ok` and you have explicit `--approve`.
-
-## A ≠ B verification recipe
-
-Goal: prove the patch routes **subagent** model independently of the **parent** session model.
-
-1. Set parent chat to model **A** (any BYOK model in Cursor++).
-2. Ensure `trellis-task-models.json5` maps e.g. `cstl-implement` to model **B** (`primary`/`fallback` resolving to a different slug than A).
-3. `python patch_wpelc8.py --print-map` — note the slug for `cstl-implement` (= map target **B**).
-4. `python patch_wpelc8.py --apply --approve` → Reload Window.
-5. Dispatch a `cstl-implement` Task from a parent on model **A**.
-6. **Pass:** subagent self-report / trace shows **B** (map target), not **A**.
-7. **Fail:** subagent shows **A** → patch stale or not applied; run `--check-compat`, re-patch, or `--revert`.
-
-## CLI reference
-
-```bash
-python patch_wpelc8.py --print-map          # dry-run slug map
-python patch_wpelc8.py --check-compat       # WPeLc8 locatability (no writes)
-python patch_wpelc8.py --apply --approve    # write patch (requires --approve)
-python patch_wpelc8.py --apply --dry-run    # validate without write
-python patch_wpelc8.py --revert             # remove patch
-python patch_wpelc8.py --explain            # JSON5 key meanings
-python patch_wpelc8.py --list-models        # catalog from providers.json
-python smoke.py                             # env + patch_status smoke
-```
-
-`--apply` without `--approve` **refuses** and exits non-zero.
-
-## What to put in `trellis-task-models.json5`
-
-| JSON key (under `models`) | Meaning |
-|---------------------------|---------|
-| `cstl-research` | Trellis research Task subagent |
-| `cstl-implement` | Trellis implement (+ Parent/Child default Task) |
-| `cstl-check` | Trellis check Task subagent |
-| `generalPurpose` / `shell` / `best-of-n-runner` | Cursor built-in Task types |
-
-Each role: `{ "primary": "<name>", "fallback": "<name>" }`. Names: **apiModel** or **displayName** from Cursor++ (`--list-models`). **Explore** is not in this file — use the Cursor++ panel.
-
-Policy: `.cstl/framework/cursor-subagent-policy.md` (Method 2.5 / 2.6).

package/dist/templates/trellis/local/config.local.json.example

@@ -1,6 +0,0 @@
-{
-  "ccursorHome": "",
-  "extensionJs": "",
-  "userModelsJson": "",
-  "projectModelsJson": ""
-}

package/dist/templates/trellis/local/index.d.ts

@@ -1,8 +0,0 @@
-export declare const cursor2plusPatchScript: string;
-export declare const cursor2plusReadme: string;
-export declare const cursor2plusSmokeScript: string;
-export declare const cursor2plusConfigExample: string;
-export declare const subagentModelsExample: string;
-export declare const trellisTaskModelsJson5Example: string;
-export declare const trellisTaskModelsConfigPy: string;
-//# sourceMappingURL=index.d.ts.map

package/dist/templates/trellis/local/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AACxD,eAAO,MAAM,sBAAsB,QAAwB,CAAC;AAC5D,eAAO,MAAM,wBAAwB,QAAyC,CAAC;AAC/E,eAAO,MAAM,qBAAqB,QAA4C,CAAC;AAC/E,eAAO,MAAM,6BAA6B,QAEzC,CAAC;AACF,eAAO,MAAM,yBAAyB,QAA6C,CAAC"}

package/dist/templates/trellis/local/index.js

@@ -1,15 +0,0 @@
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-function readLocal(name) {
-    return readFileSync(join(__dirname, name), "utf-8");
-}
-export const cursor2plusPatchScript = readLocal("patch_wpelc8.py");
-export const cursor2plusReadme = readLocal("README.md");
-export const cursor2plusSmokeScript = readLocal("smoke.py");
-export const cursor2plusConfigExample = readLocal("config.local.json.example");
-export const subagentModelsExample = readLocal("subagent-models.json.example");
-export const trellisTaskModelsJson5Example = readLocal("trellis-task-models.json5.example");
-export const trellisTaskModelsConfigPy = readLocal("trellis_task_models_config.py");
-//# sourceMappingURL=index.js.map

package/dist/templates/trellis/local/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,iBAAiB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAC5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAC,2BAA2B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC,8BAA8B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,SAAS,CACpD,mCAAmC,CACpC,CAAC;AACF,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC,+BAA+B,CAAC,CAAC"}

package/dist/templates/trellis/local/patch_wpelc8.py

@@ -1,421 +0,0 @@
-"""Trellis: reversible Cursor++ WPeLc8 subagent model map (BYOK). See README.md."""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from pathlib import Path
-
-from trellis_task_models_config import (
-    KNOWN_SUBAGENT_TYPES,
-    SUBAGENT_TYPE_HELP,
-    extract_raw_slots,
-    load_providers_catalog,
-    load_task_models_document,
-    resolve_slots_to_slugs,
-)
-
-MARKER = "/*TRELLIS_B2_WPeLc8*/"
-INJECT_NEEDLE = "});return!UbAQWn||"
-
-
-def _repo_root(start: Path) -> Path:
-    cur = start.resolve()
-    for _ in range(12):
-        if (cur / ".cstl").is_dir():
-            return cur
-        if cur.parent == cur:
-            break
-        cur = cur.parent
-    return start.resolve()
-
-
-def _merge_slot_maps(*layers: dict[str, list[str]]) -> dict[str, list[str]]:
-    merged: dict[str, list[str]] = {}
-    for layer in layers:
-        for k, v in layer.items():
-            merged[k] = list(v)
-    return merged
-
-
-def _ccursor_home(config: dict) -> Path:
-    for key in ("ccursorHome", "ccursor_home"):
-        if isinstance(config.get(key), str) and config[key].strip():
-            return Path(config[key].strip()).expanduser()
-    env = os.environ.get("TRELLIS_CCURSOR_HOME", "").strip()
-    if env:
-        return Path(env).expanduser()
-    return Path.home() / ".ccursor"
-
-
-def _load_config(bundle_dir: Path) -> dict:
-    cfg_path = bundle_dir / "config.local.json"
-    if not cfg_path.is_file():
-        return {}
-    try:
-        data = json.loads(cfg_path.read_text(encoding="utf-8"))
-        return data if isinstance(data, dict) else {}
-    except (OSError, json.JSONDecodeError):
-        return {}
-
-
-def resolve_providers_json(config: dict) -> Path:
-    for key in ("providersJson", "providers_json"):
-        if isinstance(config.get(key), str) and config[key].strip():
-            return Path(config[key].strip()).expanduser()
-    env = os.environ.get("TRELLIS_CCURSOR_PROVIDERS", "").strip()
-    if env:
-        return Path(env).expanduser()
-    return _ccursor_home(config) / "providers.json"
-
-
-def _first_existing(*paths: Path) -> Path | None:
-    for p in paths:
-        if p.is_file():
-            return p
-    return None
-
-
-def resolve_user_models_path(config: dict) -> Path:
-    ccursor = _ccursor_home(config)
-    if isinstance(config.get("userModelsJson"), str) and config["userModelsJson"].strip():
-        return Path(config["userModelsJson"].strip()).expanduser()
-    found = _first_existing(
-        ccursor / "trellis-task-models.json5",
-        ccursor / "trellis-task-models.json",
-    )
-    return found or (ccursor / "trellis-task-models.json5")
-
-
-def resolve_project_models_path(bundle_dir: Path, config: dict) -> Path | None:
-    root = _repo_root(bundle_dir)
-    if isinstance(config.get("projectModelsJson"), str) and config["projectModelsJson"].strip():
-        p = Path(config["projectModelsJson"].strip()).expanduser()
-        return p if p.is_file() else None
-    return _first_existing(
-        root / ".cstl" / "local" / "subagent-models.json5",
-        root / ".cstl" / "local" / "subagent-models.json",
-    )
-
-
-def resolve_model_layers(bundle_dir: Path, config: dict, providers_path: Path) -> tuple[dict[str, str], list[str]]:
-    user_path = resolve_user_models_path(config)
-    project_path = resolve_project_models_path(bundle_dir, config)
-    user_slots = extract_raw_slots(load_task_models_document(user_path))
-    project_slots = (
-        extract_raw_slots(load_task_models_document(project_path))
-        if project_path
-        else {}
-    )
-    merged = _merge_slot_maps(user_slots, project_slots)
-    return resolve_slots_to_slugs(merged, providers_path)
-
-
-def configured_slot_map(bundle_dir: Path, config: dict) -> dict[str, list[str]]:
-    """Non-secret role → [primary, fallback, …] from JSON5 only (no providers.json read)."""
-    user_path = resolve_user_models_path(config)
-    project_path = resolve_project_models_path(bundle_dir, config)
-    user_slots = extract_raw_slots(load_task_models_document(user_path))
-    project_slots = (
-        extract_raw_slots(load_task_models_document(project_path))
-        if project_path
-        else {}
-    )
-    return _merge_slot_maps(user_slots, project_slots)
-
-
-def _extension_candidates(config: dict) -> list[Path]:
-    for key in ("extensionJs", "extension_js"):
-        if isinstance(config.get(key), str) and config[key].strip():
-            return [Path(config[key].strip()).expanduser()]
-    env = os.environ.get("TRELLIS_CURSOR2PLUS_EXTENSION", "").strip()
-    if env:
-        return [Path(env).expanduser()]
-    if sys.platform == "win32":
-        local = os.environ.get("LOCALAPPDATA", "")
-        return [
-            Path(local) / "Programs" / "cursor" / "resources" / "app" / "extensions" / "cursor2plus" / "dist" / "extension.js",
-            Path(r"D:\cursor\resources\app\extensions\cursor2plus\dist\extension.js"),
-        ]
-    if sys.platform == "darwin":
-        return [
-            Path("/Applications/Cursor.app/Contents/Resources/app/extensions/cursor2plus/dist/extension.js"),
-        ]
-    return [
-        Path.home() / ".local" / "share" / "cursor" / "resources" / "app" / "extensions" / "cursor2plus" / "dist" / "extension.js",
-    ]
-
-
-def resolve_extension_js(bundle_dir: Path, config: dict) -> Path:
-    for c in _extension_candidates(config):
-        if c.is_file():
-            return c
-    raise SystemExit(
-        "extension.js not found. Set extensionJs in config.local.json or run --bootstrap"
-    )
-
-
-def try_resolve_extension_js(bundle_dir: Path, config: dict) -> Path | None:
-    for c in _extension_candidates(config):
-        if c.is_file():
-            return c
-    return None
-
-
-def build_inject_block(model_map: dict[str, str]) -> str:
-    if not model_map:
-        raise SystemExit(
-            "model map empty — use skill cstl-cursor2plus-setup or write "
-            "~/.ccursor/trellis-task-models.json5 (see .cstl/local/trellis-task-models.json5.example)"
-        )
-    pairs = ",".join(f'"{k}":"{v}"' for k, v in sorted(model_map.items()))
-    return (
-        f"{MARKER}{{const __T={{{pairs}}};const __m=__T[fQ4YPip];"
-        "if(__m&&(!UbAQWn||UbAQWn[Vyazt1(gvQ2P56[0x24a3])][Vyazt1(gvQ2P56[0x204e])]"
-        "===Vyazt1(gvQ2P56[0x2cda])))return __m;}"
-    )
-
-
-def find_wpelc8_body(source: str) -> tuple[int, int]:
-    start = source.find("function WPeLc8(")
-    if start < 0:
-        raise SystemExit("WPeLc8 not found — Cursor++/extension version mismatch?")
-    end = source.find("async function*o4ZNpa", start)
-    if end < 0:
-        raise SystemExit("WPeLc8 end anchor not found")
-    return start, end
-
-
-def probe_wpelc8_compat(source: str) -> dict[str, str]:
-    """Non-exiting WPeLc8 / inject-anchor probe for --check-compat and smoke."""
-    start = source.find("function WPeLc8(")
-    if start < 0:
-        return {"wpelc8": "not_locatable", "inject_anchor": "unknown", "end_anchor": "unknown"}
-    end = source.find("async function*o4ZNpa", start)
-    if end < 0:
-        return {"wpelc8": "locatable", "inject_anchor": "unknown", "end_anchor": "missing"}
-    fn = source[start:end]
-    anchor = "present" if INJECT_NEEDLE in fn else "missing"
-    return {"wpelc8": "locatable", "inject_anchor": anchor, "end_anchor": "present"}
-
-
-def apply_patch(source: str, inject: str) -> str:
-    start, end = find_wpelc8_body(source)
-    fn = source[start:end]
-    if MARKER in fn:
-        fn = remove_patch_from_fn(fn)
-    if INJECT_NEEDLE not in fn:
-        raise SystemExit(f"inject anchor missing: {INJECT_NEEDLE!r}")
-    fn_new = fn.replace(INJECT_NEEDLE, f"}});{inject}return!UbAQWn||", 1)
-    return source[:start] + fn_new + source[end:]
-
-
-def remove_patch_from_fn(fn: str) -> str:
-    import re
-
-    return re.sub(
-        re.escape(MARKER) + r"\{const __T=\{[^}]+\};const __m=__T\[fQ4YPip\];"
-        r"if\(__m&&\(!UbAQWn\|\|UbAQWn\[Vyazt1\(gvQ2P56\[0x24a3\]\)\]\[Vyazt1\(gvQ2P56\[0x204e\]\)\]"
-        r"===Vyazt1\(gvQ2P56\[0x2cda\]\)\)\)return __m;\}",
-        "",
-        fn,
-        count=1,
-    )
-
-
-def remove_patch(source: str) -> str:
-    if MARKER not in source:
-        raise SystemExit("marker not found — not patched?")
-    start, end = find_wpelc8_body(source)
-    fn = remove_patch_from_fn(source[start:end])
-    return source[:start] + fn + source[end:]
-
-
-def cmd_explain() -> None:
-    print("trellis-task-models.json5 — Agent 协助填写；用户只选模型名")
-    print("每项: { primary, fallback } — 首选不可用则自动备选 (WARN)")
-    print()
-    for key in KNOWN_SUBAGENT_TYPES:
-        print(f"  {key}")
-        print(f"    → {SUBAGENT_TYPE_HELP.get(key, '')}")
-    print()
-    print("Skill: cstl-cursor2plus-setup (init 后与大模型交互完成配置)")
-
-
-def cmd_list_models(providers_path: Path) -> None:
-    by_slug, _ = load_providers_catalog(providers_path)
-    if not by_slug:
-        raise SystemExit(f"no models in {providers_path}")
-    print(f"# {providers_path}")
-    print("# 给用户选 primary/fallback 时引用 apiModel 或 displayName")
-    print()
-    rows = sorted(by_slug.values(), key=lambda r: (str(r.get("provider")), str(r.get("displayName"))))
-    for r in rows:
-        print(
-            f"  {r.get('displayName')!r:28} apiModel={r.get('apiModel')!r:32} "
-            f"slug={r.get('slug')}  provider={r.get('provider')}"
-        )
-
-
-def cmd_bootstrap(bundle_dir: Path) -> None:
-    config = _load_config(bundle_dir)
-    cfg_out = bundle_dir / "config.local.json"
-    if not cfg_out.is_file():
-        config = {}
-    try:
-        resolve_extension_js(bundle_dir, config)
-        print("extension.js auto-detected", file=sys.stderr)
-    except SystemExit:
-        path = input("Paste full path to cursor2plus/dist/extension.js: ").strip()
-        if path:
-            config["extensionJs"] = path
-    cfg_out.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
-    print("wrote", cfg_out)
-    print("Next: in Cursor Agent, run skill cstl-cursor2plus-setup", file=sys.stderr)
-
-
-def cmd_check_compat(bundle_dir: Path, config: dict) -> int:
-    extension = try_resolve_extension_js(bundle_dir, config)
-    result: dict[str, object] = {
-        "extension": str(extension) if extension else None,
-        "patch_marker_present": False,
-        "wpelc8": "unknown",
-        "inject_anchor": "unknown",
-        "end_anchor": "unknown",
-    }
-    if extension is None:
-        result["status"] = "unknown"
-        result["hint"] = (
-            "extension.js not found — set extensionJs in config.local.json or run --bootstrap; "
-            "manual verification required"
-        )
-        print(json.dumps(result, indent=2, sort_keys=True))
-        return 2
-
-    source = extension.read_text(encoding="utf-8", errors="ignore")
-    result["patch_marker_present"] = MARKER in source
-    probe = probe_wpelc8_compat(source)
-    result.update(probe)
-
-    wpelc8 = probe["wpelc8"]
-    anchor = probe["inject_anchor"]
-    end_anchor = probe.get("end_anchor", "unknown")
-
-    if wpelc8 == "not_locatable" or anchor == "missing":
-        result["status"] = "fail"
-        result["hint"] = (
-            "WPeLc8 or inject anchor not found after Cursor/Cursor++ upgrade — "
-            "re-run patch with --apply --approve or revert to inherit-parent"
-        )
-    elif wpelc8 == "unknown" or anchor == "unknown" or end_anchor == "unknown":
-        result["status"] = "unknown"
-        result["hint"] = "Locator uncertain — manually verify extension.js after any upgrade"
-    else:
-        result["status"] = "ok"
-        result["hint"] = "WPeLc8 and inject anchor locatable"
-
-    print(json.dumps(result, indent=2, sort_keys=True))
-    return 0 if result["status"] == "ok" else (1 if result["status"] == "fail" else 2)
-
-
-def main() -> None:
-    ap = argparse.ArgumentParser(
-        description="Trellis Cursor++ WPeLc8 model map (Method 2.5)",
-        epilog=(
-            "Read-only: --print-map, --check-compat. "
-            "Write: --apply --approve (or --revert). "
-            "Never runs in CI by default."
-        ),
-    )
-    ap.add_argument("--revert", action="store_true", help="Remove Trellis patch from extension.js")
-    ap.add_argument("--apply", action="store_true", help="Apply patch to extension.js")
-    ap.add_argument(
-        "--approve",
-        action="store_true",
-        help="Explicit operator approval (required for --apply writes)",
-    )
-    ap.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="With --apply: validate patch without writing extension.js",
-    )
-    ap.add_argument("--bootstrap", action="store_true", help="Create config.local.json with extension path")
-    ap.add_argument("--explain", action="store_true", help="Explain trellis-task-models.json5 keys")
-    ap.add_argument("--list-models", action="store_true", help="List models from providers.json catalog")
-    ap.add_argument("--print-map", action="store_true", help="Dry-run: print resolved slug map (no file writes)")
-    ap.add_argument(
-        "--check-compat",
-        action="store_true",
-        help="Check WPeLc8 locatability in current extension.js (no file writes)",
-    )
-    args = ap.parse_args()
-
-    bundle_dir = Path(__file__).resolve().parent
-    if args.explain:
-        cmd_explain()
-        return
-    if args.bootstrap:
-        cmd_bootstrap(bundle_dir)
-        return
-
-    config = _load_config(bundle_dir)
-
-    if args.check_compat:
-        raise SystemExit(cmd_check_compat(bundle_dir, config))
-
-    providers_path = resolve_providers_json(config)
-
-    if args.list_models:
-        cmd_list_models(providers_path)
-        return
-
-    needs_map = args.print_map or args.apply or args.revert
-    model_map: dict[str, str] = {}
-    notes: list[str] = []
-    if needs_map and not args.revert:
-        model_map, notes = resolve_model_layers(bundle_dir, config, providers_path)
-        if notes:
-            print("resolve:", file=sys.stderr)
-            for line in notes:
-                print(line, file=sys.stderr)
-        if any("ERROR" in line for line in notes):
-            raise SystemExit(1)
-
-    if args.print_map:
-        print(json.dumps(model_map, indent=2, sort_keys=True))
-        return
-
-    if args.revert:
-        extension = resolve_extension_js(bundle_dir, config)
-        source = extension.read_text(encoding="utf-8", errors="ignore")
-        new = remove_patch(source)
-        extension.write_text(new, encoding="utf-8", newline="\n")
-        print("wrote", extension)
-        return
-
-    if args.apply:
-        if not args.approve and not args.dry_run:
-            print(
-                "refused: --apply writes extension.js and requires explicit --approve "
-                "(use --dry-run to validate without writing)",
-                file=sys.stderr,
-            )
-            raise SystemExit(1)
-        extension = resolve_extension_js(bundle_dir, config)
-        source = extension.read_text(encoding="utf-8", errors="ignore")
-        inject = build_inject_block(model_map)
-        new = apply_patch(source, inject)
-        if args.dry_run:
-            print("ok patch delta", len(new) - len(source))
-            return
-        extension.write_text(new, encoding="utf-8", newline="\n")
-        print("wrote", extension)
-        return
-
-    ap.print_help()
-    raise SystemExit(2)
-
-
-if __name__ == "__main__":
-    main()