harmonics demo — the voice showcase (play / file / stream)

.devague/current

@@ -1 +1 @@
-harmonics-gives-an-agent-or-robot-its-own-non-spee
+harmonics-ships-a-demo-command-one-command-tours-t

.devague/current_plan

@@ -1 +1 @@
-harmonics-gives-an-agent-or-robot-its-own-non-spee
+harmonics-ships-a-demo-command-one-command-tours-t

.devague/frames/harmonics-ships-a-demo-command-one-command-tours-t.json

@@ -0,0 +1,229 @@
+{
+  "slug": "harmonics-ships-a-demo-command-one-command-tours-t",
+  "title": "harmonics ships a demo command: one command tours the whole agent voice \u2014 play it live, write a self-contained HTML gallery, or stream the clips into your own code",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-07-08T10:50:15Z",
+  "updated": "2026-07-08T10:55:36Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "harmonics ships a demo command: one command tours the whole agent voice \u2014 play it live, write a self-contained HTML gallery, or stream the clips into your own code",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "a single 'harmonics demo' with no args runs (dry-run, lists the tour), and each output mode is reachable by one documented flag (--play / --html / --wav / --out / --json)",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "developers integrating the harmonics voice, humans who want to hear it without hand-running a script, and other Python code embedding the tour",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "explain/README names all three audiences and each maps to a concrete mode: humans -> --play/--html, integrating developers -> showcase(), embedding code -> --json/showcase()",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "v0.5.0 can render the whole voice, but there is no single command that shows it off \u2014 the 24-clip live-test gallery was a hand-built browser script, not shippable",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "demo reproduces the live-test tour as a shipped command \u2014 the same clip families the hand-built gallery had, rendered by the real CLI, not a one-off script",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "after_state",
+      "text": "one command tours the voice across every design axis in three output modes \u2014 play live, write a file (HTML gallery / per-clip WAVs / concatenated WAV), or stream/import \u2014 dry-run by default",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h11",
+          "text": "one 'harmonics demo' invocation reaches every output mode via a single flag each and covers all axis groups; tests over the mode flags verify this",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "the voice is the product; a one-command showcase is how anyone discovers and enjoys it without wiring the pipeline themselves, and it doubles as a living end-to-end integration test",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h12",
+          "text": "running demo exercises the whole pipeline end-to-end (axes -> mapping/contour -> variation -> synth), so a break anywhere surfaces as a failing demo test",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "packaging over the existing pipeline (axes/mapping/identity/variation/inference/contour/stress + audio backend), not new synthesis \u2014 no new axes, motifs, or general audio-export tooling; the matrix is curated and fixed",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h13",
+          "text": "a test asserts demo introduces no new synthesis/axis code path \u2014 it renders only via the existing render_gesture/text_contour/render_wav and the axes vocabulary",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "harmonics demo with no flags dry-runs (lists clips + axes); --json and showcase() yield note sequences per clip offline with no audio device; --html writes a deterministic self-contained gallery; only --play needs a backend; explain + doctor stay green",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "tests assert: no-flag dry-run emits the clip list with axes; --json emits a note sequence per clip; importing harmonics.demo pulls in no audio backend (simpleaudio/sounddevice stay unimported)",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "three output modes: --play (live, sequential, needs a backend), file (--html gallery / --wav DIR per-clip / --out concatenated WAV), and stream/import (public showcase() + --json)",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "each mode is tested: --play is guarded by a lazy backend import raising the friendly CliError when absent; --html/--wav/--out write valid files with no audio device; showcase()/--json run with no device",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "a public harmonics.demo.showcase() yields one (label, axes, note_sequence, wav_bytes) per clip, deterministic and offline (WAV bytes rendered with no audio device), so other Python code can embed or stream the tour",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "showcase() is importable from harmonics.demo, yields a (label, axes, note_sequence, wav_bytes) tuple per clip, needs no audio device, and is deterministic \u2014 two calls produce byte-identical wav_bytes",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "the showcase matrix lives as data (a table of label + argv/axes) covering intents, identity across ~5 agents, confidence/urgency shading, say-tracks-words sentences, and stress \u2014 so it is easy to extend without touching rendering",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "the matrix is a module-level data table; a test enumerates it and asserts it covers all five content groups (intents, identity, shading, say, stress); adding a row requires no change to rendering code",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "requirement",
+      "text": "the pure text->notes path stays dependency-free and offline-testable: default dry-run lists clips+axes, --json/--html/--wav/--out all work with no audio device and --html is deterministic (snapshot-testable); only --play imports a backend",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "the full test path passes with audio backends uninstalled, and --html output is byte-deterministic across two runs (a snapshot test pins it)",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "requirement",
+      "text": "demo ships an explain catalog entry and keeps doctor / the afi rubric green (every verb resolves in the catalog; producing sound or files needs an explicit flag)",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "test_every_catalog_path_resolves covers the ('demo',) path and 'teken cli doctor . --strict' stays green",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "decision",
+      "text": "the verb is named 'demo' (showcase/tour are rejected alternatives), consistent with the harmonics command surface",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "requirement",
+      "text": "demo exposes a top-level --articulation {discrete,speechy,smooth,alien} flag that re-renders the entire tour in that voice (default smooth, note sequences unchanged), and the matrix gains a dedicated 'articulations' group rendering one sentence in all four styles back-to-back",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "a test asserts --articulation re-renders every clip through the chosen synth style with note sequences unchanged, and the 'articulations' matrix group yields exactly the four styles (discrete/speechy/smooth/alien) for one sentence",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": []
+}