ur-agent 1.68.18 → 1.69.0

package/technical/05-providers-and-models.md

@@ -1,195 +0,0 @@
-# 05 — Providers & Models
-
-Source of truth: `src/services/providers/providerRegistry.ts`, `src/utils/model/*`,
-`src/services/agents/{modelPool,modelRouter,escalation}.ts`, `src/commands/{model,provider,connect,effort,fast}`.
-
-## Provider registry (`PROVIDERS` in providerRegistry.ts)
-
-| Provider id | Display name | Access | Credential | Status |
-|---|---|---|---|---|
-| `ollama` | Ollama | local runtime | none (localhost:11434) | **default local backend** |
-| `llama.cpp` | llama.cpp | local/server | OpenAI-compatible endpoint (localhost:8080/v1) | enabled |
-| `vllm` | vLLM | server | OpenAI-compatible endpoint (localhost:8000/v1) | enabled |
-| `openai-compatible` | OpenAI-compatible | server/api | any base URL + optional `OPENAI_COMPATIBLE_API_KEY` | enabled |
-| `openai-api` | OpenAI API | api | `OPENAI_API_KEY` | enabled |
-| `anthropic-api` | Claude API | api | `ANTHROPIC_API_KEY` | enabled |
-| `gemini-api` | Gemini API | api | `GEMINI_API_KEY` | enabled |
-| `openrouter` | OpenRouter | api | `OPENROUTER_API_KEY` | enabled |
-| `subscription` | Subscription | subscription login | OAuth | placeholder |
-| `codex-cli` | Codex CLI | subscription via official CLI | `codex login` | `disabled: true` in registry |
-| `claude-code-cli` | Claude Code | subscription via official CLI | `claude auth login` | `disabled: true` |
-| `gemini-cli` | Gemini CLI | subscription via official CLI (Code Assist Std/Ent only) | — | `disabled: true` |
-| `antigravity-cli` | Antigravity | subscription via official CLI | — | `disabled: true` |
-| `lmstudio` | LM Studio | local server | OpenAI-compatible (localhost:1234/v1) | `disabled: true` |
-
-Provider aliases are normalized by provider commands and interactive pickers (e.g.
-`chatgpt`, `codex`, `openai codex` → `codex-cli`). Raw `settings.json` is stricter:
-`provider.active` and `provider.fallback` must use canonical registry IDs. Each definition
-declares capability metadata (native tool calls, native streaming, safety boundary label)
-used by the runtime and `/provider` UI. UR-native adapters—including LM Studio—use the
-UR-native request/tool boundary and never inherit an external subscription-CLI capability
-record.
-
-### How to use
-
-```
-/provider                 # interactive picker
-/provider ollama          # switch provider
-/connect status           # show all provider connection states
-/connect openrouter --key sk-or-…    # store an API key (keychain-backed)
-/connect logout openrouter
-ur provider models openrouter        # list models a provider serves
-ur provider doctor ollama            # diagnose connectivity
-```
-
-## Ollama Cloud and the deployment enum
-
-**Authentication.** The Ollama client sends `Authorization: Bearer` when
-`OLLAMA_API_KEY` is set, and nothing otherwise. A local daemon needs no
-credential — it holds the account itself, which is how `:cloud` model suffixes
-resolve locally. A direct connection to the hosted API does need one, which is
-why CI (with no signed-in daemon) previously could not use Ollama at all. The
-key is trimmed, so a pasted trailing newline cannot corrupt the header, and
-read per request so a rotated key applies without restarting.
-
-Base-URL precedence: session override → `OLLAMA_HOST` / `OLLAMA_BASE_URL` →
-`ollama.host` setting → `https://ollama.com` when a key is set with no host →
-`http://localhost:11434`. An explicit host always wins, so self-hosted
-gateways that require a key are unaffected.
-
-`OLLAMA_API_KEY` is on the Agentic CI provider-credential allowlist, so it
-reaches the isolated agent while platform write tokens do not.
-
-**`APIProvider` is not the provider registry.** It is a deployment enum for
-request shaping, narrowed to `'foundry' | 'ollama'` — the only values
-`getAPIProvider()` can return. Comparisons against `'firstParty'`, `'bedrock'`
-or `'vertex'` were silently false and disabled advertised features; the
-typechecker now rejects them. Where such a branch is genuinely wanted, use the
-named predicates `isFirstPartyRuntime()`, `isBedrockRuntime()` and
-`isVertexRuntime()` (all currently `false`) so the intent stays greppable.
-`DeploymentKey` widens the type for legacy per-deployment lookup tables in
-`configs.ts`, `deprecation.ts` and `modelStrings.ts`, which carry rows for
-deployments this build cannot select.
-
-## Model selection
-
-```
-/model                    # interactive model picker for current provider
-/model qwen2.5-coder:7b
-ur --model llama3.3       # per-session
-ur --ollama-host http://gpu-box:11434    # remote Ollama server
-ur --discover-ollama      # scan the LAN for Ollama servers (ollamaDiscovery.ts)
-```
-
-- `startupModelSelection.ts` distinguishes deliberate model sources from
-  silent defaults. With no project/local/flag/managed, CLI/environment, agent,
-  or restored-session model, interactive startup requires
-  `ProviderFirstModelPicker`; headless startup exits before model execution.
-- The startup picker validates the provider/model pair through the provider
-  registry and persists it to `.ur/settings.local.json`. User-global model
-  settings are intentionally insufficient for a new workspace.
-- `settings.json → model`, `provider.active`, top-level `availableModels`, and top-level
-  `modelOverrides` persist choices per scope.
-- `src/utils/model/aliases.ts` maps friendly aliases; `validateModel.ts` checks against the
-  provider's discovered list; `ollamaTuning.ts` adjusts context/params for local models.
-- Deprecation warnings and 1M-context upgrade checks live in `deprecation.ts` /
-  `check1mAccess.ts`.
-- Ollama remains the default provider endpoint, but no model is silently chosen
-  for a fresh workspace. Configured Ollama base URLs are honored consistently.
-- OpenAI-compatible endpoints use a dedicated credential key so an OpenAI API
-  key is never forwarded to an arbitrary compatible base URL. Provider switches
-  clear stale endpoint/command overrides.
-- Request adapters preserve system prompts, tools, images, stops, sampling,
-  reasoning, metadata, and structured-output settings supported by each
-  provider. Provider error payloads, empty responses, and truncated streams fail
-  instead of becoming synthetic empty successes.
-- OpenAI API keeps Chat Completions as the default. Setting
-  `provider.openaiTransport` through
-  `ur config set openai_transport responses` selects the native Responses
-  adapter with `store=false` by default, semantic SSE, background
-  retrieve/poll/cancel, WebSocket continuation, compaction, deferred tool
-  search, and bounded private cursor state. Compacted context persistence
-  requires a 32-byte `UR_OPENAI_RESPONSES_STATE_KEY`.
-- `ollama.ts` selects timeouts from explicit request options, then
-  `API_TIMEOUT_MS`, then runtime defaults. Remote sessions and ordinary
-  `:cloud` models use 120 seconds; local models and Kimi K2.7 Cloud use 300
-  seconds because large Kimi coding turns can legitimately take longer than
-  two minutes before completing. The same model-aware value is applied while
-  waiting for `/api/chat` response headers and as the absolute deadline in
-  `readOllamaChunks`.
-- `ur.ts` identifies an Ollama Cloud runtime from both the selected provider and
-  the `:cloud` suffix. It disables shared automatic request retries for that
-  route, applies the same model-aware bound to any permitted non-streaming
-  fallback, and skips fallback entirely when the Ollama stream deadline itself
-  caused the failure. Explicit `API_TIMEOUT_MS` remains authoritative, and
-  remote-session safety keeps its 120-second ceiling.
-
-## Capability-aware routing
-
-### Model pools (`src/services/agents/modelPool.ts`)
-Pools named `cheap` / `strong` / `default`, loaded in priority order:
-1. `.ur/model-pool.json` in the repo — e.g. `{"cheap":["gemma2:2b"],"strong":["gpt-5.5"]}`
-2. Env: `UR_MODEL_POOL_CHEAP`, `UR_MODEL_POOL_STRONG`, `UR_MODEL_POOL_DEFAULT` (comma lists)
-3. Defaults: cheap `qwen2.5-coder:1.5b, gemma2:2b`; strong `qwen2.5-coder:32b, codex,
-   claude-3-5-sonnet, gpt-4o`; default `qwen2.5-coder`.
-
-### `/model-route` (modelRouter.ts)
-Classifies a task and recommends a model + strategy:
-```
-/model-route "port this service to Rust" --strategy strong
-/model-route "rename a variable" --strategy auto --json
-```
-
-### `/escalate` (escalation.ts)
-Run on a fast model, auto-escalate hard steps to an "oracle":
-```
-/escalate plan "design a consensus protocol"       # show the split
-/escalate run "…" --fast qwen2.5-coder:7b --oracle gpt-5.5
-/escalate policy                                    # view escalation policy
-```
-
-### `/model-doctor` (ollamaModels.ts + modelCapabilities.ts)
-Probes an installed Ollama model: tool-call support, context length, speed class, and
-reports "likely agent capabilities":
-```
-/model-doctor llama3.3 --json
-```
-
-### Automatic learning loop (learning.ts)
-Every ci-loop, arena, escalation, test-first, and completed **local** cloud
-best-of-N run
-**automatically** records its pass/fail outcome (per task category and model) into
-`.ur/learning/stats.json` — a pure JSON fold, no model calls. The `auto` routing strategy
-and `/escalate`'s difficulty bias consume this evidence: a model with ≥3 recorded runs and
-a ≥60% success rate for the task's category is preferred when selectable; thin evidence
-falls back to the static heuristics unchanged. The store is idempotent (outcome keys
-dedupe) and best-effort (a broken store never fails a run). `/learn` remains for
-inspection and the optional LLM reflection pass:
-```
-/learn stats            # view what the agent has learned
-/learn run --reflect    # optional: distill failures into lessons (uses a model)
-```
-Disable automatic learning with `automaticLearningEnabled: false` or
-`UR_CODE_DISABLE_AUTO_LEARNING=1`.
-
-## Session behavior knobs
-
-| Feature | Command | Notes |
-|---|---|---|
-| Effort level | `/effort low·medium·high·max·auto` | low/medium/high persist as `effortLevel`; max is session-only in the external build; auto clears the override |
-| Fast mode | `/fast` source exists but reports unavailable | requires the hosted first-party serving tier, which the standard npm build does not use; setting `fastMode` cannot manufacture that tier |
-| Advisor model | `/advisor` is hidden in the standard build | requires first-party beta headers plus an enabled runtime feature configuration; `advisorModel` alone does not enable it |
-| Always thinking | `alwaysThinkingEnabled` setting | force extended thinking |
-| Thinking summaries | `showThinkingSummaries` setting | UI display of thinking |
-| Fallback model | `--fallback-model` (print mode) | on overload |
-
-## Offline / local-first
-
-- `ur --offline` or `offline` setting: no cloud APIs, telemetry, auto-update, remote control.
-- Offline dispatch permits only loopback local/server endpoints; cloud,
-  subscription, remote Ollama, and remote compatible endpoints are blocked.
-- `/local-first` reports readiness for no-cloud/private/lab/edge deployment: which features
-  degrade, which local deps (Ollama, ripgrep, playwright, ffmpeg…) are present.
-- `--bare` forces the minimal local pipeline (`UR_CODE_SIMPLE=1`) and always uses Ollama.
-- Ollama config: `ollama.host` and `ollama.lanDiscovery` settings; per-session
-  `--ollama-host`; router in `ollamaRouter.ts` load-balances across discovered hosts.

package/technical/06-configuration.md

@@ -1,428 +0,0 @@
-# 06 — Configuration
-
-Source of truth: `src/utils/settings/{types.ts,constants.ts,settings.ts}`,
-`src/utils/hooks/`, `src/keybindings/`, `src/utils/permissions/`.
-
-## Settings scopes (later overrides earlier)
-
-| Scope | File | Notes |
-|---|---|---|
-| user | `~/.ur/settings.json` | global |
-| project | `.ur/settings.json` | shared, committed |
-| local | `.ur/settings.local.json` | gitignored |
-| flag | `--settings <file-or-json>` | per-invocation |
-| managed/policy | managed-settings.json or remote org settings | read-only, always loaded |
-
-`--setting-sources user,project,local` restricts which editable scopes load.
-Schema URL for editors: `https://json.schemastore.org/ur-settings.json`.
-
-Edit interactively with `/config`, by natural language with `/update-config`
-(bundled skill), or directly in the JSON files.
-
-Model selection has one intentional exception to ordinary merged precedence:
-a user-global model alone does not initialize a fresh workspace. Interactive
-startup requires a provider/model choice and writes it to
-`.ur/settings.local.json`; fresh headless startup requires `--model`, a model
-environment variable, or project/flag/managed configuration. Resumed sessions
-restore their session model without showing the picker.
-
-## settings.json keys (from `SettingsSchema`, `src/utils/settings/types.ts`)
-
-### Model & provider
-```jsonc
-{
-  "model": "qwen2.5-coder:7b",
-  "provider": {
-    "active": "ollama",
-    "model": "qwen2.5-coder:7b",
-    "baseUrl": "http://localhost:11434",
-    "timeoutMs": 30000,
-    "fallback": "disabled",
-    "openaiTransport": "responses", // chat-completions (default) | responses
-    "responses": {
-      "store": false,
-      "compactThreshold": 20000,
-      "toolSearch": "hosted"        // off (default) | hosted
-    },
-    "preferences": {}
-  },
-  "ollama": { "host": "http://localhost:11434", "lanDiscovery": true },
-  "offline": false,
-  "effortLevel": "high",
-  "fastMode": false, "fastModePerSessionOptIn": false,
-  "advisorModel": "qwen2.5-coder:32b",
-  "alwaysThinkingEnabled": false, "showThinkingSummaries": true,
-  "availableModels": [], "modelOverrides": {}
-}
-```
-
-### Permissions & safety
-```jsonc
-{
-  "permissions": {
-    "allow": ["Bash(git:*)", "Read", "WebFetch(domain:docs.example.com)"],
-    "deny":  ["Bash(rm -rf:*)", "mcp__untrusted-server"],
-    "ask":   ["Bash(git push:*)"],
-    "additionalDirectories": ["../lib"],
-    "defaultMode": "acceptEdits",       // default | plan | acceptEdits | autoApprove | bypassPermissions
-    "profiles": {                       // named rule sets, appended when active
-      "reviewing": { "deny": ["Edit", "Write", "Bash"], "description": "read-only" },
-      "trusted":   { "allow": ["Bash(git:*)"] }
-    },
-    "activeProfile": "reviewing"        // switch with /permission-profile use <name>
-  },
-  "agents": {                           // subagent fan-out limits (doc 09)
-    "maxDepth": 3,                      // default 3, hard ceiling 10
-    "maxConcurrent": 20                 // default 20, hard ceiling 100
-  },
-  "voice": {                            // end-of-turn speech, off by default
-    "speakResponses": false,
-    "name": "Samantha", "rate": 210
-  },
-  "memory": {                           // end-of-turn suggestions, off by default
-    "suggest": false,
-    "suggestMinConfidence": 0.75
-  },
-  "sandbox": { /* SandboxSettingsSchema — OS sandbox for shell commands */ },
-  "tasks": {
-    "requireBeforeChanges": {
-      "enabled": true,                  // default: true
-      "freeReads": 3                    // calls allowed before ordinary mutations require a plan
-    }
-  },
-  "disableAutoMode": "disable",
-  "skipDangerousModePermissionPrompt": false,
-  "allowManagedPermissionRulesOnly": false
-}
-```
-Profiles are appended to the base `allow`/`deny`/`ask` lists from the same
-settings source, so a profile can only narrow or extend — `deny` still beats
-`allow`. A missing or misnamed `activeProfile` contributes nothing rather than
-failing open. `/permission-profile use <name>` writes the switch to whichever
-source defines the profile, so it lands beside its definition.
-
-Fan-out limits clamp rather than disable: out-of-range, negative and
-non-numeric values fall back to the default or the ceiling, so a settings file
-cannot switch the governor off.
-
-### Global app compaction controls
-
-`autoCompactEnabled` and `compaction.autoThreshold` are global app controls
-managed by `/config` or the `Config` tool and persisted in the global UR
-configuration (`~/.ur.json`, or `.config.json` in a legacy UR config home).
-They are not keys in the project `settings.json` schema.
-
-```text
-autoCompactEnabled = true
-compaction.autoThreshold = 80
-```
-
-The threshold accepts an inclusive percentage from 50 through 95. It is
-applied to the effective model context window and retains a 3,000-token manual
-compaction reserve. `UR_AUTOCOMPACT_PCT_OVERRIDE` has higher precedence for
-the current process; `DISABLE_AUTO_COMPACT` or `DISABLE_COMPACT` disables the
-proactive trigger. `/context` and the prompt notification report an
-approximate percentage left to this same resolved threshold; the active query
-may free additional context through bounded pruning immediately before the
-trigger.
-
-Rule syntax: `ToolName` (blanket) or `ToolName(specifier)` — e.g. `Bash(npm run *)`,
-`Edit(src/**)`, `mcp__server__tool`. Managed via `/permissions` UI as well.
-
-Permission modes:
-- `default`: normal permission checks; operations that need review ask first.
-- `plan`: planning-only mode until the user approves execution.
-- `acceptEdits`: auto-approve safe in-workspace file edits and safe commands.
-- `autoApprove`: auto-approve command/tool permission approvals, while
-  user-input dialogs still ask and explicit denials remain enforced.
-- `bypassPermissions`: bypass permission prompts after the separate dangerous-mode
-  acknowledgement/CLI opt-in; use only in an external sandbox with no sensitive access.
-
-`autoMode`, `useAutoModeDuringPlan`, `skipAutoPermissionPrompt`, and
-`permissions.disableAutoMode` exist only in builds compiled with
-`TRANSCRIPT_CLASSIFIER`; `classifierPermissionsEnabled` is additionally internal-only.
-The standard npm build accepts `autoApprove`, which is deterministic permission approval,
-not model-based classification.
-
-### Hooks
-```jsonc
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash",
-        "hooks": [ { "type": "command", "command": "./scripts/lint-command.sh" } ] }
-    ],
-    "PostToolUse": [], "UserPromptSubmit": []
-  },
-  "disableAllHooks": false,
-  "allowManagedHooksOnly": false,
-  "allowedHttpHookUrls": [], "httpHookAllowedEnvVars": []
-}
-```
-Hook events (`src/entrypoints/sdk/coreTypes.ts:HOOK_EVENTS`): `PreToolUse`, `PostToolUse`,
-`PostToolUseFailure`, `Notification`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`,
-`Stop`, `StopFailure`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PostCompact`,
-`PermissionRequest`, `PermissionDenied`, `Setup`, `TeammateIdle`, `TaskCreated`,
-`TaskCompleted`, `Elicitation`, `ElicitationResult`, `ConfigChange`, `WorktreeCreate`,
-`WorktreeRemove`, `InstructionsLoaded`, `CwdChanged`, `FileChanged`, `BeforeEdit`,
-`AfterEdit`, `BeforeCommand`, `AfterCommand`, `BeforeCommit`, `OnFailure`.
-Hook types: `command` (shell), plus prompt/agent hooks (`execPromptHook.ts`,
-`execAgentHook.ts` — run a model prompt or subagent as the hook). View with `/hooks`.
-
-### MCP policy
-```jsonc
-{
-  "enableAllProjectMcpServers": false,
-  "enabledMcpjsonServers": [], "disabledMcpjsonServers": [],
-  "allowedMcpServers": [], "deniedMcpServers": [],
-  "allowManagedMcpServersOnly": false
-}
-```
-
-Server definitions do not live under `mcpServers` in `settings.json`; configure them through
-`ur mcp` / `.mcp.json`. The keys above are approval and enterprise-policy controls.
-
-### Git & attribution
-```jsonc
-{
-  "attribution": {
-    "commit": "Co-authored-by: UR-Nexus <noreply@example.invalid>",
-    "pr": "Generated with UR-Nexus"
-  },
-  "includeCoAuthoredBy": true,
-  "includeGitInstructions": true
-}
-```
-
-### UI & terminal
-```jsonc
-{
-  "statusLine": { "type": "command", "command": "./scripts/status.sh", "padding": 1 },
-  "language": "en",
-  "spinnerTipsEnabled": true, "spinnerVerbs": { "mode": "append", "verbs": [] },
-  "spinnerTipsOverride": { "excludeDefault": false, "tips": [] },
-  "syntaxHighlightingDisabled": false,
-  "terminalTitleFromRename": true,
-  "prefersReducedMotion": false,
-  "outputStyle": "…",                 // output style name (src/outputStyles)
-  "promptSuggestionEnabled": true,
-  "showClearContextOnPlanAccept": true,
-  "feedbackSurveyRate": 1
-}
-```
-
-`theme` is global application config managed by `/theme`, not a `SettingsSchema` key.
-
-### Memory & verification
-```jsonc
-{
-  "autoMemoryEnabled": true, "autoMemoryDirectory": "~/.ur/project-memory",
-  "autoMemoryExtractionInterval": 1,   // run extraction every N turns (token dial)
-  "automaticLearningEnabled": true,    // local outcome stats, no model calls
-  "verifier": { "askBeforeGates": true }, // one approval request per user turn
-  "autoDreamEnabled": false,
-  "plansDirectory": ".ur/plans"
-}
-```
-
-### Plugins & marketplaces
-```jsonc
-{
-  "enabledPlugins": { "fmt@acme": true },
-  "pluginConfigs": {},
-  "extraKnownMarketplaces": {},
-  "strictKnownMarketplaces": [
-    { "source": "github", "repo": "acme/approved-plugins" }
-  ],
-  "blockedMarketplaces": [],
-  "strictPluginOnlyCustomization": false
-}
-```
-
-### Auth, org & misc
-```jsonc
-{
-  "apiKeyHelper": "./get-key.sh",
-  "awsCredentialExport": "./scripts/aws-env.sh",
-  "awsAuthRefresh": "./scripts/aws-refresh.sh",
-  "gcpAuthRefresh": "gcloud auth application-default login",
-  "forceLoginMethod": "urai",
-  "forceLoginOrgUUID": "00000000-0000-0000-0000-000000000000",
-  "otelHeadersHelper": "./scripts/otel-headers.sh",
-  "env": { "FOO": "bar" },              // extra env for the session
-  "companyAnnouncements": [],
-  "remote": { "defaultEnvironmentId": "dev-lab" },
-  "autoUpdatesChannel": "stable",
-  "minimumVersion": "1.65.6",
-  "cleanupPeriodDays": 30,
-  "fileSuggestion": { "type": "command", "command": "./scripts/files.sh" },
-  "respectGitignore": true,
-  "defaultShell": "bash",
-  "skipWebFetchPreflight": false,
-  "voiceEnabled": false,
-  "sshConfigs": [
-    { "id": "lab", "name": "Lab server", "sshHost": "dev@lab.example" }
-  ],
-  "agent": "reviewer"                   // default agent config
-}
-```
-
-`xaaIdp` is conditional on `UR_CODE_ENABLE_XAA`; when enabled,
-`callbackPort` is optional but must be a positive integer. The
-`disableDeepLinkRegistration: "disable"` key exists only in LODESTONE builds.
-`assistantName` is KAIROS-only. There are no top-level `environment`,
-`marketplace`, or `plugin` objects in the standard settings schema.
-
-## Supported environment variables
-
-These tables cover user-facing runtime controls. Platform-detection variables,
-CI-provider metadata, test fixtures, and compile-time-only/internal branches
-are not presented as supported configuration merely because source code reads
-them.
-
-### Providers
-
-| Variable | Effect |
-|---|---|
-| `OLLAMA_API_KEY` | Bearer token for Ollama's hosted API. With no host set, also switches the base URL to `https://ollama.com` — a local daemon needs no key, a direct connection does. Allowlisted through the Agentic CI env scrub |
-| `OLLAMA_HOST` / `OLLAMA_BASE_URL` | Explicit Ollama endpoint; always wins over the key-implied cloud default |
-| `OLLAMA_CONTEXT_TOKENS` | Override the detected context window |
-| `API_TIMEOUT_MS` | Explicit Ollama request timeout in milliseconds; overrides the model-aware runtime default |
-| `UR_API_TIMEOUT_MS` | Default provider HTTP-client timeout where supported |
-| `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` | Provider credentials; also allowlisted for Agentic CI |
-
-### Core behavior
-| Variable | Effect |
-|---|---|
-| `UR_CODE_SIMPLE=1` | Minimal tool set (Bash/Read/Edit); set by `--bare` |
-| `UR_CODE_REMOTE=true` | Remote/CCR container mode (raises heap to 8GB) |
-| `UR_CODE_DISABLE_BACKGROUND_TASKS=1` | Remove background mode from the Bash, PowerShell, and Agent tools. It does not disable the separate public `ur bg` command |
-| `UR_CODE_DISABLE_AUTO_MEMORY=1` | Disable auto-memory |
-| `UR_CODE_DISABLE_COMMAND_INJECTION_CHECK=1` | Skip bash injection analysis (not recommended) |
-| `UR_CODE_MAX_OUTPUT_TOKENS` | Cap model output tokens |
-| `UR_CODE_MAX_RETRIES` | API retry cap |
-| `UR_CODE_EXTRA_BODY` | Extra JSON merged into API requests |
-| `UR_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | Opt into agent teams/swarm mode in external builds (also available through hidden `--agent-teams`); the runtime kill-switch still applies |
-| `UR_CODE_USE_POWERSHELL_TOOL=1` | Enable the PowerShell tool on Windows |
-| `UR_CODE_INDEX=1` | Force-enable the semantic code index + CodeSearch tool; an existing built index enables it automatically, while `0`, `false`, or `off` force-disable it |
-| `UR_CODE_ENABLE_TASKS=1` | Use structured TaskCreate/Get/Update/List tools in headless/SDK sessions; interactive sessions use them by default |
-| `UR_CODE_MAX_TOOL_USE_CONCURRENCY` | Cap concurrent-safe tools in the ordinary agent loop (default 10, clamped to 1–32) |
-| `UR_MAX_CONCURRENT_TOOLS` | Cap concurrent-safe tools in the streaming executor (default 8, clamped to 1–32); set both concurrency variables when one limit is desired across both paths |
-| `ENABLE_LSP_TOOL=1` | LSP tool |
-| `UR_BROWSER_TOOL=1` / `WEB_BROWSER_TOOL=1` | Enable the model-invocable Browser tool. Its guarded `fetch` action is runtime-independent; interactive actions require `playwright-core` and an installed Chromium/Chrome executable |
-| `UR_CODE_SYNTAX_HIGHLIGHT=0` | Disable syntax highlighting |
-| `UR_CODE_ACCESSIBILITY=1` | Accessibility rendering |
-| `UR_CODE_SHELL_PREFIX` | Prefix every shell command |
-| `UR_CODE_TAGS` | Add one opaque `tags` value to analytics environment metadata; it does not tag a conversation for `/resume` |
-| `UR_CODE_OVERRIDE_DATE` | Fake "today" (testing) |
-| `UR_CODE_DISABLE_AUTO_LEARNING=1` | Disable automatic local pass/fail outcome recording |
-
-### Providers & auth
-| Variable | Effect |
-|---|---|
-| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `OPENROUTER_API_KEY` | API-key providers |
-| `UR_MODEL_POOL_CHEAP/STRONG/DEFAULT` | Model pools for routing |
-| `UR_CODE_OAUTH_TOKEN` / `UR_CODE_OAUTH_REFRESH_TOKEN` / `UR_CODE_OAUTH_SCOPES` | OAuth token injection |
-| `UR_CODE_SESSION_ACCESS_TOKEN` | Remote session token |
-| `URHQ_DEFAULT_MODELO_MODEL` / `URHQ_DEFAULT_MODELS_MODEL` / `URHQ_DEFAULT_MODELH_MODEL` | Default model tiers (opus/sonnet/haiku-class) |
-| `MCP_CLIENT_SECRET` | OAuth client secret for `ur mcp add` |
-| `UR_OPENAI_RESPONSES_STATE_KEY` | 32-byte hex/base64 key required to persist encrypted compacted Responses context |
-
-### Protocol, skill, and telemetry controls
-| Variable | Effect |
-|---|---|
-| `UR_MCP_HTTP_TOKEN` / `UR_MCP_HTTP_*` | Authenticate and bound the opt-in stateless MCP 2026 Tasks/Apps server |
-| `UR_A2A_TOKEN` / `UR_A2A_DELEGATION_SECRET` / `UR_A2A_*` | Authenticate, scope, and bound A2A v0.3/v1 serving |
-| `UR_ACP_STDIO_*` | Bound ACP durable sessions, prompts, output, and runtime |
-| `UR_SKILLS_STRICT_SPEC=true` | Reject file skills that violate the Agent Skills specification |
-| `UR_SKILLS_REQUIRE_TRUSTED_SIGNATURE=true` | Require a trusted Ed25519 skill signature at load and invocation |
-| `UR_SKILL_TRUSTED_KEYS_FILE` | Override the trusted **public** skill-key store used to verify signatures |
-| `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER` / `OTEL_LOGS_EXPORTER` | Explicitly enable `otlp` or `console`; unset/`none` is off |
-| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` | Opt into bounded prompt/tool/memory content attributes (off by default) |
-| `OTEL_SDK_DISABLED=true` | Disable all OpenTelemetry SDK export |
-
-### Internal / build
-`USER_TYPE=ant` (internal commands/tools), `IS_DEMO`, `NODE_OPTIONS`,
-`COREPACK_ENABLE_AUTO_PIN=0` (forced), `UR_CODE_ENTRYPOINT`, `UR_CODE_WORKER_EPOCH`,
-`UR_CODE_ENVIRONMENT_KIND`, `UR_CODE_IS_COWORK`, `UR_CODE_BRIEF`, `UR_CODE_PROACTIVE`,
-`UR_CODE_EAGER_FLUSH`, `UR_CODE_STREAMLINED_OUTPUT`, `UR_CODE_DEBUG_REPAINTS`,
-`UR_CODE_EXIT_AFTER_FIRST_RENDER`, `UR_CODE_TEST_FIXTURES_ROOT`.
-
-Names found only in dead feature branches are not runtime switches. In particular,
-`UR_CODE_REPL`, `UR_CODE_VERIFY_PLAN`, `UR_CODE_USE_BEDROCK`,
-`UR_CODE_USE_VERTEX`, `UR_CODE_DISABLE_CRON`, `UR_CODE_COORDINATOR_MODE`, and
-`UR_CODE_ABLATION_BASELINE` do not enable their named backend/tool/mode in the standard
-build. The last three are read only inside `AGENT_TRIGGERS`, `COORDINATOR_MODE`, and
-`ABLATION_BASELINE` compile-time branches respectively; none of those features is enabled
-by `scripts/bundle.mjs`.
-
-## Keybindings
-
-`~/.claude`-style keybindings live at `~/.ur/keybindings.json`; open with `/keybindings`,
-get help with `/keybindings-help`. Managed by `src/keybindings/` (chords supported,
-global + command-scoped bindings; see `useGlobalKeybindings.tsx` / `useCommandKeybindings.tsx`).
-
-## Output styles
-
-`outputStyle` setting selects a style; custom styles load from an output-styles directory
-(`src/outputStyles/loadOutputStylesDir.ts`). `/output-style` is deprecated in favor of
-`/config`. Built-in styles (`src/constants/outputStyles.ts`) are Explanatory,
-Game Designer, Learning, Concise, JSON-strict (every response a parseable JSON object),
-Debug-verbose (hypothesis-driven diagnostics), and Release-notes (changelog tone).
-
-## Settings not covered above
-
-These keys exist in `SettingsSchema` (`src/utils/settings/types.ts`) and were
-previously undocumented — the gap that let several releases ship settings no
-one could discover. `test/settingsDocCoverage.test.ts` now fails if any schema
-key is missing from this file.
-
-| Key | What it does |
-|---|---|
-| `$schema` | JSON Schema URL for editor completion in `settings.json`. Not a UR setting; ignored at runtime. |
-| `worktree.symlinkDirectories` | Directories symlinked from the main repository into each worktree instead of being copied, to avoid disk bloat. Nothing is symlinked unless listed; `node_modules`, `.cache` and `.bin` are the usual candidates. |
-| `worktree.sparsePaths` | Paths to materialize when creating a worktree, via `git sparse-checkout` in cone mode. In a large monorepo only the listed paths are written to disk, which is dramatically faster. |
-| `channelsEnabled` | Teams/Enterprise opt-in for channel notifications from MCP servers that declare the capability. Off unless set. |
-| `allowedChannelPlugins` | Allow-list of `{ marketplace, plugin }` pairs permitted to deliver channel notifications. Used with `channelsEnabled` to bound which plugins can notify. |
-| `urMdExcludes` | Glob patterns or absolute paths of `UR.md` files to skip when loading project memory. Use it to keep vendored or generated `UR.md` files out of context. |
-| `pluginTrustMessage` | Extra text appended to the plugin trust warning shown before installation, for organizations that need to state their own policy at that moment. |
-
-## Tool-result pruning (`context.pruneToolResults`)
-
-Superseded tool results — old file reads, greps, shell output — are cleared
-from context once doing so would free a worthwhile amount, keeping the most
-recent ones untouched.
-
-| Key | Default | What it does |
-|---|---|---|
-| `context.pruneToolResults.enabled` | `true` | Master switch. |
-| `context.pruneToolResults.minTokensFreed` | `20000` | Prune only when it would free at least this many tokens. Clearing invalidates the cached prefix, so a small cleanup costs more in cache misses than it reclaims; short sessions are never touched. |
-| `context.pruneToolResults.keepRecent` | `8` | Protected zone. The most recent N compactable tool results are never cleared, so the model keeps the working set it is reasoning about. Floored at 1. |
-
-Why it is on by default: the alternative when context fills is autocompact,
-which replaces the entire history with a summary. Dropping a superseded file
-read is strictly less destructive than losing the conversation.
-
-Compactable tools are `Read`, shell, `Grep`, `Glob`, `WebSearch`, `WebFetch`,
-`Edit` and `Write`. Cleared results are replaced with a marker, not deleted, so
-the tool call itself remains visible in the transcript.
-
-This is separate from the time-based trigger (`tengu_slate_heron`), which fires
-only after an hour of idling and is configured through GrowthBook — a service a
-local install never reaches, so it is effectively always off.
-
-## Memory integrity signing (`UR_MEMORY_INTEGRITY_KEY`)
-
-Unsigned, the manifest defends against accident and unaware tampering only:
-anyone who can write a memory file can also rewrite the manifest to match, and
-verification passes. Setting `UR_MEMORY_INTEGRITY_KEY` adds an HMAC over the
-file digests, so a forged manifest is detected even when every digest matches
-the file beside it.
-
-Off by default, deliberately. A key has to live somewhere, and a key stored
-next to the data it protects adds no security — enable this only when the key
-comes from somewhere the memory directory is not (password manager, CI secret).
-
-`ur memory-integrity verify` exits non-zero on an invalid signature, and also
-when a manifest is signed but no key is available: an unverifiable signature is
-not a pass.