diff --git a/AGENTS.md b/AGENTS.md
index 43a8c02676..bae92d7216 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,20 +1,18 @@
 - Never assume, verify before claiming
-- Use `make help` to list the available development targets
-- Keep PR descriptions minimal, no task lists
-- Use Conventional Commits for commit messages and PR titles, plus Gitea's own `enhance` type for user-facing enhancements
+- List development targets with `make help`
+- PR descriptions: minimal, only what and why, no task lists or file listings. Include screenshots for UI changes, before and after when modifying existing UI
+- Reference issues and PRs by full URL, not by number
+- Use Conventional Commits for commit messages and PR titles, plus Gitea's `enhance` type for user-facing enhancements
 - Add an `Assisted-by: AGENT_NAME:MODEL_VERSION` trailer to commit messages, never `Co-Authored-By` or `Signed-off-by`
-- Never rewrite git history unless asked. Use new commits and normal push for PR updates
-- Include authorship attribution when writing issue and PR comments
-- Comments: Write almost no new ones, keep them short, preferably same-line,  explain why for a future reader. Never narrate code, the current change or prompt. Preserve existing comments when they still apply.
+- Attribute agent authorship on one trailing line in issue and PR comments, never as a PR description section
+- Never rewrite git history unless asked, update PRs with new commits and normal push
+- Comments: write almost none, short and preferably same-line, explaining why for a future reader. Never narrate code, the change or the prompt. Preserve existing ones that still apply
 - Add the current year to copyright headers of new `.go` files
-- Leave no trailing whitespace in any edited file
+- In `options/locale`, only edit `locale_en-US.json`, other locales are synced automatically
 - In TS, use `!` instead of `?.`/`??` when a value always exists
-- Prefer `tw-*` utilities over inline `style`, and `flex-*` helpers over per-child `tw-ml-*` / `tw-mr-*` margins, falling back to `tw-*` when specificity requires `!important`
-- Run `make fmt` after `.go` edits, `make tidy` after `go.mod` edits
-- Lint what changed with `make lint-go`, `lint-js`, `lint-css` or `lint-templates`
-- Run single Go tests with `go test -run '^TestName$' ./modulepath/`
-- Run single TS test files with `pnpm exec vitest <path-filter>`
-- Run single Playwright e2e test files with `GITEA_TEST_E2E_FLAGS='<filepath>' make test-e2e`
-- Write the fewest, fastest tests covering the behavior. Prefer extending an existing test before adding a new one. Avoid `sleep` and similar mechanisms
-- Prefer unit tests when logic is testable in isolation, aim for sub-2s local runtime per integration test and sub-4s per e2e test
-- Prefer semantic locators in e2e tests
+- Prefer `tw-*` utilities over inline `style` and `flex-*` helpers over per-child `tw-ml-*`/`tw-mr-*` margins, falling back to `tw-*` where specificity requires `!important`
+- Run `make fmt` after `.go` edits, `make tidy` after `go.mod` edits, `make generate-swagger` after API changes, and lint what changed with `make lint-go`, `lint-js`, `lint-css` or `lint-templates`
+- Fix the cause rather than disabling a linter or weakening a test. Where unavoidable, use the narrowest scope with a trailing comment giving the reason
+- Run single tests with `go test -run '^TestName$' ./modulepath/` for Go, `pnpm exec vitest <path-filter>` for TS and `GITEA_TEST_E2E_FLAGS='<filepath>' make test-e2e` for e2e
+- Write the fewest, fastest tests covering the behavior, extending an existing one where possible. Prefer unit tests where logic is testable in isolation
+- Aim for sub-2s per integration test and sub-4s per e2e test. Wait on a deterministic condition rather than `sleep`, and prefer semantic locators in e2e tests