# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: patch -->

## What Changed

Added the foundation of **live credential re-pointing** (Increment A, Steps 1–2) — a new, **dark-by-default** subsystem that will let the agent rebalance which subscription account's credential sits in which config home *without restarting any session* (the change is picked up on the next API call, exactly like `/login`). This ships behind a destructive dark gate: `subscriptionPool.credentialRepointing` defaults to `enabled: false` + `dryRun: true` for **everyone, including dev agents**, and going live requires a deliberate two-flag flip.

This shipment is foundation only — it has **zero runtime behavior** and writes **no credentials**:

- The config block, type, and `DARK_GATE_EXCLUSIONS` registration (category `destructive`).
- `CredentialLocationLedger` — the durable, machine-local bookkeeping core (`state/credential-locations.json`) recording which account's credential lives in which config-home slot. It enforces the one-home-per-credential invariant, refuses every mutation in unknown-mode (corrupt state → fail-closed for moves, fail-open-LOUD for reads with a HIGH attention item), and seeds/recovers from an identity oracle that refuses to guess on an ambiguous or unknown account.

The identity-oracle implementation, the staged swap executor, the consumer re-routing, and the HTTP routes are later steps in this increment; the autonomous "use-it-or-lose-it" drain balancer is Increment B.

## What to Tell Your User

Nothing yet — this feature ships **dark and does nothing** in this release. It reserves the switch and lays the bookkeeping core for a future capability: using your weekly subscription allowances before they reset by quietly moving an idle account's credential between config homes (no session restart, conversation preserved). When the rest is built and you choose to turn it on, you'll get a separate, explicit heads-up — it stays off until then.

## Summary of New Capabilities

⚗️ **Experimental / dark** — no user-facing behavior in this release:
- `subscriptionPool.credentialRepointing` config block (off + dry-run for everyone; two-flag flip to ever go live).
- Internal `CredentialLocationLedger` bookkeeping core (not yet wired to any consumer).

## Evidence

- 69 unit tests green (52 dark-gate + golden line-map; 17 ledger covering every decision boundary: never-seeded, all four seed outcomes, unknown-mode, one-home invariant, journal pruning, persistence round-trip).
- `tsc --noEmit`, the dev-agent dark-gate lint, no-empty-catch, and repo-invariants all clean.
- Spec converged across 5 review rounds (material findings 50→22→12→5→0), approved 2026-06-12.
