Epic: close Dockerized runtime status

DEVELOPMENT_STATUS.md

@@ -1,68 +1,111 @@
 # Development Status
 
-Last reviewed: 2026-05-11
+Last reviewed: 2026-05-27
 
 ## What Currently Works
 
-- Python development setup through `make setup`.
-- Deterministic simulator scenarios through `make simulate`.
-- JSONL ingestion, validation, and dead-letter handling through `make ingest`.
-- Process Sentinel drift detection, evidence, and recommendation generation through `make sentinel-run`.
-- FastAPI local API startup through `make api`, with auto-reload available through `make api-reload`.
-- PostgreSQL Docker Compose configuration through `make dev-db`.
-- Backend checks through `make lint`, `make typecheck`, and `make test`.
+- Docker Compose starts the FIP `postgres`, `api`, `web`,
+  `connector-worker`, and `sentinel-worker` services.
+- The Compose stack does not start an in-repo simulator container.
+  Demo-Factory runs separately as the local external protocol source fixture.
+- The read-only connector worker loads Demo-Factory OPC-UA, MQTT, and BACnet
+  connection fixtures and normalizes source readings into FactoryEvents.
+- Docker services use Postgres-backed runtime state by default through
+  `FACTORY_STORAGE_BACKEND=postgres`.
+- The scheduled Process Sentinel worker reads stored FactoryEvents and writes
+  advisory detections, evidence, and recommendations.
+- The FastAPI API exposes runtime health, connection profile diagnostics,
+  source inventory, detections, evidence, recommendations, and draft
+  investigation data.
+- The Next.js Workbench renders the current operator console over API state.
+- `make compose-smoke` validates API health, connector-ingested events,
+  readable Process Sentinel state, and Workbench rendering against the composed
+  runtime.
+- Focused local checks are available through `make lint`, `make typecheck`,
+  `make test`, `make test-e2e`, and `cd apps/web && npm test`.
 
 ## What Is Incomplete
 
-- `apps/web` is a placeholder; the Next.js workbench has not been implemented.
-- `make test-e2e` is a documented placeholder until the web workbench exists.
-- PostgreSQL is configured, but the default local MVP flow still uses JSONL storage.
-- Real MQTT, OPC UA, MES, QMS, CMMS, and ERP connectors are out of scope for the current skeleton.
-- Authentication, multi-tenant behavior, production deployment, and real industrial writeback are not implemented.
+- Local Demo-Factory endpoints are development fixtures, not production
+  connectors or validation evidence.
+- Authentication, multi-tenant behavior, production deployment, Kubernetes,
+  Helm, and high-availability operations are not implemented.
+- Real industrial writeback, MQTT command publishing, BACnet writes, product
+  disposition, and QMS/MES writeback are intentionally out of scope.
+- CI hardening for the full Docker Compose smoke path can still be improved
+  after the local runtime remains stable.
 
-## How To Run The Current Skeleton
+## How To Run The Current Runtime
+
+Start Demo-Factory separately from a sibling checkout:
 
 ```bash
-make setup
-make simulate SCENARIO=gradual_drift
-make ingest INPUT=.local/events/gradual_drift.jsonl
-make sentinel-run
-make api
+cd ../Demo-Factory
+docker compose up -d --build
+```
+
+Start FIP from this repository:
+
+```bash
+cd ../Factory-Intelligence-Platform
+make compose-up
+make compose-ps
+make compose-logs
 ```
 
 Then open:
 
 ```text
 http://127.0.0.1:8000/docs
+http://127.0.0.1:3000
 ```
 
-Optional local PostgreSQL:
+Stop the FIP stack with:
 
 ```bash
-make dev-db
+make compose-down
 ```
 
+Use `docs/runtime/DOCKER_COMPOSE.md` for detailed startup, shutdown, rebuild,
+logs, health, and smoke commands. Use `docs/runtime/TROUBLESHOOTING.md` when
+Docker, Postgres, connector, API, or Workbench checks fail.
+
+## Focused Local Development
+
+For direct API or Workbench loops outside the full Compose stack:
+
+```bash
+make setup
+make api
+cd apps/web
+npm run dev
+```
+
+The repository still keeps JSONL-backed fixtures for fast unit and integration
+tests. Use them only for focused regression work that intentionally does not
+need Postgres or the full composed runtime.
+
 ## Verified Commands
 
 ```bash
+docker compose -f infra/docker/docker-compose.yml config
+make compose-smoke
 make lint
 make typecheck
 make test
 make test-unit
 make test-integration
 make test-contract
 make test-e2e
-make dev-db
-docker compose -f infra/docker/docker-compose.yml config
-docker compose -f infra/docker/docker-compose.yml ps
+cd apps/web && npm test
 ```
 
-`make test-e2e` should print the placeholder message until the web workbench is implemented.
-`make dev-db` should start a healthy PostgreSQL container on local port `5432`.
-
 ## Recommended Next Steps
 
-1. Harden shared event contracts with additional fixtures for recommendation, approval, and audit events.
-2. Add the first minimal web workbench screen over the existing API state.
-3. Replace the placeholder e2e command with a Playwright test once the workbench exists.
-4. Decide when JSONL development storage should give way to the PostgreSQL-backed path for integration tests.
+1. Keep Docker Compose runtime docs current as connector, API, and Workbench
+   behavior changes.
+2. Harden CI around the Dockerized runtime when the local smoke path remains
+   stable enough for GitHub Actions.
+3. Expand external-source coverage only through read-only connector boundaries.
+4. Continue separating advisory recommendations from any future
+   human-approved action routing.

README.md

@@ -94,8 +94,8 @@ See `docs/CONNECTOR_SAFETY_MODEL.md` for the current connector safety model.
 
 ## Local Runtime Commands
 
-The Compose runtime is being introduced through epic #232. Start Demo-Factory
-separately when validating external local protocol sources:
+The Compose runtime from epic #232 is the current local integration path. Start
+Demo-Factory separately when validating external local protocol sources:
 
 ```bash
 cd ../Demo-Factory

apps/web/README.md

@@ -2,10 +2,9 @@
 
 Next.js operator-console shell for the Factory Intelligence Platform.
 
-The Workbench is moving toward the Docker/Demo-Factory runtime direction:
-external Demo-Factory protocol services feed FIP read-only connectors, which
-normalize readings into FactoryEvents for Process Sentinel, the API, and the
-Workbench.
+The Workbench is part of the Docker/Demo-Factory runtime path: external
+Demo-Factory protocol services feed FIP read-only connectors, which normalize
+readings into FactoryEvents for Process Sentinel, the API, and the Workbench.
 
 ## Local Startup
 
@@ -87,7 +86,7 @@ RCA/CAPA draft panels should be treated as missing runtime data until
 Demo-Factory, FIP Compose, connector ingestion, and Process Sentinel have all
 run.
 
-For focused Workbench development before all Compose services land, run the API
+For focused Workbench development outside the full Compose stack, run the API
 directly from the repository root:
 
 ```bash

docs/DEMO_RUNBOOK.md

@@ -54,15 +54,15 @@ Use `docker compose down` for normal shutdown. Use
 `docker compose -f infra/docker/docker-compose.yml down -v` only when you
 intentionally want to delete FIP named volumes such as local Postgres data.
 
-The Compose runtime is being built across the Dockerized runtime epic. Some
-services may be placeholders until the child issues for API/web images,
-connector worker, Postgres-backed runtime storage, Sentinel worker, and Compose
-smoke tests land.
+The Compose runtime is the current local integration path for FIP. It includes
+the API, Workbench, Postgres, read-only connector worker, and Process Sentinel
+worker. Use `make compose-smoke` with Demo-Factory already running separately
+to verify API health, connector ingestion, Process Sentinel state, and
+Workbench rendering.
 
 ## Focused Local Development
 
-For focused API or Workbench development before the full Compose stack is
-available:
+For focused API or Workbench development outside the full Compose stack:
 
 ```bash
 make setup

docs/DEVELOPMENT.md

@@ -84,9 +84,7 @@ Use `docker compose down` for normal shutdown. Use
 `docker compose -f infra/docker/docker-compose.yml down -v` only when you
 intentionally want to delete FIP named volumes such as local Postgres data.
 
-Some Compose services are still landing through the Dockerized runtime epic. For
-focused API or Workbench development before the full composed stack is
-available, run:
+For focused API or Workbench development outside the full composed stack, run:
 
 ```bash
 make setup
@@ -121,10 +119,12 @@ Current skeleton components:
 
 - `packages/factory-events` — shared event contracts
 - `services/simulator` — legacy local fixture code, not the default runtime path
-- `services/ingestion` — validation and dead-letter handling
+- `services/ingestion` — read-only connector worker, validation, and
+  dead-letter handling
 - `services/process-sentinel` — drift rules, evidence, recommendations
 - `services/api` — FastAPI endpoints for the MVP state
-- `infra/docker` — PostgreSQL compose config
+- `infra/docker` — Docker Compose runtime for Postgres, API, Workbench,
+  connector worker, and Sentinel worker
 
 ## Connector Fixture Safety
 

docs/LEARNING_LOG.md

@@ -22,6 +22,68 @@ This file should be updated by Codex after each meaningful change.
 ### What to learn next
 ```
 
+## 2026-05-27 - Dockerized runtime epic status cleanup
+
+### What changed
+
+Updated current runtime status and runbook wording so the documentation treats
+the Docker Compose path from epic #232 as the active local integration runtime,
+not a future placeholder. Added regression coverage for stale wording that
+would reintroduce the old placeholder or simulator-default framing.
+
+### Why it matters
+
+The child issues already supplied the composed API, Workbench, Postgres,
+connector worker, Sentinel worker, external Demo-Factory source fixtures, and
+Compose smoke path. Closing the epic safely requires the entry-point docs to
+match that implemented behavior.
+
+### How it works
+
+The docs now describe Demo-Factory running separately, FIP Compose running the
+platform services, connector ingestion normalizing source readings into
+FactoryEvents, Postgres-backed runtime state in Docker, and Process Sentinel
+reading that stored state. The doc regression test checks those claims and
+blocks stale placeholder language from returning to current runtime docs.
+
+### How to run it
+
+```bash
+cd ../Demo-Factory
+docker compose up -d --build
+
+cd ../Factory-Intelligence-Platform
+make compose-up
+make compose-smoke
+make compose-down
+```
+
+### How to test it
+
+```bash
+.venv/bin/python -m pytest services/simulator/tests/test_runtime_docs_transition.py services/simulator/tests/test_docker_compose_runtime_docs.py
+make lint
+make typecheck
+make test
+cd apps/web && npm test
+```
+
+### Key files
+
+- `DEVELOPMENT_STATUS.md`
+- `README.md`
+- `docs/runtime/DOCKER_COMPOSE.md`
+- `docs/DEMO_RUNBOOK.md`
+- `docs/DEVELOPMENT.md`
+- `apps/web/README.md`
+- `services/ingestion/README.md`
+- `services/simulator/tests/test_runtime_docs_transition.py`
+
+### What to learn next
+
+Keep the Docker Compose smoke path reliable enough to promote into CI without
+turning local Demo-Factory fixtures into production-readiness evidence.
+
 ## 2026-05-27 - Scheduled Process Sentinel worker
 
 ### What changed

docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md

@@ -3,7 +3,7 @@
 ## Status
 
 This document replaces the old Workbench runbook for the in-repo generated-data
-demo. The Workbench is moving toward the Dockerized FIP runtime where external
+demo. The Workbench now aligns with the Dockerized FIP runtime where external
 Demo-Factory protocol services provide local source data.
 
 ## Current Direction
@@ -31,7 +31,7 @@ cd ../Factory-Intelligence-Platform
 docker compose -f infra/docker/docker-compose.yml up --build
 ```
 
-For focused Workbench development before all Compose services land:
+For focused Workbench development outside the full Compose stack:
 
 ```bash
 make api

docs/runtime/DOCKER_COMPOSE.md

@@ -16,10 +16,10 @@ Demo-Factory protocols
 -> Next.js Workbench
 ```
 
-The Dockerized runtime is being built across epic #232. The FIP Compose stack
-now defines the API, Workbench, connector worker, Process Sentinel worker, and
-Postgres service shape. `make compose-smoke` provides the current local
-end-to-end smoke path for this composed runtime.
+The Dockerized runtime from epic #232 is the current local integration path.
+The FIP Compose stack defines the API, Workbench, connector worker, Process
+Sentinel worker, and Postgres service shape. `make compose-smoke` provides the
+local end-to-end smoke path for this composed runtime.
 
 ## Dependency Order
 

services/ingestion/README.md

@@ -5,7 +5,7 @@ FactoryEvent contracts and persists normalized events for downstream services.
 
 ## Current Runtime Direction
 
-FIP is moving toward this Docker/Demo-Factory runtime path:
+FIP uses this Docker/Demo-Factory runtime path for local integration:
 
 ```text
 Demo-Factory protocols
@@ -69,9 +69,9 @@ dead-letter records with enough context for debugging.
 
 ## Focused Development
 
-The repository still contains legacy local fixture commands and tests while the
-Dockerized runtime is being completed. Use them only for focused regression
-work on event validation and Process Sentinel behavior.
+The repository still contains legacy local fixture commands and tests. Use them
+only for focused regression work on event validation and Process Sentinel
+behavior when Postgres and the full composed runtime are not needed.
 
 Run the focused ingestion tests from the repository root: