@bitcobblers/wod-wiki-tools 0.44.2159 → 0.45.2166

package/dist/web/playground/seed/core/markdown/canvas/ai-first/README.json

@@ -5,7 +5,7 @@
   "blockIndex": [],
   "blockEfforts": [],
   "blockEquipment": [],
-  "commit": "30e43c771d712a7c09bd8056d48d096ca769e705",
+  "commit": "32bda10ffc56a61ebfca76ae94f51eddba304498",
   "uuid": "a5c37d48-73da-5e5d-b0e3-53f08dce0fe8",
   "version": 1
 }

package/dist/web/playground/seed/core/markdown/canvas/guide/README.json

@@ -1,12 +1,12 @@
 {
   "path": "markdown/canvas/guide/README.md",
-  "content": "# Learning Collection — Design Review & Page Map\n\n> **Status: SHIPPED (2026-10).** The eight chapters in this directory are the production guide: each carries `template: canvas` + `route: /guide/<slug>` frontmatter and renders as a live canvas page. The six editor chapters (start, protocols, structure, metrics, clock, sessions) have the sticky workout editor, chapter/quest gameplay, and Run; **wql and dashboards are sandbox chapters** — no workout editor or quests, but the sticky panel holds a live, editable ```query sandbox (wql: preset query tabs; dashboards: the real seeded boards loaded with live widgets). The old 18 routed learning pages (`syntax/*` hubs and routed chapters, `behaviors/*`, `analytics/*`) were deleted in the same cutover — §7 is the migration map that was applied, with no redirects left behind.\n>\n> Shipped vs contract, precisely: **§3.1–§3.3 (fresh note per Run, record exactly once including Stop, reset snapshots) are implemented in the canvas runtime and exercised for real** (first Run/Stop verified inline on a guide page). **§3.4–§5 (stage-driven run, sticky stage flow, reduced-motion runways) remain the homepage-rebuild contract** — these guide pages use the standard canvas sticky panel, not the stage machine. §1's counts and fixtures table are the **pre-cutover inventory** (historical: 18 routed learning pages then; today this directory's 8).\n\n**The shared example.** Every chapter from [First Workout](/guide/start) through Dashboards reuses one workout, `markdown/canvas/home/sample-script.md` verbatim:\n\n```time\n(3)\n  10 Kettlebell Swings 24kg\n  *:30 Rest\n```\n\nYou edit it, run it, watch what the clock records (Metrics), query the records (WQL), and pin the query to a dashboard.\n\n---\n\n## 1. Design review of the pre-cutover learning surface (historical)\n\n**Exact routed count.** A route-frontmatter search across `markdown/` finds **20 routed pages**: syntax 8, analytics 6, behaviors 4, plus the homepage `canvas/home/README.md` (`/`) and `canvas/ai-first/README.md` (`/ai-first`). That gives **18 learning pages**. The inventory report's \"19 routed\" counted the homepage row but missed that `/ai-first` also carries `route:` frontmatter. Per scope, **homepage and `/ai-first` are product/marketing, not learning pages**, and are excluded from the collection (ai-first stays linked from First Workout as \"generate with AI\").\n\n**Orphans.** 65 of the 73 files in `markdown/canvas/syntax/` are non-routed tab-page fixtures (`search: hidden`, scroll-stage sources). They are compiled by tests and rendered only as scroll stages — several contradict their own routed captions. The collection de-orphans every unique topic without keeping the dead scroll plumbing.\n\n**Duplicates merged (unique topics preserved).**\n\n| Topic | Duplicates | Resolution |\n|---|---|---|\n| Calculated metrics ×3 | syntax/calculated-metrics.md (section document), custom-metrics-5.md (section custom-metrics), custom-and-calculated-metrics.md (section advanced) | one [Calculated](/guide/metrics?h=calculated) section in metrics.md |\n| AMRAP ×2 | protocols-1.md `20:00 (AMRAP)` vs classic-amrap.md `20:00 AMRAP` | keep the caption-blessed canonical `20:00 AMRAP` |\n| EMOM ×4 | protocols-2 `10:00 (EMOM)`, protocols-5 implicit, basic-emom `(10) :60 EMOM`, alternating/longer/custom variants | keep canonical `(10) :60 EMOM` + longer-interval + alternating branches |\n| Actions ×2 | supplemental-1 vs actions-comments | merged into [start.md#actions-comments](/guide/start?h=actions-comments) |\n| Rest ×2 | supplemental-2 vs timers-4 (both `*:30 Rest`) | merged into [protocols.md#required-rest](/guide/protocols?h=required-rest) |\n| Comments ×2 | supplemental-3 vs actions-comments | merged into start.md |\n| Unknown loads ×2 | supplemental-4 vs metrics-5 (`?lb`) | merged into [metrics.md#capture](/guide/metrics?h=capture) |\n| Cheatsheets ×2 | /guide/syntax/cheatsheet + /guide/analytics/cheatsheet | **no separate cheat-sheet page** — compact reference tables fold into [start.md#reference](/guide/start?h=reference) and [wql.md](/guide/wql?h=aggregate); 8 pages max |\n| Idioms tables | behaviors/README vs timers.md vs rounds.md (near row-for-row) | behaviors/README absorbed into [clock.md#run-next](/guide/clock?h=run-next) |\n| Prototype copies | root tour-redesign.prototype.html ≡ apps/playground copy | out of scope for markdown (IntegratedPrototype's); noted for cleanup |\n\n**Contradictions — resolved or flagged.** Ground truth = `packages/lang` parser/runtime + `packages/wql` vocabulary (verified in source, not from docs).\n\n| # | Docs say | Source says | Resolution in this collection |\n|---|---|---|---|\n| 1 | \"wrap your workout in a `wod` block\"; dialects page implies ```` ```wod ````/```` ```plan ````/```` ```climb ```` fences | runtime affords `time` (run) and `log` (record) fences only; dialect fixtures themselves use ```` ```time ````/```` ```log:climbing ```` | teach `time`/`log`/`log:climbing`; `wod`/`plan`/`climb` kept as *intent* vocabulary, flagged **needs validation** ([sessions.md#intent](/guide/sessions?h=intent)) |\n| 2 | home caption + prototypes: \"```` ```wql ```` for queries\"; cookbook shows ```wql copy blocks | real in-note fence is ```` ```query ````; no ```wql handling exists | use ```query everywhere; cookbook's ```wql snippet blocks flagged **needs validation** |\n| 3 | analytics/README + anatomy document `source:all` | parser hard-errors: \"source:all is retired — omit the source: filter\" | omitting `source:` **is** the all-sources default; never write `source:all` |\n| 4 | filters.md teaches singular `source:collection`/`source:feed` | every note belongs to `notebook/{slug}`; `notebook:<id>` pins a notebook and `WQL_SOURCE_VALUES` provides storage scopes | teach `notebook:<id>` and `notebook/{slug}`; `source:collection:<id>` remains a legacy storage-identity literal |\n| 5 | structure.md caption: name groups `(Warmup)`; named-groups/mixed-sections fixtures use `// Warmup` | classifier emits a labeled group node for `(Warmup)` (`RoundsMetric(label)`); `//` is a text comment — different mechanisms, both legal | both documented with the difference ([structure.md#named-sections](/guide/structure?h=named-sections)) |\n| 6 | `:?` placement: timers-3 prefixes (`:? Max Effort`), capture/cheatsheet append (`5:00 Run :?`) | `:?` is a standalone collectible-duration token; both positions parse | append taught as the convention; prefix noted as equally legal ([metrics.md#capture](/guide/metrics?h=capture)) |\n| 7 | behaviors/timers.md: movement without duration counts up; timers-5.md: \"no timer — stopwatch mode\" | `DurationMetric.direction`: value 0/undefined/collectible → **up** | same behavior, two descriptions: a bare movement runs a count-up stopwatch ([clock.md](/guide/clock)) |\n| 8 | capture.md queries `avg:wod.rpe by {week}` | no `wod.rpe` key exists anywhere; session RPE is typed metric `session-rpe` | corrected to `avg:session-rpe{} by {week}` ([metrics.md#session-rpe](/guide/metrics?h=session-rpe)) |\n| 9 | anatomy.md lists `metMinutes` as a base metric | vocabulary registers it as `calc.metMinutes` (engine-published) | listed under calculated metrics ([metrics.md#calculated](/guide/metrics?h=calculated)) |\n| 10 | prototypes use `{tag:benchmark}`, `{intensity:zone4}`, `since:2026-01-01` | real keys: `tags:`; intensity tiers `low|moderate|high`; windows `last <n>d|w` / `from … to …` | corrected vocabulary shipped in wql.md; IntegratedPrototype notified |\n| 11 | behaviors/README idiom `AMRAP 10` (label-first) | fixtures only show duration-first `20:00 AMRAP` (canonical per caption) | duration-first everywhere; label-first order flagged **needs validation** |\n| 12 | home/README still carries a retired 720vh ```scroll:chapters spec; HomeView error cites nonexistent routes/home.md | dead plumbing | out of scope here — flagged for the homepage rebuild owner |\n| 13 | behaviors/capture.md: `5:00 Run :?` asks for \"actual distance covered in the 5 minutes\"; \"prompt for load **before** the first squat\" | `:?` is a collectible **timer**: it mounts a count-up timer whose elapsed time is recorded on completion (compliance suites `timer.compliance`/`countup.compliance`; parse skill's collectible rule: prescribed time → collect distance with `?m`, prescribed distance → collect time with `:?`). No runtime evidence schedules a load prompt \"before the first rep\" — prompt timing is a capture-surface concern | metrics.md teaches the collectible family (`?` reps, `:?` time, `?lb`/`?kg` load, `?m`/`?km`/`?mile` distance) with prescribed-vs-outcome rule; prompt timing not asserted |\n\n**Honesty rules carried into every chapter.** No invented HR/trend numbers; calculated metrics document only real prerequisites (e.g. `calc.readiness` publishes a value for a day only when soreness, sleep, and HRV were all captured that day — verified in `calc/seeds.ts`). Unlanded `calc.*` surfaces render a labeled \"proposed\" placeholder in the app; dashboards label sample answers as sample.\n\n---\n\n## 2. The eight proposed pages\n\n| # | File | Proposed title | Sticky stages | Absorbs |\n|---|---|---|---|---|\n| 1 | [start.md](/guide/start) | First Workout | editor → runtime | basics.md, syntax/README hub, core syntax tab pages, the printable cheat sheet |\n| 2 | [protocols.md](/guide/protocols) | Timers & Protocols | editor → runtime | protocols.md, all timer/protocol tab pages, the timer half of behaviors/timers.md |\n| 3 | [structure.md](/guide/structure) | Structure & Rounds | editor → runtime | structure.md, group tab pages, behaviors/rounds.md |\n| 4 | [metrics.md](/guide/metrics) | Metrics: Planned, Recorded, Calculated | editor → runtime (results focus) | custom-metrics.md, metric/calculated tab pages, behaviors/capture.md |\n| 5 | [clock.md](/guide/clock) | Run, Track & Capture (the Clock) | editor → runtime (runtime is the subject) | behaviors/README.md, the runtime halves of timers.md/capture.md |\n| 6 | [wql.md](/guide/wql) | Query Your Training (WQL) | editor → WQL table (data focus) | analytics/README, anatomy, filters, joins |\n| 7 | [dashboards.md](/guide/dashboards) | Dashboards & Cookbook | WQL table → dashboard (data focus) | analytics/cookbook, the query-block half of analytics/cheatsheet, the 6 seeded boards |\n| 8 | [sessions.md](/guide/sessions) | Dialects & Complex Sessions | editor → runtime | dialects.md, complex.md, dialect/complex tab pages |\n\nThe stages column is mirrored verbatim in each page's chapter banner. Chapters 1–3 and 8 **run and save**; chapter 5 documents the runtime itself; chapters 4, 6, 7 focus on **reading the data** runs produce. No chapter defines its own result policy — every run saves under the one contract in [§3](#run-contract).\n\n### Common page model\n\nEvery chapter uses the same skeleton: `# Title`, chapter banner (chapter number, **Sticky stages** line, replaced routes, homepage placements), the teaching sections with their existing anchors, exactly one `## Try it {#try-it}`, and a one-line chapter footer (`**Next:** … · [Overview](/guide/start)`). A Try it block has three labeled parts — **Run** (what to paste/press), **Observe** (what the runtime should show), **Result query** where the chapter reads data — and any caption buttons reuse existing action labels only (`Run`, preset names, `Cast`); no invented controls, no duplicated nav prose.\n\nEntry and deep-link anchors (used by the homepage and the prototype's learn links):\n\n| Page | Entry anchor | Try it | Key deep anchors |\n|---|---|---|---|\n| start.md | `#first-workout` | `#try-it` | `#reference`, `#measurements` |\n| protocols.md | `#countdown-countup` | `#try-it` | `#amrap`, `#required-rest` |\n| structure.md | `#rounds` | `#try-it` | `#named-sections`, `#rep-schemes` |\n| metrics.md | `#planned-vs-recorded` | `#try-it` | `#capture`, `#calculated`, `#session-rpe` |\n| clock.md | `#run-next` | `#try-it` | `#casting`, `#provenance`, `#pause-skip`, `#capture-prompts` |\n| wql.md | `#planes` | `#try-it` | `#aggregate`, `#filters`, `#sources`, `#windows`, `#joins` |\n| dashboards.md | `#note-frontmatter` | `#try-it` | `#widgets`, `#cookbook`, `#seeded-boards`, `#composer` |\n| sessions.md | `#intent` | `#try-it` | `#full-session` |\n\nReading order is the numbered order; 1–3 teach writing, 4–5 teach what running records, 6–7 teach querying, 8 composes everything.\n\n---\n\n## 3. Run & save contract — today vs proposed {#run-contract}\n\n> **Everything in §3–§5 is PROPOSED** for the homepage rebuild and these eight chapters. \"Today\" statements come from source review of the intake/recorder seams, run refs, reset paths, and scroll drivers — no runtime behavior has been exercised, and nothing here is implemented. The eight drafts above carry **no `route:` frontmatter** and no runtime wiring.\n\n### 3.1 One active workspace, immutable run archive\n\n**Today.** One active persisted Note per *surface*: `ensurePlaygroundEntry` (`createPlaygroundPage.ts`) creates once, then **updates in place** under reuseKey `'home'`, `'chapter-<id>'`, or `canvas:<route>` (`getCanvasNoteId`, `canvasUtils.ts`) — deliberately, so the library doesn't fill with duplicate experiment entries. Fresh notes are minted only by explicit New/Reset page buttons, ZIP import, templates, and journal→playground copies (each named via `formatPlaygroundTimestampId`). Reset is in-memory only: `HomeTour.startNewSession` and `useCanvasRuntime.closeRun` unmount without recording — in-flight results are silently dropped.\n\n**Proposed.** Keep exactly one active **editable workspace** per surface — the hero editor remains the single authoring surface, sticky through its stage. Nothing overwrites the draft in place, and nothing is ever activated in place of a new note: **every Run creates a fresh note, and every Reset creates a separate fresh unstarted draft snapshot — both retained** (the extra archive entries are intentional; the user explicitly asked for clones of both). Reset finalizes the active run partial, restores the template content in the editor, and mints a fresh draft snapshot (status `reset-unstarted`) as its archive record; the next Run still mints its own fresh note — a reset draft is never activated. Snapshot name = `<page label> — <section label> — <formatPlaygroundTimestampId>`: labels taken verbatim from the page H1 and the section heading the run launched from; section is optional (hero runs use the section label `Run`); run state (`running` / `completed` / `stopped` / `reset-unstarted`) is note metadata, not a second naming scheme. One workspace ≠ one saved note — **all session data is always recorded**: the archive retains every run and reset snapshot; retention is §3.6.\n\n### 3.2 Create before run; capture identity at start\n\n**Today.** Runs already persist before execution: `ensurePlaygroundEntry` completes before the runtime mounts, and save failure = toast + abort — no execution without a saved note. Run identity `{noteId, resultId, block}` is captured once at start and never re-derived (`activeRun.current`, `useCanvasRuntime.ts:56`; `playgroundEntryRef`/`playgroundBlockRef`, `HomeTour.tsx:602-616`). Recording resolves `segmentId = runBlock?.id ?? blockId`, `blockContentId = runBlock?.contentId`, origin `'playground'` for playground notes (`resultRecorder.ts:104-133`); segment **version** is deferred to the persistence adapter at write time.\n\n**Proposed.** Unchanged mechanics, new target: the captured triple points at the run's **snapshot** note — minted fresh at every Run (never a reused reset draft) — and the snapshot **source** is captured at start the same way — captured results can never retroactively bind to a later-edited draft. Editing the draft mid-run is a *try-edit*: finalize the active run partial, halt, let the editor change live; the edited content becomes a snapshot only at the next Run.\n\n### 3.3 Record once — partial or full — with failure guards\n\n**Today.** `playgroundRecorder.record` is the only result seam; natural completion and Stop both record (Stop sends `completed:false`). But `handleWorkoutComplete` never consumes the captured run — a second completion call would re-record the same resultId — and reset paths drop without recording. Other sourced races: two concurrent same-reuseKey `ensureEntry` calls can mint two same-slug notes; `completeWorkout` (workbench) is a non-atomic two-write pair whose result-write failure is only console-logged.\n\n**Proposed.** One finalization path shared by **natural completion, Stop, and metrics-stage arrival** (entering the metrics stage stops the runtime and finalizes). Record **exactly once** per run — partial (`completed:false`) or full — by consuming the captured run on record (clear `activeRun.current` / generation check, or an id-keyed guard in the recorder). Guards:\n\n- **Reset while running:** finalize the partial first and **retain the snapshot — always, even with zero outputs**, marked reset/unstarted, with no fabricated performance rows (a zero-output note honestly records \"attempted, nothing captured\"; nothing is silently dropped). Reset then mints a **separate fresh unstarted draft snapshot** as its archive record; the next Run still creates its own fresh note — prepared/reset drafts are never activated (explicit user policy: each run creates a new note; the extra archive entry is requested).\n- **Save failure:** persist-before-run stays; a failed save must **never clear recorded output nor auto-start a new run** — the run and its results stay, retry is explicit.\n- Per-run snapshots retire the reuseKey race surface entirely (each run mints its own note; no shared-slug ensure).\n- In the HTML prototype, session recording stays **page-memory only** and is labelled visibly as such; production records through the recorder seam.\n\n### 3.4 No fullscreen; stage-driven run\n\n**Today.** Run mounts a fullscreen overlay (`TourTimerScreen` tour-side, `FullscreenTimer` canvas-side) with autostart gated in `RuntimeTimerPanel` (`(autoStart||pendingStart)&&ready&&idle`).\n\n**Proposed.** Run scrolls to the **inline runtime stage** — no fullscreen. Arrival autostarts **once per run**. Captions offer existing actions only, as optional explicit buttons (`Run`, `Next`, `Stop`, `Cast` — real control labels/testids, no hidden auto-Next, no auto-cast; the autoplay entrance is user-scroll-triggered). A previous runtime resumes only via explicit **Run** (which always mints a new snapshot).\n\n### 3.5 Stage observers are idempotent\n\nBackward scroll never restarts a run nor replays a one-shot stage effect (renormalized progress + reached-once guards, the `useReachedOnce` pattern). Forward **fast scroll** that resolves straight to a later stage cannot launch the skipped runtime stage: the stage machine emits one discrete stage per frame (`resolveScrollStage`), so skipped stages' enter effects (autostart included) never fire. Every stage-enter effect runs once per run, not once per direction.\n\n### 3.6 Bounded seams and cleanup scope\n\nAll changes are bounded to existing seams — no new subsystem:\n\n1. **Snapshot naming** — a policy inside `createPlaygroundIntake` (the single note-minting seam); callers (`HomeTour`, `useCanvasRuntime`) keep their signatures. Explicit New/Reset page buttons keep today's `createPage` semantics.\n2. **Record-once** — a guard at the recorder or the run hooks (consume captured run / id-keyed guard), closing the double-record race before any autostart re-runs exist.\n3. **Partial finalize on reset** — a `completed:false` record at the two reset points (`HomeTour.startNewSession`, `useCanvasRuntime.closeRun`), retained even at zero outputs, then a separate fresh unstarted draft snapshot is minted (Run never activates it).\n4. **One active session owner** — generalize the `useCanvasRuntime` pattern instead of scattered refs (HomeTour refs vs canvas `activeRun` vs workbench store). **The workbench keeps its own multi-note session store** (`completeWorkout`, autosave, `resetStore`): it serves journal/workbench routes and promotion — one-active is a *playground-surface policy*, not a storage policy. Don't delete general workbench multi-note session support because the homepage is one-active.\n5. **Retention** — snapshot growth is handled by the existing promotion invariant (`movePlaygroundToJournal` — moved notes can never be hijacked by a later same-key ensure) and `find:note{source:playground}` scoping, not new deletion logic.\n\n**Cleanup scope when the collection is approved** (not before — nothing here routes the eight drafts or retires any `/guide/*` route):\n\n- Safe to retire with their routed parents: the 65 non-routed syntax tab-page fixtures and their ```scroll stage plumbing (they exist as scroll-stage sources for routed pages), the duplicate prototype HTML copy (keep one canonical), the `ProtoTimerMobile` throwaway (`?proto-timer`), the retired 720vh ```scroll:chapters spec in `canvas/home/README.md`.\n- **Out of scope:** workbench/journal session store and its wiring, collections/feeds/journal surfaces, promotion, chapter-run reuse — multi-note session support serves routes beyond the homepage and survives a one-active homepage.\n\n---\n\n## 4. Sticky stage flow (desktop & mobile)\n\nFour sticky stages in page order: **editor → runtime → WQL table → dashboard**. Desktop is native **sticky push-off**: each stage is a tall section whose card sticks at the nav offset (`STICKY_NAV_HEIGHT` = 104px, card `h-[calc(100vh-104px)]` — the `TourSectionRunway` pattern) and is pushed off by the next stage's sticky card, driven by the existing pure stage machine (`resolveScrollStage` with clamp01/renormalize over a capture-phase scroll listener). The hero editor is **one reused instance** sticking through stage 1. Run scrolls editor→runtime; **Stop (or metrics arrival) slides the metrics view in**; the **WQL table stage** sticks bound to the **current run's facts**, with caption query actions (real queries, `ParsedQueryChips` vocabulary) and a floating **\"Revert current session\"** that re-binds the table to the current run — discarding view-state (query tweaks, sample overlay) only; the **dashboard stage** sticks a board with **load buttons** for the seeded boards.\n\nMobile (≤1023px, `MOBILE_BREAKPOINT_PX`): **bounded sticky stage windows** — one stage card at a time in the reading zone (top 65px window, `MOBILE_STICKY_TOP`), captions **below** the card, card-visibility IntersectionObserver as the stage driver (the `TourMobileRunway` pattern). Same stage order, same run contract.\n\nReduced motion wins everywhere (`RunwayAdapter`: reduced > mobile > desktop): flat card stack, no push-off, no scroll scrub; stage arrival is visibility-based and still once-per-run.\n\nGuarantees on every form factor:\n\n- Runtime arrival autostarts once; backward scroll never restarts; fast scroll to a later stage cannot launch the skipped runtime (§3.5).\n- Caption actions are explicit buttons using existing labels; no hidden auto-Next/auto-cast.\n- Sample fallbacks are badged **sample**; sample datasets and dashboard/board edits never mutate saved session results; **Revert** restores view only.\n\n---\n\n## 5. System organization\n\n| Term | Purpose | Scope / storage |\n|---|---|---|\n| **Note** | the markdown document + identity (uuidv7 id, slug, sourceId, type) | one IndexedDB store (notes + results + attachments + analytics) |\n| **Page** | a note bound to a surface (routed guide page, playground home/canvas) | bindings via reuseKey / `getCanvasNoteId` |\n| **Block** | one addressable fenced unit in a note; the run target | Block Content Id = content hash, stable across reorders/clones |\n| **Effort** | named workout registry entry (e.g. *fran*) | content-plane query target; aggregates `by {effort}` |\n| **Session** | one recorded run | `{noteId, resultId, block}` triple; results join `Session.noteId` |\n| **Journal** | default dated training notebook (`notebook/journal`) | `notebook:journal` (`source:journal`); promotion target |\n| **Playground** | default experiment notebook (`notebook/playground`) | `notebook:playground` (`source:playground`); run snapshots archive here until promoted |\n| **Notebook** | user-created or seed-delivered notebook (`notebook/{slug}`) | `notebook:<id>` (`source:notebooks`); seed notebooks are read-only and clone into writable notebooks |\n| **Dashboard** | a note with `dashboard: true`; its query blocks render as widgets | vault (editable) vs prebuilt (read-only, clone) |\n\n**`notebook:` & `source:` scope.** Filter by `notebook:<id>` (`journal`, `playground`, `guides`, `crossfit-girls`, etc.) or plural `source:` values; omitting both searches all notes. Learning runs record in `notebook/playground` until promotion re-homes the note to `notebook/journal`.\n\n**Session vs template vs sample dataset vs revert.**\n\n- **Session** — immutable recorded facts from one run against its snapshot note.\n- **Template** — read-only source content (`sample-script.md`, `WORKOUT_PRESETS`, catalog sessions, seeded boards). Running a template copies it into the active workspace/snapshot; **templates never mutate**.\n- **Sample dataset** — the SAMPLE fallback (`SAMPLE_HOME_ANALYTICS`, `SampleDataPrompt`) shown when the store has no facts; always badged sample; never persisted as your results.\n- **Revert** (\"Revert current session\") — discards view-state only (query tweaks, sample overlay) and re-binds the stage to the current run's recorded facts; never deletes saved sessions.\n\n---\n\n## 6. Homepage placements (existing slots only)\n\n| Homepage slot | Proposed links |\n|---|---|\n| Hero / editor-blank caption | \"Start Lesson 1\" → start.md#first-workout; add \"See the full syntax\" → start.md#reference |\n| 01 Write — editor-metrics caption | add \"What each line collects\" → metrics.md |\n| 01 Write — WORKOUT_PRESETS | each preset mirrors a protocols.md / structure.md example |\n| 02 Run — behaviors caption | point \"Read the behaviors explainer\" → clock.md |\n| 02 Run — timer-cast caption | clock.md#casting |\n| 03 Own — metrics-d (\"Measures ride along\") | add action → metrics.md |\n| 03 Own — metrics-c (\"Efforts × measures compound\") | add teaser → wql.md |\n| 04 Explore (currently no inline analytics links; `home:analytics_guide_opened` telemetry declared but never fired) | header actions: \"WQL in depth\" → wql.md, \"Copy-paste queries\" → dashboards.md#cookbook; wql-dashboard/wql-live captions → dashboards.md#seeded-boards |\n| CelebrationBridge (\"Now learn the language\") | render the 8-chapter map as the card row |\n| TourChapterPicker / TourLearnSection | CHAPTER_ROUTES gains the 8 files |\n| Footer \"Where to next?\" | add Learn column: start.md, wql.md, dashboards.md |\n| /ai-first | stays a standalone marketing page, linked from start.md (\"Generate with AI\") |\n\n## 7. Old route → new page/anchor map\n\nConcrete migration map for the 18 currently routed learning pages. Slugs follow the current routed files under `markdown/canvas/`; the eight targets are §2's files. **Both cheatsheets are absorbed into existing pages — there is no ninth page.** Nothing routes or redirects until the collection is approved; until then both trees coexist.\n\n| Old location (routed file) | New target |\n|---|---|\n| `syntax/README.md` (hub) | [start.md](/guide/start) header + [sessions.md#intent](/guide/sessions?h=intent) |\n| `syntax/basics.md` | [start.md#first-workout](/guide/start?h=first-workout) |\n| `syntax/protocols.md` | [protocols.md#countdown-countup](/guide/protocols?h=countdown-countup) |\n| `syntax/structure.md` | [structure.md#rounds](/guide/structure?h=rounds) |\n| `syntax/custom-metrics.md` | [metrics.md#planned-vs-recorded](/guide/metrics?h=planned-vs-recorded) |\n| `syntax/dialects.md` | [sessions.md#intent](/guide/sessions?h=intent) |\n| `syntax/complex.md` | [sessions.md#full-session](/guide/sessions?h=full-session) |\n| `syntax/cheatsheet.md` | [start.md#reference](/guide/start?h=reference) — **cheatsheet #1 absorbed** |\n| `behaviors/README.md` | [clock.md#run-next](/guide/clock?h=run-next) |\n| `behaviors/timers.md` | [protocols.md](/guide/protocols) (syntax forms) + [clock.md#pause-skip](/guide/clock?h=pause-skip) (runtime) |\n| `behaviors/rounds.md` | [structure.md#rep-schemes](/guide/structure?h=rep-schemes) + [clock.md#run-next](/guide/clock?h=run-next) |\n| `behaviors/capture.md` | [metrics.md#capture](/guide/metrics?h=capture) + [clock.md#capture-prompts](/guide/clock?h=capture-prompts) |\n| `analytics/README.md` | [wql.md#planes](/guide/wql?h=planes) |\n| `analytics/anatomy.md` | [wql.md#aggregate](/guide/wql?h=aggregate) |\n| `analytics/filters.md` | [wql.md#filters](/guide/wql?h=filters) · [#sources](/guide/wql?h=sources) · [#windows](/guide/wql?h=windows) |\n| `analytics/joins.md` | [wql.md#joins](/guide/wql?h=joins) |\n| `analytics/cookbook.md` | [dashboards.md#cookbook](/guide/dashboards?h=cookbook) |\n| `analytics/cheatsheet.md` | [wql.md#aggregate](/guide/wql?h=aggregate) tables + [dashboards.md#widgets](/guide/dashboards?h=widgets) — **cheatsheet #2 absorbed** |\n\nThe 65 non-routed tab-page fixtures follow their routed parents (their unique content is already merged — §8). `canvas/home/README.md` (homepage) and `canvas/ai-first/README.md` stay product pages, out of the collection.\n\n## 8. Source coverage\n\nEvery routed learning page (18) and every underlying non-routed lesson source (65 syntax tab pages + 2 home sources), mapped to its target. Merged duplicates list only once with their union.\n\n| Current source (routed unless marked) | Topics kept | → New page |\n|---|---|---|\n| syntax/README.md (hub) | core concepts map, dialect intro, new-note CTA | start.md (header/TOC), sessions.md#intent |\n| syntax/basics.md | fences, one-thing-per-line, indentation, measurements, `?lb`, effort words, actions, comments | start.md |\n| syntax/protocols.md + timers-rest, timer-modifiers, timers-1..5, longer-duration, mixed-timers, classic-amrap, time-cap, multiple-amrap-windows, basic-emom, longer-intervals, alternating-emom, protocols-1..5, custom-intervals, distance-intervals, supplemental-2 | countdown/countup/`^`/`*`/`:?`, H:MM:SS, AMRAP, caps, EMOM family, Tabata, intervals, rest | protocols.md |\n| syntax/structure.md + groups-1..4, named-groups, mixed-sections, multiple-sets | rounds, rep schemes, nesting, named sections, sets | structure.md |\n| syntax/custom-metrics.md + custom-metrics-1..5, calculated-metrics, custom-and-calculated-metrics, metrics-1..5, supplemental-4 | inline JSON, rpe/rir, multi-metric lines, calculate blocks, JSON rules, unknown loads `?lb`/`?kg` | metrics.md |\n| syntax/dialects.md + dialect-wod/log/plan, dialect-climb-bouldering/hangboard/sport | intent distinction, `log:climbing`, climbing signals | sessions.md |\n| syntax/complex.md + complex-nested-protocols, complex-full-session, complex-barbell-cycling, complex-partner-workout, complex-swimming | nested protocols, full session, EMOM chains, partner windows, swimming | sessions.md |\n| syntax/cheatsheet.md (routed) | one-page syntax | start.md#reference + per-page tables (no separate page) |\n| syntax/single-movement, core-rules, measurements, effort-notes, actions-comments, supplemental-1, supplemental-3, document-1..4, welcome-1 (home/), sample-script.md (home/) | smallest workout, three rules, headers/checklists/equipment-table document patterns, actions/comments | start.md |\n| behaviors/README.md | script→parse→compile→track, 3 behavior families, idioms | clock.md |\n| behaviors/timers.md | timer strategy selection, sound/pause/skip/required-rest | clock.md (+ protocols.md for syntax forms) |\n| behaviors/rounds.md | round behavior, rep math, supersets, interval groups, rounds↔timers | structure.md (+ clock.md) |\n| behaviors/capture.md | `:?`, `?lb`/`?kg`, session RPE, trendlines, fact origins | metrics.md (+ clock.md for prompt behavior) |\n| analytics/README.md | 3 WQL surfaces, 2 query planes, where-join | wql.md |\n| analytics/anatomy.md | aggregators, base/calc metrics, dimensions, rollups, find targets | wql.md |\n| analytics/filters.md | tag filters (negation/OR/substring), source filters, time windows, Library tri-state toggles | wql.md |\n| analytics/joins.md | where joins, Block Content Id mechanics | wql.md |\n| analytics/cookbook.md | 5 canonical queries, ```query embeds, dashboard notes, widget types/spans | dashboards.md (+ wql.md) |\n| analytics/cheatsheet.md | WQL one-pager | wql.md tables + dashboards.md#widgets (no separate page) |\n| markdown/dashboards/training-block-review.md | widget exemplars (see dashboards.md#seeded-boards) | dashboards.md |\n| markdown/dashboards/road-to-560-total.md | strength PR board exemplar | dashboards.md#seeded-boards |\n| markdown/dashboards/polarized-base-marathon.md | endurance polarization exemplar | dashboards.md#seeded-boards |\n| markdown/dashboards/finger-strength-v8.md | climbing board exemplar (wellness capture, `calc.mvcBw`) | dashboards.md#seeded-boards |\n| markdown/dashboards/benchmark-pr-board.md | benchmark table exemplar (`last:elapsed{tags:benchmark}`) | dashboards.md#seeded-boards |\n| markdown/dashboards/recovery-readiness.md | ```wellness capture + readiness exemplar | dashboards.md#seeded-boards (+ metrics.md#calculated) |\n\nNot counted as learning sources: `canvas/home/README.md` (product walkthrough — the homepage itself stays), `canvas/ai-first/README.md` (AI marketing, linked as an aside). Orphaned scroll plumbing (```scroll blocks, getTabExamples/getHomeExample, protocols-1's `(AMRAP)` spelling) is dropped, not migrated.\n\n## 9. Review method\n\nEach chapter ends with a **Try it** block: what to paste/press, what the runtime should show, and — for data chapters — the result query — a reviewer checklist, not a test report. Every syntax, behavior, and query claim in this collection comes from **source review only** (parser grammar, compiler metrics, WQL vocabulary/seeds, shipped fixtures). That was true at review time; since the cutover the chapters are production pages — the §3.1–§3.3 run/save behavior is implemented and exercised, while §3.4–§5 (stage flow) stay contract-only (see the status block).\n",
+  "content": "# Learning Collection — Design Review & Page Map\n\n> **Status: SHIPPED (2026-10).** The eight chapters in this directory are the production guide: each carries `template: canvas` + `route: /page/guide-<slug>` frontmatter and renders as a live canvas page. The six editor chapters (start, protocols, structure, metrics, clock, sessions) have the sticky workout editor, chapter/quest gameplay, and Run; **wql and dashboards are sandbox chapters** — no workout editor or quests, but the sticky panel holds a live, editable ```query sandbox (wql: preset query tabs; dashboards: the real seeded boards loaded with live widgets). The old 18 routed learning pages (`syntax/*` hubs and routed chapters, `behaviors/*`, `analytics/*`) were deleted in the same cutover — §7 is the migration map that was applied, with no redirects left behind.\n>\n> Shipped vs contract, precisely: **§3.1–§3.3 (fresh note per Run, record exactly once including Stop, reset snapshots) are implemented in the canvas runtime and exercised for real** (first Run/Stop verified inline on a guide page). **§3.4–§5 (stage-driven run, sticky stage flow, reduced-motion runways) remain the homepage-rebuild contract** — these guide pages use the standard canvas sticky panel, not the stage machine. §1's counts and fixtures table are the **pre-cutover inventory** (historical: 18 routed learning pages then; today this directory's 8).\n\n**The shared example.** Every chapter from [First Workout](/page/guide-start) through Dashboards reuses one workout, `markdown/canvas/home/sample-script.md` verbatim:\n\n```time\n(3)\n  10 Kettlebell Swings 24kg\n  *:30 Rest\n```\n\nYou edit it, run it, watch what the clock records (Metrics), query the records (WQL), and pin the query to a dashboard.\n\n---\n\n## 1. Design review of the pre-cutover learning surface (historical)\n\n**Exact routed count.** A route-frontmatter search across `markdown/` finds **20 routed pages**: syntax 8, analytics 6, behaviors 4, plus the homepage `canvas/home/README.md` (`/`) and `canvas/ai-first/README.md` (`/ai-first`). That gives **18 learning pages**. The inventory report's \"19 routed\" counted the homepage row but missed that `/ai-first` also carries `route:` frontmatter. Per scope, **homepage and `/ai-first` are product/marketing, not learning pages**, and are excluded from the collection (ai-first stays linked from First Workout as \"generate with AI\").\n\n**Orphans.** 65 of the 73 files in `markdown/canvas/syntax/` are non-routed tab-page fixtures (`search: hidden`, scroll-stage sources). They are compiled by tests and rendered only as scroll stages — several contradict their own routed captions. The collection de-orphans every unique topic without keeping the dead scroll plumbing.\n\n**Duplicates merged (unique topics preserved).**\n\n| Topic | Duplicates | Resolution |\n|---|---|---|\n| Calculated metrics ×3 | syntax/calculated-metrics.md (section document), custom-metrics-5.md (section custom-metrics), custom-and-calculated-metrics.md (section advanced) | one [Calculated](/page/guide-metrics?h=calculated) section in metrics.md |\n| AMRAP ×2 | protocols-1.md `20:00 (AMRAP)` vs classic-amrap.md `20:00 AMRAP` | keep the caption-blessed canonical `20:00 AMRAP` |\n| EMOM ×4 | protocols-2 `10:00 (EMOM)`, protocols-5 implicit, basic-emom `(10) :60 EMOM`, alternating/longer/custom variants | keep canonical `(10) :60 EMOM` + longer-interval + alternating branches |\n| Actions ×2 | supplemental-1 vs actions-comments | merged into [start.md#actions-comments](/page/guide-start?h=actions-comments) |\n| Rest ×2 | supplemental-2 vs timers-4 (both `*:30 Rest`) | merged into [protocols.md#required-rest](/page/guide-protocols?h=required-rest) |\n| Comments ×2 | supplemental-3 vs actions-comments | merged into start.md |\n| Unknown loads ×2 | supplemental-4 vs metrics-5 (`?lb`) | merged into [metrics.md#capture](/page/guide-metrics?h=capture) |\n| Cheatsheets ×2 | /guide/syntax/cheatsheet + /guide/analytics/cheatsheet | **no separate cheat-sheet page** — compact reference tables fold into [start.md#reference](/page/guide-start?h=reference) and [wql.md](/page/guide-wql?h=aggregate); 8 pages max |\n| Idioms tables | behaviors/README vs timers.md vs rounds.md (near row-for-row) | behaviors/README absorbed into [clock.md#run-next](/page/guide-clock?h=run-next) |\n| Prototype copies | root tour-redesign.prototype.html ≡ apps/playground copy | out of scope for markdown (IntegratedPrototype's); noted for cleanup |\n\n**Contradictions — resolved or flagged.** Ground truth = `packages/lang` parser/runtime + `packages/wql` vocabulary (verified in source, not from docs).\n\n| # | Docs say | Source says | Resolution in this collection |\n|---|---|---|---|\n| 1 | \"wrap your workout in a `wod` block\"; dialects page implies ```` ```wod ````/```` ```plan ````/```` ```climb ```` fences | runtime affords `time` (run) and `log` (record) fences only; dialect fixtures themselves use ```` ```time ````/```` ```log:climbing ```` | teach `time`/`log`/`log:climbing`; `wod`/`plan`/`climb` kept as *intent* vocabulary, flagged **needs validation** ([sessions.md#intent](/page/guide-sessions?h=intent)) |\n| 2 | home caption + prototypes: \"```` ```wql ```` for queries\"; cookbook shows ```wql copy blocks | real in-note fence is ```` ```query ````; no ```wql handling exists | use ```query everywhere; cookbook's ```wql snippet blocks flagged **needs validation** |\n| 3 | analytics/README + anatomy document `source:all` | parser hard-errors: \"source:all is retired — omit the source: filter\" | omitting `source:` **is** the all-sources default; never write `source:all` |\n| 4 | filters.md teaches singular `source:collection`/`source:feed` | every note belongs to `notebook/{slug}`; `notebook:<id>` pins a notebook and `WQL_SOURCE_VALUES` provides storage scopes | teach `notebook:<id>` and `notebook/{slug}`; the retired `collection:`/`feed:` source literals hard-error at parse time (ticket 12) and stored occurrences rewrite to `notebook:` on read |\n| 5 | structure.md caption: name groups `(Warmup)`; named-groups/mixed-sections fixtures use `// Warmup` | classifier emits a labeled group node for `(Warmup)` (`RoundsMetric(label)`); `//` is a text comment — different mechanisms, both legal | both documented with the difference ([structure.md#named-sections](/page/guide-structure?h=named-sections)) |\n| 6 | `:?` placement: timers-3 prefixes (`:? Max Effort`), capture/cheatsheet append (`5:00 Run :?`) | `:?` is a standalone collectible-duration token; both positions parse | append taught as the convention; prefix noted as equally legal ([metrics.md#capture](/page/guide-metrics?h=capture)) |\n| 7 | behaviors/timers.md: movement without duration counts up; timers-5.md: \"no timer — stopwatch mode\" | `DurationMetric.direction`: value 0/undefined/collectible → **up** | same behavior, two descriptions: a bare movement runs a count-up stopwatch ([clock.md](/page/guide-clock)) |\n| 8 | capture.md queries `avg:wod.rpe by {week}` | no `wod.rpe` key exists anywhere; session RPE is typed metric `session-rpe` | corrected to `avg:session-rpe{} by {week}` ([metrics.md#session-rpe](/page/guide-metrics?h=session-rpe)) |\n| 9 | anatomy.md lists `metMinutes` as a base metric | vocabulary registers it as `calc.metMinutes` (engine-published) | listed under calculated metrics ([metrics.md#calculated](/page/guide-metrics?h=calculated)) |\n| 10 | prototypes use `{tag:benchmark}`, `{intensity:zone4}`, `since:2026-01-01` | real keys: `tags:`; intensity tiers `low|moderate|high`; windows `last <n>d|w` / `from … to …` | corrected vocabulary shipped in wql.md; IntegratedPrototype notified |\n| 11 | behaviors/README idiom `AMRAP 10` (label-first) | fixtures only show duration-first `20:00 AMRAP` (canonical per caption) | duration-first everywhere; label-first order flagged **needs validation** |\n| 12 | home/README still carries a retired 720vh ```scroll:chapters spec; HomeView error cites nonexistent routes/home.md | dead plumbing | out of scope here — flagged for the homepage rebuild owner |\n| 13 | behaviors/capture.md: `5:00 Run :?` asks for \"actual distance covered in the 5 minutes\"; \"prompt for load **before** the first squat\" | `:?` is a collectible **timer**: it mounts a count-up timer whose elapsed time is recorded on completion (compliance suites `timer.compliance`/`countup.compliance`; parse skill's collectible rule: prescribed time → collect distance with `?m`, prescribed distance → collect time with `:?`). No runtime evidence schedules a load prompt \"before the first rep\" — prompt timing is a capture-surface concern | metrics.md teaches the collectible family (`?` reps, `:?` time, `?lb`/`?kg` load, `?m`/`?km`/`?mile` distance) with prescribed-vs-outcome rule; prompt timing not asserted |\n\n**Honesty rules carried into every chapter.** No invented HR/trend numbers; calculated metrics document only real prerequisites (e.g. `calc.readiness` publishes a value for a day only when soreness, sleep, and HRV were all captured that day — verified in `calc/seeds.ts`). Unlanded `calc.*` surfaces render a labeled \"proposed\" placeholder in the app; dashboards label sample answers as sample.\n\n---\n\n## 2. The eight proposed pages\n\n| # | File | Proposed title | Sticky stages | Absorbs |\n|---|---|---|---|---|\n| 1 | [start.md](/page/guide-start) | First Workout | editor → runtime | basics.md, syntax/README hub, core syntax tab pages, the printable cheat sheet |\n| 2 | [protocols.md](/page/guide-protocols) | Timers & Protocols | editor → runtime | protocols.md, all timer/protocol tab pages, the timer half of behaviors/timers.md |\n| 3 | [structure.md](/page/guide-structure) | Structure & Rounds | editor → runtime | structure.md, group tab pages, behaviors/rounds.md |\n| 4 | [metrics.md](/page/guide-metrics) | Metrics: Planned, Recorded, Calculated | editor → runtime (results focus) | custom-metrics.md, metric/calculated tab pages, behaviors/capture.md |\n| 5 | [clock.md](/page/guide-clock) | Run, Track & Capture (the Clock) | editor → runtime (runtime is the subject) | behaviors/README.md, the runtime halves of timers.md/capture.md |\n| 6 | [wql.md](/page/guide-wql) | Query Your Training (WQL) | editor → WQL table (data focus) | analytics/README, anatomy, filters, joins |\n| 7 | [dashboards.md](/page/guide-dashboards) | Dashboards & Cookbook | WQL table → dashboard (data focus) | analytics/cookbook, the query-block half of analytics/cheatsheet, the 6 seeded boards |\n| 8 | [sessions.md](/page/guide-sessions) | Dialects & Complex Sessions | editor → runtime | dialects.md, complex.md, dialect/complex tab pages |\n\nThe stages column is mirrored verbatim in each page's chapter banner. Chapters 1–3 and 8 **run and save**; chapter 5 documents the runtime itself; chapters 4, 6, 7 focus on **reading the data** runs produce. No chapter defines its own result policy — every run saves under the one contract in [§3](#run-contract).\n\n### Common page model\n\nEvery chapter uses the same skeleton: `# Title`, chapter banner (chapter number, **Sticky stages** line, replaced routes, homepage placements), the teaching sections with their existing anchors, exactly one `## Try it {#try-it}`, and a one-line chapter footer (`**Next:** … · [Overview](/page/guide-start)`). A Try it block has three labeled parts — **Run** (what to paste/press), **Observe** (what the runtime should show), **Result query** where the chapter reads data — and any caption buttons reuse existing action labels only (`Run`, preset names, `Cast`); no invented controls, no duplicated nav prose.\n\nEntry and deep-link anchors (used by the homepage and the prototype's learn links):\n\n| Page | Entry anchor | Try it | Key deep anchors |\n|---|---|---|---|\n| start.md | `#first-workout` | `#try-it` | `#reference`, `#measurements` |\n| protocols.md | `#countdown-countup` | `#try-it` | `#amrap`, `#required-rest` |\n| structure.md | `#rounds` | `#try-it` | `#named-sections`, `#rep-schemes` |\n| metrics.md | `#planned-vs-recorded` | `#try-it` | `#capture`, `#calculated`, `#session-rpe` |\n| clock.md | `#run-next` | `#try-it` | `#casting`, `#provenance`, `#pause-skip`, `#capture-prompts` |\n| wql.md | `#planes` | `#try-it` | `#aggregate`, `#filters`, `#sources`, `#windows`, `#joins` |\n| dashboards.md | `#note-frontmatter` | `#try-it` | `#widgets`, `#cookbook`, `#seeded-boards`, `#composer` |\n| sessions.md | `#intent` | `#try-it` | `#full-session` |\n\nReading order is the numbered order; 1–3 teach writing, 4–5 teach what running records, 6–7 teach querying, 8 composes everything.\n\n---\n\n## 3. Run & save contract — today vs proposed {#run-contract}\n\n> **Everything in §3–§5 is PROPOSED** for the homepage rebuild and these eight chapters. \"Today\" statements come from source review of the intake/recorder seams, run refs, reset paths, and scroll drivers — no runtime behavior has been exercised, and nothing here is implemented. The eight drafts above carry **no `route:` frontmatter** and no runtime wiring.\n\n### 3.1 One active workspace, immutable run archive\n\n**Today.** One active persisted Note per *surface*: `ensurePlaygroundEntry` (`createPlaygroundPage.ts`) creates once, then **updates in place** under reuseKey `'home'`, `'chapter-<id>'`, or `canvas:<route>` (`getCanvasNoteId`, `canvasUtils.ts`) — deliberately, so the library doesn't fill with duplicate experiment entries. Fresh notes are minted only by explicit New/Reset page buttons, ZIP import, templates, and journal→playground copies (each named via `formatPlaygroundTimestampId`). Reset is in-memory only: `HomeTour.startNewSession` and `useCanvasRuntime.closeRun` unmount without recording — in-flight results are silently dropped.\n\n**Proposed.** Keep exactly one active **editable workspace** per surface — the hero editor remains the single authoring surface, sticky through its stage. Nothing overwrites the draft in place, and nothing is ever activated in place of a new note: **every Run creates a fresh note, and every Reset creates a separate fresh unstarted draft snapshot — both retained** (the extra archive entries are intentional; the user explicitly asked for clones of both). Reset finalizes the active run partial, restores the template content in the editor, and mints a fresh draft snapshot (status `reset-unstarted`) as its archive record; the next Run still mints its own fresh note — a reset draft is never activated. Snapshot name = `<page label> — <section label> — <formatPlaygroundTimestampId>`: labels taken verbatim from the page H1 and the section heading the run launched from; section is optional (hero runs use the section label `Run`); run state (`running` / `completed` / `stopped` / `reset-unstarted`) is note metadata, not a second naming scheme. One workspace ≠ one saved note — **all session data is always recorded**: the archive retains every run and reset snapshot; retention is §3.6.\n\n### 3.2 Create before run; capture identity at start\n\n**Today.** Runs already persist before execution: `ensurePlaygroundEntry` completes before the runtime mounts, and save failure = toast + abort — no execution without a saved note. Run identity `{noteId, resultId, block}` is captured once at start and never re-derived (`activeRun.current`, `useCanvasRuntime.ts:56`; `playgroundEntryRef`/`playgroundBlockRef`, `HomeTour.tsx:602-616`). Recording resolves `segmentId = runBlock?.id ?? blockId`, `blockContentId = runBlock?.contentId`, origin `'playground'` for playground notes (`resultRecorder.ts:104-133`); segment **version** is deferred to the persistence adapter at write time.\n\n**Proposed.** Unchanged mechanics, new target: the captured triple points at the run's **snapshot** note — minted fresh at every Run (never a reused reset draft) — and the snapshot **source** is captured at start the same way — captured results can never retroactively bind to a later-edited draft. Editing the draft mid-run is a *try-edit*: finalize the active run partial, halt, let the editor change live; the edited content becomes a snapshot only at the next Run.\n\n### 3.3 Record once — partial or full — with failure guards\n\n**Today.** `playgroundRecorder.record` is the only result seam; natural completion and Stop both record (Stop sends `completed:false`). But `handleWorkoutComplete` never consumes the captured run — a second completion call would re-record the same resultId — and reset paths drop without recording. Other sourced races: two concurrent same-reuseKey `ensureEntry` calls can mint two same-slug notes; `completeWorkout` (workbench) is a non-atomic two-write pair whose result-write failure is only console-logged.\n\n**Proposed.** One finalization path shared by **natural completion, Stop, and metrics-stage arrival** (entering the metrics stage stops the runtime and finalizes). Record **exactly once** per run — partial (`completed:false`) or full — by consuming the captured run on record (clear `activeRun.current` / generation check, or an id-keyed guard in the recorder). Guards:\n\n- **Reset while running:** finalize the partial first and **retain the snapshot — always, even with zero outputs**, marked reset/unstarted, with no fabricated performance rows (a zero-output note honestly records \"attempted, nothing captured\"; nothing is silently dropped). Reset then mints a **separate fresh unstarted draft snapshot** as its archive record; the next Run still creates its own fresh note — prepared/reset drafts are never activated (explicit user policy: each run creates a new note; the extra archive entry is requested).\n- **Save failure:** persist-before-run stays; a failed save must **never clear recorded output nor auto-start a new run** — the run and its results stay, retry is explicit.\n- Per-run snapshots retire the reuseKey race surface entirely (each run mints its own note; no shared-slug ensure).\n- In the HTML prototype, session recording stays **page-memory only** and is labelled visibly as such; production records through the recorder seam.\n\n### 3.4 No fullscreen; stage-driven run\n\n**Today.** Run mounts a fullscreen overlay (`TourTimerScreen` tour-side, `FullscreenTimer` canvas-side) with autostart gated in `RuntimeTimerPanel` (`(autoStart||pendingStart)&&ready&&idle`).\n\n**Proposed.** Run scrolls to the **inline runtime stage** — no fullscreen. Arrival autostarts **once per run**. Captions offer existing actions only, as optional explicit buttons (`Run`, `Next`, `Stop`, `Cast` — real control labels/testids, no hidden auto-Next, no auto-cast; the autoplay entrance is user-scroll-triggered). A previous runtime resumes only via explicit **Run** (which always mints a new snapshot).\n\n### 3.5 Stage observers are idempotent\n\nBackward scroll never restarts a run nor replays a one-shot stage effect (renormalized progress + reached-once guards, the `useReachedOnce` pattern). Forward **fast scroll** that resolves straight to a later stage cannot launch the skipped runtime stage: the stage machine emits one discrete stage per frame (`resolveScrollStage`), so skipped stages' enter effects (autostart included) never fire. Every stage-enter effect runs once per run, not once per direction.\n\n### 3.6 Bounded seams and cleanup scope\n\nAll changes are bounded to existing seams — no new subsystem:\n\n1. **Snapshot naming** — a policy inside `createPlaygroundIntake` (the single note-minting seam); callers (`HomeTour`, `useCanvasRuntime`) keep their signatures. Explicit New/Reset page buttons keep today's `createPage` semantics.\n2. **Record-once** — a guard at the recorder or the run hooks (consume captured run / id-keyed guard), closing the double-record race before any autostart re-runs exist.\n3. **Partial finalize on reset** — a `completed:false` record at the two reset points (`HomeTour.startNewSession`, `useCanvasRuntime.closeRun`), retained even at zero outputs, then a separate fresh unstarted draft snapshot is minted (Run never activates it).\n4. **One active session owner** — generalize the `useCanvasRuntime` pattern instead of scattered refs (HomeTour refs vs canvas `activeRun` vs workbench store). **The workbench keeps its own multi-note session store** (`completeWorkout`, autosave, `resetStore`): it serves journal/workbench routes and promotion — one-active is a *playground-surface policy*, not a storage policy. Don't delete general workbench multi-note session support because the homepage is one-active.\n5. **Retention** — snapshot growth is handled by the existing promotion invariant (`movePlaygroundToJournal` — moved notes can never be hijacked by a later same-key ensure) and `find:note{source:playground}` scoping, not new deletion logic.\n\n**Cleanup scope when the collection is approved** (not before — nothing here routes the eight drafts or retires any `/guide/*` route):\n\n- Safe to retire with their routed parents: the 65 non-routed syntax tab-page fixtures and their ```scroll stage plumbing (they exist as scroll-stage sources for routed pages), the duplicate prototype HTML copy (keep one canonical), the `ProtoTimerMobile` throwaway (`?proto-timer`), the retired 720vh ```scroll:chapters spec in `canvas/home/README.md`.\n- **Out of scope:** workbench/journal session store and its wiring, collections/feeds/journal surfaces, promotion, chapter-run reuse — multi-note session support serves routes beyond the homepage and survives a one-active homepage.\n\n---\n\n## 4. Sticky stage flow (desktop & mobile)\n\nFour sticky stages in page order: **editor → runtime → WQL table → dashboard**. Desktop is native **sticky push-off**: each stage is a tall section whose card sticks at the nav offset (`STICKY_NAV_HEIGHT` = 104px, card `h-[calc(100vh-104px)]` — the `TourSectionRunway` pattern) and is pushed off by the next stage's sticky card, driven by the existing pure stage machine (`resolveScrollStage` with clamp01/renormalize over a capture-phase scroll listener). The hero editor is **one reused instance** sticking through stage 1. Run scrolls editor→runtime; **Stop (or metrics arrival) slides the metrics view in**; the **WQL table stage** sticks bound to the **current run's facts**, with caption query actions (real queries, `ParsedQueryChips` vocabulary) and a floating **\"Revert current session\"** that re-binds the table to the current run — discarding view-state (query tweaks, sample overlay) only; the **dashboard stage** sticks a board with **load buttons** for the seeded boards.\n\nMobile (≤1023px, `MOBILE_BREAKPOINT_PX`): **bounded sticky stage windows** — one stage card at a time in the reading zone (top 65px window, `MOBILE_STICKY_TOP`), captions **below** the card, card-visibility IntersectionObserver as the stage driver (the `TourMobileRunway` pattern). Same stage order, same run contract.\n\nReduced motion wins everywhere (`RunwayAdapter`: reduced > mobile > desktop): flat card stack, no push-off, no scroll scrub; stage arrival is visibility-based and still once-per-run.\n\nGuarantees on every form factor:\n\n- Runtime arrival autostarts once; backward scroll never restarts; fast scroll to a later stage cannot launch the skipped runtime (§3.5).\n- Caption actions are explicit buttons using existing labels; no hidden auto-Next/auto-cast.\n- Sample fallbacks are badged **sample**; sample datasets and dashboard/board edits never mutate saved session results; **Revert** restores view only.\n\n---\n\n## 5. System organization\n\n| Term | Purpose | Scope / storage |\n|---|---|---|\n| **Note** | the markdown document + identity (uuidv7 id, slug, sourceId, type) | one IndexedDB store (notes + results + attachments + analytics) |\n| **Page** | a note bound to a surface (routed guide page, playground home/canvas) | bindings via reuseKey / `getCanvasNoteId` |\n| **Block** | one addressable fenced unit in a note; the run target | Block Content Id = content hash, stable across reorders/clones |\n| **Effort** | named workout registry entry (e.g. *fran*) | content-plane query target; aggregates `by {effort}` |\n| **Session** | one recorded run | `{noteId, resultId, block}` triple; results join `Session.noteId` |\n| **Journal** | default dated training notebook (`notebook/journal`) | `notebook:journal` (`source:journal`); promotion target |\n| **Playground** | default experiment notebook (`notebook/playground`) | `notebook:playground` (`source:playground`); run snapshots archive here until promoted |\n| **Notebook** | user-created or seed-delivered notebook (`notebook/{slug}`) | `notebook:<id>` (`source:notebooks`); seed notebooks are read-only and clone into writable notebooks |\n| **Dashboard** | a note with `dashboard: true`; its query blocks render as widgets | vault (editable) vs prebuilt (read-only, clone) |\n\n**`notebook:` & `source:` scope.** Filter by `notebook:<id>` (`journal`, `playground`, `guides`, `crossfit-girls`, etc.) or plural `source:` values; omitting both searches all notes. Learning runs record in `notebook/playground` until promotion re-homes the note to `notebook/journal`.\n\n**Session vs template vs sample dataset vs revert.**\n\n- **Session** — immutable recorded facts from one run against its snapshot note.\n- **Template** — read-only source content (`sample-script.md`, `WORKOUT_PRESETS`, seeded boards). Running a template copies it into the active workspace/snapshot; **templates never mutate**.\n- **Sample dataset** — the SAMPLE fallback (`SAMPLE_HOME_ANALYTICS`, `SampleDataPrompt`) shown when the store has no facts; always badged sample; never persisted as your results.\n- **Revert** (\"Revert current session\") — discards view-state only (query tweaks, sample overlay) and re-binds the stage to the current run's recorded facts; never deletes saved sessions.\n\n---\n\n## 6. Homepage placements (existing slots only)\n\n| Homepage slot | Proposed links |\n|---|---|\n| Hero / editor-blank caption | \"Start Lesson 1\" → start.md#first-workout; add \"See the full syntax\" → start.md#reference |\n| 01 Write — editor-metrics caption | add \"What each line collects\" → metrics.md |\n| 01 Write — WORKOUT_PRESETS | each preset mirrors a protocols.md / structure.md example |\n| 02 Run — behaviors caption | point \"Read the behaviors explainer\" → clock.md |\n| 02 Run — timer-cast caption | clock.md#casting |\n| 03 Own — metrics-d (\"Measures ride along\") | add action → metrics.md |\n| 03 Own — metrics-c (\"Efforts × measures compound\") | add teaser → wql.md |\n| 04 Explore (currently no inline analytics links; `home:analytics_guide_opened` telemetry declared but never fired) | header actions: \"WQL in depth\" → wql.md, \"Copy-paste queries\" → dashboards.md#cookbook; wql-dashboard/wql-live captions → dashboards.md#seeded-boards |\n| CelebrationBridge (\"Now learn the language\") | render the 8-chapter map as the card row |\n| TourChapterPicker / TourLearnSection | CHAPTER_ROUTES gains the 8 files |\n| Footer \"Where to next?\" | add Learn column: start.md, wql.md, dashboards.md |\n| /ai-first | stays a standalone marketing page, linked from start.md (\"Generate with AI\") |\n\n## 7. Old route → new page/anchor map\n\nConcrete migration map for the 18 currently routed learning pages. Slugs follow the current routed files under `markdown/canvas/`; the eight targets are §2's files. **Both cheatsheets are absorbed into existing pages — there is no ninth page.** Nothing routes or redirects until the collection is approved; until then both trees coexist.\n\n| Old location (routed file) | New target |\n|---|---|\n| `syntax/README.md` (hub) | [start.md](/page/guide-start) header + [sessions.md#intent](/page/guide-sessions?h=intent) |\n| `syntax/basics.md` | [start.md#first-workout](/page/guide-start?h=first-workout) |\n| `syntax/protocols.md` | [protocols.md#countdown-countup](/page/guide-protocols?h=countdown-countup) |\n| `syntax/structure.md` | [structure.md#rounds](/page/guide-structure?h=rounds) |\n| `syntax/custom-metrics.md` | [metrics.md#planned-vs-recorded](/page/guide-metrics?h=planned-vs-recorded) |\n| `syntax/dialects.md` | [sessions.md#intent](/page/guide-sessions?h=intent) |\n| `syntax/complex.md` | [sessions.md#full-session](/page/guide-sessions?h=full-session) |\n| `syntax/cheatsheet.md` | [start.md#reference](/page/guide-start?h=reference) — **cheatsheet #1 absorbed** |\n| `behaviors/README.md` | [clock.md#run-next](/page/guide-clock?h=run-next) |\n| `behaviors/timers.md` | [protocols.md](/page/guide-protocols) (syntax forms) + [clock.md#pause-skip](/page/guide-clock?h=pause-skip) (runtime) |\n| `behaviors/rounds.md` | [structure.md#rep-schemes](/page/guide-structure?h=rep-schemes) + [clock.md#run-next](/page/guide-clock?h=run-next) |\n| `behaviors/capture.md` | [metrics.md#capture](/page/guide-metrics?h=capture) + [clock.md#capture-prompts](/page/guide-clock?h=capture-prompts) |\n| `analytics/README.md` | [wql.md#planes](/page/guide-wql?h=planes) |\n| `analytics/anatomy.md` | [wql.md#aggregate](/page/guide-wql?h=aggregate) |\n| `analytics/filters.md` | [wql.md#filters](/page/guide-wql?h=filters) · [#sources](/page/guide-wql?h=sources) · [#windows](/page/guide-wql?h=windows) |\n| `analytics/joins.md` | [wql.md#joins](/page/guide-wql?h=joins) |\n| `analytics/cookbook.md` | [dashboards.md#cookbook](/page/guide-dashboards?h=cookbook) |\n| `analytics/cheatsheet.md` | [wql.md#aggregate](/page/guide-wql?h=aggregate) tables + [dashboards.md#widgets](/page/guide-dashboards?h=widgets) — **cheatsheet #2 absorbed** |\n\nThe 65 non-routed tab-page fixtures follow their routed parents (their unique content is already merged — §8). `canvas/home/README.md` (homepage) and `canvas/ai-first/README.md` stay product pages, out of the collection.\n\n## 8. Source coverage\n\nEvery routed learning page (18) and every underlying non-routed lesson source (65 syntax tab pages + 2 home sources), mapped to its target. Merged duplicates list only once with their union.\n\n| Current source (routed unless marked) | Topics kept | → New page |\n|---|---|---|\n| syntax/README.md (hub) | core concepts map, dialect intro, new-note CTA | start.md (header/TOC), sessions.md#intent |\n| syntax/basics.md | fences, one-thing-per-line, indentation, measurements, `?lb`, effort words, actions, comments | start.md |\n| syntax/protocols.md + timers-rest, timer-modifiers, timers-1..5, longer-duration, mixed-timers, classic-amrap, time-cap, multiple-amrap-windows, basic-emom, longer-intervals, alternating-emom, protocols-1..5, custom-intervals, distance-intervals, supplemental-2 | countdown/countup/`^`/`*`/`:?`, H:MM:SS, AMRAP, caps, EMOM family, Tabata, intervals, rest | protocols.md |\n| syntax/structure.md + groups-1..4, named-groups, mixed-sections, multiple-sets | rounds, rep schemes, nesting, named sections, sets | structure.md |\n| syntax/custom-metrics.md + custom-metrics-1..5, calculated-metrics, custom-and-calculated-metrics, metrics-1..5, supplemental-4 | inline JSON, rpe/rir, multi-metric lines, calculate blocks, JSON rules, unknown loads `?lb`/`?kg` | metrics.md |\n| syntax/dialects.md + dialect-wod/log/plan, dialect-climb-bouldering/hangboard/sport | intent distinction, `log:climbing`, climbing signals | sessions.md |\n| syntax/complex.md + complex-nested-protocols, complex-full-session, complex-barbell-cycling, complex-partner-workout, complex-swimming | nested protocols, full session, EMOM chains, partner windows, swimming | sessions.md |\n| syntax/cheatsheet.md (routed) | one-page syntax | start.md#reference + per-page tables (no separate page) |\n| syntax/single-movement, core-rules, measurements, effort-notes, actions-comments, supplemental-1, supplemental-3, document-1..4, welcome-1 (home/), sample-script.md (home/) | smallest workout, three rules, headers/checklists/equipment-table document patterns, actions/comments | start.md |\n| behaviors/README.md | script→parse→compile→track, 3 behavior families, idioms | clock.md |\n| behaviors/timers.md | timer strategy selection, sound/pause/skip/required-rest | clock.md (+ protocols.md for syntax forms) |\n| behaviors/rounds.md | round behavior, rep math, supersets, interval groups, rounds↔timers | structure.md (+ clock.md) |\n| behaviors/capture.md | `:?`, `?lb`/`?kg`, session RPE, trendlines, fact origins | metrics.md (+ clock.md for prompt behavior) |\n| analytics/README.md | 3 WQL surfaces, 2 query planes, where-join | wql.md |\n| analytics/anatomy.md | aggregators, base/calc metrics, dimensions, rollups, find targets | wql.md |\n| analytics/filters.md | tag filters (negation/OR/substring), source filters, time windows, Library tri-state toggles | wql.md |\n| analytics/joins.md | where joins, Block Content Id mechanics | wql.md |\n| analytics/cookbook.md | 5 canonical queries, ```query embeds, dashboard notes, widget types/spans | dashboards.md (+ wql.md) |\n| analytics/cheatsheet.md | WQL one-pager | wql.md tables + dashboards.md#widgets (no separate page) |\n| markdown/dashboards/training-block-review.md | widget exemplars (see dashboards.md#seeded-boards) | dashboards.md |\n| markdown/dashboards/road-to-560-total.md | strength PR board exemplar | dashboards.md#seeded-boards |\n| markdown/dashboards/polarized-base-marathon.md | endurance polarization exemplar | dashboards.md#seeded-boards |\n| markdown/dashboards/finger-strength-v8.md | climbing board exemplar (wellness capture, `calc.mvcBw`) | dashboards.md#seeded-boards |\n| markdown/dashboards/benchmark-pr-board.md | benchmark table exemplar (`last:elapsed{tags:benchmark}`) | dashboards.md#seeded-boards |\n| markdown/dashboards/recovery-readiness.md | ```wellness capture + readiness exemplar | dashboards.md#seeded-boards (+ metrics.md#calculated) |\n\nNot counted as learning sources: `canvas/home/README.md` (product walkthrough — the homepage itself stays), `canvas/ai-first/README.md` (AI marketing, linked as an aside). Orphaned scroll plumbing (```scroll blocks, getTabExamples/getHomeExample, protocols-1's `(AMRAP)` spelling) is dropped, not migrated.\n\n## 9. Review method\n\nEach chapter ends with a **Try it** block: what to paste/press, what the runtime should show, and — for data chapters — the result query — a reviewer checklist, not a test report. Every syntax, behavior, and query claim in this collection comes from **source review only** (parser grammar, compiler metrics, WQL vocabulary/seeds, shipped fixtures). That was true at review time; since the cutover the chapters are production pages — the §3.1–§3.3 run/save behavior is implemented and exercised, while §3.4–§5 (stage flow) stay contract-only (see the status block).\n",
   "blocks": {
     "seed:markdown/canvas/guide/README.md:0": {
       "id": "seed:markdown/canvas/guide/README.md:0",
       "kind": "wod",
-      "from": 1554,
-      "to": 1609,
+      "from": 1564,
+      "to": 1619,
       "sourceRevision": 1,
       "version": 1,
       "dialect": "time"
@@ -19,14 +19,14 @@
       "blockId": "seed:markdown/canvas/guide/README.md:0",
       "blockVersion": 1,
       "sourceRevision": 1,
-      "from": 1554,
-      "to": 1609,
+      "from": 1564,
+      "to": 1619,
       "position": 0,
       "dataType": "wod",
       "blockContentId": "bc-86bf9888",
       "rawContent": "```time\n(3)\n  10 Kettlebell Swings 24kg\n  *:30 Rest\n```",
       "noteTitle": "Overview",
-      "createdAt": 1792883209000,
+      "createdAt": 1793044829000,
       "isStatic": true,
       "sourceId": "guides:guide/README",
       "sourcePath": "markdown/canvas/guide/README.md"
@@ -41,7 +41,7 @@
       "effortSlug": "kettlebell-swing",
       "isStatic": true,
       "sourcePath": "markdown/canvas/guide/README.md",
-      "createdAt": 1792883209000
+      "createdAt": 1793044829000
     }
   ],
   "blockEquipment": [
@@ -53,10 +53,10 @@
       "equipmentSlug": "kettlebell",
       "isStatic": true,
       "sourcePath": "markdown/canvas/guide/README.md",
-      "createdAt": 1792883209000
+      "createdAt": 1793044829000
     }
   ],
-  "commit": "30e43c771d712a7c09bd8056d48d096ca769e705",
+  "commit": "32bda10ffc56a61ebfca76ae94f51eddba304498",
   "uuid": "13ff30e0-4a1b-5ec4-ba59-28bdfd3c7ae5",
   "version": 1
 }

package/dist/web/playground/seed/core/markdown/canvas/guide/clock.json

@@ -1,11 +1,11 @@
 {
   "path": "markdown/canvas/guide/clock.md",
-  "content": "---\nsearch: hidden\ntemplate: canvas\nroute: /guide/clock\ntype: guide\ntitle: \"Run, Track & Capture (the Clock)\"\ndescription: \"Run the clock, advance with Next, pause, skip optional rest, and capture times mid-workout.\"\n---\n\n```chapter\nid: clock\ntitle: The Clock\nbadge: dumbbell\nquests: clock-run, clock-rest, clock-split\nsections: []\n```\n\n```quest\nid: clock-run\nlabel: Run the First Example\nvalidation:\n  type: run-started\n```\n\n```quest\nid: clock-rest\nlabel: Program a required rest\nvalidation:\n  type: contains-token\n  value: '*:'\n```\n\n```quest\nid: clock-split\nlabel: Add a cue card action\nvalidation:\n  type: contains-token\n  value: \"[\"\n```\n\n# Run, Track & Capture (the Clock) {sticky dark full-bleed}\n\nSyntax is the plan; **behaviors** are what the runtime does with it. When you press Run, the compiler turns every line into a timeline of behaviors and the clock plays them in order.\n\n```view\nname:    preview\nstate:   note\nsource:  wods/examples/home/sample-script.md\nruntime: in-memory\nlaunch:  host\nalign:   right\nwidth:   50%\n```\n\n## From script to clock {#run-next}\n\n1. **Script** — your Markdown note with fenced blocks.\n2. **Parse** — the grammar turns each line into statements of metrics.\n3. **Compile** — statements match to behaviors and lay out a timeline.\n4. **Track** — the clock steps through the timeline: counting, prompting, logging.\n\nThree behavior families cover every line:\n\n| Family | What it does | Example line | On the clock |\n|---|---|---|---|\n| **Timers** | counts up or down, repeats, rings | `20:00 AMRAP` | countdown + round counter |\n| **Rounds** | repeats, names, walks a rep scheme | `(21-15-9)` | three rounds with descending reps |\n| **Capture** | asks for actuals | `225lb ?lb`, `:?` | prompt when reached or finished |\n\n**Run** starts the current block; **Next** advances it and locks the elapsed time as a **split** — every click records where you are. Timers choose their strategy from the line ([chapter 2](/guide/protocols?h=countdown-countup)): duration → countdown, `^` or no duration → count-up stopwatch, `EMOM`/work-rest pair → interval, the word `Rest` → rest cue.\n\n## Pause, skip, and sound {#pause-skip}\n\n```button\nlabel:  Try it: Required rest\ntarget: preview\npipeline:\n  - set-source: wods/examples/syntax/timers-rest.md\n```\n\n- **Pause / resume** — countdowns stop and resume from the same elapsed time; interval timers keep round state, so an EMOM window never restarts from zero.\n- **Skip** — any timer without `*` can be skipped. `*:30 Rest` cannot; required timers force the full wait.\n- **Sound** — the runtime emits sound cues at timer start, the final ten seconds, and round transitions; audio surfaces subscribe to them.\n\nA movement line without a duration is not \"no timer\" — it's a count-up stopwatch tracking that block while you log reps.\n\nOn a stored note, **Stop** or **Exit** saves the captured partial run. Finishing the last block saves a completed run. The fullscreen results view shows **Saved ✓** only after the write succeeds. If saving fails, the clock keeps the run open; **Retry save** retries the same run without creating another session. Live \"results captured\" counts do not confirm a save.\n\n## Capture prompts {#capture-prompts}\n\nCollectible placeholders (`?lb`, `:?`, `?m`, `?`) mark the values the plan doesn't know; you supply the actuals during capture, and each lands in the fact store with its block. Session RPE is captured after the workout — skippable, and never blocking a save. Every recorded value carries a declared origin — see [Provenance](#provenance).\n\n## Casting {#casting}\n\nThe clock casts to a big screen: the timer surface — current block, round counter, countdown, cue cards — renders on a paired display while the controls stay on your device. Timers, cue cards (`[Change Plates]`), and round indicators all cross over; pauses on the device pause the cast.\n\n## Provenance {#provenance}\n\nEvery recorded fact carries its origin, which later tells analytics what to trust:\n\n| Origin | Producer | Example |\n|---|---|---|\n| `parser` / `compiler` | from your text | planned `24kg`, rep scheme values |\n| `runtime` | the clock | elapsed spans, splits, round counts |\n| `user` | you, at a prompt | captured loads, `:?` results, session RPE, wellness entries |\n| `analyzed` | the calc engine | `calc.*` values (estimated ones are marked `analyzed-estimated`) |\n\n## Try it {#try-it}\n\n**Run** — run the shared `(3) × 10 Kettlebell Swings 24kg / *:30 Rest` note and try each control: pause mid-round (elapsed freezes, resumes exactly), attempt to skip the `*` rest (refused), then `Next` through the last round — each split is locked with its timestamp. **Observe** — the review grid afterwards is just this provenance trail, organized. Runtime behavior is the subject here; run saving is the shared run contract.\n\n```button\nlabel:  Run\ntarget: preview\nopen:   view\npipeline:\n  - set-state: track\n```\n\n",
+  "content": "---\nsearch: hidden\ntemplate: canvas\nroute: /page/guide-clock\ntype: guide\ntitle: \"Run, Track & Capture (the Clock)\"\ndescription: \"Run the clock, advance with Next, pause, skip optional rest, and capture times mid-workout.\"\n---\n\n```chapter\nid: clock\ntitle: The Clock\nbadge: dumbbell\nquests: clock-run, clock-rest, clock-split\nsections: []\n```\n\n```quest\nid: clock-run\nlabel: Run the First Example\nvalidation:\n  type: run-started\n```\n\n```quest\nid: clock-rest\nlabel: Program a required rest\nvalidation:\n  type: contains-token\n  value: '*:'\n```\n\n```quest\nid: clock-split\nlabel: Add a cue card action\nvalidation:\n  type: contains-token\n  value: \"[\"\n```\n\n# Run, Track & Capture (the Clock) {sticky dark full-bleed}\n\nSyntax is the plan; **behaviors** are what the runtime does with it. When you press Run, the compiler turns every line into a timeline of behaviors and the clock plays them in order.\n\n```view\nname:    preview\nstate:   note\nsource:  wods/examples/home/sample-script.md\nruntime: in-memory\nlaunch:  host\nalign:   right\nwidth:   50%\n```\n\n## From script to clock {#run-next}\n\n1. **Script** — your Markdown note with fenced blocks.\n2. **Parse** — the grammar turns each line into statements of metrics.\n3. **Compile** — statements match to behaviors and lay out a timeline.\n4. **Track** — the clock steps through the timeline: counting, prompting, logging.\n\nThree behavior families cover every line:\n\n| Family | What it does | Example line | On the clock |\n|---|---|---|---|\n| **Timers** | counts up or down, repeats, rings | `20:00 AMRAP` | countdown + round counter |\n| **Rounds** | repeats, names, walks a rep scheme | `(21-15-9)` | three rounds with descending reps |\n| **Capture** | asks for actuals | `225lb ?lb`, `:?` | prompt when reached or finished |\n\n**Run** starts the current block; **Next** advances it and locks the elapsed time as a **split** — every click records where you are. Timers choose their strategy from the line ([chapter 2](/page/guide-protocols?h=countdown-countup)): duration → countdown, `^` or no duration → count-up stopwatch, `EMOM`/work-rest pair → interval, the word `Rest` → rest cue.\n\n## Pause, skip, and sound {#pause-skip}\n\n```button\nlabel:  Try it: Required rest\ntarget: preview\npipeline:\n  - set-source: wods/examples/syntax/timers-rest.md\n```\n\n- **Pause / resume** — countdowns stop and resume from the same elapsed time; interval timers keep round state, so an EMOM window never restarts from zero.\n- **Skip** — any timer without `*` can be skipped. `*:30 Rest` cannot; required timers force the full wait.\n- **Sound** — the runtime emits sound cues at timer start, the final ten seconds, and round transitions; audio surfaces subscribe to them.\n\nA movement line without a duration is not \"no timer\" — it's a count-up stopwatch tracking that block while you log reps.\n\nOn a stored note, **Stop** or **Exit** saves the captured partial run. Finishing the last block saves a completed run. The fullscreen results view shows **Saved ✓** only after the write succeeds. If saving fails, the clock keeps the run open; **Retry save** retries the same run without creating another session. Live \"results captured\" counts do not confirm a save.\n\n## Capture prompts {#capture-prompts}\n\nCollectible placeholders (`?lb`, `:?`, `?m`, `?`) mark the values the plan doesn't know; you supply the actuals during capture, and each lands in the fact store with its block. Session RPE is captured after the workout — skippable, and never blocking a save. Every recorded value carries a declared origin — see [Provenance](#provenance).\n\n## Casting {#casting}\n\nThe clock casts to a big screen: the timer surface — current block, round counter, countdown, cue cards — renders on a paired display while the controls stay on your device. Timers, cue cards (`[Change Plates]`), and round indicators all cross over; pauses on the device pause the cast.\n\n## Provenance {#provenance}\n\nEvery recorded fact carries its origin, which later tells analytics what to trust:\n\n| Origin | Producer | Example |\n|---|---|---|\n| `parser` / `compiler` | from your text | planned `24kg`, rep scheme values |\n| `runtime` | the clock | elapsed spans, splits, round counts |\n| `user` | you, at a prompt | captured loads, `:?` results, session RPE, wellness entries |\n| `analyzed` | the calc engine | `calc.*` values (estimated ones are marked `analyzed-estimated`) |\n\n## Try it {#try-it}\n\n**Run** — run the shared `(3) × 10 Kettlebell Swings 24kg / *:30 Rest` note and try each control: pause mid-round (elapsed freezes, resumes exactly), attempt to skip the `*` rest (refused), then `Next` through the last round — each split is locked with its timestamp. **Observe** — the review grid afterwards is just this provenance trail, organized. Runtime behavior is the subject here; run saving is the shared run contract.\n\n```button\nlabel:  Run\ntarget: preview\nopen:   view\npipeline:\n  - set-state: track\n```\n\n",
   "blocks": {},
   "blockIndex": [],
   "blockEfforts": [],
   "blockEquipment": [],
-  "commit": "30e43c771d712a7c09bd8056d48d096ca769e705",
+  "commit": "32bda10ffc56a61ebfca76ae94f51eddba304498",
   "uuid": "905f9253-fa20-58cb-8447-6cb534e34a09",
   "version": 1
 }

package/dist/web/playground/seed/core/markdown/canvas/guide/dashboards.json

@@ -1,39 +1,39 @@
 {
   "path": "markdown/canvas/guide/dashboards.md",
-  "content": "---\nsearch: hidden\ntemplate: canvas\nroute: /guide/dashboards\ntype: guide\ntitle: \"Dashboards & Cookbook\"\ndescription: \"Dashboards are notes with query widgets — frontmatter tokens, widget fences, and the composer.\"\n---\n\n# Dashboards & Cookbook {sticky dark full-bleed}\n\nA dashboard is **just a note**: mark it `dashboard: true`, and every in-note query block becomes a widget on one grid. The panel on the right has the real Training Block Review board loaded — its ```query blocks render live results right in the sandbox, and you can edit a query without touching the seeded board.\n\n```view\nname:    sandbox\nstate:   note\nsource:  dashboards/training-block-review.md\nruntime: in-memory\nlaunch:  host\nalign:   right\nwidth:   50%\n```\n\n## The note is the dashboard {#note-frontmatter}\n\nThe real board is already loaded in the sandbox.\n\n````markdown\n---\ntitle: Training Block Review\ndashboard: true\ndashboard.weeks: 16\n---\n\n## Avg TIS\nHow hard are sessions?\n\n```query:value\navg:tis{}\n```\n\n## Weekly tonnage\nIs volume rising?\n\n```query:timeseries-2\nsum:totalVolume{} by {week}\n```\n````\n\nThree conventions:\n\n- The **heading above a block** is the widget title.\n- The **paragraph directly above a block** is its question/subtitle.\n- `dashboard.weeks`, `dashboard.intensity: [low, moderate, high]`, or any `dashboard.<name>` value in frontmatter becomes a **token control** referenced as `$name` — `$weeks`, `$intensity`. List tokens render as segmented controls; unknown token references produce a visible refusal, never a silent blank.\n\n## Widget types and spans {#widgets}\n\n```button\nlabel:  Try it: Benchmark PR board\ntarget: sandbox\npipeline:\n  - set-source: dashboards/benchmark-pr-board.md\n```\n\nThe fence tag carries type and grid span (`query:<type>[-<1..4>|-full]`); a bare ```query defaults to `table`. Grid is 4 columns wide.\n\n| Tag | Widget |\n|---|---|\n| ```query | table (default) |\n| ```query:list / ```query:value | list / single big number |\n| ```query:timeseries / ```query:timeseries-2 / ```query:timeseries-4 | line over time, 1/2/4 columns |\n| ```query:bar / ```query:stacked-bar | bars / stacked bars |\n| ```query:toplist | ranked rows |\n| ```query:goal-rings / ```query:zone-distribution | progress rings / zone split |\n\nThe block body is **one WQL line** — everything from [the WQL chapter](/guide/wql?h=aggregate) works, including tokens:\n\n```query\nsum:sessionLoad{intensity:$intensity} by {week}\n```\n\nWellness data comes from a capture fence in any note — wellness keys are plain properties, one per line:\n\n```wellness\nsoreness: 7\nsleep: 7.5h\nhrv: 62\n```\n\nCapture those daily and boards like Recovery Readiness light up ([what feeds `calc.readiness`](/guide/metrics?h=calculated)).\n\n## Compose, inspect, clone {#composer}\n\n- **Vault boards** (`/dashboard/<your-note>`) are yours: add, edit, duplicate, reorder, and resize widgets in place; concurrent-edit guards refuse lost writes visibly.\n- **Prebuilt boards** are read-only, but **Inspect** shows any widget's query with a live preview, and **Clone to vault** copies the whole board into your journal to edit.\n- The widget composer is the same three steps for both: pick the **dataset** (a WQL line), the **calculation** (aggregator/metric/filters/window via the composer pills), and the **visualization** (type + span) — preview executes against your live journal with your range and kg/lb preferences.\n- Empty journal? Widgets stay honest with a sample-data prompt instead of fake numbers.\n\n## Cookbook {#cookbook}\n\nCopy-paste queries (paste into a ```query block, or straight into the Explorer):\n\n| Question | Query |\n|---|---|\n| Weekly strength volume | `sum:totalVolume{discipline:strength} by {week}` |\n| Top volume movements | `sum:totalVolume{} by {effort}` |\n| TIS trend | `avg:tis{} by {week}` |\n| Acute:chronic load | `avg:calc.acwr{}` |\n| Find benchmark notes | `:note{effort:fran,source:notebooks}` |\n| This week's swings volume | `sum:totalVolume{effort:kettlebell-swings} last 6w` |\n\nThe shared kettlebell note feeds the last row — [run it](/guide/start?h=try-it), and it appears among the sample rows.\n\n## Seeded boards {#seeded-boards}\n\nSix real dashboard notes ship with the app — open any of them, or Inspect → Clone:\n\n| Board | Built around |\n|---|---|\n| [Training Block Review](/d/training-block-review) | values (`avg:tis{}`, `sum:totalVolume{}`, `avg:calc.adherence{}`), weekly volume timeseries, volume by effort toplist, stacked load by intensity/week, distance by discipline |\n| [Road to 560 Total](/d/road-to-560-total) | strength PR progression toward a total |\n| [Polarized Base Marathon](/d/polarized-base-marathon) | endurance polarization (intensity split across weeks) |\n| [Finger Strength V8](/d/finger-strength-v8) | climbing: `calc.mvcBw` hang strength vs grade |\n| [Benchmark PR Board](/d/benchmark-pr-board) | `last:elapsed{tags:benchmark} by {effort}`, benchmark timeseries |\n| [Recovery Readiness](/d/recovery-readiness) | ```wellness capture → `last:calc.readiness{}`, HRV/monotony/ACWR trends |\n\n## Try it {#try-it}\n\n**Run** — the sandbox has the real board loaded: edit the *Weekly tonnage* query in the panel, change `by {week}` to `by {day}`, and watch the widget re-run — sandbox edits never touch the seeded board. Then open the live board: every widget executes against your journal, rows without facts badge as **sample answers until you have logged work of your own**. **Observe** — in the board view, inspect the *Weekly tonnage* widget and clone the board to keep an edit. Sample answers and board edits read saved sessions; they never rewrite them.\n\n```button\nlabel:  Open Training Block Review →\ntarget: preview\npipeline:\n  - navigate: /d/training-block-review\n```\n\n```button\nlabel:  Browse all dashboards →\ntarget: preview\npipeline:\n  - navigate: /dashboards\n```\n\n",
+  "content": "---\nsearch: hidden\ntemplate: canvas\nroute: /page/guide-dashboards\ntype: guide\ntitle: \"Dashboards & Cookbook\"\ndescription: \"Dashboards are notes with query widgets — frontmatter tokens, widget fences, and the composer.\"\n---\n\n# Dashboards & Cookbook {sticky dark full-bleed}\n\nA dashboard is **just a note**: mark it `dashboard: true`, and every in-note query block becomes a widget on one grid. The panel on the right has the real Training Block Review board loaded — its ```query blocks render live results right in the sandbox, and you can edit a query without touching the seeded board.\n\n```view\nname:    sandbox\nstate:   note\nsource:  dashboards/training-block-review.md\nruntime: in-memory\nlaunch:  host\nalign:   right\nwidth:   50%\n```\n\n## The note is the dashboard {#note-frontmatter}\n\nThe real board is already loaded in the sandbox.\n\n````markdown\n---\ntitle: Training Block Review\ndashboard: true\ndashboard.weeks: 16\n---\n\n## Avg TIS\nHow hard are sessions?\n\n```query:value\navg:tis{}\n```\n\n## Weekly tonnage\nIs volume rising?\n\n```query:timeseries-2\nsum:totalVolume{} by {week}\n```\n````\n\nThree conventions:\n\n- The **heading above a block** is the widget title.\n- The **paragraph directly above a block** is its question/subtitle.\n- `dashboard.weeks`, `dashboard.intensity: [low, moderate, high]`, or any `dashboard.<name>` value in frontmatter becomes a **token control** referenced as `$name` — `$weeks`, `$intensity`. List tokens render as segmented controls; unknown token references produce a visible refusal, never a silent blank.\n\n## Widget types and spans {#widgets}\n\n```button\nlabel:  Try it: Benchmark PR board\ntarget: sandbox\npipeline:\n  - set-source: dashboards/benchmark-pr-board.md\n```\n\nThe fence tag carries type and grid span (`query:<type>[-<1..4>|-full]`); a bare ```query defaults to `table`. Grid is 4 columns wide.\n\n| Tag | Widget |\n|---|---|\n| ```query | table (default) |\n| ```query:list / ```query:value | list / single big number |\n| ```query:timeseries / ```query:timeseries-2 / ```query:timeseries-4 | line over time, 1/2/4 columns |\n| ```query:bar / ```query:stacked-bar | bars / stacked bars |\n| ```query:toplist | ranked rows |\n| ```query:goal-rings / ```query:zone-distribution | progress rings / zone split |\n\nThe block body is **one WQL line** — everything from [the WQL chapter](/page/guide-wql?h=aggregate) works, including tokens:\n\n```query\nsum:sessionLoad{intensity:$intensity} by {week}\n```\n\nWellness data comes from a capture fence in any note — wellness keys are plain properties, one per line:\n\n```wellness\nsoreness: 7\nsleep: 7.5h\nhrv: 62\n```\n\nCapture those daily and boards like Recovery Readiness light up ([what feeds `calc.readiness`](/page/guide-metrics?h=calculated)).\n\n## Compose, inspect, clone {#composer}\n\n- **Vault boards** (`/dashboard/<your-note>`) are yours: add, edit, duplicate, reorder, and resize widgets in place; concurrent-edit guards refuse lost writes visibly.\n- **Prebuilt boards** are read-only, but **Inspect** shows any widget's query with a live preview, and **Clone to vault** copies the whole board into your journal to edit.\n- The widget composer is the same three steps for both: pick the **dataset** (a WQL line), the **calculation** (aggregator/metric/filters/window via the composer pills), and the **visualization** (type + span) — preview executes against your live journal with your range and kg/lb preferences.\n- Empty journal? Widgets stay honest with a sample-data prompt instead of fake numbers.\n\n## Cookbook {#cookbook}\n\nCopy-paste queries (paste into a ```query block, or straight into the Explorer):\n\n| Question | Query |\n|---|---|\n| Weekly strength volume | `sum:totalVolume{discipline:strength} by {week}` |\n| Top volume movements | `sum:totalVolume{} by {effort}` |\n| TIS trend | `avg:tis{} by {week}` |\n| Acute:chronic load | `avg:calc.acwr{}` |\n| Find benchmark notes | `:note{effort:fran,source:notebooks}` |\n| This week's swings volume | `sum:totalVolume{effort:kettlebell-swings} last 6w` |\n\nThe shared kettlebell note feeds the last row — [run it](/page/guide-start?h=try-it), and it appears among the sample rows.\n\n## Seeded boards {#seeded-boards}\n\nSix real dashboard notes ship with the app — open any of them, or Inspect → Clone:\n\n| Board | Built around |\n|---|---|\n| [Training Block Review](/d/training-block-review) | values (`avg:tis{}`, `sum:totalVolume{}`, `avg:calc.adherence{}`), weekly volume timeseries, volume by effort toplist, stacked load by intensity/week, distance by discipline |\n| [Road to 560 Total](/d/road-to-560-total) | strength PR progression toward a total |\n| [Polarized Base Marathon](/d/polarized-base-marathon) | endurance polarization (intensity split across weeks) |\n| [Finger Strength V8](/d/finger-strength-v8) | climbing: `calc.mvcBw` hang strength vs grade |\n| [Benchmark PR Board](/d/benchmark-pr-board) | `last:elapsed{tags:benchmark} by {effort}`, benchmark timeseries |\n| [Recovery Readiness](/d/recovery-readiness) | ```wellness capture → `last:calc.readiness{}`, HRV/monotony/ACWR trends |\n\n## Try it {#try-it}\n\n**Run** — the sandbox has the real board loaded: edit the *Weekly tonnage* query in the panel, change `by {week}` to `by {day}`, and watch the widget re-run — sandbox edits never touch the seeded board. Then open the live board: every widget executes against your journal, rows without facts badge as **sample answers until you have logged work of your own**. **Observe** — in the board view, inspect the *Weekly tonnage* widget and clone the board to keep an edit. Sample answers and board edits read saved sessions; they never rewrite them.\n\n```button\nlabel:  Open Training Block Review →\ntarget: preview\npipeline:\n  - navigate: /d/training-block-review\n```\n\n```button\nlabel:  Browse all dashboards →\ntarget: preview\npipeline:\n  - navigate: /dashboards\n```\n\n",
   "blocks": {
     "seed:markdown/canvas/guide/dashboards.md:0": {
       "id": "seed:markdown/canvas/guide/dashboards.md:0",
       "kind": "query",
-      "from": 2357,
-      "to": 2417,
+      "from": 2367,
+      "to": 2427,
       "sourceRevision": 1,
       "version": 1
     }
   },
   "blockIndex": [
     {
-      "id": "guide/dashboards:seed:markdown/canvas/guide/dashboards.md:0",
-      "noteId": "guide/dashboards",
+      "id": "page/guide-dashboards:seed:markdown/canvas/guide/dashboards.md:0",
+      "noteId": "page/guide-dashboards",
       "blockId": "seed:markdown/canvas/guide/dashboards.md:0",
       "blockVersion": 1,
       "sourceRevision": 1,
-      "from": 2357,
-      "to": 2417,
+      "from": 2367,
+      "to": 2427,
       "position": 0,
       "dataType": "query",
       "rawContent": "```query\nsum:sessionLoad{intensity:$intensity} by {week}\n```",
       "noteTitle": "Dashboards",
-      "createdAt": 1792883209000,
+      "createdAt": 1793044829000,
       "isStatic": true,
-      "sourceId": "guides:guide/dashboards",
+      "sourceId": "guides:page/guide-dashboards",
       "sourcePath": "markdown/canvas/guide/dashboards.md",
-      "routeId": "guide/dashboards"
+      "routeId": "page/guide-dashboards"
     }
   ],
   "blockEfforts": [],
   "blockEquipment": [],
-  "commit": "30e43c771d712a7c09bd8056d48d096ca769e705",
+  "commit": "32bda10ffc56a61ebfca76ae94f51eddba304498",
   "uuid": "5055fffb-2ed1-571f-aa72-3e1525d2e01f",
   "version": 1
 }