docs: refresh config guidance for current main structure

Author: ndycode

README.md

@@ -32,6 +32,7 @@ What the installer does:
 
 - writes `~/.config/opencode/opencode.json`
 - backs up an existing config before changing it
+- normalizes the plugin entry to `"oc-chatgpt-multi-auth"`
 - clears the cached plugin copy so OpenCode reinstalls the latest package
 
 ## Example Usage
@@ -120,7 +121,7 @@ Start here if the plugin does not load or authenticate correctly:
 
 Common first checks:
 
-- confirm `"plugin": ["oc-chatgpt-multi-auth@latest"]` is present in your OpenCode config
+- confirm `"plugin": ["oc-chatgpt-multi-auth"]` is present in your OpenCode config
 - rerun `opencode auth login`
 - inspect `~/.opencode/logs/codex-plugin/` after running one request with `ENABLE_PLUGIN_REQUEST_LOGGING=1`
 

config/README.md

@@ -6,8 +6,8 @@ This directory contains the official OpenCode config templates for the ChatGPT C
 
 | File | OpenCode version | Description |
 |------|------------------|-------------|
-| [`opencode-modern.json`](./opencode-modern.json) | **v1.0.210+** | Variant-based config: 6 base models with 21 total presets |
-| [`opencode-legacy.json`](./opencode-legacy.json) | **v1.0.209 and below** | Legacy explicit entries: 21 individual model definitions |
+| [`opencode-modern.json`](./opencode-modern.json) | **v1.0.210+** | Variant-based config: 7 base models with 26 total presets |
+| [`opencode-legacy.json`](./opencode-legacy.json) | **v1.0.209 and below** | Legacy explicit entries: 26 individual model definitions |
 
 ## Quick pick
 
@@ -34,11 +34,13 @@ opencode --version
 OpenCode v1.0.210+ added model `variants`, so one model entry can expose multiple reasoning levels. That keeps modern config much smaller while preserving the same effective presets.
 
 Both templates include:
-- GPT-5.4, GPT-5 Codex, GPT-5.1, GPT-5.1 Codex, GPT-5.1 Codex Max, GPT-5.1 Codex Mini
+- GPT-5.4, GPT-5.4 Mini, GPT-5 Codex, GPT-5.1, GPT-5.1 Codex, GPT-5.1 Codex Max, GPT-5.1 Codex Mini
 - Reasoning variants per model family
 - `store: false` and `include: ["reasoning.encrypted_content"]`
 - Context metadata (`gpt-5.4*`: 1,000,000 context / 128,000 output; other shipped models: 272,000 / 128,000)
 
+Use `opencode debug config` to verify that these template entries were merged into your effective config. `opencode models openai` currently shows OpenCode's built-in provider catalog and can omit config-defined entries such as `gpt-5.4-mini`.
+
 If your OpenCode runtime supports global compaction tuning, you can also set:
 - `model_context_window = 1000000`
 - `model_auto_compact_token_limit = 900000`

docs/configuration.md

@@ -9,7 +9,7 @@ Complete reference for configuring `oc-chatgpt-multi-auth`. Most of this is opti
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["oc-chatgpt-multi-auth@latest"],
+  "plugin": ["oc-chatgpt-multi-auth"],
   "provider": {
     "openai": {
       "options": {
@@ -46,14 +46,15 @@ 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 21 presets and do not add optional IDs by default. add `gpt-5.4-pro` and/or `gpt-5.3-codex-spark` manually only for entitled workspaces.
+the shipped config templates include 7 base model families and 26 shipped presets overall (26 modern variants or 26 legacy explicit entries). add `gpt-5.4-pro` and/or `gpt-5.3-codex-spark` manually only for entitled workspaces.
 for context sizing, shipped templates use:
 - `gpt-5.4`, `gpt-5.4-mini`, and `gpt-5.4-pro`: `context=1000000`, `output=128000`
 - other shipped families: `context=272000`, `output=128000`
 
 model normalization aliases:
 - legacy `gpt-5`, `gpt-5-mini`, `gpt-5-nano` map to `gpt-5.4` (not to `gpt-5.4-mini`)
 - 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; `opencode models openai` currently shows only the built-in provider catalog
 
 if your OpenCode runtime supports global compaction tuning, you can set:
 - `model_context_window = 1000000`
@@ -254,7 +255,7 @@ same settings for all models:
 
 ```json
 {
-  "plugin": ["oc-chatgpt-multi-auth@latest"],
+  "plugin": ["oc-chatgpt-multi-auth"],
   "provider": {
     "openai": {
       "options": {
@@ -301,7 +302,7 @@ model options override global options.
 global (`~/.config/opencode/opencode.json`):
 ```json
 {
-  "plugin": ["oc-chatgpt-multi-auth@latest"],
+  "plugin": ["oc-chatgpt-multi-auth"],
   "provider": {
     "openai": {
       "options": { "reasoningEffort": "medium" }

docs/development/ARCHITECTURE.md

@@ -368,7 +368,7 @@ let include: Vec<String> = if reasoning.is_some() {
 **Alternative**: Single global config
 
 **Problem**:
-- `gpt-5-codex` optimal settings differ from `gpt-5-nano`
+- `gpt-5-codex` optimal settings differ from `gpt-5.4` or `gpt-5.4-mini`
 - Users want quick switching between quality levels
 - No way to save "presets"
 
@@ -472,12 +472,12 @@ The plugin now includes a beginner-focused operational layer in `index.ts` and `
 
 2. **Checklist and wizard flow**
    - `codex-setup` renders a checklist (`add account`, `set active`, `verify health`, `label accounts`, `learn commands`).
-   - `codex-setup wizard=true` launches an interactive menu when terminal supports TTY interaction.
+   - `codex-setup --wizard` launches an interactive menu when terminal supports TTY interaction.
    - Wizard gracefully falls back to checklist output when menus are unavailable.
 
 3. **Doctor + next-action diagnostics**
    - `codex-doctor` maps runtime/account states into severity findings (`ok`, `warning`, `error`) with specific action text.
-   - `codex-doctor fix=true` performs safe remediation:
+   - `codex-doctor --fix` performs safe remediation:
      - refreshes tokens using queued refresh,
      - persists refreshed credentials,
      - switches active account to healthiest eligible account when beneficial.