From 4abe8183d8c2c748f76a68ce4f50c527473d3c81 Mon Sep 17 00:00:00 2001
From: Albert <albert@noreply.git.vaporware.studio>
Date: Mon, 10 Nov 2025 14:12:58 +0000
Subject: [PATCH] docs: Update AGENTS.md with CI testing infrastructure details
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Documented the containerized CI approach using docker-compose.ci.yml
- Added instructions for local CI testing with test-ci-locally.sh
- Explained benefits of the approach (reproducibility, simplicity)
- Updated .gitignore to ignore SurrealDB data directory

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .gitignore |  3 +++
 AGENTS.md  | 43 +++++++++++++++++++++++++++++++++----------
 2 files changed, 36 insertions(+), 10 deletions(-)

diff --git a/.gitignore b/.gitignore
index d9921ee..eb92dca 100644
--- a/.gitignore
+++ b/.gitignore
@@ -46,3 +46,6 @@ tests/playwright/.auth/
 
 # claude settings (keep .claude/CLAUDE.md but ignore user settings)
 .claude/settings.local.json
+
+# surrealdb data
+surreal/data/
diff --git a/AGENTS.md b/AGENTS.md
index 18d269b..d880cbc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -160,28 +160,51 @@ Playwright is integrated into docker-compose for consistent testing environments
 
 **CI/CD with Gitea Actions**:
 
-Magnitude tests run automatically on every push and pull request via Gitea Actions:
+Magnitude tests run automatically on every push and pull request using a fully containerized setup:
 
 1. **Configuration**: `.gitea/workflows/magnitude.yml`
 
-2. **Workflow steps**:
-   - Checkout code
-   - Setup Node.js and pnpm
-   - Start SurrealDB in Docker
-   - Start Next.js dev server with environment variables
-   - Run Magnitude tests
-   - Upload test results as artifacts
+2. **Workflow steps** (simplified to just 2 steps!):
+   - Create `.env` file with secrets
+   - Run `docker compose -f docker-compose.ci.yml --profile test up`
+   - Upload test results and show logs on failure
+   - Cleanup
 
 3. **Required Secrets** (configure in Gitea repository settings):
    - `ANTHROPIC_API_KEY` - For Magnitude AI vision testing
    - `TEST_BLUESKY_HANDLE` - Test account handle
    - `TEST_BLUESKY_PASSWORD` - Test account password
-   - `SURREALDB_USER`, `SURREALDB_PASS`, `SURREALDB_NS`, `SURREALDB_DB`
    - `ATPROTO_CLIENT_ID`, `ATPROTO_REDIRECT_URI`
    - `GOOGLE_API_KEY`, `DEEPGRAM_API_KEY`
    - `SURREAL_JWT_SECRET`
 
-4. **Test results**: Available as workflow artifacts for 30 days
+4. **CI-specific docker-compose**: `docker-compose.ci.yml`
+   - Fully containerized (SurrealDB + Next.js + Magnitude)
+   - Excludes surrealmcp (only needed for local MCP development)
+   - Health checks ensure services are ready before tests run
+   - Uses in-memory SurrealDB for speed
+   - Services dependency chain: magnitude → nextjs → surrealdb
+
+5. **Debugging CI failures locally**:
+   ```bash
+   # Runs the EXACT same docker-compose setup as CI
+   ./scripts/test-ci-locally.sh
+
+   # Or manually:
+   docker compose -f docker-compose.ci.yml --profile test up \
+     --abort-on-container-exit \
+     --exit-code-from magnitude
+   ```
+   Since CI just runs docker-compose, you can reproduce failures **exactly** without any differences between local and CI environments!
+
+6. **Test results**: Available as workflow artifacts for 30 days
+
+7. **Why this approach is better**:
+   - ✅ Identical local and CI environments (both use same docker-compose.ci.yml)
+   - ✅ Fast debugging (no push-test-fail cycles)
+   - ✅ Self-contained (all dependencies in containers)
+   - ✅ Simple (just 2 steps in CI workflow)
+   - ✅ Reproducible (docker-compose ensures consistency)
 
 **Testing Framework Separation**: