AGENTS.md git:20261017.f2ede2dA

Immutable. This exact content never changes and is served at /api/v1/blob/3e6836578f9f60cc.

<!-- TRELLIS:START -->
# Trellis Instructions

These instructions are for AI assistants working in this project.

This project is managed by Trellis. The working knowledge you need lives under `.trellis/`:

- `.trellis/workflow.md` — development phases, when to create tasks, skill routing
- `.trellis/spec/` — package- and layer-scoped coding guidelines (read before writing code in a given layer)
- `.trellis/workspace/` — per-developer journals and session traces
- `.trellis/tasks/` — active and archived tasks (PRDs, research, jsonl context)

If a Trellis command is available on your platform (e.g. `/trellis:finish-work`, `/trellis:continue`), prefer it over manual steps. Not every platform exposes every command.

If you're using Codex or another agent-capable tool, additional project-scoped helpers may live in:
- `.agents/skills/` — reusable Trellis skills
- `.codex/agents/` — optional custom subagents

Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.

<!-- TRELLIS:END -->

## UI Component Policy

- For frontend UI, prefer the project's existing shadcn components and compose them before writing custom interactive primitives.
- If a required component is missing, add the matching shadcn/Radix component and wrap it under `src/components/ui/` so styling, accessibility, focus management, and behavior stay consistent.
- Write a custom component only when shadcn components and their composition APIs cannot satisfy the requirement. Record the reason before doing so.
- Custom UI must still reuse the project's Rhea theme tokens, spacing, radii, states, and accessibility conventions. Do not substitute native interactive shortcuts such as `details/summary` when an appropriate shadcn component exists.

## Git Commit Language

- Use Conventional Commit type prefixes such as `feat:`, `fix:`, and `docs:`.
- Write the commit subject and body in Chinese by default. Use English only when the user explicitly requests it.

## 文档规范（Documentation Layout）

`docs/` 按**生命周期**分区，入口是 [`docs/README.md`](docs/README.md)（文档地图）。**新增或移动文档前先读它。**

| 目录 | 放什么 | 更新策略 |
|:--|:--|:--|
| `docs/guides/` | 安装、开发、客户端接入步骤 | 跟版本更新 |
| `docs/policies/` | 许可、免责声明（README 引用） | 极少 |
| `docs/specs/` | 现行架构与决策（`PLAN.md` / `P*-ARCH.md` / `DECISIONS.md` / `VOCABULARY.md`） | **改行为就同步改** |
| `docs/history/` | 已完结的一次性报告（审计、探针、调研、旧方案） | **只读，不再改** |
| `docs/prototype/` | 原型 + JSDOM 校验套件 | 新交互先进这里 |
| `docs/releases/` | 每版发布说明（`gen-release-notes.mjs` 约定路径） | 每版一篇 |

硬性约定：

- **`docs/prototype/` 不是普通文档**：`scripts/check-scope-registry.cjs` 会直接读取其中的 `demo-app.js` 与 `buddy-switch-prototype.html`。改名或移动必须同步改脚本，否则 `npm run build` 会红。
- **不要新建同义文档**：`docs/specs/` 里已有主题就直接改那一篇；确认过时才新开，并在首段写状态行（`> 状态：现行 / 待拍板 / 实施中`）。
- **一次性文档带日期**（`xxx-2026-10-17.md`），完结后移入 `docs/history/` 并加 `> 状态：只读历史` 头。
- **移动/新增文档后必须更新 `docs/README.md` 的表格**——索引与文件不同步比没有索引更坏。
- 代码注释引用设计依据时写**仓库相对路径**（`docs/specs/P5-ARCH.md`），不要写裸文件名。