ur-agent 1.11.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,133 @@
+# Configuration
+
+UR reads configuration from CLI flags, environment variables, and project or user settings files.
+
+## Model Provider
+
+UR runs models strictly through the local Ollama app. The request endpoint is fixed and cannot be reconfigured from UR:
+
+```text
+http://localhost:11434/api
+```
+
+Any model exposed by that local Ollama app can be used, including local models and Ollama Cloud-backed models. UR does not call remote provider APIs directly and does not manage model API keys.
+
+Model selection environment variables:
+
+```sh
+OLLAMA_MODEL=qwen3-coder:480b-cloud
+UR_MODEL=qwen3-coder:480b-cloud
+```
+
+`OLLAMA_MODEL` selects the model name and takes precedence over `UR_MODEL`. If neither is set, UR lets its Ollama router choose from the model list advertised by the local Ollama app. If that discovery fails, the built-in fallback is `qwen3-coder:480b-cloud`. Neither variable can change the endpoint.
+
+## CLI Flags
+
+Frequently used flags:
+
+```sh
+ur --model <model>
+ur --settings <file-or-json>
+ur --add-dir <path>
+ur --mcp-config <file-or-json>
+ur --permission-mode <mode>
+ur --plugin-dir <path>
+ur --agents '<json>'
+```
+
+Use `ur --help` for the complete list.
+
+## Settings Files
+
+UR supports user, project, and local settings. Project-shared settings can live under `.ur/`, while local files should remain private.
+
+Recommended Git behavior:
+
+- Commit shared docs, skills, agents, and project settings that are safe for teammates.
+- Do not commit `.ur/settings.local.json`.
+- Do not commit generated `.ur/index/`, `.ur/memory/`, `.ur/cache/`, `.ur/tmp/`, or `.ur/logs/`.
+- Do not commit `UR.local.md`.
+
+## Verifier
+
+UR runs a lightweight verifier in the agent loop (L1) to catch false "task
+done" claims, infinite tool-call loops, empty assistant turns, and project
+gate failures. This is the cheap "try the implementation" pass and always
+runs (outside `mode=off`).
+
+The heavy independent `verification` subagent (L2) is **opt-in**: by default
+UR never auto-spawns it after a turn. Trigger that deep second opinion
+yourself with the `/verify` command when you want it. Set
+`UR_VERIFIER_AUTO_SUBAGENT=1` to restore the old behaviour where the verifier
+nudges the model to spawn the subagent after every mutating turn.
+
+Behaviour is controlled by environment variables:
+
+```sh
+# Overall mode (default: strict) — controls the L1 gates
+UR_VERIFIER_MODE=strict   # all L1 gates on: done-claim, loops, empty turn,
+                          # project gates
+UR_VERIFIER_MODE=loose    # only empty-turn check + loop detector
+UR_VERIFIER_MODE=off      # disable verifier entirely
+
+# L2 deep-verification subagent (default: off — run it manually via /verify)
+UR_VERIFIER_AUTO_SUBAGENT=1      # auto-nudge the subagent after every
+                                 # mutating turn (the old default)
+UR_VERIFIER_DISABLE_SUBAGENT=1   # hard-off: also unregister the verification
+                                 # agent so /verify can't spawn it either
+```
+
+Project-specific gates live in `.ur/verify.json`:
+
+```json
+{
+  "afterEdit": ["bun x tsc --noEmit", "bun test --quiet"],
+  "afterBash": [],
+  "ignorePatterns": ["**/*.md", "node_modules/**"],
+  "timeoutMs": 60000
+}
+```
+
+After a turn that modified files, every `afterEdit` command must exit 0
+before the agent can declare the task complete. A failing command surfaces
+to the model as a structured reminder with the command name and the trimmed
+stdout/stderr.
+
+Two related slash commands:
+
+- `/verify [focus]` — manually run the deep verification subagent (e.g.
+  `/verify the auth flow`). This is the primary way to trigger L2; useful
+  before a commit.
+- `/trace [n]` — print a structured view of the last `n` messages (default 8,
+  max 50): roles, tool calls, tool results, verifier verdicts. Useful for
+  debugging what the agent did during a turn.
+
+## MCP Servers
+
+Use the `mcp` subcommand to manage Model Context Protocol servers:
+
+```sh
+ur mcp list
+ur mcp get <name>
+ur mcp add-json <name> '<json>'
+ur mcp remove <name>
+```
+
+MCP servers may execute code or access external services. Only enable servers you trust, and keep credentials out of committed config.
+
+## Plugins and Skills
+
+Plugins can add commands, tools, and skills:
+
+```sh
+ur plugin list
+ur plugin install <plugin>
+ur plugin update <plugin>
+ur plugin disable <plugin>
+```
+
+Skills can be stored in `.ur/skills/` for project-specific workflows or in `~/.ur/skills/` for personal workflows.
+
+## Secrets
+
+Keep secrets in environment variables, local settings, a secret manager, or your shell profile. Never commit API keys, OAuth tokens, private keys, service-account JSON, or `.env` files.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,69 @@
+# Development Guide
+
+## Repository Layout
+
+- `bin/ur.js` launches the TypeScript CLI through Bun.
+- `src/entrypoints/cli.tsx` handles fast startup paths before loading the full CLI.
+- `src/main.tsx` defines top-level CLI flags and subcommands.
+- `src/commands.ts` registers slash commands and command modules.
+- `src/tools/` contains tool implementations.
+- `src/services/` contains API, MCP, analytics, sync, and runtime services.
+- `src/components/` and `src/ink/` implement the terminal UI.
+- `examples/` contains example prompts and workflows.
+- `test/` contains Bun tests for local UR utility modules.
+
+## Install
+
+```sh
+bun install
+```
+
+## Run
+
+```sh
+bun run start
+bun run dev
+```
+
+`bun run start` uses `bin/ur.js`. `bun run dev` runs `src/entrypoints/cli.tsx` directly with watch mode and the Bun bundle preload.
+
+## Verify
+
+```sh
+bun run typecheck
+bun test
+bun run bundle
+bun run smoke
+bun run secrets:scan
+bun run release:check
+npm pack --dry-run
+```
+
+The GitHub install path uses the bundled launcher in `dist/cli.js`, so `bun run bundle` must be run before packaging or pushing a release. `bun run release:check` verifies that `package.json`, `bunfig.toml`, the bundle, docs, and `node ./bin/ur.js --version` agree.
+
+## Build
+
+```sh
+bun run bundle
+```
+
+The build output goes to `dist/cli.js`. The directory is ignored by default, but `dist/cli.js` is intentionally tracked because GitHub installs run the bundled CLI.
+
+## Local Command Link
+
+From the repository root:
+
+```sh
+bun link
+ur --version
+```
+
+## GitHub Install
+
+This package is configured for install without cloning:
+
+```sh
+bun add -g github:Maitham16/UR-mapek
+```
+
+The package exposes the global `ur` command from `bin/ur.js`. That launcher reads `package.json` for version and repository metadata, then runs `src/entrypoints/cli.tsx` with Bun.

package/docs/USAGE.md

@@ -0,0 +1,101 @@
+# Usage Guide
+
+UR is a terminal agent. Running `ur` opens an interactive session in the current directory, while `ur -p` runs one non-interactive prompt and exits.
+
+## Interactive Mode
+
+```sh
+ur
+```
+
+Use interactive mode for iterative coding, debugging, research, and repository exploration. The session can read project instructions, use tools, call slash commands, and keep resumable conversation history.
+
+Useful options:
+
+```sh
+ur --model qwen3-coder:480b-cloud
+ur --add-dir ../other-project
+ur --permission-mode ask
+ur --continue
+ur --resume
+```
+
+## Print Mode
+
+Print mode is useful for scripts and shell pipelines:
+
+```sh
+ur -p "write a changelog entry for the current diff"
+```
+
+Output formats:
+
+```sh
+ur -p --output-format text "explain src/main.tsx"
+ur -p --output-format json "return a JSON summary of this repo"
+ur -p --output-format stream-json "stream progress while answering"
+```
+
+Structured output can be validated with a JSON schema:
+
+```sh
+ur -p \
+  --output-format json \
+  --json-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' \
+  "summarize this project"
+```
+
+## Models
+
+The wrapper in `bin/ur.js` honors explicit model choices in this order:
+
+1. `OLLAMA_MODEL`
+2. `UR_MODEL`
+
+If neither variable is set, UR lets its Ollama router choose from the models
+exposed by your local Ollama app. That list can include local models and
+Ollama Cloud-backed models. If routing cannot discover a model list, the
+built-in fallback is `qwen3-coder:480b-cloud`.
+
+You can also choose the model for a single session:
+
+```sh
+ur --model qwen3-coder:480b-cloud
+ur --model qwen2.5-coder:latest
+```
+
+UR talks only to the local Ollama app at the fixed endpoint `http://localhost:11434/api`. The endpoint cannot be changed from UR. Models exposed by that local app are valid, including Ollama Cloud-backed models. UR does not call provider APIs directly or manage model API keys.
+
+## Project Instructions
+
+Add a `UR.md` file to the repository root for team-shared instructions. UR loads it as project context.
+
+Use `UR.local.md` for private local instructions. It is ignored by `.gitignore`.
+
+Project `.ur/` assets can hold settings, skills, agents, MCP config, and local runtime state. Commit only shared files. Keep local memory, generated indexes, logs, and local settings untracked.
+
+## Commands
+
+UR includes slash commands and CLI subcommands for common workflows:
+
+- `/help` or `ur --help` for command discovery
+- `ur mcp ...` to configure MCP servers
+- `ur plugin ...` to manage plugins and marketplaces
+- `ur agents` to list configured agents
+- `ur doctor` to inspect CLI health
+- `ur update` or `ur upgrade` to check for updates
+
+Run each command with `--help` for exact flags.
+
+## Permissions
+
+By default, UR asks before sensitive tool actions. For automation, use explicit allow and deny lists:
+
+```sh
+ur -p \
+  --allowed-tools "Read,Edit,Bash(git:*)" \
+  --disallowed-tools "Bash(rm:*)" \
+  "inspect the current diff"
+```
+
+Avoid `--dangerously-skip-permissions` unless the session is inside a disposable sandbox.

package/docs/VALIDATION.md

@@ -0,0 +1,197 @@
+# Live Validation Runbook
+
+Use this checklist after installing or upgrading to verify the verifier
+subsystem (L1/L2/L3) and the in-repo marketplace work against a real Ollama
+session. Should take ~10 minutes.
+
+You need:
+
+- A running Ollama server (`ollama serve`) with at least one model available
+  in the local Ollama app. Local models and Ollama Cloud-backed models both
+  work because UR talks to the local app.
+- This repo installed globally (`bun add -g github:Maitham16/UR-mapek`) or a
+  local checkout (`bun run dev`).
+
+## 0. Smoke
+
+```sh
+ur --version
+# expected: 1.11.0 (Ur)
+```
+
+## 1. Marketplace tree resolves
+
+In a fresh interactive session:
+
+```sh
+ur
+```
+
+Then inside:
+
+```text
+/plugin
+```
+
+Expected: the plugin picker lists `ur-plugins-official` and `hello`. If the
+marketplace failed to clone, you'll see no entries — fall back to
+`/plugin marketplace add github:Maitham16/UR-mapek` and re-run `/plugin`.
+
+Install `hello`:
+
+```text
+/plugin install hello@ur-plugins-official
+```
+
+Then run the example command:
+
+```text
+/hello Maitham
+```
+
+Expected: a two-sentence greeting that addresses you by name and mentions
+the `ur-plugins-official` marketplace.
+
+## 2. L1 done-claim gate fires
+
+Ask the agent to do something simple but DON'T let it use a tool. The
+cleanest way is to prompt:
+
+```text
+Pretend you just edited README.md to add a hello function. Tell me you did
+it. Do NOT actually call any tool.
+```
+
+Expected:
+
+- The model tries to claim "done" without writing anything.
+- A `<system-reminder>` appears (or the agent's tone changes mid-turn —
+  the render-time filter strips the reminder from the visible prose; you'll
+  see the *effect* in the next turn where the agent backs off the claim or
+  actually makes the Write call).
+- If you have `UR_VERIFIER_MODE=off` set, the false claim goes through. Try
+  it both ways to confirm:
+
+  ```sh
+  UR_VERIFIER_MODE=off ur     # gates off, false claim accepted
+  UR_VERIFIER_MODE=strict ur  # default, false claim rejected
+  ```
+
+## 3. L1 loop detector fires
+
+```text
+Run `ls /nonexistent-path` over and over via the Bash tool. Don't change
+the arguments. Don't try anything else.
+```
+
+Expected: after the 3rd identical Bash call, the agent receives a "stop
+repeating the same call" reminder and switches strategy (or asks for
+clarification).
+
+## 4. Project gate from `.ur/verify.json`
+
+Create one:
+
+```sh
+mkdir -p .ur
+cat > .ur/verify.json <<'JSON'
+{
+  "afterEdit": ["false"],
+  "timeoutMs": 5000
+}
+JSON
+```
+
+Then in the REPL, ask for a real edit:
+
+```text
+Append a blank line to README.md.
+```
+
+Expected: the agent calls Write/Edit. Then the gate fires (`false` always
+exits 1) and the agent receives a reminder naming the command and its
+non-zero exit. The agent should either fix something and retry or surface
+the failure honestly instead of declaring done.
+
+Clean up:
+
+```sh
+rm .ur/verify.json
+```
+
+## 5. L2 subagent nudge (opt-in)
+
+The deep verification subagent does NOT fire automatically by default — deep
+verification is manual (step 6). To exercise the auto-nudge, start UR with it
+enabled:
+
+```sh
+UR_VERIFIER_AUTO_SUBAGENT=1 ur
+```
+
+Then:
+
+```text
+Add a short docstring to the top of any one file in src/. After that,
+just say "all done" with no further tool calls.
+```
+
+Expected after the model "finishes":
+
+- The verifier injects the L2 nudge as a `<system-reminder>`.
+- The agent calls `Task` with `subagent_type="verification"`.
+- The verifier subagent returns a `VERDICT: PASS / FAIL / PARTIAL` line.
+- The main agent echoes the verdict in its final response.
+
+If the model ignores the nudge twice in a row, the loop falls through to
+`completed` so you don't hang — that's intentional safety, not a bug.
+
+Without `UR_VERIFIER_AUTO_SUBAGENT`, the same prompt finishes with no nudge —
+that's the default. To also unregister the subagent entirely (so `/verify`
+can't spawn it either):
+
+```sh
+UR_VERIFIER_DISABLE_SUBAGENT=1 ur
+```
+
+## 6. `/verify` works manually
+
+```text
+/verify the docstring you added
+```
+
+Expected: agent spawns the verification subagent and reports the verdict.
+Same flow as step 5 but on demand.
+
+## 7. `/trace` works
+
+```text
+/trace 12
+```
+
+Expected: a numbered list of the last 12 messages with role, uuid prefix,
+text previews, `tool_use` signatures, and any `tool_result` bodies. Any
+turn that produced a `VERDICT:` line gets a `verdict: PASS/FAIL/PARTIAL`
+annotation.
+
+Try `/trace 999` to confirm it caps at 50.
+
+## 8. System-reminder filter
+
+If you've already triggered steps 2-5, look at the visible assistant prose
+for any literal `<system-reminder>` text. There should be none. The filter
+strips them at render time as defense in depth even if the model echoes a
+reminder back.
+
+## What to do if any step fails
+
+- Step 1 (marketplace): check `ls ~/.ur/marketplaces/` — `ur-plugins-official`
+  should be there. If absent, `gh repo clone Maitham16/UR-mapek` manually
+  into `~/.ur/marketplaces/ur-plugins-official` as a fallback.
+- Steps 2-5 (verifier): set `UR_VERIFIER_MODE=off` and re-run to confirm
+  the issue is the verifier path, not the rest of the loop. Then file an
+  issue with the exact prompt + the model name (`ollama list`).
+- Step 6/7 (slash commands): `/help` should show them. If not, they failed
+  to register — file an issue with the version (`ur --version`).
+- Step 8 (filter): if `<system-reminder>` appears in visible prose, copy
+  the literal output and file an issue.

package/examples/basic_chat.md

@@ -0,0 +1,11 @@
+# Basic chat
+
+```bash
+ur                 # starts the interactive TUI (big UR banner)
+```
+
+- Pick a model at startup, or switch any time with `/model`.
+- `/models` lists installed Ollama models (or reports a clean error if Ollama is offline).
+- Type normally to chat with the selected model. Streaming is live; press `Esc` to interrupt.
+- `Ctrl+V` pastes an image from the clipboard for the model to analyze.
+- `/usage` shows token usage; `/status` shows model, workspace, git, OS.

package/examples/browser.md

@@ -0,0 +1,7 @@
+# Browser
+
+- `/chrome` drives a real browser via the built-in browser integration
+  (navigate, read, screenshot) — risky actions ask for approval.
+- `/browser <url|task>` is Playwright-aware: if Playwright is installed it can
+  script the page; otherwise it prints the install command and points to `/chrome`.
+- Browsing actions that submit forms, download, or log in require explicit approval.

package/examples/coding_task.md

@@ -0,0 +1,14 @@
+# Coding task
+
+```text
+> add a /health route to server.ts and a test for it
+```
+
+UR plans, reads files, edits, and can run tests. Safety + stability:
+
+- Edits are diffable: `/diff` shows uncommitted changes; `/rewind` rolls back.
+- Every tool call is recorded to `.ur/actions.jsonl` — see `/actions`, `/evidence`.
+- `/stability metrics` and `/stability firewall` surface oscillation, repeated
+  failures, latency spikes, and blast-radius from the action ledger.
+- `/stability why "<error>"` ranks likely root causes of a failure.
+- Writes outside the workspace and destructive commands require approval.

package/examples/images.md

@@ -0,0 +1,8 @@
+# Images
+
+- Paste from clipboard with `Ctrl+V`, then ask about the image — the model's
+  vision path handles it (requires a vision-capable model).
+- `/image <file> [task]` inspects an image by path (absolute or workspace).
+  Reports size/format; notes when OCR (`tesseract`) is available.
+- If the vision model isn't installed, UR tells you the exact `ollama pull`
+  command instead of failing silently.

package/examples/mcp.md

@@ -0,0 +1,7 @@
+# MCP
+
+- `/mcp` lists configured MCP servers and lets you add/manage them.
+- Servers are configured in your settings (`.mcp.json` / UR settings); UR maps
+  their tools into the registry and runs them through the same approval +
+  evidence-ledger path as built-in tools (so MCP calls appear in `/evidence`).
+- Risky MCP tools require approval before they run.

package/examples/memory.md

@@ -0,0 +1,9 @@
+# Memory
+
+- `/remember <text>` saves a fact/preference; `/forget <text>` removes matches;
+  `/memory` edits the memory files. Notes persist in `.ur/memory/notes.jsonl`.
+- Project conventions live in project instruction files and the project DNA file.
+- `/dna` detects language, package manager, build/test/lint/run commands,
+  ignored folders, and README, saved to `.ur/project_dna.md`.
+- `/ur-init` scaffolds the `.ur/` asset folder (docs, superpowers, brainstorming,
+  memory, prompts).

package/examples/research_task.md

@@ -0,0 +1,13 @@
+# Research task
+
+```text
+> summarize the MAPE-K paper and extract its claims and metrics
+```
+
+- `/research <note>` and `/research` to add/list notes.
+- `/paper <title|path>` and `/cite <ref>` to record papers and citations.
+- `/graph` is the Research Graph (sources, papers, claims, methods, datasets,
+  metrics, limitations, citations, concepts, notes, experiments, open_questions,
+  links). e.g. `/graph claims local actions reduce oscillation`.
+- `/read <file>`, `/summarize <file>`, `/search <query>`, `/index` for files.
+- Web fetch degrades gracefully (built-in HTML→text if `turndown` is absent).

package/examples/video.md

@@ -0,0 +1,8 @@
+# Video & YouTube
+
+These are dependency-aware: they do the local part and tell you what to install.
+
+- `/video <file|url> [task]` — checks `ffmpeg` (frames/audio) and `yt-dlp`
+  (download); with them present, ask UR to extract frames or a transcript.
+- `/youtube <url> [task]` — checks `yt-dlp`; fetches metadata/subtitles/transcript
+  when installed (`brew install yt-dlp ffmpeg`).