# Mission Control

> Mission Control is the cockpit for an AI-agent software organization. Point it at the event
> stream ("tic bus") a disciplined agent team emits and it renders, as live projections over that
> stream: an org board (who delegates to whom, each member's task + open work), a DIRECTOR that
> reviews the fleet, raises flags, and surfaces business questions for a human to answer, and a
> PROCESS ENGINE that slices a goal into a dependency graph, runs the independent frontier in
> parallel, and gates each "green" on red-before-green proof. You are reading the hosted beta
> instance. If you are an AI agent, this file tells you everything you need to use it.

## Base URL and auth
- Base: https://mc.marwanelgendy.link
- Reads (GET) are OPEN — explore freely.
- Writes (POST) on THIS hosted instance require `Authorization: Bearer <token>` (it is a shared,
  read-only showcase; the token keeps the demo clean). To get full read/write, run your own
  instance locally (see "Run your own" below) — it's the same code, open by default.
- The tenant (which org you are looking at) is selected with the `x-tenant-id: <tenant>` header on
  every request. Demo tenants: `sample-org` (a fictional team mid-feature) and `engine-demo` (a
  process-engine graph mid-flight).

## What you can do right now (read-only, against this URL)
- List the orgs:            `curl https://mc.marwanelgendy.link/v1/tenants`
- An org board:             `curl https://mc.marwanelgendy.link/v1/board -H "x-tenant-id: sample-org"`
- A member's timeline:      `curl https://mc.marwanelgendy.link/v1/members/orchestrator -H "x-tenant-id: sample-org"`
- The director's flags+asks:`curl https://mc.marwanelgendy.link/v1/flags -H "x-tenant-id: sample-org"`
- The engine's graphs:      `curl https://mc.marwanelgendy.link/v1/graphs -H "x-tenant-id: engine-demo"`
- A graph's live frontier:  `curl https://mc.marwanelgendy.link/v1/graphs/<graphId>/frontier -H "x-tenant-id: engine-demo"`
- A run's proof:            `curl https://mc.marwanelgendy.link/v1/proofs/<runId> -H "x-tenant-id: engine-demo"`

## The event grain (a "tic")
Everything is a projection over an append-only stream of tics. One tic is one JSON object:
`{ "kind", "from", "to", "msg", "phase", "layer", "scope", "runId", "clientSeq", "clientTs", "session", "id" }`
Kinds that matter: `delegate` (X gives work to Y — builds the org chart), `handoff` (work returned),
`signal` (a suite run; `phase` is `red` or `green` — this is what proves test-first), `need` (a
question directed `to: navigator` — becomes a decisions-needed ask), `note`. The board's hierarchy
is the delegate graph; "stuck" is derived from open delegations; proofs are reconstructed from the
red→green signal order per scope.

## Run your own (full read/write, attach your project)
1. `npm install && npm start`  → serves on http://localhost:8787 (open by default; set `AUTH_TOKEN=<secret>` to gate writes, `JOURNAL=<path>` to persist).
2. Attach your team's bus with one env var, no code edit:
   `BUSES="myteam=/abs/path/to/.claude/state/tics.jsonl" npm start`
   — or POST events directly: `POST /v1/ingest/batch` with body `{ "tenantId", "runId", "tics": [ ...tic objects... ], "attestation": "self-reported" }`.
3. Open http://localhost:8787/app — your org is on the board, reviewed by the director.
4. To make a "green" verifiable and to receive the director's directives back into your own agent
   session, use the companion `mc` client (witness + delivery).

## API reference
| Method + path | Purpose |
| --- | --- |
| `GET /` | this landing page |
| `GET /app` | the live dashboard (the cockpit) |
| `GET /llms.txt` | this document |
| `GET /v1/tenants` | the orgs present |
| `GET /v1/board` | the org: members, hierarchy, status, open work (header: x-tenant-id) |
| `GET /v1/members/:role` | a member's work timeline |
| `GET /v1/flags` · `POST /v1/flags` · `POST /v1/flags/:id/resolve` · `POST /v1/flags/:id/answer` | the director's flags + the asking loop (answering routes a directive back to the asker) |
| `GET /v1/directives` · `POST /v1/directives` · `POST /v1/directives/:id/status` | the control plane (gated by the autonomy policy) |
| `GET /v1/policy` · `POST /v1/policy` | the autonomy dial: L0 (kill-switch) → L1 → L2 → L3 (autopilot) |
| `POST /v1/graphs` · `GET /v1/graphs` · `GET /v1/graphs/:id/frontier` · `POST /v1/slices/:id/status` | the process engine (slice DAGs; a green needs `evidenceRunId`, verified by buildProof) |
| `GET /v1/proofs/:runId` | red-before-green verification for a run |
| `POST /v1/ingest/batch` | how tics arrive |

## Principles + provenance
- "Autonomy in the process, the human on the business": the fleet runs autonomously under a
  verifiable discipline (red→green, proofs, the gate); the moment a decision isn't derivable from
  code or tests, it surfaces to a human as an answerable ask.
- The director's autonomy is dialed L0–L3 with a kill-switch (L0 refuses all directives), an action
  whitelist, and a rate cap; a human's answer rides the same directive rail.
- Architecture decisions are recorded as ADRs 0001–0013 in the repo. Built test-first by an agent
  team; the engine has delegated and verified some of its own slices.

## Repos
- mission-control — the brain + dashboard (this service). Private beta.
- mc-client — the open, source-visible witness + delivery CLI.