@taiga-ai/mcp-server 0.16.0-dev.437 → 0.17.0-dev.438

package/dist/index.js

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
 import { McpServer, ProtocolError, ProtocolErrorCode, ResourceTemplate } from "@modelcontextprotocol/server";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -96,7 +97,7 @@ function seg(value) {
 * is one. Every value goes through URLSearchParams, so nothing a tool passes
 * can add a parameter of its own.
 */
-function query(params) {
+function query$1(params) {
 	const search = new URLSearchParams();
 	for (const [key, value] of Object.entries(params)) if (value !== void 0 && value !== null && value !== "") search.set(key, String(value));
 	const text = search.toString();
@@ -338,10 +339,10 @@ var TaigaClient = class {
 		return this.request("GET", `/products/${seg(productId)}/maintenance/summary`);
 	}
 	async listMaintenanceSweeps(productId, opts) {
-		return this.request("GET", `/products/${seg(productId)}/maintenance/runs${query({ limit: opts?.limit })}`);
+		return this.request("GET", `/products/${seg(productId)}/maintenance/runs${query$1({ limit: opts?.limit })}`);
 	}
 	async listFindings(productId, opts) {
-		return this.request("GET", `/products/${seg(productId)}/maintenance/findings${query({ ...opts })}`);
+		return this.request("GET", `/products/${seg(productId)}/maintenance/findings${query$1({ ...opts })}`);
 	}
 	async getFinding(id) {
 		return this.request("GET", `/maintenance/findings/${seg(id)}`);
@@ -367,7 +368,7 @@ var TaigaClient = class {
 	async listInbox(opts) {
 		const { productId, ...rest } = opts;
 		const path = productId ? `/products/${seg(productId)}/inbox` : "/inbox";
-		return this.request("GET", `${path}${query({ ...rest })}`);
+		return this.request("GET", `${path}${query$1({ ...rest })}`);
 	}
 	async updateInboxItem(id, body) {
 		return this.request("PATCH", `/inbox/${seg(id)}`, body);
@@ -375,10 +376,10 @@ var TaigaClient = class {
 	async listSetupTasks(opts) {
 		const { productId, ...rest } = opts;
 		const path = productId ? `/products/${seg(productId)}/setup-tasks` : "/setup-tasks";
-		return this.request("GET", `${path}${query({ ...rest })}`);
+		return this.request("GET", `${path}${query$1({ ...rest })}`);
 	}
 	async listEnvironments(productId, opts) {
-		return this.request("GET", `/products/${seg(productId)}/environments${query({ ...opts })}`);
+		return this.request("GET", `/products/${seg(productId)}/environments${query$1({ ...opts })}`);
 	}
 	async createEnvironment(productId, body) {
 		return this.request("POST", `/products/${seg(productId)}/environments`, body);
@@ -390,13 +391,13 @@ var TaigaClient = class {
 		return this.request("GET", `/products/${seg(productId)}/deployments/current`);
 	}
 	async listDeployments(productId, opts) {
-		return this.request("GET", `/products/${seg(productId)}/deployments${query({ ...opts })}`);
+		return this.request("GET", `/products/${seg(productId)}/deployments${query$1({ ...opts })}`);
 	}
 	async getDeploymentSyncStatus(productId) {
 		return this.request("GET", `/products/${seg(productId)}/deployments/sync-status`);
 	}
 	async getDeliveryMetrics(productId, environmentId, windowDays) {
-		return this.request("GET", `/products/${seg(productId)}/deployments/insights${query({
+		return this.request("GET", `/products/${seg(productId)}/deployments/insights${query$1({
 			environmentId,
 			windowDays
 		})}`);
@@ -405,14 +406,14 @@ var TaigaClient = class {
 		return this.request("GET", `/products/${seg(productId)}/monitoring/health`);
 	}
 	async getMonitoringSignal(productId, signal, environmentId, windowDays) {
-		return this.request("GET", `/products/${seg(productId)}/monitoring/${signal}${query({
+		return this.request("GET", `/products/${seg(productId)}/monitoring/${signal}${query$1({
 			environmentId,
 			windowDays
 		})}`);
 	}
 	async listKnowledge(opts) {
 		const scope = (value) => value === null ? "null" : value;
-		return this.request("GET", `/custom-documents${query({
+		return this.request("GET", `/custom-documents${query$1({
 			...opts,
 			factoryId: scope(opts.factoryId),
 			productId: scope(opts.productId)
@@ -464,7 +465,7 @@ var TaigaClient = class {
 		return this.request("POST", "/products", body);
 	}
 	async previewProductMove(productId, factoryId) {
-		return this.request("GET", `/products/${seg(productId)}/factory/preview${query({ factoryId })}`);
+		return this.request("GET", `/products/${seg(productId)}/factory/preview${query$1({ factoryId })}`);
 	}
 	async moveProduct(productId, body) {
 		return this.request("PUT", `/products/${seg(productId)}/factory`, body);
@@ -486,7 +487,7 @@ var TaigaClient = class {
 		const data = [];
 		let cursor;
 		do {
-			const result = await this.request("GET", `/github/installations${query({
+			const result = await this.request("GET", `/github/installations${query$1({
 				limit: 100,
 				cursor
 			})}`);
@@ -496,7 +497,7 @@ var TaigaClient = class {
 		return { data };
 	}
 	async listInstallationRepositories(installationId, opts) {
-		return this.request("GET", `/github/installations/${seg(installationId)}/repositories${query({ ...opts })}`);
+		return this.request("GET", `/github/installations/${seg(installationId)}/repositories${query$1({ ...opts })}`);
 	}
 	async linkRepository(productId, body) {
 		return this.request("POST", `/products/${seg(productId)}/repositories`, body);
@@ -569,7 +570,15 @@ const OPERATE_SETTING = {
 //#endregion
 //#region src/tools/inputs.ts
 /** The inputs several tools share, so a product or a page is named the same way everywhere. */
-const productId = z.string().uuid().describe("Product ID -- taiga_get_product_context, taiga_resolve_product or taiga_list_products give it");
+/**
+* An ID input whose refusal says where the ID comes from. The client shows the
+* schema's message, not the description, when a call fails validation, and
+* "Invalid UUID" alone sends a model that passed a name to guess again.
+*/
+function idInput(what, from) {
+	return z.string().uuid({ message: `A ${what} ID is a UUID, not a name: ${from}` }).describe(`${what[0].toUpperCase()}${what.slice(1)} ID -- ${from}`);
+}
+const productId = idInput("product", "taiga_list_products (query finds one by name), taiga_resolve_product or taiga_get_product_context give it");
 /** The page inputs every list tool takes; `nextCursor` of one page is the `cursor` of the next. */
 const pagination = {
 	limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)"),
@@ -2111,14 +2120,91 @@ function emptyOriginNote(origin, product) {
 	if (origin === "plan") return imported ? `This product was imported, so no discovery chain was generated for it: its derived documents are on the reality side. Only the documents a person writes (${PLAN_ONLY_DOCUMENT_TYPES.map(productDocumentName).join(", ")}) would appear here.` : "No plan documents are published yet: they are written during discovery in Taiga.";
 	if (!imported) return "No reality documents yet: they are derived from the code once the first initiative is done (a merged pull request marks it done) or the repository is pushed to. Until then read the plan side.";
 	switch (importStatusOf(product)) {
-		case "pending": return "No reality documents yet: the import has not started. Link the repository and run the import in Taiga.";
+		case "pending": return "No reality documents yet: the import has not started. Link the repository, then taiga_start_import.";
 		case "analyzing":
 		case "generating_docs": return "No reality documents yet: the import is running and will derive them from the code.";
-		case "cancelled": return "No reality documents: the import was cancelled before it derived any. Run it again in Taiga.";
-		case "failed": return "No reality documents: the import failed before it derived any. Run it again in Taiga.";
+		case "cancelled": return "No reality documents: the import was cancelled before it derived any. taiga_start_import runs it again.";
+		case "failed": return "No reality documents: the import failed before it derived any. taiga_start_import runs it again.";
 		default: return "No reality documents: the import derives them from the code, and none have been published.";
 	}
 }
+/**
+* What a product in setup waits for, as the next call to make. Nothing on a
+* draft product says it otherwise: discoveryStep names the step and
+* importStatus the import, and the way on from each lives in tool
+* descriptions an agent reads only when it already knows which. Null once the
+* product is active.
+*/
+function setupNextStep(product) {
+	if (product?.status !== "draft") return null;
+	if (isImportedProduct(product)) switch (importStatusOf(product)) {
+		case "analyzing":
+		case "generating_docs": return "The import is running and derives the documents from the code (taiga_wait_for_job follows its job). Then review them, and taiga_finish_discovery opens the product.";
+		case "complete": return "The import is done: review the reality documents (taiga_list_product_documents), then taiga_finish_discovery opens the product.";
+		case "failed":
+		case "cancelled": return "The last import did not finish: taiga_start_import runs it again.";
+		default: return "Link its repository if it has none (taiga_list_linkable_repositories, taiga_link_repository), then taiga_start_import: the import derives the documents from the code and runs by itself.";
+	}
+	if (product.discoveryStep === void 0) return null;
+	switch (product.discoveryStep) {
+		case "documents": return "The specification is done; the other documents are generated from it (taiga_generate_product_documents starts the ones still missing). Once every required one is published, taiga_finish_discovery opens the product.";
+		case "checks": return "The documents are published; the checks are stamped in the web, then taiga_finish_discovery opens the product.";
+		default: return "Discovery is a conversation held in the web: the person describes the product there and the specification comes out of it. The other documents follow, then taiga_finish_discovery opens the product.";
+	}
+}
+/** What discoveryStep says, for a description that shows it. */
+const DISCOVERY_STEP_MEANING = "discoveryStep is where a product in setup is: context (not started), conversation or import (the specification is being talked out, or derived from the code), documents (the rest being generated and reviewed), checks (stamped in the web); null once it is active.";
+//#endregion
+//#region src/tools/hints.ts
+/**
+* The next step after the API answers 404. The API's own word is bare
+* ("Backlog item not found", "Repository link not found"), and an agent that
+* hears only that guesses another ID, or a name. Each ID a tool takes names
+* the tool that lists the right ones; the tool's arguments say which apply.
+*/
+const BY_ARGUMENT = {
+	itemId: "taiga_list_backlog_items lists a product's initiatives with their IDs; a run or plan ID is not one.",
+	backlogItemId: "taiga_list_backlog_items lists a product's initiatives with their IDs.",
+	buildId: "taiga_list_builds lists the runs, of one product or of every product the key can see.",
+	planId: "taiga_get_plan gives the initiative's active plan and its ID.",
+	repositoryId: "taiga_list_product_repositories lists the product's repository links; a GitHub repository id is not a link ID.",
+	replacesRepositoryId: "taiga_list_product_repositories lists the product's repository links.",
+	githubRepositoryId: "taiga_list_linkable_repositories lists the repositories the GitHub connection reaches, with their ids.",
+	installationId: "taiga_list_linkable_repositories lists the connected GitHub accounts.",
+	jobId: "A job ID is what the tool that started the job returned (taiga_request_initiatives, taiga_start_import).",
+	factoryId: "taiga_list_factories lists the factories the key can see.",
+	findingId: "taiga_list_findings lists a product's findings.",
+	violationId: "taiga_get_policy_standing lists a product's policy violations.",
+	environmentId: "taiga_get_deployments lists the product's environments with their IDs; a product ID is not one.",
+	knowledgeId: "taiga_list_knowledge lists the knowledge files.",
+	productId: "taiga_list_products lists the products the key can see; a name is not an ID (taiga_get_product takes a slug)."
+};
+/** Where an argument means something else on one tool, or the tool's 404 needs its own word. */
+const BY_TOOL = {
+	taiga_resolve_action: () => "taiga_list_action_required lists the items with their IDs.",
+	taiga_get_plan: (said) => /\bplan\b/i.test(said) ? "taiga_get_backlog_item says whether one is being generated (planningStatus planning) or failed, and taiga_plan_again asks for a new one." : BY_ARGUMENT.itemId
+};
+/** The hint for a 404 from one tool call: the tool's own, else one per ID it was given. */
+function notFoundHint(tool, args) {
+	if (BY_TOOL[tool]) return BY_TOOL[tool];
+	if (typeof args !== "object" || args === null) return void 0;
+	const given = Object.keys(args).filter((key) => args[key] != null && BY_ARGUMENT[key]);
+	given.sort((a, b) => Number(a === "productId") - Number(b === "productId"));
+	if (given.length === 0) return void 0;
+	const hint = given.map((key) => BY_ARGUMENT[key]).join(" ");
+	return () => hint;
+}
+/** The hint of the tool call in progress, read by runTool when the API answers 404. */
+const notFoundHints = new AsyncLocalStorage();
+/** The API's 404 message with the hint of the call in progress, if it has one. */
+function withNotFoundHint(said) {
+	const hint = notFoundHints.getStore()?.(said);
+	return hint ? `${withStop(said)} ${hint}` : said;
+}
+/** A sentence ends in a stop before the next one is added to it. */
+function withStop(text) {
+	return /[.!?]$/.test(text.trimEnd()) ? text.trimEnd() : `${text.trimEnd()}.`;
+}
 //#endregion
 //#region src/tools/errors.ts
 /** A successful tool result: one JSON text block the model reads. */
@@ -2162,21 +2248,19 @@ function networkFailureDetail(error) {
 	const why = typeof cause?.code === "string" ? cause.code : typeof cause?.message === "string" ? cause.message : null;
 	return why ? `${error.message} (${why})` : error.message;
 }
+/**
+* The code a status implies when the API sent none. 400 is VALIDATION_ERROR,
+* the code the API itself sends, so a refusal by this server and one by the
+* API read the same.
+*/
 const CODE_BY_STATUS = {
-	400: "VALIDATION_FAILED",
+	400: "VALIDATION_ERROR",
 	401: "UNAUTHENTICATED",
 	403: "FORBIDDEN",
 	404: "NOT_FOUND",
 	409: "CONFLICT",
 	429: "RATE_LIMITED"
 };
-/**
-* Run a tool handler and turn a failure into a structured error. An API
-* refusal keeps the API's own code when it sent one and its message whole:
-* on a refused publish that names the section holding template residue,
-* which is what the model needs to fix the draft. A failed connection is
-* structured too, so every failure the model sees has the same shape.
-*/
 /** What the API said, in one phrase: the status, the code it sent (or the one its status implies), its message. */
 function apiFailureText(error) {
 	return `${error.status} ${apiFailureCode(error)}${error.apiMessage ? `: ${error.apiMessage}` : ""}`;
@@ -2189,11 +2273,22 @@ function apiFailureCode(error) {
 function isMissOrRefusal(error) {
 	return error instanceof TaigaApiError && (error.status === 404 || error.status === 403);
 }
+/**
+* Run a tool handler and turn a failure into a structured error. An API
+* refusal keeps the API's own code when it sent one and its message whole:
+* on a refused publish that names the section holding template residue,
+* which is what the model needs to fix the draft. A failed connection is
+* structured too, so every failure the model sees has the same shape.
+*/
 async function runTool(handler) {
 	try {
 		return await handler();
 	} catch (error) {
-		if (error instanceof TaigaApiError) return toolError(error.code ?? CODE_BY_STATUS[error.status] ?? "API_ERROR", error.apiMessage ?? `Taiga API answered ${error.status}.`, error.details);
+		if (error instanceof TaigaApiError) {
+			const code = error.code ?? CODE_BY_STATUS[error.status] ?? "API_ERROR";
+			const said = error.apiMessage ?? `Taiga API answered ${error.status}.`;
+			return toolError(code, error.status === 404 ? withNotFoundHint(said) : said, error.details);
+		}
 		if (isNetworkFailure(error)) return toolError("NETWORK_ERROR", `Could not reach the Taiga API: ${networkFailureDetail(error)}. Check TAIGA_API_URL.`);
 		throw error;
 	}
@@ -2374,6 +2469,24 @@ function budgetSections(doc, budget) {
 	}
 	return cutTo(doc, sections, Object.fromEntries(kept));
 }
+/**
+* The answer to a read that names sections: the ones the document has, the
+* rest listed with their sizes, and the asked-for ids it lacks under
+* unknownSections. One wrong id does not throw away the right ones (the
+* model retries only the miss); none right is a miss that lists the real ids.
+*/
+function sectionReadResult(doc, ids, label) {
+	const cut = pickSections(doc, new Set(ids));
+	if (!cut) return toolError("VALIDATION_ERROR", `The ${label} is not made of sections; read it without sections.`);
+	const all = Object.keys(sectionsOf(doc.data) ?? {});
+	const unknownSections = ids.filter((id) => !all.includes(id));
+	if (unknownSections.length === ids.length) return toolError("NOT_FOUND", `The ${label} has no section ${ids.join(", ")}; its sections are ${all.join(", ")}.`);
+	return toolResult({
+		...cut.doc,
+		omittedSections: cut.omittedSections,
+		...unknownSections.length > 0 ? { unknownSections } : {}
+	});
+}
 //#endregion
 //#region src/tools/summarize.ts
 /**
@@ -2419,6 +2532,44 @@ function itemRows(items, fields) {
 		criteria: criteriaCounts(items[index])
 	} : row);
 }
+/** Pages a name search reads before it stops and says so: 1,000 rows at the API's page ceiling. */
+const SEARCH_PAGE_LIMIT = 10;
+/**
+* Rows whose text contains `query`, ignoring case, read page by page until
+* `limit` match or the rows run out. The API has no name search, and a model
+* told the person's word for a thing ("the Sandbox factory") otherwise pages
+* the whole list to find its ID. `more` is true when it stopped before the end.
+*/
+async function searchPages(fetchPage, query, text, limit) {
+	const needle = query.toLowerCase();
+	const rows = [];
+	let cursor;
+	for (let index = 0; index < SEARCH_PAGE_LIMIT; index += 1) {
+		const result = await fetchPage(cursor);
+		const page = result.data;
+		for (const [at, row] of page.entries()) {
+			if (!text(row).some((value) => typeof value === "string" && value.toLowerCase().includes(needle))) continue;
+			rows.push(row);
+			if (rows.length === limit) return {
+				rows,
+				more: at < page.length - 1 || result.nextCursor !== null
+			};
+		}
+		if (!result.nextCursor) return {
+			rows,
+			more: false
+		};
+		cursor = result.nextCursor;
+	}
+	return {
+		rows,
+		more: true
+	};
+}
+/** A search reads its own pages, so a cursor from a plain page has nothing to continue. */
+const SEARCH_WITH_CURSOR = "A search answers one page; narrow the query instead of paging it.";
+/** What a search says when it stopped before reading every row. */
+const SEARCH_NOTE = "There may be more matches than the limit carries; narrow the query or raise the limit.";
 //#endregion
 //#region src/tools/products.ts
 /** What a product row needs to say for the model to pick one and read it in full. */
@@ -2428,9 +2579,10 @@ const PRODUCT_SUMMARY_FIELDS = [
 	"slug",
 	"status",
 	"factoryId",
-	"kind",
 	"discoveryStep"
 ];
+/** A list's name search: part of a name, any case. */
+const query = (what) => z.string().trim().min(1).max(200).optional().describe(`Part of the ${what}, any case: only the rows that contain it`);
 /**
 * What a document row needs to say for the model to pick one and read it in
 * full: which document, on which timeline, how current. Not the derived-from
@@ -2577,7 +2729,7 @@ async function resolveProductRef(client, ref, accepted, usage) {
 	].filter((v) => v !== void 0).length;
 	if (given !== 1) {
 		const how = given === 0 ? usage ?? "taiga_list_products shows what exists." : "Two names could mean two products.";
-		return refusal("VALIDATION_FAILED", `Name the product exactly once: ${accepted.join(" or ")}. ${how}`);
+		return refusal("VALIDATION_ERROR", `Name the product exactly once: ${accepted.join(" or ")}. ${how}`);
 	}
 	if (ref.productId) try {
 		return { product: (await client.getProduct(ref.productId)).data };
@@ -2606,30 +2758,59 @@ async function resolveProductRef(client, ref, accepted, usage) {
 function registerProductTools(server, client) {
 	if (client.hasCapability("factories:read")) server.registerTool("taiga_list_factories", {
 		title: "List factories",
-		description: "List all factories in the organization. A factory is the group that owns a set of products. Use this to find factory IDs for reading factory instructions. Factory instructions carry the factory's standing guidance: domain context, tech preferences, and the conventions its products follow.",
-		inputSchema: z.object({ ...pagination }),
+		description: "List all factories in the organization. A factory is the group that owns a set of products. Use this to find factory IDs for reading factory instructions; query finds one by name. Factory instructions carry the factory's standing guidance: domain context, tech preferences, and the conventions its products follow.",
+		inputSchema: z.object({
+			query: query("factory name"),
+			...pagination
+		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		const result = await client.listFactories(params);
-		return toolResult(page(result.data, result.nextCursor));
+		if (params.query === void 0) {
+			const result = await client.listFactories(params);
+			return toolResult(page(result.data, result.nextCursor));
+		}
+		if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", SEARCH_WITH_CURSOR);
+		const found = await searchPages((cursor) => client.listFactories({
+			limit: 100,
+			cursor
+		}), params.query, (row) => [row.name, row.slug], params.limit ?? 25);
+		return toolResult({
+			...page(found.rows, null),
+			...found.more ? { more: SEARCH_NOTE } : {}
+		});
 	}));
 	if (client.hasCapability("products:read")) {
 		server.registerTool("taiga_list_products", {
 			title: "List products",
-			description: "List products in the organization, as summaries (id, name, slug, status, factory, kind). Use this to find a product by name; inside a git checkout, taiga_resolve_product finds it from the remote URL instead. taiga_get_product reads one in full.",
+			description: `List products in the organization, as summaries (id, name, slug, status, factory, discoveryStep). Use this to find a product by name (query); inside a git checkout, taiga_resolve_product finds it from the remote URL instead. taiga_get_product reads one in full. ${DISCOVERY_STEP_MEANING}`,
 			inputSchema: z.object({
-				factoryId: z.string().uuid().optional().describe("Filter by factory ID -- get factory IDs from taiga_list_factories"),
+				query: query("product name or slug"),
+				factoryId: idInput("factory", "taiga_list_factories (query finds one by name) gives it").optional().describe("Only the products of this factory"),
 				status: z.enum(PRODUCT_STATUSES).optional().describe("Filter by status: draft until the product finishes setup in Taiga, active after that, archived when retired."),
 				...pagination
 			}),
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			const result = await client.listProducts(params);
-			return toolResult(page(pickFields(result.data, PRODUCT_SUMMARY_FIELDS), result.nextCursor));
+			const { query: text, ...filters } = params;
+			if (text === void 0) {
+				const result = await client.listProducts(filters);
+				return toolResult(page(pickFields(result.data, PRODUCT_SUMMARY_FIELDS), result.nextCursor));
+			}
+			if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", SEARCH_WITH_CURSOR);
+			const found = await searchPages((cursor) => client.listProducts({
+				factoryId: filters.factoryId,
+				status: filters.status,
+				limit: 100,
+				cursor
+			}), text, (row) => [row.name, row.slug], params.limit ?? 25);
+			return toolResult({
+				...page(pickFields(found.rows, PRODUCT_SUMMARY_FIELDS), null),
+				...found.more ? { more: SEARCH_NOTE } : {}
+			});
 		}));
 		server.registerTool("taiga_get_product", {
 			title: "Get product",
-			description: "Get one product in full, by ID or by slug: name, slug, factory, what Taiga owns for it (application, infrastructure, deployment) and its settings; the list and resolve tools carry summaries. Use taiga_list_product_documents for its specification and design, taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did.",
+			description: "Get one product in full, by ID or by slug: name, slug, factory, what Taiga owns for it (application, infrastructure, deployment) and its settings; the list and resolve tools carry summaries; taiga_get_product_context carries this summary with the rest a session starts from. Use taiga_list_product_documents for its specification and design, taiga_list_backlog_items for its work and taiga_list_builds for what the coding agent did. A product still in setup carries nextStep: what it waits for and the call that moves it on.",
 			inputSchema: z.object({
 				productId: productId.optional(),
 				slug: slug.optional()
@@ -2637,7 +2818,12 @@ function registerProductTools(server, client) {
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
 			const resolved = await resolveProductRef(client, params, ["productId", "slug"]);
-			return "refusal" in resolved ? toolError(resolved.refusal.code, resolved.refusal.message) : toolResult(resolved.product);
+			if ("refusal" in resolved) return toolError(resolved.refusal.code, resolved.refusal.message);
+			const nextStep = setupNextStep(resolved.product);
+			return toolResult(nextStep ? {
+				...resolved.product,
+				nextStep
+			} : resolved.product);
 		}));
 		server.registerTool("taiga_resolve_product", {
 			title: "Resolve product from git remote",
@@ -2667,7 +2853,7 @@ function registerProductTools(server, client) {
 		}));
 		server.registerTool("taiga_get_product_document", {
 			title: "Get product document",
-			description: "Get the full content of one product document from one timeline. Read the plan to learn what to build: specification (requirements), architecture (design), threat_model (security risks), technology_decisions. Read reality, when the product has it, to learn what the code actually does before changing it. Omit origin for the product's own timeline. A large document runs to tens of thousands of characters: name the sections you need (the ids taiga_get_product_context lists) and the read carries only those, listing the rest with their sizes. A read that finds nothing says which documents and timelines the product does have.",
+			description: "Get the full content of one product document from one timeline. Read the plan to learn what to build: specification (requirements), architecture (design), threat_model (security risks), technology_decisions. Read reality, when the product has it, to learn what the code actually does before changing it. Omit origin for the product's own timeline. A large document runs to tens of thousands of characters: name the sections you need (the ids taiga_get_product_context lists) and the read carries only those, listing the rest with their sizes and any id the document lacks (unknownSections). A read that finds nothing says which documents and timelines the product does have.",
 			inputSchema: z.object({
 				productId,
 				type: z.enum(PRODUCT_DOCUMENT_TYPES).describe("Document type -- taiga_list_product_documents shows which ones the product has"),
@@ -2682,15 +2868,7 @@ function registerProductTools(server, client) {
 			try {
 				const doc = stripProvenance((await client.getProductDocument(params.productId, params.type, origin)).data);
 				if (!params.sections) return toolResult(doc);
-				const cut = pickSections(doc, new Set(params.sections));
-				if (!cut) return toolError("VALIDATION_FAILED", `The ${origin} ${params.type} is not made of sections; read it without sections.`);
-				const all = Object.keys(doc.data.sections);
-				const unknown = params.sections.filter((id) => !all.includes(id));
-				if (unknown.length > 0) return toolError("NOT_FOUND", `The ${origin} ${params.type} has no section ${unknown.join(", ")}; its sections are ${all.join(", ")}.`);
-				return toolResult({
-					...cut.doc,
-					omittedSections: cut.omittedSections
-				});
+				return sectionReadResult(doc, params.sections, `${origin} ${params.type}`);
 			} catch (error) {
 				if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
 				product ??= (await client.getProduct(params.productId)).data;
@@ -2812,12 +2990,16 @@ function registerDocumentTools(server, client) {
 		}));
 		server.registerTool("taiga_get_document", {
 			title: "Get company document",
-			description: "Get the full content of one of the organization's documents, sections included. Use this when you need the security requirements, data handling rules, architecture standards or compliance controls that apply to your code, or the goals, standards and voice the organization has set down. A read that finds nothing says which documents are published and whether a draft exists.",
-			inputSchema: z.object({ type: tenantDocumentType }),
+			description: "Get the full content of one of the organization's documents, sections included. Use this when you need the security requirements, data handling rules, architecture standards or compliance controls that apply to your code, or the goals, standards and voice the organization has set down. A policy runs to thousands of tokens: name the sections you need (the ids taiga_get_product_context lists for every policy) and the read carries only those, listing the rest with their sizes and any id the document lacks (unknownSections). A read that finds nothing says which documents are published and whether a draft exists.",
+			inputSchema: z.object({
+				type: tenantDocumentType,
+				sections: z.array(z.string().min(1).max(200)).min(1).max(50).optional().describe("Only these sections, by id; omit for the whole document")
+			}),
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
 			try {
-				return toolResult(stripProvenance((await client.getTenantDocument(params.type)).data));
+				const doc = stripProvenance((await client.getTenantDocument(params.type)).data);
+				return params.sections ? sectionReadResult(doc, params.sections, params.type) : toolResult(doc);
 			} catch (error) {
 				if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
 				const [draft, all] = await Promise.allSettled([client.getTenantDocumentDraft(params.type), client.listTenantDocuments({ limit: 100 })]);
@@ -2861,7 +3043,7 @@ function registerDocumentTools(server, client) {
 			title: "List factory documents",
 			description: `List a factory's documents, published and draft, as summaries (type, name, version, draft state). A factory has one document type, ${named(FACTORY_DOCUMENT_TYPES)}: its free-form standing guidance (domain context, tech preferences, conventions) that applies to every product it owns. Drafts are listed too (isDraft true); an empty list means neither a publication nor a draft exists. Use taiga_get_factory_document to read the full content.`,
 			inputSchema: z.object({
-				factoryId: z.string().uuid().describe("Factory ID -- get from taiga_list_factories"),
+				factoryId: idInput("factory", "taiga_list_factories (query finds one by name) gives it"),
 				...pagination
 			}),
 			annotations: READ_ONLY
@@ -2873,7 +3055,7 @@ function registerDocumentTools(server, client) {
 			title: "Get factory instructions",
 			description: "Get the full content of a factory's instructions. Use this when you need the domain context, tech preferences, or conventions the factory expects every product it owns to follow. A read that finds nothing says whether a draft exists and how to write one.",
 			inputSchema: z.object({
-				factoryId: z.string().uuid().describe("Factory ID -- get from taiga_list_factories"),
+				factoryId: idInput("factory", "taiga_list_factories (query finds one by name) gives it"),
 				type: z.enum(FACTORY_DOCUMENT_TYPES).default("factory_instructions").describe("Document type")
 			}),
 			annotations: READ_ONLY
@@ -2898,7 +3080,7 @@ function registerDocumentTools(server, client) {
 			saveDraft: (data) => client.saveFactoryDocumentDraft(factoryId, type, { data }),
 			publish: () => client.publishFactoryDocument(factoryId, type)
 		});
-		const factoryId = z.string().uuid().describe("Factory ID -- get from taiga_list_factories");
+		const factoryId = idInput("factory", "taiga_list_factories (query finds one by name) gives it");
 		const factoryDocumentType = z.enum(FACTORY_DOCUMENT_TYPES).default("factory_instructions").describe("Document type");
 		server.registerTool("taiga_update_factory_document", {
 			title: "Update a section of factory instructions",
@@ -2993,7 +3175,7 @@ function registerJobTools(server, client) {
 	server.registerTool("taiga_get_job", {
 		title: "Get an agent job",
 		description: "Read one agent job: background work a person asked an agent for, such as an initiative request (taiga_request_initiatives). It says where the job is (pending, processing, completed, failed, cancelled), its progress and any error. A finished initiative request also says what came of it: the initiatives it added, or why it added none (already covered by an existing initiative, not readable as work, outside the product, or not allowed by a policy, with the policy, the line it runs into and the way to decide otherwise). taiga_wait_for_job waits for a job to finish.",
-		inputSchema: z.object({ jobId: z.string().uuid().describe("Agent job ID -- a request tool returns it") }),
+		inputSchema: z.object({ jobId: idInput("job", "the tool that started the job returned it") }),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => toolResult(jobReport((await client.getAgentJob(params.jobId)).data))));
 }
@@ -3214,7 +3396,8 @@ const ITEM_OUTCOME_FIELDS = [
 	"archivedAt",
 	"lifecycle"
 ];
-const itemId = z.string().uuid().describe("Backlog item ID -- get from taiga_list_backlog_items");
+const planId = idInput("plan", "taiga_get_plan gives the initiative's active plan and its ID");
+const itemId = idInput("backlog item", "taiga_list_backlog_items (query finds one by title) gives it");
 /** The plan without its steps' prose: enough to approve it or say what a run will do. */
 const PLAN_SUMMARY_FIELDS = [
 	"id",
@@ -3274,9 +3457,10 @@ function registerBacklogTools(server, client) {
 function registerBacklogReads(server, client) {
 	server.registerTool("taiga_list_backlog_items", {
 		title: "List backlog items",
-		description: "List a product's backlog items (initiatives): titles, category, status, where each one is on the line (backlog, todo, queue, plan, build, done) and criteria, how many of its acceptance criteria are met (null before it is planned). Use this to find the item you are working on, then read its acceptance criteria and technical context with taiga_get_backlog_item. Archived items are left out unless asked for.",
+		description: "List a product's backlog items (initiatives): titles, category, status, where each one is on the line (backlog, todo, queue, plan, build, done) and criteria, how many of its acceptance criteria are met (null before it is planned; met counts the criteria the agent confirmed with evidence or a person checked off, so a done item can show fewer met than it has). Use this to find the item you are working on (query finds one by title), then read its acceptance criteria and technical context with taiga_get_backlog_item. Archived items are left out unless asked for.",
 		inputSchema: z.object({
 			productId,
+			query: z.string().trim().min(1).max(200).optional().describe("Part of the title, any case: only the items that contain it"),
 			status: z.enum([
 				"backlog",
 				"in_progress",
@@ -3300,13 +3484,26 @@ function registerBacklogReads(server, client) {
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		const result = await client.listBacklogItems(params.productId, params);
-		return toolResult(page(itemRows(result.data, BACKLOG_SUMMARY_FIELDS), result.nextCursor));
+		const { query, ...filters } = params;
+		if (query === void 0) {
+			const result = await client.listBacklogItems(params.productId, filters);
+			return toolResult(page(itemRows(result.data, BACKLOG_SUMMARY_FIELDS), result.nextCursor));
+		}
+		if (params.cursor !== void 0) return toolError("VALIDATION_ERROR", SEARCH_WITH_CURSOR);
+		const found = await searchPages((cursor) => client.listBacklogItems(params.productId, {
+			...filters,
+			limit: 100,
+			cursor
+		}), query, (row) => [row.title], params.limit ?? 25);
+		return toolResult({
+			...page(itemRows(found.rows, BACKLOG_SUMMARY_FIELDS), null),
+			...found.more ? { more: SEARCH_NOTE } : {}
+		});
 	}));
 	server.registerTool("taiga_get_backlog_item", {
 		title: "Get backlog item",
-		description: "Get one backlog item in full: description, acceptance criteria (and which are met), technical context (patterns, constraints, and the assumptions to verify before starting), dependencies and source documents. Read this before implementing an item, and read its runs with taiga_list_builds to see what the coding agent already did.",
-		inputSchema: z.object({ itemId: z.string().uuid().describe("Backlog item ID -- get from taiga_list_backlog_items") }),
+		description: "Get one backlog item in full: description, acceptance criteria (and which are met), technical context (patterns, constraints, and the assumptions to verify before starting), dependencies and source documents. Read this before implementing an item, and read its runs with taiga_list_builds to see what the coding agent already did. lifecycle says whose turn it is and what moves it on: cta start_plan is taiga_queue_backlog_item, retry_plan taiga_plan_again (planFailureCause says why the plan stopped), start_build taiga_approve_plan, resume_build taiga_resume_backlog_item, retry_build a fresh run (start over, in the web), review_pr and view_pr the pull request. needsHumanCause is set only when the line stopped on it.",
+		inputSchema: z.object({ itemId }),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
 		return toolResult((await client.getBacklogItem(params.itemId)).data);
@@ -3357,7 +3554,7 @@ function registerMove(server, client) {
 		inputSchema: z.object({
 			itemId,
 			state: z.enum(USER_DROP_STATES).describe("The column to move into"),
-			afterId: z.string().uuid().nullable().optional().describe("The initiative to follow in that column; null for the head; omit to keep rank order"),
+			afterId: idInput("backlog item", "taiga_list_backlog_items gives it").nullable().optional().describe("The initiative to follow in that column; null for the head; omit to keep rank order"),
 			archived: z.boolean().optional().describe("true files the initiative where it stands, false brings it back; omit to leave as is")
 		}),
 		annotations: OPERATE
@@ -3434,7 +3631,7 @@ function registerQueue(server, client) {
 		description: "Add an initiative to the product queue, the line the coding agent works: queued initiatives are planned and built one at a time, each advancing when the previous pull request merges. This starts paid work: a planner run, then a coding run that pushes commits and opens a pull request in the product repository. Whether the plan is built at once or waits for a person is the initiative's review gate: pass autoBuild: false to read the plan before anything is built (the product's default applies otherwise, and the outcome says which it is); the gate is set first and stays set if the move is then refused. Ask the person before calling this. An initiative already in the queue stays where it is unless afterId says where to go; one being planned or built cannot move (CONFLICT). Returns the initiative with its new state, its review gate and its place in the queue.",
 		inputSchema: z.object({
 			itemId,
-			afterId: z.string().uuid().nullable().optional().describe("The queued initiative to follow; null for the head of the queue; omit to append a new entry or leave a queued one where it is"),
+			afterId: idInput("backlog item", "taiga_list_backlog_items gives it").nullable().optional().describe("The queued initiative to follow; null for the head of the queue; omit to append a new entry or leave a queued one where it is"),
 			autoBuild: autoBuildInput.optional().describe("Set the initiative's review gate before queueing: false to read the plan first, true to build it at once, null to follow the product; omit to leave the gate as it is")
 		}),
 		annotations: OPERATE
@@ -3476,7 +3673,7 @@ function registerReviewGate(server, client) {
 function registerResume(server, client) {
 	server.registerTool("taiga_resume_backlog_item", {
 		title: "Resume backlog item",
-		description: "Resume an initiative the line stopped on (needsHumanCause is set): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first incomplete step (the steps already committed are kept), a refused build start is cleared and retried. This is the way to carry work on: a run is the record of an attempt, and decisions about the work are made on the initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume. Starts paid work; ask the person first.",
+		description: "Resume an initiative the line stopped on, which is when needsHumanCause is set (the line sets it): a failed or cancelled plan is planned again, a stopped or failed run resumes from its first unfinished part (the steps already committed are kept), a refused build start is cleared and retried. This is the way to carry work on: a run is the record of an attempt, and decisions about the work are made on the initiative. Refused (CONFLICT) when nothing is flagged or the cause has no resume: a plan that failed with needsHumanCause null (lifecycle.cta retry_plan, planFailureCause says why) is planned again with taiga_plan_again. Starts paid work; ask the person first.",
 		inputSchema: z.object({ itemId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => outcome((await client.resumeInitiative(params.itemId)).data)));
@@ -3485,14 +3682,14 @@ function registerPlanVerdicts(server, client) {
 	server.registerTool("taiga_approve_plan", {
 		title: "Approve a plan",
 		description: "Approve an initiative's plan: its build starts now, as the approver, the same start the Start run button makes. Read the plan first with taiga_get_plan and name its ID; an approval of a plan that was replaced since is refused (CONFLICT), as is one while a new plan is being generated or a build is already running. Starts a coding run that pushes commits and opens a pull request; ask the person first.",
-		inputSchema: z.object({ planId: z.string().uuid().describe("Plan ID -- get from taiga_get_plan") }),
+		inputSchema: z.object({ planId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => outcome((await client.approvePlan(params.planId)).data)));
 	server.registerTool("taiga_reject_plan", {
 		title: "Reject a plan",
 		description: "Send an initiative's plan back with direction: a new plan is generated with the comment as reviewer feedback and the rejected plan as its starting point, which supersedes it when the new one lands. Read the plan first with taiga_get_plan and name its ID. Starts a planner run; ask the person first.",
 		inputSchema: z.object({
-			planId: z.string().uuid().describe("Plan ID -- get from taiga_get_plan"),
+			planId,
 			comment: z.string().trim().min(1).max(PLAN_REJECTION_COMMENT_MAX_CHARS).describe("What the next plan should do differently: a paragraph of direction")
 		}),
 		annotations: OPERATE
@@ -3538,9 +3735,24 @@ const RUN_OUTCOME_FIELDS = [
 	"prUrl",
 	"actions"
 ];
+/**
+* Where a run that ended without finishing stopped, from its steps and its
+* hardening result: a failed run with every step completed reads as nothing
+* failed, and retry_from_failed_step then reads as a mistake, when the agent
+* stalled in the hardening pass after the steps and the retry continues it.
+* Null for a run still going or that finished.
+*/
+function stoppedIn(run, steps) {
+	if (run.prMerged === true || run.status !== "failed" && run.status !== "stopped") return null;
+	if (!steps.some((step) => step.status !== "planned")) return "before the first step started, while setting up the run (cloning, preparing the workspace)";
+	const open = steps.find((step) => step.status !== "completed" && step.status !== "skipped");
+	if (open) return open.status === "planned" ? `before step ${String(open.stepOrder)}, ${String(open.title)}, started (the ones before it completed)` : `step ${String(open.stepOrder)}, ${String(open.title)} (${String(open.status)})`;
+	if (run.hardeningResult == null) return "after the last step, in hardening: the security scanners and their fixes the agent runs before the pull request is ready. A retry continues from there; the steps stay.";
+	return "after the steps and hardening, at the pull request";
+}
 /** How many products the org-wide list names; past this a row keeps its productId only. */
 const NAMED_PRODUCTS = 100;
-const buildId = z.string().uuid().describe("Build run ID -- get from taiga_list_builds");
+const buildId = idInput("build run", "taiga_list_builds gives it");
 /** A step without its instructions: what it is, how it stands and what it changed. */
 const STEP_SUMMARY_FIELDS = [
 	"stepOrder",
@@ -3601,14 +3813,14 @@ function registerBuildTools(server, client) {
 		description: "List the coding agent's runs, newest first: status, branch, pull request, step progress and the actions a person may take on each. A run is the record of an attempt: work is carried on from its initiative (resume and retry_from_failed_step are taiga_resume_backlog_item; start_over is in the web only for now) and stopped by moving the initiative out of Build; a maintenance run, which has no initiative, is retried from its finding. With productId, the runs of that product, optionally of one backlog item; without it, the runs of every product the key can see, each row naming its product, and active: true narrows to the runs executing right now. Use this to see what Taiga already built or is building, then read one run with taiga_get_build. A run of a deleted initiative keeps its title.",
 		inputSchema: z.object({
 			productId: productId.optional(),
-			backlogItemId: z.string().uuid().optional().describe("Only this backlog item's runs -- get from taiga_list_backlog_items; needs productId"),
+			backlogItemId: idInput("backlog item", "taiga_list_backlog_items (query finds one by title) gives it").optional().describe("Only this backlog item's runs -- get from taiga_list_backlog_items; needs productId"),
 			active: z.boolean().optional().describe("Only runs the agent is executing now (cloning through reviewing; a queued pending run is not yet executing and is left out); for the org-wide list"),
 			...pagination
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		if (!params.productId && params.backlogItemId) return toolError("VALIDATION_FAILED", "backlogItemId narrows the runs of one product: pass its productId as well (the item carries it).");
-		if (params.productId && params.active) return toolError("VALIDATION_FAILED", "active narrows the org-wide list only: omit productId, or read the product's runs and judge each by its status.");
+		if (!params.productId && params.backlogItemId) return toolError("VALIDATION_ERROR", "backlogItemId narrows the runs of one product: pass its productId as well (the item carries it).");
+		if (params.productId && params.active) return toolError("VALIDATION_ERROR", "active narrows the org-wide list only: omit productId, or read the product's runs and judge each by its status.");
 		if (params.productId) {
 			const result = await client.listBuildRuns(params.productId, params);
 			return toolResult(page(pickFields(result.data, BUILD_SUMMARY_FIELDS), result.nextCursor));
@@ -3617,7 +3829,7 @@ function registerBuildTools(server, client) {
 	}));
 	server.registerTool("taiga_get_build", {
 		title: "Get build run",
-		description: "Get one run with its steps: the run (status, pull request, hardening, metrics) and each step's title, status, commit, files changed, checks, any error and headline, the first paragraph of what the agent reported. Pass full: true for each step's complete instructions and report, several thousand tokens on a long run. Use this to pick up where the coding agent stopped, or to understand the pull request it opened. Its actions name what the initiative accepts for it: resume and retry_from_failed_step are taiga_resume_backlog_item, start_over is in the web only for now; to stop it, move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
+		description: "Get one run with its steps: the run (status, pull request, hardening, metrics) and each step's title, status, commit, files changed, checks, any error and headline, the first paragraph of what the agent reported. Pass full: true for each step's complete instructions and report, several thousand tokens on a long run. Use this to pick up where the coding agent stopped, or to understand the pull request it opened. A run that failed or was stopped says where (stoppedIn: a step, or the hardening pass after them) and when it last made progress (lastProgressAt). Its actions name what the initiative accepts for it: resume and retry_from_failed_step (which continues from the first unfinished part) are taiga_resume_backlog_item, start_over is in the web only for now; to stop it, move the initiative out of Build. A maintenance run has no initiative and is retried from its finding.",
 		inputSchema: z.object({
 			buildId,
 			full: z.boolean().optional().describe("Carry each step's complete instructions and report (default false: a summary)")
@@ -3625,13 +3837,18 @@ function registerBuildTools(server, client) {
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
 		const [run, steps] = await Promise.all([client.getBuildRun(params.buildId), client.listBuildRunSteps(params.buildId)]);
+		const runRow = run.data;
+		const rows = steps.data;
+		const where = stoppedIn(runRow, rows);
+		const stop = where ? { stoppedIn: where } : {};
 		if (params.full) return toolResult({
-			...run.data,
+			...runRow,
+			...stop,
 			steps: steps.data
 		});
-		const rows = steps.data;
 		return toolResult({
-			...run.data,
+			...runRow,
+			...stop,
 			steps: pickFields(rows, STEP_SUMMARY_FIELDS).map((step, index) => ({
 				...step,
 				headline: summaryHeadline(rows[index].summary)
@@ -3922,10 +4139,12 @@ async function productContext(client, product, options) {
 	};
 	const parts = Object.keys(fetchers).filter(granted);
 	const settled = await Promise.allSettled(parts.map((part) => fetchers[part]()));
+	const nextStep = setupNextStep(product);
 	const bundle = { product: {
 		...pickFields([product], PRODUCT_SUMMARY_FIELDS)[0],
 		projectType: isImportedProduct(product) ? "brownfield" : "greenfield",
-		defaultOrigin: defaultOriginFor(product)
+		defaultOrigin: defaultOriginFor(product),
+		...nextStep ? { nextStep } : {}
 	} };
 	const unavailable = {};
 	parts.forEach((part, index) => {
@@ -3938,7 +4157,7 @@ async function productContext(client, product, options) {
 		...bundle,
 		notGranted: notGranted.map((part) => `${part} (needs ${PARTS[part]})`),
 		unavailable,
-		readNext: "Read a policy in full with taiga_get_document, another product document with taiga_get_product_document, a backlog item with taiga_get_backlog_item (taiga_list_backlog_items pages a truncated backlog) and a run with taiga_get_build."
+		readNext: "Read a policy with taiga_get_document (sections: the ids listed here, for only those), another product document with taiga_get_product_document, a backlog item with taiga_get_backlog_item (taiga_list_backlog_items pages a truncated backlog) and a run with taiga_get_build."
 	};
 	let characters = JSON.stringify(result, null, 2).length;
 	for (let measured = -1; measured !== characters;) {
@@ -3989,7 +4208,7 @@ function registerAutonomyTools(server, client) {
 		}),
 		annotations: OPERATE_SETTING
 	}, (params) => runTool(async () => {
-		if (params.autoBuild === void 0 && params.autoMerge === void 0) return toolError("VALIDATION_FAILED", "Set autoBuild, autoMerge or both.");
+		if (params.autoBuild === void 0 && params.autoMerge === void 0) return toolError("VALIDATION_ERROR", "Set autoBuild, autoMerge or both.");
 		const autoMerge = params.autoMerge === true ? null : params.autoMerge;
 		const product = (await client.updateProduct(params.productId, {
 			...params.autoBuild !== void 0 ? { autoBuild: params.autoBuild } : {},
@@ -4007,7 +4226,7 @@ function registerAutonomyTools(server, client) {
 		title: "Set whether an initiative's pull request merges on its own",
 		description: "An initiative's own switch for merging on its own: true lets its pull request merge itself once the repository's own rules pass (required checks, reviews, a code reviewer you made Taiga wait for); false makes it wait for a person; null follows the product's default. The final word within what the organization and factories allow: where either has turned autonomous merge off, true changes nothing. Taiga merges through your rules, never around them. Ask the person first.",
 		inputSchema: z.object({
-			itemId: z.string().uuid().describe("Backlog item ID -- get from taiga_list_backlog_items"),
+			itemId: idInput("backlog item", "taiga_list_backlog_items (query finds one by title) gives it"),
 			autoMerge: z.boolean().nullable().describe("true merges on its own, false waits for a person, null follows the product")
 		}),
 		annotations: OPERATE_SETTING
@@ -4027,6 +4246,7 @@ function registerAutonomyTools(server, client) {
 const ITEM_FIELDS = [
 	"id",
 	"productId",
+	"productName",
 	"category",
 	"kind",
 	"subjectType",
@@ -4043,6 +4263,7 @@ const ITEM_FIELDS = [
 const SETUP_TASK_FIELDS = [
 	"id",
 	"productId",
+	"productName",
 	"category",
 	"phase",
 	"target",
@@ -4059,7 +4280,7 @@ function registerInboxTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_list_action_required", {
 		title: "List what needs a person",
-		description: "Read Action Required, where work comes back to a person: things to review (a plan, a set of initiatives, a document, a pull request, maintenance findings, new policy violations), each a decision an agent handed back rather than made, and things to set up that only a person can (a secret, an environment variable, an account, a package registry, a cloud permission). Across every product the key can open, or one product. category gate is the reviews, setup the setup items; resolved: true reads the archive of done and dismissed ones. The inbox is shared: it is the team's, not one person's. An item snoozed until later is left out until then, as the page leaves it out (snoozedHidden counts them). taiga_list_setup_tasks has the setup tasks with what exactly to set.",
+		description: "Read Action Required, where work comes back to a person: things to review (a plan, a set of initiatives, a document, a pull request, maintenance findings, new policy violations), each a decision an agent handed back rather than made, and things to set up that only a person can (a secret, an environment variable, an account, a package registry, a cloud permission). Across every product the key can open (each row names its product), or one product. category gate is the reviews, setup the setup items; resolved: true reads the archive of done and dismissed ones. The inbox is shared: it is the team's, not one person's. An item snoozed until later is left out until then, as the page leaves it out (snoozedHidden counts them). taiga_list_setup_tasks has the setup tasks with what exactly to set.",
 		inputSchema: z.object({
 			productId: productId.optional(),
 			category: z.enum(["gate", "setup"]).optional().describe("gate: things to review; setup: things to set up"),
@@ -4084,14 +4305,19 @@ function registerInboxTools(server, client) {
 	}));
 	server.registerTool("taiga_list_setup_tasks", {
 		title: "List setup tasks",
-		description: "The setup tasks agents raised for work only a person can do, with what exactly to set and where: the name of an environment variable, secret or API key to create (key; never its value, which Taiga does not store or display), the provider page to do it on, and the phase that says when it blocks you (prereq: before the deploy, which fails without it; wiring: connecting generated values back to providers; followup: billing approvals, extra permissions and the like that can wait until after launch). A build does not wait for any of them. Across every product the key can open, or one.",
+		description: "The setup tasks agents raised for work only a person can do, with what exactly to set and where: the name of an environment variable, secret or API key to create (key; never its value, which Taiga does not store or display), the provider page to do it on, and the phase that says when it blocks you (prereq: before the deploy, which fails without it; wiring: connecting generated values back to providers; followup: billing approvals, extra permissions and the like that can wait until after launch). A build does not wait for any of them. Across every product the key can open (each row names its product), or one. The tasks still to do, oldest first, the order they depend on each other; includeDone: true adds the done and dismissed ones.",
 		inputSchema: z.object({
 			productId: productId.optional(),
+			includeDone: z.boolean().optional().describe("Also the tasks already done or dismissed (default false)"),
 			...pagination
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
-		const result = await client.listSetupTasks(params);
+		const { includeDone, ...rest } = params;
+		const result = await client.listSetupTasks({
+			...rest,
+			...includeDone ? {} : { openOnly: true }
+		});
 		return toolResult(page(pickFields(result.data, SETUP_TASK_FIELDS), result.nextCursor));
 	}));
 	if (!client.hasCapability("products:write")) return;
@@ -4099,7 +4325,7 @@ function registerInboxTools(server, client) {
 		title: "Resolve or snooze an Action Required item",
 		description: "Clear an item from Action Required, for everybody: done means you did it, dismissed means it does not apply and is not going to, in_progress means someone has picked it up. Or snooze it until a time (an hour, tomorrow, a week; null wakes it). Nothing marks a setup task done for you: setting the variable or connecting the registry is the work, and marking it done is still a person's. Resolving a review item does not approve or merge anything; the plan or pull request is answered where it lives. One exception: marking the product documents review item done records, in your name, that every published document was reviewed, and setting it back to in_progress withdraws that; do it only when the person says they read them. Ask the person before clearing what they have not dealt with.",
 		inputSchema: z.object({
-			itemId: z.string().uuid().describe("Action Required item ID -- taiga_list_action_required gives it"),
+			itemId: idInput("Action Required item", "taiga_list_action_required gives it"),
 			status: z.enum([
 				"in_progress",
 				"done",
@@ -4109,7 +4335,7 @@ function registerInboxTools(server, client) {
 		}),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
-		if (params.status === void 0 && params.snoozedUntil === void 0) return toolError("VALIDATION_FAILED", "Say what became of the item (status) or until when to snooze it.");
+		if (params.status === void 0 && params.snoozedUntil === void 0) return toolError("VALIDATION_ERROR", "Say what became of the item (status) or until when to snooze it.");
 		return toolResult(pickFields([(await client.updateInboxItem(params.itemId, {
 			...params.status !== void 0 ? { status: params.status } : {},
 			...params.snoozedUntil !== void 0 ? { snoozedUntil: params.snoozedUntil } : {}
@@ -4133,10 +4359,10 @@ const KNOWLEDGE_FIELDS = [
 ];
 /** Past this many characters a text file's content is cut when read; the download URL has it all. */
 const TEXT_LIMIT = 2e4;
-const knowledgeId = z.string().uuid().describe("Knowledge file ID -- taiga_list_knowledge gives it");
+const knowledgeId = idInput("knowledge file", "taiga_list_knowledge gives it");
 const scopeInputs = {
-	factoryId: z.string().uuid().optional().describe("A factory's knowledge"),
-	productId: z.string().uuid().optional().describe("A product's knowledge")
+	factoryId: idInput("factory", "taiga_list_factories gives it").optional().describe("A factory's knowledge"),
+	productId: productId.optional().describe("A product's knowledge")
 };
 /** Bytes of a text file the read takes at most; the download URL has the rest. */
 const READ_BYTES = 262144;
@@ -4200,7 +4426,7 @@ function registerKnowledgeTools(server, client) {
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
 		const twoLevels = oneLevel(params);
-		if (twoLevels) return toolError("VALIDATION_FAILED", twoLevels);
+		if (twoLevels) return toolError("VALIDATION_ERROR", twoLevels);
 		const scope = params.productId ? { productId: params.productId } : params.factoryId ? {
 			factoryId: params.factoryId,
 			productId: null
@@ -4257,7 +4483,7 @@ function registerKnowledgeTools(server, client) {
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
 		const twoLevels = oneLevel(params);
-		if (twoLevels) return toolError("VALIDATION_FAILED", twoLevels);
+		if (twoLevels) return toolError("VALIDATION_ERROR", twoLevels);
 		const mime = params.fileName.toLowerCase().endsWith(".md") ? "text/markdown" : "text/plain";
 		const result = await client.addKnowledge({
 			fileName: params.fileName,
@@ -4343,7 +4569,7 @@ const VIOLATION_FIELDS = [
 	"verifyRequestedAt",
 	"assessedAt"
 ];
-const findingId = z.string().uuid().describe("Finding ID -- taiga_list_findings gives it");
+const findingId = idInput("finding", "taiga_list_findings gives it");
 function registerMaintenanceTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_maintenance", {
@@ -4388,7 +4614,7 @@ function registerMaintenanceTools(server, client) {
 	}, (params) => runTool(async () => toolResult((await client.getFinding(params.findingId)).data)));
 	server.registerTool("taiga_get_policy_standing", {
 		title: "Get a product's policy standing",
-		description: "Where a product stands against the organization's own published policies: the controls it violates, each with its violations (critical and high only, each citing the policy's sentence and the document passage that contradicts it), what is being done about each (an initiative raised, a fix in progress, awaiting verification), and when the documents were derived and assessed. A control with no violation is not listed, and it is not \"passing\" either: there is no such state. Pass full: true for every violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
+		description: "Where a product stands against the organization's own published policies: the controls it violates, each with its violations (critical and high only, each citing the policy's sentence and the document passage that contradicts it), what is being done about each (an initiative raised, a fix in progress, awaiting verification), and when the documents were derived and assessed, led by a summary of the counts. A control with no violation is not listed, and it is not \"passing\" either: there is no such state. Pass full: true for every violation's evidence and the resolved ones. Fix a control with taiga_fix_policy_violation.",
 		inputSchema: z.object({
 			productId,
 			full: z.boolean().optional().describe("Carry each violation's evidence, the policy excerpt and the resolved violations (default false)")
@@ -4396,16 +4622,32 @@ function registerMaintenanceTools(server, client) {
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
 		const standing = (await client.getPolicyStanding(params.productId)).data;
-		if (params.full) return toolResult(standing);
 		const controls = Array.isArray(standing.controls) ? standing.controls : [];
 		const violations = Array.isArray(standing.divergences) ? standing.divergences : [];
 		const resolved = Array.isArray(standing.resolvedDivergences) ? standing.resolvedDivergences.length : 0;
+		const listed = controls.filter((c) => Number(c.divergenceCount ?? 0) > 0 || Number(c.findingCount ?? 0) > 0);
+		const bySeverity = {};
+		for (const violation of violations) {
+			const severity = String(violation.severity ?? "unknown");
+			bySeverity[severity] = (bySeverity[severity] ?? 0) + 1;
+		}
+		const summary = {
+			controls: listed.length,
+			violations: violations.length,
+			bySeverity,
+			resolvedViolations: resolved
+		};
+		if (params.full) return toolResult({
+			summary,
+			...standing
+		});
 		return toolResult({
+			summary,
 			productId: standing.productId,
 			hasPolicies: standing.hasPolicies,
 			assessment: standing.assessment,
 			documents: standing.documents,
-			controls: pickFields(controls.filter((c) => Number(c.divergenceCount ?? 0) > 0 || Number(c.findingCount ?? 0) > 0), [
+			controls: pickFields(listed, [
 				"controlId",
 				"policyType",
 				"text",
@@ -4414,8 +4656,7 @@ function registerMaintenanceTools(server, client) {
 				"findingCount",
 				"plannedCount"
 			]),
-			violations: pickFields(violations, VIOLATION_FIELDS),
-			resolvedViolations: resolved
+			violations: pickFields(violations, VIOLATION_FIELDS)
 		});
 	}));
 	if (!client.hasCapability("products:write")) return;
@@ -4431,7 +4672,7 @@ function registerMaintenanceTools(server, client) {
 		}),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
-		if (params.ignored && params.reason === void 0) return toolError("VALIDATION_FAILED", "Say why the finding is ignored (reason).");
+		if (params.ignored && params.reason === void 0) return toolError("VALIDATION_ERROR", "Say why the finding is ignored (reason).");
 		const body = params.ignored ? {
 			status: "ignored",
 			ignoreReason: params.reason,
@@ -4473,11 +4714,11 @@ function registerMaintenanceTools(server, client) {
 		inputSchema: z.object({
 			productId,
 			controlId: z.string().min(1).max(40).optional().describe("The control's identifier, e.g. SEC-3.4"),
-			violationId: z.string().uuid().optional().describe("One violation -- taiga_get_policy_standing gives it")
+			violationId: idInput("violation", "taiga_get_policy_standing gives it").optional()
 		}),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
-		if (params.controlId === void 0 === (params.violationId === void 0)) return toolError("VALIDATION_FAILED", "Name either a control (controlId) or one violation (violationId), not both or neither.");
+		if (params.controlId === void 0 === (params.violationId === void 0)) return toolError("VALIDATION_ERROR", "Name either a control (controlId) or one violation (violationId), not both or neither.");
 		return toolResult((params.controlId ? await client.remediatePolicyControl(params.productId, params.controlId) : await client.remediatePolicyViolation(params.productId, params.violationId)).data);
 	}));
 }
@@ -4511,7 +4752,7 @@ const ENVIRONMENT_FIELDS = [
 	"isProtected",
 	"url"
 ];
-const environmentId = z.string().uuid().describe("Environment ID -- taiga_get_deployments lists them");
+const environmentId = idInput("environment", "taiga_get_deployments lists them; a product ID is not one");
 const windowDays = (choices) => z.number().int().optional().describe(`Days to look back: ${choices} (default 30)`);
 /** Whether a failure is the API's (refused, missing, unreachable) rather than a bug here. */
 const isApiFailure = (error) => error instanceof TaigaApiError || isNetworkFailure(error);
@@ -4570,6 +4811,7 @@ function registerObserveTools(server, client) {
 			part(() => client.getDeploymentSyncStatus(params.productId))
 		]);
 		const now = current.data;
+		const note = environments.rows.length === 0 ? "This product has no environments yet: an environment is defined with taiga_define_environment, and its deployments are mirrored from the provider once it is." : history.data.length === 0 && !params.cursor ? "No deployments recorded yet: none was mirrored from the provider (syncStatus says when it last synced), or nothing has been deployed." : null;
 		return toolResult({
 			environments: pickFields(environments.rows, ENVIRONMENT_FIELDS),
 			...environments.more ? { moreEnvironments: true } : {},
@@ -4579,7 +4821,8 @@ function registerObserveTools(server, client) {
 			..."value" in sync ? { syncStatus: sync.value.data } : {
 				syncStatus: null,
 				syncUnavailable: sync.unavailable
-			}
+			},
+			...note ? { note } : {}
 		});
 	}));
 	server.registerTool("taiga_get_delivery_metrics", {
@@ -4597,7 +4840,7 @@ function registerObserveTools(server, client) {
 			30,
 			60,
 			90
-		].includes(days)) return toolError("VALIDATION_FAILED", "windowDays is 30, 60 or 90.");
+		].includes(days)) return toolError("VALIDATION_ERROR", "windowDays is 30, 60 or 90.");
 		return toolResult((await client.getDeliveryMetrics(params.productId, params.environmentId, days)).data);
 	}));
 	server.registerTool("taiga_get_monitoring", {
@@ -4611,22 +4854,32 @@ function registerObserveTools(server, client) {
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
 		const health = await client.getMonitoringHealth(params.productId);
-		if (!params.environmentId) return toolResult({ health: health.data });
+		if (!params.environmentId) return toolResult({
+			health: health.data,
+			...health.data.length === 0 ? { note: "No environment is monitored: monitoring starts when an environment has its App URL (taiga_define_environment, taiga_update_environment). No health is not good health." } : {}
+		});
 		const days = params.windowDays ?? 30;
 		if (![
 			30,
 			60,
 			90
-		].includes(days)) return toolError("VALIDATION_FAILED", "windowDays is 30, 60 or 90, the windows the page offers.");
+		].includes(days)) return toolError("VALIDATION_ERROR", "windowDays is 30, 60 or 90, the windows the page offers.");
 		const env = params.environmentId;
 		const [uptime, experience, clientHealth] = await Promise.all([
 			part(() => client.getMonitoringSignal(params.productId, "uptime", env, days)),
 			part(() => client.getMonitoringSignal(params.productId, "rum", env, days)),
 			part(() => client.getMonitoringSignal(params.productId, "client-health", env, days))
 		]);
+		if ("unavailable" in uptime && [
+			uptime,
+			experience,
+			clientHealth
+		].every((p) => "unavailable" in p && p.unavailable.startsWith("404"))) return toolError("NOT_FOUND", withNotFoundHint(uptime.unavailable.replace(/^404:\s*/, "") || "Environment not found"));
 		const value = (p) => "value" in p ? p.value.data : { unavailable: p.unavailable };
+		const envHealth = health.data.filter((row) => row.environmentId === env);
 		return toolResult({
-			health: health.data.filter((row) => row.environmentId === env),
+			health: envHealth,
+			...envHealth.length === 0 ? { note: "No health for this environment: it has no App URL to check yet (taiga_update_environment sets one). No health is not good health." } : {},
 			windowDays: days,
 			uptime: value(uptime),
 			realUserExperience: value(experience),
@@ -4662,7 +4915,7 @@ function registerObserveTools(server, client) {
 		annotations: OPERATE_SETTING
 	}, (params) => runTool(async () => {
 		const { environmentId: id, ...changes } = params;
-		if (Object.values(changes).every((value) => value === void 0)) return toolError("VALIDATION_FAILED", "Change at least one of name, type or url.");
+		if (Object.values(changes).every((value) => value === void 0)) return toolError("VALIDATION_ERROR", "Change at least one of name, type or url.");
 		const updated = (await client.updateEnvironment(id, changes)).data;
 		return toolResult(pickFields([updated], ENVIRONMENT_FIELDS)[0]);
 	}));
@@ -19386,7 +19639,7 @@ function registerPrompts(server, client) {
 	if (client.hasCapability("backlog:read") && client.hasCapability("products:read")) server.registerPrompt("taiga_implement_backlog_item", {
 		title: "Implement a backlog item",
 		description: "Implement one initiative: its description and acceptance criteria, the architecture of the product from its own timeline, the factory's instructions and the policy sections to check against. taiga_list_backlog_items gives the item ID.",
-		argsSchema: z.object({ itemId: productId.describe("The backlog item ID") })
+		argsSchema: z.object({ itemId: idInput("backlog item", "taiga_list_backlog_items (query finds one by title) gives it") })
 	}, async (args) => {
 		const item = (await served$1(client.getBacklogItem(args.itemId), "No backlog item with that ID the key can see; taiga_list_backlog_items shows what exists")).data;
 		const productId = String(item.productId);
@@ -19481,7 +19734,7 @@ const GITHUB_REPOSITORY_FIELDS = [
 	"description",
 	"language"
 ];
-const repositoryId = z.string().uuid().describe("The product's repository link ID -- taiga_list_product_repositories gives it");
+const repositoryId = idInput("repository link", "taiga_list_product_repositories gives it; a GitHub repository id is not one");
 function registerRepositoryTools(server, client) {
 	if (client.hasCapability("products:read")) {
 		server.registerTool("taiga_list_product_repositories", {
@@ -19513,7 +19766,7 @@ function registerRepositoryTools(server, client) {
 		description: "The repositories the organization's GitHub connection can reach, to link one to a product (taiga_link_repository takes its id). Searches by name with query; without installationId it reads every connected GitHub account. No connection means GitHub is not connected yet: that is done once, in the web, by someone who can install the app.",
 		inputSchema: z.object({
 			query: z.string().trim().min(1).max(256).optional().describe("Part of the repository name"),
-			installationId: z.string().uuid().optional().describe("One GitHub account -- this tool lists them"),
+			installationId: idInput("GitHub account", "this tool lists them").optional(),
 			...pagination
 		}),
 		annotations: READ_ONLY
@@ -19523,8 +19776,8 @@ function registerRepositoryTools(server, client) {
 		if (installations.length === 0) return toolError("NOT_CONNECTED", "GitHub is not connected for this organization. It is connected once, in the web; then link.");
 		const chosen = params.installationId ? installations.filter((i) => i.id === params.installationId) : installations;
 		if (chosen.length === 0) return toolError("NOT_FOUND", "No such GitHub connection; these are the connected accounts.", { accounts });
-		if (params.cursor !== void 0 && params.query !== void 0) return toolError("VALIDATION_FAILED", "A search answers one page; narrow the query instead of paging it.");
-		if (chosen.length > 1 && params.cursor !== void 0) return toolError("VALIDATION_FAILED", "A cursor pages one account: name its installationId.", { accounts });
+		if (params.cursor !== void 0 && params.query !== void 0) return toolError("VALIDATION_ERROR", SEARCH_WITH_CURSOR);
+		if (chosen.length > 1 && params.cursor !== void 0) return toolError("VALIDATION_ERROR", "A cursor pages one account: name its installationId.", { accounts });
 		const max = params.limit ?? 25;
 		const rows = (data) => pickFields(data, GITHUB_REPOSITORY_FIELDS);
 		if (chosen.length === 1) {
@@ -19558,7 +19811,7 @@ function registerRepositoryTools(server, client) {
 		description: "Link a repository the GitHub connection can reach (taiga_list_linkable_repositories gives its id) to a product, or with replacesRepositoryId swap the one linked now for it in one step (naming the same repository there changes nothing; linking one already linked without it is refused). A link Taiga manages (isManaged) cannot be replaced or unlinked. Once linked, planning reads its code, runs open pull requests in it, sweeps scan it, and its deployment history is imported in the background. Ask the person first.",
 		inputSchema: z.object({
 			productId,
-			githubRepositoryId: z.string().uuid().describe("The repository id -- taiga_list_linkable_repositories gives it"),
+			githubRepositoryId: idInput("GitHub repository", "taiga_list_linkable_repositories gives it"),
 			replacesRepositoryId: repositoryId.optional().describe("The link this one replaces")
 		}),
 		annotations: OPERATE
@@ -19579,7 +19832,7 @@ function registerRepositoryTools(server, client) {
 		}),
 		annotations: OPERATE_SETTING
 	}, (params) => runTool(async () => {
-		if (params.baseBranch === void 0 && params.label === void 0) return toolError("VALIDATION_FAILED", "Set baseBranch, label or both.");
+		if (params.baseBranch === void 0 && params.label === void 0) return toolError("VALIDATION_ERROR", "Set baseBranch, label or both.");
 		const updated = (await client.updateRepository(params.productId, params.repositoryId, {
 			...params.baseBranch !== void 0 ? { baseBranch: params.baseBranch } : {},
 			...params.label !== void 0 ? { label: params.label } : {}
@@ -19746,26 +19999,56 @@ const FACTORY_FIELDS = [
 	"slug",
 	"isDefault"
 ];
-const factoryId = z.string().uuid().describe("Factory ID -- taiga_list_factories gives it");
+const factoryId = idInput("factory", "taiga_list_factories (query finds one by name) gives it");
 const buildScope = {
 	ownsInfrastructure: z.boolean().nullable().optional().describe("Whether Taiga writes the infrastructure code; null follows the organization"),
 	ownsDeployment: z.boolean().nullable().optional().describe("Whether Taiga writes the CI/CD pipelines; null follows the organization")
 };
 const deploymentNotes = z.string().trim().min(1).max(DEPLOYMENT_NOTES_MAX_LENGTH).describe("When a half is off: a sentence on how it is done today, which Taiga designs and plans against");
+/** How a missing required document comes to exist, said with a documents_incomplete refusal. */
+const MISSING_DOCUMENTS_HOW = "An imported product gets them from its import (taiga_start_import); a product started from scratch gets the specification from the Discovery conversation in the web and the rest from taiga_generate_product_documents. A draft is published with taiga_publish_product_document.";
 /** A product row the model can act on, saying how it started as the other product tools say it. */
-function productRow(product) {
+async function productRow(client, product) {
 	const { settings: _settings, ...rest } = pickFields([product], PRODUCT_FIELDS)[0];
+	const nextStep = setupNextStep(await withDiscoveryStep(client, product));
 	return {
 		...rest,
-		projectType: isImportedProduct(product) ? "brownfield" : "greenfield"
+		projectType: isImportedProduct(product) ? "brownfield" : "greenfield",
+		...nextStep ? { nextStep } : {}
 	};
 }
 /**
+* The product with its discoveryStep. The API derives it on reads only, not
+* on the answer to a write (products.ts), and a draft started from scratch
+* needs it to say what comes next; an imported one reads its import status
+* instead. Best effort: a failed read leaves the product without a nextStep
+* rather than failing the write that already happened.
+*/
+async function withDiscoveryStep(client, product) {
+	if (product.status !== "draft" || "discoveryStep" in product || isImportedProduct(product)) return product;
+	try {
+		return (await client.getProduct(String(product.id))).data;
+	} catch (error) {
+		if (error instanceof TaigaApiError || isNetworkFailure(error)) return product;
+		throw error;
+	}
+}
+/**
+* A half turned off with nothing said about how it is done today. Allowed (the
+* web asks for the sentence but does not insist), so a warning rather than a
+* refusal: plans then design against a gap.
+*/
+function missingNotesWarning(product) {
+	const off = product.ownsInfrastructure === false || product.ownsDeployment === false;
+	const notes = typeof product.deploymentNotes === "string" ? product.deploymentNotes.trim() : "";
+	return off && !notes ? ["A half Taiga does not build has no deploymentNotes: plans cannot design against how it is done today. Ask the person for a sentence and set it."] : [];
+}
+/**
 * The sentence is for a half Taiga does not build; the web asks for it only
 * then. When both halves are decided on here, a sentence has nothing to say.
 */
 function notesWithNothingToDescribe(params) {
-	return typeof params.deploymentNotes === "string" && params.ownsInfrastructure === true && params.ownsDeployment === true ? toolError("VALIDATION_FAILED", "deploymentNotes describes a half Taiga does not build; both are on, so leave it out.") : null;
+	return typeof params.deploymentNotes === "string" && params.ownsInfrastructure === true && params.ownsDeployment === true ? toolError("VALIDATION_ERROR", "deploymentNotes describes a half Taiga does not build; both are on, so leave it out.") : null;
 }
 function registerSetupTools(server, client) {
 	if (client.hasCapability("factories:write")) {
@@ -19808,7 +20091,7 @@ function registerSetupTools(server, client) {
 				...params.stopLine ? { stopLine: true } : {}
 			});
 			return toolResult({
-				product: productRow(moved.data),
+				product: await productRow(client, moved.data),
 				changed: moved.changed,
 				previousFactoryId: moved.previousFactoryId,
 				lineStopped: moved.lineStopped,
@@ -19839,7 +20122,7 @@ function registerSetupTools(server, client) {
 			...params.ownsDeployment !== void 0 ? { ownsDeployment: params.ownsDeployment } : {},
 			...params.deploymentNotes !== void 0 ? { deploymentNotes: params.deploymentNotes } : {}
 		})).data;
-		return toolResult(productRow(product));
+		return toolResult(await productRow(client, product));
 	}));
 	server.registerTool("taiga_update_product", {
 		title: "Change a product's settings",
@@ -19854,10 +20137,15 @@ function registerSetupTools(server, client) {
 		annotations: OPERATE_SETTING
 	}, (params) => runTool(async () => {
 		const { productId: id, ...changes } = params;
-		if (Object.values(changes).every((value) => value === void 0)) return toolError("VALIDATION_FAILED", "Change at least one setting.");
+		if (Object.values(changes).every((value) => value === void 0)) return toolError("VALIDATION_ERROR", "Change at least one setting.");
 		const contradiction = notesWithNothingToDescribe(params);
 		if (contradiction) return contradiction;
-		return toolResult(productRow((await client.updateProduct(id, changes)).data));
+		const updated = (await client.updateProduct(id, changes)).data;
+		const warnings = missingNotesWarning(updated);
+		return toolResult({
+			...await productRow(client, updated),
+			...warnings.length > 0 ? { warnings } : {}
+		});
 	}));
 	server.registerTool("taiga_refresh_reality_documents", {
 		title: "Refresh a product's documents from its code",
@@ -19870,16 +20158,23 @@ function registerSetupTools(server, client) {
 	}, (params) => runTool(async () => toolResult((await client.refreshRealityDocuments(params.productId, params.docTypes)).data)));
 	server.registerTool("taiga_finish_discovery", {
 		title: "Finish Discovery",
-		description: "Finish a product's Discovery. Refused (CONFLICT) with details.reason: documents_incomplete names the required documents still unpublished (details.missingDocuments); not_in_setup means it is already finished; a required check left unstamped (stamped in the web) is refused with its details too. It locks the document set and opens the rest of the product; for an imported product it is also when the first initiatives are planned. A locked document changes only after taiga_reopen_discovery. Ask the person first: it is their decision that the documents are right.",
+		description: "Finish a product's Discovery. Refused (CONFLICT) with details.reason: documents_incomplete names the required documents still unpublished (details.missingDocuments) and how they are made; not_in_setup means it is already finished; a required check left unstamped (stamped in the web) is refused with its details too. It locks the document set and opens the rest of the product; for an imported product it is also when the first initiatives are planned. A locked document changes only after taiga_reopen_discovery. Ask the person first: it is their decision that the documents are right.",
 		inputSchema: z.object({ productId }),
 		annotations: OPERATE
-	}, (params) => runTool(async () => toolResult(productRow((await client.completeSetup(params.productId)).data))));
+	}, (params) => runTool(async () => {
+		try {
+			return toolResult(await productRow(client, (await client.completeSetup(params.productId)).data));
+		} catch (error) {
+			if (!(error instanceof TaigaApiError) || error.details?.reason !== "documents_incomplete") throw error;
+			return toolError(error.code ?? "CONFLICT", `${withStop(error.apiMessage ?? "Required documents are not published yet")} ${MISSING_DOCUMENTS_HOW}`, error.details);
+		}
+	}));
 	server.registerTool("taiga_reopen_discovery", {
 		title: "Reopen Discovery",
 		description: "Reopen a finished product's Discovery so its documents can be amended; finish it again afterwards. Nothing built from them is undone. Ask the person first.",
 		inputSchema: z.object({ productId }),
 		annotations: OPERATE
-	}, (params) => runTool(async () => toolResult(productRow((await client.reopenSetup(params.productId)).data))));
+	}, (params) => runTool(async () => toolResult(await productRow(client, (await client.reopenSetup(params.productId)).data))));
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_start_import", {
 		title: "Import a codebase into a product",
@@ -20159,7 +20454,7 @@ function registerWaitTools(server, client, options) {
 		title: "Wait for an initiative",
 		description: "Wait until an initiative reaches a point, instead of reading it again and again: changed (anything about where it is or its latest run), planned (its plan landed), your_turn (it waits on a person: a plan to review, a pull request, a flag), pr_open (a pull request open now; a merged or closed one does not count), run_settled (its latest run stopped moving) or done (finished; a canceled one stops the wait). Returns as soon as that holds (reached: true), early when it cannot hold without a person (a flag, a failed plan, a plan waiting for its verdict, a pull request waiting for a review, a cancelled initiative, or a landed plan whose review gate cannot be read; stoppedBecause says which), or at the timeout with reached: false: call again to keep waiting. Conditions are states, not events: an initiative whose latest run is already settled answers run_settled at once; item is null when not even the first read answered in time. Planning takes minutes and a build up to an hour.",
 		inputSchema: z.object({
-			itemId: z.string().uuid().describe("Backlog item ID -- get from taiga_list_backlog_items"),
+			itemId: idInput("backlog item", "taiga_list_backlog_items (query finds one by title) gives it"),
 			until: z.enum(ITEM_CONDITIONS).describe("What to wait for"),
 			timeoutSeconds
 		}),
@@ -20192,7 +20487,7 @@ function registerWaitTools(server, client, options) {
 		title: "Wait for a run",
 		description: "Wait until a coding agent's run reaches a point: changed (status, steps or pull request), step_done (one more step finished), pr_open (open now, not merged or closed) or settled (it stopped moving: in review, completed, failed, stopped). Returns as soon as that holds (reached: true), early when the run settled without it (stoppedBecause; changed waits on, since a person resuming the run is a change), or at the timeout with reached: false: call again to keep waiting. Conditions are states: a run already settled answers settled at once; run is null when not even the first read answered in time.",
 		inputSchema: z.object({
-			buildId: z.string().uuid().describe("Build run ID -- get from taiga_list_builds"),
+			buildId: idInput("build run", "taiga_list_builds gives it"),
 			until: z.enum(BUILD_CONDITIONS).describe("What to wait for"),
 			timeoutSeconds
 		}),
@@ -20213,7 +20508,7 @@ function registerWaitTools(server, client, options) {
 		title: "Wait for an agent job",
 		description: "Wait until an agent job finishes (completed, failed or cancelled): an initiative request, a document, a refresh. Returns the job as taiga_get_job reads it, with what came of an initiative request, as soon as it settles (reached: true), or at the timeout with reached: false: call again to keep waiting. Most jobs take a few minutes.",
 		inputSchema: z.object({
-			jobId: z.string().uuid().describe("Agent job ID -- a request tool returns it"),
+			jobId: idInput("job", "the tool that started the job returned it"),
 			timeoutSeconds
 		}),
 		annotations: READ_ONLY
@@ -20232,7 +20527,8 @@ function registerWaitTools(server, client, options) {
 //#endregion
 //#region src/tools/index.ts
 /**
-* Every tool refuses an argument it does not take. A plain object schema
+* Every tool refuses an argument it does not take, and every tool's 404 says
+* where the right IDs are (hints.ts). A plain object schema
 * strips one silently: a review note passed to a tool with no place for it
 * vanished and the call still succeeded, and a misspelt option quietly
 * became its default. Strict, the call fails with "Unrecognized key" and the
@@ -20244,10 +20540,12 @@ function withStrictInputs(server) {
 	server.registerTool = ((name, config, callback) => {
 		const schema = config.inputSchema;
 		if (schema !== void 0 && !(schema instanceof z.ZodObject)) throw new Error(`Tool ${name}: inputSchema must be a z.object() so unknown arguments can be refused`);
+		const handler = callback;
+		const withHint = (args, ctx) => notFoundHints.run(notFoundHint(name, args), () => handler(args, ctx));
 		return register(name, schema ? {
 			...config,
 			inputSchema: schema.strict()
-		} : config, callback);
+		} : config, withHint);
 	});
 	return server;
 }
@@ -20277,17 +20575,30 @@ function registerAllTools(server, client, options = {}) {
 	registerResources(server, client);
 	registerPrompts(server, client);
 }
-//#endregion
-//#region src/tools/instructions.ts
-/**
-* What the server tells a client at connect time: the knowledge base, the
-* order to read it in, the two document timelines, what section metadata
-* means, and when to write. Kept as data so a test can hold it to the
-* catalogue the same way it holds the tool descriptions.
-*/
 const SERVER_INSTRUCTIONS = [
-	"You have access to Taiga, a policy-aware software development platform: the organization's",
-	"engineering knowledge base, its products, their backlog and what the coding agent has built.",
+	[
+		"You have access to Taiga, a policy-aware software development platform: the organization's",
+		"engineering knowledge base, its products, their backlog and what the coding agent has built.",
+		"",
+		"**Start here.** Call taiga_get_product_context first, naming the product by its git remote URL inside a",
+		"checkout (git remote get-url origin), else by slug or ID (taiga_list_products finds one by name with",
+		"query). It returns the product (and, while it is in setup, nextStep: what it waits for), its factory",
+		"instructions, its specification and architecture, every policy as its section ids, the open initiatives,",
+		"the repositories and the latest runs. Then read only what you need: the policy sections with",
+		"taiga_get_document, an initiative with taiga_get_backlog_item. Check Action Required",
+		"(taiga_list_action_required) for what waits on a person.",
+		"",
+		"**Before you write.** Tell the person what you are about to do and wait for their yes before a tool that",
+		"starts paid agent work (queueing, approving, resuming, requesting, importing, generating), interrupts it",
+		"(stopping, pausing) or changes what others read (publishing, resolving, settings, repositories). A client",
+		"that prompts on destructive tools does part of that for you.",
+		"",
+		"**Answers.** A refusal carries the API reason: say it as it is. NOT_FOUND names the tool that lists the",
+		"right IDs; an ID is a UUID, never a name. An empty result says why when it has a reason.",
+		"",
+		"**Words.** A backlog item is an initiative; a build is a run, the record of one attempt at it; Action",
+		"Required is the inbox; the line is the queue; a factory is the group that owns a set of products."
+	].join("\n"),
 	"",
 	"**Company documents** (taiga_list_documents / taiga_get_document):",
 	`The ${POLICY_TYPES.length} policies (${named(POLICY_TYPES)}) carry the security, data, SDLC, operations and`,
@@ -20381,15 +20692,9 @@ const SERVER_INSTRUCTIONS = [
 	"`priority: core` marks the sections every organization keeps. Neither changes what the section",
 	"requires of you.",
 	"",
-	"Workflow: start with taiga_get_product_context, naming the product by its git remote URL inside a checkout",
-	"(git remote get-url origin), else by slug or ID from taiga_list_products. It returns the product, the",
-	"factory instructions, the specification and architecture as the whole sections that fit (the rest named for",
-	"taiga_get_product_document to read by section), every policy as its section ids, the open backlog",
-	"items, the repositories and the latest runs in one call, and names any part it could not read. Then read",
-	"what you need in full: a policy with taiga_get_document, a backlog item with taiga_get_backlog_item.",
-	"Without it, use taiga_list_factories and taiga_list_products, then read the factory instructions,",
-	"the product's specification and architecture, and the backlog item you are working on. A document",
-	"read that finds nothing tells you what does exist and which tool reads or writes it.",
+	"Without taiga_get_product_context, use taiga_list_factories and taiga_list_products, then read the",
+	"factory instructions, the product's specification and architecture, and the initiative you are working",
+	"on. A document read that finds nothing tells you what does exist and which tool reads or writes it.",
 	"",
 	"The same documents are resources (taiga://documents/{type}, taiga://products/{productId}/documents/{type},",
 	"taiga://factories/{factoryId}/instructions, taiga://backlog/{itemId}) for clients that attach them, and three",