docs: add maintainer runbooks

docs/README.md

@@ -63,6 +63,9 @@ Public documentation for `codex-multi-auth`.
 | [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md) | Complete field and environment inventory |
 | [development/CONFIG_FLOW.md](development/CONFIG_FLOW.md) | Configuration resolution flow |
 | [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map by repository path |
+| [development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md](development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md) | Safe workflow for adding a new `codex auth` command |
+| [development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md](development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md) | Safe workflow for introducing a new config/settings field |
+| [development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md](development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md) | Safe workflow for changing routing or account-selection policy |
 | [development/TESTING.md](development/TESTING.md) | Validation gates and test matrix |
 | [development/TUI_PARITY_CHECKLIST.md](development/TUI_PARITY_CHECKLIST.md) | Dashboard UX parity checklist |
 | [benchmarks/code-edit-format-benchmark.md](benchmarks/code-edit-format-benchmark.md) | Benchmark methodology and outputs |

docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md

@@ -0,0 +1,38 @@
+# Runbook: Add an Auth Manager Command
+
+Use this when adding a new `codex auth ...` command.
+
+## Goal
+
+Add a command without breaking the existing CLI surface, help text, JSON mode, or dashboard/menu behavior.
+
+## Where to Change
+
+- `lib/codex-manager.ts` — command parsing and dispatch
+- `lib/codex-manager/` — extracted command/controller helpers when the command grows beyond trivial size
+- `lib/cli.ts` — prompt-heavy shared CLI helpers when the command needs reusable interactive flows
+- `docs/reference/commands.md` — command reference
+- `test/codex-manager-cli.test.ts` — CLI behavior coverage
+- `test/documentation.test.ts` — docs parity when command text/help changes
+
+## Safe Workflow
+
+1. Add the smallest possible parsing/dispatch change in `lib/codex-manager.ts`.
+2. If the command has more than one logical branch, extract a helper under `lib/codex-manager/` instead of growing the main file.
+3. Keep JSON output stable and explicit if the command already has `--json`.
+4. Update command help text and `docs/reference/commands.md` in the same change.
+5. Add or extend `test/codex-manager-cli.test.ts` for the new path.
+
+## Compatibility Checks
+
+- Preserve canonical command shape: `codex auth <subcommand>`
+- Do not silently change existing help text unless docs/tests are updated too
+- If adding flags, update both help text and command reference
+
+## QA
+
+- `npm run typecheck`
+- `npm run lint -- lib/codex-manager.ts test/codex-manager-cli.test.ts docs/reference/commands.md test/documentation.test.ts`
+- `npm run test -- test/codex-manager-cli.test.ts test/documentation.test.ts`
+- For auth flows, never paste raw tokens/session headers in PRs, issues, or logs; redact sensitive output.
+- Run the real command or `--help` path in Bash and inspect output

docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md

@@ -0,0 +1,41 @@
+# Runbook: Add a Config Field Safely
+
+Use this when introducing a new `pluginConfig` or dashboard setting field.
+
+## Goal
+
+Add a field without breaking defaults, migration behavior, settings persistence, or documentation parity.
+
+## Where to Change
+
+- `lib/config.ts` — runtime config resolution/defaults
+- `lib/schemas.ts` — env/config schema validation and typed field contracts
+- `lib/dashboard-settings.ts` or `lib/unified-settings.ts` — persisted settings shape
+- `lib/codex-manager/settings-hub.ts` and extracted settings helpers — interactive editing if user-facing
+- `docs/configuration.md` — user-facing config docs
+- `docs/reference/settings.md` — settings reference
+- `docs/development/CONFIG_FIELDS.md` — full field inventory
+- `test/config.test.ts`, `test/dashboard-settings.test.ts`, `test/unified-settings.test.ts` — behavior coverage
+- `test/documentation.test.ts` — docs parity
+
+## Safe Workflow
+
+1. Define the default in the owning config/settings module first.
+2. Thread it through persistence and loading paths before exposing UI controls.
+3. If user-facing, add the smallest possible settings UI path after the storage/config part is correct.
+4. Document the field in both user docs and maintainer inventory.
+5. Add tests for defaulting, persistence, and docs parity.
+
+## Compatibility Checks
+
+- New fields must have deterministic defaults.
+- Do not change existing default values in the same PR unless that is the actual feature.
+- Keep docs and code aligned in the same change.
+- Recheck the Windows persistence notes when the field is written to disk; `EBUSY` and `EPERM` retry behavior must stay documented and covered.
+
+## QA
+
+- `npm run typecheck`
+- `npm run lint -- lib/config.ts lib/dashboard-settings.ts lib/unified-settings.ts test/config.test.ts test/dashboard-settings.test.ts test/unified-settings.test.ts test/documentation.test.ts`
+- Run the targeted test files that cover the field
+- If the field is user-visible, exercise the real settings path manually

docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md

@@ -0,0 +1,38 @@
+# Runbook: Change Routing or Account-Selection Policy Safely
+
+Use this when changing account selection, quota behavior, retry/failover logic, or forecast/report reasoning.
+
+## Goal
+
+Change policy without breaking request flow, account safety, or diagnostics.
+
+## Where to Change
+
+- `index.ts` — runtime orchestration
+- `lib/accounts.ts` — account selection inputs, health state, and cooldown readiness data
+- `lib/rotation.ts` — account selection
+- `lib/forecast.ts` — readiness/risk forecasting
+- `lib/request/failure-policy.ts` — retry/failover decisions
+- `lib/request/rate-limit-backoff.ts` — cooldown/backoff behavior
+- `lib/quota-probe.ts` / `lib/quota-cache.ts` — quota-derived decision inputs
+- `test/accounts.test.ts`, `test/rotation.test.ts`, `test/forecast.test.ts`, `test/failure-policy.test.ts`, `test/rate-limit-backoff.test.ts`, `test/codex-manager-cli.test.ts` — policy coverage
+
+## Safe Workflow
+
+1. Isolate the policy change from pure code motion.
+2. Update the reasoning-producing surfaces (`forecast`, `report`, diagnostics) if their output semantics change.
+3. Add or update focused tests before widening scope.
+4. Prefer one policy change per PR.
+
+## Compatibility Checks
+
+- Do not break existing JSON contract shapes unless the contract is explicitly being revised.
+- If recommendation or routing reasoning changes, update the explain/report output tests too.
+- Keep live-probe behavior and storage mutations covered by tests.
+
+## QA
+
+- `npm run typecheck`
+- `npm run lint -- index.ts lib/rotation.ts lib/forecast.ts lib/request/failure-policy.ts lib/request/rate-limit-backoff.ts test/rotation.test.ts test/forecast.test.ts test/failure-policy.test.ts test/rate-limit-backoff.test.ts test/codex-manager-cli.test.ts`
+- Run the targeted policy tests you touched
+- Execute at least one real CLI/manual QA path that demonstrates the changed reasoning or routing behavior

docs/releases/v1.2.0.md

@@ -0,0 +1,18 @@
+# Release v1.2.0
+
+Release line: `stable`
+
+This document anchors the current stable release reference used by the docs portal.
+
+## Scope
+
+- Current package version in `package.json` is `1.2.0`.
+- Canonical command family remains `codex auth ...`.
+- Canonical package name remains `codex-multi-auth`.
+
+## Related
+
+- [../getting-started.md](../getting-started.md)
+- [../upgrade.md](../upgrade.md)
+- [../reference/commands.md](../reference/commands.md)
+- [../reference/public-api.md](../reference/public-api.md)

test/documentation.test.ts

@@ -263,6 +263,21 @@ describe("Documentation Integrity", () => {
 		expect(manager).not.toContain("codex-multi-auth auth switch <index>");
 	});
 
+	it("keeps maintainer runbooks present", () => {
+		const runbooks = [
+			"docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md",
+			"docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md",
+			"docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md",
+		];
+
+		for (const runbook of runbooks) {
+			expect(
+				existsSync(join(projectRoot, runbook)),
+				`${runbook} should exist`,
+			).toBe(true);
+		}
+	});
+
 	it("documents stable overrides separately from advanced and internal overrides", () => {
 		const configGuide = read("docs/configuration.md").toLowerCase();
 		const settingsRef = read("docs/reference/settings.md").toLowerCase();