# AGENTS.md

Agents instructions for the linearvoid project.

## General Guidelines

- Use the architecture documentation (arc42 template and ADRs in `docs`) as the source of truth for design decisions.
- Follow the project folder structure in the root README.
- Update documentation first before implementing changes to ensure traceability of decisions.

## Task Management

- Plan any task in the `.github/instructions/TODO.md` file with clear steps and mark them as completed when done. Move completed sections to `.github/instructions/DONE.md`. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
- Before taking any action except for planning and writing `TODO.md`, always ask user for confirmation, accept `go`, `ok`, `yes`, `next`, or `continue` to proceed. If the user says `no`, `stop`, or `cancel`, abort the action and return to planning.

### Required tracking files — update at every development step

These files must be kept current with every change. Do not let them drift.

| File                              | Purpose                                       | When to update                                                     |
| --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
| `.github/instructions/TODO.md`    | Active implementation plan with checkboxes    | Mark items done as they complete; add new items when scope expands |
| `.github/instructions/BACKLOG.md` | Deferred, manual, and operational tasks       | Sync whenever TODO items complete or new gaps are identified       |
| `.github/instructions/DONE.md`    | Archive of completed TODO sections            | Move completed sections here from TODO.md                          |
| `.github/MEMORY.md`               | Session memory — what was done, when, and why | Append dated entry after each meaningful batch of changes          |
| `docs/DEVELOPMENT.md`             | Remaining task checklist organized by topic   | Sync checkboxes with TODO.md after each implementation session     |
| `CHANGELOG.md`                    | User-facing release notes                     | Add entry when a phase or significant feature completes            |
| `docs/STREAMING.md`               | Streaming pipeline contract                   | Update when playout, HLS, or caching behavior changes              |
| `docs/DEPLOYMENT.md`              | Deploy and infrastructure procedures          | Update when pipeline, topology, or provisioning changes            |
| `docs/SETUP.md`                   | Environment and onboarding guide              | Update when prerequisites, `.env`, or setup steps change           |
| `docs/MONITORING.md`              | Observability reference                       | Update when metrics, alerts, or dashboards change                  |
| `docs/API.md`                     | API contract                                  | Update when endpoints, status codes, or rate limits change         |
| `docs/SECURITY.md`                | Security posture                              | Update when auth, TLS, or rate limiting changes                    |
| `docs/operations/*.md`            | Runbooks, checklists, how-to guides           | Keep aligned with actual procedures and dashboard URLs             |

## Security & Secrets Protection

- **Never commit raw secrets or credentials** to the repository.
- **Never print or log raw secrets** in terminal commands or output files.
- **Use Gitea Actions Secrets** for all production credentials and environment variables.
- **Avoid hardcoding sensitive values** in workflow files (`.yml`). Instead, reference them using `${{ secrets.SECRET_NAME }}`.
- **Do not use the `GITEA_` prefix** for custom secrets or environment variables in Gitea, as it is reserved internally and will be silently ignored or returned as empty. Use the `CI_` prefix instead (e.g., `CI_REGISTRY_USER`, `CI_REGISTRY_TOKEN`).
- **Keep `.env` gitignored** and use `.env.example` as the template for local development.
- **For CD deployments**, generate the `.env` file dynamically on the runner using a secure step that populates values from Gitea Actions Secrets.