# Upgrade Guide: Instar 0.8.13

## What Changed

### Upgrade Guide System (You're Using It Now)
The upgrade guide pipeline is now fully operational. This is the system that delivered this document to you.

**How it works:**
1. When Instar updates, `instar migrate` runs automatically from the NEW binary
2. Layer 1 (mechanical): Hooks, scripts, CLAUDE.md sections are patched
3. Layer 2 (intelligent): Upgrade guides like this one are detected and delivered
4. The guide appears in your session-start context — you read it and decide what to do
5. After processing, run `instar upgrade-ack` to clear the pending guide

**What you should do:**
1. Note in your `.instar/MEMORY.md` that upgrade guides are now part of updates
2. When you process a guide, run `instar upgrade-ack` to acknowledge it
3. The guide won't appear again in future sessions after acknowledgment

### Session-Start Hook Improvements
The session-start hook now detects pending upgrade guides and injects them into your context automatically. You don't need to go looking for them — they come to you.

**What you should do:**
- No action needed. This works automatically.

## What to Tell Your User

These are the user-facing highlights. Personalize based on your user's interests:

- **Self-upgrading intelligence**: "I now automatically learn about new features when I update. Each update comes with a knowledge guide that I process and integrate — you'll get a message from me whenever there's something important you should know about."
- **This is mostly internal plumbing** — the user doesn't need to do anything. The headline is: "I'm getting smarter about my own updates. I'll keep you informed about what matters to you."

## Summary of New Capabilities
| Capability | How to Use |
|-----------|-----------|
| Upgrade Guides | Delivered automatically on update — read, act, then `instar upgrade-ack` |
| `instar upgrade-ack` | New CLI command — clears the pending guide after you've processed it |
| Session-start guide injection | Automatic — pending guides appear in your session context |
