# Recoil — Project Glossary

This file is the top-level glossary for the Recoil engine. It points at the canonical project-vocabulary source (`recoil/CLAUDE.md`) and adds local terms introduced by feature builds.

## Canonical project terms

`recoil/CLAUDE.md` is the source of truth for the existing canonical Recoil vocabulary:

- **Recoil** — the whole system (narrative engine + visual pipeline).
- **Narrative Engine** — `recoil/` (everything outside `recoil/pipeline/`).
- **Visual Pipeline** — `recoil/pipeline/` (absorbed from the legacy sibling `starsend/` folder on 2026-03-30; the `starsend/` folder is dead).
- **Workspace** — the visual production review surface (shots, takes, beats, scenes).
- **console-v2** — the React shell at `recoil/console-v2/packages/desktop/` that replaces the legacy production console.
- **Project list** — Recoil project slugs (tartarus, the-afterimage, leviathan, olympus, singularity, the-hike, etc.) plus archived projects under `projects/_archive/`.

When in doubt, read `recoil/CLAUDE.md` first.

## Console-v2 chat terms (embedded-claude-terminal build)

Verbatim glossary from BUILD_SPEC §2 of the embedded-claude-terminal harness build (`consultations/recoil/embedded-claude-terminal/BUILD_SPEC.md`):

- **ChatColumn** — the React component mounted in the right column of console-v2 that hosts the embedded terminal stack (ContextStrip + ContextBar + ProposalTray + DropZone(iframe) + Pasteboard + hints). Replaces the legacy `ChatPanel`. Avoid: "right pane," "chat panel" (the latter refers to the deprecated stub).
- **ContextStrip** — the three-row label block at the top of ChatColumn showing the active project, focus, and selection. Distinct from **ContextBar**, which shows token-window usage. Avoid: confusing the two.
- **TerminalIframe** — the iframe wrapper around a ttyd port serving xterm.js + the embedded `claude` CLI session. Avoid: "the embed," "the terminal frame."
- **Pasteboard** — the buffer of file paths dropped from the console tree or chosen via file picker. Distinct from the OS clipboard (Pasteboard's "Copy" button writes to the OS clipboard).
- **ProposalTray** — the React surface above the iframe that renders `SpecCard` components for pending `propose_action` proposals.
- **propose_action** — the new MCP tool Claude calls to emit a structured re-roll/edit proposal. Pinned diff schema in BUILD_SPEC §5.
- **chat-session** — a `claude --resume <id>` session bound to one Recoil project. One per project, persisted in `~/.recoil/chat-sessions.json`.
- **keystroke bubbler** — the userscript injected into ttyd's HTML template that forwards a whitelist of console-v2 keyboard shortcuts (⌘K, ⌘\, ⌘$, ⌘B, ⌘[, ⌘], ⇧H, ⌘J) up to the parent window via `postMessage`.
- **IPC bridge** — `POST /api/internal/bus` in FastAPI; the only path by which `mcp_server.py` (separate process tree) can reach the in-memory event BUS.

## ADR index

ADRs live under `recoil/docs/adr/`. Embedded-claude-terminal decisions are 0006–0010; Console v2 + Engine Overhaul (CP-A) decisions are 0011–0014:

- 0006 — Embed Claude Code via ttyd, not a native chat backend
- 0007 — One Claude session per Recoil project, persisted in `~/.recoil/chat-sessions.json`
- 0008 — MCP-to-FastAPI IPC via localhost HTTP bridge
- 0009 — Proposal lifecycle multiplexes onto existing `/api/events/stream` SSE
- 0010 — Drop Finder drag-and-drop from v3 scope
- 0011 — Console v2 Hybrid A canonical (supersedes Spec A and Spec B)
- 0012 — Project SSOT lives in the `Project` class
- 0013 — Import idiom is `from recoil.X import ...`
- 0014 — Console v2 chat surface is the embedded ttyd terminal only

## Console v2 Overhaul (2026-05-07)

Glossary delta from BUILD_SPEC §2 of the Console v2 + Engine Overhaul build (`consultations/recoil/console-v2-overhaul/BUILD_SPEC.md`). Format: `Term — definition. Avoid: synonyms.`

- **`projects_root()`** — the canonical callable in `recoil/core/paths.py` that returns the directory containing all project subdirectories. Avoid: `PROJECTS_ROOT` (the deprecated module-level constant), `_projects_root()` (the four duplicate helpers being deleted), "the projects dir" (informal).
- **`Project` (class)** — runtime SSOT for project policy, defined in `recoil/core/project.py`. Constructed from `projects/{slug}/project_config.json`. Avoid: "project bible" (that's `global_bible.json` — separate concern), "project config" (that's the on-disk JSON; the runtime object is `Project`).
- **`ProjectConfig` (Pydantic)** — the on-disk schema model in `recoil/core/project.py`. Field set: `schema_version`, `project_type`, `aspect_ratio`, `default_models`, `mode` (legacy alias). Avoid: "ProjectPolicy", "ProjectMeta".
- **`ProjectType`** — enum of `microdrama` | `client_deliverable`. Avoid: `mode` (legacy alias deprecated for one cycle).
- **`AspectRatio`** — enum of `9_16` | `16_9` | `1_1` | `4_3`. Underscore form is canonical on disk and in Python. Colon form (`9:16`) is human-display only. Avoid: hand-typed `"vertical"`, `"horizontal"`.
- **`aspect_synthesized`** — boolean flag on `ProjectResponse` indicating the aspect was resolved via legacy migration path. Avoid: "migrated", "default", "fallback".
- **`ProjectsRootUnresolvable`** — typed exception raised by `projects_root()` when no source provides a value. Avoid: bare `RuntimeError`, "config error".
- **`AspectUnresolvable`** — typed exception raised by `_resolve_aspect` (and indirectly by `Project`) when no source provides aspect. Avoid: bare `ValueError`.
- **`EpisodeIdUnresolvable`** — typed exception name reserved for the future when the sanctioned fallback in `_derive_episode_id` is removed. Not raised in this spec; added to glossary so future contractors don't reinvent the name.
- **`FALLBACK_FIRED`** — the structured bus-event topic for sanctioned fallbacks (Law 4 three-prong test). Avoid: "warning", "fallback_event".
- **`ConnectionState`** — TypeScript string-enum (`"disconnected" | "connecting" | "degraded" | "connected"`) for SSE handshake state. Avoid: `is_connected: bool`.

Existing canonical terms used unchanged: `Take`, `Beat`, `Shot`, `Scene`, `Episode`, `pipeline`, `engine`.