ur-agent 1.34.0 → 1.35.1

package/docs/CODE_FEATURE_INVENTORY.md

@@ -1,1042 +0,0 @@
-# UR-AGENT code feature inventory
-
-This file is a code-derived inventory of what this agent can do in the
-`ur-agent` 1.25.3 source tree. It is meant to cover behavior that is easy to
-miss in user-facing documentation.
-
-Sources traced include:
-
-- `package.json`
-- `bin/ur.js`
-- `src/entrypoints/cli.tsx`
-- `src/main.tsx`
-- `src/query.ts`
-- `src/commands.ts`
-- `src/tools.ts`
-- `src/constants/prompts.ts`
-- `src/tools/**`
-- `src/commands/**`
-- `src/services/**`
-- `src/security/**`
-- `src/utils/settings/**`
-- `src/utils/plugins/**`
-- `src/entrypoints/mcp.ts`
-- `src/sdk/index.ts`
-- `plugins/core/**`
-
-Notes:
-
-- "Feature-gated" means the code exists but is conditional on env vars,
-  feature flags, build type, user type, or settings.
-- "Internal-only" means the code path is restricted to Anthropic/internal
-  user types or similar checks in this tree.
-- "Stub" means the source exposes a command/tool name but the implementation is
-  intentionally disabled, null, or placeholder in this build.
-- Copy-artifact files with names like `* 2.ts` are not treated as canonical;
-  the cleanup pass removed the stale `escalate 2.ts` and `ollama 2.ts` copies.
-
-## Package and binary entry
-
-- Publishes the CLI as `ur` from `bin/ur.js`.
-- Uses Bun as the runtime.
-- Runs `dist/cli.js` when present, otherwise `src/entrypoints/cli.tsx` with
-  build macros.
-- Exposes package scripts for start, dev, bundling, release checks,
-  typechecking, tests, smoke tests, secret scanning, package checks, and
-  prepack bundling.
-- Includes a dependency-free TypeScript SDK in `src/sdk/index.ts` that shells
-  out to `ur -p --output-format json`.
-
-## Startup and runtime modes
-
-- Fast `--version`, `-v`, and `-V` handling before full CLI load.
-- Normal interactive terminal UI.
-- Headless print mode with `-p` / `--print`.
-- Output modes:
-  - `text`
-  - `json`
-  - `stream-json`
-- Streaming JSON input mode via `--input-format stream-json`.
-- Structured output through `--json-schema`.
-- Optional inclusion of hook events, partial assistant messages, and replayed
-  user messages in streamed output.
-- Debug modes:
-  - `--debug`
-  - `--debug-to-stderr`
-  - `--debug-file`
-  - verbose mode
-- Minimal `--bare` mode that forces simple/local behavior and skips many
-  startup features such as hooks, LSP, plugin sync, attribution, auto-memory,
-  background prefetches, keychain prefetch, and project instruction discovery.
-- Init flows:
-  - `--init`
-  - `--init-only`
-  - maintenance mode
-- Resume flows:
-  - continue last session
-  - resume by session
-  - fork/resume variants
-  - resume from pull request context
-  - no-persistence mode
-  - rewind files
-- Model controls:
-  - model selection
-  - effort selection
-  - fallback model
-  - workload flags
-  - beta flags
-  - custom agents passed by `--agents <json>`
-- Turn and budget controls:
-  - max turns
-  - task budget
-  - max budget
-  - thinking controls
-- System prompt controls:
-  - override system prompt
-  - append system prompt
-  - load prompt additions from a file
-  - dump system prompt when gated
-- Workspace controls:
-  - `--add-dir`
-  - `--settings`
-  - `--setting-sources`
-  - `--ide`
-  - `--strict-mcp-config`
-  - `--session-id`
-  - `--name`
-  - `--file`
-- Worktree controls:
-  - `-w` / `--worktree [name]`
-  - `--tmux`
-  - tmux worktree fast path
-- Background session controls, feature-gated:
-  - `ps`
-  - `logs`
-  - `attach`
-  - `kill`
-  - `--bg` / `--background`
-- Daemon and worker modes, feature-gated:
-  - `daemon`
-  - `--daemon-worker`
-  - environment runner
-  - self-hosted runner
-- Browser and desktop integration entrypoints:
-  - Chrome MCP mode
-  - Chrome native host mode
-  - computer-use MCP mode, feature-gated
-  - deep-link handling, feature-gated
-- Remote/session server entrypoints:
-  - `server`
-  - `open <cc-url>`
-  - SSH remote runner, feature-gated
-  - remote-control / assistant bridge, feature-gated
-- A2A fast path in `bin/ur.js`:
-  - local A2A HTTP server
-  - health endpoint
-  - agent-card endpoint
-  - task endpoint
-  - loopback-only protection unless bearer token is configured
-  - dry-run mode
-  - headless `ur -p --output-format json` execution for tasks
-
-## Main CLI command families
-
-The CLI registers these top-level command families in `src/main.tsx`:
-
-- `mcp`: configure and manage MCP servers.
-- `auth`: login, status, and logout.
-- `plugin` / `plugins`: validate, install, update, enable, disable, uninstall,
-  and manage marketplaces.
-- `setup-token`: configure a long-lived authentication token.
-- `agents`: list configured agents.
-- `agent-trends`: show coverage against current agent technology trends.
-- `agent-features` / `agent-roadmap`: show or initialize agent feature
-  scaffolds.
-- `agent-templates` / `agent-template`: list or install reusable project
-  agent templates.
-- `automation` / `automations`: manage project-local automation specs and the
-  resident scheduler.
-- `agent-task` / `task-pr`: summarize task state, git diff status, and PR
-  handoff commands.
-- `model-doctor` / `model-capabilities`: inspect local Ollama model
-  capabilities.
-- `semantic-memory` / `memory-index`: build and search a project memory index.
-- `claim-ledger` / `claims`: manage claim-to-source provenance.
-- `browser-qa`: validate and smoke-run browser QA replay fixtures.
-- `pattern` / `patterns`: run or install multi-agent collaboration patterns.
-- `workflow` / `wf`: create, validate, graph, run, plan, and resume declarative
-  workflows.
-- `agent-inspect` / `inspect-agents`: reconstruct subagent timelines from
-  transcripts.
-- `route` / `intent`: classify task intent and recommend agents/patterns.
-- `model-route` / `model-pick`: recommend a local Ollama model for a task.
-- `crew` / `crews`: run a headless multi-agent crew with a shared board.
-- `goal` / `goals`: track long-horizon objectives and resume workflows.
-- `spec` / `specs`: spec-driven development scaffolding and execution.
-- `escalate`: capability-aware local model escalation.
-- `arena` / `best-of`: run competing agents in isolated worktrees and judge
-  diffs.
-- `bg` / `background-agent`: run detached local background agents with durable
-  state, logs, optional worktrees, fanout, live steering, and opt-in PRs.
-- `ci-loop` / `heal`: self-healing build/test loop with bounded fix attempts.
-- `test-first` / `quality-loop` / `tf-loop`: stack-aware compile/test/lint
-  loop with failure traces and `.ur/verify.json` gate installation.
-- `safety` / `safety-policy`: inspect project shell safety policy, initialize
-  `.ur/safety-policy.json`, and evaluate commands for read/write/execute/network
-  permission class, destructive-command approval, sandbox posture, and secret
-  exfiltration denial.
-- `context-pack` / `project-manifest` / `ctx-pack`: write
-  `.ur/project-manifest.json`, summarize repository architecture under
-  `.ur/context/architecture.md`, record task memory, and compress context.
-- `artifacts` / `artifact`: create, review, approve, reject, and capture
-  deliverables; comments can steer linked background tasks.
-- `trigger` / `mention`: parse webhook payloads and optionally launch a run.
-- `sdk` / `embed`: show or scaffold programmatic SDK usage.
-- `knowledge` / `kb`: curated project knowledge base with provenance.
-- `eval` / `evals`: public agent eval harness.
-- `code-index` / `codeindex`: semantic code index backed by local embeddings,
-  including watch mode for auto-reindex.
-- `repo-edit` / `repoedit` / `reliable-edit`: reliable repo editing with a
-  local file/symbol index, AST-aware JavaScript/TypeScript rename plans, patch
-  previews, and rollback-safe multi-file apply.
-- `memory retention`: project-local memory retention controls.
-- `ide diff`: editor-readable inline diff bundles for native review surfaces.
-- `role-mode` / `roles`: built-in role modes such as Architect, Code, Debug,
-  and Ask.
-- `a2a`: agent-to-agent card, server, and token utilities.
-- `auto-mode`: inspect classifier defaults/config/critique when gated.
-- `doctor`: updater and health diagnostics.
-- `update` / `upgrade`: check and install updates.
-- `install`: install native builds.
-- `completion`: shell completion support.
-
-Internal-only or gated command families include rollback, log, error, export,
-task-list management, remote control, assistant bridge, and selected dev
-commands.
-
-## Slash command inventory
-
-Slash commands are assembled from built-ins, skills, plugins, workflow commands,
-MCP prompt commands, and feature-gated sources in `src/commands.ts`.
-
-Code-visible slash command names include:
-
-- `a2a-card`
-- `actions`
-- `add-dir`
-- `advisor`
-- `agent-features`
-- `agent-inspect`
-- `agent-task`
-- `agent-templates`
-- `agent-trends`
-- `agents`
-- `analyze`
-- `arena`
-- `artifacts`
-- `automation`
-- `branch`
-- `brief`
-- `browser`
-- `browser-qa`
-- `btw`
-- `chrome`
-- `ci-loop`
-- `test-first`
-- `cite`
-- `claim-ledger`
-- `clear`
-- `code-index`
-- `color`
-- `compact`
-- `compliance`
-- `config`
-- `context`
-- `context-pack`
-- `convert`
-- `copy`
-- `cost`
-- `create-skill`
-- `crew`
-- `desktop`
-- `devcontainer`
-- `diff`
-- `dna`
-- `doctor`
-- `effort`
-- `escalate`
-- `eval`
-- `evidence`
-- `exit`
-- `export`
-- `extra-usage`
-- `fast`
-- `feedback`
-- `files`
-- `forget`
-- `goal`
-- `graph`
-- `guardrails`
-- `harden`
-- `heapdump`
-- `help`
-- `hooks`
-- `ide`
-- `image`
-- `index`
-- `init`
-- `install-github-app`
-- `install-slack-app`
-- `ir`
-- `kali`
-- `keybindings`
-- `knowledge`
-- `lab`
-- `learn`
-- `login`
-- `logout`
-- `mcp`
-- `memory`
-- `mode`
-- `model`
-- `model-doctor`
-- `model-route`
-- `os`
-- `output-style`
-- `paper`
-- `passes`
-- `pattern`
-- `permissions`
-- `plan`
-- `playbook`
-- `plugin`
-- `pr-comments`
-- `privacy-settings`
-- `project`
-- `insights`
-- `rate-limit-options`
-- `read`
-- `release-notes`
-- `reload-plugins`
-- `remember`
-- `remote-control`
-- `remote-env`
-- `rename`
-- `research`
-- `resume`
-- `review` / `ultrareview`
-- `rewind`
-- `role-mode`
-- `route`
-- `sandbox`
-- `safety`
-- `scope`
-- `sdk`
-- `search`
-- `security`
-- `security-review`
-- `semantic-memory`
-- `session`
-- `skills`
-- `spec`
-- `stability`
-- `stats`
-- `status`
-- `statusline`
-- `summarize`
-- `tag`
-- `tasks`
-- `terminal-setup`
-- `theme`
-- `think-back` / `thinkback-play`
-- `threat-model`
-- `toolsmith`
-- `trace`
-- `trigger`
-- `upgrade`
-- `ur-doctor`
-- `ur-init`
-- `usage`
-- `verify`
-- `video`
-- `vim`
-- `voice`
-- `vuln`
-- `web-setup`
-- `workflow`
-- `workspace`
-- `youtube`
-
-Internal-only command stubs or restricted commands in the registry include
-backfill sessions, break cache, bughunter, commit, commit/push/PR, context
-visualization, good UR, issue, init verifiers, force snip, mock limits, bridge
-kick, version, ultraplan, subscribe PR, reset limits, onboarding, share,
-summary, teleport, trace/debug helpers, perf issue, env, OAuth refresh,
-debug-tool-call, agents platform, and autofix PR.
-
-Remote-safe slash commands are limited to session, exit, clear, help, theme,
-color, vim, cost, usage, copy, btw, feedback, plan, keybindings, and
-statusline.
-
-Bridge-safe local commands include compact, clear, cost, summary,
-release-notes, and files. Prompt commands are allowed in the bridge path, while
-local JSX commands are blocked.
-
-## Conversation loop features
-
-- Maintains an assistant/user/tool message loop in `src/query.ts`.
-- Streams assistant output and tool-use events.
-- Executes tool calls through streaming and non-streaming orchestration.
-- Supports parallel tool calls where the model emits them.
-- Validates and repairs missing tool result blocks.
-- Tracks tool-use summaries.
-- Enforces turn limits and task budgets.
-- Handles retryable API/model errors.
-- Supports fallback models.
-- Handles token-budget continuation.
-- Applies tool result output budgets and content replacement.
-- Supports large-output persistence and references.
-- Performs auto-compaction and micro-compaction.
-- Supports session-memory compaction.
-- Supports post-compact cleanup.
-- Has a disabled/stubbed context-collapse service in this build.
-- Handles prompt-too-long recovery when feature-gated.
-- Supports stop hooks and post-sampling hooks.
-- Tracks verifier state and can inject reminders.
-- Supports structured JSON output through a synthetic output tool.
-
-## Prompt and behavioral system
-
-The system prompt source in `src/constants/prompts.ts` includes:
-
-- UR identity as a coding agent.
-- Concise terminal-oriented output rules.
-- Code editing expectations.
-- Tool-use discipline and preference for file tools over shell ad hoc edits.
-- Planning guidance for multi-step tasks.
-- Guidance for using subagents.
-- Guidance for invoking skills.
-- Optional verification contract.
-- Cyber-safety risk guidance.
-- Hook instructions.
-- MCP instructions.
-- Memory instructions.
-- Language and output-style customization.
-- System reminders.
-- Token-budget instructions.
-- Brief/proactive sections.
-- Scratchpad and function-result clearing sections.
-
-For Ollama-backed providers, the prompt adds stricter instructions around:
-
-- using structured tool calls rather than raw JSON/tool XML
-- using `Write` and `Edit` for file changes
-- preferring parallel tool calls
-- planning before larger tasks
-- stopping repeated failing calls
-- verifying before claiming completion
-- responding to command failures
-- avoiding empty responses
-
-`UR_CODE_SIMPLE` replaces this with a minimal prompt containing identity, cwd,
-and date.
-
-## Built-in tools
-
-Tool assembly is centralized in `src/tools.ts`. Availability depends on mode,
-feature flags, user type, MCP, and settings.
-
-Core tools:
-
-- `Bash`: run shell commands with permissions, sandbox checks, timeout,
-  background execution, read-only auto-approval heuristics, destructive command
-  warnings, output truncation/persistence, image output handling, git operation
-  tracking, and UI collapsing for common read/search commands.
-- `PowerShell`: PowerShell command execution with similar permission,
-  path-safety, destructive-warning, and constrained-language checks.
-- `Read`: read text files, selected line ranges, images, notebooks, and PDF
-  page ranges; blocks binary or risky device paths; enforces size/token limits;
-  tracks reads before edits.
-- `Edit`: replace exact strings in files after prior read; validates paths,
-  permissions, concurrent modifications, max file size, and secret exposure;
-  records diffs/history.
-- `Write`: create or overwrite files; requires prior read for existing files;
-  validates permissions and unexpected modifications; records diffs/history.
-- `NotebookEdit`: edit notebook cells.
-- `Glob`: find files by glob pattern.
-- `Grep`: search file contents with optimized ripgrep-backed behavior.
-- `CodeSearch`: semantic code search through a local embedding index.
-- `WebFetch`: fetch a URL and run a prompt over retrieved content.
-- `WebSearch`: web search through the configured model/tool backend.
-- `TodoWrite`: maintain conversation-local todo state.
-- `Agent`: launch subagents synchronously or in the background; supports custom
-  agents, built-in agents, plugin agents, MCP requirements, worktree isolation,
-  remote mode, permission modes, cwd, background output files, teams, memory,
-  and model overrides.
-- `TaskOutput`: read background task output. Deprecated in favor of reading the
-  output file directly.
-- `TaskStop`: stop background tasks.
-- `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`: task-list v2 tools for
-  tracked work items, ownership, status, and blockers.
-- `TeamCreate`, `TeamDelete`, `SendMessage`: multi-agent team coordination.
-- `AskUserQuestion`: ask structured user questions from the agent loop.
-- `EnterPlanMode` and `ExitPlanMode`: proposal/approval planning flow.
-- `EnterWorktree` and `ExitWorktree`: enter or leave isolated worktree sessions.
-- `Skill`: execute prompt-backed skills from local skills, bundled skills,
-  plugins, or MCP.
-- `Brief`: send concise status messages or user-facing updates.
-- `SendUserFile`: send a generated file to the user, feature-gated.
-- `ListMcpResourcesTool` and `ReadMcpResourceTool`: enumerate and read MCP
-  resources.
-- `ToolSearch`: deferred tool discovery over tool metadata.
-- `Config`: read/write supported settings, internal-only in this build.
-- `REPL`: internal REPL tooling.
-- `Tungsten`: internal-only tooling.
-- `SuggestBackgroundPR`: internal-only background PR suggestion.
-- `LSP`: language-server diagnostics and symbol context, feature-gated.
-- `WorkflowTool`: workflow execution helper, feature-gated.
-- `CronCreate`, `CronDelete`, `CronList`: schedule recurring tasks,
-  feature-gated.
-- `RemoteTrigger`: trigger remote runs, feature-gated.
-- `Monitor`: monitoring helper, feature-gated or stubbed depending on build.
-- `Sleep`: wait/sleep tool.
-- `PushNotification`: push notifications, feature-gated.
-- `SubscribePR`: subscribe to PR changes, feature-gated/internal.
-- `Snip`: snip tool, feature-gated/internal.
-- `WebBrowserTool`, `CtxInspectTool`, `TerminalCaptureTool`: present as
-  tool surfaces but stubbed or disabled in this build.
-- `StructuredOutput`: synthetic tool used for JSON-schema output.
-- `mcp__<server>__<tool>`: dynamically assembled MCP server tools.
-
-Simple/bare mode keeps the tool set narrow, generally `Bash`, `Read`, and
-`Edit`, with REPL mode substituting `REPL` where applicable.
-
-## Built-in agents
-
-Built-in agents live under `src/tools/AgentTool/built-in`:
-
-- `general-purpose`: broad-purpose subagent with all tools.
-- `Explore`: read/search-only exploration agent, no file writes.
-- `plan`: planning agent for implementation designs, no file writes.
-- `verification`: adversarial verification agent for checking tests, builds,
-  browser behavior, and task completion.
-- `statusline-setup`: statusline configuration agent with read/edit tools.
-- `urCodeGuide`: UR documentation and guide agent with read/search/web tools.
-
-Custom agents can be loaded from user, project, managed, flag, or plugin
-sources. Agent definitions can configure:
-
-- description
-- tool allowlist
-- disallowed tools
-- prompt
-- model
-- effort
-- permission mode
-- required MCP servers
-- hooks
-- max turns
-- skills
-- initial prompt
-- memory
-- background behavior
-- isolation mode
-
-Agent resolution considers built-ins, plugins, user settings, project settings,
-CLI-provided agents, and managed settings.
-
-## Agent-platform features
-
-The `src/services/agents/**` area implements a large set of higher-level agent
-systems:
-
-- A2A server and Agent Card metadata, with task submit/list/status/output/cancel
-  routes backed by local background tasks.
-- Background-agent runner under `.ur/background`, including stream-json stdin
-  injection for live artifact steering.
-- HMAC-based attenuated A2A delegation tokens with audience, subject, scope,
-  and TTL.
-- Arena/best-of workflow: run multiple agents in isolated worktrees, judge
-  diffs, optionally apply the winner.
-- Reviewable artifacts under `.ur/artifacts`.
-- IDE diff bundles under `.ur/ide/diffs` plus the
-  `extensions/vscode-ur-inline-diffs` native VS Code review extension.
-- Benchmark adapters that import local SWE-bench, Terminal-Bench, and Aider
-  Polyglot JSON/JSONL exports into UR eval suites.
-- CI loop: run build/test commands, capture failures, spawn a fix agent, rerun
-  with bounded attempts, optionally commit/push.
-- Crew mode: lead agent decomposes a goal into a shared task board that worker
-  agents claim and execute.
-- Long-horizon goals persisted across sessions.
-- Spec-driven development under `.ur/specs`.
-- Declarative workflows with steps, dependencies, gates, resume state, and
-  graph rendering.
-- Live workflow board.
-- Scheduler service for automations through launchd, systemd, cron, or daemon
-  mode.
-- Knowledge base with source provenance, chunking, dense embeddings, search,
-  list, prune, and status.
-- Learning from artifact outcomes into model/category success stats and
-  lessons.
-- Local model routing based on capability fit.
-- Intent routing for task category, agent choice, and collaboration pattern.
-- Multi-agent collaboration patterns such as PEER and DOE.
-- Webhook trigger parsing for GitHub, Slack, and generic payloads.
-- Execution target wrappers for local, Docker, and devcontainer execution.
-- Eval harness with suites, cases, checks, reports, and replayable runs.
-- Agent inspector for reconstructing subagent timelines from transcripts.
-- Capability-aware model escalation between fast and oracle models.
-- Feature scaffold and reusable agent-template installation.
-
-## Memory and project knowledge
-
-- User/project/team memory loading.
-- Relevant memory scan.
-- Conversation/session memory compaction.
-- Memory extraction from sessions.
-- Auto-dream background memory consolidation.
-- Team memory sync.
-- Secret scanning and guards for team memory writes.
-- Memory commands:
-  - remember
-  - forget
-  - memory
-  - semantic-memory
-  - knowledge
-- Lightweight project file operations under `src/ur/fileops.ts`:
-  - read project files
-  - search text-like files
-  - maintain `.ur/index/files.txt`
-- Project DNA generation under `src/ur/projectDna.ts`:
-  - language detection
-  - package manager detection
-  - build/test/lint/run command detection, with Node/TypeScript typecheck
-    scripts treated as compile evidence
-  - key folders
-  - git/readme context
-  - `.ur/project_dna.md`
-- Project notes and research graph helpers under `src/ur/**`.
-
-## Verification and quality gates
-
-The verifier service in `src/services/verifier/**` includes:
-
-- L1 deterministic verifier enabled by default unless disabled by env.
-- Modes:
-  - `off`
-  - `loose`
-  - `strict`
-- Empty-turn detection.
-- Done-claim detection against actual tool/mutation evidence.
-- Project gates from `.ur/verify.json`.
-- Test-first execution loop under `src/services/agents/testFirstLoop.ts`:
-  - automatic stack and command detection
-  - compile/test/lint command ordering
-  - bounded fix-runner retries
-  - failure traces under `.ur/test-first/traces/`
-  - gate installation into `.ur/verify.json`
-- Project context pack under `src/services/context/projectContextManifest.ts`:
-  - manifest generation from package scripts, Project DNA, instruction files,
-    `.ur/verify.json`, `.ur/safety-policy.json`, and other project manifests
-  - architecture summary under `.ur/context/architecture.md`
-  - task memory JSONL for decisions, constraints, commands, diffs, and notes
-  - compressed task context under `.ur/context/compressed.md`
-- Loop detection.
-- Rejection cap.
-- Optional L2 verification subagent through env opt-in.
-- Manual deeper verification through `/verify`.
-- Verifier reminders injected back into the conversation loop.
-
-## Permissions and sandboxing
-
-Permission modes:
-
-- `default`
-- `plan`
-- `acceptEdits`
-- `bypassPermissions`
-- `dontAsk`
-- `auto`, feature-gated
-
-Permission features:
-
-- Tool-level allow, deny, and ask rules.
-- Project shell safety policy under `src/services/safety/projectSafety.ts`.
-- Command permission classes: read, write, execute, and network.
-- `ur safety check --command <cmd>` previews safety behavior before execution.
-- Bash command permission checks consult the project safety policy before broad
-  sandbox auto-allow and exact allow rules.
-- Destructive commands such as recursive remove, hard reset, git clean, forced
-  push, recursive chmod/chown, filesystem formatting, infrastructure destroy,
-  and cluster delete require approval.
-- Secret exfiltration patterns deny common secret-file reads into transcript
-  and likely secret values sent to remote sinks.
-- MCP server/tool permission rules.
-- CLI, command, session, user, project, local, and managed setting sources.
-- Permission request hooks.
-- Permission-denial tracking.
-- Auto-mode classifier integration when gated.
-- Dangerous Bash/PowerShell rule detection.
-- Auto-mode stripping of dangerous rules.
-- Additional directory validation.
-- Security restriction gates.
-
-Sandbox configuration supports:
-
-- enabled/disabled state
-- fail-if-unavailable
-- automatic Bash approval when sandboxed
-- explicit unsandboxed command allowances
-- network allowed domains
-- managed-only network controls
-- Unix socket controls
-- local binding controls
-- proxy ports
-- filesystem read/write allow and deny rules
-- ignored violations
-- weaker nested/network isolation flags
-- excluded commands
-- custom ripgrep behavior
-
-## MCP integration
-
-MCP features:
-
-- CLI management through `ur mcp`.
-- MCP stdio server via `src/entrypoints/mcp.ts`.
-- Exposes built-in tools through MCP.
-- Converts Zod schemas to JSON schema for MCP tools.
-- Runs tools in non-interactive context with normal permission checks.
-- Server scopes:
-  - local
-  - user
-  - project
-  - dynamic
-  - enterprise
-  - urai
-  - managed
-- Transports:
-  - stdio
-  - SSE
-  - HTTP
-  - WebSocket
-  - SDK/in-process
-  - IDE variants
-  - UR.ai proxy
-- Config support:
-  - command/args/env
-  - URL/headers
-  - headers helper
-  - OAuth
-  - client IDs and client secrets
-  - callback ports
-  - auth server metadata URL
-  - XAA identity-provider settings, feature-gated
-- Connection states:
-  - connected
-  - failed
-  - needs auth
-  - pending
-  - disabled
-- MCP resources and prompt commands.
-- Official registry lookup/cache.
-- Environment variable expansion.
-- Channel allowlists, permissions, and notifications.
-- Elicitation handling.
-- VS Code SDK MCP support.
-- Tool normalization as `mcp__server__tool`.
-
-## Hooks
-
-Hook events include:
-
-- `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`
-
-Hook command types:
-
-- shell command hooks
-- PowerShell hooks
-- prompt/LLM hooks
-- HTTP hooks
-- agent/verifier hooks
-
-Hook features:
-
-- conditional `if` permission-rule filters
-- timeouts
-- status messages
-- once-only hooks
-- async command hooks
-- async rewake behavior
-- model selection for prompt/agent hooks
-- HTTP headers and allowed environment variables
-- exit-code semantics that can block, feed stderr to the model, erase prompts,
-  or decide permission requests depending on event type
-
-## Security features
-
-The `src/security/**` subsystem and related slash commands provide:
-
-- Security command dispatcher.
-- Source-code security audit.
-- Secret scanning and redaction.
-- Attack-surface mapping.
-- Dependency inventory.
-- OSV vulnerability audit.
-- Dockerfile, Kubernetes, Terraform, and cloud/IaC audit.
-- Threat modeling.
-- Network snapshot and packet-capture summary helpers.
-- Incident response collection.
-- IR timeline support.
-- Containment planning.
-- Compliance reports.
-- SSDF, CIS, ASVS, OWASP, CWE, and MITRE mappings.
-- Playbooks.
-- Local security labs.
-- Hardening checks.
-- Safe command runner.
-- Policy/classifier helpers.
-- Vulnerability-intelligence helpers.
-- Web audit helpers.
-
-Security slash-command families include:
-
-- `/security`
-- `/security-review`
-- `/threat-model`
-- `/vuln`
-- `/ir`
-- `/compliance`
-- `/playbook`
-- `/lab`
-- `/harden`
-- `/kali`
-
-`/security` subcommands include scan, code, secrets, attack-surface,
-dependencies, classify, status, rules, report, scope, mode, threat-model, vuln,
-net, ir, attack, compliance, playbook(s), lab, secure-design, secure-api,
-secure-ci, secure-docker, and secure-deploy.
-
-## Plugins and marketplaces
-
-Plugin loading supports:
-
-- installed marketplace plugins
-- session-only `--plugin-dir`
-- plugin manifests
-- plugin commands
-- plugin agents
-- plugin skills
-- plugin templates
-- plugin validators
-- plugin hooks
-- output styles
-- MCP servers
-- LSP servers
-- language adapters
-- marketplace capability metadata
-- plugin settings
-- duplicate-name handling
-- enable/disable state
-- trust warnings
-- marketplace add/list/remove/update
-- sparse marketplace checkouts
-- cached marketplace installs
-- versioned plugin cache
-- seed caches
-- zip caches
-- legacy cache migration
-- blocked marketplaces
-- strict known-marketplace policy
-- managed plugin settings
-
-Bundled marketplace plugin families in `plugins/core/**`:
-
-- code review
-- evaluate response
-- explain error
-- git summary
-- GitHub issues, PR creation, PR review, repo health, and GitHub workflow skill
-- GitLab issues, merge request creation/review, pipeline, and GitLab workflow
-  skill
-- hello example plugin
-- Hugging Face model/dataset search, downloads, model cards, and HF workflow
-  skill
-- Miro board, diagram, export, stickies, and Miro workflow skill
-- Obsidian backlinks, daily notes, MOC, second brain, vault search, and second
-  brain skill
-- PowerPoint deck creation, markdown-to-deck, review, theme, and deck-craft
-  skill
-- release notes
-- reproducible release discipline, release-gate validator, release verifier
-  template, and Markdown language-adapter metadata
-- skill forge and skill authoring
-- Word document creation, markdown-to-docx, edit, review, and document-craft
-  skill
-
-## Configuration features
-
-The Config tool supports these settings where available:
-
-- `theme`
-- `editorMode`
-- `verbose`
-- `preferredNotifChannel`
-- `autoCompactEnabled`
-- `autoMemoryEnabled`
-- `autoDreamEnabled`
-- `fileCheckpointingEnabled`
-- `showTurnDuration`
-- `terminalProgressBarEnabled`
-- `todoFeatureEnabled`
-- `model`
-- `alwaysThinkingEnabled`
-- `permissions.defaultMode`
-- `language`
-- `teammateMode`
-- `classifierPermissionsEnabled`, internal-only
-- `voiceEnabled`, feature-gated
-- `remoteControlAtStartup`, feature-gated
-- push-notification settings, feature-gated
-
-The broader settings schema also covers:
-
-- environment variables
-- API-key helpers
-- AWS/GCP auth refresh
-- XAA identity-provider settings
-- file suggestions
-- gitignore behavior
-- cleanup retention
-- attribution
-- git instructions
-- permission allow/deny/ask/default mode/additional dirs
-- model lists and model overrides
-- MCP allow/deny/project approvals
-- hooks
-- worktree symlink and sparse settings
-- hook disabling
-- default shell
-- managed-only hooks, permissions, and MCP settings
-- HTTP hook URL/env policies
-- strict plugin-only customization
-- statusline command
-- enabled plugins
-- extra marketplaces
-- marketplace blocklists
-- authentication organization/method
-- output style
-- language
-- sandbox settings
-- surveys
-- spinner
-- syntax highlighting
-- terminal title
-- thinking and effort
-- advisor
-- fast mode
-- prompt suggestions
-- agent settings
-- company announcements
-- plugin config
-- remote defaults
-- auto updates/channels
-- reduced motion
-- auto memory and auto dream
-- dangerous-mode prompts
-- auto-mode config
-- SSH configs
-- UR.md excludes
-- plugin trust message state
-
-## Model/provider behavior
-
-- This external build supports legal provider adapters for subscription CLIs,
-  explicit API-key providers, and local/OpenAI-compatible runtimes.
-- The Ollama router inspects local models and classifies likely coding/fast
-  capabilities.
-- Auto-routing is on by default through `UR_OLLAMA_AUTO_ROUTE`.
-- Simple prompts can route to a faster model.
-- Complex coding prompts can route to the best available coder model.
-- Model doctor and model route commands expose capability reports and
-  recommendations.
-- Embedding-backed features use local Ollama embeddings such as
-  `nomic-embed-text` where configured.
-
-## UI and terminal experience
-
-Terminal/UI features include:
-
-- Ink/React interactive UI.
-- Theming and color controls.
-- Vim mode.
-- Status line configuration.
-- Keybinding help.
-- Cost and usage displays.
-- Session browser and resume UI.
-- Compacting UI.
-- Permission prompts.
-- MCP approval UI.
-- Plugin management UI.
-- Install/setup flows.
-- Feedback and BTW commands.
-- Terminal setup.
-- Desktop, Chrome, IDE, remote environment, and OS integration commands.
-- Voice command surface, feature-gated.
-- Image/video/youtube command surfaces.
-
-## SDK and embedding
-
-`src/sdk/index.ts` exposes:
-
-- `query`
-- `queryJSON`
-- `UrClient`
-- `parseResultText`
-
-The SDK is intentionally small and dependency-free. It shells out to the local
-`ur` binary in print mode, uses JSON output, supports cwd/env/bin overrides, and
-can pass max turns, model, permission mode, and extra args.
-
-## Documentation gaps this inventory exposes
-
-The code includes many features that are easy to miss if reading only user docs:
-
-- Agent-platform workflows, goals, specs, crews, arena, CI loop, artifacts,
-  triggers, evals, and learning.
-- A2A card/server/token support.
-- Rich hook event model.
-- Plugin marketplace and bundled plugin system.
-- Security audit, incident-response, compliance, and lab features.
-- Local knowledge, semantic memory, project DNA, and code-index subsystems.
-- Verifier and project gate logic.
-- Multiple remote/background/daemon/server modes.
-- MCP server mode that exposes UR tools to other clients.
-- Feature-gated browser, Chrome, computer-use, voice, push, cron, and remote
-  features.