docs(compaction): ceiling doesn't document limit.input vs limit.context precedence; context-only limit overrides are a silent no-op #52954

Description

The V2 docs never specify which model limit drives the automatic-compaction ceiling. In v2.0.22 the code computes the ceiling from limit.input || limit.context (packages/core/src/session/compaction.ts, calculateCeiling, reserve = max(window * 0.1, 16_000)). For split-window models (catalog input < context), auto-compaction therefore targets the input window, and a user config limit override of only context silently does not change the ceiling — the override must set both fields. This makes the workaround for #44821 undiscoverable from the docs.

Environment

• Docs pages checked (2026-10-03): /v2/docs/compaction, /v2/docs/config, /v2/docs/providers, /v2/docs/models
• Behavior verified against: opencode v2.0.22 source (packages/core/src/session/compaction.ts, packages/core/src/config/plugin/provider.ts) and a running v2.0.22 instance (/api/model)
• OS: Windows x64 (docs issue; behavior verified locally on this platform)

Reproduction

1. Read /v2/docs/compaction: "When a session approaches the model's context limit..." — no mention of limit.input vs limit.context.
2. Configure a split-window model override raising only context, e.g. providers.openai.models."gpt-6.1-sol".limit = { "context": 1050000 } while the effective catalog input is clamped to 272000 by the ChatGPT OAuth transform (see fix(openai): OAuth transform treats Codex product budget as endpoint context limit #44821).
3. Observe that auto-compaction still fires near the input-based ceiling (272000 − max(27200, 16000) = 244800), not near the configured context — the context-only override is a silent no-op for compaction.

Expected Behavior

The docs should state:

1. Which limit drives the automatic-compaction ceiling (limit.input first, falling back to limit.context in 2.0.22).
2. The reserve formula, including the undocumented 16,000-token floor (RESERVE_MIN) below the documented "10% of the limit".
3. That model limit config is merged per field ({ ...catalog.limit, ...config.limit }), so an override intended to move the compaction ceiling must set both context and input.

Actual Behavior

• /v2/docs/compaction says "approaches the model's context limit" — ambiguous, and contradicted by:
• /v2/docs/config, Compaction section: "Automatic compaction uses the selected model's usable input budget" — the only hint about input-vs-context anywhere, and it uses different wording than /compaction.
• buffer default is documented as "10% of the limit" (/compaction) but the effective reserve is max(10%, 16_000); the /config example shows "buffer": 20000 without noting that it is not the default.

Additional Context

• Source refs (v2.0.22): calculateCeiling in packages/core/src/session/compaction.ts; per-field limit merge in packages/core/src/config/plugin/provider.ts (if (config.limit !== undefined) model.limit = { ...model.limit, ...config.limit }).
• Note for versioning: the dev branch calculation changed to use context only, so the docs should either describe the versioned behavior or the behavior should be unified — today a doc sentence that is correct for one version is wrong for the other.
• Practical impact observed in the wild: users hitting fix(openai): OAuth transform treats Codex product budget as endpoint context limit #44821 (1M-context OpenAI models compacting at ~245k) could not discover from the docs that the workaround requires overriding both fields; a context-only override appears to "not work".
• Suggested placement: a short "Ceiling" subsection in /v2/docs/compaction (which limit + formula + reserve floor + override guidance), plus one sentence in /v2/docs/models near the limit field.

Cross-refs: #44821, #51251, #43703