docs: add AGENTS.md and document issue-driven workflow

- Add AGENTS.md as the cross-agent entry point (lean; points to
  .gooserules and docs/AI_* for detail)
- Document the Forgejo issue-driven workflow (report → triage →
  implement → close) and API patterns in .gooserules
- Add Forgejo step to the pre-change checklist
- Gitignore .forgejo-token

.gitignore

@@ -1,6 +1,7 @@
 .env
 .env.local
 .env.*.local
+.forgejo-token
 node_modules/
 dist/
 target/

.gooserules

@@ -76,12 +76,51 @@ cd web/normogen-web && npm test
 - Auth: JWT with middleware on protected routes
 - Testing: cargo test, npm test, integration scripts
 
+## Issue-Driven Workflow
+
+The Forgejo issue tracker at `https://gitea.soliverez.com.ar/alvaro/normogen`
+is the source of truth for bugs and features. The API token lives in
+`.forgejo-token` (gitignored; never commit or echo its value).
+
+### Lifecycle
+1. **Reporting** — the user files issues as they encounter bugs or conceive
+   features, either directly in Forgejo or by describing them in chat (then the
+   agent creates the issue). Aim for one concern per issue.
+2. **Triage** — when picking up work, the agent lists open issues
+   (`GET /api/v1/repos/alvaro/normogen/issues`), reads them, asks clarifying
+   questions as needed, and proposes a plan in the issue (or chat for small
+   items) before writing code.
+3. **Implementation** — work in chunks tied to issues. Reference the issue
+   number in branch names (`fix/123-...`, `feat/456-...`) and commit messages
+   (`fix(medication): ... (#123)`). Push progress as comments on the issue for
+   anything non-trivial or spanning multiple sessions.
+4. **Closure** — close the issue with a comment summarizing what was done and
+   pointing at the relevant commits/PR. Don't close until the change is
+   verified (tests pass) and merged/pushed.
+
+### API usage patterns
+- Auth header: `Authorization: token $(cat .forgejo-token)`
+- Create issue: `POST /api/v1/repos/alvaro/normogen/issues` with JSON
+  `{title, body, labels}` (labels must exist first; create via
+  `POST /api/v1/repos/alvaro/normogen/labels`).
+- Add a comment: `POST /api/v1/repos/alvaro/normogen/issues/{index}/comments`
+- Close an issue: `PATCH /api/v1/repos/alvaro/normogen/issues/{index}` with
+  `{"state": "closed"}` (ideally after a summary comment).
+
+### Conventions
+- Use conventional-commit prefixes in titles where natural
+  (`fix:`, `feat:`), but keep titles human-readable.
+- Add the `bug` / `feature` / `enhancement` label when creating issues if those
+  labels exist; otherwise leave unlabelled rather than failing.
+- Never paste the token into commit messages, issue bodies, comments, or chat.
+
 ## Before Making Changes
 
 1. Read [AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md)
 2. Check [product/STATUS.md](docs/product/STATUS.md) for current progress
-3. Review existing code patterns
-4. Plan your approach
+3. **Check open Forgejo issues** for the current task and its discussion
+4. Review existing code patterns
+5. Plan your approach
 
 ## Common Workflows
 

AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md
+
+Entry point for any AI agent working on this repository. Read this first,
+then follow the pointers below for detail.
+
+## Project
+
+Normogen — open-source health data platform. Monorepo:
+
+- `backend/` — Rust (Axum + MongoDB)
+- `web/normogen-web/` — React + TypeScript (Material-UI, Zustand)
+- `docs/` — architecture, product status, testing scripts
+- `shared/` — types/contracts shared across packages
+
+Stack detail, architecture, and code patterns: see
+[docs/AI_AGENT_GUIDE.md](docs/AI_AGENT_GUIDE.md) and
+[docs/AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md).
+
+## Working directory
+
+Absolute paths are preferred. Project root: `/home/asoliver/desarrollo/normogen`.
+
+## Issue-driven workflow (source of truth for tasks)
+
+Bugs and features are tracked in **Forgejo** at
+`https://gitea.soliverez.com.ar/alvaro/normogen`. This is the canonical
+backlog — do not invent tasks independently; pick up work from open issues or
+discuss before creating new ones.
+
+- Report → triage → implement → close, in chunks tied to one issue each.
+- Reference the issue number in branch names (`fix/123-…`, `feat/456-…`) and
+  commit messages (`fix(medication): … (#123)`).
+- The Forgejo API token lives in `.forgejo-token` (gitignored). Read it with
+  `cat .forgejo-token`; pass it as `Authorization: token $(cat .forgejo-token)`.
+  **Never** echo the token value, commit it, or paste it into issue/commit text.
+- Full lifecycle and API call patterns are documented in the
+  "Issue-Driven Workflow" section of [`.gooserules`](.gooserules).
+
+## Before making changes
+
+1. Read [docs/AI_QUICK_REFERENCE.md](docs/AI_QUICK_REFERENCE.md).
+2. Check [docs/product/STATUS.md](docs/product/STATUS.md) for current progress.
+3. Check open Forgejo issues for the task at hand and its prior discussion.
+4. Review existing code patterns before introducing new ones.
+5. Plan the approach and confirm before implementing non-trivial changes.
+
+## Essential commands
+
+```bash
+# Backend
+cd backend && cargo build
+cd backend && cargo test
+cd backend && cargo clippy
+cd backend && docker compose up -d
+
+# Frontend
+cd web/normogen-web && npm install
+cd web/normogen-web && npm start
+cd web/normogen-web && npm test
+
+# Integration tests
+./docs/testing/quick-test.sh
+./docs/testing/test-api-endpoints.sh
+```
+
+## Commit guidelines
+
+Conventional Commits: `feat(scope): …`, `fix(scope): …`, `docs: …`, etc.
+Reference the issue number when the commit closes or advances one:
+`fix(medication): resolve adherence bug (#123)`.
+
+## Where things live
+
+| Concern | Location |
+|---|---|
+| Backend handlers | `backend/src/handlers/` |
+| Backend models | `backend/src/models/` |
+| Routes | `backend/src/main.rs` |
+| Frontend pages | `web/normogen-web/src/pages/` |
+| Frontend API services | `web/normogen-web/src/services/` |
+| Shared types | `shared/`, `web/normogen-web/src/types/api.ts` |