# AGENTS.md

## Scope
This file governs the whole repository unless a deeper `AGENTS.md` overrides it.

## Source of truth
Read these files before making architectural changes:
- `docs/plan/system-plan.md`
- `docs/architecture/system-overview.md`
- `docs/architecture/repository-layout.md`
- `docs/ops/deployment.md`
- `docs/ops/telegram-pairing.md`
- `docs/ops/provider-key-pool.md`

## Repository intent
This repository is a TypeScript monorepo for `nproxy`, a crypto-subscription image gateway that:
- serves a B2C web product;
- routes image-generation requests to external providers;
- maintains a pool of provider API keys with failover, cooldown, and balance tracking;
- exposes admin operations through web admin and a Telegram bot;
- deploys on a single VPS with Docker Compose.

## Top-level boundaries
- `apps/web`: public site, user dashboard, admin UI, and HTTP API surface.
- `apps/worker`: background jobs for generation, billing reconciliation, media cleanup, and key health checks.
- `apps/bot`: Telegram admin bot runtime.
- `apps/cli`: server-side operational CLI, including Telegram pairing commands.
- `packages/config`: typed environment loading and shared config.
- `packages/db`: Prisma schema, migrations, and database access helpers.
- `packages/domain`: business rules, state machines, and use-case orchestration.
- `packages/providers`: external provider adapters for image generation, payments, email, storage, and Telegram.
- `docs`: architecture, product, and operations documents.
- `infra`: deployment templates and reverse-proxy configuration.

## Guardrails
- Keep business rules out of UI components.
- Keep provider-specific HTTP code out of domain services.
- Model user request attempts separately from provider-key attempts.
- Preserve the chosen deployment target: single VPS with Docker Compose.
- Preserve the chosen billing model: manual crypto invoice renewal.
- Preserve the chosen quota display contract: user-facing approximate buckets only.

## Required follow-up when changing key areas
- If you change deployment assumptions, update `docs/ops/deployment.md`.
- If you change Telegram admin auth, update `docs/ops/telegram-pairing.md`.
- If you change failover, cooldown, or balance logic, update `docs/ops/provider-key-pool.md`.

## Workflow
- At the end of each completed task, create a PR for the changes unless the user explicitly says not to.

## Gitea Workflow
- Treat the remote Gitea repository as the source of truth for task tracking when the user refers to `issues`.
- Before starting implementation, open the relevant Gitea issue and read its full problem statement and acceptance criteria instead of guessing from local notes.
- If the user asks to "continue work" or pick the next task, inspect the open Gitea issues and choose the first one that is logically ready to implement.
- After finishing the task, push the branch and create a Gitea PR linked to the issue.
- Every task PR must include an issue reference in the PR body, usually `Closes #<issue-number>` (or `Refs #<issue-number>` when it should not auto-close on merge).
- If the issue-to-PR link is not clearly visible in Gitea, add an explicit comment in the issue with the PR number and URL.
- If Gitea access requires credentials or network escalation, use the configured repository environment and approved escalation flow instead of skipping the issue lookup.