# Migrating from 3.1 to 3.2

3.2 is the **agent-usability** release that closes the remaining points
from issue #415 (the `query_logs` `labels`/`aggregate` log-side shipped
in 3.1.0, and was made reachable over MCP in the 3.1.1 hotfix). The
migration is **non-breaking** — every new capability is additive or
opt-in, and the default `docker compose --profile demo up` runs
identically on 3.1 and 3.2.

## tl;dr

| You are running… | Required action |
|---|---|
| The OSS demo / defaults | None — behaviour is unchanged. |
| Any custom env / Helm values from 3.1 | None. The new flags below are all off / inert by default. |
| An agent that calls `query_metrics` / `query_logs` | Nothing required; two new optional params (`labels` on `query_metrics`, `raw_query` on both) are available when you want them. |

## New, additive (no flag needed)

| Tool | What's new | Docs |
|---|---|---|
| `query_metrics` | optional `labels` exact-match filter, AND'd into the PromQL series selector (metrics-side of the `query_logs` `labels` param) | [prometheus.md](../prometheus.md) |
| `get_topology` | explicit `note` when no topology connector is configured (was a bare empty graph) | — |

## New, opt-in

| Env / Value | What it does | Docs |
|---|---|---|
| `OMCP_RAW_QUERY=on` | Enables the `raw_query` escape hatch (verbatim PromQL on `query_metrics`, LogQL on `query_logs`). **OFF by default** — it widens the read surface beyond the curated catalog, so it's an explicit operator opt-in. Still tenant-scoped, source-allow-listed, and (logs) redacted. | [raw-query.md](../raw-query.md) |
| `OMCP_IP_ENRICH_FILE=<path>` | Enables the `enrich_ips` tool, backed by a **local offline** CSV (`network,country,city,asn,org,hosting`). No external API call — air-gapped. Unset → `enrich_ips` returns a "not configured" notice. | [ip-enrichment.md](../ip-enrichment.md) |
| `OMCP_BYPASS_REDACTION_ANON=true` | Lets the **anonymous/stdio** identity use the per-call `bypass_redaction` arg (no named credential exists to add to `OMCP_KEY_BYPASS_REDACTION` in an anonymous deployment). Default OFF; redaction stays on for any call that doesn't set the arg. | [redaction.md](../redaction.md#opt-out) |

## New MCP tool

- **`enrich_ips`** — `{ ips: string[] }` → per-IP geo / ASN / org /
  hosting-flag from the local dataset. Always advertised; inert until
  `OMCP_IP_ENRICH_FILE` is set. The tool count goes from 11 to 12.

## Security defaults

Nothing changed by default. The two security-relevant additions
(`raw_query`, anonymous redaction bypass) are **both off unless the
operator turns them on**, and both keep their guards when on (capability
gate, two-key bypass requirement, audit trail).

## Nothing removed

No env var, Helm value, endpoint, MCP tool, or CLI command was removed
or renamed in 3.2. The 3.1 surface is a strict subset of 3.2.

## SDK

The plugin SDK is unchanged and stays at `3.1.0`. The 3.2 work is all in
the gateway's tool surface; the plugin contract / manifest
`schemaVersion` did not move.
