docs: the comparison is /goal + /loop + /schedule — add the goal-based loop

Anthropic's loop taxonomy (claude.com/blog/getting-started-with-loops) names
three primitives; /goal is the nearest sibling and deserved the honest
treatment: it has an in-session evaluator, so the loop.js difference is a
separate Verify session (own model, read-only), disk-durable resume, budget
guards, and the give-up verdict.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: shitianfang

README.md

@@ -56,23 +56,27 @@ missing piece: **an independent verdict**. The loop doesn't end because the work
 done; it ends because a separate judge, with its own permissions and its own model, says
 the bar is met — or because a declared guard fires. [Read more →](https://loop-js.mintlify.site/loop-engineering)
 
-## Why loop.js, not `/loop` or `/schedule`?
-
-Claude Code already loops: `/loop` re-runs a prompt (or lets the model pace itself toward a
-goal), and `/schedule` runs cloud agents on a cron. Both are the right tool for a developer
-driving their own session. They repeat **execution**; loop.js owns **convergence** — as a
-library you ship:
-
-- **Done is a verdict.** A separate, skeptical judge settles the loop; `/loop` stops when
-  the working model says so.
-- **State is on disk.** Every Round starts fresh and resumes from the Record; a `/loop`
-  lives and dies with its session.
+## Why loop.js, not `/goal`, `/loop`, or `/schedule`?
+
+Claude Code already loops: `/goal` iterates in your session until an evaluator passes your
+criteria, `/loop` re-runs a prompt on an interval on your machine, and `/schedule` runs
+cloud agents on a cron. All three are the right tool for a developer driving their own
+session. They are **commands inside Claude Code**; loop.js is the convergence machinery
+**as a library you ship**:
+
+- **Done is a verdict.** A separate, skeptical judge — its own model, read-only — settles
+  the loop; `/goal`'s evaluator lives inside the same session, and `/loop` stops when the
+  working model says so.
+- **State is on disk.** Every Round starts fresh and resumes from the Record — on any
+  machine, weeks later; a `/goal` or `/loop` lives and dies with its session.
 - **Overlap is safe.** The Lock's compare-and-set makes any trigger cadence safe — a
   periodic schedule doubles as the crash watchdog.
 - **Budget is enforced.** Dollars, Rounds, and per-Round timeouts are step-granular guards
   with their own exit codes.
 - **It's an API.** `Loop.define` / `loop.run` / typed events — embed the loop in your
   product, not in your terminal.
+- **Give-up is an answer.** A Goal that can never pass settles as an explicit `impossible`
+  instead of burning turns to the cap.
 
 Same agents underneath (the Claude Agent SDK) — loop.js is the convergence machinery
 around them. [Full comparison →](https://loop-js.mintlify.site/why-loop-js)

docs/index.mdx

@@ -52,6 +52,6 @@ so the loop is exactly as durable as your filesystem.
     Scaffold a project and drive your first Goal to settled.
   </Card>
   <Card title="Why loop.js" icon="scale-balanced" href="/why-loop-js">
-    Claude Code already has `/loop` and `/schedule` — when do you need more?
+    Claude Code already has `/goal`, `/loop`, and `/schedule` — when do you need more?
   </Card>
 </CardGroup>

docs/why-loop-js.mdx

@@ -1,34 +1,44 @@
 ---
 title: "Why loop.js"
-description: "Claude Code already loops — /loop and /schedule. Use them for yourself; use loop.js when the loop is a system you ship."
+description: "Claude Code already loops — /goal, /loop, and /schedule. Use them for yourself; use loop.js when the loop is a system you ship."
 ---
 
-Claude Code ships two ways to make an agent repeat, right in the terminal:
+Claude Code ships three ways to make an agent repeat, right in the terminal
+([Anthropic's loop taxonomy](https://claude.com/blog/getting-started-with-loops)):
 
-- **`/loop`** — re-run a prompt on an interval, or omit the interval and let the model pace
-  itself toward a goal.
-- **`/schedule`** — cloud agents (routines) that run on a cron schedule.
+- **`/goal`** — a goal-based loop in your live session: an evaluator checks your success
+  criteria each iteration, until the goal is achieved or a maximum number of turns is hit.
+- **`/loop`** — a time-based loop on your machine: re-run a prompt on an interval, or let
+  the model pace itself.
+- **`/schedule`** — the same idea in the cloud: agents (routines) that run on a cron.
 
-For a developer driving their own session, both are the right tool: one line, zero setup,
+For a developer driving their own session, these are the right tool: one line, zero setup,
 and you're watching the work happen. loop.js exists for the day the loop stops being
-something you *run* and becomes something you *ship* — a system with a bar to meet, a budget
-to respect, state to keep, and no human watching.
-
-The distinction in one sentence: **`/loop` and `/schedule` repeat execution; loop.js owns
-convergence.** Everything a loop needs to reach *done* — an independent verdict, durable
-state, declared guards, real scheduling — built into one npm package, driving the same
-Claude agents underneath.
-
-## Who says "done"?
-
-|  | `/loop` | `/schedule` | loop.js |
-| --- | --- | --- | --- |
-| Who judges "done" | the working model itself | each run ends when its agent stops | a separate, skeptical **Verify** agent — only its Verdict settles the Loop |
-| Where memory lives | the session's context window | carried by your prompt, run to run | on disk — Record, journal, handoff notes; every Round starts with fresh context |
-| Crash, restart, overlap | tied to the live session | fire-and-forget | the **Lock** (CAS + heartbeat): a live owner refuses overlap, a dead one is taken over |
-| Budget | — | — | total `usd` ledger with a step-granular cutoff, plus Rounds and per-Round timeout |
-| A finished goal, re-triggered | runs again | runs again | re-judged through the **Verify gate** — near-free while still ok, re-opens when stale |
-| Surface | a command inside Claude Code | a command inside Claude Code | a typed library — `Loop.define` / `loop.run`, an event stream, CLI exit codes |
+something you *run* and becomes something you *ship* — a system with a bar to meet, a
+budget to respect, state to keep, and no human watching.
+
+The distinction in one sentence: **`/goal`, `/loop`, and `/schedule` are commands inside
+Claude Code; loop.js is the convergence machinery as a library.** Everything a loop needs
+to reach *done* — an independent verdict, durable state, declared guards, real scheduling —
+built into one npm package, driving the same Claude agents underneath.
+
+## What each owns
+
+|  | `/goal` | `/loop` | `/schedule` | loop.js |
+| --- | --- | --- | --- | --- |
+| Who judges "done" | an evaluator in the same session | the working model itself | each run ends when its agent stops | a separate, skeptical **Verify** agent — own model, read-only — and only its Verdict settles the Loop |
+| Where memory lives | the session's context window | the session — stops when your machine does | carried by your prompt, run to run | on disk — Record, journal, handoff notes; every Round starts with fresh context |
+| Crash, restart, overlap | tied to the live session | tied to the live session | fire-and-forget | the **Lock** (CAS + heartbeat): a live owner refuses overlap, a dead one is taken over |
+| What stops a runaway | a maximum number of turns | you cancel it | you cancel it | total `usd` ledger (step-granular), Rounds cap, per-Round timeout — each a typed Exit |
+| A finished goal, re-triggered | — | runs again | runs again | re-judged through the **Verify gate** — near-free while still ok, re-opens when stale |
+| Surface | a command inside Claude Code | a command inside Claude Code | a command inside Claude Code | a typed library — `Loop.define` / `loop.run`, an event stream, CLI exit codes |
+
+The nearest sibling is `/goal` — it, too, refuses to let the worker declare victory early.
+The difference is what the judgement is made of and where the loop lives: `/goal`'s
+evaluator runs inside your session and ends with it; loop.js's Verify agent is a separate
+session with its own model and read-only permissions, its mandatory `reason` feeds the next
+Round, a Goal it can never meet settles as an explicit give-up, and the whole thing
+resumes from disk on any machine, any trigger, weeks later.
 
 ## What the convergence machinery buys you
 
@@ -87,12 +97,13 @@ const exit = await run.done()
 loop cron add "*/30 * * * *" --until settled   # keeps trying, removes itself when the bar is met
 ```
 
-## When to keep `/loop` and `/schedule`
+## When to keep `/goal`, `/loop`, and `/schedule`
 
-Honestly: often. Watching a refactor converge in your own session, re-checking a deploy
-every five minutes, a personal daily routine — an interactive command beats a framework.
-Reach for loop.js at the first of: the loop outlives your session, someone else (or cron)
-triggers it, money is on the line, or "done" must be *proven* rather than felt.
+Honestly: often. Watching a refactor converge in your own session (`/goal`), re-checking a
+deploy every five minutes (`/loop`), a personal daily routine (`/schedule`) — an
+interactive command beats a framework. Reach for loop.js at the first of: the loop outlives
+your session, someone else (or cron) triggers it, money is on the line, or "done" must be
+judged by an agent the worker can't influence.
 
 <CardGroup cols={2}>
   <Card title="Quickstart" icon="rocket" href="/quickstart">