# Upgrading

Upgrade the repowise package, run repowise update, and your existing index keeps working. No reindex in the normal case, and a full reindex is never forced.

repowise is built so that upgrading is painless: **upgrade the package, run
`repowise update`, and your existing index keeps working.** A full reindex is
only ever *recommended* for a genuinely breaking change, never forced, and
repowise tells you exactly when and how.

## The short version

### uv

```bash
uv tool upgrade repowise
cd your-repo
repowise update            # picks up the new version against your existing index
```

### pipx

```bash
pipx upgrade repowise
cd your-repo
repowise update            # picks up the new version against your existing index
```

### pip

```bash
pip install -U repowise
cd your-repo
repowise update            # picks up the new version against your existing index
```

That's it. No reindex in the normal case.

## What happens on upgrade

When you run `repowise update` (or `repowise serve`) after upgrading,
repowise:

1. **Reads your store's format version** and compares it to the running build.
   The on-disk store records which version wrote it, so repowise knows exactly
   what, if anything, an upgrade needs.

2. **Applies any automatic, no-cost adjustments in place.** New database columns
   are back-filled automatically. If your embedding model changed, vectors are
   re-embedded for you with **no LLM calls**. You don't run anything.

3. **Keeps your parse cache warm.** Ordinary releases do not invalidate cached
   work, so updates stay fast across releases.

4. **Shows you what changed.** A short "what's new" summary appears for the
   versions you crossed, and [`repowise whats-new`](https://docs.repowise.dev/cli/other#repowise-whats-new)
   prints the highlights and numbers any time. The dashboard's "update
   available" banner names the next release's top highlights, and after a
   minor upgrade the dashboard opens What's new once, with the release
   summary, its numbers and every change (a patch shows a short note).

## When a reindex is recommended

Rarely, a release changes the store format in a way an in-place migration
can't cover. When that happens repowise **keeps your existing index working**
and shows a clear notice with the exact command, for example:

```text
Reindex recommended: repowise init --force
```

> **Note**
>
> It is a recommendation, not a requirement. Nothing is wiped until you choose
> to run it. You can keep using the current index and reindex when convenient.

## What to do for each release

Nothing below needs a reindex. Each item says what to expect on the
first update, or what to change in a script or config.

### Upgrading to 0.59

| Topic | What to do |
|---|---|
| First update | Expect one longer `update`: health re-scores (`HEALTH_ANALYZER_VERSION` 43, for code-origin classification) and the parse cache refreshes once (`PARSER_SCHEMA_VERSION` 10, for JS and TS `tests/` folders inside `src`). `STORE_FORMAT_VERSION` is unchanged, so nothing needs re-indexing. Scores name the `analyzer_version` that wrote them. |
| Decisions | Agents accept decisions signed as themselves, and the capture prompt asks them to record committed decisions, both on by default. To keep acceptance with people, run `repowise decision config agent-acceptance --off`; `capture-prompt --off` silences the prompt. Every acceptance needs decision text: pass `confirm --decision` for a record without it. |
| Repo settings | `exclude_patterns` and `wiki_style` live in `.repowise/config.yaml` for the CLI, the indexer and the web UI. A value saved before on the server applies until the next save moves it into the file. |
| `repowise serve` | Opens the web UI in your browser once it answers, in an interactive terminal outside CI. Pass `--no-open` or set `REPOWISE_NO_OPEN=1` to keep it closed. |
| `coverage add` | A report whose files mostly do not map to the repo stores nothing and suggests a path prefix. Pass `--allow-partial` to store it flagged partial. |
| Workspace commands | From a workspace root, `health`, `dead-code`, `events` and the other single-repo commands read one repo and name it. Pass `--repo <alias>` for another. |
| Workspace dead code | A contract link from another repo cuts a finding's confidence to 30%; co-change and package links keep it and add a note. A finding with a note is never `safe_to_delete`. |

### Upgrading to 0.58

| Topic | What to do |
|---|---|
| First update | Expect one longer `update`: health re-scores under the new scoring (`HEALTH_ANALYZER_VERSION` 41) and the parse cache refreshes once (`PARSER_SCHEMA_VERSION` 9, for Kotlin calls chained on calls). `STORE_FORMAT_VERSION` is unchanged, so no model is called and nothing needs re-indexing. `repowise status` names what the next update redoes. |
| Health marker ids | `bumpy_road` is `repeated_nesting`, and `brain_method` is listed without a deduction. Old ids keep working in `.repowise/health-rules.json`, findings and filters. |
| `get_health` kpis | Read `production_average` for production code alone. `non_code_files` and `average_health_code_only` are not in the response. |
| Scripted `init` | Read the exit code: `0` ready, `2` finished with gaps, `130` interrupted. `--progress json` gives a parseable event stream. `--yes` uses a logged-in Claude Code, Codex or OpenCode only with `--provider`. |
| Mode names | `init`, `status`, `update` and the editor files name an index Index only, Built from code or `Written by <model>`, each with its [upgrade command](https://docs.repowise.dev/cli/indexing#modes). Flags, `state.json` and JSON values are unchanged, so scripts keep working. |
| `workspace add` | The added repo's documentation is built from code by default. Pass `--docs` for a model. |
| `get_overview` | Pass `include=["scope"]` for the whole `index_scope`, `include=["tools"]` for `tool_surface`, and `include=["actions"]` for the quarter's actions. `git_health` carries `riskiest_files`. |
| Dashboard links | Code Health's `coverage`, `security`, `doc-drift` and `impact` tabs open the Tests page, the Security page, Docs > Doc drift and Commits > Review a change. Old links redirect. |

### Upgrading to 0.57

| Topic | What to do |
|---|---|
| Git history window | A new index reads the newest 5,000 commits. An existing index keeps the `commit_limit` its `.repowise/config.yaml` records, and `update` prints that value once. Set `commit_limit: 5000` there to read the wider window. |
| Provider order | The CLI, `repowise serve` and the MCP server resolve provider, model and base URL in this order: the flag or dashboard choice, `.repowise/config.yaml`, the dashboard's global default, then `REPOWISE_PROVIDER` / `REPOWISE_MODEL`. A base URL in `config.yaml` takes precedence over `OPENAI_BASE_URL` and the other `*_BASE_URL` variables. If you set the model through environment variables, remove the value from `config.yaml` or change it there. |
| AI share fields | `/commits/agent-trend` returns per-label counts, `coverage_pct` and `agent_pct_of_covered`. The authorship filter accepts `agent`, `human` (human-attested) and `unknown`. `get_context` ownership carries one `agent_share` summary. Point scripts that read `agent_pct` or `agent_authored_pct` at these fields. |
| `get_answer` diagnostics | Pass `include=["diagnostics"]` to read `retrieval_quality`. `confidence` is the one trust signal. |
| History markers | Ownership, churn and other history-only markers on production files are counted under `history`, outside the default defect lists. Scores, KPIs, `get_risk` and the work queue use them. |
| Change Records | The first `update` builds a Change Record for each first-parent commit in the history window, with no model call. |

### Upgrading to 0.56

| Topic | What to do |
|---|---|
| First update | Expect one longer `update`: it reads the whole git history once, re-renders structural pages and reruns the security scan, with no model calls. Run `repowise generate --stale` to refresh prose pages it marks stale. |
| `search_codebase` rows | Read `path` on each row. |
| `get_risk` blocks | Pass `include=["blast"]` for `pr_blast_radius` and `include=["owners"]` for detailed owner metrics. |
| `repowise health` | Bare `repowise health` reads the stored analysis. Pass `--recompute` to run it in process. |

### Upgrading to 0.55

| Topic | What to do |
|---|---|
| First update | Expect one longer `update`: it re-scores and re-parses when the health analyzer or parser changed, even on an unchanged checkout. No model is called. |
| Unanalysed languages | Files in languages health cannot analyse read "not analysed" and stay out of averages and trends. |
| `get_health` | Read `fix_first` for the lead work item. |
| MCP `_meta` | Set `REPOWISE_MCP_DEBUG_META=1` for diagnostics such as `timing_ms`, and `REPOWISE_MCP_PRETTY_JSON=1` for indented JSON text. |

The full release notes are in the
[changelog](https://github.com/repowise-dev/repowise/blob/main/docs/CHANGELOG.md).

## Checking your version

- **CLI:** `repowise --version`, or [`repowise doctor`](https://docs.repowise.dev/cli/other#repowise-doctor)
  for an update check with the right upgrade command for your install method.
- **Dashboard:** the version is shown in the sidebar footer, with a dot when a
  newer release is available.

## See also

- [`repowise whats-new`](https://docs.repowise.dev/cli/other#repowise-whats-new): release notes
  since the version you last viewed.
- The full release history lives on [PyPI](https://pypi.org/project/repowise/).
- Prefer not to manage upgrades at all? The
  [hosted version](https://docs.repowise.dev/hosted/vs-self-hosted) always runs the latest engine.