[AZ-1123] Document docker-compose.perf.yml port playbook

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

_docs/02_tasks/_dependencies_table.md

@@ -261,6 +261,7 @@ Step 9 cycle 8: 5 tasks queued (AZ-812 = 3 pts Region DTO rename, AZ-808 = 3 pts
 Step 9 cycle 8b: folded into cycle 8 as step 1 (AZ-812). Section retained in dependency table for traceability.
 Step 9 cycle 9: 2 tasks created (AZ-1074 = 5 pts, AZ-1075 = 3 pts) — total 8 pts. gRPC TileStream for route-based progressive tile delivery.
 Step 9 cycle 10: 1 task created (AZ-1113 = 2 pts) — REST 400 error message sanitization (F-AZ795-1/2, F-AZ810-1). Child of AZ-795.
+Step 9 cycle 11: 1 task created (AZ-1123 = 1 pt) — document `docker-compose.perf.yml` host-port conflict playbook (cycle 10 retro action).
 
 ## Coverage Verification
 

_docs/02_tasks/done/AZ-1123_perf_compose_docs.md

@@ -0,0 +1,69 @@
+# Document docker-compose.perf.yml host-port playbook
+
+**Task**: AZ-1123_perf_compose_docs
+**Name**: Document docker-compose.perf.yml host-port conflict playbook
+**Description**: Document when and how to use the perf compose overlay so Step 11/15 gates do not fail on host port 5433 conflicts.
+**Complexity**: 1 points
+**Dependencies**: None (builds on `docker-compose.perf.yml` added cycle 10)
+**Component**: deployment docs, test environment docs
+**Tracker**: AZ-1123 (https://denyspopov.atlassian.net/browse/AZ-1123)
+**Epic**: None
+
+## Problem
+
+Cycle 9–10 autodev integration and performance gates failed with `5433: address already in use` when a sibling Postgres container occupied the host port. Operators fixed it ad hoc with `docker-compose.perf.yml`, but deployment docs still describe only the default compose file.
+
+## Outcome
+
+- Operators and agents can find the host-port conflict playbook without reading cycle metrics or deploy reports.
+- Perf harness startup command is documented next to integration-test orchestration.
+
+## Scope
+
+### Included
+- `_docs/02_document/deployment/containerization.md` — compose overlays section (default dev, integration-only, perf overlay)
+- `_docs/02_document/tests/environment.md` — cross-link and perf execution compose command
+
+### Excluded
+- Changing `docker-compose.yml` or `docker-compose.perf.yml` behavior
+- CI/Woodpecker pipeline changes
+- README changes (unless required for AC)
+
+## Acceptance Criteria
+
+**AC-1: Containerization playbook**
+Given `containerization.md` is the deployment reference
+When an operator reads the compose overlays section
+Then it explains the 5433 conflict symptom, when to use `docker-compose.perf.yml`, and the exact `docker compose -f docker-compose.yml -f docker-compose.perf.yml up` command
+
+**AC-2: Test environment cross-link**
+Given `environment.md` describes test orchestration
+When an operator runs performance tests locally
+Then the doc names the perf compose overlay and points to `containerization.md` for details
+
+**AC-3: Integration vs perf distinction**
+Given both integration and perf harnesses exist
+When the docs are read
+Then integration tests are documented as using self-contained `docker-compose.tests.yml` (no host postgres port) separately from the perf overlay pattern
+
+## Unit Tests
+
+| AC Ref | What to Test | Required Outcome |
+|--------|-------------|-----------------|
+| — | Documentation-only task | N/A |
+
+## Blackbox Tests
+
+| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
+|--------|------------------------|-------------|-------------------|----------------|
+| — | — | — | — | — |
+
+## Constraints
+
+- Documentation only — no production behavior change
+
+## Risks & Mitigation
+
+| Risk | Mitigation |
+|------|------------|
+| Docs drift from compose files | Quote actual file names and commands from repo |