# 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 |
