docs: add agent codebase guide

agents.md

@@ -1,5 +1,19 @@
 # Agent Guidelines & Code Standards
 
+## Required orientation and documentation maintenance
+
+Before changing code, read [`docs/README.md`](docs/README.md) and the documents it routes to for the area you are touching. Treat the source code, tests, generated API reference, and migrations as authoritative when a document disagrees with implementation.
+
+Documentation is part of the change, not a follow-up task:
+
+- Update the relevant file in `docs/` whenever behavior, architecture, configuration, data ownership, API contracts, operations, safety boundaries, or development workflow changes.
+- Update `docs/README.md` when adding, renaming, or removing a document.
+- Run `npm run docs:api` after changing `src/web/api-catalog.ts`; verify with `npm run docs:api:check`.
+- Prefer durable explanations and links to owning source files over copied implementation details, line counts, credentials, production IDs, or other facts likely to drift.
+- During final review, explicitly check whether the documentation still describes the code that will be committed.
+
+Do not start, restart, deploy, or otherwise enable live outreach unless the user explicitly authorizes that operational action. A code or documentation request does not imply permission to run the bot. Never expose `.env`, imported account dumps, cookies, Matrix tokens, dashboard tokens, private media, or database contents.
+
 ## Refactoring Goal
 Refactor code to improve maintainability, testability, and clarity. Break down large components into smaller, single-purpose classes/modules.
 
@@ -35,11 +49,13 @@ Refactor code to improve maintainability, testability, and clarity. Break down l
 - **Logging**: Use `winston` for structured logging. Do not use `console.log` in production code.
 
 ## Workflow for Agents
-1. **Analyze**: Before writing code, read the file and understand the context.
-2. **Plan**: Identify what needs to change and check if the change violates SRP.
-3. **Implement**: Make the scoped change. Create new small files when SRP calls for it.
-4. **Test**: Add or update useful tests as appropriate for the change.
-5. **Refactor**: Tidy the implementation and tests while preserving behavior.
-6. **Verify**: Run the relevant tests and type checks (`npm run build` or `tsc --noEmit`) in proportion to the change.
+1. **Orient**: Read `docs/README.md`, the relevant topic documents, and the owning code/tests.
+2. **Analyze**: Before writing code, read the file and understand the context.
+3. **Plan**: Identify what needs to change and check if the change violates SRP.
+4. **Implement**: Make the scoped change. Create new small files when SRP calls for it.
+5. **Test**: Add or update useful tests as appropriate for the change.
+6. **Document**: Update the routed documentation for any changed contract or workflow.
+7. **Refactor**: Tidy the implementation and tests while preserving behavior.
+8. **Verify**: Run the relevant tests, documentation checks, and type checks (`npm run build` or `tsc --noEmit`) in proportion to the change.
 
-You must use the dokploy credentials in .env for access to dokploy
+When Dokploy access is explicitly requested, use the credentials in the ignored `.env` file. Do not print, copy, commit, or blindly source that file.