docs: update AGENTS.md and dev docs (#39976)

Agents rarely read the `docs` guides when AGENTS.md only asks for
relevant ones. AGENTS.md now names the guide for each area, and rules
agents kept missing go into those guides.

- AGENTS.md maps Go, TS, CSS, Vue, templates, tests, config options,
migrations and refactors to their guide
- The backend guide lists XORM pitfalls behind recent bugs
(https://gitea.com/xorm/xorm/issues/2615): zero-valued struct
conditions, `Cols` and `updated` columns on updates, soft-delete values,
index drops by `SyncAllTables`, MSSQL limits and pagination order
- The development guide requires a `WIP:` companion docs PR copying the
ini text verbatim for `app.example.ini` changes, and says to avoid
migrations unless the alternative is a workaround

AGENTS.md

@@ -1,6 +1,6 @@
 - Never assume, verify before claiming
 - List development targets with `make help`
-- Read relevant developer documentation in the `docs` folder
+- Before working on code, read the `docs` guides for every area touched: `guidelines-backend.md` for Go, `guidelines-frontend.md` for TS, CSS and Vue, both for templates, `testing.md` for tests, `development.md` for config options and migrations, `guidelines-refactoring.md` for refactors
 - PR descriptions: minimal, only what and why, no task or file listings. Include screenshots for UI changes, before and after when modifying existing UI. Aim for less than 1000 characters
 - 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

docs/development.md

@@ -105,10 +105,13 @@ When adding configuration options it is not enough to add them to the
 [`custom/conf/app.example.ini`](../custom/conf/app.example.ini), and document them in
 the [configuration cheat sheet](https://docs.gitea.com/administration/config-cheat-sheet),
 which lives in the [documentation repository](https://gitea.com/gitea/docs).
+Every `app.example.ini` change needs a companion PR there that copies the ini text
+verbatim into every affected version's cheat sheet, translated where feasible, with a
+`WIP:` title prefix until the Gitea PR merges.
 
 ## Database migrations
 
-If you make breaking changes to a database-persisted struct under `models/`, add a
+Avoid migrations unless the alternative is a workaround. If you make breaking changes to a database-persisted struct under `models/`, add a
 new migration in `modelmigration/`. See [testing.md](testing.md#migration-tests)
 for running the migration tests.
 

docs/guidelines-backend.md

@@ -74,6 +74,19 @@ conditional `UPDATE` or a lock.
   plain `Sync`.
 - When inserting rows with preset IDs, MSSQL requires `SET IDENTITY_INSERT` to be
   enabled and PostgreSQL requires the sequence to be updated afterwards.
+- Struct conditions skip zero-valued fields, so `Get(&Reaction{IssueID: 1})` also
+  matches comment reactions. Use `Where` or `builder` when a zero value matters.
+- Struct updates skip zero-valued fields unless selected by `Cols` or `AllCols()`.
+  `Cols` silently ignores unknown names. `updated` columns are always written unless
+  `NoAutoTime()` is used.
+- `xorm:"deleted"` columns count both `0` and `NULL` as not deleted, so hand-written
+  conditions must accept both.
+- On every start, `SyncAllTables` drops indexes absent from the model, so declare
+  migration-created indexes there, including in backports. It only warns about
+  nullability and default changes, so apply them through migrations.
+- `ForUpdate` only works on MySQL and PostgreSQL. MSSQL rejects TEXT columns in
+  struct conditions and inserts of more than 1000 rows.
+- Paginated queries need a unique tiebreaker like `id` for a stable order.
 
 ## Dependencies