@alexkroman1/aai-cli 6.3.0 → 6.4.0

package/dist/scaffold/package.json

@@ -13,8 +13,8 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^6.3.0",
-    "@alexkroman1/aai-ui": "^6.3.0",
+    "@alexkroman1/aai": "^6.4.0",
+    "@alexkroman1/aai-ui": "^6.4.0",
     "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -23,7 +23,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^6.3.0",
+    "@alexkroman1/aai-cli": "^6.4.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

package/dist/templates/transcription-workflow/agent.test.ts

@@ -18,10 +18,14 @@
  */
 
 import { stubStepFetch, stubUploads } from "@alexkroman1/aai/testing";
+import { readUpload } from "@alexkroman1/aai/utils";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-import { RetryableError } from "workflow";
+import { FatalError, RetryableError } from "workflow";
 import { z } from "zod";
-import agentDef, { transcribe } from "./agent.ts";
+import agentDef, { transcribe, transcribeBatch, transcribeStream } from "./agent.ts";
+import { createJob, pollTranscript, readTranscript, uploadToProvider } from "./workflows/batch.ts";
+import { planStreamed, probeUpload } from "./workflows/stream.ts";
+
 import {
   clock,
   mergeTranscript,
@@ -49,6 +53,16 @@ const SYNC_ORIGIN = "https://sync.assemblyai.com";
 /** The id every spec below uploads under. */
 const UPLOAD_ID = "upl_test";
 
+/**
+ * A fixed run-start epoch, so `elapsedMs` is assertable at all.
+ *
+ * `startClock` is a step in production; a spec supplies the value directly, which is
+ * the point of threading it as an argument rather than reading a clock inside the
+ * merge — the duration is then a function of journaled values and not of how long the
+ * test took.
+ */
+const STARTED_AT = 1_000_000;
+
 /**
  * Publish one in-memory upload, the way `createServer` publishes a real store.
  *
@@ -109,10 +123,28 @@ function wavFile(
   return head;
 }
 
-describe("the agent declares its workflow and nothing else", () => {
-  test("under the name the REST route resolves it by", () => {
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["transcribe"]);
+describe("the agent declares its three workflows and nothing else", () => {
+  test("under the names the REST route resolves them by", () => {
+    // The page starts a run by these strings, so a rename is a runtime 400 rather
+    // than a compile error — which is what makes pinning them worth a test.
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual([
+      "transcribe",
+      "transcribeStream",
+      "transcribeBatch",
+    ]);
     expect(agentDef.workflows?.transcribe).toBe(transcribe);
+    expect(agentDef.workflows?.transcribeStream).toBe(transcribeStream);
+    expect(agentDef.workflows?.transcribeBatch).toBe(transcribeBatch);
+  });
+
+  test("all three take `recording` as an UPLOAD, which is what makes one picker serve them", () => {
+    // There is no second kind of declaration: `recording` carries an upload id in
+    // every flow, and the streaming one differs only in that the CLIENT chose the id
+    // and PUT the file to it. A divergence here would mean the form had to ask a
+    // person how the bytes should travel.
+    for (const flow of [transcribe, transcribeStream, transcribeBatch]) {
+      expect(flow.uploads).toEqual(["recording"]);
+    }
   });
 
   test("with no tools, because the interface is the page and the API", () => {
@@ -538,10 +570,15 @@ describe("transcribeSegment", () => {
 describe("mergeTranscript", () => {
   test("stitches the segments in index order, whatever order they arrive in", async () => {
     publishRecording(new Uint8Array(1));
-    const merged = await mergeTranscript(UPLOAD_ID, 12_000, [
-      { index: 1, text: "on Friday if the tests pass" },
-      { index: 0, text: "we ship on Friday" },
-    ]);
+    const merged = await mergeTranscript(
+      UPLOAD_ID,
+      12_000,
+      [
+        { index: 1, text: "on Friday if the tests pass" },
+        { index: 0, text: "we ship on Friday" },
+      ],
+      STARTED_AT,
+    );
     expect(merged.transcript).toBe("we ship on Friday if the tests pass");
     expect(merged.words).toBe(8);
     expect(merged).toMatchObject({ segments: 2, durationMs: 12_000 });
@@ -549,7 +586,7 @@ describe("mergeTranscript", () => {
 
   test("names the FILE it transcribed, not the id the run carried", async () => {
     publishRecording(new Uint8Array(1), "standup.wav");
-    const merged = await mergeTranscript(UPLOAD_ID, 1000, [{ index: 0, text: "hi" }]);
+    const merged = await mergeTranscript(UPLOAD_ID, 1000, [{ index: 0, text: "hi" }], STARTED_AT);
     expect(merged.source).toBe("standup.wav");
   });
 });
@@ -561,3 +598,207 @@ function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
   out.set(b, a.length);
   return out;
 }
+
+/**
+ * The STREAMING flow's own steps.
+ *
+ * Same honest line as the classic half above: the steps are driven directly and the
+ * body is not, because imported through vitest a `"use step"` function is an ordinary
+ * async function. Almost nothing here is new — the transcribing and the merging are
+ * `transcribe.ts`'s own steps, called unchanged — so what is worth asserting is the
+ * two things this flow adds: reading how far the upload has got, and planning from a
+ * header while most of the file is still missing.
+ */
+describe("the streaming flow", () => {
+  const FORMAT: WavFormat = { ...MONO_16K, dataStart: 44, dataEnd: 44 + 320_000 };
+
+  /** Publish a partially-arrived upload: `stored` bytes of a `declared`-byte file. */
+  function publishPartial(stored: number, declared: number, complete = false) {
+    const bytes = new Uint8Array(44 + stored);
+    bytes.set(wavFile(MONO_16K, declared), 0);
+    restore = stubUploads({
+      [UPLOAD_ID]: { bytes, name: "standup.wav", type: "audio/wav", complete },
+    });
+  }
+
+  test("probeUpload reports what has ARRIVED and whether that is all", async () => {
+    publishPartial(1000, 320_000);
+    // The poll the body runs. `complete` is separate from `size` because a size that
+    // stopped growing is not a claim that the file is finished.
+    await expect(probeUpload(UPLOAD_ID)).resolves.toEqual({ size: 44 + 1000, complete: false });
+  });
+
+  test("probeUpload reports complete once it is", async () => {
+    publishPartial(320_000, 320_000, true);
+    await expect(probeUpload(UPLOAD_ID)).resolves.toMatchObject({ complete: true });
+  });
+
+  test("planStreamed plans the WHOLE recording from a header that arrived alone", async () => {
+    // The one real difference from `splitRecording`: only 1000 bytes of audio are
+    // stored, and the plan still covers the 320,000 the header declares. Planning
+    // from what has arrived would fan out over a fraction of the recording and report
+    // success — which is the failure this argument exists to prevent.
+    publishPartial(1000, 320_000);
+    const plan = await planStreamed(UPLOAD_ID);
+    expect(plan.format.dataEnd).toBe(44 + 320_000);
+    expect(plan.segments.at(-1)?.end).toBe(44 + 320_000);
+    expect(plan.segments.length).toBe(planSegments(FORMAT).length);
+  });
+
+  test("planStreamed refuses a WAV that declares no length, naming the other flow", async () => {
+    // `0` means "unknown", and there is nothing to compute a segment list from until
+    // the file has finished — which is exactly what `transcribe` is for.
+    const bytes = new Uint8Array(44 + 100);
+    bytes.set(wavFile(MONO_16K, 100, { declaredDataSize: 0 }), 0);
+    restore = stubUploads({ [UPLOAD_ID]: { bytes, complete: false } });
+    await expect(planStreamed(UPLOAD_ID)).rejects.toThrow(/declares no data length/);
+  });
+
+  test("planStreamed refuses a file that is not a WAV, terminally", async () => {
+    restore = stubUploads({ [UPLOAD_ID]: { bytes: new Uint8Array(2000), complete: false } });
+    // Fatal, not retryable: three more attempts read the same bytes.
+    await expect(planStreamed(UPLOAD_ID)).rejects.toBeInstanceOf(FatalError);
+  });
+
+  test("a segment reads SHORT rather than failing when its bytes have not landed", async () => {
+    // The property the whole flow rests on, and it predates streaming: `readUpload`
+    // clamps its window to what is stored. So a body that asks slightly early gets
+    // what exists — which is why the body checks `end <= size` and can trust the
+    // clamp for the final segment of a file that came up short.
+    publishPartial(1000, 320_000);
+    const slice = await readUpload(UPLOAD_ID, { start: 44, end: 44 + 320_000 });
+    expect(slice.bytes.length).toBe(1000);
+    expect(slice.end).toBe(44 + 1000);
+  });
+});
+
+/**
+ * The ASYNC flow's steps.
+ *
+ * Driven against a stubbed `stepFetch`, like the sync flow's — and note what that
+ * makes assertable: the three calls this flow makes are the whole of it, so the
+ * assertions are about the CONTRACT with the provider (an id survives, a failed job
+ * is terminal, the file is streamed rather than buffered) rather than about
+ * arithmetic this flow does not do.
+ */
+describe("the async flow", () => {
+  beforeEach(() => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  const batchStubs: (() => void)[] = [];
+  afterEach(() => {
+    for (const undo of batchStubs.splice(0)) undo();
+  });
+
+  /** Answer the async API, recording what was sent. */
+  function stubBatch(answer: (url: string) => { status?: number; body?: unknown }) {
+    const stub = stubStepFetch((req) => answer(req.url));
+    batchStubs.push(stub.restore);
+    return stub.calls;
+  }
+
+  test("uploadToProvider streams the file and answers with the provider's URL", async () => {
+    publishRecording(new Uint8Array(5000), "standup.wav");
+    const calls = stubBatch(() => ({ body: { upload_url: "https://cdn.example/abc" } }));
+    await expect(uploadToProvider(UPLOAD_ID)).resolves.toEqual({
+      audioUrl: "https://cdn.example/abc",
+    });
+    expect(calls.map((one) => one.url)).toEqual(["https://api.assemblyai.com/v2/upload"]);
+  });
+
+  test("the file is STREAMED, so a step never holds a whole recording", async () => {
+    publishRecording(new Uint8Array(5000), "standup.wav");
+    const calls = stubBatch(() => ({ body: { upload_url: "https://cdn.example/abc" } }));
+    await uploadToProvider(UPLOAD_ID);
+    // `stubStepFetch` drains a streaming body into bytes, so what this asserts is that
+    // every byte went out — the streaming is what keeps a gigabyte off the heap, and
+    // the bytes arriving intact is what says the windowing is right.
+    const sent = calls[0]?.body;
+    expect(sent).toBeInstanceOf(Uint8Array);
+    expect(sent instanceof Uint8Array ? sent.length : -1).toBe(5000);
+  });
+
+  test("the upload is a SEPARATE step, so a failed submit does not re-send the file", async () => {
+    // Found by running it: as one step, a 400 on the create call retried the whole
+    // thing five times and re-uploaded 24 MB on each attempt. The split is what makes
+    // a retry of the cheap half cost the cheap half.
+    publishRecording(new Uint8Array(5000));
+    const calls = stubBatch(() => ({ status: 400, body: { error: "bad field" } }));
+    await expect(createJob("https://cdn.example/abc")).rejects.toBeInstanceOf(FatalError);
+    // One call, and it is not the upload.
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.url).toBe("https://api.assemblyai.com/v2/transcript");
+  });
+
+  test("createJob asks for `speech_models`, plural — the singular field is a 400", async () => {
+    publishRecording(new Uint8Array(10));
+    const calls = stubBatch(() => ({ body: { id: "tr_1" } }));
+    await expect(createJob("https://cdn.example/abc")).resolves.toEqual({ id: "tr_1" });
+    const sent = JSON.parse(String(calls[0]?.body)) as Record<string, unknown>;
+    // The async API deprecated `speech_model` and answers 400 for any current model
+    // name passed to it — which is how the first live run of this flow failed. The
+    // STREAMING API still uses the singular field, so neither is "the" spelling.
+    expect(sent).toMatchObject({ speech_models: ["universal-3-5-pro"] });
+    expect(sent.speech_model).toBeUndefined();
+  });
+
+  test("a job the provider gave up on is TERMINAL, not polled forever", async () => {
+    publishRecording(new Uint8Array(10));
+    stubBatch(() => ({ body: { status: "error", error: "audio too quiet" } }));
+    // The provider has decided; no number of polls changes it, so this must not come
+    // back as "not done yet".
+    await expect(pollTranscript("tr_1")).rejects.toBeInstanceOf(FatalError);
+  });
+
+  test("pollTranscript answers `done` on completed and not before", async () => {
+    publishRecording(new Uint8Array(10));
+    stubBatch(() => ({ body: { status: "processing" } }));
+    await expect(pollTranscript("tr_1")).resolves.toEqual({ done: false, status: "processing" });
+  });
+
+  test("an unknown status is NOT done, so a new one cannot end a run early", async () => {
+    publishRecording(new Uint8Array(10));
+    stubBatch(() => ({ body: {} }));
+    await expect(pollTranscript("tr_1")).resolves.toMatchObject({ done: false });
+  });
+
+  test("readTranscript reports the provider's own duration and ONE segment", async () => {
+    publishRecording(new Uint8Array(10), "standup.wav");
+    stubBatch(() => ({ body: { text: "  hello there  ", audio_duration: 12.5 } }));
+    await expect(readTranscript(UPLOAD_ID, "tr_1", STARTED_AT)).resolves.toMatchObject({
+      source: "standup.wav",
+      // Not a fudge: the async API transcribed the recording in one piece, which is
+      // the difference this flow is here to show.
+      segments: 1,
+      durationMs: 12_500,
+      words: 2,
+      transcript: "hello there",
+    });
+  });
+
+  test("a rate limit is RETRYABLE, so a busy minute does not fail the run", async () => {
+    publishRecording(new Uint8Array(10));
+    stubBatch(() => ({ status: 429, body: { error: "slow down" } }));
+    await expect(pollTranscript("tr_1")).rejects.toBeInstanceOf(RetryableError);
+  });
+
+  test("all three flows report the same SHAPE, which is what lets one page render any", async () => {
+    publishRecording(new Uint8Array(10), "standup.wav");
+    stubBatch(() => ({ body: { text: "hi", audio_duration: 1 } }));
+    const batched = await readTranscript(UPLOAD_ID, "tr_1", STARTED_AT);
+    // One key set, so the page's summary line renders every flow's output. A field on
+    // one flow and not the others is a panel that shows it for some runs and not
+    // others, with nothing saying why.
+    expect(Object.keys(batched).sort()).toEqual([
+      "durationMs",
+      "elapsedMs",
+      "segments",
+      "source",
+      "transcript",
+      "words",
+    ]);
+    // And the wall clock really is measured from what it was handed.
+    expect(batched.elapsedMs).toBeGreaterThan(0);
+  });
+});

package/dist/templates/transcription-workflow/agent.ts

@@ -38,6 +38,25 @@
  * None of that is this template's code. Uploads are the SDK's, for the reason
  * every workflow app hits this wall on its first form.
  *
+ * ## Three flows over one job, so they can be compared
+ *
+ * | | `transcribe` | `transcribeStream` | `transcribeBatch` |
+ * | --- | --- | --- | --- |
+ * | provider API | sync | sync | **async** |
+ * | run starts | after the upload | **before** it | after the upload |
+ * | client sends | `POST /uploads` | `PUT /uploads/<id>` | `POST /uploads` |
+ * | shape | plan, fan out, merge | poll, fan out, merge | submit, poll, read |
+ * | client hook | `useWorkflowSubmit` | `useWorkflowStream` | `useWorkflowSubmit` |
+ * | accepts | linear-PCM WAV | linear-PCM WAV | **any audio** |
+ * | segments | 7 for 10 minutes | 7 | **1** |
+ *
+ * The first two are the same fan-out arranged two ways, and the difference between
+ * them is measured rather than claimed — see `workflows/stream.ts`, which records
+ * what overlapping the upload actually saves (bounded by the transcription, not
+ * proportional to the file). The third does none of that work and is what a real
+ * product would probably ship; it is here because a template that only showed the
+ * clever option would be hiding the simple one.
+ *
  * ## It is scriptable, which is the other half of having an API
  *
  * The page is one caller. Two requests do the same thing from a shell — upload,
@@ -52,10 +71,17 @@
  *   -d "{\"workflow\":\"transcribe\",\"wait\":30000,\"input\":{
  *        \"recording\":\"$ID\"}}"
  * ```
+ *
+ * The streaming flow is the same three verbs in a different order — start, then
+ * upload parts, then seal — and the page renders the whole recipe under "Use the
+ * API without this page". `AGENT.md` in this template is the copy a script author
+ * reads.
  */
 
 import { workflow, workflowApp } from "@alexkroman1/aai";
 import { z } from "zod";
+import { transcribeBatchFlow } from "./workflows/batch.ts";
+import { transcribeStreamFlow } from "./workflows/stream.ts";
 import { transcribeFlow } from "./workflows/transcribe.ts";
 
 /**
@@ -83,9 +109,58 @@ export const transcribe = workflow({
   run: transcribeFlow,
 });
 
+/**
+ * The same work, started BEFORE the recording has finished uploading.
+ *
+ * Declared beside `transcribe` rather than replacing it, because the two are worth
+ * reading against each other: this one shows the transcript growing while the bytes
+ * are still moving, and the other is the shape to understand first — three steps in a
+ * straight line, with no polling.
+ *
+ * **The declaration is IDENTICAL, including `uploads`.** That is the point of the
+ * mechanism: `recording` carries an upload id either way, and what differs is only
+ * that the client CHOSE the id and `PUT` the file to it, so the id was valid before
+ * the bytes were. `useWorkflowStream` is the client half; `workflows/stream.ts` is
+ * the body, and it reuses this file's own `transcribeSegment` unchanged.
+ */
+export const transcribeStream = workflow({
+  description: "Transcribe a recording while it is still uploading",
+  input: z.object({
+    recording: z.string().describe("A linear-PCM WAV recording (16-bit or 8-bit, any rate)"),
+  }),
+  uploads: ["recording"],
+  run: transcribeStreamFlow,
+});
+
+/**
+ * The same work again, handed to AssemblyAI's ASYNC API instead of cut up.
+ *
+ * The third desk, and the one a real product would probably ship. Both flows above
+ * exist because the SYNC endpoint answers inside the request and pays for it with a
+ * 120-second, 40 MB cap — so a long recording has to be planned, fanned out and
+ * stitched. The async API has no cap: submit a job, poll, read the text.
+ *
+ * It is declared here so the page can run all three over the same file and show what
+ * each costs. What this one gives up is the inside of the work — the latency is the
+ * provider's queue rather than a fan-out you can tune — and what it gains is
+ * everything the other two spend code on, plus formats they refuse: the async API
+ * takes compressed audio, so an m4a off a phone works where a WAV-only cut does not.
+ *
+ * `workflows/batch.ts` carries the rest, including why the wait is what makes this a
+ * workflow rather than a request.
+ */
+export const transcribeBatch = workflow({
+  description: "Transcribe a recording through the async API, polling until it is done",
+  input: z.object({
+    recording: z.string().describe("Any recording the async API accepts — WAV, MP3, M4A"),
+  }),
+  uploads: ["recording"],
+  run: transcribeBatchFlow,
+});
+
 export default workflowApp({
   name: "Transcription Desk",
-  workflows: { transcribe },
+  workflows: { transcribe, transcribeStream, transcribeBatch },
   // Checked at deploy time, so a missing key is a warning naming it rather than
   // a run that fails on its second step.
   requiredEnv: ["ASSEMBLYAI_API_KEY"],

package/dist/templates/transcription-workflow/api-help.tsx

@@ -0,0 +1,206 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * "You do not need this page" — the HTTP API, on the page.
+ *
+ * A workflow app's whole surface is `GET|POST /workflows/*`, and the page is one
+ * caller of it. That is the most useful thing about the shape and the least
+ * discoverable: nothing in a form suggests that the same work is three `curl`
+ * calls, that a run id is the entire handle (no session, no cookie), or that a
+ * transcript can be collected days later from another machine. So the recipes are
+ * rendered where somebody is already looking, rather than left in a README they
+ * would have to know exists.
+ *
+ * ## It links to the LIVE listing
+ *
+ * `GET /workflows` serves each workflow's name, description and input schema — the
+ * same JSON `<WorkflowFields>` renders this form from. So the link is not
+ * documentation about the API, it is the API answering for itself, on this
+ * deployment, at this version. A reader who wants the schema gets the real one;
+ * a reader whose agent is behind `AAI_WORKFLOW_API_TOKEN` gets a 401, which is
+ * also the truth.
+ *
+ * ## The three recipes are the three flows
+ *
+ * The first two differ only in who names the upload — which is the whole of what
+ * lets one of them start before the bytes are in — and the third does none of that
+ * work at all. Showing them side by side is the clearest statement of the trade
+ * available, and cheaper than the prose that would otherwise have to make it.
+ *
+ * They are also KEPT HONEST by being runnable: every one of these was executed
+ * against a real dev server, which is how two bugs in the streaming path were
+ * found (a missing wake after the upload, and a poll that slept on a stale view).
+ */
+
+/** @jsxImportSource react */
+
+import type { ReactNode } from "react";
+
+/** The API root, relative to wherever this page is served from. */
+const API = "workflows";
+
+/**
+ * One shell recipe, with a heading and a note.
+ *
+ * Rendered in a `<pre>` rather than assembled from styled spans: it exists to be
+ * SELECTED and pasted, and any markup inside the block is markup a copy picks up.
+ */
+function Recipe({
+  title,
+  note,
+  script,
+}: {
+  title: string;
+  note: string;
+  script: string;
+}): ReactNode {
+  return (
+    <section className="flex flex-col gap-2">
+      <h4 className="text-xs font-medium uppercase tracking-[1.2px]">{title}</h4>
+      <p className="text-xs opacity-70">{note}</p>
+      <pre className="overflow-x-auto rounded-md border p-3 text-xs leading-relaxed">{script}</pre>
+    </section>
+  );
+}
+
+/** Store the whole file, then start a run on its id. */
+const CLASSIC = `# 1. store the recording. Answers 201 once the LAST byte is in, which is why
+#    this shape cannot start the run any earlier.
+ID=$(curl -s -X POST "$AGENT/workflows/uploads?name=standup.wav" \
+  -H 'content-type: audio/wav' --data-binary @standup.wav | jq -r .id)
+
+# 2. run it. \`wait\` holds the request open for up to 60s; drop it to get
+#    { runId } straight back and poll instead.
+curl -s -X POST "$AGENT/workflows/runs" \
+  -H 'content-type: application/json' \
+  -d "{\\"workflow\\":\\"transcribe\\",\\"wait\\":60000,
+       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r '.run.output.transcript'`;
+
+/** Start the run first, then stream the file to the id it is watching. */
+const STREAMING = `# No splitting, no ffmpeg — the file goes in ONE request. The only difference
+# from the recipe above is that YOU pick the upload id, so it is already valid
+# when the run starts and the run reads the bytes as they land.
+
+# 1. pick an id and start the run on it. Nothing has been uploaded yet.
+ID=$(openssl rand -hex 16)
+RUN=$(curl -s -X POST "$AGENT/workflows/runs" \
+  -H 'content-type: application/json' \
+  -d "{\\"workflow\\":\\"transcribeStream\\",
+       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r .runId)
+
+# 2. PUT the whole file. The upload record exists from the first byte with
+#    complete:false, and its size grows — which is what the run polls.
+curl -s -X PUT "$AGENT/workflows/uploads/$ID?name=standup.wav" \
+  -H 'content-type: audio/wav' --data-binary @standup.wav | jq -c '{size, complete}'
+
+# 3. wake it. The run sleeps between polls, so without this it notices the file
+#    is finished up to one poll interval late — every time.
+curl -s -X POST "$AGENT/workflows/runs/$RUN/wake" > /dev/null
+
+# 4. collect it whenever — a run id is the whole handle.
+curl -s "$AGENT/workflows/runs/$RUN?wait=60000" | jq -r '.run.output.transcript'
+
+# While it runs, from any other shell:
+#   curl -s "$AGENT/workflows/uploads/$ID/info"        # how much has arrived
+#   curl -sN "$AGENT/workflows/runs/$RUN/stream"       # what the run is saying`;
+
+/** Hand the whole thing to the async API. */
+const BATCH = `# The same two requests as the first recipe — only the workflow name differs.
+# No cutting happens anywhere: the run uploads your file to the async API,
+# polls the job, and reads the text. It also accepts mp3 and m4a, which the
+# two sync flows refuse.
+ID=$(curl -s -X POST "$AGENT/workflows/uploads?name=standup.m4a" \
+  -H 'content-type: audio/mp4' --data-binary @standup.m4a | jq -r .id)
+
+# No \`wait\` here: an async job takes minutes, well past the 60s ceiling a
+# synchronous read can hold. Start it, then follow the run.
+RUN=$(curl -s -X POST "$AGENT/workflows/runs" \
+  -H 'content-type: application/json' \
+  -d "{\\"workflow\\":\\"transcribeBatch\\",
+       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r .runId)
+
+curl -sN "$AGENT/workflows/runs/$RUN/events"          # status, as it changes
+curl -s "$AGENT/workflows/runs/$RUN" | jq -r '.output.transcript // .status'`;
+
+/** Every route this app answers, and what each is for. */
+const ROUTES: readonly { route: string; does: string }[] = [
+  { route: "GET  /workflows", does: "the three workflows and their input schemas" },
+  { route: "POST /workflows/runs", does: "start a run · body names workflow and input" },
+  { route: "GET  /workflows/runs", does: "runs so far · filter by workflow, key, limit" },
+  { route: "GET  /workflows/runs/:id", does: "one run · add wait=<ms> to block on it" },
+  { route: "GET  /workflows/runs/:id/events", does: "SSE, status transitions" },
+  { route: "GET  /workflows/runs/:id/stream", does: "SSE, what the run has written" },
+  { route: "POST /workflows/runs/:id/wake", does: "end a pending sleep early" },
+  { route: "DELETE /workflows/runs/:id", does: "cancel it" },
+  { route: "POST /workflows/uploads", does: "store a file, id minted by the store" },
+  {
+    route: "PUT  /workflows/uploads/:id",
+    does: "store a file under YOUR id, readable as it arrives",
+  },
+  { route: "GET  /workflows/uploads/:id", does: "read the bytes back · Range honoured" },
+  { route: "GET  /workflows/uploads/:id/info", does: "name, bytes stored so far, and complete" },
+];
+
+/**
+ * The whole API, collapsed by default.
+ *
+ * `<details>` rather than a state hook: the browser owns disclosure, it is
+ * keyboard-accessible and findable by in-page search without anyone wiring either,
+ * and a page that renders a transcript should not re-render because somebody
+ * expanded a help panel.
+ */
+export function ApiHelp(): ReactNode {
+  return (
+    <details className="rounded-md border">
+      <summary className="cursor-pointer p-4 text-sm font-medium">
+        Use the API without this page
+      </summary>
+      <div className="flex flex-col gap-6 border-t p-4">
+        <p className="text-sm opacity-70">
+          This page is one caller. Everything it does is plain HTTP on this agent's own origin,
+          unauthenticated unless the deployment sets{" "}
+          <code className="text-xs">AAI_WORKFLOW_API_TOKEN</code> (then every route wants{" "}
+          <code className="text-xs">Authorization: Bearer …</code>). A run id is the whole handle —
+          no session, no cookie — so a transcript can be collected from another machine, days later.
+        </p>
+        <p className="text-sm">
+          {/* The API answering for itself: same JSON this form was rendered from. */}
+          <a className="underline" href={API} target="_blank" rel="noreferrer">
+            {`GET ${API}`}
+          </a>{" "}
+          <span className="opacity-70">
+            — the live listing, including each workflow's input schema. Set{" "}
+            <code className="text-xs">AGENT</code> to this page's origin for the recipes below.
+          </span>
+        </p>
+
+        <Recipe
+          title="Store it, then transcribe"
+          note="Sync API. One request per phase, and the upload has to finish before there is a run."
+          script={CLASSIC}
+        />
+        <Recipe
+          title="Transcribe while it uploads"
+          note="Sync API, one upload request, no splitting. The run starts on an id you chose and reads the bytes as they land."
+          script={STREAMING}
+        />
+        <Recipe
+          title="Let the provider do it"
+          note="Async API. No cutting and no seams, it accepts compressed audio, and the wait belongs to the provider's queue."
+          script={BATCH}
+        />
+
+        <section className="flex flex-col gap-2">
+          <h4 className="text-xs font-medium uppercase tracking-[1.2px]">Every route</h4>
+          <ul className="flex flex-col gap-1">
+            {ROUTES.map((entry) => (
+              <li key={entry.route} className="flex flex-col gap-0.5 text-xs sm:flex-row sm:gap-3">
+                <code className="shrink-0 sm:w-72">{entry.route}</code>
+                <span className="opacity-70">{entry.does}</span>
+              </li>
+            ))}
+          </ul>
+        </section>
+      </div>
+    </details>
+  );
+}