# Upgrade Guide — v0.22.0

<!-- bump: minor -->
<!-- Valid values: patch, minor, major -->
<!-- patch = bug fixes, refactors, test additions, doc updates -->
<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
<!-- major = breaking changes to existing APIs or behavior -->

## What Changed

### Seed CLAUDE.md — Lightweight Agent Bootstrapping

Agents can now boot from a **234-line seed CLAUDE.md** instead of a monolithic 800+ line file. The seed contains only identity anchoring, capability awareness, and lookup instructions. Detailed capability documentation is served **on demand** by the self-knowledge tree.

**Why this matters**: A monolithic CLAUDE.md burns context window on every session — hundreds of lines about capabilities the agent may never use in that session. The seed approach loads only what's relevant, when it's relevant. This means:

- **More room for actual work** — 600+ fewer lines at boot frees context for the task at hand
- **Better after compaction** — when Claude compresses context, less identity to re-inject means faster recovery
- **Maintainability** — capability docs live in individual files, not a single 900-line document. Update one capability without touching everything else.
- **Smarter loading** — the self-knowledge tree uses LLM-scored triage to select only the 1-3 nodes relevant to your query, not a keyword-matched dump of everything

**New agents** created with `instar init` automatically get the seed CLAUDE.md. **Existing agents** keep their current CLAUDE.md — no forced migration. You can migrate when ready.

### How to Migrate an Existing Agent to the Seed

If you're running a monolithic CLAUDE.md and want the benefits of the seed approach:

**Step 1: Understand what moves where.**

Your monolithic CLAUDE.md likely contains these categories of content:

| Content Type | Where It Goes in the Seed Architecture |
|-------------|---------------------------------------|
| Identity (who am I, name, values) | Stays in CLAUDE.md (identity anchoring) |
| Capability Index (one-line descriptions) | Stays in CLAUDE.md (awareness table) |
| Detailed capability docs (API endpoints, usage examples) | Moves to self-knowledge tree context files |
| Anti-patterns, principles, tone guidelines | Loaded via session-start hooks (behavioral layer) |
| Lookup tables (when X → do Y) | Stays in CLAUDE.md (quick reference) |
| Compaction recovery instructions | Stays in CLAUDE.md (survival essentials) |

**Step 2: Create context files for your capabilities.**

For each detailed capability section in your CLAUDE.md, create a context file:

```
.instar/context/capabilities/telegram.md    — Telegram API docs
.instar/context/capabilities/publishing.md  — Telegraph + private viewer
.instar/context/capabilities/jobs.md        — Job scheduler details
... etc
```

These files are what the self-knowledge tree serves when an agent asks a relevant question.

**Step 3: Update your tree config.**

Add nodes to `.instar/state/self-knowledge-tree.json` pointing to your new context files. Each node needs an ID, name, description, and source path. The triage system uses the description to score relevance.

**Step 4: Slim down CLAUDE.md.**

Remove the detailed capability sections, keeping only:
- Identity files section (AGENT.md, USER.md, MEMORY.md references)
- Capability Index (one-line table for awareness)
- Quick Lookup Table
- Compaction recovery seed
- Critical anti-patterns (the top 5-7, not all of them)

**Step 5: Preserve your monolith.**

Copy your current CLAUDE.md to `CLAUDE.monolith.md` before switching. This is your instant rollback — if anything breaks, rename it back.

**Step 6: Verify.**

Query the self-knowledge tree to confirm your context files are reachable:

```bash
curl -H "Authorization: Bearer $AUTH" "http://localhost:4042/self-knowledge/search?q=telegram"
```

You should see only the telegram-related node(s), not everything.

### Self-Knowledge Tree — LLM-Primary Triage

The self-knowledge tree now uses **LLM intelligence as the primary scoring path** for both layer and node triage. Rule-based keyword matching is the emergency fallback only when the LLM is unavailable.

Previously, node scoring had two bugs:
- Layers with ≤3 nodes skipped LLM scoring entirely, giving all nodes a uniform 0.8
- When LLM returned unparseable JSON, all nodes got 0.5 (everything passed the threshold)

Both are fixed. Queries now return discriminated scores — a search for "telegram topic create" returns the telegram node scored high and unrelated nodes scored low, instead of everything at the same level.

### HMAC Integrity Verification

Context files served by the self-knowledge tree can now be **HMAC-SHA256 signed**. When a signing key is configured, the tree verifies file integrity before serving content — if a file has been tampered with, it's rejected (fail-closed).

This is **opt-in** — unsigned files are served normally. To enable:
1. A signing key is auto-generated at init (separate from auth token, doesn't rotate)
2. Sign files: the IntegrityManager signs all context files and writes a manifest to `.integrity.json`
3. TreeTraversal verifies HMAC before serving signed content

## What to Tell Your User

- **Faster, smarter sessions**: Your agent now loads only the capability docs it needs for each conversation, instead of dumping everything at startup. This means more context window for your actual work.
- **Same agent, better infrastructure**: Your existing setup keeps working exactly as before. The improvements are under the hood — better search accuracy when you ask about capabilities, and integrity protection for context files.
- **Optional migration**: If you want the full benefits, your agent can walk you through migrating to the seed CLAUDE.md. It's reversible — the original is preserved as a backup.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Seed CLAUDE.md (new agents) | Automatic at `instar init` |
| Seed migration (existing agents) | Follow migration steps above, or let your agent guide you |
| LLM-primary triage | Automatic — self-knowledge queries are now more accurate |
| HMAC integrity | Opt-in — auto-configured at init, can be enabled for existing agents |
| telegram-reply.sh port fix | Agent-side — reads port from config.json instead of hardcoding 4040 |
