From 09e469ca036e05ec392819b17ccb082879d0b42f Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Sun, 12 Jul 2026 05:02:55 +0000
Subject: [PATCH 1/8] feat(bench): reshape tasks to api-first framework-focus
 grading

---
 tasks/async-word-counter/PROMPT.md       |  49 +--
 tasks/async-word-counter/test.spec.ts    | 344 ++++++-------------
 tasks/auth-notes/PROMPT.md               |  32 +-
 tasks/auth-notes/test.spec.ts            | 242 +++++++------
 tasks/cognito-profile/PROMPT.md          |  29 +-
 tasks/cognito-profile/test.spec.ts       | 275 +++++----------
 tasks/collab-presence-board/PROMPT.md    |  30 +-
 tasks/collab-presence-board/test.spec.ts | 279 +++++----------
 tasks/file-gallery/PROMPT.md             |  29 +-
 tasks/file-gallery/test.spec.ts          | 411 ++++++++---------------
 tasks/kb-chat-agent/PROMPT.md            |  36 +-
 tasks/kb-chat-agent/test.spec.ts         | 267 +++++----------
 tasks/oidc-dsql-notes/PROMPT.md          |  41 ++-
 tasks/oidc-dsql-notes/test.spec.ts       | 297 +++++++---------
 tasks/sql-kb-catalog/PROMPT.md           |  40 ++-
 tasks/sql-kb-catalog/test.spec.ts        | 151 ++++++---
 16 files changed, 1020 insertions(+), 1532 deletions(-)

diff --git a/tasks/async-word-counter/PROMPT.md b/tasks/async-word-counter/PROMPT.md
index 4b0a5d3dc..c6c2d92c2 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 ff72ec551..efa6f842f 100644
--- a/tasks/async-word-counter/test.spec.ts
+++ b/tasks/async-word-counter/test.spec.ts
@@ -1,297 +1,177 @@
-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 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()}`;
 
-// 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: ++seq };
+	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 });
 
 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();
-
-		// 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 });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	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);
 	});
 
-	test('the word count is computed accurately for a longer phrase', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		const phrase = phraseWithWords(8);
-		await page.getByTestId('wc-input').fill(phrase);
-		await page.getByTestId('wc-submit').click();
+	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);
+	});
 
-		// 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('a single token counts as exactly one word', async ({ request }) => {
+		const id = await enqueue(request, uniq('solo'));
+		expect(await countOf(request, id)).toBe(1);
+	});
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	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');
 	});
 
-	test('a finished job persists across a full reload', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
+	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();
+		}
+	});
 
-		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('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();
+	});
 
-		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 });
+	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);
+	});
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+	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);
+
+		// A fresh caller (new request context has no client memory) must still
+		// see the persisted job via listJobs — proof it lives in the store.
+		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);
 	});
 
-	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 }) => {
-		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 }) => {
+	test('submitting through the page resolves to done and persists across reload', 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 97e6faf04..b8a8a137a 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.
+
+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 4b8dd66d1..01e54be96 100644
--- a/tasks/auth-notes/test.spec.ts
+++ b/tasks/auth-notes/test.spec.ts
@@ -1,24 +1,39 @@
-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 = 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()}`;
 
-// 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: ++seq };
+	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);
@@ -28,23 +43,16 @@ async function signUp(page: Page, username: string): Promise<void> {
 }
 
 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 +60,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 +81,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 +90,128 @@ 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[] = [];
-
-		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 });
+	// --- Framework surface: notes read/written through the api namespace ---
 
-		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 });
+	test('a fresh user\u2019s api.getNote is the empty string', async ({ page }) => {
+		await page.goto(BASE);
+		await signUp(page, uniq('fresh'));
 
-		await ctxA.close();
-		await ctxB.close();
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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('');
 	});
 
-	test('saving again overwrites the note; only the latest value persists across reload', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('api.saveNote overwrites (does not append) and api.getNote reads it back', async ({ 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 });
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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);
 	});
 
-	test('saving an empty textarea clears the note, and the cleared state persists', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('saving an empty string clears the note (not a no-op)', async ({ 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 });
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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('');
 	});
 
-	test('note text is rendered verbatim, not interpreted as HTML', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('notes are stored verbatim — markup round-trips as a literal string', async ({ 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>`;
-		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 rpc(page.request, 'api.saveNote', [raw]);
+		// Exact string equality: no HTML escaping (&amp;) and no stripping.
+		expect((await rpc(page.request, 'api.getNote', [])).body?.result).toBe(raw);
+	});
 
-		await page.reload();
-		await expect(page.getByTestId('note-display')).toHaveText(raw, { timeout: T });
+	test('a long note round-trips unchanged through the api', async ({ page }) => {
+		await page.goto(BASE);
+		await signUp(page, uniq('alice'));
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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);
 	});
 
-	test('after reload the textarea is pre-filled with the saved note for editing', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('a missing / non-string argument is rejected and leaves the note unchanged', async ({ 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 keep = uniq('keep');
+		await rpc(page.request, 'api.saveNote', [keep]);
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		// 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);
 	});
 
-	test('a long note round-trips verbatim across reload', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('note methods require a session — an unauthenticated call is refused', async ({ page, request }) => {
+		// 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')]);
+
+		// 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();
+	});
 
-		await page.reload();
-		await expect(page.getByTestId('note-display')).toHaveText(note, { timeout: T });
+	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 b4925d2e6..1e5a040e5 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`). 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 |
 |---|---|---|
diff --git a/tasks/cognito-profile/test.spec.ts b/tasks/cognito-profile/test.spec.ts
index b8b896844..5e8353697 100644
--- a/tasks/cognito-profile/test.spec.ts
+++ b/tasks/cognito-profile/test.spec.ts
@@ -7,27 +7,31 @@ const RUN = process.env.RUN_ID || String(Date.now());
 let seq = 0;
 const uniq = (base: string) => `${base}-${RUN}-${++seq}-${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: ++seq },
+	});
+	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;
@@ -48,7 +52,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);
@@ -60,140 +65,120 @@ async function signIn(page: Page, request: APIRequestContext, user: string): Pro
 }
 
 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);
+	// --- Framework surface: identity from the auth session over the api ---
 
-		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);
+	test('api.whoami reflects the signed-in identity and is gated to authenticated callers', async ({ page, request }) => {
+		// 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();
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		await page.goto(BASE);
+		const email = await signIn(page, request, uniq('user'));
+
+		// 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);
 	});
 
-	test('submitting an email advances to the code-entry view', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('after sign-out the session is gone — api.whoami is unauthenticated again', async ({ page, request }) => {
 		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();
 
-		await requestCode(page, `${uniq('user')}@test.com`);
-		await expect(page.getByTestId('otp-submit')).toBeVisible();
-		await expect(page.getByTestId('auth-email')).toHaveCount(0);
+		await page.getByTestId('signout-btn').click();
+		await expect(page.getByTestId('auth-email')).toBeVisible({ timeout: T });
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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();
 	});
 
-	test('completing the OTP lands on a profile with a sign-out button', 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 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('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('the profile renders the exact email that signed in', 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);
 
 		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('signing out returns to the signed-out email form', 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);
-
-		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, { 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 +186,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 0bbd972d9..b8dbec092 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 d2e349abe..d572b66aa 100644
--- a/tasks/collab-presence-board/test.spec.ts
+++ b/tasks/collab-presence-board/test.spec.ts
@@ -1,4 +1,4 @@
-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 SYNC = 8_000;
@@ -7,118 +7,99 @@ const RUN = process.env.RUN_ID || String(Date.now());
 let seq = 0;
 const uniq = (base: string) => `${base}-${RUN}-${++seq}-${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: ++seq },
+	});
+	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.
+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);
+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 are stored and read back verbatim (markup preserved as literal text)', 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);
-
-		const nameA = uniq('ann');
-		const nameB = uniq('bob');
-		await join(tabA, nameA);
-		await join(tabB, nameB);
+	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);
+	});
 
-		// 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);
+	test('a blank or whitespace-only name is rejected and does not change the roster', async ({ request }) => {
+		const before = (await roster(request)).length;
+		for (const bad of ['', '   ', '\t\n']) {
+			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();
+		}
+		// No phantom entry was added by the rejected joins.
+		const after = await roster(request);
+		expect(after).not.toContain('');
+		expect(after.length).toBe(before);
+	});
 
-		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 +110,43 @@ 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);
-
-		// 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);
-
-		// ...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 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 reload restores the shared roster (page fetches api.listPresent on load)', async ({ page }) => {
 		const errors = watchErrors(page);
 		await page.goto(BASE);
 
-		const name = uniq('dup');
-		await join(page, name);
+		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 });
 
-		// 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 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 });
 
 		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 +157,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([]);
-	});
-
-	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 });
-		}
+		const name = uniq('rt');
+		await tabA.getByTestId('presence-name-input').fill(name);
+		await tabA.getByTestId('join-btn').click();
 
-		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/file-gallery/PROMPT.md b/tasks/file-gallery/PROMPT.md
index 5dd0266e1..bc07a3749 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 aea9dd2bf..31bcd6cb9 100644
--- a/tasks/file-gallery/test.spec.ts
+++ b/tasks/file-gallery/test.spec.ts
@@ -1,4 +1,4 @@
-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 = 8_000;
@@ -7,339 +7,202 @@ const RUN = process.env.RUN_ID || String(Date.now());
 let seq = 0;
 const uniq = (base: string) => `${base}-${RUN}-${++seq}-${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: ++seq };
+	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}${u.startsWith('/') ? '' : '/'}${u}`);
 
-		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();
+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();
-		}
-
-		// 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);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		const noParams = await rpc(request, 'api.putFile', undefined, { omitParams: true });
+		expect(noParams.body?.error, 'no params must yield a JSON-RPC error envelope').toBeTruthy();
 	});
 
-	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 5756f3fa1..6d64149f9 100644
--- a/tasks/kb-chat-agent/PROMPT.md
+++ b/tasks/kb-chat-agent/PROMPT.md
@@ -1,6 +1,8 @@
 # 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)
 
@@ -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 c614a44ea..e57ece78c 100644
--- a/tasks/kb-chat-agent/test.spec.ts
+++ b/tasks/kb-chat-agent/test.spec.ts
@@ -1,251 +1,160 @@
-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 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()}`;
 
-// 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: ++seq },
+	});
+	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();
-}
-
 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, uniq('please just say a short friendly hello and 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.
+		// Both turns' questions and distinct answers survive in the running log.
 		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.
 		await expect.poll(() => messages(page).count(), { timeout: T }).toBeGreaterThan(3);
 
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
diff --git a/tasks/oidc-dsql-notes/PROMPT.md b/tasks/oidc-dsql-notes/PROMPT.md
index 30240533b..94f0e6193 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 287eb0730..95717da26 100644
--- a/tasks/oidc-dsql-notes/test.spec.ts
+++ b/tasks/oidc-dsql-notes/test.spec.ts
@@ -1,4 +1,4 @@
-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 SIGNIN = 10_000;
@@ -8,22 +8,32 @@ const RUN = process.env.RUN_ID || String(Date.now());
 let seq = 0;
 const uniq = (base: string) => `${base}-${RUN}-${++seq}-${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: ++seq };
+	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 +42,185 @@ 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)));
 
 test.describe('oidc-dsql-notes', () => {
-	test('signed-out visitor sees only the sign-in button', async ({ page }) => {
-		const errors = watchErrors(page);
-		await page.goto(BASE);
-
-		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([]);
-	});
+	// --- Framework surface: notes stored/queried through the api + DSQL ---
 
-	test('OIDC sign-in via the stub IdP shows the subject id and the note editor', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('api.addNote inserts a row that api.listNotes reads back with a numeric id', async ({ page }) => {
 		await page.goto(BASE);
-
 		await signIn(page);
-		await expect(page.getByTestId('signin-btn')).toHaveCount(0);
-		await expect(page.getByTestId('note-input')).toBeVisible();
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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);
 	});
 
-	test('a signed-in user can add a note that appears in the list', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('notes are stored verbatim via parameterized SQL (quotes/markup round-trip, no injection)', async ({ page }) => {
 		await page.goto(BASE);
-
 		await signIn(page);
-		await addNote(page, uniq('note'));
 
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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);
 	});
 
-	test('notes and session persist across a full reload', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('a unicode / emoji note round-trips unchanged', async ({ 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);
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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);
 	});
 
-	test('the add-note button is disabled until non-empty text is entered', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('adding the same text twice creates two separate rows (no dedup)', async ({ 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();
-
-		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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);
 	});
 
-	test('a note with SQL/HTML metacharacters is stored and shown verbatim', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('listNotes returns notes oldest-first with strictly increasing ids, stable across calls', async ({ page }) => {
 		await page.goto(BASE);
 		await signIn(page);
 
-		// 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();
-
-		// 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(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
+		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);
 	});
 
-	test('multiple notes persist across reload and the editor still works afterward', async ({ page }) => {
-		const errors = watchErrors(page);
+	test('api.addNote rejects blank / whitespace / non-string text (no row inserted)', async ({ page }) => {
 		await page.goto(BASE);
 		await signIn(page);
+		const before = (await listNotes(page.request)).length;
 
-		const a = uniq('note');
-		const b = uniq('note');
-		const c = uniq('note');
-		await addNote(page, a);
-		await addNote(page, b);
-		await addNote(page, c);
+		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();
 
-		// 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);
+		expect((await listNotes(page.request)).length, 'no rejected note may be inserted').toBe(before);
+	});
 
-		// 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 d815cd101..6dd85a529 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 1ae8d283d..30b3db6ee 100644
--- a/tasks/sql-kb-catalog/test.spec.ts
+++ b/tasks/sql-kb-catalog/test.spec.ts
@@ -1,4 +1,4 @@
-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;
@@ -7,97 +7,144 @@ const RUN = process.env.RUN_ID || String(Date.now());
 let seq = 0;
 const uniq = (base: string) => `${base}-${RUN}-${++seq}-${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: ++seq };
+	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 });
+
 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([]);

From a862a56c722c4ffc3826b38d8e3c8553f2277187 Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Sun, 12 Jul 2026 09:15:16 +0000
Subject: [PATCH 2/8] test(bench): restore page-error gate + scope
 user-bubble/roster assertions per review

---
 tasks/auth-notes/test.spec.ts            | 21 +++++++++++++++++++++
 tasks/cognito-profile/test.spec.ts       |  6 ++++++
 tasks/collab-presence-board/test.spec.ts | 18 +++++++++++++-----
 tasks/kb-chat-agent/test.spec.ts         |  4 +++-
 tasks/oidc-dsql-notes/test.spec.ts       | 18 ++++++++++++++++++
 5 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/tasks/auth-notes/test.spec.ts b/tasks/auth-notes/test.spec.ts
index 01e54be96..fdb735bf9 100644
--- a/tasks/auth-notes/test.spec.ts
+++ b/tasks/auth-notes/test.spec.ts
@@ -93,15 +93,19 @@ test.describe('auth-notes', () => {
 	// --- Framework surface: notes read/written through the api namespace ---
 
 	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 { 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('');
+
+		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
 	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'));
 
@@ -115,9 +119,12 @@ test.describe('auth-notes', () => {
 		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 string clears the note (not a no-op)', async ({ page }) => {
+		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signUp(page, uniq('alice'));
 
@@ -125,9 +132,12 @@ test.describe('auth-notes', () => {
 		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('notes are stored verbatim — markup round-trips as a literal string', async ({ page }) => {
+		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signUp(page, uniq('alice'));
 
@@ -135,18 +145,24 @@ test.describe('auth-notes', () => {
 		await rpc(page.request, 'api.saveNote', [raw]);
 		// Exact string equality: no HTML escaping (&amp;) and no stripping.
 		expect((await rpc(page.request, 'api.getNote', [])).body?.result).toBe(raw);
+
+		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
 	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('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 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'));
 
@@ -165,9 +181,12 @@ test.describe('auth-notes', () => {
 
 		// 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'));
@@ -183,6 +202,8 @@ test.describe('auth-notes', () => {
 		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 }) => {
diff --git a/tasks/cognito-profile/test.spec.ts b/tasks/cognito-profile/test.spec.ts
index 5e8353697..6a811f7e3 100644
--- a/tasks/cognito-profile/test.spec.ts
+++ b/tasks/cognito-profile/test.spec.ts
@@ -68,6 +68,7 @@ test.describe('cognito-profile', () => {
 	// --- Framework surface: identity from the auth session over the api ---
 
 	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);
@@ -81,9 +82,12 @@ test.describe('cognito-profile', () => {
 		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('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', []);
@@ -95,6 +99,8 @@ test.describe('cognito-profile', () => {
 		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([]);
 	});
 
 	// --- Page smoke: the multi-view OTP flow ---
diff --git a/tasks/collab-presence-board/test.spec.ts b/tasks/collab-presence-board/test.spec.ts
index d572b66aa..74e4d22c6 100644
--- a/tasks/collab-presence-board/test.spec.ts
+++ b/tasks/collab-presence-board/test.spec.ts
@@ -70,16 +70,24 @@ test.describe('collab-presence-board', () => {
 	});
 
 	test('a blank or whitespace-only name is rejected and does not change the roster', async ({ request }) => {
-		const before = (await roster(request)).length;
-		for (const bad of ['', '   ', '\t\n']) {
+		// 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();
 		}
-		// No phantom entry was added by the rejected joins.
+
+		// 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);
-		expect(after).not.toContain('');
-		expect(after.length).toBe(before);
+		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);
 	});
 
 	test('multiple distinct visitors all persist in the shared roster', async ({ request }) => {
diff --git a/tasks/kb-chat-agent/test.spec.ts b/tasks/kb-chat-agent/test.spec.ts
index e57ece78c..ab0ed6f42 100644
--- a/tasks/kb-chat-agent/test.spec.ts
+++ b/tasks/kb-chat-agent/test.spec.ts
@@ -153,7 +153,9 @@ test.describe('kb-chat-agent', () => {
 		await expect.poll(() => bubbleWith(page, 'QUOKKA-9F42').count(), { timeout: REPLY }).toBeGreaterThan(0);
 
 		// Both turns' questions and distinct answers survive in the running log.
-		await expect(messages(page).filter({ hasText: q1 })).toHaveAttribute('data-role', 'user');
+		// 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(orderReply()).toHaveCount(1);
 		await expect.poll(() => messages(page).count(), { timeout: T }).toBeGreaterThan(3);
 
diff --git a/tasks/oidc-dsql-notes/test.spec.ts b/tasks/oidc-dsql-notes/test.spec.ts
index 95717da26..ae652077e 100644
--- a/tasks/oidc-dsql-notes/test.spec.ts
+++ b/tasks/oidc-dsql-notes/test.spec.ts
@@ -56,6 +56,7 @@ test.describe('oidc-dsql-notes', () => {
 	// --- 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);
 
@@ -67,9 +68,12 @@ test.describe('oidc-dsql-notes', () => {
 
 		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('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);
 
@@ -79,18 +83,24 @@ test.describe('oidc-dsql-notes', () => {
 		// 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 unicode / emoji note round-trips unchanged', async ({ page }) => {
+		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signIn(page);
 
 		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('adding the same text twice creates two separate rows (no dedup)', async ({ page }) => {
+		const errors = watchErrors(page);
 		await page.goto(BASE);
 		await signIn(page);
 
@@ -100,9 +110,12 @@ test.describe('oidc-dsql-notes', () => {
 		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('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);
 
@@ -125,9 +138,12 @@ test.describe('oidc-dsql-notes', () => {
 		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('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;
@@ -142,6 +158,8 @@ test.describe('oidc-dsql-notes', () => {
 		expect(missing.body?.error, 'a missing argument must be rejected').toBeTruthy();
 
 		expect((await listNotes(page.request)).length, 'no rejected note may be inserted').toBe(before);
+
+		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
 	test('note methods require a session — an unauthenticated call is refused', async ({ request }) => {

From de164b42a72dd7d1f0b6b3e8376dab8fe9283737 Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Sun, 12 Jul 2026 09:29:22 +0000
Subject: [PATCH 3/8] test(bench): assert full cognito email + pin workers:1
 assumption + align kb-chat prompt

---
 tasks/cognito-profile/test.spec.ts       | 2 +-
 tasks/collab-presence-board/test.spec.ts | 6 +++++-
 tasks/kb-chat-agent/PROMPT.md            | 2 +-
 3 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/tasks/cognito-profile/test.spec.ts b/tasks/cognito-profile/test.spec.ts
index 6a811f7e3..872054de5 100644
--- a/tasks/cognito-profile/test.spec.ts
+++ b/tasks/cognito-profile/test.spec.ts
@@ -149,7 +149,7 @@ test.describe('cognito-profile', () => {
 		// 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, { timeout: T });
+		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([]);
diff --git a/tasks/collab-presence-board/test.spec.ts b/tasks/collab-presence-board/test.spec.ts
index 74e4d22c6..e02ecd95f 100644
--- a/tasks/collab-presence-board/test.spec.ts
+++ b/tasks/collab-presence-board/test.spec.ts
@@ -32,7 +32,11 @@ async function roster(ctx: APIRequestContext): Promise<string[]> {
 	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.
+// 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;
 
 const presence = (page: Page, name: string) => page.getByTestId('presence-item').filter({ hasText: name });
diff --git a/tasks/kb-chat-agent/PROMPT.md b/tasks/kb-chat-agent/PROMPT.md
index 6d64149f9..dde398289 100644
--- a/tasks/kb-chat-agent/PROMPT.md
+++ b/tasks/kb-chat-agent/PROMPT.md
@@ -6,7 +6,7 @@ The core of this task is **using the framework**: the agent turn — retrieval,
 
 ## 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.
 

From d36b12a78a14d2692b1b2273d71c9a3af1bef127 Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Mon, 13 Jul 2026 11:47:04 +0000
Subject: [PATCH 4/8] =?UTF-8?q?test(bench):=20address=20review=20=E2=80=94?=
 =?UTF-8?q?=20gate=20getLastCode=20backdoor,=20split=20rpc/uniq=20seq,=20w?=
 =?UTF-8?q?orkers:1=20banners,=20edge-case=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- cognito-profile: require api.getLastCode be @blocksSkipCodegen + BLOCKS_MOCK-gated (test-only); add gating test; harness exports BLOCKS_MOCK=true
- split shared seq into rpcSeq (JSON-RPC id) + uniqSeq (test-data seed) across the 8 double-duty specs
- add 'HARNESS CONTRACT: requires workers:1' banner to those 8 specs
- file-gallery: present-but-empty-name rejection test; absUrl double-slash guard
- collab: rename verbatim-roundtrip test; add fresh-tab first-paint (mount listPresent) DOM smoke
- auth-notes PROMPT: store username verbatim in note key
- tasks/README.md: document intentional per-spec helper duplication + harness contract
---
 scripts/agent-bench/steps/3-build-and-test.sh |  7 +++
 tasks/README.md                               | 43 +++++++++++++++++++
 tasks/async-word-counter/test.spec.ts         |  8 ++--
 tasks/auth-notes/PROMPT.md                    |  2 +-
 tasks/auth-notes/test.spec.ts                 |  8 ++--
 tasks/cognito-profile/PROMPT.md               |  2 +-
 tasks/cognito-profile/test.spec.ts            | 24 +++++++++--
 tasks/collab-presence-board/test.spec.ts      | 29 +++++++++++--
 tasks/file-gallery/test.spec.ts               | 22 ++++++++--
 tasks/kb-chat-agent/test.spec.ts              |  8 ++--
 tasks/oidc-dsql-notes/test.spec.ts            |  8 ++--
 tasks/sql-kb-catalog/test.spec.ts             |  8 ++--
 12 files changed, 141 insertions(+), 28 deletions(-)
 create mode 100644 tasks/README.md

diff --git a/scripts/agent-bench/steps/3-build-and-test.sh b/scripts/agent-bench/steps/3-build-and-test.sh
index 77235ce67..c5c4b6cf3 100755
--- a/scripts/agent-bench/steps/3-build-and-test.sh
+++ b/scripts/agent-bench/steps/3-build-and-test.sh
@@ -32,6 +32,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
+
 # Write pessimistic defaults up front, then update on success. If any step
 # below fails (npm install, playwright install, the parser), the workflow
 # still sees valid values and the EVIDENCE JSON in step 4 is well-formed.
diff --git a/tasks/README.md b/tasks/README.md
new file mode 100644
index 000000000..0e37da2db
--- /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/test.spec.ts b/tasks/async-word-counter/test.spec.ts
index efa6f842f..3c07d1b2c 100644
--- a/tasks/async-word-counter/test.spec.ts
+++ b/tasks/async-word-counter/test.spec.ts
@@ -5,8 +5,9 @@ const APPEAR = 8_000;
 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()}`;
 
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
@@ -19,7 +20,7 @@ async function rpc(
 	params: unknown[] | undefined,
 	opts: { omitParams?: boolean } = {},
 ): Promise<{ status: number; body: any }> {
-	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++seq };
+	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' },
@@ -53,6 +54,7 @@ async function countOf(request: APIRequestContext, id: string): Promise<number>
 // 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', () => {
 	// --- Framework surface: counting + persistence graded through the api ---
 
diff --git a/tasks/auth-notes/PROMPT.md b/tasks/auth-notes/PROMPT.md
index b8a8a137a..2ad3ec432 100644
--- a/tasks/auth-notes/PROMPT.md
+++ b/tasks/auth-notes/PROMPT.md
@@ -12,7 +12,7 @@ The workspace has already been scaffolded. Begin by reading README.md (and any A
 
 ### 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.
+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).
diff --git a/tasks/auth-notes/test.spec.ts b/tasks/auth-notes/test.spec.ts
index fdb735bf9..8bdd58dac 100644
--- a/tasks/auth-notes/test.spec.ts
+++ b/tasks/auth-notes/test.spec.ts
@@ -5,8 +5,9 @@ const T = 8_000;
 const PASSWORD = 'correct-horse-battery-staple';
 
 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 (4xx/JSON-RPC errors are expected).
 function watchErrors(page: Page, sink: string[] = []): string[] {
@@ -23,7 +24,7 @@ async function rpc(
 	params: unknown[] | undefined,
 	opts: { omitParams?: boolean } = {},
 ): Promise<{ status: number; body: any }> {
-	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++seq };
+	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' },
@@ -42,6 +43,7 @@ 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', () => {
 	// --- Page smoke: the thin client wires up and reflects server state ---
 
diff --git a/tasks/cognito-profile/PROMPT.md b/tasks/cognito-profile/PROMPT.md
index 1e5a040e5..d003ab13c 100644
--- a/tasks/cognito-profile/PROMPT.md
+++ b/tasks/cognito-profile/PROMPT.md
@@ -24,7 +24,7 @@ This is email-OTP / passwordless: the visitor never types a password.
 
 Expose an **`api` namespace** (the framework's server-side RPC surface — `POST /aws-blocks/api`) with:
 
-1. **`api.getLastCode()`** — test harness hook (the grader has no mailbox): returns the most recently delivered code as `{ username, code }` (or `null`). Retrieved via:
+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 }
diff --git a/tasks/cognito-profile/test.spec.ts b/tasks/cognito-profile/test.spec.ts
index 872054de5..aef510da0 100644
--- a/tasks/cognito-profile/test.spec.ts
+++ b/tasks/cognito-profile/test.spec.ts
@@ -4,8 +4,9 @@ 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()}`;
 
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
@@ -19,7 +20,7 @@ async function rpc(
 ): 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: ++seq },
+		data: { jsonrpc: '2.0', method, params, id: ++rpcSeq },
 	});
 	return { status: res.status(), body: await res.json().catch(() => null) };
 }
@@ -64,9 +65,26 @@ 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', () => {
 	// --- Framework surface: identity from the auth session over the api ---
 
+	test('api.getLastCode is a mock-only backdoor — gated off outside BLOCKS_MOCK', async ({ request }) => {
+		// The OTP-reader hook must never leak codes in a real deployment. In the
+		// bench (BLOCKS_MOCK=true) it is live so the grader can read the code;
+		// with the flag unset it must be gated off and return null.
+		const { status, body } = await rpc(request, 'api.getLastCode', []);
+		expect(status, `unexpected HTTP ${status}`).toBeLessThan(500);
+		if (process.env.BLOCKS_MOCK === 'true') {
+			// Live in mock mode: null (nothing delivered yet) or a { username, code }
+			// record — but never a JSON-RPC error envelope.
+			expect(body?.error, `getLastCode must not error in mock mode: ${JSON.stringify(body?.error)}`).toBeFalsy();
+		} else {
+			// Production / non-mock: the backdoor is closed — no code is exposed.
+			expect(body?.result ?? null, 'getLastCode must be gated off (null) outside BLOCKS_MOCK').toBeNull();
+		}
+	});
+
 	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.
diff --git a/tasks/collab-presence-board/test.spec.ts b/tasks/collab-presence-board/test.spec.ts
index e02ecd95f..6547f2e2a 100644
--- a/tasks/collab-presence-board/test.spec.ts
+++ b/tasks/collab-presence-board/test.spec.ts
@@ -4,8 +4,9 @@ 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()}`;
 
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
@@ -19,7 +20,7 @@ async function rpc(
 ): 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: ++seq },
+		data: { jsonrpc: '2.0', method, params, id: ++rpcSeq },
 	});
 	return { status: res.status(), body: await res.json().catch(() => null) };
 }
@@ -41,6 +42,7 @@ const count = (names: string[], name: string) => names.filter((n) => n === name)
 
 const presence = (page: Page, name: string) => page.getByTestId('presence-item').filter({ hasText: name });
 
+// 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 ---
 
@@ -59,7 +61,7 @@ test.describe('collab-presence-board', () => {
 		expect(count(await roster(request), name), 'name-keyed board must hold at most one row per name').toBe(1);
 	});
 
-	test('names are stored and read back verbatim (markup preserved as literal text)', async ({ request }) => {
+	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);
@@ -156,6 +158,25 @@ test.describe('collab-presence-board', () => {
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
+	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);
+		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([]);
+	});
+
 	// --- 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 }) => {
diff --git a/tasks/file-gallery/test.spec.ts b/tasks/file-gallery/test.spec.ts
index 31bcd6cb9..5e476951a 100644
--- a/tasks/file-gallery/test.spec.ts
+++ b/tasks/file-gallery/test.spec.ts
@@ -4,8 +4,9 @@ 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()}`;
 
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
@@ -18,7 +19,7 @@ async function rpc(
 	params: unknown[] | undefined,
 	opts: { omitParams?: boolean } = {},
 ): Promise<{ status: number; body: any }> {
-	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++seq };
+	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' },
@@ -29,7 +30,7 @@ async function rpc(
 
 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}${u.startsWith('/') ? '' : '/'}${u}`);
+const absUrl = (u: string) => (/^https?:\/\//.test(u) ? u : `${BASE.replace(/\/$/, '')}/${u.replace(/^\//, '')}`);
 
 async function putFile(ctx: APIRequestContext, name: string, buf: Buffer): Promise<any> {
 	const { body } = await rpc(ctx, 'api.putFile', [name, toB64(buf)]);
@@ -45,6 +46,7 @@ async function list(ctx: APIRequestContext): Promise<any[]> {
 
 const entryFor = (files: any[], name: string) => files.find((f) => f?.name === name);
 
+// 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 ---
 
@@ -149,6 +151,18 @@ test.describe('file-gallery', () => {
 		expect(noParams.body?.error, 'no params must yield a JSON-RPC error envelope').toBeTruthy();
 	});
 
+	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();
+
+		// No phantom entry leaked in under the blank name.
+		expect(entryFor(await list(request), ''), 'no file may be stored under an empty name').toBeFalsy();
+	});
+
 	// --- Page smoke: the thin client wires the input/list to the api ---
 
 	test('shows the upload input and the file list container', async ({ page }) => {
diff --git a/tasks/kb-chat-agent/test.spec.ts b/tasks/kb-chat-agent/test.spec.ts
index ab0ed6f42..48d7e5b50 100644
--- a/tasks/kb-chat-agent/test.spec.ts
+++ b/tasks/kb-chat-agent/test.spec.ts
@@ -7,8 +7,9 @@ const T = 10_000;
 const REPLY = 45_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()}`;
 
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
@@ -23,7 +24,7 @@ async function ask(
 ): 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: ++seq },
+		data: { jsonrpc: '2.0', method: 'api.ask', params: [message], id: ++rpcSeq },
 	});
 	const body = await res.json().catch(() => null);
 	const r = body?.result ?? {};
@@ -39,6 +40,7 @@ async function ask(
 const messages = (page: Page) => page.getByTestId('message');
 const bubbleWith = (page: Page, text: string) => messages(page).filter({ hasText: text });
 
+// HARNESS CONTRACT: requires workers:1 (serial; shared-store assertions assume no concurrent runners)
 test.describe('kb-chat-agent', () => {
 	// --- Framework surface: the agent turn runs through api.ask ---
 
diff --git a/tasks/oidc-dsql-notes/test.spec.ts b/tasks/oidc-dsql-notes/test.spec.ts
index ae652077e..d5e89e1d1 100644
--- a/tasks/oidc-dsql-notes/test.spec.ts
+++ b/tasks/oidc-dsql-notes/test.spec.ts
@@ -5,8 +5,9 @@ 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()}`;
 
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
@@ -19,7 +20,7 @@ async function rpc(
 	params: unknown[] | undefined,
 	opts: { omitParams?: boolean } = {},
 ): Promise<{ status: number; body: any }> {
-	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++seq };
+	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' },
@@ -52,6 +53,7 @@ async function listNotes(ctx: APIRequestContext): Promise<any[]> {
 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', () => {
 	// --- Framework surface: notes stored/queried through the api + DSQL ---
 
diff --git a/tasks/sql-kb-catalog/test.spec.ts b/tasks/sql-kb-catalog/test.spec.ts
index 30b3db6ee..27287f800 100644
--- a/tasks/sql-kb-catalog/test.spec.ts
+++ b/tasks/sql-kb-catalog/test.spec.ts
@@ -4,8 +4,9 @@ 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()}`;
 
 function watchErrors(page: Page, sink: string[] = []): string[] {
 	page.on('pageerror', (err) => sink.push(String(err)));
@@ -18,7 +19,7 @@ async function rpc(
 	params: unknown[] | undefined,
 	opts: { omitParams?: boolean } = {},
 ): Promise<{ status: number; body: any }> {
-	const data: Record<string, unknown> = { jsonrpc: '2.0', method, id: ++seq };
+	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' },
@@ -35,6 +36,7 @@ async function listProducts(ctx: APIRequestContext): Promise<any[]> {
 
 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', () => {
 	// --- Framework surface: products in real SQL, FAQ via knowledge base ---
 

From e93ad9b51be2a8b71dc2cee8490f575423a134dc Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Mon, 13 Jul 2026 14:00:57 +0000
Subject: [PATCH 5/8] =?UTF-8?q?test(bench):=20address=20review=20=E2=80=94?=
 =?UTF-8?q?=20honest=20OTP-gate,=20restore=20XSS=20+=20processing-state=20?=
 =?UTF-8?q?smokes,=20add=20changeset?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- #11 dead OTP-gate else: cognito-profile's api.getLastCode test dropped the never-executed `else` (bench always runs BLOCKS_MOCK=true) and documents the production gate is prompt-enforced but grader-unverified; keeps the live mock-mode assertion
- #12 restore auth-notes DOM XSS smoke: saved <b>/<i> markup must render as literal text (note-display .locator('b')/('i') toHaveCount 0), alongside the api round-trip equality
- #13 restore async-word-counter enqueue-time persistence: a job must be readable as status 'processing' the instant it is enqueued (getJob + listJobs), matching PROMPT lines 3/19/22/32, then resolves to done
- #14 fix stale async:129 comment (reuses the request fixture, not a new context)
- add empty-frontmatter changeset so the required 'Require changeset' check passes (internal bench/task content only, no packages/* change)
---
 .changeset/bench-tasks-framework-focus.md | 20 ++++++++++++++
 tasks/async-word-counter/test.spec.ts     | 33 +++++++++++++++++++++--
 tasks/auth-notes/test.spec.ts             | 14 ++++++++--
 tasks/cognito-profile/test.spec.ts        | 22 +++++++--------
 4 files changed, 73 insertions(+), 16 deletions(-)
 create mode 100644 .changeset/bench-tasks-framework-focus.md

diff --git a/.changeset/bench-tasks-framework-focus.md b/.changeset/bench-tasks-framework-focus.md
new file mode 100644
index 000000000..54f984e56
--- /dev/null
+++ b/.changeset/bench-tasks-framework-focus.md
@@ -0,0 +1,20 @@
+---
+---
+
+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/tasks/async-word-counter/test.spec.ts b/tasks/async-word-counter/test.spec.ts
index 3c07d1b2c..2f6af328e 100644
--- a/tasks/async-word-counter/test.spec.ts
+++ b/tasks/async-word-counter/test.spec.ts
@@ -126,8 +126,9 @@ test.describe('async-word-counter', () => {
 		const id = await enqueue(request, text);
 		await countOf(request, id);
 
-		// A fresh caller (new request context has no client memory) must still
-		// see the persisted job via listJobs — proof it lives in the store.
+		// 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);
@@ -136,6 +137,34 @@ test.describe('async-word-counter', () => {
 		expect(mine.text).toBe(text);
 	});
 
+	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 with status
+		// "processing" (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
+		// "processing" job — whereas a persist-on-done impl 404s here (unknown id) or omits it
+		// from listJobs. (DONE=20s / "background job + poll interval" confirms jobs are not
+		// instant, so this window is real and the read is not racy.)
+		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(job?.status, 'a just-enqueued job must be persisted as "processing"').toBe('processing');
+		expect(job?.count ?? null, 'count is null/absent while still processing').toBeNull();
+
+		// 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');
+
+		// And it still resolves to done with the correct count.
+		expect(await countOf(request, id)).toBe(5);
+	});
+
 	// --- 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 }) => {
diff --git a/tasks/auth-notes/test.spec.ts b/tasks/auth-notes/test.spec.ts
index 8bdd58dac..cd0f25024 100644
--- a/tasks/auth-notes/test.spec.ts
+++ b/tasks/auth-notes/test.spec.ts
@@ -138,16 +138,26 @@ test.describe('auth-notes', () => {
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
-	test('notes are stored verbatim — markup round-trips as a literal string', 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'));
 
 		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]);
-		// Exact string equality: no HTML escaping (&amp;) and no stripping.
 		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 });
+		await expect(page.getByTestId('note-display').locator('b')).toHaveCount(0);
+		await expect(page.getByTestId('note-display').locator('i')).toHaveCount(0);
+
 		expect(errors, `page errors: ${errors.join(' | ')}`).toEqual([]);
 	});
 
diff --git a/tasks/cognito-profile/test.spec.ts b/tasks/cognito-profile/test.spec.ts
index aef510da0..19da9e6b3 100644
--- a/tasks/cognito-profile/test.spec.ts
+++ b/tasks/cognito-profile/test.spec.ts
@@ -69,20 +69,18 @@ async function signIn(page: Page, request: APIRequestContext, user: string): Pro
 test.describe('cognito-profile', () => {
 	// --- Framework surface: identity from the auth session over the api ---
 
-	test('api.getLastCode is a mock-only backdoor — gated off outside BLOCKS_MOCK', async ({ request }) => {
-		// The OTP-reader hook must never leak codes in a real deployment. In the
-		// bench (BLOCKS_MOCK=true) it is live so the grader can read the code;
-		// with the flag unset it must be gated off and return null.
+	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);
-		if (process.env.BLOCKS_MOCK === 'true') {
-			// Live in mock mode: null (nothing delivered yet) or a { username, code }
-			// record — but never a JSON-RPC error envelope.
-			expect(body?.error, `getLastCode must not error in mock mode: ${JSON.stringify(body?.error)}`).toBeFalsy();
-		} else {
-			// Production / non-mock: the backdoor is closed — no code is exposed.
-			expect(body?.result ?? null, 'getLastCode must be gated off (null) outside BLOCKS_MOCK').toBeNull();
-		}
+		expect(body?.error, `getLastCode must not error in mock mode: ${JSON.stringify(body?.error)}`).toBeFalsy();
 	});
 
 	test('api.whoami reflects the signed-in identity and is gated to authenticated callers', async ({ page, request }) => {

From 3621978102468583c0693f5f2bed636c67ff0852 Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Tue, 14 Jul 2026 20:23:57 +0000
Subject: [PATCH 6/8] =?UTF-8?q?test(bench):=20audit=20fixes=20=E2=80=94=20?=
 =?UTF-8?q?kb-chat=20determinism,=20seq=20split,=20empty-URL=20fallback,?=
 =?UTF-8?q?=20OTP/AppSetting=20rubric=20notes?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tasks/async-word-counter/test.spec.ts    |  2 +-
 tasks/auth-notes/test.spec.ts            |  2 +-
 tasks/cognito-profile/PROMPT.md          |  1 +
 tasks/cognito-profile/test.spec.ts       |  4 ++--
 tasks/collab-presence-board/test.spec.ts |  2 +-
 tasks/email-digest/test.spec.ts          | 16 ++++++----------
 tasks/file-gallery/test.spec.ts          |  2 +-
 tasks/kb-chat-agent/test.spec.ts         |  6 +++---
 tasks/observability-api/PROMPT.md        |  1 +
 tasks/observability-api/test.spec.ts     |  6 +++---
 tasks/oidc-dsql-notes/test.spec.ts       |  2 +-
 tasks/sql-kb-catalog/test.spec.ts        |  2 +-
 12 files changed, 22 insertions(+), 24 deletions(-)

diff --git a/tasks/async-word-counter/test.spec.ts b/tasks/async-word-counter/test.spec.ts
index 2f6af328e..13e0d2f2a 100644
--- a/tasks/async-word-counter/test.spec.ts
+++ b/tasks/async-word-counter/test.spec.ts
@@ -1,6 +1,6 @@
 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 + poll interval
 
diff --git a/tasks/auth-notes/test.spec.ts b/tasks/auth-notes/test.spec.ts
index cd0f25024..cf728072a 100644
--- a/tasks/auth-notes/test.spec.ts
+++ b/tasks/auth-notes/test.spec.ts
@@ -1,6 +1,6 @@
 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';
 
diff --git a/tasks/cognito-profile/PROMPT.md b/tasks/cognito-profile/PROMPT.md
index d003ab13c..0f8cac198 100644
--- a/tasks/cognito-profile/PROMPT.md
+++ b/tasks/cognito-profile/PROMPT.md
@@ -60,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 19da9e6b3..f08a4af5e 100644
--- a/tasks/cognito-profile/test.spec.ts
+++ b/tasks/cognito-profile/test.spec.ts
@@ -1,6 +1,6 @@
 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());
@@ -40,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;
diff --git a/tasks/collab-presence-board/test.spec.ts b/tasks/collab-presence-board/test.spec.ts
index 6547f2e2a..1f5c52703 100644
--- a/tasks/collab-presence-board/test.spec.ts
+++ b/tasks/collab-presence-board/test.spec.ts
@@ -1,6 +1,6 @@
 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());
diff --git a/tasks/email-digest/test.spec.ts b/tasks/email-digest/test.spec.ts
index 1d102481e..f2da0f6c1 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/test.spec.ts b/tasks/file-gallery/test.spec.ts
index 5e476951a..79e3a7d67 100644
--- a/tasks/file-gallery/test.spec.ts
+++ b/tasks/file-gallery/test.spec.ts
@@ -1,6 +1,6 @@
 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());
diff --git a/tasks/kb-chat-agent/test.spec.ts b/tasks/kb-chat-agent/test.spec.ts
index 48d7e5b50..6d15626c6 100644
--- a/tasks/kb-chat-agent/test.spec.ts
+++ b/tasks/kb-chat-agent/test.spec.ts
@@ -1,6 +1,6 @@
 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;
 // Agent round-trip (KB retrieval + model turn). Generous ceiling for first-load
 // + KB ingestion, under Playwright's 60s per-test cap.
@@ -79,7 +79,7 @@ test.describe('kb-chat-agent', () => {
 	});
 
 	test('small talk retrieves nothing and does not fabricate the seeded facts', async ({ request }) => {
-		const a = await ask(request, uniq('please just say a short friendly hello and nothing else'));
+		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');
@@ -158,7 +158,7 @@ test.describe('kb-chat-agent', () => {
 		// 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(orderReply()).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 e724643cc..f5aea0637 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 c07990beb..e5a573f8f 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/test.spec.ts b/tasks/oidc-dsql-notes/test.spec.ts
index d5e89e1d1..48d1920e3 100644
--- a/tasks/oidc-dsql-notes/test.spec.ts
+++ b/tasks/oidc-dsql-notes/test.spec.ts
@@ -1,6 +1,6 @@
 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;
 
diff --git a/tasks/sql-kb-catalog/test.spec.ts b/tasks/sql-kb-catalog/test.spec.ts
index 27287f800..548483f9b 100644
--- a/tasks/sql-kb-catalog/test.spec.ts
+++ b/tasks/sql-kb-catalog/test.spec.ts
@@ -1,6 +1,6 @@
 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());

From 4dfd91b1fc67c49f1a5aff63ccaaf4b501da5056 Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Mon, 20 Jul 2026 20:51:13 +0000
Subject: [PATCH 7/8] test(bench): tolerate a fast 'done' in async-word-counter
 immediate read

The post-enqueue read asserted status === 'processing' with a null count,
which flakes against a legitimately-fast reference impl whose background
job finishes before the read. DONE (20s) is a poll CEILING, not a floor,
so accept 'processing' | 'done' for the immediate read (require null count
only while 'processing'). The listJobs still-processing surfacing and the
final countOf() === 5 assertion are unchanged.
---
 tasks/async-word-counter/test.spec.ts | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/tasks/async-word-counter/test.spec.ts b/tasks/async-word-counter/test.spec.ts
index 13e0d2f2a..a6a64476a 100644
--- a/tasks/async-word-counter/test.spec.ts
+++ b/tasks/async-word-counter/test.spec.ts
@@ -138,12 +138,13 @@ test.describe('async-word-counter', () => {
 	});
 
 	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 with status
-		// "processing" (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
-		// "processing" job — whereas a persist-on-done impl 404s here (unknown id) or omits it
-		// from listJobs. (DONE=20s / "background job + poll interval" confirms jobs are not
-		// instant, so this window is real and the read is not racy.)
+		// 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);
 
@@ -152,8 +153,13 @@ test.describe('async-word-counter', () => {
 		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(job?.status, 'a just-enqueued job must be persisted as "processing"').toBe('processing');
-		expect(job?.count ?? null, 'count is null/absent while still processing').toBeNull();
+		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();
+		}
 
 		// listJobs must ALSO surface the still-processing job (restored from the store, PROMPT line 22).
 		const listed = (await rpc(request, 'api.listJobs', [])).body?.result ?? [];

From 4e324420b5f4ed848e1fa073d13ef01bc4d548b5 Mon Sep 17 00:00:00 2001
From: "H. Furkan Bozkurt" <bozkurh@amazon.com>
Date: Fri, 24 Jul 2026 20:51:45 +0000
Subject: [PATCH 8/8] chore: add changeset for @aws-blocks/agent-bench
 (bench-only, no release)

---
 .changeset/bench-tasks-framework-focus.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.changeset/bench-tasks-framework-focus.md b/.changeset/bench-tasks-framework-focus.md
index 54f984e56..654edf76f 100644
--- a/.changeset/bench-tasks-framework-focus.md
+++ b/.changeset/bench-tasks-framework-focus.md
@@ -1,4 +1,5 @@
 ---
+"@aws-blocks/agent-bench": patch
 ---
 
 test(bench): reshape agent-bench task graders to be framework-surface-first