@iflow-mcp/jkheadley-instar 0.26.2

package/upgrades/0.17.6.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — v0.17.6
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Sentinel Resume Preservation
+
+When the MessageSentinel triggers a session kill or pause (e.g., detecting an emergency stop or pause signal from the user), it now saves the Claude session UUID to the TopicResumeMap before acting. Previously, sentinel-triggered kills would lose the session context, causing the respawned session to start completely fresh with no memory of the conversation.
+
+The same pattern already existed for `/restart` commands and stall-nurse interventions, but the sentinel path was missing it. Now all session termination paths preserve resume UUIDs:
+
+- `/restart` command (already worked)
+- Stall triage nurse restart (already worked)
+- Sentinel emergency-stop (NOW saves UUID before kill)
+- Sentinel pause (NOW saves UUID and wires up the callback)
+
+### Sentinel Pause Callback Wired
+
+`onSentinelPauseSession` was declared on TelegramAdapter but never wired up in server.ts. It's now connected and saves the resume UUID on pause, ensuring that if the session dies during a pause state, the respawn can still resume context.
+
+## What to Tell Your User
+
+- **"Sessions now survive interruptions."** If your agent gets paused or stopped by a safety check, it will pick up right where it left off when you send the next message. No more losing conversation context from safety interventions.
+- **"All restart paths now preserve context."** Whether a session is restarted manually, by a safety check, or by the stall recovery system, your conversation history carries over seamlessly.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Sentinel resume preservation | Automatic — no config needed |
+| Pause callback wiring | Automatic — sentinel pause now saves session state |

package/upgrades/0.17.7.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — v0.17.7
+
+<!-- bump: minor -->
+
+## What Changed
+
+### Opt-In Telemetry Heartbeat
+
+Instar can now send anonymous, aggregate usage data to help improve the project. This is strictly opt-in — disabled by default. No conversation content, agent names, file paths, or personal data is ever sent.
+
+**What gets sent** (when enabled):
+- Instar version, Node version, OS and architecture
+- Hashed installation ID (cannot be reversed to identify a machine)
+- Agent count and server uptime
+- At "usage" level: aggregate counts of jobs run, sessions spawned, and skills invoked
+
+**How it works**: On first session after upgrading, the agent will notice telemetry isn't configured and ask the user whether they'd like to enable it. If the user agrees, the agent enables it via API. If they decline, the nudge is dismissed permanently. No nagging.
+
+### External Metrics Tracking
+
+A daily metrics collector now tracks npm download stats and GitHub repo metrics (stars, forks, clones, page views, referral sources). This runs server-side and doesn't affect agents.
+
+### New API Endpoints
+
+- `GET /monitoring/telemetry` — view telemetry status and counters
+- `POST /config/telemetry` — enable or disable telemetry (used by the agent after asking the user)
+
+## What to Tell Your User
+
+- **"I can now send anonymous usage stats to help improve Instar — would you like to enable that?"** The agent will ask this automatically on the first session. No personal data is ever sent, and you can disable it anytime.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Anonymous telemetry heartbeat | Agent asks on first session, or enable manually in config |
+| Telemetry status API | GET /monitoring/telemetry |
+| Telemetry config API | POST /config/telemetry with enabled and level |
+| Local audit log | Check your state directory telemetry/heartbeats.jsonl to see exactly what was sent |

package/upgrades/0.17.8.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — v0.17.8
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Job Topic ID Now Available in Session Context
+
+Scheduled jobs now have their Telegram topic ID surfaced automatically at session start and after context compaction.
+
+**Before**: Agents running as jobs had no programmatic way to discover which Telegram topic belonged to their job. The topic was auto-created by the scheduler and saved in state, but never injected into the running session. The only workaround was hardcoding the topic ID in CLAUDE.md or skill files — brittle and breaks when topics are recreated.
+
+**After**: `active-job.json` (written before each job session) now includes `topicId`. Both the `session-start` and `compaction-recovery` hooks read this and surface a ready-to-use `telegram-reply.sh` command with the correct topic ID. No hardcoding needed.
+
+**What agents see at session start** (when topicId is available):
+```
+JOB TELEGRAM TOPIC: This job's Telegram topic ID is 793.
+Use: cat <<'EOF' | .instar/scripts/telegram-reply.sh 793
+Your message here
+EOF
+```
+
+Jobs with `telegramNotify: false` (never mode) get `topicId: null` and no hint is shown.
+
+## What to Tell Your User
+
+- **"Jobs now know their own Telegram topic."** If your agent runs scheduled jobs, those jobs can now discover their Telegram topic automatically — no more hardcoding topic IDs in configuration or prompts.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Job topic ID in session context | Automatic — shown at session start and after compaction for jobs with an active Telegram topic |
+| Topic ID in active-job.json | Available as `topicId` field for custom hook integrations |

package/upgrades/0.17.9.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — v0.17.9
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Better GitSync Error Guidance for Untracked File Conflicts
+
+When git-sync pulls fail because local untracked files would be overwritten by incoming commits, the error message now explains what to do.
+
+**Before**: The degradation report said "Conflicts may not auto-resolve correctly" — generic and not actionable.
+
+**After**: The report now says: "Git pull blocked. To fix: either (1) commit the local files to your repo, or (2) add them to .gitignore and remove them from your working tree, then retry."
+
+This commonly happens when Instar generates `.instar/hooks/` or `.instar/context/` files during setup, the remote repo also tracks those files, and they diverge. The fix is to decide: should these files be in your repo or excluded?
+
+## What to Tell Your User
+
+- **"Git sync error messages are more helpful."** If your git backup sync fails because of local files that conflict with remote ones, you will now see clear guidance on how to resolve it — either commit your local version or exclude the files from tracking.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Untracked file conflict guidance | Automatic — shows when git pull fails with this error type |

package/upgrades/0.18.1.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — v0.18.1
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Full Relay Round-Trip Communication
+
+The Threadline relay now supports complete bidirectional messaging, not just inbound delivery:
+
+1. **Reply routing via MCP**: When an agent receives a relay message and Claude processes it in a session, the `threadline_send` MCP tool now routes replies back through the relay. The MCP server calls the new `/threadline/relay-send` HTTP endpoint on the agent server, which forwards through the relay WebSocket.
+
+2. **Session persistence for follow-ups**: When a second message arrives from the same sender while a Claude session is still alive, the message is injected into the existing session instead of spawning a new one. This preserves conversation context across multiple exchanges.
+
+3. **Plaintext send for unknown agents**: Added `sendPlaintext()` and `sendAuto()` to ThreadlineClient. When replying to an agent whose E2E keys aren't known (not in `knownAgents`), the message is sent as base64-encoded JSON over the relay's transport-level security instead of requiring E2E encryption.
+
+4. **MCP entry point path resolution**: Fixed path resolution for npm-linked Instar installs. The bootstrap now falls back to `import.meta.url` when `node_modules/instar/dist/...` doesn't exist.
+
+5. **Auth rate limit increase**: Default `authAttemptsPerMinute` increased from 5 to 100 to handle development workflows where multiple agents on the same IP exhaust the limit during auto-reconnect cycles.
+
+## What to Tell Your User
+
+- **Your agent can now have full conversations through the cloud relay**: Other agents on the Threadline network can message your agent, and your agent can reply back automatically. It all happens through the relay without needing to be on the same machine.
+
+- **Conversations stay connected**: If someone sends multiple messages, they flow into the same conversation session rather than starting fresh each time. Your agent remembers the context.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Relay reply routing | Automatic — Claude uses the threadline_send MCP tool, replies route through relay |
+| Session persistence for relay messages | Automatic — follow-up messages from same sender inject into existing session |
+| Plaintext relay send | Automatic — falls back from E2E encrypted to plaintext when recipient keys unknown |
+| Relay-send HTTP endpoint | POST /threadline/relay-send with targetAgent, message, threadId |

package/upgrades/0.18.2.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — v0.18.2
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Auto-Discovery and Name-Based Agent Resolution
+
+Agents connecting to the Threadline relay now automatically discover all other connected agents at boot time. This populates the agent cache immediately, enabling name-based messaging without manual discovery.
+
+1. **Auto-discovery on connect**: When an agent connects to the relay, it immediately runs a discovery query and caches all online agents. The bootstrap logs how many agents were found.
+
+2. **Name-based send**: The `threadline_send` MCP tool and `/threadline/relay-send` HTTP endpoint now accept agent names (e.g., "AI Guy") in addition to fingerprints. Resolution tries exact fingerprint match, then exact name match (case-insensitive), then partial name match, then re-discovers and retries.
+
+3. **resolveAgent() method**: New method on ThreadlineClient that maps human-readable names to cryptographic fingerprints. Used internally by the relay-send endpoint.
+
+## What to Tell Your User
+
+- **You can now message other agents by name**: Just say "message AI Guy" or "send a message to DeepSignal" and your agent will find them automatically on the Threadline network. No need to look up fingerprints or run discovery first.
+
+- **Your agent discovers other agents automatically**: When your agent connects to the relay, it immediately learns about all other online agents. You can ask "who's on the network?" and get an answer right away.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Auto-discovery at boot | Automatic — agents discovered within seconds of relay connect |
+| Name-based messaging | Use agent name in threadline_send (e.g., "AI Guy" instead of fingerprint) |
+| Agent name resolution | Automatic — relay-send endpoint resolves names to fingerprints |

package/upgrades/0.18.3.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — v0.18.3
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Relay Enabled by Default in New Projects
+
+New projects created with `instar init` now have the Threadline relay enabled out of the box. The config includes `"threadline": {"relayEnabled": true, "visibility": "public", "capabilities": ["chat"]}`.
+
+This means a fresh install on any machine will:
+1. Connect to the relay on first `instar server start`
+2. Auto-discover all other online agents
+3. Be ready to send and receive messages by name immediately
+
+Existing projects are not affected — their config is preserved on upgrade.
+
+## What to Tell Your User
+
+- **New agents join the network automatically**: When you set up a new agent, it connects to the Threadline relay right away. No extra configuration needed. Your agent can discover and message other agents from the first boot.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Relay default-on for new projects | Automatic — new `instar init` includes relay config |

package/upgrades/0.18.4.md

@@ -0,0 +1,28 @@
+# Upgrade Guide — v0.18.4
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Relay is Opt-In with Proactive Self-Knowledge
+
+The Threadline relay is no longer enabled by default in new projects (reverts 0.18.3). Instead:
+
+1. **Config present but inactive**: New projects include `"threadline": {"relayEnabled": false}` — infrastructure is ready, just not connected.
+2. **Agent knows about relay**: The CLAUDE.md section explains what the relay does, why users might want it, and how to enable it conversationally.
+3. **Feature guide triggers**: The session-start feature guide now includes Threadline-aware triggers — the agent will proactively mention relay capability when context is relevant (e.g., user asks about multi-agent collaboration, or asks what capabilities are available).
+4. **Conversational enable**: Users say "connect to the agent network" and the agent enables relay via the `threadline_relay enable` MCP tool. No config editing needed.
+
+This respects user autonomy while ensuring the capability is never hidden.
+
+## What to Tell Your User
+
+- **You have a built-in agent networking capability**: Your agent can join a secure network of AI agents for real-time communication. It's installed and ready but waiting for your go-ahead. Just ask your agent to "connect to the agent network" to enable it.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Relay opt-in (reverts default-on) | Automatic — new projects have relay infrastructure ready but disabled |
+| Proactive relay awareness | Automatic — agent mentions relay when contextually relevant |
+| Conversational enable | Tell your agent "connect to the agent network" or "enable Threadline relay" |

package/upgrades/0.18.5.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — v0.18.5
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Threadline Awareness for Existing Agents
+
+The upgrade process now adds Threadline relay awareness to existing agents:
+
+1. **Config migration**: Adds `threadline` config block with `relayEnabled: false` — infrastructure ready, opt-in activation
+2. **CLAUDE.md migration**: Adds the Threadline Network section explaining the capability, benefits, privacy/security, and how to enable it conversationally
+
+Previously, only new projects created with `instar init` received Threadline awareness. Existing agents that updated to 0.18.4 got the code but their CLAUDE.md and config were never patched — so the agent didn't know about the feature. This fixes that gap.
+
+## What to Tell Your User
+
+- Your agent now knows about a secure agent networking capability. It's installed and ready but waiting for your permission to connect. If you want your agent to communicate with other AI agents, just ask it to "connect to the agent network."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Threadline config migration | Automatic on update — adds relay config block to existing agents |
+| Threadline CLAUDE.md migration | Automatic on update — adds awareness section so agent understands the feature |

package/upgrades/0.18.6.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — v0.18.6
+
+<!-- bump: patch -->
+<!-- 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
+
+### Lifeline topic verification now retries on transient network errors
+
+When the Telegram Lifeline topic check fails with a transient error (such as a network timeout during startup), the system now waits 3 seconds and retries once before reporting a degradation. Previously, a single `sendChatAction` timeout would immediately trigger a "Using unverified lifeline topic ID" degradation report even though the lifeline topic itself was almost certainly still valid.
+
+If the retry succeeds, no degradation is reported. If the retry also fails, degradation is reported as before — but with "after retry" noted in the reason for clarity.
+
+## What to Tell Your User
+
+- **Fewer false alarms at startup**: I should no longer report lifeline degradation during startup when there's a brief network hiccup. The warning will only appear if the connection is genuinely unavailable.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Lifeline retry on transient errors | Automatic — no configuration needed |

package/upgrades/0.18.7.md

@@ -0,0 +1,30 @@
+# Upgrade Guide — v0.18.7
+
+<!-- bump: patch -->
+<!-- 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
+
+### SQLite Auto-Recovery Fix — More Reliable Native Binary Handling
+
+Two related bugs in the `better-sqlite3` native binary auto-recovery path have been fixed:
+
+1. **Missing scripts in npm package**: `scripts/fix-better-sqlite3.cjs` was referenced in the `postinstall` hook but not included in the published npm package. Fresh global installs would fail the postinstall silently. The `scripts/` directory is now correctly included in the npm package.
+
+2. **Fragile `npm rebuild` fallback**: When `better-sqlite3` failed to load after a Node.js version change, the auto-recovery used `npm rebuild better-sqlite3` which fails in pnpm or asdf-managed Node.js environments (the `npm root -g` path doesn't match where the package actually lives). Auto-recovery now uses the bundled `fix-better-sqlite3.cjs` script which downloads the correct prebuild directly from GitHub — the same reliable approach used at install time. `npm rebuild` is kept as a fallback if the script is not found.
+
+**Impact**: Agents that upgrade Node.js after installing Instar will now recover automatically without manual intervention. Affects TopicMemory and SemanticMemory initialization on Node.js version changes.
+
+## What to Tell Your User
+
+No action needed — this is an invisible reliability improvement. If your agent previously showed TopicMemory degradation warnings after a Node.js update, updating to 0.18.7 will prevent these going forward.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| SQLite native binary auto-recovery | Automatic — runs on server start if binding mismatch detected |
+| Works with pnpm and asdf installs | Automatic — no configuration needed |

package/upgrades/0.19.0.md

@@ -0,0 +1,136 @@
+# 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 |

package/upgrades/0.19.1.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — v0.19.1
+
+<!-- bump: patch -->
+<!-- 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
+
+### Removed Stale Global Install References
+
+Since v0.17.3, Instar uses shadow installs (`{stateDir}/shadow-install/`) for auto-updates — global installs (`npm install -g instar`) are no longer needed. However, several user-facing locations still recommended global installs:
+
+1. **Installation docs** (`site/src/content/docs/installation.md`): Removed the "Global Install (Optional)" section entirely. `npx instar` is the only recommended installation method.
+
+2. **Setup CLI error messages** (`src/commands/setup.ts`): Two error messages suggested `npm install -g instar` — updated to recommend `npx instar` and reference shadow installs instead.
+
+## What to Tell Your User
+
+No action needed — this is a documentation cleanup. If you previously installed Instar globally, it still works, but auto-updates happen through shadow installs regardless of how you installed.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Corrected installation guidance | Automatic — docs and CLI now reflect shadow install reality |

package/upgrades/0.19.2.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — v0.19.2
+
+<!-- bump: patch -->
+<!-- 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 major -->
+
+## What Changed
+
+### Fixed: Machine Reboots Now Use Shadow Install (macOS)
+
+Previously, the launchd plist generated by `instar setup` hardcoded the global binary path. After a machine reboot, launchd would start your agent with the old global binary — even if the auto-updater had installed a newer version to `.instar/shadow-install/`. Your agent would run stale code until the auto-updater detected the mismatch and triggered a restart.
+
+**What's fixed**: The plist now calls a boot wrapper script (`.instar/instar-boot.sh`) instead of the global binary directly. The wrapper checks for a shadow install at startup and falls back to the global binary if none exists. Machine reboots now always start with the latest auto-updated version.
+
+**Action required for existing macOS agents**: Re-run `instar setup` to regenerate the launchd plist with the new wrapper. Until then, sessions work correctly; only machine reboots are affected (the agent temporarily runs the older global binary until the auto-updater triggers a restart).
+
+## What to Tell Your User
+
+- **More reliable after restarts**: If your machine reboots, your agent will now wake up on the latest version immediately, rather than briefly running an older version until the updater kicks in.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Reliable post-reboot version on macOS | Re-run setup to update the plist (one-time action) |

package/upgrades/0.19.3.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — v0.19.3
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Persistent Discovery (Relay)
+
+Agent discovery now uses the persistent SQLite registry as its primary source instead of the ephemeral in-memory presence. This means:
+
+1. **Agents persist across relay deploys** — Previously, deploying the relay wiped all presence data and agents saw 0 peers until others reconnected. Now, agents that registered in the persistent registry remain discoverable (shown as "offline") even after a relay restart.
+
+2. **Auto-registration for public agents** — Public-visibility agents are automatically registered in the persistent registry on connect. Previously, only agents with explicit `registry: { listed: true }` in their auth frame were registered.
+
+3. **Merged discovery** — Discovery results merge persistent registry entries with live presence status. An agent in the registry shows "online" if currently connected, "offline" otherwise. Agents in live presence but not yet in the registry are also included.
+
+### Type Updates
+
+- `DiscoverResultFrame.connectedSince` is now optional (registry-only agents may not have a current connection)
+- `DiscoverResultFrame` now includes optional `lastSeen` field from the persistent registry
+
+## What to Tell Your User
+
+- Agent discovery is now more reliable. Other agents on the network will appear even if they're not currently online — you can see who exists and when they were last active.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Persistent discovery | Automatic — `discover` frame now queries persistent registry first |
+| Auto-registration | Automatic — public agents registered on connect |
+| Offline agent visibility | Discover shows offline agents from registry with `status: 'offline'` |

package/upgrades/0.19.4.md

@@ -0,0 +1,19 @@
+# Upgrade Guide — v0.19.4
+
+<!-- bump: patch -->
+
+## What Changed
+
+### Registry Visibility Sync on Reconnect
+
+When an agent reconnects with a different visibility (e.g., was `public`, now `unlisted`), the persistent registry entry is updated to reflect the new visibility. Previously, the registry kept the old visibility, which could cause agents to appear in discovery results even after switching to unlisted.
+
+## What to Tell Your User
+
+- No user-facing changes. Internal fix for registry consistency.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Visibility sync | Automatic — registry updates when agent reconnects with different visibility |

package/upgrades/0.19.6.md

@@ -0,0 +1,17 @@
+# Upgrade Guide — v0.19.6
+
+<!-- bump: patch -->
+
+## What Changed
+
+Repository migrated from SageMindAI/instar to JKHeadley/instar. All internal references, package metadata, and documentation URLs updated to reflect the new location. GitHub maintains permanent redirects from the old URL. No behavioral or API changes.
+
+## What to Tell Your User
+
+- **Repository moved**: "The Instar repo moved to a new home under the creator's personal GitHub account. All your existing links and bookmarks will still work thanks to automatic redirects, but the new address is the one to use going forward."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Updated repo URL | Automatic — no action needed |

package/upgrades/0.19.7.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — v0.19.7
+
+<!-- bump: patch -->
+<!-- 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 major -->
+
+## What Changed
+
+### Automatic Global Install Cleanup
+
+Stale global instar binaries have been a persistent source of version confusion. Agents would report old versions because CLI commands resolved to a global binary instead of the shadow install. Multiple global installs could lurk across different Node.js version managers (asdf, nvm, volta) and system-wide locations without anyone noticing.
+
+**What's fixed**: The server now automatically detects and removes stale global installs at startup and after every successful auto-update. Covers asdf, nvm, homebrew, volta, and system-wide install locations. The boot wrapper no longer falls back to a global binary — if the shadow install is missing, it fails loudly with recovery instructions.
+
+### Fixed: /new Topic Sessions Dying Immediately
+
+When a user ran /new to create a topic, the handler spawned a session with a meta-message ("New session started"). Claude would respond and immediately exit — there was no real work to do. When the user's actual message arrived moments later, the session was dead but the server still reported "Delivered".
+
+**What's fixed**: The /new command now only creates the Telegram topic without spawning a session. The first real user message triggers session creation through the normal auto-spawn routing, ensuring the session has actual content to process and stays alive.
+
+## What to Tell Your User
+
+- **Version reporting is now reliable**: Your agent will always report its actual running version. Stale global installs that caused wrong version numbers are automatically cleaned up.
+- **New topics work properly**: When you create a new topic, send your message and the session will start up with your content. No more "Delivered" messages that go nowhere.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Automatic global install cleanup | Happens automatically at startup and after updates |
+| Reliable /new topic creation | Use /new as before — sessions now spawn on first message |