reviewzy 0.2.0 → 0.3.0

package/src/db/queries.ts

@@ -43,7 +43,7 @@ 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;

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 }),

package/src/mcp/file-entries.ts

@@ -34,25 +34,31 @@ const ConstraintsJson = z.strictObject({
 });
 
 /**
- * Held loose on purpose. The SDK's own schema check would refuse a malformed constraints with an
- * isError tool result naming the tool and the field path ("entries.0.constraints"). The handler's
- * refusal adds what that cannot: the entry (file and anchor) and the fix. So `context` and
- * `constraints` stay untyped here and are validated below.
+ * The wire schema is loose on purpose: a plain z.object lets the sdk strip an unrecognized
+ * top-level key before the handler sees it, so a misspelled anchor_text would file an entry with
+ * no anchor and a misspelled agent_draft one with no draft. The handler re-parses each entry
+ * against StrictEntryArgs and refuses the key by name, with the entry and the fix. `context` and
+ * `constraints` stay untyped for the same reason: the sdk's refusal can name only the tool and the
+ * field path ("entries.0.constraints"), never the entry (file and anchor) and the fix.
  */
-const FileEntryArgs = z.object({
-  repo: z.string().min(1),
-  file: z.string().min(1),
-  title: z.string().min(1).optional(),
-  anchor_text: z.string().min(1),
-  anchor_before: z.string().optional(),
-  anchor_after: z.string().optional(),
-  agent_draft: z.string().optional(),
-  file_content: z.string().optional(),
-  file_hash: z.string().optional(),
-  context: z.unknown().optional(),
-  constraints: z.unknown().optional(),
-  images: z.unknown().optional(),
-});
+const EntryShape = {
+  repo: z.string().min(1).describe("Which repo the entry is about: the git remote url preferred, the absolute path when the repo has no remote."),
+  file: z.string().min(1).describe("The path relative to the repo root."),
+  title: z.string().min(1).optional().describe("Optional human-readable label the dashboard shows in place of the file path."),
+  anchor_text: z.string().min(1).describe("The exact current text to replace: one line or many, the whole passage being replaced."),
+  anchor_before: z.string().optional().describe("3 lines of context above the anchor, disambiguating a repeated string."),
+  anchor_after: z.string().optional().describe("3 lines of context below the anchor, disambiguating a repeated string."),
+  agent_draft: z.string().optional().describe("The proposed replacement text; inert until a human touches it."),
+  file_content: z.string().optional().describe("The whole file at filing time; the server hashes it."),
+  file_hash: z.string().optional().describe("The sha256 of the whole file as 64 lowercase hex chars."),
+  context: z.unknown().optional().describe("A json object of free-form notes for the human: where the string renders, surrounding code."),
+  constraints: z.unknown().optional().describe("What the copy must keep: max_len (a length cap), placeholders (strings the text must contain), tone, notes — all optional."),
+  images: z.unknown().optional().describe("Screenshots and links for the human, shown on the dashboard, never returned by an mcp tool."),
+};
+const FileEntryArgs = z.looseObject(EntryShape);
+
+/** Strict twin of the wire shape: the handler re-parses against it to refuse an unrecognized top-level key by name. */
+const StrictEntryArgs = z.strictObject(EntryShape);
 
 const FiledOutput = z.object({
   batch_id: z.string(),
@@ -104,6 +110,17 @@ function refuseConstraints(index: number, file: string, anchorText: string, issu
   return refuse(where, problem, fix);
 }
 
+/** Turns zod's unrecognized_keys issues into the named-key refusal: the key, the entry, the fix. */
+function refuseEntryKeys(index: number, file: string, anchorText: string, issues: readonly z.ZodIssue[]): never {
+  const where = entryName(index, file, anchorText);
+  const keys = issues.flatMap((issue) => (issue.code === "unrecognized_keys" ? issue.keys : []));
+  return refuse(
+    where,
+    `unrecognized key(s) ${keys.map((k) => JSON.stringify(k).slice(0, 60)).join(", ")}`,
+    "entries take only repo, file, title, anchor_text, anchor_before, anchor_after, agent_draft, file_content, file_hash, context, constraints, and images; drop the extra key or spell it snake_case",
+  );
+}
+
 /**
  * One entry from wire shape to store shape: json validated at this boundary, `anchor_hash` always
  * computed here, and file provenance taken from exactly one of `file_content` (the server hashes
@@ -113,6 +130,12 @@ function refuseConstraints(index: number, file: string, anchorText: string, issu
 function validateEntry(index: number, raw: z.output<typeof FileEntryArgs>): NewEntry {
   const where = entryName(index, raw.file, raw.anchor_text);
 
+  // Unknown keys first: a wire-shape mistake outranks every field-level check below.
+  const strict = StrictEntryArgs.safeParse(raw);
+  if (!strict.success) {
+    refuseEntryKeys(index, raw.file, raw.anchor_text, strict.error.issues);
+  }
+
   const context = ContextJson.safeParse(raw.context ?? {});
   if (!context.success) {
     refuse(
@@ -229,11 +252,11 @@ export function registerFileEntriesTool(server: McpServer, baseUrl: string, stor
     {
       title: "File entries for review",
       description:
-        "File draft entries for a human to author or approve. One entry is one edit: anchor_text is the whole passage being replaced and agent_draft the proposed replacement; either may be a single line or span many lines, and a multi-line block is ONE entry, never one entry per line. Each entry names repo (git remote url preferred), file path, an optional title (a human-readable label the dashboard shows in place of the file path), anchor_text, and anchor_before/anchor_after context lines. Identity is (project, repo, file, sha256(anchor_text)): re-filing a known draft overwrites the agent draft, context, and constraints in place; an entry already approved, applied, or rejected is returned untouched with its own status, and a rejected anchor stays rejected — stop proposing a turned-down passage. file provenance: send exactly one of file_content (the whole file at filing time; the server hashes it) or file_hash (its sha256 hex). constraints: {max_len?, placeholders?: string[], tone?, notes?} — a save breaking max_len or dropping a placeholder is refused later, so declare what the copy must keep. images: up to 8 per entry, each a data:image/ data url or an http(s) url of at most 5 MiB, rendered on the dashboard. Keys the schema does not list are ignored. The dashboard shows entries in the order the agent sends them, so file the most important entries first.",
+        "File the text you want changed as draft entries for a human to author, approve or reject on the dashboard. One entry is one edit: a multi-line block is ONE entry, not one entry per line. Re-filing a known anchor is safe: a draft updates in place; an approved, applied or rejected entry comes back untouched. The dashboard groups entries by project and batch, newest batches first.",
       inputSchema: z.object({
-        project: z.string().min(1),
-        entries: z.array(FileEntryArgs).min(1),
-        filed_by: z.string().min(1).optional(),
+        project: z.string().min(1).describe("The project slug: 1-63 chars of lowercase letters, digits, and inner hyphens. An unknown slug auto-creates the project on first file."),
+        entries: z.array(FileEntryArgs).min(1).describe("The entries to file. One edit per entry."),
+        filed_by: z.string().min(1).optional().describe("A free-form label for the filing agent, shown on the dashboard."),
       }),
       outputSchema: FiledOutput,
     },

package/src/mcp/list-entries.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
-import { listEntries, projectIdBySlug } from "../db/queries.ts";
+import { listEntries, listProjects, projectIdBySlug } from "../db/queries.ts";
 import type { EntryRow } from "../db/queries.ts";
 import type { Store } from "../db/store.ts";
 
@@ -11,75 +11,60 @@ import type { Store } from "../db/store.ts";
  * they meant.
  */
 const ListEntriesArgs = z.object({
-  project: z.string().min(1).optional(),
-  status: z.enum(["draft", "approved", "applied", "rejected"]).optional(),
-  ids: z.array(z.string().min(1)).min(1).optional(),
-  q: z.string().min(1).optional(),
-  limit: z.number().int().min(1).max(200).default(50),
-  cursor: z.string().min(1).optional(),
+  project: z.string().min(1).optional().describe("Only entries of this project slug."),
+  status: z.enum(["draft", "approved", "applied", "rejected"]).optional().describe("Only entries in this status: draft, approved, applied, or rejected. Unset = all statuses."),
+  ids: z.array(z.string().min(1)).min(1).optional().describe("Only these exact entry ids."),
+  q: z.string().min(1).optional().describe("Case-insensitive substring (ASCII-only case fold) over file, anchor_text, agent_draft, and human_text."),
+  limit: z.number().int().min(1).max(200).default(50).describe("Rows per page (max: 200, default 50)."),
+  cursor: z.string().min(1).optional().describe("Keyset pagination: pass the previous page's next_cursor to continue from after the last row returned."),
 });
 
 /**
- * The one mapping from stored rows to the wire shape: every field spelled out, so a new store
- * column reaches the wire only when someone adds it here deliberately — `human_notes` must never
- * (the contract pins it dashboard-only), and `images` is carried on purpose. The SDK passes
+ * Caller-supplied scalars are capped wire-side: a listed page's worst row is bounded even when a
+ * caller filed a huge path or title. The store keeps the full value — the marker names what the
+ * wire row dropped, and fetch_approved still returns the exact untruncated apply-back fields.
+ */
+const LEAN_CAP_CHARS = 200;
+
+function ellipsize(value: string): string {
+  // Code points, never UTF-16 units: an astral glyph straddling the boundary must not split.
+  const glyphs = [...value];
+  return glyphs.length <= LEAN_CAP_CHARS
+    ? value
+    : `${glyphs.slice(0, LEAN_CAP_CHARS).join("")}…+${glyphs.length - LEAN_CAP_CHARS} chars`;
+}
+
+/**
+ * The one mapping from stored rows to the wire's lean index row: every kept field spelled out, so
+ * a new store column reaches the wire only when someone adds it here deliberately — the default
+ * for a new column is OFF the wire (`human_notes` must never reach it; anchors, drafts, texts,
+ * context, constraints, hashes, and images stay fetch_approved/dashboard-side). The SDK passes
  * structuredContent through untouched, so this projection is the strip, not the schema.
  */
-function toWireEntry(row: EntryRow): z.infer<typeof Entry> {
+function toWireEntry(row: EntryRow, slugByProjectId: ReadonlyMap<string, string>): z.infer<typeof Entry> {
   return {
     id: row.id,
-    project_id: row.project_id,
-    batch_id: row.batch_id,
-    repo: row.repo,
-    file: row.file,
-    title: row.title,
-    anchor_text: row.anchor_text,
-    anchor_before: row.anchor_before,
-    anchor_after: row.anchor_after,
-    anchor_hash: row.anchor_hash,
-    file_hash: row.file_hash,
-    agent_draft: row.agent_draft,
-    human_text: row.human_text,
+    project: slugByProjectId.get(row.project_id) ?? row.project_id,
+    file: ellipsize(row.file),
+    title: row.title === null ? null : ellipsize(row.title),
     status: row.status,
-    context: row.context,
-    constraints: row.constraints,
-    filed_by: row.filed_by,
-    stale_note: row.stale_note,
-    applied_hash: row.applied_hash,
-    images: row.images,
-    created_at: row.created_at,
     updated_at: row.updated_at,
-    applied_at: row.applied_at,
-    archived_at: row.archived_at,
   };
 }
 
-/** The wire row shape, `context`, `constraints`, and `images` kept as their stored JSON strings — no re-parse on the way out. */
+/**
+ * The contract's lean index row: short scalar fields only, no text payloads, no images — a listed
+ * page of 200 rows must stay a page. The apply-back row is not reachable through this tool at all:
+ * fetch_approved returns an approved entry's apply-back fields complete, and the dashboard reads
+ * the store directly.
+ */
 const Entry = z.object({
   id: z.string(),
-  project_id: z.string(),
-  batch_id: z.string(),
-  repo: z.string(),
+  project: z.string(),
   file: z.string(),
   title: z.string().nullable(),
-  anchor_text: z.string(),
-  anchor_before: z.string(),
-  anchor_after: z.string(),
-  anchor_hash: z.string(),
-  file_hash: z.string(),
-  agent_draft: z.string().nullable(),
-  human_text: z.string().nullable(),
   status: z.enum(["draft", "approved", "applied", "rejected"]),
-  context: z.string(),
-  constraints: z.string(),
-  filed_by: z.string().nullable(),
-  stale_note: z.string().nullable(),
-  applied_hash: z.string().nullable(),
-  images: z.string(),
-  created_at: z.number(),
   updated_at: z.number(),
-  applied_at: z.number().nullable(),
-  archived_at: z.number().nullable(),
 });
 
 const ListEntriesOutput = z.object({
@@ -103,7 +88,7 @@ export function registerListEntriesTool(server: McpServer, store: Store): void {
     {
       title: "List entries for review",
       description:
-        "List entries in the review queue, ordered by ascending entry id (ulid, i.e. filing order) — the same order a cursor walk covers. Every filter is optional and they combine with AND: project (a slug with no project is refused: read tools never create one), status (draft, approved, applied, rejected), ids (exact entry ids), q (case-insensitive substring, ASCII-only case fold: a row matches when any of file, anchor_text, agent_draft, human_text contains it), limit (default 50, max 200 — a higher value is refused), cursor (keyset pagination: pass the previous page's next_cursor to continue from after the last entry returned). next_cursor is present only when the page returned exactly limit rows, meaning more may exist; absent means the walk is exhausted — stop paging then, never craft a cursor of your own. Each entry carries its stored fields as stored: 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, applied_hash, images, created_at, updated_at, applied_at, archived_at — with context, constraints, and images as their stored JSON strings, not parsed objects. The human's own notes (human_notes) are dashboard-only and never appear in a listed entry.",
+        "List the review queue's entries, ordered by ascending entry id. Every filter is optional and combines with AND. Walk pages via next_cursor; the walk is exhausted when it stops coming back. Each row is a lean index: id, project slug, file, title, status, updated_at. Apply-back fields (anchor, hashes, human text, constraints) come back through fetch_approved, and rejected or applied entries expose no agent-readable text anywhere — the dashboard owns authoring.",
       inputSchema: ListEntriesArgs,
       outputSchema: ListEntriesOutput,
     },
@@ -131,9 +116,11 @@ export function registerListEntriesTool(server: McpServer, store: Store): void {
       });
 
       // An exhausted walk carries no `next_cursor` key at all: absent is the signal to stop, so an
-      // empty page must never smuggle one in.
+      // empty page must never smuggle one in. The slug map mirrors the dashboard's own
+      // project_id → slug resolution (the store row carries the fk, never the slug).
+      const slugByProjectId = new Map(listProjects(store).map((p) => [p.id, p.slug]));
       const output = {
-        entries: rows.map(toWireEntry),
+        entries: rows.map((row) => toWireEntry(row, slugByProjectId)),
         ...(nextCursor === null ? {} : { next_cursor: nextCursor }),
       };
       return {

package/src/mcp/mark-applied.ts

@@ -12,10 +12,10 @@ const SHA256_HEX = /^[0-9a-f]{64}$/;
  * says nothing about what the anchor matched instead.
  */
 const MarkAppliedArgs = z.object({
-  id: z.string().min(1),
-  result: z.enum(["applied", "anchor_stale"]),
-  applied_hash: z.string().regex(SHA256_HEX).optional(),
-  found_text: z.string().min(1).optional(),
+  id: z.string().min(1).describe("The entry id to report on."),
+  result: z.enum(["applied", "anchor_stale"]).describe('`"applied"`: the approved text is in place; the entry moves to applied. `"anchor_stale"`: the anchor no longer matches the file; the entry returns to approved for re-anchoring on the dashboard.'),
+  applied_hash: z.string().regex(SHA256_HEX).optional().describe("The sha256 of the text you applied, as 64 lowercase hex chars; the server does not read repos and records it unverified."),
+  found_text: z.string().min(1).optional().describe("What the anchor matched instead, shown on the dashboard for re-anchoring."),
 });
 
 /** The loop-close answer: the id and the resulting status, nothing more. */
@@ -42,7 +42,7 @@ export function registerMarkAppliedTool(server: McpServer, store: Store): void {
     {
       title: "Report an applied entry or a stale anchor",
       description:
-        "Report the outcome of applying one entry's approved text, closing the loop: result \"applied\" moves an approved entry to applied and stamps applied_at; result \"anchor_stale\" returns the entry to approved and records found_text (optional — what the anchor matched instead; an empty string is refused, so send the matched text or omit the field) in stale_note for re-anchoring on the dashboard. applied_hash (optional) stores the sha256 hex of the text you applied — 64 lowercase hex characters, refused at the boundary when malformed — and is only ever accepted with result \"applied\". Returns {id, status} with the resulting status. Refused, naming the entry, its status, and the fix: an unknown id; an entry in draft (inert until a human approves or rejects it — an agent can never move a draft); an entry in rejected (terminal); an applied entry reported applied again; applied_hash sent with anchor_stale. approved + anchor_stale stays approved; applied + anchor_stale returns to approved; those and approved + applied are the whole agent-side surface.",
+        "Report the outcome of applying one approved entry's text, closing the loop. Call it after applying the approved text in place, or when the anchor no longer matches the file.",
       inputSchema: MarkAppliedArgs,
       outputSchema: MarkAppliedOutput,
     },

package/src/mcp/server.ts

@@ -11,12 +11,17 @@ import type { Notifier } from "../notify.ts";
 import { NAME, VERSION } from "../version.ts";
 
 /**
- * Read by a client before it calls anything, so it states the rule an agent cannot discover from a
- * tool signature: prose belongs to the human, and filing a draft is not shipping it.
+ * Framing plus the router: one line per tool in the order a caller decides, and the one
+ * cross-tool fact no tool owns (a rejected anchor stays rejected). Nothing here restates a
+ * tool's own description, and the refusal text teaches what the boundary refuses by name.
  */
 const INSTRUCTIONS = `reviewzy is a review queue for user-facing text. Agents draft, a human signs off.
 
-File the text you want to change as draft entries against a project. One entry is one edit: anchor_text is the whole passage being replaced and agent_draft the proposed replacement; either may be a single line or span many lines, and a multi-line block is ONE entry, never one entry per line. A human authors or approves the wording on the dashboard, then you fetch those words back and apply them in place. You can create a draft, move an approved entry to applied, and report an anchor that no longer matches. You can never approve or reject an entry, and a rejected anchor stays rejected: re-filing it returns the existing entry instead of proposing the passage again.`;
+- \`file_entries\`: file the text you want to change as draft entries.
+- \`await_approved\`: wait when this session needs the human's sign-off before continuing.
+- \`fetch_approved\`: fetch whatever is approved and apply the text in place.
+- \`mark_applied\`: after applying, report the outcome (applied or anchor_stale).
+- rejected stays rejected: re-filing a rejected anchor returns the existing entry.`;
 
 /**
  * A fresh server per request, since the 2026-07-28 revision is stateless and `createMcpHandler`