ur-agent 1.65.6 → 1.65.7

package/technical/12-security-sandbox-stability.md

@@ -0,0 +1,271 @@
+# 12 — Security, Sandbox & Stability
+
+Source of truth: `src/utils/permissions/`, `src/utils/sandbox/`,
+`src/entrypoints/sandboxTypes.ts`, `src/services/safety/projectSafety.ts`,
+`src/security/`, `src/services/guardrails/guardrails.ts`, `src/stability/`,
+`src/services/verifier/`, and `src/services/tools/toolHooks.ts`.
+
+This chapter distinguishes an **enforced runtime boundary** from an
+**inspection/advisory helper**. A command that can scan, classify, or print a
+warning is not described as blocking ordinary agent execution unless it is
+actually wired into that execution path.
+
+## Permission engine — enforced
+
+Every enabled tool call passes through the permission engine. Rules are loaded
+from `permissions.allow`, `permissions.ask`, and `permissions.deny`, the
+`--allowed-tools`/`--disallowed-tools` flags, session decisions, and managed
+policy. Rule syntax is `Tool` or `Tool(specifier)`, for example
+`Bash(git:*)`, `Edit(src/**)`, or `mcp__server__tool`.
+
+User-addressable modes are:
+
+| Mode | Runtime behavior |
+|---|---|
+| `default` | Honor explicit rules and ask for undecided operations. |
+| `plan` | Restrict mutation while planning. |
+| `acceptEdits` | Auto-accept the supported edit path while retaining other checks. |
+| `autoApprove` | Convert ordinary approval prompts to allow, except tools that require user interaction. Explicit deny rules and earlier safety checks still apply. |
+| `bypassPermissions` | Broad bypass mode, but explicit ask rules and safety-check decisions that are marked bypass-immune can still prompt. Org/settings kill switches can disable the mode. |
+
+`--dangerously-skip-permissions` selects bypass mode;
+`--allow-dangerously-skip-permissions` makes that mode available to the
+interactive selector. Managed settings can restrict permission rules, hooks,
+and MCP servers to managed sources.
+
+The normal external build does **not** enable the `TRANSCRIPT_CLASSIFIER`
+feature. Its AI-classified `auto` mode is therefore source-only. The accepted
+`permissions.classifierPermissionsEnabled` schema field is not read by a
+shipped enforcement path and must not be treated as an active control.
+
+Bash adds command parsing, command-injection checks, dangerous-pattern
+classification, project safety policy, path validation, and sandbox-aware
+permission decisions. `UR_CODE_DISABLE_COMMAND_INJECTION_CHECK` weakens one of
+those checks and is not a safe default.
+
+## OS sandbox — enforced when enabled and available
+
+Set `sandbox.enabled` in settings to request OS-level Bash isolation. macOS uses
+`/usr/bin/sandbox-exec`; Linux/WSL uses `bwrap`; Windows is unsupported. With
+`sandbox.failIfUnavailable: false` (the default), an unavailable sandbox warns
+and may run commands unsandboxed subject to permissions. Set
+`failIfUnavailable: true` for a startup hard failure. The
+`allowUnsandboxedCommands` policy controls whether a tool call may explicitly
+request an unsandboxed run.
+
+```text
+/sandbox status
+/sandbox check
+/sandbox init
+/sandbox eval "curl https://example.com" --json
+/sandbox exclude "npm run test:*"
+```
+
+The command surface is easy to misread:
+
+- `status` and `check` inspect support/configuration.
+- `init` writes `.ur/safety-policy.json`; it does **not** write or enable an OS
+  sandbox configuration.
+- `eval` classifies a shell string through the project safety policy. It does
+  not execute the command.
+- `/sandbox exclude "<pattern>"` is an interactive slash-command action. It
+  appends a non-duplicate pattern to `sandbox.excludedCommands` in the
+  project-local `.ur/settings.local.json`; the shell form `ur sandbox exclude`
+  is not implemented by the separate non-interactive command.
+- An excluded match skips the OS sandbox for the entire Bash tool call. This is
+  a convenience exception, not a security boundary: it weakens isolation and
+  matching is heuristic. A compound call is excluded only when **every**
+  non-empty executable subcommand matches an exclusion; one unmatched segment
+  or a parse failure keeps the whole call sandboxed. Normal Bash permission
+  and safety-policy checks still apply:
+  exclusion does not itself grant tool permission.
+
+Filesystem settings are merged with permission-derived paths. Existing parents
+are canonicalized, sensitive UR/settings/skill paths are made non-writable, and
+a sandbox-created bare-repository signature is scrubbed only when all required
+signature paths appeared after the command.
+
+Selective network-domain enforcement is not implemented by the compatibility
+runtime. If allowed/denied domain lists are present, it fails closed by blocking
+network for the sandboxed process instead of pretending to enforce host-level
+filtering.
+
+### Deny-default helper versus active profile
+
+`buildSeatbeltProfile()` has a source-level `denyByDefault` option and also uses
+a `(deny default)` profile when `allowRead` is non-empty. However,
+`denyByDefault` is not part of `SandboxSettingsSchema`, and the shipped runtime
+adapter does not pass it. With no `allowRead`, the macOS compatibility profile
+uses `(allow default)` plus write/network/targeted denials. Therefore
+`denyByDefault` is a tested builder capability, not a selectable shipped
+setting. Linux `bwrap` separately mounts `/` read-only when no read allow-list
+is supplied.
+
+## Project shell safety policy — enforced for Bash
+
+`.ur/safety-policy.json` classifies commands as read-only, project edits, safe
+local commands, network operations, or destructive operations. Bash permission
+checks consume this evaluation.
+
+```text
+/safety status
+/safety init
+/safety check --command "rm -rf build" --json
+```
+
+## Untrusted-content framing — enforced on three channels
+
+`src/security/promptInjection.ts` provides deterministic detection and framing,
+not a proof that prompt injection is impossible.
+
+| Function | What it does |
+|---|---|
+| `scanForInjection(text)` | Detects seven instruction/exfiltration/boundary patterns plus hidden Unicode and reports a score. |
+| `stripHiddenCharacters(text)` | Removes zero-width and bidirectional control characters. |
+| `wrapUntrusted(text, source)` | Adds a random 128-bit nonce boundary, warning labels, and an in-memory source-ledger record. |
+| `makeCanary()` / `canaryLeaked()` | Standalone canary helpers. |
+
+The shipped automatic wrappers are exactly:
+
+- `WebFetch` textual results;
+- `WebSearch` formatted results (its citation reminder stays outside the data
+  boundary); and
+- textual MCP tool-result blocks, except a tool explicitly marked as a trusted
+  control channel.
+
+Local file reads, GitHub tool results, arbitrary user text, and every other
+tool result do not pass through this wrapper merely because the module comment
+mentions those threat classes. `makeCanary()` and `canaryLeaked()` are exported
+helpers but are not installed in the main query/tool loop. `/sources` exposes
+the bounded in-memory provenance created by actual `wrapUntrusted()` calls; it
+does not prove that a model used a source to form a claim.
+
+The durable boundaries remain permissions, OS sandboxing where enabled, scoped
+credentials, and explicit human approval.
+
+## Guardrails — manual checks plus two diff gates
+
+Rules in `.ur/guardrails/*.json` support `regex`, `contains`, `pii`,
+`maxLength`, `jsonSchema`, and `llm`; phases are `input`, `output`, or `both`;
+actions are `warn` or `block`.
+
+```text
+/guardrails init
+/guardrails list
+/guardrails validate
+/guardrails check "send this to x@y.com" --phase output --json
+```
+
+`/guardrails check` evaluates the supplied text and reports a tripwire. The
+engine is **not** a universal pre/post hook on every normal tool call. Its
+deterministic diff-compatible rules are additionally wired into:
+
+- `agent-task pr --create` self-review; and
+- the Agent CI review path.
+
+LLM and JSON-schema guardrails are not part of those diff gates. A blocking
+finding prevents the relevant PR/CI handoff unless that command's explicit
+override path is used; it does not globally stop unrelated agent activity.
+
+## Security toolkit — deterministic/local commands
+
+The `/security` family is a command toolkit, not a collection of automatically
+invoked model tools:
+
+```text
+/security scan
+/security code
+/security secrets
+/security report
+/scope set local
+/threat-model
+/vuln
+/ir
+/compliance
+/playbook
+/harden
+/kali
+/lab create web-vuln
+```
+
+Workspace code/secret scans are bounded heuristic scanners. `/vuln` consults
+the dependency vulnerability implementation and can report no results when the
+registry is unavailable. `/ir` and `/harden` are read-only collection/check
+paths. `/scope` controls the security module's active web/testing operations;
+it is separate from ordinary UR filesystem tool permissions. Lab creation
+accepts only known templates and rejects unsafe roots.
+
+The bundled `/security-review` skill is a model workflow prompt with explicit
+verification and publishing instructions. Its existence does not turn the
+security scanners into a universal automatic gate.
+
+## Devcontainer target
+
+`/devcontainer` is an explicit Docker-backed execution target described by
+`.ur/devcontainer.json`:
+
+```text
+/devcontainer status
+/devcontainer init --image node:22
+/devcontainer exec -- npm test
+```
+
+It affects commands deliberately routed through the devcontainer command. It
+does not transparently move every Bash/tool call into Docker.
+
+## Stability ledger — recording is enforced; analysis is advisory
+
+Normal tool start/finish hooks append action evidence to `.ur/actions.jsonl`.
+The commands below inspect that ledger:
+
+```text
+/stability metrics
+/stability firewall
+/stability why "ECONNRESET"
+/stability policy
+/stability cooldown
+/evidence 20
+/actions 10
+```
+
+`metrics`, `firewall`, `why`, and `cooldown` calculate failure, latency,
+repetition, blast-radius, or likely-cause summaries. `firewall` prints an
+advisory recommendation; it does not pause or cancel the core query loop.
+`StabilityMonitor` is a self-contained source API and is not instantiated by
+the normal query loop. This is a Monitor/Analyze evidence layer, not a fully
+automatic MAPE-K controller.
+
+## Verifier gates — separate enforced query-loop layer
+
+The verifier is independent of `/stability`. In the default `strict` mode its
+L1 query-loop checks include empty turns, repeated calls, completion claims
+versus successful tool effects, unfinished actionable tasks, and configured or
+auto-detected project gates after edits. Interactive sessions ask before
+running project gates; non-interactive sessions can run them directly unless
+`verifier.askBeforeGates` says otherwise. `UR_VERIFIER_MODE=loose|off` weakens
+or disables these checks.
+
+Immediate promises such as “let me create it now” are checked only in the final
+visible clause and require matching successful mutation evidence. Rejections
+are capped at three per user turn to avoid an infinite correction loop. The
+independent L2 verification subagent is opt-in through `/verify` or
+`UR_VERIFIER_AUTO_SUBAGENT=1`; it is not auto-spawned by default.
+
+## Claim ledger and credentials
+
+`/claim-ledger add` stores claim/source strings in
+`.ur/evidence/claims.json` through the contained private-state writer (atomic
+replacement, regular-file/symlink checks, `0600` mode, and a 2 MiB bound).
+Loading is fail-closed: malformed JSON, a wrong root shape, duplicate IDs,
+unsupported confidence/source kinds, or malformed records make `list`,
+`validate`, and `add` fail nonzero; `add` never replaces the corrupt file with
+an empty ledger. Source kinds are `web`, `file`, `mcp`, `tool`, and `user`.
+`validate` checks only this stored structure; it does **not** fetch URLs, open files,
+or prove that a source still resolves.
+
+On macOS, credentials prefer Keychain and fall back to
+`~/.ur/.credentials.json` when keychain reads/writes fail. On Linux and Windows,
+the current implementation uses that plaintext JSON store directly. The file
+is chmod `0600`, but it is still plaintext; “kept in the OS keychain” is not a
+cross-platform guarantee. `/privacy-settings` and `--offline` control
+telemetry/network behavior separately from credential storage.

package/technical/13-research.md

@@ -0,0 +1,129 @@
+# 13 — Research & File/Media Analysis
+
+Source of truth: `src/services/agents/workingMode.ts`,
+`src/constants/prompts.ts`, `src/ur/{notes,researchGraph,fileops,sysinfo}.ts`,
+and `src/commands/{research,paper,cite,graph,read,search,index,summarize,analyze,convert,image,video,youtube,mode}/`.
+
+## Working mode
+
+```text
+/mode research
+/mode code
+/mode debug
+/mode browser
+/mode image
+/mode video
+/mode data
+```
+
+The selected value is persisted in `.ur/mode`. `getWorkingModePrompt()` loads it
+for the `working_mode` system-prompt section, so it changes the behavioral
+instructions used on subsequent model turns. Invalid or unreadable values fall
+back to `code`; changing the mode atomically writes a regular in-workspace
+marker and clears the system-prompt section cache. A failed write returns
+nonzero and leaves the previous marker intact.
+
+This is prompt guidance, not a different model, tool registry, permission mode,
+or deterministic workflow engine. Security-specific mode names are handled by
+the separate security module.
+
+## Notes, papers, and citations
+
+| Command | Actual operation | Example |
+|---|---|---|
+| `/research [note]` | Append a timestamped research note, or list notes. | `/research RAG eval baselines chosen` |
+| `/paper [title or path]` | Append a paper string, or list papers. It does not parse a PDF. | `/paper papers/mamba.pdf` |
+| `/cite [citation]` | Append a citation string, or list citations. It does not resolve or validate the citation. | `/cite Gu & Dao 2023` |
+
+These are per-project file-backed collections under `.ur/`; they do not
+automatically enter the model context merely because they were stored. Record
+text is non-empty and capped at 64 KiB. The `.ur/research/` directories and
+JSONL collection files must be regular in-workspace paths; symlinked storage,
+read failures, and write failures return a nonzero command result rather than
+claiming success.
+
+## “Research graph”
+
+`/graph` is currently a set of typed append-only JSONL collections under
+`.ur/graph/`, not an edge-traversable graph database.
+
+Supported entity names are `sources`, `papers`, `claims`, `methods`, `datasets`,
+`metrics`, `limitations`, `citations`, `concepts`, `notes`, `experiments`,
+`open_questions`, and `links`.
+
+```text
+/graph
+/graph papers
+/graph papers Mamba: Linear-Time Sequence Modeling
+/graph claims SSMs match attention at 1B scale
+```
+
+With no argument it reports per-collection counts. With an entity it lists
+that collection. With an entity plus text it appends `{ts,text}`. Records do
+not have IDs or validated links, so this surface must not be described as a
+relational or knowledge graph. Writes are bounded, reject symlinked/outside
+storage, and report a nonzero failure instead of claiming a record was saved.
+
+## Text-file helpers
+
+| Command | Operation |
+|---|---|
+| `/read <path>` | Return a bounded text-like file to the user/model. |
+| `/summarize <path>` | Return the bounded file prefixed with a summarization instruction. The model performs the summary. |
+| `/analyze <path>` | Return the bounded file prefixed with an analysis instruction. The model performs the analysis. |
+| `/search <query>` | Case-insensitive substring search across bounded workspace text files; at most 60 hits. |
+| `/index` | Write a path-only workspace index to `.ur/index/files.txt`; this is not an embedding index. |
+
+`/read`, `/summarize`, and `/analyze` accept the entire remaining command string
+as the path, so workspace-relative paths containing spaces work without special
+token parsing. `readFileSafe()` rejects absolute paths, `..`, directories,
+binary extensions, and symlinks that resolve outside the workspace. Reads are
+truncated at 64,000 characters by default.
+
+`/search` and `/index` walk at most 8,000 entries and skip hidden entries other
+than `.ur` plus common dependency/build directories. They are dependency-free
+convenience helpers, not substitutes for the model tools `Grep`, `Glob`, or
+semantic `CodeSearch`. The walker canonicalizes candidate files and skips
+symlinks resolving outside the workspace. `/index` writes atomically beneath a
+canonical in-workspace `.ur/index/` directory and returns nonzero if
+`files.txt` cannot be persisted.
+
+## Conversion and media commands
+
+These commands have intentionally narrow behavior:
+
+| Command | What it actually does |
+|---|---|
+| `/convert <file> <target>` | Reports which of `pandoc`, `ffmpeg`, and `libreoffice` are installed. It does **not** execute a conversion or create an output file. |
+| `/image <file> [task]` | Reports extension/size and, when `tesseract` exists, runs bounded OCR. It ignores the optional task text and does not invoke a vision model. |
+| `/video <file\|url> [task]` | For a local file, reports bounded `ffprobe` format/stream metadata. For a URL, reports whether `yt-dlp` is installed. It does not extract frames/audio and ignores task text. |
+| `/youtube <url> [task]` | Runs `yt-dlp --dump-json --skip-download` and prints selected metadata/description. It does not fetch subtitles/transcripts or summarize, and ignores task text. |
+
+`/convert`, `/image`, `/video`, and `/youtube` take only the first whitespace
+token as the file/URL (and `/convert` takes the second as target), so paths
+containing spaces are not supported by those four parsers. Their output may
+suggest asking the agent to use Bash or a vision-capable model for the next
+step, but the local command itself has not performed that next step.
+`/image` and `/video` also accept absolute paths and do not enforce workspace
+containment.
+
+`/os` reports presence of `git`, `ollama`, `node`, `bun`, `python3`, `ffmpeg`,
+`yt-dlp`, `rg`, `cargo`, and `go`. `/ur-doctor` repeats that tool list, probes
+the selected Ollama host, lists selected `.ur` assets, and checks for workspace
+Playwright. Its current `mcp cfg` line checks legacy
+`.ur/mcp/servers.toml` paths rather than the normal `.mcp.json`/settings MCP
+sources, so it is not an authoritative MCP configuration diagnostic.
+
+## Research-oriented bundled skills
+
+The normal build registers these user-invocable prompt workflows:
+
+- `/paper-implementation` (alias `/implement-paper`);
+- `/latex-paper` (alias `/latex`); and
+- `/benchmark` (aliases `/bench`, `/perf`).
+
+Their prompts instruct the model to spawn an isolated worktree agent, gather
+focused evidence, ask before a broader final verification sequence, and avoid
+commit/push/PR publication unless separately requested. Those are agent
+instructions, not a deterministic guarantee that the model completed every
+step; verify the returned worktree, diff, and command evidence.

package/technical/14-sessions.md

@@ -0,0 +1,177 @@
+# 14 — Sessions, History & Recovery
+
+Source of truth: `src/utils/{sessionStorage,sessionStoragePortable,fileHistory}.ts`,
+`src/cost-tracker.ts`, `src/commands/{resume,rewind,branch,export,tag,rename,session,tasks,stats,cost,usage,files}/`,
+`src/commands/bg/bg.ts`, `src/services/agents/backgroundRunner.ts`,
+`src/cli/transports/{SSETransport,WebSocketTransport}.ts`, `src/tasks.ts`, and
+`src/Task.ts`.
+
+## Transcript persistence
+
+Interactive sessions persist JSONL transcripts under
+`~/.ur/projects/<sanitized-project-path>/<session-id>.jsonl`. Session name,
+tag, mode, agent, worktree, and PR-link metadata are entries in that transcript.
+`cleanupPeriodDays: 0`, `--no-session-persistence` in print mode, test mode, or
+`UR_CODE_SKIP_PROMPT_HISTORY` suppresses transcript writes.
+
+Cost is **not** stored independently in every transcript. The cost tracker saves
+one “last session” cost/usage snapshot in the project entry of `~/.ur.json`; a
+resume restores it only when that stored `lastSessionId` matches. Older
+sessions can therefore have transcripts without a restorable cost snapshot.
+
+## Continue and resume
+
+```text
+ur -c
+ur -r
+ur -r 6f9d…
+ur -r "auth refactor"
+ur -c --fork-session
+ur --from-pr 123
+/resume [id or search]
+```
+
+- `-c` continues the most recent session for the project.
+- `-r` opens the picker; its optional value is an ID or search term.
+- `--fork-session` creates a new session ID while loading the prior
+  conversation.
+- `--from-pr` resolves a transcript linked to a GitHub PR.
+- `-n "name"` sets a startup title; `/rename` changes it later.
+
+`/tag <name>` stores exactly one searchable tag on the current session.
+Applying a different value replaces the prior tag; running the same value again
+opens the removal confirmation. This is not a many-tags-per-session system.
+
+Transcript appends use a single active drain with per-file FIFO queues. Failed
+entries are restored ahead of later arrivals, the failure is retained until
+`flush()` observes it, and a later `flush()` can retry after the underlying
+filesystem problem is repaired. Session IDs used to construct transcript paths
+must match the bounded alphanumeric/dash form.
+
+## Transport recovery
+
+For CCR-v2 remote sessions, `SSETransport` validates numeric sequence IDs,
+requires contiguous delivery, advances its checkpoint only after delivering a
+valid frame, and reconnects on malformed, mismatched, gapped, or incomplete
+frames.
+
+`WebSocketTransport` keeps a maximum of 1,000 meaningful outbound frames for
+replay. On overflow it drops the oldest buffered frame and logs a diagnostic.
+Reconnection replays buffered UUID messages and control frames that use
+`request_id`. Frames remain buffered until a reconnect reports a last-received
+UUID; confirming that UUID evicts it and every earlier buffered frame. A buffer
+containing only control frames has no per-control acknowledgement key, so those
+frames can replay again on later reconnects.
+
+These are transport-level guarantees. They do not make an unavailable remote
+service durable, and the direct-connect/remote-control launch commands are
+source-only in the normal external bundle as described in chapter 11.
+
+## Checkpoints, rewind, branches, and side chats
+
+File-history snapshots are captured as agent edits occur.
+
+```text
+/rewind
+/checkpoint
+/branch try-other-approach
+/fork try-other-approach
+/btw what's the difference between execa and spawn?
+```
+
+`/rewind`/`/checkpoint` can restore conversation state, UR-managed file
+snapshots, or both. These snapshots are separate from git commits.
+
+`/branch`/`/fork` copies the persisted main-chain conversation into a new
+session ID and switches to it; the optional argument is the branch session
+title. `/btw` manages a durable side chat without replacing the main chain.
+
+## Export and inspection
+
+```text
+/export session.txt
+/copy
+/trace
+/agent-inspect
+/cost
+/stats
+/usage
+/insights
+```
+
+`/export [filename]` renders the same plain-text transcript for both supported
+filename suffixes. Explicit `.txt` and `.md` suffixes are preserved, so
+`/export session.md` writes `session.md`; `.md` does not select a separate
+Markdown renderer. A missing suffix or any other suffix is normalized to
+`.txt`. Without a filename, the interactive export dialog offers a generated
+`.txt` name or clipboard behavior. File targets must be relative to the
+workspace, their parent directory must already exist, and traversal or symlink
+escapes are rejected.
+
+`/cost` reports the in-memory current-session cost/duration for API-key/local
+usage. For ordinary UR subscription users it reports subscription/overage state
+instead of an exact dollar breakdown and is hidden from the slash menu.
+`/stats` is an interactive activity view; `/usage` opens the Usage settings tab
+for plan limits. They are not aliases for the same data.
+
+`/files` lists the paths in the current read-file cache, but its command is
+enabled only for `USER_TYPE=ant`; it is not available in the normal external
+build. `/trace` and `/agent-inspect` expose recent/tool and subagent execution
+views respectively.
+
+## Detached background agents — shipped
+
+The supported external command family is `ur bg`, not the source-only legacy
+`--bg`, `ur ps`, `ur logs`, `ur attach`, and `ur kill` fast paths.
+
+```text
+ur bg run "run the full test suite and summarize"
+ur bg fanout "audit each package" --agents 3 --worktree
+ur bg list
+ur bg status <id>
+ur bg logs <id> --tail 120
+ur bg attach <id>
+ur bg steer <id> --message "focus on the failing integration test"
+ur bg kill <id>
+```
+
+`run` starts one detached child; `fanout` starts the requested bounded number.
+`--worktree` is opt-in. `--pr` is also opt-in and is rejected without
+`--worktree`; when supplied, it authorizes the background PR/push handoff
+configured by the remaining PR flags. `--dry-run` records/plans the task without
+spawning its worker.
+
+State, logs, outputs, and idempotent steering inboxes live under the git/project
+root's `.ur/background/`. The manifest is lock-protected and atomically
+replaced. Steering applies only to queued/running tasks and is bounded to
+64 KiB per message and 8 MiB per inbox.
+
+The legacy `--bg` and process-level `ps|logs|attach|kill` fast paths are behind
+the `BG_SESSIONS` build feature, which the normal external bundle does not
+enable. They must not be documented as the supported npm command syntax.
+
+## In-session tasks
+
+`/tasks` (alias `/bashes`) opens the task dialog for the current process.
+`TaskOutput` reads task output and `TaskStop` stops a supported running task.
+The five creatable lifecycle implementations in the external runtime are:
+
+- local shell;
+- local agent;
+- remote agent;
+- in-process teammate; and
+- dream.
+
+`local_workflow` and `monitor_mcp` remain parseable/renderable historical task
+types, but have no constructor or stop lifecycle in this distribution. A stop
+request for them returns an explicit unsupported-type error.
+
+## Multi-directory access and trust
+
+- `/add-dir ../other-repo` or `--add-dir` extends the allowed working
+  directories; normal path/permission checks still apply.
+- Interactive startup asks whether the workspace is trusted. Print mode skips
+  that dialog and therefore must be used only in a directory the caller already
+  trusts.
+- `/ur-init` scaffolds UR project assets under `.ur/`; `/init` generates the
+  agent-instruction file (`UR.md`).

package/technical/README.md

@@ -0,0 +1,43 @@
+# UR-Nexus — Technical Specifications
+
+> Audited against the executable source and tests for `ur-agent` v1.65.7.
+> Command, tool, flag, provider, and setting claims are checked against the
+> implementation rather than copied from product prose. Release validation
+> keeps this version synchronized and packages the complete `technical/`
+> catalog with the npm artifact.
+
+UR-Nexus is an autonomous engineering workflow engine: a terminal (Ink/React) coding agent
+with a plan → execute → test → verify → document → benchmark loop, local/server model support
+(Ollama, llama.cpp, and vLLM), cloud API providers (OpenAI, Anthropic, Gemini, OpenRouter,
+and any OpenAI-compatible endpoint), a multi-agent orchestration layer, and a large built-in
+command/tool surface. An LM Studio adapter remains in the registry but is explicitly disabled
+in this release, so it is not advertised as an available backend.
+
+## Document map
+
+| File | Contents |
+|---|---|
+| [01-architecture.md](01-architecture.md) | Runtime architecture: entrypoints, REPL, query engine, task types, services |
+| [02-cli-reference.md](02-cli-reference.md) | The `ur` binary: flags, subcommands, headless mode, background sessions |
+| [03-slash-commands.md](03-slash-commands.md) | Every interactive slash command with usage examples |
+| [04-tools.md](04-tools.md) | Every model-invocable tool (built-in + conditional) with schemas and examples |
+| [05-providers-and-models.md](05-providers-and-models.md) | Provider registry, model selection, routing, escalation, effort/fast modes |
+| [06-configuration.md](06-configuration.md) | settings.json schema, scopes, permission rules, env variables, keybindings |
+| [07-memory-and-context.md](07-memory-and-context.md) | UR.md, auto-memory, /remember, semantic memory, knowledge base, context pack, compaction |
+| [08-skills-plugins-workflows.md](08-skills-plugins-workflows.md) | Skills (SKILL.md), bundled skills, plugins/marketplaces, declarative workflows, patterns, toolsmith |
+| [09-multi-agent.md](09-multi-agent.md) | Subagents, crews, arena, background agents, routing, escalation, worktrees per task |
+| [10-headless-automation-eval.md](10-headless-automation-eval.md) | `-p` print mode, /exec, SDK, automations, triggers, CI loop, eval harness, benchmarks |
+| [11-integrations.md](11-integrations.md) | MCP, IDE/ACP, A2A, Chrome, GitHub, Slack, remote control, desktop, voice |
+| [12-security-sandbox-stability.md](12-security-sandbox-stability.md) | Permission system, sandbox, safety policy, guardrails, security toolkit, stability/MAPE-K |
+| [13-research.md](13-research.md) | Research notes, papers, citations, research graph, file/media analysis commands |
+| [14-sessions.md](14-sessions.md) | Session persistence, resume, rewind/checkpoints, branching, export, tags, insights |
+
+## Quick facts (from code)
+
+- **Package**: `ur-agent`, binary `ur` (`bin/ur.js` → `dist/cli.js`, bundled from `src/entrypoints/cli.tsx`).
+- **Runtime**: the npm binary uses a Node ≥ 18.18 launcher and requires Bun ≥ 1.3 for the bundled CLI; the TUI uses React 19 and the vendored Ink fork in `src/ink`.
+- **Local-first**: default model backend is the local Ollama runtime (`http://localhost:11434`); `--offline` disables all cloud paths.
+- **Registered commands at this release**: 168 bundled registry entries, 161 visible entries, 237 visible slash invocation tokens, and 70 rows in `ur --help`; fast-path lifecycle/server commands are documented separately in doc 02. User/project skills, installed plugins, workflows, and MCP prompts are additive and normalized by source priority.
+- **Registered tools**: the built-in pool is assembled per session from `src/tools.ts:getAllBaseTools()` and then filtered by runtime, mode, settings, permissions, and availability. Doc 04 enumerates the public built-ins and every supported gate; connected MCP tools are additive.
+- **Feature flags**: compile-time `feature(...)` gates (`bun:bundle`) dead-code-eliminate internal-only surfaces from external builds; `USER_TYPE=ant` gates internal commands.
+- **Project state**: lives under `.ur/` in each repo (artifacts, specs, workflows, guardrails, safety policy, knowledge, memory index, devcontainer config, tools, index).