@blxzer/cursor-trellis 0.2.9 → 0.3.2

package/dist/commands/init.js

@@ -12,7 +12,8 @@ import { AI_TOOLS } from "../types/ai-tools.js";
 import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
 import { VERSION } from "../constants/version.js";
 import { agentsMdContent } from "../templates/markdown/index.js";
-import { setWriteMode, startRecordingWrites, stopRecordingWrites, writeFile, } from "../utils/file-writer.js";
+import { setWriteMode, getWriteMode, startRecordingWrites, stopRecordingWrites, writeFile, } from "../utils/file-writer.js";
+import { insertCstlManagedBlock } from "../utils/agents-md.js";
 import { emptyTaskJson } from "../utils/task-json.js";
 import { detectProjectType, detectMonorepo, sanitizePkgName, } from "../utils/project-detector.js";
 import { initializeHashes, removeHash } from "../utils/template-hash.js";
@@ -21,7 +22,7 @@ import { isCwdHomedir, homedirGuardMessage, homedirBypassEnabled, } from "../uti
 import { fetchTemplateIndex, probeRegistryIndex, downloadTemplateById, downloadRegistryDirect, parseRegistrySource, TIMEOUTS, TEMPLATE_INDEX_URL, } from "../utils/template-fetcher.js";
 import { setupProxy, maskProxyUrl } from "../utils/proxy.js";
 import { checkProjectCapabilityReadiness, checkSmartSearchReadiness, } from "../utils/readiness.js";
-import { getProjectCapabilityChoices, parseProjectCapabilities, writeProjectCapabilityFiles, } from "../utils/project-capabilities.js";
+import { getProjectCapability, getProjectCapabilityChoices, loadProjectCapabilities, parseProjectCapabilities, writeProjectCapabilityFiles, } from "../utils/project-capabilities.js";
 import { assertCursorRulesValid } from "../utils/validate-rules.js";
 const MIN_PYTHON_MAJOR = 3;
 const MIN_PYTHON_MINOR = 9;
@@ -78,7 +79,7 @@ export function requireSupportedPython(command) {
  * Windows: `python` is the usual python.org installer choice, but Microsoft
  * Store ships `python3`, and the `py` launcher is `py -3`. We try all three
  * before giving up — fixes #236 where users with only `python3` (not
- * `python`) had `trellis init` fail outright.
+ * `python`) had `cstl init` fail outright.
  *
  * Non-Windows: `python3` is canonical; `python` is a fallback for systems
  * where Python 3 is the only Python and is named `python` (some Arch
@@ -176,10 +177,10 @@ function logPythonAdaptationNotice(command) {
 }
 function logCursor2plusSetupHint() {
     console.log("");
-    console.log(chalk.cyan("🔧 Cursor++ BYOK: 在 Cursor Agent 中运行 skill trellis-cursor2plus-setup"));
-    console.log(chalk.gray("   与大模型交互选择各 Task 角色的 primary/fallback 模型，并应用 WPeLc8 patch。"));
-    console.log(chalk.gray("   本地包: .trellis/local/cursor2plus/ · 示例: trellis-task-models.json5.example"));
-    console.log(chalk.gray("   使用官方 Cursor API（非 Cursor++）可安全忽略 `.trellis/local/cursor2plus/`。"));
+    console.log(chalk.cyan("🔧 Cursor++ BYOK: 在 Cursor Agent 中运行 skill cstl-cursor2plus-setup"));
+    console.log(chalk.gray("   与大模型交互选择各 Task 角色的 primary/fallback 模型，并应用 Method 2.5 patch（升级 Cursor/Cursor++ 后先跑 patch_wpelc8.py --check-compat）。"));
+    console.log(chalk.gray("   本地包: .cstl/local/cursor2plus/ · 示例: trellis-task-models.json5.example"));
+    console.log(chalk.gray("   使用官方 Cursor API（非 Cursor++）可安全忽略 `.cstl/local/cursor2plus/`。"));
     console.log("");
 }
 // =============================================================================
@@ -248,19 +249,50 @@ function getBootstrapChecklistItems(projectType, packages) {
         "Add code examples",
     ];
 }
+function renderCapabilityReadinessSection(selectedCapabilities) {
+    if (selectedCapabilities.length === 0) {
+        return "";
+    }
+    const checklist = selectedCapabilities
+        .map((id) => {
+        const capability = getProjectCapability(id);
+        return `- [ ] \`${capability.id}\` — ${capability.title}. Verify the generated MCP/config path is usable before claiming it in task evidence.`;
+    })
+        .join("\n");
+    return `
+## Capability readiness (required before archive)
+
+Init selected optional project capabilities for this repo. Treat them as
+\`pending\` until you verify they work in this checkout.
+
+${checklist}
+
+- Read \`.cstl/capabilities.json\` / \`.cstl/capabilities.md\` and keep the
+  readiness state honest: \`pending\`, \`ready\`, or \`failed\`.
+- For \`codebase-retrieval\`, verify \`.codegraph/\` exists (or initialize it)
+  and confirm the MCP path is usable. After the first index, CodeGraph's file
+  watcher auto-syncs later edits; you do not need to re-run full indexing for
+  every code change.
+- If a capability cannot be made ready, record the failure and fallback path in
+  \`verify.md\` before archiving bootstrap.
+- Validation entrypoint: \`cstl capability-smoke --write-status\`
+
+---
+`;
+}
 function getBootstrapRelatedFiles(projectType, packages) {
     if (packages && packages.length > 0) {
-        return packages.map((pkg) => `.trellis/spec/${sanitizePkgName(pkg.name)}/`);
+        return packages.map((pkg) => `.cstl/spec/${sanitizePkgName(pkg.name)}/`);
     }
     if (projectType === "frontend") {
-        return [".trellis/spec/frontend/"];
+        return [".cstl/spec/frontend/"];
     }
     if (projectType === "backend") {
-        return [".trellis/spec/backend/"];
+        return [".cstl/spec/backend/"];
     }
-    return [".trellis/spec/backend/", ".trellis/spec/frontend/"];
+    return [".cstl/spec/backend/", ".cstl/spec/frontend/"];
 }
-function getBootstrapPrdContent(projectType, pythonCmd, packages) {
+function getBootstrapPrdContent(projectType, pythonCmd, selectedCapabilities, packages) {
     const checklistItems = getBootstrapChecklistItems(projectType, packages);
     const checklistMarkdown = checklistItems
         .map((item) => `- [ ] ${item}`)
@@ -269,14 +301,14 @@ function getBootstrapPrdContent(projectType, pythonCmd, packages) {
 
 **You (the AI) are running this task. The developer does not read this file.**
 
-The developer just ran \`trellis init\` on this project for the first time.
-\`.trellis/\` now exists with empty spec scaffolding, and this bootstrap task
-exists under \`.trellis/tasks/\`. When they want to work on it, they should start
+The developer just ran \`cstl init\` on this project for the first time.
+\`.cstl/\` now exists with empty spec scaffolding, and this bootstrap task
+exists under \`.cstl/tasks/\`. When they want to work on it, they should start
 this task from a session that provides Trellis session identity.
 
-**Your job**: help them populate \`.trellis/spec/\` with the team's real
+**Your job**: help them populate \`.cstl/spec/\` with the team's real
 coding conventions. Every future AI session — this project's
-\`trellis-implement\` and \`trellis-check\` sub-agents — auto-loads spec files
+\`cstl-implement\` and \`cstl-check\` sub-agents — auto-loads spec files
 listed in per-task jsonl manifests. Empty spec = sub-agents write generic
 code. Real spec = sub-agents match the team's actual patterns.
 
@@ -292,6 +324,8 @@ ${checklistMarkdown}
 
 ---
 
+${renderCapabilityReadinessSection(selectedCapabilities)}
+
 ## Spec files to populate
 `;
     const backendSection = `
@@ -300,11 +334,11 @@ ${checklistMarkdown}
 
 | File | What to document |
 |------|------------------|
-| \`.trellis/spec/backend/directory-structure.md\` | Where different file types go (routes, services, utils) |
-| \`.trellis/spec/backend/database-guidelines.md\` | ORM, migrations, query patterns, naming conventions |
-| \`.trellis/spec/backend/error-handling.md\` | How errors are caught, logged, and returned |
-| \`.trellis/spec/backend/logging-guidelines.md\` | Log levels, format, what to log |
-| \`.trellis/spec/backend/quality-guidelines.md\` | Code review standards, testing requirements |
+| \`.cstl/spec/backend/directory-structure.md\` | Where different file types go (routes, services, utils) |
+| \`.cstl/spec/backend/database-guidelines.md\` | ORM, migrations, query patterns, naming conventions |
+| \`.cstl/spec/backend/error-handling.md\` | How errors are caught, logged, and returned |
+| \`.cstl/spec/backend/logging-guidelines.md\` | Log levels, format, what to log |
+| \`.cstl/spec/backend/quality-guidelines.md\` | Code review standards, testing requirements |
 `;
     const frontendSection = `
 
@@ -312,18 +346,18 @@ ${checklistMarkdown}
 
 | File | What to document |
 |------|------------------|
-| \`.trellis/spec/frontend/directory-structure.md\` | Component/page/hook organization |
-| \`.trellis/spec/frontend/component-guidelines.md\` | Component patterns, props conventions |
-| \`.trellis/spec/frontend/hook-guidelines.md\` | Custom hook naming, patterns |
-| \`.trellis/spec/frontend/state-management.md\` | State library, patterns, what goes where |
-| \`.trellis/spec/frontend/type-safety.md\` | TypeScript conventions, type organization |
-| \`.trellis/spec/frontend/quality-guidelines.md\` | Linting, testing, accessibility |
+| \`.cstl/spec/frontend/directory-structure.md\` | Component/page/hook organization |
+| \`.cstl/spec/frontend/component-guidelines.md\` | Component patterns, props conventions |
+| \`.cstl/spec/frontend/hook-guidelines.md\` | Custom hook naming, patterns |
+| \`.cstl/spec/frontend/state-management.md\` | State library, patterns, what goes where |
+| \`.cstl/spec/frontend/type-safety.md\` | TypeScript conventions, type organization |
+| \`.cstl/spec/frontend/quality-guidelines.md\` | Linting, testing, accessibility |
 `;
     const footer = `
 
 ### Thinking guides (already populated)
 
-\`.trellis/spec/guides/\` contains general thinking guides pre-filled with
+\`.cstl/spec/guides/\` contains general thinking guides pre-filled with
 best practices. Customize only if something clearly doesn't fit this project.
 
 ---
@@ -333,7 +367,7 @@ best practices. Customize only if something clearly doesn't fit this project.
 ### Step 1: Import from existing convention files first (preferred)
 
 Search the repo for existing convention docs. If any exist, read them and
-extract the relevant rules into the matching \`.trellis/spec/\` files —
+extract the relevant rules into the matching \`.cstl/spec/\` files —
 usually much faster than documenting from scratch.
 
 | File / Directory | Notes |
@@ -364,14 +398,14 @@ is a separate conversation, not a bootstrap concern.
 
 ## Quick explainer of the runtime (share when they ask "why do we need spec at all")
 
-- Every AI coding task spawns two sub-agents: \`trellis-implement\` (writes
-  code) and \`trellis-check\` (verifies quality).
+- Every AI coding task spawns two sub-agents: \`cstl-implement\` (writes
+  code) and \`cstl-check\` (verifies quality).
 - Each task has \`implement.jsonl\` / \`check.jsonl\` manifests listing which
   spec files to load.
 - The platform hook auto-injects those spec files + the task's \`prd.md\`
   into every sub-agent prompt, so the sub-agent codes/reviews per team
   conventions without anyone pasting them manually.
-- Source of truth: \`.trellis/spec/\`. That's why filling it well now pays
+- Source of truth: \`.cstl/spec/\`. That's why filling it well now pays
   off forever.
 
 ---
@@ -382,7 +416,7 @@ When the developer confirms the checklist items above are done with real
 examples (not placeholders), guide them to run:
 
 \`\`\`bash
-${pythonCmd} ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
+${pythonCmd} ./.cstl/scripts/task.py archive 00-bootstrap-guidelines
 \`\`\`
 
 After archive, every new developer who joins this project will get a
@@ -406,10 +440,10 @@ etc.) I can pull from, or should I scan the codebase from scratch?"
             const specName = sanitizePkgName(pkg.name);
             content += `\n### Package: ${pkg.name} (\`spec/${specName}/\`)\n`;
             if (pkgType !== "frontend") {
-                content += `\n- Backend guidelines: \`.trellis/spec/${specName}/backend/\`\n`;
+                content += `\n- Backend guidelines: \`.cstl/spec/${specName}/backend/\`\n`;
             }
             if (pkgType !== "backend") {
-                content += `\n- Frontend guidelines: \`.trellis/spec/${specName}/frontend/\`\n`;
+                content += `\n- Frontend guidelines: \`.cstl/spec/${specName}/frontend/\`\n`;
             }
         }
     }
@@ -446,15 +480,15 @@ function getBootstrapTaskJson(developer, projectType, packages) {
         assignee: developer,
         createdAt: today,
         relatedFiles,
-        notes: `First-time setup task created by trellis init (${projectType} project)`,
+        notes: `First-time setup task created by cstl init (${projectType} project)`,
     });
 }
 /**
  * Create bootstrap task for first-time setup
  */
-function createBootstrapTask(cwd, developer, pythonCmd, projectType, packages) {
+function createBootstrapTask(cwd, developer, pythonCmd, projectType, selectedCapabilities, packages) {
     const taskJson = getBootstrapTaskJson(developer, projectType, packages);
-    const prdContent = getBootstrapPrdContent(projectType, pythonCmd, packages);
+    const prdContent = getBootstrapPrdContent(projectType, pythonCmd, selectedCapabilities, packages);
     return writeTaskSkeleton(cwd, BOOTSTRAP_TASK_NAME, taskJson, prdContent);
 }
 // =============================================================================
@@ -478,22 +512,44 @@ function getJoinerTaskJson(developer, taskName) {
         creator: developer,
         assignee: developer,
         createdAt: today,
-        notes: "Generated by trellis init for a new developer joining an existing Trellis project",
+        notes: "Generated by cstl init for a new developer joining an existing Trellis project",
     });
 }
 /**
  * PRD content for joiner onboarding. Kept concise (~80 lines) — deeper
  * guidance lives in skills and docs.
  */
-function getJoinerPrdContent(developer, pythonCmd) {
+function getJoinerPrdContent(developer, pythonCmd, selectedCapabilities) {
     const slug = slugifyDeveloperName(developer);
+    const selectedCapabilityChecklist = selectedCapabilities
+        .map((id) => {
+        const capability = getProjectCapability(id);
+        return `- \`${capability.id}\` — re-check readiness in this clone before claiming it is available.`;
+    })
+        .join("\n");
+    let capabilitySection = "";
+    if (selectedCapabilities.length > 0) {
+        capabilitySection = `
+### 5. Re-verify selected project capabilities
+
+This repo has capability selections recorded in \`.cstl/capabilities.json\`.
+Before they rely on MCP-backed behavior, remind them to check the selected set:
+
+${selectedCapabilityChecklist}
+
+- If a capability is not \`ready\`, have them re-run the local verification path
+  instead of assuming the previous machine's setup carries over.
+
+---
+`;
+    }
     return `# Joiner Onboarding Task
 
 **You (the AI) are running this task. The developer does not read this file.**
 
-\`${developer}\` just ran \`trellis init\` on a fresh clone, saw "Developer
+\`${developer}\` just ran \`cstl init\` on a fresh clone, saw "Developer
 initialized", and will now start asking you questions in chat. This joiner task
-exists under \`.trellis/tasks/\`; when they want to work on it, they should
+exists under \`.cstl/tasks/\`; when they want to work on it, they should
 select it from a session that provides Trellis session identity.
 
 Your job is to orient them to Trellis. Don't dump all of this at them — open
@@ -511,13 +567,13 @@ agents consistent with project-specific conventions instead of writing generic
 code every session.
 
 - **Three phases**: Plan (brainstorm → \`prd.md\`) → Execute (code + check) →
-  Finish (capture + wrap). Full reference: \`.trellis/workflow.md\`.
+  Finish (capture + wrap). Full reference: \`.cstl/workflow.md\`.
 - **Task lifecycle**: planning → in_progress → done → archive, under
-  \`.trellis/tasks/\`.
+  \`.cstl/tasks/\`.
 - **Core slash commands**:
-  - \`/trellis:continue\` — continue the current live session's selected task
-  - \`/trellis:finish-work\` — wrap up a finished task
-  - \`/trellis:start\` — framework/dashboard entry (not needed here; the
+  - \`/cstl:continue\` — continue the current live session's selected task
+  - \`/cstl:finish-work\` — wrap up a finished task
+  - \`/cstl:start\` — framework/dashboard entry (not needed here; the
     SessionStart hook does its job automatically)
 
 ### 2. Runtime mechanics (explain when they ask "how does it know what to do")
@@ -527,28 +583,28 @@ code every session.
   conversation at every session start.
 - **\`<workflow-state>\` tag** is auto-injected with every user message,
   carrying the selected task + phase hint.
-- **\`/trellis:continue\`** loads the Phase Index, reads \`prd.md\` + recent
-  activity, and routes to the right skill (\`trellis-brainstorm\` for planning,
-  \`trellis-implement\` for coding, \`trellis-check\` for verification).
-- **\`trellis-implement\` sub-agent** is spawned when code needs to be written.
+- **\`/cstl:continue\`** loads the Phase Index, reads \`prd.md\` + recent
+  activity, and routes to the right skill (\`cstl-brainstorm\` for planning,
+  \`cstl-implement\` for coding, \`cstl-check\` for verification).
+- **\`cstl-implement\` sub-agent** is spawned when code needs to be written.
   The platform hook reads \`{TASK_DIR}/implement.jsonl\` and auto-injects those
   spec files + \`prd.md\` into the sub-agent's prompt so it codes per project
   conventions.
-- **\`trellis-check\` sub-agent** follows the same pattern with \`check.jsonl\`
+- **\`cstl-check\` sub-agent** follows the same pattern with \`check.jsonl\`
   — reviews changes against specs, auto-fixes issues, runs lint/typecheck.
 
 File layout (mention when they ask "where does what live"):
-- \`.trellis/.runtime/sessions/<session>.json\` — live-session selected-task state, gitignored
-- \`.trellis/tasks/<task>/{implement,check}.jsonl\` — per-task context manifests
-- \`.trellis/spec/\` — project-wide conventions (source of truth)
-- \`.trellis/workspace/${developer}/journal-*.md\` — their session log,
+- \`.cstl/.runtime/sessions/<session>.json\` — live-session selected-task state, gitignored
+- \`.cstl/tasks/<task>/{implement,check}.jsonl\` — per-task context manifests
+- \`.cstl/spec/\` — project-wide conventions (source of truth)
+- \`.cstl/workspace/${developer}/journal-*.md\` — their session log,
   rotated at ~2000 lines
 
 ### 3. This project's actual conventions
 
-- Summarize \`.trellis/spec/\` for them — what coding conventions this
+- Summarize \`.cstl/spec/\` for them — what coding conventions this
   specific team enforces.
-- Point at the last 5 entries in \`.trellis/tasks/archive/\` as a rhythm
+- Point at the last 5 entries in \`.cstl/tasks/archive/\` as a rhythm
   example of how people actually work here. **If archive is empty** (the
   project just started), skip this — don't invent examples.
 - Not your job in this onboarding to teach them the business code itself —
@@ -556,20 +612,22 @@ File layout (mention when they ask "where does what live"):
 
 ### 4. Their assigned work
 
-- Check if \`.trellis/workspace/${developer}/\` already exists — if yes, it's
+- Check if \`.cstl/workspace/${developer}/\` already exists — if yes, it's
   their journal from another machine and worth mentioning.
-- Run \`${pythonCmd} ./.trellis/scripts/task.py list --assignee ${developer}\` to
+- Run \`${pythonCmd} ./.cstl/scripts/task.py list --assignee ${developer}\` to
   show tasks assigned to them. (Quote the name if it contains spaces.)
 - Remind them that the "My Tasks" section appears in the SessionStart context
   on every new session.
 
 ---
 
+${capabilitySection}
+
 ## Optional: walk through a small task end-to-end
 
 If they want to practice before touching real work, offer to pick a tiny
-P3 task or a typo fix and run the full cycle together: \`/trellis:continue\`
-→ you implement via sub-agents → \`/trellis:finish-work\`.
+P3 task or a typo fix and run the full cycle together: \`/cstl:continue\`
+→ you implement via sub-agents → \`/cstl:finish-work\`.
 
 ---
 
@@ -579,14 +637,14 @@ When they feel oriented (or after you've covered the four topics with
 reasonable back-and-forth), guide them to run:
 
 \`\`\`bash
-${pythonCmd} ./.trellis/scripts/task.py archive 00-join-${slug}
+${pythonCmd} ./.cstl/scripts/task.py archive 00-join-${slug}
 \`\`\`
 
 ---
 
 ## Suggested opening line
 
-"Welcome! Your \`trellis init\` set me up to onboard you to this project. I
+"Welcome! Your \`cstl init\` set me up to onboard you to this project. I
 can walk you through the workflow, show you the runtime mechanics under the
 hood, summarize the team's spec, or jump to what you're already curious about
 — which would you prefer?"
@@ -601,11 +659,11 @@ function createJoinerOnboardingTask(cwd, developer, pythonCmd) {
     const slug = slugifyDeveloperName(developer);
     const taskName = `00-join-${slug}`;
     const taskJson = getJoinerTaskJson(developer, taskName);
-    const prdContent = getJoinerPrdContent(developer, pythonCmd);
+    const prdContent = getJoinerPrdContent(developer, pythonCmd, loadProjectCapabilities(cwd));
     return writeTaskSkeleton(cwd, taskName, taskJson, prdContent);
 }
 /**
- * Handle re-init when .trellis/ already exists.
+ * Handle re-init when .cstl/ already exists.
  * Returns true if handled (caller should return), false if user chose full re-init.
  */
 async function handleReinit(cwd, options, developerName, pythonCmd) {
@@ -734,7 +792,7 @@ async function handleReinit(cwd, options, developerName, pythonCmd) {
         }
         catch {
             console.log(chalk.yellow("⚠ Could not initialize developer. Run manually:"));
-            console.log(chalk.gray(`  ${pythonCmd} .trellis/scripts/init_developer.py ${devName}`));
+            console.log(chalk.gray(`  ${pythonCmd} .cstl/scripts/init_developer.py ${devName}`));
         }
         // Create joiner onboarding task for fresh checkouts (no prior .developer).
         // Runs outside the init_developer try/catch so failures surface as warnings.
@@ -789,7 +847,7 @@ function writeMonorepoConfig(cwd, packages) {
     fs.writeFileSync(configPath, content.trimEnd() + "\n" + lines.join("\n") + "\n", "utf-8");
 }
 async function checkSmartSearchReadinessForInit(options) {
-    const skipReadinessCommand = "trellis init --skip-readiness";
+    const skipReadinessCommand = "cstl init --skip-readiness";
     try {
         checkSmartSearchReadiness({
             skipReadiness: options.skipReadiness,
@@ -845,7 +903,7 @@ async function checkSmartSearchReadinessForInit(options) {
     }
 }
 async function checkProjectCapabilityReadinessForInit(options) {
-    const skipReadinessCommand = "trellis init --skip-readiness";
+    const skipReadinessCommand = "cstl init --skip-readiness";
     try {
         checkProjectCapabilityReadiness({
             cwd: options.cwd,
@@ -893,7 +951,7 @@ async function checkProjectCapabilityReadinessForInit(options) {
 export async function init(options) {
     // Refuse to run in $HOME — running here would scoop platform runtime data
     // (Claude/Codex/OpenCode session histories etc.) into the trellis hash
-    // manifest, and a subsequent `trellis uninstall` would wipe it.
+    // manifest, and a subsequent `cstl uninstall` would wipe it.
     if (isCwdHomedir() && !homedirBypassEnabled()) {
         console.error(chalk.red(homedirGuardMessage("init")));
         process.exit(1);
@@ -902,8 +960,19 @@ export async function init(options) {
     const isFirstInit = !fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW));
     // Captured here (before createWorkflowStructure + init_developer run) so
     // the three-branch dispatch at the bottom can tell "fresh clone joiner"
-    // (.trellis/ exists, .developer missing) apart from "creator first init".
+    // (.cstl/ exists, .developer missing) apart from "creator first init".
     const hadDeveloperFileAtStart = fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW, FILE_NAMES.DEVELOPER));
+    // Coexistence mode: an upstream mindfold-ai/Trellis `.trellis/` tree exists
+    // but cursor-trellis has no `.cstl/` yet. The user is adding cursor-trellis
+    // on Cursor alongside upstream Trellis (scenario 2). cursor-trellis owns
+    // `.cursor/` and `.cstl/`; it must NOT touch `.trellis/` and must preserve
+    // an existing `<!-- TRELLIS:START -->` block in AGENTS.md.
+    const coexistenceMode = isFirstInit && fs.existsSync(path.join(cwd, ".trellis"));
+    if (coexistenceMode) {
+        console.log(chalk.cyan("\n  Detected upstream `.trellis/` — coexistence mode: cursor-trellis will use `.cstl/`"));
+        console.log(chalk.gray("  alongside `.trellis/` and take over `.cursor/`. `.trellis/` will not be touched.\n"));
+        console.log(chalk.gray("  Do NOT run `cstl update --migrate` here — that would rename the upstream `.trellis/`.\n"));
+    }
     // Generate ASCII art banner dynamically using FIGlet "Rebel" font
     const banner = figlet.textSync("Trellis", { font: "Rebel" });
     console.log(chalk.cyan(`\n${banner.trimEnd()}`));
@@ -952,9 +1021,9 @@ export async function init(options) {
     }
     const { command: pythonCmd } = resolveSupportedPython();
     // ==========================================================================
-    // Re-init fast path: skip full flow when .trellis/ already exists
+    // Re-init fast path: skip full flow when .cstl/ already exists
     // ==========================================================================
-    // Aborted-init recovery (issue #204): if .trellis/ exists but tasks/ is
+    // Aborted-init recovery (issue #204): if .cstl/ exists but tasks/ is
     // empty, the previous init never reached bootstrap creation. Fall through
     // to the full flow so the main-dispatch tasksEmpty fallback fires —
     // handleReinit's joiner branch would otherwise mis-route the recovery.
@@ -1022,7 +1091,7 @@ export async function init(options) {
             console.log(chalk.gray("  ✗ .gitmodules"));
             console.log(chalk.gray("  ✗ sibling .git directories (need ≥ 2)"));
             console.log("");
-            console.log("To configure manually, add to .trellis/config.yaml:");
+            console.log("To configure manually, add to .cstl/config.yaml:");
             console.log("");
             console.log(chalk.cyan("  packages:"));
             console.log(chalk.cyan("    frontend:"));
@@ -1439,8 +1508,8 @@ export async function init(options) {
             console.log(chalk.yellow(`   ${result.message}`));
             console.log(chalk.gray("   Falling back to blank templates..."));
             const retryCmd = registry
-                ? `trellis init --registry ${registry.gigetSource} --template ${selectedTemplate}`
-                : `trellis init --template ${selectedTemplate}`;
+                ? `cstl init --registry ${registry.gigetSource} --template ${selectedTemplate}`
+                : `cstl init --template ${selectedTemplate}`;
             console.log(chalk.gray(`   You can retry later: ${retryCmd}`));
         }
     }
@@ -1481,7 +1550,7 @@ export async function init(options) {
         else {
             console.log(chalk.yellow(`   ${result.message}`));
             console.log(chalk.gray("   Falling back to blank templates..."));
-            console.log(chalk.gray(`   You can retry later: trellis init --registry ${registry.gigetSource}`));
+            console.log(chalk.gray(`   You can retry later: cstl init --registry ${registry.gigetSource}`));
         }
     }
     // ==========================================================================
@@ -1522,7 +1591,7 @@ export async function init(options) {
                 {
                     type: "confirm",
                     name: "byok",
-                    message: "使用 Cursor++ BYOK 代理？（原生 Cursor API 用户选 No；仅 BYOK 需要 .trellis/local/cursor2plus/）",
+                    message: "使用 Cursor++ BYOK 代理？（原生 Cursor API 用户选 No；仅 BYOK 需要 .cstl/local/cursor2plus/）",
                     default: false,
                 },
             ]);
@@ -1546,14 +1615,28 @@ export async function init(options) {
         // Write version file for update tracking
         const versionPath = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
         fs.writeFileSync(versionPath, VERSION);
-        // Configure selected tools by copying entire directories (dogfooding)
+        // Configure selected tools by copying entire directories (dogfooding).
+        // In coexistence mode cursor-trellis takes over `.cursor/` — force-write
+        // platform files even when `-y`/`--skipExisting` is set, so cstl hooks,
+        // rules, and commands land regardless of upstream files already present.
         const selectedPlatformIds = [];
-        for (const tool of tools) {
-            const platformId = resolveCliFlag(tool);
-            if (platformId) {
-                selectedPlatformIds.push(platformId);
-                console.log(chalk.blue(`📝 Configuring ${AI_TOOLS[platformId].name}...`));
-                await configurePlatform(platformId, cwd);
+        const savedMode = getWriteMode();
+        if (coexistenceMode) {
+            setWriteMode("force");
+        }
+        try {
+            for (const tool of tools) {
+                const platformId = resolveCliFlag(tool);
+                if (platformId) {
+                    selectedPlatformIds.push(platformId);
+                    console.log(chalk.blue(`📝 Configuring ${AI_TOOLS[platformId].name}...`));
+                    await configurePlatform(platformId, cwd);
+                }
+            }
+        }
+        finally {
+            if (coexistenceMode) {
+                setWriteMode(savedMode);
             }
         }
         if (selectedPlatformIds.includes("cursor")) {
@@ -1569,7 +1652,7 @@ export async function init(options) {
             logCursor2plusSetupHint();
         }
         // Create root files (skip if exists)
-        await createRootFiles(cwd);
+        await createRootFiles(cwd, coexistenceMode);
     }
     finally {
         stopRecordingWrites();
@@ -1580,7 +1663,7 @@ export async function init(options) {
         console.log(chalk.gray(`📋 Tracking ${hashedCount} template files for updates`));
     }
     // Non-native workflow is user-managed local content. Drop the
-    // `.trellis/workflow.md` hash entry so `trellis update` classifies it as
+    // `.cstl/workflow.md` hash entry so `trellis update` classifies it as
     // modified and does not silently restore native bytes. See design.md
     // "Durable-state contract".
     if (workflowMdOverride !== undefined && workflowId !== NATIVE_WORKFLOW_ID) {
@@ -1605,7 +1688,7 @@ export async function init(options) {
         //   isFirstInit=false + no .developer file → joiner onboarding (fresh clone)
         //   isFirstInit=false + .developer exists  → same-dev re-init, no task
         //
-        // Tasks-empty fallback (issue #204): if .trellis/ exists but tasks dir is
+        // Tasks-empty fallback (issue #204): if .cstl/ exists but tasks dir is
         // empty, the previous init aborted before creating the bootstrap task. Run
         // bootstrap creation regardless of isFirstInit. writeTaskSkeleton is
         // idempotent so repeated triggers are safe.
@@ -1616,7 +1699,10 @@ export async function init(options) {
         const tasksDir = path.join(cwd, PATHS.TASKS);
         const tasksEmpty = !fs.existsSync(tasksDir) || fs.readdirSync(tasksDir).length === 0;
         if (isFirstInit || tasksEmpty) {
-            createBootstrapTask(cwd, developerName, pythonCmd, projectType, monorepoPackages);
+            const bootstrapCreated = createBootstrapTask(cwd, developerName, pythonCmd, projectType, selectedCapabilities, monorepoPackages);
+            if (bootstrapCreated) {
+                console.log(chalk.gray(`Next: complete ${BOOTSTRAP_TASK_NAME} to verify selected capabilities and fill the project spec.`));
+            }
         }
         else if (!hadDeveloperFileAtStart) {
             try {
@@ -1645,8 +1731,28 @@ function askInput(prompt) {
         });
     });
 }
-async function createRootFiles(cwd) {
+async function createRootFiles(cwd, coexistenceMode = false) {
     const agentsPath = path.join(cwd, FILE_NAMES.AGENTS);
+    if (coexistenceMode && fs.existsSync(agentsPath)) {
+        // Coexistence: preserve an upstream `<!-- TRELLIS:START -->` block and any
+        // user content, and add/refresh the `<!-- CSTL:START -->` block alongside.
+        // Force-write the merged result (via writeFile so the write is recorded
+        // for hash tracking) even under `-y`.
+        const existing = fs.readFileSync(agentsPath, "utf-8");
+        const merged = insertCstlManagedBlock(existing, agentsMdContent);
+        const saved = getWriteMode();
+        setWriteMode("force");
+        try {
+            const wrote = await writeFile(agentsPath, merged);
+            if (wrote) {
+                console.log(chalk.blue("📄 Updated AGENTS.md with cursor-trellis managed block (preserved upstream block)"));
+            }
+        }
+        finally {
+            setWriteMode(saved);
+        }
+        return;
+    }
     // Write AGENTS.md from template
     const agentsWritten = await writeFile(agentsPath, agentsMdContent);
     if (agentsWritten) {