@giamme/forge 0.8.0 → 0.10.0

package/docs/fractal.md

@@ -0,0 +1,181 @@
+# Fractal execution
+
+[← README](../README.md) · [All docs](README.md)
+
+Fractal is an optional implementation backend for both solo and decomposed runs. It uses
+the existing Forge dispatcher for Codex, Claude, OpenClaude, OpenCode and Antigravity.
+Each work step gets a fresh model invocation; preserved files and child results provide
+continuity when a parent resumes. Independent QA reviews the complete Forge task diff.
+
+`--decompose-level` plans top-level Forge tasks before execution. `--fractal` lets an
+implementer request nested children during execution. They can be used together, and
+solo runs can use Fractal without a top-level decomposition.
+
+## Install the optional runtime
+
+```bash
+forge fractal install --dry-run
+forge fractal install --yes --with-prerequisites
+forge fractal doctor --spec sol --spec opus --json
+```
+
+The managed runtime pins **Fractal 1.2.0** at revision
+`18793200c0d7e8cdb2db369ea3abe5647a1e15e4`, checks the source archive checksum,
+and includes the required `wiki` executable. It prefers an existing Python 3.12–3.14;
+with prerequisite installation selected, it can provision uv, Python 3.13 and tmux.
+tmux installation uses an existing Homebrew on macOS or apt on Debian/Ubuntu.
+The [installation reference](../references/fractal.md#installation-and-provenance) covers
+consent, supported bootstrap platforms, provenance and failure diagnostics.
+
+Installation never enables Fractal for a run, adds no command and leaves your shell startup
+files alone.
+Doctor checks the runtime and advertised harness capabilities without calling a provider.
+
+## Start and inspect a run
+
+Through the skill:
+
+```text
+/forge "add retry with exponential backoff to the HTTP client" --dwarf sol:high --fractal
+```
+
+Or prepare a solo run directory outside the product repository and invoke the runner:
+
+```bash
+FORGE_RUN="$HOME/.local/state/forge/examples/http-client"
+mkdir -p "$FORGE_RUN"
+printf '%s\n' 'Add bounded exponential backoff to the HTTP client and run its tests.' > "$FORGE_RUN/prompt.md"
+bash scripts/forge-solo.sh "$FORGE_RUN" --repo /absolute/path/to/product \
+  --dwarf sol:high --qa opus --fractal --fractal-concurrency 3
+```
+
+Choose a new run directory for unrelated work. Backend selection, routing pools and limits
+are stored with the run; resume and explicit retry retain them. For a prepared, approved
+decomposed plan, select the backend on `run`:
+
+```bash
+bash scripts/forge-parallel.sh run /absolute/path/to/plan --fractal --dry-run
+bash scripts/forge-parallel.sh run /absolute/path/to/plan --fractal
+```
+
+Dry runs show resolved model pools, limits and proposed workspaces without installation
+or provider calls. When a selected runtime is unavailable, interactive runs offer
+installation; unattended runs return an actionable error instead of changing backends.
+
+Discover the managed run ID, then inspect it from another terminal:
+
+```bash
+forge fractal runs --repo /absolute/path/to/product --json
+forge fractal open                         # live runs index
+forge fractal status RUN_ID --json
+forge fractal tree RUN_ID --json
+forge fractal logs RUN_ID --follow
+forge fractal report RUN_ID --html /absolute/path/to/report.html
+```
+
+`RUN_ID` is the `run-…` identifier returned by `runs`, not the solo directory or plan name.
+The [run inspector](../references/fractal-dashboard.md) opens on progress and problems, then lets
+readers inspect task QA/history or node decisions, logs and changes. It refreshes about every
+two seconds without replacing the workspace; search, selection, focus and scrolling remain in
+place. “Pause live updates” affects the browser only. Browser access is read-only, bound to
+`127.0.0.1` with an ephemeral access token. Closing its server does not stop execution.
+Portable HTML embeds complete captured history and logs, works offline and needs no Fractal
+runtime to read.
+
+## Automatic recursive decomposition
+
+`--fractal` permits workers to request children. To require a planning decision before
+every eligible node implements, use `--fractal-auto-decompose`:
+
+```text
+/forge "<goal>" --dwarf luna:high --qa sol:high --fractal-auto-decompose --fractal-planner sol:xhigh --fractal-depth 3 --fractal-nodes 24
+```
+
+After the top-level Forge approval, the planner automatically splits useful work or
+records why it is atomic. Children repeat this decision within the approved ownership
+and frozen limits. `--fractal-planner` selects a separate decision model; when omitted,
+Forge reuses the configured top-level planner, then the task's initial root model.
+Decisions use disposable snapshots, persist for resume, and appear in tree/status/HTML
+reports. Ordinary `--fractal` and existing runs retain their current behavior. Start a
+new run to change policy or planner. See the [full decision contract](../references/fractal.md#automatic-decomposition-decisions).
+
+## Bounds, recovery and acceptance
+
+Defaults per Forge task are two nesting levels below implementation, three unsettled
+direct children per node, twelve lifetime nodes, six iterations per node per attempt,
+and a 45-minute attempt deadline excluding explicit pauses. Three model slots are shared
+across the whole Forge run, including QA. `--max-parallel` bounds top-level task pipelines;
+`--fractal-concurrency` bounds model invocations across their nested trees.
+
+Child difficulty selects a frozen `--dwarf-low`, `--dwarf-medium` or `--dwarf-high` pool,
+falling back to the configured general dwarf, then the parent. Dependencies and owned
+paths constrain admission; overlapping ownership is serialized. Fractal never implies
+`--yolo-dwarf`. Costs are observational; unavailable usage stays unknown and dollar-cap
+requests are rejected.
+
+```bash
+forge fractal pause RUN_ID
+forge fractal resume RUN_ID
+forge fractal stop RUN_ID
+```
+
+Pause and stop preserve work and diagnostics. Run-level resume recovers recorded execution
+and the Forge pipeline without repeating accepted stages. Use explicit runner retry for
+a new attempt, retaining work and the original Forge QA baseline. Controls also accept
+`--task TASK_ID` and `--task TASK_ID --node NODE_ID`; those IDs come from `tree` output.
+
+Managed data lives in `${XDG_STATE_HOME:-$HOME/.local/state}/forge/fractal/`. Solo execution
+uses an isolated snapshot and imports changes only after checking source drift, preserving
+staging and leaving changes uncommitted. Decomposed candidates return to Forge's existing
+review/integration pipeline. **Fractal completion is not Forge acceptance**: QA, repository
+verification and authorization to update the user's branch remain distinct.
+
+See the [full Fractal reference](../references/fractal.md) for limits, child requests and
+recovery details, and [verification evidence](../tests/fractal-verification.md) for the tested
+platforms and browser checks. No paid-provider or speed/cost claim follows from fake-CLI tests.
+
+## `forge fractal` command group
+
+Run it as `forge fractal`, or `forge fractal` from a git checkout.
+This group manages Fractal runs; it does not replace the `/forge` skill or runner scripts.
+
+| Command | Purpose |
+| --- | --- |
+| `install [--dry-run] [--yes] [--with-prerequisites]` | preview or install the isolated pinned runtime |
+| `doctor [--spec SPEC] [--json]` | check runtime/hooks/tmux and optional repeated harness specs without provider calls |
+| `runs [--repo DIR] [--json] [--html PATH]` | discover managed runs, optionally filtered by repository |
+| `status\|tree\|activity RUN_ID` | inspect progress, hierarchy and history |
+| `logs\|costs\|messages\|config RUN_ID` | inspect diagnostics, observed accounting, radio traffic and effective settings |
+| `pause\|resume\|stop RUN_ID` | request a control and record its observed state |
+| `open [RUN_ID] [--port PORT]` | open the read-only live dashboard or runs index |
+| `report RUN_ID [--html PATH]` | capture a self-contained HTML report; default filename is `RUN_ID.html` |
+
+Inspection commands accept `--task TASK_ID`, `--node NODE_ID`, `--json`, `--html PATH`,
+`--offset N` and `--limit N` (1–1000). They currently return a common JSON run projection;
+the command names do not imply separate output schemas. `logs --follow` follows changes.
+HTML exports capture full history and logs. Controls require an explicit run ID, and a
+node control also requires its task ID; they never guess the latest run. Use each command's
+`--help` for its accepted options. Installation is also available through
+`bash scripts/forge-install-fractal.sh`.
+
+Fractal adds a managed workspace alongside the runner artifacts described here:
+
+```text
+${XDG_STATE_HOME:-$HOME/.local/state}/forge/fractal/
+  runtime/                       isolated pinned Fractal and wiki environment
+  provenance.json                installed versions and source checksum
+  installs/                      installation attempts and diagnostics
+  runs/<run-id>/run.json          effective routing, limits and runner binding
+  runs/<run-id>/controls/         requested controls and observed results
+  runs/<run-id>/tasks/<task-id>/
+    request.json / state.json     task request and execution checkpoint
+    initialization.json         control repository and Fractal ledger provenance
+    control/                     Fractal metadata, separate from product changes
+    nodes/<node-id>/product/      isolated product candidate
+    nodes/<node-id>/steps/        fresh dispatcher attempts and raw logs
+    outcome.json                 captured Forge acceptance and verification
+```
+
+The original solo/plan directory stores `fractal-selection.json`; decomposed plans also
+store `fractal-routing.json`. Prefer `forge fractal runs`, `tree`, `logs` and `report`
+to direct ledger access. Inspection and stop never delete managed work.

package/docs/install.md

@@ -0,0 +1,160 @@
+# Install and update
+
+[← README](../README.md) · [All docs](README.md)
+
+Install forge from npm or a git checkout, check which agent CLIs it can reach, and keep every harness installation current.
+
+## Requirements
+
+forge runs on macOS and Linux. It needs bash, git and Python 3.9 or later, plus the agent
+CLIs you route models through; the doctor below shows which ones it finds. Installing from
+npm brings none of these with it.
+
+## From npm
+
+```bash
+npm install -g @giamme/forge
+forge install
+```
+
+`forge install` links the installed package into each harness, as the installer does for a
+checkout below. It is a step of its own rather than an npm install script, so it works where
+scripts are turned off (`--ignore-scripts`). To update:
+
+```bash
+npm install -g @giamme/forge@latest && forge install
+```
+
+The links point into npm's global package directory, so they keep working across updates;
+`forge install` refreshes antigravity's copied plugin. Under nvm, that directory belongs to
+one Node version: after switching Node, install forge on the new one and run `forge install`
+again.
+
+> **Foundry users:** Foundry's `forge` has the same name, and whichever directory comes first
+> on your `PATH` wins; npm's global bin usually comes first. Runs start from your harness
+> (`/forge`), so this command is only for `forge install` and the optional tools. If you keep
+> Foundry's `forge` first, run ours as `"$(npm root -g)/@giamme/forge/forge"`.
+
+## From a git checkout
+
+```bash
+git clone https://github.com/Giamme/forge.git ~/.claude/skills/forge
+bash ~/.claude/skills/forge/scripts/forge-install.sh
+```
+
+Clone anywhere you like — the installer works out its own location and links from there.
+`~/.claude/skills/forge` is just the tidiest home: claude reads that path directly, and
+opencode and grok scan it on their own.
+
+The installer also offers optional Fractal support in an interactive terminal. Declining
+or a Fractal installation failure does not prevent ordinary Forge setup. See
+[Fractal installation](fractal.md#install-the-optional-runtime) for prerequisites and a separate install.
+
+## Check what forge can reach
+
+`<forge>` is your checkout, or `"$(npm root -g)/@giamme/forge"` for an npm install:
+
+```bash
+bash <forge>/scripts/forge-dispatch.sh doctor
+```
+
+```
+HARNESS      STATUS     DETAIL
+codex        found      /Users/you/.nvm/versions/node/v24.18.0/bin/codex
+claude       found      /Users/you/.local/bin/claude
+openclaude   found      /Users/you/.nvm/versions/node/v24.18.0/bin/openclaude
+opencode     found      /Users/you/.opencode/bin/opencode
+antigravity  MISSING    agy not on PATH
+grok         found      /Users/you/.grok/bin/grok
+```
+
+A `MISSING` harness is fine — forge only needs the ones you actually route models through.
+
+**Binary presence is not reachability.** A harness can be installed and still fail on auth or
+billing (opencode in particular fails this way), and that failure only surfaces mid-dispatch.
+To prove a pairing end to end before spending a real run:
+
+```bash
+bash <forge>/scripts/forge-dispatch.sh dwarf <spec> --prompt-file /dev/stdin --repo <scratch dir> \
+    <<< 'Reply with exactly: FORGE_OK'
+```
+
+## What the installer does per harness
+
+Each CLI discovers skills differently, and the differences are not guessable — so verify
+with the listed check rather than trusting file placement.
+
+| Harness | Mechanism | Verify with |
+|---|---|---|
+| claude | `~/.claude/skills/forge/` | `/forge` appears in the skill list |
+| openclaude | symlink into `~/.openclaude/skills/` | `openclaude skills list --json` |
+| codex | symlink into **`~/.codex/skills/`** | `codex exec "do you have a skill named forge?"` |
+| opencode | **nothing** — it scans `~/.claude/` itself | `opencode debug skill` |
+| antigravity | `agy plugin install` of a generated wrapper | `agy --print='/forge'` |
+
+> **The one ongoing caveat:** `agy plugin install` *copies* the files instead of referencing
+> them. The other four track the source directory live, so an edit reaches them instantly —
+> antigravity keeps running whatever it copied. **Re-run `forge-install.sh` after any edit**,
+> or agy silently runs a stale version.
+
+`forge-install.sh --dry-run` prints what it would do and touches nothing. It never clobbers
+a real directory that isn't a symlink.
+
+## Updating all harness installations
+
+Run the updater from your Forge checkout (or through one of its skill symlinks):
+
+```bash
+./forge update            # same as: bash ~/.claude/skills/forge/scripts/forge-update.sh
+./forge version           # VERSION, checkout commit, tracked upstream, last known release
+./forge version --check   # ask the upstream for its newest release now
+```
+
+It fetches the current branch's configured upstream, fast-forwards the checkout, and
+runs Forge's installer to refresh Claude, OpenClaude and Codex links, OpenCode discovery,
+and Antigravity's copied plugin. Harnesses that are not present are skipped. Restart
+active harness sessions afterward to load the updated skill.
+
+```bash
+# Preview without fetching or changing files:
+bash <forge-checkout>/scripts/forge-update.sh --dry-run
+
+# Refresh harness installations after local edits, without fetching:
+bash <forge-checkout>/scripts/forge-update.sh --local
+
+# Point a copied installation's updater at the original checkout:
+bash <path>/scripts/forge-update.sh --source <forge-checkout>
+```
+
+When a solo run, `plan` or `run` finishes, forge checks the checkout's upstream for a newer
+release tag at most once a day (`git ls-remote`, 5-second timeout, cached in
+`${XDG_STATE_HOME:-~/.local/state}/forge/update-check.json`) and, if there is one, prints a
+single line on stderr: `forge 0.8 is available (you have 0.7.1): forge update`. The check is
+silent offline, in a copied installation without Git, in CI (`CI` set) and with
+`FORGE_UPDATE_CHECK=off`, and it never changes a run's outcome or exit code.
+
+An npm installation has no Git upstream, so there the same daily check asks the npm registry
+for the package's `latest` (`npm_config_registry` when you set one, as npm does), and the line
+names npm's command instead: `forge 0.9.0 is available (you have 0.8): npm install -g
+@giamme/forge@latest && forge install`. `forge version` shows the same command.
+
+The default update requires a clean Git checkout and a branch with an upstream. Local
+changes, detached HEAD, fetch failures and diverged branches stop the update without
+resetting or stashing your work. `--local` deliberately allows current local edits.
+Real skill directories are preserved; a conflicting directory or plugin installation
+failure produces a nonzero exit and an explanation. After fixing an installation
+failure, use `--local` to retry from the updated source. Updating Forge does not prompt
+for optional Ripwire installation.
+
+An npm installation is not a Git checkout, so the updater stops there and prints the npm
+command [above](#from-npm) instead. `--local` still refreshes its harness installations.
+
+## `scripts/forge-install.sh`
+
+```
+forge-install.sh [--dry-run]
+```
+
+Links this directory into every installed harness. Skips harnesses that aren't present,
+skips a destination that exists and isn't a symlink (it will never clobber a directory you
+may have edited in place), and reports opencode as auto-detected.

package/docs/memory.md

@@ -0,0 +1,156 @@
+# Project memory
+
+[← README](../README.md) · [All docs](README.md)
+
+What forge learns about a repository, where it keeps it, what each role is told, and what forge has spent there.
+
+Every forge dispatch is a clean slate, so without help the tenth run in a repo rediscovers
+what the first one learned. forge keeps that in the repo, in two files:
+
+```
+.forge/memory.md     small, capped, injected into every prompt
+.forge/ledger.tsv    append-only, one row per dispatch, never injected
+```
+
+The split is the design. Injected context is paid for on every dispatch of every future run,
+so "remember everything" and "stay small" pull against each other — the ledger remembers at
+zero context cost and is read only when asked, while `memory.md` is capped at 40 lines / 4 KB.
+
+```markdown
+## Verify
+- pytest -q runs the suite; make test also lints and is 4x slower
+
+## Known traps
+- tests/test_api.py::test_timeout is flaky under -n auto  [tests/test_api.py]
+
+## Recurring QA findings
+- 3x: route added without updating openapi.yaml  [src/routes]
+```
+
+## How a fact gets in
+
+The role that just did the work writes it down, in its final message, next to the verdict:
+
+```
+FORGE_LEARNING: trap | src/proto/*_pb2.py is generated, never hand-edit [src/proto]
+```
+
+No extra dispatch and no separate model guessing what mattered — the one that hit the
+landmine is the one that records it. Everything after that is deterministic bash.
+
+**What stops it becoming a junk drawer:**
+
+| Guard | Effect |
+|---|---|
+| recurrence threshold | a `finding` needs **two distinct runs** before it is injected. One occurrence is an incident, not a pattern |
+| stale anchors | an entry ending in `[path]` is dropped once that path stops existing, so memory stays true as code moves |
+| hard cap | over 40 lines / 4 KB, lowest-count and least-recent facts are trimmed; one entry is clamped to 180 chars |
+| bias to silence | the prompt says most runs teach nothing durable and emitting nothing is correct. A false fact costs every future run; a missing one costs a single rediscovery |
+
+Only `verify` and `trap` are kept on first sighting — those are facts, true the first time.
+
+## Slices, and what forge writes
+
+| Role | Gets |
+|---|---|
+| planner, dwarf | Verify + Known traps + Recurring findings |
+| qa | Known traps + Recurring findings |
+
+QA is not told the build command; it is not building anything. It *is* told the recurring
+findings, so it can notice this is the fourth time the same bug shipped.
+
+`.forge/` is the **only** thing forge writes into your working tree rather than onto a branch
+of its own. It is excluded from every captured diff, so a reviewer never sees it as the
+dwarf's work — but it *will* show up as untracked in `git status` after your first run.
+
+## What to do with `.forge/` when it appears
+
+forge never commits it. That decision is yours, and there are three sane answers:
+
+| You want | Do this |
+|---|---|
+| memory shared with your team, and with future you | **commit `.forge/`** — the intended case; every teammate's runs then build on the same facts |
+| memory kept to your machine | `echo '.forge/' >> .gitignore` |
+| no memory at all | `--no-memory`, or `FORGE_MEMORY=off` in your environment |
+
+Two things that are easy to get wrong:
+
+**Gitignoring is not the same as turning it off.** An ignored `.forge/` is still written and
+still injected into every prompt — it just stops travelling. Only `--no-memory` /
+`FORGE_MEMORY=off` actually disables the feature.
+
+**Never commit one file and ignore the other.** `memory.md` is *rebuilt from* `ledger.tsv` on
+every write, so a clone that has the memory but not the ledger loses everything the moment
+anyone runs forge there — the rebuild regenerates `memory.md` from that machine's own short
+ledger and the shared facts are gone, silently. Verified behaviour, not a theoretical risk:
+
+```
+teammate A commits memory.md only, ledger.tsv gitignored
+  memory.md: - pytest -q runs the suite
+             - src/a.py is generated [src/a.py]
+
+teammate B clones, runs forge once, learns one unrelated thing
+  memory.md: - b learned something new        ← A's two facts destroyed
+```
+
+Commit both, or neither. If you commit them, expect `ledger.tsv` to gain a line per dispatch
+— small, but it will appear in your diffs; that growth is the price of the recurrence
+counting that keeps `memory.md` honest.
+
+If you contribute to someone else's repo, gitignore it. A pull request containing forge's
+notes to itself is noise to a reviewer who does not use forge.
+
+## `scripts/forge-memory.sh`
+
+```
+forge-memory.sh inject <repo> <planner|dwarf|qa>   # the block to prepend to a prompt
+forge-memory.sh note <planner|dwarf|qa>            # the instruction to append
+forge-memory.sh record <repo> --last <file> --role <r> [--run-id X] [--task T]
+                              [--model M] [--verdict V] [--duration S]
+forge-memory.sh show <repo>
+forge-memory.sh prune <repo>                       # re-apply staleness and the cap now
+forge-memory.sh spend <repo> [--run <run-id>]      # what forge has cost this repo
+```
+
+`record` appends to the ledger and then rebuilds `memory.md` from the whole ledger — the
+rebuild is idempotent, so a crashed run can leave the ledger a row short but can never leave
+memory half-written. Editing `memory.md` by hand therefore does not stick; remove the ledger
+rows instead.
+
+```bash
+# what would a dwarf actually be told about this repo?
+bash scripts/forge-memory.sh inject ~/dev/api dwarf
+
+# start over
+rm -rf ~/dev/api/.forge
+```
+
+## Spend
+
+The ledger already holds a row per dispatch and is never injected into a prompt, so
+accounting from it costs nothing:
+
+```bash
+bash scripts/forge-memory.sh spend ~/dev/api
+```
+```
+14 dispatch(es) across 3 run(s), 1h12m of model time
+Durations sum concurrent work, so they exceed the wall-clock of a parallel run.
+
+  by model                     disp     total      mean
+  sol:xhigh                       4     38m20s     9m35s
+  opus                            7     22m10s     3m10s
+  gemini:low:antigravity          3     11m30s     3m50s
+
+  by role                      disp     total
+  dwarf                           7     49m50s
+  qa                              7     22m10s
+```
+
+**Time and dispatch counts, never tokens or money.** The six CLIs expose usage differently
+or not at all, and a number forge cannot actually measure would be worse than no number.
+
+`duration_s` is the ledger's tenth column, appended at the end on purpose: a ledger written
+by an older forge — possibly already committed and shared — has nine fields, and awk yields
+an empty string for the missing one instead of shifting every column. Those rows are counted
+but not timed, and the output says so.

package/docs/models.md

@@ -0,0 +1,118 @@
+# Models, efforts and harnesses
+
+[← README](../README.md) · [All docs](README.md)
+
+How forge names a model (`alias:effort:harness`), what each harness offers, how effort is validated and clamped, when to drop the sandbox, and how to teach forge a new model.
+
+## The spec: `alias:effort:harness`
+
+Everywhere forge takes a model, it takes the same three-field spec. Each field after the
+first is optional:
+
+| Spec | Resolves to |
+|---|---|
+| `sol` | alias `sol`, default effort for the role, its default harness (codex) |
+| `sol:xhigh` | `sol` at `xhigh` effort on its default harness |
+| `sol:xhigh:openclaude` | same model and effort, run through the `openclaude` CLI |
+| `opus::claude` | explicit harness, effort left to the role default — the middle field may be empty |
+| `gpt-5.6-sol::codex` | not in the registry? passed through as a literal model id — but only with an explicit harness |
+
+An alias with no registry row still works, provided you name the harness. forge won't guess
+a default harness for a model it has never seen; that guess would silently spend quota on
+the wrong provider.
+
+**Role defaults when you leave things out:**
+
+- `--dwarf` missing → forge **asks**. Every dispatch spends real quota on your account, so
+  picking for you isn't its call.
+- `--qa` missing → `opus`, which runs locally through `claude` and adds no cost surprise.
+- effort missing → dwarf builds at `medium`, qa reviews at `xhigh`. A reviewer thinking
+  *less* than the implementer tends to wave things through, which wastes the stage entirely.
+
+## Effort, ceilings and clamping
+
+Every harness has its own effort ladder:
+
+| Harness | Ladder |
+|---|---|
+| codex | `low medium high xhigh max ultra` |
+| claude | `low medium high xhigh max` |
+| openclaude | `low medium high xhigh max ultracode` |
+| antigravity | `low medium high` |
+| grok | `low medium high xhigh max` (grok-4.7 offers up to `xhigh`) |
+| opencode | provider-specific; forwarded verbatim |
+
+And support is more irregular than one ceiling per backend:
+
+- **Ceilings** — `luna` tops out at `max` on codex, so `luna:ultra` clamps down.
+- **Gaps** — `gemini-pro` offers `low` and `high` but *not* `medium`, so `gemini-pro:medium`
+  clamps to `low`.
+- **None at all** — Claude models on antigravity take no effort flag; passing one errors, so
+  forge reports it and drops it.
+
+When forge clamps, it says so (`clamped=ultra -> max`) and the orchestrator passes that on
+to you. Getting less thinking than you paid for, silently, is exactly the failure worth ten
+lines of validation to prevent — and it's a real one: **codex accepts an invalid effort
+without complaint and quietly runs at some other level.** forge validates first.
+
+A word that isn't a recognized effort at all is an error, not a clamp.
+
+## Yolo mode
+
+`--yolo-dwarf` and `--yolo-qa` drop that role's sandbox and approval gates:
+
+| Harness | Flag used |
+|---|---|
+| codex | `--dangerously-bypass-approvals-and-sandbox` |
+| claude / openclaude / antigravity | `--dangerously-skip-permissions` |
+| opencode | `--auto` |
+| grok | `--always-approve` |
+
+Each flag applies to **one role only**, so `--yolo-dwarf` alone is the normal combination:
+the implementer gets a free hand, the reviewer stays fenced in and still can't edit the code
+it's judging.
+
+You mostly don't need it. On codex, claude and openclaude the sandboxed roles are already
+useful — the dwarf edits files and runs tests, qa reads and runs commands but cannot write.
+Reach for yolo when a role genuinely must escape the sandbox: installing dependencies,
+writing outside the repo, touching the network.
+
+> **Antigravity is the exception worth knowing.** Without yolo it cannot run *any* shell
+> command, and a single denied command **aborts the whole run** rather than degrading — a
+> dwarf that tries to run the test suite ends with an error and an empty diff. forge detects
+> this and appends a note telling that role not to attempt commands, which is why an
+> antigravity dwarf reports its work as unverified by execution. If you want a Gemini dwarf
+> that can actually run the tests it writes, it needs `--yolo-dwarf`.
+
+## Model registry
+
+`registry.tsv` is the single source of truth for alias resolution. Four tab-separated
+columns, plus an optional fifth:
+
+```
+# alias	harness	model	effort	[timeout]
+sol	codex	gpt-6.1-sol	<=ultra
+sol	openclaude	gpt-6.1-sol	<=max
+gemini-pro	antigravity	gemini-3.1-pro	low,high
+opus	antigravity	claude-opus-4-6-thinking	none
+grok	grok	grok-4.7	<=xhigh
+grok	opencode	github-copilot/grok-4.6	-
+```
+
+| `effort` form | Means |
+|---|---|
+| `<=X` | any effort on that harness's ladder up to and including `X` |
+| `a,b,c` | exactly these efforts — gaps are real, and this is how they're expressed |
+| `none` | takes no effort flag at all; passing one errors |
+| `-` | no validated ladder; forwarded verbatim |
+
+The optional fifth column, `timeout`, is a per-model default dispatch limit in seconds (`-`
+or absent = the built-in default). It applies only when neither `--timeout` nor
+`FORGE_TIMEOUT` was given and is scaled by the resolved effort (see
+[timeout precedence](commands.md#scriptsforge-dispatchsh)). Rows without it behave exactly as before.
+
+**Row order is meaningful:** the *first* row for an alias is that alias's default harness.
+`--dwarf sol` means sol on codex; `--dwarf sol:high:openclaude` moves the same model
+elsewhere.
+
+Adding a model is one line in this file. Nothing else needs to change.