Endorphin-Document/AGENTS.md

文档维护约定

适用于本目录及所有子目录。

文档组织

• 正文放在 guide，按概念依赖顺序编号；术语、文法、设计状态和补充说明放在 appendices。
• README 作为读者入口，提供顺序目录与查询索引，不用核心约定清单替代语言介绍。
• 每章先定义概念，再说明语法、示例和行为。内容应在未阅读讨论历史的情况下独立成立。
• 使用技术文档陈述句，不使用对话回应、提问清单、讨论过程或开发日志作为正文。
• 不在各章重复说明全书目标、全部约束和设计过程；未定规则集中维护在规范状态附录，必要的局部提案保留短注。
• 每个概念指定主要说明章节，其余章节使用引用；完整 EBNF 集中在形式文法附录。
• 修改章节位置时同步更新目录、相邻导航、术语索引、正文链接与文法。外部读者正文使用中文。

语言边界

• 只使用语言名称 Endorphin，不出现开发软件代称、版本或实现兼容说明。
• 文档定义源码与可观察效果，不以开发实现进度定义语言规则。
• 构建阶段固定为 Preflight，运行阶段固定为 inflight，保持大小写；定义见 guide/05-preflight-and-inflight.md。
• 两个阶段名称不自动成为源码关键字。新增语法说明必要的 Preflight 检查和 inflight 效果。
• 不设计云端实体、持久化类或自动建表。数据读取只是逻辑调用用法，不引入通信、缓存、部署与编排方案。
• 普通调用不要求业务代码额外定义 RPC 服务、监听器、协议客户端或接口描述文件。

示例与状态

• key 采用用户名:namespace路径，用户名唯一，路径至少一级；各层 namespace 语义一致。
• 归属通过外部 key 与索引提供，正文不声明自身 namespace。
• use 只引用完整 key，不附加选择性名称列表。
• 官方 UI 组件不列为示例用户库的内容；未定的官方引用方式不可写成免导入默认能力。
• 示例围绕商品定价展开，标明外部归属与片段位置；局部片段不能混写为完整程序。
• 名称查找、可见性和数据读取成员的假设明确说明，不虚构未确认 API。
• 已确定约定、语法提案和未定义边界统一记录在 appendices/specification-status.md；文档重构不代表语法提案被确认。
• 共用程序和表达式文法；UI 单根限制仅约束 render，不限制全语言。