Improve Copilot code reviews with repository-specific guidance

.github/copilot-instructions.md

@@ -0,0 +1,19 @@
+# Vortex code review instructions
+
+## Review scope and priorities
+
+- Review the complete base-to-head change and the combined behavior across files, not only the latest push or each file in isolation.
+- Trace changed behavior end to end: untrusted input, business rules, persisted state, external side effects, and the returned or rendered result. Inspect directly affected callers, callees, and alternate branches before concluding the path is safe.
+- Prioritize exploitable security issues, loss or misrouting of funds, authorization failures, data corruption, broken public contracts, concurrency bugs, and user-visible regressions.
+- Review changed tests as production-quality evidence. Verify that assertions exercise the intended failure, boundary, retry, and fallback behavior and would fail if the implementation regressed.
+- Only report a problem caused or exposed by the change. Do not request unrelated cleanup, speculative flexibility, one-use abstractions, or formatter/linter changes that Biome, ESLint, TypeScript, or CI already enforce.
+- Every finding must describe a concrete failure scenario and impact, then propose the smallest practical fix. Do not leave vague “consider handling” comments.
+
+## Repository invariants
+
+- Treat `docs/security-spec/` as normative for security-sensitive behavior. Flag code/spec contradictions and behavior changes that leave the relevant specification stale.
+- Treat public OpenAPI schemas, `packages/sdk` exports, and shared wire types as compatibility contracts. Check consumers and documentation when their shapes, semantics, defaults, or errors change.
+- Changes to `packages/shared` can affect every application. Check downstream assumptions, and require the shared build before consumer verification.
+- `FiatToken` has exactly `EURC`, `ARS`, `BRL`, `USD`, `MXN`, and `COP`; mappings and behavior branches must be exhaustive unless a documented capability deliberately excludes a token.
+- New features need meaningful tests. Bug fixes need a regression test that fails without the fix unless the behavior cannot reasonably be automated.
+- Do not review generated output as handwritten code (`routeTree.gen.ts`, OpenAPI declarations, contract artifacts, or build output); only flag it when the source change should have regenerated it and did not.

.github/instructions/api.instructions.md

@@ -0,0 +1,17 @@
+---
+applyTo: "apps/api/**/*.ts,apps/api/**/*.sql"
+---
+
+# API and payment-engine review instructions
+
+- Validate request bodies, query values, headers, webhook payloads, database JSON, and provider responses at runtime before property access or string/array methods. A TypeScript annotation does not validate external data.
+- Derive authentication and authorization from trusted middleware state. Check profile, customer-entity, credential, partner, and resource ownership independently; never authorize from a client-supplied identifier alone.
+- Treat read-then-write limits, uniqueness checks, allocation, revocation, and state transitions as concurrency-sensitive. Require a database constraint, transaction/lock, compare-and-set, or other atomic guarantee when parallel requests can violate the invariant.
+- Keep monetary values as decimal strings, `Big`, or integer raw units. Never use binary `number` arithmetic for amounts, fees, limits, rates, or percentages that influence behavior. Apply token precision and rounding once at an explicit boundary.
+- For ramp phases, workers, and webhooks, verify idempotency across retries, crashes, duplicate delivery, and concurrent execution. Persist or reconcile external operation identifiers and transaction receipts before repeating a side effect.
+- Check BUY and SELL, direct/same-chain and cross-chain routes, all supported currencies and destination networks, legacy in-flight records, and failure/recovery paths affected by a routing or flow-version change.
+- For provider integrations, verify timeouts, retry classification, fallback order, provider-status normalization, sanitized logging, and partial or malformed responses. An outage must not silently become success or switch to an invalid corridor.
+- Remember that pending Sequelize migrations run automatically at API startup. Review backward compatibility with old application instances and staged rollout order; irreversible drops require an independently enforceable gate or a later deployment.
+- Review dates and reporting boundaries with explicit timezone and inclusive/exclusive semantics. Use the event timestamp named by the business rule, not a nearby creation/update timestamp.
+- Production reconciliation and migration scripts need the same scrutiny as services: safe parsing, dry-run or fail-closed behavior, bounded retries, secret/PII handling, atomic output, and focused tests for destructive decisions.
+- Cross-check changed API behavior against the relevant OpenAPI source, partner guide, integration skill, and security specification. Generated declarations alone are not the source of truth.

.github/instructions/react.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "apps/frontend/**/*.ts,apps/frontend/**/*.tsx,apps/dashboard/**/*.ts,apps/dashboard/**/*.tsx"
+---
+
+# React application review instructions
+
+- Preserve monetary values at their configured token precision in form state, query parameters, and API payloads. Apply display precision only while rendering; formatting must never truncate or mutate the value submitted or quoted.
+- Treat authentication refresh, sign-out, OTP completion, navigation, and query completion as race-prone. A stale promise or response must not overwrite a newer session, clear replacement credentials, or update an unmounted/superseded flow.
+- Use `useEffect` only to synchronize with an external system. Flag effects that merely derive state, mirror props/query data, orchestrate an event that belongs in its handler, or omit cleanup for subscriptions and async work.
+- Keep server state in TanStack Query, local UI state close to the component, shared client state in the established Zustand/context boundary, and multi-step workflows in XState. Flag duplicate sources of truth and manual synchronization between them.
+- For XState changes, use XState v5 `setup(...).createMachine(...)` and verify every event, guard, actor result, error, cancellation, retry, and persisted/resumed state affected by the change. Shared KYC/KYB workflow belongs in `packages/kyc`, not a fork in an app.
+- Validate API and browser-storage data at the boundary. Loading/error/empty states must not expose stale data from a previous user, entity, route, or query key.
+- Check TanStack Query keys, invalidation, optimistic updates, cancellation, and rollback together; a mutation must not refresh or corrupt the cache for another profile, entity, corridor, or filter.
+- Require tests for the meaningful interaction and failure modes introduced by the change, including async races where relevant. Assertions should verify submitted wire values and resulting state, not only formatted text or the happy-path screen.

.github/instructions/solidity.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "contracts/**/*.sol"
+---
+
+# Solidity review instructions
+
+- Compare relayer changes with `docs/security-spec/04-smart-contracts/token-relayer.md`; any weakened invariant or stale security claim is a finding.
+- Trace checks-effects-interactions across every external call. Nonces and replay protection must be committed before interaction, reentrancy must be blocked, and any revert must roll back the full execution.
+- Verify that signed data binds the chain, verifying contract, immutable destination, owner, token, value, native value, nonce, deadline, and exact payload bytes. Use OpenZeppelin EIP-712/ECDSA behavior rather than custom recovery.
+- Account for tokens using execution-local before/after balances and safe ERC-20 operations. Fee-on-transfer, rebasing, partial consumption, pre-existing balances, and stale allowances must fail closed without spending unrelated funds.
+- Keep approvals exact and transient, validate low-level call success and return behavior, reject zero or codeless destinations, and return native refunds to the executor without opening a reentrancy path.
+- Check current-owner access control for recovery operations, emitted audit events, zero-address handling, and behavior after ownership transfer.
+- Require regression tests for replay, expiry, wrong signer/domain/destination, permit front-running, destination revert/reentrancy, receipt mismatch, partial token consumption, refund failure, and withdrawal authorization when the affected logic changes.
+- Treat deployment modules and configured addresses as part of the security change. Source fixes are not production fixes until every supported chain is updated and verified.