@blxzer/cursor-trellis 0.4.1 → 0.4.3

package/dist/templates/markdown/{spec/guides → framework}/cursor-subagent-policy.md.txt

@@ -2,6 +2,8 @@
 
 > **Purpose:** Cursor-first guidance for when to spawn Trellis custom agents, which mode to use, and how model choice stays on the Cursor side.
 
+> **⚠️ Cursor++ 路线已废弃（2026-08-19 用户裁决）**：Trellis 不再为 Cursor++ / `cstl-cursor2plus-setup` / `.cstl/local/cursor2plus/` 服务。现行路径 = **Native Cursor API**。Cursor++ 产品面已从 Trellis SSOT 移除；遗留 `.cstl/local/cursor2plus/` 视为死档残渣（勿 patch）。下文 **Historical appendix** 仅保留 Method 2.5/2.6 证据摘要，**禁止当操作指南**（勿 patch、勿 Reload、勿跑 `patch_wpelc8.py`）。
+
 **Abstract policy:** `model_policy: cursor-configured` — Trellis workflow, agents, skills, and hooks **must not** hardcode vendor model IDs in **committed** defaults (`gpt-*`, `claude-*`, etc.).
 
 ---
@@ -14,13 +16,13 @@ The same `cstl-*` name can be reached via three entry points with **different mo
 How did I reach cstl-research / cstl-implement / cstl-check?
 │
 ├─ Opened a Cursor chat and @mentioned or /slash-invoked it
-│  → Agent session. Top-bar model decides. Cursor Settings for cstl-* are
-│    largely ineffective under BYOK. Do NOT expect json5 + Method 2.5 here.
+│  → Agent session. Top-bar model decides.
 │
 ├─ Main session dispatched Task(subagent_type=cstl-*)
-│  → Task dispatch. ONLY path where BYOK json5 + Method 2.5 applies.
-│    Context: CLI Layer 2 pre-embed (primary on Cursor); hook is best-effort
-│    (<!-- cstl-hook-injected --> marker; skips if already present).
+│  → Task dispatch. Native: frontmatter `model:` (Method 4) may apply.
+│    BYOK env: inherit parent unless the gateway override
+│    is configured. Context: CLI Layer 2 pre-embed (primary on Cursor);
+│    hook is best-effort (<!-- cstl-hook-injected --> marker).
 │
 └─ Used the cstl-check SKILL in main session (no subagent spawn)
    → Skill form. Main-session model. Only cstl-check has both
@@ -39,34 +41,34 @@ If unsure: Task dispatch is the path Trellis workflow routes through; Agent sess
 | Implementation (after `start-execution --approved`) | `cstl-implement`                                            | Agent                               | Code edits; no `git commit` in subagent; **CLI Layer 2** dispatch prompt on Cursor |
 | Post-implementation verification                    | `cstl-check`                                                | Agent                               | Fixes + `verify.md` / gate hints; **CLI Layer 2** on Cursor; main session records gates |
 | Parent/Child child worker                           | `generate-child-prompt --mode subagent`                        | **Parent Task** `cstl-implement` (default) | Child delivers `verify.md` + `handoff.md`; rare per-child model → **new writable Agent** session when user names that child |
-| Architecture / deep review                          | `cstl-check` or documented inline deep review               | Agent or main session               | Model via dispatch strategy (Methods 1–2.5, 3–4 below)                                               |
+| Architecture / deep review                          | `cstl-check` or documented inline deep review               | Agent or main session               | Model via dispatch strategy (Methods 1–4 below)                                               |
 | PRD Grill (planning)                                | `cstl-micro-grill` contract **inside** `cstl-brainstorm` | **Not** a subagent                  | Single-question business follow-ups only                                                     |
 | Small unclear ask (no task)                         | `cstl-micro-grill` skill                                    | Main session                        | No task artifacts by default                                                                 |
 
 ---
 
-## Model dispatch strategy (BYOK-aware)
-
-> **Model routing details:** See Method 2.5 / 2.6 below and Cursor++ provider settings (`~/.ccursor/providers.json`).
+## Model dispatch strategy (Native / BYOK env detection)
 
 ### Environment detection
 
-| Environment           | Custom Task subagent model control                                                                 | Explore subagent model control                     |
-| --------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| **Native Cursor API** | Frontmatter `model:` works (server-side routing)                                                   | Native model picker                                |
-| **Cursor++ BYOK**     | ❌ Frontmatter / Cursor Settings per-agent: not wired for `cstl-*`; **✅ Method 2.5** if applied | ✅ Independent model via Cursor++ panel (v0.0.11+) |
+`cursorEnv` (`native` | `byok` | `unknown`) comes from `~/.ccursor/routes.json` `byokMode` or `TRELLIS_CURSOR_BYOK`. Detection is for retrieval/model env split (`cursorEnv`) — **not** a Cursor++ install path.
 
-Under Cursor++ BYOK, **committed** agent frontmatter `model:` and **Cursor Settings** UI for `cstl-research` / `cstl-implement` / `cstl-check` do **not** populate `subagentModelOverrides` for those types (verified). Without **Method 2.5**, custom Task subagents **inherit** the parent session BYOK model.
+| Environment | Custom Task subagent model control | Explore subagent model control |
+| ----------- | ---------------------------------- | ------------------------------ |
+| **Native Cursor API** | Frontmatter `model:` works (server-side routing) | Native model picker |
+| **BYOK env (`cursorEnv=byok`)** | Inherit parent session model unless the gateway override is configured | Native / gateway picker — **not** a Cursor++ panel |
+
+Do **not** install Cursor++ or run archived `patch_wpelc8.py`. Without a gateway override, custom Task subagents **inherit** the parent session model.
 
 ### Dispatch strategy matrix
 
-| Subagent type                       | Independent model? (BYOK)            | Method                                                                  | Fallback             |
-| ----------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- | -------------------- |
-| **Explore** (built-in)              | ✅ Yes                               | Cursor++ panel (built-in override row)                                  | Inherit parent model |
-| **cstl-research** (custom Task)  | ✅ Yes if **Method 2.5** map applied | **Method 2.5** (machine-local); else Method 1 or **Method 3** (manual) | Inherit parent model |
-| **cstl-implement** (custom Task) | ✅ Yes if **Method 2.5** map applied | **Method 2.5**; else Method 1 or **Method 3**                           | Inherit parent model |
-| **cstl-check** (custom Task)     | ✅ Yes if **Method 2.5** map applied | **Method 2.5**; else Method 1 or **Method 3**                           | Inherit parent model |
-| **generalPurpose** / **shell** / **best-of-n-runner** | ✅ Yes if map includes keys | **Method 2.5 / 2.6** JSON map | Inherit parent model |
+| Subagent type                       | Independent model? | Method | Fallback |
+| ----------------------------------- | ------------------ | ------ | -------- |
+| **Explore** (built-in)              | ✅ Yes (Native picker) | Method 2 | Inherit parent model |
+| **cstl-research** (custom Task)  | Native: Method 4 overlay; else inherit | Method 1 or **Method 3** (manual) | Inherit parent model |
+| **cstl-implement** (custom Task) | Native: Method 4 overlay; else inherit | Method 1 or **Method 3** | Inherit parent model |
+| **cstl-check** (custom Task)     | Native: Method 4 overlay; else inherit | Method 1 or **Method 3** | Inherit parent model |
+| **generalPurpose** / **shell** / **best-of-n-runner** | Inherit unless Native overlay | Method 1 or Method 3 | Inherit parent model |
 
 ### When to ask (and when not)
 
@@ -84,7 +86,7 @@ Task mode (Lite / Full / Parent) does **not** by itself trigger the question —
 
 ### Method 2: Explore subagent with custom model (read-only research)
 
-When research is purely **codebase exploration** (no external web search, no file writing outside exploration scope), dispatch an **Explore subagent** instead of cstl-research. The Explore type gets independent model selection via the Cursor++ panel.
+When research is purely **codebase exploration** (no external web search, no file writing outside exploration scope), dispatch an **Explore subagent** instead of cstl-research. Pick the Explore model with the **Native** model picker (or inherit).
 
 **Constraints:**
 
@@ -94,40 +96,9 @@ When research is purely **codebase exploration** (no external web search, no fil
 
 **Use when:** Pure codebase search/understanding tasks where a different model adds value. Main session receives findings and writes the research files.
 
-### Method 2.5: Cursor++ BYOK proxy map (publishable bundle)
-
-**What it is:** A reversible patch to Cursor++ `extension.js` **subagent model resolver** that maps `subagentType` → BYOK catalog **slug** (`model-xxxxx`), evaluated **before** the inherit-parent branch. Obfuscated symbol names change per build (historical `WPeLc8`; 2026-08+ profile `ZiKp4I`). Script uses multi-profile detection.
-
-**Trellis ships (every `cstl init` / `cstl update`, strategy C):** `.cstl/local/cursor2plus/` — `patch_wpelc8.py`, `README.md`, **`UPGRADE-NOTE.md`** (upgrade re-apply), `config.local.json.example`. Native Cursor API users can ignore this directory.
-
-**Operator workflow (Cursor++ BYOK only):**
-
-1. Fill **`~/.ccursor/trellis-task-models.json5`** (user-wide) with `subagent_type` → displayName/apiModel from **`~/.ccursor/providers.json`**.
-2. Optionally override per repo: **`.cstl/local/subagent-models.json5`** (project wins on same key).
-3. If paths are not auto-detected: copy `config.local.json.example` → `config.local.json`, or run `python patch_wpelc8.py --bootstrap`, or set `TRELLIS_CCURSOR_HOME` / `TRELLIS_CURSOR2PLUS_EXTENSION`.
-4. From `.cstl/local/cursor2plus/`: `python patch_wpelc8.py --check-compat` → `--print-map` → `--apply --approve` → **Developer: Reload Window**.
-5. **Verify:** A≠B probe (parent model ≠ map target) or `resolvedModelId` matches slug.
-
-**Revert:** `python patch_wpelc8.py --revert`; Reload Window.
-
-**After any Cursor / Cursor++ upgrade:** assume patch is stale — follow **`.cstl/local/cursor2plus/UPGRADE-NOTE.md`** (`--check-compat`, re-apply, or add a new resolver profile if symbols moved).
-
-**Cursor++ sidebar / Cursor Settings:** Do **not** wire `cstl-*` BYOK routing; use JSON + patch.
-
-### Method 2.6: Temporary Task types (advanced, BYOK)
-
-For rare per-dispatch models on the Task channel without changing global slots:
-
-1. Add `.cursor/agents/cstl-worker-<id>.md` (role prompt only; no committed `model:`).
-2. Add `"cstl-worker-<id>": "model-xxxxx"` to **project** `.cstl/local/subagent-models.json`.
-3. Re-run `patch_wpelc8.py`; dispatch `Task(subagent_type=cstl-worker-<id>)`.
-4. Remove agent file and JSON key when done.
-
-Parent/Child **default** does not use 2.6 — it uses `cstl-implement` from the user map. Per-child manual model → **new writable Agent** session (user-named exception).
-
 ### Method 3: Manual dispatch (different model for Task subagent)
 
-When a custom Task subagent (`cstl-research`, `cstl-implement`, `cstl-check`) needs a **different model** than the parent under BYOK **and Method 2.5 is not available**:
+When a custom Task subagent (`cstl-research`, `cstl-implement`, `cstl-check`) needs a **different model** than the parent **and** Native overlay (Method 4) is not available or not desired:
 
 1. **Main session prepares the dispatch prompt** — full text with:
    - First line: Selected task: <path> (e.g. .cstl/tasks/06-17-my-task)
@@ -168,12 +139,10 @@ Under **native Cursor API** (non-BYOK), frontmatter model: on agent files works
 
 ```text
 Subagent dispatch needed
-├─ Cursor++ BYOK + cstl-* needs fixed per-role models?
-│  └─ Method 2.5 applied on this machine? → dispatch Task normally (map handles routing)
 ├─ Parent model appropriate for cstl-*? → Method 1 (inherit)
-├─ Read-only codebase exploration only? → Method 2 (Explore + Cursor++ panel)
+├─ Read-only codebase exploration only? → Method 2 (Explore + Native picker)
 ├─ Native Cursor API (non-BYOK)? → Method 4 (ephemeral frontmatter overlay)
-└─ BYOK, no Method 2.5, different model required? → Method 3 (manual dispatch)
+└─ Different model required, overlay unavailable? → Method 3 (manual dispatch)
 ```
 
 ### Main-session contract
@@ -181,46 +150,44 @@ Subagent dispatch needed
 When a dispatch is imminent:
 
 1. Assess which method applies based on the decision flow.
-2. If **Method 2.5** is active on this machine: dispatch `cstl-research` / `cstl-implement` / `cstl-check` via Task tool as usual — **do not** ask model each time; **do not** edit agent frontmatter.
-3. If Method 1 (inherit): dispatch directly, no model question.
-4. If Method 2 (Explore): set Explore model in Cursor++ panel if needed, dispatch `explore`.
-5. If Method 3 (manual): prepare the full dispatch prompt, present to user.
-6. If Method 4 (overlay, native API): ask model preference, apply overlay, dispatch, restore.
+2. If Method 1 (inherit): dispatch directly, no model question.
+3. If Method 2 (Explore): set Explore model in the Native picker if needed, dispatch `explore`.
+4. If Method 3 (manual): prepare the full dispatch prompt, present to user.
+5. If Method 4 (overlay, native API): ask model preference, apply overlay, dispatch, restore.
 
 ### Rules
 
 - **Never** commit long-lived model: in shared Trellis templates or team repo defaults.
 - **Never** inject model IDs via hooks (inject-subagent-context.py stays task-only).
 - **Do not** attempt ephemeral model overlay under BYOK — it silently fails for routing (Method 4).
-- **Do not** rely on Cursor Settings per `cstl-*` agent for BYOK routing — use Method 2.5 map or Method 3.
-- Method 2.5 map lives **outside** committed Trellis templates (machine-local); never commit patched `extension.js` into the Trellis repo.
+- **Do not** rely on Cursor Settings per `cstl-*` agent for BYOK routing — inherit, BYOK env override, or Method 3.
+- **Do not** apply Cursor++ `extension.js` patches, `patch_wpelc8.py`, or `cstl-cursor2plus-setup`. Those paths are retired.
 - **Do not** assume Explore subagent can replace cstl-research for all scenarios — it is read-only and cannot persist files.
 - Workflow and skills **must not** hardcode vendor model IDs.
 
 ### Child worker
 
-- **Default (BYOK + map):** Parent session dispatches **Task** `cstl-implement` with prompt from `generate-child-prompt --mode subagent`; model from user/project JSON map.
+- **Default:** Parent session dispatches **Task** `cstl-implement` with prompt from `generate-child-prompt --mode subagent`; model inherits parent (Native overlay Method 4 when applicable).
 - **Exception:** User or `child-prompts.md` names a child for **separate writable Agent** → new chat, manual model, paste prompt (Method 3).
 - **Native API:** ephemeral overlay on `cstl-implement` (Method 4) still valid.
 
 ### Technical note
 
-Client layer still only builds override rows for built-in types such as `explore`. Cursor Settings entries for custom agent **names** do not reach the BYOK proxy override list for `cstl-*`. **Method 2.5** patches Cursor++ subagent model resolver (profile-bound; see `UPGRADE-NOTE.md`) so `taskToolCall` sets `resolvedModelId` from a local `subagentType → slug` table before inherit-parent. **Method 3** bypasses Task routing (user picks model in a new chat).
+Client layer still only builds override rows for built-in types such as `explore`. Cursor Settings entries for custom agent **names** do not reliably reach custom `cstl-*` Task types. **Method 3** bypasses Task routing (user picks model in a new chat). Historical Cursor++ resolver-map evidence lives in the appendix — not a current control plane.
 
 ---
 
+## Trellis workflow: using per-agent models (Native / BYOK env)
 
-## Trellis workflow: using per-agent models (BYOK + Method 2.5)
-
-Operational contract between the Trellis task ladder and Cursor++ BYOK.
+Operational contract between the Trellis task ladder and Cursor model routing.
 
 ### Roles and who picks the model
 
 | Layer | Picks model for… | Mechanism |
 | ----- | ---------------- | --------- |
-| **You (operator)** | Main orchestration chat | Cursor model picker (parent BYOK route) |
-| **You (operator)** | `cstl-research` / `cstl-implement` / `cstl-check` (+ optional built-in Task types) | **Method 2.5 / 2.6** JSON maps + `.cstl/local/cursor2plus/patch_wpelc8.py` — **not** repo agent files |
-| **You (operator)** | `explore` | Cursor++ panel |
+| **You (operator)** | Main orchestration chat | Cursor model picker |
+| **You (operator)** | `cstl-research` / `cstl-implement` / `cstl-check` | Inherit, Native Method 4 overlay, or Method 3 — **not** Cursor++ JSON/patch |
+| **You (operator)** | `explore` | Native model picker |
 | **Main Agent session** | When to spawn which agent | `workflow.md`, skills, scene matrix |
 | **Hooks** | Never | `inject-subagent-context.py` — task context only |
 
@@ -228,39 +195,32 @@ Operational contract between the Trellis task ladder and Cursor++ BYOK.
 
 1. **Select task** — `task.py select`; dispatch prompts include `Selected task: .cstl/tasks/<id>` when hooks need it.
 2. **Main session model** — your choice for planning and orchestration.
-3. **Research** — Task `subagent_type=cstl-research` → mapped research slug (Method 2.5).
-4. **Implement** — after `start-execution --approved`, Task `cstl-implement` → mapped implement slug.
-5. **Check** — Task `cstl-check` → mapped check slug.
+3. **Research** — Task `subagent_type=cstl-research` (inherit or Method 4).
+4. **Implement** — after `start-execution --approved`, Task `cstl-implement`.
+5. **Check** — Task `cstl-check`.
 6. **Gates / finish** — main session `record-gate`, `cstl-finish-work`.
 
-No model field in dispatch prompt under Method 2.5. Task `model: fast` does **not** override custom types under BYOK.
+Task `model: fast` does **not** override custom types under BYOK.
 
 ### When to use which method
 
 | Setup | Research | Implement | Check |
 | ----- | -------- | --------- | ----- |
-| Method 2.5 configured | `cstl-research` Task | `cstl-implement` Task | `cstl-check` Task |
-| No map; one parent model | Task (inherit) | Task (inherit) | Task (inherit) |
-| No map; different models | Method 3 | Method 3 | Method 3 |
+| One parent model | Task (inherit) | Task (inherit) | Task (inherit) |
+| Native; different models | Method 4 | Method 4 | Method 4 |
+| BYOK / overlay unavailable; different models | Method 3 | Method 3 | Method 3 |
 | Repo read-only only | Method 2 Explore | — | — |
 
 ### Parent/Child
 
-- **Default:** Parent dispatches **Task** `cstl-implement` (BYOK map applies to `subagentType`).
+- **Default:** Parent dispatches **Task** `cstl-implement`.
 - **Rare per-child model:** new writable Agent session when user names that child — not a separate Trellis subagent type by default.
 - Parent retains `review-child` / `integrate-child`; serial integration and worktree rules unchanged.
 
-### Maintainer checklist (BYOK)
-
-1. Resolve slugs in `~/.ccursor/providers.json` (or path in `config.local.json`).
-2. Edit user and/or project JSON maps; include `generalPurpose`, `shell`, `best-of-n-runner` if you use those Task types.
-3. Run `patch_wpelc8.py` from `.cstl/local/cursor2plus/` → Reload Window.
-4. Re-apply after Cursor / Cursor++ upgrades.
-
 ### What stays in the Trellis repo
 
 - `.cursor/agents/cstl-*.md` — no committed `model:`; link to this policy.
-- Skills/workflow — **which** agent to spawn, not BYOK slugs.
+- Skills/workflow — **which** agent to spawn, not vendor slugs.
 
 ---
 
@@ -273,13 +233,13 @@ Optional team paste (comments only — not Cursor product settings):
 
 ```yaml
 model_policy: cursor-configured
-dispatch_model: inherit_or_method25_or_manual
+dispatch_model: inherit_or_native_overlay_or_manual
 child_worker:
   mode: separate_writable_agent_session
 explore_subagent:
-  model: independent # Cursor++ panel
+  model: independent # Native picker
 trellis_task_subagents:
-  model: method_2_5_proxy_map # machine-local; not in git
+  model: inherit # Native Method 4 overlay optional; Cursor++ map retired
 ```
 
 ---
@@ -293,7 +253,7 @@ trellis_task_subagents:
 | `beforeShellExecution`     | Short-lived ticket for `task.py select` / `selected` / `exit` in shells |
 | `stop`                     | Optional `retrieval-pack-latest.json` when task has `research/`         |
 
-**Per-turn workflow-state on Cursor:** deferred — use `sessionStart` + `/cstl-continue` / `get_context.py --mode phase` instead of a per-turn hook injection (the relevant Cursor channel has a confirmed `additional_context` bug, see `cursor-context-injection-guide.md`).
+**Per-turn workflow-state on Cursor:** deferred — use `sessionStart` + `/cstl-continue` / `get_context.py --mode phase` instead of a per-turn hook injection (the relevant Cursor channel has a confirmed `additional_context` bug, see `./cursor-context-injection-guide.md`).
 
 ---
 
@@ -311,6 +271,7 @@ trellis_task_subagents:
 - Do not spawn `cstl-implement` from inside `cstl-implement` (recursion guard in agent defs).
 - Do not spawn a subagent for PRD Grill — use brainstorm Phase B + micro-grill contract.
 - Do not leave `model:` on agent files after dispatch (always restore).
+- Do not treat Cursor++ / `cstl-cursor2plus-setup` / Method 2.5 as a current option.
 
 ---
 
@@ -330,43 +291,18 @@ This command is **Agent-facing** — not listed in user README or slash command
 
 When `preToolUse` cannot resolve a selected task, the subagent should read **`Selected task:`** from the first line of its dispatch prompt, then load `implement.jsonl` / `check.jsonl`, `prd.md`, `design.md`, and `implement.md` manually. Trellis does **not** document or depend on Cursor `/multitask` for workflow orchestration.
 
-## Cursor++ (BYOK) compatibility
-
-[Cursor++](https://ccursor.cometix.dev) (ccursor by cometix) is a third-party Patch that intercepts Cursor API traffic via a local server (`127.0.0.1:39831`). It does **not** modify `.cursor/` files — it intercepts at the API/gRPC layer (`AgentService/RunSSE`, `AvailableModels`, etc.) and routes requests to BYOK providers.
-
-### Confirmed compatibility (v0.0.11+, Cursor 3.7.27)
-
-| Trellis component     | Status under Cursor++ | Notes                                                                               |
-| --------------------- | --------------------- | ----------------------------------------------------------------------------------- |
-| `.cursor/agents/`     | Normal                | Agent files not intercepted; `model:` frontmatter read by Cursor at spawn           |
-| `.cursor/hooks/`      | Normal                | Hook config loads; verify `hooksConfig` in agent logs when debugging                  |
-| `.cursor/mcp.json`    | Normal                | MCP servers and tools load normally                                                 |
-| SubAgent write access | **Fixed in v0.0.11**  | Prior versions defaulted SubAgent to readonly; `cstl-implement` now writes files |
-
-**Minimum version: v0.0.11.** Earlier versions break `cstl-implement` due to SubAgent readonly bug.
-
-### Model routing under BYOK (verified 2026-06-18)
-
-- **Explore subagent:** Independent model selection works via Cursor++ panel (v0.0.11+). Cursor++ intercepts and routes the selected BYOK model for Explore-type requests.
-- **Custom Task subagents:** Frontmatter `model:` and Cursor Settings per-agent names are **not** applied for `cstl-*` BYOK routing. Use **Method 2.5** or **Method 3**. **Explore** uses Cursor++ panel.
-- The `model:` ID **must match** a model configured in Cursor++ provider settings (`~/.ccursor/providers.json`). If it doesn't match, the request will fail with a provider error.
-- Cursor++ intercepts `AvailableModels`/`GetDefaultModel` - the model picker and model list are determined by BYOK provider config, not Cursor's official model catalog.
-- Under Cursor++, "inherit" means the parent session's BYOK-routed model, which may differ from what the Cursor UI label suggests.
+---
 
-### Safety boundary
+## Historical appendix — Cursor++ Method 2.5 / 2.6 (retired; not SOP)
 
-- Cursor++ patches Cursor internal modules at runtime. Strongest recovery: reinstall Cursor.
-- API keys are stored in **plaintext** in `~/.ccursor/providers.json` — restrict file permissions (`chmod 600` / Windows ACL).
-- Cursor++ stores rules in `~/.ccursor/knowledge-base.json`, independent of `.cursor/rules/` and Trellis rules.
-- Version updates lag behind Cursor releases — after a Cursor update, BYOK routing may break until Cursor++ catches up. Trellis hooks/agents/skills survive the window (they don't depend on API routing).
-- Do not mix Cursor++ BYOK sessions with Cursor official sessions — they cannot be continued across each other.
-- Cursor++ may violate Cursor ToS; use at own risk. Not recommended for enterprise/compliance environments.
+**Do not follow this appendix as an operator runbook.** It records what existed so archive evidence stays findable.
 
-### Anti-patterns for Cursor++
+- **What it was:** A reversible patch to a third-party Cursor++ `extension.js` subagent-model resolver (historical symbol `WPeLc8`, later `ZiKp4I`) mapping `subagentType` → catalog slug before inherit-parent. Operator maps lived in `~/.ccursor/trellis-task-models.json5` and project json5; apply required Reload Window.
+- **Where the dead files are:** `.cstl/local/archive/cursor2plus/`, `.cstl/local/archive/cursor2plus_bundle_src/`, archived `subagent-models.json5`. Reverse-engineering notes: `.cstl/spec/guides/cursor-subagent-reverse-engineering-report.md` (also retired).
+- **Why it is not current:** User retired Cursor++ (2026-08-19). `cstl-cursor2plus-setup` and live `.cstl/local/cursor2plus/` were removed from the Trellis SSOT (P23). Product path = Native Cursor.
+- **Do not:** run `patch_wpelc8.py`, copy archive back into `.cstl/local/cursor2plus/`, invoke `cstl init --cursor2plus`, or use a Cursor++ panel as the Trellis model control plane.
 
-- Do not use Cursor++ older than v0.0.11 with Trellis (SubAgent readonly bug).
-- Do not assume Cursor official model IDs work under BYOK — use model IDs from your provider config.
-- Do not mix Cursor++ and Cursor official sessions for the same conversation.
+---
 
 ## Worktree template
 
@@ -388,7 +324,7 @@ For multi-package workspaces, list all install commands needed after a fresh che
 
 - `.cursor/agents/cstl-research.md`, `cstl-implement.md`, `cstl-check.md`
 - `.cursor/agents/.cstl-model-overlay.local.md` — optional overlay audit stub (native API)
-- Reference `patch_wpelc8.py` in task `06-18-byok-manual-dispatch-automation/research/` — copy locally; not a runtime git dependency
+- `.cstl/local/archive/` — retired Cursor++ bundle (not a runtime dependency)
 - `.cstl/workflow.md` — Task Ladder + Parent orchestration
 - [Cursor Subagents](https://cursor.com/docs/subagents) — `model: inherit | <id>`
 - [Cursor Multitask changelog](https://cursor.com/changelog/04-24-26) — `/multitask`, Worktrees, Multi-root Workspaces

package/dist/templates/markdown/framework/dogfood-only-surfaces.md.txt

@@ -0,0 +1,29 @@
+# Dogfood-Only vs Default Install Surfaces
+
+> **Purpose**: An inventory of surfaces that exist in the **maintainer harness** (MyHarness) but are **not** shipped by a default `cstl init` / `cstl update`. Use it to avoid the false conclusion "the product feature disappeared" when comparing a consumer repo to the harness. A file missing from a consumer project is **by design**, not a regression — the CLI/script/guide surface still carries the capability.
+
+## Rule of thumb
+
+- **Shipped by default** = written by `cstl init --cursor` and refreshed by `cstl update` (workflow, `.cstl/framework/` docs, scripts, AGENTS.md CSTL block, `.cursor/{commands,rules,agents,hooks}`). `.cstl/spec/` seeds are init-only and **never** refreshed — update never touches that directory.
+- **Dogfood-only / harness-only** = present only in the maintainer harness or after manual copy. Absence in a consumer repo is expected.
+
+## Inventory
+
+| Surface | Where it exists | Why dogfood-only | Decision |
+| --- | --- | --- | --- |
+| `.claude/skills/*` full suite | `.claude/skills/` in the harness | Cursor default install is **commands-only**; Claude skill files are for Claude platforms, not Cursor consumers | **non-Cursor** (not in Cursor default install) |
+| `.cstl/local/cursor2plus/` residue (if present) | (retired) | Cursor++ local bundle retired — **not** an optional live surface and **not** an install path; hash-safe cleanup on update | **retired residue** — do not patch; do not treat as optional |
+| Private review-pool items / plan narratives | `.cstl/pool/items/`, `{TASK}/research/` in the harness | Personal or project-specific content; the pool **mechanism** ships, the items do not | **narrative not packaged** — mechanism ships, content stays local |
+| `.codegraph/`, `.worktrees/`, scratch/analysis files | Harness root | Per-machine index / tooling state | **local only** |
+
+## If a capability seems missing in a consumer repo
+
+1. Check the [internal-skills-cursor-reachability.md](./internal-skills-cursor-reachability.md) matrix — the capability's load channel (guide / script / agent / CLI) should be present.
+2. Check AGENTS.md `Invocation map (short)` — the intended entry point (`/cstl-handoff`, etc.).
+3. If the entry point is a harness-only file from the table above, the capability is intentionally **not** shipped to consumers — do not backfill it by copying harness files.
+
+## Related
+
+- [internal-skills-cursor-reachability.md](./internal-skills-cursor-reachability.md) — reachability of internal skill names.
+- [prd-grill-frontier.md](./prd-grill-frontier.md) — P11 grilling on-demand path.
+- AGENTS.md `Invocation map (short)` — session handoff = `/cstl-handoff`.

package/dist/templates/markdown/{spec/guides → framework}/execution-strategy.md.txt

@@ -2,6 +2,8 @@
 
 > **Purpose**: Suggest a Development Strategy Contract before you freeze `implement.md`, and align Phase 2 dispatch with the approved contract.
 
+This file answers **who** implements/checks and **where** files are edited. It is **not** a parallel scheduler. Parallel-first (default native parallel, serial needs `serial_reason`) lives in `workflow.md` and `cursor-native-modes-guide.md`; declaration fields in `parallel-first-execution.md`.
+
 ---
 
 ## Two orthogonal dimensions

package/dist/templates/markdown/framework/index.md.txt

@@ -0,0 +1,31 @@
+# Framework Docs (`.cstl/framework/`)
+
+> **Ownership**: These files are **framework-managed**. `cstl update` refreshes them (with the same hash-conflict prompt as `workflow.md`). If you edit one, update will ask before overwriting — prefer putting project-specific norms in `.cstl/spec/` instead, which update never touches.
+
+Versioned framework and platform-adapter documentation. Project/team knowledge lives in `.cstl/spec/` (user-owned); this directory documents how the framework itself behaves.
+
+## Docs
+
+| Doc | What it covers |
+| --- | --- |
+| [prd-grill-frontier.md](./prd-grill-frontier.md) | On-demand path to the PRD grill and Frontier discipline (bundled `brainstorm` skill is SSOT) |
+| [internal-skills-cursor-reachability.md](./internal-skills-cursor-reachability.md) | How each internal workflow skill is reachable on Cursor (commands-only baseline) |
+| [dogfood-only-surfaces.md](./dogfood-only-surfaces.md) | Which surfaces ship by default vs exist only in the maintainer harness |
+| [cursor-subagent-policy.md](./cursor-subagent-policy.md) | When to spawn Trellis custom agents; model policy stays on the Cursor side |
+| [retrieval-daily-guide.md](./retrieval-daily-guide.md) | Daily retrieval tool routing (search vs retrieval-pack scoring; web-research gate) |
+| [cursor-native-modes-guide.md](./cursor-native-modes-guide.md) | Mapping Cursor Plan / Ask / Debug / Agent / Multitask onto Trellis phases |
+| [parallel-first-execution.md](./parallel-first-execution.md) | Parallel-first **product** principle + execution contract: native parallel default, `serial_reason`, task-map fields |
+| [middleware-protocol.md](./middleware-protocol.md) | Middleware Protocol v1: one ABI, overlay `.cstl/middleware/`, `update` never writes/deletes/hashes it |
+| [upgrade.md](./upgrade.md) | Terminal-user upgrade half-page: install package → `cstl update` → confirm → keep working |
+| [release-boundary.md](./release-boundary.md) | CSTL this-batch ship vs independent cstl-byok ship; BYOK is not a CSTL release gate |
+| [cursor-context-injection-guide.md](./cursor-context-injection-guide.md) | Which Cursor injection channels actually reach the model |
+| [cursor-semantic-compliance.md](./cursor-semantic-compliance.md) | Plan-vs-exec semantic compliance on Cursor |
+| [injection-budget-guide.md](./injection-budget-guide.md) | Context injection budget across reliable Cursor channels |
+| [execution-strategy.md](./execution-strategy.md) | Development Strategy Contract (`execution_mode` / isolation) |
+| [verification-strength-guide.md](./verification-strength-guide.md) | How deeply tasks must be verified before closeout, graded by task mode |
+| [artifact-locale-guide.md](./artifact-locale-guide.md) | How human-reviewed artifacts follow the user's language |
+
+## Related
+
+- `.cstl/workflow.md` — the workflow itself (also framework-managed)
+- `.cstl/spec/guides/` — project thinking guides (user-owned; update never modifies)

package/dist/templates/markdown/framework/internal-skills-cursor-reachability.md.txt

@@ -0,0 +1,45 @@
+# Internal Skills Cursor Reachability Matrix
+
+> **Purpose**: Every skill name the AGENTS.md command surface lists must have a documented **load channel** on a pure Cursor project. Internal workflow skills are **not** shipped to `.cursor/skills/` and have **no** default slash command — by design (commands-only). This matrix is the honest index: how each internal name is actually reachable on-demand, so an agent never claims a skill is loaded without a file read, and users never assume internal skills are slash commands.
+
+## Commands-only baseline
+
+- Default Cursor install writes only: `.cursor/commands/` (user slash commands), `.cursor/rules/*.mdc`, `.cursor/agents/*.md`, `.cursor/hooks`, and `.cstl/` (workflow, framework docs, scripts, spec/guides seeds).
+- Bundled skill **bodies** live in the npm package templates (`dist/templates/common/skills/`, `dist/templates/common/bundled-skills/`). They are **not** copied into a consumer project by `cstl init` on Cursor.
+- "Not in the project" ≠ "missing from the framework": the CLI/script/agent/guide surface below is the reachable carrier.
+
+## Matrix
+
+| Skill name | Package SSOT | Cursor load channel | Slash? | AGENTS lists it? |
+| --- | --- | --- | --- | --- |
+| `cstl-brainstorm` (PRD Grill) | `common/skills/brainstorm.md` | **Read `./prd-grill-frontier.md`** (on-demand summary; full body in npm package) | no | yes |
+| `cstl-micro-grill` | `bundled-skills/cstl-micro-grill/SKILL.md` | Contract embedded in `.cstl/workflow.md` Request Triage + `./prd-grill-frontier.md` §Micro-grill unresolved; full body in npm package | no | yes |
+| `cstl-before-dev` | `common/skills/before-dev.md` | Workflow routes the behavior (Read task artifacts → `get_context.py --mode packages` → spec indexes); full body in npm package | no | yes |
+| `cstl-break-loop` | `common/skills/break-loop.md` | Workflow routes the behavior (Debug → evidence → `cstl-break-loop`); full body in npm package; output pattern in `.cstl/spec/guides/debug-loop-guide.md` | no | yes |
+| `cstl-update-spec` | `common/skills/update-spec.md` | Workflow Phase 3.3 routes the decision (`update-spec` \| `no-update` \| `unsure`); full body in npm package | no | yes |
+| `cstl-check` | `bundled-skills/cstl-check/SKILL.md` | **Agent form `.cursor/agents/cstl-check.md`** (Task tool, dual-axis) — prefer Agent when `execution_mode: worker` | no | yes |
+| `cstl-meta` | `bundled-skills/cstl-meta/SKILL.md` | Maintainer skill; body in npm package; no Cursor project file (not routed in consumer workflows) | no | yes |
+| `cstl-spec-bootstrap` | `bundled-skills/cstl-spec-bootstrap/SKILL.md` | One-shot scaffolding skill; body in npm package; not routed in steady-state consumer workflow | no | yes |
+| `cstl-skill-creator` | `bundled-skills/cstl-skill-creator/SKILL.md` | **Authoring-time (mandatory for new / structural skill edits):** Read `cursor-trellis/packages/cli/src/templates/common/bundled-skills/cstl-skill-creator/SKILL.md` then `…/references/review-checklist.md`. Harness dogfood copy: `.claude/skills/cstl-skill-creator/SKILL.md` and `.claude/skills/cstl-skill-creator/references/review-checklist.md`. Installed npm: `dist/templates/common/bundled-skills/cstl-skill-creator/`. Not a slash command. Skip typo/link-only. Does **not** apply to Cursor product skills (`~/.cursor/skills-cursor/`). | no | yes |
+| `smart-search-cli` | `bundled-skills/smart-search-cli/SKILL.md` | **`python ./.cstl/scripts/run_smart_search.py "<question>" --intent deep-research --json`** (shipped script); Cursor web tools are downgrade-only fallback | no | yes |
+| `cstl-handoff` | `bundled-skills/cstl-handoff/SKILL.md` | **Slash `/cstl-handoff`** (writes session handoff to OS temp dir) | **yes** | n/a (user command) |
+| `cstl-continue` / `cstl-finish-work` / `cstl-start` | `common/commands/*.md` | **Slash `/cstl-continue`, `/cstl-finish-work`** (`cstl-start` filtered on agent-capable platforms) | **yes** | n/a (user commands) |
+| `cstl-research` / `cstl-implement` / `cstl-check` (agents) | `packages/cli/src/templates/cursor/agents/*.md` | **`.cursor/agents/*.md`** — Agent (Task tool), dispatched via `generate_dispatch_prompt.py` (CLI Layer 2) | no | n/a (agent types) |
+
+## Reading this matrix
+
+- **Reachable on-demand** (green path): brainstorm → guide; check → agent; smart-search → script; micro-grill → embedded contract; **skill authoring → Read `cstl-skill-creator/SKILL.md` + `review-checklist.md`** (paths in the matrix row).
+- **Body in npm package only**: the skill is real and shipped, but a pure Cursor project has no project-relative copy. The workflow routes its **behavior** directly; the full body is discoverable under the installed package (`npm root -g` → `dist/templates/…`). Do not claim these are loaded without reading the actual body when the behavior matters.
+- **Maintainer-only** (`cstl-meta`, `cstl-spec-bootstrap`): named in AGENTS for framework completeness; not part of the consumer execution path. No extra consumer load path beyond the package body.
+- **Authoring-time mandatory** (`cstl-skill-creator`): not a consumer runtime path and not a slash command, but **must** be Read before creating or structurally changing Trellis / blaze-skills / harness skills. Cursor product skills are out of scope.
+
+## Honesty rule
+
+If a skill is named in AGENTS.md, it must be reachable here. If a row ever becomes unreachable, either add a project-relative carrier (guide/script/agent) or remove the name from AGENTS.md. Never claim "skill loaded" without a file read.
+
+## Related
+
+- [prd-grill-frontier.md](./prd-grill-frontier.md) — P11: brainstorm/grill on-demand path.
+- [dogfood-only-surfaces.md](./dogfood-only-surfaces.md) — what ships only in the maintainer harness (goal_*.py, `.claude/skills`, local overlays).
+- AGENTS.md `Invocation map (short)` + `Internal skill reachability` sections.
+- `./cursor-context-injection-guide.md` — which channels actually reach the Cursor model.

package/dist/templates/markdown/framework/middleware-protocol.md.txt

@@ -0,0 +1,83 @@
+# Middleware Protocol v1
+
+> 一种中间件。官方与用户同一契约，只靠 `source` 区分。字段名英文；正文跟 `artifact_locale`（当前 zh）。
+>
+> Overlay（已拍）：项目 **`.cstl/middleware/`**。默认可进 git。`cstl init` / `cstl update` **永不写入、不删除、不纳入 `.template-hashes.json`**。Cursor++ 残渣清理是另一条 allow-list，不得误删本目录。
+
+Capability router 只声明 `exact` / `semantic` / `structural` / `external`，不绑 Agent 工具名。
+
+## 双轨
+
+| 轨 | CSTL 管什么 |
+| --- | --- |
+| 集成 | 本协议：Manifest + Profile + 健康 |
+| Extra | 只在宿主里配 Agent / MCP，不写成中间件 → CSTL 不管 |
+
+## 义务
+
+1. **一种 ABI。** `source: shipped | user` 不是两套协议。
+2. **Update 不顶掉。** 用户 overlay 不进模板 hash / 官方 refresh 写集。同 id：用户赢，并报告。
+3. **Secret。** Manifest 只许引用（环境变量名 / 平台 Secret），不许写密钥原文。日志与 Artifact 同样禁止。
+4. **权限。** 新权限首次启用走一次 Resolution Approval。后续 `update` 不得扩大已批权限；要扩大再批一次。
+5. **校验。** 缺必填字段则拒绝接入并说明，不得半接入。
+6. **Hook。** 只订 Event Bridge 已有事件。未订阅模块不得让 hook 失败。
+7. **协议版本。** Manifest 可带 `protocol: 1`。不兼容升级必须在应用前被发现。
+
+本条不实现安装器、不做商店、不改全局 MCP。可选日后加 `cstl middleware add`，非发布阻塞。
+
+## 生命周期
+
+添加（放入 overlay 的 Manifest）→ 启用/停用（Profile `required` / `optional` / `unset`）→ 移除（用户删 overlay，CSTL 忘记）。
+
+停用 ≠ 删除文件。官方 shipped 可被用户停用，不得被 `update` 强行再打开。`update` 可刷新 shipped 声明，但不得删用户 overlay，也不得在用户停用后自动重装实现。
+
+同一 capability 多个 Provider：Profile 选一个 active；其余 standby。不得静默抢当前 active。
+
+## 传输类
+
+`transport` 取其一：`skill+cli` | `mcp` | `skill` | `hook`。宿主里额外配置的，CSTL 不管。
+
+## 发现与健康
+
+发现方式：在 `.cstl/middleware/` 放 Manifest。缺必填字段则拒绝接入。
+
+Status / Continue 在任务需要该 capability 时展示 `ready` / `missing` / `failed` / `degraded`。不把 Extra 轨的 MCP 列进健康表。
+
+## 第一波 shipped（不挡用户自添）
+
+| Provider | Profile | 说明 |
+| --- | --- | --- |
+| smart-search | required `external-knowledge` | 独立包；缺失则 degrade |
+| codegraph / fast-context | optional | 默认不装 |
+| cstl-byok | 协议里占可选位 | **实现与发版延后**；本批发协议，不带 BYOK 安装 |
+| Playwright / GitHub | 默认不集成 | — |
+
+## Manifest 样例
+
+```yaml
+id: smart-search
+protocol: 1
+capability: external-knowledge
+source: shipped          # shipped | user
+ownership:
+  kind: external-package
+  name: smart-search
+transport: skill+cli     # skill+cli | mcp | skill | hook
+profile: required        # required | optional | unset
+readiness:
+  probe: cli
+  command_hint: smart-search doctor
+on_missing: degrade      # degrade | block-if-required
+permissions:
+  network: true
+  shell: true
+  secrets: true
+secret_refs: []          # 只写引用名，不写值
+update_policy: preserve-user-overlay
+```
+
+## 相关
+
+- [upgrade.md](./upgrade.md) — 终端用户升级半页
+- [release-boundary.md](./release-boundary.md) — CSTL 本批 vs cstl-byok
+- `.cstl/workflow.md` — 并行第一原则（约定，不是 CLI gate）