diff --git a/.changeset/bench-tasks-framework-focus.md b/.changeset/bench-tasks-framework-focus.md
new file mode 100644
index 00000000..654edf76
--- /dev/null
+++ b/.changeset/bench-tasks-framework-focus.md
@@ -0,0 +1,21 @@
+---
+"@aws-blocks/agent-bench": patch
+---
+
+test(bench): reshape agent-bench task graders to be framework-surface-first
+
+Internal CI/bench tooling only — changes are confined to the private, unpublished
+`@aws-blocks/agent-bench` workspace and its task content (`tasks/*`). No
+published-package (`packages/*`) changes, so this needs no release (empty changeset).
+
+- The per-task Playwright graders now assert the **framework `api` surface** (the
+  JSON-RPC `POST /aws-blocks/api` namespace) as the canonical signal, with a thin
+  page smoke on top, so a task is graded on genuine Building-Block usage rather than
+  DOM-only behavior that a mock UI could fake.
+- Follow-up review hardening (same PR): removed a dead, never-executed OTP-gate
+  `else` assertion in `cognito-profile` (the bench always runs with `BLOCKS_MOCK=true`)
+  and documented that the production gate is prompt-enforced but grader-unverified;
+  restored the `auth-notes` DOM XSS smoke (saved markup must render as literal text,
+  not interpreted HTML); and restored the `async-word-counter` enqueue-time
+  processing-state persistence assertion (a job must be persisted as `"processing"`
+  the instant it is enqueued, not only on completion).
diff --git a/scripts/agent-bench/steps/3-build-and-test.sh b/scripts/agent-bench/steps/3-build-and-test.sh
index 90f575a8..34b4060f 100755
--- a/scripts/agent-bench/steps/3-build-and-test.sh
+++ b/scripts/agent-bench/steps/3-build-and-test.sh
@@ -19,6 +19,13 @@ CELL_TMP="/tmp/bench-${TASK:-default}-$$"
 mkdir -p "$CELL_TMP"
 export PW_RESULTS_JSON="${CELL_TMP}/pw-results.json"
 
+# Test-only mock switch, inherited by both the dev server and Playwright. Tasks
+# whose grader needs a server-side test backdoor gate that surface on BLOCKS_MOCK
+# and return null otherwise, so it is inert in a real deployment. Example:
+# cognito-profile's api.getLastCode exposes the most-recently delivered OTP
+# (the grader has no mailbox) only when this is set.
+export BLOCKS_MOCK=true
+
 # Pessimistic defaults up front, updated on success, so a failure still yields well-formed EVIDENCE.
 # build_status defaults "failed" (matches build_succeeded=false); the build step overwrites both.
 {
diff --git a/tasks/README.md b/tasks/README.md
new file mode 100644
index 00000000..0e37da2d
--- /dev/null
+++ b/tasks/README.md
@@ -0,0 +1,43 @@
+# Bench tasks
+
+Each subdirectory is one benchmark task with exactly two files:
+
+- **`PROMPT.md`** — the instructions handed to the building agent.
+- **`test.spec.ts`** — the Playwright grader run against the agent-built app.
+
+The reference app is **not** committed; the agent builds it during the bench,
+then the spec grades the running dev server.
+
+## Intentional per-spec helper duplication
+
+Every spec re-declares the same small helpers inline — `watchErrors(page)`, a
+JSON-RPC `rpc(ctx, method, params)` wrapper, and the `uniq(base)` seed — rather
+than importing them from a shared module. **This duplication is deliberate:**
+each `test.spec.ts` must be a self-contained grader that can be dropped next to
+a single task app and run on its own, with no cross-task imports or build step.
+Keeping the helpers local keeps the specs portable and independently readable;
+do not refactor them into a shared import.
+
+## Harness contract
+
+The bench runs each spec **serially with `workers: 1`** (see
+`scripts/agent-bench/steps/3-build-and-test.sh`). Specs assert against a
+**shared server-side store** (e.g. the presence roster, the file list) and scope
+their assertions to their own `uniq(...)` names rather than to absolute counts.
+Those assertions are race-free **only** under `workers: 1`; running with more
+workers would require reworking them to tolerate concurrent runners. Each spec
+that relies on this carries a `// HARNESS CONTRACT: requires workers:1` banner.
+
+Two independent counters back the helpers so neither perturbs the other:
+
+- **`rpcSeq`** — the JSON-RPC `id` on each request.
+- **`uniqSeq`** — the monotonic component of `uniq(...)` test-data seeds.
+
+## Test-only backdoors (`BLOCKS_MOCK`)
+
+A few tasks need a server-side hook the grader can read because it has no real
+side channel (e.g. `cognito-profile`'s `api.getLastCode`, which surfaces the
+most-recently delivered OTP since the grader has no mailbox). Such hooks MUST be
+gated: annotated `@blocksSkipCodegen` and returning `null` unless
+`process.env.BLOCKS_MOCK === 'true'`, so they are inert in a real deployment.
+The harness exports `BLOCKS_MOCK=true` for the graded dev server.
diff --git a/tasks/async-word-counter/PROMPT.md b/tasks/async-word-counter/PROMPT.md
index 4b0a5d3d..c6c2d92c 100644
--- a/tasks/async-word-counter/PROMPT.md
+++ b/tasks/async-word-counter/PROMPT.md
@@ -1,41 +1,50 @@
 # Task: Async Word Counter
 
-Build an async word counter in this AWS Blocks app. A user submits some text; the counting happens in a background job. The row for that submission starts as "processing" and flips to "done" with the word count once the job finishes. Results survive a page reload.
+Build an async word counter in this AWS Blocks app. A user submits some text; the counting happens in a **background job**. A submission starts as `"processing"` and flips to `"done"` with its word count once the job finishes. Results are persisted and survive a reload.
+
+The core of this task is **using the framework**: submissions are enqueued and read through an **`api` namespace** whose methods run on the server, do the counting in a **background job block**, and persist each job in a **key/value block** keyed by job id. The page is a thin client that polls that API.
 
 ## Setup (do this first)
 
-The workspace has already been scaffolded. Begin by reading README.md, then do all your edits in this workspace.
+The workspace has already been scaffolded. Begin by reading README.md (and any AGENTS.md), then do all your edits in this workspace.
 
 ## Requirements
 
-1. A user types text into an input and clicks submit.
-2. Submitting enqueues a background job (do the counting in the job — not inline in the request handler) and immediately adds a row for it whose `data-status` is `"processing"`.
-3. The background job counts the words and stores the result in a key/value block keyed by the job id. **Count by whitespace runs only:** trim the text, then split on any run of whitespace (spaces, tabs) — so `one two three four five` is 5, and `"   a   b  "` (leading/trailing + double spaces) is 2. A naive `split(' ')` that counts empty gaps is wrong.
-   - **Punctuation is part of a word, not a separator:** only whitespace separates words, so `hello,world foo.bar-baz!` is **3** words, not 5.
-   - **Unicode and emoji tokens each count as one word:** `café 日本語 🙂 naïve` is **4** words. Count each maximal run of non-whitespace as one word — do **not** use `\w+` / `\W+`, which miscount punctuation and non-ASCII/emoji characters.
-4. **Polling:** the frontend polls for the result; when it's ready the row's `data-status` becomes `"done"` and the row shows the word count.
-5. **Persistence (including in-flight jobs):** persist each submission to the key/value block **when you enqueue it** (status `"processing"`, keyed by job id) — not only when it finishes. On load, **restore the whole list from the store** (every job, including still-`processing` ones) and resume polling — not just the most recent submission. A row reloaded **while still processing** must reappear and still resolve to `"done"` with its count. (An app that tracks the job list only in client memory loses an in-flight row on reload — that fails.)
-6. **Multiple jobs, keyed by job id:** submitting several times enqueues several independent jobs; each gets its own row and its own correct count. Results must be keyed by **job id**, never by the input text — so submitting the **same text twice** produces **two** independent rows, each with its own result that doesn't bleed into the other.
-7. **Input validation:** disable `[data-testid=wc-submit]` whenever the input is empty or whitespace-only (trim before the check); re-enable it once real text is present. Don't enqueue a job for blank input.
+### The `api` namespace (primary surface)
+
+Expose an **`api` namespace** (a `POST /aws-blocks/api` JSON-RPC endpoint) with these methods:
+
+1. **`api.enqueue(text)`** — enqueues a background word-count job for `text` and returns the new job's id as `{ "id": <string> }` (a non-empty job id). It must:
+   - do the counting in a **background job** (the AsyncJob block) — **not** inline in the request handler;
+   - **persist the job at enqueue time** with status `"processing"`, keyed by job id, in the key/value block (not only when it finishes);
+   - **validate the input** — `text` that is empty or whitespace-only (trim first) is rejected with a JSON-RPC **error** envelope and enqueues **no** job.
+2. **`api.getJob(id)`** — returns the job as exactly `{ "id": <string>, "text": <string>, "status": "processing" | "done", "count": <number|null> }`. `count` is the word count once `status === "done"` (and may be `null`/absent while processing). An **unknown** id returns a JSON-RPC **error** envelope (not a bogus success).
+3. **`api.listJobs()`** — returns an array of every job (each the same `{ id, text, status, count }` shape), **restored from the store** — including still-`processing` ones. This is what lets the page rebuild its list on load.
+
+**Word count — count by whitespace runs only.** Trim the text, then split on any run of whitespace (spaces, tabs, newlines): `one two three four five` is `5`, and `"   a   b  "` is `2` (a naive `split(' ')` that counts empty gaps is wrong). **Punctuation is part of a word, not a separator** — `hello,world foo.bar-baz!` is `3`. **Unicode and emoji tokens each count as one word** — `café 日本語 🙂 naïve` is `4`. Count each maximal run of non-whitespace as one word; do **not** use `\w+` / `\W+` (they miscount punctuation and non-ASCII/emoji).
+
+**Keyed by job id, never by text.** Submitting the **same text twice** produces **two** independent jobs, each with its own id and its own result — results must never bleed between jobs or collapse into one.
 
-A single shared list — no login.
+### The page (thin client / light smoke)
+
+1. A text input (`[data-testid=wc-input]`) and a submit button (`[data-testid=wc-submit]`). Disable submit whenever the input is empty or whitespace-only (trim before checking); re-enable it once real text is present.
+2. Submitting calls `api.enqueue`, then the page polls (`api.getJob` / `api.listJobs`) and renders a row per job inside `[data-testid=wc-list]`.
+3. On load, the list is rebuilt from `api.listJobs` (every job, including still-processing ones) and polling resumes — so a row reloaded while still processing reappears and still resolves to `"done"`.
 
 ## Selector contract
 
-The Playwright test grades your work using `data-testid` hooks and one data attribute. Implement them exactly.
+The page smoke test uses these hooks. Implement them exactly.
 
 | Selector | Element | Purpose |
 |---|---|---|
 | `[data-testid=wc-input]` | `<input type="text">` (or `<textarea>`) | Where the user types the text to count |
-| `[data-testid=wc-submit]` | `<button>` | Enqueue an async word-count job for the input text |
+| `[data-testid=wc-submit]` | `<button>` | Enqueue a job (calls `api.enqueue`) |
 | `[data-testid=wc-list]` | container | Wraps every job row |
-| `[data-testid=wc-item]` | one per job, inside the list | The row for a single job; must also render the submitted text as its content |
+| `[data-testid=wc-item]` | one per job, inside the list | The row for a single job; must render the submitted text as its content |
 | `[data-testid=wc-status]` | inside the item | Renders the job's status |
-| `[data-testid=wc-result]` | inside the item | Renders the word count once the job is done |
-
-Set `data-status` on each `[data-testid=wc-item]`: `"processing"` while the job runs, `"done"` once the result is stored. When done, `[data-testid=wc-result]` must show the word count as a bare number (e.g. `5`).
+| `[data-testid=wc-result]` | inside the item | Renders the word count (a bare number, e.g. `5`) once done |
 
-A `[data-testid=wc-item]` must contain the submitted text (the test locates a submission's row via `filter({ hasText: <submitted text> })`, since the job list is shared).
+Set `data-status` on each `[data-testid=wc-item]`: `"processing"` while running, `"done"` once the result is stored. A `[data-testid=wc-item]` must contain the submitted text (the smoke test locates a row via `filter({ hasText: <submitted text> })`).
 
 The mount point for your page is the existing root element. You can replace whatever placeholder content the template ships with.
 
@@ -44,8 +53,8 @@ The mount point for your page is the existing root element. You can replace what
 - Authentication, accounts, per-user lists
 - Cancelling or retrying jobs, progress percentages
 - Counting anything other than whitespace-separated words
-- Styling beyond what makes the test pass
 - Ordering, sorting, filtering, search, pagination
+- Styling beyond what makes the test pass
 
 ## Done means
 
diff --git a/tasks/async-word-counter/test.spec.ts b/tasks/async-word-counter/test.spec.ts
index ff72ec55..a6a64476 100644
--- a/tasks/async-word-counter/test.spec.ts
+++ b/tasks/async-word-counter/test.spec.ts
@@ -1,297 +1,214 @@
-import { test, expect, type Page } from '@playwright/test';
+import { test, expect, type Page, type APIRequestContext } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const APPEAR = 8_000;
-const DONE = 20_000; // background job + frontend poll interval
+const DONE = 20_000; // background job + poll interval
 
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: ONLY uncaught page errors.
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
-// A phrase with a unique leading token (keeps the submission unique per run)
-// plus `total - 1` filler words, for a deterministic whitespace word count of
-// exactly `total`. The uniq token has no spaces, so it counts as one word.
-function phraseWithWords(total: number): string {
-	const filler = Array.from({ length: Math.max(0, total - 1) }, (_, i) => `w${i}`);
-	return [uniq('word'), ...filler].join(' ');
+async function rpc(
+	request: APIRequestContext,
+	method: string,
+	params: unknown[] | undefined,
+	opts: { omitParams?: boolean } = {},
+): Promise<{ status: number; body: any }> {
+	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++rpcSeq };
+	if (!opts.omitParams) data.params = params ?? [];
+	const res = await request.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data,
+	});
+	return { status: res.status(), body: await res.json().catch(() => null) };
+}
+
+async function enqueue(request: APIRequestContext, text: string): Promise<string> {
+	const { body } = await rpc(request, 'api.enqueue', [text]);
+	expect(body?.error, `JSON-RPC error from enqueue: ${JSON.stringify(body?.error)}`).toBeFalsy();
+	const id = body?.result?.id;
+	expect(typeof id, `enqueue must return { id: string }, got ${JSON.stringify(body?.result)}`).toBe('string');
+	expect(String(id).length).toBeGreaterThan(0);
+	return id as string;
+}
+
+// Poll api.getJob until the job reaches "done"; returns its numeric count.
+async function countOf(request: APIRequestContext, id: string): Promise<number> {
+	let job: any = null;
+	await expect
+		.poll(async () => {
+			job = (await rpc(request, 'api.getJob', [id])).body?.result ?? null;
+			return job?.status;
+		}, { timeout: DONE })
+		.toBe('done');
+	expect(typeof job.count, `count must be a number, got ${JSON.stringify(job.count)}`).toBe('number');
+	return job.count as number;
 }
 
-// The row for a specific submission, located by its unique phrase text. The
-// shared list persists across the run (and across a Playwright retry), so we
-// never use .first() or a result-only count — either can match a STALE row from
-// another submission/attempt and pass vacuously. The phrase carries a per-call
-// unique token, so this scopes to exactly the row we just submitted.
+// The DOM row for a submission, located by its unique phrase text.
 const rowFor = (page: Page, phrase: string) => page.getByTestId('wc-item').filter({ hasText: phrase });
 
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
 test.describe('async-word-counter', () => {
-	test('shows the text input and submit button', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		await expect(page.getByTestId('wc-input')).toBeVisible();
-		await expect(page.getByTestId('wc-submit')).toBeVisible();
-		// Enforce the wc-list container contract (in the PROMPT selector table)
-		// so an impl can't omit the list wrapper and still pass.
-		await expect(page.getByTestId('wc-list')).toBeVisible();
+	// --- Framework surface: counting + persistence graded through the api ---
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('api.enqueue \u2192 getJob resolves to done with the correct word count', async ({ request }) => {
+		const id = await enqueue(request, `${uniq('word')} one two three four`); // 5 tokens
+		expect(await countOf(request, id)).toBe(5);
 	});
 
-	test('submitting adds a job row carrying a valid status', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const phrase = phraseWithWords(4);
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
-
-		// The row for THIS submission (scoped by its unique phrase) renders with
-		// the status hook and a valid lifecycle status. It may already have
-		// flipped to "done", so accept either rather than racing the intermediate
-		// "processing" state.
-		const row = rowFor(page, phrase);
-		await expect(row).toBeVisible({ timeout: APPEAR });
-		await expect(row.getByTestId('wc-status')).toBeVisible({ timeout: APPEAR });
-		await expect(row).toHaveAttribute('data-status', /^(processing|done)$/, { timeout: APPEAR });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('word count collapses whitespace runs and ignores leading/trailing space', async ({ request }) => {
+		// Trim then split on whitespace RUNS: exactly 3 tokens.
+		const id = await enqueue(request, `   ${uniq('sp')}    alpha\tbeta   `);
+		expect(await countOf(request, id)).toBe(3);
 	});
 
-	test('a submitted job resolves to done with the correct word count', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const phrase = phraseWithWords(5);
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
+	test('punctuation is part of a word, not a separator', async ({ request }) => {
+		// Only whitespace separates: 3 tokens (a `\W+` split would over-count).
+		const id = await enqueue(request, `${uniq('punct')} hello,world foo.bar-baz!`);
+		expect(await countOf(request, id)).toBe(3);
+	});
 
-		// THIS submission's row must reach "done" and render its word count (5).
-		const row = rowFor(page, phrase);
-		await expect(row).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(row.getByTestId('wc-status')).toContainText(/done/i, { timeout: DONE });
-		await expect(row.getByTestId('wc-result')).toHaveText(/^\s*5\s*$/, { timeout: DONE });
+	test('unicode and emoji tokens each count as one word', async ({ request }) => {
+		// Five non-whitespace runs incl. non-ASCII + emoji (a `\w+` impl undercounts).
+		const id = await enqueue(request, `${uniq('uni')} café 日本語 🙂 naïve`);
+		expect(await countOf(request, id)).toBe(5);
+	});
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('a single token counts as exactly one word', async ({ request }) => {
+		const id = await enqueue(request, uniq('solo'));
+		expect(await countOf(request, id)).toBe(1);
 	});
 
-	test('the word count is computed accurately for a longer phrase', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+	test('getJob echoes the submitted text and a well-formed shape', async ({ request }) => {
+		const text = `${uniq('shape')} lorem ipsum`;
+		const id = await enqueue(request, text);
+		expect(await countOf(request, id)).toBe(3);
+		const job = (await rpc(request, 'api.getJob', [id])).body?.result;
+		expect(job?.id).toBe(id);
+		expect(job?.text).toBe(text);
+		expect(job?.status).toBe('done');
+	});
 
-		const phrase = phraseWithWords(8);
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
+	test('empty / whitespace-only input is rejected and enqueues no job', async ({ request }) => {
+		for (const bad of ['', '   \t  ']) {
+			const { status, body } = await rpc(request, 'api.enqueue', [bad]);
+			expect(status, `unexpected HTTP ${status}`).toBeLessThan(500);
+			expect(body?.error, `blank input must yield a JSON-RPC error envelope (input=${JSON.stringify(bad)})`).toBeTruthy();
+			expect(body?.result ?? null).toBeNull();
+		}
+	});
 
-		// Scoped to this submission's row; its result must render exactly 8.
-		const row = rowFor(page, phrase);
-		await expect(row).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(row.getByTestId('wc-result')).toHaveText(/^\s*8\s*$/, { timeout: DONE });
+	test('an unknown job id returns a JSON-RPC error envelope', async ({ request }) => {
+		const { status, body } = await rpc(request, 'api.getJob', [`missing-${uniq('x')}`]);
+		expect(status, `unexpected HTTP ${status}`).toBeLessThan(500);
+		expect(body?.error, 'an unknown id must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(body?.result ?? null).toBeNull();
+	});
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('the same text twice yields two independent jobs keyed by id', async ({ request }) => {
+		const text = `${uniq('dup')} alpha beta gamma`; // 4 tokens
+		const idA = await enqueue(request, text);
+		const idB = await enqueue(request, text);
+		expect(idA, 'the two submissions must get distinct job ids').not.toBe(idB);
+		expect(await countOf(request, idA)).toBe(4);
+		expect(await countOf(request, idB)).toBe(4);
 	});
 
-	test('a finished job persists across a full reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+	test('listJobs restores every enqueued job from the store', async ({ request }) => {
+		const text = `${uniq('listed')} a b`; // 3 tokens
+		const id = await enqueue(request, text);
+		await countOf(request, id);
+
+		// The `request` fixture is a raw API client (reused here, NOT a new context) — it holds no
+		// in-page/client-side list state, so seeing the job via listJobs proves it was restored from
+		// the server-side store, not replayed from any client memory.
+		const { body } = await rpc(request, 'api.listJobs', []);
+		expect(body?.error, `JSON-RPC error: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		expect(Array.isArray(body?.result), 'listJobs must return an array').toBe(true);
+		const mine = body.result.find((j: any) => j?.id === id);
+		expect(mine, 'listJobs must include the enqueued job').toBeTruthy();
+		expect(mine.text).toBe(text);
+	});
 
-		const phrase = phraseWithWords(6);
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
-		await expect(rowFor(page, phrase)).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(rowFor(page, phrase).getByTestId('wc-result')).toHaveText(/^\s*6\s*$/, { timeout: DONE });
+	test('a job is persisted at enqueue time as "processing" — not only when it finishes', async ({ request }) => {
+		// PROMPT (lines 3, 19, 22, 32): enqueue must persist the job IMMEDIATELY (keyed by id in
+		// the KV block), not only on completion. The background job runs asynchronously, so reading
+		// right after enqueue returns must surface a persisted job — whereas a persist-on-done impl
+		// 404s here (unknown id) or omits it from listJobs. We assert the job is READABLE and, while
+		// still running, reports "processing" with a null count. DONE=20s is a poll CEILING (the most
+		// we ever wait), NOT a floor: a legitimately-fast reference impl can finish its background job
+		// before this immediate read, so we tolerate a fast "done" here rather than flaking.
+		const text = `${uniq('proc')} alpha beta gamma delta`; // 5 tokens
+		const id = await enqueue(request, text);
+
+		const { body } = await rpc(request, 'api.getJob', [id]);
+		expect(body?.error, `getJob right after enqueue must not error: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		const job = body?.result;
+		expect(job?.id, 'the job must be readable the instant it is enqueued').toBe(id);
+		expect(job?.text).toBe(text);
+		expect(
+			['processing', 'done'],
+			'a just-enqueued job must be readable — "processing", or "done" if a fast impl already finished',
+		).toContain(job?.status);
+		if (job?.status === 'processing') {
+			expect(job?.count ?? null, 'count is null/absent while still processing').toBeNull();
+		}
 
-		await page.reload();
-		await expect(rowFor(page, phrase)).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(rowFor(page, phrase).getByTestId('wc-result')).toHaveText(/^\s*6\s*$/, { timeout: DONE });
+		// listJobs must ALSO surface the still-processing job (restored from the store, PROMPT line 22).
+		const listed = (await rpc(request, 'api.listJobs', [])).body?.result ?? [];
+		const mine = Array.isArray(listed) ? listed.find((j: any) => j?.id === id) : null;
+		expect(mine, 'listJobs must include the still-processing job (not only done ones)').toBeTruthy();
+		expect(mine.status, 'the listed job is still processing').toBe('processing');
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		// And it still resolves to done with the correct count.
+		expect(await countOf(request, id)).toBe(5);
 	});
 
-	test('the submit button is disabled until non-empty text is entered', async ({ page }) => {
+	// --- Page smoke: the thin client enqueues, polls, and persists ---
+
+	test('shows the input, submit button, and list; submit gates on non-empty text', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
 		const input = page.getByTestId('wc-input');
 		const submit = page.getByTestId('wc-submit');
 		await expect(input).toBeVisible();
+		await expect(page.getByTestId('wc-list')).toBeVisible();
 
-		// Empty input cannot be submitted...
 		await input.fill('');
 		await expect(submit).toBeDisabled();
-		// ...nor can whitespace-only input (the value must be trimmed before the
-		// emptiness check) — a job with no text is meaningless.
 		await input.fill('   \t  ');
 		await expect(submit).toBeDisabled();
-		// Real text re-enables submit, so the control isn't simply always-disabled.
 		await input.fill('hello world');
 		await expect(submit).toBeEnabled();
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('the word count collapses runs of whitespace and ignores leading/trailing space', async ({ page }) => {
+	test('submitting through the page resolves to done and persists across reload', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		// Irregular spacing (leading/trailing, double spaces, a tab) around exactly
-		// three tokens. A correct count trims then splits on whitespace RUNS
-		// (`.trim().split(/\s+/)`); a naive `split(' ')` would over-count the empty
-		// gaps. Scoped to this submission by its unique leading token.
-		const token = uniq('spaced');
-		const phrase = `   ${token}    alpha\tbeta   `;
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
-
-		const row = rowFor(page, token);
-		await expect(row).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(row.getByTestId('wc-result')).toHaveText(/^\s*3\s*$/, { timeout: DONE });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('multiple submissions each resolve to their own independent count', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// Three distinct submissions with different word counts, enqueued back to
-		// back. Each row must resolve to ITS OWN count — the per-job results must
-		// not bleed into one another (each keyed by its own job id).
-		const specs = [3, 7, 2].map((n) => ({ n, phrase: phraseWithWords(n) }));
-		for (const s of specs) {
-			await page.getByTestId('wc-input').fill(s.phrase);
-			await page.getByTestId('wc-submit').click();
-		}
-		for (const s of specs) {
-			const row = rowFor(page, s.phrase);
-			await expect(row).toHaveAttribute('data-status', 'done', { timeout: DONE });
-			await expect(row.getByTestId('wc-result')).toHaveText(new RegExp(`^\\s*${s.n}\\s*$`), { timeout: DONE });
-		}
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('multiple finished jobs all persist across a full reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const first = phraseWithWords(4);
-		const second = phraseWithWords(9);
-		for (const phrase of [first, second]) {
-			await page.getByTestId('wc-input').fill(phrase);
-			await page.getByTestId('wc-submit').click();
-		}
-		await expect(rowFor(page, first)).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(rowFor(page, second)).toHaveAttribute('data-status', 'done', { timeout: DONE });
-
-		// After a reload BOTH finished jobs must still be present with their counts
-		// — persistence must restore the whole list, not just the most recent row.
-		await page.reload();
-		await expect(rowFor(page, first).getByTestId('wc-result')).toHaveText(/^\s*4\s*$/, { timeout: DONE });
-		await expect(rowFor(page, second).getByTestId('wc-result')).toHaveText(/^\s*9\s*$/, { timeout: DONE });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('unicode and emoji tokens each count as one word', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// Five space-separated tokens, including non-ASCII words and an emoji.
-		// Whitespace-run splitting counts each as one word (5). An impl built on
-		// `\w+` undercounts the unicode/emoji tokens.
-		const token = uniq('uni');
-		const phrase = `${token} café 日本語 🙂 naïve`;
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
-
-		const row = rowFor(page, token);
-		await expect(row).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(row.getByTestId('wc-result')).toHaveText(/^\s*5\s*$/, { timeout: DONE });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('punctuation is part of a word, not a separator', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// Only whitespace separates words, so these three punctuation-laden tokens
-		// count as 3. An impl that splits on `\W+` would over-count.
-		const token = uniq('punct');
-		const phrase = `${token} hello,world foo.bar-baz!`;
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
-
-		const row = rowFor(page, token);
-		await expect(row).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(row.getByTestId('wc-result')).toHaveText(/^\s*3\s*$/, { timeout: DONE });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('a single token counts as exactly one word', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// Boundary case: one token, no internal whitespace. `.trim().split(/\s+/)`
-		// is 1; an off-by-one that counts separators would be 0.
-		const phrase = uniq('solo');
+		const phrase = `${uniq('ui')} one two three four five`; // 6 tokens
 		await page.getByTestId('wc-input').fill(phrase);
 		await page.getByTestId('wc-submit').click();
 
 		const row = rowFor(page, phrase);
+		await expect(row).toBeVisible({ timeout: APPEAR });
 		await expect(row).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(row.getByTestId('wc-result')).toHaveText(/^\s*1\s*$/, { timeout: DONE });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('a job reloaded while still processing is restored and still resolves to done', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// Submit, then wait only for the row to APPEAR (it may still be
-		// "processing"), and reload right away. Because each submission is
-		// persisted at enqueue time (keyed by job id), the row must survive the
-		// reload and still resolve to "done" with its count — an impl that tracks
-		// the job list only in client memory loses this in-flight row.
-		const phrase = phraseWithWords(7);
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
-		await expect(rowFor(page, phrase)).toBeVisible({ timeout: APPEAR });
+		await expect(row.getByTestId('wc-result')).toHaveText(/^\s*6\s*$/, { timeout: DONE });
 
+		// Restored from api.listJobs on reload (not just client memory).
 		await page.reload();
 		await expect(rowFor(page, phrase)).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(rowFor(page, phrase).getByTestId('wc-result')).toHaveText(/^\s*7\s*$/, { timeout: DONE });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('the same text submitted twice yields two independent rows keyed by job id', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// Identical text submitted twice = two independent jobs. Each must get its
-		// OWN row and its OWN result (keyed by job id). An impl that keys results
-		// by the input text collapses these into one row or shares a single result.
-		const phrase = phraseWithWords(6); // unique leading token shared by both rows
-		for (let i = 0; i < 2; i++) {
-			await page.getByTestId('wc-input').fill(phrase);
-			await page.getByTestId('wc-submit').click();
-		}
-
-		const rows = rowFor(page, phrase);
-		await expect(rows).toHaveCount(2, { timeout: DONE });
-		await expect(rows.nth(0)).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(rows.nth(1)).toHaveAttribute('data-status', 'done', { timeout: DONE });
-		await expect(rows.nth(0).getByTestId('wc-result')).toHaveText(/^\s*6\s*$/, { timeout: DONE });
-		await expect(rows.nth(1).getByTestId('wc-result')).toHaveText(/^\s*6\s*$/, { timeout: DONE });
+		await expect(rowFor(page, phrase).getByTestId('wc-result')).toHaveText(/^\s*6\s*$/, { timeout: DONE });
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
diff --git a/tasks/auth-notes/PROMPT.md b/tasks/auth-notes/PROMPT.md
index 97e6faf0..2ad3ec43 100644
--- a/tasks/auth-notes/PROMPT.md
+++ b/tasks/auth-notes/PROMPT.md
@@ -2,26 +2,34 @@
 
 Build a personal notepad in this AWS Blocks app. A visitor signs up (or signs in), edits a single private note, and that note is saved to their account — it survives a reload and is never visible to other users.
 
+The core of this task is **using the framework**: the note is read and written through an **`api` namespace** whose methods run **on the server** and persist through the app's auth + key/value blocks. The page is a thin client over that API.
+
 ## Setup (do this first)
 
-The workspace has already been scaffolded. Begin by reading README.md, then do all your edits in this workspace.
+The workspace has already been scaffolded. Begin by reading README.md (and any AGENTS.md), then do all your edits in this workspace.
 
 ## Requirements
 
-1. A signed-out visitor sees a username field, a password field, and a submit button. Submitting signs them up (or signs an existing user in).
-2. Once authenticated, the visitor sees a single editable note (a textarea) and a save button — the signed-out form is gone.
-3. Clicking save stores the note for the current user (per-user, in a key/value block under the key `note:{username}`). Saving **overwrites** the user's single note — it does not append. Saving while the textarea is empty is allowed and **clears** the note (the saved value becomes the empty string).
-4. **Persistence:** after a full page reload the visitor is still signed in, the textarea is **pre-filled** with their saved note (not blank), and the display shows it. Notes are stored and rendered **verbatim** — exactly the characters saved, with no HTML interpretation (a note containing markup such as `<b>x</b>` is shown as literal text, not a bold element). Notes up to a few thousand characters round-trip unchanged.
-5. **Per-user isolation:** a different user who signs in sees their own note (empty until they save one), never another user's note.
-6. A signed-in visitor can sign out, which returns them to the signed-out form.
+### The `api` namespace (primary surface)
+
+Expose an **`api` namespace** (the framework's server-side RPC surface — a `POST /aws-blocks/api` JSON-RPC endpoint) with these methods. Each note operation must run **on the server** and persist through the **key/value block** under the per-user key `note:{username}`. Both methods derive the current user from the **auth session** (the sign-in cookie) — the note key is **never** taken from a client-supplied argument. Store the username **verbatim** in the key (`note:{username}`) — no URL-encoding, hashing, or case-folding — so the key maps exactly back to the authenticated identity.
+
+1. **`api.getNote()`** — returns the signed-in user's saved note as a **string** (the empty string `""` when they have never saved one). Structured return: exactly the string value, nothing appended.
+2. **`api.saveNote(text)`** — saves `text` as the current user's single note and returns the stored value. Saving **overwrites** (it does not append). Saving `""` is allowed and **clears** the note (the stored value becomes `""`). Notes are stored and returned **verbatim** — exactly the characters saved, with no HTML interpretation or escaping (a note containing markup such as `<b>x</b>` round-trips as that literal string). Notes up to a few thousand characters round-trip unchanged. A **missing or non-string** argument is rejected with a JSON-RPC **error** envelope and leaves the stored note **unchanged** (no degenerate empty save).
+
+**Auth gating (framework-enforced):** both methods require an authenticated session. Called with **no session** (e.g. a direct `POST /aws-blocks/api` carrying no sign-in cookie), a note method must return a JSON-RPC **error** envelope (unauthenticated) — **not** a `result`, and never another user's data. **Per-user isolation:** each user's `getNote` returns only their own note.
+
+### The page (thin client / light smoke)
+
+1. A signed-out visitor sees a username field, a password field, and a submit button. Submitting signs them up (or signs an existing user in) — establishing the auth session.
+2. Once authenticated, the visitor sees a single editable note (a textarea), a save button, and a display of the current note; the signed-out form is gone. The save button calls `api.saveNote`; on load / after reload the editor and display are populated from `api.getNote` (so the note is pre-filled, not blank).
+3. A signed-in visitor can sign out, returning to the signed-out form.
 
 Exactly one note per user. No password reset, email verification, or multiple notes.
 
 ## Selector contract
 
-The Playwright test grades your work using these `data-testid` hooks. Implement them exactly. The signed-out and signed-in views are told apart by which hooks are present: the auth fields show only when signed out; the note hooks and sign-out button show only when signed in.
-
-An inactive view's hooks must be REMOVED from the DOM (the grader asserts `toHaveCount(0)`); hiding them with CSS (`display:none` / `hidden`) will fail.
+The page smoke test uses these `data-testid` hooks. Implement them exactly. The signed-out and signed-in views are told apart by which hooks are present: the auth fields show only when signed out; the note hooks and sign-out button show only when signed in. An inactive view's hooks must be **removed** from the DOM (not merely hidden with CSS).
 
 | Selector | Element | Purpose |
 |---|---|---|
@@ -30,10 +38,10 @@ An inactive view's hooks must be REMOVED from the DOM (the grader asserts `toHav
 | `[data-testid=auth-submit]` | `<button>` | Submit credentials to sign up or sign in |
 | `[data-testid=auth-signout]` | `<button>` | Sign out; shown only when signed in |
 | `[data-testid=note-textarea]` | `<textarea>` | The current user's editable note; shown only when signed in |
-| `[data-testid=note-save]` | `<button>` | Save the note for the current user |
+| `[data-testid=note-save]` | `<button>` | Save the note (calls `api.saveNote`) |
 | `[data-testid=note-display]` | element in the signed-in view | Renders the currently-saved note text (empty string when the user has no saved note) |
 
-After a save, `[data-testid=note-display]` must show exactly the text that was saved. After a reload (or a fresh sign-in), `[data-testid=note-textarea]`'s value must equal the user's saved note.
+After a reload (or a fresh sign-in), `[data-testid=note-textarea]`'s value must equal the user's saved note (loaded via `api.getNote`).
 
 The mount point for your page is the existing root element. You can replace whatever placeholder content the template ships with.
 
diff --git a/tasks/auth-notes/test.spec.ts b/tasks/auth-notes/test.spec.ts
index 4b8dd66d..cf728072 100644
--- a/tasks/auth-notes/test.spec.ts
+++ b/tasks/auth-notes/test.spec.ts
@@ -1,24 +1,40 @@
-import { test, expect, type Page } from '@playwright/test';
+import { test, expect, type Page, type APIRequestContext } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const T = 8_000;
 const PASSWORD = 'correct-horse-battery-staple';
 
-// Run-stable unique identity: seeded once per worker (so a retry reuses the
-// same RUN seed) yet unique per call, so tests never collide with leftover
-// server state and never have to assert global counts.
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: collect ONLY uncaught page errors. Console warnings
-// and 4xx/5xx responses are intentionally NOT failures — the local dev server
-// returns HTTP 200 for JSON-RPC errors and 4xx pre-auth, which are expected.
+// Per-test no-error gate: ONLY uncaught page errors (4xx/JSON-RPC errors are expected).
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
+// JSON-RPC call over the framework's api endpoint. `ctx` decides identity:
+// page.request carries the page's sign-in cookie (authenticated user); the
+// top-level `request` fixture has no cookies (unauthenticated).
+async function rpc(
+	ctx: APIRequestContext,
+	method: string,
+	params: unknown[] | undefined,
+	opts: { omitParams?: boolean } = {},
+): Promise<{ status: number; body: any }> {
+	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++rpcSeq };
+	if (!opts.omitParams) data.params = params ?? [];
+	const res = await ctx.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data,
+	});
+	return { status: res.status(), body: await res.json().catch(() => null) };
+}
+
+// Sign up (or in) through the DOM, establishing the auth session cookie on
+// this page's context — after this, page.request calls the api as this user.
 async function signUp(page: Page, username: string): Promise<void> {
 	await expect(page.getByTestId('auth-username')).toBeVisible({ timeout: T });
 	await page.getByTestId('auth-username').fill(username);
@@ -27,24 +43,18 @@ async function signUp(page: Page, username: string): Promise<void> {
 	await expect(page.getByTestId('note-textarea')).toBeVisible({ timeout: T });
 }
 
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
 test.describe('auth-notes', () => {
-	test('signed-out visitor sees the username/password sign-in form', async ({ page }) => {
+	// --- Page smoke: the thin client wires up and reflects server state ---
+
+	test('signed-out visitor sees the sign-in form; signing in reveals the editor', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
 		await expect(page.getByTestId('auth-username')).toBeVisible({ timeout: T });
 		await expect(page.getByTestId('auth-password')).toBeVisible();
-		await expect(page.getByTestId('auth-submit')).toBeVisible();
-		// Signed-in hooks must be absent before authentication.
 		await expect(page.getByTestId('note-textarea')).toHaveCount(0, { timeout: T });
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('signing up reveals the note editor and hides the auth form', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
 		await signUp(page, uniq('alice'));
 		await expect(page.getByTestId('note-save')).toBeVisible();
 		await expect(page.getByTestId('auth-username')).toHaveCount(0, { timeout: T });
@@ -52,32 +62,19 @@ test.describe('auth-notes', () => {
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('saving a note shows it immediately in the display', async ({ page }) => {
+	test('a note saved through the page persists (via api.getNote) across a full reload', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signUp(page, uniq('alice'));
-		const noteText = uniq('note');
-		await page.getByTestId('note-textarea').fill(noteText);
-		await page.getByTestId('note-save').click();
-		await expect(page.getByTestId('note-display')).toHaveText(noteText, { timeout: T });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
 
-	test('a saved note persists across a full reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		await signUp(page, uniq('alice'));
 		const noteText = uniq('note');
 		await page.getByTestId('note-textarea').fill(noteText);
 		await page.getByTestId('note-save').click();
 		await expect(page.getByTestId('note-display')).toHaveText(noteText, { timeout: T });
 
 		await page.reload();
-		// Still signed in and the saved note is still shown.
-		await expect(page.getByTestId('note-textarea')).toBeVisible({ timeout: T });
+		// After reload the editor is repopulated from the server (api.getNote).
+		await expect(page.getByTestId('note-textarea')).toHaveValue(noteText, { timeout: T });
 		await expect(page.getByTestId('note-display')).toHaveText(noteText, { timeout: T });
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
@@ -86,8 +83,8 @@ test.describe('auth-notes', () => {
 	test('signing out returns the visitor to the sign-in form', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signUp(page, uniq('alice'));
+
 		await page.getByTestId('auth-signout').click();
 		await expect(page.getByTestId('auth-username')).toBeVisible({ timeout: T });
 		await expect(page.getByTestId('note-textarea')).toHaveCount(0, { timeout: T });
@@ -95,129 +92,159 @@ test.describe('auth-notes', () => {
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a second user sees their own empty note, never the first user (isolation)', async ({ browser }) => {
-		const errors: string[] = [];
+	// --- Framework surface: notes read/written through the api namespace ---
 
-		const ctxA = await browser.newContext();
-		const pageA = await ctxA.newPage();
-		watchErrors(pageA, errors);
-		await pageA.goto(BASE);
-		const noteA = uniq('alice-secret');
-		await signUp(pageA, uniq('alice'));
-		await pageA.getByTestId('note-textarea').fill(noteA);
-		await pageA.getByTestId('note-save').click();
-		await expect(pageA.getByTestId('note-display')).toHaveText(noteA, { timeout: T });
+	test('a fresh user\u2019s api.getNote is the empty string', async ({ page }) => {
+		const errors = watchErrors(page);
+		await page.goto(BASE);
+		await signUp(page, uniq('fresh'));
 
-		const ctxB = await browser.newContext();
-		const pageB = await ctxB.newPage();
-		watchErrors(pageB, errors);
-		await pageB.goto(BASE);
-		await signUp(pageB, uniq('bob'));
-		// A fresh user: empty textarea + empty display (which already proves bob
-		// never sees alice's note — an empty display cannot equal noteA).
-		await expect(pageB.getByTestId('note-textarea')).toHaveValue('', { timeout: T });
-		await expect(pageB.getByTestId('note-display')).toHaveText('', { timeout: T });
+		const { body } = await rpc(page.request, 'api.getNote', []);
+		expect(body?.error, `JSON-RPC error: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		expect(body?.result, 'getNote must return a string').toBe('');
 
-		await ctxA.close();
-		await ctxB.close();
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('saving again overwrites the note; only the latest value persists across reload', async ({ page }) => {
+	test('api.saveNote overwrites (does not append) and api.getNote reads it back', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signUp(page, uniq('alice'));
+
 		const first = uniq('first');
-		await page.getByTestId('note-textarea').fill(first);
-		await page.getByTestId('note-save').click();
-		await expect(page.getByTestId('note-display')).toHaveText(first, { timeout: T });
+		const s1 = await rpc(page.request, 'api.saveNote', [first]);
+		expect(s1.body?.error, `JSON-RPC error: ${JSON.stringify(s1.body?.error)}`).toBeFalsy();
+		await expect.poll(async () => (await rpc(page.request, 'api.getNote', [])).body?.result, { timeout: T }).toBe(first);
 
 		const second = uniq('second');
-		await page.getByTestId('note-textarea').fill(second); // fill() replaces existing content
-		await page.getByTestId('note-save').click();
-		await expect(page.getByTestId('note-display')).toHaveText(second, { timeout: T });
-
-		await page.reload();
-		// Exact-text match: an append-style impl would render `first` + `second`.
-		await expect(page.getByTestId('note-display')).toHaveText(second, { timeout: T });
+		const s2 = await rpc(page.request, 'api.saveNote', [second]);
+		expect(s2.body?.error, `JSON-RPC error: ${JSON.stringify(s2.body?.error)}`).toBeFalsy();
+		// Overwrite, not append — the stored value is exactly the second note.
+		expect((await rpc(page.request, 'api.getNote', [])).body?.result).toBe(second);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('saving an empty textarea clears the note, and the cleared state persists', async ({ page }) => {
+	test('saving an empty string clears the note (not a no-op)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signUp(page, uniq('alice'));
-		const note = uniq('note');
-		await page.getByTestId('note-textarea').fill(note);
-		await page.getByTestId('note-save').click();
-		await expect(page.getByTestId('note-display')).toHaveText(note, { timeout: T });
 
-		// An empty save is allowed and clears the note — not ignored.
-		await page.getByTestId('note-textarea').fill('');
-		await page.getByTestId('note-save').click();
-		await expect(page.getByTestId('note-display')).toHaveText('', { timeout: T });
-
-		await page.reload();
-		await expect(page.getByTestId('note-display')).toHaveText('', { timeout: T });
-		await expect(page.getByTestId('note-textarea')).toHaveValue('', { timeout: T });
+		await rpc(page.request, 'api.saveNote', [uniq('note')]);
+		const cleared = await rpc(page.request, 'api.saveNote', ['']);
+		expect(cleared.body?.error, `JSON-RPC error: ${JSON.stringify(cleared.body?.error)}`).toBeFalsy();
+		expect((await rpc(page.request, 'api.getNote', [])).body?.result).toBe('');
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('note text is rendered verbatim, not interpreted as HTML', async ({ page }) => {
+	test('notes are stored verbatim AND rendered as literal text — markup is never interpreted as HTML', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signUp(page, uniq('alice'));
-		// Contains markup; must render as literal characters, not a <b> element.
+
 		const raw = `<b>${uniq('x')}</b> & <i>plain</i>`;
+
+		// API round-trip: exact string equality — no HTML escaping (&amp;) and no stripping.
+		await rpc(page.request, 'api.saveNote', [raw]);
+		expect((await rpc(page.request, 'api.getNote', [])).body?.result).toBe(raw);
+
+		// DOM smoke (XSS): save the markup THROUGH the page and confirm note-display treats it as a
+		// literal string, not HTML. An unsafe `innerHTML = note` sink would parse the <b>/<i> into
+		// real child elements; a correct textContent render yields ZERO such nodes and the exact text.
 		await page.getByTestId('note-textarea').fill(raw);
 		await page.getByTestId('note-save').click();
 		await expect(page.getByTestId('note-display')).toHaveText(raw, { timeout: T });
-		// An innerHTML impl would create a real <b>; a text impl has none.
 		await expect(page.getByTestId('note-display').locator('b')).toHaveCount(0);
-
-		await page.reload();
-		await expect(page.getByTestId('note-display')).toHaveText(raw, { timeout: T });
+		await expect(page.getByTestId('note-display').locator('i')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('after reload the textarea is pre-filled with the saved note for editing', async ({ page }) => {
+	test('a long note round-trips unchanged through the api', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signUp(page, uniq('alice'));
-		const note = uniq('draft');
-		await page.getByTestId('note-textarea').fill(note);
-		await page.getByTestId('note-save').click();
-		await expect(page.getByTestId('note-display')).toHaveText(note, { timeout: T });
 
-		await page.reload();
-		// The editor must be repopulated (not blank) so the user can keep editing.
-		await expect(page.getByTestId('note-textarea')).toHaveValue(note, { timeout: T });
+		const note = (uniq('long') + ' ' + 'lorem ipsum dolor sit amet '.repeat(45)).trim();
+		await rpc(page.request, 'api.saveNote', [note]);
+		expect((await rpc(page.request, 'api.getNote', [])).body?.result).toBe(note);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a long note round-trips verbatim across reload', async ({ page }) => {
+	test('a missing / non-string argument is rejected and leaves the note unchanged', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
+		await signUp(page, uniq('alice'));
+
+		const keep = uniq('keep');
+		await rpc(page.request, 'api.saveNote', [keep]);
+
+		// No params at all.
+		const missing = await rpc(page.request, 'api.saveNote', undefined, { omitParams: true });
+		expect(missing.status, `unexpected HTTP ${missing.status}`).toBeLessThan(500);
+		expect(missing.body?.error, 'a missing argument must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(missing.body?.result ?? null).toBeNull();
+
+		// Non-string argument.
+		const nonString = await rpc(page.request, 'api.saveNote', [12345]);
+		expect(nonString.body?.error, 'a non-string argument must yield a JSON-RPC error envelope').toBeTruthy();
+
+		// The known-good note survived both rejections.
+		expect((await rpc(page.request, 'api.getNote', [])).body?.result).toBe(keep);
 
+		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	});
+
+	test('note methods require a session — an unauthenticated call is refused', async ({ page, request }) => {
+		const errors = watchErrors(page);
+		// Establish a real note as a signed-in user.
+		await page.goto(BASE);
 		await signUp(page, uniq('alice'));
-		// ~1.2k characters with a unique marker, exercising larger stored values.
-		const marker = uniq('long');
-		const note = (marker + ' ' + 'lorem ipsum dolor sit amet '.repeat(45)).trim();
-		await page.getByTestId('note-textarea').fill(note);
-		await page.getByTestId('note-save').click();
-		await expect(page.getByTestId('note-display')).toHaveText(note, { timeout: T });
+		await rpc(page.request, 'api.saveNote', [uniq('secret')]);
 
-		await page.reload();
-		await expect(page.getByTestId('note-display')).toHaveText(note, { timeout: T });
+		// The top-level `request` fixture carries NO sign-in cookie: the gated
+		// method must return an error envelope, never a result or someone's note.
+		const anon = await rpc(request, 'api.getNote', []);
+		expect(anon.status, `unexpected HTTP ${anon.status}`).toBeLessThan(500);
+		expect(anon.body?.error, 'an unauthenticated getNote must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(anon.body?.result ?? null).toBeNull();
+
+		const anonSave = await rpc(request, 'api.saveNote', ['hijack']);
+		expect(anonSave.body?.error, 'an unauthenticated saveNote must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(anonSave.body?.result ?? null).toBeNull();
+
+		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	});
+
+	test('per-user isolation: each user\u2019s api.getNote returns only their own note', async ({ browser }) => {
+		const errors: string[] = [];
 
+		const ctxA = await browser.newContext();
+		const pageA = await ctxA.newPage();
+		watchErrors(pageA, errors);
+		await pageA.goto(BASE);
+		await signUp(pageA, uniq('alice'));
+		const noteA = uniq('alice-secret');
+		await rpc(pageA.request, 'api.saveNote', [noteA]);
+
+		const ctxB = await browser.newContext();
+		const pageB = await ctxB.newPage();
+		watchErrors(pageB, errors);
+		await pageB.goto(BASE);
+		await signUp(pageB, uniq('bob'));
+		// Bob's note is empty and is NOT alice's.
+		expect((await rpc(pageB.request, 'api.getNote', [])).body?.result).toBe('');
+		const noteB = uniq('bob-secret');
+		await rpc(pageB.request, 'api.saveNote', [noteB]);
+
+		// Each user still sees only their own note.
+		expect((await rpc(pageA.request, 'api.getNote', [])).body?.result).toBe(noteA);
+		expect((await rpc(pageB.request, 'api.getNote', [])).body?.result).toBe(noteB);
+
+		await ctxA.close();
+		await ctxB.close();
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 });
diff --git a/tasks/cognito-profile/PROMPT.md b/tasks/cognito-profile/PROMPT.md
index b4925d2e..0f8cac19 100644
--- a/tasks/cognito-profile/PROMPT.md
+++ b/tasks/cognito-profile/PROMPT.md
@@ -2,9 +2,11 @@
 
 Build a passwordless sign-in flow in this AWS Blocks app. A visitor enters their email, receives a one-time code, enters the code, and lands on a profile page that shows who they're signed in as. They can sign out.
 
+The sign-in flow is an intrinsically multi-view browser experience, but the signed-in **identity** is a framework surface: an **`api` namespace** method reads the current user from the **auth session** on the server. The page reflects that identity.
+
 ## Setup (do this first)
 
-The workspace has already been scaffolded. Begin by reading README.md, then do all your edits in this workspace.
+The workspace has already been scaffolded. Begin by reading README.md (and any AGENTS.md), then do all your edits in this workspace.
 
 ## Requirements
 
@@ -12,27 +14,26 @@ The workspace has already been scaffolded. Begin by reading README.md, then do a
 2. The view then shows a **code field** and its own **submit button**. Submitting the code completes authentication and establishes a session.
 3. Once authenticated, the visitor sees a **profile** view that renders the signed-in user's identity (their email / username) — and the email/code fields are gone.
 4. The profile view has a **sign-out** button that returns the visitor to the signed-out email form.
-5. **Reject bad codes.** If the submitted code is wrong **or blank/empty**, catch the error and stay on the code-entry view — do **not** establish a session or throw an unhandled error. When a code is actually rejected, show a message in `[data-testid=auth-error]`; that hook must be **absent until a code is rejected** (don't render an empty error element on the fresh code-entry view). A wrong code does **not** end the attempt: the verification session stays valid (retriable), so the visitor can immediately re-enter the **correct** code on the same view and sign in — and once they do, the error must be **cleared** (`auth-error` is removed again).
-6. **Session persistence.** The session lives in a cookie: on a full page reload the visitor stays signed in and the profile re-renders their identity (restore it on load). The signed-out and code-entry hooks must be absent while signed in.
+5. **Reject bad codes.** If the submitted code is wrong **or blank/empty**, catch the error and stay on the code-entry view — do **not** establish a session or throw an unhandled error. When a code is actually rejected, show a message in `[data-testid=auth-error]`; that hook must be **absent until a code is rejected**. A wrong code does **not** end the attempt: the verification session stays valid (retriable), so the visitor can immediately re-enter the **correct** code and sign in — and once they do, the error must be **cleared** (`auth-error` removed again).
+6. **Session persistence.** The session lives in a cookie: on a full page reload the visitor stays signed in and the profile re-renders their identity (restore it on load).
 7. **Clean sign-out.** Signing out fully clears the session so a *different* email can sign in afterward and the profile shows the new identity (no stale cached user). A full page reload **after** signing out must **not** restore the session — it stays on the signed-out email form.
 
-This is email-OTP / passwordless: the visitor never types a password. One identifier (the email) on the way in, then the emailed code.
+This is email-OTP / passwordless: the visitor never types a password.
 
-## Test harness contract (required)
+## The `api` namespace (required)
 
-The grader has no mailbox, so it reads the OTP over JSON-RPC. **Expose an `api` namespace method `getLastCode()`** that returns the most recently delivered code as `{ username, code }` (or `null`). The grader retrieves it by POSTing to `/aws-blocks/api`:
+Expose an **`api` namespace** (the framework's server-side RPC surface — `POST /aws-blocks/api`) with:
 
-```
-POST /aws-blocks/api
-Content-Type: application/json
-{ "jsonrpc": "2.0", "method": "api.getLastCode", "params": [], "id": 1 }
-```
+1. **`api.getLastCode()`** — test harness hook (the grader has no mailbox): returns the most recently delivered code as `{ username, code }` (or `null`). **This is a test-only backdoor and MUST NOT be a production attack surface:** annotate it `@blocksSkipCodegen` (keep it out of the generated client/types) and gate its body so it returns `null` unless `process.env.BLOCKS_MOCK === 'true'`. Under real Cognito the code is emailed and never retained, so outside mock/test mode this method must reveal nothing. The bench harness runs the dev server with `BLOCKS_MOCK=true`, so the grader can still read the code. Retrieved via:
+   ```
+   POST /aws-blocks/api
+   { "jsonrpc": "2.0", "method": "api.getLastCode", "params": [], "id": 1 }
+   ```
+2. **`api.whoami()`** — returns the **currently signed-in** user's identity as `{ username }` (their email), derived on the server from the **auth session cookie** — not from a client-supplied argument. Called with **no session** (a request carrying no sign-in cookie), it returns a JSON-RPC **error** envelope (unauthenticated) — never a `result` and never a stale/other identity. After sign-out the session is gone, so `whoami` is again unauthenticated.
 
 ## Selector contract
 
-The Playwright test grades your work using these `data-testid` hooks. Implement them exactly. The signed-out, code-entry, and signed-in views are told apart by which hooks are present.
-
-An inactive view's hooks must be REMOVED from the DOM (the grader asserts `toHaveCount(0)`); hiding them with CSS (`display:none` / `hidden`) will fail.
+The Playwright test grades your work using these `data-testid` hooks. Implement them exactly. The signed-out, code-entry, and signed-in views are told apart by which hooks are present. An inactive view's hooks must be **removed** from the DOM (not merely hidden with CSS).
 
 | Selector | Element | Purpose |
 |---|---|---|
@@ -59,3 +60,4 @@ The mount point for your page is the existing root element. You can replace what
 - All Playwright assertions pass against the running dev server.
 - No errors in the browser console under normal use.
 - Your changes stay inside the workspace root. Don't modify anything under `node_modules/`.
+- **Source inspection (grader; behaviorally unverifiable at runtime):** confirm in the source that `api.getLastCode` returns `null` unless `process.env.BLOCKS_MOCK === 'true'` — i.e. the production OTP-reader gate actually exists. The bench always runs with `BLOCKS_MOCK=true`, so this prod-gate branch is never exercised by the Playwright grader and must be verified by reading the code.
diff --git a/tasks/cognito-profile/test.spec.ts b/tasks/cognito-profile/test.spec.ts
index b8b89684..f08a4af5 100644
--- a/tasks/cognito-profile/test.spec.ts
+++ b/tasks/cognito-profile/test.spec.ts
@@ -1,33 +1,38 @@
 import { test, expect, type APIRequestContext, type Page } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const T = 10_000;
 
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: ONLY uncaught page errors. The local dev server
-// returns HTTP 200 for JSON-RPC errors, so legitimate pre-auth errors never
-// trip the gate.
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
+async function rpc(
+	ctx: APIRequestContext,
+	method: string,
+	params: unknown[] = [],
+): Promise<{ status: number; body: any }> {
+	const res = await ctx.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data: { jsonrpc: '2.0', method, params, id: ++rpcSeq },
+	});
+	return { status: res.status(), body: await res.json().catch(() => null) };
+}
+
 // The grader has no mailbox: it reads the most-recently delivered OTP over the
-// same local JSON-RPC endpoint the app uses, by calling `api.getLastCode()`.
+// same JSON-RPC endpoint via api.getLastCode().
 async function fetchOtp(request: APIRequestContext, user: string): Promise<string> {
 	let code = '';
 	await expect
 		.poll(
 			async () => {
-				const res = await request.post(`${BASE}/aws-blocks/api`, {
-					headers: { 'Content-Type': 'application/json' },
-					data: { jsonrpc: '2.0', method: 'api.getLastCode', params: [], id: Date.now() },
-				});
-				if (!res.ok()) return '';
-				const body = await res.json().catch(() => null);
+				const { body } = await rpc(request, 'api.getLastCode', []);
 				const last = body?.result;
 				if (last && typeof last.code === 'string' && String(last.username ?? '').includes(user)) {
 					code = last.code;
@@ -35,7 +40,7 @@ async function fetchOtp(request: APIRequestContext, user: string): Promise<strin
 				}
 				return '';
 			},
-			{ timeout: T },
+			{ timeout: T, message: 'OTP not delivered — check api.getLastCode returns { code, username } in mock mode' },
 		)
 		.not.toBe('');
 	return code;
@@ -48,7 +53,8 @@ async function requestCode(page: Page, email: string): Promise<void> {
 	await expect(page.getByTestId('otp-input')).toBeVisible({ timeout: T });
 }
 
-// Drive the full passwordless flow and return the email that signed in.
+// Drive the full passwordless flow; returns the email that signed in. After
+// this the page's cookie jar is authenticated (page.request calls whoami as it).
 async function signIn(page: Page, request: APIRequestContext, user: string): Promise<string> {
 	const email = `${user}@test.com`;
 	await requestCode(page, email);
@@ -59,141 +65,142 @@ async function signIn(page: Page, request: APIRequestContext, user: string): Pro
 	return email;
 }
 
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
 test.describe('cognito-profile', () => {
-	test('signed-out visitor sees the email field and submit button', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('auth-submit')).toBeVisible();
-		// Code-entry and signed-in hooks are absent before anything is submitted.
-		await expect(page.getByTestId('otp-input')).toHaveCount(0);
-		await expect(page.getByTestId('profile-username')).toHaveCount(0);
+	// --- Framework surface: identity from the auth session over the api ---
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('api.getLastCode is live in mock mode (the grader can read the OTP) and never errors', async ({ request }) => {
+		// The OTP-reader hook is a mock-only backdoor: the PROMPT requires it to gate on
+		// BLOCKS_MOCK and return null in a real deployment. This grader can only exercise the
+		// LIVE (mock) side — the bench always runs with BLOCKS_MOCK=true (3-build-and-test.sh),
+		// so the production-gate branch (getLastCode → null when the flag is unset) never runs
+		// here. That gate is PROMPT-enforced and codegen-skipped but grader-UNVERIFIED; asserting
+		// it under a `else` that can never execute would be a misleading dead assertion, so we
+		// assert only what the bench actually reaches: in mock mode the call must succeed (so the
+		// OTP flow is graded) and must never surface a JSON-RPC error envelope.
+		const { status, body } = await rpc(request, 'api.getLastCode', []);
+		expect(status, `unexpected HTTP ${status}`).toBeLessThan(500);
+		expect(body?.error, `getLastCode must not error in mock mode: ${JSON.stringify(body?.error)}`).toBeFalsy();
 	});
 
-	test('submitting an email advances to the code-entry view', async ({ page }) => {
+	test('api.whoami reflects the signed-in identity and is gated to authenticated callers', async ({ page, request }) => {
 		const errors = watchErrors(page);
+		// Unauthenticated (top-level request, no cookie): refused.
+		const anon = await rpc(request, 'api.whoami', []);
+		expect(anon.status, `unexpected HTTP ${anon.status}`).toBeLessThan(500);
+		expect(anon.body?.error, 'unauthenticated whoami must yield an error envelope').toBeTruthy();
+		expect(anon.body?.result ?? null).toBeNull();
+
 		await page.goto(BASE);
+		const email = await signIn(page, request, uniq('user'));
 
-		await requestCode(page, `${uniq('user')}@test.com`);
-		await expect(page.getByTestId('otp-submit')).toBeVisible();
-		await expect(page.getByTestId('auth-email')).toHaveCount(0);
+		// Authenticated (page.request shares the sign-in cookie): returns identity.
+		const me = await rpc(page.request, 'api.whoami', []);
+		expect(me.body?.error, `JSON-RPC error: ${JSON.stringify(me.body?.error)}`).toBeFalsy();
+		expect(String(me.body?.result?.username)).toContain(email);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('completing the OTP lands on a profile with a sign-out button', async ({ page, request }) => {
+	test('after sign-out the session is gone — api.whoami is unauthenticated again', async ({ page, request }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
+		await signIn(page, request, uniq('user'));
+		const before = await rpc(page.request, 'api.whoami', []);
+		expect(before.body?.result?.username, 'whoami must be authenticated before sign-out').toBeTruthy();
 
-		const user = uniq('user');
-		await signIn(page, request, user);
-		await expect(page.getByTestId('profile-username')).toContainText(user, { timeout: T });
-		await expect(page.getByTestId('signout-btn')).toBeVisible();
-		// Signed-in view hides the email/code inputs.
-		await expect(page.getByTestId('auth-email')).toHaveCount(0);
-		await expect(page.getByTestId('otp-input')).toHaveCount(0);
+		await page.getByTestId('signout-btn').click();
+		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
+
+		const after = await rpc(page.request, 'api.whoami', []);
+		expect(after.body?.error, 'whoami must be unauthenticated after sign-out').toBeTruthy();
+		expect(after.body?.result ?? null).toBeNull();
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('the profile renders the exact email that signed in', async ({ page, request }) => {
+	// --- Page smoke: the multi-view OTP flow ---
+
+	test('signed-out visitor sees the email field; code/profile hooks are absent', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		const email = await signIn(page, request, uniq('user'));
-		await expect(page.getByTestId('profile-username')).toContainText(email, { timeout: T });
+		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
+		await expect(page.getByTestId('auth-submit')).toBeVisible();
+		await expect(page.getByTestId('otp-input')).toHaveCount(0);
+		await expect(page.getByTestId('profile-username')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('signing out returns to the signed-out email form', async ({ page, request }) => {
+	test('completing the OTP flow lands on a profile with the exact email and a sign-out button', async ({ page, request }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		await signIn(page, request, uniq('user'));
-		await page.getByTestId('signout-btn').click();
-		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('profile-username')).toHaveCount(0);
+		const email = await signIn(page, request, uniq('user'));
+		await expect(page.getByTestId('profile-username')).toContainText(email, { timeout: T });
+		await expect(page.getByTestId('signout-btn')).toBeVisible();
+		await expect(page.getByTestId('auth-email')).toHaveCount(0);
+		await expect(page.getByTestId('otp-input')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('an incorrect code is rejected and does not establish a session', async ({ page, request }) => {
+	test('a wrong code is rejected (error shown, no session); the correct code then signs in and clears the error', async ({ page, request }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		const user = uniq('user');
+		const user = uniq('retry');
 		await requestCode(page, `${user}@test.com`);
-		// Fetch the genuinely-delivered code, then submit a guaranteed-different
-		// one so the rejection is deterministic (not a lucky-guess collision).
+		// auth-error is absent on the fresh code-entry view.
+		await expect(page.getByTestId('auth-error')).toHaveCount(0);
+
 		const real = await fetchOtp(request, user);
 		const wrong = real === '000000' ? '111111' : '000000';
 		await page.getByTestId('otp-input').fill(wrong);
 		await page.getByTestId('otp-submit').click();
-
-		// A wrong code must surface an error and leave the visitor on the
-		// code-entry view — no session is established. (The local dev server
-		// returns JSON-RPC errors as HTTP 200, so a HANDLED rejection never trips
-		// the page-error gate; only an unhandled rejection would.)
 		await expect(page.getByTestId('auth-error')).toBeVisible({ timeout: T });
 		await expect(page.getByTestId('profile-username')).toHaveCount(0);
-		await expect(page.getByTestId('otp-input')).toBeVisible();
+
+		// Retriable: the real code on the same view signs in and clears the error.
+		await page.getByTestId('otp-input').fill(real);
+		await page.getByTestId('otp-submit').click();
+		await expect(page.getByTestId('profile-username')).toContainText(`${user}@test.com`, { timeout: T });
+		await expect(page.getByTestId('auth-error')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('the session persists across a full page reload', async ({ page, request }) => {
+	test('the session persists across reload, and sign-out + reload stays signed out', async ({ page, request }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
 		const email = await signIn(page, request, uniq('user'));
-		// The session lives in a cookie — a reload must restore it: still signed
-		// in, same identity, and the signed-out forms stay absent.
 		await page.reload();
-		await expect(page.getByTestId('profile-username')).toBeVisible({ timeout: T });
 		await expect(page.getByTestId('profile-username')).toContainText(email, { timeout: T });
 		await expect(page.getByTestId('auth-email')).toHaveCount(0);
-		await expect(page.getByTestId('otp-input')).toHaveCount(0);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('signing out fully clears the session so a different user can sign in', async ({ page, request }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
 
-		const firstEmail = await signIn(page, request, uniq('user'));
-		await expect(page.getByTestId('profile-username')).toContainText(firstEmail, { timeout: T });
+		// Sign out the (cookie-restored) session; a reload must NOT resurrect it.
 		await page.getByTestId('signout-btn').click();
 		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
-
-		// A second, DIFFERENT identity signs in on the same page; the profile must
-		// render the NEW user, never a stale identity cached from the first session.
-		const secondEmail = await signIn(page, request, uniq('user'));
-		await expect(page.getByTestId('profile-username')).toContainText(secondEmail, { timeout: T });
-		await expect(page.getByTestId('profile-username')).not.toContainText(firstEmail, { timeout: T });
+		await page.reload();
+		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
+		await expect(page.getByTestId('profile-username')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a returning user can sign in again with the SAME email after signing out', async ({ page, request }) => {
+	test('a returning user signs in again with the SAME email after signing out', async ({ page, request }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		// First visit establishes the account (sign-up → confirm → session).
 		const user = uniq('returning');
 		const email = await signIn(page, request, user);
-		await expect(page.getByTestId('profile-username')).toContainText(email, { timeout: T });
 		await page.getByTestId('signout-btn').click();
 		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
 
-		// Second visit with the SAME email: the account already exists, so a
-		// sign-up-ONLY impl throws "user already exists" here. A correct app
-		// detects the existing user and runs the sign-in OTP path, landing a
-		// session for the same identity.
+		// The account already exists → a sign-up-ONLY impl throws here; a correct
+		// app detects the existing user and runs the sign-in OTP path.
 		const email2 = await signIn(page, request, user);
 		expect(email2).toBe(email);
 		await expect(page.getByTestId('profile-username')).toContainText(email, { timeout: T });
@@ -201,138 +208,36 @@ test.describe('cognito-profile', () => {
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('after sign-out, a full reload stays signed out (session fully cleared, not resurrected)', async ({ page, request }) => {
+	test('a different user signing in after sign-out never leaks the prior identity', async ({ page, request }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		await signIn(page, request, uniq('user'));
+		const firstEmail = await signIn(page, request, uniq('user'));
 		await page.getByTestId('signout-btn').click();
 		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
 
-		// The cookie/session must be gone: a reload must NOT restore the profile.
-		// An impl that only flips a client flag (without calling the block's
-		// signOut) leaves the cookie behind, and the profile reappears here.
-		await page.reload();
-		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('profile-username')).toHaveCount(0);
-		await expect(page.getByTestId('signout-btn')).toHaveCount(0);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('the error hook is absent on the fresh code-entry view (before any rejection)', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		await requestCode(page, `${uniq('user')}@test.com`);
-		// Per the contract, auth-error is absent until a code is actually
-		// rejected — an always-rendered (empty) error element fails here.
-		await expect(page.getByTestId('otp-submit')).toBeVisible();
-		await expect(page.getByTestId('auth-error')).toHaveCount(0);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('submitting a blank code does not establish a session', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		await requestCode(page, `${uniq('user')}@test.com`);
-		// Submit with no code typed. force:true so the assertion holds whether the
-		// app disables the button until a code is entered (click is a no-op) or
-		// validates on submit (must catch, not throw). Either way: no session.
-		await page.getByTestId('otp-submit').click({ force: true });
-		await expect(page.getByTestId('profile-username')).toHaveCount(0);
-		await expect(page.getByTestId('otp-input')).toBeVisible();
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('a rejected code clears its error once the correct code is accepted (retriable session)', async ({ page, request }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const user = uniq('retry');
-		await requestCode(page, `${user}@test.com`);
-		const real = await fetchOtp(request, user);
-		const wrong = real === '000000' ? '111111' : '000000';
-
-		// A wrong code surfaces the error and keeps us on code-entry.
-		await page.getByTestId('otp-input').fill(wrong);
-		await page.getByTestId('otp-submit').click();
-		await expect(page.getByTestId('auth-error')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('profile-username')).toHaveCount(0);
-
-		// CodeMismatch keeps the verification session valid (retriable): entering
-		// the REAL code on the same view must sign in AND clear the stale error.
-		await page.getByTestId('otp-input').fill(real);
-		await page.getByTestId('otp-submit').click();
-		await expect(page.getByTestId('profile-username')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('profile-username')).toContainText(user, { timeout: T });
-		await expect(page.getByTestId('auth-error')).toHaveCount(0);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('three sequential sign-in/out cycles never leak a prior identity', async ({ page, request }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		let prev = '';
-		for (let i = 0; i < 3; i++) {
-			const email = await signIn(page, request, uniq('cycle'));
-			await expect(page.getByTestId('profile-username')).toContainText(email, { timeout: T });
-			// The freshly signed-in profile must never still show the prior identity.
-			if (prev) await expect(page.getByTestId('profile-username')).not.toContainText(prev, { timeout: T });
-
-			await page.getByTestId('signout-btn').click();
-			await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
-			await expect(page.getByTestId('profile-username')).toHaveCount(0);
-			prev = email;
-		}
+		const secondEmail = await signIn(page, request, uniq('user'));
+		await expect(page.getByTestId('profile-username')).toContainText(secondEmail, { timeout: T });
+		await expect(page.getByTestId('profile-username')).not.toContainText(firstEmail, { timeout: T });
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a blank / whitespace-only email does not begin auth', async ({ page }) => {
+	test('blank inputs never begin auth or establish a session', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
+		// Blank email: stay on the email form, no code view.
 		await page.getByTestId('auth-email').fill('   ');
-		// force:true so this holds whether the app disables submit until a valid
-		// email is entered (no-op click) or validates on submit (must catch, not
-		// advance). Either way: no code sent, stay on the email form.
 		await page.getByTestId('auth-submit').click({ force: true });
-
 		await expect(page.getByTestId('auth-email')).toBeVisible();
 		await expect(page.getByTestId('otp-input')).toHaveCount(0);
-		await expect(page.getByTestId('profile-username')).toHaveCount(0);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('a cookie-restored session signs out cleanly and does not leak into the next identity', async ({ page, request }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const firstEmail = await signIn(page, request, uniq('restore'));
-		// Reload so the signed-in state comes purely from the restored cookie/
-		// session — not the in-memory result of the sign-in call.
-		await page.reload();
-		await expect(page.getByTestId('profile-username')).toContainText(firstEmail, { timeout: T });
 
-		// Signing out the RESTORED session must fully clear it (an impl that only
-		// cleared a client variable set during sign-in would fail: that variable
-		// is empty after the reload, so its signOut is a no-op and the cookie stays).
-		await page.getByTestId('signout-btn').click();
-		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
+		// Advance with a real email, then submit a blank code: no session.
+		await requestCode(page, `${uniq('user')}@test.com`);
+		await page.getByTestId('otp-submit').click({ force: true });
 		await expect(page.getByTestId('profile-username')).toHaveCount(0);
-
-		// A different identity signs in; the profile shows only the new user.
-		const secondEmail = await signIn(page, request, uniq('restore'));
-		await expect(page.getByTestId('profile-username')).toContainText(secondEmail, { timeout: T });
-		await expect(page.getByTestId('profile-username')).not.toContainText(firstEmail, { timeout: T });
+		await expect(page.getByTestId('otp-input')).toBeVisible();
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
diff --git a/tasks/collab-presence-board/PROMPT.md b/tasks/collab-presence-board/PROMPT.md
index 0bbd972d..b8dbec09 100644
--- a/tasks/collab-presence-board/PROMPT.md
+++ b/tasks/collab-presence-board/PROMPT.md
@@ -2,31 +2,39 @@
 
 Build a shared presence board in this AWS Blocks app. Each visitor picks a name and "joins"; everyone with the app open sees the live roster of who's present, updated in real time. The roster also survives a page reload.
 
+The shared board itself — registering, deduping, storing, and reading back the roster — must run through an **`api` namespace** backed by real framework blocks (a **distributed-table** block for the durable roster, a **realtime** block for fan-out). The page is a thin client over that API plus the realtime channel.
+
 ## Setup (do this first)
 
 The workspace has already been scaffolded. Begin by reading README.md, then do all your edits in this workspace.
 
 ## Requirements
 
-1. A visitor sees a name field and a join button.
-2. Submitting the name registers the visitor on the shared presence board and adds a row for them. Presence is **keyed by name**: joining with a name that is already present does **not** create a duplicate row — the board shows at most one row per name.
-3. **Realtime:** when one tab/visitor joins, every other open tab reflects the new presence within a couple of seconds — no manual refresh.
-4. The presence row for a given visitor renders that visitor's name.
-5. **Persistence:** the board is stored so that after a full page reload **every** present visitor is still shown — restore the whole shared roster, not just the visitor who joined in this tab. A freshly-opened tab must also load the current roster on first paint (fetch the stored board on load): a tab opened *after* others joined sees them immediately, not a blank board that only fills in on the next realtime event.
-6. **Input validation:** disable `[data-testid=join-btn]` whenever the name field is empty or whitespace-only (trim before the check); re-enable it once a real name is present.
-7. **Untrusted names:** names are visitor-supplied — render them as **text**, never as markup. A name like `<b>x</b>` must appear literally as text and must not create a real `<b>` element (no `innerHTML` injection). Non-ASCII and emoji names (e.g. `日本語 🙂`) must render correctly as text.
+### The `api` namespace (authoritative shared board)
+
+Expose an **`api` namespace** (the framework's server-side RPC surface — `POST /aws-blocks/api`) with:
+
+- **`api.join(name)`** — registers `name` on the shared board (persisting it via the **distributed-table** block) and broadcasts the change over the **realtime** block. **Keyed by name:** joining a name that is already present must **not** create a duplicate — the roster holds at most one entry per name. The name is stored and returned **verbatim** (a name like `<b>x</b>` is preserved literally as text; non-ASCII / emoji preserved exactly). A blank or whitespace-only `name` is rejected with a JSON-RPC **error** envelope and does not change the roster.
+- **`api.listPresent()`** — returns the current shared roster as an array `[{ name }]` read from the store. Because the roster is persisted, a fresh caller (or a freshly-loaded tab) sees everyone who has joined — not a blank board.
+
+### Realtime + persistence
+1. **Realtime:** when one tab/visitor joins, every other open tab reflects the new presence within a couple of seconds — no manual refresh (driven by the realtime block's broadcast).
+2. **Persistence / first paint:** on load the page fetches the stored roster via `api.listPresent()` and renders it, so a tab opened *after* others joined sees them immediately, and a reload restores the whole shared roster.
+
+### Chat UI (thin client / light smoke)
+3. A visitor sees a name field `[data-testid=presence-name-input]` and a join button `[data-testid=join-btn]`. Submitting the name calls `api.join`; a `[data-testid=presence-item]` row appears for each present visitor, rendering that visitor's name.
+4. **Input validation:** disable `[data-testid=join-btn]` whenever the name field is empty or whitespace-only (trim before the check); re-enable it once a real name is present.
+5. **Untrusted names:** render visitor names as **text**, never as markup — a name like `<b>x</b>` must appear literally and must not create a real `<b>` element (no `innerHTML` injection).
 
 A single shared board across all tabs — no login, no per-user filtering.
 
 ## Selector contract
 
-The Playwright test grades your work using these `data-testid` hooks. Implement them exactly.
-
 | Selector | Element | Purpose |
 |---|---|---|
 | `[data-testid=presence-name-input]` | `<input type="text">` | Where the visitor types their presence name |
-| `[data-testid=join-btn]` | `<button>` | Registers the typed name on the shared board |
-| `[data-testid=presence-item]` | one per present visitor | The row for a single present visitor |
+| `[data-testid=join-btn]` | `<button>` | Registers the typed name (`api.join`) on the shared board |
+| `[data-testid=presence-item]` | one per present visitor | The row for a single present visitor; renders the name as its text |
 
 Each `[data-testid=presence-item]` must render the visitor's name as its text (the test locates a visitor by `filter({ hasText: name })`).
 
diff --git a/tasks/collab-presence-board/test.spec.ts b/tasks/collab-presence-board/test.spec.ts
index d2e349ab..1f5c5270 100644
--- a/tasks/collab-presence-board/test.spec.ts
+++ b/tasks/collab-presence-board/test.spec.ts
@@ -1,124 +1,119 @@
-import { test, expect, type Page } from '@playwright/test';
+import { test, expect, type Page, type APIRequestContext } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const SYNC = 8_000;
 
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: ONLY uncaught page errors.
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
-const presence = (page: Page, name: string) => page.getByTestId('presence-item').filter({ hasText: name });
-
-async function join(page: Page, name: string): Promise<void> {
-	await expect(page.getByTestId('presence-name-input')).toBeVisible({ timeout: SYNC });
-	await page.getByTestId('presence-name-input').fill(name);
-	await page.getByTestId('join-btn').click();
+async function rpc(
+	ctx: APIRequestContext,
+	method: string,
+	params: unknown[] = [],
+): Promise<{ status: number; body: any }> {
+	const res = await ctx.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data: { jsonrpc: '2.0', method, params, id: ++rpcSeq },
+	});
+	return { status: res.status(), body: await res.json().catch(() => null) };
 }
 
-test.describe('collab-presence-board', () => {
-	test('shows the name input and the join button', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+const join = (ctx: APIRequestContext, name: string) => rpc(ctx, 'api.join', [name]);
 
-		await expect(page.getByTestId('presence-name-input')).toBeVisible();
-		await expect(page.getByTestId('join-btn')).toBeVisible();
+async function roster(ctx: APIRequestContext): Promise<string[]> {
+	const { body } = await rpc(ctx, 'api.listPresent', []);
+	const rows = Array.isArray(body?.result) ? body.result : [];
+	return rows.map((r: any) => String(r?.name ?? r));
+}
+// The shared board holds every name every test joins, so scope roster reads to
+// this call's own unique names rather than asserting on absolute counts. The
+// `count(...) === 1` assertions below are race-free only because the harness
+// runs specs serially (fullyParallel:false / workers:1 in
+// scripts/agent-bench/steps/3-build-and-test.sh); moving to >1 worker would
+// require reworking them to tolerate concurrent joins of the same unique name.
+const count = (names: string[], name: string) => names.filter((n) => n === name).length;
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
+const presence = (page: Page, name: string) => page.getByTestId('presence-item').filter({ hasText: name });
 
-	test('joining adds a presence row rendering the visitor name', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
+test.describe('collab-presence-board', () => {
+	// --- Framework surface: the shared board runs through the api ---
 
+	test('api.join registers a visitor and api.listPresent reads them back from the store', async ({ request }) => {
 		const name = uniq('user');
-		await join(page, name);
-		await expect(presence(page, name)).toHaveCount(1, { timeout: SYNC });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		const j = await join(request, name);
+		expect(j.body?.error, `join error: ${JSON.stringify(j.body?.error)}`).toBeFalsy();
+		expect(count(await roster(request), name)).toBe(1);
 	});
 
-	test('a new join appears in another already-open tab in real time', async ({ browser }) => {
-		const errors: string[] = [];
-		const ctxA = await browser.newContext();
-		const ctxB = await browser.newContext();
-		const tabA = await ctxA.newPage();
-		const tabB = await ctxB.newPage();
-		watchErrors(tabA, errors);
-		watchErrors(tabB, errors);
-
-		await tabA.goto(BASE);
-		await tabB.goto(BASE);
-
-		const name = uniq('user');
-		await join(tabA, name);
-
-		// Tab B had the board open before A joined; it must reflect A's presence
-		// within a couple seconds — realtime, no reload.
-		await expect.poll(() => presence(tabB, name).count(), { timeout: SYNC }).toBe(1);
-
-		await ctxA.close();
-		await ctxB.close();
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('presence is keyed by name — a repeat join never duplicates the roster row', async ({ request }) => {
+		const name = uniq('dup');
+		await join(request, name);
+		await join(request, name);
+		await join(request, name);
+		expect(count(await roster(request), name), 'name-keyed board must hold at most one row per name').toBe(1);
 	});
 
-	test('the roster persists across a full reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const name = uniq('user');
-		await join(page, name);
-		await expect(presence(page, name)).toHaveCount(1, { timeout: SYNC });
-
-		await page.reload();
-		await expect(presence(page, name)).toHaveCount(1, { timeout: SYNC });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('names round-trip verbatim through the store', async ({ request }) => {
+		const name = `${uniq('xss')} <b>BOOM</b>`;
+		await join(request, name);
+		const names = await roster(request);
+		// The exact string round-trips — no escaping, stripping, or mutation server-side.
+		expect(names).toContain(name);
 	});
 
-	test('two visitors with different names both appear on the board', async ({ browser }) => {
-		const errors: string[] = [];
-		const ctxA = await browser.newContext();
-		const ctxB = await browser.newContext();
-		const tabA = await ctxA.newPage();
-		const tabB = await ctxB.newPage();
-		watchErrors(tabA, errors);
-		watchErrors(tabB, errors);
-
-		await tabA.goto(BASE);
-		await tabB.goto(BASE);
+	test('a unicode / emoji name round-trips byte-for-byte', async ({ request }) => {
+		const name = `${uniq('uni')} 日本語 🙂`;
+		await join(request, name);
+		expect(await roster(request)).toContain(name);
+	});
 
-		const nameA = uniq('ann');
-		const nameB = uniq('bob');
-		await join(tabA, nameA);
-		await join(tabB, nameB);
+	test('a blank or whitespace-only name is rejected and does not change the roster', async ({ request }) => {
+		// A real name of our own, so we can assert on OUR entry rather than the
+		// shared roster's absolute length (which other workers/tests mutate).
+		const mine = uniq('valid');
+		await join(request, mine);
+		expect(count(await roster(request), mine)).toBe(1);
+
+		const bads = ['', '   ', '\t\n'];
+		for (const bad of bads) {
+			const j = await join(request, bad);
+			expect(j.status, `unexpected HTTP ${j.status}`).toBeLessThan(500);
+			expect(j.body?.error, `blank name must be rejected, got result ${JSON.stringify(j.body?.result)}`).toBeTruthy();
+		}
 
-		// Each tab eventually sees both rosters via realtime sync.
-		await expect.poll(() => presence(tabA, nameA).count(), { timeout: SYNC }).toBe(1);
-		await expect.poll(() => presence(tabA, nameB).count(), { timeout: SYNC }).toBe(1);
-		await expect.poll(() => presence(tabB, nameA).count(), { timeout: SYNC }).toBe(1);
-		await expect.poll(() => presence(tabB, nameB).count(), { timeout: SYNC }).toBe(1);
+		// No phantom entry was added by the rejected joins, and our own valid entry
+		// is untouched — neither depends on the global roster length.
+		const after = await roster(request);
+		for (const bad of bads) expect(after, `rejected input ${JSON.stringify(bad)} leaked into the roster`).not.toContain(bad);
+		expect(count(after, mine), 'the rejected joins must not disturb this visitor\u2019s entry').toBe(1);
+	});
 
-		await ctxA.close();
-		await ctxB.close();
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('multiple distinct visitors all persist in the shared roster', async ({ request }) => {
+		const names = [uniq('m1'), uniq('m2'), uniq('m3')];
+		for (const n of names) await join(request, n);
+		const present = await roster(request);
+		for (const n of names) expect(count(present, n), `${n} missing from roster`).toBe(1);
 	});
 
-	test('the join button is disabled until a non-empty name is entered', async ({ page }) => {
+	// --- Page smoke: thin client renders + primary control ---
+
+	test('renders the composer; join is disabled until a real name is typed', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
 		const input = page.getByTestId('presence-name-input');
 		const joinBtn = page.getByTestId('join-btn');
-		await expect(input).toBeVisible();
+		await expect(input).toBeVisible({ timeout: SYNC });
+		await expect(joinBtn).toBeVisible();
 
-		// Empty and whitespace-only names cannot be joined (trim before checking);
-		// a real name re-enables the control so it isn't simply always-disabled.
 		await input.fill('');
 		await expect(joinBtn).toBeDisabled();
 		await input.fill('   ');
@@ -129,85 +124,62 @@ test.describe('collab-presence-board', () => {
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a visitor name with markup is rendered as text, not injected as HTML', async ({ page }) => {
+	test('joining from the UI adds a row; a markup name renders as text, not injected HTML', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		// Names are untrusted. A correct impl renders the name as text (escaped);
-		// one that uses innerHTML would parse this into a real <b> element.
 		const token = uniq('xss');
 		const name = `${token} <b>BOOM</b>`;
-		await join(page, name);
+		await page.getByTestId('presence-name-input').fill(name);
+		await page.getByTestId('join-btn').click();
 
-		// Scope by the clean unique token (a substring of the name).
 		const row = presence(page, token);
 		await expect(row).toHaveCount(1, { timeout: SYNC });
-		// The markup is shown verbatim as text...
 		await expect(row).toContainText('<b>BOOM</b>', { timeout: SYNC });
-		// ...and was NOT parsed into a live element.
 		await expect(row.locator('b')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('the shared board persists multiple visitors across a reload', async ({ browser }) => {
-		const errors: string[] = [];
-		const ctxA = await browser.newContext();
-		const ctxB = await browser.newContext();
-		const tabA = await ctxA.newPage();
-		const tabB = await ctxB.newPage();
-		watchErrors(tabA, errors);
-		watchErrors(tabB, errors);
-
-		await tabA.goto(BASE);
-		await tabB.goto(BASE);
-
-		const nameA = uniq('persistA');
-		const nameB = uniq('persistB');
-		await join(tabA, nameA);
-		await join(tabB, nameB);
+	test('a reload restores the shared roster (page fetches api.listPresent on load)', async ({ page }) => {
+		const errors = watchErrors(page);
+		await page.goto(BASE);
 
-		// Both rosters first reach tab A via realtime...
-		await expect.poll(() => presence(tabA, nameA).count(), { timeout: SYNC }).toBe(1);
-		await expect.poll(() => presence(tabA, nameB).count(), { timeout: SYNC }).toBe(1);
+		const name = uniq('persist');
+		await page.getByTestId('presence-name-input').fill(name);
+		await page.getByTestId('join-btn').click();
+		await expect(presence(page, name)).toHaveCount(1, { timeout: SYNC });
 
-		// ...then a reload of tab A must restore BOTH from the persisted board —
-		// not just the visitor who joined in this tab.
-		await tabA.reload();
-		await expect.poll(() => presence(tabA, nameA).count(), { timeout: SYNC }).toBe(1);
-		await expect.poll(() => presence(tabA, nameB).count(), { timeout: SYNC }).toBe(1);
+		await page.reload();
+		// A blank first-paint that only fills on the next realtime event would fail:
+		// the stored roster must be fetched and rendered on load.
+		await expect(presence(page, name)).toHaveCount(1, { timeout: SYNC });
 
-		await ctxA.close();
-		await ctxB.close();
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('joining with a name already present does not create a duplicate row', async ({ page }) => {
+	test('a freshly-opened tab paints the pre-existing roster on mount (first-paint from listPresent)', async ({ page, request }) => {
 		const errors = watchErrors(page);
+		// Seed the shared board over the api BEFORE this tab ever opens — these
+		// joins are "already present" from the new tab's point of view.
+		const a = uniq('early');
+		const b = uniq('early');
+		await join(request, a);
+		await join(request, b);
+
+		// Opening the page now must render the already-present roster on load
+		// (a mount-time api.listPresent), not sit blank waiting for a future
+		// realtime event. Deterministic: the joins completed before goto.
 		await page.goto(BASE);
-
-		const name = uniq('dup');
-		await join(page, name);
-		await expect(presence(page, name)).toHaveCount(1, { timeout: SYNC });
-
-		// Join the SAME name again. Presence is keyed by name, so this must NOT add
-		// a second row (an append-by-random-key impl would).
-		await join(page, name);
-
-		// Deterministic flush: a sentinel join issued AFTER the duplicate must
-		// round-trip through the same persist/broadcast path. Once its row is
-		// visible, the duplicate join above has fully settled — so the count for
-		// `name` is final (not racing an in-flight second row).
-		const sentinel = uniq('flush');
-		await join(page, sentinel);
-		await expect(presence(page, sentinel)).toHaveCount(1, { timeout: SYNC });
-
-		await expect(presence(page, name)).toHaveCount(1, { timeout: SYNC });
+		await expect(presence(page, a)).toHaveCount(1, { timeout: SYNC });
+		await expect(presence(page, b)).toHaveCount(1, { timeout: SYNC });
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a tab opened AFTER others have joined loads the existing roster on first paint', async ({ browser }) => {
+	// --- Realtime fan-out: intrinsically two browser contexts (PARTIALLY-DOM) ---
+
+	test('a join in one tab appears in another already-open tab in real time', async ({ browser }) => {
 		const errors: string[] = [];
 		const ctxA = await browser.newContext();
 		const ctxB = await browser.newContext();
@@ -218,61 +190,17 @@ test.describe('collab-presence-board', () => {
 
 		await tabA.goto(BASE);
 		await tabB.goto(BASE);
-		const nameA = uniq('early-a');
-		const nameB = uniq('early-b');
-		await join(tabA, nameA);
-		await join(tabB, nameB);
-		// Make sure both are committed/broadcast before the late tab opens.
-		await expect.poll(() => presence(tabA, nameA).count(), { timeout: SYNC }).toBe(1);
-		await expect.poll(() => presence(tabA, nameB).count(), { timeout: SYNC }).toBe(1);
-
-		// A brand-new tab opens with no prior realtime events: it must fetch the
-		// stored roster on load and show BOTH immediately — a realtime-only impl
-		// (no initial fetch) would show a blank board here.
-		const ctxC = await browser.newContext();
-		const tabC = await ctxC.newPage();
-		watchErrors(tabC, errors);
-		await tabC.goto(BASE);
-		await expect.poll(() => presence(tabC, nameA).count(), { timeout: SYNC }).toBe(1);
-		await expect.poll(() => presence(tabC, nameB).count(), { timeout: SYNC }).toBe(1);
 
-		await ctxA.close();
-		await ctxB.close();
-		await ctxC.close();
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
+		const name = uniq('rt');
+		await tabA.getByTestId('presence-name-input').fill(name);
+		await tabA.getByTestId('join-btn').click();
 
-	test('a unicode/emoji name renders correctly on the board', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const token = uniq('uni');
-		const name = `${token} 日本語 🙂`;
-		await join(page, name);
-
-		const row = presence(page, token);
-		await expect(row).toHaveCount(1, { timeout: SYNC });
-		await expect(row).toContainText('日本語', { timeout: SYNC });
-		await expect(row).toContainText('🙂', { timeout: SYNC });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('multiple names joined from one tab all persist across a reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const names = [uniq('m1'), uniq('m2'), uniq('m3')];
-		for (const n of names) {
-			await join(page, n);
-			await expect(presence(page, n)).toHaveCount(1, { timeout: SYNC });
-		}
-
-		await page.reload();
-		for (const n of names) {
-			await expect(presence(page, n)).toHaveCount(1, { timeout: SYNC });
-		}
+		// Tab B had the board open before A joined; it must reflect A's presence
+		// within a couple seconds — realtime broadcast, no reload.
+		await expect.poll(() => presence(tabB, name).count(), { timeout: SYNC }).toBe(1);
 
+		await ctxA.close();
+		await ctxB.close();
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 });
diff --git a/tasks/email-digest/test.spec.ts b/tasks/email-digest/test.spec.ts
index 1d102481..f2da0f6c 100644
--- a/tasks/email-digest/test.spec.ts
+++ b/tasks/email-digest/test.spec.ts
@@ -1,11 +1,12 @@
 import { test, expect, type APIRequestContext, type Page } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const T = 5_000;
 
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
 // Per-test no-error gate: ONLY uncaught page errors.
 function watchErrors(page: Page, sink: string[] = []): string[] {
@@ -22,7 +23,7 @@ async function rpc(
 ): Promise<{ status: number; body: any }> {
 	const res = await request.post(`${BASE}/aws-blocks/api`, {
 		headers: { 'Content-Type': 'application/json' },
-		data: { jsonrpc: '2.0', method, params, id: Date.now() },
+		data: { jsonrpc: '2.0', method, params, id: ++rpcSeq },
 	});
 	return { status: res.status(), body: await res.json().catch(() => null) };
 }
@@ -144,12 +145,7 @@ test.describe('email-digest', () => {
 		await expect
 			.poll(
 				async () => {
-					const res = await request.post(`${BASE}/aws-blocks/api`, {
-						headers: { 'Content-Type': 'application/json' },
-						data: { jsonrpc: '2.0', method: 'api.getLastDigest', params: [], id: Date.now() },
-					});
-					if (!res.ok()) return false;
-					last = (await res.json().catch(() => null))?.result ?? null;
+					last = await getLast(request);
 					return !!last && typeof last.to === 'string' && typeof last.at === 'string';
 				},
 				{ timeout: T },
diff --git a/tasks/file-gallery/PROMPT.md b/tasks/file-gallery/PROMPT.md
index 5dd0266e..bc07a374 100644
--- a/tasks/file-gallery/PROMPT.md
+++ b/tasks/file-gallery/PROMPT.md
@@ -2,33 +2,42 @@
 
 Build a file gallery in this AWS Blocks app. A user uploads a file, sees it listed by name with a working download link, and can delete it. The list survives a page reload.
 
+The core of this task is **using the framework**: files are stored, listed, served, and deleted through an **`api` namespace** backed by the app's **file-storage block**. The page is a thin client over that API.
+
 ## Setup (do this first)
 
-The workspace has already been scaffolded. Begin by reading README.md, then do all your edits in this workspace.
+The workspace has already been scaffolded. Begin by reading README.md (and any AGENTS.md), then do all your edits in this workspace.
 
 ## Requirements
 
-1. A user can choose a file and click a button to upload it.
-2. Every uploaded file is listed by its name. Names may contain spaces or non-ASCII / unicode characters and must be shown verbatim. Uploading a file whose name matches one already in the gallery **overwrites** it — the gallery shows a single row for that name, serving the latest bytes (no duplicate rows).
-3. Each listed file has a download link that points at the stored file — use the storage block's download / presigned URL, not a placeholder. Fetching the link must return the **exact bytes that were uploaded** — byte-for-byte, including **binary (non-text)** files and **empty (0-byte)** files (the file is really stored and served, not just listed by name).
-4. Each listed file has a button that deletes it, removing **only that file** from the list and leaving the other files intact.
-5. **Persistence:** after a full page reload the list still shows the uploaded files (all of them), and a deleted file stays gone.
-6. **No-file upload is safe.** Clicking upload with no file selected must not throw or insert a phantom/blank row — disable the upload button until a file is chosen, or no-op the click. But a file that *is* selected is always uploaded and listed, even when it is empty (0 bytes).
+### The `api` namespace (primary surface)
+
+Expose an **`api` namespace** (the framework's server-side RPC surface — a `POST /aws-blocks/api` JSON-RPC endpoint) with these methods, each storing/serving real bytes through the **file-storage block** (not an in-memory map):
+
+1. **`api.putFile(name, contentBase64)`** — stores a file under `name` from the base64-encoded bytes and returns `{ name, size }` where `size` is the exact byte length. Storing a `name` that already exists **overwrites** it (one entry per name, latest bytes). Names may contain spaces or non-ASCII / unicode characters and are preserved verbatim. Storing an **empty (0-byte)** file is valid and returns `size: 0`. A **missing `name`** or **missing/invalid base64** is rejected with a JSON-RPC **error** envelope (no entry created).
+2. **`api.listFiles()`** — returns an array of `{ name, size, url }`, one per stored file. `url` is a **real download URL from the storage block** (its download / presigned URL) that serves the **exact stored bytes** — not `#`, not a placeholder. Fetching a file's `url` must return the uploaded bytes **byte-for-byte**, including binary (non-UTF-8) and empty files.
+3. **`api.deleteFile(name)`** — deletes **only** that file and returns `{ deleted: name }`; other files are untouched. The removal persists (a subsequent `listFiles` no longer includes it).
+
+### The page (thin client / light smoke)
+
+1. A user can choose a file (`<input type="file">`) and click a button to upload it. The button reads the chosen file and calls `api.putFile` (base64-encoding its bytes) — it must route through the API / storage block, not keep files only in the browser.
+2. The page lists every stored file (from `api.listFiles`) by name, each row with a working download link (the storage `url`) and a delete button (calls `api.deleteFile`). The list survives a full reload (it re-reads from `api.listFiles`).
+3. **No-file upload is safe:** clicking upload with no file selected must not throw or insert a phantom/blank row — disable the button until a file is chosen, or no-op the click.
 
 A single shared gallery — no login, no per-user separation.
 
 ## Selector contract
 
-The Playwright test grades your work using these `data-testid` hooks. Implement them exactly.
+The page smoke test uses these `data-testid` hooks. Implement them exactly.
 
 | Selector | Element | Purpose |
 |---|---|---|
 | `[data-testid=file-input]` | `<input type="file">` | Choose the file to upload |
-| `[data-testid=file-upload]` | `<button>` | Upload the chosen file |
+| `[data-testid=file-upload]` | `<button>` | Upload the chosen file (calls `api.putFile`) |
 | `[data-testid=file-list]` | container | Wraps every uploaded-file row |
 | `[data-testid=file-item]` | one per file, inside the list | The row for a single file |
 | `[data-testid=file-name]` | inside the item | Renders the file's name |
-| `[data-testid=file-download]` | `<a href=...>` inside the item | Download link for that file — a real URL that serves the exact stored bytes, not `#` |
+| `[data-testid=file-download]` | `<a href=...>` inside the item | Download link (the storage `url`) — a real URL, not `#` |
 | `[data-testid=file-delete]` | `<button>` inside the item | Deletes only that file |
 
 The mount point for your page is the existing root element. You can replace whatever placeholder content the template ships with.
diff --git a/tasks/file-gallery/test.spec.ts b/tasks/file-gallery/test.spec.ts
index aea9dd2b..79e3a7d6 100644
--- a/tasks/file-gallery/test.spec.ts
+++ b/tasks/file-gallery/test.spec.ts
@@ -1,345 +1,222 @@
-import { test, expect, type Page } from '@playwright/test';
+import { test, expect, type Page, type APIRequestContext } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const T = 8_000;
 
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: ONLY uncaught page errors (not console warnings, not
-// 4xx/5xx responses).
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
-// Scope to exactly the row whose file-name renders `name` — never a global count.
-const itemFor = (page: Page, name: string) =>
-	page.getByTestId('file-item').filter({ has: page.getByTestId('file-name').filter({ hasText: name }) });
-
-async function upload(page: Page, name: string, body = 'hello blocks file gallery'): Promise<void> {
-	await page.getByTestId('file-input').setInputFiles({
-		name,
-		mimeType: 'text/plain',
-		buffer: Buffer.from(body),
+async function rpc(
+	ctx: APIRequestContext,
+	method: string,
+	params: unknown[] | undefined,
+	opts: { omitParams?: boolean } = {},
+): Promise<{ status: number; body: any }> {
+	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++rpcSeq };
+	if (!opts.omitParams) data.params = params ?? [];
+	const res = await ctx.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data,
 	});
-	await page.getByTestId('file-upload').click();
-	await expect(itemFor(page, name)).toHaveCount(1, { timeout: T });
+	return { status: res.status(), body: await res.json().catch(() => null) };
 }
 
-test.describe('file-gallery', () => {
-	test('shows the upload input and the file list', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+const toB64 = (buf: Buffer) => buf.toString('base64');
+// Download URLs may be absolute (presigned) or root-relative (served locally).
+const absUrl = (u: string) => (/^https?:\/\//.test(u) ? u : `${BASE.replace(/\/$/, '')}/${u.replace(/^\//, '')}`);
 
-		await expect(page.getByTestId('file-input')).toBeVisible();
-		// The list container must exist on load, but an empty list may reasonably be
-		// hidden (e.g. swapped for an empty-state), so assert presence — not
-		// visibility. Visibility is asserted after an upload (next test).
-		await expect(page.getByTestId('file-list')).toHaveCount(1);
+async function putFile(ctx: APIRequestContext, name: string, buf: Buffer): Promise<any> {
+	const { body } = await rpc(ctx, 'api.putFile', [name, toB64(buf)]);
+	expect(body?.error, `JSON-RPC error from putFile: ${JSON.stringify(body?.error)}`).toBeFalsy();
+	return body?.result;
+}
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
+async function list(ctx: APIRequestContext): Promise<any[]> {
+	const { body } = await rpc(ctx, 'api.listFiles', []);
+	expect(body?.error, `JSON-RPC error from listFiles: ${JSON.stringify(body?.error)}`).toBeFalsy();
+	return Array.isArray(body?.result) ? body.result : [];
+}
 
-	test('uploading a file lists it by name', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+const entryFor = (files: any[], name: string) => files.find((f) => f?.name === name);
 
-		const name = `${uniq('hello')}.txt`;
-		await upload(page, name);
-		// With an item present the list is non-empty, so the container must now show.
-		await expect(page.getByTestId('file-list')).toBeVisible();
-		await expect(itemFor(page, name)).toBeVisible();
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
+test.describe('file-gallery', () => {
+	// --- Framework surface: store / list / serve / delete through the api ---
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('putFile stores a file that listFiles reports with the exact byte size', async ({ request }) => {
+		const name = `${uniq('hello')}.txt`;
+		const body = Buffer.from('hello blocks file gallery');
+		const put = await putFile(request, name, body);
+		expect(put?.name).toBe(name);
+		expect(put?.size).toBe(body.byteLength);
+
+		const entry = entryFor(await list(request), name);
+		expect(entry, 'listFiles must include the stored file').toBeTruthy();
+		expect(entry.size).toBe(body.byteLength);
 	});
 
-	test('an uploaded file exposes a resolvable download link', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const name = `${uniq('download')}.txt`;
-		await upload(page, name);
-
-		// A real, resolvable href (absolute URL, root-relative path, or blob:) —
-		// not a "#" placeholder.
-		const href = await itemFor(page, name).getByTestId('file-download').getAttribute('href');
-		expect(href, 'download link must have an href').toBeTruthy();
-		expect(href).toMatch(/^(https?:\/\/|\/|blob:)/);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('a stored file\u2019s url serves the exact uploaded text bytes', async ({ request }) => {
+		const name = `${uniq('content')}.txt`;
+		const body = Buffer.from(`payload-${uniq('body')}`);
+		await putFile(request, name, body);
+
+		const entry = entryFor(await list(request), name);
+		expect(entry?.url, 'listFiles entry must expose a download url').toBeTruthy();
+		const res = await request.get(absUrl(String(entry.url)));
+		expect(res.ok(), `download fetch failed: HTTP ${res.status()}`).toBe(true);
+		expect((await res.body()).equals(body), 'served bytes must equal uploaded bytes').toBe(true);
 	});
 
-	test('an uploaded file persists across a full reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const name = `${uniq('persist')}.txt`;
-		await upload(page, name);
-
-		await page.reload();
-		await expect(itemFor(page, name)).toHaveCount(1, { timeout: T });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('binary (non-UTF-8) bytes round-trip byte-for-byte', async ({ request }) => {
+		const name = `${uniq('binary')}.bin`;
+		const bytes = Buffer.from([0x00, 0x01, 0xff, 0xfe, 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x80, 0x7f, 0xc3, 0x28]);
+		await putFile(request, name, bytes);
+
+		const entry = entryFor(await list(request), name);
+		expect(entry?.url).toBeTruthy();
+		expect(entry.size).toBe(bytes.byteLength);
+		const res = await request.get(absUrl(String(entry.url)));
+		expect(res.ok(), `download fetch failed: HTTP ${res.status()}`).toBe(true);
+		expect((await res.body()).equals(bytes), 'binary bytes must survive intact').toBe(true);
 	});
 
-	test('deleting a file removes it, and the deletion survives a reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const name = `${uniq('delete')}.txt`;
-		await upload(page, name);
-
-		await itemFor(page, name).getByTestId('file-delete').click();
-		await expect(itemFor(page, name)).toHaveCount(0, { timeout: T });
-
-		await page.reload();
-		await expect(itemFor(page, name)).toHaveCount(0, { timeout: T });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('a zero-byte file is stored (size 0) and served as empty', async ({ request }) => {
+		const name = `${uniq('empty')}.txt`;
+		const put = await putFile(request, name, Buffer.alloc(0));
+		expect(put?.size).toBe(0);
+
+		const entry = entryFor(await list(request), name);
+		expect(entry?.size).toBe(0);
+		const res = await request.get(absUrl(String(entry.url)));
+		expect(res.ok(), `download fetch failed: HTTP ${res.status()}`).toBe(true);
+		expect((await res.body()).byteLength).toBe(0);
 	});
 
-	test('two uploaded files coexist in the list', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const first = `${uniq('first')}.txt`;
-		const second = `${uniq('second')}.txt`;
-		await upload(page, first, 'first file body');
-		await upload(page, second, 'second file body');
-
-		await expect(itemFor(page, first)).toHaveCount(1, { timeout: T });
-		await expect(itemFor(page, second)).toHaveCount(1, { timeout: T });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('re-putting the same name overwrites it (one entry, latest bytes)', async ({ request }) => {
+		const name = `${uniq('dup')}.txt`;
+		await putFile(request, name, Buffer.from(`v1-${uniq('a')}`));
+		const v2 = Buffer.from(`v2-${uniq('b')}`);
+		await putFile(request, name, v2);
+
+		const files = await list(request);
+		expect(files.filter((f) => f?.name === name), 'exactly one entry for the name').toHaveLength(1);
+		const res = await request.get(absUrl(String(entryFor(files, name).url)));
+		expect((await res.body()).equals(v2), 'the url must serve the latest bytes').toBe(true);
 	});
 
-	test('the download link serves the exact uploaded bytes', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const name = `${uniq('content')}.txt`;
-		const body = `payload-${uniq('body')}`;
-		await upload(page, name, body);
-
-		const href = await itemFor(page, name).getByTestId('file-download').getAttribute('href');
-		expect(href, 'download link must have an href').toBeTruthy();
-
-		// Fetch the link from the page context (same-origin object URL) and confirm
-		// it returns the exact bytes uploaded — proving the file was really stored
-		// and served, not merely listed by name.
-		const served = await page.evaluate(async (u) => {
-			const r = await fetch(u as string);
-			return { ok: r.ok, text: await r.text() };
-		}, href);
-		expect(served.ok, `download fetch failed for ${href}`).toBe(true);
-		expect(served.text).toBe(body);
+	test('a name with spaces and unicode is preserved verbatim and still serves its bytes', async ({ request }) => {
+		const name = `${uniq('spaced')} report (v2) \u65e5\u672c.txt`;
+		const body = Buffer.from(`payload-${uniq('body')}`);
+		await putFile(request, name, body);
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		const entry = entryFor(await list(request), name);
+		expect(entry, 'the unicode-named file must be listed verbatim').toBeTruthy();
+		const res = await request.get(absUrl(String(entry.url)));
+		expect(res.ok(), `download fetch failed: HTTP ${res.status()}`).toBe(true);
+		expect((await res.body()).equals(body)).toBe(true);
 	});
 
-	test('deleting one of two files leaves the other intact (and the split survives reload)', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
+	test('deleteFile removes only that file; others survive and the removal persists', async ({ request }) => {
 		const keep = `${uniq('keep')}.txt`;
 		const drop = `${uniq('drop')}.txt`;
-		await upload(page, keep, 'keep this one');
-		await upload(page, drop, 'drop this one');
-
-		// Delete only `drop`; the targeted delete must not touch `keep`.
-		await itemFor(page, drop).getByTestId('file-delete').click();
-		await expect(itemFor(page, drop)).toHaveCount(0, { timeout: T });
-		await expect(itemFor(page, keep)).toHaveCount(1, { timeout: T });
-
-		// The deletion and the survivor both persist across a reload.
-		await page.reload();
-		await expect(itemFor(page, drop)).toHaveCount(0, { timeout: T });
-		await expect(itemFor(page, keep)).toHaveCount(1, { timeout: T });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		await putFile(request, keep, Buffer.from('keep this one'));
+		await putFile(request, drop, Buffer.from('drop this one'));
+
+		const del = await rpc(request, 'api.deleteFile', [drop]);
+		expect(del.body?.error, `JSON-RPC error from deleteFile: ${JSON.stringify(del.body?.error)}`).toBeFalsy();
+
+		const files = await list(request);
+		expect(entryFor(files, drop), 'the deleted file must be gone').toBeFalsy();
+		const survivor = entryFor(files, keep);
+		expect(survivor, 'the untouched file must remain').toBeTruthy();
+		// The survivor is still really served.
+		const res = await request.get(absUrl(String(survivor.url)));
+		expect((await res.body()).toString()).toBe('keep this one');
 	});
 
-	test('attempting to upload with no file selected is handled gracefully', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const uploadBtn = page.getByTestId('file-upload');
-		await expect(uploadBtn).toBeVisible();
-
-		// Baseline count (the bucket persists across tests in this run).
-		const before = await page.getByTestId('file-item').count();
+	test('putFile validates its input — missing name or bad base64 is rejected', async ({ request }) => {
+		const noName = await rpc(request, 'api.putFile', [toB64(Buffer.from('x'))]);
+		expect(noName.status, `unexpected HTTP ${noName.status}`).toBeLessThan(500);
+		expect(noName.body?.error, 'a missing name must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(noName.body?.result ?? null).toBeNull();
 
-		// No file chosen: a correct impl either disables the button or no-ops on
-		// click — it must NOT throw (e.g. reading files[0] of an empty selection).
-		if (await uploadBtn.isEnabled()) {
-			await uploadBtn.click();
-		}
+		const noParams = await rpc(request, 'api.putFile', undefined, { omitParams: true });
+		expect(noParams.body?.error, 'no params must yield a JSON-RPC error envelope').toBeTruthy();
+	});
 
-		// A subsequent real upload must add EXACTLY ONE row — proving the empty
-		// click neither crashed the app nor inserted a phantom row (which would
-		// land this at before + 2).
-		const name = `${uniq('after-noop')}.txt`;
-		await upload(page, name);
-		await expect.poll(() => page.getByTestId('file-item').count(), { timeout: T }).toBe(before + 1);
+	test('putFile rejects a present-but-empty name (nothing stored under a blank key)', async ({ request }) => {
+		// A name that is present but blank must be rejected just like a missing
+		// one — never stored under an empty key.
+		const empty = await rpc(request, 'api.putFile', ['', toB64(Buffer.from('x'))]);
+		expect(empty.status, `unexpected HTTP ${empty.status}`).toBeLessThan(500);
+		expect(empty.body?.error, 'an empty name must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(empty.body?.result ?? null).toBeNull();
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		// No phantom entry leaked in under the blank name.
+		expect(entryFor(await list(request), ''), 'no file may be stored under an empty name').toBeFalsy();
 	});
 
-	test('the download link serves binary (non-UTF8) bytes intact', async ({ page }) => {
+	// --- Page smoke: the thin client wires the input/list to the api ---
+
+	test('shows the upload input and the file list container', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		const name = `${uniq('binary')}.bin`;
-		// Bytes that are NOT valid UTF-8 text (NUL, 0xFF/0xFE, PNG magic, high
-		// bytes). A store/serve path that round-trips through a UTF-8 string would
-		// corrupt these; only a true binary store survives byte-for-byte.
-		const bytes = [0x00, 0x01, 0xff, 0xfe, 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x80, 0x7f, 0xc3, 0x28];
-		await page.getByTestId('file-input').setInputFiles({
-			name,
-			mimeType: 'application/octet-stream',
-			buffer: Buffer.from(bytes),
-		});
-		await page.getByTestId('file-upload').click();
-		await expect(itemFor(page, name)).toHaveCount(1, { timeout: T });
-
-		const href = await itemFor(page, name).getByTestId('file-download').getAttribute('href');
-		expect(href, 'download link must have an href').toBeTruthy();
-		const served = await page.evaluate(async (u) => {
-			const r = await fetch(u as string);
-			return { ok: r.ok, bytes: Array.from(new Uint8Array(await r.arrayBuffer())) };
-		}, href);
-		expect(served.ok, `download fetch failed for ${href}`).toBe(true);
-		expect(served.bytes).toEqual(bytes);
+		await expect(page.getByTestId('file-input')).toBeVisible();
+		await expect(page.getByTestId('file-list')).toHaveCount(1);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a filename with spaces and unicode lists verbatim and still serves its bytes', async ({ page }) => {
+	test('uploading through the page lists the file with a resolvable link, and delete removes it', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		// Spaces, parentheses and non-ASCII characters in the name — these need
-		// careful key/URL handling. The row must show the name and the link must
-		// still resolve to the exact bytes.
-		const token = uniq('spaced');
-		const name = `${token} report (v2) 日本.txt`;
-		const body = `payload-${uniq('body')}`;
-		await page.getByTestId('file-input').setInputFiles({
-			name,
-			mimeType: 'text/plain',
-			buffer: Buffer.from(body),
-		});
+		const name = `${uniq('via-dom')}.txt`;
+		await page.getByTestId('file-input').setInputFiles({ name, mimeType: 'text/plain', buffer: Buffer.from('dom upload body') });
 		await page.getByTestId('file-upload').click();
 
 		const row = page
 			.getByTestId('file-item')
-			.filter({ has: page.getByTestId('file-name').filter({ hasText: token }) });
+			.filter({ has: page.getByTestId('file-name').filter({ hasText: name }) });
 		await expect(row).toHaveCount(1, { timeout: T });
-		await expect(row.getByTestId('file-name')).toContainText('日本', { timeout: T });
 
 		const href = await row.getByTestId('file-download').getAttribute('href');
-		expect(href, 'download link must have an href').toBeTruthy();
-		const served = await page.evaluate(async (u) => {
-			const r = await fetch(u as string);
-			return { ok: r.ok, text: await r.text() };
-		}, href);
-		expect(served.ok, `download fetch failed for ${href}`).toBe(true);
-		expect(served.text).toBe(body);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('a zero-byte file is stored and served as empty', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const name = `${uniq('empty')}.txt`;
-		// A selected-but-empty file must still upload and list (only the *no
-		// selection* case is skipped). An impl that guards on `file.size > 0`
-		// would silently drop this file.
-		await page.getByTestId('file-input').setInputFiles({
-			name,
-			mimeType: 'text/plain',
-			buffer: Buffer.from(''),
-		});
-		await page.getByTestId('file-upload').click();
-		await expect(itemFor(page, name)).toHaveCount(1, { timeout: T });
-
-		const href = await itemFor(page, name).getByTestId('file-download').getAttribute('href');
-		expect(href, 'download link must have an href').toBeTruthy();
-		const served = await page.evaluate(async (u) => {
-			const r = await fetch(u as string);
-			return { ok: r.ok, text: await r.text() };
-		}, href);
-		expect(served.ok, `download fetch failed for ${href}`).toBe(true);
-		expect(served.text).toBe('');
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('re-uploading the same filename overwrites it (one row, latest bytes)', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const name = `${uniq('dup')}.txt`;
-		const v1 = `v1-${uniq('a')}`;
-		const v2 = `v2-${uniq('b')}`;
-		await upload(page, name, v1);
-
-		// Second upload of the SAME name, inline (the helper's count-based wait
-		// would pass early off the v1 row). We settle on the SERVED bytes instead.
-		await page.getByTestId('file-input').setInputFiles({
-			name,
-			mimeType: 'text/plain',
-			buffer: Buffer.from(v2),
-		});
-		await page.getByTestId('file-upload').click();
-
-		// Poll the served content of the (single) row until it reflects v2 — this
-		// deterministically waits for the overwrite to round-trip. (An append-style
-		// impl yields two rows, so the scoped link is ambiguous and never resolves
-		// to v2 here — and the explicit count assertion below also fails it.)
-		await expect
-			.poll(
-				async () => {
-					try {
-						const h = await itemFor(page, name).getByTestId('file-download').getAttribute('href');
-						if (!h) return null;
-						return await page.evaluate(async (u) => {
-							try {
-								const r = await fetch(u as string);
-								return r.ok ? await r.text() : null;
-							} catch {
-								return null;
-							}
-						}, h);
-					} catch {
-						return null;
-					}
-				},
-				{ timeout: T },
-			)
-			.toBe(v2);
-
-		await expect(itemFor(page, name)).toHaveCount(1, { timeout: T });
+		expect(href, 'download link must have a real href').toBeTruthy();
+		expect(href).toMatch(/^(https?:\/\/|\/|blob:)/);
 
+		await row.getByTestId('file-delete').click();
+		await expect(row).toHaveCount(0, { timeout: T });
 		await page.reload();
-		await expect(itemFor(page, name)).toHaveCount(1, { timeout: T });
+		await expect(row).toHaveCount(0, { timeout: T });
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('three uploaded files all persist across a reload', async ({ page }) => {
+	test('clicking upload with no file selected is handled gracefully (no throw, no phantom row)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		const names = [`${uniq('p1')}.txt`, `${uniq('p2')}.txt`, `${uniq('p3')}.txt`];
-		for (const n of names) await upload(page, n, `body-${n}`);
+		const uploadBtn = page.getByTestId('file-upload');
+		await expect(uploadBtn).toBeVisible();
+		const before = await page.getByTestId('file-item').count();
 
-		await page.reload();
-		for (const n of names) await expect(itemFor(page, n)).toHaveCount(1, { timeout: T });
+		if (await uploadBtn.isEnabled()) await uploadBtn.click();
+
+		const name = `${uniq('after-noop')}.txt`;
+		await page.getByTestId('file-input').setInputFiles({ name, mimeType: 'text/plain', buffer: Buffer.from('real') });
+		await page.getByTestId('file-upload').click();
+		await expect(page.getByTestId('file-item').filter({ has: page.getByTestId('file-name').filter({ hasText: name }) }))
+			.toHaveCount(1, { timeout: T });
+		// The empty click added no phantom row: exactly one net new item.
+		await expect.poll(() => page.getByTestId('file-item').count(), { timeout: T }).toBe(before + 1);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
diff --git a/tasks/kb-chat-agent/PROMPT.md b/tasks/kb-chat-agent/PROMPT.md
index 5756f3fa..dde39828 100644
--- a/tasks/kb-chat-agent/PROMPT.md
+++ b/tasks/kb-chat-agent/PROMPT.md
@@ -1,10 +1,12 @@
 # Task: Knowledge-Base Chat Agent with Tool Use
 
-Build a chat assistant in this AWS Blocks app. A user types a question; an AI **agent** answers it. The agent must be able to (a) look facts up in a **knowledge base** you seed from a local folder of documents, and (b) call at least one **tool** to take an action. Each answer is shown as a chat bubble, the questions and answers accumulate in a message list, and when the agent uses a tool or cites a document the UI shows that.
+Build a chat assistant in this AWS Blocks app. A user types a question; an AI **agent** answers it. The agent must be able to (a) look facts up in a **knowledge base** you seed from a local folder of documents, and (b) call at least one **tool** to take an action.
+
+The core of this task is **using the framework**: the agent turn — retrieval, tool calls, and the final answer — runs through an **`api` namespace** method backed by the **agent block**. The chat page is a thin client over that API.
 
 ## Setup (do this first)
 
-The workspace has already been scaffolded. Begin by reading `README.md` and `AGENTS.md`, then do all your edits in this workspace.
+The workspace has already been scaffolded. Begin by reading README.md (and any AGENTS.md), then do all your edits in this workspace.
 
 Replace the scaffold's starter content with your chat UI.
 
@@ -18,35 +20,43 @@ Replace the scaffold's starter content with your chat UI.
    - its factory calibration code **`NBS-7Q6X`** (a second, distinct fact from the product code),
    - the word **`sample`**.
 
-   These four facts must appear **only** in the knowledge base — nowhere in your frontend or backend source — so that an answer repeating them proves a real retrieval happened. The same (or another) document must also describe the **return / refund policy** and contain the word **`refund`**. Write real prose, not a stub. Configure the block's chunking so this whole passage stays in a single chunk, rather than being split apart.
+   These four facts must appear **only** in the knowledge base — nowhere in your frontend or backend source — so that an answer repeating them proves a real retrieval happened. The same (or another) document must also describe the **return / refund policy** and contain the word **`refund`**. Write real prose, not a stub. Configure the block's chunking so this whole passage stays in a single chunk.
 
 ### Agent + tools
 3. Wire an **agent block** whose deployed model is Amazon Bedrock with the Claude Sonnet 4.6 inference profile — model id exactly **`us.anthropic.claude-sonnet-4-6`**. (Locally a lightweight mock stands in for Bedrock — no AWS creds needed to run the dev server.)
-4. The agent must expose **exactly two tools**, named **exactly** `searchKnowledgeBase` and `lookupOrderStatus` (the grader's questions are phrased to invoke them by name):
-   - **`searchKnowledgeBase`** — takes a search query and returns matching passages from the knowledge base (each hit's text and its source document). **Treat an empty or missing query as a broad lookup** — default it to `'sample'` — so the tool still returns the seeded passage.
-   - **`lookupOrderStatus`** — returns a **fixed, deterministic** result regardless of its input: `{ status: 'shipped', trackingCode: 'TRK-9F42-OK' }`. (A real implementation would look the order up; for this task a constant is required so the result is checkable.)
+4. The agent must expose **exactly two tools**, named **exactly** `searchKnowledgeBase` and `lookupOrderStatus`:
+   - **`searchKnowledgeBase`** — takes a search query and returns matching passages from the knowledge base (each hit's text and its source document). **Treat an empty or missing query as a broad lookup** — default it to `'sample'`.
+   - **`lookupOrderStatus`** — returns a **fixed, deterministic** result regardless of its input: `{ status: 'shipped', trackingCode: 'TRK-9F42-OK' }`.
 5. The agent's system prompt must steer it to call `searchKnowledgeBase` for product / returns / refund questions and `lookupOrderStatus` for order / shipping / tracking questions, and to answer **only** from what those tools return.
 
-### Chat UI
-6. A user types a question into `[data-testid=chat-input]` and submits it with `[data-testid=chat-send]`. The question appears immediately as a `[data-testid=message]` bubble with `data-role="user"`, and the agent's reply appears as a `[data-testid=message]` bubble with `data-role="assistant"` inside `[data-testid=message-list]`. Messages accumulate (the list is a transcript).
-7. When the agent's reply used a tool, that assistant bubble must contain a `[data-testid=tool-indicator]` (e.g. naming the tool(s) called). When the reply drew on the knowledge base, the bubble must contain a `[data-testid=citation]` naming the source document. The assistant reply text must include what the tool returned (the retrieved passage, or the tracking code).
+### The `api` namespace (primary surface)
+
+Expose an **`api` namespace** (the framework's server-side RPC surface — `POST /aws-blocks/api`) with:
+
+- **`api.ask(message)`** — runs one agent turn through the **agent block** and returns structured data `{ reply, toolsUsed, citations }`:
+  - `reply` — the agent's answer text. It must literally contain what the tool returned: the retrieved fact (`QUOKKA-9F42`, `1337`, `NBS-7Q6X`) for KB questions, or the tracking code (`TRK-9F42-OK`) for order questions.
+  - `toolsUsed` — an array of the tool names the agent invoked this turn (`"searchKnowledgeBase"` and/or `"lookupOrderStatus"`); empty when no tool ran.
+  - `citations` — an array of source-document names when the reply drew on the knowledge base; empty otherwise.
+  A blank/empty `message` is rejected with a JSON-RPC **error** envelope.
+
+### Chat UI (thin client / light smoke)
+6. A user types a question into `[data-testid=chat-input]` and submits with `[data-testid=chat-send]`. The question appears immediately as a `[data-testid=message]` bubble with `data-role="user"`; the agent's reply (from `api.ask`) appears as a `[data-testid=message]` bubble with `data-role="assistant"` inside `[data-testid=message-list]`. Messages accumulate (the list is a transcript).
+7. When the reply used a tool, that assistant bubble contains a `[data-testid=tool-indicator]`; when it drew on the knowledge base, the bubble contains a `[data-testid=citation]` naming the source document.
 
 A single shared assistant — no login.
 
 ## Selector contract
 
-The Playwright test grades your work using these `data-testid` hooks and one data attribute. Implement them exactly.
-
 | Selector | Element | Purpose |
 |---|---|---|
 | `[data-testid=chat-input]` | `<input type="text">` (or `<textarea>`) | Where the user types a question |
-| `[data-testid=chat-send]` | `<button>` | Submits the question to the agent |
+| `[data-testid=chat-send]` | `<button>` | Submits the question to the agent (`api.ask`) |
 | `[data-testid=message-list]` | container | Wraps every chat bubble (the transcript) |
-| `[data-testid=message]` | one per message, inside the list | A chat bubble; must render the message text as its content |
+| `[data-testid=message]` | one per message, inside the list | A chat bubble; renders the message text as its content |
 | `[data-testid=tool-indicator]` | inside an assistant bubble | Present when that reply used a tool |
 | `[data-testid=citation]` | inside an assistant bubble | Present when that reply drew on the knowledge base; names the source document |
 
-Set `data-role` on each `[data-testid=message]`: `"user"` for the person's questions, `"assistant"` for the agent's replies. The test locates a bubble by the text it contains (`filter({ hasText: … })`), so the assistant reply must literally contain the retrieved fact (`QUOKKA-9F42`, `1337`, `NBS-7Q6X`) or the tracking code (`TRK-9F42-OK`).
+Set `data-role` on each `[data-testid=message]`: `"user"` for questions, `"assistant"` for replies. The assistant reply must literally contain the retrieved fact (`QUOKKA-9F42`, `1337`, `NBS-7Q6X`) or the tracking code (`TRK-9F42-OK`).
 
 The mount point for your page is the existing root element. Replace the template's placeholder content.
 
diff --git a/tasks/kb-chat-agent/test.spec.ts b/tasks/kb-chat-agent/test.spec.ts
index c614a44e..6d15626c 100644
--- a/tasks/kb-chat-agent/test.spec.ts
+++ b/tasks/kb-chat-agent/test.spec.ts
@@ -1,251 +1,164 @@
-import { test, expect, type Page } from '@playwright/test';
+import { test, expect, type Page, type APIRequestContext } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
-const T = 10_000; // UI render / echo
-// Agent round-trip (KB retrieval + model turn). Local dev answers in
-// milliseconds; the generous ceiling absorbs first-load + KB-ingestion latency
-// while staying under Playwright's 60s per-test cap.
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
+const T = 10_000;
+// Agent round-trip (KB retrieval + model turn). Generous ceiling for first-load
+// + KB ingestion, under Playwright's 60s per-test cap.
 const REPLY = 45_000;
 
-// Run-stable unique identity: seeded once per worker (a retry reuses the same
-// RUN seed) yet unique per call, so an echoed question never collides with a
-// bubble left by another test or an earlier attempt.
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: ONLY uncaught page errors. JSON-RPC error envelopes
-// come back as HTTP 200, so they are intentionally not treated as failures.
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
+// One agent turn over the api. Non-deterministic model, so callers assert only
+// on the deterministic fragments the seeded KB / fixed-output tool force in.
+async function ask(
+	ctx: APIRequestContext,
+	message: string,
+): Promise<{ status: number; body: any; reply: string; toolsUsed: string[]; citations: string[] }> {
+	const res = await ctx.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data: { jsonrpc: '2.0', method: 'api.ask', params: [message], id: ++rpcSeq },
+	});
+	const body = await res.json().catch(() => null);
+	const r = body?.result ?? {};
+	return {
+		status: res.status(),
+		body,
+		reply: String(r.reply ?? ''),
+		toolsUsed: Array.isArray(r.toolsUsed) ? r.toolsUsed.map(String) : [],
+		citations: Array.isArray(r.citations) ? r.citations.map(String) : [],
+	};
+}
+
 const messages = (page: Page) => page.getByTestId('message');
-// A bubble located by the text it contains (substring match), so assertions
-// never depend on the model's exact phrasing — only on the deterministic
-// fragments the seeded KB / fixed-output tool force into the reply.
 const bubbleWith = (page: Page, text: string) => messages(page).filter({ hasText: text });
 
-async function ask(page: Page, question: string): Promise<void> {
-	await expect(page.getByTestId('chat-input')).toBeVisible({ timeout: T });
-	await page.getByTestId('chat-input').fill(question);
-	await page.getByTestId('chat-send').click();
-}
-
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
 test.describe('kb-chat-agent', () => {
-	test('renders the chat composer and an empty message list', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		await expect(page.getByTestId('chat-input')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('chat-send')).toBeVisible();
-		await expect(page.getByTestId('message-list')).toBeVisible();
-		// Nothing answered yet, so the seeded fact must not be on the page —
-		// guards against a hard-coded reply that would pass the retrieval test
-		// vacuously.
-		await expect(bubbleWith(page, 'QUOKKA-9F42')).toHaveCount(0);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	// --- Framework surface: the agent turn runs through api.ask ---
+
+	test('api.ask retrieves the seeded KB facts and reports the tool + a citation', async ({ request }) => {
+		const a = await ask(request, 'According to the product knowledge base, what is the internal product code and the maximum hover altitude?');
+		expect(a.body?.error, `JSON-RPC error from api.ask: ${JSON.stringify(a.body?.error)}`).toBeFalsy();
+		// Facts live ONLY in the KB — their presence proves a real retrieval.
+		expect(a.reply).toContain('QUOKKA-9F42');
+		expect(a.reply).toContain('1337');
+		expect(a.toolsUsed, `toolsUsed: ${JSON.stringify(a.toolsUsed)}`).toContain('searchKnowledgeBase');
+		expect(a.citations.length, 'a KB answer must name a source document').toBeGreaterThan(0);
 	});
 
-	test('echoes the user question as a user-role message bubble', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// A unique, tool-free question: it must surface verbatim as the user's
-		// own bubble (the assistant's reply will not contain this token).
-		const question = uniq('hello there');
-		await ask(page, question);
-
-		const mine = messages(page).filter({ hasText: question });
-		await expect(mine).toHaveCount(1, { timeout: T });
-		await expect(mine).toHaveAttribute('data-role', 'user');
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('api.ask surfaces a SECOND distinct seeded fact (whole-passage retrieval, not a hard-coded code)', async ({ request }) => {
+		const a = await ask(request, 'From the product knowledge base, what is the Nimbus-7 factory calibration code?');
+		expect(a.body?.error, `error: ${JSON.stringify(a.body?.error)}`).toBeFalsy();
+		// NBS-7Q6X shares the passage with QUOKKA-9F42 and is asserted nowhere else.
+		expect(a.reply).toContain('NBS-7Q6X');
+		expect(a.toolsUsed).toContain('searchKnowledgeBase');
 	});
 
-	test('answers a knowledge-base question with the seeded fact (proves retrieval)', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// The answer to this lives ONLY in the seeded knowledge base. The product
-		// code and altitude are not in the question, so a bubble that contains them
-		// can only have come from a real retrieval round-trip.
-		await ask(page, 'According to the product knowledge base, what is the internal product code and the maximum hover altitude?');
-
-		await expect.poll(() => bubbleWith(page, 'QUOKKA-9F42').count(), { timeout: REPLY }).toBeGreaterThan(0);
-		// A second seeded fragment from the same document, for good measure.
-		await expect.poll(() => bubbleWith(page, '1337').count(), { timeout: REPLY }).toBeGreaterThan(0);
-		// The seeded fact must land in an assistant bubble, not the echoed question.
-		await expect(bubbleWith(page, 'QUOKKA-9F42').first()).toHaveAttribute('data-role', 'assistant');
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('api.ask routes an order question to the deterministic tool', async ({ request }) => {
+		const a = await ask(request, 'Can you look up my order status and tracking code?');
+		expect(a.body?.error, `error: ${JSON.stringify(a.body?.error)}`).toBeFalsy();
+		expect(a.reply).toContain('TRK-9F42-OK');
+		expect(a.toolsUsed, `toolsUsed: ${JSON.stringify(a.toolsUsed)}`).toContain('lookupOrderStatus');
 	});
 
-	test('a knowledge-base answer surfaces the tool-use indicator and a citation', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// Neither the tool-use indicator nor a citation may be present before any
-		// answer lands — guards against always-rendered chrome passing these
-		// vacuously via the global `.first()` lookups below.
-		await expect(page.getByTestId('tool-indicator')).toHaveCount(0);
-		await expect(page.getByTestId('citation')).toHaveCount(0);
-
-		await ask(page, 'What does the knowledge base say about the return and refund policy?');
-
-		// Wait for the assistant's REPLY to land — an assistant-role bubble, not the
-		// echoed question (which already contains "refund", so polling that word would
-		// pass vacuously before any round-trip). Once the reply is in, it must be
-		// attributed: the agent called a tool and cited a source.
-		await expect.poll(() => page.locator('[data-testid=message][data-role=assistant]').count(), { timeout: REPLY }).toBeGreaterThan(0);
-		await expect(page.getByTestId('tool-indicator').first()).toBeVisible({ timeout: REPLY });
-		await expect(page.getByTestId('citation').first()).toBeVisible({ timeout: REPLY });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('the order tool is deterministic across two differently-phrased inputs', async ({ request }) => {
+		const a1 = await ask(request, 'What is my order status right now?');
+		const a2 = await ask(request, 'Please look up the shipping status for a second, different order.');
+		expect(a1.reply).toContain('TRK-9F42-OK');
+		expect(a2.reply).toContain('TRK-9F42-OK');
+		expect(a1.toolsUsed).toContain('lookupOrderStatus');
+		expect(a2.toolsUsed).toContain('lookupOrderStatus');
 	});
 
-	test('an order question returns the deterministic tool output (proves tool use)', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// No tool indicator may be present before the tool runs — guards the
-		// global `.first()` lookup below against always-rendered chrome.
-		await expect(page.getByTestId('tool-indicator')).toHaveCount(0);
-
-		// This routes to a fixed-output tool whose tracking code is computable and
-		// constant, so the exact string must appear in the answer regardless of how
-		// the (non-deterministic) model phrases the rest of its reply.
-		await ask(page, 'Can you look up my order status and tracking code?');
-
-		await expect.poll(() => bubbleWith(page, 'TRK-9F42-OK').count(), { timeout: REPLY }).toBeGreaterThan(0);
-		await expect(bubbleWith(page, 'TRK-9F42-OK').first()).toHaveAttribute('data-role', 'assistant');
-		await expect(page.getByTestId('tool-indicator').first()).toBeVisible({ timeout: REPLY });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('small talk retrieves nothing and does not fabricate the seeded facts', async ({ request }) => {
+		const a = await ask(request, 'Please say a short friendly hello, nothing else.');
+		expect(a.body?.error, `error: ${JSON.stringify(a.body?.error)}`).toBeFalsy();
+		// Nothing to retrieve/look up → the KB/tool-only payloads must not appear.
+		expect(a.reply).not.toContain('QUOKKA-9F42');
+		expect(a.reply).not.toContain('NBS-7Q6X');
+		expect(a.reply).not.toContain('TRK-9F42-OK');
+		expect(a.toolsUsed, 'no tool should run for pure small talk').toHaveLength(0);
 	});
 
-	test('surfaces a SECOND distinct seeded fact — proves the answer is the retrieved passage, not a hard-coded product code', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		// The calibration code `NBS-7Q6X` lives ONLY in the same seeded passage as
-		// QUOKKA-9F42 and is asserted by NO other test. An impl that just hard-codes
-		// the two well-known strings (QUOKKA-9F42 / 1337) would pass the retrieval
-		// test above yet FAIL here — only a real retrieval that surfaces the whole
-		// passage carries this second, independent fact into the reply.
-		await ask(page, 'From the product knowledge base, what is the Nimbus-7 factory calibration code?');
-
-		await expect.poll(() => bubbleWith(page, 'NBS-7Q6X').count(), { timeout: REPLY }).toBeGreaterThan(0);
-		await expect(bubbleWith(page, 'NBS-7Q6X').first()).toHaveAttribute('data-role', 'assistant');
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('api.ask rejects a blank message with a JSON-RPC error envelope', async ({ request }) => {
+		const a = await ask(request, '   ');
+		expect(a.status, `unexpected HTTP ${a.status}`).toBeLessThan(500);
+		expect(a.body?.error, 'a blank message must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(a.body?.result ?? null).toBeNull();
 	});
 
-	test('a question with no knowledge-base match does NOT fabricate the seeded facts', async ({ page }) => {
+	// --- Page smoke: the thin chat client renders the transcript ---
+
+	test('renders the composer and an empty transcript (no seeded fact before asking)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		// Tool-free, KB-free small talk: it names none of the tools and asks for none
-		// of the seeded content, so a faithful agent has nothing to retrieve or look
-		// up. The unique token keeps the echoed question from colliding with any
-		// other test's bubbles.
-		const question = uniq('please just say a short friendly hello and nothing else');
-		await ask(page, question);
-
-		// Wait until the assistant has ACTUALLY replied (its own bubble, not the
-		// echoed question) BEFORE asserting absence — otherwise the checks below
-		// would pass vacuously against an always-answering impl before its
-		// fabricated reply even lands.
-		const assistant = page.locator('[data-testid=message][data-role=assistant]');
-		await expect.poll(() => assistant.count(), { timeout: REPLY }).toBeGreaterThan(0);
-
-		// No retrieval or tool call happened, so none of the KB/tool-only payloads may
-		// appear anywhere on the page. Each fragment is distinctive enough never to
-		// collide with a uniq()/timestamp token. Catches an impl that always answers
-		// with the seeded fact regardless of the question.
+		await expect(page.getByTestId('chat-input')).toBeVisible({ timeout: T });
+		await expect(page.getByTestId('chat-send')).toBeVisible();
+		await expect(page.getByTestId('message-list')).toBeVisible();
 		await expect(bubbleWith(page, 'QUOKKA-9F42')).toHaveCount(0);
-		await expect(bubbleWith(page, 'NBS-7Q6X')).toHaveCount(0);
-		await expect(bubbleWith(page, 'TRK-9F42-OK')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('the order tool returns the SAME deterministic code across two different inputs', async ({ page }) => {
+	test('asking a KB question shows a user bubble and an assistant answer with tool-indicator + citation', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		const orderReplies = () =>
-			page.locator('[data-testid=message][data-role=assistant]').filter({ hasText: 'TRK-9F42-OK' });
-
-		// Two differently-phrased order questions, each routing to the order tool.
-		// Its result is a fixed constant, so BOTH turns must produce an assistant
-		// bubble carrying the exact same tracking code — a per-input or
-		// non-deterministic tool would yield a different (or missing) second answer.
-		await ask(page, 'What is my order status right now?');
-		await expect.poll(() => orderReplies().count(), { timeout: REPLY }).toBe(1);
-
-		await ask(page, 'Please look up the shipping status for a second, different order.');
-		await expect.poll(() => orderReplies().count(), { timeout: REPLY }).toBe(2);
-
-		// The tool ran on both turns (an indicator per tool-using reply).
-		await expect.poll(() => page.getByTestId('tool-indicator').count(), { timeout: REPLY }).toBeGreaterThan(1);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
-
-	test('the user question and the assistant answer render as distinct bubbles with distinct roles', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+		// Nothing rendered before the first answer lands.
+		await expect(page.getByTestId('tool-indicator')).toHaveCount(0);
+		await expect(page.getByTestId('citation')).toHaveCount(0);
 
-		// A KB product question carrying a unique marker: the marker appears ONLY in
-		// the user's echoed bubble, while the retrieved fact (QUOKKA-9F42) appears
-		// ONLY in the assistant's bubble — so the two must be separate elements with
-		// opposite roles, not one merged/mis-attributed bubble.
 		const marker = uniq('marker');
-		await ask(page, `Using the product knowledge base, answer this tagged request ${marker}`);
+		await page.getByTestId('chat-input').fill(`Using the product knowledge base, answer this tagged request ${marker}`);
+		await page.getByTestId('chat-send').click();
 
+		// The user's question echoes as a user-role bubble.
 		const mine = messages(page).filter({ hasText: marker });
 		await expect(mine).toHaveCount(1, { timeout: T });
 		await expect(mine).toHaveAttribute('data-role', 'user');
 
+		// The assistant reply carries the retrieved fact in an assistant bubble.
 		await expect.poll(() => bubbleWith(page, 'QUOKKA-9F42').count(), { timeout: REPLY }).toBeGreaterThan(0);
 		const reply = bubbleWith(page, 'QUOKKA-9F42').first();
 		await expect(reply).toHaveAttribute('data-role', 'assistant');
-		// The answer is a DIFFERENT bubble from the user's echo: it must not carry the
-		// user's marker.
 		await expect(reply).not.toContainText(marker);
+		await expect(page.getByTestId('tool-indicator').first()).toBeVisible({ timeout: REPLY });
+		await expect(page.getByTestId('citation').first()).toBeVisible({ timeout: REPLY });
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('multi-turn: both turns\u2019 answers accumulate in one transcript', async ({ page }) => {
+	test('multi-turn answers accumulate in one transcript', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
 		const orderReply = () =>
 			page.locator('[data-testid=message][data-role=assistant]').filter({ hasText: 'TRK-9F42-OK' });
 
-		// Turn 1 hits the order tool; turn 2 hits the knowledge base — two turns in
-		// ONE page session. Because the transcript is a running log, BOTH assistant
-		// answers (with their DIFFERENT deterministic payloads) must still be present
-		// after the second turn. An impl that clears the list per turn, or re-renders
-		// only the latest answer, loses the first and fails.
 		const q1 = uniq('turn-one order status');
-		await ask(page, q1);
+		await page.getByTestId('chat-input').fill(q1);
+		await page.getByTestId('chat-send').click();
 		await expect.poll(() => orderReply().count(), { timeout: REPLY }).toBe(1);
 
 		const q2 = uniq('turn-two product knowledge base');
-		await ask(page, q2);
+		await page.getByTestId('chat-input').fill(q2);
+		await page.getByTestId('chat-send').click();
 		await expect.poll(() => bubbleWith(page, 'QUOKKA-9F42').count(), { timeout: REPLY }).toBeGreaterThan(0);
 
-		// The first turn's user + assistant messages survive alongside the second's.
-		await expect(messages(page).filter({ hasText: q1 })).toHaveAttribute('data-role', 'user');
-		await expect(messages(page).filter({ hasText: q2 })).toHaveAttribute('data-role', 'user');
-		await expect(orderReply()).toHaveCount(1);
-		await expect(bubbleWith(page, 'QUOKKA-9F42').first()).toHaveAttribute('data-role', 'assistant');
-		// At least four bubbles: two questions + two distinct answers.
+		// Both turns' questions and distinct answers survive in the running log.
+		// Scope to the user role: an assistant bubble that quotes q1 must not
+		// satisfy this — only the user's own echoed bubble.
+		await expect(page.locator('[data-testid=message][data-role=user]').filter({ hasText: q1 })).toHaveCount(1);
+		await expect(page.locator('[data-testid=message][data-role=assistant]').nth(0)).toContainText('TRK-9F42-OK');
 		await expect.poll(() => messages(page).count(), { timeout: T }).toBeGreaterThan(3);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
diff --git a/tasks/observability-api/PROMPT.md b/tasks/observability-api/PROMPT.md
index e724643c..f5aea063 100644
--- a/tasks/observability-api/PROMPT.md
+++ b/tasks/observability-api/PROMPT.md
@@ -54,3 +54,4 @@ The Playwright test grades your work using these `data-testid` hooks on the serv
 - All Playwright assertions pass against the running dev server.
 - No errors in the browser console under normal use.
 - Your changes stay inside the workspace root. Don't modify anything under `node_modules/`.
+- **Source inspection (grader; behaviorally unverifiable at runtime):** confirm in the source that the app name is read from the **AppSetting block** (via the block's documented API), not returned from a hard-coded `"Observability Service"` constant. Because the expected value is fixed, a hard-coded string would satisfy every runtime assertion, so the real setting-read must be verified by reading the code.
diff --git a/tasks/observability-api/test.spec.ts b/tasks/observability-api/test.spec.ts
index c07990be..e5a573f8 100644
--- a/tasks/observability-api/test.spec.ts
+++ b/tasks/observability-api/test.spec.ts
@@ -2,14 +2,14 @@ import { test, expect, type Page } from '@playwright/test';
 
 // Backend template: dev server listens on :3001 (the bench harness sets
 // BLOCKS_URL accordingly; the default mirrors that).
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3001';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3001';
 const T = 8_000;
 
 // Run-stable unique suffix so echoed payloads can't collide with anything a
 // retry (or another test) wrote. Mirrors the harness's RUN_ID seed.
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
 // Per-test no-error gate: ONLY uncaught page errors.
 function watchErrors(page: Page, sink: string[] = []): string[] {
diff --git a/tasks/oidc-dsql-notes/PROMPT.md b/tasks/oidc-dsql-notes/PROMPT.md
index 30240533..94f0e619 100644
--- a/tasks/oidc-dsql-notes/PROMPT.md
+++ b/tasks/oidc-dsql-notes/PROMPT.md
@@ -2,40 +2,47 @@
 
 Build a personal notes app gated by OIDC sign-in. A visitor signs in through an OIDC provider, then creates notes that belong to them and persist in a distributed SQL database across reloads.
 
+The core of this task is **using the framework**: notes are added and listed through an **`api` namespace** whose methods run **on the server**, derive the caller from the **OIDC auth session**, and persist through the **`DistributedDatabase`** block. The page is a thin client over that API; the OIDC sign-in itself is a browser redirect flow.
+
 ## Setup (do this first)
 
-The workspace has already been scaffolded. Begin by reading README.md, then do all your edits in this workspace.
+The workspace has already been scaffolded. Begin by reading README.md (and any AGENTS.md), then do all your edits in this workspace.
 
 Replace the scaffold's starter todo demo with your OIDC-gated notes app.
 
 ## Requirements
 
-1. **OIDC sign-in.** A signed-out visitor sees a single sign-in button; clicking it signs the visitor in through an OIDC provider (**named exactly `stub`**), after which a cookie session is established and the profile + note editor appear. On load, the session is **restored from the cookie** and the signed-in view re-renders — surfacing the profile and keeping the visitor signed in across reloads (requirement 4).
-2. **Profile.** Once signed in, show the signed-in user's stable subject id (e.g. the OIDC `userId`) in `[data-testid=profile-sub]`, and hide the sign-in button.
-3. **Notes in DistributedDatabase.** A signed-in user can type a note and add it. Notes are stored in a **`DistributedDatabase`** table (create a `.sql` migration under `aws-blocks/dsql-migrations/`), scoped to the current user, and each note renders in the list.
-   - Store and display note text **verbatim** — including long notes and unicode / emoji: use **parameterized** SQL (so a note containing a single quote like `' OR '1'='1` round-trips intact rather than breaking the query), and render the text as **text content**, never as HTML (`<b>x</b>` must show literally, not become a real element).
-   - **Stable ordering:** list the notes **oldest-first (in the order they were created)**, backed by a stored timestamp or sequential id plus an explicit `ORDER BY` — the order must be identical on every load and after adding more notes (don't rely on unspecified database row order).
-   - **No deduplication:** adding the same text twice creates **two** separate note rows.
-4. **Persistence.** After a full page reload the visitor is still signed in (session cookie restored) and **all** of their notes are still listed; the note editor remains functional after the reload (adding another note still works).
-5. **Input validation.** Disable `[data-testid=add-note-btn]` while the note input is empty or whitespace-only (trim before the check); re-enable it once real text is present.
+### OIDC sign-in (browser flow)
 
-## Selector contract
+1. A signed-out visitor sees a single sign-in button; clicking it signs the visitor in through an OIDC provider (**named exactly `stub`**), after which a cookie session is established and the profile + note editor appear. On load, the session is **restored from the cookie** and the signed-in view re-renders — keeping the visitor signed in across reloads.
+2. Once signed in, show the signed-in user's stable subject id (e.g. the OIDC `userId`) in `[data-testid=profile-sub]`, and hide the sign-in button.
+
+### The `api` namespace (primary surface)
+
+Expose an **`api` namespace** (the framework's server-side RPC surface — a `POST /aws-blocks/api` JSON-RPC endpoint) whose note methods derive the current user from the **OIDC session** (the sign-in cookie) — never from a client-supplied id — and persist through a **`DistributedDatabase`** table (create a `.sql` migration under `aws-blocks/dsql-migrations/`):
+
+1. **`api.addNote(text)`** — inserts a note for the current user and returns the created row `{ id, text }`. Text is stored **verbatim** via **parameterized** SQL — a note containing a single quote such as `' OR '1'='1` round-trips intact (never breaks or injects into the query) and is never HTML-processed. There is **no deduplication** (adding the same text twice creates two rows). A blank/whitespace-only or non-string `text` is rejected with a JSON-RPC **error** envelope (no row inserted).
+2. **`api.listNotes()`** — returns the current user's notes as `[{ id, text }]` in **oldest-first** creation order, backed by a stored timestamp / sequential id plus an explicit `ORDER BY` (identical on every call, never relying on unspecified row order).
 
-The Playwright test grades your work using these `data-testid` hooks. Implement them exactly. The signed-out vs signed-in views are told apart by which hooks are present: the sign-in button shows only when signed out; the profile + note hooks show only when signed in.
+**Auth gating (framework-enforced):** both methods require an authenticated OIDC session. Called with **no session** (a direct `POST /aws-blocks/api` carrying no sign-in cookie), a note method returns a JSON-RPC **error** envelope — never a `result` and never another user's notes.
 
-An inactive view's hooks must be REMOVED from the DOM (the grader asserts `toHaveCount(0)`); hiding them with CSS (`display:none` / `hidden`) will fail.
+### The page (thin client / light smoke)
+
+Once signed in, the user types a note and adds it (the add button calls `api.addNote`); each note renders in the list (from `api.listNotes`), verbatim as **text content** (never as HTML — `<b>x</b>` shows literally). After a full reload the visitor is still signed in and all notes are still listed. Disable `[data-testid=add-note-btn]` while the note input is empty or whitespace-only (trim before the check); re-enable it once real text is present.
+
+## Selector contract
+
+The page smoke test uses these `data-testid` hooks. Implement them exactly. The signed-out vs signed-in views are told apart by which hooks are present: the sign-in button shows only when signed out; the profile + note hooks show only when signed in. An inactive view's hooks must be **removed** from the DOM (not merely hidden with CSS).
 
 | Selector | Element | Purpose |
 |---|---|---|
 | `[data-testid=signin-btn]` | `<button>` | Starts the OIDC sign-in flow; shown when signed out |
 | `[data-testid=profile-sub]` | element in the signed-in view | Renders the signed-in user's subject id (non-empty) |
 | `[data-testid=note-input]` | `<input>` / `<textarea>` | Where the user types a note |
-| `[data-testid=add-note-btn]` | `<button>` | Adds the note for the current user; disabled while the input is empty/whitespace |
-| `[data-testid=note-item]` | one per note | A note row; must render the note's text verbatim as text content (no HTML injection) |
-
-A `[data-testid=note-item]` must contain the note's text (the test locates a note via `filter({ hasText: text })`).
+| `[data-testid=add-note-btn]` | `<button>` | Adds the note (calls `api.addNote`); disabled while the input is empty/whitespace |
+| `[data-testid=note-item]` | one per note | A note row; renders the note's text verbatim as text content (no HTML injection) |
 
-The mount point is the existing root element. Replace the template's todo UI.
+A `[data-testid=note-item]` must contain the note's text. The mount point is the existing root element. Replace the template's todo UI.
 
 ## Out of scope
 
diff --git a/tasks/oidc-dsql-notes/test.spec.ts b/tasks/oidc-dsql-notes/test.spec.ts
index 287eb073..48d1920e 100644
--- a/tasks/oidc-dsql-notes/test.spec.ts
+++ b/tasks/oidc-dsql-notes/test.spec.ts
@@ -1,29 +1,40 @@
-import { test, expect, type Page } from '@playwright/test';
+import { test, expect, type Page, type APIRequestContext } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const SIGNIN = 10_000;
 const T = 8_000;
 
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: ONLY uncaught page errors (persists across the
-// sign-in redirect navigations).
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
+async function rpc(
+	ctx: APIRequestContext,
+	method: string,
+	params: unknown[] | undefined,
+	opts: { omitParams?: boolean } = {},
+): Promise<{ status: number; body: any }> {
+	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++rpcSeq };
+	if (!opts.omitParams) data.params = params ?? [];
+	const res = await ctx.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data,
+	});
+	return { status: res.status(), body: await res.json().catch(() => null) };
+}
+
 const note = (page: Page, text: string) => page.getByTestId('note-item').filter({ hasText: text });
 
-// Server-initiated OIDC sign-in: navigating to the auth block's signin route
-// runs the whole flow through server-side 302s — signin → stub IdP authorize
-// (auto-approved by the provider's `onAuthorize`) → callback sets the session
-// cookie → postSignInPath ('/'). The browser follows the redirect chain and
-// lands back on the app, where the on-load session hydration shows the signed-in
-// subject id. This is the same path the block's own integration tests exercise;
-// it deliberately avoids the client-side PKCE redirect round-trip.
+// Server-initiated OIDC sign-in through the auth block's signin route: the
+// browser follows signin → stub IdP authorize (auto-approved) → callback (sets
+// the session cookie) → app. After this the page's cookie jar is authenticated,
+// so page.request calls the gated api as the signed-in user.
 async function signIn(page: Page): Promise<void> {
 	await page.goto(`${BASE}/aws-blocks/auth/signin/stub`);
 	await expect(page.getByTestId('profile-sub')).toBeVisible({ timeout: SIGNIN });
@@ -32,242 +43,204 @@ async function signIn(page: Page): Promise<void> {
 		.toMatch(/.+/);
 }
 
-async function addNote(page: Page, text: string): Promise<void> {
-	await expect(page.getByTestId('note-input')).toBeVisible({ timeout: T });
-	await page.getByTestId('note-input').fill(text);
-	await page.getByTestId('add-note-btn').click();
-	await expect.poll(() => note(page, text).count(), { timeout: T }).toBe(1);
+async function listNotes(ctx: APIRequestContext): Promise<any[]> {
+	const { body } = await rpc(ctx, 'api.listNotes', []);
+	expect(body?.error, `JSON-RPC error from listNotes: ${JSON.stringify(body?.error)}`).toBeFalsy();
+	return Array.isArray(body?.result) ? body.result : [];
 }
 
-// DOM-order index of each token within the full note list. Tokens are unique
-// per run, so each matches exactly one row, and the RELATIVE order of a test's
-// own tokens is stable even when other notes (the shared stub user) interleave.
-async function indicesOf(page: Page, tokens: string[]): Promise<number[]> {
-	const texts = await page.getByTestId('note-item').allInnerTexts();
-	return tokens.map((tok) => texts.findIndex((t) => t.includes(tok)));
-}
+// Relative order of tokens within the (shared stub user) note list.
+const indicesOf = (rows: any[], tokens: string[]) =>
+	tokens.map((tok) => rows.findIndex((r) => String(r?.text ?? '').includes(tok)));
 
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
 test.describe('oidc-dsql-notes', () => {
-	test('signed-out visitor sees only the sign-in button', async ({ page }) => {
+	// --- Framework surface: notes stored/queried through the api + DSQL ---
+
+	test('api.addNote inserts a row that api.listNotes reads back with a numeric id', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
+		await signIn(page);
 
-		await expect(page.getByTestId('signin-btn')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('note-input')).toHaveCount(0);
-		await expect(page.getByTestId('profile-sub')).toHaveCount(0);
+		const text = uniq('note');
+		const { body } = await rpc(page.request, 'api.addNote', [text]);
+		expect(body?.error, `JSON-RPC error from addNote: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		expect(typeof body?.result?.id, 'addNote must return a numeric id').toBe('number');
+		expect(body?.result?.text).toBe(text);
+
+		const rows = await listNotes(page.request);
+		expect(rows.some((r) => r?.text === text), 'the note must be listed').toBe(true);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('OIDC sign-in via the stub IdP shows the subject id and the note editor', async ({ page }) => {
+	test('notes are stored verbatim via parameterized SQL (quotes/markup round-trip, no injection)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signIn(page);
-		await expect(page.getByTestId('signin-btn')).toHaveCount(0);
-		await expect(page.getByTestId('note-input')).toBeVisible();
+
+		const text = `${uniq('sqlnote')} ' OR '1'='1 -- <b>BOOM</b> "q"`;
+		const { body } = await rpc(page.request, 'api.addNote', [text]);
+		expect(body?.error, `JSON-RPC error: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		// Exact string equality: a concatenated-SQL impl would break or mangle it.
+		expect(body?.result?.text).toBe(text);
+		expect((await listNotes(page.request)).find((r) => r?.text === text)?.text).toBe(text);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a signed-in user can add a note that appears in the list', async ({ page }) => {
+	test('a unicode / emoji note round-trips unchanged', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signIn(page);
-		await addNote(page, uniq('note'));
+
+		const text = `${uniq('uni')} caf\u00e9 \u65e5\u672c\u8a9e \ud83d\ude42 \u2014 na\u00efve`;
+		await rpc(page.request, 'api.addNote', [text]);
+		expect((await listNotes(page.request)).find((r) => r?.text === text)?.text).toBe(text);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('notes and session persist across a full reload', async ({ page }) => {
+	test('adding the same text twice creates two separate rows (no dedup)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-
 		await signIn(page);
-		const text = uniq('note');
-		await addNote(page, text);
 
-		await page.reload();
-		await expect(page.getByTestId('profile-sub')).toBeVisible({ timeout: SIGNIN });
-		await expect.poll(() => note(page, text).count(), { timeout: T }).toBe(1);
+		const text = uniq('dupnote');
+		await rpc(page.request, 'api.addNote', [text]);
+		await rpc(page.request, 'api.addNote', [text]);
+		const matches = (await listNotes(page.request)).filter((r) => r?.text === text);
+		expect(matches, 'both identical notes must be stored as separate rows').toHaveLength(2);
+		expect(matches[0].id).not.toBe(matches[1].id);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('the add-note button is disabled until non-empty text is entered', async ({ page }) => {
+	test('listNotes returns notes oldest-first with strictly increasing ids, stable across calls', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signIn(page);
 
-		const input = page.getByTestId('note-input');
-		const addBtn = page.getByTestId('add-note-btn');
-		await expect(input).toBeVisible();
-
-		// Empty / whitespace-only notes are rejected (trim before checking); a real
-		// note re-enables the control so it isn't simply always-disabled.
-		await input.fill('');
-		await expect(addBtn).toBeDisabled();
-		await input.fill('   ');
-		await expect(addBtn).toBeDisabled();
-		await input.fill(uniq('valid'));
-		await expect(addBtn).toBeEnabled();
+		const t1 = uniq('ord');
+		const t2 = uniq('ord');
+		const t3 = uniq('ord');
+		for (const t of [t1, t2, t3]) await rpc(page.request, 'api.addNote', [t]);
+
+		const rows = await listNotes(page.request);
+		const [i1, i2, i3] = indicesOf(rows, [t1, t2, t3]);
+		expect([i1, i2, i3].every((i) => i >= 0), `missing notes: ${JSON.stringify([i1, i2, i3])}`).toBe(true);
+		// Creation order preserved by an explicit ORDER BY.
+		expect(i1).toBeLessThan(i2);
+		expect(i2).toBeLessThan(i3);
+		expect(rows[i1].id).toBeLessThan(rows[i2].id);
+		expect(rows[i2].id).toBeLessThan(rows[i3].id);
+
+		// A fresh query yields the identical relative order (not unspecified row order).
+		const again = await listNotes(page.request);
+		const [j1, j2, j3] = indicesOf(again, [t1, t2, t3]);
+		expect(j1).toBeLessThan(j2);
+		expect(j2).toBeLessThan(j3);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a note with SQL/HTML metacharacters is stored and shown verbatim', async ({ page }) => {
+	test('api.addNote rejects blank / whitespace / non-string text (no row inserted)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signIn(page);
+		const before = (await listNotes(page.request)).length;
 
-		// Single quotes must round-trip through the DSQL table (parameterized
-		// query, not concatenated SQL); markup must render as text, not inject.
-		const token = uniq('sqlnote');
-		const text = `${token} ' OR '1'='1 -- <b>BOOM</b> "q"`;
-		await page.getByTestId('note-input').fill(text);
-		await page.getByTestId('add-note-btn').click();
+		for (const bad of [[''], ['   '], [42]] as unknown[][]) {
+			const r = await rpc(page.request, 'api.addNote', bad);
+			expect(r.status, `unexpected HTTP ${r.status}`).toBeLessThan(500);
+			expect(r.body?.error, `must reject ${JSON.stringify(bad)} with an error envelope`).toBeTruthy();
+			expect(r.body?.result ?? null).toBeNull();
+		}
+		const missing = await rpc(page.request, 'api.addNote', undefined, { omitParams: true });
+		expect(missing.body?.error, 'a missing argument must be rejected').toBeTruthy();
 
-		// Scope by the clean unique token (a substring) so it matches whether or
-		// not a buggy impl strips the markup.
-		const row = note(page, token);
-		await expect.poll(() => row.count(), { timeout: T }).toBe(1);
-		await expect(row).toContainText(`' OR '1'='1`);
-		await expect(row).toContainText('<b>BOOM</b>');
-		await expect(row.locator('b')).toHaveCount(0);
+		expect((await listNotes(page.request)).length, 'no rejected note may be inserted').toBe(before);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('multiple notes persist across reload and the editor still works afterward', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-		await signIn(page);
-
-		const a = uniq('note');
-		const b = uniq('note');
-		const c = uniq('note');
-		await addNote(page, a);
-		await addNote(page, b);
-		await addNote(page, c);
-
-		// All three survive a full reload (re-read from the DSQL table, scoped to
-		// this signed-in user).
-		await page.reload();
-		await expect(page.getByTestId('profile-sub')).toBeVisible({ timeout: SIGNIN });
-		await expect.poll(() => note(page, a).count(), { timeout: T }).toBe(1);
-		await expect.poll(() => note(page, b).count(), { timeout: T }).toBe(1);
-		await expect.poll(() => note(page, c).count(), { timeout: T }).toBe(1);
-
-		// The editor remains functional after the reload — a 4th note still adds.
-		const d = uniq('note');
-		await addNote(page, d);
-		await expect.poll(() => note(page, d).count(), { timeout: T }).toBe(1);
+	test('note methods require a session — an unauthenticated call is refused', async ({ request }) => {
+		// The top-level `request` fixture carries no sign-in cookie.
+		const l = await rpc(request, 'api.listNotes', []);
+		expect(l.status, `unexpected HTTP ${l.status}`).toBeLessThan(500);
+		expect(l.body?.error, 'unauthenticated listNotes must yield an error envelope').toBeTruthy();
+		expect(l.body?.result ?? null).toBeNull();
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		const a = await rpc(request, 'api.addNote', ['hijack']);
+		expect(a.body?.error, 'unauthenticated addNote must yield an error envelope').toBeTruthy();
+		expect(a.body?.result ?? null).toBeNull();
 	});
 
-	test('notes are listed oldest-first and keep that order across a reload', async ({ page }) => {
+	// --- Page smoke: OIDC redirect flow + thin note client ---
+
+	test('signed-out visitor sees only the sign-in button', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
-		await signIn(page);
 
-		const t1 = uniq('ord');
-		const t2 = uniq('ord');
-		const t3 = uniq('ord');
-		await addNote(page, t1);
-		await addNote(page, t2);
-		await addNote(page, t3);
-
-		// Oldest-first: t1 before t2 before t3 (relative order, robust to other
-		// interleaved notes from the shared stub user).
-		const before = await indicesOf(page, [t1, t2, t3]);
-		expect(before.every((i) => i >= 0), `missing notes: ${JSON.stringify(before)}`).toBe(true);
-		expect(before[0]).toBeLessThan(before[1]);
-		expect(before[1]).toBeLessThan(before[2]);
-
-		// A reload re-reads the table; the order must be identical. An impl with no
-		// explicit ORDER BY can return a different order here.
-		await page.reload();
-		await expect(page.getByTestId('profile-sub')).toBeVisible({ timeout: SIGNIN });
-		await expect.poll(() => note(page, t3).count(), { timeout: T }).toBe(1);
-		const after = await indicesOf(page, [t1, t2, t3]);
-		expect(after.every((i) => i >= 0), `missing after reload: ${JSON.stringify(after)}`).toBe(true);
-		expect(after[0]).toBeLessThan(after[1]);
-		expect(after[1]).toBeLessThan(after[2]);
+		await expect(page.getByTestId('signin-btn')).toBeVisible({ timeout: T });
+		await expect(page.getByTestId('note-input')).toHaveCount(0);
+		await expect(page.getByTestId('profile-sub')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a note added after reload appears last in creation order', async ({ page }) => {
+	test('OIDC sign-in shows the subject id and note editor; a note added via the page persists across reload', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signIn(page);
+		await expect(page.getByTestId('signin-btn')).toHaveCount(0);
+		await expect(page.getByTestId('note-input')).toBeVisible();
 
-		const t1 = uniq('post');
-		const t2 = uniq('post');
-		await addNote(page, t1);
-		await addNote(page, t2);
+		const text = uniq('note');
+		await page.getByTestId('note-input').fill(text);
+		await page.getByTestId('add-note-btn').click();
+		await expect.poll(() => note(page, text).count(), { timeout: T }).toBe(1);
 
 		await page.reload();
 		await expect(page.getByTestId('profile-sub')).toBeVisible({ timeout: SIGNIN });
-		await expect.poll(() => note(page, t2).count(), { timeout: T }).toBe(1);
-
-		// A note created AFTER the reload must sort after the earlier two (newest
-		// at the bottom of an oldest-first list) — proving order is driven by a
-		// stored timestamp/id, not insertion-into-a-client-array order.
-		const t3 = uniq('post');
-		await addNote(page, t3);
-
-		const idx = await indicesOf(page, [t1, t2, t3]);
-		expect(idx.every((i) => i >= 0), `missing notes: ${JSON.stringify(idx)}`).toBe(true);
-		expect(idx[0]).toBeLessThan(idx[1]);
-		expect(idx[1]).toBeLessThan(idx[2]);
+		await expect.poll(() => note(page, text).count(), { timeout: T }).toBe(1);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('adding the same text twice creates two separate note rows', async ({ page }) => {
+	test('the add-note button is disabled until non-empty text is entered', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signIn(page);
 
-		// Notes are not deduplicated.
-		const text = uniq('dupnote');
-		for (let i = 0; i < 2; i++) {
-			await page.getByTestId('note-input').fill(text);
-			await page.getByTestId('add-note-btn').click();
-		}
-		// Poll to 2 (never satisfied at 1, so a dedupe-by-text impl that keeps a
-		// single row fails here).
-		await expect.poll(() => note(page, text).count(), { timeout: T }).toBe(2);
+		const input = page.getByTestId('note-input');
+		const addBtn = page.getByTestId('add-note-btn');
+		await expect(input).toBeVisible();
 
-		// Both rows survive a reload.
-		await page.reload();
-		await expect(page.getByTestId('profile-sub')).toBeVisible({ timeout: SIGNIN });
-		await expect.poll(() => note(page, text).count(), { timeout: T }).toBe(2);
+		await input.fill('');
+		await expect(addBtn).toBeDisabled();
+		await input.fill('   ');
+		await expect(addBtn).toBeDisabled();
+		await input.fill(uniq('valid'));
+		await expect(addBtn).toBeEnabled();
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('a unicode / emoji note is stored and shown verbatim', async ({ page }) => {
+	test('a note with markup renders as literal text, not an injected element', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signIn(page);
 
-		const token = uniq('uni');
-		const text = `${token} café 日本語 🙂 — naïve`;
+		const token = uniq('xss');
+		const text = `${token} <b>BOOM</b>`;
 		await page.getByTestId('note-input').fill(text);
 		await page.getByTestId('add-note-btn').click();
 
 		const row = note(page, token);
 		await expect.poll(() => row.count(), { timeout: T }).toBe(1);
-		await expect(row).toContainText('日本語', { timeout: T });
-		await expect(row).toContainText('🙂', { timeout: T });
-
-		await page.reload();
-		await expect(page.getByTestId('profile-sub')).toBeVisible({ timeout: SIGNIN });
-		await expect(note(page, token)).toContainText('🙂', { timeout: T });
+		await expect(row).toContainText('<b>BOOM</b>');
+		await expect(row.locator('b')).toHaveCount(0);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
diff --git a/tasks/sql-kb-catalog/PROMPT.md b/tasks/sql-kb-catalog/PROMPT.md
index d815cd10..6dd85a52 100644
--- a/tasks/sql-kb-catalog/PROMPT.md
+++ b/tasks/sql-kb-catalog/PROMPT.md
@@ -2,36 +2,48 @@
 
 Build a product catalog with an FAQ search panel in this AWS Blocks app. Products live in a real SQL table (add + list). A separate panel answers questions by searching over a small folder of FAQ documents.
 
+The core of this task is **using the framework**: products are added and listed through an **`api` namespace** backed by the **relational database block**, and FAQ answers come from the **knowledge-base block**. The page is a thin client over that API.
+
 ## Setup (do this first)
 
-The workspace has already been scaffolded. Begin by reading README.md, then do all your edits in this workspace.
+The workspace has already been scaffolded. Begin by reading README.md (and any AGENTS.md), then do all your edits in this workspace.
 
 ## Requirements
 
-### Product catalog (SQL)
-1. Products are stored in a **SQL table** via the relational database block (PGlite locally). Create the table with a numbered `.sql` migration file (e.g. `aws-blocks/migrations/001_products.sql`).
-2. A user types a product name into an input and clicks a button to add it; the new product is `INSERT`ed and then appears in the list.
-3. The catalog lists every product, each rendering its name.
+### The `api` namespace (primary surface)
+
+Expose an **`api` namespace** (the framework's server-side RPC surface — a `POST /aws-blocks/api` JSON-RPC endpoint) with these methods:
+
+1. **`api.addProduct(name)`** — `INSERT`s a product row into the **SQL table** via the relational database block (PGlite locally) and returns the created row `{ id, name }` (`id` a number). A blank/whitespace-only or non-string `name` is rejected with a JSON-RPC **error** envelope (no row inserted).
+2. **`api.listProducts()`** — returns every product as `[{ id, name }]`, read back from the SQL table, in a stable order (oldest first / ascending `id`). Because rows live in real SQL, they persist across reloads and process restarts.
+3. **`api.searchKb(query)`** — runs a retrieval query against the **knowledge-base block** (local TF-IDF over your `knowledge/` folder) and returns an array of hits, each `{ text }` (the matched FAQ snippet/text). An empty/blank query returns an empty array (no error).
+
+You must create the SQL table with a numbered `.sql` migration file (e.g. `aws-blocks/migrations/001_products.sql`).
+
+### The knowledge base (real seeded content)
+
+- **Create a `knowledge/` folder** (e.g. `./knowledge/`) containing **at least one real `.md` FAQ document**, and point the knowledge-base block at it.
+- **Required seed content:** at least one FAQ doc must cover your store's **return / refund policy** and must contain the words **`return`** and **`refund`** (the grader searches for these and asserts the returned snippet really contains them). Write a real short FAQ (a few Q&A lines) — not a stub.
+
+### The page (thin client / light smoke)
 
-### FAQ search (knowledge base)
-4. **You must create a `knowledge/` folder** (e.g. `./knowledge/`) containing **at least one `.md` FAQ document**, and point the knowledge-base block at it. Locally the block indexes the folder (TF-IDF) and answers retrieval queries.
-5. **Required seed content:** at least one FAQ doc must cover your store's **return / refund policy** and must contain the words **`return`** and **`refund`** (the grader searches for these). Write a real short FAQ (a few Q&A lines) — not a stub.
-6. A user types a question into a search input and clicks a button; the panel shows one result row per knowledge-base hit.
+1. A product-name input + add button (calls `api.addProduct`); the catalog lists every product (from `api.listProducts`), one row per product rendering its name.
+2. An FAQ question input + search button (calls `api.searchKb`); the panel shows one result row per hit.
 
 ## Selector contract
 
-The Playwright test grades your work using these `data-testid` hooks. Implement them exactly.
+The page smoke test uses these `data-testid` hooks. Implement them exactly.
 
 | Selector | Element | Purpose |
 |---|---|---|
 | `[data-testid=product-name-input]` | `<input type="text">` | Where the user types a new product name |
-| `[data-testid=add-product-btn]` | `<button>` | Inserts the product into the SQL table |
-| `[data-testid=product-item]` | one per product | A catalog row; must render the product's name as its text |
+| `[data-testid=add-product-btn]` | `<button>` | Inserts the product (calls `api.addProduct`) |
+| `[data-testid=product-item]` | one per product | A catalog row; renders the product's name as its text |
 | `[data-testid=kb-query-input]` | `<input type="text">` | Where the user types an FAQ question |
-| `[data-testid=kb-search-btn]` | `<button>` | Runs the knowledge-base search |
+| `[data-testid=kb-search-btn]` | `<button>` | Runs the knowledge-base search (`api.searchKb`) |
 | `[data-testid=kb-result]` | one per search hit | A single FAQ search result |
 
-A `[data-testid=product-item]` must contain the product's name (the test locates a product via `filter({ hasText: name })`). After a search that matches the seeded FAQ, at least one `[data-testid=kb-result]` must be present.
+A `[data-testid=product-item]` must contain the product's name. After a search that matches the seeded FAQ, at least one `[data-testid=kb-result]` must be present.
 
 The mount point for your page is the existing root element / page. Replace the template's placeholder content.
 
diff --git a/tasks/sql-kb-catalog/test.spec.ts b/tasks/sql-kb-catalog/test.spec.ts
index 1ae8d283..548483f9 100644
--- a/tasks/sql-kb-catalog/test.spec.ts
+++ b/tasks/sql-kb-catalog/test.spec.ts
@@ -1,103 +1,152 @@
-import { test, expect, type Page } from '@playwright/test';
+import { test, expect, type Page, type APIRequestContext } from '@playwright/test';
 
-const BASE = process.env.BLOCKS_URL ?? 'http://localhost:3000';
+const BASE = process.env.BLOCKS_URL || 'http://localhost:3000';
 const T = 10_000;
 
 const RUN = process.env.RUN_ID || String(Date.now());
-let seq = 0;
-const uniq = (base: string) => `${base}-${RUN}-${++seq}-${Date.now()}`;
+let rpcSeq = 0;
+let uniqSeq = 0;
+const uniq = (base: string) => `${base}-${RUN}-${++uniqSeq}-${Date.now()}`;
 
-// Per-test no-error gate: ONLY uncaught page errors.
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
 	return sink;
 }
 
-const product = (page: Page, name: string) => page.getByTestId('product-item').filter({ hasText: name });
-
-async function addProduct(page: Page, name: string): Promise<void> {
-	await expect(page.getByTestId('product-name-input')).toBeVisible({ timeout: T });
-	await page.getByTestId('product-name-input').fill(name);
-	await page.getByTestId('add-product-btn').click();
-	await expect.poll(() => product(page, name).count(), { timeout: T }).toBe(1);
+async function rpc(
+	ctx: APIRequestContext,
+	method: string,
+	params: unknown[] | undefined,
+	opts: { omitParams?: boolean } = {},
+): Promise<{ status: number; body: any }> {
+	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++rpcSeq };
+	if (!opts.omitParams) data.params = params ?? [];
+	const res = await ctx.post(`${BASE}/aws-blocks/api`, {
+		headers: { 'Content-Type': 'application/json' },
+		data,
+	});
+	return { status: res.status(), body: await res.json().catch(() => null) };
 }
 
-async function searchFaq(page: Page, query: string): Promise<void> {
-	await expect(page.getByTestId('kb-query-input')).toBeVisible({ timeout: T });
-	await page.getByTestId('kb-query-input').fill(query);
-	await page.getByTestId('kb-search-btn').click();
+async function listProducts(ctx: APIRequestContext): Promise<any[]> {
+	const { body } = await rpc(ctx, 'api.listProducts', []);
+	expect(body?.error, `JSON-RPC error from listProducts: ${JSON.stringify(body?.error)}`).toBeFalsy();
+	return Array.isArray(body?.result) ? body.result : [];
 }
 
+const product = (page: Page, name: string) => page.getByTestId('product-item').filter({ hasText: name });
+
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
 test.describe('sql-kb-catalog', () => {
-	test('shows the product form and the FAQ search controls', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+	// --- Framework surface: products in real SQL, FAQ via knowledge base ---
 
-		await expect(page.getByTestId('product-name-input')).toBeVisible({ timeout: T });
-		await expect(page.getByTestId('add-product-btn')).toBeVisible();
-		await expect(page.getByTestId('kb-query-input')).toBeVisible();
-		await expect(page.getByTestId('kb-search-btn')).toBeVisible();
+	test('addProduct inserts a row that listProducts reads back with a numeric id', async ({ request }) => {
+		const name = uniq('prod');
+		const { body } = await rpc(request, 'api.addProduct', [name]);
+		expect(body?.error, `JSON-RPC error from addProduct: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		expect(typeof body?.result?.id, 'addProduct must return a numeric id').toBe('number');
+		expect(body?.result?.name).toBe(name);
+
+		const rows = await listProducts(request);
+		const row = rows.find((r) => r?.name === name);
+		expect(row, 'the inserted product must be listed').toBeTruthy();
+		expect(row.id).toBe(body.result.id);
+	});
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('multiple products all persist in the SQL table in a stable ascending order', async ({ request }) => {
+		const a = uniq('alpha');
+		const b = uniq('bravo');
+		const ra = await rpc(request, 'api.addProduct', [a]);
+		const rb = await rpc(request, 'api.addProduct', [b]);
+		expect(ra.body?.error, `error: ${JSON.stringify(ra.body?.error)}`).toBeFalsy();
+		expect(rb.body?.error, `error: ${JSON.stringify(rb.body?.error)}`).toBeFalsy();
+
+		const rows = await listProducts(request);
+		const ia = rows.findIndex((r) => r?.name === a);
+		const ib = rows.findIndex((r) => r?.name === b);
+		expect(ia, 'first product must be listed').toBeGreaterThanOrEqual(0);
+		expect(ib, 'second product must be listed').toBeGreaterThanOrEqual(0);
+		// Insertion order preserved: the earlier row precedes the later row.
+		expect(ia).toBeLessThan(ib);
+		expect(rows.find((r) => r?.name === a).id).toBeLessThan(rows.find((r) => r?.name === b).id);
 	});
 
-	test('adding a product inserts it into the catalog list', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+	test('addProduct rejects a blank / non-string name (no row inserted)', async ({ request }) => {
+		const before = (await listProducts(request)).length;
 
-		await addProduct(page, uniq('prod'));
+		const blank = await rpc(request, 'api.addProduct', ['   ']);
+		expect(blank.status, `unexpected HTTP ${blank.status}`).toBeLessThan(500);
+		expect(blank.body?.error, 'a blank name must yield a JSON-RPC error envelope').toBeTruthy();
+		expect(blank.body?.result ?? null).toBeNull();
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
-	});
+		const missing = await rpc(request, 'api.addProduct', undefined, { omitParams: true });
+		expect(missing.body?.error, 'a missing name must yield a JSON-RPC error envelope').toBeTruthy();
 
-	test('a product persists across a full reload (real SQL row)', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+		expect((await listProducts(request)).length, 'no row may be inserted for a rejected name').toBe(before);
+	});
 
-		const name = uniq('prod');
-		await addProduct(page, name);
+	test('searchKb over the seeded FAQ returns a hit whose text really mentions the policy', async ({ request }) => {
+		const { body } = await rpc(request, 'api.searchKb', ['return refund policy']);
+		expect(body?.error, `JSON-RPC error from searchKb: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		const hits = Array.isArray(body?.result) ? body.result : [];
+		expect(hits.length, 'the seeded return/refund FAQ must produce at least one hit').toBeGreaterThan(0);
+		// Prove real retrieval, not a stub: some hit's text contains the seed words.
+		const joined = hits.map((h: any) => String(h?.text ?? '')).join('\n').toLowerCase();
+		expect(joined).toMatch(/return/);
+		expect(joined).toMatch(/refund/);
+	});
 
-		await page.reload();
-		await expect.poll(() => product(page, name).count(), { timeout: T }).toBe(1);
+	test('searchKb matches a single policy keyword too', async ({ request }) => {
+		const { body } = await rpc(request, 'api.searchKb', ['refund']);
+		expect(body?.error, `JSON-RPC error from searchKb: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		const hits = Array.isArray(body?.result) ? body.result : [];
+		expect(hits.length, 'a single-keyword query must still hit the FAQ').toBeGreaterThan(0);
+	});
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	test('searchKb with a blank query returns an empty array (no error)', async ({ request }) => {
+		const { body } = await rpc(request, 'api.searchKb', ['']);
+		expect(body?.error, `JSON-RPC error from searchKb: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		expect(Array.isArray(body?.result), 'searchKb must return an array').toBe(true);
+		expect(body?.result.length).toBe(0);
 	});
 
-	test('two products coexist in the catalog', async ({ page }) => {
+	// --- Page smoke: the thin client wires the inputs to the api ---
+
+	test('shows the product form and the FAQ search controls', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		const a = uniq('alpha');
-		const b = uniq('bravo');
-		await addProduct(page, a);
-		await addProduct(page, b);
-
-		await expect.poll(() => product(page, a).count(), { timeout: T }).toBe(1);
-		await expect.poll(() => product(page, b).count(), { timeout: T }).toBe(1);
+		await expect(page.getByTestId('product-name-input')).toBeVisible({ timeout: T });
+		await expect(page.getByTestId('add-product-btn')).toBeVisible();
+		await expect(page.getByTestId('kb-query-input')).toBeVisible();
+		await expect(page.getByTestId('kb-search-btn')).toBeVisible();
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('FAQ search over the seeded knowledge base returns a result', async ({ page }) => {
+	test('adding a product through the page lists it and it survives a reload', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		// The PROMPT requires a seeded FAQ doc covering the return/refund policy.
-		// Guard: no result is rendered before a search runs, so an impl that
-		// shows results on load (ignoring the query) fails here.
-		await expect(page.getByTestId('kb-result')).toHaveCount(0);
-		await searchFaq(page, 'return refund policy');
-		await expect(page.getByTestId('kb-result').first()).toBeVisible({ timeout: T });
+		const name = uniq('prod');
+		await page.getByTestId('product-name-input').fill(name);
+		await page.getByTestId('add-product-btn').click();
+		await expect.poll(() => product(page, name).count(), { timeout: T }).toBe(1);
+
+		await page.reload();
+		await expect.poll(() => product(page, name).count(), { timeout: T }).toBe(1);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('FAQ search for a single policy keyword returns a result', async ({ page }) => {
+	test('searching the FAQ through the page renders a result (and none before searching)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
+		// No result is shown until a search runs.
 		await expect(page.getByTestId('kb-result')).toHaveCount(0);
-		await searchFaq(page, 'refund');
+		await page.getByTestId('kb-query-input').fill('return refund policy');
+		await page.getByTestId('kb-search-btn').click();
 		await expect(page.getByTestId('kb-result').first()).toBeVisible({ timeout: T });
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);