From 5ad31e0fdf326af35b0f8374df9d13363adad12f Mon Sep 17 00:00:00 2001
From: Hussen <hussen@Hussens-MacBook-Pro.local>
Date: Sun, 28 Jun 2026 15:03:18 +0530
Subject: [PATCH] Add Codex project guidance

---
 .gitignore |  3 +++
 AGENTS.md  | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/.gitignore b/.gitignore
index 965717a..7b49652 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,6 @@
 __pycache__/
 .pytest_cache/
 *.pyc
+.codex/
+PROJECT_MEMORY.md
+project_memory.json
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2d080b7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,56 @@
+# AGENTS.md
+
+Guidance for Codex and other coding agents working in this repository.
+
+## Project
+
+- This is a simple Python Flask app intended for containerized deployment to AWS ECS.
+- The app entrypoint is `app.py`.
+- Tests live in `tests/test_app.py`.
+- Dependencies are listed in `requirements.txt`.
+- A `Dockerfile` is present for image builds.
+
+## Local Validation
+
+Use the existing test flow before changing deploy behavior or app routes:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pytest -q
+```
+
+If dependencies are already installed, `pytest -q` is enough.
+
+## CI/CD
+
+- Primary workflow: `.github/workflows/deploy.yml`.
+- The `validate` job runs Python tests with pytest.
+- The `deploy` job builds and pushes Docker images to ECR, then updates the ECS service.
+- Keep `environment: dev` on the deploy job so GitHub environment variables are available.
+- The workflow uses GitHub OIDC to assume an AWS role via the `AWS_ROLE_TO_ASSUME` secret.
+
+## AWS Deployment Notes
+
+- ECR image tags use two forms:
+  - Immutable tag: `dev-<sha>`.
+  - Moving alias: `dev-latest`.
+- ECS task definition image references must use repository/tag syntax, for example:
+
+```text
+<account>.dkr.ecr.<region>.amazonaws.com/<repo>:dev-latest
+```
+
+- Do not use a slash in place of the tag separator, such as `<repo>/dev-latest`.
+- If ECS tasks run in private subnets, they need outbound access through NAT or VPC endpoints for ECR and S3.
+
+## Preferred Future Direction
+
+The current workflow updates the ECS service with `--force-new-deployment` after pushing `dev-latest`.
+
+Preferred improvement: register a new ECS task definition revision using the immutable `dev-<sha>` image, then update the service to that revision. This makes deployments more auditable and avoids relying only on a moving tag.
+
+## Private Local Context
+
+Detailed imported project memory may exist locally under `.codex/`. That folder is intentionally ignored by Git and should not be committed.