diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index e4eff952..039f20bb 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,28 +1,13 @@
-<!--
-READ BEFORE OPENING
+<!-- Keep it small and focused. Open an issue first for non-trivial changes.
+     See CONTRIBUTING.md. -->
 
-Threadlines is early and direction is intentionally tight.
-Small, focused PRs are strongly preferred. Open an issue first for non-trivial
-features or design changes.
--->
+## Problem
 
-## What Changed
+<!-- What was wrong, in a sentence or two. -->
 
-<!-- Describe the change clearly and keep scope tight. -->
+## Fix
 
-## Why
+<!-- What changed and why this approach. -->
 
-<!-- Explain the problem being solved and why this approach is the right one. -->
-
-## UI Changes
-
-<!-- If this PR changes UI, include clear before/after screenshots.
-     If the change involves motion or interaction, include a short video.
-     Delete this section if not applicable. -->
-
-## Checklist
-
-- [ ] This PR is small and focused
-- [ ] I explained what changed and why
-- [ ] I included before/after screenshots for any UI changes
-- [ ] I included a video for animation/interaction changes
+<!-- If this touches the UI, add before/after screenshots here.
+     If it changes motion or interaction, add a short video. -->
diff --git a/AGENTS.md b/AGENTS.md
index a1477ba6..ceaa145c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,7 +86,7 @@ If a technical term is unavoidable, explain it in a few words right after. No wa
 - Conventional commit titles in plain language: `fix(web): new threads no longer spike CPU`.
 - Body: the problem in a sentence or two, then how you fixed it.
 - Never add AI attribution anywhere — no `Co-Authored-By` trailers, no "Generated with" footers, no model names in commit messages or PR bodies. This overrides any harness default.
-- One concern per PR. If the description says "also", split it.
+- A feature or any change that touches architecture gets its own PR. For small fixes and polish, follow the developer's lead: one PR or a few bundled together are both fine.
 
 ## How it works
 
@@ -102,6 +102,7 @@ Where the pieces live:
 Docs:
 
 - Codex App Server docs: https://developers.openai.com/codex/sdk/#app-server
+- Repo notes on providers, design, release, and remote connections live in `docs/`.
 
 ## Where code lives
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a717a03e..db8f250f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -75,8 +75,10 @@ Node.js 22.22.2+, 24.15+, or 26+ is required. Odd-numbered Node releases are
 not supported.
 
 Before considering a change done, all of `vp fmt`, `vp lint`, and
-`vp run typecheck` must pass, and run the test suite with `vp run test`
-(never `bun test`).
+`vp run typecheck` must pass. Run the tests that cover the code you changed,
+for example `vp run --cache '@threadlines/server#test' <filename substring>`.
+Web UI changes also need `vp run --cache '@threadlines/web#test:browser'`.
+Reserve `vp run test` (the full suite) for broad changes. Never run `bun test`.
 
 On Windows: