From d3f086801f85c1b94c6e33f29490aac164e0d222 Mon Sep 17 00:00:00 2001
From: Naeel <naeel@nubes.ru>
Date: Mon, 13 Apr 2026 07:23:51 +0300
Subject: [PATCH] agents: add AGENTS.md with machine-readable deployment
 instructions

---
 AGENTS.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 186 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..456be04
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,186 @@
+# AGENTS.md — Machine-readable deployment instructions for AI agents
+
+## YOUR TASK
+
+Deploy `shared-sqs` to a Kubernetes cluster using the Helm chart in `./deploy/`.
+
+---
+
+## STEP 1 — COLLECT REQUIRED INFORMATION FROM USER
+
+Ask the user for ALL of the following before doing anything else.
+Do NOT proceed if any required value is missing.
+
+### Required
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `REDIS_ADDR` | Redis address, format `host:port` | `redis.default.svc.cluster.local:6379` |
+| `REDIS_PASSWORD` | Redis password | `mysecretpassword` |
+| `ADMIN_TOKEN` | Admin API token, any random string | output of `openssl rand -hex 20` |
+| `INGRESS_HOST` | Domain pointing to cluster ingress IP | `sqs.example.com` |
+
+### Optional
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `REDIS_USER` | `default` | Redis username, change only if using Redis ACL |
+| `NAMESPACE` | `shared-sqs` | Kubernetes namespace |
+| `IMAGE_TAG` | `v0.1.24` | Service image version |
+| `SEED_DEMO` | `true` | Create demo tenant on first start |
+| `BILLING_ENABLED` | `false` | Enable billing to PostgreSQL |
+| `PG_HOST` | — | Required only if BILLING_ENABLED=true |
+| `PG_PORT` | `5432` | Required only if BILLING_ENABLED=true |
+| `PG_DATABASE` | — | Required only if BILLING_ENABLED=true |
+| `PG_USER` | — | Required only if BILLING_ENABLED=true |
+| `PG_PASSWORD` | — | Required only if BILLING_ENABLED=true |
+| `PG_SSLMODE` | `require` | Required only if BILLING_ENABLED=true |
+
+---
+
+## STEP 2 — CLONE REPOSITORY
+
+```bash
+git clone https://gitea.services.ngcloud.ru/Nail/shared-SQS.git
+cd shared-SQS
+```
+
+---
+
+## STEP 3 — EDIT deploy/values.yaml
+
+Replace placeholder values with values collected in Step 1.
+
+Mandatory substitutions:
+- `your-redis-host:6379` → value of `REDIS_ADDR`
+- `your-redis-password` → value of `REDIS_PASSWORD`
+- `your-admin-token` → value of `ADMIN_TOKEN`
+- `sqs.your-domain.com` → value of `INGRESS_HOST`
+
+If `BILLING_ENABLED=true`, also set `billing.enabled: true` and fill all `billing.postgres.*` fields.
+
+---
+
+## STEP 4 — DEPLOY
+
+```bash
+helm install shared-sqs ./deploy -n shared-sqs --create-namespace
+```
+
+Expected output must contain:
+```
+STATUS: deployed
+```
+
+If output contains `Error:` — stop and report the error to the user.
+
+---
+
+## STEP 5 — WAIT FOR POD READY
+
+```bash
+kubectl rollout status deployment/shared-sqs -n shared-sqs --timeout=90s
+```
+
+Expected output:
+```
+deployment "shared-sqs" successfully rolled out
+```
+
+If timeout or error — run `kubectl describe pod -n shared-sqs` and report to user.
+
+---
+
+## STEP 6 — VERIFY SERVICE IS RESPONDING
+
+```bash
+curl -s https://<INGRESS_HOST>/health
+```
+
+Expected output:
+```
+OK
+```
+
+If response is not `OK` — check pod logs:
+```bash
+kubectl logs -n shared-sqs deployment/shared-sqs --tail=50
+```
+Report logs to user.
+
+---
+
+## STEP 7 — CREATE FIRST TENANT
+
+```bash
+curl -s -X POST https://<INGRESS_HOST>/admin/tenants \
+  -H "Authorization: Bearer <ADMIN_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-tenant"}'
+```
+
+Expected response contains `access_key` and `secret_key`:
+```json
+{
+  "id": "t-...",
+  "name": "my-tenant",
+  "access_key": "SSAK-...",
+  "secret_key": "...",
+  ...
+}
+```
+
+**Save `secret_key` — it is shown only once.**
+
+If response contains `"error"` — report the full response to user.
+
+---
+
+## STEP 8 — VERIFY SQS WORKS
+
+```bash
+export AWS_ACCESS_KEY_ID="<access_key from step 7>"
+export AWS_SECRET_ACCESS_KEY="<secret_key from step 7>"
+export AWS_DEFAULT_REGION="us-east-1"
+ENDPOINT="--endpoint-url https://<INGRESS_HOST>"
+
+aws sqs create-queue --queue-name test-queue $ENDPOINT
+```
+
+Expected output contains `QueueUrl`.
+
+---
+
+## SUCCESS CRITERIA
+
+Deployment is complete and correct when ALL of the following are true:
+
+- [ ] `curl /health` returns `OK`
+- [ ] Tenant created, `access_key` and `secret_key` received
+- [ ] `aws sqs create-queue` returns a `QueueUrl`
+
+---
+
+## KNOWN ISSUES
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Pod stuck in `Pending` | Not enough cluster resources | Check `kubectl describe pod` for resource limits |
+| Pod in `CrashLoopBackOff` | Wrong Redis address or password | Check `kubectl logs`, fix `redis.addr` / `redis.password` in values.yaml, then `helm upgrade` |
+| `curl /health` times out | DNS not pointing to ingress IP | Ask user to check DNS A-record for `INGRESS_HOST` |
+| Admin API returns 401 | Wrong `ADMIN_TOKEN` | Token in `Authorization: Bearer` must match `admin.token` in values.yaml |
+
+---
+
+## UPGRADE
+
+```bash
+helm upgrade shared-sqs ./deploy -n shared-sqs
+```
+
+## UNINSTALL
+
+```bash
+helm uninstall shared-sqs -n shared-sqs
+kubectl delete namespace shared-sqs
+```