feat: centralize agent docs harness

apps/docs/content/docs/en/add.md

@@ -3,7 +3,7 @@ title: one add
 description: Add a templated project to an existing workspace.
 ---
 
-`one add` selects a template from the registry, writes it into the workspace, registers it in the manifest, and syncs template defaults such as Dockerfile, Kustomize, workflows, and AI guides.
+`one add` selects a template from the registry, writes it into the workspace, registers it in the manifest, and syncs template defaults such as Dockerfile, Kustomize, workflows, and agent docs.
 
 There are two entry points:
 
@@ -54,15 +54,21 @@ one add nestjs-api --name api --yes
     "status": "completed",
     "providers": ["codex", "claude-code"],
     "generated_files": [
-      "/abs/path/my-app/AGENTS.md",
-      "/abs/path/my-app/CLAUDE.md"
+      "AGENTS.md",
+      "CLAUDE.md",
+      ".one/agents/conventions.md",
+      ".one/agents/projects/services-user-api.md",
+      ".one/agents/ops/dev.md",
+      ".one/agents/ops/secrets.md",
+      ".one/agents/ops/container.md",
+      ".one/agents/ops/deploy.md"
     ],
-    "file_count": 2
+    "file_count": 8
   }
 }
 ```
 
-`warnings[]` means a compatibility or post-sync step produced a non-blocking warning; the project was still added. `ai_guides.status` tells you whether root `AGENTS.md` / `CLAUDE.md` refreshed successfully. `ai_guides.generated_files` contains absolute paths under the workspace root.
+`warnings[]` means a compatibility or post-sync step produced a non-blocking warning; the project was still added. `ai_guides.status` tells you whether root `AGENTS.md`, `CLAUDE.md`, and `.one/agents/**` refreshed successfully. `ai_guides.generated_files` contains workspace-relative paths.
 
 ## Examples
 
@@ -112,9 +118,9 @@ one add nestjs-api --name user-api --yes -o json | jq
 - Adds `kustomize/base` and `kustomize/overlays/{dev,staging,prod}` for `deploy/kustomize`
 - S3-compatible deploy projects do not write local deploy artifacts; deploy uses the object-storage profile configured by `one configure add deploy/aws-s3 --profile <name>` or another split S3 backend (`deploy/aliyun-oss`, `deploy/r2`, etc.)
 - Adds GitHub Actions workflow entries
-- Refreshes `AGENTS.md` / `CLAUDE.md`
+- Refreshes `AGENTS.md`, `CLAUDE.md`, and `.one/agents/**`
 
-If a non-critical step fails, such as AI guide refresh, the project still exists and the related status is marked `failed` or `skipped`.
+If a non-critical step fails, such as agent-doc refresh, the project still exists and the related status is marked `failed` or `skipped`.
 
 ## Common Errors
 
@@ -138,5 +144,5 @@ Not sure which one to use? Read the [template decision tree](/en/docs/templates/
 ## After Adding
 
 - Check `one.manifest.json#projects[]` to confirm registration
-- AI guides and container / deploy artifacts are synced by `one add`
+- Agent docs and container / deploy artifacts are synced by `one add`
 - `one add` does not install dependencies: JS / TS workspaces install from the root with the package manager; Go projects run `go mod download` in the project directory, then `go mod tidy` only after changing imports or when module metadata needs repair

apps/docs/content/docs/en/ai-native.md

@@ -17,7 +17,7 @@ That layer covers four boundaries:
 
 1. **Automation interface**: agents and CI read structured output instead of scraping terminal text.
 2. **Error recovery**: agents recover from stable codes, context, and remediation hints.
-3. **Engineering contracts**: agents read durable rules from `AGENTS.md` / `CLAUDE.md`.
+3. **Engineering contracts**: agents read durable rules from `AGENTS.md` and `.one/agents/` (`CLAUDE.md` points to `AGENTS.md`).
 4. **Permission boundaries**: local credentials, environment setup, and deployment configuration have explicit owners instead of being guessed by agents.
 
 ## Rule 1: Command Output Must Be Parseable
@@ -97,13 +97,15 @@ The full catalogue is in [Error codes](/en/docs/error-codes/).
 
 ## Rule 3: Engineering Contracts Belong In The Repository
 
-When One CLI creates a workspace or adds a template, it maintains repository-level agent guides:
+When One CLI creates a workspace or adds a template, it maintains a repository-level agent harness:
 
-- `AGENTS.md`: read by Codex and similar agents
-- `CLAUDE.md`: read by Claude Code
-- Each template's own `CLAUDE.md`: copied into the generated subproject with stack-specific rules
+- `AGENTS.md`: the canonical, thin routing entry for Codex and similar agents
+- `CLAUDE.md`: a generated pointer that tells Claude Code to follow `./AGENTS.md`
+- `.one/agents/conventions.md`: workspace-level conventions and One CLI operating rules
+- `.one/agents/projects/<dir>.md`: one stack-specific guide per manifest project, named from `relativeDir` with slashes flattened to hyphens
+- `.one/agents/ops/*.md`: domain operation guides for `one dev`, `one env`, `one container`, and `one deploy` when the manifest enables those domains
 
-These files are not temporary prompts. They are part of the repository. An agent entering the workspace should read them before deciding how to code, run commands, install dependencies, or change configuration.
+These files are not temporary prompts. They are a projection of `one.manifest.json`: the manifest is the source of truth, `AGENTS.md` stays small, and detail files are opened on demand. One CLI does not copy agent stubs into subproject directories.
 
 Example rules:
 
@@ -155,9 +157,9 @@ Inside any One workspace, trigger a missing template to see the `one-cli/error/v
 one add api-fastify --name api --yes -o json
 ```
 
-After adding a real template, check the workspace-level and subproject-level agent guides:
+After adding a real template, check the workspace-level router and centralized detail guides:
 
 ```bash
 one add nestjs-api --name api --yes -o json
-ls AGENTS.md CLAUDE.md services/api/CLAUDE.md
+ls AGENTS.md CLAUDE.md .one/agents/conventions.md .one/agents/projects/services-api.md
 ```

apps/docs/content/docs/en/error-codes.md

@@ -223,9 +223,9 @@ Profile file schema does not match this binary. Upgrade CLI or recreate profiles
 Release-flow backend expected a toolchain or repo state that the workspace does not have.
 
 
-## AI Guides / Skills
+## Agent Docs / Skills
 
-`AGENTS.md`, `CLAUDE.md`, and One CLI skill installation.
+`AGENTS.md`, `CLAUDE.md`, `.one/agents/**`, and One CLI skill installation.
 
 ### `AI_CONFIG_INVALID`
 
@@ -237,7 +237,7 @@ Legacy provider gate; the current CLI renders all supported providers and should
 
 ### `AI_GUIDES_FAILED`
 
-AI guide refresh failed. Read the surfaced error.
+Agent docs refresh failed. Read the surfaced error.
 
 ### `AI_GUIDE_EXISTS`
 

apps/docs/content/docs/zh/add.md

@@ -54,15 +54,21 @@ one add nestjs-api --name api --yes
     "status": "completed",
     "providers": ["codex", "claude-code"],
     "generated_files": [
-      "/abs/path/my-app/AGENTS.md",
-      "/abs/path/my-app/CLAUDE.md"
+      "AGENTS.md",
+      "CLAUDE.md",
+      ".one/agents/conventions.md",
+      ".one/agents/projects/services-user-api.md",
+      ".one/agents/ops/dev.md",
+      ".one/agents/ops/secrets.md",
+      ".one/agents/ops/container.md",
+      ".one/agents/ops/deploy.md"
     ],
-    "file_count": 2
+    "file_count": 8
   }
 }
 ```
 
-`warnings[]` 存在时表示模板兼容性或后置同步有非阻断提示；项目仍然加成功。`ai_guides.status` 表示根目录 `AGENTS.md` / `CLAUDE.md` 是否刷新成功。`ai_guides.generated_files` 是工作区根目录下的绝对路径。
+`warnings[]` 存在时表示模板兼容性或后置同步有非阻断提示；项目仍然加成功。`ai_guides.status` 表示根目录 `AGENTS.md`、`CLAUDE.md` 和 `.one/agents/**` 是否刷新成功。`ai_guides.generated_files` 是工作区相对路径。
 
 ## 示例
 
@@ -112,9 +118,9 @@ one add nestjs-api --name user-api --yes -o json | jq
 - `deploy/kustomize` 工作区根加 `kustomize/base` 和 `kustomize/overlays/{dev,staging,prod}`
 - S3 兼容 deploy 后端不写本地部署产物；部署时使用 `one configure add deploy/aws-s3 --profile <name>` 或其它拆分后的 S3 后端（`deploy/aliyun-oss`、`deploy/r2` 等）配置的对象存储 profile
 - 加 GitHub Actions workflow 条目
-- 刷 `AGENTS.md` / `CLAUDE.md`
+- 刷 `AGENTS.md`、`CLAUDE.md` 和 `.one/agents/**`
 
-如果有失败的 step（比如 AI 指南刷新失败），项目仍然加成功，只是相关字段会标 `failed` / `skipped`。
+如果有失败的 step（比如 agent 文档刷新失败），项目仍然加成功，只是相关字段会标 `failed` / `skipped`。
 
 ## 错误恢复
 
@@ -138,5 +144,5 @@ one add nestjs-api --name user-api --yes -o json | jq
 ## 加完之后
 
 - 检查 `one.manifest.json#projects[]` 确认项目登记
-- AI 指南、容器 / 部署 artefacts 都已由 `one add` 在执行过程中同步完成
+- Agent 文档、容器 / 部署 artefacts 都已由 `one add` 在执行过程中同步完成
 - `one add` 不自动安装依赖：JS / TS 工作区在根目录跑 package manager install；Go 项目进项目目录跑 `go mod download`，修改 imports 或需要修复模块元数据时再跑 `go mod tidy`

apps/docs/content/docs/zh/ai-native.md

@@ -17,7 +17,7 @@ One CLI 不只生成项目文件，也会在 monorepo 里留下可持续执行
 
 1. **自动化接口**：agent 和 CI 读取结构化输出，不抓终端文本
 2. **错误恢复**：agent 按稳定错误码、上下文和恢复建议处理失败
-3. **工程契约**：agent 从仓库里的 `AGENTS.md` / `CLAUDE.md` 读取长期规则
+3. **工程契约**：agent 从仓库里的 `AGENTS.md` 和 `.one/agents/` 读取长期规则（`CLAUDE.md` 指向 `AGENTS.md`）
 4. **权限边界**：本机凭据、环境和部署配置有明确归属，不交给 agent 猜
 
 ## 规则一：命令输出必须可解析
@@ -97,13 +97,15 @@ agent 的处理顺序应该是：
 
 ## 规则三：工程契约要留在仓库里
 
-One CLI 创建工作区和添加模板时，会维护仓库级 agent 指南：
+One CLI 创建工作区和添加模板时，会维护仓库级 agent harness：
 
-- `AGENTS.md`：给 Codex 等 agent 读取
-- `CLAUDE.md`：给 Claude Code 读取
-- 每个模板自己的 `CLAUDE.md`：放在生成出来的子项目里，描述该技术栈的约定
+- `AGENTS.md`：canonical 的瘦路由入口，给 Codex 等 agent 读取
+- `CLAUDE.md`：生成的一行指针，让 Claude Code 跟随 `./AGENTS.md`
+- `.one/agents/conventions.md`：工作区约定和 One CLI 操作规则
+- `.one/agents/projects/<dir>.md`：每个 manifest 项目一份技术栈指南，文件名来自 `relativeDir`，斜杠会拍平成连字符
+- `.one/agents/ops/*.md`：当 manifest 启用相关 domain 时生成 `one dev`、`one env`、`one container`、`one deploy` 操作指南
 
-这些文件不是一次性提示词，而是仓库的一部分。agent 进来后先读它们，再决定怎么写代码、跑命令、补依赖和改配置。
+这些文件不是一次性提示词，而是 `one.manifest.json` 的投影：manifest 是事实源，`AGENTS.md` 保持小而稳定，细节文件按需打开。One CLI 不会再把 agent stub 复制进子项目目录。
 
 示例约定：
 
@@ -155,9 +157,9 @@ one templates -o json
 one add api-fastify --name api --yes -o json
 ```
 
-添加一个真实模板后，可以检查工作区级和子项目级 agent 指南：
+添加一个真实模板后，可以检查工作区级路由和集中式细节指南：
 
 ```bash
 one add nestjs-api --name api --yes -o json
-ls AGENTS.md CLAUDE.md services/api/CLAUDE.md
+ls AGENTS.md CLAUDE.md .one/agents/conventions.md .one/agents/projects/services-api.md
 ```

apps/docs/content/docs/zh/error-codes.md

@@ -321,9 +321,9 @@ The release-flow backend's expected toolchain or repo state does not match the w
 
 > 没有默认 remediation。具体恢复方式请看错误的 `context` 字段。
 
-## AI 指南 / Skills
+## Agent 文档 / Skills
 
-`AGENTS.md` / `CLAUDE.md` 生成与 bundled skill 安装。
+`AGENTS.md` / `CLAUDE.md` / `.one/agents/**` 生成与 bundled skill 安装。
 
 ### `AI_CONFIG_INVALID`
 
@@ -339,7 +339,7 @@ Reserved for legacy AI provider gates; current workspaces always render for ever
 
 ### `AI_GUIDES_FAILED`
 
-AI guides refresh failed; see surfaced error message.
+Agent docs refresh failed; see surfaced error message.
 
 > 没有默认 remediation。具体恢复方式请看错误的 `context` 字段。