feat: runtime manager

rtmanager/docs/README.md

@@ -0,0 +1,44 @@
+# Runtime Manager — Service-Local Documentation
+
+This directory hosts the service-local documentation for `Runtime
+Manager`. The top-level [`../README.md`](../README.md) describes the
+current-state contract (purpose, scope, lifecycles, surfaces,
+configuration, observability); the documents below complement it with
+focused content docs and design-rationale records.
+
+## Content docs
+
+- [Runtime and components](runtime.md) — process diagram, listeners,
+  workers, lifecycle services, stream offsets, configuration groups,
+  runtime invariants.
+- [Flows](flows.md) — mermaid sequence diagrams for the lifecycle and
+  observability flows.
+- [Operator runbook](runbook.md) — startup, readiness, shutdown, and
+  recovery scenarios.
+- [Configuration and contract examples](examples.md) — `.env`,
+  REST request bodies, stream payloads, storage inspection snippets.
+
+## Design rationale
+
+- [PostgreSQL schema decisions](postgres-migration.md) — the schema
+  decision record consolidating the persistence-layer agreements
+  (tables, indexes, CAS shape, `created_at` preservation, jsonb
+  round-trip, schema/role provisioning split).
+- [Domain and ports](domain-and-ports.md) — string-typed enums, the
+  four allowed runtime transitions, why `Inspect` splits into
+  `InspectImage` / `InspectContainer`, why `LobbyGameRecord` is
+  minimal, and other domain-layer choices.
+- [Adapters](adapters.md) — Docker SDK adapter, Lobby internal HTTP
+  client, the three Redis publishers, the `mockgen` convention for
+  wide ports, and the unit-test strategy for HTTP-backed adapters.
+- [Lifecycle services](services.md) — per-game lease semantics, the
+  `Result`-shaped contract, failure-mode tables, the lease-bypass
+  `Run` method on inner services, the `X-Galaxy-Caller` header
+  convention, and the canonical error code → HTTP status mapping.
+- [Background workers](workers.md) — single-ownership table per
+  `event_type`, `container_disappeared` suppression rules, probe
+  hysteresis, the events listener reconnect policy, the reconciler's
+  per-game lease and three drift kinds.
+- [Service-local integration suite](integration-tests.md) — the
+  `integration` build tag, the in-process `app.NewRuntime` choice,
+  the Lobby HTTP stub, and the test isolation strategy.