auriga-cli 1.27.0 → 1.29.0

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,20 +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
 
-Copies `CLAUDE.md` to 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`.
 
-- Backs up existing `CLAUDE.md` before overwriting
+- **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 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
@@ -133,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,20 +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` 显式选择。
 
-- 目标已有 `CLAUDE.md` 时会自动备份后覆盖
+- **可扩展、可升级**：auriga 工作流被一对 `<!-- AURIGA:WORKFLOW:v1 START/END -->` 标记包成「受管区块」。把你的工程专属规则写在 END 标记**之后**——再次安装只就地升级受管区块,你的内容原样保留。
+- 旧版本装下的、无标记的 `CLAUDE.md` 会在下次安装时安全迁移到新的 `AGENTS.md` 主文件形态,旧文件备份到 `CLAUDE.md.bak`。别的工具生成的 `AGENTS.md` 或 `CLAUDE.md` 会作为用户区保留在全新受管区块下方。
 - 涵盖：需求澄清、TDD、代码 Review、分支工作流、Subagent 编排
 
 ### Skills
@@ -133,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 AGENTS.md (the default).
+ * - "en":    English AGENTS.en.md.
  *
  * 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-16T06:04:29.959Z",
+  "generatedAt": "2026-05-16T13:16:49.448Z",
   "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,7 +693,7 @@ 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,
+    //   - contentRoot: where the runtime install recipes live (AGENTS.md,
     //     marketplace manifests, extra_plugin_configs.json, skills-lock.json).
     //     These files are
     //     NOT in the npm tarball — the `files` allowlist only ships `dist/*`
@@ -750,7 +757,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,7 +774,7 @@ async function runUi(p, version) {
         pluginAgentsByName.set(name, def.agents);
     }
     const applyHandlers = buildDefaultApplyHandlers({
-        // contentRoot: install handlers read CLAUDE.md, marketplace manifests,
+        // contentRoot: install handlers read AGENTS.md, 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,
@@ -793,7 +800,7 @@ 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
+                // (marketplace manifests, extra plugin config, AGENTS.md, …) was already injected
                 // into applyHandlers above with contentRoot.
                 packageRoot: tarballRoot,
                 heartbeatTimeoutMs: UI_HEARTBEAT_TIMEOUT_MS,
@@ -878,13 +885,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 +935,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 +943,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 workflow in the root AGENTS.md
 // 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
@@ -24,6 +25,8 @@ import fs from "node:fs";
 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
@@ -147,50 +150,63 @@ function aggregateStatus(records) {
 // ---------------------------------------------------------------------------
 // Workflow
 // ---------------------------------------------------------------------------
-const WORKFLOW_HEADER_RE = /^#\s+auriga\s+Workflow\s*\(v\d+\.\d+\.\d+\)/;
 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 };
     }
-    // Walk the first non-blank lines looking for the auriga header. We only
-    // need to know "is this our CLAUDE.md or foreign" — the actual version
-    // string is unused since v1.19.0 dropped update-available status.
-    for (const line of content.split(/\r?\n/)) {
-        if (WORKFLOW_HEADER_RE.test(line)) {
-            return { status: "installed", observedScope: scope };
-        }
-        if (line.trim().length > 0)
-            break;
-    }
-    // CLAUDE.md exists but no recognizable auriga marker. The file is foreign
-    // — not our workflow. Report `not-installed` honestly; the install path
-    // (src/workflow.ts) protects user content by backing it up to
-    // `CLAUDE.md.bak` (backup-once: never clobbers a prior .bak).
+    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.
+    //   - an auriga workflow header with no markers (a pre-marker install).
+    //     Still ours; the next install migrates it to the marked format.
+    if (parseMarkers(content).kind === "marked" || hasAurigaHeader(content)) {
+        return { status: "installed", observedScope: scope };
+    }
+    // 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 back up to CLAUDE.md.bak.`,
+        code: workflowForeignWarningCode(filePath),
+        message: workflowForeignWarningMessage(filePath),
     });
     return { status: "not-installed", observedScope: scope };
 }