reviewzy 0.1.0 → 0.3.0

package/src/dashboard/word-diff.ts

@@ -0,0 +1,89 @@
+/**
+ * The word-level diff between the anchor text and the proposed text, computed server-side at
+ * render time so the marks need no client js. Whitespace-token based: the split keeps whitespace
+ * runs as their own tokens, so both streams re-join to their exact input, bytes included.
+ */
+
+/** One token of a diffed string, carrying its mark. Whitespace runs are tokens too, always `same` when both sides share them. */
+export type WordDiffToken = {
+  readonly text: string;
+  readonly kind: "same" | "removed" | "added";
+};
+
+export type WordDiff = {
+  /** The anchor text tokenized: tokens the proposal does not keep are `removed`, the rest `same`. */
+  readonly before: readonly WordDiffToken[];
+  /** The proposal tokenized: tokens the anchor did not have are `added`, the rest `same`. */
+  readonly after: readonly WordDiffToken[];
+};
+
+/** Splits on whitespace boundaries, keeping the runs: `"a b"` becomes `["a", " ", "b"]`. */
+function tokenize(text: string): string[] {
+  return text.split(/(\s+)/).filter((token) => token !== "");
+}
+
+/**
+ * The LCS table is quadratic in token count, and the anchor is agent-controlled with no length
+ * cap, so past this cell ceiling the walk is skipped: each side reads fully changed, which is
+ * honest (no word is claimed unchanged) and renders in linear time.
+ */
+const MAX_LCS_CELLS = 1_000_000;
+
+/**
+ * A longest-common-subsequence walk over the two token streams: a token both sides share is
+ * `same`, one only the anchor has is `removed`, one only the proposal has is `added`. Identical
+ * strings produce all-`same` streams, so nothing renders a mark.
+ */
+export function diffWords(before: string, after: string): WordDiff {
+  const a = tokenize(before);
+  const b = tokenize(after);
+
+  if (a.length * b.length > MAX_LCS_CELLS) {
+    return {
+      before: a.map((text) => ({ text, kind: "removed" as const })),
+      after: b.map((text) => ({ text, kind: "added" as const })),
+    };
+  }
+
+  // dp[i][j] is the LCS length of a[i:] against b[j:], filled bottom-up so the walk can pick the
+  // branch that keeps the longest match. One flat typed array: 8 bytes a cell, no nested rows.
+  const stride = b.length + 1;
+  const dp = new Float64Array((a.length + 1) * stride);
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      const below = dp[(i + 1) * stride + j]!;
+      const right = dp[i * stride + j + 1]!;
+      dp[i * stride + j] = a[i] === b[j] ? below + 1 : Math.max(below, right);
+    }
+  }
+
+  const beforeTokens: WordDiffToken[] = [];
+  const afterTokens: WordDiffToken[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      beforeTokens.push({ text: a[i]!, kind: "same" });
+      afterTokens.push({ text: b[j]!, kind: "same" });
+      i++;
+      j++;
+    } else if (dp[(i + 1) * stride + j]! >= dp[i * stride + j + 1]!) {
+      // Skipping the anchor's token keeps at least as long a match: it is removed.
+      beforeTokens.push({ text: a[i]!, kind: "removed" });
+      i++;
+    } else {
+      afterTokens.push({ text: b[j]!, kind: "added" });
+      j++;
+    }
+  }
+  while (i < a.length) {
+    beforeTokens.push({ text: a[i]!, kind: "removed" });
+    i++;
+  }
+  while (j < b.length) {
+    afterTokens.push({ text: b[j]!, kind: "added" });
+    j++;
+  }
+
+  return { before: beforeTokens, after: afterTokens };
+}

package/src/db/human-save.ts

@@ -240,3 +240,115 @@ export function listRevisions(store: Store, entryId: string): RevisionRow[] {
     )
     .all(entryId) as RevisionRow[];
 }
+
+/**
+ * The tolerant parse for `entries.images`, mirroring `parseConstraints`: the column holds foreign
+ * data (it is also fed by the wire), and an unparseable or shape-broken value must read as no
+ * images, never as a 500. Non-string items are dropped rather than propagated.
+ */
+export function parseEntryImages(json: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((item): item is string => typeof item === "string");
+}
+
+/** The per-entry image cap `docs/mcp-contract.md` pins for `images`; the wire's boundary carries the same number in its own layer. */
+const MAX_ENTRY_IMAGES = 8;
+
+/** Everything the image writes refuse; the dashboard's upload and remove routes format the messages. */
+export type ImageWriteRefusal =
+  | { readonly kind: "unknown" }
+  | { readonly kind: "too_many" }
+  | { readonly kind: "no_image"; readonly index: number };
+
+/**
+ * Appends one image the human uploaded to the entry's image list. A note-like write, not a save:
+ * it works on every status, writes no revision row, changes no status, and fires no status event
+ * (a waiter cares about approval, not about a new screenshot). `updated_at` moves so the row
+ * reflects the write. The data url already passed the route's mime and size checks, and the
+ * stored list must stay inside the contract's image cap.
+ *
+ * The read and the write share one immediate transaction: a deferred one would let two racing
+ * uploads (a double submit) both read the old list and drop one image on the later write, while
+ * the immediate lock serializes them at the read.
+ */
+export function appendEntryImage(
+  store: Store,
+  id: string,
+  dataUrl: string,
+): { readonly ok: true } | { readonly ok: false; readonly refusal: ImageWriteRefusal } {
+  const write = store.db.transaction(() => {
+    const row = store.db.query("SELECT images FROM entries WHERE id = ?").get(id) as { images: string } | null;
+    if (row === null) return { ok: false as const, refusal: { kind: "unknown" as const } };
+
+    const images = parseEntryImages(row.images);
+    if (images.length >= MAX_ENTRY_IMAGES) {
+      return { ok: false as const, refusal: { kind: "too_many" as const } };
+    }
+    images.push(dataUrl);
+    store.db.run("UPDATE entries SET images = ?, updated_at = ? WHERE id = ?", [
+      JSON.stringify(images),
+      Date.now(),
+      id,
+    ]);
+    return { ok: true as const };
+  });
+  return write.immediate();
+}
+
+/**
+ * Removes one image by its index in the stored array. Same write class as `appendEntryImage`: no
+ * revision, no status change, no event; `updated_at` moves, and the read + write share one
+ * immediate transaction for the same double-submit race the append guards. An index past either
+ * end is a refusal carrying the index the route's message names.
+ */
+export function removeEntryImage(
+  store: Store,
+  id: string,
+  index: number,
+): { readonly ok: true } | { readonly ok: false; readonly refusal: ImageWriteRefusal } {
+  const write = store.db.transaction(() => {
+    const row = store.db.query("SELECT images FROM entries WHERE id = ?").get(id) as { images: string } | null;
+    if (row === null) return { ok: false as const, refusal: { kind: "unknown" as const } };
+
+    const images = parseEntryImages(row.images);
+    if (index < 0 || index >= images.length) {
+      return { ok: false as const, refusal: { kind: "no_image" as const, index } };
+    }
+    images.splice(index, 1);
+    store.db.run("UPDATE entries SET images = ?, updated_at = ? WHERE id = ?", [
+      JSON.stringify(images),
+      Date.now(),
+      id,
+    ]);
+    return { ok: true as const };
+  });
+  return write.immediate();
+}
+
+/**
+ * Saves the human's own notes. Deliberately unlike `saveHumanText`: the notes are a scratchpad, so
+ * the write works on every status (an applied or rejected entry's notes stay editable), an empty
+ * string clears them rather than refusing, and nothing else moves — no revision row (only prose
+ * saves make history), no status change, no status event (a waiter cares about approval, not about
+ * a note). `updated_at` moves so the row reflects the write. The only refusal is an unknown id.
+ */
+export function saveHumanNotes(
+  store: Store,
+  input: { readonly id: string; readonly notes: string },
+): { readonly ok: true } | { readonly ok: false; readonly refusal: { readonly kind: "unknown" } } {
+  const row = store.db.query("SELECT id FROM entries WHERE id = ?").get(input.id) as { id: string } | null;
+  if (row === null) return { ok: false, refusal: { kind: "unknown" } };
+
+  store.db.run("UPDATE entries SET human_notes = ?, updated_at = ? WHERE id = ?", [
+    input.notes,
+    Date.now(),
+    input.id,
+  ]);
+  return { ok: true };
+}

package/src/db/migrations.ts

@@ -146,4 +146,42 @@ export const MIGRATIONS: Migration[] = [
       ALTER TABLE entries_archive ADD COLUMN applied_hash TEXT;
     `,
   },
+  {
+    version: 4,
+    name: "entry-title",
+    sql: `
+      -- An optional human-readable label the dashboard shows in place of the file basename, so a
+      -- row reads as what it changes rather than where it lives (cloudy, 2026-08-20). Nullable:
+      -- an entry without one falls back to its anchor text at render. The archive mirrors entries
+      -- column-for-column, so it gains the column too.
+      ALTER TABLE entries ADD COLUMN title TEXT;
+      ALTER TABLE entries_archive ADD COLUMN title TEXT;
+    `,
+  },
+  {
+    version: 5,
+    name: "entry-images",
+    sql: `
+      -- Screenshots and links attached to an entry, filed by agents and appended to by the human
+      -- on the dashboard. A json array of strings, each a data:image/ data url or an http(s) url;
+      -- the wire boundary enforces the shape (max 8, max 5 MiB each). NOT NULL with an empty
+      -- array default: an entry without images stores [] like the other json columns. The archive
+      -- mirrors entries column-for-column, so it gains the column too.
+      ALTER TABLE entries ADD COLUMN images TEXT NOT NULL DEFAULT '[]';
+      ALTER TABLE entries_archive ADD COLUMN images TEXT NOT NULL DEFAULT '[]';
+    `,
+  },
+  {
+    version: 6,
+    name: "entry-human-notes",
+    sql: `
+      -- The human's own scratchpad, dashboard-only: agents can neither set nor read it, so the
+      -- filing insert leaves it NULL and the list_entries tool projects it out of the wire row.
+      -- Nullable, unlike the agent-fed json columns: no agent ever sends a value, and NULL is
+      -- what renders as "no notes yet". The archive mirrors entries column-for-column, so it
+      -- gains the column too.
+      ALTER TABLE entries ADD COLUMN human_notes TEXT;
+      ALTER TABLE entries_archive ADD COLUMN human_notes TEXT;
+    `,
+  },
 ];

package/src/db/queries.ts

@@ -8,14 +8,15 @@ export type EntryStatus = "draft" | "approved" | "applied" | "rejected";
 /**
  * One entry as it crosses into the store: every field already typed, hashed, and stringified.
  * The json boundary belongs to the tool that reads the wire (`src/mcp/file-entries.ts`); nothing
- * here re-parses what it already accepted. `agentDraft`, `contextJson`, and `constraintsJson` are
- * null when the caller did not send the field: a first filing stores the empty default, and a
- * draft re-file keeps the stored value (the schema refuses explicit null, so no caller can
- * express a wipe).
+ * here re-parses what it already accepted. `agentDraft`, `contextJson`, `constraintsJson`, and
+ * `imagesJson` are null when the caller did not send the field: a first filing stores the empty
+ * default, and a draft re-file keeps the stored value (the schema refuses explicit null, so no
+ * caller can express a wipe).
  */
 export type NewEntry = {
   readonly repo: string;
   readonly file: string;
+  readonly title: string | null;
   readonly anchorText: string;
   readonly anchorBefore: string;
   readonly anchorAfter: string;
@@ -24,6 +25,7 @@ export type NewEntry = {
   readonly agentDraft: string | null;
   readonly contextJson: string | null;
   readonly constraintsJson: string | null;
+  readonly imagesJson: string | null;
 };
 
 export type FiledEntry = {
@@ -41,13 +43,14 @@ export type FiledBatch = {
 type ProjectRow = { id: string };
 type IdentityRow = { id: string; status: EntryStatus };
 
-/** One entry row as `list_entries` returns it: the columns `docs/mcp-contract.md`'s entry schema lists, `archived_at` included (every v1 row carries null — the archive sweep is not built yet). */
+/** One entry row as the store's shared list query returns it: the columns `docs/mcp-contract.md`'s entry schema lists, `archived_at` included (every v1 row carries null — the archive sweep is not built yet). The dashboard consumes the full row; the mcp `list_entries` tool projects it down to the contract's lean index row. */
 export type EntryRow = {
   readonly id: string;
   readonly project_id: string;
   readonly batch_id: string;
   readonly repo: string;
   readonly file: string;
+  readonly title: string | null;
   readonly anchor_text: string;
   readonly anchor_before: string;
   readonly anchor_after: string;
@@ -61,6 +64,8 @@ export type EntryRow = {
   readonly filed_by: string | null;
   readonly stale_note: string | null;
   readonly applied_hash: string | null;
+  readonly images: string;
+  readonly human_notes: string | null;
   readonly created_at: number;
   readonly updated_at: number;
   readonly applied_at: number | null;
@@ -189,16 +194,17 @@ function fileOneEntry(
     const now = Date.now();
     db.run(
       `INSERT INTO entries (
-        id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
+        id, project_id, batch_id, repo, file, title, anchor_text, anchor_before, anchor_after,
         anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
-        filed_by, stale_note, created_at, updated_at, applied_at, archived_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 'draft', ?, ?, ?, NULL, ?, ?, NULL, NULL)`,
+        filed_by, stale_note, images, created_at, updated_at, applied_at, archived_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 'draft', ?, ?, ?, NULL, ?, ?, ?, NULL, NULL)`,
       [
         id,
         projectId,
         batchId,
         entry.repo,
         entry.file,
+        entry.title,
         entry.anchorText,
         entry.anchorBefore,
         entry.anchorAfter,
@@ -208,6 +214,7 @@ function fileOneEntry(
         entry.contextJson ?? "{}",
         entry.constraintsJson ?? "{}",
         filedBy,
+        entry.imagesJson ?? "[]",
         now,
         now,
       ],
@@ -219,8 +226,8 @@ function fileOneEntry(
     // `COALESCE(?, column)`: a field the newer call did not carry (null) keeps the stored value.
     // The schema refuses explicit null, so a re-file can only move the fields it names.
     db.run(
-      "UPDATE entries SET agent_draft = COALESCE(?, agent_draft), context = COALESCE(?, context), constraints = COALESCE(?, constraints), updated_at = ? WHERE id = ?",
-      [entry.agentDraft, entry.contextJson, entry.constraintsJson, Date.now(), existing.id],
+      "UPDATE entries SET agent_draft = COALESCE(?, agent_draft), context = COALESCE(?, context), constraints = COALESCE(?, constraints), title = COALESCE(?, title), images = COALESCE(?, images), updated_at = ? WHERE id = ?",
+      [entry.agentDraft, entry.contextJson, entry.constraintsJson, entry.title, entry.imagesJson, Date.now(), existing.id],
     );
     return { id: existing.id, status: "draft", deduped: true, updated: true };
   }
@@ -254,9 +261,10 @@ const APPROVED_PAGE_SIZE = 50;
 
 /** The columns `docs/mcp-contract.md`'s entry schema names; the one place the output row's shape is spelled out in SQL. */
 const ENTRY_COLUMNS = [
-  "id", "project_id", "batch_id", "repo", "file", "anchor_text", "anchor_before",
-  "anchor_after", "anchor_hash", "file_hash", "agent_draft", "human_text", "status",
-  "context", "constraints", "filed_by", "stale_note", "applied_hash", "created_at", "updated_at", "applied_at", "archived_at",
+  "id", "project_id", "batch_id", "repo", "file", "title", "anchor_text", "anchor_before",
+  "anchor_after", "anchor_hash", "file_hash", "agent_draft", "human_notes", "human_text", "status",
+  "context", "constraints", "filed_by", "stale_note", "applied_hash", "images", "created_at",
+  "updated_at", "applied_at", "archived_at",
 ] as const;
 
 /**
@@ -304,6 +312,21 @@ export function listEntries(store: Store, filter: ListEntriesFilter): ListEntrie
   return { rows, nextCursor };
 }
 
+/**
+ * The entries immediately before and after `id` in the ascending-id walk the list renders, for the
+ * editor's full-height prev/next rails; null at either boundary. The `id` column is a primary key,
+ * so both comparisons run on its unique index.
+ */
+export function adjacentEntryIds(store: Store, id: string): { prevId: string | null; nextId: string | null } {
+  const prev = store.db.query("SELECT id FROM entries WHERE id < ? ORDER BY id DESC LIMIT 1").get(id) as
+    | { id: string }
+    | null;
+  const next = store.db.query("SELECT id FROM entries WHERE id > ? ORDER BY id ASC LIMIT 1").get(id) as
+    | { id: string }
+    | null;
+  return { prevId: prev?.id ?? null, nextId: next?.id ?? null };
+}
+
 /**
  * The `fetch_approved` read. The status is not a filter: the tool's invariant is `'approved'`
  * (a draft, applied, or rejected row never leaves this query), and the page size is the contract's

package/src/db/sweep.ts

@@ -55,12 +55,12 @@ export function sweepArchive(store: Store, now: number, archiveAfterDays: number
       `INSERT INTO entries_archive (
         id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
         anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
-        filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, archived_at
+        filed_by, stale_note, applied_hash, images, human_notes, created_at, updated_at, applied_at, archived_at
       )
       SELECT
         id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
         anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
-        filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, ?
+        filed_by, stale_note, applied_hash, images, human_notes, created_at, updated_at, applied_at, ?
       FROM entries
       WHERE ${EXPIRED_APPLIED}`,
       [now, cutoff],

package/src/mcp/await-approved.ts

@@ -25,8 +25,8 @@ export function clampTimeoutMs(ms: number): number {
 }
 
 const AwaitApprovedArgs = z.object({
-  ids: z.array(z.string().min(1)).min(1),
-  timeout_ms: z.number().int().min(1).default(AWAIT_TIMEOUT_DEFAULT_MS),
+  ids: z.array(z.string().min(1)).min(1).describe("The exact entry ids to wait for; duplicates are dropped."),
+  timeout_ms: z.number().int().min(1).default(AWAIT_TIMEOUT_DEFAULT_MS).describe("How long to block (max: 600000, default 60000). A larger value is clamped."),
 });
 
 const AwaitApprovedOutput = z.object({
@@ -34,12 +34,14 @@ const AwaitApprovedOutput = z.object({
   statuses: z.record(z.string(), z.enum(["draft", "approved", "applied", "rejected"])),
   entries: z.array(ApprovedEntry).optional(),
   poll_again_after_ms: z.number().int().min(1).optional(),
+  missing_ids: z.array(z.string()).optional(),
 });
 
 type AwaitOutcome = {
   readonly resolved: boolean;
   readonly statuses: Record<string, EntryStatus>;
   readonly entries: z.infer<typeof ApprovedEntry>[];
+  readonly missingIds: string[];
 };
 
 /** A refusal is an ordinary thrown Error: the SDK answers it as a tool result with `isError: true`, never as a json-rpc protocol error. */
@@ -77,16 +79,16 @@ function waitForEntries(store: Store, ids: readonly string[], timeoutMs: number)
         statuses[row.id] = row.status;
         if (row.status === "approved") approved.push(row);
       }
-      // The status map's contract is one key per named id, so a row that vanished since the
-      // up-front check (the planned retention sweep moves rows to the archive) must not resolve
-      // the wait with the id silently missing: keep waiting, and the caller's next call surfaces
-      // the missing id in the up-front refusal.
+      // A row that vanished since the up-front check (the retention sweep moves rows to the
+      // archive) must not resolve the wait, and its id must not sit silently absent from the
+      // statuses map on a non-resolved reply: the gap is named in missing_ids instead.
+      const missingIds = ids.filter((id) => statuses[id] === undefined);
       const done =
         rows.length === ids.length &&
         rows.every((row) => row.status === "approved" || row.status === "rejected");
       return done
-        ? { resolved: true, statuses, entries: approvedRowsToWire(approved) }
-        : { resolved: false, statuses, entries: [] };
+        ? { resolved: true, statuses, entries: approvedRowsToWire(approved), missingIds: [] }
+        : { resolved: false, statuses, entries: [], missingIds };
     }
 
     function recheck(): void {
@@ -125,7 +127,7 @@ export function registerAwaitApprovedTool(server: McpServer, store: Store): void
     {
       title: "Wait for entries to be approved or rejected",
       description:
-        "Block until every named entry reaches approved or rejected, holding the call open — the one long-poll on this server, for a live session that filed entries and wants to sleep until the human signs off instead of polling fetch_approved. ids: the exact entry ids to wait for; duplicates are deduped silently, and the status map carries one key per id. timeout_ms: how long to block, default 60000, capped at 600000 — a larger value is clamped, never refused. Resolves when every named id is approved or rejected: resolved true, statuses one per named id, and entries the approved rows only, each in fetch_approved's row shape (id, repo, file, anchor_text, anchor_before, anchor_after, anchor_hash, file_hash, text, constraints parsed) — a rejected id appears in statuses only, never in entries. On timeout: resolved false, the current per-id statuses, and poll_again_after_ms 5000 — never an error; call again with the same ids to keep waiting. Refused, naming the id and the fix: an id that does not exist at call time (a read tool never creates one). An entry in applied does not resolve the wait: only approved or rejected does.",
+        "Blocks until every named entry reaches approved or rejected; the client may park the call and deliver the result when it lands. This is the long-poll for a live session that filed entries and wants to sleep until the human signs off, rather than poll `fetch_approved`. Only approved or rejected resolves the wait; applied does not.",
       inputSchema: AwaitApprovedArgs,
       outputSchema: AwaitApprovedOutput,
     },
@@ -146,7 +148,12 @@ export function registerAwaitApprovedTool(server: McpServer, store: Store): void
       const outcome = await waitForEntries(store, ids, timeoutMs);
       const output = outcome.resolved
         ? { resolved: true, statuses: outcome.statuses, entries: outcome.entries }
-        : { resolved: false, statuses: outcome.statuses, poll_again_after_ms: AWAIT_POLL_AGAIN_MS };
+        : {
+            resolved: false,
+            statuses: outcome.statuses,
+            poll_again_after_ms: AWAIT_POLL_AGAIN_MS,
+            missing_ids: outcome.missingIds.length > 0 ? outcome.missingIds : undefined,
+          };
       return {
         content: [{ type: "text" as const, text: JSON.stringify(output) }],
         structuredContent: output,

package/src/mcp/fetch-approved.ts

@@ -9,9 +9,9 @@ import type { Store } from "../db/store.ts";
  * style guide is per-project, and the applying agent needs the voice of the project it writes into.
  */
 const FetchApprovedArgs = z.object({
-  project: z.string().min(1),
-  ids: z.array(z.string().min(1)).min(1).optional(),
-  since: z.string().min(1).optional(),
+  project: z.string().min(1).describe("The project slug to fetch from."),
+  ids: z.array(z.string().min(1)).min(1).optional().describe("Only these exact entry ids. Combines with since: both filters apply."),
+  since: z.string().min(1).optional().describe("Resume a walk: pass the previous page's next_since to get the rows after it."),
 });
 
 /**
@@ -42,7 +42,7 @@ export const ApprovedEntry = z.object({
 
 const FetchApprovedOutput = z.object({
   entries: z.array(ApprovedEntry),
-  style_guide: z.string(),
+  style_guide: z.string().optional(),
   next_since: z.string().optional(),
 });
 
@@ -100,7 +100,7 @@ export function registerFetchApprovedTool(server: McpServer, store: Store): void
     {
       title: "Fetch approved entries to apply",
       description:
-        "Fetch the approved entries of a project, ready to apply: the human-signed prose (text), the anchor to locate and replace it by, and the constraints the replacement must keep. Only approved entries are ever returned — a draft, applied, or rejected entry never appears, and an id naming one simply contributes nothing. Entries come back ordered by ascending entry id, at most 50 per call (fixed server-side page); when exactly 50 come back, next_since holds the last entry's id, and the walk continues by passing that id back as since (rows with id > since) — when next_since is absent the walk is exhausted, stop fetching. ids (exact entry ids) combines with since by AND. The project slug is required and must already exist: an unknown slug is refused (read tools never create one). Each entry carries id, repo, file, anchor_text, anchor_before, anchor_after, anchor_hash, file_hash, text (the approved prose; null only on an approved row nobody ever wrote into), and constraints — parsed into {max_len?, placeholders?, tone?, notes?} so the apply-back can check the text against them, an unparseable stored value rendering as {}. style_guide is the same merged text the reviewzy://projects/{slug}/style-guide resource serves, embedded so bulk rewrites share one voice.",
+        "Fetch a project's approved entries, ready to apply: the human-signed text, the anchor to locate and replace it by, and the constraints the replacement must keep. Only approved entries are returned: an id naming a draft, applied or rejected entry contributes nothing. At most 50 per page, ordered by ascending id; when next_since comes back, pass it back as since to continue. The merged style guide rides the first page of a walk (neither ids nor since) so bulk rewrites pay it once.",
       inputSchema: FetchApprovedArgs,
       outputSchema: FetchApprovedOutput,
     },
@@ -118,7 +118,12 @@ export function registerFetchApprovedTool(server: McpServer, store: Store): void
 
       const output = {
         entries: approvedRowsToWire(rows),
-        style_guide: mergedStyleGuide(store, args.project),
+        // The guide rides a walk's first page only — a call carrying neither ids nor since.
+        // Continuation pages and targeted id fetches omit it: the same text is the style-guide
+        // resource, so a bulk rewrite pays it once per walk.
+        ...(args.ids === undefined && args.since === undefined
+          ? { style_guide: mergedStyleGuide(store, args.project) }
+          : {}),
         // An exhausted walk carries no `next_since` key at all: absent is the signal to stop, so an
         // empty page must never smuggle one in.
         ...(nextSince === null ? {} : { next_since: nextSince }),