ur-agent 1.65.6 → 1.65.7

package/technical/07-memory-and-context.md

@@ -0,0 +1,147 @@
+# 07 — Memory & Context Management
+
+Source of truth: `src/memdir/`, `src/services/{SessionMemory,extractMemories,compact,contextCollapse}/`,
+`src/commands/{memory,remember,forget,memory-retention,semantic-memory,knowledge,context-pack,compact,context}`.
+
+## Layered memory model
+
+| Layer | Location | Written by | Loaded |
+|---|---|---|---|
+| Project instructions | `UR.md` (repo root, committed) | user or `/init` | normal, non-`--bare` root sessions |
+| Local project instructions | `UR.local.md` (gitignored) | user | normal, non-`--bare` root sessions |
+| Auto-memory (memdir) | the project-scoped auto-memory path under `~/.ur` (`autoMemoryDirectory` setting; `UR_CODE_REMOTE_MEMORY_DIR` in containers) | the main agent, while working, when the injected memory instructions call for a durable note | either the bounded `MEMORY.md` index or selected topic attachments, depending on the relevance-recall gate |
+| Team memory | shared team paths (`teamMemPaths.ts`, `TEAMMEM` build gate) | team sync service | source-only in this repository's standard npm build |
+| Session transcripts | `~/.ur/projects/<slug>/` | automatic | via `/resume`, past-session search |
+
+### Auto-memory (memdir)
+- On by default; disable via `UR_CODE_DISABLE_AUTO_MEMORY=1`, `--bare`, or
+  `autoMemoryEnabled: false` (project-level opt-out supported).
+- The stable path loads the byte/line-capped `MEMORY.md` index. When the
+  `tengu_moth_copse` runtime gate is enabled, UR instead performs a
+  non-blocking recall: a lexical header prefilter narrows candidates, a small
+  model selects at most three, and each selected file is truncated and
+  session-byte-capped before attachment. A failed or late selector never blocks
+  the main turn.
+- Topic files use frontmatter (`name`, `description`,
+  `type: user|feedback|project|reference`); `MEMORY.md` is their index.
+- The normal npm build asks the main agent to maintain these files directly.
+  The separate turn-end `extractMemories` implementation is behind the
+  compile-time `EXTRACT_MEMORIES` feature and is not bundled by
+  `scripts/bundle.mjs`; setting an environment variable alone cannot enable
+  that background extractor.
+- `/memory` opens memory files for editing. There is no special `#` prompt
+  prefix for writing a note.
+- `/remember <text>` writes the legacy project note and also promotes the note
+  into auto-memory when enabled. `/forget <text>` removes matching legacy
+  notes, their deterministic promoted topic files, and the corresponding index
+  links. Persistence failures are reported as failures or partial results,
+  rather than as successful saves. The project-note JSONL text is non-empty
+  and capped at 64 KiB; its `.ur/memory/` path must remain a regular directory
+  inside the canonical workspace, and symlinked collection files are rejected.
+
+### Explicit memory commands
+```
+/remember we never bump major versions on Fridays   # save a fact
+/forget Fridays                                     # remove matching notes
+/memory                                             # edit files interactively
+/memory-retention set --ttl-days 90 --max-entries 500 --decay-days 14
+/memory-retention prune                             # apply the policy now
+```
+The bundled `/remember` skill (no args) reviews auto-memory and proposes promotions to
+UR.md / UR.local.md and detects stale/duplicate/conflicting entries.
+
+### Automatic learning
+- On by default; disable via `UR_CODE_DISABLE_AUTO_LEARNING=1` or
+  `automaticLearningEnabled: false`.
+- ci-loop, arena, escalation, test-first, and cloud-task outcomes are folded into
+  `.ur/learning/stats.json` as local JSON. This automatic path uses no model
+  calls and no prompt tokens.
+- Learned success rates bias auto model routing and escalation only when there
+  is enough evidence; otherwise static routing is unchanged.
+
+### Lexical memory index
+```
+/semantic-memory build            # build a local lexical index
+/semantic-memory search "how do we rotate tokens"
+/semantic-memory status
+```
+
+Despite the historical command name, this implementation does not call an
+embedding model. It tokenizes paragraphs from `UR.md`, `README.md`,
+`.ur/memory/`, and `.ur/docs/`, then ranks by query-token overlap. Use
+`/knowledge build --embeddings` or `/code-index build` when dense embedding
+retrieval is required.
+
+### Knowledge base (`/knowledge`, alias `/kb`) — curated, with provenance
+```
+/knowledge add src/auth/jwt.ts --note "token flow" --label auth
+/knowledge build --embeddings --embed-model nomic-embed-text
+/knowledge search "refresh rotation"
+/knowledge prune --older-than 60
+/knowledge status
+```
+
+### Context pack (`/context-pack`, aliases `/ctx-pack`, `/project-manifest`)
+Repo-architecture summary + task memory + compressed project context in `.ur/context/`:
+```
+/context-pack scan
+/context-pack remember --type decision --text "we chose fastify over express"
+/context-pack memory verify
+/context-pack memory quarantine
+/context-pack memory rollback --to <entry-id>
+/context-pack compress
+/context-pack status
+```
+Types: `decision | constraint | command | diff | note | architecture |
+preference | attempt | accepted | rejected`. New entries contain UUIDs,
+source provenance, content digests, and a SHA-256 previous-entry chain. Appends
+are locked, private, no-follow, and fsynced; reads fail closed. Quarantine and
+rollback preserve a private copy of the full original before replacement.
+
+## Context window management
+
+| Feature | How |
+|---|---|
+| Visualize usage | `/context` (colored grid); `/files` is an ant-only command and is absent from the standard npm CLI |
+| Manual compaction | `/compact [focus instructions]` |
+| Auto-compaction | `src/services/compact` — triggers near the limit; `DISABLE_AUTO_COMPACT` env disables; PreCompact/PostCompact hooks fire |
+| Context collapse | `src/services/contextCollapse` and `CtxInspect` are behind the compile-time `CONTEXT_COLLAPSE` feature, which the standard npm bundle does not include |
+| Micro-compaction | session-memory compact (`sessionMemoryCompact.ts`): force on with `ENABLE_UR_CODE_SM_COMPACT=1`, force off with `DISABLE_UR_CODE_SM_COMPACT=1`; otherwise both `tengu_session_memory` and `tengu_sm_compact` runtime gates must be on |
+| Clear | `/clear` (aliases `/reset`, `/new`) |
+| Read caps | Read tool truncates large files/lines; `/read`, `/analyze`, `/summarize` for deliberate loads |
+
+## Repo wiki & map
+
+```
+/wiki generate       # .ur/wiki/: overview, architecture, dependency map (from DNA + code index)
+/wiki install-hook   # refresh automatically after every merge
+/wiki map            # regenerate .ur/repo-map.md
+```
+When `.ur/repo-map.md` exists and is fresh (less than seven days), a byte-capped
+repo map is injected into the system prompt automatically (zero tokens until
+generated).
+
+## Project DNA & indexes
+
+```
+/dna              # detect language, package manager, build/test/lint → .ur/dna
+/index            # build workspace file index (.ur/index)
+/code-index build # semantic embeddings index — CodeSearch auto-enables once built
+/code-index watch # keep it fresh
+/code-index search "debounce input"
+```
+`/project` and `/workspace` display the recorded DNA + workspace facts.
+
+## What gets injected into the system prompt
+
+The interactive and print entrypoints both assemble the prompt through
+`src/constants/prompts.ts` plus the context helpers. A normal root prompt
+includes UR.md/UR.local.md instructions, auto-memory as described above, the
+active working-mode discipline, output style, enabled-tool guidance, and
+environment information. Read-only `Explore` and `Plan` subagents omit the
+UR.md hierarchy when the default-on `tengu_slim_subagent_agentmd` runtime gate
+is active and the caller did not explicitly supply user context. Project DNA
+is not injected directly; it can appear through a fresh generated repo map.
+`--bare` replaces the root prompt with a minimal prompt and drops automatic
+memory, hooks, and most extras. The internal `--dump-system-prompt` diagnostic
+exists only in ant builds.

package/technical/08-skills-plugins-workflows.md

@@ -0,0 +1,211 @@
+# 08 — Skills, Plugins & Workflows
+
+Source of truth: `src/skills/`, `src/utils/plugins/`, `src/plugins/`,
+`src/services/agents/{workflows,patterns}.ts`, `src/tools/WorkflowTool/`.
+
+## Skills
+
+Two skill formats coexist:
+
+### 1. Prompt skills (SKILL.md)
+Directory format `skill-name/SKILL.md` with Agent Skills-compatible YAML
+frontmatter (`name`, `description`, optional `license`, `compatibility`,
+`metadata`, `allowed-tools`). Loaded from:
+- project: `.ur/skills/<name>/SKILL.md`
+- user: `~/.ur/skills/<name>/SKILL.md`
+- cross-client project/user: `.agents/skills/<name>/SKILL.md` and
+  `~/.agents/skills/<name>/SKILL.md`
+- plugins and MCP servers (MCP skills never execute embedded shell blocks)
+- bundled skills compiled into the binary (`src/skills/bundled/`, list in doc 03 §13)
+
+Resolution is deterministic: nearer project roots beat parent roots, project
+beats user, and native `.ur` beats cross-client `.agents` at the same scope.
+
+Body supports `${UR_SKILL_DIR}` (skill directory path) and `${UR_SESSION_ID}`
+substitution, plus the exclamation-backtick inline form and
+exclamation-labelled fenced shell blocks for any loaded non-MCP prompt skill.
+Those commands still pass through the normal
+shell-tool permission checks and the skill's `allowed-tools` rules. Remote MCP
+skills never execute embedded shell; “local” here is not a cryptographic trust
+claim.
+
+```
+/create-skill release-notes "draft release notes from git log" --project
+# → .ur/skills/release-notes/SKILL.md, then invoke with:
+/release-notes v2.1
+```
+`/skills` opens the prompt-skill browser; the model can also self-invoke prompt
+skills through the `Skill` tool. `/skill` is intentionally separate and runs
+the executable `skill.yaml` workflows below. Neither slash token aliases the
+other.
+`/skillify` (bundled) converts the current session's workflow into a skill.
+
+For a file-backed `SKILL.md`, UR attempts to compute deterministic content-tree
+and permission digests and validates names, directory identity, field
+types/lengths, and metadata; signed skills cannot contain symlinks. Trust
+commands:
+
+```
+ur skill verify <name-or-directory> [--require-trusted] [--json]
+ur skill keygen <key-id> [--out <private-key.pem>]
+ur skill sign <name-or-directory> --key <private-key.pem> --key-id <key-id>
+```
+
+Ed25519 manifests embed the public key and signed digests. Trusted keys live in
+a private store (override its file with `UR_SKILL_TRUSTED_KEYS_FILE`). In the
+default mode, provenance-inspection and Agent Skills validation failures are
+logged and an otherwise readable skill may still load.
+`UR_SKILLS_STRICT_SPEC=true` rejects invalid or uninspectable skills;
+`UR_SKILLS_REQUIRE_TRUSTED_SIGNATURE=true` requires a verified trusted
+signature at load. When provenance was successfully recorded, UR re-hashes the
+file tree immediately before invocation to detect changes after discovery.
+The corresponding `ur skill` trust flags are declared by the shipped CLI, not
+only by the local command parser.
+
+### 2. Executable skills (skill.yaml) — skills as workflows
+`skill.yaml` is searched through the same project/user native and cross-client
+skill roots (`.ur/skills` and `.agents/skills`).
+`src/skills/skillSpec.ts` compiles it into a `WorkflowSpec`:
+
+```yaml
+version: 1
+name: deploy-checklist
+description: Gate a deploy behind checks
+allowedTools: [Bash, Read]
+steps:
+  - id: tests
+    name: Run tests
+    agent: general-purpose
+    prompt: Run the full test suite and report failures.
+  - id: approve
+    name: Human sign-off
+    agent: general-purpose
+    prompt: Summarize risk.
+    dependsOn: [tests]
+    gate: approval
+    checkpoint: true
+```
+The directory may include `instructions.md`, `scripts/`, `templates/`, and
+`checklists/` referenced via `${UR_SKILL_DIR}`. `allowedTools` is validated,
+copied to every compiled workflow step, and passed to the child `ur -p` process
+as its exact `--tools` pool; it is not merely descriptive metadata. Each
+step's `agent` is also forwarded as `ur --agent <name>`, so the selected
+built-in or project-defined agent governs that child session.
+
+```
+/skill list · /skill show deploy-checklist · /skill run deploy-checklist
+/skill approve deploy-checklist approve
+/skill run deploy-checklist --resume · /skill reset deploy-checklist
+/skill init <name>
+```
+
+An approval-gated step is held before its model/tool execution. Approval is
+accepted only for the currently held step, stored as a single-use token, and
+consumed by `run --resume`. A run that fails, is blocked, or is held returns a
+nonzero command status.
+
+The `ur skill verify|sign|keygen` supply-chain commands above operate on
+Agent Skills directories containing `SKILL.md`. Executable `skill.yaml`
+workflows are parsed and schema-validated, but that execution path does not
+currently require or verify the `SKILL.md` Ed25519 manifest. Do not treat
+signing a neighboring prompt skill as a signature over `skill.yaml`.
+
+All skill, plugin, workflow, and built-in invocation tokens pass through the
+same registry normalizer. Earlier sources retain priority, duplicate canonical
+tokens are omitted, and a later command loses only aliases already claimed by
+another command.
+
+## Workflows (`/workflow`, aliases `/wf`, `/workflows`)
+
+Declarative, checkpointed DAGs of agent steps (`src/services/agents/workflows.ts`).
+Each step: `id`, `name`, `agent` (subagent type), `prompt`, `dependsOn`,
+optional `allowedTools`, `gate: approval|verification`,
+`verificationMode: enforcing|advisory`, and `checkpoint: true`. Stored under
+`.ur/workflows/`.
+
+```
+/workflow init release             # scaffold
+/workflow validate release        # cycle/agent checks
+/workflow graph release --ascii   # Mermaid or ASCII rendering
+/workflow plan release            # topological dry-run
+/workflow run release             # execute until completion, failure, or a gate hold
+/workflow approve release step-id # approve the currently held approval step
+/workflow run release --resume    # consume approval/resume persisted progress
+/workflow next release            # show the next ready step
+/workflow done release step-id    # manually complete an ungated step only
+/workflow reset release
+```
+
+Progress and exact step outputs are persisted after every completed step for
+crash recovery, within a 32 KiB per-step and 256 KiB per-run output budget.
+Oversized outputs are not silently truncated: the completed step remains done
+and is never replayed, while an output-dependent successor fails closed on
+resume and tells the operator to reset for an intentional rerun. Legacy state
+without captured outputs follows the same rule. Resumed completed steps are
+reported as done with zero executions in the resumed run, not as skipped.
+`checkpoint: true` additionally creates a semantic checkpoint record.
+Parallel waves use all-settled accounting: if one branch fails, every sibling
+that already ran is still recorded and successful siblings remain completed;
+only dependent, unstarted steps are reported as skipped.
+Verification gates require exactly one standalone non-error `VERDICT: PASS`
+line; inline, missing, or multiple verdicts, `FAIL`, `PARTIAL`, and runner
+errors fail closed unless that step explicitly
+sets `verificationMode: advisory`. Non-completed CLI runs return nonzero.
+The declared `agent` is passed to each child session through `--agent`; the
+built-in `worker` alias falls back to `general-purpose`, while a project
+definition named `worker` takes precedence.
+Workflow execution is foreground in this build. Historical
+`LocalWorkflowTask` records remain renderable, but no runtime constructor or
+stop operation advertises them as live background tasks.
+
+## Collaboration patterns (`/pattern`)
+
+Prebuilt multi-agent topologies (`src/services/agents/patterns.ts`):
+`peer` (plan-execute-express-review), `doe` (data-oriented ensemble), `concurrent`,
+`handoff`, `debate`, `parallel`.
+
+```
+/pattern list
+/pattern show peer
+/pattern run debate "adopt tRPC or keep REST?" --execute
+/pattern install peer --save     # materialize as an editable workflow
+```
+
+## Plugins
+
+Plugin manifests + marketplaces (`src/utils/plugins/`, `.ur-plugin/marketplace.json`
+format). Plugins can contribute: commands, skills, agents, hooks, MCP servers, output
+styles.
+
+```
+ur plugin marketplace add github.com/acme/ur-plugins   # or a local path
+ur plugin marketplace list / update / remove <name>
+ur plugin install fmt@acme -s project     # scopes: user | project | local
+ur plugin list --json --available
+ur plugin enable fmt / disable fmt / disable -a
+ur plugin update fmt
+ur plugin validate ./my-plugin            # manifest validation
+ur plugin doctor --path ./plugins         # diagnose
+/plugin                                    # interactive Ink UI (alias /plugins, /marketplace)
+/reload-plugins                            # activate pending changes in-session
+ur --plugin-dir ./dev-plugin               # session-only plugin load
+```
+Settings: `enabledPlugins`, `pluginConfigs`, `extraKnownMarketplaces`,
+`strictKnownMarketplaces`, `blockedMarketplaces`, `strictPluginOnlyCustomization`.
+
+## Local helper tools (`/toolsmith`)
+
+Scaffolds a small custom tool under `.ur/tools/<name>/` in python/bash/node/go/rust; UR
+runs it with approval like any command:
+```
+/toolsmith csv-differ python
+```
+
+## Automations (`/automation`)
+
+Project-local scheduled prompts (`.ur/automations/`), separate from skills:
+```
+/automation create nightly-tests --schedule "0 3 * * *" --prompt "run tests; open an issue on failure"
+/automation run-due                      # execute anything due now
+ur automation install --platform launchd --interval 300   # host scheduler integration
+```

package/technical/09-multi-agent.md

@@ -0,0 +1,249 @@
+# 09 — Multi-Agent Orchestration
+
+Source of truth: `src/tools/AgentTool/`, `src/services/agents/`, `src/commands/{agents,bg,crew,arena,pattern,task,worktree,route,escalate}`,
+`src/coordinator/coordinatorMode.ts`, `src/tools/Team*Tool/`.
+
+## Subagents (the `Agent` tool)
+
+The main agent can spawn subagents. Built-in agent types
+(`src/tools/AgentTool/built-in/`):
+
+| Type | Purpose |
+|---|---|
+| `general-purpose` | catch-all multi-step worker (all tools) |
+| `worker` | stable workflow/crew alias for `general-purpose`; a project-defined `worker` overrides it |
+| `verification` | verifies a change actually works (used by `/verify`) |
+| `statusline-setup` | configures the status line |
+| `ur-code-guide` | answers UR/SDK/API questions |
+| `Explore`, `Plan` | read-only search and planning agents, available only in builds compiled with `BUILTIN_EXPLORE_PLAN_AGENTS` and when their runtime gate is enabled; the standard npm bundle does not compile that feature |
+
+Custom agents:
+- `/agents` — interactive management UI.
+- Definition files loaded from agents directories (project + user), validated by
+  `AgentJsonSchema`: `description` (required), `prompt` (required), `tools`,
+  `disallowedTools`, `model` (or `inherit`), `effort`, `permissionMode`,
+  `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`,
+  `background`, and worktree `isolation`.
+- CLI: `ur --agents '{"reviewer":{"description":"…","prompt":"…"}}'` and
+  `ur --agent reviewer` to run a whole session as that agent.
+- `/agent-templates install <name>` installs reusable templates;
+  `/role-mode install architect|code|debug|ask` installs the four classic role modes as
+  scoped agents.
+
+When present, read-only `Explore`/`Plan` agents omit the UR.md hierarchy only
+when the default-on `tengu_slim_subagent_agentmd` gate remains enabled and the
+caller did not explicitly provide user context (token saving; see
+`loadAgentsDir.ts`).
+
+Inspection: `/agent-inspect` reconstructs a per-subagent timeline (spawns, prompts,
+results, verdicts, tools, tokens) from the session or a transcript file.
+
+## Fan-out limits (`src/tools/AgentTool/fanOutLimits.ts`)
+
+These limits apply specifically to nested, in-process launches through the
+`Agent` tool. Both are checked in `runAgent` before that child starts, so a
+refusal is free.
+
+| Limit | Default | Hard ceiling | Setting |
+|---|---|---|---|
+| Nesting depth | 3 | 10 | `agents.maxDepth` |
+| Concurrent agents | 20 | 100 | `agents.maxConcurrent` |
+
+```json
+{ "agents": { "maxConcurrent": 40, "maxDepth": 4 } }
+```
+
+Out-of-range, negative and non-numeric values clamp rather than disabling the
+governor — a settings file cannot switch it off. Exceeding a limit throws with
+a message naming both the limit and the setting that raises it. Slot ownership
+enters a single `try/finally` immediately after registration. Failures during
+context loading, hooks, skill or MCP setup, cache callbacks, query execution,
+cancellation, and normal completion all release it exactly once; partial setup
+resources are cleaned conditionally.
+
+Depth is derived from the live registry rather than passed down: a child's
+depth is its parent's plus one, and an agent whose parent is unknown counts as
+a root.
+
+`/crew`, `/arena`, `/bg fanout`, and `/exec` launch subprocess/worktree
+orchestrators and do **not** register in this `Agent`-tool governor. They have
+their own concurrency limits (`crew` clamps fixed and dynamic pools to 1–32;
+`bg fanout` and `exec` also clamp their public counts) and their own model/token
+cost. Detached background agents are separate processes with separate
+in-process registries.
+
+## Running several workers at once
+
+Four ways to parallelise, differing mainly in whether workers share your
+checkout:
+
+| Command | Shape | Isolation flag |
+|---|---|---|
+| `ur exec "a" "b" --concurrency 3` | different prompts in parallel | `--worktree` |
+| `ur crew run <name> --workers 4` | one goal split across a task board | `--worktrees` |
+| `ur arena "<task>" --agents 3` | same task, N attempts, judge picks | isolated by default |
+| `ur bg fanout "<task>" --agents 4` | detached, survives the session | `--worktree` |
+
+Pass the isolation flag whenever workers might touch the same files. Without
+it every worker edits the same checkout concurrently and they overwrite each
+other. Agents are much heavier than test workers — each is a full model session
+with its own token spend — so 4–6 is usually the practical ceiling on a laptop
+regardless of the configured limit.
+
+Isolation does not imply integration. `/crew --worktrees` creates a fresh
+worktree for every task attempt and leaves a passing attempt at its recorded
+path for lead/human review; it does not merge, cherry-pick, or apply those
+changes to the starting checkout. A dependent crew task receives its
+prerequisite's text result, but its fresh worktree does not inherit the
+prerequisite worktree's unmerged file changes. Design dependent code edits
+accordingly. `/exec --worktree` instead gives all steps of one top-level prompt
+the same plan worktree (doc 10).
+
+## Shared task-list correctness
+
+Interactive sessions use the canonical Task V2 tools. Print/headless sessions
+use legacy `TodoWrite` by default, or Task V2 when
+`UR_CODE_ENABLE_TASKS=1`. Both feed the same mutation gate:
+
+- Task IDs are ordered numerically (`1, 2, 10`), with non-numeric external IDs
+  sorted stably after numeric IDs.
+- Dependencies block transition or claim until prerequisites are complete.
+- Actionable `pending` or `in_progress` entries open the gate; completed and
+  internal entries do not.
+- Reads remain unrestricted. Ordinary mutations have a default allowance of
+  three preceding tool calls, counted by tool call rather than message.
+  Delegation and child mutations always require an actionable parent task.
+- An unreadable task store fails closed. Task create/update/list/get tools stay
+  exempt so the agent can repair the plan.
+- Configure the behavior at
+  `tasks.requireBeforeChanges.{enabled,freeReads}`.
+
+The prompt contract tells the model to update each task after observing its
+tool result. Runtime dependencies and mutation gating enforce ordering and
+plan presence; they cannot prove that an arbitrary natural-language task is
+semantically complete. Workflows and crews add stricter verdict rules where a
+machine-checkable execution boundary exists.
+
+## Task routing
+
+```
+/route "why does login 500 intermittently?"      # → recommends subagent + pattern
+/model-route "port to Rust" --strategy strong    # → recommends model (doc 05)
+/escalate run "hard problem" --oracle gpt-5.5    # fast model + oracle escalation (doc 05)
+```
+`src/services/agents/intentRouter.ts` does the task classification;
+`decomposer.ts` splits goals into tasks; `delegation.ts` hands tasks to workers.
+
+## Background agents (`/bg`, `ur bg`)
+
+Detached local agents managed by `src/services/agents/backgroundRunner.ts`:
+```
+/bg run "upgrade eslint to v9" --worktree         # isolated local worktree
+/bg run "upgrade eslint to v9" --worktree --pr    # explicit opt-in PR creation
+/bg fanout "fix all TODO(sec) comments" --agents 4
+/bg list · /bg status <id> · /bg logs <id> · /bg attach <id> · /bg kill <id>
+```
+The standard CLI exposes the same operations through `ur bg ...`. The separate
+process-session fast path (`ur --bg -p`, then top-level `ur ps|logs|attach|kill`)
+requires the `BG_SESSIONS` build feature and is not present in the normal npm
+bundle.
+
+## Crews (`/crew`) — shared task board
+
+A lead agent decomposes a goal into a task board; worker subagents claim and execute tasks
+(`src/services/agents/crew.ts`):
+```
+/crew create cleanup --goal "remove dead code and fix lints" --decompose
+/crew plan cleanup --goal "remove dead code and fix lints" --decompose
+/crew add cleanup --task "delete unused exports in src/utils"
+/crew run cleanup --workers 3 --worktrees
+/crew run cleanup --dynamic --max-workers 8   # scale workers to the board (own 1–32 cap)
+/crew show cleanup · /crew reset cleanup --max-attempts 2 · /crew delete cleanup
+```
+
+A task succeeds only when the worker process is non-error and returns exactly
+one standalone `VERDICT: PASS` line; inline, missing, or multiple verdicts,
+`PARTIAL`, and `FAIL` are failures. Automatic
+retries are bounded (hard cap five), cancellation-aware, and allowed only for
+dry runs or fresh worktree attempts. Shared-checkout failures are not replayed
+because their mutations are ambiguous. `--resume` and `reset` reopen only safe
+isolated attempts that still have budget; ambiguous claimed tasks are marked
+failed. Dynamic mode exits rather than spinning when claimed tasks prevent
+further progress. Fixed `--workers` and dynamic `--max-workers` are clamped to
+1–32 independently of the in-process `Agent`-tool governor. A board that is
+not completely done returns nonzero.
+
+## Arena (`/arena`) — best-of-N with a judge
+
+N agents attempt the same task in isolated worktrees, a deterministic judge compares the
+diffs, and a passing winner can be applied (`src/services/agents/arena.ts`). Worktree
+creation failure fails that candidate; it never falls back to concurrent writes in cwd.
+Only non-error `PASS` candidates with a non-empty, non-blocking diff can win:
+```
+/arena "make the image pipeline 2x faster" --agents 3 --max-turns 30
+/arena "…" --apply          # apply the winning diff
+/arena "…" --keep           # keep losing worktrees for inspection
+```
+
+## Worktree-per-task sessions
+
+```
+ur -w feature-x             # session in a fresh git worktree (+ --tmux for panes)
+/task start rate-limiter --worktree --base main
+/task run <id> · /task status <id> · /task list
+/task pr <id> --create --draft --base main
+/worktree list · /worktree status · /worktree clean
+```
+`EnterWorktree` / `ExitWorktree` tools let the model move itself into isolation mid-turn
+(worktree mode). Worktree settings: `worktree.symlinkDirectories`, `worktree.sparsePaths`.
+`task start --worktree` creates only local isolated state; it never pushes or
+opens a PR. Publishing begins only with the explicit `task pr --create`
+command.
+
+Bundled worktree skills (`/debug-v2`, `/refactor`, `/security-review`,
+`/dockerize`, `/paper-implementation`, `/latex-paper`, `/benchmark`, `/batch`)
+carry instructions to leave changes local, run focused checks while working,
+ask before the final full verification suite, and avoid commit/push/PR actions
+unless the user separately requests publishing. These are model instructions,
+not a separate OS enforcement boundary. `agentSkillRunner.createPr` defaults
+to false.
+
+## Teams / swarm mode (feature-gated)
+
+- The standard external build can opt into in-process teams with
+  `UR_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, subject to the
+  `tengu_amber_flint` runtime kill switch. This enables `TeamCreate`,
+  `TeamDelete`, `SendMessage`, `InProcessTeammateTask`, and the
+  `TeammateIdle` hook. `--agent-teams` is registered only in ant builds, so it
+  is not a supported external CLI flag.
+- Coordinator mode (`UR_CODE_COORDINATOR_MODE=1`) is additionally behind the
+  compile-time `COORDINATOR_MODE` feature. The standard npm bundle does not
+  include it; setting the environment variable there has no effect.
+- `/peers` and `ListPeers` are behind the compile-time `UDS_INBOX` feature and
+  are likewise absent from the standard npm bundle.
+- Team-memory synchronization is separately behind the compile-time `TEAMMEM`
+  feature; enabling teams does not make that source-only memory service appear.
+
+## Goals — long-horizon persistence (`/goal`)
+
+```
+/goal add v2-launch --objective "ship v2" --workflow release
+/goal list · /goal show v2-launch · /goal note v2-launch "auth blocked on infra"
+/goal resume v2-launch      # run the linked workflow now from its saved checkpoint
+/goal pause|done|abandon|delete v2-launch
+```
+`resume` executes the linked workflow through child sessions from the current
+command; it does not open a new main interactive session. A stored `--pattern`
+is descriptive metadata today and is not executed by `goal resume`, which
+requires a linked workflow.
+
+## Verification layer (`src/services/verifier/`)
+
+The main query loop has a verifier with done detection, loop detection, project
+quality gates (`projectGates.ts`, installed by
+`/test-first install --install-gates`), and optional subagent nudges.
+`verifier.askBeforeGates` controls prompting. Workflow verification gates,
+crew verdicts, arena judging, and exec evidence checks are separate
+orchestrator-specific mechanisms; they should not be conflated with this query
+verifier. Proof helpers in `verificationProofs.ts` are consumed by the
+spec/kernel verification paths and related evidence reporting.