auriga-cli 1.28.0 → 1.29.1

package/README.md

@@ -10,7 +10,7 @@ This repo itself is a fully configured harness project. You can clone it to see
 
 | Module | Description |
 |---|---|
-| **Workflow** | `CLAUDE.md` auriga workflow: requirement clarification -> TDD -> Review, Harness principles, Subagent usage guide |
+| **Workflow** | `AGENTS.md` auriga workflow: requirement clarification -> TDD -> Review, Harness principles, Subagent usage guide |
 | **Skills** | External development process skills — systematic-debugging, TDD, verification, planning, playwright (spec authoring and architecture design ship as the `spec-design` and `arch-design` skills inside the `auriga-workflow` plugin) |
 | **Recommended Skills** | Optional utility skills (e.g. `codex-agent`, `claude-code-agent`) you can add on top of the workflow skills |
 | **Plugins** | Recommended Claude Code and Codex plugins — skill-creator, claude-md-management, playground, codex, auriga-workflow, auriga-notify, session-instructions-loader |
@@ -40,9 +40,9 @@ The leading `-y` belongs to `npx` (it auto-confirms package installation), **not
 Non-interactive install commands:
 
 ```bash
-npx -y auriga-cli install --preset           # curated workflow core: CLAUDE.md/AGENTS.md
+npx -y auriga-cli install --preset           # curated workflow core: AGENTS.md/CLAUDE.md
                                              #   + workflow skills + auriga-workflow plugin
-                                             #   (defaults: scope user, agent both, lang en)
+                                             #   (defaults: scope user, agent both, lang zh-CN)
 npx -y auriga-cli install --all              # everything: workflow + skills + recommended + plugins
 npx -y auriga-cli install recommended        # just the opt-in utility skills
 npx -y auriga-cli install plugins --agent codex --plugin session-instructions-loader
@@ -50,9 +50,9 @@ npx -y auriga-cli install <type> [--flags]   # one of: workflow | skills | recom
 npx -y auriga-cli --help                     # full catalog + flags
 ```
 
-`--preset` is atomic — it cannot be combined with a `<type>` or any filter flag, but it accepts `--scope`, `--agent`, and `--lang` (preset defaults: `user` / `both` / `en`, which differ from the per-category defaults).
+`--preset` is atomic — it cannot be combined with a `<type>` or any filter flag, but it accepts `--scope`, `--agent`, and `--lang` (preset defaults: `user` / `both` / `zh-CN`, which differ from the per-category defaults).
 
-Exit codes: `0` success, `1` fatal (precheck / parse / fetch), `2` partial success — `stderr` lists per-category `[OK]/[FAIL]` and a `Retry:` hint. After install, reload the Claude Code or Codex session so the new `CLAUDE.md` / skills / plugins / hook-plugin registrations are picked up.
+Exit codes: `0` success, `1` fatal (precheck / parse / fetch), `2` partial success — `stderr` lists per-category `[OK]/[FAIL]` and a `Retry:` hint. After install, reload the Claude Code or Codex session so the new `AGENTS.md` / skills / plugins / hook-plugin registrations are picked up.
 
 ### Web UI (opt-in)
 
@@ -76,21 +76,21 @@ Interactive menu — select what to install:
 
 ```
 ? Select what to install:
-  ◉ Recommended preset — CLAUDE.md/AGENTS.md + workflow skills + auriga-workflow plugin
+  ◉ Recommended preset — AGENTS.md/CLAUDE.md + workflow skills + auriga-workflow plugin
   ◯ Optional skills — opt-in utility skills (claude-code-agent, codex-agent...)
   ◯ Other plugins — everything except auriga-workflow (auriga-notify, skill-creator, codex...)
 ```
 
-The **Recommended preset** is checked by default and installs silently with the preset defaults (scope `user`, agent `both`, language `en`) — to fine-tune those, use the non-interactive `install --preset` flags. The other two items drill down into a per-item sub-selection. Plugin installation also asks which runtime to target: Claude Code, Codex, or both.
+The **Recommended preset** is checked by default and installs silently with the preset defaults (scope `user`, agent `both`, language `zh-CN`) — to fine-tune those, use the non-interactive `install --preset` flags. The other two items drill down into a per-item sub-selection. Plugin installation also asks which runtime to target: Claude Code, Codex, or both.
 
 ## Module Details
 
 ### Workflow
 
-Installs `CLAUDE.md` into the target project and creates an `AGENTS.md` symlink for compatibility with different Agent frameworks. Supports English and Chinese — you choose during installation.
+Installs `AGENTS.md` into the target project and creates a `CLAUDE.md` symlink for Claude Code compatibility. Chinese is the default; English remains available with `--lang en`.
 
 - **Extensible and upgradable**: the auriga workflow ships inside a managed block delimited by `<!-- AURIGA:WORKFLOW:v1 START/END -->` markers. Add your project-specific instructions *after* the END marker — re-running install upgrades the managed block in place and leaves your section untouched.
-- A pre-marker `CLAUDE.md` (installed by an older version) is migrated to the marked format on the next install, with the old file backed up to `CLAUDE.md.bak`. A foreign `CLAUDE.md` from another tool is kept as your user section below a fresh managed block.
+- A pre-marker `CLAUDE.md` (installed by an older version) is safely migrated into the new `AGENTS.md` primary shape on the next install, with the old file backed up to `CLAUDE.md.bak`. A foreign `AGENTS.md` or `CLAUDE.md` from another tool is kept as your user section below a fresh managed block.
 - Covers: requirement clarification, TDD, code review, branch workflow, subagent orchestration
 
 ### Skills
@@ -134,7 +134,7 @@ npx -y auriga-cli install plugins --agent codex --plugin session-instructions-lo
 | Plugin | Runtime | Description |
 |---|---|---|
 | skill-creator | Claude Code | Create and manage custom skills |
-| claude-md-management | Claude Code / Codex | Audit and improve CLAUDE.md |
+| claude-md-management | Claude Code / Codex | Audit and improve AGENTS.md / CLAUDE.md |
 | playground | Claude Code / Codex | Build interactive HTML playgrounds |
 | codex | Claude Code | Codex cross-model collaboration |
 | auriga-workflow | Claude Code / Codex | The auriga workflow plugin — workflow skills plus the git lifecycle hooks that enforce them. Skills: `incremental-impl`, `test-designer`, `spec-design`, `arch-design`, `code-simplify`, `session-compound`, `goalify` (plans an autonomous goal and dispatches it via the built-in `/goal` command), `deep-review` (multi-dimensional PR review orchestrator — parallel per-dimension reviewers synthesized into an actionable punch list), `reviewer-creator` (scaffolds project-level custom reviewers under `docs/rules/review/`), and `git-workflow` (git lifecycle skill). Hooks: `commit-reminder` (PostToolUse on file edits — `Edit` / `Write` / `MultiEdit` in Claude Code, `apply_patch` in Codex — nudges to commit at the next semantic boundary when uncommitted diff vs `HEAD` exceeds 200 lines or 8 files), `pr-create-guard` (PostToolUse on `gh pr create` → injects a PR-body snapshot for five-element self-verification and flags non-Conventional-Commits titles), `pr-ready-guard` (PreToolUse on `gh pr ready` and non-draft `gh pr create` → blocks on stray planning docs, unfinalized active specs under `docs/specs/`, or unpushed commits), and `pr-merge-guard` (PreToolUse on `gh pr merge` → blocks while the PR body's Acceptance criteria section still has unchecked checklist items). The two PostToolUse hooks reach full Claude Code / Codex parity; Codex currently fails open on `pr-ready-guard`'s PreToolUse `additionalContext` informational path (block path identical). Installed by default through the plugin path. |

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 
 | 模块 | 说明 |
 |---|---|
-| **Workflow** | `CLAUDE.md` 里的 auriga 工作流：需求澄清 → TDD → Review，Harness 原则，Subagent 使用指南 |
+| **Workflow** | `AGENTS.md` 里的 auriga 工作流：需求澄清 → TDD → Review，Harness 原则，Subagent 使用指南 |
 | **Skills** | 外部开发流程 skills —— systematic-debugging、TDD、verification、planning、playwright（spec 撰写与架构设计由 `auriga-workflow` 插件内的 `spec-design`、`arch-design` skill 提供）|
 | **Recommended Skills** | 可选的工具类 skills（如 `codex-agent`、`claude-code-agent`），在 workflow skills 之外按需追加 |
 | **Plugins** | 推荐的 Claude Code 和 Codex 插件 —— skill-creator、claude-md-management、playground、codex、auriga-workflow、auriga-notify、session-instructions-loader |
@@ -40,9 +40,9 @@ npx -y auriga-cli guide
 非交互安装命令：
 
 ```bash
-npx -y auriga-cli install --preset           # 工作流核心:CLAUDE.md/AGENTS.md
+npx -y auriga-cli install --preset           # 工作流核心:AGENTS.md/CLAUDE.md
                                              #   + 工作流 skill + auriga-workflow 插件
-                                             #   (默认:scope user、agent both、lang en)
+                                             #   (默认:scope user、agent both、lang zh-CN)
 npx -y auriga-cli install --all              # 全装:workflow + skills + recommended + plugins
 npx -y auriga-cli install recommended        # 只装可选工具 skills
 npx -y auriga-cli install plugins --agent codex --plugin session-instructions-loader
@@ -50,9 +50,9 @@ npx -y auriga-cli install <type> [--flags]   # 单类:workflow | skills | recomm
 npx -y auriga-cli --help                     # 完整 catalog + flag 说明
 ```
 
-`--preset` 是原子标志 —— 不能与 `<type>` 或任何过滤标志同时使用,但可带 `--scope`、`--agent`、`--lang`(预设默认 `user` / `both` / `en`,与分类安装的默认不同)。
+`--preset` 是原子标志 —— 不能与 `<type>` 或任何过滤标志同时使用,但可带 `--scope`、`--agent`、`--lang`(预设默认 `user` / `both` / `zh-CN`,与分类安装的默认不同)。
 
-退出码：`0` 成功；`1` 致命错误（前置检查 / 解析 / 拉取失败）；`2` 部分成功——`stderr` 会列出逐类 `[OK]/[FAIL]` 和 `Retry:` 提示。装完后请重启 Claude Code 或 Codex 会话，让新的 `CLAUDE.md` / skills / plugins / hook 插件注册生效。
+退出码：`0` 成功；`1` 致命错误（前置检查 / 解析 / 拉取失败）；`2` 部分成功——`stderr` 会列出逐类 `[OK]/[FAIL]` 和 `Retry:` 提示。装完后请重启 Claude Code 或 Codex 会话，让新的 `AGENTS.md` / skills / plugins / hook 插件注册生效。
 
 ### Web UI（可选）
 
@@ -76,21 +76,21 @@ npx auriga-cli
 
 ```
 ? Select what to install:
-  ◉ Recommended preset — CLAUDE.md/AGENTS.md + workflow skills + auriga-workflow plugin
+  ◉ Recommended preset — AGENTS.md/CLAUDE.md + workflow skills + auriga-workflow plugin
   ◯ Optional skills — opt-in utility skills (claude-code-agent, codex-agent...)
   ◯ Other plugins — everything except auriga-workflow (auriga-notify, skill-creator, codex...)
 ```
 
-**Recommended preset** 默认勾选,以预设默认值静默安装（scope `user`、agent `both`、语言 `en`）—— 要精调这些参数,改用非交互的 `install --preset` 标志。另两项会下钻到逐项子勾选。安装插件时还会先选择目标运行时：Claude Code、Codex 或两者都装。
+**Recommended preset** 默认勾选,以预设默认值静默安装（scope `user`、agent `both`、语言 `zh-CN`）—— 要精调这些参数,改用非交互的 `install --preset` 标志。另两项会下钻到逐项子勾选。安装插件时还会先选择目标运行时：Claude Code、Codex 或两者都装。
 
 ## 模块详情
 
 ### Workflow
 
-将 `CLAUDE.md` 安装到目标项目，并创建 `AGENTS.md` 软链接以兼容不同 Agent 框架。支持中英文版本，安装时可选择。
+将 `AGENTS.md` 安装到目标项目，并创建 `CLAUDE.md` 软链接以兼容 Claude Code。默认安装中文版本，英文可通过 `--lang en` 显式选择。
 
 - **可扩展、可升级**：auriga 工作流被一对 `<!-- AURIGA:WORKFLOW:v1 START/END -->` 标记包成「受管区块」。把你的工程专属规则写在 END 标记**之后**——再次安装只就地升级受管区块,你的内容原样保留。
-- 旧版本装下的、无标记的 `CLAUDE.md` 会在下次安装时迁移为标记格式,旧文件备份到 `CLAUDE.md.bak`。别的工具生成的 `CLAUDE.md` 会作为用户区保留在全新受管区块下方。
+- 旧版本装下的、无标记的 `CLAUDE.md` 会在下次安装时安全迁移到新的 `AGENTS.md` 主文件形态,旧文件备份到 `CLAUDE.md.bak`。别的工具生成的 `AGENTS.md` 或 `CLAUDE.md` 会作为用户区保留在全新受管区块下方。
 - 涵盖：需求澄清、TDD、代码 Review、分支工作流、Subagent 编排
 
 ### Skills
@@ -134,7 +134,7 @@ npx -y auriga-cli install plugins --agent codex --plugin session-instructions-lo
 | 插件 | 运行时 | 说明 |
 |---|---|---|
 | skill-creator | Claude Code | 创建和管理自定义 skills |
-| claude-md-management | Claude Code / Codex | 审计和改进 CLAUDE.md |
+| claude-md-management | Claude Code / Codex | 审计和改进 AGENTS.md / CLAUDE.md |
 | playground | Claude Code / Codex | 构建交互式 HTML playground |
 | codex | Claude Code | Codex 跨模型协作 |
 | auriga-workflow | Claude Code / Codex | auriga 工作流插件 —— 工作流 skill 加上强制执行工作流的 git 生命周期 hook。Skills：`incremental-impl`、`test-designer`、`spec-design`、`arch-design`、`code-simplify`、`session-compound`、`goalify`（plan 出自驱 goal 并通过内置 `/goal` 命令分发执行）、`deep-review`（多维度 PR review 编排器——并行派发各维度 reviewer，汇总成可执行的 punch list）、`reviewer-creator`（在 `docs/rules/review/` 下生成项目级自定义 reviewer）、`git-workflow`（git 生命周期 skill）。Hooks：`commit-reminder`（文件编辑的 PostToolUse —— Claude Code 匹配 `Edit` / `Write` / `MultiEdit`，Codex 匹配 `apply_patch` —— 未提交 diff 对比 `HEAD` 超过 200 行或 8 个文件时，提醒在下一个语义边界 commit）、`pr-create-guard`（`gh pr create` 的 PostToolUse —— 注入 PR body 快照供五要素自检，并对不符合 Conventional Commits 的标题提示）、`pr-ready-guard`（`gh pr ready` 与非 draft `gh pr create` 的 PreToolUse —— 拦截游离规划文档、`docs/specs/` 内未结案的活跃 spec、未 push commits）、`pr-merge-guard`（`gh pr merge` 的 PreToolUse —— PR body 的验收标准章节仍有未勾选清单项时拦截合并）。两个 PostToolUse hook 在 Claude Code / Codex 上完全对齐；Codex 仅对 `pr-ready-guard` 的 PreToolUse `additionalContext` 信息路径 fail-open（block 路径两边一致）。默认通过插件路径安装。 |

package/dist/api-types.d.ts

@@ -71,11 +71,11 @@ export interface PluginState {
 }
 export interface StateWarning {
     code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline" | "claude-code-not-installed" | "settings-unreadable" | "skill-malformed"
-    /** Project-scope CLAUDE.md (or the user-scope fallback when scanning
-     *  user scope) is present but has no recognizable `# auriga Workflow (vX.Y.Z)`
-     *  header. The row reports `not-installed`; install will back up the
-     *  existing file to `CLAUDE.md.bak` and write ours. */
-     | "workflow-foreign-claudemd";
+    /** Workflow instruction file is present but has no recognizable
+     *  `# auriga Workflow (vX.Y.Z)` header. The row reports `not-installed`;
+     *  install keeps the existing content in the user region before writing
+     *  ours. */
+     | "workflow-foreign-agentsmd" | "workflow-foreign-claudemd";
     message: string;
 }
 export type ApplyCategory = "workflow" | "skill" | "recommended-skill" | "plugin"
@@ -93,10 +93,10 @@ export type ApplyAction = "install" | "uninstall";
  */
 export type ApplyScope = "project" | "user";
 /**
- * Workflow CLAUDE.md language variant.
+ * Workflow AGENTS.md language variant.
  *
- * - "en":    English CLAUDE.md (the default).
- * - "zh-CN": Simplified Chinese CLAUDE.md (the localized variant).
+ * - "zh-CN": Simplified Chinese workflow template (the default).
+ * - "en":    English workflow template.
  *
  * Only meaningful for `category === "workflow"`; rejected for other
  * categories so the API surface stays explicit.
@@ -120,7 +120,7 @@ export interface ApplyItemRef {
      *  server rejects this field for category="workflow" because workflow
      *  has no scope concept (it's a single file at the project root). */
     scope?: ApplyScope;
-    /** Workflow CLAUDE.md language variant. Omitted = "en" (back-compat
+    /** Workflow AGENTS.md language variant. Omitted = "zh-CN"
      *  default). The server accepts this field only for category="workflow"
      *  and category="preset" (the preset installs the workflow doc). */
     lang?: ApplyLang;

package/dist/apply-handlers.d.ts

@@ -11,7 +11,7 @@ export interface ApplyHandlerContext {
      *  and the handler iterates the list, installing to each agent in turn.
      *  Names not in the map default to `["claude"]` (existing CLI default). */
     pluginAgentsByName: Map<string, ("claude" | "codex")[]>;
-    /** Workflow language for install. Defaults to "en". */
+    /** Workflow language for install. Defaults to "zh-CN". */
     workflowLang?: ApplyLang;
 }
 export declare function buildDefaultApplyHandlers(ctx: ApplyHandlerContext): ApplyHandlers;

package/dist/apply-handlers.js

@@ -23,6 +23,7 @@
 import { installPlugins, uninstallPlugin, } from "./plugins.js";
 import { installPreset } from "./preset.js";
 import { installRecommendedSkills, installSkills, uninstallSkill, } from "./skills.js";
+import { DEFAULT_WORKFLOW_LANG } from "./utils.js";
 import { installWorkflow, uninstallWorkflow } from "./workflow.js";
 const ALL_ACTIONS = new Set([
     "install",
@@ -37,7 +38,7 @@ function assertAction(action) {
 }
 export function buildDefaultApplyHandlers(ctx) {
     const { packageRoot, cwd, pluginAgentsByName } = ctx;
-    const lang = ctx.workflowLang ?? "en";
+    const lang = ctx.workflowLang ?? DEFAULT_WORKFLOW_LANG;
     const workflow = async (action, _name, { onLog, lang: requestedLang }) => {
         assertAction(action);
         // Per-item lang overrides the ctx default (the UI now drives this via
@@ -155,7 +156,7 @@ export function buildDefaultApplyHandlers(ctx) {
     // The preset is a single apply item that drives the whole installPreset
     // orchestration. scope / agent / lang come from the Dashboard's preset
     // controls; omitted values fall back to the preset defaults
-    // (user / both / en). Uninstall is not a preset operation.
+    // (user / both / zh-CN). Uninstall is not a preset operation.
     const preset = async (action, _name, { onLog, scope, lang: requestedLang, agent }) => {
         assertAction(action);
         if (action !== "install") {

package/dist/catalog.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-16T10:40:59.234Z",
+  "generatedAt": "2026-05-17T06:16:55.450Z",
   "workflowSkills": [
     {
       "name": "planning-with-files",
@@ -78,7 +78,7 @@
     },
     {
       "name": "claude-md-management",
-      "description": "(Claude/Codex) Audit and improve CLAUDE.md files",
+      "description": "(Claude/Codex) Audit and improve AGENTS.md / CLAUDE.md files",
       "agents": [
         "claude",
         "codex"

package/dist/cli.d.ts

@@ -49,7 +49,7 @@ type LegacyMenuValue = "preset" | "recommended" | "plugins";
  *
  * Workflow + Skills are absorbed by the「推荐预设」item.
  * The preset label spells out the silent defaults (scope user / agent
- * both / lang en) so a TTY user knows what they're getting — fine-tuning
+ * both / lang zh-CN) so a TTY user knows what they're getting — fine-tuning
  * those goes through the non-interactive `install --preset` flags.
  */
 export declare const LEGACY_MENU_CHOICES: ReadonlyArray<{

package/dist/cli.js

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { exec, fetchContentRoot, getPackageRoot, isNonInteractive, LANGUAGES, log, readPackageVersion, } from "./utils.js";
+import { exec, DEFAULT_WORKFLOW_LANG, fetchContentRoot, getPackageRoot, isNonInteractive, LANGUAGES, log, readPackageVersion, } from "./utils.js";
 import { installWorkflow } from "./workflow.js";
 import { installSkills, installRecommendedSkills } from "./skills.js";
 import { installPlugins } from "./plugins.js";
@@ -11,7 +11,7 @@ import { loadCatalog } from "./catalog.js";
 import { renderHelp, renderTypeHelp } from "./help.js";
 import { renderGuide } from "./guide.js";
 import { CATEGORY_NAMES } from "./types.js";
-const RELOAD_REMINDER = "\n⚠ Reload your Claude Code or Codex session to pick up the new harness (CLAUDE.md / skills / plugins are loaded at session startup).\n";
+const RELOAD_REMINDER = "\n⚠ Reload your Claude Code or Codex session to pick up the new harness (AGENTS.md / skills / plugins are loaded at session startup).\n";
 const CATEGORY_SET = new Set(CATEGORY_NAMES);
 const TYPE_FOR_FILTER = {
     "--skill": "skills",
@@ -259,7 +259,7 @@ function validateInstall(out, filterFlag) {
     // (workflow doc + workflow skills + auriga-workflow plugin) and cannot
     // combine with a <type>, a sub-item filter, or --all. Unlike a category
     // install it DOES accept --scope / --agent / --lang as preset modifiers
-    // (the preset defaults differ: user / both / en). --cwd is not a preset
+    // (the preset defaults differ: user / both / zh-CN). --cwd is not a preset
     // modifier — the workflow doc always lands in the current directory.
     if (out.preset) {
         if (out.all) {
@@ -475,7 +475,7 @@ async function runInstall(p) {
  * succeed → 0; any step fails → 2 with per-step status on stderr.
  *
  * The preset defaults differ from a category install — scope=user,
- * agent=both, lang=en — and are resolved here before handing off, so
+ * agent=both, lang=zh-CN — and are resolved here before handing off, so
  * `installPreset` itself stays default-free (the TUI / Web UI callers
  * resolve their own defaults the same way).
  */
@@ -489,7 +489,7 @@ async function runPreset(p) {
         interactive: false,
         scope: p.scope ?? "user",
         agent,
-        lang: p.lang ?? "en",
+        lang: p.lang ?? DEFAULT_WORKFLOW_LANG,
     });
     for (const r of results) {
         if (r.ok) {
@@ -507,7 +507,14 @@ async function runPreset(p) {
     // The preset is one atomic "install the right defaults" action — the
     // retry is the whole command again, not a per-category fan-out like
     // runAll's hint.
-    process.stderr.write("\nRetry:\n  npx -y auriga-cli install --preset\n");
+    const retryArgs = ["install", "--preset"];
+    if (p.scope)
+        retryArgs.push("--scope", p.scope);
+    if (p.agent)
+        retryArgs.push("--agent", p.agent);
+    if (p.lang)
+        retryArgs.push("--lang", p.lang);
+    process.stderr.write(`\nRetry:\n  npx -y auriga-cli ${retryArgs.join(" ")}\n`);
     if (failed.length < results.length) {
         process.stderr.write(RELOAD_REMINDER);
     }
@@ -619,7 +626,7 @@ async function runAll(p) {
         process.stderr.write(`  npx -y auriga-cli install ${s.category}${suffix}\n`);
     }
     // Partial success still installed assets that need a session reload
-    // (CLAUDE.md / skills / plugins load at startup). Without this hint
+    // (AGENTS.md / skills / plugins load at startup). Without this hint
     // the user may retry the failed category and act on stale state.
     if (failed.length < status.length) {
         process.stderr.write(RELOAD_REMINDER);
@@ -686,8 +693,9 @@ async function runUi(p, version) {
     //   - tarballRoot: where `dist/catalog.json` + the bundled DEV ui/dist live.
     //     Always read from the installed npm package; can't be fetched because
     //     dist/ is built artifact, not git content.
-    //   - contentRoot: where the runtime install recipes live (CLAUDE.md,
-    //     marketplace manifests, extra_plugin_configs.json, skills-lock.json).
+    //   - contentRoot: where the runtime install recipes live (workflow
+    //     templates, marketplace manifests, extra_plugin_configs.json,
+    //     skills-lock.json).
     //     These files are
     //     NOT in the npm tarball — the `files` allowlist only ships `dist/*`
     //     + npm defaults. They are fetched from GitHub, pinned to the CLI
@@ -750,7 +758,7 @@ async function runUi(p, version) {
         return 1;
     }
     const applyCatalog = {
-        // Workflow is a singleton (one CLAUDE.md per project); we pick the
+        // Workflow is a singleton (one AGENTS.md per project); we pick the
         // sentinel name "workflow" to match what the Web UI's Dashboard sends
         // and to remain semantically self-describing. The handler ignores the
         // name argument either way.
@@ -767,8 +775,9 @@ async function runUi(p, version) {
         pluginAgentsByName.set(name, def.agents);
     }
     const applyHandlers = buildDefaultApplyHandlers({
-        // contentRoot: install handlers read CLAUDE.md, marketplace manifests,
-        // extra_plugin_configs.json, and skills-lock.json — all CONTENT_FILES.
+        // contentRoot: install handlers read workflow templates, marketplace
+        // manifests, extra_plugin_configs.json, and skills-lock.json — all
+        // CONTENT_FILES.
         // Routing them at tarballRoot fails ENOENT for npm-installed users.
         packageRoot: contentRoot,
         cwd,
@@ -793,8 +802,8 @@ async function runUi(p, version) {
                 cwd,
                 // server reads dist/catalog.json (tarball-shipped) via
                 // buildScanCatalog on each /api/state call; install-time content
-                // (marketplace manifests, extra plugin config, CLAUDE.md, …) was already injected
-                // into applyHandlers above with contentRoot.
+                // (workflow templates, marketplace manifests, extra plugin config, …)
+                // was already injected into applyHandlers above with contentRoot.
                 packageRoot: tarballRoot,
                 heartbeatTimeoutMs: UI_HEARTBEAT_TIMEOUT_MS,
                 applyHandlers,
@@ -878,13 +887,13 @@ function highlight(text) {
  *
  * Workflow + Skills are absorbed by the「推荐预设」item.
  * The preset label spells out the silent defaults (scope user / agent
- * both / lang en) so a TTY user knows what they're getting — fine-tuning
+ * both / lang zh-CN) so a TTY user knows what they're getting — fine-tuning
  * those goes through the non-interactive `install --preset` flags.
  */
 export const LEGACY_MENU_CHOICES = [
     {
         value: "preset",
-        name: "Recommended preset — CLAUDE.md/AGENTS.md + workflow skills + auriga-workflow plugin (scope user · agent both · lang en)",
+        name: "Recommended preset — AGENTS.md/CLAUDE.md + workflow skills + auriga-workflow plugin (scope user · agent both · lang zh-CN)",
         checked: true,
     },
     {
@@ -928,7 +937,7 @@ async function runLegacyMenu() {
         return 0;
     }
     // 「推荐预设」silently uses the preset defaults (scope user / agent
-    // both / lang en) — it does not prompt for them. The other two items
+    // both / lang zh-CN) — it does not prompt for them. The other two items
     // drill down into their category's per-item sub-selection as before.
     if (picks.includes("preset")) {
         console.log("\n--- Recommended preset ---\n");
@@ -936,7 +945,7 @@ async function runLegacyMenu() {
             interactive: true,
             scope: "user",
             agent: "both",
-            lang: "en",
+            lang: DEFAULT_WORKFLOW_LANG,
         });
     }
     if (picks.includes("recommended")) {

package/dist/guide.js

@@ -20,7 +20,7 @@ export function renderGuide(opts) {
     return `${h(`# auriga-cli bootstrap SOP (v${opts.version})`)}
 
 This guide walks an Agent through installing the auriga harness
-(CLAUDE.md + skills + plugins) into the current repository.
+(AGENTS.md + skills + plugins) into the current repository.
 
 Run each step in order. If any step fails with exit 1, stop and report.
 If exit 2, see stderr for per-category status and follow the "Retry"
@@ -61,9 +61,10 @@ Per-type detail (flags + only that category's catalog slice):
 
 ${h("## Step 3 — Install")}
 
-Recommended — the curated workflow preset (CLAUDE.md/AGENTS.md +
+Recommended — the curated workflow preset (AGENTS.md/CLAUDE.md +
 workflow skills + the auriga-workflow plugin). Defaults: scope user,
-agent both (Claude Code + Codex), lang en:
+agent both (Claude Code + Codex), lang zh-CN. Scope applies to skills
+and plugins; the workflow doc always writes to the current project:
   ${cmd("npx -y auriga-cli install --preset")}
 
 Everything — workflow + skills + recommended skills + default plugins:
@@ -96,7 +97,7 @@ Exit codes:
 
 ${h("## Step 4 — Reload session (REQUIRED when installed non-interactively)")}
 
-${warn("⚠")} CLAUDE.md, .agents/skills/, and plugin enablement /
+${warn("⚠")} AGENTS.md, .agents/skills/, and plugin enablement /
 registrations are loaded at session startup. If you ran
 \`npx -y auriga-cli install\` inside an existing Claude Code or Codex session
 (e.g., \`claude -p\` / \`claude -p --worktree\` / \`codex exec\`), the current session
@@ -110,8 +111,8 @@ Action:
 ${h("## Step 5 — Verify install")}
 
 Expected artifacts/checks:
-  - CLAUDE.md                 (workflow manifesto)
-  - AGENTS.md -> CLAUDE.md    (symlink)
+  - AGENTS.md                 (workflow manifesto, Chinese by default)
+  - CLAUDE.md -> AGENTS.md    (Claude Code compatibility symlink)
   - .agents/skills/<name>/    (one per installed skill)
   - claude plugins list       (shows Claude plugins, if Claude plugins selected)
   - ~/.codex/config.toml      (Codex plugin enablement, if Codex plugins selected)

package/dist/help.js

@@ -13,7 +13,8 @@ USAGE
   npx auriga-cli install --preset [--scope <s>] [--agent <a>] [--lang <code>]
                                                          curated default set: workflow doc
                                                          + workflow skills + auriga-workflow plugin
-                                                         (defaults: scope user, agent both, lang en)
+                                                         (defaults: scope user, agent both, lang zh-CN)
+                                                         scope applies to skills/plugins; workflow writes current project
   npx auriga-cli install --all [--scope <s>] [--agent <a>]
                                                          everything: workflow + skills
                                                          + recommended + plugins
@@ -28,13 +29,13 @@ USAGE
     npx -y auriga-cli install --preset
 
 TYPES (exactly one with <type> form)
-  workflow       CLAUDE.md + AGENTS.md (workflow manifesto)
+  workflow       AGENTS.md + CLAUDE.md symlink (workflow manifesto)
   skills         Default-on workflow skills (listed below)
   recommended    Opt-in utility skills (listed below)
   plugins        Claude Code and Codex plugins (listed below)
 
 TYPE-SPECIFIC FLAGS
-  workflow:       --lang <code>                  default en; available: en, zh-CN
+  workflow:       --lang <code>                  default zh-CN; available: zh-CN, en
                   --cwd <dir>                    default current working directory
   skills:         --skill <names...>             space-separated; '*' = all
                   --scope <project|user>         default project
@@ -80,11 +81,11 @@ USAGE
   npx auriga-cli install workflow [--lang <code>] [--cwd <dir>]
 
 FLAGS
-  --lang <code>   default en; available: en, zh-CN
+  --lang <code>   default zh-CN; available: zh-CN, en
   --cwd <dir>     default current working directory
 
 NOTE
-  workflow has no --scope flag (single file + AGENTS.md symlink).
+  workflow has no --scope flag (AGENTS.md primary + CLAUDE.md symlink).
 `;
         case "skills":
             return `${header}

package/dist/preset.d.ts

@@ -6,7 +6,7 @@ import type { PluginAgent } from "./utils.js";
  */
 export declare const PRESET_PLUGINS: readonly ["auriga-workflow"];
 /**
- * installPreset 的输入。三个默认值(scope=user / agent=both / lang=en)
+ * installPreset 的输入。三个默认值(scope=user / agent=both / lang=zh-CN)
  * 与分类安装不同,由调用方负责落定后再传入 —— 预设的默认不在本函数内
  * 兜底,使「默认值是什么」对每个调用端都显式可见。
  */

package/dist/preset.js

@@ -3,7 +3,7 @@
 // installPreset —— 「推荐预设安装」的单一编排入口。
 //
 // 预设由三部分组成,按下面的顺序安装:
-//   1. workflow 文档 (CLAUDE.md + AGENTS.md)
+//   1. workflow 文档 (AGENTS.md + CLAUDE.md 兼容软链)
 //   2. 工作流 skill (WORKFLOW_SKILLS 全集 —— installSkills 自身已限定)
 //   3. auriga-workflow 插件
 //

package/dist/server.d.ts

@@ -5,8 +5,8 @@ export interface ApplyHandlerOptions {
      *  translate into the per-installer flag (`--scope project|user`). The
      *  workflow handler ignores it (workflow has no scope concept). */
     scope?: "project" | "user";
-    /** Workflow CLAUDE.md language variant. Meaningful for the workflow and
-     *  preset handlers; other handlers ignore it. Omitted = "en". */
+    /** Workflow AGENTS.md language variant. Meaningful for the workflow and
+     *  preset handlers; other handlers ignore it. Omitted = "zh-CN". */
     lang?: "en" | "zh-CN";
     /** Preset install runtime. Only meaningful for the preset handler;
      *  other handlers ignore it. Omitted = "both". */

package/dist/skills.js

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { checkbox, select } from "@inquirer/prompts";
 import { atomicWriteFile, exec, execAsync, log, withEsc } from "./utils.js";
-// Curated default-on set: skills that the workflow in the root CLAUDE.md
+// Curated default-on set: skills that the shipped workflow template
 // directly references. Anything else in skills-lock.json is surfaced via
 // installRecommendedSkills as an opt-in utility.
 export const WORKFLOW_SKILLS = [

package/dist/state.js

@@ -3,7 +3,8 @@
 // own dev-repo layout. The truth sources:
 //
 //   Workflow:  ~/.claude/CLAUDE.md                          (user scope)
-//              <proj>/CLAUDE.md                             (project scope)
+//              <proj>/AGENTS.md                             (project scope primary)
+//              <proj>/CLAUDE.md                             (project scope legacy fallback)
 //   Skills:    ~/.claude/skills/<name>/SKILL.md             (user scope)
 //              <proj>/.claude/skills/<name>/SKILL.md        (project scope)
 //   Plugins(Claude): execPluginList(scope) + settings.json enabledPlugins
@@ -25,6 +26,7 @@ import os from "node:os";
 import path from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { hasAurigaHeader, parseMarkers } from "./workflow-markers.js";
+import { WORKFLOW_COMPAT_FILE, WORKFLOW_PRIMARY_FILE, } from "./workflow-docs.js";
 /**
  * Shorten an absolute path by replacing the user's $HOME with `~`. Avoids
  * leaking the full username in screenshots and keeps the TopBar label
@@ -152,29 +154,44 @@ function workflowPathsForScope(scope, projectRoot, home) {
     if (scope === "user") {
         return [path.join(home, ".claude", "CLAUDE.md")];
     }
-    // Project: only `<proj>/CLAUDE.md` — the auriga workflow installer
-    // (src/workflow.ts) writes here and never to `<proj>/.claude/CLAUDE.md`.
-    // The old fallback collapsed onto `$HOME/.claude/CLAUDE.md` when
-    // projectRoot === $HOME (user runs `web-ui` from home dir), leaking
-    // user-scope content into the project-scope row.
-    return [path.join(projectRoot, "CLAUDE.md")];
+    // Project: prefer the current `<proj>/AGENTS.md` primary. Keep
+    // `<proj>/CLAUDE.md` as a legacy fallback so already-installed projects do
+    // not flash as missing before their next install flips the symlink direction.
+    // Never fall back to `<proj>/.claude/CLAUDE.md`: that path can collapse onto
+    // user scope when projectRoot === HOME.
+    return [
+        path.join(projectRoot, WORKFLOW_PRIMARY_FILE),
+        path.join(projectRoot, WORKFLOW_COMPAT_FILE),
+    ];
 }
-function scanWorkflow(scope, projectRoot, home, warnings) {
-    const candidates = workflowPathsForScope(scope, projectRoot, home);
-    let content = null;
+function workflowForeignWarningCode(filePath) {
+    return path.basename(filePath) === WORKFLOW_PRIMARY_FILE
+        ? "workflow-foreign-agentsmd"
+        : "workflow-foreign-claudemd";
+}
+function workflowForeignWarningMessage(filePath) {
+    const name = path.basename(filePath);
+    return `Foreign ${name} detected at the workflow path — no auriga-workflow header. Install will preserve existing content or link intent before replacing the workflow path.`;
+}
+function readFirstWorkflowCandidate(candidates) {
     for (const candidate of candidates) {
         try {
-            content = fs.readFileSync(candidate, "utf8");
-            break;
+            return { content: fs.readFileSync(candidate, "utf8"), filePath: candidate };
         }
         catch {
             // try next candidate
         }
     }
-    if (content === null) {
+    return null;
+}
+function scanWorkflow(scope, projectRoot, home, warnings) {
+    const candidates = workflowPathsForScope(scope, projectRoot, home);
+    const workflowFile = readFirstWorkflowCandidate(candidates);
+    if (workflowFile === null) {
         return { status: "not-installed", observedScope: scope };
     }
-    // "Is this our CLAUDE.md?" — two recognizable shapes:
+    const { content, filePath } = workflowFile;
+    // "Is this our workflow instruction file?" — two recognizable shapes:
     //   - managed-block markers (the current install format). The START marker
     //     is an HTML comment ahead of the auriga header, so a first-non-blank-
     //     line header walk would miss it — detect the marker pair directly.
@@ -183,13 +200,13 @@ function scanWorkflow(scope, projectRoot, home, warnings) {
     if (parseMarkers(content).kind === "marked" || hasAurigaHeader(content)) {
         return { status: "installed", observedScope: scope };
     }
-    // CLAUDE.md exists but is neither marked nor auriga-headed. The file is
-    // foreign — not our workflow. Report `not-installed` honestly; the install
-    // path (src/workflow.ts) keeps the foreign content as the user region
-    // below a fresh managed block, so nothing is lost.
+    // The workflow path exists but is neither marked nor auriga-headed. The file
+    // is foreign — not our workflow. Report `not-installed` honestly; the install
+    // path keeps the foreign content as the user region below a fresh managed
+    // block, so nothing is lost.
     warnings.push({
-        code: "workflow-foreign-claudemd",
-        message: `Foreign CLAUDE.md detected at the workflow path — no auriga-workflow header. Install will keep your content as the user region below the managed block.`,
+        code: workflowForeignWarningCode(filePath),
+        message: workflowForeignWarningMessage(filePath),
     });
     return { status: "not-installed", observedScope: scope };
 }

package/dist/utils.d.ts

@@ -92,6 +92,8 @@ export interface LangOption {
     label: string;
     file: string;
 }
+export declare const DEFAULT_WORKFLOW_LANG = "zh-CN";
+export declare const DEFAULT_WORKFLOW_TEMPLATE_FILE = "AGENTS.template.zh-CN.md";
 export declare const LANGUAGES: LangOption[];
 /**
  * Reads `version` from the packaged manifest. Throws when the package

package/dist/utils.js

@@ -100,9 +100,11 @@ export function execAsync(cmd, opts) {
         });
     });
 }
+export const DEFAULT_WORKFLOW_LANG = "zh-CN";
+export const DEFAULT_WORKFLOW_TEMPLATE_FILE = "AGENTS.template.zh-CN.md";
 export const LANGUAGES = [
-    { value: "en", label: "English", file: "CLAUDE.md" },
-    { value: "zh-CN", label: "中文", file: "CLAUDE.zh-CN.md" },
+    { value: "zh-CN", label: "中文", file: "AGENTS.template.zh-CN.md" },
+    { value: "en", label: "English", file: "AGENTS.template.en.md" },
 ];
 // --- Remote content ---
 const REPO = "Ben2pc/auriga-cli";
@@ -146,12 +148,17 @@ function resolveContentRef() {
     return "main";
 }
 const CONTENT_FILES = [
-    "CLAUDE.md",
+    DEFAULT_WORKFLOW_TEMPLATE_FILE,
+    "AGENTS.template.en.md",
     "skills-lock.json",
     ".claude-plugin/marketplace.json",
     ".agents/plugins/marketplace.json",
     "extra_plugin_configs.json",
 ];
+const LEGACY_CONTENT_FILE_FALLBACKS = {
+    "AGENTS.template.zh-CN.md": "AGENTS.md",
+    "AGENTS.template.en.md": "AGENTS.en.md",
+};
 async function fetchFile(file) {
     const ref = resolveContentRef();
     const url = `https://raw.githubusercontent.com/${REPO}/${ref}/${file}`;
@@ -160,6 +167,18 @@ async function fetchFile(file) {
         throw new Error(`Failed to fetch ${url}: ${res.status}`);
     return res.text();
 }
+async function fetchContentFile(file) {
+    try {
+        return await fetchFile(file);
+    }
+    catch (err) {
+        const legacyFile = LEGACY_CONTENT_FILE_FALLBACKS[file];
+        if (!legacyFile || !(err instanceof Error) || !/: 404$/.test(err.message)) {
+            throw err;
+        }
+        return fetchFile(legacyFile);
+    }
+}
 async function fetchFileBinary(file) {
     const ref = resolveContentRef();
     const url = `https://raw.githubusercontent.com/${REPO}/${ref}/${file}`;
@@ -174,7 +193,7 @@ export async function fetchContentRoot() {
     }
     const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "auriga-cli-"));
     for (const file of CONTENT_FILES) {
-        const content = await fetchFile(file);
+        const content = await fetchContentFile(file);
         const dest = path.join(tmpDir, file);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         fs.writeFileSync(dest, content);
@@ -182,8 +201,10 @@ export async function fetchContentRoot() {
     return tmpDir;
 }
 export async function fetchExtraContent(tmpDir, file) {
-    const content = await fetchFile(file);
     const dest = path.join(tmpDir, file);
+    if (fs.existsSync(dest))
+        return;
+    const content = await fetchFile(file);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.writeFileSync(dest, content);
 }

package/dist/workflow-docs.d.ts

@@ -0,0 +1,4 @@
+export declare const WORKFLOW_PRIMARY_FILE = "AGENTS.md";
+export declare const WORKFLOW_COMPAT_FILE = "CLAUDE.md";
+export declare const WORKFLOW_COMPAT_SYMLINK_TARGET = "AGENTS.md";
+export declare const LEGACY_AGENTS_SYMLINK_TARGET = "CLAUDE.md";

package/dist/workflow-docs.js

@@ -0,0 +1,4 @@
+export const WORKFLOW_PRIMARY_FILE = "AGENTS.md";
+export const WORKFLOW_COMPAT_FILE = "CLAUDE.md";
+export const WORKFLOW_COMPAT_SYMLINK_TARGET = WORKFLOW_PRIMARY_FILE;
+export const LEGACY_AGENTS_SYMLINK_TARGET = WORKFLOW_COMPAT_FILE;

package/dist/workflow-markers.d.ts

@@ -30,7 +30,7 @@ export type MarkerParse = {
     endHash: string | null;
 };
 /**
- * Classify a CLAUDE.md body by its managed-block markers.
+ * Classify an AGENTS.md body by its managed-block markers.
  *
  *  - `unmarked`   — neither marker present (fresh-target / foreign / old-format)
  *  - `malformed`  — exactly one marker, or END before START (can't safely splice)
@@ -38,7 +38,7 @@ export type MarkerParse = {
  */
 export declare function parseMarkers(content: string): MarkerParse;
 /**
- * Build a marked CLAUDE.md from its three parts. The END marker hash is
+ * Build a marked AGENTS.md from its three parts. The END marker hash is
  * computed from `blockBody` here, so callers never hand-maintain it.
  *
  * `blockBody` is expected to end with a newline (it is the content the START
@@ -55,5 +55,5 @@ export declare function composeMarkedFile(opts: {
     lang?: string;
 }): string;
 /** True when the first non-blank line is an auriga workflow header. Used to
- *  tell an old-format (pre-marker) auriga CLAUDE.md from a foreign one. */
+ *  tell an old-format (pre-marker) auriga workflow file from a foreign one. */
 export declare function hasAurigaHeader(content: string): boolean;

package/dist/workflow-markers.js

@@ -1,14 +1,14 @@
-// Managed-block markers for the installed CLAUDE.md.
+// Managed-block markers for the installed AGENTS.md.
 //
 // auriga-cli installs its workflow document wrapped in a pair of HTML-comment
 // markers. Everything *between* the markers is the "managed block" — owned by
 // auriga-cli, replaced wholesale on upgrade. Everything *outside* (notably the
 // region after the END marker) is the project's own — auriga-cli never touches
-// it. This lets a downstream project extend its CLAUDE.md while still
+// it. This lets a downstream project extend its AGENTS.md while still
 // receiving workflow upgrades.
 //
 // Markers are HTML comments so both Claude Code and Codex (which read the same
-// file via the AGENTS.md → CLAUDE.md symlink) treat them as inert.
+// file via the CLAUDE.md → AGENTS.md symlink) treat them as inert.
 //
 // This module is the single source of truth for the marker contract; it is
 // imported by both src/workflow.ts (install / upgrade) and src/state.ts
@@ -21,9 +21,9 @@ export const MARKER_SCHEMA = "v1";
  * START marker line, one per template language. Only the prose differs — the
  * structural `AURIGA:WORKFLOW:v1 START` token is language-independent, so the
  * parser (`START_LINE_RE`) keys on the token alone and never needs to know the
- * language. The English `CLAUDE.md` gets the English marker; `CLAUDE.zh-CN.md`
- * gets the Chinese one, so a downstream file never carries a comment in the
- * wrong language for its document.
+ * language. `AGENTS.template.en.md` gets the English marker;
+ * `AGENTS.template.zh-CN.md` gets the Chinese one, so a downstream file never
+ * carries a comment in the wrong language for its document.
  */
 const WORKFLOW_START_MARKERS = {
     en: `<!-- AURIGA:WORKFLOW:${MARKER_SCHEMA} START — Managed block, maintained by auriga-cli. Do not edit by hand; upgrades replace it wholesale. Put project-specific instructions after the END marker below. -->`,
@@ -53,7 +53,7 @@ export function hashBlock(blockBody) {
     return createHash("sha256").update(blockBody, "utf8").digest("hex").slice(0, 16);
 }
 /**
- * Classify a CLAUDE.md body by its managed-block markers.
+ * Classify an AGENTS.md body by its managed-block markers.
  *
  *  - `unmarked`   — neither marker present (fresh-target / foreign / old-format)
  *  - `malformed`  — exactly one marker, or END before START (can't safely splice)
@@ -87,7 +87,7 @@ export function parseMarkers(content) {
     };
 }
 /**
- * Build a marked CLAUDE.md from its three parts. The END marker hash is
+ * Build a marked AGENTS.md from its three parts. The END marker hash is
  * computed from `blockBody` here, so callers never hand-maintain it.
  *
  * `blockBody` is expected to end with a newline (it is the content the START
@@ -105,7 +105,7 @@ export function composeMarkedFile(opts) {
         (opts.userRegion ?? ""));
 }
 /** True when the first non-blank line is an auriga workflow header. Used to
- *  tell an old-format (pre-marker) auriga CLAUDE.md from a foreign one. */
+ *  tell an old-format (pre-marker) auriga workflow file from a foreign one. */
 export function hasAurigaHeader(content) {
     for (const line of content.split("\n")) {
         if (line.trim().length === 0)

package/dist/workflow.d.ts

@@ -1,14 +1,13 @@
 import { type InstallOpts } from "./utils.js";
 export declare function installWorkflow(packageRoot: string, opts: InstallOpts): Promise<void>;
 /**
- * Uninstall the workflow (CLAUDE.md + AGENTS.md) from `opts.cwd`.
+ * Uninstall the workflow (AGENTS.md + CLAUDE.md) from `opts.cwd`.
  *
  * Safety contract:
  * - `opts.force` MUST be true. The CLI / server caller is responsible for
  *   confirming user intent BEFORE invoking this; we refuse otherwise.
- * - `AGENTS.md` is removed ONLY if it's a symlink (the install-time shape).
- *   A real-file AGENTS.md is left in place with a warning — the user has
- *   diverged from the install pattern and probably hand-edited it.
+ * - Real files are removed only when they are recognizable auriga workflow
+ *   files. Foreign instruction files are left in place with a warning.
  * - Missing files are a no-op: callers can re-run uninstall idempotently.
  * - `.claude/` is not touched; skills / plugins / hooks have their own
  *   uninstall paths.

package/dist/workflow.js

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { input, select } from "@inquirer/prompts";
-import { LANGUAGES, fetchExtraContent, log, withEsc, } from "./utils.js";
+import { DEFAULT_WORKFLOW_LANG, DEFAULT_WORKFLOW_TEMPLATE_FILE, LANGUAGES, fetchExtraContent, log, withEsc, } from "./utils.js";
 import { composeMarkedFile, hasAurigaHeader, hashBlock, parseMarkers, } from "./workflow-markers.js";
+import { LEGACY_AGENTS_SYMLINK_TARGET, WORKFLOW_COMPAT_FILE, WORKFLOW_COMPAT_SYMLINK_TARGET, WORKFLOW_PRIMARY_FILE, } from "./workflow-docs.js";
 /**
  * Back up `filePath` once. The canonical `<file>.bak` slot is reserved for the
  * FIRST capture (the user's pre-auriga original) and is never overwritten — a
@@ -12,8 +13,8 @@ import { composeMarkedFile, hasAurigaHeader, hashBlock, parseMarkers, } from "./
  * `verbatimSymlinks` copies a symlink AS a symlink, preserving its literal
  * (possibly relative) target — a foreign AGENTS.md may be a symlink pointing
  * elsewhere, and we want the backup to preserve that target verbatim rather
- * than snapshot whatever it currently resolves to. A real file (CLAUDE.md)
- * copies as a real file. `lstat` (not `existsSync`) probes the `.bak` slot so
+ * than snapshot whatever it currently resolves to. A real workflow file copies
+ * as a real file. `lstat` (not `existsSync`) probes the `.bak` slot so
  * a backup that is itself a possibly-broken symlink still counts as present
  * and is not silently overwritten.
  */
@@ -32,14 +33,26 @@ function backupOnce(filePath) {
     fs.cpSync(filePath, dest, { verbatimSymlinks: true });
     return dest;
 }
+function lstatMaybe(filePath) {
+    try {
+        return fs.lstatSync(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSymlinkTo(filePath, target) {
+    const stat = lstatMaybe(filePath);
+    return !!stat?.isSymbolicLink() && fs.readlinkSync(filePath) === target;
+}
 export async function installWorkflow(packageRoot, opts) {
     const lang = opts.interactive
         ? await withEsc(select({
-            message: "CLAUDE.md language:",
+            message: "Workflow language:",
             choices: LANGUAGES.map((l) => ({ name: l.label, value: l.value })),
-            default: "en",
+            default: DEFAULT_WORKFLOW_LANG,
         }))
-        : (opts.lang ?? "en");
+        : (opts.lang ?? DEFAULT_WORKFLOW_LANG);
     const targetDir = opts.interactive
         ? await withEsc(input({
             message: "Workflow install target directory:",
@@ -56,19 +69,19 @@ export async function installWorkflow(packageRoot, opts) {
         throw new Error(msg);
     }
     const langOpt = LANGUAGES.find((l) => l.value === lang);
-    // Lazy fetch: only download non-default language file when needed
-    if (langOpt.file !== "CLAUDE.md") {
+    // Lazy fetch: only download non-default language files when needed.
+    if (langOpt.file !== DEFAULT_WORKFLOW_TEMPLATE_FILE) {
         console.log(`Fetching ${langOpt.label} template...`);
         await fetchExtraContent(packageRoot, langOpt.file);
     }
-    const sourceClaude = path.join(packageRoot, langOpt.file);
-    const targetClaude = path.join(resolved, "CLAUDE.md");
-    const targetAgents = path.join(resolved, "AGENTS.md");
+    const sourceWorkflow = path.join(packageRoot, langOpt.file);
+    const targetPrimary = path.join(resolved, WORKFLOW_PRIMARY_FILE);
+    const targetCompat = path.join(resolved, WORKFLOW_COMPAT_FILE);
     // The packaged template is authored with managed-block markers. Extract its
     // managed block (the auriga workflow body) and its user-region placeholder.
     // Defensive fallback: if the template somehow lacks markers, treat the whole
     // file as the managed block with an empty user region.
-    const sourceContent = fs.readFileSync(sourceClaude, "utf8");
+    const sourceContent = fs.readFileSync(sourceWorkflow, "utf8");
     const sourceParsed = parseMarkers(sourceContent);
     const sourceBlock = sourceParsed.kind === "marked"
         ? sourceParsed.blockBody
@@ -76,16 +89,43 @@ export async function installWorkflow(packageRoot, opts) {
             ? sourceContent
             : sourceContent + "\n";
     const templateUserRegion = sourceParsed.kind === "marked" ? sourceParsed.userRegion : "";
+    const primaryStat = lstatMaybe(targetPrimary);
+    const compatStat = lstatMaybe(targetCompat);
+    const legacyShape = primaryStat?.isSymbolicLink() === true &&
+        fs.readlinkSync(targetPrimary) === LEGACY_AGENTS_SYMLINK_TARGET &&
+        compatStat?.isFile() === true;
+    const primaryForeignSymlink = primaryStat?.isSymbolicLink() === true &&
+        fs.readlinkSync(targetPrimary) !== LEGACY_AGENTS_SYMLINK_TARGET;
+    const compatIsCurrentPrimary = !primaryStat &&
+        compatStat !== undefined &&
+        !isSymlinkTo(targetCompat, WORKFLOW_COMPAT_SYMLINK_TARGET);
+    const currentPath = primaryStat && !primaryStat.isSymbolicLink()
+        ? targetPrimary
+        : legacyShape || compatIsCurrentPrimary
+            ? targetCompat
+            : undefined;
+    let wrotePrimary = false;
+    const writePrimary = (content) => {
+        if (primaryStat?.isSymbolicLink()) {
+            if (primaryForeignSymlink) {
+                const bak = backupOnce(targetPrimary);
+                log.warn(`AGENTS.md 是指向其它目标的软链;已备份到 ${path.basename(bak)} 后改为主文件。`);
+            }
+            fs.unlinkSync(targetPrimary);
+        }
+        fs.writeFileSync(targetPrimary, content);
+        wrotePrimary = true;
+    };
     // Installing the workflow doc is one of five cases. The managed block is
     // always replaced with the packaged version; the cases differ in how the
     // project's own content (the user region) is preserved or backed up.
-    if (!fs.existsSync(targetClaude)) {
+    if (!currentPath) {
         // 1. Fresh install — write the marked template as-is, no backup.
-        fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
-        log.ok(`CLAUDE.md installed (${langOpt.label})`);
+        writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+        log.ok(`AGENTS.md installed (${langOpt.label})`);
     }
     else {
-        const current = fs.readFileSync(targetClaude, "utf8");
+        const current = fs.readFileSync(currentPath, "utf8");
         const parsed = parseMarkers(current);
         if (parsed.kind === "marked") {
             // 2. Upgrade — splice the managed block, preserve the user region.
@@ -97,80 +137,74 @@ export async function installWorkflow(packageRoot, opts) {
             //        marker). Can't prove the block is untouched, so back up
             //        conservatively rather than risk silently dropping an edit.
             if (parsed.endHash === null) {
-                const bak = backupOnce(targetClaude);
-                log.warn(`CLAUDE.md 的受管区块缺少校验标记,无法确认是否被改动;升级前已备份到 ${path.basename(bak)}`);
+                const bak = backupOnce(currentPath);
+                log.warn(`工作流文档的受管区块缺少校验标记,无法确认是否被改动;升级前已备份到 ${path.basename(bak)}`);
             }
             else if (parsed.endHash !== hashBlock(parsed.blockBody)) {
-                const bak = backupOnce(targetClaude);
-                log.warn(`CLAUDE.md 的受管区块曾被手改;升级已整块覆盖该区块,改动前的文件见 ${path.basename(bak)}`);
+                const bak = backupOnce(currentPath);
+                log.warn(`工作流文档的受管区块曾被手改;升级已整块覆盖该区块,改动前的文件见 ${path.basename(bak)}`);
             }
-            fs.writeFileSync(targetClaude, composeMarkedFile({
+            writePrimary(composeMarkedFile({
                 prefix: parsed.prefix,
                 blockBody: sourceBlock,
                 userRegion: parsed.userRegion,
                 lang,
             }));
-            log.ok(`CLAUDE.md upgraded (${langOpt.label}); your project section was preserved`);
+            log.ok(`AGENTS.md upgraded (${langOpt.label}); your project section was preserved`);
         }
         else if (parsed.kind === "unmarked" && hasAurigaHeader(current)) {
-            // 3. Old-format migration — an auriga CLAUDE.md from before markers
+            // 3. Old-format migration — an auriga workflow doc from before markers
             //    existed. The user region can't be recovered from an unmarked file,
             //    so back the whole thing up and install fresh.
-            const bak = backupOnce(targetClaude);
-            fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
-            log.warn(`检测到旧版 CLAUDE.md(无受管标记);已备份到 ${path.basename(bak)}。` +
+            const bak = backupOnce(currentPath);
+            writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+            log.warn(`检测到旧版工作流文档(无受管标记);已备份到 ${path.basename(bak)}。` +
                 `若你改过它,请从备份把工程定制手动迁移到 END 标记之后的用户区。`);
-            log.ok(`CLAUDE.md migrated to the managed-block format (${langOpt.label})`);
+            log.ok(`AGENTS.md migrated to the managed-block format (${langOpt.label})`);
         }
         else if (parsed.kind === "unmarked") {
-            // 4. Foreign first install — a CLAUDE.md from another tool. Keep its
+            // 4. Foreign first install — a workflow doc from another tool. Keep its
             //    content in place as the user region; no backup needed.
             const foreign = current.endsWith("\n") ? current : current + "\n";
-            fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: "\n" + foreign, lang }));
-            log.ok(`CLAUDE.md installed (${langOpt.label}); your existing content was kept below the managed block`);
+            writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: "\n" + foreign, lang }));
+            log.ok(`AGENTS.md installed (${langOpt.label}); your existing content was kept below the managed block`);
+            if (currentPath === targetPrimary) {
+                log.warn("AGENTS.md already existed; its content was kept below the managed block.");
+            }
         }
         else {
             // 5. Malformed markers — can't locate the block boundaries safely.
             //    Back up and reinstall fresh rather than splice into a broken file.
-            const bak = backupOnce(targetClaude);
-            fs.writeFileSync(targetClaude, composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
-            log.warn(`CLAUDE.md 的受管标记已损坏(${parsed.reason});已备份到 ${path.basename(bak)} 并重装。`);
+            const bak = backupOnce(currentPath);
+            writePrimary(composeMarkedFile({ blockBody: sourceBlock, userRegion: templateUserRegion, lang }));
+            log.warn(`工作流文档的受管标记已损坏(${parsed.reason});已备份到 ${path.basename(bak)} 并重装。`);
         }
     }
-    // Point AGENTS.md at CLAUDE.md via a symlink (the install shape — Claude
-    // Code and Codex then read the same workflow doc). If the path is already
-    // occupied by something that ISN'T that symlink — a real file from another
-    // tool, or a symlink pointing elsewhere — it holds content or intent we
-    // must not silently destroy. Back it up first (symmetric with how a foreign
-    // / hand-edited CLAUDE.md is preserved above), then replace.
-    let agentsStat;
-    try {
-        agentsStat = fs.lstatSync(targetAgents);
-    }
-    catch {
-        // does not exist — nothing to preserve.
-    }
-    if (agentsStat) {
-        const pointsToClaude = agentsStat.isSymbolicLink() &&
-            fs.readlinkSync(targetAgents) === "CLAUDE.md";
-        if (!pointsToClaude) {
-            const bak = backupOnce(targetAgents);
-            log.warn(`AGENTS.md 不是指向 CLAUDE.md 的软链;已备份到 ${path.basename(bak)} 后替换为软链。`);
+    // Point CLAUDE.md at AGENTS.md via a compatibility symlink. If CLAUDE.md was
+    // the old primary file and its content was migrated above, replacing it with
+    // the symlink is safe. Otherwise preserve any real file or foreign symlink
+    // before replacing it.
+    const latestCompatStat = lstatMaybe(targetCompat);
+    if (latestCompatStat) {
+        const pointsToPrimary = isSymlinkTo(targetCompat, WORKFLOW_COMPAT_SYMLINK_TARGET);
+        const migratedFromCompat = currentPath === targetCompat && wrotePrimary && !latestCompatStat.isSymbolicLink();
+        if (!pointsToPrimary && !migratedFromCompat) {
+            const bak = backupOnce(targetCompat);
+            log.warn(`CLAUDE.md 不是指向 AGENTS.md 的软链;已备份到 ${path.basename(bak)} 后替换为软链。`);
         }
-        fs.unlinkSync(targetAgents);
+        fs.unlinkSync(targetCompat);
     }
-    fs.symlinkSync("CLAUDE.md", targetAgents);
-    log.ok("AGENTS.md -> CLAUDE.md symlink created");
+    fs.symlinkSync(WORKFLOW_COMPAT_SYMLINK_TARGET, targetCompat);
+    log.ok("CLAUDE.md -> AGENTS.md symlink created");
 }
 /**
- * Uninstall the workflow (CLAUDE.md + AGENTS.md) from `opts.cwd`.
+ * Uninstall the workflow (AGENTS.md + CLAUDE.md) from `opts.cwd`.
  *
  * Safety contract:
  * - `opts.force` MUST be true. The CLI / server caller is responsible for
  *   confirming user intent BEFORE invoking this; we refuse otherwise.
- * - `AGENTS.md` is removed ONLY if it's a symlink (the install-time shape).
- *   A real-file AGENTS.md is left in place with a warning — the user has
- *   diverged from the install pattern and probably hand-edited it.
+ * - Real files are removed only when they are recognizable auriga workflow
+ *   files. Foreign instruction files are left in place with a warning.
  * - Missing files are a no-op: callers can re-run uninstall idempotently.
  * - `.claude/` is not touched; skills / plugins / hooks have their own
  *   uninstall paths.
@@ -190,38 +224,58 @@ export async function uninstallWorkflow(opts) {
     const emit = (line) => {
         opts.onLog?.(line);
     };
-    const targetClaude = path.join(resolved, "CLAUDE.md");
-    const targetAgents = path.join(resolved, "AGENTS.md");
-    // CLAUDE.md — flat file. lstat to avoid following a symlink (would be
-    // unusual but we'd rather refuse to traverse than chase one out).
-    if (fs.existsSync(targetClaude)) {
-        fs.unlinkSync(targetClaude);
-        log.ok("CLAUDE.md removed");
-        emit("removed CLAUDE.md");
-    }
-    else {
-        log.skip("CLAUDE.md not present");
-        emit("CLAUDE.md not present");
-    }
-    // AGENTS.md — only remove symlinks (our install shape). lstatSync
-    // refuses to follow the link so we inspect the link itself.
-    try {
-        const stat = fs.lstatSync(targetAgents);
+    const targetClaude = path.join(resolved, WORKFLOW_COMPAT_FILE);
+    const targetAgents = path.join(resolved, WORKFLOW_PRIMARY_FILE);
+    const isAurigaWorkflowFile = (filePath) => {
+        try {
+            const content = fs.readFileSync(filePath, "utf8");
+            return parseMarkers(content).kind === "marked" || hasAurigaHeader(content);
+        }
+        catch {
+            return false;
+        }
+    };
+    const removeWorkflowPath = (filePath, name) => {
+        let stat;
+        try {
+            stat = fs.lstatSync(filePath);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                log.skip(`${name} not present`);
+                emit(`${name} not present`);
+                return;
+            }
+            throw err;
+        }
         if (stat.isSymbolicLink()) {
-            fs.unlinkSync(targetAgents);
-            log.ok("AGENTS.md symlink removed");
-            emit("removed AGENTS.md symlink");
+            const linkTarget = fs.readlinkSync(filePath);
+            const isManagedSymlink = (name === WORKFLOW_PRIMARY_FILE && linkTarget === LEGACY_AGENTS_SYMLINK_TARGET) ||
+                (name === WORKFLOW_COMPAT_FILE && linkTarget === WORKFLOW_COMPAT_SYMLINK_TARGET);
+            if (isManagedSymlink) {
+                fs.unlinkSync(filePath);
+                log.ok(`${name} symlink removed`);
+                emit(`removed ${name} symlink`);
+            }
+            else {
+                log.warn(`foreign ${name} symlink left in place`);
+                emit(`foreign ${name} symlink left in place`);
+            }
+        }
+        else if (stat.isFile() && isAurigaWorkflowFile(filePath)) {
+            fs.unlinkSync(filePath);
+            log.ok(`${name} removed`);
+            emit(`removed ${name}`);
         }
         else {
-            // Real file (or directory) — user diverged from install. Don't
-            // silently destroy their content; warn and leave it.
-            log.warn("AGENTS.md is not a symlink; left in place");
-            emit("AGENTS.md is not a symlink; left in place");
+            log.warn(`foreign ${name} left in place`);
+            emit(`foreign ${name} left in place`);
         }
-    }
-    catch {
-        // ENOENT — already gone, idempotent no-op.
-        log.skip("AGENTS.md not present");
-        emit("AGENTS.md not present");
-    }
+    };
+    // Remove AGENTS.md first because it is the current primary. lstatSync refuses
+    // to follow symlinks, so the legacy AGENTS.md -> CLAUDE.md shape is handled
+    // without deleting CLAUDE.md through the link.
+    removeWorkflowPath(targetAgents, "AGENTS.md");
+    removeWorkflowPath(targetClaude, "CLAUDE.md");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.28.0",
+  "version": "1.29.1",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins)",
   "license": "MIT",
   "repository": {
@@ -25,8 +25,8 @@
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "pretest": "npm run build",
-    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-markers.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/goalify.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
-    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-markers.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/goalify.test.js dist-test/tests/plugin-skill-frontmatter.test.js",
+    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-markers.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/goalify.test.js dist-test/tests/plugin-skill-frontmatter.test.js dist-test/tests/auriga-workflow-skills.test.js",
+    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/preset.test.js dist-test/tests/legacy-menu.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-markers.test.js dist-test/tests/workflow-install.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js dist-test/tests/spec-design.test.js dist-test/tests/goalify.test.js dist-test/tests/plugin-skill-frontmatter.test.js dist-test/tests/auriga-workflow-skills.test.js",
     "pretest:e2e": "npm run build",
     "test:e2e": "tsc -p tsconfig.test.json && node --test dist-test/tests/e2e-install.test.js",
     "pretest:web-ui-e2e": "npm run build && npm --prefix ui ci && npm --prefix ui run build",