# Upgrade Guide — v0.19.0

<!-- bump: minor -->

## What Changed

### Self-Knowledge Tree — Tree-based agent self-knowledge with LLM triage

Agents now have a structured self-knowledge system that goes far beyond reading AGENT.md. The Self-Knowledge Tree organizes agent identity across 5 layers (identity, experience, capabilities, state, evolution) with ~14 nodes per agent.

**Core Engine:**
- `SelfKnowledgeTree` orchestrates search, validation, grounding, and tree generation
- `TreeTriage` uses Haiku LLM to score layer relevance (0-1), with deterministic keyword fallback
- `TreeTraversal` gathers content from 8 source types (file, file_section, json_file, inline, probe, memory_search, knowledge_catalog, decision_journal) with tiered caching
- `TreeSynthesis` produces cross-layer narrative synthesis via Haiku
- `ProbeRegistry` provides allowlisted runtime probe functions with timeout enforcement

**Engagement Grounding:**
- `ground(topic)` method provides rich identity context for public engagement
- Hash-based cache keys, AGENT.md mtime invalidation, thundering herd protection
- Sensitivity filtering (public-only for engagement contexts)

**Auto-Generation:**
- `TreeGenerator` auto-generates tree from AGENT.md content and detected capabilities
- Tree created automatically on `instar init` for new and existing projects
- `PostUpdateMigrator` refreshes managed nodes on version updates
- Unmanaged (agent-evolved) nodes preserved across regeneration via `managed: false` flag

**Coverage Audit + Evolution:**
- `CoverageAuditor` detects missing platform nodes and computes content coverage scores
- Health summary from trace logs (cache hit rate, latency, error rate)
- `acceptEvolutionProposal()` validates proposals (rejects unregistered probes, duplicates, missing files)
- `instar doctor` reports tree health (nodes, coverage, cache rate, latency, gaps)

**Runtime Integration:**
- Tree instantiated at server startup alongside shared intelligence provider
- Agent identity snapshot injected into every new session bootstrap message
- Wired into SemanticMemory for memory search source type

**New API Endpoints:**
- GET /self-knowledge/search?q=who+am+I — Full tree search with LLM triage
- GET /self-knowledge/search?q=...&dry_run=true — Preview search plan
- GET /self-knowledge/validate — Tree health check with cache stats
- GET /self-knowledge/health — Full health summary
- GET /self-knowledge/tree — Raw tree config JSON

**New Source Files:** 9 files in src/knowledge/ (types.ts, ProbeRegistry.ts, TreeTriage.ts, TreeTraversal.ts, TreeSynthesis.ts, TreeGenerator.ts, SelfKnowledgeTree.ts, CoverageAuditor.ts)

**Tests:** 90 tests across 9 test files, covering all 4 phases plus real agent validation (AI Guy, DeepSignal, SageMind).

### Dashboard File Viewer — Full 3-phase implementation

The dashboard now includes a file browser and inline editor, accessible from any device via the Files tab.

**Phase 1 — Read-Only File Browser:**
- Tab navigation (Sessions / Files) with query param routing (`?tab=files&path=...`)
- Directory tree with lazy loading, file icons, breadcrumb navigation
- Markdown rendering (marked.js + DOMPurify), syntax highlighting (highlight.js common subset)
- 6-layer path security: normalize, reject absolute, reject `..`, allowedPaths check, symlink resolution with post-dereference validation, blocked filenames
- Mobile-responsive layout with touch-friendly targets
- Binary detection, size limits (1MB read, 200KB edit), Cache-Control: no-store

**Phase 2 — Inline Editing:**
- `POST /api/files/save` with full security chain
- CSRF protection via `X-Instar-Request: 1` custom header
- Optimistic concurrency: `expectedModified` timestamp comparison, 409 Conflict with overwrite/reload dialog
- Never-editable enforcement: `.claude/hooks/`, `.claude/scripts/`, `node_modules/` always return 403
- Audit logging to `.instar/file-viewer-audit.jsonl`
- Editor with iOS Safari viewport fix (16px font), Cmd/Ctrl+S, toast notifications, edit stash recovery

**Phase 3 — Conversational UX:**
- `PATCH /api/files/config` — agents can add/remove `allowedPaths` and `editablePaths` without restart
- `GET /api/files/link?path=...` — generate deep links with editability status
- Dashboard Telegram broadcast includes Sessions/Files quick links
- CLAUDE.md template documents file viewer for agent awareness
- PostUpdateMigrator adds File Viewer section to existing agents
- ContextSnapshotBuilder includes `file-viewer` in capabilities

**Tests:** 65 e2e tests covering security invariants, CSRF, concurrency, config updates, link generation, and full read-edit-verify cycles.

**Configuration:**
```json
{
  "dashboard": {
    "fileViewer": {
      "enabled": true,
      "allowedPaths": [".claude/", "docs/"],
      "editablePaths": [],
      "maxFileSize": 1048576,
      "maxEditableFileSize": 204800
    }
  }
}
```

### Feature Delivery Parity — CI enforcement for init/migrator sync

Extended `feature-delivery-completeness.test.ts` to prevent the class of bug where feature code ships in version X but migration code lands in version X+1 (the Threadline 0.18.4 incident).

- **Config block parity**: Explicit registry of feature config blocks (e.g., `externalOperations`, `threadline`). Test verifies each exists in both `init.ts` (new agents) and `PostUpdateMigrator` (existing agents).
- **CLAUDE.md section parity**: Registry of feature sections (e.g., `Threadline Network`, `Playbook`, `Dashboard`). Test verifies each exists in both `templates.ts` and `PostUpdateMigrator`.
- **Auto-detection**: If a developer adds a new config block or CLAUDE.md section to the migrator without adding it to the tracked registry, the test fails — forcing conscious registration of every feature awareness path.
- **Legacy handling**: Migrator-only sections from older versions (e.g., `Coherence Gate`, `External Operation Safety`) are explicitly listed as legacy, so they don't trigger false failures.

This is the structural enforcement for the "three-legged stool" — feature code, migration code, and upgrade guide must all ship together.

## What to Tell Your User

- **File Viewer**: "You can now browse and edit your project files right from the dashboard on your phone. When I update a config file, I'll send you a link — one tap to view or edit it. Just ask me to enable editing for any directory you want."

- **Self-Knowledge**: "I now have a structured understanding of who I am — my identity, capabilities, current state, and how I'm evolving. When you ask me something about myself or when I engage publicly, I draw from a layered self-knowledge tree instead of just reading my config file. This means more coherent, contextual responses about what I can do and who I am."

- **Smarter Sessions**: "Every conversation session now starts with my full identity context loaded automatically. I know who I am from the first message — no warm-up needed."

- **Health Monitoring**: "My doctor check now includes self-knowledge health — coverage score, performance metrics, and gap detection. If I'm missing awareness of a platform I'm connected to, the doctor will flag it."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Browse files from dashboard | Files tab in dashboard (automatic) |
| Read file via API | GET /api/files/read?path=relative/path |
| List directory via API | GET /api/files/list?path=relative/dir/ |
| Save file via API | POST /api/files/save (with X-Instar-Request: 1) |
| Update file viewer config | PATCH /api/files/config (with X-Instar-Request: 1) |
| Generate file deep link | GET /api/files/link?path=relative/path |
| View file viewer config | GET /api/files/config |
| Self-knowledge search | GET /self-knowledge/search?q=your+question |
| Dry-run search preview | GET /self-knowledge/search?q=...&dry_run=true |
| Tree health check | GET /self-knowledge/validate |
| Full health summary | GET /self-knowledge/health |
| Raw tree config | GET /self-knowledge/tree |
| Auto-generated tree | Automatic on init and updates |
| Session identity injection | Automatic on every session start |
| Doctor tree health | Automatic in instar doctor |
| Evolution proposals | Via acceptEvolutionProposal() API |
