From 39f299aed54e15033594a18adab77d6bc8904b8b Mon Sep 17 00:00:00 2001 From: Idan Ayalon Date: Mon, 29 Jun 2026 09:20:12 -0400 Subject: [PATCH 1/2] docs(tutorial): outcome hero, core/rest syntax split, one "how to run" home MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tutorial (docs/index.html): - Hero: replace the good-vs-bad comparison with a single outcome-in-motion terminal — the loop self-correcting fail → reflect → green → gated PR — with the .loop that drove it below. New "Stop babysitting the agent" framing. - Syntax split: TOC regrouped into "Core syntax · the five decisions" and "The rest of the syntax"; #what names the core/rest cut; new #beyond section catalogs the non-core constructs (compose / augment / ops) with reference links. - One "how to run" home: a 3-way chooser (write by hand in VS Code · run in Claude Code [recommended] · run headless via the CLI), VS Code consolidated into a single #running-vscode subsection (was documented twice, inconsistently), getting-started trimmed to a pointer. runMode standardized on ask/session/output. Keyword reference (docs/keywords/): - Recut into two tiers (Core syntax / The rest) with re-sorted groups; detail-page category badges synced (Core syntax / Compose / Augment / Human / Ops & reuse). - Add the missing use-skills + remember-in pages and cards (0.4.0 constructs). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/index.html | 140 ++++++++++++++++--------------- docs/keywords/after-n-tries.html | 2 +- docs/keywords/allow.html | 2 +- docs/keywords/also.html | 2 +- docs/keywords/done-when.html | 2 +- docs/keywords/each-cycle.html | 2 +- docs/keywords/flow.html | 2 +- docs/keywords/for-each.html | 2 +- docs/keywords/goal.html | 2 +- docs/keywords/index.html | 19 +++-- docs/keywords/look-at.html | 2 +- docs/keywords/loop.html | 2 +- docs/keywords/pipeline.html | 2 +- docs/keywords/plan-from.html | 2 +- docs/keywords/reflect.html | 2 +- docs/keywords/remember-in.html | 39 +++++++++ docs/keywords/run.html | 2 +- docs/keywords/stage.html | 2 +- docs/keywords/style.css | 6 +- docs/keywords/use-skills.html | 39 +++++++++ docs/keywords/when.html | 2 +- 21 files changed, 185 insertions(+), 90 deletions(-) create mode 100644 docs/keywords/remember-in.html create mode 100644 docs/keywords/use-skills.html diff --git a/docs/index.html b/docs/index.html index bdd4a9f..d023126 100644 --- a/docs/index.html +++ b/docs/index.html @@ -196,15 +196,20 @@
  • vs /loop & /goal
  • Get started
  • Install + first loop
    • +
  • Core syntax · the five decisions
  • done when — verify
  • The cycle + reflect
  • Human gates
    • +
  • The rest of the syntax
  • Composing
    • +
  • The rest of the syntax
  • In practice
  • Real workflows
  • LoopFlow by role
  • Starter templates
    • -
  • Running it
    • +
  • Run it
    • +
  • Running a loop
    • +
  • In VS Code
  • Live dashboard
  • Your global library
  • Go deeper
    • @@ -217,21 +222,19 @@
    -

    LoopFlow, the tutorial

    -
    Stop tuning prompts. Start editing the loop. Hands-on? → Workshop 🛠️ · Or play → LoopFlow Lab 🎮
    +

    Stop babysitting the agent.

    +
    Write the goal once — the loop plans, acts, reflects on red, and stops only when the check is green, at the gates you set. Hands-on? → Workshop 🛠️ · Or play → LoopFlow Lab 🎮

    LoopFlow is a small natural-language DSL for loop engineering. A .loop file describes a self-correcting, human-gated coding workflow — its objective, the context it may read, the actions it may take, how it verifies itself, and when it stops. This page teaches the whole language from the first line to full A-to-Z pipelines, every section grounded in a real example you can run.

    -
    -
    -
    a claude session● ● ●
    -
    -
    -
    -
    …or one loop
    - 
    # run in chat:  /loopflow run rate-limit.loop
-# (the agent knows LoopFlow from AGENTS.md — your repo's memory)
+  
    
+    
    /loopflow run rate-limit.loop● ● ●
    
+    
    
+  
    
+  
    ↓ the one .loop that drove the run above — the whole job, written once
    
 
-git:
+  
    
+    
    rate-limit.loop
    
+    
    git:
   work on a branch
   commit when the goal is met
   open a pull request
@@ -245,10 +248,8 @@ 
    LoopFlow, the tutorial
    
   also: run a security check
   when it fails: reflect, then plan again
   after 6 tries: stop and warn "thrashing"
    
-      
    Skill: /loopflow runs it · Memory: AGENTS.md + reflect · Git: branch + commit + PR, never main
    
-    
    
+    
    Skill: /loopflow runs it · Memory: AGENTS.md + reflect · Git: branch + commit + PR, never main
    -

    Left: a dozen messages, and it still pushed to main. Right: the whole job, written once — it runs, verifies, and stops only when it's really done.

    @@ -272,6 +273,7 @@

    What is a loop basic

    Verificationdone whenHow do we know it worked? Stoppingwhen… / after N triesWhen do we stop — done, or thrashing? +

    These five are the core syntax — the engine. Everything else in the language either composes loops into bigger workflows (pipeline, flow, for each) or configures a run (the rest of the syntax) — you'll meet those after the core.

    Here are all five decisions as one real loop — every line is one of the rows above:

    loop "fix the failing test":                       # the work
   goal: the cart total is correct with a coupon    # Objective
@@ -370,7 +372,7 @@ 
    vs Claude Code's /loop and /goal<
 
    
   
    Getting started setup
    
   
    That's the why. From here down is the deep dive — set LoopFlow up once, then learn the language line by line.
    
-  
    Prerequisites: Node 18+, the Claude Code CLI (LoopFlow drives it), and a git repo to work in. The primary way to use LoopFlow is a Claude Code chat — type /loopflow and the assistant writes and runs the loop with you, watching every step and answering gates inline. (Prefer to write .loop files by hand? The VS Code extension is there too — see below — but the chat is the recommended path.) One command installs everything:
    
+  
    Prerequisites: Node 18+, the Claude Code CLI (LoopFlow drives it), and a git repo to work in. The primary way to use LoopFlow is a Claude Code chat — type /loopflow and the assistant writes and runs the loop with you, watching every step and answering gates inline. (Prefer to write .loop files by hand? The VS Code extension is there too — see Running a loop ▸ In VS Code — but the chat is the recommended path.) One command installs everything:
    
 
   
    1 · Install with npm
    
   
    From your repo, run the installer. In one step it writes the /loopflow skill and AGENTS.md (the full language reference) into the project:
    
@@ -412,16 +414,7 @@ 
    2 · Run your first loop — in a Claude Code chat
    -

    Optional · author by hand in VS Code if you prefer an editor

    -

    The chat above is the main way to use LoopFlow. If you'd rather write .loop files by hand, the optional LoopFlow VS Code extension helps — Extensions ▸ search “LoopFlow” ▸ Install — then open any .loop file:

    -
      -
    • Syntax highlighting for the whole language — goal, done when, gates, flow, for each, git:.
      • -
    • Completion + formatting — keyword snippets so you type a loop from muscle memory, not a cheat sheet.
      • -
    • A ▶ Run button on every loop (the LoopFlow: Run this loop CodeLens) — and you choose where it runs via the loop.runMode setting: open an interactive Claude Code session, or a headless output-panel trace.
      • -
    • New from template (command palette → LoopFlow: New from template) — scaffold a ready-to-edit .loop bundle.
      • -
    • A soft linter that nudges, never blocks — "this loop has no way to verify it's done", "add a thrash guard".
      • -
    -

    Same file, same engine: prompt the agent to generate a loop, or open VS Code and write the .loop yourself. The chat is the first-class way to run; the extension is the first-class way to author by hand.

    +

    Prefer to write .loop files by hand in an editor? The optional LoopFlow VS Code extension — highlighting, completion, a ▶ Run button, and New from template — is covered under Running a loop ▸ In VS Code. The chat is the first-class way to run; the extension is the first-class way to author by hand.

    Safe from the first run: with no git: block, LoopFlow works on a branch and commits when the goal is met, and never pushes to main/master — see the git keyword.

    Rather learn hands-on?

    @@ -555,6 +548,29 @@

    Composing — pipeline, flow, for each scaling u

    The full grammar — pipelines, flow chains, and for each iteration, with worked examples — is in the manual and the keyword reference.

    + +
    +

    The rest of the syntax beyond the core

    +

    The five decisions (plus the cycle) are the whole engine. Everything else in the language either composes loops into bigger workflows or configures a run — none of it changes how a single loop thinks. Here's the rest at a glance; each construct links to its keyword reference page.

    + + + + + + + + + + + + + + + + +
    ConstructWhat it does
    Compose — scale one loop into many
    pipeline · stageRun stages in order; a failing stage halts the rest. An epic → a pipeline, a story → a stage. More ↑
    flow · run / then runChain whole .loop files; each step's summary carries forward (with the result of picks a specific earlier step).
    for each … inRun a template loop once per item in a YAML/Markdown plan — A-to-Z over every story.
    Augment a loop
    use skills:Named skills the loop may invoke during plan/act — coordinate proven skills instead of one mega-prompt.
    remember inCross-run memory: read past lessons on start, append the run's outcome on stop, so the loop improves over time.
    also:Extra finishing passes run after the goal is met (skipped on failure).
    plan from "file"Execute a plan you wrote instead of one the agent generates.
    Ops & reuse — configure the run
    git:Version-control policy — branch / commit cadence / push / PR. Never pushes to main by default.
    models:Tier the model by phase — a fast model to plan/reflect, a strong one to act.
    use the X methodImport a reusable preset (its own .loop) that another repo can share.
    schedule: · target: · notify:The config tier — when it runs, where it runs, and who to tell when it's done.
    +
    + @@ -704,7 +720,14 @@

    Starter templates — don't write from scratch c
    -

    Running a loop intermediate

    +

    Running a loop how to run

    +

    Three ways to work with a .loop — write it, then run it. Same file, same engine:

    + + + + + +
    What you wantUseHow
    1 · Write the loop by handthe VS Code extension — syntax highlighting, completion, a soft linteropen a .loop in VS Code
    2 · Run it in Claude Code recommendedthe /loopflow skill — watch every step, answer gates inline/loopflow run <file>
    3 · Run it headlessthe CLI — CI, scripts, cron, no chat in the looploop-run run <file>

    Every command below runs the same kind of file — here's the one referenced throughout this section:

    # examples/fix_test.loop
 loop "fix the failing checkout tax test":
@@ -718,6 +741,17 @@ 
    In a Claude Code chat recommended — the main w
   
    /loopflow "fix the failing checkout tax test"   # write a .loop from a request
 /loopflow run examples/fix_test.loop            # run it, right here in the chat
    
   
    You stay in the chat the whole time: you watch each step, you answer the gate, and the loop ends on a real green test — not the assistant saying "done". This is the only mode where a long interactive discovery works, because the human is already in the loop.
    
+
+  
    In VS Code optional — author by hand
    
+  
    Reach for the extension when you'd rather write .loop files by hand in an editor. Install it from Extensions ▸ search "LoopFlow" ▸ Install, then open any .loop file:
    
+  
      
+    
    • Syntax highlighting, hover docs, and context-aware tab-completion for every construct — including the latest vocabulary (use skills, remember in, flow, for each, and done when the skill "…" approves / scores N or more).
      • 
+    
    • A ▶ Run CodeLens above each definition. You choose where it runs via loop.runMode: ask (prompt each time), session (open a Claude Code session in the integrated terminal — watch every step, answer gates in chat), or output (headless, streamed into the VS Code output panel with native gate dialogs).
      • 
+    
    • A soft linter that nudges, never blocks: "this loop has no way to verify it's done", "add a thrash guard".
      • 
+    
    • New Loop from template — from File ▸ New File…, an Explorer folder right-click, or the Command Palette — scaffolds a best-practice loop (bugfix, feature, security, … the full library) into your workspace, # TODO lines marked.
      • 
+  
    
+  
    Same file, same engine: the chat is the first-class way to run; the extension is the first-class way to author by hand.
    
+
   
    Headless CLI
    
   
    loop-run run   examples/ship_feature.loop  # drive Claude Code, glyph trace
 loop-run run   examples/ship_feature.loop --live  # …plus a live browser dashboard
@@ -736,15 +770,6 @@ 
    Watch it run — live dashboard interm
 live=true            # /loopflow shows the live dashboard during in-session runs
    
   
    The page streams over Server-Sent Events (each event carries an id; the server replays on connect and dedupes on reconnect), is self-contained — no external assets — and binds to 127.0.0.1 only.
    
 
-  
    In VS Code optional — for hand-authoring
    
-  
    Secondary to the chat — reach for the extension only when you want to write .loop files by hand in an editor.
    
-  
      
-    
    • Syntax highlighting, hover docs, and tab-completion for every construct.
      • 
-    
    • A ▶ Run CodeLens above each definition. When you click it, you choose where it runs (the loop.runMode setting): open a Claude Code session — an interactive run in the integrated terminal where you watch every step and answer gates in chat — or the VS Code output panel (headless, with a live trace and native gate dialogs). Set loop.runMode to ask (prompt each time), session, or output.
      • 
-    
    • A soft linter that nudges (never blocks): "this loop has no way to verify it's done", "add a thrash guard".
      • 
-    
    • LoopFlow: New from template — scaffold a ready-to-edit method bundle (a generic for each setup, or a BMAD A-to-Z one) into your workspace in one pick.
      • 
-  
    
-
   
    Troubleshooting
    
   
@@ -787,7 +812,7 @@ 
    Your global library — save a loop, run it in any repo done when check, its reflect-and-retry, its gates, and its look at scope with it. Running it re-applies all of that, identically, anywhere. It's a reusable guarantee you built once — not a prompt you re-type and re-trust.
   
 
-  
    Claude is the first-class home for LoopFlow. The library and every /loopflow command live in the chat — that's where you watch each step and answer gates as the loop runs. VS Code is the second seat: handy for editing a .loop with highlighting and a ▶ Run button, but the loop still runs through Claude. If you only ever use one surface, use the chat.
    
+  
    Claude is the first-class home for LoopFlow. The library and every /loopflow command live in the chat — that's where you watch each step and answer gates as the loop runs. VS Code is the second seat: handy for editing a .loop with highlighting and a ▶ Run button, but the loop still runs through Claude. If you only ever use one surface, use the chat.
    
 
 
 
@@ -894,38 +919,21 @@ 
    Go deeper
    
 (function(){
   var el=document.getElementById('agentterm'); if(!el) return;
   var T=[
-    {c:'tl-dim',t:'$ claude'},
-    {c:'tl-u',t:'❯ add rate limiting to the API'},
-    {c:'tl-tool',t:'● Edit src/api/limiter.ts'},
-    {c:'tl-dim',t:'   + token-bucket limiter, 100 req/min'},
-    {c:'tl-ok',t:'✓ Done — added a limiter.'},
-    {c:'tl-u',t:'❯ did you add tests?'},
-    {c:'tl-tool',t:'● Write tests/limiter.test.ts'},
-    {c:'tl-ok',t:'✓ Added 3 tests.'},
-    {c:'tl-u',t:'❯ run them'},
+    {c:'tl-u',t:'❯ /loopflow run rate-limit.loop'},
+    {c:'tl-dim',t:'  goal: requests are rate-limited per API key'},
+    {c:'tl-plan',t:'↻ cycle 1 · plan → act → observe'},
     {c:'tl-tool',t:'● Bash  pnpm test rate-limit'},
     {c:'tl-bad',t:'   ✗ 2 failing: resets-after-window, per-key-isolation'},
-    {c:'tl-u',t:'❯ fix them, then re-run'},
+    {c:'tl-plan',t:'~ reflect: the window resets per key, not globally'},
     {c:'tl-tool',t:'● Edit src/api/limiter.ts'},
+    {c:'tl-plan',t:'↻ cycle 2 · plan → act → observe'},
     {c:'tl-tool',t:'● Bash  pnpm test rate-limit'},
-    {c:'tl-ok',t:'   ✓ 5 passing'},
-    {c:'tl-u',t:'❯ now the whole suite — do not break anything'},
-    {c:'tl-tool',t:'● Bash  pnpm test'},
-    {c:'tl-bad',t:'   ✗ 1 failing: checkout.spec.ts (shared middleware)'},
-    {c:'tl-u',t:'❯ ugh. fix that too'},
-    {c:'tl-tool',t:'● Edit src/middleware/index.ts'},
-    {c:'tl-tool',t:'● Bash  pnpm test'},
-    {c:'tl-ok',t:'   ✓ all green'},
-    {c:'tl-u',t:'❯ now the security scan'},
-    {c:'tl-tool',t:'● Bash  semgrep --severity=high'},
-    {c:'tl-bad',t:'   ✗ 1 high: unbounded map → memory DoS'},
-    {c:'tl-u',t:'❯ fix it. and do NOT push to main'},
-    {c:'tl-tool',t:'● Edit src/api/limiter.ts'},
-    {c:'tl-tool',t:'● Bash  git commit -am "rate limiting"'},
-    {c:'tl-tool',t:'● Bash  git push origin main'},
-    {c:'tl-bad',t:'⚠ pushed to main.'},
-    {c:'tl-u',t:'❯ you literally said DO NOT push to main'},
-    {c:'tl-dim',t:'— and tomorrow, you type all of this again.'}
+    {c:'tl-ok',t:'   ✓ all green — done-when satisfied'},
+    {c:'tl-tool',t:'● Bash  git checkout -b rate-limiting'},
+    {c:'tl-gate',t:'⛐ gate: open a pull request?  ▸ approved'},
+    {c:'tl-tool',t:'● Bash  git push origin rate-limiting · gh pr create'},
+    {c:'tl-ok',t:'◼ done — PR #128 opened, never touched main'},
+    {c:'tl-dim',t:'— you wrote the goal once; the loop did the rest.'}
   ];
   var i=0, cur;
   function restart(){ el.innerHTML=''; i=0; startLine(); }
diff --git a/docs/keywords/after-n-tries.html b/docs/keywords/after-n-tries.html
index cb2fbf4..2c3ada9 100644
--- a/docs/keywords/after-n-tries.html
+++ b/docs/keywords/after-n-tries.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / after N tries (thrash guard)
    
 
    after N tries (thrash guard)
    
-
    Stop & warn if it gets stuck. Control & transitions
    
+
    Stop & warn if it gets stuck. Core syntax
    
 
    Syntax
    
 
    after N tries: stop and warn "<message>"
    
 
    What it does
    
diff --git a/docs/keywords/allow.html b/docs/keywords/allow.html
index 751bf76..98adcb0 100644
--- a/docs/keywords/allow.html
+++ b/docs/keywords/allow.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / allow / ask me before
    
 
    allow / ask me before
    
-
    The action policy: auto vs confirm. Building blocks
    
+
    The action policy: auto vs confirm. Core syntax
    
 
    Syntax
    
 
    allow edits automatically, but ask me before migrations or pushes
    
 
    What it does
    
diff --git a/docs/keywords/also.html b/docs/keywords/also.html
index eac6cae..0ac7b07 100644
--- a/docs/keywords/also.html
+++ b/docs/keywords/also.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / also
    
 
    also
    
-
    Finishing passes after the goal is met. Building blocks
    
+
    Finishing passes after the goal is met. Augment
    
 
    Syntax
    
 
    also: <pass>, <pass>
    
 
    What it does
    
diff --git a/docs/keywords/done-when.html b/docs/keywords/done-when.html
index 762b813..bfaad2a 100644
--- a/docs/keywords/done-when.html
+++ b/docs/keywords/done-when.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / done when
    
 
    done when
    
-
    How a loop verifies itself. Building blocks
    
+
    How a loop verifies itself. Core syntax
    
 
    Syntax
    
 
    done when <predicate>
    
 
    What it does
    
diff --git a/docs/keywords/each-cycle.html b/docs/keywords/each-cycle.html
index e125aa5..22b2b2e 100644
--- a/docs/keywords/each-cycle.html
+++ b/docs/keywords/each-cycle.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / each cycle
    
 
    each cycle
    
-
    The repeated steps, in order. Building blocks
    
+
    The repeated steps, in order. Core syntax
    
 
    Syntax
    
 
    each cycle: plan, then act, then observe
    
 
    What it does
    
diff --git a/docs/keywords/flow.html b/docs/keywords/flow.html
index d08d72f..9fe5a9e 100644
--- a/docs/keywords/flow.html
+++ b/docs/keywords/flow.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / flow
    
 
    flow
    
-
    Chain whole .loop files in order. Structure
    
+
    Chain whole .loop files in order. Compose
    
 
    Syntax
    
 
    flow "<name>":
   run "a.loop"
diff --git a/docs/keywords/for-each.html b/docs/keywords/for-each.html
index d118204..02e20e8 100644
--- a/docs/keywords/for-each.html
+++ b/docs/keywords/for-each.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / for each
    
 
    for each
    
-
    Run a template once per item. Structure
    
+
    Run a template once per item. Compose
    
 
    Syntax
    
 
    for each <var> in "<file>":
   run "<template.loop>"
    
diff --git a/docs/keywords/goal.html b/docs/keywords/goal.html
index 646f5e9..e954a3a 100644
--- a/docs/keywords/goal.html
+++ b/docs/keywords/goal.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / goal
    
 
    goal
    
-
    What "done" means, in plain language. Building blocks
    
+
    What "done" means, in plain language. Core syntax
    
 
    Syntax
    
 
    goal: <text>
    
 
    What it does
    
diff --git a/docs/keywords/index.html b/docs/keywords/index.html
index 84f6785..687c741 100644
--- a/docs/keywords/index.html
+++ b/docs/keywords/index.html
@@ -22,15 +22,20 @@
 
    Keywords
    
 
    Every construct in the LoopFlow language — one page each, with syntax, what it does, examples, and a diagram where it helps.
    
 
    Learning the language top-to-bottom? Read the tutorial. This is the by-keyword reference.
    
-
    Structure
    
-
    loopA self-correcting unit of work.pipelineStages in order; fail-fast.stageOne step of a pipeline — a story.flowChain whole .loop files in order.run / then runA step inside a flow.for eachRun a template once per item.
    
-
    Building blocks
    
-
    goalWhat "done" means, in plain language.done whenHow a loop verifies itself.look atScope the context the agent reads.each cycleThe repeated steps, in order.allow / ask me beforeThe action policy: auto vs confirm.alsoFinishing passes after the goal is met.reflectTurn a failure into the next plan.
    
-
    Control & transitions
    
-
    when … (transitions)Rules evaluated after each observe.after N tries (thrash guard)Stop & warn if it gets stuck.
    
+
    Core syntax — the five decisionsThe engine. Objective, context, actions, verification, stopping — plus the cycle that drives them, and where a human steps in.
    
+
    The five decisions
    
+
    goalObjective — what "done" means, in plain language.look atContext — scope what the agent reads first.allow / ask me beforeActions — auto vs confirm.done whenVerification — how a loop proves itself.when … (transitions)Stopping — rules evaluated after each observe.after N tries (thrash guard)Stopping — stop & warn if it gets stuck.
    
+
    The cycle
    
+
    each cycleThe repeated steps, in order.reflectTurn a failure into the next plan.
    
 
    Human-in-the-loop
    
 
    human gatesWhere a person steps in.
    
+
+
    The rest of the syntaxEverything that composes loops into bigger workflows or configures a run — none of it changes how a single loop thinks.
    
+
    Compose — scale one loop into many
    
+
    loopA self-correcting unit of work.pipelineStages in order; fail-fast.stageOne step of a pipeline — a story.flowChain whole .loop files in order.run / then runA step inside a flow.for eachRun a template once per item.
    
+
    Augment a loop
    
+
    use skills:Named skills the loop may invoke.remember inCross-run memory across runs.alsoFinishing passes after the goal is met.plan fromRead the plan from a file you control.
    
 
    Ops & reuse
    
-
    git:Branch / commit / push strategy.models:Model tiering by phase.use the <X> methodImport a reusable preset.scheduleWhen to run.targetWhere the runner operates.notifyWhere to send completion.plan fromRead the plan from a file you control.
    
+
    git:Branch / commit / push strategy.models:Model tiering by phase.use the <X> methodImport a reusable preset.scheduleWhen to run.targetWhere the runner operates.notifyWhere to send completion.
    
 
    LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
    
 
    
\ No newline at end of file
diff --git a/docs/keywords/look-at.html b/docs/keywords/look-at.html
index 3401f24..e5e2895 100644
--- a/docs/keywords/look-at.html
+++ b/docs/keywords/look-at.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / look at
    
 
    look at
    
-
    Scope the context the agent reads. Building blocks
    
+
    Scope the context the agent reads. Core syntax
    
 
    Syntax
    
 
    look at: <files>, and the last failure
    
 
    What it does
    
diff --git a/docs/keywords/loop.html b/docs/keywords/loop.html
index ebc3435..7ebb783 100644
--- a/docs/keywords/loop.html
+++ b/docs/keywords/loop.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / loop
    
 
    loop
    
-
    A self-correcting unit of work. Structure
    
+
    A self-correcting unit of work. Compose
    
 
    Syntax
    
 
    loop "<name>":
    
 
    What it does
    
diff --git a/docs/keywords/pipeline.html b/docs/keywords/pipeline.html
index 4bd6052..d26ed6d 100644
--- a/docs/keywords/pipeline.html
+++ b/docs/keywords/pipeline.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / pipeline
    
 
    pipeline
    
-
    Stages in order; fail-fast. Structure
    
+
    Stages in order; fail-fast. Compose
    
 
    Syntax
    
 
    pipeline "<name>":
   stage <name>: …
    
diff --git a/docs/keywords/plan-from.html b/docs/keywords/plan-from.html
index 8492d84..664b3bd 100644
--- a/docs/keywords/plan-from.html
+++ b/docs/keywords/plan-from.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / plan from
    
 
    plan from
    
-
    Read the plan from a file you control. Ops & reuse
    
+
    Read the plan from a file you control. Augment
    
 
    Syntax
    
 
    plan from "docs/plan.md"
    
 
    What it does
    
diff --git a/docs/keywords/reflect.html b/docs/keywords/reflect.html
index 0db3f3a..5eb8f0f 100644
--- a/docs/keywords/reflect.html
+++ b/docs/keywords/reflect.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / reflect
    
 
    reflect
    
-
    Turn a failure into the next plan. Building blocks
    
+
    Turn a failure into the next plan. Core syntax
    
 
    Syntax
    
 
    when it fails: reflect, then plan again
    
 
    What it does
    
diff --git a/docs/keywords/remember-in.html b/docs/keywords/remember-in.html
new file mode 100644
index 0000000..94f54d3
--- /dev/null
+++ b/docs/keywords/remember-in.html
@@ -0,0 +1,39 @@
+
+
+remember in — LoopFlow keyword
+
+
+
+
+
    
+  
    LoopFlow
    
+  Tutorial
+  Workshop
+  Keywords
+  🎮 LoopFlow Lab
+
    
+
    
+
    Keywords / remember in
    
+
    remember in
    
+
    Cross-run memory — read past lessons on start, append the outcome on stop. Augment
    
+
    Syntax
    
+
    remember in "<file.md>"
    
+
    What it does
    
+
    Names a Markdown file the loop treats as its memory. On start it reads the file and feeds those lessons into the first plan; on stop it appends a dated entry recording how the run went. Across runs, the loop learns from its own history instead of starting cold each time.
    
+
    Example
    
+
    loop "keep the flaky e2e suite green":
+  goal: the end-to-end suite passes three times in a row
+  remember in "loop.memory.md"
+  done when "pnpm test:e2e --repeat 3" passes
+  each cycle: plan, then act, then observe
+  when it fails: reflect, then plan again
    a loop that carries lessons between runs
+
+
    Related
    
+
    reflectuse skillsgoal
    
+
    LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
    
+
    
diff --git a/docs/keywords/run.html b/docs/keywords/run.html
index 5a50f87..992ca7c 100644
--- a/docs/keywords/run.html
+++ b/docs/keywords/run.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / run / then run
    
 
    run / then run
    
-
    A step inside a flow. Structure
    
+
    A step inside a flow. Compose
    
 
    Syntax
    
 
    run "<file.loop>"
 then run "<file.loop>"
diff --git a/docs/keywords/stage.html b/docs/keywords/stage.html
index 61b0085..eadeece 100644
--- a/docs/keywords/stage.html
+++ b/docs/keywords/stage.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / stage
    
 
    stage
    
-
    One step of a pipeline — a story. Structure
    
+
    One step of a pipeline — a story. Compose
    
 
    Syntax
    
 
    stage <name>:
   goal: …
    
diff --git a/docs/keywords/style.css b/docs/keywords/style.css
index b7c2176..4cf87e3 100644
--- a/docs/keywords/style.css
+++ b/docs/keywords/style.css
@@ -42,6 +42,7 @@ code.inl{background:var(--panel2); border:1px solid var(--line); border-radius:6
 .badge{display:inline-block; font-family:var(--ui); font-weight:700; font-size:10px; letter-spacing:1.4px;
   text-transform:uppercase; padding:3px 10px; border-radius:20px; vertical-align:middle;}
 .cat-structure{color:var(--blue); border:1px solid color-mix(in srgb,var(--blue) 50%,transparent);}
+.cat-core{color:var(--fwd); border:1px solid color-mix(in srgb,var(--fwd) 50%,transparent);}
 .cat-definition{color:var(--fwd); border:1px solid color-mix(in srgb,var(--fwd) 50%,transparent);}
 .cat-flow{color:var(--reflect); border:1px solid color-mix(in srgb,var(--reflect) 50%,transparent);}
 .cat-human{color:var(--gate); border:1px solid color-mix(in srgb,var(--gate) 50%,transparent);}
@@ -69,8 +70,11 @@ footer{color:var(--muted); font-size:12px; border-top:1px solid var(--line); mar
 footer a{color:var(--muted);} footer a:hover{color:var(--ink);}
 
 /* index grid */
+.tierhdr{font-family:var(--display); font-weight:700; font-size:22px; letter-spacing:-.2px; color:var(--ink);
+  margin:38px 0 2px; padding-bottom:8px; border-bottom:1px solid var(--line);}
+.tierhdr .sub{display:block; font-family:var(--ui); font-weight:400; font-size:13px; color:var(--muted); letter-spacing:0; margin-top:3px;}
 .grouphdr{font-family:var(--ui); font-weight:700; letter-spacing:1.6px; text-transform:uppercase; font-size:11px;
-  color:var(--fwd); margin:30px 0 10px;}
+  color:var(--fwd); margin:22px 0 10px;}
 .kwgrid{display:grid; grid-template-columns:repeat(auto-fill,minmax(232px,1fr)); gap:12px;}
 .kwcard{display:block; border:1px solid var(--line); border-radius:13px; padding:14px 15px; background:linear-gradient(180deg,rgba(255,255,255,.04),rgba(255,255,255,.012));
   transition:border-color .15s, transform .1s;}
diff --git a/docs/keywords/use-skills.html b/docs/keywords/use-skills.html
new file mode 100644
index 0000000..6364777
--- /dev/null
+++ b/docs/keywords/use-skills.html
@@ -0,0 +1,39 @@
+
+
+use skills — LoopFlow keyword
+
+
+
+
+
    
+  
    LoopFlow
    
+  Tutorial
+  Workshop
+  Keywords
+  🎮 LoopFlow Lab
+
    
+
    
+
    Keywords / use skills
    
+
    use skills
    
+
    Named skills the loop may invoke during plan and act. Augment
    
+
    Syntax
    
+
    use skills: <skill-a>, <skill-b>
    
+
    What it does
    
+
    Lists skills the agent is allowed to call while it works — so the loop coordinates proven, reusable skills instead of one mega-prompt. Pair it with done when the skill "<name>" approves to let a review skill decide the verdict.
    
+
    Example
    
+
    loop "harden the upload endpoint":
+  goal: no high-severity findings in the upload path
+  use skills: security-review, code-review
+  done when the skill "security-review" approves
+  each cycle: plan, then act, then observe
+  when it fails: reflect, then plan again
    a loop that drives two named skills
+
+
    Related
    
+
    done whenremember inreflect
    
+
    LoopFlow · the keyword reference. New here? Start with the tutorial or learn by playing LoopFlow Lab.
    
+
    
diff --git a/docs/keywords/when.html b/docs/keywords/when.html
index f41d89a..60fbe55 100644
--- a/docs/keywords/when.html
+++ b/docs/keywords/when.html
@@ -20,7 +20,7 @@
 
    
 
    Keywords / when … (transitions)
    
 
    when … (transitions)
    
-
    Rules evaluated after each observe. Control & transitions
    
+
    Rules evaluated after each observe. Core syntax
    
 
    Syntax
    
 
    when it passes and the goal is met: stop
 when it fails: reflect, then plan again

From f2ee0750ffe6801ab6ea2c834671247c7b6559d1 Mon Sep 17 00:00:00 2001
From: Idan Ayalon 
Date: Mon, 29 Jun 2026 10:07:39 -0400
Subject: [PATCH 2/2] =?UTF-8?q?docs(tutorial):=20tighten=20the=20hero=20?=
 =?UTF-8?q?=E2=80=94=20static=20run=20trace,=20no=20diversion=20links?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Replace the animated terminal with a static, auto-height full run trace so
  there's no oversized empty box (the fixed 330px pane left dead space). Drop
  the now-unused animation script.
- Remove the Workshop / LoopFlow Lab links from the hero lede so it doesn't
  push readers out of the tutorial before they start (still linked from
  Getting started and the TOC).

Co-Authored-By: Claude Opus 4.8 (1M context) 
---
 docs/index.html | 57 ++++++++++++++++---------------------------------
 1 file changed, 18 insertions(+), 39 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index d023126..3b622f6 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -223,12 +223,28 @@
 
    
 
    
   
    Stop babysitting the agent.
    
-  
    Write the goal once — the loop plans, acts, reflects on red, and stops only when the check is green, at the gates you set. Hands-on? → Workshop 🛠️ · Or play → LoopFlow Lab 🎮
    
+  
    Write the goal once — the loop plans, acts, reflects on red, and stops only when the check is green, at the gates you set.
    
   
    LoopFlow is a small natural-language DSL for loop engineering. A .loop file describes a self-correcting, human-gated coding workflow — its objective, the context it may read, the actions it may take, how it verifies itself, and when it stops. This page teaches the whole language from the first line to full A-to-Z pipelines, every section grounded in a real example you can run.
    
 
   
    
     
    /loopflow run rate-limit.loop● ● ●
    
-    
    
+    
    
+      
    ❯ /loopflow run rate-limit.loop
    
+      
      goal: requests are rate-limited per API key
    
+      
    ↻ cycle 1 · plan → act → observe
    
+      
    ● Bash  pnpm test rate-limit
    
+      
       ✗ 2 failing: resets-after-window, per-key-isolation
    
+      
    ~ reflect: the window resets per key, not globally
    
+      
    ● Edit src/api/limiter.ts
    
+      
    ↻ cycle 2 · plan → act → observe
    
+      
    ● Bash  pnpm test rate-limit
    
+      
       ✓ all green — done-when satisfied
    
+      
    ● Bash  git checkout -b rate-limiting
    
+      
    ⛐ gate: open a pull request?  ▸ approved
    
+      
    ● Bash  git push origin rate-limiting · gh pr create
    
+      
    ◼ done — PR #128 opened, never touched main
    
+      
    — you wrote the goal once; the loop did the rest.
    
+    
    
   
    
   
    ↓ the one .loop that drove the run above — the whole job, written once
    
 
@@ -915,43 +931,6 @@ 
    Go deeper
    
   document.querySelectorAll("section[id]").forEach(function(s){ obs.observe(s); });
 })();
 
-// ---- animated agent terminal: human types, agent streams ----
-(function(){
-  var el=document.getElementById('agentterm'); if(!el) return;
-  var T=[
-    {c:'tl-u',t:'❯ /loopflow run rate-limit.loop'},
-    {c:'tl-dim',t:'  goal: requests are rate-limited per API key'},
-    {c:'tl-plan',t:'↻ cycle 1 · plan → act → observe'},
-    {c:'tl-tool',t:'● Bash  pnpm test rate-limit'},
-    {c:'tl-bad',t:'   ✗ 2 failing: resets-after-window, per-key-isolation'},
-    {c:'tl-plan',t:'~ reflect: the window resets per key, not globally'},
-    {c:'tl-tool',t:'● Edit src/api/limiter.ts'},
-    {c:'tl-plan',t:'↻ cycle 2 · plan → act → observe'},
-    {c:'tl-tool',t:'● Bash  pnpm test rate-limit'},
-    {c:'tl-ok',t:'   ✓ all green — done-when satisfied'},
-    {c:'tl-tool',t:'● Bash  git checkout -b rate-limiting'},
-    {c:'tl-gate',t:'⛐ gate: open a pull request?  ▸ approved'},
-    {c:'tl-tool',t:'● Bash  git push origin rate-limiting · gh pr create'},
-    {c:'tl-ok',t:'◼ done — PR #128 opened, never touched main'},
-    {c:'tl-dim',t:'— you wrote the goal once; the loop did the rest.'}
-  ];
-  var i=0, cur;
-  function restart(){ el.innerHTML=''; i=0; startLine(); }
-  function blockCursor(){ var c=document.createElement('span'); c.className='tcur'; return c; }
-  function startLine(){
-    if(i>=T.length){ setTimeout(restart, 5000); return; }
-    cur=document.createElement('div'); cur.className='ln '+T[i].c; el.appendChild(cur);
-    if(T[i].c==='tl-u'){ var cursor=blockCursor(); cur.appendChild(cursor); typeOut(T[i].t, 0, cursor); }
-    else { cur.textContent=T[i].t; el.scrollTop=el.scrollHeight; i++; setTimeout(startLine, 430); }
-  }
-  function typeOut(text, j, cursor){
-    if(j>=text.length){ cursor.remove(); el.scrollTop=el.scrollHeight; i++; setTimeout(startLine, 780); return; }
-    cursor.insertAdjacentText('beforebegin', text.charAt(j)); el.scrollTop=el.scrollHeight;
-    setTimeout(function(){ typeOut(text, j+1, cursor); }, 58);
-  }
-  startLine();
-})();
-
 
 
 

    
     
    SymptomFix