Merge pull request #3 from chendbox/codex-final-acceptance

refine README overview

Author: chendbox

README.md

@@ -29,36 +29,33 @@
 
 This platform map shows the major control-plane, execution-plane, persistence,
 and observability domains. The public demo path is intentionally narrower than
-the full platform surface.
+the full platform surface, but the same boundaries carry through the production
+shape of the system.
 
 ![MLIS platform map](docs/images/platform-map.svg)
 
+The diagram below connects those domains along the primary request, scheduling,
+execution, and persistence path.
+
+![Primary control and execution flow](docs/images/primary-control-execution-flow.svg)
+
 `/internal/workers` and `/internal/assignments` are worker/data-plane protocol
 routes, not public user APIs. Users submit and inspect work through `/v1/jobs`,
-the CLI, or the console; worker containers use `/internal/*` to register
-capacity, poll assignments, and report execution state. See the
+the CLI, or the console. Worker containers use `/internal/*` to register
+capacity, claim assignments, heartbeat lease ownership, and report execution
+state. See the
 [worker protocol runbook](docs/runbooks/worker-protocol.md).
 
-```mermaid
-stateDiagram-v2
-    [*] --> PENDING: admission accepted
-    PENDING --> RUNNING: assignment claimed
-    RUNNING --> SUCCEEDED: worker finish
-    RUNNING --> FAILED: worker/report failure
-    RUNNING --> PENDING: lease expired / reclaim
-    PENDING --> CANCELLED: user cancel
-    RUNNING --> CANCELLED: user cancel
-    SUCCEEDED --> [*]
-    FAILED --> [*]
-    CANCELLED --> [*]
-```
-
-This diagram shows the public `job` lifecycle. Execution attempts are modeled
-separately as `job_assignments`, which is what makes lease expiry and reclaim
-possible without collapsing user intent and worker execution into one state
-machine.
+The public lifecycle is modeled at two levels: `job` captures durable user
+intent, while `job_assignment` captures individual execution attempts. That
+separation makes lease expiry, reclaim, and worker recovery possible without
+collapsing user intent and worker execution into one state machine. See
+[job lifecycle](docs/design/job-lifecycle.md) and
+[lease-based recovery](docs/design/lease-recovery.md) for the full state model.
 
-Authentication and tenant binding happen in middleware before route handlers. Tenant context comes from the verified token; database queries are filtered by `tenant_id` from `request.state.identity`, not from request bodies.
+Authentication and tenant binding happen in middleware before route handlers.
+Tenant context comes from the verified token; database queries are filtered by
+`tenant_id` from `request.state.identity`, not from request bodies.
 
 <!-- Screenshot slot: docs/images/console-overview.png -->
 <!-- ![Console overview](docs/images/console-overview.png) -->