# Upgrade Guide: Instar 0.8.23

> This guide covers new capabilities introduced in v0.8.23 through v0.8.26.

## What Changed

### Standalone Agents — Agents Without a Project Directory
Previously, Instar required a project directory (a git repo) to house `.instar/`. This meant agents couldn't exist independently of a codebase.

Now you can create **standalone agents** — agents that live in `~/.instar/agents/<name>/` with no associated project. These are ideal for general-purpose assistants, personal agents, or agents that work across multiple projects.

```bash
# Create a standalone agent
instar init --standalone my-agent

# Start it
instar server start --dir ~/.instar/agents/my-agent
```

### Global Agent Registry
All agents (project-based and standalone) are now tracked in a global registry at `~/.instar/registry.json`. This enables:
- Listing all agents across your machine
- Coordinating between agents
- Health monitoring across your agent fleet

### Backup & Restore — Protect Agent State
A new backup system lets you snapshot and restore your agent's state.

```bash
instar backup create          # Snapshot current state
instar backup list            # See all snapshots
instar backup restore <id>    # Restore from snapshot
```

Backups capture everything: AGENT.md, MEMORY.md, config, job state, relationships.

### Git-Backed State for Standalone Agents
Standalone agents can sync their state via git. Useful for multi-machine setups.

```bash
instar git init               # Initialize git tracking
instar git status             # See uncommitted changes
instar git sync               # Commit and push state
```

### Memory Search — Find What You've Remembered
Your MEMORY.md is searchable now. Full-text search across all memory files.

```bash
instar memory search "project goals"     # Search memory
instar memory index                       # Re-index for faster search
instar memory stats                       # See memory statistics
```

**What you should do:**
1. If you manage multiple agents or want a personal agent, explore `instar init --standalone`.
2. Consider setting up `instar backup create` as a regular habit (or add it to a scheduled job).
3. Try `instar memory search` to surface things from your MEMORY.md you may have forgotten.

### Multi-Machine Coordination Infrastructure
Under the hood, significant infrastructure was added for coordinating agents across machines. This powers future capabilities for syncing agent state and coordinating work between machines. No user-facing action needed now.

---

## What Changed: Conversational Notification Tone
Agent notifications have been tuned to sound more like a colleague than a system alert. Expect updates and status messages to use natural language rather than technical jargon.

**What you should do:** Nothing. Just notice that your messages to your user sound more natural. If you have custom notification templates in your jobs, consider whether they match this tone.

---

## What Changed: Telegram Photo Viewing
When your user sends a photo in Telegram, it's now delivered as `[image:path]` in your message input — a path you can pass directly to Claude for viewing. Previously photos were dropped or passed as raw file references that Claude couldn't process.

**What you should do:** If you have photo-handling logic that worked around the old behavior, you may be able to simplify it. Now when you receive `[image:path]`, treat it as a viewable image.

---

## What Changed: Health Check Stability
The server's health check now uses hysteresis — a brief failure doesn't immediately mark the server as unhealthy. This prevents false-positive health failures during brief transient issues.

Also: `ANTHROPIC_API_KEY` is now trimmed of whitespace on startup. Keys with trailing newlines (a common copy-paste artifact) were previously silently failing.

**What you should do:** If you experienced flapping health states or mysterious API key errors, this is fixed.

---

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Standalone agents | `instar init --standalone <name>` |
| Global registry | `~/.instar/registry.json` — all agents tracked |
| Backup/restore | `instar backup create/list/restore` |
| Git-backed state | `instar git init/status/sync` |
| Memory search | `instar memory search "<query>"` |
| Photo messages | Receive `[image:path]` — viewable by Claude directly |
| Health hysteresis | Fewer false-positive health failures |

## What to Tell Your User

Pick what's relevant to your context:
- **Standalone agents**: "Instar can now run agents that aren't tied to a specific project. You could create a dedicated personal assistant this way."
- **Backup**: "I can now snapshot my own state. Want me to set up regular backups so your preferences and my memory are protected?"
- **Photo messages**: "I can now see photos you send me in Telegram — just attach them like normal."
- **Cleaner notifications**: "My messages should sound a bit more natural now — less system-speak."
