From 0ae7fd766ea5872c946773662fe97674a1615472 Mon Sep 17 00:00:00 2001 From: roboomp Date: Sat, 13 Jun 2026 09:10:16 +0000 Subject: [PATCH] docs: documented project settings and disabled providers Added user-facing settings, providers, and context-file documentation for project config precedence, project-local settings files, disabledProviders model-provider behavior, and path-scoped provider settings. Fixes #2447 --- docs/context-files.md | 40 ++++++++++++++++ docs/providers.md | 67 +++++++++++++++++++++++++++ docs/settings.md | 104 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 211 insertions(+) create mode 100644 docs/context-files.md create mode 100644 docs/providers.md create mode 100644 docs/settings.md diff --git a/docs/context-files.md b/docs/context-files.md new file mode 100644 index 000000000..fd8303c98 --- /dev/null +++ b/docs/context-files.md @@ -0,0 +1,40 @@ +# Context files + +Context files are markdown files `omp` discovers and injects into the agent context so repository rules, project notes, and tool-specific instructions follow the session. + +## Native `.omp` files + +| File | Scope | Behavior | +|---|---|---| +| `/.omp/AGENTS.md` | Project | Project instructions loaded with the current directory. | +| `~/.omp/agent/AGENTS.md` | User | User-level instructions loaded from the agent directory. | +| `/.omp/RULES.md` | Project | Sticky always-apply rule content re-injected near the current turn. | +| `~/.omp/agent/RULES.md` | User | User-level sticky rule content. | + +Other discovery providers can contribute compatible context files from their own conventions, such as Claude, Codex, Gemini, and GitHub instruction files. + +## Discovery providers vs model providers + +`disabledProviders` is a setting, not a context-file field. It accepts provider IDs in a shared namespace: + +| Entry type | Examples | Effect | +|---|---|---| +| Model provider IDs | `anthropic`, `openai`, `gemini`, `groq`, `ollama`, `openrouter` | Prevent those model providers from becoming selectable, even when credentials are present. | +| Discovery provider IDs | `native`, `claude`, `codex`, `gemini`, `github` | Prevent that capability provider from contributing context files, commands, hooks, tools, prompts, or other capability items. | + +Most provider-control use cases should list model provider IDs. Use discovery provider IDs only when you intend to disable an entire config source. + +```yaml +# Disable model providers in this project. +disabledProviders: + - anthropic + - openai +``` + +```yaml +# Disable the Claude discovery source entirely. +disabledProviders: + - claude +``` + +Project-level values are configured in `/.omp/config.yml`; global values live in `~/.omp/agent/config.yml`. See [Settings](./settings.md) for precedence and array replacement behavior. diff --git a/docs/providers.md b/docs/providers.md new file mode 100644 index 000000000..0915735c7 --- /dev/null +++ b/docs/providers.md @@ -0,0 +1,67 @@ +# Providers + +Providers are the model backends `omp` can route requests to: Anthropic, OpenAI, Gemini, Groq, Ollama, OpenRouter, custom `models.yml` providers, and extension-registered providers. + +## Credentials + +Provider credentials can come from stored auth, OAuth, `models.yml`, or environment variables. `omp` eagerly reads `.env` files at startup, including the current project's `/.env`, so provider API keys in a project directory can make those providers available without any additional config. + +Common environment variables include: + +| Provider | Environment variable | +|---|---| +| Anthropic | `ANTHROPIC_API_KEY` | +| OpenAI | `OPENAI_API_KEY` | +| Gemini | `GEMINI_API_KEY` | +| Groq | `GROQ_API_KEY` | +| OpenRouter | `OPENROUTER_API_KEY` | + +## Disabling model providers + +Use the `disabledProviders` setting to make a model provider unavailable, even if credentials exist in `.env` or stored auth: + +```yaml +# ~/.omp/agent/config.yml or /.omp/config.yml +disabledProviders: + - anthropic + - openai + - gemini + - groq +``` + +Project settings replace the global `disabledProviders` array. To disable a different set in one repository, put that complete set in `/.omp/config.yml`. + +```yaml +# ~/.omp/agent/config.yml +disabledProviders: + - anthropic + - openai + - gemini + +# /.omp/config.yml +disabledProviders: + - groq +``` + +Effective result inside the project: only `groq` is disabled. + +For configuration file locations and precedence, see [Settings](./settings.md). + +## Path-scoped provider settings + +Scope `disabledProviders` to a directory with `path:` when only one subtree needs different provider availability: + +```yaml +disabledProviders: + - ollama + - path: ~/projects/sensitive + providers: + - anthropic + - openai +``` + +String entries apply everywhere. Scoped entries apply when the current working directory is the configured path or one of its subdirectories. + +## Custom providers + +Custom providers live in `~/.omp/agent/models.yml`. See [Model and Provider Configuration](./models.md) for the full `models.yml` schema, runtime discovery options, provider overrides, and model resolution behavior. diff --git a/docs/settings.md b/docs/settings.md new file mode 100644 index 000000000..3d79f3a34 --- /dev/null +++ b/docs/settings.md @@ -0,0 +1,104 @@ +# Settings + +`omp` reads settings from global files, project files, one-shot config overlays, and runtime inputs. Use project settings when one repository needs a different provider set, model role, tool policy, or UI setting than your global defaults. + +## Files + +| Scope | Path | Notes | +|---|---|---| +| Global | `~/.omp/agent/config.yml` | Main persistent settings file. `/settings` and `omp config set` write here. | +| Global legacy | `~/.omp/agent/settings.json` | Migrated to `config.yml` when possible. | +| Project | `/.omp/config.yml` | Recommended per-project override file. Read from the process cwd's `.omp/` directory. | +| Project legacy | `/.omp/settings.json` | Still supported for project settings. | +| Overlay | Any YAML file passed with `--config ` | Applies only to that process and is not persisted. Repeat `--config` to layer files. | + +Project settings are read-only from discovery: changing settings through `/settings` or `omp config set` updates the global file, not `/.omp/config.yml`. + +## Precedence + +Highest priority wins: + +1. Runtime overrides and dedicated CLI flags (`--slow`, `--no-pty`, `--api-key`, etc.) +2. Environment variables for fields that define env fallbacks (`PI_SLOW_MODEL`, provider API keys, etc.) +3. CLI config overlays (`--config `, later files override earlier files) +4. Project settings (`/.omp/settings.json`, then `/.omp/config.yml`; `config.yml` wins within the project layer) +5. Global settings (`~/.omp/agent/config.yml`) +6. Built-in defaults + +The settings merge itself is: + +```text +defaults <- global <- project <- CLI config overlays <- runtime overrides +``` + +Environment variables are not written into config files; they are consulted by the feature that owns the setting or credential. + +## Project settings + +Put a config file in a project's `.omp/` directory to override global settings only for sessions launched from that directory: + +```yaml +# /.omp/config.yml +disabledProviders: + - groq +modelRoles: + default: anthropic/claude-sonnet-4-5 + smol: openai/gpt-5.3-mini +``` + +Objects are deep-merged. Arrays are replaced wholesale by the higher-precedence layer. + +```yaml +# ~/.omp/agent/config.yml +disabledProviders: + - anthropic + - openai + - gemini + +# /.omp/config.yml +disabledProviders: + - groq +``` + +Effective result in that project: + +```json +["groq"] +``` + +The project array replaces the global array; it does not append to it. In this example, `anthropic`, `openai`, and `gemini` are re-enabled for the project. + +## `disabledProviders` + +`disabledProviders` accepts provider IDs. It disables model providers such as `anthropic`, `openai`, `gemini`, `groq`, `openrouter`, `ollama`, and extension-registered model providers. The same setting also gates capability discovery providers when the entry matches a discovery provider ID such as `native`, `claude`, `codex`, or `gemini`. + +Use model provider IDs when you want to prevent a provider from becoming selectable even if credentials are available from `.env`, OAuth, or stored auth. + +```yaml +disabledProviders: + - anthropic + - openai + - gemini + - groq +``` + +## Path-scoped arrays + +`enabledModels` and `disabledProviders` can include entries scoped to a path prefix: + +```yaml +enabledModels: + - claude-sonnet-4-5 + - path: ~/work/high-context + models: + - anthropic/claude-opus-4-5 + +disabledProviders: + - ollama + - path: ~/projects/sensitive + providers: + - anthropic + - openai +``` + +String entries apply everywhere. Scoped entries apply when the current working directory is the configured path or one of its subdirectories. Accepted path keys: `path`, `paths`, `pathPrefix`, `pathPrefixes`. Use `models` for `enabledModels`, `providers` for `disabledProviders`, or `values` for either.