# Plan: Flexible Intake — Deferred Variables + Prepared Sessions

## Context

The current intake form on procedural flows is a blocking modal that forces engineers to enter all variables before the flow starts. This creates friction because:
- Engineers don't always have all the information upfront
- Information often lives in PSA tickets, RMM tools, or was communicated verbally
- Sometimes a lead/PM has the info and wants to set up the session for an engineer to execute later

**Goal:** Replace the blocking intake modal with two complementary workflows:
1. **Deferred Variables** — start the flow immediately, fill variables inline as you encounter them
2. **Prepared Sessions** — pre-fill variables ahead of time, optionally assign to an engineer, execute later

---

## Design

### Workflow 1: Deferred Variables (Start Now, Fill Later)

- "Start Flow" launches the session immediately — no intake modal
- Variables begin empty
- When a step references `[VAR:server_name]` and it's unfilled, an **inline input prompt** renders in place — visually prominent with the field's label, help text, and styling that stands out (cyan border, slight glow)
- Once filled, the value persists and resolves everywhere in the session
- Engineers can also open a **"Session Variables" side panel** at any time to see/edit all variables
- At **session completion**, if required variables are still empty → soft warning with a prompt to fill them (for complete export documentation), but not a hard block

### Workflow 2: Prepared Sessions (Set Up Ahead, Execute Later)

- From a flow's detail page: "Prepare Session" action opens a form to fill variables + assign an engineer
- Creates a session in `prepared` state — `started_at` is null, variables populated, no steps executed
- **Assignment:** Preparer can assign to a specific engineer on their team (or leave unassigned)
- **Personal queue:** Engineers see prepared sessions assigned to them in a dedicated section (Quick Start page or Session History tab)
- Clicking a prepared session opens the flow with variables pre-populated; execution begins normally
- Unassigned prepared sessions are visible to all team members

### Data Model Changes

**Session model additions:**
- `prepared_by_id` — UUID FK to users, nullable. Who created the prepared session.
- `assigned_to_id` — UUID FK to users, nullable. Who should execute it.
- Use existing convention: `started_at IS NULL` = prepared, `started_at IS NOT NULL, completed_at IS NULL` = active, `completed_at IS NOT NULL` = completed

**Session variables become mutable:**
- `session_variables` is currently write-once at session creation
- New endpoint: `PATCH /sessions/{id}/variables` — updates individual variables during an active session
- Only the session owner (or assigned engineer) can update variables

**Migration:** One migration adding `prepared_by_id` and `assigned_to_id` columns with FK constraints.

### Variable Resolution Changes

**Backend:**
- No changes to export pipeline — it already resolves variables from `session_variables`
- New `PATCH /sessions/{id}/variables` endpoint accepts partial variable updates
- Session creation no longer validates required intake fields (they can be filled later)

**Frontend — `resolveVariables()` in `lib/variableResolver.ts`:**
- Currently returns a plain string with `[VAR:x]` replaced
- New behavior: also identify unresolved variables so `StepDetail` can render inline prompts

**Frontend — `StepDetail.tsx`:**
- When rendering step content, unresolved `[VAR:x]` references render as inline input components
- Inline prompt design: input field with the field's label as placeholder, cyan border, subtle glow background to make them visually prominent and easy to spot
- On blur/enter: calls `PATCH /sessions/{id}/variables` → re-renders step with resolved value
- Lookup field metadata (label, field_type, help_text, options) from the intake form definition in the tree snapshot

**Frontend — Session Variables Panel:**
- Existing "View Parameters" button becomes "Session Variables" — now editable
- Shows all intake form fields with filled/unfilled status
- Unfilled required fields highlighted
- Editing a field here updates the session and re-resolves all visible steps

### API Changes

| Method | Endpoint | Description |
|--------|----------|-------------|
| `PATCH` | `/sessions/{id}/variables` | Update one or more session variables (partial dict merge) |
| `POST` | `/sessions` | Remove required-field validation for intake forms (allow empty start) |
| `GET` | `/sessions` | Add `assigned_to_id` and `status=prepared` filter params |
| `POST` | `/sessions/prepare` | New endpoint: create a prepared session with variables + optional assignee |

### UI Changes

| Location | Change |
|----------|--------|
| **Flow detail page** | "Start Flow" no longer shows intake modal. Add "Prepare Session" option (dropdown or secondary button) |
| **ProceduralNavigationPage** | Remove `IntakeFormModal` gating. Add "Session Variables" panel button. Inline prompts on steps with unfilled variables |
| **StepDetail** | Render inline input prompts for unresolved `[VAR:x]` references |
| **Quick Start page** | New "Prepared for You" section showing assigned prepared sessions |
| **Session History** | New "Prepared" tab/filter showing prepared sessions |
| **Prepare Session form** | New modal/page: select flow, fill variables, assign engineer, save |
| **Session completion** | Soft warning if required variables still empty |

### What Gets Removed

- `IntakeFormModal.tsx` — no longer used as a blocking gate (may repurpose as the "Prepare Session" form)
- Required-field validation in `POST /sessions` for intake form fields
- The `showIntakeForm` / intake modal state in `ProceduralNavigationPage`

---

## Implementation Phases

### Phase 1: Mutable Variables + Inline Prompts
**Files:** `sessions.py`, `variableResolver.ts`, `StepDetail.tsx`, `ProceduralNavigationPage.tsx`
1. Add `PATCH /sessions/{id}/variables` endpoint
2. Remove intake form required-field blocking from `POST /sessions`
3. Update `resolveVariables()` to identify unresolved variables
4. Build inline variable prompt component for `StepDetail`
5. Make "View Parameters" panel editable
6. Remove `IntakeFormModal` gating from `ProceduralNavigationPage`

### Phase 2: Prepared Sessions
**Files:** `sessions.py`, `session.py` (schemas), migration, `PrepareSessionModal.tsx`, `QuickStartPage.tsx`, `SessionHistoryPage.tsx`
1. Migration: add `prepared_by_id`, `assigned_to_id` to sessions table
2. `POST /sessions/prepare` endpoint
3. `GET /sessions` filter support for `assigned_to_id` and prepared status
4. Prepare Session modal/form (reuse IntakeFormModal field rendering)
5. "Prepared for You" section on Quick Start
6. "Prepared" filter on Session History

### Phase 3: Polish
1. Soft completion warning for unfilled required variables
2. Prepared session staleness indicator (optional)
3. Notification when a session is prepared/assigned to you (optional, future)

---

## Verification

- Start a procedural flow without filling any variables → flow starts immediately, no modal
- Navigate to a step with `[VAR:server_name]` → see inline input prompt
- Fill the variable inline → value resolves across all steps
- Open Session Variables panel → see all fields, edit one → reflected in steps
- Prepare a session from flow detail page → assign to another engineer
- Log in as assigned engineer → see prepared session in Quick Start queue
- Click prepared session → flow opens with variables pre-filled, execute normally
- Complete a session with one unfilled required variable → see soft warning
- Export session → variables resolved in output, unfilled ones show as `[VAR:x]` or blank