@blxzer/cursor-trellis 0.1.0

package/dist/commands/init.js

@@ -0,0 +1,1656 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import chalk from "chalk";
+import figlet from "figlet";
+import inquirer from "inquirer";
+import { createWorkflowStructure } from "../configurators/workflow.js";
+import { getInitToolChoices, resolveCliFlag, configurePlatform, getConfiguredPlatforms, getPlatformsWithPythonHooks, } from "../configurators/index.js";
+import { getPythonCommandForPlatform, setResolvedPythonCommand, } from "../configurators/shared.js";
+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 { emptyTaskJson } from "../utils/task-json.js";
+import { detectProjectType, detectMonorepo, sanitizePkgName, } from "../utils/project-detector.js";
+import { initializeHashes, removeHash } from "../utils/template-hash.js";
+import { NATIVE_WORKFLOW_ID, resolveWorkflowTemplate, } from "../utils/workflow-resolver.js";
+import { isCwdHomedir, homedirGuardMessage, homedirBypassEnabled, } from "../utils/cwd-guard.js";
+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";
+const MIN_PYTHON_MAJOR = 3;
+const MIN_PYTHON_MINOR = 9;
+const PYTHON_VERSION_RE = /Python (\d+)\.(\d+)/;
+export function isSupportedPythonVersion(versionOutput) {
+    const match = versionOutput.match(PYTHON_VERSION_RE);
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    return (major > MIN_PYTHON_MAJOR ||
+        (major === MIN_PYTHON_MAJOR && minor >= MIN_PYTHON_MINOR));
+}
+function detectPythonVersion(command) {
+    try {
+        return execSync(`${command} --version`, {
+            encoding: "utf-8",
+            stdio: "pipe",
+        }).trim();
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "EPERM" || code === "EACCES") {
+            return "sandbox-restricted";
+        }
+        return null;
+    }
+}
+export function requireSupportedPython(command) {
+    // Final escape hatch — set when the user knows python3 is on PATH but
+    // the probe keeps failing for environment-specific reasons.
+    if (process.env.TRELLIS_SKIP_PYTHON_CHECK === "1") {
+        return `version check skipped (TRELLIS_SKIP_PYTHON_CHECK=1)`;
+    }
+    const versionOutput = detectPythonVersion(command);
+    if (versionOutput === "sandbox-restricted") {
+        console.warn(chalk.yellow(`⚠ Python version check skipped — sandboxed environment blocked ` +
+            `child_process spawn (EPERM/EACCES). Assuming "${command}" is on ` +
+            `PATH. If init fails later, re-run on the host or set ` +
+            `TRELLIS_SKIP_PYTHON_CHECK=1.`));
+        return `version unknown (sandbox-restricted)`;
+    }
+    if (!versionOutput) {
+        throw new Error(`Python command "${command}" not found. Trellis init requires Python ≥ 3.9.`);
+    }
+    if (!isSupportedPythonVersion(versionOutput)) {
+        throw new Error(`${versionOutput} detected via "${command}", but Trellis init requires Python ≥ 3.9.`);
+    }
+    return versionOutput;
+}
+/**
+ * Candidate Python command list per platform.
+ *
+ * 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.
+ *
+ * Non-Windows: `python3` is canonical; `python` is a fallback for systems
+ * where Python 3 is the only Python and is named `python` (some Arch
+ * configs, conda envs).
+ */
+const PYTHON_CANDIDATES = {
+    win32: ["python", "python3", "py -3"],
+    other: ["python3", "python"],
+};
+/**
+ * Detect a working Python ≥ 3.9 command on the host platform.
+ *
+ * Honors `TRELLIS_PYTHON_CMD` (explicit override, no probe) and
+ * `TRELLIS_SKIP_PYTHON_CHECK=1` (skip probe, trust platform default).
+ *
+ * Otherwise tries each candidate in `PYTHON_CANDIDATES` in order and returns
+ * the first whose `--version` matches `Python ≥ 3.9`. Caches the result via
+ * `setResolvedPythonCommand` so all downstream template / configurator
+ * writes pick up the resolved value.
+ *
+ * Throws a helpful, Windows-aware error if no candidate works.
+ */
+export function resolveSupportedPython() {
+    // Explicit override — user knows their environment.
+    const override = process.env.TRELLIS_PYTHON_CMD?.trim();
+    if (override) {
+        setResolvedPythonCommand(override);
+        return { command: override, version: "set via TRELLIS_PYTHON_CMD" };
+    }
+    // Skip probe entirely.
+    if (process.env.TRELLIS_SKIP_PYTHON_CHECK === "1") {
+        const fallback = getPythonCommandForPlatform();
+        setResolvedPythonCommand(fallback);
+        return {
+            command: fallback,
+            version: "version check skipped (TRELLIS_SKIP_PYTHON_CHECK=1)",
+        };
+    }
+    const candidates = process.platform === "win32"
+        ? PYTHON_CANDIDATES.win32
+        : PYTHON_CANDIDATES.other;
+    const probeFailures = [];
+    for (const candidate of candidates) {
+        const probe = detectPythonVersion(candidate);
+        if (probe === "sandbox-restricted") {
+            console.warn(chalk.yellow(`⚠ Python version check skipped — sandboxed environment blocked ` +
+                `child_process spawn (EPERM/EACCES). Assuming "${candidate}" is ` +
+                `on PATH. If init fails later, re-run on the host or set ` +
+                `TRELLIS_SKIP_PYTHON_CHECK=1.`));
+            setResolvedPythonCommand(candidate);
+            return {
+                command: candidate,
+                version: "version unknown (sandbox-restricted)",
+            };
+        }
+        if (!probe) {
+            probeFailures.push(`${candidate}: not found`);
+            continue;
+        }
+        if (!isSupportedPythonVersion(probe)) {
+            probeFailures.push(`${candidate}: ${probe} (< 3.9)`);
+            continue;
+        }
+        setResolvedPythonCommand(candidate);
+        return { command: candidate, version: probe };
+    }
+    const isWindows = process.platform === "win32";
+    const installHint = isWindows
+        ? `Install Python ≥ 3.9 from https://www.python.org/downloads/windows/ — make sure ` +
+            `"Add Python to PATH" is checked in the installer. Or, if Python is ` +
+            `installed under a different name, set TRELLIS_PYTHON_CMD=<your-cmd> ` +
+            `before re-running init (e.g. \`set TRELLIS_PYTHON_CMD=py -3\`).`
+        : `Install Python ≥ 3.9 from https://www.python.org/downloads/ or via your ` +
+            `package manager. Or set TRELLIS_PYTHON_CMD=<your-cmd> before re-running.`;
+    throw new Error(`No supported Python command found. Tried: ${candidates.join(", ")}.\n` +
+        `Probe results:\n  ${probeFailures.join("\n  ")}\n\n` +
+        `Trellis init requires Python ≥ 3.9. ${installHint}\n` +
+        `Last-resort escape hatch: set TRELLIS_SKIP_PYTHON_CHECK=1 to skip the probe entirely.`);
+}
+function getOsDisplayName(platform = process.platform) {
+    switch (platform) {
+        case "win32":
+            return "Windows";
+        case "darwin":
+            return "macOS";
+        case "linux":
+            return "Linux";
+        default:
+            return platform;
+    }
+}
+function logPythonAdaptationNotice(command) {
+    const osName = getOsDisplayName();
+    console.log(chalk.blue(`📌 ${osName} detected: Trellis rendered Python commands as "${command}" in generated hooks, settings, and help text`));
+}
+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++）可忽略此步骤。"));
+    console.log("");
+}
+// =============================================================================
+// Bootstrap Task Creation
+// =============================================================================
+const BOOTSTRAP_TASK_NAME = "00-bootstrap-guidelines";
+/**
+ * Slugify a developer name for safe use in task directory names.
+ *
+ * Unlike `sanitizePkgName` (which only strips npm @scope/ prefixes), this
+ * handles arbitrary developer input: spaces, Unicode letters, punctuation,
+ * path separators. Returns "user" fallback when input slugifies to empty.
+ *
+ * Exported for unit testing; not part of the public API.
+ */
+export function slugifyDeveloperName(name) {
+    const slug = name
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^\p{Letter}\p{Number}]+/gu, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "user";
+}
+/**
+ * Write a task skeleton (task.json + prd.md).
+ *
+ * Idempotent: if the task dir already exists, returns true without touching
+ * anything. Shared by both creator bootstrap and joiner onboarding flows.
+ */
+function writeTaskSkeleton(cwd, taskName, taskJson, prdContent) {
+    const taskDir = path.join(cwd, PATHS.TASKS, taskName);
+    if (fs.existsSync(taskDir))
+        return true; // idempotent
+    try {
+        fs.mkdirSync(taskDir, { recursive: true });
+        fs.writeFileSync(path.join(taskDir, FILE_NAMES.TASK_JSON), JSON.stringify(taskJson, null, 2), "utf-8");
+        fs.writeFileSync(path.join(taskDir, FILE_NAMES.PRD), prdContent, "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Compute the bootstrap checklist items (previously stored as structured
+ * `subtasks: [{name, status}]` in task.json). Per task 04-21-task-schema-unify
+ * (D1), these live as markdown `- [ ]` items in prd.md instead, so task.json
+ * stays canonical with `subtasks: string[]` (child task dir names, same as
+ * task_store.py).
+ */
+function getBootstrapChecklistItems(projectType, packages) {
+    if (packages && packages.length > 0) {
+        const items = packages.map((pkg) => `Fill guidelines for ${pkg.name}`);
+        items.push("Add code examples");
+        return items;
+    }
+    if (projectType === "frontend") {
+        return ["Fill frontend guidelines", "Add code examples"];
+    }
+    if (projectType === "backend") {
+        return ["Fill backend guidelines", "Add code examples"];
+    }
+    return [
+        "Fill backend guidelines",
+        "Fill frontend guidelines",
+        "Add code examples",
+    ];
+}
+function getBootstrapRelatedFiles(projectType, packages) {
+    if (packages && packages.length > 0) {
+        return packages.map((pkg) => `.trellis/spec/${sanitizePkgName(pkg.name)}/`);
+    }
+    if (projectType === "frontend") {
+        return [".trellis/spec/frontend/"];
+    }
+    if (projectType === "backend") {
+        return [".trellis/spec/backend/"];
+    }
+    return [".trellis/spec/backend/", ".trellis/spec/frontend/"];
+}
+function getBootstrapPrdContent(projectType, pythonCmd, packages) {
+    const checklistItems = getBootstrapChecklistItems(projectType, packages);
+    const checklistMarkdown = checklistItems
+        .map((item) => `- [ ] ${item}`)
+        .join("\n");
+    const header = `# Bootstrap Task: Fill Project Development Guidelines
+
+**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
+this task from a session that provides Trellis session identity.
+
+**Your job**: help them populate \`.trellis/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
+listed in per-task jsonl manifests. Empty spec = sub-agents write generic
+code. Real spec = sub-agents match the team's actual patterns.
+
+Don't dump instructions. Open with a short greeting, figure out if the repo
+has any existing convention docs (CLAUDE.md, .cursorrules, etc.), and drive
+the rest conversationally.
+
+---
+
+## Status (update the checkboxes as you complete each item)
+
+${checklistMarkdown}
+
+---
+
+## Spec files to populate
+`;
+    const backendSection = `
+
+### Backend guidelines
+
+| 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 |
+`;
+    const frontendSection = `
+
+### Frontend guidelines
+
+| 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 |
+`;
+    const footer = `
+
+### Thinking guides (already populated)
+
+\`.trellis/spec/guides/\` contains general thinking guides pre-filled with
+best practices. Customize only if something clearly doesn't fit this project.
+
+---
+
+## How to fill the spec
+
+### 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 —
+usually much faster than documenting from scratch.
+
+| File / Directory | Tool |
+|------|------|
+| \`CLAUDE.md\` / \`CLAUDE.local.md\` | Claude Code |
+| \`AGENTS.md\` | Codex / Claude Code / agent-compatible tools |
+| \`.cursorrules\` | Cursor |
+| \`.cursor/rules/*.mdc\` | Cursor (rules directory) |
+| \`.windsurfrules\` | Windsurf |
+| \`.clinerules\` | Cline |
+| \`.roomodes\` | Roo Code |
+| \`.github/copilot-instructions.md\` | GitHub Copilot |
+| \`.vscode/settings.json\` → \`github.copilot.chat.codeGeneration.instructions\` | VS Code Copilot |
+| \`CONVENTIONS.md\` / \`.aider.conf.yml\` | aider |
+| \`CONTRIBUTING.md\` | General project conventions |
+| \`.editorconfig\` | Editor formatting rules |
+
+### Step 2: Analyze the codebase for anything not covered by existing docs
+
+Scan real code to discover patterns. Before writing each spec file:
+- Find 2-3 real examples of each pattern in the codebase.
+- Reference real file paths (not hypothetical ones).
+- Document anti-patterns the team clearly avoids.
+
+### Step 3: Document reality, not ideals
+
+**Critical**: write what the code *actually does*, not what it should do.
+Sub-agents match the spec, so aspirational patterns that don't exist in the
+codebase will cause sub-agents to write code that looks out of place.
+
+If the team has known tech debt, document the current state — improvement
+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).
+- 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
+  off forever.
+
+---
+
+## Completion
+
+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
+\`\`\`
+
+After archive, every new developer who joins this project will get a
+\`00-join-<slug>\` onboarding task instead of this bootstrap task.
+
+---
+
+## Suggested opening line
+
+"Welcome to Trellis! Your init just set me up to help you fill the project
+spec — a one-time setup so every future AI session follows the team's
+conventions instead of writing generic code. Before we start, do you have
+any existing convention docs (CLAUDE.md, .cursorrules, CONTRIBUTING.md,
+etc.) I can pull from, or should I scan the codebase from scratch?"
+`;
+    let content = header;
+    if (packages && packages.length > 0) {
+        // Monorepo: generate per-package sections
+        for (const pkg of packages) {
+            const pkgType = pkg.type === "unknown" ? "fullstack" : pkg.type;
+            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`;
+            }
+            if (pkgType !== "backend") {
+                content += `\n- Frontend guidelines: \`.trellis/spec/${specName}/frontend/\`\n`;
+            }
+        }
+    }
+    else if (projectType === "frontend") {
+        content += frontendSection;
+    }
+    else if (projectType === "backend") {
+        content += backendSection;
+    }
+    else {
+        // fullstack
+        content += backendSection;
+        content += frontendSection;
+    }
+    content += footer;
+    return content;
+}
+function getBootstrapTaskJson(developer, projectType, packages) {
+    const today = new Date().toISOString().split("T")[0];
+    const relatedFiles = getBootstrapRelatedFiles(projectType, packages);
+    // Canonical 24-field shape via emptyTaskJson factory.
+    // Checklist items (previously stored as structured `subtasks`) are now
+    // rendered as `- [ ]` items in prd.md; task.json.subtasks is always
+    // string[] (child task dir names) per the canonical schema.
+    return emptyTaskJson({
+        id: BOOTSTRAP_TASK_NAME,
+        name: BOOTSTRAP_TASK_NAME,
+        title: "Bootstrap Guidelines",
+        description: "Fill in project development guidelines for AI agents",
+        status: "in_progress",
+        dev_type: "docs",
+        priority: "P1",
+        creator: developer,
+        assignee: developer,
+        createdAt: today,
+        relatedFiles,
+        notes: `First-time setup task created by trellis init (${projectType} project)`,
+    });
+}
+/**
+ * Create bootstrap task for first-time setup
+ */
+function createBootstrapTask(cwd, developer, pythonCmd, projectType, packages) {
+    const taskJson = getBootstrapTaskJson(developer, projectType, packages);
+    const prdContent = getBootstrapPrdContent(projectType, pythonCmd, packages);
+    return writeTaskSkeleton(cwd, BOOTSTRAP_TASK_NAME, taskJson, prdContent);
+}
+// =============================================================================
+// Joiner Onboarding Task Creation
+// =============================================================================
+/**
+ * task.json factory for joiner onboarding. Mirrors the bootstrap factory but
+ * uses dev_type "docs", higher priority "P1", and the developer-specific task
+ * name (so multiple joiners in the same checkout don't collide).
+ */
+function getJoinerTaskJson(developer, taskName) {
+    const today = new Date().toISOString().split("T")[0];
+    return emptyTaskJson({
+        id: taskName,
+        name: taskName,
+        title: `Joining: Onboard to this Trellis project (${developer})`,
+        description: "Onboard a new developer to an existing Trellis project: learn the workflow, conventions, and find assigned work",
+        status: "in_progress",
+        dev_type: "docs",
+        priority: "P1",
+        creator: developer,
+        assignee: developer,
+        createdAt: today,
+        notes: "Generated by trellis 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) {
+    const slug = slugifyDeveloperName(developer);
+    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
+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
+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
+with a short greeting, ask where they want to start, and fill in the rest as
+they engage.
+
+---
+
+## Topics to cover (adapt order to their questions)
+
+### 1. What Trellis is + the workflow
+
+Trellis is a workflow layer over Claude Code / Cursor / etc. that keeps AI
+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\`.
+- **Task lifecycle**: planning → in_progress → done → archive, under
+  \`.trellis/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
+    SessionStart hook does its job automatically)
+
+### 2. Runtime mechanics (explain when they ask "how does it know what to do")
+
+- **SessionStart hook** runs \`get_context.py\` and injects identity, git
+  status, selected task, active task list, and workflow phase into the AI
+  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.
+  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\`
+  — 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,
+  rotated at ~2000 lines
+
+### 3. This project's actual conventions
+
+- Summarize \`.trellis/spec/\` for them — what coding conventions this
+  specific team enforces.
+- Point at the last 5 entries in \`.trellis/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 —
+  the README and their teammates handle that.
+
+### 4. Their assigned work
+
+- Check if \`.trellis/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
+  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.
+
+---
+
+## 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\`.
+
+---
+
+## Completion
+
+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}
+\`\`\`
+
+---
+
+## Suggested opening line
+
+"Welcome! Your \`trellis 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?"
+`;
+}
+/**
+ * Create joiner onboarding task for a new developer on an existing Trellis
+ * project. Task name is slugified to be filesystem-safe for arbitrary
+ * developer names (spaces, Unicode, punctuation).
+ */
+function createJoinerOnboardingTask(cwd, developer, pythonCmd) {
+    const slug = slugifyDeveloperName(developer);
+    const taskName = `00-join-${slug}`;
+    const taskJson = getJoinerTaskJson(developer, taskName);
+    const prdContent = getJoinerPrdContent(developer, pythonCmd);
+    return writeTaskSkeleton(cwd, taskName, taskJson, prdContent);
+}
+/**
+ * Handle re-init when .trellis/ already exists.
+ * Returns true if handled (caller should return), false if user chose full re-init.
+ */
+async function handleReinit(cwd, options, developerName, pythonCmd) {
+    const TOOLS = getInitToolChoices();
+    const configuredPlatforms = getConfiguredPlatforms(cwd);
+    const configuredNames = [...configuredPlatforms]
+        .map((id) => AI_TOOLS[id].name)
+        .join(", ");
+    // Determine explicit platform flags
+    const explicitTools = TOOLS.filter((t) => options[t.key]).map((t) => t.key);
+    let doAddPlatforms = explicitTools.length > 0;
+    let doAddDeveloper = !!options.user;
+    let platformsToAdd = explicitTools;
+    // No explicit flags → show menu
+    if (!doAddPlatforms && !doAddDeveloper) {
+        if (options.yes) {
+            console.log(chalk.gray(`Already initialized with: ${configuredNames}`));
+            console.log(chalk.gray("Use platform flags (e.g., --codex) or -u <name> to add platforms/developer."));
+            return true;
+        }
+        console.log(chalk.gray(`\n   Already initialized with: ${configuredNames}\n`));
+        const { action } = await inquirer.prompt([
+            {
+                type: "list",
+                name: "action",
+                message: "Trellis is already initialized. What would you like to do?",
+                choices: [
+                    { name: "Add AI platform(s)", value: "add-platform" },
+                    {
+                        name: "Set up developer identity on this device",
+                        value: "add-developer",
+                    },
+                    { name: "Full re-initialize", value: "full" },
+                ],
+            },
+        ]);
+        if (action === "full") {
+            return false; // Fall through to full init
+        }
+        if (action === "add-platform")
+            doAddPlatforms = true;
+        if (action === "add-developer")
+            doAddDeveloper = true;
+    }
+    // --- Add platforms ---
+    if (doAddPlatforms) {
+        if (platformsToAdd.length === 0) {
+            // Interactive: show only unconfigured platforms
+            const unconfigured = TOOLS.filter((t) => {
+                const pid = resolveCliFlag(t.key);
+                return pid && !configuredPlatforms.has(pid);
+            });
+            if (unconfigured.length === 0) {
+                console.log(chalk.green("✓ All available platforms are already configured."));
+            }
+            else {
+                const answers = await inquirer.prompt([
+                    {
+                        type: "checkbox",
+                        name: "tools",
+                        message: "Select platforms to add:",
+                        choices: unconfigured.map((t) => ({
+                            name: t.name,
+                            value: t.key,
+                        })),
+                    },
+                ]);
+                platformsToAdd = answers.tools;
+            }
+        }
+        const reinitWritten = startRecordingWrites(cwd);
+        try {
+            for (const tool of platformsToAdd) {
+                const platformId = resolveCliFlag(tool);
+                if (platformId) {
+                    if (configuredPlatforms.has(platformId)) {
+                        console.log(chalk.gray(`  ○ ${AI_TOOLS[platformId].name} already configured, skipping`));
+                    }
+                    else {
+                        console.log(chalk.blue(`📝 Configuring ${AI_TOOLS[platformId].name}...`));
+                        await configurePlatform(platformId, cwd);
+                    }
+                }
+            }
+        }
+        finally {
+            stopRecordingWrites();
+        }
+        if (platformsToAdd.some((tool) => resolveCliFlag(tool) === "cursor")) {
+            logCursor2plusSetupHint();
+        }
+        // Update template hashes. Merge mode: preserve previously-tracked
+        // platforms' hashes, layer in the newly-added platform's writes.
+        const hashedCount = initializeHashes(cwd, {
+            trackedPaths: reinitWritten,
+            merge: true,
+        });
+        if (hashedCount > 0) {
+            console.log(chalk.gray(`📋 Tracking ${hashedCount} template files for updates`));
+        }
+    }
+    // --- Add developer ---
+    if (doAddDeveloper) {
+        let devName = developerName;
+        if (!devName) {
+            devName = await askInput("Your name: ");
+            while (!devName) {
+                console.log(chalk.yellow("Name is required"));
+                devName = await askInput("Your name: ");
+            }
+        }
+        // Capture pre-init state: if .developer did not exist before we ran
+        // init_developer.py, this checkout had no identity → treat as a new
+        // joiner onboarding onto an existing Trellis project.
+        const hadDeveloperFileBefore = fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW, FILE_NAMES.DEVELOPER));
+        try {
+            const scriptPath = path.join(cwd, PATHS.SCRIPTS, "init_developer.py");
+            execSync(`${pythonCmd} "${scriptPath}" "${devName}"`, {
+                cwd,
+                stdio: "pipe",
+            });
+            console.log(chalk.green(`✓ Developer "${devName}" initialized`));
+        }
+        catch {
+            console.log(chalk.yellow("⚠ Could not initialize developer. Run manually:"));
+            console.log(chalk.gray(`  ${pythonCmd} .trellis/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.
+        if (!hadDeveloperFileBefore) {
+            try {
+                if (!createJoinerOnboardingTask(cwd, devName, pythonCmd)) {
+                    console.warn(chalk.yellow("⚠ Failed to create joiner onboarding task"));
+                }
+            }
+            catch (err) {
+                console.warn(chalk.yellow(`⚠ Joiner onboarding setup failed: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
+    }
+    return true;
+}
+const _cliFlagCheck = true;
+/**
+ * Write monorepo package configuration to config.yaml (non-destructive patch).
+ * Appends packages: and default_package: without disturbing existing config.
+ */
+function writeMonorepoConfig(cwd, packages) {
+    const configPath = path.join(cwd, DIR_NAMES.WORKFLOW, "config.yaml");
+    let content = "";
+    try {
+        content = fs.readFileSync(configPath, "utf-8");
+    }
+    catch {
+        // Config not created yet; will be created by createWorkflowStructure
+        return;
+    }
+    // Don't overwrite if packages: already exists (re-init case)
+    if (/^packages\s*:/m.test(content)) {
+        return;
+    }
+    const lines = ["\n# Auto-detected monorepo packages", "packages:"];
+    for (const pkg of packages) {
+        lines.push(`  ${sanitizePkgName(pkg.name)}:`);
+        lines.push(`    path: ${pkg.path}`);
+        if (pkg.isSubmodule) {
+            lines.push("    type: submodule");
+        }
+        else if (pkg.isGitRepo) {
+            lines.push("    git: true");
+        }
+    }
+    // Use first non-submodule package as default, fallback to first package
+    const defaultPkg = packages.find((p) => !p.isSubmodule)?.name ?? packages[0]?.name;
+    if (defaultPkg) {
+        lines.push(`default_package: ${defaultPkg}`);
+    }
+    fs.writeFileSync(configPath, content.trimEnd() + "\n" + lines.join("\n") + "\n", "utf-8");
+}
+async function checkSmartSearchReadinessForInit(options) {
+    const skipReadinessCommand = "trellis init --skip-readiness";
+    try {
+        checkSmartSearchReadiness({
+            skipReadiness: options.skipReadiness,
+            skipReadinessCommand,
+        });
+        return;
+    }
+    catch (error) {
+        if (!options.interactive || options.skipReadiness) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(chalk.yellow(message));
+        const answer = await inquirer.prompt([
+            {
+                type: "list",
+                name: "smartSearchSetupAction",
+                message: "Smart Search provider configuration is missing or not ready. What should Trellis do?",
+                choices: [
+                    {
+                        name: "Run `smart-search setup` now, then re-check readiness",
+                        value: "setup",
+                    },
+                    {
+                        name: "Abort init so I can configure Smart Search manually",
+                        value: "abort",
+                    },
+                ],
+                default: "setup",
+            },
+        ]);
+        if (answer.smartSearchSetupAction !== "setup") {
+            throw error;
+        }
+        console.log(chalk.blue("🔧 Running smart-search setup..."));
+        try {
+            execSync("smart-search setup", { stdio: "inherit" });
+        }
+        catch (setupError) {
+            const setupMessage = setupError instanceof Error ? setupError.message : String(setupError);
+            throw new Error([
+                "Smart Search setup failed.",
+                `Details: ${setupMessage}`,
+                "Recovery:",
+                "  smart-search setup",
+                `  ${skipReadinessCommand}`,
+            ].join("\n"));
+        }
+        checkSmartSearchReadiness({
+            skipReadiness: false,
+            skipReadinessCommand,
+        });
+    }
+}
+async function checkProjectCapabilityReadinessForInit(options) {
+    const skipReadinessCommand = "trellis init --skip-readiness";
+    try {
+        checkProjectCapabilityReadiness({
+            cwd: options.cwd,
+            selected: options.selected,
+            skipReadiness: options.skipReadiness,
+            skipReadinessCommand,
+        });
+        return;
+    }
+    catch (error) {
+        if (!options.interactive || options.skipReadiness) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(chalk.yellow(message));
+        const answer = await inquirer.prompt([
+            {
+                type: "list",
+                name: "capabilitySetupAction",
+                message: "Selected project capability readiness failed. Fix setup/config outside Trellis, then choose whether to re-check.",
+                choices: [
+                    {
+                        name: "I have fixed the selected capability setup/config; re-check readiness",
+                        value: "recheck",
+                    },
+                    {
+                        name: "Abort init without writing project files",
+                        value: "abort",
+                    },
+                ],
+                default: "recheck",
+            },
+        ]);
+        if (answer.capabilitySetupAction !== "recheck") {
+            throw error;
+        }
+        checkProjectCapabilityReadiness({
+            cwd: options.cwd,
+            selected: options.selected,
+            skipReadiness: false,
+            skipReadinessCommand,
+        });
+    }
+}
+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.
+    if (isCwdHomedir() && !homedirBypassEnabled()) {
+        console.error(chalk.red(homedirGuardMessage("init")));
+        process.exit(1);
+    }
+    const cwd = process.cwd();
+    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".
+    const hadDeveloperFileAtStart = fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW, FILE_NAMES.DEVELOPER));
+    // Generate ASCII art banner dynamically using FIGlet "Rebel" font
+    const banner = figlet.textSync("Trellis", { font: "Rebel" });
+    console.log(chalk.cyan(`\n${banner.trimEnd()}`));
+    console.log(chalk.gray("\n   All-in-one AI framework & toolkit for Codex, Claude Code & Cursor\n"));
+    // Set up proxy before any network calls
+    const proxyUrl = setupProxy();
+    if (proxyUrl) {
+        console.log(chalk.gray(`   Using proxy: ${maskProxyUrl(proxyUrl)}\n`));
+    }
+    // Set write mode based on options
+    let writeMode = "ask";
+    if (options.force) {
+        writeMode = "force";
+        console.log(chalk.gray("Mode: Force overwrite existing files\n"));
+    }
+    else if (options.skipExisting) {
+        writeMode = "skip";
+        console.log(chalk.gray("Mode: Skip existing files\n"));
+    }
+    else if (options.yes) {
+        // -y implies non-interactive: never prompt on conflicts. Default to skip
+        // (preserve user files) — explicit --force is required to overwrite.
+        writeMode = "skip";
+        console.log(chalk.gray("Mode: Non-interactive (skip existing files)\n"));
+    }
+    setWriteMode(writeMode);
+    // Detect developer name from git config or options
+    let developerName = options.user;
+    if (!developerName) {
+        // Only detect from git if current directory is a git repo
+        const isGitRepo = fs.existsSync(path.join(cwd, ".git"));
+        if (isGitRepo) {
+            try {
+                developerName = execSync("git config user.name", {
+                    cwd,
+                    encoding: "utf-8",
+                }).trim();
+            }
+            catch {
+                // Git not available or no user.name configured
+            }
+        }
+    }
+    if (developerName) {
+        console.log(chalk.blue("👤 Developer:"), chalk.gray(developerName));
+    }
+    const { command: pythonCmd } = resolveSupportedPython();
+    // ==========================================================================
+    // Re-init fast path: skip full flow when .trellis/ already exists
+    // ==========================================================================
+    // Aborted-init recovery (issue #204): if .trellis/ 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.
+    const tasksDirEarly = path.join(cwd, PATHS.TASKS);
+    const tasksEmptyEarly = !fs.existsSync(tasksDirEarly) || fs.readdirSync(tasksDirEarly).length === 0;
+    if (!isFirstInit &&
+        !options.force &&
+        !options.skipExisting &&
+        !tasksEmptyEarly) {
+        const reinitDone = await handleReinit(cwd, options, developerName, pythonCmd);
+        if (reinitDone)
+            return;
+        // reinitDone === false means user chose "full re-initialize" → fall through
+    }
+    if (!developerName && !options.yes) {
+        // Ask for developer name if not detected and not in yes mode
+        console.log(chalk.gray("\nTrellis supports team collaboration - each developer has their own\n" +
+            `workspace directory (${PATHS.WORKSPACE}/{name}/) to track AI sessions.\n` +
+            "Tip: Usually this is your git username (git config user.name).\n"));
+        developerName = await askInput("Your name: ");
+        while (!developerName) {
+            console.log(chalk.yellow("Name is required"));
+            developerName = await askInput("Your name: ");
+        }
+        console.log(chalk.blue("👤 Developer:"), chalk.gray(developerName));
+    }
+    // Detect project type (silent - no output)
+    const detectedType = detectProjectType(cwd);
+    // Parse custom registry source early (needed by both monorepo + single-repo flows)
+    let registry;
+    if (options.registry) {
+        try {
+            registry = parseRegistrySource(options.registry);
+        }
+        catch (error) {
+            console.log(chalk.red(error instanceof Error ? error.message : "Invalid registry source"));
+            return;
+        }
+    }
+    // Determine template strategy from flags (needed before monorepo template downloads)
+    let templateStrategy = "skip";
+    if (options.overwrite) {
+        templateStrategy = "overwrite";
+    }
+    else if (options.append) {
+        templateStrategy = "append";
+    }
+    // ==========================================================================
+    // Monorepo Detection
+    // ==========================================================================
+    let monorepoPackages;
+    let remoteSpecPackages;
+    if (options.monorepo !== false) {
+        // options.monorepo: true = --monorepo, false = --no-monorepo, undefined = auto
+        const detected = detectMonorepo(cwd);
+        if (options.monorepo === true && !detected) {
+            console.log(chalk.red("Error: --monorepo specified but no multi-package layout detected."));
+            console.log("");
+            console.log(chalk.gray("Checked:"));
+            console.log(chalk.gray("  ✗ pnpm-workspace.yaml"));
+            console.log(chalk.gray("  ✗ package.json workspaces"));
+            console.log(chalk.gray("  ✗ Cargo.toml [workspace]"));
+            console.log(chalk.gray("  ✗ go.work"));
+            console.log(chalk.gray("  ✗ pyproject.toml [tool.uv.workspace]"));
+            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("");
+            console.log(chalk.cyan("  packages:"));
+            console.log(chalk.cyan("    frontend:"));
+            console.log(chalk.cyan("      path: ./frontend"));
+            console.log(chalk.cyan("      git: true       # if it has its own .git"));
+            console.log(chalk.cyan("    backend:"));
+            console.log(chalk.cyan("      path: ./backend"));
+            console.log(chalk.cyan("      git: true"));
+            return;
+        }
+        if (detected && detected.length > 0) {
+            let enableMonorepo = false;
+            if (options.monorepo === true || options.yes) {
+                enableMonorepo = true;
+            }
+            else {
+                // Show detected packages and ask
+                console.log(chalk.blue("\n🔍 Detected monorepo packages:"));
+                for (const pkg of detected) {
+                    const tag = pkg.isSubmodule
+                        ? chalk.gray(" (submodule)")
+                        : pkg.isGitRepo
+                            ? chalk.gray(" (git repo)")
+                            : "";
+                    console.log(chalk.gray(`   - ${pkg.name}`) +
+                        chalk.gray(` (${pkg.path})`) +
+                        chalk.gray(` [${pkg.type}]`) +
+                        tag);
+                }
+                console.log("");
+                const { useMonorepo } = await inquirer.prompt([
+                    {
+                        type: "confirm",
+                        name: "useMonorepo",
+                        message: "Enable monorepo mode?",
+                        default: true,
+                    },
+                ]);
+                enableMonorepo = useMonorepo;
+            }
+            if (enableMonorepo) {
+                monorepoPackages = detected;
+                remoteSpecPackages = new Set();
+                // Per-package template selection (unless -y mode: all use blank spec)
+                if (!options.yes && !options.template) {
+                    for (const pkg of detected) {
+                        const { specSource } = await inquirer.prompt([
+                            {
+                                type: "list",
+                                name: "specSource",
+                                message: `Spec source for ${pkg.name} (${pkg.path}):`,
+                                choices: [
+                                    { name: "From scratch (Trellis default)", value: "blank" },
+                                    { name: "Download remote template", value: "remote" },
+                                ],
+                                default: "blank",
+                            },
+                        ]);
+                        if (specSource === "remote") {
+                            // Use existing template download flow, targeting spec/<name>/
+                            const destDir = path.join(cwd, PATHS.SPEC, sanitizePkgName(pkg.name));
+                            console.log(chalk.blue(`📦 Select template for ${pkg.name}...`));
+                            // Fetch templates if not already done
+                            const templates = await fetchTemplateIndex();
+                            const specTemplates = templates
+                                .filter((t) => t.type === "spec")
+                                .map((t) => ({
+                                name: `${t.id} (${t.name})`,
+                                value: t.id,
+                            }));
+                            if (specTemplates.length > 0) {
+                                const { templateId } = await inquirer.prompt([
+                                    {
+                                        type: "list",
+                                        name: "templateId",
+                                        message: `Select template for ${pkg.name}:`,
+                                        choices: specTemplates,
+                                    },
+                                ]);
+                                const result = await downloadTemplateById(cwd, templateId, templateStrategy, templates.find((t) => t.id === templateId), undefined, destDir);
+                                if (result.success) {
+                                    console.log(chalk.green(`   ${result.message}`));
+                                    remoteSpecPackages.add(sanitizePkgName(pkg.name));
+                                }
+                                else {
+                                    console.log(chalk.yellow(`   ${result.message}`));
+                                    console.log(chalk.gray("   Falling back to blank spec..."));
+                                }
+                            }
+                            else {
+                                console.log(chalk.gray("   No templates available. Using blank spec."));
+                            }
+                        }
+                    }
+                }
+                else if (options.template) {
+                    // --template as default for all packages
+                    for (const pkg of detected) {
+                        const destDir = path.join(cwd, PATHS.SPEC, sanitizePkgName(pkg.name));
+                        const result = await downloadTemplateById(cwd, options.template, templateStrategy, undefined, registry, destDir);
+                        if (result.success && !result.skipped) {
+                            remoteSpecPackages.add(sanitizePkgName(pkg.name));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Tool definitions derived from platform registry
+    const TOOLS = getInitToolChoices();
+    // Build tools from explicit flags
+    const explicitTools = TOOLS.filter((t) => options[t.key]).map((t) => t.key);
+    let tools;
+    if (explicitTools.length > 0) {
+        // Explicit flags take precedence (works with or without -y)
+        tools = explicitTools;
+    }
+    else if (options.yes) {
+        // No explicit tools + -y: default to Cursor and Claude
+        tools = TOOLS.filter((t) => t.defaultChecked).map((t) => t.key);
+    }
+    else {
+        // Interactive mode
+        const answers = await inquirer.prompt([
+            {
+                type: "checkbox",
+                name: "tools",
+                message: "Select AI tools to configure:",
+                choices: TOOLS.map((t) => ({
+                    name: t.name,
+                    value: t.key,
+                    checked: t.defaultChecked,
+                })),
+            },
+        ]);
+        tools = answers.tools;
+    }
+    // Treat unknown project type as fullstack
+    const projectType = detectedType === "unknown" ? "fullstack" : detectedType;
+    if (tools.length === 0) {
+        console.log(chalk.yellow("No tools selected. At least one tool is required."));
+        return;
+    }
+    const explicitCapabilities = parseProjectCapabilities(options.capability);
+    let selectedCapabilities = explicitCapabilities;
+    if (!options.yes && !options.capability?.length) {
+        const capabilityAnswers = await inquirer.prompt([
+            {
+                type: "checkbox",
+                name: "capabilities",
+                message: "Select optional project capabilities:",
+                choices: getProjectCapabilityChoices().map((choice) => ({
+                    name: choice.name,
+                    value: choice.id,
+                    checked: false,
+                })),
+            },
+        ]);
+        selectedCapabilities = capabilityAnswers.capabilities ?? [];
+    }
+    await checkSmartSearchReadinessForInit({
+        interactive: !options.yes,
+        skipReadiness: options.skipReadiness,
+    });
+    await checkProjectCapabilityReadinessForInit({
+        cwd,
+        selected: selectedCapabilities,
+        interactive: !options.yes,
+        skipReadiness: options.skipReadiness,
+    });
+    // ==========================================================================
+    // Template Selection (single-repo only; monorepo handles templates above)
+    // ==========================================================================
+    let selectedTemplate = null;
+    // Pre-fetched templates list (used to pass selected SpecTemplate to downloadTemplateById)
+    let fetchedTemplates = [];
+    let registryBackend;
+    // Determine the index URL based on registry
+    const indexUrl = registry
+        ? `${registry.rawBaseUrl}/index.json`
+        : TEMPLATE_INDEX_URL;
+    if (monorepoPackages) {
+        // Monorepo: template selection already handled above
+    }
+    else if (options.template) {
+        // Template specified via --template flag
+        selectedTemplate = options.template;
+    }
+    else if (!options.yes) {
+        // Interactive mode: show template selection
+        const timeoutSec = TIMEOUTS.INDEX_FETCH_MS / 1000;
+        const sourceLabel = registry ? registry.gigetSource : TEMPLATE_INDEX_URL;
+        console.log(chalk.gray(`   Fetching available templates from ${sourceLabel}`));
+        let elapsed = 0;
+        const ticker = setInterval(() => {
+            elapsed++;
+            process.stdout.write(`\r${chalk.gray(`   Loading... ${elapsed}s/${timeoutSec}s`)}`);
+        }, 1000);
+        process.stdout.write(chalk.gray(`   Loading... 0s/${timeoutSec}s`));
+        let templates;
+        let registryProbeNotFound = false;
+        let registryProbeError;
+        if (registry) {
+            const probeResult = await probeRegistryIndex(indexUrl, registry);
+            templates = probeResult.templates;
+            registryProbeNotFound = probeResult.isNotFound;
+            registryProbeError = probeResult.error;
+            registryBackend = probeResult.backend;
+        }
+        else {
+            templates = await fetchTemplateIndex(indexUrl);
+        }
+        clearInterval(ticker);
+        // Clear the loading line
+        process.stdout.write("\r\x1b[2K");
+        fetchedTemplates = templates;
+        if (templates.length === 0 && registry && registryProbeNotFound) {
+            // Custom registry: confirmed no index.json — will try direct download later
+            console.log(chalk.gray("   No index.json found at registry. Will download as direct spec template."));
+        }
+        else if (templates.length === 0 && registry) {
+            // Custom registry: transient error (not a 404) — abort, don't misclassify
+            console.log(chalk.red(`   ${registryProbeError?.message ?? "Could not reach registry. Check your connection and try again."}`));
+            return;
+        }
+        else if (templates.length === 0) {
+            console.log(chalk.gray("   Could not fetch templates (offline or server unavailable)."));
+            console.log(chalk.gray("   Using blank templates.\n"));
+        }
+        if (templates.length > 0) {
+            // Build template choices
+            const specTemplates = templates
+                .filter((t) => t.type === "spec")
+                .map((t) => ({
+                name: `${t.id} (${t.name})`,
+                value: t.id,
+            }));
+            const templateChoices = registry
+                ? specTemplates
+                : [
+                    {
+                        name: "from scratch (default)",
+                        value: "blank",
+                    },
+                    ...specTemplates,
+                    {
+                        name: "custom (enter a registry source)",
+                        value: "__custom__",
+                    },
+                ];
+            // Loop to allow returning from custom source input back to the picker
+            let templatePicked = false;
+            while (templateChoices.length > 0 && !templatePicked) {
+                const templateAnswer = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "template",
+                        message: "Select a spec template:",
+                        choices: templateChoices,
+                        default: registry ? undefined : "blank",
+                    },
+                ]);
+                if (templateAnswer.template === "__custom__") {
+                    // Prompt for custom registry source (empty → back to picker)
+                    const customSource = await askInput("Enter registry source (e.g., gh:myorg/myrepo/specs), or press Enter to go back: ");
+                    if (!customSource) {
+                        continue; // Back to picker
+                    }
+                    try {
+                        registry = parseRegistrySource(customSource);
+                        fetchedTemplates = []; // Reset so direct-download guard works correctly
+                        // Probe index.json to detect marketplace vs direct download
+                        const customIndexUrl = `${registry.rawBaseUrl}/index.json`;
+                        console.log(chalk.gray(`   Checking for templates at ${registry.gigetSource}...`));
+                        const customProbe = await probeRegistryIndex(customIndexUrl, registry);
+                        const customTemplates = customProbe.templates;
+                        registryBackend = customProbe.backend;
+                        if (customTemplates.length > 0) {
+                            // Marketplace mode: show picker with custom templates
+                            fetchedTemplates = customTemplates;
+                            const customChoices = customTemplates
+                                .filter((t) => t.type === "spec")
+                                .map((t) => ({
+                                name: `${t.id} (${t.name})`,
+                                value: t.id,
+                            }));
+                            if (customChoices.length > 0) {
+                                const customAnswer = await inquirer.prompt([
+                                    {
+                                        type: "list",
+                                        name: "template",
+                                        message: "Select a spec template:",
+                                        choices: customChoices,
+                                    },
+                                ]);
+                                selectedTemplate = customAnswer.template;
+                                // Check if spec directory already exists and ask what to do
+                                const specDir = path.join(cwd, PATHS.SPEC);
+                                if (fs.existsSync(specDir) &&
+                                    !options.overwrite &&
+                                    !options.append) {
+                                    const actionAnswer = await inquirer.prompt([
+                                        {
+                                            type: "list",
+                                            name: "action",
+                                            message: `Directory ${PATHS.SPEC} already exists. What do you want to do?`,
+                                            choices: [
+                                                { name: "Skip (keep existing)", value: "skip" },
+                                                {
+                                                    name: "Overwrite (replace all)",
+                                                    value: "overwrite",
+                                                },
+                                                {
+                                                    name: "Append (add missing files only)",
+                                                    value: "append",
+                                                },
+                                            ],
+                                            default: "skip",
+                                        },
+                                    ]);
+                                    templateStrategy = actionAnswer.action;
+                                }
+                            }
+                            templatePicked = true;
+                        }
+                        else if (customProbe.isNotFound) {
+                            // No index.json → direct download mode
+                            templatePicked = true;
+                        }
+                        else {
+                            // Transient error (not 404) — loop back, don't misclassify
+                            console.log(chalk.yellow(`   ${customProbe.error?.message ?? "Could not reach registry. Try again or enter a different source."}`));
+                            registry = undefined; // Reset so we don't fall through to direct download
+                        }
+                    }
+                    catch (error) {
+                        console.log(chalk.red(error instanceof Error
+                            ? error.message
+                            : "Invalid registry source"));
+                        // Loop back to picker
+                    }
+                }
+                else {
+                    templatePicked = true;
+                    if (templateAnswer.template !== "blank") {
+                        selectedTemplate = templateAnswer.template;
+                        // Check if spec directory already exists and ask what to do
+                        const specDir = path.join(cwd, PATHS.SPEC);
+                        if (fs.existsSync(specDir) &&
+                            !options.overwrite &&
+                            !options.append) {
+                            const actionAnswer = await inquirer.prompt([
+                                {
+                                    type: "list",
+                                    name: "action",
+                                    message: `Directory ${PATHS.SPEC} already exists. What do you want to do?`,
+                                    choices: [
+                                        { name: "Skip (keep existing)", value: "skip" },
+                                        { name: "Overwrite (replace all)", value: "overwrite" },
+                                        {
+                                            name: "Append (add missing files only)",
+                                            value: "append",
+                                        },
+                                    ],
+                                    default: "skip",
+                                },
+                            ]);
+                            templateStrategy = actionAnswer.action;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // -y mode with --registry (no --template): probe index.json to detect mode
+    // Skip when monorepo mode already handled templates above
+    if (options.yes && registry && !selectedTemplate && !monorepoPackages) {
+        const probeResult = await probeRegistryIndex(`${registry.rawBaseUrl}/index.json`, registry);
+        registryBackend = probeResult.backend;
+        if (probeResult.templates.length > 0) {
+            // Marketplace mode requires interactive selection — can't auto-select
+            console.log(chalk.red("Error: Registry is a marketplace with multiple templates. " +
+                "Use --template <id> to specify which one, or remove -y for interactive selection."));
+            return;
+        }
+        if (!probeResult.isNotFound) {
+            // Transient error (not 404) — abort, don't misclassify as direct-download
+            console.log(chalk.red(`Error: ${probeResult.error?.message ?? "Could not reach registry. Check your connection and try again."}`));
+            return;
+        }
+        // isNotFound=true → no index.json, proceed with direct download (fetchedTemplates stays empty)
+    }
+    // ==========================================================================
+    // Download Remote Template (if selected or direct registry download)
+    // ==========================================================================
+    let useRemoteTemplate = false;
+    if (selectedTemplate) {
+        // Marketplace mode: download specific template by ID
+        console.log(chalk.blue(`📦 Downloading template "${selectedTemplate}"...`));
+        console.log(chalk.gray("   This may take a moment on slow connections."));
+        // Find pre-fetched SpecTemplate to avoid double-fetch
+        const prefetched = fetchedTemplates.find((t) => t.id === selectedTemplate);
+        const result = await downloadTemplateById(cwd, selectedTemplate, templateStrategy, prefetched, registry, undefined, registryBackend);
+        if (result.success) {
+            if (result.skipped) {
+                console.log(chalk.gray(`   ${result.message}`));
+            }
+            else {
+                console.log(chalk.green(`   ${result.message}`));
+                useRemoteTemplate = true;
+            }
+        }
+        else {
+            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}`;
+            console.log(chalk.gray(`   You can retry later: ${retryCmd}`));
+        }
+    }
+    else if (registry && fetchedTemplates.length === 0) {
+        // Direct download mode: registry has no index.json, download directory directly
+        console.log(chalk.blue(`📦 Downloading spec from ${registry.gigetSource}...`));
+        console.log(chalk.gray("   This may take a moment on slow connections."));
+        // Ask about existing spec dir in interactive mode
+        if (!options.yes && !options.overwrite && !options.append) {
+            const specDir = path.join(cwd, PATHS.SPEC);
+            if (fs.existsSync(specDir)) {
+                const actionAnswer = await inquirer.prompt([
+                    {
+                        type: "list",
+                        name: "action",
+                        message: `Directory ${PATHS.SPEC} already exists. What do you want to do?`,
+                        choices: [
+                            { name: "Skip (keep existing)", value: "skip" },
+                            { name: "Overwrite (replace all)", value: "overwrite" },
+                            { name: "Append (add missing files only)", value: "append" },
+                        ],
+                        default: "skip",
+                    },
+                ]);
+                templateStrategy = actionAnswer.action;
+            }
+        }
+        const result = await downloadRegistryDirect(cwd, registry, templateStrategy, undefined, registryBackend);
+        if (result.success) {
+            if (result.skipped) {
+                console.log(chalk.gray(`   ${result.message}`));
+            }
+            else {
+                console.log(chalk.green(`   ${result.message}`));
+                useRemoteTemplate = true;
+            }
+        }
+        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}`));
+        }
+    }
+    // ==========================================================================
+    // Resolve workflow template (default: native bundled)
+    // ==========================================================================
+    const workflowIdInput = options.workflow?.trim();
+    const workflowId = workflowIdInput && workflowIdInput.length > 0
+        ? workflowIdInput
+        : NATIVE_WORKFLOW_ID;
+    let workflowMdOverride;
+    if (workflowId !== NATIVE_WORKFLOW_ID || options.workflowSource) {
+        const resolved = await resolveWorkflowTemplate(workflowId, {
+            source: options.workflowSource,
+        });
+        if (resolved.id !== NATIVE_WORKFLOW_ID) {
+            workflowMdOverride = resolved.content;
+            console.log(chalk.blue(`🧭 Using workflow template: ${chalk.cyan(resolved.id)}`));
+        }
+    }
+    // ==========================================================================
+    // Create Workflow Structure
+    // ==========================================================================
+    // Record every successful write from here through createRootFiles. The
+    // captured set is the source of truth for `.template-hashes.json`'s
+    // platform/root entries — replacing the previous "walk every managed dir"
+    // approach that swept user-owned runtime files into the manifest
+    // (.codex/sessions/, .claude/projects/, pre-existing AGENTS.md).
+    const writtenPaths = startRecordingWrites(cwd);
+    try {
+        // Determine whether to materialize the Cursor++ BYOK local bundle.
+        // Default off from 1.1.0; only ask when Cursor is selected in
+        // interactive mode. --yes / non-interactive skips the question and
+        // does NOT write the bundle unless --cursor2plus is passed.
+        let cursor2plusOptIn = options.cursor2plus === true;
+        const cursorSelected = tools.includes("cursor");
+        if (cursorSelected && !options.yes && !cursor2plusOptIn) {
+            const byok = await inquirer.prompt([
+                {
+                    type: "confirm",
+                    name: "byok",
+                    message: "使用 Cursor++ BYOK 代理？（原生 Cursor API 用户选 No；仅 BYOK 需要 .trellis/local/cursor2plus/）",
+                    default: false,
+                },
+            ]);
+            cursor2plusOptIn = byok.byok;
+        }
+        // Create workflow structure with project type
+        console.log(chalk.blue("📁 Creating workflow structure..."));
+        await createWorkflowStructure(cwd, {
+            projectType,
+            skipSpecTemplates: useRemoteTemplate,
+            cursor2plus: cursor2plusOptIn,
+            packages: monorepoPackages,
+            remoteSpecPackages,
+            workflowMdOverride,
+        });
+        // Write monorepo packages to config.yaml (non-destructive patch)
+        if (monorepoPackages) {
+            writeMonorepoConfig(cwd, monorepoPackages);
+            console.log(chalk.blue("📦 Monorepo packages written to config.yaml"));
+        }
+        // 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)
+        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);
+            }
+        }
+        await writeProjectCapabilityFiles(cwd, selectedCapabilities, selectedPlatformIds);
+        const pythonPlatforms = getPlatformsWithPythonHooks();
+        const hasSelectedPythonPlatform = pythonPlatforms.some((id) => tools.includes(AI_TOOLS[id].cliFlag));
+        if (hasSelectedPythonPlatform) {
+            logPythonAdaptationNotice(pythonCmd);
+        }
+        if (cursor2plusOptIn) {
+            logCursor2plusSetupHint();
+        }
+        // Create root files (skip if exists)
+        await createRootFiles(cwd);
+    }
+    finally {
+        stopRecordingWrites();
+    }
+    // Initialize template hashes for modification tracking
+    const hashedCount = initializeHashes(cwd, { trackedPaths: writtenPaths });
+    if (hashedCount > 0) {
+        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
+    // modified and does not silently restore native bytes. See design.md
+    // "Durable-state contract".
+    if (workflowMdOverride !== undefined && workflowId !== NATIVE_WORKFLOW_ID) {
+        removeHash(cwd, PATHS.WORKFLOW_GUIDE_FILE);
+    }
+    // Initialize developer identity (silent - no output)
+    if (developerName) {
+        try {
+            const scriptPath = path.join(cwd, PATHS.SCRIPTS, "init_developer.py");
+            execSync(`${pythonCmd} "${scriptPath}" "${developerName}"`, {
+                cwd,
+                stdio: "pipe", // Silent
+            });
+        }
+        catch {
+            // Silent failure - user can run init_developer.py manually
+        }
+        // Three-branch dispatch using flags captured at init() start (before
+        // createWorkflowStructure/init_developer ran, so they reflect the disk
+        // state of the user's checkout, not the state this init just produced):
+        //   isFirstInit=true                       → creator bootstrap (new project)
+        //   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
+        // empty, the previous init aborted before creating the bootstrap task. Run
+        // bootstrap creation regardless of isFirstInit. writeTaskSkeleton is
+        // idempotent so repeated triggers are safe.
+        //
+        // Runs OUTSIDE the init_developer try/catch (which uses stdio: "pipe")
+        // so joiner failures surface as warnings instead of being silently
+        // swallowed.
+        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);
+        }
+        else if (!hadDeveloperFileAtStart) {
+            try {
+                if (!createJoinerOnboardingTask(cwd, developerName, pythonCmd)) {
+                    console.warn(chalk.yellow("⚠ Failed to create joiner onboarding task"));
+                }
+            }
+            catch (err) {
+                console.warn(chalk.yellow(`⚠ Joiner onboarding setup failed: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
+    }
+}
+/**
+ * Simple readline-based input (no flickering like inquirer)
+ */
+function askInput(prompt) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function createRootFiles(cwd) {
+    const agentsPath = path.join(cwd, FILE_NAMES.AGENTS);
+    // Write AGENTS.md from template
+    const agentsWritten = await writeFile(agentsPath, agentsMdContent);
+    if (agentsWritten) {
+        console.log(chalk.blue("📄 Created AGENTS.md"));
+    }
+}
+//# sourceMappingURL=init.js.map