docs: overhaul agent guidance

[t3dotgg]

The existing agent guidance did not capture enough of T3 Code's architecture, product constraints, or the operational hazards of developing the app from inside itself.

This replaces it with focused guidance on terminology, multi-surface changes, remote behavior, isolated dev state, verification, pull requests, architecture, and repository taste. The Markdown uses one physical line per paragraph and list item so editors can handle visual wrapping without noisy reflow diffs.

Validation: deno fmt --check --prose-wrap never AGENTS.md and git diff --check.

Authored with gpt-5.6-sol in the Codex harness.

---

Note

Low Risk
Documentation-only changes to AGENTS.md and README.md; no runtime, API, or security behavior changes.

Overview
Replaces the short AGENTS.md checklist with a full agent contributor guide aimed at coding inside T3 Code: product principles (open, performance, remote, multi-surface), shared glossary, operational hazards (safe process kills, isolated .t3 vs live userdata, no dev origin env vars), a hit every surface checklist, dev/test-data/verification defaults, PR etiquette, and a concise architecture + repo map. The old package-roles-only structure is folded into broader guidance; formatting is one physical line per paragraph/list item to reduce reflow noise.

README.md is updated in parallel to pitch T3 Code as an agent harness control surface, add Grok Build to supported providers and install warnings, expand the install-free npx t3@latest quick start, and soften the contribution stance (small fixes maybe; large features not).

^{Reviewed by Cursor Bugbot for commit 488374f. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Overhaul AGENTS.md and README.md contributor and product documentation

• Rewrites AGENTS.md to replace task-focused guidelines with a full contributor guide covering architecture overview, coding standards, surfaces to verify, PR process, integration testing policy, and security guidance.
• Updates README.md to reframe the project as an agent harness control surface, expand provider support (adding Grok Build), clarify the quick-start flow, and soften the contribution policy to accept small fixes.

^{Macroscope summarized 488374f.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 43a6eac0-7329-484c-9453-f5cab2d42703

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch theo/agent-audit-guidance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Approved

Documentation-only changes to AGENTS.md and README.md with no runtime code impact. Updates agent guidance and project description text.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate 8229b08

Dismissing prior approval to re-evaluate 7e746b2

Dismissing prior approval to re-evaluate e7bdbec