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

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

_docs/02_tasks/done/AZ-1131_environment_md_integration_command.md

@@ -0,0 +1,86 @@
+# Align environment.md integration test command with run-tests.sh
+
+**Task**: AZ-1131_environment_md_integration_command
+**Name**: Align environment.md integration command with run-tests.sh
+**Description**: Fix stale integration-test orchestration docs that still reference `docker-compose.yml` + `docker-compose.tests.yml` while `scripts/run-tests.sh` uses self-contained `docker-compose.tests.yml` only.
+**Complexity**: 1 points
+**Dependencies**: None
+**Component**: test environment documentation
+**Tracker**: AZ-1131 (https://denyspopov.atlassian.net/browse/AZ-1131)
+**Epic**: None
+
+## Problem
+
+`_docs/02_document/tests/environment.md` § Test Execution documents:
+
+`docker-compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit`
+
+`scripts/run-tests.sh` (canonical Step 11 gate) runs integration tests with:
+
+`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). The dual-file command is stale since the test stack was split out. This mismatch has been a carry-over since cycle 12 retro and misleads operators copying docs instead of the script.
+
+## Outcome
+
+- `environment.md` matches the real integration test orchestration path
+- Operators can run integration tests by following either `environment.md` or `run-tests.sh` without conflicting instructions
+- Stale dual-compose references in agent-facing docs are corrected or cross-linked
+
+## Scope
+
+### Included
+
+- Update `environment.md` § Test Execution to document `docker-compose.tests.yml` only and cite `scripts/run-tests.sh` as the canonical entry point
+- Ripple fix: `README.md` and `AGENTS.md` integration-test command lines (same stale dual-compose pattern)
+- No compose file or script behavior changes
+
+### Excluded
+
+- Historical task specs in `_docs/02_tasks/done/` (AZ-285 AC-2 records the old command — leave as historical artifact)
+- Perf orchestration docs (already correct — uses `docker-compose.yml` + `docker-compose.perf.yml`)
+- CI Woodpecker pipeline changes
+
+## Acceptance Criteria
+
+**AC-1: environment.md accuracy**
+Given `environment.md` § Test Execution
+When an operator reads the documented integration command
+Then it matches `scripts/run-tests.sh` Step 2 (`docker compose -f docker-compose.tests.yml …`) and names the script as canonical
+
+**AC-2: Agent-facing doc ripple**
+Given `README.md` and `AGENTS.md` integration test sections
+When an operator follows those instructions
+Then they reference `docker-compose.tests.yml` only (or point to `./scripts/run-tests.sh` exclusively)
+
+**AC-3: No runtime change**
+Given the task is complete
+When `./scripts/run-tests.sh --smoke` is run
+Then behavior is unchanged (docs-only delta)
+
+## Non-Functional Requirements
+
+**Compatibility**
+- Documented manual command must remain valid on darwin/arm64 without requiring `docker-compose.yml`
+
+## Unit Tests
+
+| AC Ref | What to Test | Required Outcome |
+|--------|-------------|-----------------|
+| AC-3 | N/A (docs only) | Verified by grep + optional smoke run |
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|------------------------|-------------|-------------------|----------------|
+| AC-1 | `environment.md` on disk | Ripgrep for `docker-compose.yml -f docker-compose.tests.yml` | Zero matches in `environment.md` | — |
+| AC-2 | `README.md`, `AGENTS.md` | Ripgrep for stale dual-compose integration command | Zero matches or explicit redirect to `run-tests.sh` | — |
+
+## Constraints
+
+- Documentation-only — no compose or script edits unless a comment in `run-tests.sh` is needed for cross-link clarity
+
+## Risks & Mitigation
+
+**Risk 1: Operators relied on dual-compose for host port mapping**
+- *Mitigation*: `docker-compose.tests.yml` does not publish postgres to host; document that this is intentional (internal network only)