docs: update root AGENTS guidance

AGENTS.md

@@ -1,17 +1,14 @@
 # Development Rules
 
-## First Message
+## Conversational Style
-If the user did not give you a concrete task in their first message,
+
-read README.md, then ask which module(s) to work on. Based on the answer, read the relevant README.md files in parallel.
+- Keep answers short and concise
-- packages/ai/README.md
+- No emojis in commits, issues, PR comments, or code
-- packages/tui/README.md
+- No fluff or cheerful filler text
-- packages/agent/README.md
+- Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!")
-- packages/coding-agent/README.md
-- packages/mom/README.md
-- packages/pods/README.md
-- packages/web-ui/README.md
 
 ## Code Quality
+
 - No `any` types unless absolutely necessary
 - Check node_modules for external API type definitions instead of guessing
 - **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports.
@@ -21,6 +18,7 @@ read README.md, then ask which module(s) to work on. Based on the answer, read t
 - Never hardcode key checks with, eg. `matchesKey(keyData, "ctrl+x")`. All keybindings must be configurable. Add default to matching object (`DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS`)
 
 ## Commands
+
 - After code changes (not documentation changes): `npm run check` (get full output, no tail). Fix all errors, warnings, and infos before committing.
 - Note: `npm run check` does not run tests.
 - NEVER run: `npm run dev`, `npm run build`, `npm test`
@@ -32,15 +30,8 @@ read README.md, then ask which module(s) to work on. Based on the answer, read t
 - Put issue-specific regressions under `packages/coding-agent/test/suite/regressions/` and name them `<issue-number>-<short-slug>.test.ts`.
 - NEVER commit unless user asks
 
-## GitHub Issues
-When reading issues:
-- Always read all comments on the issue
-- Use this command to get everything in one call:
-  ```bash
-  gh issue view <number> --json title,body,comments,labels,state
-  ```
-
 ## Contribution Gate
+
 - New issues from new contributors are auto-closed by `.github/workflows/issue-gate.yml`
 - New PRs from new contributors without PR rights are auto-closed by `.github/workflows/pr-gate.yml`
 - Maintainer approval comments are handled by `.github/workflows/approve-contributor.yml`
@@ -50,11 +41,13 @@ When reading issues:
 - `lgtm` approves future issues and rights to submit PRs
 
 When creating issues:
+
 - Add `pkg:*` labels to indicate which package(s) the issue affects
   - Available labels: `pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:mom`, `pkg:pods`, `pkg:tui`, `pkg:web-ui`
 - If an issue spans multiple packages, add all relevant labels
 
 When posting issue/PR comments:
+
 - Write the full comment to a temp file and use `gh issue comment --body-file` or `gh pr comment --body-file`
 - Never pass multi-line markdown directly via `--body` in shell commands
 - Preview the exact comment text before posting
@@ -63,18 +56,16 @@ When posting issue/PR comments:
 - Keep comments concise, technical, and in the user's tone
 
 When closing issues via commit:
+
 - Include `fixes #<number>` or `closes #<number>` in the commit message
 - This automatically closes the issue when the commit is merged
 
 ## PR Workflow
+
 - Analyze PRs without pulling locally first
 - If the user approves: create a feature branch, pull PR, rebase on main, apply adjustments, commit, merge into main, push, close PR, and leave a comment in the user's tone
 - You never open PRs yourself. We work in feature branches until everything is according to the user's requirements, then merge into main, and push.
 
-## Tools
-- GitHub CLI for issues/PRs
-- Add package labels to issues/PRs: pkg:agent, pkg:ai, pkg:coding-agent, pkg:mom, pkg:pods, pkg:tui, pkg:web-ui
-
 ## Testing pi Interactive Mode with tmux
 
 To test pi's TUI in a controlled terminal environment:
@@ -100,17 +91,14 @@ tmux send-keys -t pi-test C-o  # ctrl+o
 tmux kill-session -t pi-test
 ```
 
-## Style
-- Keep answers short and concise
-- No emojis in commits, issues, PR comments, or code
-- No fluff or cheerful filler text
-- Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!")
-
 ## Changelog
+
 Location: `packages/*/CHANGELOG.md` (each package has its own)
 
 ### Format
+
 Use these sections under `## [Unreleased]`:
+
 - `### Breaking Changes` - API changes requiring migration
 - `### Added` - New features
 - `### Changed` - Changes to existing functionality
@@ -118,6 +106,7 @@ Use these sections under `## [Unreleased]`:
 - `### Removed` - Removed features
 
 ### Rules
+
 - Before adding entries, read the full `[Unreleased]` section to see which subsections already exist
 - New entries ALWAYS go under `## [Unreleased]` section
 - Append to existing subsections (e.g., `### Fixed`), do not create duplicates
@@ -125,6 +114,7 @@ Use these sections under `## [Unreleased]`:
 - Each version section is immutable once released
 
 ### Attribution
+
 - **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/badlogic/pi-mono/issues/123))`
 - **External contributions**: `Added feature X ([#456](https://github.com/badlogic/pi-mono/pull/456) by [@username](https://github.com/username))`
 
@@ -133,13 +123,16 @@ Use these sections under `## [Unreleased]`:
 Adding a new provider requires changes across multiple files:
 
 ### 1. Core Types (`packages/ai/src/types.ts`)
+
 - Add API identifier to `Api` type union (e.g., `"bedrock-converse-stream"`)
 - Create options interface extending `StreamOptions`
 - Add mapping to `ApiOptionsMap`
 - Add provider name to `KnownProvider` type union
 
 ### 2. Provider Implementation (`packages/ai/src/providers/`)
+
 Create provider file exporting:
+
 - `stream<Provider>()` function returning `AssistantMessageEventStream`
 - `streamSimple<Provider>()` for `SimpleStreamOptions` mapping
 - Provider-specific options interface
@@ -147,16 +140,19 @@ Create provider file exporting:
 - Response parsing emitting standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`)
 
 ### 3. Provider Exports and Lazy Registration
+
 - Add a package subpath export in `packages/ai/package.json` pointing at `./dist/providers/<provider>.js`
 - Add `export type` re-exports in `packages/ai/src/index.ts` for provider option types that should remain available from the root entry
 - Register the provider in `packages/ai/src/providers/register-builtins.ts` via lazy loader wrappers, do not statically import provider implementation modules there
 - Add credential detection in `packages/ai/src/env-api-keys.ts`
 
 ### 4. Model Generation (`packages/ai/scripts/generate-models.ts`)
+
 - Add logic to fetch/parse models from provider source
 - Map to standardized `Model` interface
 
 ### 5. Tests (`packages/ai/test/`)
+
 Add provider to: `stream.test.ts`, `tokens.test.ts`, `abort.test.ts`, `empty.test.ts`, `context-overflow.test.ts`, `image-limits.test.ts`, `unicode-surrogate.test.ts`, `tool-call-without-result.test.ts`, `image-tool-result.test.ts`, `total-tokens.test.ts`, `cross-provider-handoff.test.ts`.
 
 For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If the provider exposes multiple model families (for example GPT and Claude), add at least one pair per family.
@@ -164,11 +160,13 @@ For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If t
 For non-standard auth, create utility (e.g., `bedrock-utils.ts`) with credential detection.
 
 ### 6. Coding Agent (`packages/coding-agent/`)
+
 - `src/core/model-resolver.ts`: Add default model ID to `DEFAULT_MODELS`
 - `src/cli/args.ts`: Add env var documentation
 - `README.md`: Add provider setup instructions
 
 ### 7. Documentation
+
 - `packages/ai/README.md`: Add to providers table, document options/auth, add env vars
 - `packages/ai/CHANGELOG.md`: Add entry under `## [Unreleased]`
 
@@ -177,6 +175,7 @@ For non-standard auth, create utility (e.g., `bedrock-utils.ts`) with credential
 **Lockstep versioning**: All packages always share the same version number. Every release updates all packages together.
 
 **Version semantics** (no major releases):
+
 - `patch`: Bug fixes and new features
 - `minor`: API breaking changes
 
@@ -192,15 +191,12 @@ For non-standard auth, create utility (e.g., `bedrock-utils.ts`) with credential
 
 The script handles: version bump, CHANGELOG finalization, commit, tag, publish, and adding new `[Unreleased]` sections.
 
-## **CRITICAL** Tool Usage Rules **CRITICAL**
-- NEVER use sed/cat to read a file or a range of a file. Always use the read tool (use offset + limit for ranged reads).
-- You MUST read every file you modify in full before editing.
-
 ## **CRITICAL** Git Rules for Parallel Agents **CRITICAL**
 
 Multiple agents may work on different files in the same worktree simultaneously. You MUST follow these rules:
 
 ### Committing
+
 - **ONLY commit files YOU changed in THIS session**
 - ALWAYS include `fixes #<number>` or `closes #<number>` in the commit message when there is a related issue or PR
 - NEVER use `git add -A` or `git add .` - these sweep up changes from other agents
@@ -209,7 +205,9 @@ Multiple agents may work on different files in the same worktree simultaneously.
 - Track which files you created/modified/deleted during the session
 
 ### Forbidden Git Operations
+
 These commands can destroy other agents' work:
+
 - `git reset --hard` - destroys uncommitted changes
 - `git checkout .` - destroys uncommitted changes
 - `git clean -fd` - deletes untracked files
@@ -218,6 +216,7 @@ These commands can destroy other agents' work:
 - `git commit --no-verify` - bypasses required checks and is never allowed
 
 ### Safe Workflow
+
 ```bash
 # 1. Check status first
 git status
@@ -234,9 +233,11 @@ git pull --rebase && git push
 ```
 
 ### If Rebase Conflicts Occur
+
 - Resolve conflicts in YOUR files only
 - If conflict is in a file you didn't modify, abort and ask the user
 - NEVER force push
 
 ### User override
+
 If the user instructions conflict with rules set out here, ask for confirmation that they want to override the rules. Only then execute their instructions.