docs: refresh the lib knowledge-base tree for the extraction era - #589

Summary

• Doc-only companion to docs: refresh test knowledge-base counts and list the new suites #588 for the other knowledge base: lib/AGENTS.md's curated STRUCTURE tree never picked up the module clusters the §4.1 extraction era created, so a reader following it today misses several load-bearing seams.

What Changed

• STRUCTURE tree gains, in tree style: codex-manager/formatters/ (shared CLI text/account/model/quota formatters), policy/, the request/ sub-entries (helpers/, rate-limit-decision.ts, stream-failover-runtime.ts), the runtime/rotation-*.ts extraction cluster (selection/state/storage-meta/server-type helpers), plus four top-level modules: fs-retry.ts (the shared withRetry/withRetrySync home from §4.2), temp-path.ts (the crypto-random staging-path helper from audit H1), budget-guard.ts, and local-bridge.ts.
• WHERE TO LOOK gains two rows: "Retry policies" → fs-retry.ts (every retry loop declares its policy there as of refactor: migrate the last two hand-rolled retry loops to withRetry #585) and "Temp/staging paths" → temp-path.ts (with the never-Math.random() reminder from H1).
• The errors.ts row now names the CodexError hierarchy, matching the typed-error contracts shipped in refactor: throw CodexValidationError from rotation-proxy startup guards #586/refactor: abort unreadable config saves with a typed StorageError #587.
• Kept the tree's curated style (representative entries + └── ... ellipses), mirroring how docs: refresh test knowledge-base counts and list the new suites #588 handled the test knowledge bases.

Validation

• npm run typecheck (pre-commit hook)
• npm test -- test/documentation.test.ts — passes
• Every added path verified to exist on current main
• npm test / npm run build — not run for this markdown-only change

Docs and Governance Checklist

• No user-visible behavior changed; contributor-facing knowledge base only

Risk and Rollback

• Risk level: minimal — markdown only.
• Rollback plan: revert the single commit.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

refreshes lib/AGENTS.md to reflect the module layout created during the §4.1 extraction era. all added paths have been verified to exist on main.

• structure tree gains codex-manager/formatters/, policy/, request/ sub-entries, and runtime/rotation-*.ts (all five helpers including token-refresh), plus four new top-level entries: fs-retry.ts, temp-path.ts, budget-guard.ts, local-bridge.ts.
• WHERE TO LOOK gains "retry policies" → fs-retry.ts and "temp/staging paths" → temp-path.ts; errors.ts description is updated to name the CodexError hierarchy.

Confidence Score: 5/5

markdown-only change; every added path verified to exist on main; no runtime behavior touched.

all documented paths exist, rotation-*.ts now covers all five helpers including token-refresh, and withRetry/withRetrySync exports match the WHERE TO LOOK entry. no code changed.

no files require special attention.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    LIB[lib/] --> CM[codex-manager/]
    LIB --> POL[policy/]
    LIB --> REQ[request/]
    LIB --> RT[runtime/]
    LIB --> TOP[top-level modules]

    CM --> FMT[formatters/ ← NEW\ntext/account/model/quota]
    CM --> SCMD[commands/]

    POL --> RPT[runtime-policy.ts ← NEW]

    REQ --> HLP[helpers/ ← NEW\nmodel-map, input/tool utils]
    REQ --> RLD[rate-limit-decision.ts ← NEW]
    REQ --> SFR[stream-failover-runtime.ts ← NEW]

    RT --> ROT[rotation-*.ts ← NEW\nselection/state/storage-meta\nserver-type/token-refresh]

    TOP --> FSR[fs-retry.ts ← NEW\nwithRetry / withRetrySync]
    TOP --> TMP[temp-path.ts ← NEW\ncrypto-random staging paths]
    TOP --> BGD[budget-guard.ts ← NEW]
    TOP --> LBR[local-bridge.ts ← NEW]
    TOP --> ERR[errors.ts\nCodexError hierarchy]

_{Reviews (2): Last reviewed commit: "docs: include token-refresh in the rotat..." | Re-trigger Greptile}

Context used:

• Context used - lib/AGENTS.md (source)