@ctrl-spc/cs 0.7.10 → 0.7.11

package/dist/mcp.js

@@ -1,3 +1,7 @@
+import { listStructureArtifactsHandler, getStructureArtifactHandler, searchAgentCardsHandler, createStructureArtifactHandler, updateStructureArtifactHandler } from './product-tools.js';
+import { createEpicHandler, createSprintHandler, listStructureHandler, updateStructureHandler } from './product-tools.js';
+export { createEpicHandler, createSprintHandler, listStructureHandler, updateStructureHandler } from './product-tools.js';
+import { listArtifactFoldersHandler, setArtifactFolderHandler, workItemDependencyHandler } from './product-tools.js';
 import { presentDesign } from './design-review.js';
 import { must, errorMessage, textResult, errorResult, canonicalArgsHash, TASK_PLACEMENT, placeWorkItemHandler, UUID_RE, resolveFeedbackHandler, PROJECT_DOCUMENT_TYPES, countCharacters, resolveContextProject, resolveContextCodebase, getDocumentHandler, PROPOSAL_SCOPES, MAX_PROPOSALS, MAX_PROPOSAL_BATCH_CHARS, proposeProjectContextHandler } from './product-tools.js';
 export { canonicalArgsHash, placeWorkItemHandler, resolveFeedbackHandler, getDocumentHandler, proposeProjectContextHandler } from './product-tools.js';
@@ -248,7 +252,7 @@ function validateGrounding(value) {
  *  reused verbatim so get_task and create_artifact hand back the same shape, plus
  *  `revision` so the agent has the optimistic-concurrency token update_artifact
  *  needs for `expected_revision` (mirrors how get_task returns tasks.revision). */
-const ARTIFACT_COLUMNS = 'id,task_id,type,format,title,purpose_key,system_kind,content,storage_path,created_by,from_agent,created_at,revision';
+const ARTIFACT_COLUMNS = 'id,task_id,type,format,title,purpose_key,system_kind,content,storage_path,created_by,from_agent,created_at,revision,folder_name';
 /** Columns a decision row exposes to the agent (D3) — reused verbatim so get_task
  *  and ask_question hand back the same shape. RLS `decisions_select` grants the
  *  signed-in user read via `app.can_access_task`. */
@@ -835,6 +839,7 @@ connectionTodoId = null) {
             .from('artifacts')
             .insert({
             task_id: args.task_id,
+            folder_name: args.folder_name ?? null,
             type: args.type,
             format: args.format ?? 'md',
             ...(args.title?.trim()
@@ -2105,357 +2110,6 @@ connectionTodoId = null) {
         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)}`);
-    }
-}
-const STRUCTURE_TABLE = { epic: 'epics', sprint: 'sprints' };
-/**
- * WHAT STRUCTURE THIS PROJECT HAS — the read that made "read before you write"
- * possible (I13).
- *
- * LIVE ONES BY DEFAULT, because that is what "what exists" means to an agent
- * about to add to it: an archived epic is not something to extend, and listing
- * it invites a duplicate-name refusal the agent cannot act on. `include_archived`
- * is deliberately NOT offered — nothing in this phase's Gherkin needs it, and
- * YAGNI beats a flag with no caller.
- *
- * BOTH KINDS IN ONE CALL. They are always wanted together, and two tools would
- * mean two round trips for the one question an agent actually has.
- */
-export async function listStructureHandler(client, args) {
-    try {
-        const project = await resolveSkeletonProject(client, args.project_id, 'list_structure');
-        if (!project.ok)
-            return project.error;
-        const [epics, sprints] = await Promise.all([
-            must(client
-                .from('epics')
-                .select('id, name, description, start_date, target_date, created_at')
-                .eq('project_id', project.value.id)
-                .is('archived_at', null)
-                .order('created_at', { ascending: true })),
-            must(client
-                .from('sprints')
-                .select('id, name, start_date, end_date, created_at')
-                .eq('project_id', project.value.id)
-                .is('archived_at', null)
-                .order('created_at', { ascending: true })),
-        ]);
-        return textResult({
-            project: project.value,
-            epics: epics ?? [],
-            sprints: sprints ?? [],
-            note: 'Live epics and sprints only. Extend these rather than creating a near-duplicate — a ' +
-                'case-insensitive name match is refused. Place a work item with place_work_item, and see ' +
-                "where items already sit in list_tasks's epic and sprint fields.",
-        });
-    }
-    catch (err) {
-        return errorResult(`list_structure failed: ${errorMessage(err)}`);
-    }
-}
-/**
- * RENAME OR ARCHIVE an epic or a sprint (I13).
- *
- * THE ARCHIVE RULE IS THE DATABASE'S, NOT THIS FUNCTION'S. A trigger refuses
- * archiving anything that still has unfinished work
- * (`app.guard_epic_archive` / `app.guard_sprint_archive`, SQLSTATE PT423). This
- * does not pre-check it — a client-side check would read a snapshot of a table
- * this write does not touch, so it can be stale, and duplicating the rule means
- * two places to keep in step. It translates the refusal instead.
- *
- * THE MACHINE TOKEN NEVER REACHES THE AGENT. The raise's message is
- * `epic_archive_blocked`, which the shipped web UI is explicit must never be
- * rendered; the SAME rule applies to a tool result, which is read by an agent
- * that will repeat it to the user. Keyed off SQLSTATE, exactly as
- * `archiveErrorMessage` in ProjectSettings.tsx does, and the sentence says what
- * would unblock it — the Gherkin asserts all three.
- */
-export async function updateStructureHandler(client, args) {
-    try {
-        const kind = typeof args.kind === 'string' ? args.kind.trim().toLowerCase() : '';
-        if (kind !== 'epic' && kind !== 'sprint') {
-            return errorResult(`update_structure: kind must be "epic" or "sprint", got "${args.kind ?? ''}". Nothing was changed.`);
-        }
-        const table = STRUCTURE_TABLE[kind];
-        const id = typeof args.id === 'string' ? args.id.trim() : '';
-        if (!id || !UUID_RE.test(id)) {
-            return errorResult(`update_structure: "${id}" is not a ${kind} id. Call list_structure to see them. Nothing was changed.`);
-        }
-        const name = typeof args.name === 'string' ? args.name.trim() : undefined;
-        if (args.name !== undefined && !name) {
-            return errorResult(`update_structure: name cannot be blank. Nothing was changed.`);
-        }
-        if (name === undefined && args.archived === undefined) {
-            return errorResult('update_structure: pass a new name, archived, or both — there is nothing to change. ' +
-                'Nothing was changed.');
-        }
-        const current = await must(client.from(table).select('id, project_id, name, archived_at').eq('id', id).maybeSingle());
-        if (!current) {
-            return errorResult(`update_structure: no ${kind} found for id "${id}". Nothing was changed.`);
-        }
-        /* THE SAME DUPLICATE-NAME RULE THE CREATE TOOLS ENFORCE. Without it, rename
-           is a way around the refusal `create_epic` gives — two live epics with one
-           name, reached by creating under a throwaway name and renaming. Scoped to
-           LIVE rows in the same project, and it ignores the row being renamed so
-           that setting a name to itself is not a conflict. */
-        if (name !== undefined && name.toLowerCase() !== current.name.trim().toLowerCase()) {
-            const siblings = (await must(client
-                .from(table)
-                .select('id, name')
-                .eq('project_id', current.project_id)
-                .is('archived_at', null))) ?? [];
-            const clash = siblings.find((row) => row.id !== id && row.name.trim().toLowerCase() === name.toLowerCase());
-            if (clash) {
-                return errorResult(`update_structure: a live ${kind} named "${clash.name}" already exists in this project ` +
-                    `(id ${clash.id}). Use that one, or pick a different name. Nothing was changed.`);
-            }
-        }
-        const patch = {};
-        if (name !== undefined)
-            patch.name = name;
-        /* THE DATABASE OWNS THE TIMESTAMP. The guard trigger coalesces whatever is
-           sent on the archiving transition to `now()`, so this sends a marker
-           instant rather than pretending to choose one; restoring sends null, which
-           the trigger leaves alone. */
-        if (args.archived !== undefined)
-            patch.archived_at = args.archived ? new Date().toISOString() : null;
-        const { data, error } = await client
-            .from(table)
-            .update(patch)
-            .eq('id', id)
-            .select('id, project_id, name, archived_at')
-            .maybeSingle();
-        if (error) {
-            /* PT423 — the archive guard. The sentence is OURS: the raise's message is
-               a machine token (`epic_archive_blocked`) and must never be repeated to
-               the user. The database's own `hint` says the same thing, but keying off
-               the stable SQLSTATE rather than parsing prose is what the web does. */
-            if (error.code === 'PT423') {
-                return errorResult(`update_structure: this ${kind} still has work items that are not done, so it cannot be ` +
-                    `archived. Finish them or move them to another ${kind} first, then archive it. ` +
-                    'Nothing was changed.');
-            }
-            throw new Error(error.message);
-        }
-        /* RLS REFUSING A WRITE RETURNS NO ERROR AND NO ROW — the silent-failure
-           shape this repo has been bitten by before. Reported as a refusal rather
-           than as success. */
-        if (!data) {
-            return errorResult(`update_structure: the ${kind} could not be changed — it may have been removed, or you may ` +
-                'not have permission. Nothing was changed.');
-        }
-        return textResult({
-            [kind]: data,
-            note: args.archived
-                ? `Archived. Its work items survive and keep their other placements.`
-                : 'Updated.',
-        });
-    }
-    catch (err) {
-        return errorResult(`update_structure failed: ${errorMessage(err)}`);
-    }
-}
 /* ═══════════════════════ 16d SLICE 3a — THE PERMISSION GATE ═══════════════
    `.implementations/z-done-16d-inbox-and-permission/ux.md` § "3a — One tool asks
    first, and waits".
@@ -8680,9 +8334,18 @@ export const TOOL_NAMES = [
     'create_epic',
     'create_sprint',
     // !Cleanup Phase 5 (I13, I14): the structure was write-only until these.
+    'search_agent_cards', 'list_structure_artifacts',
+    'get_structure_artifact',
+    'create_structure_artifact',
+    'update_structure_artifact',
     'list_structure',
     'update_structure',
     'place_work_item',
+    'list_artifact_folders',
+    'set_artifact_folder',
+    'list_work_item_dependencies',
+    'add_work_item_dependency',
+    'remove_work_item_dependency',
     'begin_work',
     'end_work',
     // 18c Slice 1: the run's own activity, unasked, on the request's card.
@@ -8935,6 +8598,7 @@ runTodoIdSource = null) {
         inputSchema: {
             workflow_tool_instance: z.string().uuid().optional().describe('The id of this tool mention in the active workflow stage. ' + WORKFLOW_TOOL_TEACHING),
             task_id: z.string(),
+            folder_name: z.string().max(80).nullable().optional().describe('Optional folder. Read list_artifact_folders first to reuse an existing name.'),
             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(),
@@ -9259,6 +8923,7 @@ runTodoIdSource = null) {
             "create_task's sprint_id.",
         inputSchema: {
             project_id: z.string().describe('Project id the sprint belongs to'),
+            description: z.string().optional(),
             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'),
@@ -9283,6 +8948,7 @@ runTodoIdSource = null) {
             'because they are not something to extend. To see where each work item already sits, read ' +
             "list_tasks's epic and sprint fields. Read-only.",
         inputSchema: {
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
             project_id: z.string().describe('Project whose epics and sprints to list'),
         },
     }, async (args) => {
@@ -9290,7 +8956,7 @@ runTodoIdSource = null) {
         return listStructureHandler(client, args);
     });
     server.registerTool('update_structure', {
-        description: 'Rename or archive an epic or a sprint, WITH THE USER\'S PERMISSION — nothing changes until ' +
+        description: 'Edit an epic or sprint name, description, dates, or archive state. Null clears a date; use target_date for epics and end_date for sprints. Follow workflow tool permission when provided. Otherwise nothing changes until ' +
             'they approve, and you will be asked to call again with identical arguments once they have. ' +
             'NEEDS AN OPEN WORK SESSION (begin_work) because the approval is recorded against it: if you ' +
             'have no work item to open one on, say what you would rename or archive and let the user do ' +
@@ -9303,8 +8969,13 @@ runTodoIdSource = null) {
             'rename is refused if another live epic or sprint of that project already carries the name, ' +
             'the same rule create_epic and create_sprint enforce.',
         inputSchema: {
+            workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING),
             kind: z.enum(['epic', 'sprint']).describe('Which kind of thing to change'),
             id: z.string().describe('Its id, from list_structure'),
+            description: z.string().optional(),
+            start_date: z.string().nullable().optional(),
+            end_date: z.string().nullable().optional(),
+            target_date: z.string().nullable().optional(),
             name: z.string().optional().describe('A new name. Omit to leave it alone'),
             archived: z
                 .boolean()
@@ -9320,10 +8991,76 @@ runTodoIdSource = null) {
            creating it, so it sits in the same class as `create_epic` and
            `create_sprint` rather than with `create_task`. */
         const structureArgs = args;
-        const what = structureArgs.archived === true ? 'Archive' : 'Rename';
-        return runGated(client, userId, openSessions.get(connectionId) ?? null, 'update_structure', structureArgs, `${what} the ${structureArgs.kind} ${structureArgs.name ? `to “${structureArgs.name}”` : ''}`.trim(), () => updateStructureHandler(client, structureArgs), 
-        // 18k Slice 10b — the run this call belongs to, so approving it resumes the work.
-        await runTodoIdOf());
+        const write = () => updateStructureHandler(client, structureArgs);
+        const summary = `${structureArgs.archived === true ? 'Archive' : structureArgs.archived === false ? 'Restore' : 'Update'} the ${structureArgs.kind} details`;
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'update_structure', args, write, async () => runGated(client, userId, openSessions.get(connectionId) ?? null, 'update_structure', args, summary, write, await runTodoIdOf()), await runTodoIdOf());
+    });
+    server.registerTool('search_agent_cards', {
+        description: 'Find your agent conversations by literal text in titles or messages, or by work item they worked on. Includes archived cards unless archived is specified. Follow next_offset to read every page. Read-only.',
+        inputSchema: { query: z.string().max(500).optional(), work_item_id: z.string().uuid().optional(), archived: z.boolean().optional(), limit: z.number().int().min(1).max(1000).optional(), offset: z.number().int().min(0).optional() },
+    }, async (args) => searchAgentCardsHandler(client, args));
+    server.registerTool('list_structure_artifacts', {
+        description: 'Read active artifacts attached directly to an epic or sprint.',
+        inputSchema: { kind: z.enum(['epic', 'sprint']), structure_id: z.string().uuid(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'list_structure_artifacts', args, () => listStructureArtifactsHandler(client, args.kind, args.structure_id), undefined, await runTodoIdOf());
+    });
+    server.registerTool('get_structure_artifact', {
+        description: 'Read a full epic or sprint artifact and its current revision.',
+        inputSchema: { artifact_id: z.string().uuid(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'get_structure_artifact', args, () => getStructureArtifactHandler(client, args.artifact_id), undefined, await runTodoIdOf());
+    });
+    server.registerTool('create_structure_artifact', {
+        description: 'Create a titled artifact on an epic or sprint. It appears on its management page.',
+        inputSchema: { kind: z.enum(['epic', 'sprint']), structure_id: z.string().uuid(), title: z.string().min(1).max(200), type: z.enum(['analysis', 'plan', 'spec', 'user_story', 'diagram', 'mock', 'wireframe']), format: z.enum(['md', 'html', 'json', 'svg']).optional(), content: z.string().min(1), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'create_structure_artifact', args, () => createStructureArtifactHandler(client, userId, args), undefined, await runTodoIdOf());
+    });
+    server.registerTool('update_structure_artifact', {
+        description: 'Update an epic or sprint artifact using the revision you read. Concurrent edits refuse without overwriting. archived=true removes it; false restores it.',
+        inputSchema: { artifact_id: z.string().uuid(), expected_revision: z.number().int().positive(), title: z.string().min(1).max(200).optional(), type: z.enum(['analysis', 'plan', 'spec', 'user_story', 'diagram', 'mock', 'wireframe']).optional(), format: z.enum(['md', 'html', 'json', 'svg']).optional(), content: z.string().optional(), archived: z.boolean().optional(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'update_structure_artifact', args, () => updateStructureArtifactHandler(client, args), undefined, await runTodoIdOf());
+    });
+    server.registerTool('list_artifact_folders', {
+        description: 'Read existing artifact folder names and counts on a work item before choosing a folder.',
+        inputSchema: { work_item_id: z.string().uuid(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'list_artifact_folders', args, () => listArtifactFoldersHandler(client, args.work_item_id), undefined, await runTodoIdOf());
+    });
+    server.registerTool('set_artifact_folder', {
+        description: 'Move an artifact into one folder, replacing its previous folder. Null clears it to Unfiled. Content and approval stay unchanged.',
+        inputSchema: { artifact_id: z.string().uuid(), folder_name: z.string().max(80).nullable(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'set_artifact_folder', args, () => setArtifactFolderHandler(client, args.artifact_id, args.folder_name), undefined, await runTodoIdOf());
+    });
+    server.registerTool('list_work_item_dependencies', {
+        description: 'Read blockers, dependents, and whether this work item is waiting.',
+        inputSchema: { work_item_id: z.string().uuid(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'list_work_item_dependencies', args, () => workItemDependencyHandler(client, 'list', args), undefined, await runTodoIdOf());
+    });
+    server.registerTool('add_work_item_dependency', {
+        description: 'Make work_item_id wait for depends_on_work_item_id to reach Done. Same-project work items only; self-links and cycles are refused.',
+        inputSchema: { work_item_id: z.string().uuid(), depends_on_work_item_id: z.string().uuid(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'add_work_item_dependency', args, () => workItemDependencyHandler(client, 'add', args), undefined, await runTodoIdOf());
+    });
+    server.registerTool('remove_work_item_dependency', {
+        description: 'Remove exactly this dependency edge without changing either work item status.',
+        inputSchema: { work_item_id: z.string().uuid(), depends_on_work_item_id: z.string().uuid(), workflow_tool_instance: z.string().uuid().optional().describe(WORKFLOW_TOOL_TEACHING) },
+    }, async (args) => {
+        touchSession(connectionId);
+        return runWorkflowTool(client, userId, openSessions.get(connectionId) ?? null, 'remove_work_item_dependency', args, () => workItemDependencyHandler(client, 'remove', args), undefined, await runTodoIdOf());
     });
     server.registerTool('place_work_item', {
         description: 'Move a work item into an epic and/or a sprint, after it was created. Pass work_item_id and ' +