参与贡献
有用的贡献让比赛更容易理解、参加、运行或验证。先找到拥有这个行为的仓库，然后读它的 README、源码和相关测试。各应用仓库是彼此独立的 Git 检出，即使你把它们放在同一个父目录下开发也是如此。
各类内容写在哪里
| 位置 | 包含什么 |
|---|---|
| 本章节 | 平台如何构成，到各个部件及其契约的层面 |
仓库的 README.md | 如何运行、配置、运维和发布它；它的目录布局、不变量和已知缺口 |
仓库的 CLAUDE.md | 改动之后要运行的检查，以及代码本身没有说明的规则和陷阱 |
| 源码 | 其余一切：SQL 语句、工作流描述和注释就是规范 |
平台不保留决策记录，也不保留状态日志。仓库的 Known gaps（已知缺口）一节就是它的待办工作：在打开或关闭一个缺口的那次改动里把它更新到最新。在把一个说法写进代码或文档之前，先对照当前的生产方和消费方核实它。对用户可见的改动，要描述参赛者做了什么、随后看到什么，以及涉及的内部组件。
每个仓库都直接提交到 main；没有功能分支。
源码约定
Soma 和 Kalam 的包是整个提交的，你直接编辑提交的文件：没有生成器，也没有什么需要重新生成。构建出的插件和 Ants 的构建产物不进 git，而是随各自仓库的镜像发布，Ants 则随它的 GitHub 发布版本发布。
发布一个 Ants 发布版本就是在更新 Kalam 所玩的引擎：Kalam 的镜像从 Ants 的最新发布版本、或 ANTS_RELEASE 指定的标签获取组件，自己不内置副本。本地重新构建的结果只有在你用 --build-context ants=<an ants dist/> 构建 Kalam 镜像时才会进入镜像。对组件源码的任何改动都会改变它的摘要，注释也不例外。既然 wasm 本身会变，重构就要用产物差异和逐回合输出哈希来证明，之后再重新给插件签名。
数据库模式的改动放进 Soma 的两个迁移文件，在模式尚未正式发布期间就地重写它们；然后检查每一个使用它的包。部署地址和凭据放在配置里。用锁定的 Orion 版本对定义做 lint，因为别的版本可能报出误导性的兼容性错误。
重要的检查
运行你改动的仓库和边界所对应的检查：
| 范围 | 现有的检查，在该仓库根目录运行 |
|---|---|
| 文档 | mdbook build；tutorials/build.sh，它的摘要检查会拒绝内置查看器画不对的回放 |
| Ants | ./build.sh：确定性检查、engine/ 和 mapgen/ 里的 cargo test，然后把每个产物输出到 dist/；viz/build.sh 构建查看器；tools/equivalence.py 逐回合比对发布版本与检出 |
| Soma 插件 | cargo test --manifest-path plugins/Cargo.toml，两个 crate 都要跑 |
| Soma、Kalam 的定义 | 两个仓库里的 ./scripts/check-defs.sh：名称和标签、对定义的 clippy 和 fmt，以及每个工作流的离线用例；Soma 的 ./scripts/check-sql.sh 和 ./scripts/verify/run.sh |
| Web | npm run lint 和 npm run build |
| 整个栈 | web 的 ./scripts/check/configs.sh，以及在 web 的 compose 栈上配合一个 Kalam 运行器跑一遍有代表性的端到端流程（scripts/dev/submission-storm.py） |
| CLI | cargo fmt --check、cargo clippy --locked --release -- -D warnings、cargo test --locked --release，用这次构建打一遍入门套件的对局，并对仓库保存在 fixtures/ 下、由 Kalam 写出的回放运行 tinybrains conform |
check/configs.sh 横跨多个仓库：它断言边界两侧必须相等的常量（引擎摘要与赛季及每个副本所指定的值、模型前缀、适配器预算和 Orion 版本）。
SQL 检查会创建一次性的临时数据库并验证随包发布的语句；它们对线上的调度或并发什么也证明不了。所需镜像缺失时，配置检查可能会跳过运行时解析。tinybrains conform 让 CLI 的对局循环与 Kalam 的工作流保持一致，它需要一个回放来运行。报告时写明跑了什么，包括这些局限。
API 契约的改动要通过 HTTP 工作流实际演练。游戏或适配器的改动需要行为示例。回放的改动需要从真实存储的封包做一次重建；引擎内部的测试夹具不够。单元检查无法确定结果时，用本地栈来取得集成证据。
撰写文档
先面向参赛者：他们需要构建什么、平台检查什么、他们能观察到什么，以及接下来做什么。架构内容留在这个平台章节里，除非它解释的是某个实际的限制；并且保持在部件与契约的层面：源码才是规范。规划中的工具要标明是规划中的，绝不要把设计提案写成可用的接口。写现在为真的事，略去曾经如何。
书内使用相对链接，并让 src/SUMMARY.md 与页面保持一致。回放占位要说明它将要展示的行为，并保留文字解释。拿到素材之后再记录真实的回放和引擎标识，绝不要编造对局结果来填充示例位置。
提交改动
说明具体的问题和改动后的行为，列出它触及的契约，并给出支持它的检查。改动需要时，附上生成或内置的输出，并在同一次改动里更新面向参赛者的文档。跨仓库的改动要写明它需要的配套修订和部署顺序，好让评审者能评估一组一致的产物。
问题报告要给出相关的版本或对局 ID、预期与实际观察到的行为，以及复现步骤。不要附上会话 cookie 和部署凭据。尽可能保留导致失败的输入或回放，这样修复的人就能对照原始问题验证修复。