@ctrl-spc/cs 0.4.0 → 0.6.0

package/dist/mcp.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { createServer as createHttpServer } from 'node:http';
@@ -9,6 +9,8 @@ import { z } from 'zod';
 import { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
 import { agentPath } from './agents.js';
 import { mcpToken, readSession } from './config.js';
+import { readPngScreenshot, } from './screenshots.js';
+import { hostedRemoteIdentity } from './git-remote.js';
 export function attributionFromClientName(name) {
     if (!name)
         return null;
@@ -18,6 +20,50 @@ export function attributionFromClientName(name) {
         return 'codex';
     return null;
 }
+/** 31 Slice 2: the grounding manifest — what the author READ before writing.
+ *  The three keys are a CONTRACT with the web parser
+ *  (web/src/lib/artifactGrounding.ts ID_LIST_KEYS): anything else stored in
+ *  the column renders as no grounding, so the keys are pinned here and
+ *  validated in the handler rather than left to convention. */
+const GROUNDING_KEYS = ['client_context_record_ids', 'project_document_ids', 'codebases'];
+/**
+ * Validate a grounding manifest into exactly what will be stored, or refuse
+ * it (31 Slice 2). Enforcement stays MANIFEST ONLY — nothing here inspects
+ * whether the reads happened; it only refuses a manifest the web parser
+ * could never render, which would otherwise be a provenance claim that
+ * silently reads as no claim at all.
+ */
+function validateGrounding(value) {
+    const refuse = (message) => ({
+        ok: false,
+        error: errorResult(`create_artifact: ${message} Nothing was created.`),
+    });
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return refuse('grounding must be an object of id lists: { client_context_record_ids, project_document_ids, codebases }.');
+    }
+    const manifest = {};
+    let named = 0;
+    for (const [key, lists] of Object.entries(value)) {
+        if (!GROUNDING_KEYS.includes(key)) {
+            return refuse(`grounding key "${key}" is not part of the manifest contract — use only ` +
+                `${GROUNDING_KEYS.join(' / ')} (anything else renders as NO grounding in the web app).`);
+        }
+        if (lists === undefined)
+            continue;
+        if (!Array.isArray(lists) || lists.some((entry) => typeof entry !== 'string' || !entry.trim())) {
+            return refuse(`grounding.${key} must be an array of non-empty strings.`);
+        }
+        if (lists.length === 0)
+            continue;
+        manifest[key] = lists.map((entry) => entry.trim());
+        named += lists.length;
+    }
+    if (named === 0) {
+        return refuse('this grounding manifest names nothing you read — omit `grounding` instead, and say in the ' +
+            'artifact itself that available context went unread.');
+    }
+    return { ok: true, value: manifest };
+}
 /** Awaits a Supabase call and throws on error — callers catch once, at the
  *  handler boundary (mirrors v1's `must`). */
 async function must(query) {
@@ -26,6 +72,12 @@ async function must(query) {
         throw new Error(error.message);
     return data;
 }
+/** The message of a thrown value, WITHOUT assuming it is an `Error`. `(err as
+ *  Error).message` is a lie the type system permits: a thrown string, a
+ *  `DOMException` from an aborted fetch, or a rejected non-Error makes it a
+ *  `TypeError` raised from inside the very catch block that exists to contain
+ *  failures — which escapes the catch and defeats it. */
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
 function textResult(payload) {
     return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
 }
@@ -60,7 +112,13 @@ async function listTasksHandler(client, args) {
         let query = client
             .from('tasks')
             .select(`id, project_id, name, status, due_date, ${TASK_TAGS}`)
-            .is('archived_at', null);
+            .is('archived_at', null)
+            // 22b: a Product Idea is a `tasks` row the organization has NOT agreed to
+            // build. It is not backlog work, and an agent that cannot tell the
+            // difference will happily start on one — so it never appears here. The
+            // agent surface for ideas is a later slice; until then they are invisible
+            // to tools, exactly as they are to the board.
+            .eq('is_idea', false);
         if (args.project_id)
             query = query.eq('project_id', args.project_id);
         const rows = (await must(query
@@ -143,7 +201,32 @@ async function fetchFeedbackRounds(client, taskId) {
  * Adapted from v1's `getTaskHandler` for the column shapes, with every
  * topology / checkout / coordination section dropped.
  */
-async function getTaskHandler(client, args) {
+/**
+ * Fetch a task's live artifacts WITH their grounding manifests (31 Slice 2),
+ * degrading gracefully against a database that predates migration
+ * 20260730150000 — the fetchFeedbackRounds posture, for the same reason: the
+ * published CLI is versioned independently of DB migrations, and get_task
+ * must not die because one optional column is missing. Any OTHER error still
+ * throws, so genuinely failed queries surface through get_task's normal
+ * error path.
+ */
+async function fetchTaskArtifacts(client, taskId) {
+    const artifactsQuery = (columns) => client
+        .from('artifacts')
+        .select(columns)
+        .eq('task_id', taskId)
+        .is('deleted_at', null)
+        .order('created_at', { ascending: true })
+        .order('id', { ascending: true });
+    const withGrounding = await artifactsQuery(`${ARTIFACT_COLUMNS},grounding`);
+    if (!withGrounding.error)
+        return (withGrounding.data ?? []);
+    if (!isUndefinedColumnError(withGrounding.error))
+        throw new Error(withGrounding.error.message);
+    const base = await must(artifactsQuery(ARTIFACT_COLUMNS));
+    return base ?? [];
+}
+export async function getTaskHandler(client, args) {
     try {
         const row = await must(client
             .from('tasks')
@@ -153,20 +236,17 @@ async function getTaskHandler(client, args) {
             .maybeSingle());
         if (!row)
             return errorResult(`No task found for id "${args.id}".`);
-        const [comments, artifacts, decisions, feedback] = await Promise.all([
+        const [comments, artifacts, decisions, feedback, openFlags] = await Promise.all([
             must(client
                 .from('comments')
                 .select('id,task_id,body,author_id,from_agent,agent_run_id,created_at,updated_at')
                 .eq('task_id', row.id)
                 .order('created_at', { ascending: true })
                 .order('id', { ascending: true })),
-            must(client
-                .from('artifacts')
-                .select(ARTIFACT_COLUMNS)
-                .eq('task_id', row.id)
-                .is('deleted_at', null)
-                .order('created_at', { ascending: true })
-                .order('id', { ascending: true })),
+            // 31 Slice 2: artifacts ride with their grounding manifests (nullable
+            // column, degrade-tolerant helper) so a reader can tell what an
+            // artifact's author read — and, by absence, what it did not.
+            fetchTaskArtifacts(client, row.id),
             // D3: the item's decisions — the questions ask_question opened and the
             // answers the user gave in the web UI, so the agent can read them back.
             must(client
@@ -186,12 +266,79 @@ async function getTaskHandler(client, args) {
             // a pre-20260724210000 database the helper degrades to the base columns
             // with defaulted resolution state rather than failing the whole read.
             fetchFeedbackRounds(client, row.id),
+            // 24c Slice 2: the item's OPEN flags — what the human-invoked
+            // apply-flags agent was handed. Dismissed/resolved flags are a human's
+            // settled judgement and are deliberately not surfaced here.
+            must(client
+                .from('cliv2_work_item_flags')
+                .select('id, suggested_edit, quote, source_id, agent_name, raised_at')
+                .eq('work_item_id', row.id)
+                .eq('status', 'open')
+                .order('raised_at', { ascending: true })
+                .order('id', { ascending: true })),
         ]);
+        // Source attribution for the flags (which material the quote lives in) —
+        // read only when flags exist, so an unflagged item costs nothing extra.
+        const flagList = openFlags ?? [];
+        let flagsSection = {};
+        if (flagList.length > 0) {
+            const flagSourceIds = [...new Set(flagList.map((flag) => flag.source_id))];
+            const flagSources = (await must(client
+                .from('client_sources')
+                .select('id, kind, from_name, happened_at')
+                .in('id', flagSourceIds))) ?? [];
+            const sourceById = new Map(flagSources.map((source) => [source.id, source]));
+            flagsSection = {
+                flags: flagList.map((flag) => {
+                    const source = sourceById.get(flag.source_id);
+                    return {
+                        id: flag.id,
+                        suggested_edit: flag.suggested_edit,
+                        quote: flag.quote,
+                        source_id: flag.source_id,
+                        // Attribution degrades visibly, never silently: a source the
+                        // caller cannot resolve reads as unresolved, not omitted.
+                        source_kind: source?.kind ?? null,
+                        source_from: source?.from_name ?? null,
+                        source_happened_at: source?.happened_at ?? null,
+                        agent_name: flag.agent_name,
+                        raised_at: flag.raised_at,
+                    };
+                }),
+                flags_note: 'These flags were raised by an intake agent because newer client material contradicts this ' +
+                    'item. They are guidance, not patches: act on them ONLY because the human handed you this ' +
+                    'item. When the edits are made, call resolve_work_item_flags with this work item id.',
+            };
+        }
+        // Grounding presence, made legible in the listing: a null manifest is
+        // DROPPED (an ungrounded artifact claims nothing — an ever-present null
+        // would train agents to skim past the real ones), and one note explains
+        // the key when at least one artifact carries it.
+        const artifactList = (artifacts ?? []).map((artifact) => {
+            const { grounding, ...rest } = artifact;
+            return grounding !== null && grounding !== undefined ? { ...rest, grounding } : rest;
+        });
+        const anyGrounded = artifactList.some((artifact) => 'grounding' in artifact);
         const { task_tags: _drop, ...task } = row;
         return textResult({
             task: { ...task, tags: tagsOf(row) },
+            // 22b Slice 4: FIRST key after the task when the item is an idea, so it
+            // cannot be skimmed past. The flag alone (is_idea buried among columns)
+            // told an agent nothing, and every sentence about the boundary lived in
+            // tools this flow never calls.
+            ...(row.is_idea === true ? { product_idea_boundary: IDEA_BOUNDARY } : {}),
+            // 24c Slice 2: present ONLY when open flags exist — an empty flags
+            // shell on every item would train agents to skim past the real ones.
+            ...flagsSection,
             comments: comments ?? [],
-            artifacts: artifacts ?? [],
+            artifacts: artifactList,
+            ...(anyGrounded
+                ? {
+                    artifacts_grounding_note: 'Artifacts carrying `grounding` were written after reading the named context ' +
+                        '(client_context_record_ids / project_document_ids / codebases). An artifact without ' +
+                        'one claims no grounding — its text should say why available context went unread.',
+                }
+                : {}),
             decisions: decisions ?? [],
             feedback: feedback ?? [],
         });
@@ -211,7 +358,211 @@ async function getTaskHandler(client, args) {
  * `from_agent` is rejected ("agent artifacts must be created through
  * create_agent_artifact"), so un-coordinated tool use writes as the user.
  */
-async function createArtifactHandler(client, userId, currentSession, args) {
+/* 22b Slice 2: an idea has not been agreed to, so a plan for BUILDING it is a
+   category error — the web does not offer the type while `is_idea`, and the two
+   tools that can set a type refuse it. Enforced at the tool rather than in the
+   database by the user's ruling; the residual (a service-key caller going
+   straight to PostgREST) is named in the feature's ux.md. */
+const PLAN_ON_IDEA_REFUSAL = 'A Product Idea cannot carry an implementation plan. Promote it to the Backlog first, or record this as an analysis or spec instead.';
+/* 22b Slice 3 — an agent turning a signal into Product Ideas.
+   Two tools, because everything else it needs already ships. */
+/** The Description of a Product Idea is the human's own thinking (22b, user
+    ruling): the agent may fill an EMPTY one, and may never overwrite or edit one
+    that has content. Its own analysis belongs in an artifact. */
+/** A Product Idea has no status. The web hides the control (22b user ruling)
+    because "Backlog" under a banner saying the item is NOT in the Backlog is a
+    contradiction — and an agent that sets `in_progress` on an idea pre-starts
+    work nobody agreed to, invisibly, since the board does not render ideas. */
+const STATUS_ON_IDEA_REFUSAL = 'A Product Idea has no status — it is not on the board, and nothing about it has been agreed to. Promote it first (a human does that in the web app); then it can move through Backlog / In Progress / Done.';
+/* 22b Slice 4 — the boundary, stated where the agent actually reads it.
+   An agent is handed an idea id through /ctrl-spc work <id> or a human saying
+   "look at wi-4821"; the flows that carry the Concept guidance
+   (list_product_ideas, create_product_idea) are never called. get_task is the
+   read every such flow passes through, so the read is where the item says what
+   it is. "Do not implement" has NO enforcement point — an agent edits files
+   directly, outside this tool surface — so it is stated, honestly, as a rule
+   rather than pretended to be a guard. The other three rules are backed by
+   refusals that already ship (Slices 2 and 3). */
+const IDEA_BOUNDARY = {
+    what_this_is: 'This work item is a PRODUCT IDEA — pre-backlog. Nobody has agreed to build it.',
+    you_may: [
+        'Explore it: read the codebase, and write what you find as artifacts on this item (create_artifact — analysis, spec, diagram, mock, wireframe, user_story).',
+        "Write the description ONLY if it is empty. It is the human's own thinking, and one with content cannot be changed.",
+    ],
+    you_may_not: [
+        'Change production code for it. Exploration is not implementation — no source files, no migrations, nothing that ships.',
+        'Promote it, or treat it as started work. Promotion is a human decision, taken in the web app; no tool you have can do it.',
+    ],
+};
+const DESCRIPTION_IS_THE_HUMANS_REFUSAL = "The description of a Product Idea is the human's own. This one already has content, so it cannot be changed — put your analysis in an artifact instead (create_artifact), where it sits next to the original signal. "
+    + 'This is enforced by the tool, not a preference: asking again, or being told to, will not change the answer. If the human wants their own words replaced, they edit them themselves in the web app. Do not offer to overwrite it.';
+/**
+ * The project's Product Ideas — the pre-backlog work items `list_tasks`
+ * deliberately hides (Slice 1), so an agent stops treating unapproved ideas as
+ * committed work.
+ *
+ * WHICH IS EXACTLY WHY THIS EXISTS. With ideas invisible, an agent asked to
+ * capture a signal cannot tell whether the project already has an idea for that
+ * problem, and the only thing it can do is create another one. This is the
+ * deliberate way to see them.
+ *
+ * Returns enough to JUDGE OVERLAP and nothing more: title, whether a human has
+ * written a description, how many artifacts it carries, and when it last moved.
+ * Artifact bodies are not included — reading three ideas' worth of analysis to
+ * decide "is this the same problem?" would spend the context window on the
+ * question rather than the answer. `get_task` reads one in full when the answer
+ * is "maybe".
+ */
+/** Ideas returned in one call. Past this the listing is TRUNCATED and says so —
+ *  the same doctrine as MANIFEST_FETCH_ROWS: an unreported truncation here reads
+ *  as "no existing idea covers this", which is precisely the duplicate this tool
+ *  exists to prevent. */
+const IDEA_FETCH_ROWS = 200;
+/** Ids per artifact-count request. `.in()` puts every id in the GET query
+ *  string (~37 bytes each), so one batch of 200 ideas would push ~8 KB at the
+ *  gateway's URI limit and fail the whole tool exactly when a project has
+ *  enough ideas for duplicate-checking to matter. */
+const COUNT_BATCH = 50;
+export async function listProductIdeasHandler(client, args) {
+    try {
+        if (args.project_id && !UUID_RE.test(args.project_id)) {
+            return errorResult(`"${args.project_id}" is not a project id. Call list_tasks (or list_product_ideas with no argument) to see your projects and their ids.`);
+        }
+        const projects = (await must(client.from('projects').select('id, name'))) ?? [];
+        let query = client
+            .from('tasks')
+            .select('id, project_id, name, description, created_at, updated_at', { count: 'exact' })
+            .eq('is_idea', true)
+            .is('archived_at', null);
+        if (args.project_id)
+            query = query.eq('project_id', args.project_id);
+        const { rows, total } = await mustWithCount(query.order('updated_at', { ascending: false }).limit(IDEA_FETCH_ROWS));
+        const counts = new Map();
+        for (let i = 0; i < rows.length; i += COUNT_BATCH) {
+            const ids = rows.slice(i, i + COUNT_BATCH).map((row) => row.id);
+            const artifacts = (await must(client
+                .from('artifacts')
+                .select('task_id')
+                .in('task_id', ids)
+                .is('deleted_at', null))) ?? [];
+            for (const artifact of artifacts) {
+                counts.set(artifact.task_id, (counts.get(artifact.task_id) ?? 0) + 1);
+            }
+        }
+        const ideas = rows.map((row) => ({
+            id: row.id,
+            project_id: row.project_id,
+            project: projects.find((p) => p.id === row.project_id) ?? { id: row.project_id },
+            title: row.name,
+            // Not the text: whether the human has written one. That is what decides
+            // whether you may fill it, and it keeps their thinking out of a listing.
+            has_description: typeof row.description === 'string' && row.description.trim().length > 0,
+            artifact_count: counts.get(row.id) ?? 0,
+            created_at: row.created_at,
+            last_activity_at: row.updated_at,
+        }));
+        return textResult({
+            projects,
+            ideas,
+            // Say what was left out rather than letting a truncated listing read as
+            // "nothing like this exists yet".
+            ...(total > rows.length
+                ? {
+                    omitted: {
+                        ideas: total - rows.length,
+                        note: `Showing the ${rows.length} most recently active of ${total} Product Ideas. Narrow with project_id before concluding that nothing covers your signal.`,
+                    },
+                }
+                : {}),
+            guidance: [
+                'Before creating anything, check these for an idea that already covers the same problem — including ideas in OTHER projects listed here — and add an artifact to it instead of creating a near-duplicate.',
+                'Read the codebase before proposing anything. Read the repository you are working in, whether or not a codebase is attached to the project: an empty idea list does not mean an empty product.',
+                'CREATING NOTHING IS A VALID AND COMPLETE OUTCOME. If the product already does what the signal asks for, do not create an idea for it, do not create an idea for an adjacent gap you noticed instead, and do not record the absence anywhere. Just say so briefly and stop.',
+                'One signal is usually AT MOST one idea. Several customers describing one problem is one idea, not one per quote.',
+                'SAME SUBJECT IS NOT THE SAME PROBLEM. An existing idea about what a digest CONTAINS does not cover a signal about WHEN it is delivered; an idea about doing something faster does not cover a signal about undoing it. Fold a signal into an existing idea only when the underlying problem is the one that idea already names — otherwise it is its own idea, even though it sounds adjacent. When you genuinely cannot tell, add the artifact to the existing idea AND say which reading you took, so a human can split it.',
+            ].join(' '),
+        });
+    }
+    catch (err) {
+        return errorResult(`list_product_ideas failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Create a pre-backlog work item — `is_idea = true` — through the RPC Slice 1
+ * already shipped. It is NOT in the Backlog, no work starts, and only a human
+ * can promote it.
+ *
+ * `description` is accepted only because a brand-new idea's description is empty
+ * by definition; there is nothing to overwrite. Every later write to it goes
+ * through update_task, which refuses once a human has written there.
+ */
+export async function createProductIdeaHandler(client, userId, args) {
+    try {
+        const title = args.title?.trim();
+        if (!args.project_id)
+            return errorResult('create_product_idea requires project_id.');
+        if (!UUID_RE.test(args.project_id)) {
+            return errorResult(`"${args.project_id}" is not a project id. Call list_product_ideas (or list_tasks) to see your projects and their ids.`);
+        }
+        if (!title)
+            return errorResult('create_product_idea requires a title.');
+        // 24c Slice 3 (Q4 ruling): from an intake run the tool takes an explicit
+        // project_id AND the client it serves, and validates the edge — an idea
+        // from a client conversation must land in a project attached to THAT
+        // client (24b's projects.client_id), never in whichever project the agent
+        // happened to think of. Additive: without client_id the 22b behaviour is
+        // byte-for-byte unchanged.
+        if (args.client_id !== undefined) {
+            const resolvedClient = await resolveClient(client, args.client_id, 'create_product_idea');
+            if (!resolvedClient.ok)
+                return resolvedClient.error;
+            const project = await must(client.from('projects').select('id, name, client_id').eq('id', args.project_id).maybeSingle());
+            if (!project) {
+                return errorResult(`create_product_idea: no project found for id "${args.project_id}". Nothing was created.`);
+            }
+            if (project.client_id !== resolvedClient.value.id) {
+                return errorResult(`create_product_idea: project "${project.name}" (${project.id}) is not attached to client ` +
+                    `"${resolvedClient.value.name}" — an idea from this client's material lands in one of THIS ` +
+                    "client's projects. get_client_context lists them under `projects`; when there are several, " +
+                    'choose one and say why. Nothing was created.');
+            }
+        }
+        const id = await must(client.rpc('create_product_idea', {
+            p_project: args.project_id,
+            p_name: title,
+            p_description: args.description?.trim() ?? '',
+            p_owner: userId,
+        }));
+        if (!id)
+            throw new Error('create_product_idea returned no id.');
+        // The row is COMMITTED by this point. A failure to read it back is not a
+        // failed create, and reporting it as one makes the agent retry — producing
+        // the duplicate this whole tool exists to avoid.
+        let task = null;
+        let readBackWarning;
+        try {
+            task = await fetchTask(client, id);
+        }
+        catch (err) {
+            readBackWarning = `The Product Idea was created (id ${id}) but could not be read back: ${errorMessage(err)}. Do NOT create it again — call get_task with that id.`;
+        }
+        // `status` is omitted deliberately: the row carries 'backlog' so it has a
+        // place to land on promotion, but echoing it directly under "not in the
+        // Backlog" contradicts the note in the one result an agent reads to decide
+        // whether it just did something committal. The web hides the same field for
+        // the same reason.
+        const { status: _unpromotedStatus, ...ideaRow } = (task ?? { id });
+        return textResult({
+            product_idea: ideaRow,
+            ...(readBackWarning ? { warning: readBackWarning } : {}),
+            note: 'Created as a Product Idea — not in the Backlog, and no work has started. Put your analysis in an artifact on it (create_artifact). Only a human can promote it.',
+        });
+    }
+    catch (err) {
+        return errorResult(`create_product_idea failed: ${errorMessage(err)}`);
+    }
+}
+export async function createArtifactHandler(client, userId, currentSession, args) {
     try {
         if (!args.task_id)
             return errorResult('create_artifact requires task_id.');
@@ -231,9 +582,21 @@ async function createArtifactHandler(client, userId, currentSession, args) {
         if (args.purpose_key?.trim().startsWith('wireframe_option:')) {
             return errorResult("The purpose_key prefix 'wireframe_option:' is reserved for present_wireframes / present_mocks presentations.");
         }
-        const task = await must(client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null).maybeSingle());
+        // 31 Slice 2: the grounding manifest, validated to the exact key contract
+        // the web parser reads — refused BEFORE any write, like every other shape
+        // problem.
+        let grounding;
+        if (args.grounding !== undefined) {
+            const validated = validateGrounding(args.grounding);
+            if (!validated.ok)
+                return validated.error;
+            grounding = validated.value;
+        }
+        const task = await must(client.from('tasks').select('id, is_idea').eq('id', args.task_id).is('archived_at', null).maybeSingle());
         if (!task)
             return errorResult(`No task found for id "${args.task_id}".`);
+        if (task.is_idea === true && args.type === 'plan')
+            return errorResult(PLAN_ON_IDEA_REFUSAL);
         const row = await must(client
             .from('artifacts')
             .insert({
@@ -246,6 +609,9 @@ async function createArtifactHandler(client, userId, currentSession, args) {
             created_by: userId,
             from_agent: null,
             agent_run_id: null,
+            // Only ever ADDS the key: an insert without grounding stays
+            // byte-compatible with a database that predates the column.
+            ...(grounding !== undefined ? { grounding } : {}),
         })
             .select(ARTIFACT_COLUMNS)
             .single());
@@ -273,12 +639,310 @@ async function createArtifactHandler(client, userId, currentSession, args) {
                 attributionWarning = `Artifact created, but recording session attribution failed: ${err.message}`;
             }
         }
-        return textResult(attributionWarning ? { artifact: row, attribution_warning: attributionWarning } : { artifact: row });
+        return textResult({
+            // The re-select uses ARTIFACT_COLUMNS (which deliberately predates the
+            // grounding column, so every other read path keeps working against a
+            // pre-migration database); the stored manifest is echoed from the
+            // validated input instead.
+            artifact: grounding !== undefined ? { ...row, grounding } : row,
+            ...(attributionWarning ? { attribution_warning: attributionWarning } : {}),
+        });
     }
     catch (err) {
         return errorResult(`create_artifact failed: ${err.message}`);
     }
 }
+const SCREENSHOT_PLATFORM_LABEL = {
+    web: 'Web',
+    ios: 'iOS',
+    android: 'Android',
+};
+function attachScreenshotFailure(title, reason) {
+    return errorResult(`Couldn’t attach "${title}": ${reason}. No artifact was created.`);
+}
+function screenshotArtifactId(taskId, title, platform, target, bytes) {
+    const digest = createHash('sha256')
+        .update('ctrl-spc:screenshot:v1\0')
+        .update(taskId)
+        .update('\0')
+        .update(title)
+        .update('\0')
+        .update(platform)
+        .update('\0')
+        .update(target)
+        .update('\0')
+        .update(bytes)
+        .digest()
+        .subarray(0, 16);
+    // RFC 9562-shaped, deterministic UUID. The content-addressed identity makes
+    // a retry after Storage succeeded but Postgres failed converge on the same
+    // object instead of leaking one new object per retry.
+    digest[6] = (digest[6] & 0x0f) | 0x50;
+    digest[8] = (digest[8] & 0x3f) | 0x80;
+    const hex = digest.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function isDuplicateStorageObject(error) {
+    return /duplicate|already exists|resource exists/i.test(`${error.message} ${error.error ?? ''} ${error.name ?? ''}`);
+}
+function screenshotArtifactMatches(row, expected) {
+    return (row.id === expected.id &&
+        row.task_id === expected.taskId &&
+        row.type === 'image' &&
+        row.format === 'png' &&
+        row.title === expected.title &&
+        row.content === expected.content &&
+        row.storage_path === expected.storagePath &&
+        row.created_by === expected.userId &&
+        row.deleted_at === null);
+}
+async function fetchScreenshotArtifact(client, artifactId) {
+    return must(client
+        .from('artifacts')
+        .select('id,task_id,type,format,title,content,storage_path,created_by,deleted_at')
+        .eq('id', artifactId)
+        .maybeSingle());
+}
+async function downloadScreenshotObject(client, storagePath) {
+    const { data, error } = await client.storage.from('artifacts').download(storagePath);
+    if (error)
+        throw new Error(error.message);
+    if (!data)
+        throw new Error('Storage returned no file data');
+    const arrayBuffer = await data.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+async function ensureScreenshotAttribution(client, userId, sessionId, artifactId) {
+    try {
+        await must(client.from('cliv2_agent_outputs').insert({
+            user_id: userId,
+            session_id: sessionId,
+            kind: 'artifact',
+            product_id: artifactId,
+        }));
+        return undefined;
+    }
+    catch (err) {
+        // A completed call whose response was lost already has this unique
+        // attribution row. Treat it as converged rather than warning or duplicating.
+        try {
+            const existing = await must(client
+                .from('cliv2_agent_outputs')
+                .select('user_id,session_id,product_id')
+                .eq('kind', 'artifact')
+                .eq('product_id', artifactId)
+                .maybeSingle());
+            if (existing?.user_id === userId && existing.product_id === artifactId)
+                return undefined;
+        }
+        catch {
+            // Preserve the original attribution failure below.
+        }
+        return `Screenshot attached, but recording session attribution failed: ${err.message}`;
+    }
+}
+function attachedScreenshotResult(title, platform, target, artifactId, attributionWarning) {
+    const success = `✓ Attached "${title}" to this work item.\n` +
+        `  ${SCREENSHOT_PLATFORM_LABEL[platform]} · ${target} · image artifact ${artifactId}`;
+    return attributionWarning
+        ? { content: [{ type: 'text', text: `${success}\n  Warning: ${attributionWarning}` }] }
+        : { content: [{ type: 'text', text: success }] };
+}
+/**
+ * Attach one already-captured PNG to this connection's open work session.
+ *
+ * The local file is fully validated before the first hosted request. The
+ * Storage upload intentionally precedes the artifact INSERT: the private bucket
+ * has no DELETE policy (objects follow the artifact soft-delete posture), so an
+ * upload failure must never leave a live broken card. There is no transaction
+ * across Supabase Storage and Postgres; if the upload succeeds but the row
+ * insert fails, the stable object key is reported for maintenance cleanup.
+ */
+export async function attachScreenshotHandler(client, userId, currentSession, args, deps = {}) {
+    const title = args.title?.trim() ?? '';
+    if (!currentSession) {
+        return errorResult('attach_screenshot needs an open work session — call begin_work first. No artifact was created.');
+    }
+    if (!title) {
+        return attachScreenshotFailure('Untitled screenshot', 'title must be non-empty');
+    }
+    const target = args.target?.trim() ?? '';
+    if (!target) {
+        return attachScreenshotFailure(title, 'target must be non-empty');
+    }
+    if (!['web', 'ios', 'android'].includes(args.platform)) {
+        return attachScreenshotFailure(title, "platform must be 'web', 'ios', or 'android'");
+    }
+    let screenshot;
+    try {
+        screenshot = await (deps.readScreenshot ?? readPngScreenshot)(args.path);
+    }
+    catch (err) {
+        return attachScreenshotFailure(title, err.message);
+    }
+    try {
+        // Resolve only the open session's task. There is deliberately no task_id
+        // argument, so one MCP connection cannot attach a screenshot to some other
+        // work item while it is working this one.
+        const task = await must(client
+            .from('tasks')
+            .select('id,project_id')
+            .eq('id', currentSession.taskId)
+            .is('archived_at', null)
+            .maybeSingle());
+        if (!task) {
+            return attachScreenshotFailure(title, 'the open work item was not found or is archived');
+        }
+        const project = await must(client
+            .from('projects')
+            .select('id,org_id')
+            .eq('id', task.project_id)
+            .is('archived_at', null)
+            .maybeSingle());
+        if (!project) {
+            return attachScreenshotFailure(title, 'the work item project was not found or is not accessible');
+        }
+        const artifactId = deps.artifactId?.() ??
+            screenshotArtifactId(task.id, title, args.platform, target, screenshot.bytes);
+        const storagePath = `${project.org_id}/${task.project_id}/${task.id}/${artifactId}.png`;
+        const metadata = {
+            platform: args.platform,
+            target,
+            width: screenshot.width,
+            height: screenshot.height,
+            size_bytes: screenshot.sizeBytes,
+        };
+        const content = JSON.stringify(metadata);
+        const expectedArtifact = {
+            id: artifactId,
+            taskId: task.id,
+            title,
+            content,
+            storagePath,
+            userId,
+        };
+        // Supabase Storage documents that upload needs INSERT RLS. upsert:false is
+        // intentional: this call never replaces an existing screenshot and
+        // therefore does not require SELECT + UPDATE permissions.
+        const { error: uploadError } = await client.storage
+            .from('artifacts')
+            .upload(storagePath, screenshot.bytes, {
+            contentType: 'image/png',
+            upsert: false,
+        });
+        if (uploadError && !isDuplicateStorageObject(uploadError)) {
+            return attachScreenshotFailure(title, `the PNG could not be uploaded: ${uploadError.message}`);
+        }
+        if (uploadError) {
+            let existing;
+            try {
+                existing = await fetchScreenshotArtifact(client, artifactId);
+            }
+            catch (err) {
+                return errorResult(`Couldn’t attach "${title}": the screenshot object already exists, but CTRL+SPC could not confirm ` +
+                    `whether artifact ${artifactId} is complete: ${err.message}. The existing object and any ` +
+                    'artifact record were left unchanged; do not retry until the artifact can be checked.');
+            }
+            if (existing) {
+                if (!screenshotArtifactMatches(existing, expectedArtifact)) {
+                    return errorResult(`Couldn’t attach "${title}": the retry key is already linked to a different artifact record. ` +
+                        `Existing artifact ${artifactId} was left unchanged; no new artifact was created.`);
+                }
+                const warning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+                return attachedScreenshotResult(title, args.platform, target, artifactId, warning);
+            }
+            // No artifact row means this may be an orphan from an interrupted call.
+            // Verify the private object's exact bytes before linking it; a key
+            // collision must never turn someone else's object into this evidence.
+            let existingBytes;
+            try {
+                existingBytes = await downloadScreenshotObject(client, storagePath);
+            }
+            catch (err) {
+                return errorResult(`Couldn’t attach "${title}": the screenshot object already exists, but CTRL+SPC could not verify ` +
+                    `its bytes: ${err.message}. The existing object was left unchanged; no artifact was created.`);
+            }
+            if (!existingBytes.equals(screenshot.bytes)) {
+                return errorResult(`Couldn’t attach "${title}": the retry key points to an existing screenshot with different bytes. ` +
+                    `The existing object was left unchanged; no artifact was created.`);
+            }
+            // The exact object is an orphan from a previous call that failed at
+            // Postgres. Continue with the same deterministic id/path to finish it.
+        }
+        let row;
+        try {
+            row = await must(client
+                .from('artifacts')
+                .insert({
+                id: artifactId,
+                task_id: task.id,
+                type: 'image',
+                format: 'png',
+                title,
+                content,
+                storage_path: storagePath,
+                created_by: userId,
+                from_agent: null,
+                agent_run_id: null,
+            })
+                .select(ARTIFACT_COLUMNS)
+                .single());
+        }
+        catch (err) {
+            // The insert response may have been lost after Postgres committed, or a
+            // concurrent retry may have won. Re-read before describing an orphan.
+            let existing;
+            try {
+                existing = await fetchScreenshotArtifact(client, artifactId);
+            }
+            catch (readErr) {
+                return errorResult(`Couldn’t confirm whether "${title}" finished attaching after the PNG upload: ` +
+                    `${readErr.message}. Artifact ${artifactId} may already exist; the private object at ` +
+                    `"${storagePath}" was left unchanged. Do not retry until the artifact can be checked.`);
+            }
+            if (existing) {
+                if (!screenshotArtifactMatches(existing, expectedArtifact)) {
+                    return errorResult(`Couldn’t attach "${title}": artifact id ${artifactId} is already used by a different record. ` +
+                        'The existing artifact was left unchanged; no new artifact was created.');
+                }
+                const warning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+                return attachedScreenshotResult(title, args.platform, target, artifactId, warning);
+            }
+            // The bucket intentionally has no DELETE policy. Removing an object by
+            // writing storage.objects directly is unsupported by Supabase, so do not
+            // pretend this cross-service boundary is atomic.
+            return errorResult(`Couldn’t attach "${title}": the PNG uploaded, but the artifact record could not be created: ` +
+                `${err.message}. No artifact was created. The unlinked private object at ` +
+                `"${storagePath}" may require maintenance cleanup.`);
+        }
+        if (!row) {
+            let existing;
+            try {
+                existing = await fetchScreenshotArtifact(client, artifactId);
+            }
+            catch (readErr) {
+                return errorResult(`Couldn’t confirm whether "${title}" finished attaching after the PNG upload: ` +
+                    `${readErr.message}. Artifact ${artifactId} may already exist; the private object at ` +
+                    `"${storagePath}" was left unchanged. Do not retry until the artifact can be checked.`);
+            }
+            if (existing) {
+                if (!screenshotArtifactMatches(existing, expectedArtifact)) {
+                    return errorResult(`Couldn’t attach "${title}": artifact id ${artifactId} is already used by a different record. ` +
+                        'The existing artifact was left unchanged; no new artifact was created.');
+                }
+                const warning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+                return attachedScreenshotResult(title, args.platform, target, artifactId, warning);
+            }
+            return errorResult(`Couldn’t attach "${title}": the PNG uploaded, but the artifact record returned no row. ` +
+                `No artifact was created. The unlinked private object at "${storagePath}" may require maintenance cleanup.`);
+        }
+        const attributionWarning = await ensureScreenshotAttribution(client, userId, currentSession.sessionId, artifactId);
+        return attachedScreenshotResult(title, args.platform, target, artifactId, attributionWarning);
+    }
+    catch (err) {
+        return attachScreenshotFailure(title, err.message);
+    }
+}
 /** Re-fetch one task with the SAME select get_task uses (`*` + the tag join),
  *  returning the parsed task object ({ ...row, tags }, task_tags dropped) or null.
  *  Shared by update_task and create_task so their result shape matches get_task's
@@ -298,15 +962,30 @@ async function fetchTask(client, id) {
  * the same `save_task_if_current` RPC v1 uses; an `edit_conflict` maps to a clear
  * "call get_task again and retry" message. Re-fetches with get_task's select.
  */
-async function updateTaskHandler(client, args) {
+export async function updateTaskHandler(client, args) {
     try {
         const { id, fields, expected_revision } = args;
         if (!Number.isInteger(expected_revision) || expected_revision < 1) {
             return errorResult('update_task requires expected_revision (a positive integer) from the most recent get_task response.');
         }
-        const current = await must(client.from('tasks').select('id,status,revision').eq('id', id).is('archived_at', null).maybeSingle());
+        const current = await must(client.from('tasks').select('id,status,revision,is_idea,description').eq('id', id).is('archived_at', null).maybeSingle());
         if (!current)
             return errorResult(`No task found for id "${id}".`);
+        // 22b Slice 3: on a Product Idea the description IS the user-only section.
+        // An empty one may be filled; one with content is the human's and is never
+        // edited or overwritten — not with a prompt, not "just this once".
+        if (fields.description !== undefined
+            && current.is_idea === true
+            && (current.description ?? '').trim().length > 0) {
+            return errorResult(DESCRIPTION_IS_THE_HUMANS_REFUSAL);
+        }
+        // Found by the Step 2b end-to-end gate: status was writable on an idea. The
+        // board hides ideas, so it looked harmless — but the value persisted, and
+        // promotion then landed the item in In Progress while the human's
+        // confirmation dialog promised "Backlog … this will not start work".
+        if (fields.status !== undefined && current.is_idea === true) {
+            return errorResult(STATUS_ON_IDEA_REFUSAL);
+        }
         const patch = {};
         if (fields.name !== undefined)
             patch.name = fields.name;
@@ -355,7 +1034,7 @@ async function updateTaskHandler(client, args) {
  * "call get_task again and retry" message updateTask uses. Re-fetches the live
  * artifact with ARTIFACT_COLUMNS so the result matches get_task / create_artifact.
  */
-async function updateArtifactHandler(client, args) {
+export async function updateArtifactHandler(client, args) {
     try {
         const { id, fields, expected_revision } = args;
         if (!Number.isInteger(expected_revision) || expected_revision < 1) {
@@ -365,6 +1044,24 @@ async function updateArtifactHandler(client, args) {
         // tool exposes (title / type / format / content). purpose_key is deliberately
         // excluded (it could escape the context-artifact reservation), and deleted_at is
         // never sent from here.
+        // update_artifact is the OTHER door onto the plan rule: its patch carries
+        // `type`, so refusing only at insert would leave "create an analysis, then
+        // retype it to plan" wide open.
+        if (fields.type === 'plan') {
+            // No `deleted_at` filter: save_artifact_if_current does not filter on it
+            // either, so a soft-deleted artifact is still writable — filtering here
+            // would find no owner and skip the check on exactly the rows the RPC will
+            // happily update.
+            const owner = await must(client.from('artifacts').select('task_id').eq('id', id).maybeSingle());
+            // Refuse unless it is PROVEN not to be an idea. A null task (RLS, a race,
+            // a deleted row) is not proof, and this branch guards a rule — failing
+            // open here would let the exact write it exists to stop through.
+            if (owner) {
+                const task = await must(client.from('tasks').select('is_idea').eq('id', owner.task_id).maybeSingle());
+                if (task?.is_idea !== false)
+                    return errorResult(PLAN_ON_IDEA_REFUSAL);
+            }
+        }
         const patch = {};
         if (fields.title !== undefined)
             patch.title = fields.title;
@@ -478,6 +1175,46 @@ async function addCommentHandler(client, userId, currentSession, args) {
         return errorResult(`add_comment failed: ${err.message}`);
     }
 }
+/**
+ * Validate an epic/sprint placement target BEFORE anything is created (feature
+ * 32, Slice 1). The three refusals mirror app.guard_task's same-project rule
+ * and the archive semantics 27/28 shipped (an archived container "leaves the
+ * picker" — it takes no NEW work), but they fire HERE, where the agent can fix
+ * the call, instead of as a Postgres exception after the task row exists.
+ */
+async function resolvePlacementTarget(client, table, noun, id, projectId) {
+    if (!UUID_RE.test(id)) {
+        return {
+            ok: false,
+            error: errorResult(`create_task: "${id}" is not ${noun === 'epic' ? 'an epic' : 'a sprint'} id. Use the id ` +
+                `create_${noun} returned, or the one a duplicate-name refusal named. Nothing was created.`),
+        };
+    }
+    const row = await must(client.from(table).select('id, name, project_id, archived_at').eq('id', id).maybeSingle());
+    if (!row) {
+        return {
+            ok: false,
+            error: errorResult(`create_task: no ${noun} found for id "${id}". Nothing was created.`),
+        };
+    }
+    if (row.project_id !== projectId) {
+        return {
+            ok: false,
+            error: errorResult(`create_task: ${noun} "${row.name}" (${row.id}) belongs to a different project than ` +
+                `"${projectId}". ${noun === 'epic' ? 'An epic groups' : 'A sprint sequences'} work inside ONE ` +
+                `project — create the task in the ${noun}'s project, or pick ${noun === 'epic' ? 'an epic' : 'a sprint'} from this one. ` +
+                'Nothing was created.'),
+        };
+    }
+    if (row.archived_at !== null) {
+        return {
+            ok: false,
+            error: errorResult(`create_task: ${noun} "${row.name}" (${row.id}) is archived — it has left the picker and takes ` +
+                `no new work. Place the task in a live ${noun}, or leave ${noun}_id off. Nothing was created.`),
+        };
+    }
+    return { ok: true, value: { id: row.id } };
+}
 /**
  * Create a new task in a project the user owns (via RLS), owned by the user.
  * Adapted from v1's `createTaskHandler`, minimal — tags / depends_on /
@@ -485,11 +1222,32 @@ async function addCommentHandler(client, userId, currentSession, args) {
  * (SECURITY DEFINER; the old `create_task_with_workflow` was removed with the
  * Workflows feature, see 20260721150000_drop_workflows.sql) to insert the task
  * and return its id, then re-fetches with get_task's select.
+ *
+ * Feature 32 (agile skeleton), Slice 1: optional `epic_id` / `sprint_id` place
+ * the new task at creation — additive args per the Step −1 ruling (small
+ * orthogonal tools; update_task's refusal of sprint fields stands untouched).
+ * Both targets are validated BEFORE the create (same project, not archived),
+ * and the placement itself goes through `save_task_if_current` — the ONLY
+ * task-update path the web uses, whose p_changes whitelist has carried
+ * `epic_id` / `sprint_id` since 20260727080000 — with the fresh row's
+ * revision, so the CAS contract is honored rather than bypassed.
  */
-async function createTaskHandler(client, userId, currentSession, args) {
+export async function createTaskHandler(client, userId, currentSession, args) {
     try {
         if (!args.name || !args.name.trim())
             return errorResult('create_task requires a non-empty name.');
+        // Placement targets are validated before ANY write: a refusal here must
+        // leave nothing to un-create.
+        if (args.epic_id !== undefined) {
+            const epic = await resolvePlacementTarget(client, 'epics', 'epic', args.epic_id, args.project_id);
+            if (!epic.ok)
+                return epic.error;
+        }
+        if (args.sprint_id !== undefined) {
+            const sprint = await resolvePlacementTarget(client, 'sprints', 'sprint', args.sprint_id, args.project_id);
+            if (!sprint.ok)
+                return sprint.error;
+        }
         const taskId = await must(client.rpc('create_task', {
             p_project: args.project_id,
             p_name: args.name,
@@ -498,9 +1256,40 @@ async function createTaskHandler(client, userId, currentSession, args) {
         }));
         if (!taskId)
             throw new Error('Task insert returned no id.');
-        const task = await fetchTask(client, taskId);
+        let task = await fetchTask(client, taskId);
         if (!task)
             throw new Error('Created task could not be re-fetched.');
+        // Place the fresh task under its epic/sprint. The task row is COMMITTED by
+        // this point, so a placement failure is surfaced as a warning on the real
+        // result — reporting it as a failed create would make the agent retry and
+        // duplicate the task (the create_product_idea read-back lesson).
+        let placementWarning;
+        if (args.epic_id !== undefined || args.sprint_id !== undefined) {
+            try {
+                const revision = task.revision;
+                if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 1) {
+                    throw new Error('the created task carried no usable revision');
+                }
+                await must(client.rpc('save_task_if_current', {
+                    p_task_id: taskId,
+                    p_expected_revision: revision,
+                    p_changes: {
+                        ...(args.epic_id !== undefined ? { epic_id: args.epic_id } : {}),
+                        ...(args.sprint_id !== undefined ? { sprint_id: args.sprint_id } : {}),
+                    },
+                    p_tag_ids: null,
+                    p_reorder: false,
+                    p_before_task_id: null,
+                }));
+                task = (await fetchTask(client, taskId)) ?? task;
+            }
+            catch (err) {
+                placementWarning =
+                    `The task was created (id ${taskId}) but placing it under its epic/sprint failed: ` +
+                        `${errorMessage(err)}. Do NOT create the task again — report the failed placement; ` +
+                        'a human can place it from the board.';
+            }
+        }
         // D2a attribution: if this connection has an open session, record that the
         // session produced this NEW task — one cliv2_agent_outputs row referencing the
         // task BY VALUE. This is a follow-up task the subagent created, NOT the
@@ -524,12 +1313,219 @@ async function createTaskHandler(client, userId, currentSession, args) {
                 attributionWarning = `Task created, but recording session attribution failed: ${err.message}`;
             }
         }
-        return textResult(attributionWarning ? { task, attribution_warning: attributionWarning } : { task });
+        return textResult({
+            task,
+            ...(placementWarning ? { placement_warning: placementWarning } : {}),
+            ...(attributionWarning ? { attribution_warning: attributionWarning } : {}),
+        });
     }
     catch (err) {
         return errorResult(`create_task failed: ${err.message}`);
     }
 }
+/* ---------------------------------------------------------------------------
+ * Agile skeleton (feature 32, Slice 1) — `create_epic` / `create_sprint`,
+ * beside the grown `create_task` above.
+ *
+ * The agent lays out the WHOLE skeleton from one feature ask: an epic (what
+ * for), work items under it, sprints (ordered batches). Step −1 rulings
+ * (ux.md, 2026-07-30): DIRECT WRITE as the user under RLS — a skeleton of
+ * backlog items is un-started work, closer to an idea than an edit, so no
+ * propose queue; SMALL ORTHOGONAL TOOLS, not a composite draft pass;
+ * IDEMPOTENCE = read-before-write plus a duplicate-name refusal that teaches
+ * extending the existing structure instead of minting a parallel one.
+ *
+ * THE CALIBRATION RULE LIVES IN THE DESCRIPTIONS (teach-in-the-description
+ * doctrine): agents dramatically overestimate how long building takes because
+ * their training is saturated with human engineering timelines. The
+ * descriptions state the bias outright, size sprints as ordered batches of
+ * agent-executable work, and forbid duration estimates on items unless the
+ * user asked. Nothing here stores an estimate — there is no column for one,
+ * deliberately.
+ *
+ * GRANTS, verified against the seeded rows rather than assumed: members hold
+ * ('member','epic','create') (20260727080000 §4) and ('member','sprint',
+ * 'create') (20260708000000 init.sql §9), and no later migration revokes
+ * either — so the epics_insert / sprints_insert RLS policies already admit
+ * every org member and NO new grants migration is needed. A denial for some
+ * future role surfaces through the normal error path.
+ *
+ * NO cliv2_agent_outputs attribution row is written for an epic or a sprint:
+ * the kind check is ('artifact','comment','task','decision') and widening it
+ * is a migration this slice does not need — the skeleton's provenance is
+ * legible through its work items, which create_task already attributes.
+ * ------------------------------------------------------------------------- */
+/** Date args are refused by shape HERE (the resolveClient idiom) so a
+ *  malformed date gets a clean tool error instead of a Postgres cast failure
+ *  after other work happened. */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** The project a skeleton tool writes into, resolved by id: UUID-shape-checked
+ *  before the read, and a miss (no such project, or one outside the caller's
+ *  orgs — RLS makes those indistinguishable on purpose) refused by id. */
+async function resolveSkeletonProject(client, projectIdArg, tool) {
+    const projectId = typeof projectIdArg === 'string' ? projectIdArg.trim() : '';
+    if (!projectId || !UUID_RE.test(projectId)) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: "${projectId}" is not a project id. Call list_tasks to see your projects and their ids. ` +
+                'Nothing was created.'),
+        };
+    }
+    const row = await must(client.from('projects').select('id, name').eq('id', projectId).maybeSingle());
+    if (!row) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: no project found for id "${projectId}". Nothing was created.`),
+        };
+    }
+    return { ok: true, value: row };
+}
+/** Refuse a malformed date arg by name; `undefined` passes (the arg is
+ *  optional everywhere it appears). */
+function validDateArg(tool, field, value) {
+    if (value === undefined)
+        return null;
+    if (!ISO_DATE_RE.test(value)) {
+        return errorResult(`${tool}: ${field} must be an ISO date (YYYY-MM-DD), got "${value}". Nothing was created.`);
+    }
+    return null;
+}
+/**
+ * Create an Epic in a project — writes public.epics as the user (RLS
+ * epics_insert, the 'epic'/'create' grant every member holds).
+ *
+ * THE DUPLICATE-NAME REFUSAL IS THE IDEMPOTENCE MECHANISM (Step −1 ruling 4):
+ * a re-run, or a "feature ABC v2" ask, must EXTEND the existing epic, not
+ * mint a second one — 24c's updating-beats-creating rule applied to
+ * structure. The match is case-insensitive on the trimmed name, against LIVE
+ * epics only: an archived epic has left the picker and can take no new work,
+ * so a fresh epic re-using its name is a legitimate new start, not a
+ * duplicate. The refusal lists the project's live epics so it doubles as the
+ * read surface the skeleton pass otherwise lacks (no epic-listing tool ships
+ * in this slice).
+ */
+export async function createEpicHandler(client, args) {
+    try {
+        const project = await resolveSkeletonProject(client, args.project_id, 'create_epic');
+        if (!project.ok)
+            return project.error;
+        const name = typeof args.name === 'string' ? args.name.trim() : '';
+        if (!name)
+            return errorResult('create_epic requires a non-empty name. Nothing was created.');
+        for (const [field, value] of [
+            ['start_date', args.start_date],
+            ['target_date', args.target_date],
+        ]) {
+            const refused = validDateArg('create_epic', field, value);
+            if (refused)
+                return refused;
+        }
+        // Mirrors the DB's epics_target_not_before_start check, refused where the
+        // agent can fix it instead of as a constraint violation.
+        if (args.start_date && args.target_date && args.target_date < args.start_date) {
+            return errorResult(`create_epic: target_date (${args.target_date}) is before start_date (${args.start_date}). ` +
+                'Nothing was created.');
+        }
+        const epics = (await must(client.from('epics').select('id, name, archived_at').eq('project_id', project.value.id))) ?? [];
+        const live = epics.filter((epic) => epic.archived_at === null);
+        const duplicate = live.find((epic) => epic.name.trim().toLowerCase() === name.toLowerCase());
+        if (duplicate) {
+            const listing = live.map((epic) => `"${epic.name}" (${epic.id})`).join(', ');
+            return errorResult(`create_epic: an epic named "${duplicate.name}" already exists in "${project.value.name}" ` +
+                `(id ${duplicate.id}). Do not create a duplicate — EXTEND the existing epic: create the new ` +
+                `work items with epic_id ${duplicate.id}, and reshape what already hangs under it. A re-run ` +
+                'or a "v2" ask extends the existing skeleton; it never mints a second one. Live epics in ' +
+                `this project: ${listing}. Nothing was created.`);
+        }
+        const epic = await must(client
+            .from('epics')
+            .insert({
+            project_id: project.value.id,
+            name,
+            ...(args.description?.trim() ? { description: args.description.trim() } : {}),
+            ...(args.start_date ? { start_date: args.start_date } : {}),
+            ...(args.target_date ? { target_date: args.target_date } : {}),
+        })
+            .select('id, project_id, name, description, start_date, target_date, created_at')
+            .single());
+        if (!epic)
+            throw new Error('Epic insert returned no row.');
+        return textResult({
+            epic,
+            note: 'Created as an empty epic — no work has started and none is declared. Place work items under ' +
+                "it with create_task's epic_id, sequence them with create_sprint + sprint_id, and add NO " +
+                'duration estimates to anything unless the user asked: sequencing is the value.',
+        });
+    }
+    catch (err) {
+        return errorResult(`create_epic failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Create a Sprint in a project — writes public.sprints as the user (RLS
+ * sprints_insert, the 'sprint'/'create' grant every member holds). Dates are
+ * optional (28 made the columns nullable): for agent-executed work a sprint is
+ * an ORDERED BATCH, not a time-box, and an invented fortnight is exactly the
+ * human-timeline bias this feature exists to counter.
+ *
+ * Same duplicate-name posture as create_epic, for the same reason: a re-run
+ * must extend the existing sprint sequence, never mint a parallel one.
+ */
+export async function createSprintHandler(client, args) {
+    try {
+        const project = await resolveSkeletonProject(client, args.project_id, 'create_sprint');
+        if (!project.ok)
+            return project.error;
+        const name = typeof args.name === 'string' ? args.name.trim() : '';
+        if (!name)
+            return errorResult('create_sprint requires a non-empty name. Nothing was created.');
+        for (const [field, value] of [
+            ['start_date', args.start_date],
+            ['end_date', args.end_date],
+        ]) {
+            const refused = validDateArg('create_sprint', field, value);
+            if (refused)
+                return refused;
+        }
+        // Mirrors the sprints table's own start <= end check (init.sql), refused
+        // where the agent can fix it.
+        if (args.start_date && args.end_date && args.end_date < args.start_date) {
+            return errorResult(`create_sprint: end_date (${args.end_date}) is before start_date (${args.start_date}). ` +
+                'Nothing was created.');
+        }
+        const sprints = (await must(client.from('sprints').select('id, name, archived_at').eq('project_id', project.value.id))) ?? [];
+        const live = sprints.filter((sprint) => sprint.archived_at === null);
+        const duplicate = live.find((sprint) => sprint.name.trim().toLowerCase() === name.toLowerCase());
+        if (duplicate) {
+            const listing = live.map((sprint) => `"${sprint.name}" (${sprint.id})`).join(', ');
+            return errorResult(`create_sprint: a sprint named "${duplicate.name}" already exists in "${project.value.name}" ` +
+                `(id ${duplicate.id}). Reuse it — place items into it with create_task's sprint_id — or name ` +
+                'the NEXT batch in the sequence; a re-run extends the existing sprint sequence, it never ' +
+                `mints a parallel one. Live sprints in this project: ${listing}. Nothing was created.`);
+        }
+        const sprint = await must(client
+            .from('sprints')
+            .insert({
+            project_id: project.value.id,
+            name,
+            ...(args.start_date ? { start_date: args.start_date } : {}),
+            ...(args.end_date ? { end_date: args.end_date } : {}),
+        })
+            .select('id, project_id, name, start_date, end_date, created_at')
+            .single());
+        if (!sprint)
+            throw new Error('Sprint insert returned no row.');
+        return textResult({
+            sprint,
+            note: 'Created. Sprints for agent-executed work are ordered batches: the first holds what unblocks ' +
+                "everything else, each sized to what agents deliver in a session or a day. Place items with " +
+                "create_task's sprint_id, and add NO duration estimates unless the user asked.",
+        });
+    }
+    catch (err) {
+        return errorResult(`create_sprint failed: ${errorMessage(err)}`);
+    }
+}
 /**
  * Ask the user a question about the work item the open session is on (D3). Unlike
  * the write tools, this REQUIRES an open session — the question is a decision on
@@ -1414,24 +2410,2216 @@ async function getCredentialHandler(client, args) {
     }
 }
 // ---------------------------------------------------------------------------
-// The twenty-two tools this server exposes. Exported for the self-check.
+// Project context (feature 13a, Phase 3) — `get_project_context`.
+//
+// READ-ONLY, and read-only over a V1-OWNED PRODUCT TABLE. `public.project_documents`
+// is the table the web app writes under Project settings → Project context (Phase 1)
+// and on a codebase page (Phase 2). AGENTS.md § "Database schema naming" allows
+// exactly this: the v2 surface may `select` shared product data through the signed-in
+// user's RLS, as the web app does; what it may not do is WRITE outside `cliv2_*` or
+// hold its own state there. This tool writes nothing and adds no `cliv2_*` row.
+//
+// SCOPE IS FILTERED IN THE QUERY, NOT IN JS. A document is project-scoped when
+// `codebase_id is null` and codebase-scoped when `codebase_id = <id>` — the whole
+// model, per 20260726220000_project_documents_codebase_scope.sql. Both scopes are
+// read with their own predicate (`.is('codebase_id', null)` / `.eq('codebase_id', id)`)
+// so a codebase document can NEVER reach a project-only response, whatever the
+// caller passed. Filtering after the fact would make that a code-path property
+// instead of a query property; both earlier phases were reviewed on this point.
+//
+// NO OPEN SESSION IS REQUIRED when `task_id` is passed. That is a deliberate
+// departure from the '<tool> needs an open work session — call begin_work first.'
+// gate every WRITE tool carries: reading a project's standing context BEFORE
+// opening a work session is a legitimate and expected flow (an agent orienting
+// itself), and the tool mutates nothing that would need attributing to a session.
+// With neither a session nor a task_id there is genuinely no project to resolve,
+// and the refusal is phrased as the instruction (the doctrine at registerTool):
+// it names both ways out.
 // ---------------------------------------------------------------------------
-export const TOOL_NAMES = [
-    'list_tasks',
-    'get_task',
-    'create_artifact',
-    'update_task',
-    'update_artifact',
-    'set_task_role_slugs',
-    'add_comment',
-    'create_task',
-    'begin_work',
-    'end_work',
-    'ask_question',
-    'present_wireframes',
-    'present_mocks',
-    'resolve_feedback',
-    'record_user_input',
+/** The five types `public.project_documents.type` admits, verbatim from the
+ *  migration's check constraint and the web composer's Select. */
+const PROJECT_DOCUMENT_TYPES = ['instructions', 'architecture', 'design', 'conventions', 'other'];
+/** Phase 4's `propose_project_context` resolves the project exactly as Phase 3's
+ *  reader does, so the refusal copy is written once and parameterized by the
+ *  tool doing the asking rather than duplicated and left to drift. */
+const noProjectContextError = (tool) => `${tool} needs to know which project. Call begin_work first, or pass task_id.`;
+/** The empty-state note, verbatim from the approved transcript. It says where the
+ *  documents come from, so an agent that finds none doesn't try to create one —
+ *  there is no write path, by design.
+ *
+ *  IT ONLY FIRES ON AN UNNARROWED READ (no `codebase`, no `types`) — a user ruling —
+ *  AND ONLY WHEN THE PROJECT REALLY IS EMPTY, codebase scopes included; see
+ *  `unnarrowedEmptyNote`.
+ *  When a filter emptied the result the project may be full of documents, and
+ *  telling the agent "this project has no context documents yet" would make it
+ *  conclude there is no context to read. That case gets `narrowedEmptyNote` below,
+ *  which names the filter and points at relaxing it. It also never points at
+ *  *Project settings → Project context*, because a codebase's own documents are
+ *  written on the codebase page (Phase 2), not there. */
+const NO_PROJECT_DOCUMENTS_NOTE = 'This project has no context documents yet. They are written by people in the web app, under Project settings → Project context.';
+/**
+ * WHOLE-RESPONSE BYTE BUDGET. `project_documents.content` is unbounded `text` and
+ * the default call — `get_project_context({})` — asks for every project document
+ * at once, so without a cap one team's long architecture doc can blow an agent's
+ * context window with no warning.
+ *
+ * THE BUDGET IS A BOUND, AND A BOUND CAN COST ROWS. A document that doesn't fit
+ * comes back with its content cut at an explicit marker plus `content_length`, so
+ * the agent still sees it exists and how big it is. But metadata is not free: with
+ * enough documents the zero-content stubs alone exceed the budget, and at that
+ * point "never drop a row" and "never exceed 100KB" cannot both hold. The bound
+ * wins and the tail is dropped — with an explicit omitted COUNT in the note, so
+ * the invariant that survives is *the agent is always told what it did not get*,
+ * not *every row appears*.
+ */
+const MAX_RESPONSE_BYTES = 100_000;
+/** A hard row cap per scope, so a pathological document count can't make the
+ *  response unbounded in row terms even when every document is tiny. Both scopes
+ *  are read separately, so a codebase-scoped call can return up to 2× this. */
+const MAX_DOCUMENT_ROWS = 200;
+const TRUNCATION_MARKER = '…[truncated by get_project_context]';
+/** Emitted once, at the top level, whenever any document was cut. Phrased as the
+ *  next action: narrow with `types` and call again. */
+const TRUNCATED_NOTE = 'Some documents were truncated to keep this response under 100KB — each one carries its full ' +
+    'character count as `content_length`. Call again with `types` (and `codebase`) to narrow the read ' +
+    'and get the documents you need in full.';
+/** Appended to TRUNCATED_NOTE when the budget ran out before every document could
+ *  even be listed. It names the count, because a silently short array is exactly
+ *  the failure this whole block exists to prevent. */
+const omittedNote = (count) => `${count} further document${count === 1 ? ' was' : 's were'} omitted entirely — not even ` +
+    'their titles fit the 100KB budget. Call again with `types` (and `codebase`) to reach them.';
+/** Emitted when a scope hit the row cap, so the caller learns the array is a
+ *  prefix rather than the whole scope. */
+const ROW_CAP_NOTE = `Only the first ${MAX_DOCUMENT_ROWS} documents per scope were read — this project has more. ` +
+    'Call again with `types` (and `codebase`) to narrow the read and reach the rest.';
+/**
+ * One scope's documents, ordered deterministically.
+ *
+ * `codebaseId === null` reads the PROJECT scope (`codebase_id is null`); a value
+ * reads that codebase's own (`codebase_id = <id>`). The two predicates are the
+ * whole difference, and they live here rather than in the caller so neither can
+ * be forgotten.
+ *
+ * ORDER: `created_at` ascending, `id` ascending as the tie-break. `created_at` is
+ * what BOTH web reads use (it is the order the card list renders and new documents
+ * append in, and the trailing column of `project_documents_scope_idx`), so an agent
+ * sees the documents in the order the team wrote them and in the same order the
+ * humans see them. `id` breaks ties so two documents created in the same tick can
+ * never swap places between calls.
+ *
+ * ROW CAP: the query asks for `MAX_DOCUMENT_ROWS + 1`. Postgres truncating at
+ * exactly the cap would be invisible to JS — the caller would get a full-looking
+ * array of 200 with no signal that 300 more exist — so the extra row is the
+ * overflow probe: if it comes back, the scope is `capped` and the response says
+ * so. The byte budget then caps what the kept rows are allowed to say.
+ *
+ * ponytail: nothing caps the bytes FETCHED. `MAX_DOCUMENT_ROWS` caps rows, not
+ * size, so a project with 200 × 1MB documents still pulls ~200MB over the wire
+ * before the budget discards most of it. Bounding the fetch needs a server-side
+ * cut — an RPC selecting `substring(content, 1, N)`. (Phase 3b did add
+ * `project_documents.content_chars`, so a SIZE is now free; a truncated BODY
+ * still is not, and this reader needs the body.) Deliberately left: the ceiling
+ * is real and this comment is the marker, not an oversight.
+ */
+async function fetchProjectDocuments(client, projectId, codebaseId, types) {
+    let query = client
+        .from('project_documents')
+        .select('title, type, content, created_at, updated_at')
+        .eq('project_id', projectId);
+    query = codebaseId === null ? query.is('codebase_id', null) : query.eq('codebase_id', codebaseId);
+    if (types)
+        query = query.in('type', types);
+    const rows = (await must(query
+        .order('created_at', { ascending: true })
+        .order('id', { ascending: true })
+        .limit(MAX_DOCUMENT_ROWS + 1))) ?? [];
+    return { rows: rows.slice(0, MAX_DOCUMENT_ROWS), capped: rows.length > MAX_DOCUMENT_ROWS };
+}
+/**
+ * Does this project hold ANY codebase-scoped document? Asked only when an
+ * unnarrowed read of the project scope came back empty, so the note can say
+ * "pass `codebase`" instead of "this project has no context documents yet" —
+ * a project whose documents all live on codebase pages (Phase 2) is exactly the
+ * shape that made the flat empty-state note a lie.
+ */
+async function hasCodebaseScopedDocuments(client, projectId) {
+    const rows = await must(client
+        .from('project_documents')
+        .select('type')
+        .eq('project_id', projectId)
+        .not('codebase_id', 'is', null)
+        .limit(1));
+    return (rows ?? []).length > 0;
+}
+/**
+ * The distinct document TYPES one scope actually holds, ignoring any `types`
+ * narrowing. Read only when a narrowed read came back empty, so the note can tell
+ * the agent what relaxing the filter would get it instead of leaving it to guess.
+ *
+ * NO ROW LIMIT. This is a `select distinct` in intent: there are five possible
+ * types, and a cap with no `.order()` would leave *which* rows come back
+ * unspecified — a type present only on row 201 would silently vanish from
+ * "Without the type filter it would return: …". One narrow column, at most on a
+ * cold empty-result path.
+ */
+async function fetchProjectDocumentTypes(client, projectId, codebaseId) {
+    let query = client.from('project_documents').select('type').eq('project_id', projectId);
+    query = codebaseId === null ? query.is('codebase_id', null) : query.eq('codebase_id', codebaseId);
+    const rows = await must(query);
+    return [...new Set((rows ?? []).map((row) => row.type))];
+}
+const jsonBytes = (value) => Buffer.byteLength(JSON.stringify(value, null, 2), 'utf8');
+/** CHARACTERS, meaning code points — what `content_length` claims to be and what a
+ *  person counting emoji would say. `String.length` is UTF-16 code units, which
+ *  double-counts every astral character (60,000 emoji would report 120,000).
+ *  The surrogate test short-circuits the allocating spread for the ordinary case. */
+const countCharacters = (text) => /[\uD800-\uDFFF]/.test(text) ? [...text].length : text.length;
+/**
+ * Fit the shaped documents into MAX_RESPONSE_BYTES, in order, cutting content
+ * first and dropping the tail only when even the metadata will not fit.
+ *
+ * The cost of a candidate response is measured by SERIALIZING IT — the same
+ * `JSON.stringify(payload, null, 2)` textResult emits — rather than by summing
+ * per-document estimates, because indentation and escaping make an estimate wrong
+ * in the unsafe direction. It is always measured WITH the WORST-CASE note present
+ * (every note this response could carry, with the largest possible omitted count),
+ * so choosing the real note afterwards can never push the response back over.
+ *
+ * THE STUB FLOOR IS SIZED FIRST. Every not-yet-emitted document is reserved as its
+ * zero-content stub, so the room available to document i is the budget minus what
+ * documents i+1… cost at minimum. That reserve is only sound if the reserve itself
+ * fits: at ~270 bytes of JSON per stub, 400 stubs (both scopes at MAX_DOCUMENT_ROWS)
+ * blow a 100KB budget on metadata alone. So the number of stubs the budget can hold
+ * is binary-searched up front, and anything past it is dropped and COUNTED — see
+ * MAX_RESPONSE_BYTES for why a bound that cannot drop rows is not a bound.
+ *
+ * Two consequences worth keeping:
+ *  - Once a document is cut all the way to zero characters, the budget is spent;
+ *    every remaining document is stubbed WITHOUT probing. Otherwise each of them
+ *    runs a full ⌈log2(len)⌉ binary search whose every probe re-serializes the
+ *    whole payload — measured at seconds of blocked event loop for 400 × 1MB.
+ *  - Cutting is by CODE POINT, not by UTF-16 code unit, so a prefix can never
+ *    split a surrogate pair. That also keeps `fits()` monotone in `chars`, which
+ *    is the binary search's precondition — a half-pair prefix serializes LARGER
+ *    than the whole pair (`\ud83d` escapes to 6 bytes), so a code-unit slice made
+ *    the predicate non-monotone and the search correct only by accident.
+ *    `content_length` is a code-point count for the same reason: the note calls it
+ *    a character count, and 60,000 emoji are 60,000 characters, not 120,000.
+ */
+function fitToBudget(envelope, documents, extraNotes) {
+    // Fast path: everything fits whole and no truncation note is needed. Guarded by
+    // a CHEAP lower bound first — JSON can only ever be longer than the content it
+    // quotes, so once the raw content alone exceeds the budget there is no point
+    // serializing it to find out. Without the guard, 400 × 1MB documents get a
+    // 400MB `JSON.stringify` before the first real decision.
+    const rawChars = documents.reduce((total, document) => total + document.content.length, 0);
+    if (rawChars <= MAX_RESPONSE_BYTES) {
+        const asIs = { ...envelope, documents };
+        if (extraNotes.length)
+            asIs.note = extraNotes.join(' ');
+        if (jsonBytes(asIs) <= MAX_RESPONSE_BYTES) {
+            return { documents, truncated: false, omitted: 0 };
+        }
+    }
+    // The largest note this response could end up carrying. Every real note is a
+    // prefix-or-shorter of it (the omitted count can only shrink), so budgeting
+    // against it is safe in the only direction that matters.
+    const worstCaseNote = [...extraNotes, TRUNCATED_NOTE, omittedNote(documents.length)].join(' ');
+    const size = (docs) => jsonBytes({ ...envelope, documents: docs, note: worstCaseNote });
+    const stubs = documents.map((document) => ({
+        ...document,
+        content: TRUNCATION_MARKER,
+        truncated: true,
+        content_length: countCharacters(document.content),
+    }));
+    // Code points are materialized LAZILY, for the one document actually being cut:
+    // `[...content]` on 400 × 1MB is 400M array elements nobody reads.
+    let pointsIndex = -1;
+    let points = [];
+    const withPrefix = (index, chars) => {
+        if (chars <= 0)
+            return { ...stubs[index], content: TRUNCATION_MARKER };
+        if (pointsIndex !== index) {
+            pointsIndex = index;
+            points = [...documents[index].content];
+        }
+        return {
+            ...stubs[index],
+            content: `${points.slice(0, chars).join('')}\n\n${TRUNCATION_MARKER}`,
+        };
+    };
+    // How many stubs the budget can hold at all. `size` is monotone in the number
+    // of stubs, so this binary search is exact.
+    let floorLo = 0;
+    let floorHi = stubs.length;
+    while (floorLo < floorHi) {
+        const mid = Math.ceil((floorLo + floorHi) / 2);
+        if (size(stubs.slice(0, mid)) <= MAX_RESPONSE_BYTES)
+            floorLo = mid;
+        else
+            floorHi = mid - 1;
+    }
+    if (floorLo < documents.length) {
+        // Metadata alone overflows. No content can fit, so don't pretend to look for
+        // any: emit the stubs that fit and report the rest as an explicit count.
+        return {
+            documents: stubs.slice(0, floorLo),
+            truncated: true,
+            omitted: documents.length - floorLo,
+        };
+    }
+    const fitted = [];
+    let truncated = false;
+    let exhausted = false;
+    for (let index = 0; index < documents.length; index += 1) {
+        // INVARIANT: `[...fitted, stubs[index], ...rest] <= MAX_RESPONSE_BYTES`. Base
+        // case is the stub-floor check above (fitted empty, every document a stub);
+        // each iteration pushes something the last `fits()` call measured against the
+        // same tail, so it holds inductively. That is what makes a zero-character cut
+        // — and every stub after it — safe to push unchecked.
+        if (exhausted) {
+            fitted.push(stubs[index]);
+            continue;
+        }
+        const document = documents[index];
+        const rest = stubs.slice(index + 1);
+        const fits = (candidate) => size([...fitted, candidate, ...rest]) <= MAX_RESPONSE_BYTES;
+        if (fits(document)) {
+            fitted.push(document);
+            continue;
+        }
+        truncated = true;
+        let lo = 0;
+        let hi = stubs[index].content_length ?? 0;
+        while (lo < hi) {
+            const mid = Math.ceil((lo + hi) / 2);
+            if (fits(withPrefix(index, mid)))
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        if (lo === 0)
+            exhausted = true;
+        fitted.push(withPrefix(index, lo));
+    }
+    return { documents: fitted, truncated, omitted: 0 };
+}
+/**
+ * PROJECT RESOLUTION, shared by `get_project_context` (Phase 3) and
+ * `propose_project_context` (Phase 4). Both paths reduce to one task id — `task_id` when given,
+ * otherwise the open session's task (the session registry carries `taskId`, not a
+ * project) — and the project is read off that task. Agents therefore never have to
+ * find, or be trusted with, a project id. An archived or deleted task resolves to
+ * nothing and is refused by id, which is also what happens when a session's task
+ * was archived or deleted after begin_work.
+ *
+ * The task id is UUID-shape-checked BEFORE the read, exactly as resolve_feedback
+ * does, so `{ task_id: "task-1" }` gets a clean tool error naming it instead of a
+ * Postgres `invalid input syntax for type uuid`. A `task_id` that was supplied but
+ * is blank is refused rather than falling through to the open session's task —
+ * silently answering about a DIFFERENT task and reporting success is the worst
+ * possible reading of "   ".
+ *
+ * The project's NAME rides along on the task select (`projects(name)`) rather than
+ * costing a second round-trip; the FK makes the embed non-null, so there is no
+ * "no project for task" state to write copy for.
+ */
+async function resolveContextProject(client, session, taskIdArg, tool) {
+    if (taskIdArg !== undefined && taskIdArg.trim() === '') {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: task_id was blank. Pass a task id, or omit it to use the open session's task.`),
+        };
+    }
+    const taskId = taskIdArg?.trim() || session?.taskId;
+    if (!taskId)
+        return { ok: false, error: errorResult(noProjectContextError(tool)) };
+    if (!UUID_RE.test(taskId)) {
+        return { ok: false, error: errorResult(`${tool}: not a valid task id: "${taskId}".`) };
+    }
+    const task = await must(client
+        .from('tasks')
+        .select('project_id, projects(name)')
+        .eq('id', taskId)
+        .is('archived_at', null)
+        .maybeSingle());
+    if (!task)
+        return { ok: false, error: errorResult(`${tool}: no task found for id "${taskId}".`) };
+    // PostgREST returns a to-one embed as an object, but has returned an array
+    // for the same shape across versions, so both are unwrapped. A MISSING name
+    // is not defaulted to '': `tasks.project_id` is a non-null FK, so a blank
+    // project in the envelope could only mean the read did not return what it
+    // was asked for, and answering with an empty project name is a silent wrong
+    // value in a field the agent uses to know which project it is reading.
+    const embedded = Array.isArray(task.projects) ? (task.projects[0] ?? null) : task.projects;
+    if (!embedded?.name) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: could not read the project for task "${taskId}". Try again, ` +
+                'and if it keeps happening report it — a task always has a project.'),
+        };
+    }
+    return { ok: true, value: { id: task.project_id, name: embedded.name } };
+}
+/**
+ * CODEBASE MATCHING is over the project's own `cliv2_codebases` rows only, on
+ * either the display name or the canonical `host/path` git remote (case-insensitive;
+ * a raw remote URL is canonicalized with the same `hostedRemoteIdentity` the CLI
+ * uses to register one, so `https://github.com/acme/web.git` matches `github.com/acme/web`).
+ * A miss names the known codebases rather than just refusing — the agent can retry
+ * without a second call.
+ *
+ * A NAME CAN BE AMBIGUOUS. `cliv2_codebases` is unique on `(project_id,
+ * git_remote_url)` and NOT on `name`, so one project holding `github.com/acme/web`
+ * and `gitlab.com/acme/web` — both named "web" — is normal. Taking the first hit
+ * would silently answer about whichever was created first, with nothing in the
+ * response for the agent to notice. Every match is collected and more than one is
+ * an error listing the candidates by remote, phrased like the unknown-codebase
+ * miss: it tells the agent exactly what to pass instead.
+ */
+async function resolveContextCodebase(client, projectId, wanted, tool) {
+    const rows = (await must(client
+        .from('cliv2_codebases')
+        .select('id, name, git_remote_url')
+        .eq('project_id', projectId)
+        .order('created_at', { ascending: true }))) ?? [];
+    // `normalizeRemoteUrl` already lowercases (src/git-remote.ts:32) and is
+    // idempotent, and `git_remote_url` is STORED canonical (src/codebases.ts:87),
+    // so the identity comparison subsumes any raw-value comparison. Name matching
+    // stays case-insensitive.
+    const needle = wanted.toLowerCase();
+    const identity = hostedRemoteIdentity(wanted) ?? null;
+    const found = rows.filter((row) => row.name.toLowerCase() === needle ||
+        (identity !== null && row.git_remote_url.toLowerCase() === identity));
+    if (found.length === 0) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: no codebase named "${wanted}" in this project. ` +
+                (rows.length
+                    ? // Deduped: `name` has no unique constraint (only (project_id,
+                        // git_remote_url) does), so two codebases can share one name.
+                        // Listing it twice tells the agent nothing and reads as a bug.
+                        `Known codebases: ${[...new Set(rows.map((row) => row.name))].join(', ')}.`
+                    : 'This project has no codebases yet.')),
+        };
+    }
+    if (found.length > 1) {
+        return {
+            ok: false,
+            error: errorResult(`${tool}: more than one codebase named "${wanted}" in this project. ` +
+                `Matching git remotes: ${found.map((row) => row.git_remote_url).join(', ')}. ` +
+                'Pass the git remote instead of the name.'),
+        };
+    }
+    return { ok: true, value: { id: found[0].id, name: found[0].name } };
+}
+/**
+ * Read the context documents for the project a task belongs to, optionally also
+ * those of one of its codebases, optionally narrowed to some types. Project and
+ * codebase resolution are the two helpers above, shared with Phase 4's
+ * `propose_project_context`.
+ */
+export async function getProjectContextHandler(client, session, args) {
+    try {
+        const resolvedProject = await resolveContextProject(client, session, args.task_id, 'get_project_context');
+        if (!resolvedProject.ok)
+            return resolvedProject.error;
+        const project = resolvedProject.value;
+        const wanted = args.codebase?.trim();
+        let codebase = null;
+        if (wanted) {
+            const resolvedCodebase = await resolveContextCodebase(client, project.id, wanted, 'get_project_context');
+            if (!resolvedCodebase.ok)
+                return resolvedCodebase.error;
+            codebase = resolvedCodebase.value;
+        }
+        // An empty `types` array is treated as "not narrowed", the same as omitting it:
+        // `.in('type', [])` would return nothing, which is never what an agent that sent
+        // an empty list meant.
+        const types = args.types && args.types.length > 0 ? args.types : undefined;
+        // Project documents FIRST, then the codebase's — the order the transcript
+        // fixes and the order the feature's North Star states ("project docs first,
+        // then the codebase's own").
+        const projectDocuments = await fetchProjectDocuments(client, project.id, null, types);
+        const codebaseDocuments = codebase
+            ? await fetchProjectDocuments(client, project.id, codebase.id, types)
+            : { rows: [], capped: false };
+        const shape = (row, scope) => ({
+            title: row.title,
+            type: row.type,
+            scope,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+            content: row.content,
+        });
+        const envelope = {
+            project: project.name,
+            scope: codebase ? `project + codebase:${codebase.name}` : 'project',
+        };
+        // Notes that are true regardless of how the budget lands, and that the budget
+        // therefore has to reserve room for.
+        const notes = [];
+        if (projectDocuments.capped || codebaseDocuments.capped)
+            notes.push(ROW_CAP_NOTE);
+        const fit = fitToBudget(envelope, [
+            ...projectDocuments.rows.map((row) => shape(row, 'project')),
+            ...codebaseDocuments.rows.map((row) => shape(row, 'codebase')),
+        ], notes);
+        if (fit.truncated)
+            notes.push(TRUNCATED_NOTE);
+        if (fit.omitted > 0)
+            notes.push(omittedNote(fit.omitted));
+        const payload = { ...envelope, documents: fit.documents };
+        if (notes.length === 0 && fit.documents.length === 0) {
+            // Only a read that returned NOTHING and hit no cap can be an empty state.
+            const narrowed = Boolean(codebase) || Boolean(types);
+            notes.push(narrowed
+                ? await narrowedEmptyNote(client, project.id, codebase, types)
+                : await unnarrowedEmptyNote(client, project.id));
+        }
+        if (notes.length)
+            payload.note = notes.join(' ');
+        return textResult(payload);
+    }
+    catch (err) {
+        return errorResult(`get_project_context failed: ${err.message}`);
+    }
+}
+/**
+ * The note for a read that a FILTER emptied, not an empty project. It names what
+ * matched nothing and what the same read would return unnarrowed, so an agent
+ * learns that relaxing `types` would help rather than concluding the project has
+ * no context. It never points at *Project settings → Project context*: with a
+ * codebase in play those documents are written on the codebase page (Phase 2).
+ */
+async function narrowedEmptyNote(client, projectId, codebase, types) {
+    const filters = [
+        ...(codebase ? [`codebase "${codebase.name}"`] : []),
+        ...(types ? [`types ${types.join(', ')}`] : []),
+    ];
+    const matched = `No context documents match this read (${filters.join('; ')})`;
+    const scopePhrase = codebase
+        ? `neither this project nor codebase "${codebase.name}" has any context documents at all`
+        : 'this project has no context documents at all';
+    // Without a `types` narrowing there is no type filter to relax, and every scope
+    // this call read came back empty — so the answer is settled without a second
+    // read, and "Without the type filter it would return: …" would be nonsense.
+    if (!types)
+        return `${matched}, and ${scopePhrase}.`;
+    // The extra read is COSMETIC — it only enriches the note. Its failure must not
+    // turn a correct empty answer into `get_project_context failed: …`, so it is
+    // caught here rather than at the handler boundary, and the note degrades to the
+    // sentence that is true without it.
+    let available;
+    try {
+        available = [
+            ...new Set([
+                ...(await fetchProjectDocumentTypes(client, projectId, null)),
+                ...(codebase ? await fetchProjectDocumentTypes(client, projectId, codebase.id) : []),
+            ]),
+        ].sort();
+    }
+    catch {
+        return `${matched}. Call again with different \`types\`, or omit \`types\` to get everything.`;
+    }
+    if (available.length === 0)
+        return `${matched}, and ${scopePhrase}.`;
+    return (`${matched}. ` +
+        `Without the type filter it would return: ${available.join(', ')}. ` +
+        'Call again with different `types`, or omit `types` to get everything.');
+}
+/**
+ * The note for an UNNARROWED read that came back empty. Only the project scope is
+ * read when no `codebase` was passed, so "this project has no context documents
+ * yet" is a lie for exactly the project Phase 2 exists to serve — one whose
+ * documents all live on codebase pages. So before saying it, ask whether any
+ * codebase-scoped document exists, and if so name the way to reach it.
+ *
+ * The lookup is cosmetic and its failure is swallowed: a correct empty answer is
+ * never discarded because a note lookup failed. Falling back to the approved
+ * empty-state note is the honest default — it is what the read this call actually
+ * made returned.
+ */
+async function unnarrowedEmptyNote(client, projectId) {
+    try {
+        if (await hasCodebaseScopedDocuments(client, projectId)) {
+            return ('This project has no project-wide context documents, but at least one of its codebases ' +
+                'has its own. Call again with `codebase` set to the codebase you are working in to read them.');
+        }
+    }
+    catch {
+        // Fall through to the empty-state note.
+    }
+    return NO_PROJECT_DOCUMENTS_NOTE;
+}
+// ---------------------------------------------------------------------------
+// Project context (feature 13a, Phase 4) — `propose_project_context`.
+//
+// THE ONLY WRITE THIS FEATURE'S CLI SURFACE MAKES, AND IT CREATES NO DOCUMENT.
+// An agent that has just read the repo it is working in hands over a batch of
+// PROPOSALS; approval happens in the web app, one by one or all at once, and
+// only an accept creates a `public.project_documents` row. So this tool writes
+// `public.cliv2_context_proposals` — a `cliv2_*` table, per AGENTS.md
+// § "Database schema naming": v2 may READ shared product data through the
+// user's RLS (that is what Phase 3 does), but its own state and every write it
+// makes live behind the `cliv2_` prefix. `project_id`, `codebase_id` and
+// `scanned_codebase_id` are held BY VALUE with no FK, for the same reason.
+//
+// SCOPE IS PER PROPOSAL, NOT PER CALL. A settled user ruling: one scan produces
+// both project-scoped and codebase-scoped proposals at once and they are
+// reviewed together in project settings. `scope: "project"` stores
+// `codebase_id = null`; `scope: "codebase"` stores the SCANNED codebase's id.
+// There is deliberately no way to target a different codebase — the agent read
+// one repo, and a proposal aimed somewhere it never looked is a claim it cannot
+// support.
+//
+// A RE-SCAN REPLACES, AND AN EMPTY SCAN CLEARS. Before inserting, this user's
+// pending rows for (project_id, scanned_codebase_id) are deleted. A scan
+// reports what the repo holds NOW; it carries no memory of past answers — so a
+// scan that finds NOTHING is a real finding and is accepted: it runs the same
+// replace-delete, inserts nothing, and reports what it cleared. Refusing it
+// would mean a repo whose context files were deleted could never get back to
+// "no proposals", which the review surface models as a state (user ruling,
+// 2026-07-27). `codebase` stays required either way — a scan always names the
+// repo it read. The user ruled explicitly
+// that rejecting a proposal DISCARDS it and stores nothing — there is no
+// rejected list and no "already rejected" state to suppress against, and a
+// later scan is free to propose the same thing again (ux.md § Corrections,
+// Phase 4 / 2026-07-27). Anything that looked like suppression here would be
+// inventing that state.
+//
+// NOTHING IS EVER SILENTLY TRUNCATED. The batch is bounded by a proposal COUNT
+// and a total CHARACTER budget, and a batch over either is REFUSED with the
+// limit and the actual figure named. Phase 3's log is a catalogue of what
+// silent truncation costs; a write path has an easier answer than a read path —
+// refuse, and let the agent send a smaller batch — so it takes it.
+//
+// NO ABSOLUTE PATH REACHES THE CLOUD — IN `source_path`. That column, and not
+// the whole row, is what this rule covers, because `source_path` is
+// PRODUCT-EMITTED: the agent derives it from the filesystem it just walked, and
+// it is rendered in `mono` on every proposal card by hosted browser JS, where
+// this product hard-enforces that absolute local paths never appear (AGENTS.md;
+// the contract test at web/src/lib/hosted-path-privacy.contract.test.ts).
+// `content` is deliberately NOT policed the same way: it is AUTHORED prose that
+// the agent read verbatim out of the repo, a hand-typed document may legally
+// contain any text at all, and a check there would refuse AGENTS.md itself —
+// the very document this feature exists to import (user ruling, 2026-07-27).
+// The table cannot police the path either — no check constraint tells a legal
+// relative path from an absolute one across POSIX, Windows drive-letter,
+// drive-relative and UNC forms without knowing the platform — so this tool
+// does, and it REFUSES rather than rewriting: silently rewriting a path the
+// agent sent is how a proposal ends up pointing at a file that isn't there.
+// ---------------------------------------------------------------------------
+/** The scopes a proposal may carry. `project` stores `codebase_id = null`;
+ *  `codebase` stores the scanned codebase's id. */
+const PROPOSAL_SCOPES = ['project', 'codebase'];
+/** `public.project_documents.title` is `length(title) <= 100` (Phase 1 §1).
+ *  Refused HERE so the agent learns at propose time, rather than the user
+ *  discovering at accept time that a proposal can never become a document. */
+const MAX_PROPOSAL_TITLE_CHARS = 100;
+/** How many proposals one scan may hand over. A review surface is a human
+ *  reading cards; a hundred of them is not a review. Refused, never trimmed. */
+const MAX_PROPOSALS = 50;
+/** Total characters across the whole batch (content + title + reason +
+ *  source_path). `content` has no length cap on `project_documents` and gets
+ *  none here — a bound this table enforced but the document table did not would
+ *  make a legal document un-acceptable — so the BATCH is what is bounded, which
+ *  is the thing that actually protects the write. */
+const MAX_PROPOSAL_BATCH_CHARS = 400_000;
+/** Absolute in any form a repo path can arrive in: POSIX (`/etc`), UNC and
+ *  root-relative Windows (`\\server\share`, `\Users\Lane\repo`), Windows
+ *  drive-letter (`C:\repo`, `C:/repo`) and drive-RELATIVE (`C:AGENTS.md`, which
+ *  resolves against that drive's current directory and still discloses a local
+ *  layout). One leading separator of EITHER kind, or any drive letter, is
+ *  enough — a single leading backslash is a Windows absolute path just as `/`
+ *  is a POSIX one.
+ *
+ *  `cliv2_work_reservations_path_relative`
+ *  (20260722160000_cliv2_coordination.sql) is the same rule for the same
+ *  reason, and it has the narrower form with both of those holes. That is a
+ *  pre-existing bug on that table, not a licence to repeat it here. */
+const ABSOLUTE_PATH_RE = /^(?:[\\/]|[A-Za-z]:)/;
+/** A `..` segment under either separator. A relative path that climbs out of
+ *  the scanned repo names a file the scan had no business reading, and it is
+ *  refused for the same privacy reason an absolute path is. */
+const ESCAPING_PATH_RE = /(?:^|[\\/])\.\.(?:[\\/]|$)/;
+/** Where the user reviews what was proposed. The agent's job ends at proposing,
+ *  so the success result has to say this in prose it can relay verbatim. */
+const REVIEW_LOCATION = 'Project settings → Project context';
+/**
+ * Validate one proposal into the row it will become, or refuse it by index AND
+ * by title — an agent that sent twelve proposals needs to know WHICH one, and
+ * an index alone is a poor handle when it is re-reading its own array.
+ */
+function validateProposal(proposal, index, project, scanned) {
+    const at = `proposal ${index + 1}`;
+    const refuse = (message) => ({
+        ok: false,
+        error: errorResult(`propose_project_context: ${at} ${message}`),
+    });
+    if (!proposal || typeof proposal !== 'object') {
+        return refuse('is not an object. Each proposal needs title, type, content, source_path, reason and scope.');
+    }
+    const title = typeof proposal.title === 'string' ? proposal.title.trim() : '';
+    if (!title)
+        return refuse('has no title.');
+    if (countCharacters(title) > MAX_PROPOSAL_TITLE_CHARS) {
+        return refuse(`has a ${countCharacters(title)}-character title; the limit is ${MAX_PROPOSAL_TITLE_CHARS}. ` +
+            'Shorten it — a document title is a heading, not a summary.');
+    }
+    if (!PROJECT_DOCUMENT_TYPES.includes(proposal.type)) {
+        return refuse(`("${title}") has type "${String(proposal.type)}", which is not a context document type. ` +
+            `Use one of: ${PROJECT_DOCUMENT_TYPES.join(', ')}.`);
+    }
+    if (!PROPOSAL_SCOPES.includes(proposal.scope)) {
+        return refuse(`("${title}") has scope "${String(proposal.scope)}". Use "project" for context that applies to the ` +
+            `whole project, or "codebase" for context that belongs to "${scanned.name}" alone.`);
+    }
+    const content = typeof proposal.content === 'string' ? proposal.content : '';
+    if (content.trim() === '') {
+        return refuse(`("${title}") has no content. Propose only what you actually read — an empty document helps nobody.`);
+    }
+    const reason = typeof proposal.reason === 'string' ? proposal.reason.trim() : '';
+    if (!reason) {
+        return refuse(`("${title}") has no reason. Every proposal carries one line saying why this belongs in the ` +
+            "project's context, so the user can judge the judgement and not just the text.");
+    }
+    const rawPath = typeof proposal.source_path === 'string' ? proposal.source_path.trim() : '';
+    if (!rawPath) {
+        return refuse(`("${title}") has no source_path. Name the file in the repo this content came from.`);
+    }
+    if (ABSOLUTE_PATH_RE.test(rawPath)) {
+        return refuse(`("${title}") has an absolute source_path: "${rawPath}". Pass it relative to the root of ` +
+            `"${scanned.name}" (e.g. "docs/architecture.md"). Absolute local paths must never leave this machine.`);
+    }
+    if (ESCAPING_PATH_RE.test(rawPath)) {
+        return refuse(`("${title}") has a source_path that climbs out of the repo: "${rawPath}". Propose only files ` +
+            `inside "${scanned.name}".`);
+    }
+    // A leading "./" is the one rewrite made, because it changes nothing about
+    // which file is named and "./AGENTS.md" renders as noise on a card.
+    const sourcePath = rawPath.replace(/^\.\//, '');
+    return {
+        ok: true,
+        value: {
+            project_id: project.id,
+            codebase_id: proposal.scope === 'project' ? null : scanned.id,
+            scanned_codebase_id: scanned.id,
+            title,
+            type: proposal.type,
+            content,
+            source_path: sourcePath,
+            reason,
+        },
+    };
+}
+/**
+ * Hand over a batch of proposed context documents for a repo the agent has read.
+ *
+ * WRITES PENDING ROWS ONLY. No `project_documents` row is created here under any
+ * argument — the web app's accept does that. The success result therefore ends
+ * by telling the agent where the human reviews them, because that is the only
+ * remaining step and the agent cannot take it.
+ *
+ * REQUIRES NO OPEN SESSION when `task_id` is passed, matching Phase 3. This is a
+ * write, and every other write tool in this file demands a session — but the
+ * session exists to ATTRIBUTE work to a task, and a proposal is attributed to a
+ * project and a codebase, neither of which the session supplies. Scanning a repo
+ * before opening a work session is the ordinary flow (an agent orienting itself),
+ * and refusing it would buy nothing.
+ *
+ * THE REPLACE AND THE INSERT ARE NOT ATOMIC. Two statements, no transaction —
+ * PostgREST has none to offer, and an RPC to get one would put v2 logic in the
+ * database for a case that cannot corrupt anything: the delete is scoped to this
+ * user's rows for exactly this (project, scanned codebase), so a failure between
+ * the two leaves the previous scan's proposals gone and the new ones unwritten.
+ * The recovery is to run the scan again, which is precisely what this tool does.
+ * The insert failing after the delete is reported as a failure, so nothing is
+ * silently lost.
+ */
+export async function proposeProjectContextHandler(client, session, args) {
+    try {
+        const resolvedProject = await resolveContextProject(client, session, args.task_id, 'propose_project_context');
+        if (!resolvedProject.ok)
+            return resolvedProject.error;
+        const project = resolvedProject.value;
+        // The scanned codebase is REQUIRED — every proposal, project-scoped ones
+        // included, records which repo the claim came from, and a project-scoped
+        // proposal with no provenance is unreviewable.
+        const wanted = args.codebase?.trim();
+        if (!wanted) {
+            return errorResult('propose_project_context: name the codebase you scanned in `codebase` (its name or git remote). ' +
+                'Every proposal records which repo it came from.');
+        }
+        const resolvedCodebase = await resolveContextCodebase(client, project.id, wanted, 'propose_project_context');
+        if (!resolvedCodebase.ok)
+            return resolvedCodebase.error;
+        const scanned = resolvedCodebase.value;
+        // AN EMPTY BATCH IS A REAL SCAN RESULT, NOT A MISTAKE. `[]` says the repo
+        // holds no standing context now, and it clears whatever an earlier scan left
+        // pending — without it there is no path from a real scan back to "no
+        // proposals" (user ruling, 2026-07-27). A MISSING or non-array `proposals`
+        // is still a malformed call, and is refused so the empty-scan meaning stays
+        // something the agent has to state on purpose.
+        const proposals = args.proposals;
+        if (!Array.isArray(proposals)) {
+            return errorResult('propose_project_context: `proposals` must be an array. Send the documents you found, or send ' +
+                '`[]` to report that this repo holds no standing context — an empty scan is a finding, and it ' +
+                'clears anything an earlier scan left waiting for review.');
+        }
+        if (proposals.length > MAX_PROPOSALS) {
+            return errorResult(`propose_project_context: ${proposals.length} proposals is more than the limit of ${MAX_PROPOSALS}. ` +
+                'Nothing was written. Propose the documents that carry standing context for the whole team, ' +
+                'not every file you read.');
+        }
+        const rows = [];
+        for (const [index, proposal] of proposals.entries()) {
+            const validated = validateProposal(proposal, index, project, scanned);
+            if (!validated.ok)
+                return validated.error;
+            rows.push(validated.value);
+        }
+        // Measured AFTER per-proposal validation so the agent hears about a broken
+        // proposal before it hears about the batch's size — the specific fault is
+        // more useful than the aggregate one.
+        const totalChars = rows.reduce((total, row) => total +
+            countCharacters(row.content) +
+            countCharacters(row.title) +
+            countCharacters(row.reason) +
+            countCharacters(row.source_path), 0);
+        if (totalChars > MAX_PROPOSAL_BATCH_CHARS) {
+            return errorResult(`propose_project_context: this batch is ${totalChars.toLocaleString('en-US')} characters, over the ` +
+                `limit of ${MAX_PROPOSAL_BATCH_CHARS.toLocaleString('en-US')}. Nothing was written, and nothing was ` +
+                'truncated. Send the batch in smaller parts, or drop the documents that are too long to be ' +
+                'standing context.');
+        }
+        // A RE-SCAN REPLACES: this user's pending rows for this (project, scanned
+        // codebase) go first. RLS scopes the delete to the user; the two eq filters
+        // scope it to this scan's subject, so another codebase's pending proposals —
+        // and another user's — are untouched. `.select('id')` makes the replaced
+        // COUNT knowable, which is what the result reports instead of leaving the
+        // agent to guess whether its earlier scan is still standing.
+        const replaced = (await must(client
+            .from('cliv2_context_proposals')
+            .delete()
+            .eq('project_id', project.id)
+            .eq('scanned_codebase_id', scanned.id)
+            .select('id'))) ?? [];
+        // Nothing to insert on an empty scan — the delete above WAS the whole call.
+        if (rows.length)
+            await must(client.from('cliv2_context_proposals').insert(rows));
+        const projectScoped = rows.filter((row) => row.codebase_id === null).length;
+        const codebaseScoped = rows.length - projectScoped;
+        const noun = rows.length === 1 ? 'proposal' : 'proposals';
+        const sentences = [];
+        if (rows.length === 0) {
+            sentences.push(`Nothing was found: this scan of "${scanned.name}" turned up no standing context to propose for ` +
+                `"${project.name}", so nothing is waiting for review.`);
+            sentences.push(replaced.length
+                ? `It cleared ${replaced.length} proposal${replaced.length === 1 ? '' : 's'} from an earlier scan ` +
+                    `of "${scanned.name}", which no longer stand — a scan reports what the repo holds now.`
+                : 'There was nothing pending to clear.');
+            sentences.push('No document was touched: accepted context documents are not proposals and are unaffected. Tell ' +
+                'the user the repo holds no standing context worth importing.');
+        }
+        else {
+            sentences.push(`${rows.length} context document ${noun} ${rows.length === 1 ? 'is' : 'are'} now waiting for review ` +
+                `in the web app, under ${REVIEW_LOCATION} for "${project.name}".`);
+            if (replaced.length) {
+                sentences.push(`This re-scan replaced ${replaced.length} proposal${replaced.length === 1 ? '' : 's'} from an ` +
+                    `earlier scan of "${scanned.name}" — a scan reports what the repo holds now.`);
+            }
+            sentences.push('Nothing has been created yet: the user accepts or rejects each one there, and only an accept ' +
+                'makes it a context document. Tell them where to look.');
+        }
+        return textResult({
+            project: project.name,
+            scanned_codebase: scanned.name,
+            proposed: rows.length,
+            project_scoped: projectScoped,
+            codebase_scoped: codebaseScoped,
+            replaced: replaced.length,
+            review_in: REVIEW_LOCATION,
+            instruction: sentences.join(' '),
+        });
+    }
+    catch (err) {
+        return errorResult(`propose_project_context failed: ${errorMessage(err)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Client context intake (feature 24c, Slice 1) — `get_client_context` /
+// `propose_client_context`.
+//
+// THE SAME SPLIT AS 13a, ON A CLIENT INSTEAD OF A REPO. The agent READS the
+// client's existing context (product tables — allowed, AGENTS.md: v2 may
+// select shared product data through the signed-in user's RLS) and WRITES
+// only `cliv2_*` state: a pending proposal queue
+// (`cliv2_client_context_proposals`) reviewed on the client page, and a
+// processed flag per source (`cliv2_client_source_reads`). Nothing here
+// writes a product table — `client_context_records` rows are created only by
+// the web's accept.
+//
+// ANCHORING: `client_id`, not a task or session. A client is not reachable
+// through a task (Slice 1 deliberately predates any project attachment —
+// ux.md: "a client can have context before any project is attached to it"),
+// so the copyable instruction on the client page hands the agent the client
+// id directly, and neither tool requires an open work session — the same
+// reasoning as get/propose_project_context with task_id: the session exists
+// to attribute work to a task, and this work is attributed to a client, which
+// the session cannot supply. cli-v2 has no agent_run; there is nothing else
+// to anchor to.
+//
+// THE CITATION NON-NEGOTIABLE IS ENFORCED AT THE WRITE. Every proposal's
+// `quote` must be a VERBATIM substring of its source's stored body
+// (indexOf !== -1) — the Step −1 ruling made a citation "the quoted span
+// stored verbatim plus the source id", and the web finds the span with
+// indexOf to highlight it, so a quote this check would refuse is a citation
+// that can never resolve. Refused at propose time, where the agent can
+// re-quote — 13a's fail-at-propose argument, applied to the field that IS
+// this feature.
+//
+// VALIDATION IS ALL-BEFORE-ANY-WRITE, AND REFUSAL IS WHOLE-BATCH. One run
+// hands over one batch (one result per source it read); a partially-applied
+// batch would flag sources processed whose proposals were refused. So every
+// result and every proposal is validated first, the refusal names the
+// offending source and proposal, and nothing is written on any refusal.
+//
+// A RE-RUN REPLACES ITS OWN PENDING SET AND RE-FLAGS, NEVER DUPLICATES: per
+// source, this user's pending proposals are deleted before the fresh ones go
+// in, and the read row is deleted and re-inserted — the flag reports the
+// LATEST run. `found_nothing: true` is a real result (a thank-you note holds
+// no durable context) recorded as a fact, because the mere absence of
+// proposals also describes a source nobody read.
+// ---------------------------------------------------------------------------
+/** The four kinds `client_context_records.kind` admits, verbatim from the
+ *  migration's check constraint (20260730080000) and the approved mock. */
+/** 31's citation convention (Step −1 ruling 1, shared with 24c Slice 3): ONE
+ *  fixed markdown line, no schema — a citation is prose the web app can parse,
+ *  never a column. Taught VERBATIM in every tool description that writes
+ *  grounded prose (create_product_idea, create_artifact), because 31 Slice 1's
+ *  gate proved prose conventions in live tool output are schema too: a
+ *  convention that lives in only one description is a convention half the
+ *  flows never see. */
+const CITATION_LINE_TEACHING = 'Cite with the fixed citation line — on its own line, directly under the claim it grounds: ' +
+    '> "<verbatim quote>" — <source kind> <id> ' +
+    '(use `client source <id>` for raw client material, `client context record <id>` for accepted ' +
+    'records, `project document <id>` for project context, and a repo-relative file path for code). ' +
+    'The quote is VERBATIM — character for character, never paraphrased, trimmed or normalized — ' +
+    'and it must be a span of the THING YOU CITE: when citing a client source, quote the raw ' +
+    "material itself, never a context record's restatement of it (a record's wording presented as " +
+    "the client's words is the misattribution this convention exists to prevent); when citing a " +
+    "record, quote the record's own quote field.";
+/** Characters of an idea's body shown in get_client_context's listing — a
+ *  snippet to judge overlap by, not the human's whole thinking (the 22b
+ *  listing withholds bodies entirely; intake gets a snippet because judging
+ *  update-over-create needs more than a title). */
+const IDEA_BODY_SNIPPET_CHARS = 240;
+const CLIENT_RECORD_KINDS = ['fact', 'constraint', 'preference', 'decision'];
+/** `client_context_records.title` is `length(title) <= 100`, the house cap.
+ *  Refused HERE so the agent learns at propose time, rather than the user
+ *  discovering at accept time that a proposal can never become a record. */
+const MAX_CLIENT_RECORD_TITLE_CHARS = 100;
+/** Where the user reviews what was proposed. The agent's job ends at
+ *  proposing, so the success result says this in prose it can relay. */
+const CLIENT_REVIEW_LOCATION = "the client's page in the web app";
+/**
+ * CLIENT RESOLUTION, shared by both tools. The id is UUID-shape-checked
+ * BEFORE the read (the resolveContextProject idiom) so `"c-1"` gets a clean
+ * tool error instead of a Postgres `invalid input syntax for type uuid`, and
+ * a miss — no such client, or one outside the caller's orgs, which RLS makes
+ * indistinguishable on purpose — is refused by id in the house shape.
+ */
+async function resolveClient(client, clientIdArg, tool) {
+    const clientId = typeof clientIdArg === 'string' ? clientIdArg.trim() : '';
+    if (!clientId) {
+        return {
+            ok: false,
+            error: errorResult(`${tool} requires client_id — the id of the client whose context this is, from the instruction that sent you here.`),
+        };
+    }
+    if (!UUID_RE.test(clientId)) {
+        return { ok: false, error: errorResult(`${tool}: not a valid client id: "${clientId}".`) };
+    }
+    const row = await must(client.from('clients').select('id, name').eq('id', clientId).maybeSingle());
+    if (!row)
+        return { ok: false, error: errorResult(`${tool}: no client found for id "${clientId}".`) };
+    return { ok: true, value: { id: row.id, name: row.name } };
+}
+/**
+ * List the clients the caller can see, with their attached projects — THE
+ * ENTRY POINT for a client-shaped ask ("build what <client name> asked for"):
+ * without it a thin ask dead-ends, because every other client tool requires a
+ * client_id and nothing resolved a NAME to one (found by the 2026-07-30
+ * live-take rehearsal — a real agent stalled asking the user for a uuid).
+ * READ-ONLY; RLS scopes rows to the caller's orgs.
+ */
+export async function listClientsHandler(client) {
+    try {
+        const clients = (await must(client.from('clients').select('id, name, website, archived_at').order('name'))) ?? [];
+        const live = clients.filter((c) => !c.archived_at);
+        const ids = live.map((c) => c.id);
+        const projects = ids.length
+            ? ((await must(client.from('projects').select('id, name, client_id').in('client_id', ids))) ?? [])
+            : [];
+        return textResult({
+            clients: live.map((c) => ({
+                id: c.id,
+                name: c.name,
+                website: c.website,
+                projects: projects
+                    .filter((p) => p.client_id === c.id)
+                    .map((p) => ({ id: p.id, name: p.name })),
+            })),
+            note: live.length === 0
+                ? 'No clients visible. Either this org has none, or agency mode is off.'
+                : 'Pass a client id to get_client_context to read what the client actually said before writing anything.',
+        });
+    }
+    catch (err) {
+        return errorResult(`list_clients failed: ${err.message}`);
+    }
+}
+/**
+ * Read a client's whole context surface: every source with its processed
+ * flag, every accepted record with its citation, and the calling user's
+ * pending proposal count. READ-ONLY, over product tables plus the two
+ * `cliv2_*` intake tables.
+ *
+ * THIS IS THE READ-BEFORE-WRITE ux.md NON-NEGOTIABLE 2 REQUIRES — "the agent
+ * therefore reads before it writes … every run. That read is not an
+ * optimization; it is the feature." An agent that proposes without calling
+ * this first is the duplicate farm Slice 4 exists to prevent.
+ *
+ * PROCESSED IS DERIVED FROM `cliv2_client_source_reads`, ACROSS ALL USERS:
+ * the SELECT policy is org-scoped precisely so a source one member's agent
+ * handled reads as handled to every teammate — processed when ANY read row
+ * exists. `found_nothing` is reported true only when every read row says so:
+ * one run that proposed something outranks another that found nothing.
+ */
+export async function getClientContextHandler(client, args) {
+    try {
+        const resolved = await resolveClient(client, args.client_id, 'get_client_context');
+        if (!resolved.ok)
+            return resolved.error;
+        const theClient = resolved.value;
+        const sources = (await must(client
+            .from('client_sources')
+            .select('id, kind, from_name, happened_at, body')
+            .eq('client_id', theClient.id)
+            .order('created_at', { ascending: true })
+            .order('id', { ascending: true }))) ?? [];
+        const reads = (await must(client
+            .from('cliv2_client_source_reads')
+            .select('source_id, found_nothing')
+            .eq('client_id', theClient.id))) ?? [];
+        const records = (await must(client
+            .from('client_context_records')
+            .select('id, kind, title, body, reason, quote, source_id')
+            .eq('client_id', theClient.id)
+            .order('created_at', { ascending: true })
+            .order('id', { ascending: true }))) ?? [];
+        // The CALLING user's pending set only — RLS owner-scopes the table, so the
+        // unqualified read is already "mine".
+        const pending = (await must(client.from('cliv2_client_context_proposals').select('id').eq('client_id', theClient.id))) ?? [];
+        // Slice 2 — THE READ-BEFORE-FLAG SURFACE. The client's work items (every
+        // live task in every project attached to this client, 24b's edge) and the
+        // EXISTING flags in every status, each with its (work_item_id, quote)
+        // identity — so a run can see what was already raised or dismissed and
+        // never re-derive it, instead of trying-and-failing against the dedup.
+        // Appended sections; everything above keeps its exact Slice 1 shape.
+        const clientProjects = (await must(client.from('projects').select('id, name').eq('client_id', theClient.id))) ?? [];
+        const projectIds = clientProjects.map((project) => project.id);
+        const workItems = projectIds.length
+            ? ((await must(client
+                .from('tasks')
+                .select('id, name, status, description, project_id')
+                .in('project_id', projectIds)
+                .is('archived_at', null)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true }))) ?? [])
+            : [];
+        const existingFlags = (await must(client
+            .from('cliv2_work_item_flags')
+            .select('id, work_item_id, source_id, quote, suggested_edit, status')
+            .eq('client_id', theClient.id)
+            .order('raised_at', { ascending: true })
+            .order('id', { ascending: true }))) ?? [];
+        // Slice 3 — THE READ-BEFORE-WRITE SURFACE FOR IDEAS (non-negotiable 2):
+        // the client's projects' existing Product Ideas, so an intake run can
+        // extend the idea that already covers a problem instead of minting a
+        // near-duplicate. A SNIPPET of the body, not the whole: enough to judge
+        // overlap; get_task reads one in full when a title alone cannot settle it.
+        const productIdeas = projectIds.length
+            ? ((await must(client
+                .from('tasks')
+                .select('id, project_id, name, description')
+                .eq('is_idea', true)
+                .in('project_id', projectIds)
+                .is('archived_at', null)
+                .order('created_at', { ascending: true })
+                .order('id', { ascending: true }))) ?? [])
+            : [];
+        const readsBySource = new Map();
+        for (const read of reads) {
+            const list = readsBySource.get(read.source_id);
+            if (list)
+                list.push(read);
+            else
+                readsBySource.set(read.source_id, [read]);
+        }
+        const shapedSources = sources.map((source) => {
+            const sourceReads = readsBySource.get(source.id) ?? [];
+            const processed = sourceReads.length > 0;
+            return {
+                id: source.id,
+                kind: source.kind,
+                from_name: source.from_name,
+                happened_at: source.happened_at,
+                processed,
+                // Only meaningful on a processed source; true only when EVERY run that
+                // read it found nothing — a run that proposed something outranks one
+                // that did not.
+                ...(processed ? { found_nothing: sourceReads.every((read) => read.found_nothing) } : {}),
+                body: source.body,
+            };
+        });
+        const unprocessed = shapedSources.filter((source) => !source.processed).length;
+        return textResult({
+            client: theClient.name,
+            sources: shapedSources,
+            // Shaped explicitly — the payload is a contract, not whatever the read
+            // happened to return.
+            records: records.map((record) => ({
+                id: record.id,
+                kind: record.kind,
+                title: record.title,
+                body: record.body,
+                reason: record.reason,
+                quote: record.quote,
+                source_id: record.source_id,
+            })),
+            pending_proposals: pending.length,
+            // Slice 3: the client's attached projects, by id — create_product_idea
+            // takes an explicit project_id (Q4 ruling: one project auto-resolves
+            // the choice, several means the agent chooses and says why), and this
+            // is where the legal choices come from.
+            projects: clientProjects.map((project) => ({ id: project.id, name: project.name })),
+            // Slice 3: the existing Product Ideas across those projects — read
+            // BEFORE writing any (update-over-create, non-negotiable 2).
+            product_ideas: productIdeas.map((idea) => {
+                const project = clientProjects.find((candidate) => candidate.id === idea.project_id);
+                const body = (idea.description ?? '').trim();
+                return {
+                    id: idea.id,
+                    title: idea.name,
+                    body_snippet: body.length > IDEA_BODY_SNIPPET_CHARS ? `${body.slice(0, IDEA_BODY_SNIPPET_CHARS)}…` : body,
+                    project_id: idea.project_id,
+                    project: project ? project.name : idea.project_id,
+                };
+            }),
+            // Slice 2 sections, appended after the Slice 1 shape (backward
+            // compatible: nothing above moved or changed).
+            work_items: workItems.map((item) => {
+                const project = clientProjects.find((candidate) => candidate.id === item.project_id);
+                return {
+                    id: item.id,
+                    name: item.name,
+                    status: item.status,
+                    description: item.description,
+                    project: project ? project.name : item.project_id,
+                };
+            }),
+            // Every existing flag, ALL statuses, with its (work_item_id, quote)
+            // identity: a flag here — open, dismissed OR resolved — must never be
+            // raised again. raise_work_item_flags skips duplicates, but honoring a
+            // dismissal starts with seeing it.
+            work_item_flags: existingFlags.map((flag) => ({
+                id: flag.id,
+                work_item_id: flag.work_item_id,
+                source_id: flag.source_id,
+                quote: flag.quote,
+                suggested_edit: flag.suggested_edit,
+                status: flag.status,
+            })),
+            note: (unprocessed > 0
+                ? `${unprocessed} source${unprocessed === 1 ? '' : 's'} ${unprocessed === 1 ? 'is' : 'are'} unprocessed. ` +
+                    'Read each one, then hand over ONE propose_client_context call covering all of them — every ' +
+                    "proposal's quote must be a VERBATIM substring of its source's body, and a source that holds " +
+                    'nothing durable is reported with found_nothing: true, which is a correct outcome. '
+                : 'Every source has been processed. Propose again only if you have re-read a source and your ' +
+                    'proposals changed — a re-run replaces your pending set for that source. ') +
+                'Where the material shows a product opportunity, read product_ideas here FIRST: updating beats ' +
+                'creating — extend the idea that already covers the problem (a cited artifact via ' +
+                'create_artifact) instead of minting a near-duplicate, and create a genuinely new one with ' +
+                "create_product_idea, passing this client_id and one of this client's project ids from " +
+                '`projects`.',
+        });
+    }
+    catch (err) {
+        return errorResult(`get_client_context failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Validate one proposed record into the row it will become, or refuse it by
+ * source, index AND title — an agent re-reading its own batch needs all three
+ * handles. The checks mirror `client_context_records`' constraints exactly
+ * (13a's argument: a proposal the records table would reject must fail HERE,
+ * where the agent can see it, not at accept time in the browser), plus the
+ * one check no table can make — the quote must be a verbatim substring of the
+ * source's stored body.
+ */
+function validateClientProposal(proposal, index, clientId, source) {
+    const at = `proposal ${index + 1} for source ${source.id}`;
+    const refuse = (message) => ({
+        ok: false,
+        error: errorResult(`propose_client_context: ${at} ${message} Nothing was written.`),
+    });
+    if (!proposal || typeof proposal !== 'object') {
+        return refuse('is not an object. Each proposal needs kind, title, body, reason and quote.');
+    }
+    const title = typeof proposal.title === 'string' ? proposal.title.trim() : '';
+    if (!title)
+        return refuse('has no title.');
+    if (countCharacters(title) > MAX_CLIENT_RECORD_TITLE_CHARS) {
+        return refuse(`has a ${countCharacters(title)}-character title; the limit is ${MAX_CLIENT_RECORD_TITLE_CHARS}. ` +
+            'Shorten it — a record title is a heading, not the record.');
+    }
+    if (!CLIENT_RECORD_KINDS.includes(proposal.kind)) {
+        return refuse(`("${title}") has kind "${String(proposal.kind)}", which is not a context record kind. ` +
+            `Use one of: ${CLIENT_RECORD_KINDS.join(', ')}.`);
+    }
+    const body = typeof proposal.body === 'string' ? proposal.body : '';
+    if (body.trim() === '') {
+        return refuse(`("${title}") has no body. State the durable fact, constraint, preference or decision.`);
+    }
+    const reason = typeof proposal.reason === 'string' ? proposal.reason.trim() : '';
+    if (!reason) {
+        return refuse(`("${title}") has no reason. Every proposal carries one line saying why this is durable client ` +
+            'context, so the user can judge the judgement and not just the text.');
+    }
+    const quote = typeof proposal.quote === 'string' ? proposal.quote : '';
+    if (quote.trim() === '') {
+        return refuse(`("${title}") has no quote. Every record cites its source: quote the span this came from, ` +
+            'VERBATIM from the material.');
+    }
+    // THE CITATION NON-NEGOTIABLE. The quote is stored verbatim and the web
+    // finds it with indexOf to highlight it in the source — so a quote that is
+    // not a verbatim substring is a citation that can never resolve, and it is
+    // refused where the agent can fix it.
+    if (source.body.indexOf(quote) === -1) {
+        return refuse(`("${title}") has a quote that is not a VERBATIM substring of that source's body. ` +
+            'Re-quote the span exactly as it appears in the material — character for character, ' +
+            'including line breaks and punctuation; do not paraphrase, trim or normalize it — and send ' +
+            'the batch again.');
+    }
+    return {
+        ok: true,
+        value: {
+            client_id: clientId,
+            source_id: source.id,
+            kind: proposal.kind,
+            title,
+            body,
+            reason,
+            quote,
+        },
+    };
+}
+/**
+ * Hand over one intake run's results: per source read, either the records it
+ * proposes or `found_nothing: true`. WRITES `cliv2_*` STATE ONLY — pending
+ * proposals the user accepts or rejects on the client page, and one read row
+ * per source flagging it processed. No product table is written here under
+ * any argument; only the web's accept creates a `client_context_records` row.
+ *
+ * EVERYTHING IS VALIDATED BEFORE ANYTHING IS WRITTEN, and any refusal names
+ * the offending source and proposal — a partially-applied batch would flag
+ * sources processed whose proposals were refused.
+ *
+ * THE WRITES ARE BATCHED, NOT ATOMIC. Four statements (replace-delete +
+ * insert, per table), no transaction — PostgREST has none to offer, the same
+ * accepted trade as propose_project_context: every delete is scoped to this
+ * user's rows for exactly these sources, so a failure between statements
+ * leaves nothing corrupted, and the recovery is to run the batch again —
+ * which is precisely what a re-run does (replace and re-flag).
+ */
+export async function proposeClientContextHandler(client, args) {
+    try {
+        const resolved = await resolveClient(client, args.client_id, 'propose_client_context');
+        if (!resolved.ok)
+            return resolved.error;
+        const theClient = resolved.value;
+        // One result per source read. An EMPTY batch is refused, unlike
+        // propose_project_context's empty scan: there, `[]` is the only way to
+        // say "nothing found"; here that meaning lives on each source as
+        // `found_nothing: true`, so an empty `results` says nothing at all.
+        const results = args.results;
+        if (!Array.isArray(results) || results.length === 0) {
+            return errorResult('propose_client_context: `results` must be a non-empty array — one entry per source you read. ' +
+                'A source that holds nothing durable is a real result: report it with `found_nothing: true` ' +
+                'rather than leaving it out, so it is flagged processed.');
+        }
+        // Every source_id is shape-checked and de-duplicated BEFORE the ownership
+        // read. Two results for one source would make the replace-then-insert
+        // last-wins by array order, silently — refused instead.
+        const seen = new Set();
+        for (const [index, result] of results.entries()) {
+            const at = `result ${index + 1}`;
+            if (!result || typeof result !== 'object') {
+                return errorResult(`propose_client_context: ${at} is not an object. Each result needs source_id, and either ` +
+                    'proposals or found_nothing: true. Nothing was written.');
+            }
+            const sourceId = typeof result.source_id === 'string' ? result.source_id.trim() : '';
+            if (!sourceId || !UUID_RE.test(sourceId)) {
+                return errorResult(`propose_client_context: ${at} has an invalid source_id: "${String(result.source_id)}". ` +
+                    'Use the source ids get_client_context returned. Nothing was written.');
+            }
+            if (seen.has(sourceId)) {
+                return errorResult(`propose_client_context: source ${sourceId} appears in more than one result. Send one result ` +
+                    'per source, holding everything you propose from it. Nothing was written.');
+            }
+            seen.add(sourceId);
+        }
+        const sourceIds = [...seen];
+        // Ownership: every named source must exist AND belong to THIS client. The
+        // read is scoped to the client, so a source from another client — even one
+        // the caller can see — comes back missing and is refused by id.
+        const ownedSources = (await must(client
+            .from('client_sources')
+            .select('id, body')
+            .eq('client_id', theClient.id)
+            .in('id', sourceIds))) ?? [];
+        const bodyBySource = new Map(ownedSources.map((source) => [source.id, source.body]));
+        for (const sourceId of sourceIds) {
+            if (!bodyBySource.has(sourceId)) {
+                return errorResult(`propose_client_context: source ${sourceId} does not exist on client "${theClient.name}". ` +
+                    'Propose only from the sources get_client_context returned for this client. Nothing was written.');
+            }
+        }
+        // Slice 3's dedupe assist (the Slice 4 roadmap line, folded in): the
+        // ACCEPTED records citing this run's sources, keyed by (source_id, quote).
+        // A proposal that re-quotes a span an accepted record already cites is the
+        // duplicate farm arriving one accept at a time — refused whole-batch (the
+        // house style; the flag tools' skip semantics don't apply because a
+        // pending proposal, unlike a flag, is cheap to resend corrected).
+        const acceptedRecords = (await must(client
+            .from('client_context_records')
+            .select('id, title, source_id, quote')
+            .eq('client_id', theClient.id)
+            .in('source_id', sourceIds))) ?? [];
+        const acceptedByCitation = new Map(acceptedRecords.map((record) => [`${record.source_id}\u0000${record.quote}`, record]));
+        // Per result: EXACTLY ONE of found_nothing or proposals, then every
+        // proposal validated — all of it before any write.
+        const rows = [];
+        const readRows = [];
+        // 13a's batch caps, ported (gate A, 2026-07-30): without them one propose
+        // call could insert unbounded rows/bytes into the pending queue, and the
+        // review surface renders every one as a card. Counted across the whole
+        // batch, checked before any write.
+        let totalProposals = 0;
+        let totalChars = 0;
+        for (const result of results) {
+            const sourceId = result.source_id.trim();
+            const proposals = result.proposals;
+            const foundNothing = result.found_nothing === true;
+            if (foundNothing && Array.isArray(proposals) && proposals.length > 0) {
+                return errorResult(`propose_client_context: the result for source ${sourceId} says found_nothing but carries ` +
+                    `${proposals.length} proposal${proposals.length === 1 ? '' : 's'}. A run either found nothing ` +
+                    'durable in a source or proposes from it — never both. Nothing was written.');
+            }
+            if (!foundNothing && (!Array.isArray(proposals) || proposals.length === 0)) {
+                return errorResult(`propose_client_context: the result for source ${sourceId} has no proposals and does not say ` +
+                    'found_nothing: true. Send the records you propose from it, or state found_nothing: true — ' +
+                    'finding nothing durable is a correct outcome, but it has to be stated on purpose. ' +
+                    'Nothing was written.');
+            }
+            if (!foundNothing) {
+                const body = bodyBySource.get(sourceId);
+                for (const [index, proposal] of proposals.entries()) {
+                    const validated = validateClientProposal(proposal, index, theClient.id, {
+                        id: sourceId,
+                        body,
+                    });
+                    if (!validated.ok)
+                        return validated.error;
+                    const accepted = acceptedByCitation.get(`${sourceId}\u0000${validated.value.quote}`);
+                    if (accepted) {
+                        return errorResult(`propose_client_context: proposal ${index + 1} for source ${sourceId} ` +
+                            `("${validated.value.title}") re-proposes a span that is already an ACCEPTED context ` +
+                            `record — "${accepted.title}" (${accepted.id}) carries this exact (source, quote) ` +
+                            'citation. Updating beats creating: drop it and send the batch again proposing only ' +
+                            'what is NEW; if the material genuinely adds to that record, propose the addition ' +
+                            'under its own quote. Nothing was written.');
+                    }
+                    totalProposals += 1;
+                    totalChars += validated.value.title.length + validated.value.body.length +
+                        validated.value.reason.length + validated.value.quote.length;
+                    // Fail fast (re-review): the refusal fires the moment a cap is
+                    // crossed, not after fully validating an unbounded batch.
+                    if (totalProposals > MAX_PROPOSALS || totalChars > MAX_PROPOSAL_BATCH_CHARS)
+                        break;
+                    rows.push(validated.value);
+                }
+            }
+            readRows.push({ client_id: theClient.id, source_id: sourceId, found_nothing: foundNothing });
+        }
+        if (totalProposals > MAX_PROPOSALS) {
+            return errorResult(`propose_client_context: ${totalProposals} proposed records is more than the limit of ` +
+                `${MAX_PROPOSALS}. Propose only what is durable — the user reviews every one by hand. ` +
+                'Nothing was written.');
+        }
+        if (totalChars > MAX_PROPOSAL_BATCH_CHARS) {
+            return errorResult(`propose_client_context: the batch is ${totalChars.toLocaleString('en-US')} characters, over the ` +
+                `limit of ${MAX_PROPOSAL_BATCH_CHARS.toLocaleString('en-US')}. Nothing was written. Propose ` +
+                'tighter records — the source stays readable in full; a record distills it.');
+        }
+        // A RE-RUN REPLACES: this user's pending proposals for these sources go
+        // first. RLS owner-scopes the delete to the caller; the filters scope it
+        // to this run's sources, so another source's pending set — and another
+        // user's — is untouched. `.select('id')` makes the replaced count
+        // knowable, which the result reports.
+        const replaced = (await must(client
+            .from('cliv2_client_context_proposals')
+            .delete()
+            .eq('client_id', theClient.id)
+            .in('source_id', sourceIds)
+            .select('id'))) ?? [];
+        if (rows.length)
+            await must(client.from('cliv2_client_context_proposals').insert(rows));
+        // …AND RE-FLAGS: delete-then-insert rather than upsert, so the read row
+        // always reports the LATEST run (fresh read_at, fresh found_nothing) and
+        // `unique (user_id, source_id)` is never contended.
+        await must(client
+            .from('cliv2_client_source_reads')
+            .delete()
+            .eq('client_id', theClient.id)
+            .in('source_id', sourceIds));
+        await must(client.from('cliv2_client_source_reads').insert(readRows));
+        const foundNothingCount = readRows.filter((read) => read.found_nothing).length;
+        const noun = rows.length === 1 ? 'record' : 'records';
+        const sentences = [];
+        if (rows.length === 0) {
+            sentences.push(`Nothing durable was found in the ${sourceIds.length} source${sourceIds.length === 1 ? '' : 's'} ` +
+                `this run read for "${theClient.name}" — a correct outcome, recorded as one; the sources are ` +
+                'now flagged processed.');
+        }
+        else {
+            sentences.push(`${rows.length} proposed context ${noun} ${rows.length === 1 ? 'is' : 'are'} now waiting for ` +
+                `review in ${CLIENT_REVIEW_LOCATION}, on "${theClient.name}".`);
+            if (foundNothingCount > 0) {
+                sentences.push(`${foundNothingCount} source${foundNothingCount === 1 ? '' : 's'} held nothing durable — ` +
+                    'a correct outcome, recorded as one.');
+            }
+        }
+        if (replaced.length) {
+            sentences.push(`This run replaced ${replaced.length} pending proposal${replaced.length === 1 ? '' : 's'} of ` +
+                'yours for these sources — a run reports what the material holds now.');
+        }
+        sentences.push('No context record has been created: the user accepts or rejects each proposal there, and only ' +
+            'an accept makes one a record. Tell them where to look.');
+        return textResult({
+            client: theClient.name,
+            sources_processed: sourceIds.length,
+            proposed: rows.length,
+            found_nothing_sources: foundNothingCount,
+            replaced: replaced.length,
+            review_in: CLIENT_REVIEW_LOCATION,
+            instruction: sentences.join(' '),
+        });
+    }
+    catch (err) {
+        return errorResult(`propose_client_context failed: ${errorMessage(err)}`);
+    }
+}
+/** A flag's identity — the "dismissed stays dismissed" key. `` cannot
+ *  appear in a UUID, so the join is collision-free. */
+const flagIdentity = (workItemId, quote) => `${workItemId}${quote}`;
+/**
+ * WHO FLAGGED, resolved the way the codebase already names agents: the
+ * machine's effective name (web-owned `display_name` when set, else the
+ * heartbeat's `machine_name` — the 20260721130000 rule) from the caller's own
+ * `cliv2_agents` presence row, plus the connection's provider from the MCP
+ * `initialize` clientInfo (`attributionFromClientName`) — composing e.g.
+ * "lane's-macbook · claude", the approved mock's exact shape. Best-effort and
+ * HONEST in degradation: a missing presence row or unknown provider narrows
+ * the string rather than inventing one, and the floor is 'an agent' — never
+ * a fabricated machine or provider.
+ */
+export async function resolveFlagAgentName(client, machineId, provider) {
+    let machine = null;
+    if (machineId) {
+        try {
+            const row = await must(client
+                .from('cliv2_agents')
+                .select('machine_name, display_name')
+                .eq('machine_id', machineId)
+                .maybeSingle());
+            const display = typeof row?.display_name === 'string' ? row.display_name.trim() : '';
+            machine = display || row?.machine_name || null;
+        }
+        catch {
+            machine = null; // attribution must never fail the raise
+        }
+    }
+    if (machine && provider)
+        return `${machine} · ${provider}`;
+    return machine ?? provider ?? 'an agent';
+}
+/**
+ * Raise one intake run's flags on a client's work items. WRITES `cliv2_*`
+ * STATE ONLY — a flag changes nothing on the item; only a human (or the
+ * agent a human hands the copyable command to) acts on it.
+ *
+ * ALL VALIDATION BEFORE ANY WRITE, whole-batch refusal — EXCEPT the dedup:
+ * a flag whose (work_item_id, quote) already exists — open, dismissed OR
+ * resolved, whoever raised it — is SKIPPED and reported, because a re-ingest
+ * re-deriving a known contradiction is the feature working, not an error.
+ * Raising zero after skips is likewise a success.
+ *
+ * `agentName` is resolved by the caller (registration wires
+ * resolveFlagAgentName over this connection's machine + clientInfo) so the
+ * handler stays a pure (client, args) function the tests can drive.
+ */
+export async function raiseWorkItemFlagsHandler(client, args, agentName) {
+    try {
+        const resolved = await resolveClient(client, args.client_id, 'raise_work_item_flags');
+        if (!resolved.ok)
+            return resolved.error;
+        const theClient = resolved.value;
+        const flags = args.flags;
+        if (!Array.isArray(flags) || flags.length === 0) {
+            return errorResult('raise_work_item_flags: `flags` must be a non-empty array — one entry per contradiction you ' +
+                'found. A run that flags nothing simply does not call this tool: flagging nothing is a ' +
+                'correct outcome, not something to report here.');
+        }
+        // Shape + caps, before any read. The 13a caps are REUSED on purpose (see
+        // the section header): same reviewed-by-hand queue shape, same limits.
+        if (flags.length > MAX_PROPOSALS) {
+            return errorResult(`raise_work_item_flags: ${flags.length} flags is more than the limit of ${MAX_PROPOSALS}. ` +
+                'Flag only what the material actually contradicts — a human reads every one. Nothing was written.');
+        }
+        const validated = [];
+        let totalChars = 0;
+        for (const [index, flag] of flags.entries()) {
+            const at = `flag ${index + 1}`;
+            if (!flag || typeof flag !== 'object') {
+                return errorResult(`raise_work_item_flags: ${at} is not an object. Each flag needs work_item_id, source_id, ` +
+                    'quote and suggested_edit. Nothing was written.');
+            }
+            const workItemId = typeof flag.work_item_id === 'string' ? flag.work_item_id.trim() : '';
+            if (!workItemId || !UUID_RE.test(workItemId)) {
+                return errorResult(`raise_work_item_flags: ${at} has an invalid work_item_id: "${String(flag.work_item_id)}". ` +
+                    'Use the work item ids get_client_context returned. Nothing was written.');
+            }
+            const sourceId = typeof flag.source_id === 'string' ? flag.source_id.trim() : '';
+            if (!sourceId || !UUID_RE.test(sourceId)) {
+                return errorResult(`raise_work_item_flags: ${at} has an invalid source_id: "${String(flag.source_id)}". ` +
+                    'Use the source ids get_client_context returned. Nothing was written.');
+            }
+            const suggestedEdit = typeof flag.suggested_edit === 'string' ? flag.suggested_edit.trim() : '';
+            if (!suggestedEdit) {
+                return errorResult(`raise_work_item_flags: ${at} has no suggested_edit. State plainly what should change on the ` +
+                    'work item and why — it is guidance a human reads, not a patch. Nothing was written.');
+            }
+            const quote = typeof flag.quote === 'string' ? flag.quote : '';
+            if (quote.trim() === '') {
+                return errorResult(`raise_work_item_flags: ${at} has no quote. Every flag cites the client's own words: quote ` +
+                    'the span that contradicts the item, VERBATIM from the material. Nothing was written.');
+            }
+            totalChars += suggestedEdit.length + quote.length;
+            if (totalChars > MAX_PROPOSAL_BATCH_CHARS) {
+                return errorResult(`raise_work_item_flags: the batch is over the limit of ` +
+                    `${MAX_PROPOSAL_BATCH_CHARS.toLocaleString('en-US')} characters. Nothing was written. ` +
+                    'Tighten the suggested edits — the source stays readable in full; a flag distills it.');
+            }
+            validated.push({ work_item_id: workItemId, source_id: sourceId, quote, suggested_edit: suggestedEdit });
+        }
+        // OWNERSHIP, scoped in the queries, not filtered in JS. A work item must
+        // belong to one of THIS client's projects (24b's projects.client_id edge);
+        // a source must belong to THIS client. Either miss is refused by id —
+        // RLS makes "foreign" and "nonexistent" indistinguishable on purpose.
+        const workItemIds = [...new Set(validated.map((flag) => flag.work_item_id))];
+        const sourceIds = [...new Set(validated.map((flag) => flag.source_id))];
+        const clientProjects = (await must(client.from('projects').select('id').eq('client_id', theClient.id))) ?? [];
+        const projectIds = clientProjects.map((project) => project.id);
+        // LIVE items only: an archived work item is outside every agent flow
+        // (the resolve handler's rule), so it is refused by id exactly like a
+        // foreign one — RLS-style, "archived" and "not yours" are
+        // indistinguishable on purpose.
+        const ownedItems = projectIds.length
+            ? ((await must(client
+                .from('tasks')
+                .select('id')
+                .in('project_id', projectIds)
+                .in('id', workItemIds)
+                .is('archived_at', null))) ?? [])
+            : [];
+        const ownedItemIds = new Set(ownedItems.map((item) => item.id));
+        for (const workItemId of workItemIds) {
+            if (!ownedItemIds.has(workItemId)) {
+                return errorResult(`raise_work_item_flags: work item ${workItemId} does not belong to a project of client ` +
+                    `"${theClient.name}". Flag only the work items get_client_context returned for this client. ` +
+                    'Nothing was written.');
+            }
+        }
+        const ownedSources = (await must(client.from('client_sources').select('id, body').eq('client_id', theClient.id).in('id', sourceIds))) ?? [];
+        const bodyBySource = new Map(ownedSources.map((source) => [source.id, source.body]));
+        for (const sourceId of sourceIds) {
+            if (!bodyBySource.has(sourceId)) {
+                return errorResult(`raise_work_item_flags: source ${sourceId} does not exist on client "${theClient.name}". ` +
+                    'Cite only the sources get_client_context returned for this client. Nothing was written.');
+            }
+        }
+        // THE CITATION NON-NEGOTIABLE, same check as propose_client_context: the
+        // quote must be a VERBATIM substring of its source's stored body, or the
+        // justification is a citation that can never resolve.
+        for (const [index, flag] of validated.entries()) {
+            if (bodyBySource.get(flag.source_id).indexOf(flag.quote) === -1) {
+                return errorResult(`raise_work_item_flags: flag ${index + 1} has a quote that is not a VERBATIM substring of ` +
+                    "its source's body. Re-quote the span exactly as it appears in the material — character " +
+                    'for character, including line breaks and punctuation; do not paraphrase, trim or ' +
+                    'normalize it — and send the batch again. Nothing was written.');
+            }
+        }
+        // THE DEDUP PRE-READ — the "dismissed stays dismissed" read. Existing
+        // flags on these work items, ANY status and any user's (the SELECT policy
+        // is org-scoped so a teammate's dismissal binds this run too). A flag
+        // whose (work_item_id, quote) identity already exists is SKIPPED, never
+        // re-raised; the DB's unique index backstops the race this read cannot
+        // see. Within-batch duplicates collapse through the same set.
+        const existing = (await must(client.from('cliv2_work_item_flags').select('work_item_id, quote').in('work_item_id', workItemIds))) ?? [];
+        const known = new Set(existing.map((flag) => flagIdentity(flag.work_item_id, flag.quote)));
+        const rows = [];
+        let skipped = 0;
+        for (const flag of validated) {
+            const identity = flagIdentity(flag.work_item_id, flag.quote);
+            if (known.has(identity)) {
+                skipped += 1;
+                continue;
+            }
+            known.add(identity);
+            rows.push({
+                client_id: theClient.id,
+                work_item_id: flag.work_item_id,
+                source_id: flag.source_id,
+                suggested_edit: flag.suggested_edit,
+                quote: flag.quote,
+                agent_name: agentName,
+            });
+        }
+        // THE INSERT, WITH THE RACE THE PRE-READ CANNOT SEE HANDLED IN KIND: a
+        // concurrent run can commit an identical flag between the dedup read and
+        // this insert, and the identity index then refuses the whole batch with a
+        // unique violation (23505). That is the dedup guarantee FIRING, not a
+        // failure — so re-run the pre-read once, drop the rows that now exist,
+        // and retry with the survivors (all-duplicates degrades to the same
+        // skip-success as the pre-read path). The constraint's raw words never
+        // reach the agent: every outcome here is reported in the tool's own.
+        let toInsert = rows;
+        let skippedTotal = skipped;
+        if (toInsert.length) {
+            const { error: insertError } = await client.from('cliv2_work_item_flags').insert(toInsert);
+            if (insertError) {
+                if (insertError.code !== '23505')
+                    throw new Error(insertError.message);
+                const raced = (await must(client
+                    .from('cliv2_work_item_flags')
+                    .select('work_item_id, quote')
+                    .in('work_item_id', workItemIds))) ?? [];
+                const racedKnown = new Set(raced.map((flag) => flagIdentity(flag.work_item_id, flag.quote)));
+                const survivors = toInsert.filter((row) => !racedKnown.has(flagIdentity(row.work_item_id, row.quote)));
+                skippedTotal += toInsert.length - survivors.length;
+                toInsert = survivors;
+                if (toInsert.length) {
+                    const { error: retryError } = await client.from('cliv2_work_item_flags').insert(toInsert);
+                    if (retryError) {
+                        if (retryError.code !== '23505')
+                            throw new Error(retryError.message);
+                        // Raced twice: stop cleanly rather than loop — and still in the
+                        // tool's words, never the constraint's.
+                        return errorResult('raise_work_item_flags: another run is raising overlapping flags on these work items ' +
+                            'right now. Nothing further was written — call get_client_context to see which flags ' +
+                            'now exist before raising again.');
+                    }
+                }
+            }
+        }
+        const sentences = [];
+        if (toInsert.length === 0) {
+            sentences.push(`Every flag in this batch was already raised on its work item — ${skippedTotal} skipped, none ` +
+                'written. That is the system working: a flag that was dismissed stays dismissed, and a ' +
+                'later ingest of overlapping material never raises it again.');
+        }
+        else {
+            sentences.push(`${toInsert.length} flag${toInsert.length === 1 ? '' : 's'} raised on work items of "${theClient.name}". ` +
+                'The flags change NOTHING: a human reads each one where the work item lives and edits by ' +
+                'hand, hands the item to their own agent, or dismisses it.');
+            if (skippedTotal > 0) {
+                sentences.push(`${skippedTotal} ${skippedTotal === 1 ? 'was' : 'were'} skipped — already raised or dismissed; ` +
+                    'a dismissal is permanent.');
+            }
+        }
+        return textResult({
+            client: theClient.name,
+            raised: toInsert.length,
+            skipped: skippedTotal,
+            instruction: sentences.join(' '),
+        });
+    }
+    catch (err) {
+        return errorResult(`raise_work_item_flags failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Resolve every OPEN flag on one work item — the last step of the copyable
+ * "apply the flags on <id> … and mark the flags resolved" command, invoked by
+ * the HUMAN'S agent after it made the edits the human told it to make.
+ * Dismissed flags are untouched (a dismissal is the human's judgement, not
+ * this run's), and 0 open flags is a success — the command may be pasted
+ * twice, and "nothing to resolve" is the correct second answer.
+ */
+export async function resolveWorkItemFlagsHandler(client, args) {
+    try {
+        const workItemId = typeof args.work_item_id === 'string' ? args.work_item_id.trim() : '';
+        if (!workItemId) {
+            return errorResult('resolve_work_item_flags requires work_item_id — the id of the work item whose flags you were ' +
+                'told to apply.');
+        }
+        if (!UUID_RE.test(workItemId)) {
+            return errorResult(`resolve_work_item_flags: not a valid work item id: "${workItemId}".`);
+        }
+        // The item must resolve under the caller's RLS. DELIBERATELY NO archived
+        // filter (re-review, 2026-07-30): only RAISE refuses archived items.
+        // Resolving is closing bookkeeping on past work — an item archived while
+        // its flags were open must still be resolvable, or the copyable
+        // apply-flags command dead-ends on it forever.
+        const task = await must(client.from('tasks').select('id, name').eq('id', workItemId).maybeSingle());
+        if (!task) {
+            return errorResult(`resolve_work_item_flags: no work item found for id "${workItemId}".`);
+        }
+        // Flip ONLY the open flags; the status filter (not just the trigger)
+        // keeps dismissed/resolved rows out of the statement entirely.
+        const resolvedFlags = (await must(client
+            .from('cliv2_work_item_flags')
+            .update({ status: 'resolved', resolved_at: new Date().toISOString() })
+            .eq('work_item_id', workItemId)
+            .eq('status', 'open')
+            .select('id'))) ?? [];
+        if (resolvedFlags.length === 0) {
+            return textResult({
+                work_item: task.name,
+                resolved: 0,
+                instruction: `"${task.name}" has no open flags — nothing to resolve. Already-dismissed and ` +
+                    'already-resolved flags are terminal and stay as they are.',
+            });
+        }
+        return textResult({
+            work_item: task.name,
+            resolved: resolvedFlags.length,
+            instruction: `${resolvedFlags.length} flag${resolvedFlags.length === 1 ? '' : 's'} on "${task.name}" ` +
+                'marked resolved. Resolve only after the edits are actually made — the flag section on the ' +
+                'item now reads as handled.',
+        });
+    }
+    catch (err) {
+        return errorResult(`resolve_work_item_flags failed: ${errorMessage(err)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Project context (feature 13a, Phase 3b) — the `begin_work` MANIFEST.
+//
+// Phase 3 shipped a read tool whose only discovery route is its own description
+// in `tools/list`, which is exactly how `list_credentials` works and exactly why
+// nobody calls it. `begin_work` is the one per-run handshake there is, so it now
+// carries TITLES AND SIZES — never content — plus one `instruction` line naming
+// the literal next call. The content stays behind `get_project_context`, so a
+// 40KB doc set never lands in a session that did not need it.
+//
+// THE MANIFEST MAY NEVER FAIL begin_work. Opening a work session is the
+// load-bearing operation; this is an extra. That is enforced in TWO places, on
+// purpose: `projectContextManifest` is the only entry point and its whole body
+// is inside one try/catch that cannot itself throw (it never touches
+// `.message` on a value it has not proved is an `Error`), AND the `begin_work`
+// call site wraps it in a try of its own that falls back to the bare session.
+// The inner guard is the contract; the outer one means the contract holding is
+// not a precondition of `begin_work` working.
+//
+// ABSENT, NOT EMPTY. No documents means no `project_context` key at all — an
+// empty array is a shape an agent has to interpret.
+//
+// AND THE AGENT IS ALWAYS TOLD WHAT IT DID NOT GET. Every cap here is paired
+// with a machine-readable `omitted` object, not with a hedging word in the
+// prose — the same invariant Phase 3's budget was corrected into.
+// ---------------------------------------------------------------------------
+/** Documents LISTED per scope. A manifest is a POINTER, not an index: it exists
+ *  to make the documents' existence impossible to miss, and `get_project_context`
+ *  is one call away for the rest. 12 keeps the whole `project_context` object in
+ *  the low hundreds of bytes per scope on realistic data — the approved sizing is
+ *  "~150 tokens for a typical project" — and anything past it is COUNTED in
+ *  `omitted` rather than hinted at. */
+const MANIFEST_DOCUMENT_ROWS = 12;
+/** Rows pulled PER SCOPE by the manifest's two document reads, before the
+ *  listing cap is applied in JS. Larger than what is listed because one scope's
+ *  window covers every codebase at once (see `buildProjectContextManifest`); the
+ *  rows are metadata-only (no `content`, see `content_chars`), so this is tens of
+ *  KB at the very worst, and the exact total comes from each query's `count`
+ *  rather than from the row count.
+ *
+ *  PER SCOPE, not project-wide. A single project-wide read ordered on
+ *  `codebase_id` first put the codebase scope entirely outside the window as soon
+ *  as the project scope held this many documents — so the manifest emitted no
+ *  codebase at all and then told the agent that the unqualified call "returns the
+ *  rest", a call that structurally cannot reach a codebase-scoped document. A
+ *  bounded slice of EACH scope makes that false negative impossible. */
+const MANIFEST_FETCH_ROWS = 200;
+/** The project's own codebases, read so a codebase-scoped document can be NAMED
+ *  (`get_project_context` takes a codebase, not a `codebase_id`).
+ *
+ *  Its own constant, not `MANIFEST_FETCH_ROWS`: this bounds a different table for
+ *  a different reason. Past it a real document becomes unnameable, so — like
+ *  every other cap in this block — the overflow is REPORTED, in
+ *  `omitted.unnamed_codebases`, rather than quietly turning documents into
+ *  ordinary omissions. */
+const MANIFEST_CODEBASE_ROWS = 200;
+/** Codebase references NAMED in `omitted.omitted_document_codebases` — the
+ *  codebases that hold documents the listing left out.
+ *
+ *  Counting omitted codebase-scoped documents without naming their codebases is
+ *  the same defect as naming a document no call can reach, one step removed:
+ *  `get_project_context` takes a codebase, so "each codebase's own need that
+ *  codebase passed as `codebase`" is only actionable if the agent is told WHICH.
+ *  Like every other cap in this block, the overflow past this is REPORTED — in
+ *  `omitted.further_document_codebases` — rather than truncated in silence. */
+const MANIFEST_OMITTED_CODEBASE_REFS = 12;
+/** Codebase targets read for one task. `cliv2_task_codebase_targets` is unique
+ *  on `(task_id, git_remote_url)` and nothing bounds how many a task may have,
+ *  so the read is capped; the overflow is reported in `omitted.codebases`
+ *  (an exact count, from the same query) rather than silently dropped. */
+const MANIFEST_TARGET_ROWS = 20;
+/** A hung read must not hold a session open. The manifest is abandoned — not
+ *  failed — past this, and `begin_work` answers with the session alone.
+ *
+ *  1.5s, not the 4s first built: `begin_work` is awaited on BOTH of its paths,
+ *  so this is a hold on the one handshake every session opens with. Something
+ *  optional does not get to delay the load-bearing operation for four seconds. */
+const MANIFEST_TIMEOUT_MS = 1_500;
+/** "a", "a and b", "a, b and c" — the transcript's phrasing for the type list. */
+const humanList = (items) => items.length <= 1
+    ? items.join('')
+    : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+/** A literal `get_project_context` call, rendered exactly as an agent should
+ *  type it. `codebase` is NOT decoration: `get_project_context` reads the
+ *  codebase scope ONLY when it is passed, so an instruction that names a
+ *  codebase-scoped document and then omits `codebase` sends the agent to a call
+ *  that answers "this project has no context documents". */
+const contextCall = (type, codebase) => {
+    const args = [
+        ...(type ? [`types: ['${type}']`] : []),
+        ...(codebase ? [`codebase: '${codebase}'`] : []),
+    ];
+    return `get_project_context({${args.length ? ` ${args.join(', ')} ` : ''}})`;
+};
+/**
+ * The one `instruction` line. It names a LITERAL call, with `types` already
+ * narrowed, which is the live v2 idiom (`present_wireframes` / `present_mocks`).
+ *
+ * WITH an `instructions` document it is the transcript's line. WITHOUT one it
+ * must NOT tell the agent to fetch a document that does not exist, so it narrows
+ * to a type this project actually has (the first document's — documents are in
+ * creation order, project scope first, so it is deterministic) and offers the
+ * unnarrowed call for the rest. Error/edge copy is the builder's call per Phase
+ * 3's Learned; this is that call, reported.
+ *
+ * `other` is dropped from the prose list ("the standing other for this work" is
+ * not a sentence); when it is the only type there is, the clause falls back to
+ * "standing context" rather than leaving the em-dash with nothing after it.
+ *
+ * EVERY NAMED CALL IS QUALIFIED FROM THE DOCUMENT IT NAMES, never from a single
+ * manifest-wide guess. The `instructions` line is qualified with the
+ * `instructions` document's own `codebase` (absent → the unqualified call, which
+ * is exactly right for a project-scoped one); the fallback line is qualified with
+ * the first document's. A qualifier drawn from anywhere else was the bug: it
+ * could name a codebase whose documents were never listed, sending every call to
+ * a different document than the manifest just showed.
+ *
+ * AND ONE CALL IS NEVER IMPLIED TO COVER MANY CODEBASES. `get_project_context`
+ * takes ONE codebase; when the listing spans more than one, the line says so
+ * plainly and points at each entry's own `codebase` field rather than pretending.
+ *
+ * The COUNT is the project's real total, never "at least N" — a hedging word is
+ * not a signal. When it exceeds what is listed, the `omitted` object carries the
+ * numbers and this line points at the call that returns the rest — SEPARATELY per
+ * scope, because the unqualified call returns project-scoped documents only and
+ * saying it "returns the rest" of a codebase's own is simply false.
+ *
+ * AND THE OMITTED CODEBASE-SCOPED ONES ARE NAMED, NOT JUST COUNTED. Telling an
+ * agent that N documents live on codebases it must pass as `codebase`, without
+ * ever saying which codebases those are, leaves it guessing — counted but
+ * unreachable, the same defect as named but unreachable. The names come from
+ * `omitted.omitted_document_codebases` and this line repeats exactly them, so the
+ * prose and the machine-readable field can never disagree.
+ */
+function manifestInstruction(input) {
+    const { projectName, documents, total, omittedProjectDocuments, omittedCodebaseDocuments, omittedDocumentCodebases, furtherDocumentCodebases, omittedCodebases, unnamedCodebases, } = input;
+    const singular = total === 1;
+    const they = singular ? 'it is' : 'they are';
+    const types = [...new Set(documents.map((document) => document.type))];
+    const named = types.filter((type) => type !== 'other');
+    const body = named.length
+        ? `${they} the standing ${humanList(named)} for this work, and ${they} not in the repo. `
+        : `${they} standing context for this work, and ${they} not in the repo. `;
+    const lead = `This project keeps ${total} context document${singular ? '' : 's'} in ${projectName} — ${body}`;
+    // The codebases actually REPRESENTED in the listing, in listing order.
+    const listedCodebases = [
+        ...new Set(documents.flatMap((document) => (document.codebase ? [document.codebase] : []))),
+    ];
+    // `documents` is project scope first, so a project-scoped `instructions`
+    // document wins over a codebase-scoped one — and its unqualified call is the
+    // call that actually returns it.
+    const instructionsDocument = documents.find((document) => document.type === 'instructions');
+    const first = documents[0];
+    // The unqualified call is only OFFERED when it would actually return
+    // something: it reads the project scope, so a listing with no project-scoped
+    // document in it must not point at a call that answers "no context documents".
+    const anyProjectScoped = documents.some((document) => document.scope === 'project');
+    const everything = !anyProjectScoped
+        ? ''
+        : listedCodebases.length
+            ? `, or ${contextCall(null, null)} for the project-scoped ones`
+            : `, or ${contextCall(null, null)} for all of them`;
+    const core = instructionsDocument
+        ? 'Read the instructions document before you change anything: ' +
+            `${contextCall('instructions', instructionsDocument.codebase ?? null)}. ` +
+            'Pull the others when the work touches them.'
+        : `There is no instructions document — read the ones the work touches, e.g. ` +
+            `${contextCall(first.type, first.codebase ?? null)}${everything}.`;
+    const scoping = listedCodebases.length === 0
+        ? ''
+        : listedCodebases.length === 1
+            ? ` The codebase-scoped documents above belong to ${listedCodebases[0]} — ` +
+                `${contextCall(null, listedCodebases[0])} reads them.`
+            : ` The codebase-scoped documents above span ${listedCodebases.length} codebases and no ` +
+                'single call covers them: `get_project_context` takes one codebase, and every entry ' +
+                'names its own in `codebase`.';
+    const listed = documents.length;
+    const rest = omittedProjectDocuments && omittedCodebaseDocuments
+        ? `${contextCall(null, null)} returns the rest of the project-scoped ones, and each ` +
+            "codebase's own need that codebase passed as `codebase`."
+        : omittedProjectDocuments
+            ? `${contextCall(null, null)} returns the rest.`
+            : 'the rest are codebase-scoped: pass the codebase that holds them as `codebase`.';
+    // NAMED, not merely counted. "each codebase's own need that codebase passed as
+    // `codebase`" is only actionable if the agent is told WHICH codebases — and the
+    // prose must say exactly what `omitted.omitted_document_codebases` says, so the
+    // list is never encoded in one of them alone.
+    const holders = furtherDocumentCodebases
+        ? `${humanList(omittedDocumentCodebases)} and ${furtherDocumentCodebases} more ` +
+            `codebase${furtherDocumentCodebases === 1 ? '' : 's'}`
+        : humanList(omittedDocumentCodebases);
+    const omissions = [
+        ...(omittedProjectDocuments + omittedCodebaseDocuments
+            ? [` Only ${listed} of them ${listed === 1 ? 'is' : 'are'} listed here — ${rest}`]
+            : []),
+        ...(omittedDocumentCodebases.length
+            ? [
+                ` The omitted codebase-scoped ones are held by ${holders} — pass each named one as ` +
+                    '`codebase`.',
+            ]
+            : []),
+        ...(omittedCodebases
+            ? [
+                ` This task targets ${omittedCodebases} more codebase${omittedCodebases === 1 ? '' : 's'} ` +
+                    'than were read, so their documents were not preferred for the listing (they are still ' +
+                    'counted above).',
+            ]
+            : []),
+        ...(unnamedCodebases
+            ? [
+                ` This project has ${unnamedCodebases} more codebase${unnamedCodebases === 1 ? '' : 's'} ` +
+                    'than were read, so any documents of theirs are neither listed nor counted above.',
+            ]
+            : []),
+    ];
+    return lead + core + scoping + omissions.join('');
+}
+/**
+ * A warning that cannot become the failure it is describing.
+ *
+ * `console.warn` CAN THROW: the companion is routinely detached, and a write to a
+ * closed stderr raises EPIPE synchronously. Every never-fail path in this block
+ * ends in a warn, so an unguarded one turns "the manifest is unavailable" into
+ * `begin_work failed: EPIPE` for a session row that already exists. The MESSAGE
+ * is built inside the guard too — `errorMessage` calls `String(err)`, which a
+ * thrown object with a hostile `toString` can also make throw.
+ */
+function warnQuietly(build) {
+    try {
+        console.warn(build());
+    }
+    catch {
+        // A lost warning is not a failure. There is nowhere left to report it to.
+    }
+}
+/** Awaits a Supabase call that asked for `{ count: 'exact' }` and returns both.
+ *  `must` deliberately returns only `data`; the manifest needs the count to say
+ *  what it omitted, and PostgREST answers it in the SAME round trip (a
+ *  `Content-Range` header), so the honesty costs no query. */
+async function mustWithCount(query) {
+    const { data, error, count } = await query;
+    if (error)
+        throw new Error(error.message);
+    const rows = data ?? [];
+    return { rows, total: count ?? rows.length };
+}
+/**
+ * Build the manifest for one task, or return null (no documents at all, in any
+ * scope).
+ *
+ * ONE ROUND TRIP, FOUR QUERIES. A BOUNDED SLICE OF EACH SCOPE (project-scoped
+ * documents, codebase-scoped documents), the task's codebase targets, and the
+ * project's codebases all fan out in a single `Promise.all` — none of them
+ * depends on another's result, and `begin_work` runs this on every session open,
+ * so the sequencing is the cost that matters. The target→codebase match and the
+ * per-scope listing cap happen in memory afterwards.
+ *
+ * WHY TWO DOCUMENT READS AND NOT ONE. A single project-wide read has to order the
+ * scopes against each other, and whichever loses can fall entirely outside the
+ * fetch window: with `MANIFEST_FETCH_ROWS` project-scoped documents, the codebase
+ * scope vanished from the manifest — no codebase named, and an instruction
+ * claiming the unqualified call "returns the rest" of documents that call cannot
+ * return. A window per scope makes that structurally impossible, and each read
+ * reports its own exact `count`, so omissions are counted PER SCOPE and the prose
+ * can say which call actually returns which remainder.
+ *
+ * SCOPE-AWARE WITHOUT BEING ASKED. `cliv2_task_codebase_targets` records which
+ * codebase(s) a task targets, BY VALUE — a canonical `git_remote_url`, no FK —
+ * so the targets are matched against the project's own `cliv2_codebases` rows to
+ * reach the ids `project_documents.codebase_id` uses. A target with no
+ * registered codebase in this project simply contributes nothing. Both sides are
+ * stored canonical (`cliv2_codebases` per src/codebases.ts:87, the targets per
+ * their own hosted-remote CHECK), so equality is enough.
+ *
+ * EVERY CODEBASE-SCOPED DOCUMENT CARRIES ITS OWN CODEBASE. The reference the
+ * agent must literally pass is computed per codebase — the display name when that
+ * name is unique in the project, the canonical git remote when it is not, because
+ * `get_project_context` refuses an ambiguous name and a manifest must never hand
+ * out a call the tool rejects. A codebase-scoped document whose codebase row is
+ * gone (Phase 2 orphans rather than cascades), or whose codebase fell past
+ * `MANIFEST_CODEBASE_ROWS`, is therefore unnameable: it is never listed AND never
+ * counted — the agent has no call that would reach it, so counting it would be a
+ * promise the named call cannot keep.
+ *
+ * MORE THAN ONE TARGET IS NORMAL and all of them are included. Phase 3 refuses
+ * an AMBIGUOUS codebase because the caller typed one name and could have meant
+ * either repo; here nobody typed anything — the task states its targets, and
+ * answering about a subset of them would be the silent pick that refusal exists
+ * to prevent. Documents stay ordered project scope first, then codebase scope,
+ * each carrying `scope`, exactly as Phase 3 returns them.
+ *
+ * THE UNTARGETED-ONLY FALLBACK. A project whose documents all live on codebase
+ * pages the task does not target would otherwise get NO manifest — the exact
+ * silence Phase 3 was corrected for ("call again with `codebase`"). When nothing
+ * is listable in the ordinary scopes, the codebase-scoped documents that DO
+ * exist are listed instead and the instruction names their codebase. That never
+ * widens the ordinary case: when the task's own scopes have documents, another
+ * codebase's stay out (and are counted in `omitted`).
+ */
+async function buildProjectContextManifest(client, project, taskId) {
+    // Every read is made through an ASYNC thunk, so a client that throws
+    // SYNCHRONOUSLY (a dead connection, say) rejects the promise `Promise.all` is
+    // already holding rather than throwing while the array is still being built —
+    // which would leave the earlier reads' promises floating and unhandled.
+    const documentColumns = 'title, type, updated_at, codebase_id, content_chars';
+    const [projectRead, codebaseRead, targetRead, codebaseRowsRead] = await Promise.all([
+        (async () => mustWithCount(client
+            .from('project_documents')
+            .select(documentColumns, { count: 'exact' })
+            .eq('project_id', project.id)
+            .is('codebase_id', null)
+            .order('created_at', { ascending: true })
+            .order('id', { ascending: true })
+            .limit(MANIFEST_FETCH_ROWS)))(),
+        (async () => mustWithCount(client
+            .from('project_documents')
+            .select(documentColumns, { count: 'exact' })
+            .eq('project_id', project.id)
+            .not('codebase_id', 'is', null)
+            // Grouped by codebase, then creation order inside each. No `nullsFirst`
+            // is needed — and none is silently load-bearing — because the `not …
+            // is null` predicate means this read has no null `codebase_id` to sort.
+            .order('codebase_id', { ascending: true })
+            .order('created_at', { ascending: true })
+            .order('id', { ascending: true })
+            .limit(MANIFEST_FETCH_ROWS)))(),
+        (async () => mustWithCount(client
+            .from('cliv2_task_codebase_targets')
+            .select('git_remote_url', { count: 'exact' })
+            .eq('task_id', taskId)
+            .order('created_at', { ascending: true })
+            .limit(MANIFEST_TARGET_ROWS)))(),
+        (async () => mustWithCount(client
+            .from('cliv2_codebases')
+            .select('id, name, git_remote_url', { count: 'exact' })
+            .eq('project_id', project.id)
+            .order('created_at', { ascending: true })
+            .limit(MANIFEST_CODEBASE_ROWS)))(),
+    ]);
+    const codebases = codebaseRowsRead.rows;
+    const unnamedCodebases = Math.max(0, codebaseRowsRead.total - codebases.length);
+    // What the agent must LITERALLY pass as `codebase`, per codebase id. The name
+    // when it is unique in this project, the canonical git remote when it is not:
+    // `cliv2_codebases` is unique on `(project_id, git_remote_url)` and NOT on
+    // `name`, and `get_project_context` refuses an ambiguous name outright. Matched
+    // case-insensitively because that tool's name matching is.
+    const nameUses = new Map();
+    for (const row of codebases) {
+        const key = row.name.toLowerCase();
+        nameUses.set(key, (nameUses.get(key) ?? 0) + 1);
+    }
+    const refById = new Map(codebases.map((row) => [
+        row.id,
+        (nameUses.get(row.name.toLowerCase()) ?? 0) > 1 ? row.git_remote_url : row.name,
+    ]));
+    const targeted = new Set(targetRead.rows.map((row) => row.git_remote_url));
+    const targetedIds = new Set(codebases.filter((row) => targeted.has(row.git_remote_url)).map((row) => row.id));
+    const projectRows = projectRead.rows;
+    // Unnameable rows are dropped from the LISTING and from the COUNTS alike: no
+    // `get_project_context` call reaches them, so a total that included them would
+    // promise documents the instruction's own call cannot return. Only what this
+    // window saw can be discounted, which makes the total an upper bound rather
+    // than a fiction — the direction that cannot over-promise.
+    const nameable = (row) => row.codebase_id !== null && refById.has(row.codebase_id);
+    const namedCodebaseRows = codebaseRead.rows.filter(nameable);
+    const unreachable = codebaseRead.rows.length - namedCodebaseRows.length;
+    const codebaseTotal = Math.max(0, codebaseRead.total - unreachable);
+    const targetedRows = namedCodebaseRows.filter((row) => targetedIds.has(row.codebase_id));
+    const otherRows = namedCodebaseRows.filter((row) => !targetedIds.has(row.codebase_id));
+    const listedProject = projectRows.slice(0, MANIFEST_DOCUMENT_ROWS);
+    const listedCodebase = (listedProject.length || targetedRows.length ? targetedRows : otherRows).slice(0, MANIFEST_DOCUMENT_ROWS);
+    const shape = (row, scope) => ({
+        title: row.title,
+        type: row.type,
+        scope,
+        ...(scope === 'codebase' ? { codebase: refById.get(row.codebase_id) } : {}),
+        updated_at: row.updated_at,
+        characters: row.content_chars ?? 0,
+    });
+    const documents = [
+        ...listedProject.map((row) => shape(row, 'project')),
+        ...listedCodebase.map((row) => shape(row, 'codebase')),
+    ];
+    // Absent, not empty.
+    if (documents.length === 0)
+        return null;
+    const omittedProjectDocuments = Math.max(0, projectRead.total - listedProject.length);
+    const omittedCodebaseDocuments = Math.max(0, codebaseTotal - listedCodebase.length);
+    const omittedDocuments = omittedProjectDocuments + omittedCodebaseDocuments;
+    const totalDocuments = documents.length + omittedDocuments;
+    // WHICH codebases hold the documents that were left out. Derived from the rows
+    // themselves (identity against the listed slice), so a codebase with some rows
+    // listed and some omitted is named too — its remainder needs the same call.
+    // Only the fetch window can be attributed, which makes this a lower bound
+    // rather than a fiction: the direction that cannot name a codebase that does
+    // not hold an omitted document.
+    const listedCodebaseRows = new Set(listedCodebase);
+    const omittedCodebaseRefs = omittedCodebaseDocuments
+        ? [
+            ...new Set(namedCodebaseRows
+                .filter((row) => !listedCodebaseRows.has(row))
+                .map((row) => refById.get(row.codebase_id))),
+        ]
+        : [];
+    const omittedDocumentCodebases = omittedCodebaseRefs.slice(0, MANIFEST_OMITTED_CODEBASE_REFS);
+    const furtherDocumentCodebases = omittedCodebaseRefs.length - omittedDocumentCodebases.length;
+    const omittedCodebases = Math.max(0, targetRead.total - targetRead.rows.length);
+    const omitted = omittedDocuments || omittedCodebases || unnamedCodebases
+        ? {
+            // Conditional, so `omitted_documents: 0` can never contradict its own
+            // "always > 0 when present" contract.
+            ...(omittedDocuments
+                ? { total_documents: totalDocuments, omitted_documents: omittedDocuments }
+                : {}),
+            ...(omittedDocumentCodebases.length
+                ? { omitted_document_codebases: omittedDocumentCodebases }
+                : {}),
+            ...(furtherDocumentCodebases
+                ? { further_document_codebases: furtherDocumentCodebases }
+                : {}),
+            ...(omittedCodebases ? { omitted_codebases: omittedCodebases } : {}),
+            ...(unnamedCodebases ? { unnamed_codebases: unnamedCodebases } : {}),
+        }
+        : null;
+    return {
+        project: project.name,
+        documents,
+        ...(omitted ? { omitted } : {}),
+        instruction: manifestInstruction({
+            projectName: project.name,
+            documents,
+            total: totalDocuments,
+            omittedProjectDocuments,
+            omittedCodebaseDocuments,
+            omittedDocumentCodebases,
+            furtherDocumentCodebases,
+            omittedCodebases,
+            unnamedCodebases,
+        }),
+    };
+}
+/**
+ * The manifest, or null — THE ONLY ENTRY POINT, and it cannot fail.
+ *
+ * Every throw is caught here and every slow path is abandoned here, so a caller
+ * physically has no error to handle: the return type says `Manifest | null` and
+ * nothing else can come out. The catch itself is written so that it cannot
+ * throw either — a thrown non-Error (`throw 'nope'`, an aborted fetch's
+ * `DOMException`, anything) would make `(err as Error).message` a `TypeError`
+ * raised FROM INSIDE the catch, which escapes this function entirely and turns
+ * an optional extra into a permanently failing `begin_work` on a session that
+ * has already been inserted.
+ */
+async function projectContextManifest(client, project, taskId) {
+    let timer;
+    try {
+        return await Promise.race([
+            buildProjectContextManifest(client, project, taskId),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(null), MANIFEST_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch (err) {
+        // Warned, not surfaced: the session is the result the agent asked for.
+        warnQuietly(() => `begin_work: project context manifest unavailable: ${errorMessage(err)}`);
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ---------------------------------------------------------------------------
+// The twenty-seven tools this server exposes. Exported for the self-check.
+// ---------------------------------------------------------------------------
+export const TOOL_NAMES = [
+    'list_tasks',
+    'get_task',
+    'create_artifact',
+    'attach_screenshot',
+    'update_task',
+    'update_artifact',
+    'set_task_role_slugs',
+    'add_comment',
+    'create_task',
+    'create_epic',
+    'create_sprint',
+    'begin_work',
+    'end_work',
+    'ask_question',
+    'present_wireframes',
+    'present_mocks',
+    'resolve_feedback',
+    'record_user_input',
     'record_context_exploration',
     'reserve_work_paths',
     'release_work_paths',
@@ -1439,8 +4627,17 @@ export const TOOL_NAMES = [
     'acknowledge_unavailable_checkout',
     'list_credentials',
     'get_credential',
+    'get_project_context',
+    'propose_project_context',
+    'list_product_ideas',
+    'create_product_idea',
+    'get_client_context',
+    'list_clients',
+    'propose_client_context',
+    'raise_work_item_flags',
+    'resolve_work_item_flags',
 ];
-/** Build a per-session McpServer with the twenty-two tools. A fresh instance per
+/** Build a per-session McpServer with the thirty-three tools. A fresh instance per
  *  session is what makes `server.server.getClientVersion()` (populated during
  *  that session's `initialize`) the right source for attribution — mirroring
  *  v1's per-session `buildServer`. `connectionId` is this connection's key into
@@ -1464,6 +4661,63 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
         touchSession(connectionId);
         return listTasksHandler(client, args);
     });
+    server.registerTool('list_product_ideas', {
+        description: 'List the Product Ideas in your CTRL+SPC projects — pre-backlog work items the organization has NOT agreed to build. '
+            + 'These are deliberately absent from list_tasks, so this is the only way to see them. '
+            + 'Call this BEFORE capturing a new signal as an idea: if one of these already covers the same problem — in THIS project '
+            + 'or another one listed here — add an artifact to it (create_artifact) instead of creating a near-duplicate. '
+            + 'Also read the code first, in the repository you are working in, whether or not a codebase is attached: if the product '
+            + 'already does what the signal asks for, the right outcome is to create NOTHING and say so. '
+            + 'Returns titles and counts, not artifact bodies; use get_task to read one in full when a title alone cannot settle '
+            + 'whether two signals are the same problem.',
+        inputSchema: { project_id: z.string().optional() },
+    }, async (args) => {
+        touchSession(connectionId);
+        return listProductIdeasHandler(client, args);
+    });
+    server.registerTool('create_product_idea', {
+        description: 'Capture a signal (customer feedback, market context, a support thread, a technical opportunity) as a Product Idea — '
+            + 'a work item that is NOT in the Backlog and that only a human can promote. Creating one starts no work and commits '
+            + 'nobody. '
+            + 'FIRST call list_product_ideas and read the relevant code. If an existing idea already covers the problem, add an '
+            + 'artifact to that idea instead of calling this. If the product ALREADY DOES what the signal asks for, create '
+            + 'nothing at all — say so and stop; do not substitute an adjacent gap you noticed. '
+            + 'ONE SIGNAL IS USUALLY AT MOST ONE IDEA: several people describing the same problem is one idea, not one per quote, '
+            + 'and a signal with two genuinely different problems in it is two. '
+            + 'Put your analysis in an artifact on the new idea (create_artifact) — the '
+            + "idea's DESCRIPTION is the human's own thinking, so write it only when it is empty and never edit one they wrote. "
+            + 'UPDATING BEATS CREATING, especially from client intake: when new client material discusses something an existing '
+            + 'idea already covers, do NOT create a second idea — add the newly discussed requirements, with their citations, to '
+            + 'the EXISTING idea as an artifact; a Product Ideas list with eleven near-identical checkout entries, one per '
+            + 'meeting, is noise. From a client intake run pass client_id: the idea must land in a project attached to THAT '
+            + 'client (get_client_context lists them under `projects` — one project resolves the choice itself, several means '
+            + "you choose and say why). Ground the idea in the client's own words in a CITED ARTIFACT on it "
+            + '(create_artifact) — the description is the human\'s plain-text surface and carries no citation lines. '
+            + CITATION_LINE_TEACHING,
+        inputSchema: {
+            project_id: z.string(),
+            title: z
+                .string()
+                .min(1)
+                .describe('One line naming the PROBLEM, in the vocabulary the user would use — not a quote from their message, and not your '
+                + 'summary of your own analysis. A later run has to recognise a duplicate from this line alone, so "Bulk archive is '
+                + 'too slow for CS" beats "I gave up halfway through and left the rest sitting on the board".'),
+            description: z
+                .string()
+                .optional()
+                .describe('Only for a brand-new idea whose description is empty. Never a summary of your own analysis — that is an '
+                + 'artifact — and never citation lines: the description is plain text, so quotes and source ids go in a '
+                + 'cited artifact on the idea instead.'),
+            client_id: z
+                .string()
+                .optional()
+                .describe('From a client intake run: the client this idea came from. The project must be attached to this client, '
+                + 'and the call is refused if it is not.'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return createProductIdeaHandler(client, userId, args);
+    });
     server.registerTool('get_task', {
         description: 'Read a full task — its tags, comments, artifacts, decisions (so you can read the answers to questions ' +
             'you asked), and feedback (the cumulative wireframe-review rounds the user sent, each tagged with the ' +
@@ -1472,17 +4726,31 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
             "attention ('reopened' means the user flipped a round you resolved back to not resolved — treat it as " +
             "open feedback on your next pass); 'resolved' rounds don't (resolved_in_revision names the revision that " +
             'addressed them; mark rounds resolved with resolve_feedback after revising). ' +
-            'Read-only; it has no status or presence side effects.',
+            'Read-only; it has no status or presence side effects. '
+            + 'If the item is a Product Idea (pre-backlog, not agreed work), the result carries a product_idea_boundary block — follow it: explore and write artifacts, never implement.',
         inputSchema: { id: z.string().describe('Task id') },
     }, async ({ id }) => {
         touchSession(connectionId);
         return getTaskHandler(client, { id });
     });
     server.registerTool('create_artifact', {
-        description: 'Create a titled analysis/plan/spec/diagram/mock/wireframe on a task. It appears in the web UI, attributed to you.',
+        // 31 Slice 2: the grounded pass is taught HERE (enforcement is manifest
+        // only — Step −1 ruling 2: no warning, no refusal; 13a's caution
+        // stands). The citation convention is the SAME constant the intake
+        // tools teach, because a convention that lives in one description is a
+        // convention half the flows never see.
+        description: 'Create a titled analysis/plan/spec/diagram/mock/wireframe/user_story on a task. It appears in the web UI, attributed to you. ' +
+            "A user_story artifact carries the work item's FULL story set — every \"As a … I want … so that …\" story with its acceptance criteria, in one markdown artifact. Never create one artifact per story. " +
+            'GROUND WHAT YOU AUTHOR: before writing a user_story, spec or plan, fan out and READ what the ' +
+            "product knows — the client's context (get_client_context, when the project serves a client), " +
+            "the project's context documents (get_project_context), and the codebase — then pass " +
+            '`grounding` naming exactly what you read. The manifest is stored with the artifact and its ' +
+            'absence is visible to every reader: a user_story written WITHOUT reading available client ' +
+            'context must say so in its opening line. ' +
+            CITATION_LINE_TEACHING,
         inputSchema: {
             task_id: z.string(),
-            type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']),
+            type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe', 'user_story']),
             format: z.enum(['md', 'html', 'json', 'svg']).optional().describe('Defaults to md'),
             title: z.string().min(1).optional(),
             purpose_key: z
@@ -1491,13 +4759,48 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
                 .optional()
                 .describe('Stable machine-readable identity for this artifact purpose'),
             content: z.string(),
+            grounding: z
+                .object({
+                client_context_record_ids: z
+                    .array(z.string())
+                    .optional()
+                    .describe('Ids of the client context records you read (get_client_context)'),
+                project_document_ids: z
+                    .array(z.string())
+                    .optional()
+                    .describe('Ids of the project context documents you read (get_project_context)'),
+                codebases: z
+                    .array(z.string())
+                    .optional()
+                    .describe('Names or remotes of the codebases you read'),
+            })
+                .optional()
+                .describe('The manifest of what you READ before authoring — stored with the artifact. Omit it when ' +
+                'you read nothing, and say so in the artifact instead of sending an empty manifest.'),
         },
     }, async (args) => {
         touchSession(connectionId);
         return createArtifactHandler(client, userId, openSessions.get(connectionId) ?? null, args);
     });
+    server.registerTool('attach_screenshot', {
+        description: 'Attach one real Web, iOS, or Android PNG screenshot to the work item in your open session. ' +
+            'Playwright or Maestro captures the file first; pass its absolute local path, a clear title, the ' +
+            'platform, and the exact browser/simulator/emulator target. The local path is never uploaded or stored. ' +
+            'Requires an open session (begin_work).',
+        inputSchema: {
+            path: z.string().describe('Absolute local path to one existing PNG'),
+            title: z.string().describe('Non-empty title shown on the work item'),
+            platform: z.enum(['web', 'ios', 'android']),
+            target: z.string().describe('Non-empty exact browser, simulator, or emulator name'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return attachScreenshotHandler(client, userId, openSessions.get(connectionId) ?? null, args);
+    });
     server.registerTool('update_task', {
-        description: 'Update a task you own — its status (backlog / in_progress / done), name, description, or due_date. ' +
+        description: "On a Product Idea the description is the human's own thinking: you may write it only while it is EMPTY, and never edit or overwrite one they wrote — put your analysis in an artifact (create_artifact) instead. "
+            + 'That is not a default you can be talked out of: if the user asks you to rewrite a description that has content, say you cannot and offer the artifact, rather than offering to do it anyway. '
+            + 'Update a task you own — its status (backlog / in_progress / done), name, description, or due_date. ' +
             'Pass expected_revision from the most recent get_task for optimistic concurrency; on a conflict, ' +
             'call get_task again to re-read and retry. The change appears in the web board.',
         inputSchema: {
@@ -1531,7 +4834,7 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
                 .describe('The artifact revision from the most recent get_task (optimistic concurrency)'),
             fields: z.object({
                 title: z.string().min(1).optional(),
-                type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe']).optional(),
+                type: z.enum(['analysis', 'plan', 'spec', 'diagram', 'mock', 'wireframe', 'user_story']).optional(),
                 format: z.enum(['md', 'html', 'json', 'svg']).optional(),
                 content: z.string().optional(),
             }),
@@ -1562,17 +4865,84 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
         return addCommentHandler(client, userId, openSessions.get(connectionId) ?? null, args);
     });
     server.registerTool('create_task', {
-        description: 'Create a new task in one of your projects — for splitting work or leaving follow-ups. ' +
-            'It appears on the web board, owned by you.',
+        // Feature 32: the calibration rule lives HERE (teach-in-the-description
+        // doctrine) — the bias is stated outright and the tests pin the text.
+        description: 'Create a new task in one of your projects — for splitting work, leaving follow-ups, or laying ' +
+            "out an Agile skeleton's work items. It appears on the web board, owned by you, in backlog: lay " +
+            'out work, never declare progress. Optional epic_id / sprint_id place it under an epic and into ' +
+            'a sprint at creation; both must be live (not archived) and belong to the SAME project. ' +
+            'READ BEFORE YOU WRITE: list what exists (list_tasks) before adding structure, and cut items ' +
+            'along real seams — separately buildable, separately testable — not one item per noun in the ' +
+            'ask. Add NO duration estimates to names or descriptions unless the user asked: agents ' +
+            'overestimate toward human timelines, and sequencing, not duration, is the value.',
         inputSchema: {
             project_id: z.string().describe('Project id the task belongs to'),
             name: z.string().min(1),
             description: z.string().optional(),
+            epic_id: z
+                .string()
+                .optional()
+                .describe('Epic to place the task under — a live epic of this SAME project (create_epic)'),
+            sprint_id: z
+                .string()
+                .optional()
+                .describe('Sprint to place the task into — a live sprint of this SAME project (create_sprint)'),
         },
     }, async (args) => {
         touchSession(connectionId);
         return createTaskHandler(client, userId, openSessions.get(connectionId) ?? null, args);
     });
+    server.registerTool('create_epic', {
+        // Feature 32, Slice 1. The description carries the calibration rule and
+        // the read-before-write doctrine — both load-bearing, both pinned by
+        // tests: the scenario evidence from 22b is that agents OBEY this text.
+        description: "Create an Epic — the what-for container a feature's work items hang under, visible on the " +
+            'project board and in Epic management. Use it to lay out an Agile skeleton from a feature ask: ' +
+            'ONE epic for the feature, work items under it (create_task with epic_id), ordered into sprints ' +
+            '(create_sprint). READ BEFORE YOU WRITE: list what exists first (list_tasks for the projects ' +
+            'and board, get_task for detail) — if an epic already covers this feature, EXTEND it with new ' +
+            'work items instead of creating a near-duplicate; a case-insensitive name match is refused for ' +
+            'exactly that reason. CALIBRATE TO AGENT TIME, NOT HUMAN TIME: agents dramatically overestimate ' +
+            'how long building takes because their training is saturated with human engineering timelines — ' +
+            'this plan is executed by agents in sessions and days, not team-weeks and quarters. Do not pad ' +
+            'the epic across a quarter, and add NO duration estimates to anything unless the user asked; ' +
+            'sequencing is the value. Dates are optional — set them only when the user gave real calendar ' +
+            'constraints. Writes as you under RLS; the skeleton lands in backlog — it lays out work, it ' +
+            'never declares progress. ATTRIBUTION: your byline lands on created work items only while a ' +
+            'work session is open — create the FIRST work item, begin_work on it, then create the rest, ' +
+            'so the skeleton is legibly agent-drafted on the board.',
+        inputSchema: {
+            project_id: z.string().describe('Project id the epic belongs to'),
+            name: z.string().min(1).describe('The feature this epic is for — refused if a live epic already carries the name'),
+            description: z.string().optional().describe('What the epic is for and how the work under it is cut'),
+            start_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — only when the user gave one'),
+            target_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — a hope, not an estimate; only when the user gave one'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return createEpicHandler(client, args);
+    });
+    server.registerTool('create_sprint', {
+        description: 'Create a Sprint in a project. For agent-executed work a sprint is an ORDERED BATCH, not a ' +
+            'time-box: the first sprint holds what unblocks everything else, the next builds on it — each ' +
+            'sized to what agents deliver in a session or a day, not what a human team ships in a ' +
+            'fortnight. Agents dramatically overestimate how long building takes (their training is ' +
+            'saturated with human engineering timelines); counter the bias with fewer, tighter sprints and ' +
+            'NO duration estimates on work items unless the user asked. Dates are optional and usually ' +
+            'unnecessary — set them only for a real calendar constraint the user stated. READ BEFORE YOU ' +
+            "WRITE: list what exists first and reuse the project's existing sprint sequence (a " +
+            'case-insensitive name match is refused) rather than minting a parallel one. Place items with ' +
+            "create_task's sprint_id.",
+        inputSchema: {
+            project_id: z.string().describe('Project id the sprint belongs to'),
+            name: z.string().min(1).describe('The batch name — refused if a live sprint already carries it'),
+            start_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — only for a real calendar constraint'),
+            end_date: z.string().optional().describe('ISO date (YYYY-MM-DD) — only for a real calendar constraint'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return createSprintHandler(client, args);
+    });
     server.registerTool('begin_work', {
         description: 'Open a work session on a task so the outputs you create afterward are attributed to this run. ' +
             'Call it once, before create_artifact, for the task you are about to work. ' +
@@ -1591,10 +4961,72 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
             if (!provider) {
                 return errorResult('begin_work needs a supported agent (Claude or Codex); this client is not recognized as one.');
             }
-            // The task must exist and be live under the user's RLS.
-            const task = await must(client.from('tasks').select('id').eq('id', args.task_id).is('archived_at', null).maybeSingle());
+            // The task must exist and be live under the user's RLS. The project id
+            // and name ride along on this SAME select (13a Phase 3b) so the context
+            // manifest below costs no extra round-trip to find its project — the
+            // embed is non-null (`tasks.project_id` is a NOT NULL FK), and a shape
+            // that ever came back without it just means no manifest.
+            const task = await must(client
+                .from('tasks')
+                .select('id, project_id, projects(name)')
+                .eq('id', args.task_id)
+                .is('archived_at', null)
+                .maybeSingle());
             if (!task)
                 return errorResult(`No task found for id "${args.task_id}".`);
+            // PostgREST returns a to-one embed as an object but has returned an
+            // array for the same shape across versions; both are unwrapped.
+            const embeddedProject = Array.isArray(task.projects)
+                ? (task.projects[0] ?? null)
+                : task.projects;
+            const projectForManifest = embeddedProject?.name
+                ? { id: task.project_id, name: embeddedProject.name }
+                : null;
+            /** STARTED HERE, AWAITED LATER. The manifest needs only `task.project_id`
+             *  and the project name — both already in hand — and depends on nothing
+             *  the session insert/update produces. Sequencing it after that write put
+             *  up to `MANIFEST_TIMEOUT_MS` of OPTIONAL work on the critical path of
+             *  the one handshake every session opens with; kicking it off now
+             *  overlaps it with the write instead.
+             *
+             *  The `.catch` is attached in the same expression that creates the
+             *  promise, so a rejection can never be unhandled during the window where
+             *  the session write is what is being awaited. */
+            const manifestPromise = projectForManifest
+                ? projectContextManifest(client, projectForManifest, args.task_id).catch((err) => {
+                    warnQuietly(() => `begin_work: project context manifest unavailable: ${errorMessage(err)}`);
+                    return null;
+                })
+                : Promise.resolve(null);
+            /** The session payload, plus the context manifest when there is one —
+             *  this can only ever ADD a key.
+             *
+             *  `projectContextManifest` already contracts never to throw and never
+             *  to hang past `MANIFEST_TIMEOUT_MS`. This try does NOT duplicate that
+             *  guard, it makes it stop being a precondition: the session row has
+             *  ALREADY been inserted and registered by the time this runs, so a
+             *  throw escaping the callee would reach `begin_work`'s outer catch and
+             *  return `begin_work failed: …` for a session that exists — and the
+             *  retry would take the reuse path and fail identically, forever. The
+             *  never-fail property has to be a property of THIS call site, not of
+             *  the callee's internals.
+             *
+             *  THE FALLBACK IS BUILT BEFORE ANYTHING IS LOGGED. A `console.warn` that
+             *  throws (EPIPE on a detached companion's stderr) used to escape from
+             *  inside this very catch — the one place whose entire job is to not let
+             *  that happen. `warnQuietly` swallows it, and the fallback exists before
+             *  the warn runs either way. */
+            const withProjectContext = async (session) => {
+                const fallback = textResult({ session });
+                try {
+                    const manifest = await manifestPromise;
+                    return manifest ? textResult({ session, project_context: manifest }) : fallback;
+                }
+                catch (err) {
+                    warnQuietly(() => `begin_work: project context manifest unavailable: ${errorMessage(err)}`);
+                    return fallback;
+                }
+            };
             // Already have a session on THIS connection for THIS task: refresh its
             // liveness (and model, if newly provided) and reuse it — no second row.
             const prev = openSessions.get(connectionId);
@@ -1610,7 +5042,9 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
                     .single());
                 if (!updated)
                     throw new Error('Session update returned no row.');
-                return textResult({ session: updated });
+                // The REUSE path carries the manifest too: a resumed session opens on
+                // the same handshake and has the same reason to know the context exists.
+                return withProjectContext(updated);
             }
             // Open the NEW session FIRST (FIX 3): if this insert throws, the registry
             // still points at the previous (valid) session rather than an ended one.
@@ -1648,7 +5082,7 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
                 taskId: session.task_id,
                 expiresAt: Date.now() + SESSION_TTL_MS,
             });
-            return textResult({ session });
+            return withProjectContext(session);
         }
         catch (err) {
             return errorResult(`begin_work failed: ${err.message}`);
@@ -1901,6 +5335,212 @@ export function buildToolsServer(client, userId, machineId, connectionId) {
         touchSession(connectionId);
         return getCredentialHandler(client, args);
     });
+    server.registerTool('get_project_context', {
+        // Verbatim from .implementations/13a-project-context/ux.md § Phase 3
+        // "Tool description" — the approved text. Per the doctrine above, the
+        // description is what TEACHES the agent when to reach for this (which
+        // types serve which work), and the handler is what enforces.
+        description: 'Read the context documents for the project you are working — the instructions, architecture, design ' +
+            'and conventions the team keeps in CTRL+SPC instead of a repo root. Pass `codebase` to also get the ' +
+            'documents that belong to that one repo; pass `types` to pull only what the work needs ' +
+            '(`instructions` before you change anything, `design` for UI work, `conventions` at review). ' +
+            "Uses the open session's task when `task_id` is omitted. Read-only.",
+        inputSchema: {
+            task_id: z
+                .string()
+                .optional()
+                .describe("Task whose project to read; defaults to the open session's task"),
+            codebase: z
+                .string()
+                .optional()
+                .describe("Codebase name or git remote — also returns that codebase's own documents, after the project's"),
+            // Constrained here, unlike present_mocks' deliberately unconstrained
+            // schema: the five values are a closed set an agent cannot reason its
+            // way to, and zod's enum refusal LISTS them, which is more useful than
+            // silently returning nothing for a typo.
+            types: z
+                .array(z.enum(PROJECT_DOCUMENT_TYPES))
+                .optional()
+                .describe('Only these document types; omitted returns every type'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return getProjectContextHandler(client, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('propose_project_context', {
+        // The description TEACHES: when to reach for this (after reading a repo),
+        // what a good proposal is (content it actually read, one line of why),
+        // and — the part an agent will otherwise get wrong — that this creates
+        // NOTHING, so its job ends at telling the user where to review.
+        description: 'Propose context documents for the repo you are working in, after reading it. You decide what counts ' +
+            'as standing context — instructions, architecture, design, conventions — wherever it lives in the ' +
+            'repo; there is no fixed list of filenames. Each proposal carries the content you read, its ' +
+            '`source_path`, and one line of `reason` saying why it belongs, so the user can judge your judgement. ' +
+            'Set each proposal\'s `scope`: "project" for context that applies to the whole project, "codebase" ' +
+            'for context that belongs to this repo alone — one scan can send both. This CREATES NOTHING: it ' +
+            'writes proposals the user accepts or rejects in the web app, under Project settings → Project ' +
+            'context. Say so when you report back. Re-running replaces this codebase\'s pending proposals; send ' +
+            'an empty `proposals` array to report that the repo holds no standing context, which clears them. ' +
+            "Uses the open session's task when `task_id` is omitted.",
+        inputSchema: {
+            task_id: z
+                .string()
+                .optional()
+                .describe("Task whose project to propose into; defaults to the open session's task"),
+            codebase: z
+                .string()
+                .min(1)
+                .describe('The codebase you scanned — its name or git remote, as get_project_context takes it'),
+            proposals: z
+                .array(z.object({
+                title: z.string().min(1).describe('Document title, 100 characters or fewer'),
+                // Constrained, as get_project_context's `types` is: a closed set
+                // an agent cannot reason its way to, and zod's refusal lists it.
+                type: z.enum(PROJECT_DOCUMENT_TYPES),
+                content: z.string().min(1).describe('The content you read, verbatim — do not draft new material'),
+                source_path: z
+                    .string()
+                    .min(1)
+                    .describe('Path of the file this came from, RELATIVE to the repo root — never absolute'),
+                reason: z.string().min(1).describe('One line: why this belongs in the project context'),
+                scope: z
+                    .enum(PROPOSAL_SCOPES)
+                    .describe('"project" for the whole project, "codebase" for this repo alone'),
+            }))
+                .describe('The proposals from this scan — send `[]` if the repo holds no standing context, which clears ' +
+                'anything an earlier scan left waiting'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return proposeProjectContextHandler(client, openSessions.get(connectionId) ?? null, args);
+    });
+    server.registerTool('list_clients', {
+        description: 'List the clients you can see in CTRL+SPC, each with its attached projects. THE ENTRY POINT ' +
+            'for a client-shaped ask ("build what <client name> asked for on the last call"): resolve the ' +
+            'name to a client id here, then call get_client_context with that id to read what the client ' +
+            'actually said before writing anything. Read-only.',
+        inputSchema: {},
+    }, async () => {
+        touchSession(connectionId);
+        return listClientsHandler(client);
+    });
+    server.registerTool('get_client_context', {
+        // The description TEACHES the read-before-write non-negotiable: reading
+        // what exists is required before proposing, every run — it is the
+        // feature, not an optimization (ux.md non-negotiable 2).
+        description: "Read a client's whole context surface in CTRL+SPC: every piece of raw material (sources — pasted " +
+            'emails, transcripts, documents), whether each has been processed by an agent run, every accepted ' +
+            "context record with its citation, the client's attached projects and their existing Product " +
+            'Ideas, and your own pending proposal count. Call this FIRST, before propose_client_context or ' +
+            'any idea write, every run — reading the context that already exists before writing is ' +
+            'required, not an optimization: it is how you avoid proposing near-duplicates of records the ' +
+            'client already has, and how you extend the Product Idea that already covers a problem instead ' +
+            'of minting another. Takes the client_id from the instruction that sent you here. Read-only.',
+        inputSchema: {
+            client_id: z.string().min(1).describe('The client whose context to read, as given in your instruction'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return getClientContextHandler(client, args);
+    });
+    server.registerTool('propose_client_context', {
+        // Teaches the two things an agent will otherwise get wrong: the quote
+        // must be VERBATIM, and this creates nothing — review is the human's.
+        description: 'Hand over one intake run\'s results for a client, after reading its unprocessed sources with ' +
+            'get_client_context: per source, either the durable context records you propose from it ' +
+            '(facts, constraints, preferences, decisions) or found_nothing: true — finding nothing durable in ' +
+            'a source is a correct outcome and must be stated, not skipped. EVERY proposal cites its source: ' +
+            "`quote` must be a VERBATIM substring of that source's stored body, character for character — " +
+            'never paraphrase, trim or normalize it. A proposal that re-quotes a span an ACCEPTED record ' +
+            'already cites is refused whole-batch — updating beats creating; propose only what is NEW. ' +
+            'This CREATES NOTHING: it writes proposals the user ' +
+            "accepts or rejects on the client's page in the web app, and flags each source processed. Say so " +
+            "when you report back. Re-running replaces your own pending proposals for the sources you send.",
+        inputSchema: {
+            client_id: z.string().min(1).describe('The client whose material you read'),
+            results: z
+                .array(z.object({
+                source_id: z.string().min(1).describe('A source id from get_client_context'),
+                found_nothing: z
+                    .boolean()
+                    .optional()
+                    .describe('true when this source holds nothing durable — send it with no proposals'),
+                proposals: z
+                    .array(z.object({
+                    // Constrained, as get_project_context's `types` is: a
+                    // closed set an agent cannot reason its way to, and zod's
+                    // refusal lists it.
+                    kind: z.enum(CLIENT_RECORD_KINDS),
+                    title: z.string().min(1).describe('Record title, 100 characters or fewer'),
+                    body: z.string().min(1).describe('The durable fact, constraint, preference or decision'),
+                    reason: z.string().min(1).describe('One line: why this is durable client context'),
+                    quote: z
+                        .string()
+                        .min(1)
+                        .describe("The span this came from, VERBATIM from the source's body — the citation"),
+                }))
+                    .optional()
+                    .describe('The records you propose from this source — 1 or more, or found_nothing instead'),
+            }))
+                .describe('One entry per source you read this run'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return proposeClientContextHandler(client, args);
+    });
+    server.registerTool('raise_work_item_flags', {
+        // Teaches non-negotiable 3 (never edit — flag), the verbatim citation,
+        // and the dedup-skip semantics an agent will otherwise misread as an
+        // error.
+        description: "Flag a client's existing work items that new client material CONTRADICTS — after reading them " +
+            'with get_client_context, in the same intake run. You NEVER edit a work item: a flag carries ' +
+            'your suggested edit stated plainly plus the justification, and a human acts on it, hands it ' +
+            "to their own agent, or dismisses it. Every flag cites the client's own words: `quote` must be " +
+            "a VERBATIM substring of that source's stored body — never paraphrase, trim or normalize it. " +
+            'A flag whose (work_item_id, quote) was already raised — even one since dismissed — is ' +
+            'SKIPPED, not an error: a dismissal is permanent, and get_client_context shows you the ' +
+            'existing flags so you can avoid re-deriving them. Finding no contradictions is a correct ' +
+            'outcome: simply do not call this.',
+        inputSchema: {
+            client_id: z.string().min(1).describe('The client whose material you read'),
+            flags: z
+                .array(z.object({
+                work_item_id: z
+                    .string()
+                    .min(1)
+                    .describe('The contradicted work item, from get_client_context'),
+                source_id: z.string().min(1).describe('The source the quote lives in'),
+                quote: z
+                    .string()
+                    .min(1)
+                    .describe("The contradicting span, VERBATIM from the source's body — the citation"),
+                suggested_edit: z
+                    .string()
+                    .min(1)
+                    .describe('What should change on the item, stated plainly — guidance, not a patch'),
+            }))
+                .describe('One entry per contradiction you found'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        // WHO FLAGGED, resolved at raise time: this machine's effective name +
+        // this connection's provider (best-effort, honest fallbacks).
+        const agentName = await resolveFlagAgentName(client, machineId, attribution());
+        return raiseWorkItemFlagsHandler(client, args, agentName);
+    });
+    server.registerTool('resolve_work_item_flags', {
+        description: 'Mark every OPEN flag on one work item resolved — the LAST step of an "apply the flags" ' +
+            'instruction a human handed you: make the edits each flag suggests first, then call this. ' +
+            'Dismissed flags are untouched (a dismissal is the human\'s permanent judgement), and a work ' +
+            'item with no open flags resolves to "nothing to resolve", which is a success. Never call ' +
+            'this from an intake run — raising and resolving belong to different agents.',
+        inputSchema: {
+            work_item_id: z.string().min(1).describe('The work item whose flags you applied'),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        return resolveWorkItemFlagsHandler(client, args);
+    });
     return server;
 }
 let handle = null;