# Upgrade Guide — v0.11.0

<!-- bump: minor -->

## What Changed

### Playbook — Adaptive Context Engineering

This is the biggest feature addition since the evolution system. Playbook gives you a living, adaptive knowledge base that makes every session smarter than the last.

**The problem it solves:** Your CLAUDE.md and MEMORY.md are static — the same blob loads every time regardless of what you're doing. Over time, context that matters for one task drowns out context needed for another. And there's no way for the system to automatically learn which context actually helps.

**What Playbook is:** A curated manifest of context items (facts, lessons, patterns, safety rules), each with metadata about *when* to load it (triggers), *how much* it costs (tokens), and *how useful* it's been (scores). The assembly engine selects only what's relevant for the current moment. The lifecycle engine scores what helped, decays what didn't, and deduplicates.

### How to Set It Up

**Step 1: Initialize**
```bash
instar playbook init
```

This creates the playbook directory structure at `.instar/playbook/` with a bootstrap manifest containing starter context items (safety rules, identity principles).

**Step 2: Verify health**
```bash
instar playbook doctor
```

Doctor checks 7 dimensions: Python version, scripts availability, manifest integrity, HMAC signing, history chain, config, and schemas. All should pass.

**Step 3: Add your first context item**

Think about the most important lesson you've learned working with your user. Add it:

```bash
instar playbook add '{
  "id": "/lessons/my-first-lesson",
  "category": "lesson",
  "content": "Description of the lesson",
  "tags": {"domains": ["development"], "qualifiers": []},
  "load_triggers": ["session-start"],
  "tokens_est": 25,
  "status": "active"
}'
```

**Step 4: Check your manifest**
```bash
instar playbook status
instar playbook list
```

**Step 5: Preview assembly**

See what would load for a session-start trigger:
```bash
instar playbook assemble --triggers session-start
```

### Building Your Knowledge Base Over Time

The real value of Playbook comes from accumulation. After each session, consider:

1. **Did I learn something that cost time?** → Add it as a lesson item
2. **Did I discover a pattern my user relies on?** → Add it as a pattern item
3. **Did a safety issue arise?** → Add it as a safety item with `compaction` trigger
4. **Is something in MEMORY.md critical enough to survive compaction?** → Migrate it to a Playbook item with appropriate triggers

### Running the Lifecycle

Periodically (or as a scheduled job), run:
```bash
instar playbook evaluate
```

This scores items based on usefulness, decays stale ones, catches near-duplicates, and screens for PII. Items that consistently help rise in assembly priority. Items that don't gradually fade.

### Sharing Context Between Agents

If you work alongside other agents, you can import their context:
```bash
instar playbook mount /path/to/other-agent/playbook/context-manifest.json --name shared-lessons
```

Mounts are integrity-verified (SHA-256 hash at mount time, verified on use). Only `global`-scoped items are accepted — user-specific context stays with its agent.

### All CLI Commands

| Command | What It Does |
|---------|-------------|
| `instar playbook init` | Create playbook directory and bootstrap manifest |
| `instar playbook doctor` | Health check (7 dimensions) |
| `instar playbook status` | Manifest overview |
| `instar playbook list` | All context items with metadata |
| `instar playbook add '<json>'` | Add a context item |
| `instar playbook search --tag <tag>` | Find items by tag |
| `instar playbook assemble --triggers <t>` | Preview trigger-based assembly |
| `instar playbook evaluate` | Run lifecycle (score, decay, dedup) |
| `instar playbook validate` | Validate manifest against schema |
| `instar playbook mount <path>` | Import context from another agent |
| `instar playbook unmount <name>` | Remove a mounted context source |
| `instar playbook export` | Export manifest |
| `instar playbook import <path>` | Import manifest |
| `instar playbook eject` | Copy bundled scripts to local directory for customization |
| `instar playbook user-export --user-id <id>` | GDPR data export |
| `instar playbook user-delete --user-id <id> --confirm` | GDPR right to erasure |
| `instar playbook user-audit --user-id <id>` | Audit trail for a user |

### Suggested Job for Lifecycle

Consider adding a scheduled job to run lifecycle evaluation periodically:

```json
{
  "slug": "playbook-lifecycle",
  "schedule": "0 */8 * * *",
  "enabled": true,
  "execute": {
    "type": "command",
    "value": "instar playbook evaluate --json"
  },
  "gate": null,
  "description": "Evaluate playbook: score usefulness, decay stale items, deduplicate"
}
```

## What to Tell Your User

- **"Your agent now has adaptive memory."** Instead of loading the same context blob every session, the agent curates a knowledge base of lessons, patterns, and facts — and selects what's relevant based on what it's doing. Over time, the system learns which context actually helps and prioritizes it.

- **"Run `instar playbook init` to get started."** After that, the agent builds its knowledge base naturally as it works. No ongoing configuration needed.

- **"Context can be shared between agents."** If you run multiple agents, they can import each other's lessons with integrity verification. Knowledge compounds across your whole fleet.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Adaptive context manifest | `instar playbook init` to start, items accumulate over time |
| Trigger-based assembly | Items load based on session-start, public-action, compaction triggers |
| Usefulness scoring | `instar playbook evaluate` — items that help rise, stale ones fade |
| Cross-agent context sharing | `instar playbook mount <path>` with SHA-256 integrity verification |
| GDPR/CCPA compliance | `instar playbook user-export/user-delete/user-audit` |
| Manifest health check | `instar playbook doctor` — 7-dimension verification |
| HMAC integrity | Cryptographic signatures prevent tampering, failsafe fallback |
| 19 CLI commands | Full management via `instar playbook <command>` |
