docs: establish Go backend repository rules

.gitignore

@@ -0,0 +1,19 @@
+# Raw/local data: keep README only
+/data/incoming/*
+!/data/incoming/README.md
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Go outputs and local tooling
+/bin/
+/dist/
+/coverage/
+*.test
+*.out
+/vendor/
+.idea/
+.vscode/
+

AGENT.md

@@ -0,0 +1,4 @@
+# Compatibility Pointer
+
+The canonical agent instructions are in [`AGENTS.md`](AGENTS.md). Do not duplicate or diverge from them here.
+

AGENTS.md

@@ -0,0 +1,39 @@
+# Backend Agent Operating Contract
+
+## Phase gate
+
+This repository is in specification mode. Do not create `go.mod`, application packages, migrations, containers, or executable code until the relevant capability spec is approved.
+
+For every Go-related task, always invoke and follow the `golang-how-to` skill, then the secondary Go skills it routes to. Before creating the Go project layout, ask the user to approve the architecture style and dependency-injection approach in that order.
+
+## Product invariants
+
+- The backend is the authority for authentication, authorization, tenant isolation, metric definitions, and data provenance.
+- Every merchant-scoped query derives merchant identity from the authenticated server-side session; never trust a client-supplied merchant identifier as authorization.
+- Cross-merchant results are minimum-cohort, anonymized aggregates only.
+- Use integer minor currency units or an explicitly documented fixed-precision representation; never floating point for money.
+- Preserve source timestamps and document their timezone assumptions. Normalize operational timestamps consistently.
+- Raw imports are immutable inputs; corrections are new import versions, not silent mutation.
+- `adjusted_fee` is obfuscated and may be used only for relative analysis.
+
+## Go baseline after approval
+
+- Keep `main` packages thin under `cmd/`; business code lives under `internal/`.
+- Use explicit constructors; avoid `init()` side effects and mutable globals.
+- Configuration comes from validated environment variables. Logs go to stdout as structured records without credentials, card keys, or sensitive payloads.
+- Propagate `context.Context`; bound external calls, queues, batches, and database pools.
+- Use parameterized queries and transactions with explicit boundaries. Stream/bulk-load the multi-million-row input instead of holding it in memory.
+- Passwords use an approved adaptive hash (Argon2id or bcrypt per the approved auth spec); sessions use secure, HttpOnly cookies and server-side revocation.
+- Required verification includes unit/integration tests, race detection where applicable, `go vet`, `golangci-lint`, `govulncheck`, and migration/import tests.
+
+## Git and documentation
+
+- Use atomic Conventional/Commitizen commits.
+- Track specs, ERD/schema definitions, migrations, importer code, validation rules, manifests/templates, and runbooks.
+- Ignore raw CSV archives, database volumes/dumps, credentials, and generated runtime data.
+- Changes to a metric, API, schema, authorization rule, or AI data boundary require the corresponding spec/ADR update.
+
+## AI boundary (post-MVP)
+
+AvalAI is accessed only from the backend using a server-held API key. Prefer the simplest bounded LLM call/workflow that satisfies the approved use case. Send minimized, sanitized aggregates with explicit budgets/timeouts; persist trace metadata and deterministic inputs, not unnecessary sensitive prompts. AI output is advisory and must cite underlying deterministic metrics.
+

README.md

@@ -0,0 +1,27 @@
+# ZarinPal Merchant Analytics — Backend
+
+Go backend for merchant identity, dataset ingestion, deterministic analytics, authenticated APIs, and later AvalAI integration.
+
+Current state: specification bootstrap only. There is intentionally no Go module or application scaffold yet because the architecture and dependency-injection choices still require approval.
+
+## Local dataset input
+
+Place the provided archive at:
+
+```text
+data/incoming/challenge_data.csv.gz
+```
+
+The entire `data/incoming/` payload is ignored by Git. Future import tooling will read from this location (or an explicitly supplied path), stream the compressed CSV, validate it, and write a tracked import manifest containing the source checksum, schema version, row counts, quality results, and importer revision. The raw file and resulting PostgreSQL data are not committed.
+
+## Planned runnable boundaries
+
+One repository may expose several small `cmd/` entry points while sharing domain packages under `internal/`:
+
+- HTTP API
+- dataset importer
+- database migration command
+- analytics refresh/background job, only if the approved spec requires one
+
+The exact package layout is deferred until the Go architecture and DI decisions are approved.
+

data/incoming/README.md

@@ -0,0 +1,16 @@
+# Incoming dataset
+
+Copy the challenge dataset to this directory as `challenge_data.csv.gz` before running the future importer. The archive is intentionally ignored by Git.
+
+Expected source columns:
+
+```text
+session_key, try_seq, terminal_key, merchant_key, category_id,
+category_title, amount, adjusted_fee, session_status, try_status,
+switch_response_code, psp_code, issuer_bank_code, payer_card_key,
+verify_type, init_time_ms, verify_time_ms, created_at, try_created_at,
+verified_at, settled_at, expire_in
+```
+
+Do not add merchant passwords or other secrets to this directory. Demo credentials will be generated/seeding inputs managed separately through secure environment or one-off administrative workflows.
+