ndycode · ndycode · Jul 28, 2026 · Jul 27, 2026 · Jul 27, 2026 · Jul 27, 2026
@@ -61,7 +61,7 @@ Package version: 6.9.1
 - Canonical package/plugin name is `oc-codex-multi-auth`.
 - The npm bin is an installer and thin standalone CLI, not a long-running runtime daemon.
 - OpenCode loads the provider plugin and TUI plugin from built package exports.
-- Default installer mode writes compact modern OpenCode config (12 bases / 53 variants); `--full` adds 53 explicit selector IDs; `--legacy` writes legacy explicit-only config; `--dry-run` and `--no-cache-clear` are supported.
+- Default installer mode only registers plugin entries and preserves `provider.openai`; `--modern` writes compact config (12 bases / 53 variants), `--full` adds 53 explicit selector IDs, and `--legacy` writes legacy explicit-only config; `--dry-run` and `--no-cache-clear` are supported.
 - Runtime requests preserve Codex stateless requirements: `store: false` and `reasoning.encrypted_content`.
 - GPT-5.6 uses responses-lite shaping and default client identity `opencode`; other models default to `codex_cli_rs`.
 - Account selection uses `rotationStrategy` (`hybrid` default) with health scoring in `lib/rotation.ts`.

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added a cache-only `update` command and provider-preserving `install --plugin-only` mode. Updating no longer requires invoking the provider/model installer, and manual update notifications now recommend the config-safe command.
+
+### Changed
+- Default install now manages only the OpenCode/TUI plugin entries and preserves `provider.openai`; model catalogs require explicit `--modern`, `--full`, or `--legacy`. Installer writes and backups are skipped when merged configuration is semantically unchanged, plugin-only mode rejects non-object JSON roots, dry-run diffs report changed paths without values, and managed cache cleanup covers bare and `@latest` layouts with retries for transient Windows cache locks.
+
 ## [6.10.1] - 2026-07-23
 
 ### Fixed

@@ -46,7 +46,7 @@ Use it when you want OpenCode to run Codex-style coding workflows from your own
 
 | Surface | Purpose |
 | --- | --- |
-| `oc-codex-multi-auth` | npm installer bin; updates `~/.config/opencode/opencode.json`, manages `tui.json`, normalizes stale plugin entries, and clears OpenCode plugin cache. Also runs standalone commands: `doctor`, `status`, `list`, `limits`, `dashboard`, `health`, `diag`, `warm` |
+| `oc-codex-multi-auth` | npm CLI; explicit install modes manage OpenCode provider/TUI config, while `update` only clears the managed package cache. Also runs standalone commands: `doctor`, `status`, `list`, `limits`, `dashboard`, `health`, `diag`, `warm` |
 | OpenCode plugin entry (`index.ts`) | auth loader, OAuth login modes, provider fetch pipeline, account rotation, retry/failover, and `codex-*` tool registry |
 | OpenCode TUI plugin (`tui.ts`) | prompt quota status, quota details, shared quota cache, and active-account-aware display |
 | 24 `codex-*` tools | setup, help, status, list, switch, warm, limits, health, metrics, doctor, dashboard, pool, backup, keychain, diagnostics, and recovery actions |
@@ -76,9 +76,9 @@ The plugin does not replace OpenCode. OpenCode remains the host; this package in
 <details open>
 <summary><b>For Humans</b></summary>
 
-### Option A: Standard install (compact modern)
+### Option A: Standard install (preserve provider config)
 
-Default mode writes 12 base OAuth model families and leaves reasoning depth to OpenCode's variant picker.
+Default mode registers the OpenCode and TUI plugin entries without changing `provider.openai`.
 
 ```bash
 npx -y oc-codex-multi-auth@latest
@@ -88,29 +88,46 @@ Installer flags:
 
 | Flag | Effect |
 | --- | --- |
-| (default) / `--modern` | Compact modern catalog: 12 bases, 53 variants |
+| (default) / `--plugin-only` | Register the plugin and TUI integration without changing `provider.openai` |
+| `--modern` | Install compact modern catalog: 12 bases, 53 variants |
 | `--full` | Compact bases plus 53 explicit selector IDs |
 | `--legacy` | Explicit-only catalog for older OpenCode |
-| `--dry-run` | Show actions without writing |
+| `--dry-run` | Show changed config paths without values or writes |
 | `--no-cache-clear` | Skip clearing the OpenCode plugin cache |
 
-### Option B: Full explicit model catalog
+### Option B: Compact modern model catalog
+
+```bash
+npx -y oc-codex-multi-auth@latest --modern
+```
+
+Use this when OpenCode does not already provide the OAuth model definitions or you want the shipped variant presets.
+
+### Option C: Full explicit model catalog
 
 Use this when you want direct selector IDs such as `openai/gpt-5.5-medium` in addition to OpenCode variants.
 
 ```bash
 npx -y oc-codex-multi-auth@latest --full
 ```
 
-### Option C: Verify wiring
+### Updating without config changes
+
+```bash
+npx -y oc-codex-multi-auth@latest update
+```
+
+`update` clears only the OpenCode-managed package cache. It does not read or write `opencode.json` or `tui.json`; restart OpenCode afterward to install the current package.
+
+### Option D: Verify wiring
 
 ```bash
 opencode --version
 opencode debug config
 opencode auth login
 ```
 
-The installer updates `~/.config/opencode/opencode.json`, backs up the previous config, normalizes the plugin entry to `"oc-codex-multi-auth"`, enables the TUI status plugin in `~/.config/opencode/tui.json`, and clears the OpenCode cached plugin copy so OpenCode reinstalls the latest package.
+The default installer only normalizes the plugin entry in `~/.config/opencode/opencode.json`, enables the TUI status plugin in `~/.config/opencode/tui.json`, and clears the cached plugin copy. Catalog modes additionally merge their selected `provider.openai` definitions. Changed config files are backed up before writing.
 
 ### Standalone CLI (no agent / no token cost)
 
@@ -133,13 +150,14 @@ oc-codex-multi-auth diag
 
 ### Step-by-step
 
-1. Install or refresh config:
+1. Register the plugin without changing `provider.openai`:
    - `npx -y oc-codex-multi-auth@latest`
+   - Use `--modern` only when the shipped compact model catalog is required.
 2. Run first login flow:
    - `opencode auth login`
 3. Validate config:
    - `opencode debug config`
-4. Run a smoke request (compact modern selectors):
+4. Run a smoke request (after OpenCode or `--modern` supplies the selector):
    - `opencode run "Explain this repository" --model=openai/gpt-5.5 --variant=medium`
 5. Inspect plugin state with the OpenCode tool surface:
    - `codex-status`

@@ -13,17 +13,19 @@ This directory contains the official OpenCode config templates for `oc-codex-mul
 
 | Installer flag | What gets written |
 |----------------|-------------------|
-| default / `--modern` | Compact modern: 12 base OAuth families + variant picker |
+| default / `--plugin-only` | Register plugin entries; preserve `provider.openai` |
+| `--modern` | Compact modern: 12 base OAuth families + variant picker |
 | `--full` | Modern bases **plus** explicit legacy selector IDs |
 | `--legacy` | Explicit-only catalog (53 preset model entries) |
 
 ```bash
-npx -y oc-codex-multi-auth@latest          # compact modern (default)
+npx -y oc-codex-multi-auth@latest          # plugin entries only
+npx -y oc-codex-multi-auth@latest --modern # compact modern catalog
 npx -y oc-codex-multi-auth@latest --full   # modern + explicit IDs
 npx -y oc-codex-multi-auth@latest --legacy # explicit only
 ```
 
-Rerun the default installer to remove explicit preset IDs and stale base models left by earlier plugin catalogs.
+Run the installer with `--modern` to remove explicit preset IDs and stale base models left by earlier plugin catalogs.
 
 ## Quick pick
 

@@ -33,7 +33,8 @@ Install modes:
 
 | Flag | Config written |
 | --- | --- |
-| (default) / `--modern` | Compact modern: 12 base model families + variant picker (53 variants total) |
+| (default) / `--plugin-only` | Register plugin entries; preserve `provider.openai` |
+| `--modern` | Compact modern: 12 base model families + variant picker (53 variants total) |
 | `--full` | Compact modern bases **plus** explicit legacy selector IDs |
 | `--legacy` | Explicit-only catalog (53 model entries) |
 

@@ -53,7 +53,7 @@ controls how much thinking the model does.
 | `gpt-5.1-codex-mini` | medium, high |
 | `gpt-5.1` | none, low, medium, high |
 
-The shipped config templates include 12 base model families and 53 shipped presets overall (53 modern variants or 53 legacy explicit entries). The default installer uses the compact modern template so the TUI model picker shows base OAuth model families and the separate variant picker selects the reasoning preset. Use `--full` to install explicit selector IDs too. `gpt-5.5-pro` is ChatGPT-only (not routed by this plugin), while `gpt-5.3-codex-spark` remains a manual add-on for entitled workspaces only.
+The shipped config templates include 12 base model families and 53 shipped presets overall (53 modern variants or 53 legacy explicit entries). Default install preserves `provider.openai`; use `--modern` to install the compact base families and variant picker, or `--full` to install explicit selector IDs too. `gpt-5.5-pro` is ChatGPT-only (not routed by this plugin), while `gpt-5.3-codex-spark` remains a manual add-on for entitled workspaces only.
 
 Base families:
 
@@ -106,14 +106,14 @@ model normalization aliases:
 - `gpt-5.5*`, `gpt-5.5-fast*`, and user-typed `gpt-5.5-pro*` normalize to the public Codex model id `gpt-5.5`
 - legacy `gpt-5` maps to `gpt-5.5`; legacy `gpt-5-mini` / `gpt-5-nano` map to `gpt-5.4-mini` / `gpt-5.4-nano`
 - snapshot ids `gpt-5.4-2026-03-05*`, `gpt-5.4-mini-2026-03-05*`, and `gpt-5.4-pro-2026-03-05*` map to stable `gpt-5.4` / `gpt-5.4-mini` / `gpt-5.4-pro`
-- `opencode debug config` is the reliable way to confirm merged custom/template model entries; default installs expose compact entries like `gpt-5.5` and `gpt-5.5-fast`, while `--full` also exposes explicit entries like `gpt-5.5-medium`, `gpt-5.5-fast-medium`, and `gpt-5.5-high`
+- `opencode debug config` is the reliable way to confirm merged custom/template model entries; `--modern` exposes compact entries like `gpt-5.5` and `gpt-5.5-fast`, while `--full` also exposes explicit entries like `gpt-5.5-medium`, `gpt-5.5-fast-medium`, and `gpt-5.5-high`
 
 if your OpenCode runtime supports global compaction tuning, you can set:
 - `model_context_window = 1000000`
 - `model_auto_compact_token_limit = 900000`
 
 selector note:
-- the default installer is optimized for the TUI model picker: choose a base `(OAuth)` model, then choose a variant
+- `--modern` is optimized for the TUI model picker: choose a base `(OAuth)` model, then choose a variant
 - install with `--full` when you need direct selector IDs such as `openai/gpt-5.5-medium` or `openai/gpt-5.5-fast-medium`
 
 what they mean:
@@ -464,7 +464,7 @@ global (`~/.config/opencode/opencode.json`):
 
 project override (`<project>/.opencode.json`) can set a default model or per-project provider options without changing the global install.
 
-### Compact modern selectors (default install)
+### Compact modern selectors (`--modern` install)
 
 ```bash
 opencode run "task" --model=openai/gpt-5.5 --variant=medium

@@ -24,14 +24,15 @@ Runtime architecture for the `oc-codex-multi-auth` OpenCode plugin, installer, C
 Install / refresh / standalone CLI
   |
   | npx -y oc-codex-multi-auth@latest
-  |   default compact modern | --full | --legacy
+  |   install: default plugin-only | --modern | --full | --legacy
+  |   update: managed package cache only
   |   [--dry-run] [--no-cache-clear]
   | standalone: doctor | status | list | limits | dashboard | health | diag | warm
   v
 scripts/install-oc-codex-multi-auth.js
   |- delegates to scripts/install-oc-codex-multi-auth-core.js
-  |- writes ~/.config/opencode/opencode.json
-  |- writes ~/.config/opencode/tui.json
+  |- install writes changed ~/.config/opencode/opencode.json and tui.json
+  |- update never reads or writes OpenCode config
   |- merges config/opencode-modern.json and/or config/opencode-legacy.json
   |- normalizes old package/plugin entries
   |- clears OpenCode plugin cache (unless --no-cache-clear)
@@ -260,7 +261,7 @@ The request path also writes quota snapshots from response headers, so the TUI c
 
 ## Model Catalog and Fallback Notes
 
-The default installer writes the modern OpenCode template (`config/opencode-modern.json`):
+The default installer preserves `provider.openai`. `--modern` writes the modern OpenCode template (`config/opencode-modern.json`):
 
 - 12 base model families in the picker:
   - `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`

@@ -278,7 +278,7 @@ the tool does not automatically prune them because they may be valid elsewhere.
 
 Use these commands when validating config fields.
 
-### Compact modern (default install)
+### Compact modern (`--modern` install)
 
 ```bash
 opencode debug config

@@ -48,28 +48,33 @@ That file controls plugin behavior such as retry policy, rotation strategy, begi
 `scripts/install-oc-codex-multi-auth.js` performs these steps:
 
 1. Load the selected template set:
-   - default / `--modern`: `config/opencode-modern.json` (compact 12 bases / 53 variants)
+   - default / `--plugin-only`: preserve `provider.openai`
+   - `--modern`: `config/opencode-modern.json` (compact 12 bases / 53 variants)
    - `--full`: modern bases merged with `config/opencode-legacy.json` explicit entries
    - `--legacy`: `config/opencode-legacy.json` only (53 explicit IDs)
-2. Back up an existing `~/.config/opencode/opencode.json`.
+2. Back up an existing `~/.config/opencode/opencode.json` only when the merged result changes.
 3. Normalize the plugin list so it ends with plain `oc-codex-multi-auth`.
-4. Replace `provider.openai` with the selected shipped template block.
+4. Merge `provider.openai` with the selected shipped template block; `--plugin-only` skips this step entirely.
 5. Enable the TUI plugin in `~/.config/opencode/tui.json`.
 6. Clear the cached OpenCode plugin copy under `~/.cache/opencode/` unless `--no-cache-clear`.
 
 Additional flags:
 
 | Flag | Effect |
 |------|--------|
-| `--dry-run` | Print planned actions without writing |
+| `--dry-run` | Print changed config paths without values or writes |
 | `--no-cache-clear` | Skip OpenCode plugin cache cleanup |
+| `--plugin-only` | Explicit alias for default plugin/TUI registration without changing `provider.openai` |
+| `update [--dry-run]` | Clear managed package caches without reading or writing OpenCode config |
 | standalone first arg | Run CLI without install: `doctor`, `status`, `list`, `limits`, `dashboard`, `health`, `diag`, `warm` |
 
 Important detail:
 
 - The installer intentionally writes the plugin entry as `oc-codex-multi-auth`, not `oc-codex-multi-auth@latest`.
-- The default install mode uses the compact modern base-model template so the TUI model picker shows real OAuth model families and leaves reasoning depth to the variant picker.
+- The default install mode only manages plugin entries; catalog installation is explicit.
+- `--modern` uses the compact base-model template so the TUI model picker shows real OAuth model families and leaves reasoning depth to the variant picker.
 - `--full` merges the modern base-model template with the explicit legacy preset entries for scripts that require direct selector IDs.
+- `update` returns before template loading and config parsing, so even malformed user config is left untouched.
 
 ## Shipped Template Structure
 
@@ -107,11 +112,16 @@ gpt-5-codex
 
 ### Default installer mode
 
-The default installer mode writes:
+The default installer mode writes only:
 
-- the 12 modern base model entries from `config/opencode-modern.json`
+- the `oc-codex-multi-auth` entry in OpenCode's plugin list
+- the `oc-codex-multi-auth` entry in the TUI plugin list
+
+It preserves `provider.openai` exactly.
+
+### Modern installer mode
 
-That compact install mode keeps the OpenCode TUI model picker focused on actual OAuth model families. Reasoning presets are selected through the separate variant picker.
+`--modern` writes the 12 modern base model entries from `config/opencode-modern.json`. Reasoning presets are selected through the separate variant picker.
 
 Example shape:
 
@@ -148,7 +158,7 @@ Example shape:
 }
 ```
 
-Default install uses base model IDs plus variants:
+Modern install uses base model IDs plus variants:
 
 ```bash
 opencode run "task" --model=openai/gpt-5.5 --variant=medium
@@ -221,7 +231,7 @@ ENABLE_PLUGIN_REQUEST_LOGGING=1 opencode run "ping" --model=openai/gpt-5.6-sol -
 Important runtime behavior:
 
 - `opencode debug config` shows merged provider models from your config.
-- The default install shows compact OAuth base entries such as `gpt-5.5`, `gpt-5.5-fast`, and `gpt-5.6-sol`.
+- `--modern` shows compact OAuth base entries such as `gpt-5.5`, `gpt-5.5-fast`, and `gpt-5.6-sol`.
 - `--full` additionally shows explicit entries such as `gpt-5.5-medium` / `gpt-5.5-fast-medium` / `gpt-5.6-sol-high`.
 - Compact verification should use `--model=openai/gpt-5.5 --variant=medium`, not `gpt-5.5-medium`, unless `--full` or `--legacy` was installed.
 

@@ -44,7 +44,7 @@ The shipped templates include **12 base families** and **53 presets** total:
 
 GPT-5.6 is entitlement-gated for some accounts. Without access, the plugin auto-falls back `sol → terra → luna → gpt-5.5` (disable with `CODEX_AUTH_DISABLE_GPT56_AUTO_FALLBACK=1`). Optional or entitlement-gated model IDs can be added manually when your workspace supports them. `gpt-5.5-pro` is ChatGPT-only and is not routed through this Codex plugin.
 
-Default install is compact modern (bases + variants). Use `--full` for modern + explicit IDs, or `--legacy` for explicit-only.
+Default install preserves `provider.openai` and only registers plugin entries. Use `--modern` for compact bases + variants, `--full` for modern + explicit IDs, or `--legacy` for explicit-only.
 
 ## Can I use multiple accounts?