docs: add hierarchical AGENTS knowledge base

[YanzheL]

Summary

• update the AGENTS hierarchy to a deliberate six-file layout: root, backend, frontend, backend/migrations, backend/ent/schema, and deploy
• add deploy/AGENTS.md for Docker Compose, systemd, env-template, and deployment-script guidance that has distinct operational failure modes
• refine the root and backend knowledge bases so they point to the nearest child file, reflect the real backend structure, and avoid subtree-document sprawl

Why this matters

This repo already has strong project-specific conventions, but they were split across READMEs, scripts, config files, and code comments. The AGENTS hierarchy is meant to make that guidance discoverable where an agent or contributor is actually working.

The important change in this update is scope discipline. Rather than proliferating AGENTS files for every large subtree, this branch keeps the hierarchy intentionally small and adds a child file only where the local failure modes are materially different. deploy/ meets that bar because deployment mistakes are operational, environment-specific, and easy to miss from code-oriented parent docs.

What changed

Root

• document the repo purpose, stack, structure, code map, commands, and global anti-patterns
• point deployment work at deploy/AGENTS.md instead of trying to keep deploy-specific rules in the root file
• add clearer lookup anchors for tools/ and docs/

Backend

• keep backend-wide architecture, layering, codegen boundaries, and runtime navigation in backend/AGENTS.md
• update the backend structure to match the actual internal/ layout, including config, domain, integration, middleware, model, pkg, testutil, and util
• correct the middleware path to internal/middleware/
• make the service-layer description honest about its breadth while still keeping it under the backend parent

Backend migrations

• document forward-only migration rules, checksum immutability, filename ordering, and _notx.sql behavior
• keep the custom migration runner as the execution source of truth

Backend Ent schema

• isolate the handwritten Ent authoring surface from generated output
• document the custom mixin workflow and the expectation that schema changes usually ship with matching SQL migrations

Frontend

• keep frontend-wide pnpm/Vite/Vitest/bootstrap/router/API/test guidance in one place
• continue deferring to strong existing local READMEs in src/router/, src/stores/, src/components/common/, src/components/layout/, and src/views/auth/

Deploy

• add a dedicated child file for Docker variant selection, setup mode differences, fixed-secret requirements, PGDATA gotchas, socket-path constraints, and deployment command anchors
• keep deploy guidance operational and subtree-specific rather than repeating repo-wide conventions

Deliberate design choices

• stop at six AGENTS files total to minimize overlap and drift
• do not add AGENTS files under backend/internal/service, backend/internal/repository, backend/internal/handler/admin, or frontend subtrees because current evidence points to shared parent rules and existing local READMEs, not separate instruction contracts
• split on distinct local risk, not on file count alone

Validation

• reviewed the final hierarchy after editing to keep parent/child scope non-redundant
• re-read the changed AGENTS files after generation
• ran git diff --check
• docs-only change; no runtime, test, or build behavior changed