# Data Model

Shows and plays are first-class entities in `state.db` (SQLite).

## Tables

```
shows table:
  id, topic, goal, repo, base_branch, integration_branch
  status: active | completed | aborted | imported
  show_dir, status_source, created_at, updated_at

plays table:
  id, show_id, name, playbook, effort
  status: pending | prepared | running | running_complete |
          gated | gate_failed | redoing | merged |
          escalated | blocked | aborted_after_finish
  attempt (1 or 2), session_id, started_at, ended_at, exit_code
  worktree, branch, merge_sha, merged_at
  gate_passed, gate_feedback, depends_on (JSON array), sort_order
  created_at, updated_at
```

Source: `lionagi/state/schema.sql` line ~218.

## Status enums

### Show status

| Value | Meaning |
|---|---|
| `active` | Show is in progress — plays are running or pending |
| `completed` | Final gate passed; integration PR opened |
| `aborted` | Operator triggered abort; no more plays will launch |
| `imported` | Show was imported from an external show directory |

### Play status

| Value | Meaning |
|---|---|
| `pending` | Not yet started; waiting for deps to merge |
| `prepared` | Worktree and prompt files written; not yet fired |
| `running` | The play's run is live (`job.status` for its `run_id` reports it non-terminal) |
| `running_complete` | Process exited; gate not yet run |
| `gated` | Gate ran and passed (synonym: about to merge) |
| `gate_failed` | Gate ran and failed; may redo |
| `redoing` | Attempt 2 is in progress |
| `merged` | Branch merged into integration; `merge_sha` recorded |
| `escalated` | Failed gate on attempt 2; human intervention needed |
| `blocked` | Dep failed or escalated; this play cannot proceed |
| `aborted_after_finish` | Show was aborted but the play had already completed |

## Reading a show from Studio

Studio's backend serves shows over `/api/shows` — list, detail, import and an SSE watcher —
and that is the interface to use.

**There is no Studio page for shows.** The frontend has no `/shows` route, and while a
`PlayDag` component exists in the source tree nothing imports it, so there is no dependency
graph to look at. Do not plan a show around watching it in the UI. The `_show.md` file and the
per-play `_meta.json` and `_verdict.json` are the readable state, and `job.status`,
`job.output` and `job.wait` are how you follow a play that is running.

The show directory is controlled by `LIONAGI_SHOWS_ROOT`. **Set it explicitly, and set it for
Studio too.** Both sides fall back to a built-in default when it is unset, and you should not
rely on those agreeing: if the skill writes a show somewhere Studio does not enumerate, the
show simply never appears and nothing reports an error. One variable, exported once, in the
environment both the skill and the Studio process see.
