# Export Improvements Phase B — Design

> **Date:** 2026-02-13
> **Depends on:** Phase A (complete on `feat/export-phase-a`)
> **Scope:** B1 (Summary Block), B2 (Custom Step Markers), B3 (Detail Levels), B4 (Editable Preview)

---

## Decisions Made

| Question | Decision |
|----------|----------|
| B1 summary form vs single editable preview | Single editable preview (B4). No separate structured form for summary fields. |
| Detail levels | standard/full only. Dropped "summary" level — primary users are engineers, not dispatchers. |
| Mid-session editable preview | No. TreeNavigationPage keeps quick one-click copy. Editable preview is SessionDetailPage only. |

---

## 1. Schema Changes

Add to `SessionExport` (backend + frontend):

```python
include_summary: bool = False
detail_level: Literal["standard", "full"] = "standard"
```

No database migration needed — these are export-time options only.

---

## 2. Custom Step Differentiation (B2)

Detect custom steps by checking `node_id.startswith("custom-")` in each decision dict.

**Markdown:**
```markdown
### Step 5: [CUSTOM] Check Additional Event Logs
*Custom step added by engineer*
```

**Text:**
```
5. [CUSTOM] Check Additional Event Logs
```

**HTML:**
```html
<span style="background: #7c3aed; color: white; padding: 2px 6px; border-radius: 3px; font-size: 0.75em; margin-right: 6px;">CUSTOM</span>
```

**PSA:**
```
5. [CUSTOM] Check Additional Event Logs -> ...
```

Pure backend change — all 4 generators in `export_service.py`.

---

## 3. Summary Block (B1)

When `include_summary=True`, insert a Summary section after metadata, before Evidence/Steps.

Auto-populated fields:

| Field | Source |
|-------|--------|
| Issue | Tree name + description |
| Impact | `[Edit in preview]` placeholder |
| Status | "Resolved" if completed, else "In Progress — paused at step N" |
| Resolution | `outcome_notes` if available |
| Next Steps | `next_steps` if available |

Blank/placeholder fields are editable in the preview modal (B4). Format varies by generator (markdown table, text key-value, HTML styled table, PSA `--- SUMMARY ---` section).

The summary block is opt-in (`include_summary=False` default), independent of detail level.

---

## 4. Detail Levels (B3)

Two levels:

- **standard** (default): Current behavior, except command outputs >5 lines are truncated with `*(full output omitted — N lines)*`
- **full**: No truncation. All command outputs, scratchpad, notes rendered completely.

Implementation: Helper function `_truncate_command_output(output, max_lines=5)` used in all 4 generators when `detail_level="standard"`.

Frontend: Dropdown on SessionDetailPage export controls — "Standard" / "Full Detail".

---

## 5. Editable Preview (B4)

Modify `ExportPreviewModal`:

- Replace read-only `<pre>` with editable `<textarea>`
- Local state `editedContent` initialized from `content` prop
- "Copy" copies `editedContent`
- "Download" downloads `editedContent`
- "Reset" button restores original content
- "Include Summary" checkbox re-fetches export with `include_summary=true`
- Edits are NOT saved back to the session

Only applies to SessionDetailPage. TreeNavigationPage keeps instant "Copy for Ticket" behavior.

---

## Files Affected

**Backend:**
- `backend/app/schemas/session.py` — Add `include_summary`, `detail_level` to `SessionExport`
- `backend/app/services/export_service.py` — All 4 generators: custom step markers, summary block, command output truncation

**Frontend:**
- `frontend/src/types/session.ts` — Add `include_summary`, `detail_level` to `SessionExport`
- `frontend/src/components/session/ExportPreviewModal.tsx` — Editable textarea, reset, summary toggle
- `frontend/src/pages/SessionDetailPage.tsx` — Detail level dropdown, pass new options to export calls

**No migration needed.**