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

docs: polish public release materials

Author: chendbox

README.md

@@ -116,6 +116,9 @@ stateDiagram-v2
 
 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) -->
+
 ## Why This Project Exists
 
 The project demonstrates practical AI infrastructure design: lifecycle state, capacity control, scheduler/worker separation, lease-based recovery, resource accounting, multi-tenant authorization, observability, and productized developer workflows.
@@ -185,8 +188,9 @@ docker compose up -d --scale worker=4 app worker
 
 The stack runs Postgres, the API in push-scheduler mode, and 4 worker containers. Each worker
 container starts multiple logical worker slots from `jobs.worker_concurrency`, so the console may
-show more ACTIVE worker slots than Docker containers. For example, 4 containers with concurrency 4
-produce 16 logical execution slots. The public compose file sets
+show more ACTIVE worker slots than Docker containers. These slots are logical execution capacity,
+not additional Docker worker containers. For example, 4 containers with concurrency 4 produce
+16 logical execution slots. The public compose file sets
 `WORKER_GPU_HEALTH_PROBE=0` because `gpu_demo` is a simulated GPU scheduling demo and should run
 without a local NVIDIA runtime.
 
@@ -217,6 +221,9 @@ with `gpu_health_ok=true` only if `nvidia-smi -L` works inside the container. Th
 `python:3.11-slim`, so the public `gpu_demo` remains a scheduling simulation. Real PyTorch/CUDA execution
 requires a CUDA/PyTorch runtime image and matching dependencies.
 
+<!-- Screenshot slot: docs/images/gpu-demo-result.png -->
+<!-- ![GPU demo result](docs/images/gpu-demo-result.png) -->
+
 Useful URLs:
 
 - Console: http://localhost:8001/console
@@ -327,6 +334,9 @@ curl -sS http://localhost:8001/v1/jobs/<job_id>
 
 This demonstrates the worker lease/heartbeat/reclaim path: work is not permanently lost when an executor disappears. In a successful recovery run, the job first appears under the killed worker's `worker_uid`, then later appears under a different `worker_uid`, and finally reaches `state: "SUCCEEDED"`.
 
+<!-- Screenshot slot: docs/images/job-detail-lease-recovery.png -->
+<!-- ![Lease recovery job detail](docs/images/job-detail-lease-recovery.png) -->
+
 PowerShell notes:
 
 - Use `Select-String` instead of `grep`: `docker compose logs worker | Select-String -Pattern "<worker_uid>"`.
@@ -408,16 +418,11 @@ Install test dependencies:
 pip install -e ".[test]"
 ```
 
-Run the public release gate used by CI:
+Run the backend test suite used by GitHub Actions:
 
 ```bash
-pytest tests/unit \
-  tests/integration/test_health.py \
-  tests/integration/test_auth_middleware.py \
-  tests/integration/test_scoped_authorization.py \
-  tests/integration/test_jobs.py \
-  tests/integration/test_ui.py \
-  -q
+pytest tests/unit -q
+pytest tests/integration -q
 ```
 
 Run only the unit tests:
@@ -426,20 +431,40 @@ Run only the unit tests:
 pytest tests/unit -q
 ```
 
-Run the curated integration smoke tests:
+Run a smaller local integration smoke set:
 
 ```bash
 pytest tests/integration/test_health.py tests/integration/test_auth_middleware.py tests/integration/test_scoped_authorization.py tests/integration/test_jobs.py tests/integration/test_ui.py -q
 ```
 
+Build the React console:
+
+```bash
+cd src/app/ui-react
+npm install
+npm run build
+```
+
+Run the same Docker Compose smoke path used by CI:
+
+```bash
+docker compose up -d --build --scale worker=2
+curl -fsS http://localhost:8001/health/ready/full
+curl -fsS http://localhost:8001/ui
+docker compose down -v
+```
+
 PowerShell equivalent:
 
 ```powershell
 .\.venv\Scripts\python.exe -m pip install -e ".[test]"
-.\.venv\Scripts\python.exe -m pytest tests\unit tests\integration\test_health.py tests\integration\test_auth_middleware.py tests\integration\test_scoped_authorization.py tests\integration\test_jobs.py tests\integration\test_ui.py -q
+.\.venv\Scripts\python.exe -m pytest tests\unit -q
+.\.venv\Scripts\python.exe -m pytest tests\integration -q
 ```
 
-The project includes unit and integration coverage for core state transitions, scheduler behavior, worker paths, artifact handling, auth boundaries, and UI/CLI behavior.
+The GitHub Actions pipeline currently runs three gates: Python + Postgres tests, React console build,
+and a Docker Compose smoke test. The project includes unit and integration coverage for core state
+transitions, scheduler behavior, worker paths, artifact handling, auth boundaries, and UI/CLI behavior.
 
 ## Repository Guide
 
@@ -465,6 +490,8 @@ Runtime outputs such as `artifacts/`, `tmp/`, `logs/`, `reports/`, model files,
 
 ## Public Release Scope
 
+See the current release draft in [docs/release-notes/v0.1.0.md](docs/release-notes/v0.1.0.md).
+
 ### Implemented MVP
 
 - durable job and assignment lifecycle

docs/images/.gitkeep

@@ -0,0 +1 @@
+

docs/release-notes/v0.1.0.md

@@ -0,0 +1,92 @@
+# MLIS v0.1.0
+
+## Summary
+
+MLIS v0.1.0 is the first public-release candidate of the Machine Learning
+Infrastructure Service. This release focuses on the platform layer around ML
+inference workloads: job submission, durable state, scheduler-driven placement,
+worker execution, artifact-backed payloads, tenant-scoped authorization, and
+lease-based recovery when workers fail.
+
+The public release is intentionally local-first. The recommended demo path uses
+Docker Compose with Postgres, one API/control-plane process, and scalable
+worker/data-plane containers.
+
+## What This Release Includes
+
+- FastAPI control plane with `/v1/jobs` as the primary public API surface
+- Postgres-backed job and assignment state
+- Push scheduler and worker/data-plane separation
+- Worker registration, heartbeat, lease ownership, and reclaim-based recovery
+- Artifact-backed inputs and outputs
+- React operator console served by FastAPI
+- `mlis` CLI for local operator workflows
+- JWT-based auth, tenant binding, worker auth, and audit foundations
+- Simulated `gpu_demo` that exercises GPU-aware placement without requiring a
+  physical NVIDIA GPU
+- CI gates for:
+  - Python + Postgres tests
+  - React console build
+  - Docker Compose smoke startup
+
+## Recommended Demo Path
+
+The release is designed to be demonstrated through:
+
+1. `docker compose up -d --scale worker=4`
+2. `/console` for operator visibility
+3. `sleep` jobs for queue and assignment behavior
+4. lease recovery by killing a worker mid-run
+5. `gpu_demo` for simulated GPU-aware scheduling
+
+This path keeps the public story focused on the platform itself rather than on
+model quality or benchmark marketing.
+
+## Intentionally Out of Scope
+
+This release does not try to be:
+
+- a training platform
+- a benchmark-optimized serving stack
+- a hosted SaaS product
+- an identity provider
+- a real CUDA execution demo by default
+
+Optional integrations such as `tiny_llm` remain available as examples, but they
+are not the default public quickstart path.
+
+## Key Validation Performed
+
+Before release-candidate signoff, the project was validated through:
+
+- local Docker Compose startup with API, Postgres, and multiple worker
+  containers
+- successful `/health/ready/full` readiness checks
+- successful `/console` shell delivery
+- end-to-end `sleep` job execution
+- lease recovery by killing a worker during an active job and verifying
+  reassignment plus eventual success
+- successful simulated `gpu_demo` execution with GPU placement signals such as
+  `gpu_ids` and `cuda_visible_devices`
+- green GitHub Actions runs for backend tests, frontend build, and compose smoke
+
+## Known Constraints
+
+- The default Docker image is `python:3.11-slim`, so `gpu_demo` is a scheduling
+  simulation, not a real CUDA compute workload.
+- The console may show more ACTIVE worker slots than Docker worker containers
+  because each worker container can advertise multiple logical execution slots.
+- Advanced runtime panels and optional runners are present, but the public
+  release emphasizes the core scheduler/worker/job lifecycle path.
+
+## Release Positioning
+
+This release is best read as:
+
+- a local-first AI infrastructure platform demo
+- a design and systems project
+- a working reference for scheduler, worker, lease, auth, and observability
+  boundaries
+
+It is not positioned as a production-managed service offering or a finished ML
+product.

docs/validation/security_test.md

@@ -5,7 +5,7 @@ The examples below use PowerShell.
 ## 1. Start the service in warn mode
 
 ```powershell
-cd D:\Downloads\machine-learning-infrastructure-service\open-source-release
+cd path\to\machine-learning-infrastructure-service\open-source-release
 
 $env:PYTHONPATH="src"
 $env:ENABLE_POSTGRES="0"