📝 docs: rewrite AGENTS.md for JevTown

AGENTS.md

@@ -1,59 +1,45 @@
-# remaining-time · Agent 协作约定
-
-## 分支与 PR
-
-- 默认集成分支为 `dev`。
-- 用户说“同步”“拉取最新”或“合入后同步”时，默认同步 `dev`：先 fetch，再切换到本地
-  `dev`，以 fast-forward 方式更新到 `origin/dev`。
-- 新建 feature、fix 或其他工作分支前，先同步 `dev`，从最新的 `dev` 创建分支。
-- 所有 PR 默认以 `dev` 为 base；创建时显式指定 `--base dev`，不依赖 GitHub 仓库的默认分支设置。
-- 以上约定从 `feat/character-dialogue-bubbles` 分支开始执行。处理已有工作分支时，先确认它与 `dev`
-  的提交关系，保留本地改动；不要为了切换 base 擅自丢弃工作或改写已发布历史。
-- 只有用户明确指定其他目标分支时才覆盖这些默认值。向 `main` 集成属于用户明确安排的操作。
-
-## 主线与实验方向
-
-- `main` / `dev`
-  主线继续保持任务、经济及其他玩法系统的最简实现，只承载当前明确需要的能力，不为实验想法预建复杂框架。主线不保留酒馆内容包及餐饮、演出、教学系统；这些内容仅在实验分支维护。
-- 独立实验分支 `experiment/tavern-agentic` 以 tavern 为试验场，逐步落地酒馆玩法、NPC
-  Agent 与涌现交互等探索性想法；实验不受主线功能范围限制，但仍按具体需求迭代。
-- 实验分支首次从同步后的 `dev` 创建，与已有的 `feat/agentic`
-  分开维护。后续实验工作分支从该实验分支创建，PR 显式以实验分支为 base，作为上述默认分支约定的例外。
-- 实验功能不默认合回 `dev` /
-  `main`，也不因主线要求最简而擅自删除实验内容。需要合回的能力另行确认，并只提取主线实际需要的最小改动。
-
-## 文档分工
-
-- 世界定义、运行状态、记录与持久化恢复的架构说明集中在公共文档仓库，按日期与游戏代码提交号发布快照，列出具体字段结构、嵌套关系、可选性、单位和引用，并标明适用模式及可能过时的范围。
-- 修正事实错误时保留版本依据；职责或存储方式发生实质变化时另写快照并相互链接，不为每次代码修改同步重写架构文档。
-- 游戏仓库 `docs/`
-  暂停新增与扩写；已被快照覆盖的旧说明可删除并修复引用，保留仍有独立价值的视觉说明、设计参考与测试样例。玩家向系统说明与架构快照分开组织。
-
-## 资产制作与 PR
-
-- 当前资产改动统一追加到 PR #68 的 `chore/unit-404-extraction` 分支，目标为
-  `dev`；使用现有 worktree 前先检查状态，保留其他本地改动。#68 合并后再确定后续资产 PR。
-- 当前阶段先保留各房间空背景、原始布局图与布局数据，搭建房间间连接、通行和任务接入，再逐件添加可独立摆放的物件资产。大地图由多个房间及门连接组成。
-- 地图资产制作遵循
-  `.agents/skills/map-asset-extraction/SKILL.md`：从原图矩形框取材，由 Agent 规划独立物件，逐件提取并补全遮挡；保持原始透视，核对后再交付。
-- 制作候选和提示词保留在本地制作目录；未经验收不替换已收录的正式资产。
-
-## 快速迭代
-
-- 当前处于 MVP 快速迭代阶段，优先完成用户要求的改动，控制范围。
-- 默认不主动新增或运行测试、类型检查、lint、构建、浏览器自动化、试玩或截图检查；用户明确要求或修复当前实际错误确有必要时再做最小检查。
-- 先读取必要代码、理解实际流程再修改，不借验证之名扩展任务，也不顺带添加未要求的功能。
-- 保留与当前任务无关的本地文件和改动，提交时明确选择本次涉及的文件。
-- 未验证时如实说明，不声称测试通过。
-
-## 提交与 PR 描述
-
-- 标题沿用 `<gitmoji> <type>: <subject>` 风格，PR 描述保留并填写
-  `.github/pull_request_template.md`。
-- 每个 Agent 协助完成的提交必须在实际提交消息末尾保留对应的 `Co-authored-by` trailer。Codex 使用
-  `Co-authored-by: Codex <codex@openai.com>`。
-- 可通过 `PI_MODEL` 确认模型 ID 时，在同一个 trailer 段落另写一行
-  `AI-Model: <实际模型 ID>`；不可猜测模型。
-- trailer 段落与标题、正文之间留真实空行。优先将完整消息写入 UTF-8 文件，再用 `git commit -F` 提交。
-- 创建提交后、推送前，读取 `git log -1 --format=%B` 并通过 `git interpret-trailers --parse`
-  确认署名确实存在；squash 合并也需保留署名。
+# JevTown · Agent Guide
+
+## Branches and PRs
+
+- `main` is the main branch. Unless told otherwise, branch from the latest `origin/main` and open
+  PRs against `main`.
+- `feat/agentic` is the development branch for agentic features. Agentic work branches from
+  `feat/agentic` and its PRs target `feat/agentic`.
+- Pass `--base` explicitly when creating a PR instead of relying on the repository default.
+- Only integrate `feat/agentic` into `main` when the user asks for it.
+- Preserve local changes unrelated to the task, and don't rewrite published history.
+
+## CI
+
+PRs into `main` run these checks:
+
+- Format: `npm run fmt:check` (Prettier; `npm run fmt` fixes it)
+- Lint: `npm run lint`
+- Typecheck: `npx tsc --noEmit`
+- Unit tests: `npm test`
+- PR title validation (see below)
+
+`npm install` sets `core.hooksPath` to `.githooks`. The pre-commit hook then runs Prettier on staged
+files.
+
+## Docs
+
+- `docs/` is open for new and updated documents. Update design docs when the design they describe
+  changes.
+- Numbered design docs use `docs/NN-topic.md`. Commit subjects may cite the section they implement,
+  e.g. `(docs/13 §2)`.
+- Keep player-facing explanations separate from design and architecture docs.
+
+## Commits and PRs
+
+- Use the `<gitmoji> <type>: <subject>` style for commit subjects and PR titles, e.g.
+  `📝 docs: restructure the README around the two modes`.
+- Types: `feat`, `fix`, `docs`, `refactor`, `perf`, `dx`, `workflow`, `wip`, `test`, `types`, `ci`,
+  `chore`, `deps`, `release`, `build`. An optional scope is allowed: `🐛 fix(engine): ...`.
+- CI enforces this format on PR titles only (the gitmoji is optional there). Commit messages are not
+  checked, but should follow the same style.
+- Fill in `.github/pull_request_template.md` for PR descriptions; don't delete it.
+- Stage only the files the task touched.
+- Agent-assisted commits end with the agent's `Co-authored-by` trailer, separated from the body by a
+  blank line. Before pushing, confirm it with `git log -1 --format=%B`.

README.md

@@ -8,8 +8,8 @@ Jev Town is a game engine where the characters are driven by AI, not scripts. Ev
 world decides what to do next through two kinds of models working together:
 
 - **Jev**, a System One model, makes the fast, structured decisions: whether to seek someone out,
-  who to go to, where to wander, how long to wait. The engine offers the options; Jev chooses
-  within them, so an illegal move is never possible.
+  who to go to, where to wander, how long to wait. The engine offers the options; Jev chooses within
+  them, so an illegal move is never possible.
 - **An LLM** does the language work: conversations between agents, memory, and what each agent
   believes about the world.
 
@@ -19,8 +19,8 @@ never sees them. It is an MVP and still taking shape.
 
 ## Coming soon
 
-We are building a game on top of this engine: a pixel-art narrative world where every character
-you meet is a Jev-driven agent with a life of its own. Star the repository to follow along.
+We are building a game on top of this engine: a pixel-art narrative world where every character you
+meet is a Jev-driven agent with a life of its own. Star the repository to follow along.
 
 ## Installation