docs: expand PR template with ELI5, before/after screenshots, and X handle

Make the pull request template clearer for contributors: plain-language
ELI5, what/why, mandatory before/after UI proof, testing checklist, AI
disclosure, and an Author X field. Align CONTRIBUTING with the template.

.github/CONTRIBUTING.md

@@ -56,17 +56,15 @@ CI enforces this for `src/preload/` and `src/shared/` — see `docs/preload-type
 
 ## Pull Requests
 
-Each pull request should:
+Each pull request should follow [`.github/pull_request_template.md`](./pull_request_template.md). In particular:
 
-- explain the user-visible change
-- stay focused on a single topic when possible
-- include screenshots or screen recordings for new UI or behavior changes
+- open with an ELI5 of the change (plain language paragraph; the PR title is the one-liner)
+- explain what changed and why, and stay focused on a single topic when possible
+- for any UI or interaction change, attach **before and after** screenshots (or short videos); if there is no visual change, say `No visual change` and why
 - include high-quality tests when behavior changes or bug fixes warrant them
 - include a brief code review summary from your AI coding agent that explicitly checks cross-platform compatibility, SSH/remote/local compatibility, supported agent and integration compatibility, performance risk, UI quality when applicable, and basic security risk
 - mention any platform-specific, remote/SSH-specific, agent-specific, integration-specific, or git-provider-specific behavior and testing notes
-- **Include your X (Twitter) handle!** We love giving shoutouts to our contributors when we merge features on [@orca_build](https://x.com/orca_build).
-
-If there is no visual change, say that explicitly in the PR description.
+- **Include your X (Twitter) handle** in the PR template Author section — we shout out contributors when we merge features on [@orca_build](https://x.com/orca_build).
 
 ## Release Process
 

.github/pull_request_template.md

@@ -1,19 +1,59 @@
-## Summary
+## ELI5
 
-Describe the user-visible change.
+<!-- Explain this change like the reader has never seen the codebase. Plain language, no jargon — what broke or was missing, what you did, and what users notice now. A short paragraph is fine; the PR title is the one-liner. -->
 
-## Screenshots
+## What Changed
 
-- Add screenshots or a screen recording for any new or changed UI behavior.
-- If there is no visual change, say `No visual change`.
+<!-- Describe the change clearly and keep scope tight. -->
 
-## Testing
+## Why
 
-- [ ] `pnpm lint`
-- [ ] `pnpm typecheck`
-- [ ] `pnpm test`
-- [ ] `pnpm build`
-- [ ] Added or updated high-quality tests that would catch regressions, or explained why tests were not needed
+<!-- What problem does this solve, and why is this approach right? -->
+
+## Linked Issue
+
+<!-- Link the issue this PR addresses, if any. -->
+
+- Fixes #
+
+## Screenshots (required for UI / behavior changes)
+
+**Before and after are mandatory** for any user-visible or UI change. Do not open a UI PR with only a description.
+
+- Attach a **before** screenshot (or short recording of the old behavior).
+- Attach an **after** screenshot (or short recording of the new behavior).
+- Side-by-side or labeled before/after is preferred.
+- For motion, transitions, or interactions, include a short **before and after** video (or one video that clearly shows both).
+- If there is truly no visual or interaction change, write exactly: `No visual change` and briefly say why.
+
+### Before
+
+<!-- Attach before image/video -->
+
+### After
+
+<!-- Attach after image/video -->
+
+## How to test
+
+<!-- How did you verify this? Steps a reviewer can follow. Which platforms did you actually test (macOS / Linux / Windows / SSH)? -->
+
+- [ ] I manually tested these changes locally
+- [ ] Automated tests added/updated, or explained why not below
+
+## Checklist
+
+- [ ] This PR is small and focused
+- [ ] I explained what changed and why (including ELI5)
+- [ ] Before/after screenshots or videos attached for UI changes, or `No visual change` with reason
+- [ ] Self-reviewed for correctness, security, and performance
+- [ ] Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
+- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test`, and `pnpm build` pass (or CI will cover; local preferred)
+
+## AI assistance
+
+- [ ] This PR was created or substantially assisted by an AI coding agent (optional disclosure)
+- [ ] I reviewed the full diff, understand every change, and can explain it in review
 
 ## AI Review Report
 
@@ -27,3 +67,8 @@ Provide a basic security audit summary from your AI coding agent. Call out any i
 ## Notes
 
 Call out any platform-specific behavior, risks, or follow-up work.
+
+## Author
+
+- X / Twitter: @your_handle
+  <!-- Optional but appreciated — we shout out contributors when we merge features on [@orca_build](https://x.com/orca_build). -->