openspec/changes/archive/2026-06-23-inline-document-attachment/specs/inline-document-attachment.md

## Capability: inline-document-attachment

File attachment moved inline into the Chat tab via `gr.MultimodalTextbox`. Documents tab removed. How To Guide updated to 4-step flow.

---

### Scenario 1: Chat input accepts text with no attachment

**Given** the user is on the Chat tab  
**When** they type a complaint message and submit without attaching a file  
**Then** the message is sent to the agent exactly as before  
**And** the agent responds normally  
**And** no upload call is made

---

### Scenario 2: Chat input accepts a file attachment with text

**Given** the user is on the Chat tab  
**When** they type a message and attach a supported file (PDF, PNG, JPG, JPEG, WEBP)  
**And** submit  
**Then** the file is uploaded via `POST /session/{id}/upload` first  
**And** then the message is sent via `POST /session/{id}/message`  
**And** the agent sees `[Document uploaded: <path>]` prepended and calls `process_document` in the same turn  
**And** the agent's response references the extracted document entities

---

### Scenario 3: File attachment without text is allowed

**Given** the user attaches a file but types no message  
**When** they submit  
**Then** the upload is called with the file  
**And** the message is sent with empty text (agent sees only `[Document uploaded: <path>]`)  
**And** the agent responds about the document content

---

### Scenario 4: Submitting with neither text nor file is a no-op

**Given** the user submits the chat input with no text and no file  
**When** the handler runs  
**Then** no API call is made  
**And** the chat history is unchanged

---

### Scenario 5: Upload failure surfaces in chat and blocks message send

**Given** the user attaches a file and types a message  
**When** the `/upload` call fails (network error or unsupported format)  
**Then** an error message is appended to chat history  
**And** the `/message` call is NOT made  
**And** the user can retry by attaching the file again

**Example error message in chat:**
> ⚠️ Could not process the document: [error detail]. Please try again or describe the details manually.

---

### Scenario 6: Only supported file types are accepted in the attachment picker

**Given** the user tries to attach a file  
**When** the file picker opens  
**Then** only `.pdf`, `.png`, `.jpg`, `.jpeg`, `.webp` files are selectable  
**And** other file types are filtered out by the component

---

### Scenario 7: Documents tab is removed

**Given** the app loads  
**When** the user looks at the tab bar  
**Then** there is no `📎 Documents` tab  
**And** the tab order is: 📖 How To Guide · 💬 Chat · ✅ Verify Entities · 📄 Complaint Draft · 🏛️ Escalation Guide · ℹ️ About

---

### Scenario 8: How To Guide reflects 4-step flow

**Given** the user is on the How To Guide tab  
**When** they read the step-by-step flow  
**Then** the flow shows exactly 4 steps (not 5)  
**And** Step 1 describes Chat with optional document attachment  
**And** there is no separate Documents step  
**And** the feature table has no Documents row

**Updated step flow:**

| Step | Tab | What you do |
|------|-----|-------------|
| 1️⃣ | 💬 **Chat** | Describe your complaint and optionally attach a receipt, bill, or screenshot |
| 2️⃣ | ✅ **Verify Entities** | Review and confirm the key details extracted |
| 3️⃣ | 📄 **Complaint Draft** | Read, copy, or download your ready-to-send letter |
| 4️⃣ | 🏛️ **Escalation Guide** | Find the right regulatory authority with portal links |

**Updated feature table** (Documents row removed, Chat row updated):

| Tab | What it does |
|-----|-------------|
| 💬 **Chat** | Describe your complaint in plain language and optionally attach a receipt, bill, or screenshot. G.U.I.D.E. asks follow-up questions and reads any attached document automatically. |
| ✅ **Verify Entities** | Review and correct the key details G.U.I.D.E. extracted. Click Confirm & Generate Draft to create your letter. |
| 📄 **Complaint Draft** | Your ready-to-send formal complaint letter. Copy or download as a text file. |
| 🏛️ **Escalation Guide** | Find the right authority — NCH, TRAI, RBI, IRDAI — with direct portal links. |

---

### Scenario 9: Privacy badge still shows when PII is redacted

**Given** the user sends a message containing PII  
**When** the agent responds  
**Then** the 🔒 privacy badge appears below the chatbot as before  
**And** the badge behaviour is unchanged by the input component swap