mdjastrzebski · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026 · Oct 5, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -3,7 +3,7 @@
 `@testing-library/react-native` is a TypeScript/Jest library for testing React Native components with user-focused testing patterns.
 
 > [!IMPORTANT]
-> Never run git commands that create commits, push, or modify the index/history (`git commit`, `git push`, `git add`, `git rm`, `git reset`, `git rebase`, `git merge`, `git stash`, `git tag`, etc.). Only make working-tree changes and read-only git inspections; the human stages and commits. See [Git, releases, and PR workflow](agents/git-workflow.md).
+> Never run git commands that create commits, push, or modify the index/history. The human stages and commits. See [Agent rules](#agent-rules).
 
 - Package manager: `yarn` (`yarn@4.11.0`)
 - Common commands:
@@ -14,11 +14,31 @@
   - `yarn format:check`
   - `yarn build`
   - `yarn validate`
-- Task-specific guidance:
-  - [Architecture and API design](agents/architecture.md)
-  - [Build, validation, and repo layout](agents/build-and-validation.md)
-  - [TypeScript and code style](agents/code-style.md)
-  - [Testing conventions](agents/testing.md)
-  - [Native event propagation (bubbling vs direct)](agents/native-events.md)
-  - [Example app regeneration](agents/example-apps.md)
-  - [Git, releases, and PR workflow](agents/git-workflow.md)
+- Contributor guides (shared with human contributors, see also [CONTRIBUTING.md](CONTRIBUTING.md)):
+  - [Architecture and API design](contributing/architecture.md)
+  - [Build, validation, and repo layout](contributing/build-and-validation.md)
+  - [TypeScript and code style](contributing/code-style.md)
+  - [Testing conventions](contributing/testing.md)
+  - [Native event propagation (bubbling vs direct)](contributing/native-events.md)
+  - [Native state for uncontrolled components](contributing/native-state.md)
+  - [Event dispatch (`fireEvent` vs `userEvent`)](contributing/event-dispatch.md)
+  - [Accessibility model](contributing/accessibility.md)
+  - [Async, `act`, and timers](contributing/async-and-timers.md)
+  - [Example app regeneration](contributing/example-apps.md)
+  - [Git, releases, and PR workflow](contributing/git-workflow.md)
+
+## Agent rules
+
+### Git restrictions
+
+- Never run git commands that create commits, push, or modify the index/history. The human owns these actions.
+- Forbidden commands include (non-exhaustive): `git commit`, `git push`, `git add`, `git rm`, `git mv`, `git restore --staged`, `git reset`, `git rebase`, `git merge`, `git cherry-pick`, `git stash`, `git commit --amend`, and `git tag`.
+- Read-only inspection is fine: `git status`, `git log`, `git diff`, `git show`, `git blame`.
+- When conflicts or staging are involved, resolve file contents in the working tree only, then hand off to the human to stage and commit. Describe the exact commands you would run instead of running them.
+
+### PR draft
+
+- Maintain `PR.txt` at the repository root using the structure from `.github/PULL_REQUEST_TEMPLATE.md`.
+- Keep `PR.txt` aligned with the current branch diff relative to `origin/main`.
+- Include tests actually run and any known validation gaps in `PR.txt`.
+- Do not commit `PR.txt`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,46 +14,25 @@ The core team works directly on GitHub and all work is public.
 
 1. Fork the repo and create your branch from `main` (a guide on [how to fork a repository](https://help.github.com/articles/fork-a-repo/)).
 2. Run `yarn` to setup the development environment.
-3. Do the changes you want and test them out in the example app before sending a pull request.
-
-### Commit message convention
-
-We prefix our commit messages with one of the following to signify the kind of change:
-
-- `fix`: bug fixes, e.g. fix incorrect error message.
-- `feat`: new features, e.g. add useful API.
-- `refactor`: code/structure refactor, e.g. new folder structure.
-- `docs`: changes into documentation, e.g. add usage example for `getByText`.
-- `test`: adding or updating tests, eg unit, snapshot testing.
-- `chore`: tooling changes, e.g. change circle ci config.
-- `BREAKING`: for changes that break existing usage, e.g. change API.
-
-Our pre-commit hooks verify that your commit message matches this format when committing.
-
-### Linting and tests
-
-We use TypeScript for type checking, `eslint` and `oxfmt` for linting and formatting the code, and `jest` for testing. Our pre-commit hooks verify that the linter and tests pass when committing. You can also run the following commands manually:
-
-- `yarn typecheck`: run TypeScript compiler on all files.
-- `yarn lint`: run eslint.
-- `yarn test`: run tests.
-
-### Sending a pull request
-
-When you're sending a pull request:
-
-- Prefer small pull requests focused on one change.
-- Verify that `typecheck`, `eslint` and tests are passing.
-- Preview the documentation to make sure it looks good.
-- Follow the pull request template when opening a pull request.
-
-### Publishing a release
-
-We use [release-it](https://github.com/release-it/release-it) to publish a release. It takes care of versioning, changelog generation, and publishing to NPM.
-
-```sh
-yarn release
-```
+3. Make your changes, add tests, and try them out in the example app.
+4. Run `yarn validate` to type check, test, lint, and check formatting. CI runs the same checks on your pull request.
+5. Open a pull request following the [pull request guidelines](contributing/git-workflow.md#pull-requests).
+
+### Contributor guides
+
+Detailed guides live in [`contributing/`](contributing/). They are written for both human contributors and AI coding agents:
+
+- [Architecture and API design](contributing/architecture.md): project goals, API design principles, and host component detection
+- [Build, validation, and repo layout](contributing/build-and-validation.md): commands, package docs generation, folder structure
+- [TypeScript and code style](contributing/code-style.md): lint and formatting rules
+- [Testing conventions](contributing/testing.md): how the library's own tests are organized
+- [Native event propagation](contributing/native-events.md): which React Native events bubble and which are direct
+- [Native state](contributing/native-state.md): how RNTL simulates state that lives in native views, like `TextInput` text and scroll position
+- [Event dispatch](contributing/event-dispatch.md): how `fireEvent` and `userEvent` find handlers and which events they send
+- [Accessibility model](contributing/accessibility.md): hidden elements, roles, accessible names, and state used by queries and matchers
+- [Async, `act`, and timers](contributing/async-and-timers.md): `act` environment, fake timer detection, `waitFor`, `userEvent` delays, and cleanup
+- [Example app regeneration](contributing/example-apps.md): upgrading the Expo apps in `examples/`
+- [Git, releases, and PR workflow](contributing/git-workflow.md): commit message convention, pull requests, releases
 
 ## Reporting issues
 

diff --git a/agents/architecture.md b/agents/architecture.md
diff --git a/agents/build-and-validation.md b/agents/build-and-validation.md
diff --git a/agents/code-style.md b/agents/code-style.md
diff --git a/agents/example-apps.md b/agents/example-apps.md
diff --git a/agents/git-workflow.md b/agents/git-workflow.md