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.

During CI incident diagnosis, do not change Woodpecker pipeline files, Dockerfiles, build scripts, deploy commands, clone strategy, cache behavior, prune behavior, or the production build procedure unless the user explicitly asks for that exact change.
Diagnose and report the failure first. Classify it as clone/auth, Docker host storage, app build, deploy/compose, notification, or infrastructure before proposing any build-procedure edits.
Last-known-good build references are backend 5d7d2af1b35d4a595eefc2317a345ba5156fa833 and frontend ade735281fdb712c026a45947ea52e17a3f8ecdf.
Do not add Docker prune, cache cleanup, dependency-install rewrites, or host cleanup blocks to production pipelines without explicit approval. Treat host disk cleanup as an operational action by default.
Any CI/build change must have explicit user approval, a narrow stated scope, a verification plan, and the required version bump if it will trigger a build or deploy.

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.

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.

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.

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.