Add capsules/turtle.4th, a limited LOGO-style turtle graphics demo capsule

First entry in the "cookbook" track: a demo capsule plus HOWTO, per the
sequencing laid out after the POST-coverage sweep. Built entirely in FORTH
on top of existing primitives -- fabric.4th's LINE (raster Bresenham) and
Q.SIN/Q.COS (Q48.16 trig), plus PLOT/FB-WIDTH/FB-HEIGHT -- no new C words.

FORWARD/BACK/LEFT/RIGHT/PENUP/PENDOWN/HOME/SETXY/SETHEADING/SETCOLOR give
the classic turtle model; POLYGON and STAR compose FORWARD+turn into simple
demo shapes; TURTLE-DEMO is a one-call visual smoke test. Not wired into
init.4th -- REPL-invoked only, matching the original idea's own scope.

Verified: mkcapsule --lint clean, hosted-build logic trace shows zero VM
errors and correct stack balance through the whole vocabulary, zero build
warnings and capsule loads cleanly on all three kernel architectures.
Visual pixel-level confirmation not yet done (needs an interactive
gtk-display session or driving past the ~25-30 min DoE-before-REPL wall),
documented as an open item in the HOWTO.

HOWTO: docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md

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

FABRIC-2.md

@@ -1611,3 +1611,34 @@ independent, previously-undetected production bugs in `physics_freeze_words.c` t
 this session entirely. Per the user's own sequencing ("code sweeps → HOL green → POST
 coverage"), this closes that sequence; LOGO/turtle demo + HOWTOs + SDK beginnings are next,
 pending explicit go-ahead.
+
+**Cookbook, first entry — `capsules/turtle.4th`, a limited LOGO-style turtle graphics
+capsule.** Started 2026-08-19 on explicit go-ahead, picking up the "cookbook" idea from the
+user's own sequencing note above (demo capsule + DoE package/library, each with a HOWTO,
+before SDK v1.9.0 scoping) and the older `project-stadium-logo-turtle-idea` memory (floated
+2026-08-11, explicitly deferred until raised again). Composed entirely in FORTH on top of
+existing primitives — `PLOT`/`FB-WIDTH`/`FB-HEIGHT` (`framebuffer_words.c`) and, more
+significantly, `capsules/fabric.4th`'s already-implemented `LINE` (raster-space Bresenham) and
+`Q.SIN`/`Q.COS` (Q48.16 trig, `q48_words.c`) — no new C words, matching this repo's "compose
+in FORTH first" rule. `FORWARD`/`BACK` compute `dx`/`dy` from the turtle's heading (stored
+directly in Q48.16 radians, not degrees, so no per-step conversion) and call `LINE` when the
+pen is down; `LEFT`/`RIGHT`/`SETHEADING` do the degrees→radians conversion once, at the turn,
+via a `DEG2RAD` constant. `POLYGON` and `STAR` compose `FORWARD`+turn in a loop (`STAR` uses a
+144° turn, not `360/5=72°` — a regular pentagon doesn't self-intersect, the classic star shape
+needs the overshoot). Block range `5100`–`5108`, clear of `fabric.4th`'s highest block
+(`5002`). Not wired into `init.4th` — matches the memory's own note that this is REPL-invoked,
+not part of Mama's boot sequence.
+
+Verified: `mkcapsule --lint capsules/` clean. Logic verified on the hosted build by piping
+`fabric.4th`'s core blocks (`4900`–`4909`) plus `turtle.4th` directly into the hosted binary —
+zero VM errors, `--log-debug` trace confirms correct stack balance through `HOME`/`SETCOLOR`/
+`POLYGON`/`STAR`/`FORWARD`/`LINE`. Baked cleanly into `capsule_generated.c` and built with zero
+warnings on all three kernel architectures (amd64/aarch64/riscv64, only the two known
+pre-existing linker warnings on aarch64 — RWX LOAD segment, `/align` — present as always).
+amd64 boot verified clean through POST and into the DoE campaign with the capsule present.
+**Not yet visually confirmed pixel-by-pixel in a live framebuffer** — driving the serial socket
+interactively hits the same ~25–30 minute DoE-before-REPL wall every kernel boot does, and
+wasn't practical to sit through unattended for a demo capsule; the arithmetic and control flow
+are verified, the actual rendered image is not. HOWTO:
+`docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md`. Second cookbook entry (DoE
+package/library + its own HOWTO) is next.

capsules/BLOCK_MAP.md

@@ -1,5 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-<!-- Generated by mkcapsule --manifest  2026-08-19T04:08:45Z -->
+<!-- Generated by mkcapsule --manifest  2026-08-19T05:50:05Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->
@@ -35,6 +35,7 @@
 | `init.4th` | 2049, 2050, 2057 | `0x214d424abd382707` |
 | `lib.4th` | 4050 | `0x20625ebf1276c239` |
 | `process.4th` | 4300, 4301 | `0x781afc1dbd0294f7` |
+| `turtle.4th` | 5100, 5101, 5102, 5103, 5104, 5105, 5106, 5107, 5108 | `0x4d470418ca543365` |
 | `user-font-demo.4th` | 4200, 4201, 4202 | `0xce1fd7d1b581a56d` |
 | `zuse.4th` | 4016, 4017, 4018 | `0x12f38ec782434a77` |
 
@@ -325,10 +326,19 @@
 | 5000 | `fabric.4th` | `0x9b1d061339cea98d` | ok |
 | 5001 | `fabric.4th` | `0x9b1d061339cea98d` | ok |
 | 5002 | `fabric.4th` | `0x9b1d061339cea98d` | ok |
+| 5100 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5101 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5102 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5103 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5104 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5105 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5106 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5107 | `turtle.4th` | `0x4d470418ca543365` | ok |
+| 5108 | `turtle.4th` | `0x4d470418ca543365` | ok |
 
 ## Conflicts
 
 None.
 
 ---
-*29 capsule(s) scanned.  Re-run `mkcapsule --manifest <dir>` to refresh.*
+*30 capsule(s) scanned.  Re-run `mkcapsule --manifest <dir>` to refresh.*

capsules/turtle.4th

@@ -0,0 +1,99 @@
+Block 5100
+( turtle.4th -- limited LOGO-style turtle graphics. Cookbook  )
+( demo capsule. Built on capsules/fabric.4th's LINE and       )
+( Q48.16 Q.SIN/Q.COS -- pure FORTH, no new C words. Load      )
+( fabric.4th first: uses LINE, FB-WIDTH, FB-HEIGHT, PLOT,     )
+( Q.SIN, Q.COS, Q.FROM-INT, Q.TO-INT, Q.*, Q.+.               )
+1144 CONSTANT DEG2RAD  ( Q48.16 rad/deg, pi/180 ~= 0.0174533 )
+VARIABLE TX  VARIABLE TY  VARIABLE THEAD
+VARIABLE TPEN  VARIABLE TCOLOR
+
+Block 5101
+( HOME: turtle to screen center, heading 0 (east), pen down, )
+( color white. Does not clear the screen -- see CS for that. )
+: HOME ( -- )
+  FB-WIDTH 2/ TX !
+  FB-HEIGHT 2/ TY !
+  0 THEAD !
+  1 TPEN !
+  16777215 TCOLOR ! ;
+
+Block 5102
+( PENUP / PENDOWN: whether FORWARD/BACK draw while moving.    )
+( SETCOLOR: 24-bit 0xRRGGBB, matches PLOT's own format.       )
+( SETXY: jump to (x y) without drawing, any pen state.        )
+( SETHEADING: absolute heading in degrees, 0=east, CCW+.      )
+: PENUP ( -- )      0 TPEN ! ;
+: PENDOWN ( -- )    1 TPEN ! ;
+: SETCOLOR ( color -- )  TCOLOR ! ;
+: SETXY ( x y -- )  TY ! TX ! ;
+: SETHEADING ( deg -- )  Q.FROM-INT DEG2RAD Q.* THEAD ! ;
+
+Block 5103
+( FORWARD / BACK: move n pixels along current heading        )
+( (THEAD, Q48.16 radians), drawing a LINE from old to new     )
+( position if pen is down. z is always 0 -- turtle graphics   )
+( is flat; fabric.4th's LINE just carries z through for the   )
+( 3D case it also supports.                                   )
+VARIABLE TNX  VARIABLE TNY
+: FORWARD ( n -- )
+  DUP Q.FROM-INT THEAD @ Q.COS Q.* Q.TO-INT TX @ + TNX !
+  Q.FROM-INT THEAD @ Q.SIN Q.* Q.TO-INT TY @ + TNY !
+  TPEN @ IF
+    TX @ TY @ 0 TNX @ TNY @ 0 TCOLOR @ LINE
+  THEN
+  TNX @ TX !  TNY @ TY ! ;
+: BACK ( n -- )  NEGATE FORWARD ;
+
+Block 5104
+( LEFT / RIGHT: turn in place by n degrees, CCW / CW.         )
+: LEFT ( deg -- )
+  Q.FROM-INT DEG2RAD Q.* THEAD @ Q.+ THEAD ! ;
+: RIGHT ( deg -- )  NEGATE LEFT ;
+
+Block 5105
+( CS: clear the framebuffer to black. framebuffer_words.c     )
+( only exposes PLOT (no fill primitive), so this is a plain   )
+( nested PLOT loop -- slow under TCG for a full screen, fine  )
+( for a one-shot demo clear, not meant to run per-frame.      )
+: CS ( -- )
+  FB-HEIGHT 0 DO
+    FB-WIDTH 0 DO
+      I J 0 PLOT
+    LOOP
+  LOOP ;
+
+Block 5106
+( POLYGON: regular polygon, SIDES corners, LEN pixels per     )
+( edge, drawn from the turtle's current position/heading      )
+( (call HOME first for a clean start). Classic LOGO idiom:     )
+( forward + turn 360/sides, repeated SIDES times.              )
+VARIABLE PLEN
+: POLYGON ( sides len -- )
+  PLEN !
+  DUP 0 DO
+    PLEN @ FORWARD
+    DUP 360 SWAP / LEFT
+  LOOP
+  DROP ;
+
+Block 5107
+( STAR: self-intersecting 5-pointed LOGO star -- forward +    )
+( a 144-degree turn (not 360/5=72, a plain pentagon), 5x.      )
+: STAR ( len -- )
+  DUP 5 0 DO
+    DUP FORWARD
+    144 LEFT
+  LOOP
+  DROP ;
+
+Block 5108
+( TURTLE-DEMO: visual smoke test -- clear screen, a cyan      )
+( hexagon, then a magenta star from the same start point.     )
+( Run after loading: S" turtle.4th" EXEC  TURTLE-DEMO          )
+: TURTLE-DEMO ( -- )
+  CS
+  HOME  65535 SETCOLOR     ( cyan  0x00FFFF )
+  6 80 POLYGON
+  HOME  16711935 SETCOLOR  ( magenta 0xFF00FF )
+  100 STAR ;

docs/working/architecture/TURTLE-GRAPHICS-HOWTO-20260819.md

@@ -0,0 +1,140 @@
+<!-- Living draft (docs/working/ tier). Source for a future docs/formal/cookbook
+     scrap once reviewed -- see docs/formal/CLAUDE.md's Scraps System. Not yet
+     promoted; do not cite. -->
+
+# Turtle Graphics HOWTO — `capsules/turtle.4th`
+
+**Status:** WORKING. First entry in the "cookbook" track Captain Bob asked
+for on 2026-08-18 (memory: `project-stadium-logo-turtle-idea`, floated
+2026-08-11) — a small, low-stakes demo capsule meant to make the CANVAS/
+framebuffer substrate satisfying to drive interactively, not a production
+subsystem. Second cookbook entry (DoE package/library HOWTO) is a separate,
+later doc.
+
+## What this is
+
+A limited LOGO-style turtle graphics vocabulary: a cursor with a position
+and heading that moves around the screen, drawing a trail when its "pen" is
+down. Classic commands — `FORWARD`, `BACK`, `LEFT`, `RIGHT`, `PENUP`/
+`PENDOWN` — composed entirely in FORTH on top of primitives that already
+exist:
+
+- `PLOT` / `FB-WIDTH` / `FB-HEIGHT` (`src/word_source/framebuffer_words.c`)
+  — raw hardware-boundary pixel write, kernel-only (no-op on hosted builds).
+- `LINE` / `CIRC-PT` / `Q.SIN` / `Q.COS` (`capsules/fabric.4th`,
+  `src/word_source/q48_words.c`) — Cartesian line-drawing (Bresenham, in
+  raster space) and Q48.16 fixed-point trig, both already load-bearing for
+  the glyph-rendering pipeline.
+
+No new C words were added for this — per this repo's standing rule ("compose
+in FORTH first; new C primitives are justified only for raw hardware access,
+atomics, syscalls, or freestanding kernel ops"), a turtle is pure policy on
+top of primitives that already exist.
+
+## Prerequisites
+
+- `capsules/fabric.4th` must be loaded first — the turtle uses its `LINE`
+  word directly, and (transitively) `Q.SIN`/`Q.COS`/`Q.FROM-INT`/`Q.TO-INT`/
+  `Q.*`/`Q.+` from `q48_words.c`, which is always registered.
+- A real framebuffer. `PLOT` is a no-op on hosted (`make`) builds, so the
+  turtle is only visually meaningful under the kernel/QEMU build with the
+  `gtk` display (`make -f Makefile.starkernel ARCH=<arch> qemu`). It loads
+  and runs its arithmetic identically on hosted builds — useful for logic
+  verification, not for seeing anything.
+
+## Loading it
+
+Not wired into `init.4th` — it is not part of the Mama VM's boot sequence,
+by design (memory: "invoked from the REPL", not autoloaded). Load and run it
+interactively:
+
+```forth
+S" turtle.4th" EXEC
+TURTLE-DEMO
+```
+
+`TURTLE-DEMO` clears the screen, draws a cyan hexagon, then a magenta
+five-pointed star from the same starting point — a one-call visual smoke
+test.
+
+## Vocabulary
+
+| Word | Stack effect | Effect |
+|------|---------------|--------|
+| `HOME` | `( -- )` | Turtle to screen center, heading east (0°), pen down, color white. Does not clear the screen. |
+| `CS` | `( -- )` | Clear the framebuffer to black. Plain nested `PLOT` loop (no fill primitive exists) — slow under TCG for a full screen; a one-shot clear, not a per-frame op. |
+| `PENUP` / `PENDOWN` | `( -- )` | Whether `FORWARD`/`BACK` draw while moving. |
+| `SETCOLOR` | `( color -- )` | 24-bit `0xRRGGBB`, same format `PLOT` takes directly. |
+| `SETXY` | `( x y -- )` | Jump to `(x y)` without drawing, regardless of pen state. |
+| `SETHEADING` | `( deg -- )` | Absolute heading in degrees, 0 = east, counterclockwise positive. |
+| `FORWARD` | `( n -- )` | Move `n` pixels along the current heading, drawing a `LINE` from old to new position if the pen is down. |
+| `BACK` | `( n -- )` | `FORWARD` in reverse (`NEGATE FORWARD`). |
+| `LEFT` | `( deg -- )` | Turn `deg` degrees counterclockwise in place. |
+| `RIGHT` | `( deg -- )` | Turn `deg` degrees clockwise in place (`NEGATE LEFT`). |
+| `POLYGON` | `( sides len -- )` | Regular polygon, drawn from the turtle's current position/heading — call `HOME` first for a clean start. |
+| `STAR` | `( len -- )` | Classic self-intersecting 5-pointed star (`FORWARD` + a 144° turn, five times — not `360/5=72°`, which draws a plain pentagon). |
+| `TURTLE-DEMO` | `( -- )` | `CS`, a cyan hexagon, then a magenta star. |
+
+Internal state (`TX`/`TY`/`THEAD`/`TPEN`/`TCOLOR` and the `FORWARD` scratch
+pair `TNX`/`TNY`) is exposed as ordinary `VARIABLE`s, matching every other
+piece of drawing-fabric state in `fabric.4th` — nothing here is hidden or
+C-side.
+
+## Worked example — a five-pointed star by hand
+
+```forth
+S" turtle.4th" EXEC
+HOME
+16711935 SETCOLOR   ( magenta, 0xFF00FF )
+100 STAR
+```
+
+Equivalent to running `TURTLE-DEMO`'s second half. `STAR` is not built from
+`POLYGON` with a different turn angle — a mathematically regular pentagon
+(`5 100 POLYGON`, turning `360/5 = 72°` per corner) is convex and does not
+self-intersect; the classic five-pointed star shape requires overshooting
+the turn to `144°` per corner instead, which is why `STAR` is its own word
+rather than a `POLYGON` call with `n=5`.
+
+## Design notes for anyone extending this
+
+- **Heading storage.** `THEAD` stores heading directly in Q48.16 radians
+  (not degrees) so `FORWARD` can hand it straight to `Q.SIN`/`Q.COS` without
+  a conversion on every step. `LEFT`/`RIGHT`/`SETHEADING` do the
+  degrees→radians conversion once, at the turn, via the `DEG2RAD` constant
+  (`1144`, Q48.16 for `π/180 ≈ 0.0174533`).
+- **No manual angle wraparound.** `q48_sin_approx`/`q48_cos_approx`
+  (`src/math_portable.c`) range-reduce internally via `q48_reduce_angle()`,
+  so `THEAD` can accumulate indefinitely across many turns without the
+  turtle needing to keep it inside `[0, 2π)` itself.
+- **Coordinates are Cartesian, not raster.** `TX`/`TY` follow `fabric.4th`'s
+  own convention (Y increases upward) — the Y-flip to raster space happens
+  once, inside `LINE`'s call to `TO-RASTER`/`CART-Y`. The turtle never
+  touches raster coordinates directly.
+- **z is always 0.** `fabric.4th`'s `LINE` takes 3D Cartesian points
+  (`x1 y1 z1 x2 y2 z2 color`) because it also serves the cavalier-projection
+  glyph/cube-drawing code; the turtle is flat, so it always passes `0` for
+  both z arguments.
+
+## Verification performed
+
+- `mkcapsule --lint capsules/` — clean, no block-size or namespace
+  violations (block range `5100`–`5108`, clear of `fabric.4th`'s highest
+  block at `5002`).
+- Logic verified on the hosted build: `fabric.4th`'s core blocks (`4900`–
+  `4909`) plus `turtle.4th` piped directly into `./build/amd64/standard/
+  starforth`, exercising `HOME`, `SETCOLOR`, `POLYGON`, `STAR`, `FORWARD`,
+  and (transitively) `LINE` — zero VM errors, correct stack balance
+  throughout (`--log-debug` trace confirms every `FORWARD` call computes
+  `dx`/`dy` via `Q.COS`/`Q.SIN` correctly and calls `LINE` with the expected
+  seven arguments).
+- Baked cleanly into `capsule_generated.c` (capsule `[35]`) on a full
+  `Makefile.starkernel ARCH=amd64` build, zero warnings; boot verified
+  clean through POST and into the DoE campaign with the capsule present
+  (not autoloaded, so it cannot affect the boot path it isn't on).
+- Not yet visually confirmed pixel-by-pixel in a live framebuffer (that
+  requires an interactive `gtk`-display QEMU session with a human at the
+  keyboard, or driving the serial socket past the ~25–30 minute DoE
+  campaign that runs automatically before the REPL is reachable — neither
+  was practical to do unattended). The arithmetic and control flow are
+  verified; the actual rendered image is not.