[CodeBuildder]

Summary

Phase 3 replaces Argus's collection of disconnected setup instructions with one paved, cluster-free path from a fresh checkout to a working and populated console.

An unfamiliar developer or judge can now run:

make setup-local
make demo-local

The second command starts the API and UI, waits for backend readiness, generates incidents, prints every useful URL, and keeps both services alive until the user presses Ctrl-C.

Closes #94.

This is a stacked PR targeting agent/build-week-phase-2-world-model. Its diff contains only Phase 3. After earlier phases merge, it can be retargeted to main.

Why this change

The previous README contained the necessary components, but not a reliable sequence:

• OrbStack and Kubernetes prerequisites appeared before the cluster-free path;
• backend, UI, and simulation commands were presented independently;
• make simulate-threats did not say that the API must already be running;
• a missing backend produced only curl: (7) Failed to connect;
• local synthetic incidents and real Falco/Cilium detections were not clearly separated;
• there was no readiness check, combined launcher, stopping instruction, or expected result;
• a judge had to infer which parts required an API key or live cluster.

That ambiguity is especially costly for a developer-tool submission, where judges are not required to reconstruct the environment themselves.

The paved path

1. Install

make setup-local

This creates the Python virtual environment, installs the locked agent dependencies, and installs UI dependencies with npm ci.

2. Launch and populate

make demo-local

The launcher:

1. verifies Python and Node dependencies;
2. checks ports 8000 and 5173;
3. starts FastAPI on 127.0.0.1:8000;
4. starts Vite on 127.0.0.1:5173;
5. polls the backend health endpoint;
6. detects either child exiting during startup;
7. generates ten mixed incidents;
8. prints the console, API documentation, and health URLs;
9. stops both child processes on Ctrl-C or launcher exit.

3. Explore and replay

While the demo is running:

make simulate-threats THREAT_COUNT=10 THREAT_SCENARIO=mixed

Deterministic replay remains available:

make simulate-threats \
  THREAT_COUNT=10 \
  THREAT_SCENARIO=attack_chain \
  THREAT_SEED=20260717

Clear testing modes

The README and guide now distinguish:

Mode	Cluster	Purpose
Local synthetic	Not required	Console, API, approval, incident, and attack-chain workflows
Full Kubernetes	Required	Real Falco, Cilium, Kyverno, and remediation evidence

Local mode explicitly requires no OrbStack VM, Kubernetes cluster, Falco, Cilium, Kyverno, API key, or cloud infrastructure.

Developer commands

New Make targets:

• make setup-local
• make demo-local
• make dev-agent
• make dev-ui

The existing make simulate-threats now performs a backend health preflight and prints the exact recovery command when the API is unavailable.

Documentation

docs/GETTING_STARTED.md provides:

• mode selection;
• exact prerequisites;
• numbered setup and launch steps;
• expected behavior;
• scenario descriptions;
• deterministic replay;
• separate-service development;
• local-mode limitations;
• full-cluster handoff;
• troubleshooting by symptom, cause, and fix;
• repository verification.

The README surfaces the two-command path immediately after the project hero instead of burying it below cluster implementation details.

Validation

Automated

• make test
  • 86 backend tests passed
  • TypeScript compilation passed
  • Vite production build passed
• bash -n scripts/demo-local.sh
• git diff --check

End-to-end launcher verification

Verified locally without Kubernetes:

• FastAPI bound to port 8000;
• Vite bound to port 5173;
• /health returned 200;
• seeded human_approval and mixed scenarios were generated;
• generated incidents were returned from /incidents;
• the UI root returned successfully;
• Ctrl-C terminated the backend and UI processes.

Failure-path verification

With no backend running, make simulate-threats now reports:

Argus backend is not running on localhost:8000.
Start it with: make dev-agent
Or launch the complete cluster-free demo with: make demo-local

Reviewer guide

1. Start at the README quickstart and follow only the commands it presents.
2. Review scripts/demo-local.sh for lifecycle and readiness behavior.
3. Review docs/GETTING_STARTED.md as a first-time evaluator.
4. Confirm local and cluster modes never imply the same evidence source.
5. Stop the launcher with Ctrl-C and confirm ports 8000 and 5173 are released.

Out of scope and follow-ups

• One-command deployment of the full Kubernetes stack
• Combined Argus, Phoenix, and Sentinel local launcher
• Public hosted judge sandbox
• Dashboard content and visual polish
• Final demonstration video