diff --git a/docs/docs/configure/config.md b/docs/docs/configure/config.md index 737d0e03ef..332bc5cb3c 100644 --- a/docs/docs/configure/config.md +++ b/docs/docs/configure/config.md @@ -24,6 +24,8 @@ Configuration is loaded from multiple sources, with later sources overriding ear !!! tip For most projects, create a `altimate-code.json` in your project root or use the `.altimate-code/` directory for a cleaner setup. +Project files named `altimate-code.json`, `altimate-code.jsonc`, `opencode.json`, or `opencode.jsonc` are read from the project root down to the working directory. Within that layer, the nearest directory wins and the branded names override the legacy names. In the later directory-config layer (`.altimate-code/` and `.opencode/`), the legacy names load after the branded names. JSONC overrides JSON for the same name in both layers. + ## Minimal Example ```json diff --git a/docs/docs/configure/models.md b/docs/docs/configure/models.md index baebe3cb19..fe462c86ce 100644 --- a/docs/docs/configure/models.md +++ b/docs/docs/configure/models.md @@ -16,7 +16,7 @@ altimate supports models from all configured providers. Use the `model` and `sma } ``` -The model format is `provider/model-name`. +The model format is `provider/model-name`. In `run`, sessions, and the TUI, an unavailable effective model produces an error instead of silently selecting another provider. Explicit selections include `--model`, the `model` field, agent and command configurations, and a session's recorded model. Only the selection that applies to the request is validated. The order is: a command's own model, then the command's agent, then a model in the request (`--model`), then the agent's configured model, then the session's recorded model, then the `model` field. So a resumed session keeps its model over the `model` field, but not over an agent that sets its own model. Correct that selection or choose an available model. Automatic model selection applies when there is no effective explicit selection. In the TUI, when `--model` or the `model` field sets the model, a model chosen with the picker applies to the current conversation only and does not change your config: a new conversation or a restart uses the configured model again, so update the config to make a choice permanent. Without a configured model, new conversations start on your most recent pick. When a submitted message is rejected because the configured chat model is unavailable, the TUI opens the picker so you can choose one for this conversation; a command that sets its own model shows the error without the picker, since a pick does not override it. `small_model` handles the small background requests that are not part of the conversation, such as the session title and prompt enhancement. When it is not set, Altimate Code picks a cheap model from the same provider (Claude Haiku, Gemini Flash or GPT-5 nano when the provider lists one) and otherwise uses the chat model. A `small_model` the provider cannot serve, or does not list, fails only those requests: chat keeps working, while new sessions keep their `New session -