# RTK

Repository rules agents must follow for Amanat escrow work.

## Version and Build Numbers

- **Every build of `frontend/` or `backend/` must bump the patch component (`Z` in `X.Y.Z`) by one.** Container images on `git.manko.yoga` are tagged from `package.json` version — a build with an unchanged version overwrites the previous image and erases history. Patch bump on every build, no exceptions.
  - Bump together so frontend and backend stay aligned (e.g. both go `2.6.18 → 2.6.19`).
  - Bumping `Y` (minor) or `X` (major) is only for explicit milestone releases the user requests; never as a side-effect of an ordinary build.
- For any product or code change that affects `frontend/` or `backend/`, bump both versions together before final response in:
  - `frontend/package.json`
  - `frontend/package-lock.json`
  - tracked frontend env files that set `NEXT_PUBLIC_APP_VERSION`
  - `backend/package.json`
  - `backend/package-lock.json`
- Backend runtime/version reporting should read from `backend/package.json`, not a hardcoded fallback.
- Keep frontend and backend on the same version/build number unless the user explicitly asks otherwise.
- Do not bump versions for docs-only changes unless the user asks for a release/build number.
- Mention the resulting frontend and backend version numbers in the final response.

## Pre-Deploy CLI Verification

- For any backend or frontend change, run the focused CLI smoke test for the touched area **before pushing a commit that would trigger a build**. The image tracker patch-bumps per build, so a failed build still consumes a version slot.
- Smoke-test scripts live under `backend/scripts/smoke/*.sh` (and the equivalent frontend dir). `scripts/test-*` is in `.gitignore`, so put committed smoke tests in `scripts/smoke/`. They must accept `BASE_URL` so the same script can target a local backend, dev, or production.
- Confirm the script passes against a local backend (or, where local isn't feasible, an explicitly named target) before pushing. After the deploy completes, re-run the same script against the deployed URL to confirm production behavior matches.
- If no smoke-test script exists for the touched area, create one as part of the change.

## CI Notification Safety

- Telegram CI notifications (`appleboy/drone-telegram` in `.woodpecker/*.yml`) must HTML-escape commit messages and strip git trailers (`Co-Authored-By:`, `Signed-off-by:`, `Reviewed-by:`, `Reported-by:`) before sending. Unescaped `<email@addr>` trailers cause "Bad Request: can't parse entities" 400 errors from the Telegram API.
- Use a `compose-notify` shell step that writes the rendered message into `.tgmsg`, then have the telegram plugin send `message_file: .tgmsg`. Do not interpolate `{{commit.message}}` directly into an `html`-formatted message body.
- Woodpecker eats `${VAR}` in command strings — always use `$VAR` (or `$$VAR` to escape) in pipeline command shells.

## Telegram Authentication

- `POST /api/auth/telegram` must allow Telegram Mini App retries with the same signed `initData`; Telegram may reuse launch data across reloads, retries, and duplicate client calls.
- Do not add one-time replay rejection to first-class Telegram login. Use signature verification, `auth_date` freshness, bot rejection, blocked-link checks, and rate limiting for this login path.
- Keep replay/deduplication checks scoped to routes where the payload is actually a one-time operation, such as webhook update handling or explicit Mini App session creation.
- Preserve or add regression tests whenever Telegram auth behavior changes.

## Verification

- Run focused tests for the changed area and a typecheck/build when practical.
- If Redis, email, or other optional infrastructure is unavailable during tests, successful auth paths should fail open only where the production code already treats that dependency as non-critical, and the final response should mention any noisy but non-failing warnings.
- Before final response, report the important verification commands and whether they passed.