teamix-evo 0.7.0 → 0.9.0

package/README.md

@@ -167,30 +167,36 @@ TEAMIX_DEBUG=1 teamix-evo tokens init opentrek
 
 ## 命令参考
 
-| 命令                                                | 说明                                                           |
-| --------------------------------------------------- | -------------------------------------------------------------- |
-| `teamix-evo tokens init <variant>`                  | 初始化 tokens                                                  |
-| `teamix-evo tokens list-variants`                   | 列出可用 variant                                               |
-| `teamix-evo tokens list`                            | 查看已装机的 variant                                           |
-| `teamix-evo tokens update`                          | 更新已装资源(stub,v0.7 见 ADR 0019)                            |
-| `teamix-evo tokens uninstall`                       | 卸载已装 tokens                                                |
-| `teamix-evo skills init`                            | 自举 skills(按 variant + scope 全装 — ADR 0034)                |
-| `teamix-evo skills add <name...>`                   | 增量装指定 skill(`<name...>` 必填)                             |
-| `teamix-evo skills list`                            | 列出所有 skill 的安装状态                                      |
-| `teamix-evo skills update [name...] [--dry-run]`    | 升级 skills(双闸 + version 短路 — ADR 0035)                    |
-| `teamix-evo skills sync [name...]`                  | 源 → IDE 镜像(漂移恢复用)                                      |
-| `teamix-evo skills doctor`                          | 检测源/镜像漂移(ADR 0013)                                      |
-| `teamix-evo skills uninstall`                       | 卸载 skills(源 + 镜像 + lock)                                  |
-| `teamix-evo ui init`                                | 初始化 ui 配置(aliases / iconLibrary / tsx / rsc)              |
-| `teamix-evo ui add <id...>`                         | 安装指定 ui 组件源码                                           |
-| `teamix-evo ui list [--installed]`                  | 列出可用/已安装 ui 组件                                        |
-| `teamix-evo biz-ui list-variants`                   | 列出 biz-ui 包内提供的业务变体                                 |
-| `teamix-evo biz-ui add <id...> --variant <name>`    | 安装变体感知业务组件(`--variant` 必填)                         |
-| `teamix-evo templates list-variants`                | 列出 templates 包内提供的页面模板变体                          |
-| `teamix-evo templates add <id...> --variant <name>` | 安装变体感知页面模板(`--variant` 必填)                         |
-| `teamix-evo lint init [-y]`                         | 一键安装 ESLint + Stylelint token-discipline 规则集            |
-| `teamix-evo logs analyze [...]`                     | 分析 vibe-logger AI 调用链(`.log/ai/**/*.jsonl`)               |
-| `teamix-evo logs trace [...]`                       | 按会话还原 AI 调用链(prompt → PreToolUse → PostToolUse → Stop) |
+| 命令                                                | 说明                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `teamix-evo init [-y] [--dry-run] [--variant <n>]`  | 普通版接入：检测冲突 → wizard → 静默落地（已有 npm 工程入口）                   |
+| `teamix-evo update [--dry-run] [--cwd <dir>]`       | 一键升级已装资源（tokens + skills，ADR 0003 三态 + ADR 0035 短路）              |
+| `teamix-evo restore [ts] [--list] [-y]`             | 回滚 `.teamix-evo/` 到指定 snapshot（ADR 0019 §2 — 自身可逆）                   |
+| `teamix-evo switch <new-variant> [--apply] [-y]`    | variant 切换：默认 dry-run 展示 file-level diff，--apply 才真写（ADR 0019 §D3） |
+| `teamix-evo tokens init <variant>`                  | 初始化 tokens                                                                   |
+| `teamix-evo tokens list-variants`                   | 列出可用 variant                                                                |
+| `teamix-evo tokens list`                            | 查看已装机的 variant                                                            |
+| `teamix-evo tokens update`                          | 更新已装资源(stub,v0.7 见 ADR 0019)                                             |
+| `teamix-evo tokens uninstall`                       | 卸载已装 tokens                                                                 |
+| `teamix-evo tokens audit`                           | 审计 tokens 引用（4 类：redundant / kept / migrate / custom，v3↔v4 语义比较）   |
+| `teamix-evo skills init`                            | 自举 skills(按 variant + scope 全装 — ADR 0034)                                 |
+| `teamix-evo skills add <name...>`                   | 增量装指定 skill(`<name...>` 必填)                                              |
+| `teamix-evo skills list`                            | 列出所有 skill 的安装状态                                                       |
+| `teamix-evo skills update [name...] [--dry-run]`    | 升级 skills(双闸 + version 短路 — ADR 0035)                                     |
+| `teamix-evo skills sync [name...]`                  | 源 → IDE 镜像(漂移恢复用)                                                       |
+| `teamix-evo skills doctor`                          | 检测源/镜像漂移(ADR 0013)                                                       |
+| `teamix-evo skills uninstall`                       | 卸载 skills(源 + 镜像 + lock)                                                   |
+| `teamix-evo ui init`                                | 初始化 ui 配置(aliases / iconLibrary / tsx / rsc)                               |
+| `teamix-evo ui add <id...>`                         | 安装指定 ui 组件源码                                                            |
+| `teamix-evo ui list [--installed]`                  | 列出可用/已安装 ui 组件                                                         |
+| `teamix-evo ui promote-to-biz <id...>`              | 把 ui 组件提升为业务组件（8 模式：Coexist/Preset/Wrapper/Compose/Variant/Fork/TokenOnly/ManualReview） |
+| `teamix-evo biz-ui list-variants`                   | 列出 biz-ui 包内提供的业务变体                                                  |
+| `teamix-evo biz-ui add <id...> --variant <name>`    | 安装变体感知业务组件(`--variant` 必填)                                          |
+| `teamix-evo templates list-variants`                | 列出 templates 包内提供的页面模板变体                                           |
+| `teamix-evo templates add <id...> --variant <name>` | 安装变体感知页面模板(`--variant` 必填)                                          |
+| `teamix-evo lint init [-y]`                         | 一键安装 ESLint + Stylelint token-discipline 规则集                             |
+| `teamix-evo logs analyze [...]`                     | 分析 vibe-logger AI 调用链(`.log/ai/**/*.jsonl`)                                |
+| `teamix-evo logs trace [...]`                       | 按会话还原 AI 调用链(prompt → PreToolUse → PostToolUse → Stop)                  |
 
 > 占位组件 → 真组件的升级流程**不是** CLI 子命令，由
 > [`teamix-evo-manage`](../../packages/skills/src/teamix-evo-manage/SKILL.md)

package/dist/core/index.d.ts

@@ -103,6 +103,13 @@ type RunSkillsInitResult = {
     resources: InstalledResource[];
     addedSkillIds: string[];
     skippedSkillIds: string[];
+    /**
+     * Always `[]` for `runSkillsInit` — bulk bootstrap deliberately does not
+     * surface upgrade hints (only `runSkillsAdd` does, ADR 0034). Kept on
+     * the type so the result shape stays consistent with `RunSkillsAddResult`
+     * and `finalizeSkillsInstall`'s return.
+     */
+    outdatedSkills: OutdatedSkillInfo[];
 } | {
     /** Returned when a skills package is already installed and bulk has nothing new to add. */
     status: 'already-initialized';
@@ -133,6 +140,18 @@ interface RunSkillsAddOptions {
     /** Override the skills package name (defaults to "@teamix-evo/skills"). */
     packageName?: string;
 }
+/**
+ * Detail for an already-installed skill whose locked version is older than
+ * the manifest's latest version. Use `skills update <id>` to upgrade.
+ */
+interface OutdatedSkillInfo {
+    /** Skill id */
+    id: string;
+    /** Version recorded in `.teamix-evo/skills.lock.json` */
+    installed: string;
+    /** Version available in the upstream manifest (i.e. `npx` resolved `@latest`) */
+    latest: string;
+}
 type RunSkillsAddResult = {
     status: 'installed';
     packageName: string;
@@ -147,8 +166,18 @@ type RunSkillsAddResult = {
     resources: InstalledResource[];
     /** Skill ids that were freshly added in this call. */
     addedSkillIds: string[];
-    /** Skill ids that were requested but already installed; skipped. */
+    /**
+     * Skill ids that were requested but already installed at the latest version;
+     * nothing to do. Outdated installs are reported separately via
+     * {@link outdatedSkills}.
+     */
     skippedSkillIds: string[];
+    /**
+     * Skill ids that were requested, are already installed, but whose locked
+     * version is older than the manifest version. Caller should surface a hint
+     * recommending `skills update <id>`.
+     */
+    outdatedSkills: OutdatedSkillInfo[];
 };
 /**
  * Programmatic equivalent of `teamix-evo skills add <names...>` (ADR 0034).
@@ -390,6 +419,15 @@ interface ListVariantUiEntriesResult {
 declare function listBizUiEntries(variant: string, packageRoot?: string): Promise<ListVariantUiEntriesResult>;
 declare function listTemplatesEntries(variant: string, packageRoot?: string): Promise<ListVariantUiEntriesResult>;
 
+/**
+ * Phase 3.E lint conflict strategies (mirrors `init-conflicts.ts`).
+ *
+ * `merge` and `backup-overwrite` both back up the existing user file before
+ * writing the teamix-evo template; `merge` additionally surfaces an AI-assist
+ * hint so the manage / code skill can guide the user through merging custom
+ * rules. `skip` keeps the user's file as-is and emits no template.
+ */
+type LintConflictStrategy = 'merge' | 'backup-overwrite' | 'skip' | 'overwrite';
 interface RunLintInitOptions {
     /** Absolute project root directory. */
     projectRoot: string;
@@ -399,11 +437,43 @@ interface RunLintInitOptions {
      * installed in a later batch step.
      */
     skipInstall?: boolean;
+    /**
+     * Phase 3.E: strategy for handling existing ESLint config files.
+     * Defaults to `'overwrite'` (legacy behaviour); the `init` orchestrator
+     * passes the wizard-resolved value when consumer files are detected.
+     */
+    eslintStrategy?: LintConflictStrategy;
+    /**
+     * Phase 3.E: strategy for handling existing Stylelint config files.
+     */
+    stylelintStrategy?: LintConflictStrategy;
+    /**
+     * Phase 3.E: paths of existing ESLint configs (relative to projectRoot)
+     * to back up. Empty when no consumer config was detected.
+     */
+    eslintExistingPaths?: string[];
+    /**
+     * Phase 3.E: paths of existing Stylelint configs (relative to projectRoot).
+     */
+    stylelintExistingPaths?: string[];
 }
 type RunLintInitResult = {
     status: 'installed';
     eslint: boolean;
     stylelint: boolean;
+    /** True when the user had a custom config and asked for AI-assisted merge. */
+    eslintMergeRequested?: boolean;
+    stylelintMergeRequested?: boolean;
+    /** True when the strategy asked us to keep the user file untouched. */
+    eslintSkipped?: boolean;
+    stylelintSkipped?: boolean;
+    /**
+     * True when `package.json` was actually patched (lint / lint:css
+     * scripts inserted). Powers the project-init change ledger so the
+     * CLI does not report a phantom write when both scripts already
+     * existed.
+     */
+    packageJsonPatched?: boolean;
 } | {
     status: 'already-initialized';
 };
@@ -415,6 +485,443 @@ type RunLintInitResult = {
  */
 declare function runLintInit(options: RunLintInitOptions): Promise<RunLintInitResult>;
 
+/**
+ * Generate `<projectRoot>/AGENTS.md` as a skill-trigger fallback (ADR 0038).
+ *
+ * The file is **regenerable**: it consolidates TRIGGER / SKIP excerpts from
+ * each installed SKILL.md frontmatter description into one terse index, so
+ * AGENTS.md-aware IDEs (Codex / Cursor / Claude Code / Qoder) preheat the
+ * skill activation conditions even when the user prompt does not directly
+ * hit the description-based trigger.
+ *
+ * Out of scope (per ADR 0038):
+ * - Does NOT copy skill body / rules / patterns — those stay in the skill.
+ * - Does NOT include `teamix-evo-manage` (entry skill, global scope, ADR 0033).
+ *
+ * Lifted from `create-teamix-evo` (v0.5) into `teamix-evo/core` so both
+ * `npm create teamix-evo` (scaffold path) and `teamix-evo init` (existing-
+ * project path, ADR 0019 task #5) emit identical AGENTS.md output.
+ *
+ * @module teamix-evo/core/agents-md
+ */
+interface RunGenerateAgentsMdOptions {
+    /** Absolute path to the consumer project root. */
+    projectRoot: string;
+    /** Tokens / skills variant (e.g. "opentrek"). Used for header context. */
+    variant: string;
+    /**
+     * Skill ids whose `<projectRoot>/.teamix-evo/skills/<id>/SKILL.md` should be
+     * indexed. Caller is responsible for filtering out global-only skills
+     * (e.g. `teamix-evo-manage`).
+     */
+    skillIds: string[];
+    /**
+     * Reconciliation mode (Phase 2.B):
+     *   - `'overwrite'` (default): always rewrite the full file. Pre-existing
+     *     content is backed up and discarded.
+     *   - `'merge-managed'`: rewrite only the `teamix-evo-skills` managed
+     *     region. When the consumer file lacks the region, prepend a fresh
+     *     managed block ahead of the user's content (auto-adopt). The user's
+     *     non-managed sections are preserved.
+     *
+     * In both modes, an existing file is backed up under
+     * `.teamix-evo/.backups/AGENTS.md.<isoTs>.bak` before any mutation.
+     */
+    mode?: 'overwrite' | 'merge-managed';
+}
+interface RunGenerateAgentsMdResult {
+    /** Absolute path of the written `AGENTS.md`. */
+    path: string;
+    /** Number of skill sections rendered (missing SKILL.md degradations are still counted). */
+    skillCount: number;
+    /** Skill ids whose SKILL.md could not be read (rendered as degraded section). */
+    missingSkillIds: string[];
+    /**
+     * True when an existing AGENTS.md was backed up under
+     * `.teamix-evo/.backups/AGENTS.md.<isoTs>.bak` before being overwritten
+     * (Phase 1.A2 — full backup strategy).
+     */
+    backedUp: boolean;
+    /**
+     * Outcome of the merge step (Phase 2.B):
+     *   - `'created'`: no AGENTS.md existed; wrote a fresh full template.
+     *   - `'overwritten'`: existed but mode='overwrite' — full rewrite.
+     *   - `'managed-replaced'`: mode='merge-managed' and the consumer file
+     *     already had the `teamix-evo-skills` managed region; only that region
+     *     was rewritten. User content outside is preserved.
+     *   - `'managed-prepended'`: mode='merge-managed' but the consumer file
+     *     did not yet have the managed region; a fresh block was inserted at
+     *     the top, with the existing user content kept below.
+     */
+    merge: 'created' | 'overwritten' | 'managed-replaced' | 'managed-prepended';
+}
+interface SkillDescriptionParts {
+    /** First non-empty line(s) of `description` (the capability statement). */
+    capability: string;
+    trigger: string | null;
+    skip: string | null;
+    coordinates: string | null;
+}
+/**
+ * Generate and write the `AGENTS.md` file.
+ *
+ * Phase 2.B — reconciliation modes:
+ *   - `'overwrite'` (default): regenerable behaviour, full rewrite.
+ *   - `'merge-managed'`: rewrite only the `teamix-evo-skills` managed region
+ *     so user-authored sections (project-specific guidance, design tokens,
+ *     prompts) are never clobbered.
+ *
+ * Existing files are always backed up under `.teamix-evo/.backups/` before
+ * mutation (ADR 0019 §2, Phase 1.A2).
+ */
+declare function runGenerateAgentsMd(options: RunGenerateAgentsMdOptions): Promise<RunGenerateAgentsMdResult>;
+/**
+ * Parse a SKILL.md frontmatter description into capability / TRIGGER / SKIP /
+ * Coordinates parts.
+ *
+ * Why hand-rolled (no gray-matter): we only need the `description: |` block.
+ * The full YAML grammar is overkill and adds a runtime dep to a CLI / scaffold
+ * tool that should stay zero-cost. ADR 0015 keeps frontmatter shape stable.
+ */
+declare function extractDescriptionParts(fileContent: string): SkillDescriptionParts | null;
+
+/**
+ * Three branches of `teamix-evo init` decision tree (ADR 0019 D1).
+ *
+ * - `empty`               : 空目录或仅含可忽略文件 → 推荐用户走 `npm create teamix-evo`（完整版）
+ * - `teamix-evo-installed`: 已存在 `.teamix-evo/` → 推荐 `teamix-evo update` / 卸载流程
+ * - `non-teamix-evo`      : 已有非 teamix-evo 工程 → 走 `teamix-evo init` 普通版接入
+ */
+type ProjectState = 'empty' | 'teamix-evo-installed' | 'non-teamix-evo';
+interface ProjectStateReport {
+    /** Decision-tree branch the caller should take. */
+    state: ProjectState;
+    /** Absolute path that was inspected. */
+    cwd: string;
+    /** Whether `.teamix-evo/` exists at `cwd`. */
+    hasTeamixDir: boolean;
+    /** Whether `package.json` exists at `cwd`. */
+    hasPackageJson: boolean;
+    /**
+     * Up to 20 entries (relative to `cwd`) that caused us to consider the
+     * directory non-empty. Useful for explaining the decision to humans.
+     */
+    significantEntries: string[];
+}
+/**
+ * Inspect `cwd` and decide which branch of the `teamix-evo init` decision
+ * tree applies. Pure read-only — never mutates the filesystem.
+ *
+ * Resolution order (first match wins):
+ * 1. `.teamix-evo/` exists      → `teamix-evo-installed`
+ * 2. cwd missing OR all entries are in the IGNORED_TOP_LEVEL set
+ *                               → `empty`
+ * 3. otherwise                  → `non-teamix-evo`
+ */
+declare function detectProjectState(cwd: string): Promise<ProjectStateReport>;
+
+/**
+ * The 8 categories of consumer-side files that `teamix-evo init` may
+ * conflict with when running against a non-teamix-evo project.
+ *
+ * See ADR 0019 D1 task #5 — these are the only files we mutate at
+ * `init` time, so they're the only ones we ask the user about.
+ */
+type ConflictKey = 'agents-md' | 'components-json' | 'tailwind-config' | 'tokens' | 'index-css' | 'shadcn-source' | 'eslint-config' | 'stylelint-config';
+/** Strategy options per conflict category. */
+type ConflictStrategy = 'overwrite' | 'merge-managed' | 'skip' | 'diff-prompt' | 'backup-overwrite' | 'migrate' | 'coexist' | 'append' | 'skip-existing' | 'per-file-prompt' | 'merge';
+interface ConflictItem {
+    /** Stable id for the category. */
+    key: ConflictKey;
+    /** True if at least one path in `paths` matched on disk. */
+    exists: boolean;
+    /**
+     * Project-relative paths that matched. Empty when `exists === false`.
+     * For `shadcn-source`, may contain a directory path (with trailing `/`).
+     */
+    paths: string[];
+    /** sha256 fingerprint of (sorted) matched contents. Omitted for directories or when nothing matched. */
+    fingerprint?: string;
+    /** Default strategy presented to the user. */
+    recommendedStrategy: ConflictStrategy;
+    /** All allowed strategies for this category, in display order. */
+    availableStrategies: ConflictStrategy[];
+    /** Category-specific metadata (e.g. detected tailwind major version). */
+    meta?: Record<string, unknown>;
+}
+interface ConflictReport {
+    cwd: string;
+    /** Always 8 items, ordered by ConflictKey enumeration above. */
+    items: ConflictItem[];
+    /** True if any item has `exists === true`. */
+    hasAnyConflict: boolean;
+}
+/**
+ * Inspect `cwd` for the 8 categories of files that `teamix-evo init` may
+ * touch. Pure read-only — never mutates the filesystem. Returns one
+ * `ConflictItem` per category in stable order so callers can render a
+ * deterministic wizard.
+ */
+declare function detectConflicts(cwd: string): Promise<ConflictReport>;
+
+/**
+ * Final answers produced by the init wizard. Every consumer of `teamix-evo
+ * init` (orchestrator + later sub-commands) reads from this object exclusively
+ * — flags / prompts must not be re-evaluated downstream (silent sub-commands).
+ */
+interface InitWizardAnswers {
+    variant: string;
+    ides: SkillIde[];
+    scope: SkillScope;
+    withLint: boolean;
+    withUi: boolean;
+    /** 'baseline' = preset 推荐组件子集；'all' = 全量装 */
+    uiSelection: 'baseline' | 'all';
+    withBizUi: boolean;
+    /**
+     * 每类冲突文件的最终策略。键是 6 类 ConflictKey，值是 user-chosen
+     * `ConflictStrategy`。当对应 ConflictItem.exists === false 时，值默认为
+     * `'overwrite'`（即首次写入）。
+     */
+    conflictDecisions: Record<ConflictKey, ConflictStrategy>;
+}
+
+/** Result of `createSnapshot` when a snapshot was actually taken. */
+interface SnapshotResult {
+    /** Filesystem-safe UTC timestamp identifier (e.g. `2026-06-11T20-59-03-000Z`). */
+    ts: string;
+    /** Absolute path to the snapshot directory. */
+    path: string;
+}
+
+type FileChangeKind = 'created' | 'modified' | 'backed-up' | 'deleted';
+interface FileChange {
+    kind: FileChangeKind;
+    /** Project-root-relative path, posix style (forward slashes). */
+    path: string;
+    /** Originating pipeline step (free-form to avoid coupling on `ProjectInitStepName`). */
+    step: string;
+    /** Optional human-readable note (e.g. `frozen` / `regenerable` / `managed`). */
+    detail?: string;
+}
+
+/**
+ * Programmatic orchestrator for `teamix-evo init` (existing-project adoption).
+ *
+ * Consumes {@link InitWizardAnswers} produced by `runInitWizard` and drives
+ * the existing core sub-commands (`runTokensInit`, `runSkillsAdd`,
+ * `runGenerateAgentsMd`, `runUiInit`, `runUiAdd`, `runLintInit`) in a fixed
+ * order. Sub-commands are invoked silently — no interactive prompts here.
+ *
+ * Conflict handling:
+ * - `conflictDecisions[key] === 'skip'` skips the corresponding step entirely.
+ * - `'overwrite'` is the trivial path (the underlying core APIs already write).
+ * - `'merge-managed'` (agents-md) is implemented today via
+ *   `runGenerateAgentsMd` which writes managed regions natively.
+ * - `'skip-existing'` (shadcn-source) maps to `runUiAdd({ overwrite: false })`,
+ *   the existing default.
+ * - All other strategies (`diff-prompt`, `backup-overwrite`, `migrate`,
+ *   `coexist`, `append`, `per-file-prompt`) require the managed-region engine
+ *   from batch 4 — they are recorded to `pendingConflictWork` so the CLI
+ *   surface can guide the user to the followup `teamix-evo conflict resolve`
+ *   step (post-batch-4).
+ *
+ * No interactive prompts, no `process.exit`. Throws on hard failure (P8).
+ */
+
+type ProjectInitStepName = 'tokens' | 'skills' | 'agents-md' | 'ui-init' | 'ui-add' | 'lint';
+type ProjectInitStepStatus = 'ok' | 'skip' | 'fail' | 'planned';
+interface ProjectInitStep {
+    name: ProjectInitStepName;
+    status: ProjectInitStepStatus;
+    detail?: string;
+    /**
+     * Files this step touched (Phase 1.A1). Empty when the step skipped or
+     * failed before any I/O. The `kind` is `created` by default; the orchestrator
+     * upgrades entries to `modified` post-hoc by checking the backup ledger
+     * (`.teamix-evo/.backups/`).
+     */
+    changes?: FileChange[];
+}
+interface PendingConflictWork {
+    key: ConflictKey;
+    strategy: ConflictStrategy;
+    reason: string;
+}
+interface ResumeHint {
+    /** The first step that failed (caller resumes from here). */
+    failedAt: ProjectInitStepName;
+    /** Steps already finished (status === 'ok'); will short-circuit on resume. */
+    completed: ProjectInitStepName[];
+    /** All steps that ended in fail status. */
+    failed: ProjectInitStepName[];
+    /** Human-readable error from the first failed step. */
+    error: string;
+    /**
+     * Suggested CLI command to resume. Today this is just `teamix-evo init`
+     * itself — every sub-step is idempotent (returns `already-initialized`
+     * when the matching state file already exists), so a re-run continues
+     * from the failure point automatically. Future batches may grow a
+     * dedicated `--resume` flag with a richer recovery model (batch 3).
+     */
+    resumeCommand: string;
+}
+interface RunProjectInitOptions {
+    /** Absolute project root (existing repo to adopt teamix-evo into). */
+    projectRoot: string;
+    /** Wizard outcome (single source of truth for every silent sub-command). */
+    answers: InitWizardAnswers;
+    /**
+     * Override the resolved UI entry list. When provided, replaces the
+     * `answers.uiSelection`-driven list (`'baseline'` / `'all'`). Useful for
+     * tests and for callers that want to install a custom subset.
+     */
+    uiEntries?: string[];
+    /**
+     * If true, skip `npm install` for lint deps. Defaults to `false` so lint
+     * works out of the box; pass `true` from the create scaffold which installs
+     * everything in one batch.
+     */
+    skipInstall?: boolean;
+    /**
+     * Legacy token CSS files (paths relative to `projectRoot`) detected by
+     * `detectConflicts` for the `tokens` key. When `conflictDecisions.tokens`
+     * is `'migrate'` and this list is non-empty, the orchestrator appends
+     * each file's content into `tokens/tokens.overrides.css` and backs the
+     * legacy files up to `.teamix-evo/.backups/` (W1.4 of the manage-entry
+     * plan; see [`legacy-tokens-migrate`](./legacy-tokens-migrate.ts)).
+     *
+     * Ignored for any other `tokens` decision. The caller (init command) is
+     * responsible for filtering out paths already inside `tokens/`.
+     */
+    legacyTokensPaths?: string[];
+    /**
+     * Phase 3.E: existing ESLint config paths (relative to `projectRoot`)
+     * detected by `detectConflicts` for the `eslint-config` key. Used to
+     * back up the consumer's file before writing the teamix-evo template,
+     * and to gate the `merge` / `backup-overwrite` / `skip` strategies in
+     * `runLintInit`.
+     */
+    legacyEslintPaths?: string[];
+    /**
+     * Phase 3.E: existing Stylelint config paths (relative to `projectRoot`).
+     */
+    legacyStylelintPaths?: string[];
+    /** Step-level progress hook (caller controls presentation). */
+    onStep?: (step: ProjectInitStep) => void;
+    /**
+     * If true, plan-only mode: compute the full step list without running any
+     * sub-command. Returns each step with `status: 'planned'`.
+     */
+    dryRun?: boolean;
+}
+interface RunProjectInitResult {
+    status: 'installed' | 'partial' | 'dry-run';
+    steps: ProjectInitStep[];
+    /** Conflicts whose strategy needs the post-batch-4 managed-region engine. */
+    pendingConflictWork: PendingConflictWork[];
+    /**
+     * Aggregated, classified file-change ledger covering every step
+     * (Phase 1.A1). Backup entries are surfaced as `kind: 'backed-up'` so the
+     * CLI can render a four-bucket summary (新建 / 修改 / 备份 / 删除).
+     */
+    changes: FileChange[];
+    /**
+     * Present when at least one step ended in `fail`. Lets the CLI surface a
+     * structured recovery message instead of just a stack-trace, and gives
+     * programmatic consumers a deterministic field to branch on.
+     */
+    resumeHint?: ResumeHint;
+    /**
+     * Pre-init snapshot of `.teamix-evo/`, captured automatically before any
+     * file is written ([ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) §2).
+     *
+     * - `null` on first-ever init (`.teamix-evo/` did not yet exist) and on
+     *   `dryRun`.
+     * - Failure to capture a snapshot is **non-fatal** — surfaced via
+     *   {@link snapshotError} so the CLI can warn the user. The init pipeline
+     *   itself still runs.
+     */
+    snapshot?: SnapshotResult | null;
+    /** Reason a snapshot capture failed (best-effort — never blocks init). */
+    snapshotError?: string;
+}
+/**
+ * Existing-project init pipeline.
+ *
+ * Order:
+ *   1. tokens init (auto-installs `teamix-evo-design-${variant}` skill)
+ *   2. skills add (`teamix-evo-code-${variant}`; entry skill is global, ADR 0033)
+ *   3. AGENTS.md (skill trigger fallback, ADR 0038)
+ *   4. ui init + ui add (gated by `withUi`)
+ *   5. lint init (gated by `withLint`)
+ */
+declare function runProjectInit(options: RunProjectInitOptions): Promise<RunProjectInitResult>;
+
+type ProjectUpdateStepName = 'tokens' | 'skills' | 'ui' | 'biz-ui';
+type ProjectUpdateStepStatus = 'ok' | 'skip' | 'fail' | 'planned';
+interface ProjectUpdateStep {
+    name: ProjectUpdateStepName;
+    status: ProjectUpdateStepStatus;
+    detail?: string;
+}
+interface ProjectUpdateResumeHint {
+    /** The first step that failed (caller resumes from here). */
+    failedAt: ProjectUpdateStepName;
+    /** Steps already finished (status === 'ok'); will short-circuit on resume. */
+    completed: ProjectUpdateStepName[];
+    /** All steps that ended in fail status. */
+    failed: ProjectUpdateStepName[];
+    /** Human-readable error from the first failed step. */
+    error: string;
+    /**
+     * Suggested CLI command to resume. Today this is just `teamix-evo update`
+     * itself — every sub-step is idempotent (version-diff short-circuits when
+     * up-to-date), so a re-run continues from the failure point automatically.
+     */
+    resumeCommand: string;
+}
+interface RunProjectUpdateOptions {
+    /** Absolute project root (must already be teamix-evo-installed). */
+    projectRoot: string;
+    /**
+     * If true, plan-only mode: compute version deltas without writing any
+     * file. Returns each step with `status: 'planned'`.
+     */
+    dryRun?: boolean;
+    /** Step-level progress hook (caller controls presentation). */
+    onStep?: (step: ProjectUpdateStep) => void;
+    /** Override the tokens package name (defaults to `@teamix-evo/tokens`). */
+    tokensPackageName?: string;
+    /** Override the skills package name (defaults to `@teamix-evo/skills`). */
+    skillsPackageName?: string;
+}
+type RunProjectUpdateResult = {
+    status: 'not-initialized';
+} | {
+    status: 'up-to-date' | 'updated' | 'partial' | 'dry-run';
+    steps: ProjectUpdateStep[];
+    resumeHint?: ProjectUpdateResumeHint;
+    /**
+     * Pre-update snapshot of `.teamix-evo/` ([ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) §2).
+     * `null` on `dryRun`. Best-effort — capture failures surface via
+     * {@link snapshotError} but never abort the pipeline.
+     */
+    snapshot?: SnapshotResult | null;
+    /** Reason a snapshot capture failed (best-effort — never blocks update). */
+    snapshotError?: string;
+};
+/**
+ * Post-init refresh pipeline.
+ *
+ * Order:
+ *   1. tokens update (regenerable rewrite + frozen preserved — ADR 0003 三态)
+ *   2. skills update (lock ∩ scope ∩ version-diff short-circuit — ADR 0035)
+ *
+ * Re-runs are safe: each sub-step short-circuits when already at latest.
+ */
+declare function runProjectUpdate(options: RunProjectUpdateOptions): Promise<RunProjectUpdateResult>;
+
 interface InstallOptions {
     /** Project root directory */
     projectRoot: string;
@@ -443,7 +950,7 @@ declare function installResources(options: InstallOptions): Promise<InstallResul
  *
  * Two-stage flow:
  *   1. **writeSkillSources** — render upstream `<packageRoot>/<skill.source>` and
- *      write to `<projectRoot>/.teamix-evo/skills/<id>/` (the consumer-side
+ *      write to `<projectRoot>/.teamix-evo/skills-source/<id>/` (the consumer-side
  *      source of truth, regenerable, in git).
  *   2. **syncSkillsToIdes** — pure byte-for-byte copy from source dir to each
  *      requested IDE mirror path (`.qoder/skills/<id>/`, `.claude/skills/<id>/`).
@@ -662,4 +1169,4 @@ declare function readInstalledManifest(projectRoot: string): Promise<InstalledMa
  */
 declare function writeInstalledManifest(projectRoot: string, manifest: InstalledManifest): Promise<void>;
 
-export { DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type ListVariantUiEntriesResult, type ListVariantUiResult, type ListVariantsResult, type RunLintInitOptions, type RunLintInitResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunSkillsInitOptions, type RunSkillsInitResult, type RunSkillsUpdateOptions, type RunSkillsUpdateResult, type RunTokensInitOptions, type RunTokensInitResult, type RunUiAddOptions, type RunUiAddResult, type RunUiInitOptions, type RunUiInitResult, type RunUiListOptions, type RunUiListResult, type RunVariantUiAddOptions, type RunVariantUiAddResult, type SkillInstallOptions, type SkillInstallResult, type SkillSyncOptions, type SkillSyncResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, type UpdatePlanItem, ensureTeamixDir, getTeamixDir, installResources, installSkills, installUiEntries, listBizUiEntries, listBizUiVariants, listTemplatesEntries, listTemplatesVariants, listTokenVariants, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runBizUiAdd, runLintInit, runSkillsAdd, runSkillsInit, runSkillsUpdate, runTemplatesAdd, runTokensInit, runUiAdd, runUiInit, runUiList, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };
+export { type ConflictItem, type ConflictKey, type ConflictReport, type ConflictStrategy, DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type ListVariantUiEntriesResult, type ListVariantUiResult, type ListVariantsResult, type PendingConflictWork, type ProjectInitStep, type ProjectInitStepName, type ProjectInitStepStatus, type ProjectState, type ProjectStateReport, type ProjectUpdateResumeHint, type ProjectUpdateStep, type ProjectUpdateStepName, type ProjectUpdateStepStatus, type ResumeHint, type RunGenerateAgentsMdOptions, type RunGenerateAgentsMdResult, type RunLintInitOptions, type RunLintInitResult, type RunProjectInitOptions, type RunProjectInitResult, type RunProjectUpdateOptions, type RunProjectUpdateResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunSkillsInitOptions, type RunSkillsInitResult, type RunSkillsUpdateOptions, type RunSkillsUpdateResult, type RunTokensInitOptions, type RunTokensInitResult, type RunUiAddOptions, type RunUiAddResult, type RunUiInitOptions, type RunUiInitResult, type RunUiListOptions, type RunUiListResult, type RunVariantUiAddOptions, type RunVariantUiAddResult, type SkillInstallOptions, type SkillInstallResult, type SkillSyncOptions, type SkillSyncResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, type UpdatePlanItem, detectConflicts, detectProjectState, ensureTeamixDir, extractDescriptionParts, getTeamixDir, installResources, installSkills, installUiEntries, listBizUiEntries, listBizUiVariants, listTemplatesEntries, listTemplatesVariants, listTokenVariants, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runBizUiAdd, runGenerateAgentsMd, runLintInit, runProjectInit, runProjectUpdate, runSkillsAdd, runSkillsInit, runSkillsUpdate, runTemplatesAdd, runTokensInit, runUiAdd, runUiInit, runUiList, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };