# Upgrade Guide — v0.20.0

<!-- bump: minor -->

## What Changed

### Drop Zone — Dashboard Paste Input

A new "Drop Zone" tab in the dashboard lets users send large text content (code, logs, configs, specs) directly to an active agent session, bypassing Telegram's 4096-character limit.

**How it works:**
1. Open the dashboard (local or via tunnel)
2. Click the "Drop Zone" tab
3. Paste content, optionally add a label, pick a target session
4. Hit Send — content is delivered to the session as a file-reference notification

**Key design decisions:**
- **File-based delivery**: Content is written to `.instar/paste/` and the session receives a short notification pointing to the file. Content is never inlined in the notification (isolation boundary).
- **Prompt injection defense**: Notifications include explicit framing telling the agent to treat paste content as data, not instructions. Routed through InputGuard.
- **Three delivery states**: `written` → `notified` → `acknowledged`, with WebSocket events for real-time dashboard updates.
- **Security hardened**: UUID-only filenames (no label in paths), 0600 permissions, rate limiting (10/min), 10MB per-paste cap, 500MB directory cap, programmatic gitignore enforcement.

**API endpoints:**
- `POST /pastes` — Create a paste
- `GET /pastes` — List pastes (metadata only)
- `GET /pastes/:id` — Get paste with content
- `DELETE /pastes/:id` — Delete a paste

**Configuration (optional, in config.json):**
- `pasteMaxSizeMB` — Max paste size in MB (default: 10)
- `pasteRetentionDays` — Days to keep paste files (default: 7)

### Telegram Truncation Detection

Server-side middleware in the Telegram message ingestion path detects when a user's message appears truncated:
- Messages near the 4096-char limit ending mid-word or with unclosed delimiters
- Rapid multi-part messages from the same user (manual splitting)
- Structurally incomplete code/log content

When detected, the agent receives a system hint suggesting the Drop Zone. One nudge per topic per 30 minutes to avoid nagging.

## What to Tell Your User

Your dashboard has a new tab called "Drop Zone" — it's for sending long content (code, logs, error outputs, configs) that won't fit in a Telegram message. Just paste it and hit send. If your agent notices you're fighting Telegram's character limit, it'll suggest using the Drop Zone automatically.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Drop Zone paste input | Dashboard → Drop Zone tab. Paste content, hit Send. |
| Paste API | `POST /pastes` with `{content, label?, targetSession?}` |
| Paste history | Dashboard shows recent pastes with delivery status |
| Truncation detection | Automatic — agent suggests Drop Zone when Telegram messages look truncated |
| Paste cleanup | Automatic — files expire after 7 days (configurable) |
