docs: home the tail-call walkthrough in the trace playground

The interactive tail-call-optimization walkthrough belongs with the
other step-through examples in the Explore trace playground, not in the
tracing reference. Move the two tail-recursive examples and the O0/O2
call-stack comparison into a "Watching the optimizer" section under the
trace playground, and leave the tracing page with a reference-style
summary plus the back-edge transform-context schema example, linking to
the playground for the interactive version. Restore the optimizer
mention to the Explore hub.

Author: gnidan

packages/web/docs/core-schemas/programs/tracing.mdx

@@ -4,11 +4,6 @@ sidebar_position: 4
 
 import SpecLink from "@site/src/components/SpecLink";
 import SchemaExample from "@site/src/components/SchemaExample";
-import { TraceExample } from "@theme/ProgramExample";
-import {
-  tailRecursiveSum,
-  tailRecursiveFactorial,
-} from "./tracing-examples";
 
 # Tracing execution
 
@@ -178,44 +173,14 @@ instead of (or alongside) a reason pointer:
 }`}
 </SchemaExample>
 
-## Tail-call optimization
-
-The recursion examples above push a new frame for every call — step
-through them and watch the call stack grow. A compiler can often avoid
-that. When a recursive call sits in **tail position** — its result is
-returned directly, with no further work after it — the compiler can
-reuse the current frame instead of pushing a new one. This is
-**tail-call optimization** (TCO), and it turns recursion into a loop.
-
-The two programs below are written so bugc's optimizer folds them. Each
-accumulates its result in an `acc` parameter and hands it to the next
-call in tail position, so no work is left pending on the stack.
-
-Use the **Opt** selector in the trace drawer to set the optimization
-level. Compile at **O0** (no optimization) and again at **O2**
-(optimizations on, including TCO), then step through and compare the
-call stack. TCO kicks in at **O2**.
-
-<TraceExample
-  title="Tail-recursive sum"
-  description="Sums 1..5 with an accumulator; TCO folds it into a loop"
-  source={tailRecursiveSum}
-/>
-
-<TraceExample
-  title="Tail-recursive factorial"
-  description="Computes 5! with an accumulator; TCO folds it into a loop"
-  source={tailRecursiveFactorial}
-/>
-
-At **O0**, each `sum`/`fact` call is a real invoke/return pair and the
-call stack grows one frame per iteration. At **O2**, the recursive
-call becomes a **back-edge**: a single JUMP that ends one iteration and
-begins the next without pushing a frame. The call stack stays flat.
-
-That one JUMP carries three facts at once, composed as sibling keys on a
-single context — the flat form described on the
-[transform context](/spec/program/context/transform) page:
+## Optimized code: the tailcall transform
+
+When the compiler optimizes tail-recursive calls, it turns the recursion
+into a loop: the recursive call becomes a **back-edge** — a single JUMP that
+ends one iteration and begins the next without pushing a frame. That one
+JUMP carries three facts at once, composed as sibling keys on a single
+context (the flat form described on the
+[transform context](/spec/program/context/transform) page):
 
 <SchemaExample
   schema="program/context/transform"
@@ -239,14 +204,17 @@ single context — the flat form described on the
 
 The `return` and `invoke` state the source-level facts — the previous
 iteration returned, the next was invoked — and `transform: ["tailcall"]`
-explains how the compiler realized that pair as one JUMP. Because no
-value crosses a frame boundary here, the `return` carries no `data` and
-the `invoke` no `arguments`: the accumulator is threaded through the
-loop directly, and the invoke `target` points at the loop header the
-JUMP re-enters. A debugger that ignores the transform still reads a
-coherent invoke/return sequence; one that understands it can show that
-the call stack isn't really growing, and present the recursion as the
-loop it compiled to.
+explains how the compiler realized that pair as one JUMP. Because no value
+crosses a frame boundary here, the `return` carries no `data` and the
+`invoke` no `arguments`: the accumulator is threaded through the loop
+directly, and the invoke `target` points at the loop header the JUMP
+re-enters. A debugger that ignores the transform still reads a coherent
+invoke/return sequence; one that understands it can show that the call stack
+isn't really growing.
+
+To watch this happen — flipping the optimizer between **O0** and **O2** and
+stepping through the back-edge — see the tail-call optimization examples in
+the [Trace playground](/docs/explore/trace-playground).
 
 ## Trace data structure
 

packages/web/docs/explore/index.mdx

@@ -16,7 +16,8 @@ your browser; no setup required.
   storage slot, a struct, and a computed location each select their bytes.
 - [**Trace playground**](/docs/explore/trace-playground) — Compile a BUG
   program and step through its execution trace: source location, in-scope
-  variables, the call stack, and instruction context at every step.
+  variables, the call stack, and instruction context at every step —
+  including the optimizer's tail-call transform.
 - [**BUG playground**](/docs/explore/bug-playground) — Compile the BUG
   language end to end and inspect each stage: AST, IR, control-flow graph,
   and bytecode.

packages/web/docs/explore/trace-playground.mdx

@@ -8,6 +8,8 @@ import { TracePlayground, TraceExample } from "@theme/ProgramExample";
 import {
   counterIncrement,
   functionCallAndReturn,
+  tailRecursiveSum,
+  tailRecursiveFactorial,
 } from "../core-schemas/programs/tracing-examples";
 
 # Trace playground
@@ -18,8 +20,8 @@ source line, in-scope variables, call stack, and instruction context
 light up at every step.
 
 Click **"Try it"** on an example to open the trace drawer, then use the
-step controls to walk through execution. The two examples build on each
-other: start with the storage write, then follow a function call.
+step controls to walk through execution. The examples build on each
+other: start at the top and work down, picking up one idea at a time.
 
 <TracePlayground>
 
@@ -51,4 +53,30 @@ For the exact shape of invoke, return, and revert contexts, see the
 [function call spec](/spec/program/context/function) and the
 [tracing reference](/docs/core-schemas/programs/tracing).
 
+## Watching the optimizer
+
+Compilers rewrite code as they optimize, and **transform** contexts
+record what they did. Set the **Opt** selector to **O2** and step through
+these tail-recursive programs: the recursive call folds into a loop, and
+the back-edge JUMP carries `transform: ["tailcall"]` next to its invoke
+and return. The call stack stays flat instead of growing one frame per
+iteration.
+
+<TraceExample
+  title="Tail-recursive sum"
+  description="Sums 1..5 with an accumulator; TCO folds it into a loop"
+  source={tailRecursiveSum}
+/>
+
+<TraceExample
+  title="Tail-recursive factorial"
+  description="Computes 5! with an accumulator; TCO folds it into a loop"
+  source={tailRecursiveFactorial}
+/>
+
+Flip the **Opt** selector between **O0** and **O2** to see the call stack
+change. For how the `tailcall` transform composes with invoke/return, see
+the [transform context spec](/spec/program/context/transform) and the
+[tail-call optimization walkthrough](/docs/core-schemas/programs/tracing).
+
 </TracePlayground>