docs: Enforce GPT 5.1 full-opencode.json as only supported configuration

[numman-ali]

Summary

This PR standardizes the OpenCode Codex plugin on GPT 5.1 model identifiers, removes deprecated GPT 5.0 models, and enforces config/full-opencode.json as the only officially supported configuration. We now strongly discourage minimal configurations and custom setups due to GPT 5 models' temperamental behavior. All documentation has been updated to reflect the new model naming (gpt-5.1-codex-*), updated context limits for Codex Mini, and comprehensive warnings about configuration requirements. The changes ensure users have a reliable, tested setup that works consistently with OpenCode features.

Key Changes

🏷️ Model Naming & Configuration Updates

• Updated all model IDs from gpt-5-codex-* → gpt-5.1-codex-* in config/full-opencode.json
• Updated display names from "GPT 5 Codex..." → "GPT 5.1 Codex..."
• Removed deprecated GPT 5.0 models: gpt-5-minimal, gpt-5-mini, gpt-5-nano (being phased out by OpenAI)
• Updated Codex Mini context limits from 200k/100k → 272k/128k tokens to match current API specs
• Now shipping 8 verified GPT 5.1 variants instead of 11 mixed 5.0/5.1 models

⚠️ Documentation: Enforce full-opencode.json as Required Config

• README.md: Changed "Recommended" → "⚠️ REQUIRED: Full Configuration (Only Supported Setup)"

  • Added explicit warnings about GPT 5 models being temperamental
  • Marked minimal config section as "❌ NOT RECOMMENDED - DO NOT USE"
  • Added detailed "Why this doesn't work" explanations
  • Updated all code examples to use GPT 5.1 model IDs
  • Updated model variant table with correct GPT 5.1 naming and temperamental behavior warnings

• docs/getting-started.md: Restructured installation guide

  • Changed "Option A: Full Configuration (Recommended)" → "⚠️ REQUIRED: Full Configuration (Only Supported Setup)"
  • Removed "Option B: Minimal Configuration" - replaced with "❌ Minimal Configuration (NOT SUPPORTED - DO NOT USE)"
  • Added comprehensive warnings about GPT 5 models requiring proper configuration
  • Updated all examples to GPT 5.1 models

• docs/configuration.md: Enhanced configuration guidance

  • Added warnings throughout about using official full-opencode.json
  • Updated "Recommended" → "⚠️ REQUIRED: Use Pre-Configured File"
  • Added migration guide showing GPT 5.0 → GPT 5.1 upgrade path
  • Added warnings on custom configurations not being supported
  • Updated all examples to GPT 5.1 models

• docs/index.md: Updated features and warnings

  • Updated features list to emphasize verified configuration
  • Added prominent warning about GPT 5 models being temperamental
  • Noted GPT 5.0 model deprecation

• config/README.md: Complete restructure

  • Changed from "Configuration Examples" → "Configuration" with required emphasis
  • Marked minimal-opencode.json as NOT SUPPORTED
  • Marked full-opencode-gpt5.json as DEPRECATED
  • Added explicit "DO NOT USE" section for other configurations
  • Clear explanation of why other configs don't work (missing metadata, no OpenCode feature support)

🔧 Technical & Code Updates

• Updated AGENTS.md with correct model normalization flow (5.0 and 5.1 families)
• Updated CHANGELOG.md to document GPT 5.1 family support and config changes
• All test examples and documentation snippets now use gpt-5.1-codex-* naming
• Updated usage examples: --model=openai/gpt-5.1-codex-low throughout

Implementation Details

1. GPT 5 Model Temperamental Behavior
   Added consistent warnings that GPT 5 models can be temperamental - some variants work, some don't, some may error. This is why the full, tested configuration is required rather than allowing users to create custom setups.

2. Configuration Enforcement
   All documentation now explicitly states that config/full-opencode.json is the ONLY supported configuration. Minimal configs lack the per-model limit metadata required for OpenCode's auto-compaction and usage sidebar features, and custom configs may not work reliably with temperamental GPT 5 models.

3. Model Migration Path
   Clear guidance for users to migrate from deprecated GPT 5.0 models to GPT 5.1:

   • Old: gpt-5-codex-low → New: gpt-5.1-codex-low
   • Old: gpt-5-mini, gpt-5-nano → Removed (deprecated)
   • All configs must be updated to use the new 5.1 identifiers

4. Context Limit Corrections
   Updated Codex Mini from incorrect 200k/100k to correct 272k/128k context/output limits, matching the actual API specifications and ensuring OpenCode displays accurate token usage.

Testing

• Verified all model ID updates match config/full-opencode.json
• Confirmed all documentation examples use correct GPT 5.1 naming
• Ensured warnings about temperamental behavior are consistent across all docs
• Validated migration path from GPT 5.0 to GPT 5.1 is clear
• Checked that all references to deprecated models are removed or marked as such

---

Note: This PR focuses on documentation and configuration alignment. No code logic changes - just standardizing on GPT 5.1 models and enforcing the tested, reliable configuration path for users.

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]