diff --git a/docs/ai-readiness-decisions.md b/docs/ai-readiness-decisions.md
new file mode 100644
index 0000000..ec3888a
--- /dev/null
+++ b/docs/ai-readiness-decisions.md
@@ -0,0 +1,185 @@
+# AI Readiness Decisions
+
+This file records one-time tooling decisions for this repository that the ThinkAI readiness
+scanner cannot infer from the repository tree.
+
+Fill each section that applies to your repo. Leave any field as `TODO` if the decision
+hasn't been made yet — the fix agent will pause and open a PR for you to complete it before
+continuing.
+
+---
+
+## What to fill in
+
+Complete the fields below that apply to your repository, then merge this PR and re-queue the fix.
+
+- [ ] **Repository context** — primary archetype and language/stack
+- [ ] **Database migrations** — does this repo own migrations? If yes, which tool and where?
+- [ ] **Code quality & test coverage** — Sonar project key, host URL, and coverage thresholds
+- [ ] **Behavior-driven development** — adopt BDD? If yes, which runner and where are feature files?
+- [ ] **Load & performance testing** — which load test tool and CI cadence?
+- [ ] **Chaos & resilience testing** — which chaos approach and target environment?
+- [ ] **API end-to-end tests** — which E2E tool and staging base URL env var?
+- [ ] **API contracts** — OpenAPI source type, spec path, and async messaging?
+- [ ] **Container publishing** — image build method, registry host, and CI auth method
+- [ ] **Deployment & infrastructure** — K8s, GitOps, and Terraform directories (if applicable)
+- [ ] **Repository & platform settings** — required CI checks and protected branches
+- [ ] **Dependency updates** — which dependency bot (Dependabot or Renovate)?
+
+Sections that do not apply to your repo can be left as-is or removed.
+
+---
+
+## Repository context
+
+- **Primary archetype**: `library`
+  <!-- backend-api | frontend-spa | mobile-ios | mobile-android | data-pipeline | library | other -->
+- **Default branch**: `main`
+  <!-- main | master | develop -->
+- **Primary language / stack**: `Go`
+  <!-- e.g. Node.js/TypeScript, Python/FastAPI, Java/Spring Boot, Go/Gin, PHP/Laravel -->
+
+---
+
+## Deployment & infrastructure
+
+<!-- Used when creating Kubernetes manifests, GitOps config, Terraform, or deployment runbooks. -->
+
+- **K8s manifests directory**: `none`
+  <!-- e.g. k8s/, deploy/k8s/, infrastructure/k8s/ — or "none" if not applicable -->
+- **GitOps controller**: `none`
+  <!-- ArgoCD | FluxCD | none -->
+- **Terraform directory**: `none`
+  <!-- e.g. infrastructure/terraform/, terraform/ — or "none" if not applicable -->
+- **Terraform remote state backend**: `none`
+  <!-- S3 | GCS | AzureBlob | TerraformCloud | none -->
+
+---
+
+## Database migrations
+
+- **Owns DB migrations**: `no`
+  <!-- yes | no — if "no", remaining fields are N/A -->
+- **Migration tool**: `N/A`
+  <!-- Flyway | Liquibase | Alembic | golang-migrate | Knex | Prisma | other -->
+- **Changeset location**: `N/A`
+  <!-- e.g. src/main/resources/db/migration, migrations/, db/migrations/ -->
+- **Baseline strategy**: `N/A`
+  <!-- baseline_existing_schema | fresh_schema_only | no_baseline -->
+
+---
+
+## Code quality & test coverage
+
+- **Sonar project key**: `TODO`
+  <!-- e.g. myorg_my-service -->
+- **Sonar host URL**: `TODO`
+  <!-- e.g. https://sonarcloud.io or https://sonar.internal.example.com -->
+- **Sonar organization** *(SonarCloud only)*: `TODO`
+- **Line coverage threshold %**: `90`
+  <!-- e.g. 80 — README contribution guidelines require >90% test coverage -->
+- **Branch coverage threshold %**: `TODO`
+  <!-- e.g. 75 -->
+
+---
+
+## Behavior-driven development
+
+- **Adopt BDD in this repo**: `no`
+  <!-- yes | no — if "no", this section is N/A -->
+- **BDD runner**: `N/A`
+  <!-- cucumber-jvm | serenity-bdd | pytest-bdd | behat | other -->
+- **Feature files location**: `N/A`
+  <!-- e.g. src/test/resources/features/, features/, tests/features/ -->
+
+---
+
+## Load & performance testing
+
+- **Load test tool**: `TODO`
+  <!-- k6 | Gatling | JMeter | Locust | Artillery | other -->
+- **CI cadence**: `TODO`
+  <!-- nightly | weekly | manual | per-pr -->
+- **Traffic-model source**: `none`
+  <!-- prod-logs | synthetic | none -->
+- **Baseline environment**: `TODO`
+  <!-- staging | dedicated-perf | local -->
+
+---
+
+## Chaos & resilience testing
+
+- **Chaos approach**: `TODO`
+  <!-- toxiproxy | chaos_monkey | litmus | documented_drill_only -->
+- **Target environment**: `TODO`
+  <!-- staging | production | local-only -->
+- **Chaos test directory**: `TODO`
+  <!-- e.g. chaos/, tests/chaos/ — or leave TODO for documented_drill_only -->
+
+---
+
+## API end-to-end tests
+
+- **E2E tool**: `N/A`
+  <!-- rest-assured | playwright | cypress | karate | other -->
+- **Staging base URL** *(env var name)*: `N/A`
+  <!-- e.g. STAGING_BASE_URL, E2E_API_URL — agent will use this as an env var reference -->
+
+---
+
+## API contracts
+
+- **OpenAPI source**: `none`
+  <!-- springdoc_runtime | committed_spec | ci_generated | none -->
+- **OpenAPI spec path** *(if committed_spec or ci_generated)*: `N/A`
+  <!-- e.g. api/openapi.yaml, openapi/openapi.yaml, docs/openapi.yaml -->
+- **Has async messaging**: `no`
+  <!-- yes | no -->
+- **AsyncAPI spec path** *(if has async messaging)*: `N/A`
+  <!-- e.g. api/asyncapi.yaml, docs/asyncapi.yaml -->
+
+---
+
+## Container publishing
+
+- **Image build method**: `dockerfile`
+  <!-- dockerfile | buildpacks | jib | kaniko -->
+- **Registry host**: `TODO`
+  <!-- e.g. ghcr.io, registry.digitalocean.com, docker.io/myorg, gcr.io/myproject -->
+- **CI auth method**: `TODO`
+  <!-- oidc | registry_secret -->
+- **Image name** *(optional — inferred from repo name if blank)*: `ghcr.io/ckshitij/collection`
+  <!-- e.g. myorg/my-service -->
+
+---
+
+## Repository & platform settings
+
+<!-- These require GitHub admin actions — no file commit can satisfy them.
+     Fill these so the guidance PR includes your exact desired configuration. -->
+
+- **Required CI status checks** *(comma-separated)*: `Code Quality Checks`
+  <!-- e.g. build,test,lint — checks that must pass before merge -->
+- **Protected branches**: `main`
+  <!-- e.g. main — or "main,develop" for multiple -->
+- **Repo visibility target**: `TODO`
+  <!-- private | internal | public -->
+
+---
+
+## Dependency updates
+
+- **Dependency bot choice**: `TODO`
+  <!-- dependabot | renovate -->
+- **Auto-merge minor/patch**: `TODO`
+  <!-- yes | no -->
+- **Target branches**: `main`
+  <!-- e.g. main — leave blank to use default branch -->
+
+---
+
+## Sign-off
+
+- **Filled by**: `TODO`
+- **Date**: `TODO`
+- **Notes**: `TODO`