ur-agent 1.33.0 → 1.35.0

package/docs/AGENT_FEATURES.md

@@ -161,11 +161,11 @@ while keeping them project-local and manifest-backed:
 | Primitive | UR surface | Project-backed source |
 | --- | --- | --- |
 | Agent | `ur`, `ur agents`, `ur crew`, `ur bg`, `ur agent-templates` | `.ur/agents/`, `AGENTS.md`, `UR.md` |
-| Rules | `ur context-pack scan`, `ur safety`, `ur guardrails`, `/hooks` | `AGENTS.md`, `UR.md`, `.cursor/rules/*.mdc`, `.cursorrules`, `.ur/safety-policy.json`, `.ur/guardrails.json`, `.ur/hooks.json` |
+| Rules | `ur context-pack scan`, `ur safety`, `/guardrails`, `/hooks` | `AGENTS.md`, `UR.md`, `.cursor/rules/*.mdc`, `.cursorrules`, `.ur/safety-policy.json`, `.ur/guardrails.json`, `.ur/hooks.json` |
 | MCP | `ur mcp`, built-in MCP server mode, MCP tools/resources | `.mcp.json`, `.ur/mcp/`, plugin manifests |
 | Skills | `/skills`, `/create-skill`, bundled skills, plugin skills | `.ur/skills/`, user skills, plugin skill folders |
 | CLI | `ur --help`, `ur -p`, `ur exec`, `ur acp`, workflow subcommands | `package.json` scripts, `.ur/project-manifest.json`, `.ur/verify.json` |
-| Models | `ur model`, `ur model-doctor`, model router, Ollama discovery | Ollama endpoint, settings, `OLLAMA_MODEL`, model metadata cache |
+| Models | `/model`, `ur model-doctor`, model router, Ollama discovery | Ollama endpoint, settings, `OLLAMA_MODEL`, model metadata cache |
 
 ## v1.19.0 Additions
 

package/docs/AGENT_TRENDS.md

@@ -76,7 +76,7 @@ Inside an interactive session:
 | Reliable repo editing | Covered | `ur repo-edit` builds a file/symbol index, performs AST-aware JS/TS identifier rename planning, previews patches before writing, and applies multi-file edits transactionally with rollback on syntax or check failure | Extend AST edits beyond identifier rename into import moves and signature-aware refactors |
 | Permission and safety policy | Covered | `ur safety`, `.ur/safety-policy.json`, pre-Bash safety evaluation, read/write/execute/network command classes, destructive-command approval, sandbox recommendations, and secret exfiltration denial | Record sandbox attestation in every risky command's evidence trail |
 | Project context management | Covered | `ur context-pack`, `.ur/project-manifest.json`, `.ur/context/*`, Project DNA, instruction files, verify gates, and task memory for decisions/constraints/commands/diffs | Feed the generated project manifest into subagent prompt selection and verifier gate choice |
-| AGENTS.md interoperability | Covered | `AGENTS.md` loaded as runtime project context (before `UR.md`), plus imported at `ur init` | Keep aligned as the AGENTS.md spec evolves |
+| AGENTS.md interoperability | Covered | `AGENTS.md` loaded as runtime project context (before `UR.md`), plus imported by the `/init` command | Keep aligned as the AGENTS.md spec evolves |
 | Browser and computer-use workflows | Covered | `/browser`, `/chrome`, Playwright-aware tasks, WebSearch, WebFetch, risky-action approval | Add more release fixtures with screenshots and replay assertions |
 | Provenance and citations | Partial | WebFetch source URLs, `/cite`, `/graph`, `/trace`, evidence ledgers | Add claim-to-source mapping for web/MCP answers |
 | Evals and observability | Covered | verifier gates, `.ur/verify.json`, `/verify`, `/trace`, OpenTelemetry hooks, release checks, eval dashboard, benchmark adapters | Publish benchmark numbers from local reproducible suites |

package/docs/CONFIGURATION.md

@@ -10,9 +10,10 @@ UR-AGENT supports official provider access paths only:
   OpenAI-compatible endpoints.
 - Local/server providers: Ollama, LM Studio, llama.cpp, and vLLM OpenAI-compatible
   server mode.
-- External app bridges: Codex CLI, Claude Code CLI, Gemini CLI, and Antigravity
-  where officially supported. These are diagnostics/opt-in bridges, not required
-  dependencies for normal UR runtime.
+- Subscription CLI providers: Codex CLI, Claude Code CLI, Gemini CLI, and
+  Antigravity where officially supported. These dispatch turns through the
+  vendor's official CLI using your subscription login. They are optional and
+  never required for normal UR runtime.
 
 UR-AGENT never scrapes browser sessions, extracts OAuth refresh tokens, reads
 hidden provider auth files, bypasses provider restrictions, or proxies consumer
@@ -48,10 +49,10 @@ ur config set base_url <url>
 
 Provider values accept canonical IDs and common aliases. Examples:
 `openai-api`, `anthropic-api`, `gemini-api`, `openrouter`, `ollama`,
-`lmstudio`, `LM Studio`, `llama.cpp`, and `vllm`. External app bridge aliases
-such as `codex-cli`, `claude-code-cli`, `gemini-cli`, and `antigravity-cli` are
-accepted only when `UR_ENABLE_EXTERNAL_APP_PROVIDERS=1` is set. Values with
-spaces should be quoted in shell commands.
+`lmstudio`, `LM Studio`, `llama.cpp`, `vllm`, and the subscription CLI
+providers `codex-cli` (`chatgpt`), `claude-code-cli` (`claude`), `gemini-cli`
+(`gemini`), and `antigravity-cli` (`agy`). Values with spaces should be quoted
+in shell commands.
 
 In the interactive app, `/model` is provider-first: choose a provider, then
 choose a model from that provider only. The picker labels providers as
@@ -70,8 +71,9 @@ ur provider status
 The status output includes active provider, active model, access type,
 credential type, and runtime backend.
 
-API keys are not written to UR settings. Set them in the environment when you
-explicitly choose API mode:
+API keys are never written to UR settings files. Store one securely with
+`ur connect <provider>` (OS keychain, with an encrypted file fallback), or set
+it in the environment when you explicitly choose API mode:
 
 ```sh
 OPENAI_API_KEY=...

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,204 @@
+# Troubleshooting
+
+Each entry lists the symptom, the likely cause, the fix, and a command that
+verifies the fix.
+
+## Install and startup
+
+### `ur: command not found`
+
+- Likely cause: the package is not installed globally, or the npm/bun global
+  bin directory is not on `PATH`.
+- Fix: reinstall globally and check the global bin path.
+
+```sh
+npm install -g ur-agent
+npm prefix -g       # ensure <prefix>/bin is on PATH
+ur --version
+```
+
+### `npm install -g ur-agent` fails
+
+- Likely cause: permission errors on the global prefix, or an old Node.js.
+- Fix: use a user-writable npm prefix (or a Node version manager), then retry.
+
+```sh
+npm config set prefix ~/.npm-global   # then add ~/.npm-global/bin to PATH
+npm install -g ur-agent
+ur --version
+```
+
+### Bun is missing or too old
+
+- Likely cause: UR runs through Bun; source checkouts and the GitHub install
+  path need Bun (this repository pins `bun@1.3.14`).
+- Fix: install Bun, then rerun.
+
+```sh
+npm install -g bun   # or: curl -fsSL https://bun.sh/install | bash
+bun --version
+```
+
+### Invalid or corrupted settings
+
+- Likely cause: malformed JSON in `~/.ur/settings.json` or project settings.
+- Fix: repair the JSON or set values through safe config commands instead of
+  editing by hand.
+
+```sh
+ur config set provider ollama
+ur provider status
+```
+
+## Providers and models
+
+### Provider selected but the model is unavailable
+
+- Likely cause: the model was never pulled/served, or it belongs to a
+  different provider.
+- Fix: pick a model scoped to the active provider.
+
+```sh
+ur provider status
+ur config set model <model-from-this-provider>   # or use /model in a session
+```
+
+### Selected model belongs to another provider
+
+- Likely cause: provider was changed and the old model is incompatible; UR
+  warns and clears the model in this case.
+- Fix: choose a model from the current provider's list.
+
+```sh
+ur provider status
+# then in a session: /model
+```
+
+### Requests appear to hit the wrong backend
+
+- Likely cause: a stale provider/model pair.
+- Fix: inspect the runtime backend; there is no cross-provider fallback, so
+  the reported backend is the one receiving requests.
+
+```sh
+ur provider status
+ur provider doctor
+```
+
+### Subscription CLI exits non-zero
+
+- Likely cause: the vendor CLI (codex, claude, gemini, agy) is missing or not
+  logged in.
+- Fix: install the official CLI and log in.
+
+```sh
+ur provider doctor codex-cli    # or claude-code-cli, gemini-cli, antigravity-cli
+ur auth chatgpt                 # or: ur auth claude | gemini | antigravity
+```
+
+### Provider produces output but exits with an error
+
+- Likely cause: the vendor CLI wrote a partial result and then failed (quota,
+  network, auth expiry). UR reports the provider, model, and backend with the
+  failure instead of discarding the output silently.
+- Fix: read the reported provider error, then re-check login/quota.
+
+```sh
+ur provider doctor <provider-id>
+```
+
+### Model discovery fails / model list is empty
+
+- Likely cause: for local/server providers the endpoint is down; for API
+  providers the key is missing, so only the curated fallback list shows.
+- Fix: start the server or connect the key.
+
+```sh
+curl http://localhost:11434/api/tags        # Ollama
+curl http://localhost:1234/v1/models        # LM Studio (llama.cpp: 8080, vLLM: 8000)
+ur connect openai-api                       # store an API key securely
+ur provider doctor
+```
+
+### Local server unreachable
+
+- Likely cause: wrong `base_url` or the server is not running.
+- Fix: point UR at the right endpoint.
+
+```sh
+ur config set base_url http://localhost:11434
+ur provider doctor
+```
+
+## Sessions and workflows
+
+### No visible progress in scripts
+
+- Likely cause: `ur -p` prints the final result only.
+- Fix: stream structured progress.
+
+```sh
+ur -p --output-format stream-json "explain this repository"
+```
+
+### Dry-run works but the real run fails
+
+- Likely cause: `--dry-run` skips model calls and permissions; the real run
+  needs a reachable provider and permission approval.
+- Fix: verify the provider, then run without `--dry-run` and approve prompts
+  (or scope tools explicitly).
+
+```sh
+ur provider status
+ur -p --allowed-tools "Read,Edit,Bash(git:*)" "run the task"
+```
+
+### Permission or sandbox issues
+
+- Likely cause: the requested command is classified as write/execute/network
+  and requires approval, or sandbox dependencies are missing.
+- Fix: inspect the policy and the sandbox status.
+
+```sh
+ur safety check --command "<the command>"
+ur sandbox status
+```
+
+### Tests fail after an agent edit
+
+- Likely cause: the edit broke a project gate.
+- Fix: use the CI loop to repair with bounded attempts, or inspect verify
+  gates.
+
+```sh
+ur ci-loop --command "bun test" --max-attempts 3
+ur test-first detect
+```
+
+## Integrations
+
+### Plugin fails to load
+
+- Likely cause: invalid manifest or wrong install scope.
+- Fix: validate the manifest and re-check installed state.
+
+```sh
+ur plugin doctor
+ur plugin list
+```
+
+### ACP / editor connection issues
+
+- Likely cause: the ACP server is not running, or the editor config block is
+  missing.
+- Fix: check status, regenerate the editor config, and run the IDE doctor.
+
+```sh
+ur acp status
+ur ide doctor
+ur ide config zed    # or vscode, cursor, windsurf, jetbrains, neovim
+```
+
+If a problem persists, run the repository's validation runbook
+([docs/VALIDATION.md](VALIDATION.md)) and file an issue at
+<https://github.com/Maitham16/UR/issues> with the exact command and output.

package/docs/USAGE.md

@@ -115,24 +115,25 @@ back to Ollama, Claude API does not fall back to Claude Code, and local/server
 providers do not leak cloud model lists. Use `ur provider status` to inspect the
 active provider, model, access type, and runtime backend.
 
-The default provider list keeps subscription access visible as `subscription`,
-but it is marked unavailable unless a real independent subscription runtime is
-configured. UR does not list fake subscription models and does not call provider
-apps by default.
+The provider list shows API, local/server, and subscription CLI providers.
+Subscription CLIs (Codex CLI, Claude Code, Gemini CLI, Antigravity) are
+first-class: selecting one dispatches turns through the vendor's official CLI
+using your subscription login (`ur auth <provider>`). The generic
+`subscription` entry is an internal placeholder and is hidden from listings;
+UR does not list fake subscription models.
 
 Provider values accept canonical IDs and common aliases. For example,
 `openai-api`, `anthropic-api`, `gemini-api`, `openrouter`, `ollama`,
-`lmstudio`, `llama.cpp`, and `vllm` are normal UR-native runtime providers.
-External app bridge aliases such as `codex-cli`, `claude-code-cli`,
-`gemini-cli`, and `antigravity-cli` are accepted only when the external bridge
-opt-in is enabled.
+`lmstudio`, `llama.cpp`, and `vllm` are UR-native runtime providers, and
+`codex-cli` (`chatgpt`), `claude-code-cli` (`claude`), `gemini-cli` (`gemini`),
+and `antigravity-cli` (`agy`) are subscription CLI providers.
 
-API modes are explicit and read keys only from environment variables:
+API modes are explicit. Keys are read from a key stored via
+`ur connect <provider>` (OS keychain) or from the environment variables
 `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and
-`OPENROUTER_API_KEY`. Provider app bridges are not required dependencies; they
-are blocked from normal runtime selection unless
-`UR_ENABLE_EXTERNAL_APP_PROVIDERS=1` is set. UR-AGENT never scrapes browser
-sessions, extracts OAuth tokens, or bypasses provider restrictions.
+`OPENROUTER_API_KEY`. Subscription CLIs are optional, never required
+dependencies, and never used as a silent fallback. UR-AGENT never scrapes
+browser sessions, extracts OAuth tokens, or bypasses provider restrictions.
 OpenAI-compatible local or cloud endpoints use `base_url` plus `model`.
 
 Use `/model` in an interactive session to select provider first and model
@@ -208,6 +209,7 @@ Hooks are advisory by default. A `BeforeEdit`/`BeforeCommand`/`BeforeCommit` hoo
 UR includes slash commands and CLI subcommands for common workflows:
 
 - `/help` or `ur --help` for command discovery
+- `ur connect ...` to connect provider accounts (subscription login or stored API key)
 - `ur mcp ...` to configure MCP servers
 - `ur plugin ...` to manage plugins and marketplaces. Marketplace plugins can
   add MCP tools, commands, executable skills, templates, validators, language
@@ -238,6 +240,24 @@ UR includes slash commands and CLI subcommands for common workflows:
 - `ur eval bench ...` to import local SWE-bench, Terminal-Bench, or Aider Polyglot exports
 - `ur crew ...` to run lead+worker agent crews with optional automatic task decomposition
 - `ur pattern ...` to run multi-agent collaboration patterns (PEER, DOE, concurrent, handoff, debate, parallel)
+- `ur workflow ...` to define, validate, graph, run, and resume declarative agent workflows
+- `ur goal ...` to track long-horizon objectives that persist across sessions
+- `ur task ...` to run worktree-per-task sessions with PR handoff
+- `ur worktree ...` to list, inspect, and clean up UR agent worktrees
+- `ur automation ...` to store and run project-local scheduled automation specs
+- `ur sandbox ...` to inspect sandbox/permission architecture and command approval levels
+- `ur knowledge ...` to manage a curated project knowledge base with provenance
+- `ur semantic-memory ...` to build and search the project-local memory index
+- `ur claim-ledger ...` to map generated claims to their sources
+- `ur route ...` to classify a task and recommend a subagent and collaboration pattern
+- `ur model-doctor` and `ur model-route ...` to inspect local Ollama models and pick one by capability fit
+- `ur local-first` to report readiness for offline/no-cloud environments
+- `ur browser-qa ...` to validate and smoke-run browser QA replay fixtures
+- `ur trigger ...` to parse GitHub/Slack webhook payloads and optionally launch a headless run
+- `ur agent-templates ...`, `ur agent-task ...`, `ur agent-inspect`, `ur agent-features`, and `ur agent-trends` for agent template, PR handoff, timeline, and coverage utilities
+- `ur role-mode ...` to install built-in Architect, Code, Debug, and Ask role modes
+- `ur a2a ...` for Agent Card metadata, delegation tokens, and the opt-in A2A task server
+- `ur sdk ...` to scaffold TS/Python headless SDK examples
 - `ur doctor` to inspect CLI health
 - `ur update` or `ur upgrade` to check for updates
 
@@ -253,11 +273,13 @@ Interactive sessions include a compact bottom status bar when stdout is a real
 terminal:
 
 ```text
-Ollama | llama3 | ask | main | update 1.30.6 available
+Ollama | llama3 | ask | main
 ```
 
-The bar is not rendered in non-interactive mode, CI, dumb terminals, or
-assistant viewer mode. Custom status-line hooks override the built-in bar.
+When a newer npm release exists, the bar appends an
+`update <version> available` segment. The bar is not rendered in
+non-interactive mode, CI, dumb terminals, or assistant viewer mode. Custom
+status-line hooks override the built-in bar.
 
 ## IDE Integration
 

package/docs/VALIDATION.md

@@ -18,7 +18,7 @@ You need:
 
 ```sh
 ur --version
-# expected: 1.25.3 (UR-AGENT)
+# expected: the version from package.json, e.g. "1.35.0 (UR-AGENT)"
 ```
 
 ## 0.1 Permission safety and context pack (1.19.0)

package/docs/providers.md

@@ -3,9 +3,10 @@
 UR-AGENT integrates official model access paths only. API-key providers, local
 runtimes, and OpenAI-compatible servers are UR-native backends: UR owns the
 conversation loop, tool loop, streaming, errors, and output. Subscription CLI
-integrations are external app bridges, not required dependencies. They stay
-diagnosable, but normal runtime selection blocks them unless
-`UR_ENABLE_EXTERNAL_APP_PROVIDERS=1` is set.
+providers (Codex CLI, Claude Code, Gemini CLI, Antigravity) are external app
+bridges: they are first-class in `/model` and dispatch each turn through the
+vendor's official CLI using your subscription login. They are optional, never
+required dependencies, and never used as a silent fallback.
 
 ## Legal auth policy
 
@@ -35,7 +36,10 @@ variables only when the user explicitly selects API mode.
 | LM Studio | local/server | UR-native | `openai-compatible:lmstudio` | local OpenAI-compatible server |
 | llama.cpp | local/server | UR-native | `openai-compatible:llama.cpp` | local OpenAI-compatible server |
 | vLLM | local/server | UR-native | `openai-compatible:vllm` | OpenAI-compatible server |
-| External app bridges | subscription | opt-in diagnostics | `subscription-cli:*` | disabled unless explicitly enabled |
+| Codex CLI | subscription | external app bridge | `subscription-cli:codex` | official Codex CLI login |
+| Claude Code | subscription | external app bridge | `subscription-cli:claude-code` | official Claude Code CLI login |
+| Gemini CLI | subscription | external app bridge | `subscription-cli:gemini` | official Gemini Code Assist login |
+| Antigravity | subscription | external app bridge | `subscription-cli:antigravity` | official Antigravity CLI login, where supported |
 
 ## Commands
 
@@ -45,8 +49,11 @@ ur provider status
 ur provider doctor
 ur provider doctor codex-cli
 ur provider doctor agy
-# Optional external app bridge diagnostics:
+# Subscription CLI logins (official vendor CLIs):
 ur auth chatgpt
+ur auth claude
+ur auth gemini
+ur auth antigravity
 ur config set provider ollama
 ur config set provider openai-api
 ur config set provider anthropic-api
@@ -69,13 +76,13 @@ through that provider's backend:
 
 - **API providers** make direct HTTP calls in each provider's native wire format: Anthropic uses `x-api-key` + `anthropic-version` against `/v1/messages`; OpenAI uses `Authorization: Bearer` against `/v1/chat/completions`; Gemini uses `x-goog-api-key` against `…:generateContent`; OpenRouter uses its OpenAI-compatible chat endpoint.
 - **Local/server providers** connect to the configured local or OpenAI-compatible endpoint (`/v1/chat/completions` for LM Studio, llama.cpp and vLLM; the native tags/chat API for Ollama)
-- **External app bridges** for subscription CLIs are blocked by default because
-  they delegate turns to another agent app. If deliberately enabled with
-  `UR_ENABLE_EXTERNAL_APP_PROVIDERS=1`, failures still remain provider-scoped
-  and never fall back to Ollama.
-- **Subscription** access is visible but blocked when no independent
-  subscription backend exists. It does not expose fake UR model IDs and does not
-  call external provider apps by default.
+- **Subscription CLI providers** (Codex CLI, Claude Code, Gemini CLI,
+  Antigravity) dispatch the turn through the vendor's official CLI using your
+  subscription login. Failures remain provider-scoped and never fall back to
+  Ollama or any other provider.
+- The generic **`subscription`** entry is an internal placeholder with no
+  models and no backend; it is hidden from listings. Choose a specific
+  subscription CLI, API, or local/server provider instead.
 
 The selected provider determines:
 - Which backend receives your requests
@@ -166,11 +173,11 @@ ur config set provider anthropic-api
 | API providers (openai-api, anthropic-api, gemini-api, openrouter) | Live discovery from the provider's `/models` endpoint using your connected key (curated fallback until connected) | live |
 | Local/server providers (ollama, lmstudio, llama.cpp, vllm) | Dynamic discovery from the selected provider endpoint | live |
 | OpenAI-compatible | Dynamic discovery from configured endpoint | live |
-| Subscription CLIs (codex-cli, claude-code-cli, gemini-cli, antigravity-cli) | Curated list (the official CLIs expose no models API); shown in `/model`, enabled once you `ur connect` them | static |
+| Subscription CLIs (codex-cli, claude-code-cli, gemini-cli, antigravity-cli) | Curated list (the official CLIs expose no models API); first-class in `/model`, dispatched via the official CLI. Log in with `ur auth <provider>` | static |
 
 ### API vs Subscription distinction
 
-**External app bridge providers** require official CLI login and explicit runtime opt-in:
+**Subscription CLI providers** require the vendor's official CLI login:
 - `codex-cli` — Codex CLI subscription via `codex login`
 - `claude-code-cli` — Claude Code subscription via `claude auth login`
 - `gemini-cli` — Gemini Code Assist enterprise login
@@ -245,9 +252,9 @@ Warning: Current model "gpt-5.5" is not available for provider "anthropic-api" a
   After changing provider, run /model or: ur config set model claude-sonnet-5
 ```
 
-For external app bridges, UR stores scoped IDs such as `claude-code/sonnet`,
-but normal runtime dispatch rejects the bridge before spawning the external app
-unless `UR_ENABLE_EXTERNAL_APP_PROVIDERS=1` is set.
+For subscription CLI providers, UR stores provider-scoped model IDs such as
+`claude-code/sonnet`, and runtime dispatch validates the pair against the
+provider's curated list before spawning the official CLI.
 
 ### Troubleshooting
 
@@ -257,11 +264,12 @@ unless `UR_ENABLE_EXTERNAL_APP_PROVIDERS=1` is set.
 ur provider status
 ```
 
-**Provider is an external app bridge:**
-- Choose a UR-native API/local/server provider for normal UR interaction
-- Run `ur provider doctor <provider>` only to inspect the external app bridge
-- Set `UR_ENABLE_EXTERNAL_APP_PROVIDERS=1` only if you intentionally want UR to
-  delegate turns to that external app
+**Subscription CLI provider is not working:**
+- Run `ur provider doctor <provider>` to check CLI presence and login status
+- Install the vendor's official CLI if it is missing, then log in with
+  `ur auth <chatgpt|claude|gemini|antigravity>`
+- Remember these run through the external vendor CLI; UR-native behavior
+  (API/local/server providers) does not require them
 
 **Provider shows "unavailable":**
 - Check API key: `echo $OPENAI_API_KEY`

package/documentation/app.js

@@ -39,7 +39,7 @@ const featureGroups = [
     title: 'Knowledge and memory',
     tags: ['retrieval', 'provenance', 'citations'],
     text: 'Durable memory, semantic memory, curated knowledge sources, lexical or embedding retrieval, citations, claim ledgers, and research graph primitives.',
-    commands: ['ur knowledge', 'ur semantic-memory', 'ur remember', 'ur claim-ledger'],
+    commands: ['ur knowledge', 'ur semantic-memory', 'ur context-pack remember', 'ur claim-ledger'],
   },
   {
     title: 'Evaluation and verification',
@@ -56,8 +56,8 @@ const featureGroups = [
   {
     title: 'Providers and auth',
     tags: ['subscription', 'API', 'local', 'status bar'],
-    text: 'UR-native API/local/OpenAI-compatible runtimes, visible-but-unavailable subscription access when no independent backend exists, optional external app bridge diagnostics, provider doctor checks, non-secret config, fallback hints, and provider-aware status-bar output.',
-    commands: ['ur provider list', 'ur provider status', 'ur provider doctor agy', 'ur config set provider openai-api', 'ur config set provider ollama'],
+    text: 'UR-native API/local/OpenAI-compatible runtimes, first-class subscription CLI providers dispatched through the official vendor CLIs, provider doctor checks, secure API-key connect, non-secret config, fallback hints, and provider-aware status-bar output.',
+    commands: ['ur provider list', 'ur provider status', 'ur provider doctor agy', 'ur connect status', 'ur config set provider openai-api', 'ur config set provider ollama'],
   },
   {
     title: 'Security and operations',
@@ -265,11 +265,60 @@ const commands = [
     examples: ['ur goal add release-docs --objective "Ship professional docs" --workflow docs', 'ur goal note release-docs --note "Command reference drafted"', 'ur goal resume release-docs --dry-run', 'ur goal done release-docs'],
   },
   {
-    name: 'install',
+    name: 'update',
     category: 'Ops',
+    aliases: ['upgrade'],
+    summary: 'Check npm for UR-AGENT updates.',
+    examples: ['ur update', 'ur upgrade'],
+  },
+  {
+    name: 'connect',
+    category: 'Providers',
+    aliases: [],
+    summary: 'Connect a provider account: subscription login through the official CLI, or store an API key in the OS keychain.',
+    examples: ['ur connect status', 'ur connect codex-cli', 'ur connect openai-api --key <KEY>', 'ur connect logout openai-api'],
+  },
+  {
+    name: 'ide',
+    category: 'Interop',
     aliases: [],
-    summary: 'Install or update the native UR build for a target version/channel.',
-    examples: ['ur install', 'ur install latest', 'ur update'],
+    summary: 'Manage IDE integrations: status, doctor, per-editor config, and inline diff bundles under .ur/ide/diffs.',
+    examples: ['ur ide status', 'ur ide doctor', 'ur ide config zed', 'ur ide diff capture --title "Parser fix"', 'ur ide diff list'],
+  },
+  {
+    name: 'skill',
+    category: 'Automation',
+    aliases: ['skills'],
+    summary: 'Executable skill workflows: list, show, run, and scaffold project skills.',
+    examples: ['ur skill list', 'ur skill init security-review', 'ur skill run security-review "src/auth.ts"'],
+  },
+  {
+    name: 'task',
+    category: 'Agents',
+    aliases: ['taskctl'],
+    summary: 'Start, run, and hand off worktree-per-task sessions with optional PR creation.',
+    examples: ['ur task list', 'ur task start parser-fix --worktree', 'ur task pr parser-fix --create --dry-run'],
+  },
+  {
+    name: 'sandbox',
+    category: 'Safety',
+    aliases: ['sandboxctl'],
+    summary: 'Inspect and manage the sandbox/permission architecture: status, dependency check, policy init, and command approval levels.',
+    examples: ['ur sandbox status', 'ur sandbox check', 'ur sandbox init'],
+  },
+  {
+    name: 'memory',
+    category: 'Knowledge',
+    aliases: [],
+    summary: 'Manage UR memory, including local retention policies by TTL, max entries, and decay.',
+    examples: ['ur memory retention show', 'ur memory retention set --ttl-days 30 --max-entries 500', 'ur memory retention prune'],
+  },
+  {
+    name: 'local-first',
+    category: 'Ops',
+    aliases: ['local', 'offline-readiness'],
+    summary: 'Show UR readiness for no-cloud, private, lab, offline, and edge/server environments.',
+    examples: ['ur local-first', 'ur local-first --json'],
   },
   {
     name: 'knowledge',
@@ -369,13 +418,6 @@ const commands = [
     summary: 'Scaffold requirements, design, and task documents under `.ur/specs`, track approvals, and run the task list one item at a time.',
     examples: ['ur spec init demo --goal "1. add a utils.add function 2. add a test"', 'ur spec status demo', 'ur spec approve demo requirements', 'ur spec run demo --all --dry-run', 'ur spec generate demo tasks --dry-run'],
   },
-  {
-    name: 'setup-token',
-    category: 'Ops',
-    aliases: [],
-    summary: 'Set up a long-lived authentication token when that subscription surface is enabled.',
-    examples: ['ur setup-token'],
-  },
   {
     name: 'exec',
     category: 'Automation',

package/documentation/index.html

@@ -44,7 +44,7 @@
     <main id="content" class="content">
       <header class="topbar">
         <div>
-          <p class="eyebrow">Version 1.30.6</p>
+          <p class="eyebrow">Version 1.35.0</p>
           <h1>UR-AGENT Documentation</h1>
           <p class="lead">A practical, tutorial-style reference for installing, configuring, automating, extending, and operating UR-AGENT.</p>
         </div>
@@ -140,13 +140,13 @@ ur -p --output-format json "Review the current diff"</code></pre>
         </div>
         <div class="reference-grid">
           <article>
-            <h3>External app bridges</h3>
+            <h3>Subscription CLI providers</h3>
             <pre><code>ur auth chatgpt
 ur auth claude
 ur auth gemini
 ur auth antigravity
 ur provider doctor agy</code></pre>
-            <p>External app bridges are optional diagnostics only. Normal runtime selection uses API, local, OpenAI-compatible, or a real configured subscription backend; the generic subscription entry does not expose fake models and stays unavailable when no independent backend exists.</p>
+            <p>Codex CLI, Claude Code, Gemini CLI, and Antigravity are first-class providers that dispatch each turn through the vendor's official CLI using your subscription login. They are optional, never required, and never used as a silent fallback. The generic subscription entry is an internal placeholder hidden from listings and exposes no fake models.</p>
           </article>
           <article>
             <h3>API and local providers</h3>
@@ -155,11 +155,11 @@ ur config set provider openai-api
 ur config set base_url http://localhost:11434/v1
 ur config set model qwen3-coder:480b-cloud
 ur config set provider.fallback ollama</code></pre>
-            <p>API providers require explicit selection and read keys only from environment variables. Local providers include Ollama, LM Studio, llama.cpp server mode, and vLLM OpenAI-compatible server mode.</p>
+            <p>API providers require explicit selection and read keys from a key stored via <code>ur connect</code> (OS keychain) or from environment variables. Local providers include Ollama, LM Studio, llama.cpp server mode, and vLLM OpenAI-compatible server mode. Subscription CLI providers (Codex CLI, Claude Code, Gemini CLI, Antigravity) dispatch through the official vendor CLIs.</p>
           </article>
           <article>
             <h3>Status bar and updates</h3>
-            <pre><code>Ollama | llama3 | ask | main | update 1.30.6 available</code></pre>
+            <pre><code>Ollama | llama3 | ask | main | update 1.35.1 available</code></pre>
             <p>The interactive status bar shows only important runtime state: provider, model, mode, branch, active tasks, checks status when known, and update availability. It is hidden in CI, dumb terminals, and non-interactive mode.</p>
           </article>
         </div>