teamix-evo 0.8.0 → 0.10.1

package/README.md

@@ -167,34 +167,41 @@ TEAMIX_DEBUG=1 teamix-evo tokens init opentrek
 
 ## 命令参考
 
-| 命令                                                | 说明                                                                            |
-| --------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `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 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 tokens diagnose`                          | 诊断 tokens 使用情况，生成分级报告（L1-L3）+ `.treatment-plan.md`                                                       |
+| `teamix-evo tokens treat [--lock-baseline] [--apply]` | 一键 token 治理流水线：lint → codemod → lint → 报告 → 可选锁定 baseline                                                 |
+| `teamix-evo tokens codemod [name] [--apply] [--list]` | 执行指定 token codemod（5 个可用：hsl-to-v4 / hex-to-token / tw-scale-to-semantic / space-to-gap / arbitrary-to-token） |
+| `teamix-evo tokens reflect [--min-frequency <n>]`     | 扫描重复色值，推荐新增项目级 token（反哺 overrides.css）                                                                |
+| `teamix-evo tokens baseline-check`                    | 对比 baseline 检查 token 违规是否超标（CI 友好，exitCode=1 on fail）                                                    |
+| `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,49 @@ 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;
+    /**
+     * True when the consumer's existing stylelint config was kept (skip /
+     * merge) and does not extend a teamix-evo preset — token definition
+     * files may trigger false-positive lint errors without `ignoreFiles`.
+     */
+    stylelintIgnoreFilesWarning?: boolean;
 } | {
     status: 'already-initialized';
 };
@@ -445,14 +521,45 @@ interface RunGenerateAgentsMdOptions {
      * (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 (excludes missing SKILL.md degradations are still counted). */
+    /** 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). */
@@ -462,8 +569,16 @@ interface SkillDescriptionParts {
     coordinates: string | null;
 }
 /**
- * Generate and write the `AGENTS.md` file. Idempotent — repeated invocations
- * fully overwrite the file (regenerable per ADR 0038 §4).
+ * 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>;
 /**
@@ -512,15 +627,15 @@ interface ProjectStateReport {
 declare function detectProjectState(cwd: string): Promise<ProjectStateReport>;
 
 /**
- * The 6 categories of consumer-side files that `teamix-evo init` may
+ * 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';
+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';
+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;
@@ -542,13 +657,13 @@ interface ConflictItem {
 }
 interface ConflictReport {
     cwd: string;
-    /** Always 6 items, ordered by ConflictKey enumeration above. */
+    /** Always 8 items, ordered by ConflictKey enumeration above. */
     items: ConflictItem[];
     /** True if any item has `exists === true`. */
     hasAnyConflict: boolean;
 }
 /**
- * Inspect `cwd` for the 6 categories of files that `teamix-evo init` may
+ * 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.
@@ -577,6 +692,33 @@ interface InitWizardAnswers {
     conflictDecisions: Record<ConflictKey, ConflictStrategy>;
 }
 
+interface UiConflictEntry {
+    /** UI entry id from manifest (e.g. "button") */
+    id: string;
+    /** Absolute path on disk that conflicts */
+    targetPath: string;
+    /** Project-relative posix path for display */
+    relativePath: string;
+    /**
+     * Heuristic guess: true when the existing file looks like an unmodified
+     * shadcn/ui original (no `data-slot` attribute from teamix-evo).
+     * v1 uses filename + content heuristics; future versions may hash-compare.
+     */
+    isShadcnOriginal: boolean;
+}
+interface UiConflictReport {
+    /** Entries whose target file already exists on disk */
+    conflictEntries: UiConflictEntry[];
+    /** Number of manifest entries with no on-disk conflict */
+    unconflictedTargets: number;
+    /** Total manifest entries checked */
+    totalEntries: number;
+    /** True when at least one conflict exists — caller should block */
+    shouldBlock: boolean;
+    /** Distinct target alias directories that have conflicts */
+    conflictDirs: string[];
+}
+
 /** Result of `createSnapshot` when a snapshot was actually taken. */
 interface SnapshotResult {
     /** Filesystem-safe UTC timestamp identifier (e.g. `2026-06-11T20-59-03-000Z`). */
@@ -585,6 +727,17 @@ interface SnapshotResult {
     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).
  *
@@ -609,12 +762,31 @@ interface SnapshotResult {
  * No interactive prompts, no `process.exit`. Throws on hard failure (P8).
  */
 
-type ProjectInitStepName = 'tokens' | 'skills' | 'agents-md' | 'ui-init' | 'ui-add' | 'lint';
+/**
+ * Strategy for handling UI component conflicts when existing shadcn/ui
+ * components are found in the target project.
+ *
+ * - `isolate-progressive` (Path A): move existing → shadcn-ui/, install
+ *    fresh teamix-evo components into ui/, rewrite imports, let user
+ *    migrate at their own pace.
+ * - `isolate-aggressive` (Path C): same as A + immediately generate
+ *    upgrade staging so user can batch-replace.
+ * - `frozen-skip`: legacy behaviour — skip existing files, no migration.
+ */
+type UiConflictStrategy = 'isolate-progressive' | 'isolate-aggressive' | 'frozen-skip';
+type ProjectInitStepName = 'tokens' | 'skills' | 'agents-md' | 'ui-init' | 'ui-add' | 'lint' | 'gitignore';
 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;
@@ -668,6 +840,30 @@ interface RunProjectInitOptions {
      * 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[];
+    /**
+     * UI conflict resolution strategy. When omitted AND conflicts are
+     * detected, the orchestrator returns `uiDecisionRequired` so the
+     * caller can prompt the user. When `-y` (non-interactive), defaults
+     * to `'isolate-progressive'`.
+     */
+    uiConflictStrategy?: UiConflictStrategy;
+    /**
+     * When true, treat the invocation as non-interactive (`-y` flag).
+     * Affects default conflict strategy selection.
+     */
+    nonInteractive?: boolean;
     /** Step-level progress hook (caller controls presentation). */
     onStep?: (step: ProjectInitStep) => void;
     /**
@@ -676,11 +872,32 @@ interface RunProjectInitOptions {
      */
     dryRun?: boolean;
 }
+/**
+ * Returned when UI conflicts are detected and no `uiConflictStrategy` was
+ * provided. The caller should present the options to the user and re-invoke
+ * `runProjectInit` with the chosen strategy.
+ */
+interface UiDecisionRequired {
+    /** The full conflict report for display */
+    report: UiConflictReport;
+    /** Available strategies with human-readable descriptions */
+    options: Array<{
+        strategy: UiConflictStrategy;
+        label: string;
+        description: string;
+    }>;
+}
 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
@@ -700,6 +917,12 @@ interface RunProjectInitResult {
     snapshot?: SnapshotResult | null;
     /** Reason a snapshot capture failed (best-effort — never blocks init). */
     snapshotError?: string;
+    /**
+     * Present when UI conflicts are detected and no `uiConflictStrategy`
+     * was provided (interactive mode). Caller should prompt the user with
+     * `options`, then re-invoke with the chosen strategy.
+     */
+    uiDecisionRequired?: UiDecisionRequired;
 }
 /**
  * Existing-project init pipeline.
@@ -805,7 +1028,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>/`).