# Upgrade Guide — v0.12.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

Guided Setup with scenario-aware discovery pipeline. The setup wizard now automatically discovers agents, repos, and organizational context before asking the user questions.

- **Discovery module** (`src/commands/discovery.ts`): 4-source agent scanning (local filesystem, registry with zombie validation, GitHub personal repos, GitHub org repos). Resolves into one of 8 scenarios via a 3-axis topology matrix (repo/standalone, single/multi-user, single/multi-machine).
- **Setup refactored** (`src/commands/setup.ts`): Structured JSON context replaces ad-hoc strings. UNTRUSTED data delimiters for GitHub data passed to LLM wizard. Non-interactive mode (`--non-interactive`) for CI/CD with recovery key generation. File permissions (chmod 0600) on configs containing secrets.
- **Wizard skill updated**: Privacy disclosure before data collection. Phase 0 rewired to parse structured JSON blocks. Scenario resolution table + step counter per scenario.
- **Security**: Path traversal protection, name/URL validation, clone URL allowlist, graceful degradation when `gh` CLI unavailable.

## What to Tell Your User

- **Guided Setup**: "Setup is now smarter — it discovers your existing agents, repos, and team structure automatically before asking you anything. Run `instar setup` to try the new flow."
- **CI/CD Support**: "You can now run `instar setup --non-interactive` for automated deployments. It generates a recovery key so you can resume if something goes wrong."
- **Privacy**: "Setup now tells you exactly what data it will collect and why before scanning your GitHub repos."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Guided discovery | `instar setup` (automatic) |
| Non-interactive setup | `instar setup --non-interactive` |
| Agent discovery | `instar discover` (standalone) |
| 8-scenario topology | Automatic — resolved from discovered context |
