docs: align reasoning-effort values and model references#1199
docs: align reasoning-effort values and model references#1199TheFactoriousDROID wants to merge 3 commits into
Conversation
Document the label-to-value mapping (e.g. Extra High -> xhigh, Max -> max) as a single source of truth in settings.mdx, and point the CLI reference and choosing-your-model pages at it plus /models instead of duplicating per-model lists that drift. Also fix the stale 'Anthropic defaults to off' claim, nest model/reasoningEffort under sessionDefaultSettings, and refresh stale model names/examples. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Reverts docs/cli/user-guides/choosing-your-model.mdx to match main so this branch is scoped to the factual reasoning-effort settings and CLI reference updates. The page redesign is parked in a git stash for separate handling. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Drops the inaccurate claim that `dynamic` is an internal, non-selectable level (no CLI-available model exposes it, so CLI users never encounter it) and notes that the `max` label can render as Max or Maximum depending on surface. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
|
Droid finished @TheFactoriousDROID's task —— View job The doc updates look directionally correct and improve alignment with model-dependent reasoning levels. There are a couple of cross-doc inconsistencies (notably |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![factory-droid[bot]](https://avatars.githubusercontent.com/in/358017?s=60&v=4){kind=small}
| | Label | `settings.json` value | | ||
| | ------------ | --------------------- | | ||
| | Off / None | `off` / `none` | | ||
| | Minimal | `minimal` | |
There was a problem hiding this comment.
[P1] Reconcile reasoningEffort values across docs (missing dynamic)
docs/enterprise/hierarchical-settings-and-org-control.mdx documents sessionDefaultSettings.reasoningEffort as allowing dynamic, but the new table here omits it; please reconcile by either adding dynamic (if valid for settings.json) or explicitly calling out that dynamic is enterprise/API-only and not accepted in local CLI settings to avoid contradictory guidance.
| | `Ctrl+E` | Toggle the approval details view | | ||
| | `Ctrl+V` | Paste an image from the clipboard as an attachment | | ||
| | `Tab` | Cycle reasoning effort (`low` → `medium` → `high` → `off`) | | ||
| | `Tab` | Cycle reasoning effort through the levels supported by the current model | |
There was a problem hiding this comment.
[P1] Update other shortcut docs to match new Tab reasoning-effort behavior
This changes Tab to “cycle through the levels supported by the current model”, but docs/cli/user-guides/become-a-power-user.mdx still claims a fixed cycle (low → medium → high → off); aligning those docs will prevent users from assuming missing levels (e.g., minimal, xhigh, max) are unreachable via the TUI.
1 participant
Summary
Aligns the reasoning-effort and model documentation with the actual implementation (the
ReasoningEffortenum, settings schema, and model registry).docs/cli/configuration/settings.mdxoff/none,minimal,low,medium,high,xhigh,max— mapped to the labels shown in the model picker and the Available Models Reasoning column.sessionDefaultSettings.*(canonical), and note that legacy top-levelmodel,reasoningEffort,autonomyMode,specModeModel, andspecModeReasoningEffortare migrated automatically on load.maxmay display as Max or Maximum depending on surface.docs/reference/cli-reference.mdx-r,--worker-reasoning-effort, etc.) are model-dependent rather than a fixed value list.claude-opus-4-8in model-ID examples.Verified against the implementation: the
ReasoningEffortenum,SessionDefaultSettingsSchema/ManagedSettingsBaseSchema(session + org defaults),MissionModelSettingsSchema, and the model registry — and confirmed the samesessionDefaultSettingskeys are read by both the CLI and desktop/daemon.Test plan
Docs-only change; no code paths affected.