@blxzer/cursor-trellis 0.2.9 → 0.3.2

package/CHANGELOG.md

@@ -9,6 +9,100 @@ SemVer: [semver.org](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [Unreleased]
+
+## [0.3.2] - 2026-07-04
+
+> **0.3.1 was withdrawn** shortly after publish: the initial `npm publish` did not rewrite the `workspace:*` dependency on `@blxzer/cursor-trellis-core` (and core@0.3.1 was not published alongside), so 0.3.1 was uninstallable (`EUNSUPPORTEDPROTOCOL`). 0.3.2 reissues the same content via the proper `pnpm publish` orchestration (`publish-packages.js` publishes core first, then cli, rewriting `workspace:*` to the resolved version).
+
+**Breaking (coexistence)**: cursor-trellis runtime directory moves from `.trellis/` to **`.cstl/`** so upstream [mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis) can keep `.trellis/` in the same repository while Cursor uses `cstl`.
+
+### Breaking
+
+- **feat(runtime)**: project runtime root `.trellis/` → **`.cstl/`** (`rename-dir` via `cstl update --migrate`; history preserved).
+- **feat(agents)**: AGENTS.md managed block uses `<!-- CSTL:START -->` / `<!-- CSTL:END -->` (legacy `TRELLIS:START` upgraded on migrate).
+- **chore(channel)**: `cstl channel` multi-agent CLI is **not registered** (Cursor-only product; upstream channel runtime out of scope).
+- **chore(config)**: removed default `channel.worker_guard` from `config.yaml` template.
+
+### Added
+
+- **feat(init) coexistence mode**: when `cstl init` detects an upstream `.trellis/` (and no `.cstl/`), it creates `.cstl/` alongside, **takes over `.cursor/`** (force-writes cstl hooks/rules/commands even under `-y`), leaves `.trellis/` and other upstream platform dirs untouched, and adds a `<!-- CSTL:START -->` block to AGENTS.md **alongside** an existing `<!-- TRELLIS:START -->` block (dual-block). Prints a guidance banner warning not to run `cstl update --migrate` in coexistence repos.
+- **feat(update) conservative migrate gate**: `cstl update --migrate` refuses the `.trellis/` → `.cstl/` rename unless a positive cursor-trellis fingerprint is present (`cstl-*` command, `cstl-triage.mdc`, or cstl-flavored `cli_adapter.py`). Mixed cursor-trellis + upstream Trellis layouts abort for manual split. New **`--force-cstl-migrate`** escape hatch overrides upstream-signal aborts (still gated on `.trellis/` existing and `.cstl/` absent).
+
+### Migration
+
+```bash
+npm install -g @blxzer/cursor-trellis@0.3.1
+cd /path/to/project
+cstl update --migrate
+```
+
+## [0.3.1] — withdrawn (2026-07-04)
+
+Withdrawn due to an npm publish defect (unresolvable `workspace:*` dep on `@blxzer/cursor-trellis-core` + missing core@0.3.1). Reissued as **0.3.2** with identical content. See [0.3.2] above.
+
+## [0.3.0] - 2026-07-02
+
+**Breaking**: rename CLI command from `trellis`/`tl` to `cstl`. The `trellis` and `tl` bin aliases are **removed**. All skill, command, agent, and rule name prefixes renamed `trellis-*` → `cstl-*` (hard cut, no compatibility aliases).
+
+### Breaking
+
+- **feat(cli)**: rename CLI command from `trellis`/`tl` to `cstl`. Update any aliases, CI scripts, or shell history that reference `trellis` or `tl`.
+- **feat(templates)**: all skill, command, agent, and rule names renamed `trellis-*` → `cstl-*` (hard cut, no compatibility aliases):
+  - `.cursor/commands/trellis-continue.md` → `cstl-continue.md`
+  - `.cursor/commands/trellis-finish-work.md` → `cstl-finish-work.md`
+  - `.cursor/commands/trellis-cursor2plus-setup.md` → `cstl-cursor2plus-setup.md`
+  - `.cursor/rules/trellis-triage.mdc` → `cstl-triage.mdc`
+  - `.cursor/rules/trellis-subagent-dispatch.mdc` → `cstl-subagent-dispatch.mdc`
+  - `.cursor/agents/trellis-research.md` → `cstl-research.md`
+  - `.cursor/agents/trellis-implement.md` → `cstl-implement.md`
+  - `.cursor/agents/trellis-check.md` → `cstl-check.md`
+  - `.cursor/skills/trellis-meta/` → `cstl-meta/` (and 4 other bundled skill dirs)
+- **fix(hooks)**: `<!-- trellis-hook-injected -->` marker → `<!-- cstl-hook-injected -->`
+- **fix(subagents)**: `subagent_type` identifiers `trellis-research/implement/check` → `cstl-research/implement/check` (affects Cursor++ BYOK `trellis-task-models.json5` keys)
+
+### Added
+
+- **feat(cli)**: `cstl capability-smoke` (`--json`, `--write-status`) probes selected project capabilities and can persist `ready` / `failed` in `.trellis/capabilities.json` without losing status on later template refreshes.
+- Migration manifest `src/migrations/manifests/0.3.0.json` (13 rename entries for `trellis-*` → `cstl-*` under `.cursor/`).
+
+### Changed
+
+- `AUTO_PLANNING_REVIEWER` identifier `"trellis-cli"` → `"cstl-cli"`
+- `<!-- trellis-research-end-pack -->` marker → `<!-- cstl-research-end-pack -->`
+- `CURSOR_SKILL_RESIDUE_DIRS` in `update.ts` now checks both `cstl-*` (current) and `trellis-*` (legacy) skill directories for residue detection
+- **feat(init/capabilities)**: selected capabilities default to `pending` in `capabilities.json` (schema v3); bootstrap/join PRDs prompt capability verification.
+- **docs(spec)**: mirror Native OC-06/OC-15 live evidence into spec templates (`cursor-subagent-policy`, `cursor-semantic-compliance`).
+- **docs(migration)**: README / CHANGELOG closed-loop for `npm install -g` + `cstl update --migrate`; remove stale `tl` bin alias from user docs.
+- **docs(cursor)**: Native + BYOK **coexistence** (per-repo `--cursor2plus`, not either/or); Method 2.5 ops — run `--check-compat` after Cursor/Cursor++ upgrades (`cstl update` prints BYOK reminder when `cursor2plus/` exists).
+- **fix(tasks)**: Parent `record-gate` / archive share the same `implement.md` contract fingerprint (fixes `stale contract fingerprint` on `parent-integrated`).
+
+### Migration
+
+**Manual npm install required** — the old `trellis upgrade` command no longer exists after install.
+
+```bash
+npm install -g @blxzer/cursor-trellis@latest
+cstl update --migrate
+```
+
+The `--migrate` flag is REQUIRED to trigger the file renames in your project (`trellis-*` → `cstl-*`). Renames are hash-verified; locally modified files are preserved with a warning.
+
+New migration manifest `src/migrations/manifests/0.3.0.json` ships 13 rename entries (3 commands, 2 rules, 3 agents, 5 skill directories). See **Added** above.
+
+If you use Cursor++ BYOK (`.trellis/local/cursor2plus/`), the `trellis-task-models.json5` keys must be updated from `trellis-research/implement/check` to `cstl-research/implement/check`. Run the `cstl-cursor2plus-setup` skill or edit `~/.ccursor/trellis-task-models.json5` manually then re-run `patch_wpelc8.py --apply`.
+
+The `.trellis/` directory name is UNCHANGED — only the CLI command and skill/command/agent/rule name prefixes changed.
+
+### Notes
+
+- npm package name `@blxzer/cursor-trellis` is unchanged.
+- `trellis-task-models.json5` filename is unchanged (user data file).
+- `trellis_task_models_config.py` module name is unchanged.
+- `<!-- TRELLIS:START -->` / `<!-- TRELLIS:END -->` managed block markers are unchanged.
+
+[0.3.0]: https://github.com/blxzer77/cursor-trellis/releases/tag/v0.3.0
+
 ## [0.2.9] - 2026-06-26
 
 Adapt `@blxzer/cursor-trellis` to **@blxzer/smart-search 0.1.15** (research locale scope, dry-run/progress, structured citations, provider TTL cache). Cursor **commands-only** policy unchanged — internal `smart-search-cli` is not exposed under `.cursor/skills/`.

package/README.md

@@ -1,6 +1,9 @@
 # cursor-trellis
 
 <p>
+  <a href="https://github.com/blxzer77/cursor-trellis/actions/workflows/ci.yml">
+    <img src="https://github.com/blxzer77/cursor-trellis/actions/workflows/ci.yml/badge.svg" alt="CI">
+  </a>
   <a href="https://www.npmjs.com/package/@blxzer/cursor-trellis">
     <img src="https://img.shields.io/npm/v/@blxzer/cursor-trellis?label=npm%20latest" alt="npm latest">
   </a>
@@ -11,46 +14,104 @@
 
 English | [简体中文](README.zh-CN.md)
 
-**Trellis** is a progressive context management system for AI coding agents. It structures agent instructions as `.trellis/` (workflow, specs, tasks, workspace) instead of a single large file, and generates platform-specific integration files (`.cursor/` for Cursor).
+**Trellis** is a progressive context management system for AI coding agents. It structures agent instructions as `.cstl/` (workflow, specs, tasks, workspace) instead of a single large file, and generates platform-specific integration files (`.cursor/` for Cursor).
 
 Based on the [Trellis framework by mindfold-ai](https://github.com/mindfold-ai/Trellis), this version is adapted for Cursor with rules, commands, agents, and hooks.
 
+## Why `cstl` and `.cstl/`?
+
+To avoid clashing with upstream [mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis) in the same repo or on the same machine:
+
+- **CLI command `cstl`** (since v0.3.0) — replaces the `trellis` / `tl` bins so you can install and run cursor-trellis alongside upstream Trellis tooling.
+- **Runtime directory `.cstl/`** (since v0.3.1) — holds workflow, spec, tasks, and scripts. Upstream Trellis keeps **`.trellis/`**; both trees can coexist in one repository without overwriting each other.
+
+Fresh installs use `.cstl/` directly. Projects on 0.3.0 run `cstl update --migrate` to rename `.trellis/` → `.cstl/` (history preserved).
+
 ## What it does
 
-- Task artifacts (PRD, design, implementation plan) persist in `.trellis/tasks/`
-- Resume work across chat sessions with `/trellis-continue`
+- Task artifacts (PRD, design, implementation plan) persist in `.cstl/tasks/`
+- Resume work across chat sessions with `/cstl-continue`
 - Load specs progressively based on files being edited
 - Route requests through structured workflow: triage → plan → gate → execute → verify
-- **Validated gates** — `trellis validate-rules` + `pnpm mirror-check` enforce dogfood/template sync; `init`/`update` throw on regression
+- **Validated gates** — `cstl validate-rules` + `pnpm mirror-check` enforce dogfood/template sync; `init`/`update` throw on regression
 - **Retrieval compliance** — BYOK/Native split with conservative `unknown` routing; LSP overpromises softened to codegraph + Read; telemetry separates planned vs executed semantic
 - **Cursor++ safety** — Method 2.5 patch requires explicit `--approve`; `--check-compat` pre-flight; `smoke.py` health check (no secrets)
 - **Evidence pack** — finish/check cite `retrieval-pack-latest.json` when present; research prompts include provider relevance caveats
 
+## Quick demo (~5 min)
+
+Try Trellis on an empty app directory without touching this source tree:
+
+```bash
+npm install -g @blxzer/cursor-trellis
+cd examples/minimal-agent-app
+./demo.sh          # or demo.ps1 on Windows
+```
+
+The script runs `cstl init --cursor -y` → `cstl validate-rules` → lists `.cstl/` and `.cursor/`. Details: [examples/minimal-agent-app/README.md](examples/minimal-agent-app/README.md). Agent tooling narrative (CLI / MCP / Hook / Rule): [docs/agent-tooling-narrative.zh-CN.md](docs/agent-tooling-narrative.zh-CN.md).
+
 ## Quick start (Cursor)
 
 **1. Install the CLI** (global or project-local):
 
 ```bash
 npm install -g @blxzer/cursor-trellis
-trellis --version
+cstl --version
 ```
 
 **2. Initialize your application repo** (not the Trellis source tree):
 
 ```bash
 cd /path/to/your-app
-trellis init --cursor
+cstl init --cursor
 ```
 
-**3. Open the project in Cursor** and use Agent mode. User-facing slash commands include `/trellis-continue` and `/trellis-finish-work`. Request Triage is enforced via `.cursor/rules/trellis-triage.mdc`.
+**3. Open the project in Cursor** and use Agent mode. User-facing slash commands include `/cstl-continue` and `/cstl-finish-work`. Request Triage is enforced via `.cursor/rules/cstl-triage.mdc`.
+
+Optional: `cstl init --cursor --cursor2plus` materializes a **per-repo** Cursor++ BYOK bundle (not a global either/or choice). Native and BYOK can coexist across projects on one machine — see [Native and BYOK coexistence](docs/cursor.md#native-and-byok-coexistence-not-eitheror).
 
-Optional: `trellis init --cursor --cursor2plus` for Cursor++ BYOK local bundle; see [docs/cursor.md](docs/cursor.md#cursor-optional-appendix).
+## Upgrade from 0.3.0 (v0.3.1)
+
+v0.3.1 moves the cursor-trellis **runtime directory** from `.trellis/` to **`.cstl/`** so upstream [mindfold-ai/Trellis](https://github.com/mindfold-ai/Trellis) can keep `.trellis/` in the same repository. AGENTS.md managed blocks use `<!-- CSTL:START -->` markers.
+
+```bash
+npm install -g @blxzer/cursor-trellis@latest
+cd /path/to/your-app
+cstl update --migrate
+```
+
+`--migrate` is **required** — history is preserved via directory rename, not delete-recreate. Script paths become `python ./.cstl/scripts/...`.
+
+## Upgrade from 0.2.x (v0.3.0)
+
+v0.3.0 is a **breaking rename**. The CLI is **`cstl` only** — the `trellis` and `tl` bin aliases are removed.
+
+| Changed | Unchanged |
+| --- | --- |
+| CLI: `trellis` / `tl` → `cstl` | (0.3.1+) runtime dir is `.cstl/` |
+| Skills, commands, agents, rules: `trellis-*` → `cstl-*` | `trellis-task-models.json5` filename |
+
+**Migration steps** (run in each project):
+
+```bash
+npm install -g @blxzer/cursor-trellis@latest
+cd /path/to/your-app
+cstl update --migrate
+```
+
+`--migrate` is **required** for the `trellis-*` → `cstl-*` renames under `.cursor/`. Renames are hash-verified; locally modified files are preserved with a warning — manually rename or re-apply customizations to the new `cstl-*` paths.
+
+After 0.3.0, routine CLI bumps can use `cstl upgrade`. The old `trellis upgrade` command no longer exists once you are on 0.3.0.
+
+**Cursor++ BYOK** (optional, `.cstl/local/cursor2plus/` only): update `trellis-task-models.json5` keys from `trellis-research/implement/check` to `cstl-research/implement/check`, then re-run `patch_wpelc8.py --apply`. Use `/cstl-cursor2plus-setup` in Agent mode.
+
+Details: [CHANGELOG](packages/cli/CHANGELOG.md#030---2026-07-01).
 
 ## After init: what appears
 
 ```text
 your-app/
-  .trellis/          workflow, spec, tasks, workspace, scripts
+  .cstl/          workflow, spec, tasks, workspace, scripts
   AGENTS.md          Trellis-managed agent entry
   .cursor/           commands, rules, agents, hooks (Cursor)
 ```
@@ -61,10 +122,10 @@ Details: [Cursor integration](docs/cursor.md).
 
 | Path | Role |
 | --- | --- |
-| `.trellis/workflow.md` | Lifecycle: triage, plan, execute, finish, learning |
-| `.trellis/spec/` | Layer/package coding guidelines |
-| `.trellis/tasks/` | PRD, design, implement, verify artifacts |
-| `.trellis/workspace/` | Developer journals and session traces |
+| `.cstl/workflow.md` | Lifecycle: triage, plan, execute, finish, learning |
+| `.cstl/spec/` | Layer/package coding guidelines |
+| `.cstl/tasks/` | PRD, design, implement, verify artifacts |
+| `.cstl/workspace/` | Developer journals and session traces |
 
 ## Workflow (summary)
 
@@ -72,7 +133,7 @@ Details: [Cursor integration](docs/cursor.md).
 2. **Plan** with task artifacts for durable work (especially Full Tasks).
 3. **Gate**: `task.py validate` + `start-execution --check`.
 4. **Approve** execution explicitly, then `start-execution --approved`.
-5. **Verify** and finish (`/trellis-finish-work`).
+5. **Verify** and finish (`/cstl-finish-work`).
 
 Walkthrough: [workflow.md](docs/workflow.md) — Triage decision tree, Task Ladder, upgrade/downgrade rules, Parent/Child task trees, Phase 1–3 lifecycle.
 
@@ -80,7 +141,7 @@ Walkthrough: [workflow.md](docs/workflow.md) — Triage decision tree, Task Ladd
 
 - **Rules** — reliable always-on policy (including Triage and retrieval routing).
 - **Commands** — small `/` palette (`commands-only` policy; skills not copied to `.cursor/skills/` by default).
-- **Agents** — `trellis-research`, `trellis-implement`, `trellis-check`.
+- **Agents** — `cstl-research`, `cstl-implement`, `cstl-check`.
 - **Hooks** — Python scripts for session, shell, and subagent context.
 
 Deep dive: [docs/cursor.md](docs/cursor.md) — Native vs Cursor++ BYOK environments, subagent dispatch Methods 1–4, environment detection. Retrieval layer design: [docs/retrieval.md](docs/retrieval.md).
@@ -118,9 +179,9 @@ The workflow routes external fact queries to smart-search when available. See th
 
 | Command | Purpose |
 | --- | --- |
-| `trellis init --cursor` | Create `.trellis/` + `.cursor/` in the current project |
-| `trellis update` | Refresh templates from the installed CLI version |
-| `trellis uninstall` | Remove Trellis-managed files from the project |
+| `cstl init --cursor` | Create `.cstl/` + `.cursor/` in the current project |
+| `cstl update` | Refresh templates from the installed CLI version |
+| `cstl uninstall` | Remove Trellis-managed files from the project |
 
 Full CLI reference: [packages/cli/README.md](packages/cli/README.md).
 
@@ -128,7 +189,7 @@ Full CLI reference: [packages/cli/README.md](packages/cli/README.md).
 
 | | |
 | --- | --- |
-| **npm CLI** | `@blxzer/cursor-trellis` (`trellis`, `tl`) |
+| **npm CLI** | `@blxzer/cursor-trellis` (`cstl`) |
 | **Core SDK** | `@blxzer/cursor-trellis-core` |
 | **smart-search** | `@blxzer/smart-search` (auto-installed dependency) |
 | **Repository** | https://github.com/blxzer77/cursor-trellis |
@@ -142,8 +203,11 @@ Contributors working on **this** repository:
 pnpm install
 pnpm build
 pnpm test
+pnpm mirror-check   # dogfood .cursor vs templates (contributors)
 ```
 
+CI runs the same pipeline on push/PR (see badge above).
+
 Package-level detail: [packages/cli/README.md](packages/cli/README.md). Agent-oriented codebase guide: [AGENTS.md](AGENTS.md).
 
 ## Maintainer note
@@ -161,6 +225,8 @@ Local harness layout (`D:\MyHarness`), Git remote policy, release/publish, and d
 | [docs/architecture.md](docs/architecture.md) | High-level structure + smart-search |
 | [docs/skills.md](docs/skills.md) | Internal skills reference |
 | [docs/subagents.md](docs/subagents.md) | Subagent dispatch design |
+| [docs/agent-tooling-narrative.zh-CN.md](docs/agent-tooling-narrative.zh-CN.md) | CLI / MCP / Hook / Rule layering (ZH) |
+| [examples/minimal-agent-app/](examples/minimal-agent-app/) | 5-minute init demo |
 | [docs/spec-system.md](docs/spec-system.md) | Progressive spec system |
 | [docs/task-system.md](docs/task-system.md) | Task artifacts, gates, Parent/Child |
 | [packages/cli/README.md](packages/cli/README.md) | CLI / npm reference |

package/README.zh-CN.md

@@ -4,6 +4,8 @@
 
 Trellis CLI 的 npm 包。项目总览：[../../README.zh-CN.md](../../README.zh-CN.md)。Cursor 工作流：[../../docs/workflow.zh-CN.md](../../docs/workflow.zh-CN.md)。
 
+**为何 `cstl` 与 `.cstl/`？** CLI 为 `cstl`（非 `trellis`），运行时目录为 `.cstl/`（非 `.trellis/`），以便与上游 Trellis 在同一仓库共存。详见[仓库 README](../../README.zh-CN.md#为何使用-cstl-与-cstl)。
+
 ## 安装
 
 ```bash
@@ -12,15 +14,52 @@ npm install -g @blxzer/cursor-trellis
 
 需要 **Node.js ≥ 18.17**。生成项目的钩子在运行 Cursor 的机器上需要 **Python ≥ 3.9**。
 
+## 从 0.3.0 升级（v0.3.1）
+
+v0.3.1 将 cursor-trellis **运行时目录**从 `.trellis/` 迁至 **`.cstl/`**。
+
+```bash
+npm install -g @blxzer/cursor-trellis@latest
+cd /path/to/your-app
+cstl update --migrate
+```
+
+`--migrate` **必须**带上；历史通过目录 rename 保留。脚本路径为 `python ./.cstl/scripts/...`。
+
+## 从 0.2.x 升级（v0.3.0）
+
+v0.3.0 为**硬切更名**：CLI 仅保留 **`cstl`**，`trellis` 与 `tl` 两个 bin 别名已移除。
+
+| 变了 | 没变 |
+| --- | --- |
+| CLI：`trellis` / `tl` → `cstl` | （0.3.1+）运行时目录为 `.cstl/` |
+| skill / command / agent / rule：`trellis-*` → `cstl-*` | `trellis-task-models.json5` 文件名 |
+
+**迁移步骤**（每个项目执行一次）：
+
+```bash
+npm install -g @blxzer/cursor-trellis@latest
+cd /path/to/your-app
+cstl update --migrate
+```
+
+`--migrate` **必须**带上，才会重命名 `.cursor/` 下的 `trellis-*` → `cstl-*`。重命名经哈希校验；若你本地改过文件，会保留旧路径并警告——请手动改名或把自定义内容迁到新的 `cstl-*` 路径。
+
+0.3.0 之后日常 CLI 小版本可用 `cstl upgrade`。升级到 0.3.0 后，旧的 `trellis upgrade` 命令已不存在。
+
+**Cursor++ BYOK**（可选，仅 `.cstl/local/cursor2plus/`）：将 `trellis-task-models.json5` 中的 `trellis-research/implement/check` 键改为 `cstl-research/implement/check`，然后重跑 `patch_wpelc8.py --apply`。可在 Agent 模式使用 `/cstl-cursor2plus-setup`。
+
+详见 [CHANGELOG](./CHANGELOG.md#030---2026-07-01)。
+
 ## 可执行文件
 
-| Bin | 别名 | 作用 |
-| --- | --- | --- |
-| `trellis` | `tl` | 在项目中初始化、更新、管理 Trellis |
-| `smart-search` | — | 随包分发的网页检索 CLI（见 [smart-search](#smart-search)） |
+| Bin | 作用 |
+| --- | --- |
+| `cstl` | 在项目中初始化、更新、管理 Trellis |
+| `smart-search` | 随包分发的网页检索 CLI（见 [smart-search](#smart-search)） |
 
 ```bash
-trellis --version
+cstl --version
 smart-search --version
 ```
 
@@ -28,25 +67,25 @@ smart-search --version
 
 | 命令 | 用途 |
 | --- | --- |
-| `init` | 创建 `.trellis/` 与所选平台目录 |
+| `init` | 创建 `.cstl/` 与所选平台目录 |
 | `update` | 将模板同步到当前安装的 CLI 版本 |
 | `uninstall` | 从项目中移除 Trellis 管理文件 |
 | `upgrade` | 升级全局 CLI npm 包 |
 | `rollout` | 对多个项目路径批量 `update` |
 | `workflow` | 工作流模板工具（进阶） |
 
-与 **channel** 相关的命令服务于进阶多 Agent 工作流，不属于 Cursor-first 公开文档范围。完整列表：`trellis --help`。
+与 **channel** 相关的命令服务于进阶多 Agent 工作流，不属于 Cursor-first 公开文档范围。完整列表：`cstl --help`。
 
 下文详述 **`init`**、**`update`**、**`uninstall`**。
 
 ---
 
-## `trellis init`
+## `cstl init`
 
 在**目标项目根目录**执行：
 
 ```bash
-trellis init --cursor
+cstl init --cursor
 ```
 
 ### 平台标志
@@ -69,26 +108,26 @@ trellis init --cursor
 | `-u, --user <name>` | 开发者身份 |
 | `--skip-readiness` | 跳过 smart-search / 能力项 readiness |
 | `--capability <id>` | 启用可选能力（可重复；`all` 表示全部可选） |
-| `--workflow <id>` | `.trellis/workflow.md` 工作流模板 |
+| `--workflow <id>` | `.cstl/workflow.md` 工作流模板 |
 | `-t, --template <name>` | 远程 spec 模板 |
 | `-r, --registry <source>` | 自定义模板 registry |
 | `--monorepo` / `--no-monorepo` | monorepo 检测覆盖 |
 
 ### 生成内容
 
-- `.trellis/` — workflow、spec、tasks、workspace、scripts、模板哈希
+- `.cstl/` — workflow、spec、tasks、workspace、scripts、模板哈希
 - `AGENTS.md` — 受管说明块
 - 平台目录 — Cursor 下为 `.cursor/commands`、`rules`、`agents`、`hooks`、`hooks.json`、`worktrees.json`
 
 ---
 
-## `trellis update`
+## `cstl update`
 
-在已有 `.trellis/` 的项目根目录：
+在已有 `.cstl/` 的项目根目录：
 
 ```bash
-trellis update
-trellis update --dry-run
+cstl update
+cstl update --dry-run
 ```
 
 ### 标志
@@ -105,16 +144,16 @@ trellis update --dry-run
 | `--json` | 单行 JSON rollout 证据 |
 | `--skip-post-update-smoke` | 跳过应用后 Python 冒烟脚本 |
 
-常见流程：升级全局 CLI → 进入项目 → `trellis update` → 若自定义过 workflow/rules 请审阅 diff。
+常见流程：升级全局 CLI → 进入项目 → `cstl update`（从 0.2.x 首次升到 0.3.0 须加 `--migrate`）→ 若自定义过 workflow/rules 请审阅 diff。
 
 ---
 
-## `trellis uninstall`
+## `cstl uninstall`
 
 ```bash
-trellis uninstall
-trellis uninstall --dry-run
-trellis uninstall -y
+cstl uninstall
+cstl uninstall --dry-run
+cstl uninstall -y
 ```
 
 ### 标志
@@ -124,7 +163,7 @@ trellis uninstall -y
 | `-y, --yes` | 跳过确认 |
 | `--dry-run` | 仅列出将删除/_scrub_ 的内容 |
 
-按哈希清单与结构化 scrubber 移除受管平台文件及 `.trellis/`。卸载前请**备份**自定义 workflow 或 rules。
+按哈希清单与结构化 scrubber 移除受管平台文件及 `.cstl/`。卸载前请**备份**自定义 workflow 或 rules。
 
 ---
 

package/bin/smart-search.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { spawn } from "node:child_process";
 import { dirname, join } from "node:path";

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAIhE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAIhE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/cli/index.js

@@ -1,16 +1,16 @@
 import fs from "node:fs";
-import path from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
+import { ensureCapabilitiesFileExists, runCapabilitySmokeCommand, } from "../commands/capability-smoke.js";
 import { init } from "../commands/init.js";
 import { update } from "../commands/update.js";
 import { rollout } from "../commands/rollout.js";
 import { upgrade } from "../commands/upgrade.js";
 import { uninstall } from "../commands/uninstall.js";
 import { runWorkflowCommand, WorkflowCommandError, } from "../commands/workflow.js";
-import { registerChannelCommand } from "../commands/channel/index.js";
+// import { registerChannelCommand } from "../commands/channel/index.js";
 import { runValidateRules } from "../commands/validate-rules.js";
-import { DIR_NAMES } from "../constants/paths.js";
+import { isWorkflowInitialized, workflowPath } from "../utils/workflow-dir.js";
 import { PACKAGE_NAME, VERSION } from "../constants/version.js";
 import { compareVersions } from "../utils/compare-versions.js";
 // Re-export for backwards compatibility (consumers should prefer constants/version.js)
@@ -19,8 +19,8 @@ export { VERSION, PACKAGE_NAME };
  * Check if a Trellis update is available (compare project version with CLI version)
  */
 function checkForUpdates(cwd) {
-    const versionFile = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
-    if (!fs.existsSync(versionFile))
+    const versionFile = workflowPath(cwd, ".version");
+    if (!versionFile || !fs.existsSync(versionFile))
         return;
     const projectVersion = fs.readFileSync(versionFile, "utf-8").trim();
     const cliVersion = VERSION;
@@ -28,17 +28,17 @@ function checkForUpdates(cwd) {
     if (comparison > 0) {
         // CLI is newer than project - update available
         console.log(chalk.yellow(`\n⚠️  Trellis update available: ${projectVersion} → ${cliVersion}`));
-        console.log(chalk.gray(`   Run: trellis update\n`));
+        console.log(chalk.gray(`   Run: cstl update\n`));
     }
     else if (comparison < 0) {
         // CLI is older than project - CLI needs updating
         console.log(chalk.yellow(`\n⚠️  Your CLI (${cliVersion}) is older than project (${projectVersion})`));
-        console.log(chalk.gray(`   Run: trellis upgrade\n`));
+        console.log(chalk.gray(`   Run: cstl upgrade\n`));
     }
 }
-// Check for updates at CLI startup (only if .trellis exists)
+// Check for updates at CLI startup when a workflow dir exists
 const cwd = process.cwd();
-if (fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW))) {
+if (isWorkflowInitialized(cwd)) {
     checkForUpdates(cwd);
 }
 const program = new Command();
@@ -46,7 +46,7 @@ function collectOption(value, previous) {
     return [...previous, value];
 }
 program
-    .name("trellis")
+    .name("cstl")
     .description("AI-assisted development workflow framework for Cursor")
     .version(VERSION, "-v, --version", "output the version number");
 program
@@ -54,7 +54,7 @@ program
     .description("Initialize trellis in the current project")
     .option("--cursor", "Include Cursor commands")
     .option("-y, --yes", "Skip prompts and use defaults")
-    .option("--cursor2plus", "Materialize Cursor++ BYOK local bundle (.trellis/local/cursor2plus/); ignored unless --cursor is also selected")
+    .option("--cursor2plus", "Materialize Cursor++ BYOK local bundle (.cstl/local/cursor2plus/); ignored unless --cursor is also selected")
     .option("-u, --user <name>", "Initialize developer identity with specified name")
     .option("-f, --force", "Overwrite existing files without asking")
     .option("-s, --skip-existing", "Skip existing files without asking")
@@ -66,7 +66,7 @@ program
     .option("--overwrite", "Overwrite existing spec directory when using template")
     .option("--append", "Only add missing files when using template")
     .option("-r, --registry <source>", "Use a custom template registry (e.g., gh:myorg/myrepo/specs)")
-    .option("--workflow <id>", "Workflow template id for .trellis/workflow.md (default: native; e.g., tdd, channel-driven-subagent-dispatch)")
+    .option("--workflow <id>", "Workflow template id for .cstl/workflow.md (default: native; e.g., tdd, channel-driven-subagent-dispatch)")
     .option("--workflow-source <source>", "Custom marketplace source for the --workflow lookup (e.g., gh:myorg/myrepo/marketplace)")
     .action(async (options) => {
     try {
@@ -80,6 +80,31 @@ program
         process.exit(1);
     }
 });
+program
+    .command("capability-smoke")
+    .description("Verify selected project capabilities and optionally write readiness statuses")
+    .option("--json", "Emit machine-readable capability smoke output")
+    .option("--write-status", "Write ready/failed status back to .cstl/capabilities.json and capabilities.md")
+    .action(async (options) => {
+    try {
+        ensureCapabilitiesFileExists(process.cwd());
+        const report = await runCapabilitySmokeCommand({
+            cwd: process.cwd(),
+            json: options.json,
+            writeStatus: options.writeStatus,
+        });
+        if (!report.ok) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(chalk.red("Error:"), error instanceof Error ? error.message : error);
+        if (process.env.DEBUG || process.env.TRELLIS_DEBUG) {
+            console.error(error instanceof Error ? error.stack : error);
+        }
+        process.exit(1);
+    }
+});
 program
     .command("update")
     .description("Update trellis configuration and commands to latest version")
@@ -92,6 +117,7 @@ program
     .option("--skip-readiness", "Skip Smart Search and selected capability readiness checks and report framework readiness as unverified")
     .option("--json", "Emit one-line JSON rollout evidence (dry-run or apply)")
     .option("--skip-post-update-smoke", "Skip post-apply Python script smoke checks")
+    .option("--force-cstl-migrate", "Force the .trellis/ → .cstl/ rename even when upstream Trellis signals are detected (escape hatch)")
     .action(async (options) => {
     try {
         await update({
@@ -104,6 +130,7 @@ program
             skipReadiness: options.skipReadiness,
             json: options.json,
             skipPostUpdateSmoke: options.skipPostUpdateSmoke,
+            forceCstlMigrate: options.forceCstlMigrate,
         });
     }
     catch (error) {
@@ -116,8 +143,8 @@ program
 });
 program
     .command("rollout")
-    .description("Run trellis update across multiple project paths and aggregate rollout evidence")
-    .requiredOption("-p, --project <path>", "Project root with .trellis/ (repeatable)", (val, prev) => [...(prev ?? []), val], [])
+    .description("Run cstl update across multiple project paths and aggregate rollout evidence")
+    .requiredOption("-p, --project <path>", "Project root with .cstl/ (repeatable)", (val, prev) => [...(prev ?? []), val], [])
     .option("--dry-run", "Preview updates without applying")
     .option("-f, --force", "Overwrite all changed files without asking")
     .option("-s, --skip-all", "Skip all changed files without asking")
@@ -174,7 +201,7 @@ program
 });
 program
     .command("uninstall")
-    .description("Remove all trellis files (managed platform files + .trellis/) from this project")
+    .description("Remove all trellis files (managed platform files + .cstl/) from this project")
     .option("-y, --yes", "Skip confirmation prompt")
     .option("--dry-run", "List what would be removed without changing anything")
     .action(async (options) => {
@@ -194,12 +221,12 @@ program
 });
 program
     .command("workflow")
-    .description("List or switch the project's .trellis/workflow.md template (native, tdd, channel-driven-subagent-dispatch, or marketplace)")
+    .description("List or switch the project's .cstl/workflow.md template (native, tdd, channel-driven-subagent-dispatch, or marketplace)")
     .option("-t, --template <id>", "Workflow template id (e.g., native, tdd, channel-driven-subagent-dispatch)")
     .option("-m, --marketplace <source>", "Custom marketplace source (e.g., gh:myorg/myrepo/marketplace)")
     .option("--list", "List available workflow templates and exit")
     .option("-f, --force", "Overwrite a modified workflow.md without asking")
-    .option("-n, --create-new", "Write .trellis/workflow.md.new instead of replacing the active workflow")
+    .option("-n, --create-new", "Write .cstl/workflow.md.new instead of replacing the active workflow")
     .action(async (options) => {
     try {
         await runWorkflowCommand({
@@ -222,7 +249,8 @@ program
         process.exit(1);
     }
 });
-registerChannelCommand(program);
+// Cursor-only product: multi-agent `channel` runtime is upstream Trellis scope; not registered.
+// registerChannelCommand(program);
 program
     .command("validate-rules")
     .description("Validate Cursor .cursor/rules against the expected manifest (templates and/or installed rules)")