[AZ-1131] Align integration test docs with run-tests.sh

Co-authored-by: Cursor <cursoragent@cursor.com>

AGENTS.md

@@ -161,10 +161,7 @@ docker-compose up --build
 ./scripts/run-tests.sh
 ```
 
-**Run tests** (Docker Compose with tests):
+See `_docs/02_document/tests/environment.md` for manual `docker-compose.tests.yml` invocation and required env vars.
-```bash
-docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit
-```
 
 ### CI / Deploy platforms
 
@@ -281,8 +278,9 @@ From goal.md:
 - Volume mounts for tiles, ready, logs
 
 **docker-compose.tests.yml:**
-- Integration tests service
+- Self-contained stack: postgres, api, and integration-tests (internal network only; postgres not published to host)
-- Depends on api and db services
+- Integration tests service depends on api and db health
+- Canonical runner: `./scripts/run-tests.sh` (Step 2 uses this file only)
 - Runs and exits after completion
 
 ## Troubleshooting

README.md

@@ -35,13 +35,10 @@ Swagger documentation: `http://localhost:5100/swagger`
 ### Run with Tests
 
 ```bash
-docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit
+./scripts/run-tests.sh
 ```
 
-This command:
+This script runs unit tests, then integration tests via the self-contained `docker-compose.tests.yml` stack. Use `--smoke` for a fast subset or `--full` for the complete suite.
-- Builds and starts all services
-- Runs integration tests
-- Exits when tests complete
 
 ## Architecture
 
@@ -384,10 +381,13 @@ dotnet test
 ```
 
 **Integration Tests:**
+
 ```bash
-docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit
+./scripts/run-tests.sh
 ```
 
+See `_docs/02_document/tests/environment.md` for manual Compose invocation and environment variables.
+
 ### Database Migrations
 
 Migrations run automatically on startup. SQL files are located in:

_docs/02_document/tests/environment.md

@@ -67,7 +67,15 @@ Suite CI/agent reference: [`suite/_infra/ci/README.md`](../../../../_infra/ci/RE
 
 **Decision**: Docker (no hardware dependencies detected)
 **Hardware dependencies found**: None
-**Execution method**: `docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit`
+**Canonical entry point**: `./scripts/run-tests.sh` (Step 0: format check; Step 1: unit tests; Step 2: integration tests via Compose).
+
+**Manual integration command** (matches `run-tests.sh` Step 2):
+
+```bash
+docker compose -f docker-compose.tests.yml up --build --abort-on-container-exit --exit-code-from integration-tests
+```
+
+`docker-compose.tests.yml` is self-contained (postgres + api + integration-tests on an internal Docker network). Postgres is not published to the host — intentional when host port 5433 is occupied by a sibling stack.
 
 **Performance tests** (Step 15 / `scripts/run-performance-tests.sh`): start the API with the perf overlay when host port 5433 is occupied — `docker compose -f docker-compose.yml -f docker-compose.perf.yml up -d --build`. Details: [containerization.md](../deployment/containerization.md#compose-overlays-dev--test--perf). PT-10 (`DeliverRouteTiles` gRPC stream) runs via `dotnet SatelliteProvider.IntegrationTests --run-pt10` inside the script; host-side default `API_URL=https://localhost:18980` with TLS trust via `./certs/api.crt` (`PERF_CA_CERT` override). Harness knobs:
 

_docs/02_tasks/_dependencies_table.md

@@ -270,7 +270,7 @@ Step 9 cycle 14: 1 task created (AZ-1131 = 1 pt) — align `environment.md` inte
 
 | Task | Depends On | Points | Status |
 |------|-----------|--------|--------|
-| AZ-1131 environment.md integration command | — | 1 | Todo |
+| AZ-1131 environment.md integration command | — | 1 | Done (In Testing) |
 
 ### Step 9 cycle 13 (capturedAt DateTimeOffset — AZ-1126)
 

_docs/03_implementation/batch_01_cycle14_report.md

@@ -0,0 +1,29 @@
+# Batch Report
+
+**Batch**: 1
+**Tasks**: AZ-1131_environment_md_integration_command
+**Date**: 2026-06-26
+**Cycle**: 14
+
+## Task Results
+
+| Task | Status | Files Modified | Tests | AC Coverage | Issues |
+|------|--------|---------------|-------|-------------|--------|
+| AZ-1131 | Done | 3 files | N/A (docs) | 3/3 ACs covered | None |
+
+## AC Test Coverage: All covered
+
+| AC | Verification |
+|----|--------------|
+| AC-1 | `rg 'docker-compose.yml.*docker-compose.tests.yml' environment.md` → zero matches; canonical `run-tests.sh` + Step 2 command documented |
+| AC-2 | Same pattern in `README.md` and `AGENTS.md` → zero matches; both point to `./scripts/run-tests.sh` |
+| AC-3 | Docs-only delta; no compose/script edits |
+
+## Code Review Verdict: PASS
+
+Docs-only ripple; no production code touched. Stale dual-compose integration command removed from operator-facing surfaces.
+
+## Auto-Fix Attempts: 0
+## Stuck Agents: None
+
+## Next Batch: All tasks complete

_docs/03_implementation/implementation_completeness_cycle14_report.md

@@ -0,0 +1,20 @@
+# Implementation Completeness — Cycle 14
+
+**Date**: 2026-06-26
+**Gate**: Product Implementation Completeness (Step 15)
+
+## Per-Task Classification
+
+| Task | Classification | Evidence |
+|------|----------------|----------|
+| AZ-1131 | PASS | `environment.md`, `README.md`, `AGENTS.md` updated; grep confirms zero stale dual-compose integration commands; scope explicitly docs-only |
+
+## System Pipeline Audit
+
+| Pipeline | Sequence | Classification | Evidence |
+|----------|----------|----------------|----------|
+| N/A | — | N/A | Docs-only cycle — no production pipeline changes |
+
+## Gate Verdict: PASS
+
+All product tasks PASS. No remediation tasks required.

_docs/03_implementation/implementation_report_environment_md_integration_command_cycle14.md

@@ -0,0 +1,30 @@
+# Implementation Report — environment_md_integration_command (Cycle 14)
+
+**Cycle**: 14
+**Date**: 2026-06-26
+**Tasks**: AZ-1131
+
+## Summary
+
+Aligned integration-test orchestration documentation with the canonical `scripts/run-tests.sh` path. Removed stale `docker-compose.yml` + `docker-compose.tests.yml` dual-file instructions from operator-facing docs.
+
+## Changes
+
+| File | Change |
+|------|--------|
+| `_docs/02_document/tests/environment.md` | § Test Execution now cites `./scripts/run-tests.sh` and documents self-contained `docker-compose.tests.yml` Step 2 command |
+| `README.md` | Run-with-tests and integration-test sections point to `./scripts/run-tests.sh` |
+| `AGENTS.md` | Removed stale dual-compose block; expanded `docker-compose.tests.yml` description |
+
+## Verification
+
+- AC-1/AC-2: `rg 'docker-compose.yml.*docker-compose.tests.yml'` → zero matches in `environment.md`, `README.md`, `AGENTS.md`
+- AC-3: No runtime files modified
+
+## Test Handoff
+
+Full-suite gate deferred to autodev Step 11 (Run Tests) per implement skill Step 16 handoff rule.
+
+## Completeness
+
+See `implementation_completeness_cycle14_report.md` — PASS.