@taiga-ai/mcp-server 0.17.0-dev.441 → 0.18.0-dev.443

package/dist/index.js

@@ -284,6 +284,10 @@ var TaigaClient = class {
 	async getBacklogItem(itemId, signal) {
 		return this.request("GET", `/backlog/${seg(itemId)}`, void 0, { signal });
 	}
+	/** The initiative's history, oldest first: every turn event and audited move, each with who did it. */
+	async listBacklogItemActivity(itemId) {
+		return this.request("GET", `/backlog/${seg(itemId)}/activity`);
+	}
 	/** A person's move on the line board: the column dropped into, and what to follow there. */
 	async transitionInitiative(itemId, body) {
 		return this.request("PUT", `/backlog/${seg(itemId)}/state`, body);
@@ -2178,7 +2182,7 @@ const BY_ARGUMENT = {
 	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.",
+	environmentId: "taiga_list_environments 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)."
 };
@@ -2473,17 +2477,23 @@ function budgetSections(doc, budget) {
 	return cutTo(doc, sections, Object.fromEntries(kept));
 }
 /**
+* The `sections` input of a document read: some sections by id, none for the
+* outline (every id with its size and no text), or omitted for the whole.
+*/
+const sectionsInput = z.array(z.string().min(1).max(200)).max(50).optional().describe("Only these sections, by id; [] for the outline (every section id and its size, no text); omit for the whole document");
+/**
 * 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.
+* unknownSections. One shape whatever matched (PRO-2778): a wrong id does not
+* throw away the right ones, and an answer with none right still lists every
+* real id with its size, so the retry needs nothing else. No ids is the
+* outline.
 */
 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,
@@ -2847,7 +2857,7 @@ function registerProductTools(server, client) {
 		}));
 		server.registerTool("taiga_list_product_documents", {
 			title: "List product documents",
-			description: `List a product's documents on both timelines, as summaries (type, name, version, draft state, review and update times), and say which timeline is the product's own (defaultOrigin). Two timelines: ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} An empty side comes with a note saying why; a side the API could not list is null, with a note. Use taiga_get_product_document with the type and origin to read one in full.`,
+			description: `List a product's documents on both timelines, as summaries (type, name, version, draft state, review and update times), and say which timeline is the product's own (defaultOrigin). Two timelines: ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} An empty side comes with a note saying why; a side the API could not list is null, with a note. Use taiga_get_product_document with the type and origin to read one in full, or with sections: [] for its outline (section ids and sizes) first.`,
 			inputSchema: z.object({ productId }),
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
@@ -2856,12 +2866,12 @@ 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 and any id the document lacks (unknownSections). 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: sections: [] reads its outline (every section id with its size, no text) on either timeline, then name the sections you need 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"),
 				origin: originInput,
-				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")
+				sections: sectionsInput
 			}),
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
@@ -2993,10 +3003,10 @@ 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 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.",
+			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, or sections: [] for the outline) and the read carries only those, listing the rest with their sizes and any id the document lacks (unknownSections). A read that finds no document 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")
+				sections: sectionsInput
 			}),
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
@@ -3399,6 +3409,51 @@ const ITEM_OUTCOME_FIELDS = [
 	"archivedAt",
 	"lifecycle"
 ];
+/** What each plan failure cause means for whoever reads it next (PLAN_FAILURE_CAUSES in @taiga/types). */
+const PLAN_FAILURE_MEANING = {
+	agent_error: "The planning agent failed. Planning again is the usual next step.",
+	worker_lost: "Nobody was running the planning any more (the worker stopped). Planning again is the usual next step.",
+	cancelled: "A person stopped the planning (by says who). Ask before planning it again."
+};
+/**
+* Who or what ended a failed plan, and when, from the initiative's history
+* (PRO-2780): planFailureCause alone said "cancelled" with nobody behind it.
+* Best effort: a history the API will not give leaves the item as it was.
+*/
+async function planFailureOf(client, itemId, itemCause) {
+	let events;
+	try {
+		events = (await client.listBacklogItemActivity(itemId)).data;
+	} catch (error) {
+		if (error instanceof TaigaApiError || isNetworkFailure(error)) return null;
+		throw error;
+	}
+	let failed;
+	for (const event of [...events].reverse()) {
+		if (event.kind !== "turn") continue;
+		if (event.trigger === "plan_started") break;
+		if (event.trigger === "plan_failed") {
+			failed = event;
+			break;
+		}
+	}
+	if (!failed) return null;
+	const actor = failed.actor ?? {};
+	const data = failed.data ?? {};
+	const cause = typeof data.cause === "string" ? data.cause : null;
+	if (typeof itemCause === "string" && cause !== itemCause) return {
+		cause: itemCause,
+		meaning: PLAN_FAILURE_MEANING[itemCause] ?? "Planning ended without a plan.",
+		at: null,
+		by: null
+	};
+	return {
+		cause,
+		meaning: (cause && PLAN_FAILURE_MEANING[cause]) ?? "Planning ended without a plan.",
+		at: failed.occurredAt ?? null,
+		by: typeof actor.name === "string" ? actor.name : actor.type ?? null
+	};
+}
 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. */
@@ -3505,11 +3560,17 @@ function registerBacklogReads(server, client) {
 	}));
 	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. 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.",
+		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. A failed plan carries planFailure: the cause, what it means, when, and by whom. 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);
+		const item = (await client.getBacklogItem(params.itemId)).data;
+		if (item.planningStatus !== "failed") return toolResult(item);
+		const planFailure = await planFailureOf(client, params.itemId, item.planFailureCause);
+		return toolResult(planFailure ? {
+			...item,
+			planFailure
+		} : item);
 	}));
 	server.registerTool("taiga_get_plan", {
 		title: "Get the active plan",
@@ -3572,7 +3633,7 @@ const BUILD_STATION = /* @__PURE__ */ new Set(["plan", "build"]);
 function registerPlanAgain(server, client) {
 	server.registerTool("taiga_plan_again", {
 		title: "Plan an initiative again",
-		description: "Supersede the plan of the initiative at the Build station and ask the planner for a new one: for a plan that failed, a plan you do not want built, or a run whose direction was wrong once it has stopped. The earlier plan is kept, and every run records which plan version it built; a pull request still open stays open. Offered only when the turn is yours: refused (CONFLICT) while an agent holds it (planning, building, reviewing). Also refused while a dependency is still in flight or a UI direction has no chosen concept, unless force says to plan anyway, which only the person decides. Anywhere off the Build station, put the initiative in the queue instead (taiga_queue_backlog_item): the queue is the only way to start work. To send a plan back with direction, taiga_reject_plan. Starts a planner run; ask the person first.",
+		description: "Supersede the plan of the initiative at the Build station and ask the planner for a new one: for a plan that failed, a plan you do not want built, or a run whose direction was wrong once it has stopped. The earlier plan is kept, and every run records which plan version it built; a pull request still open stays open. Offered only when the turn is yours: refused (CONFLICT) while an agent holds it (planning, building, reviewing). Also refused while a dependency is still in flight or a UI direction has no chosen concept, unless force says to plan anyway, which only the person decides. Anywhere off the Build station, put the initiative in the queue instead (taiga_queue_backlog_item): the queue is the only way to start work. To send a plan back with direction, taiga_reject_plan. Starts a planner run.",
 		inputSchema: z.object({
 			itemId,
 			force: z.boolean().optional().describe("Plan anyway past an unsettled dependency or an unchosen UI direction; only when the person says so")
@@ -3657,7 +3718,7 @@ function registerQueue(server, client) {
 function registerReviewGate(server, client) {
 	server.registerTool("taiga_set_auto_build", {
 		title: "Set an initiative's review gate",
-		description: "Set whether an initiative's plan is built as soon as it lands (true) or waits for a person to read it and approve or reject it (false); null follows the product's default. Standing: it applies to every plan the initiative gets, including one being written now. Opening the gate on a plan that is already waiting starts its build, so ask the person first. Returns the initiative with the gate that now applies.",
+		description: "Set whether an initiative's plan is built as soon as it lands (true) or waits for a person to read it and approve or reject it (false); null follows the product's default. Standing: it applies to every plan the initiative gets, including one being written now. Opening the gate on a plan that is already waiting starts its build at once. Returns the initiative with the gate that now applies.",
 		inputSchema: z.object({
 			itemId,
 			autoBuild: autoBuildInput
@@ -3676,7 +3737,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, 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.",
+		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.",
 		inputSchema: z.object({ itemId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => outcome((await client.resumeInitiative(params.itemId)).data)));
@@ -3684,13 +3745,13 @@ function registerResume(server, client) {
 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.",
+		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.",
 		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.",
+		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.",
 		inputSchema: z.object({
 			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")
@@ -3943,6 +4004,17 @@ function withoutCitations(doc) {
 		dropped
 	};
 }
+/**
+* How much of the two documents the bundle carries. The outline by default
+* (PRO-2778): the whole sections that fit a budget made the opening read run
+* to 43k characters for an active product, most of it prose a "where does it
+* stand" question never reads.
+*/
+const DOCUMENT_DEPTHS = [
+	"outline",
+	"budget",
+	"full"
+];
 /** Pages of 100 the backlog part follows before it stops and says so. */
 const BACKLOG_PAGE_LIMIT = 10;
 /**
@@ -4005,7 +4077,7 @@ async function factoryPart(client, factoryId) {
 }
 /**
 * The specification and architecture from the product's own timeline: their
-* whole sections up to a budget by default, in full or as section ids when
+* outline by default, the whole sections up to a budget or in full when
 * asked. Null, with a note, where unpublished.
 */
 async function documentsPart(client, product, depth) {
@@ -4039,11 +4111,16 @@ async function documentsPart(client, product, depth) {
 				} else out[type] = cut.doc;
 			} else {
 				const sections = sectionsOf(doc.data ?? {});
-				if (sections) out[type] = {
-					version: doc.version,
-					sections: Object.keys(sections)
-				};
-				else {
+				if (sections) {
+					const outline = Object.keys(sections).map((id) => ({
+						id,
+						characters: sectionContent(sections, id)?.length ?? 0
+					}));
+					out[type] = {
+						version: doc.version,
+						sections: outline
+					};
+				} else {
 					out[type] = {
 						version: doc.version,
 						sections: null
@@ -4160,7 +4237,7 @@ async function productContext(client, product, options) {
 		...bundle,
 		notGranted: notGranted.map((part) => `${part} (needs ${PARTS[part]})`),
 		unavailable,
-		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."
+		readNext: "Read a policy with taiga_get_document (sections: the ids listed here, for only those), the specification's or architecture's sections or 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;) {
@@ -4179,12 +4256,12 @@ function registerContextTools(server, client) {
 	if (!client.hasCapability("products:read")) return;
 	server.registerTool("taiga_get_product_context", {
 		title: "Get product context",
-		description: `Everything a coding session starts from, in one call: the product and which document timeline is its own, its factory with the instructions in full, the specification and architecture from that timeline, every published policy as its section ids, the open backlog items, the linked repositories and the latest runs. Name the product by ID, slug or the git remote URL of the checkout. A part the API refused or failed is named under unavailable with what it said; a part the key cannot read is named under notGranted; neither is shown as empty. The two documents bring as many whole sections as fit, about ${DOCUMENT_BUDGET / 1e3}k characters each, and name the sections left out (omittedSections) for taiga_get_product_document to read; fullDocuments: true carries them whole, tens of thousands of tokens on a large product and more than some clients accept, and false carries their section ids only. characters says how large the result is. Call this first, then read what you need.`,
+		description: `Everything a coding session starts from, in one call: the product and which document timeline is its own, its factory with the instructions in full, the specification and architecture from that timeline, every published policy as its section ids, the open backlog items, the linked repositories and the latest runs. Name the product by ID, slug or the git remote URL of the checkout. A part the API refused or failed is named under unavailable with what it said; a part the key cannot read is named under notGranted; neither is shown as empty. The two documents come as their outline by default: each section id with its size, to read with taiga_get_product_document naming the sections. Before writing code, documents: budget brings as many whole sections as fit, about ${DOCUMENT_BUDGET / 1e3}k characters each, naming the ones left out; full brings them whole, tens of thousands of tokens on a large product and more than some clients accept. characters says how large the result is. Call this first, then read what you need.`,
 		inputSchema: z.object({
 			productId: productId.optional(),
 			slug: slug.optional(),
 			remoteUrl: remoteUrl.optional(),
-			fullDocuments: z.boolean().optional().describe("true carries the specification and architecture whole, false as section ids only; omit for the whole sections that fit a budget")
+			documents: z.enum(DOCUMENT_DEPTHS).optional().describe("The specification and architecture as outline (section ids and sizes, the default), budget (the whole sections that fit) or full")
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
@@ -4194,8 +4271,7 @@ function registerContextTools(server, client) {
 			"remoteUrl"
 		]);
 		if ("refusal" in resolved) return toolError(resolved.refusal.code, resolved.refusal.message);
-		const documents = params.fullDocuments === void 0 ? "budget" : params.fullDocuments ? "full" : "sectionIds";
-		return productContext(client, resolved.product, { documents });
+		return productContext(client, resolved.product, { documents: params.documents ?? "outline" });
 	}));
 }
 //#endregion
@@ -4203,7 +4279,7 @@ function registerContextTools(server, client) {
 function registerAutonomyTools(server, client) {
 	if (client.hasCapability("products:write")) server.registerTool("taiga_set_product_autonomy", {
 		title: "Set a product's autonomy defaults",
-		description: "Set the defaults a product's initiatives follow when they have not decided for themselves. autoBuild: false makes every landed plan wait for a person to approve or reject it; true builds it as soon as the product has room. autoMerge: false makes pull requests wait for a person to merge them; null follows the organization and factory above (autonomous merge needs the organization's switch on, and a factory can turn it off for everything under it; neither can be opened from here). Defaults, not rules: an initiative can decide otherwise for itself. Changes how work proceeds; ask the person first.",
+		description: "Set the defaults a product's initiatives follow when they have not decided for themselves. autoBuild: false makes every landed plan wait for a person to approve or reject it; true builds it as soon as the product has room. autoMerge: false makes pull requests wait for a person to merge them; null follows the organization and factory above (autonomous merge needs the organization's switch on, and a factory can turn it off for everything under it; neither can be opened from here). Defaults, not rules: an initiative can decide otherwise for itself. Changes how work proceeds.",
 		inputSchema: z.object({
 			productId,
 			autoBuild: z.boolean().optional().describe("Build landed plans without a review by default"),
@@ -4227,7 +4303,7 @@ function registerAutonomyTools(server, client) {
 	}));
 	if (client.hasCapability("backlog:write")) server.registerTool("taiga_set_auto_merge", {
 		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.",
+		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.",
 		inputSchema: z.object({
 			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")
@@ -4279,11 +4355,15 @@ const SETUP_TASK_FIELDS = [
 	"inboxItemStatus",
 	"createdAt"
 ];
+/** The API's count across every page, on the first page; nothing from an API that does not send one. */
+function totalOf(result) {
+	return typeof result.totalCount === "number" ? { totalCount: result.totalCount } : {};
+}
 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 (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.",
+		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). The first page says how many there are on every page (totalCount, snoozed ones included). 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"),
@@ -4295,7 +4375,8 @@ function registerInboxTools(server, client) {
 		const { resolved, ...rest } = params;
 		const result = await client.listInbox({
 			...rest,
-			...resolved ? { resolved: true } : {}
+			...resolved ? { resolved: true } : {},
+			...params.cursor === void 0 ? { withTotal: true } : {}
 		});
 		const now = Date.now();
 		const rows = result.data;
@@ -4303,12 +4384,13 @@ function registerInboxTools(server, client) {
 		const hidden = rows.length - due.length;
 		return toolResult({
 			...page(pickFields(due, ITEM_FIELDS), result.nextCursor),
+			...totalOf(result),
 			...hidden > 0 ? { snoozedHidden: hidden } : {}
 		});
 	}));
 	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 (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.",
+		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. The first page says how many there are on every page (totalCount).",
 		inputSchema: z.object({
 			productId: productId.optional(),
 			includeDone: z.boolean().optional().describe("Also the tasks already done or dismissed (default false)"),
@@ -4319,9 +4401,13 @@ function registerInboxTools(server, client) {
 		const { includeDone, ...rest } = params;
 		const result = await client.listSetupTasks({
 			...rest,
-			...includeDone ? {} : { openOnly: true }
+			...includeDone ? {} : { openOnly: true },
+			...params.cursor === void 0 ? { withTotal: true } : {}
+		});
+		return toolResult({
+			...page(pickFields(result.data, SETUP_TASK_FIELDS), result.nextCursor),
+			...totalOf(result)
 		});
-		return toolResult(page(pickFields(result.data, SETUP_TASK_FIELDS), result.nextCursor));
 	}));
 	if (!client.hasCapability("products:write")) return;
 	server.registerTool("taiga_resolve_action", {
@@ -4477,7 +4563,7 @@ function registerKnowledgeTools(server, client) {
 	if (!client.hasCapability("customDocuments:write")) return;
 	server.registerTool("taiga_add_knowledge", {
 		title: "Add knowledge",
-		description: "File a Markdown or plain-text reference document as knowledge, at the level it is relevant: a product (productId), a factory (factoryId), or the organization (neither; that takes an owner or admin, because every factory and product inherits it). Good candidates are what a new engineer would be handed to read: specifications and contracts to conform to, glossaries and code lists, third-party documentation, internal write-ups. A rule that applies every time belongs in instructions instead. The file is processed before agents can read it; taiga_list_knowledge says when it is ready. PDFs and spreadsheets are added in the web. The same content already filed at that level comes back as that file, with deduplicated: true: it was not created here, so do not delete it as if it were. Every agent at that level reads it from then on, and processing it is paid work; ask the person first.",
+		description: "File a Markdown or plain-text reference document as knowledge, at the level it is relevant: a product (productId), a factory (factoryId), or the organization (neither; that takes an owner or admin, because every factory and product inherits it). Good candidates are what a new engineer would be handed to read: specifications and contracts to conform to, glossaries and code lists, third-party documentation, internal write-ups. A rule that applies every time belongs in instructions instead. The file is processed before agents can read it; taiga_list_knowledge says when it is ready. PDFs and spreadsheets are added in the web. The same content already filed at that level comes back as that file, with deduplicated: true: it was not created here, so do not delete it as if it were. Every agent at that level reads it from then on, and processing it is paid work.",
 		inputSchema: z.object({
 			...scopeInputs,
 			fileName: z.string().trim().min(1).max(200).regex(/\.(md|txt)$/i, "A Markdown (.md) or plain-text (.txt) file name").describe("The file name, ending in .md or .txt"),
@@ -4502,14 +4588,14 @@ function registerKnowledgeTools(server, client) {
 	}));
 	server.registerTool("taiga_retry_knowledge", {
 		title: "Retry processing a knowledge file",
-		description: "Retry processing a knowledge file that failed (status failed): until it is processed, nothing reads it. Processing is paid work; ask the person first.",
+		description: "Retry processing a knowledge file that failed (status failed): until it is processed, nothing reads it. Processing is paid work.",
 		inputSchema: z.object({ knowledgeId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => toolResult(pickFields([(await client.retryKnowledge(params.knowledgeId)).data], KNOWLEDGE_FIELDS)[0])));
 	if (!client.hasCapability("customDocuments:delete")) return;
 	server.registerTool("taiga_delete_knowledge", {
 		title: "Delete a knowledge file",
-		description: "Delete a knowledge file that is stale or wrong: stale reference material is worse than none, because it is confidently specific, and nothing expires on its own. Agents stop reading it at once. It cannot be undone; ask the person first. Organization knowledge takes an owner or admin.",
+		description: "Delete a knowledge file that is stale or wrong: stale reference material is worse than none, because it is confidently specific, and nothing expires on its own. Agents stop reading it at once. It cannot be undone. Organization knowledge takes an owner or admin.",
 		inputSchema: z.object({ knowledgeId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
@@ -4617,7 +4703,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, 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.",
+		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 breached by scanner findings counts them by tier (findingsByTier): a breach of routine findings only, such as secrets in test fixtures, is not an urgent one. 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)")
@@ -4657,6 +4743,7 @@ function registerMaintenanceTools(server, client) {
 				"state",
 				"divergenceCount",
 				"findingCount",
+				"findingsByTier",
 				"plannedCount"
 			]),
 			violations: pickFields(violations, VIOLATION_FIELDS)
@@ -4687,7 +4774,7 @@ function registerMaintenanceTools(server, client) {
 	}));
 	server.registerTool("taiga_fix_finding", {
 		title: "Fix a finding",
-		description: "Ask for a finding's fix: Taiga raises an initiative and adds it to the end of the product's queue, where the line plans it in turn; whether the build then waits for a person is the initiative's review gate, as for any initiative. The fix is a normal run that ends in a pull request you review and merge. With wholeGroup: true it fixes the finding's whole group in one initiative, as the page does: for a dependency, every open advisory on that package at that installed version in one version bump; for code or infrastructure, every location the same rule flagged. Absent for a secret only in history, anything in a submodule, and a dependency with no fixed version (remediableBy says upstream_only); the API refuses those. Starts paid work; ask the person first.",
+		description: "Ask for a finding's fix: Taiga raises an initiative and adds it to the end of the product's queue, where the line plans it in turn; whether the build then waits for a person is the initiative's review gate, as for any initiative. The fix is a normal run that ends in a pull request you review and merge. With wholeGroup: true it fixes the finding's whole group in one initiative, as the page does: for a dependency, every open advisory on that package at that installed version in one version bump; for code or infrastructure, every location the same rule flagged. Absent for a secret only in history, anything in a submodule, and a dependency with no fixed version (remediableBy says upstream_only); the API refuses those. Starts paid work.",
 		inputSchema: z.object({
 			productId,
 			findingId,
@@ -4713,7 +4800,7 @@ function registerMaintenanceTools(server, client) {
 	}));
 	server.registerTool("taiga_fix_policy_violation", {
 		title: "Fix policy violations",
-		description: "Ask for the fix of a product's policy violations: name a control to cover every violation recorded against it that has no initiative yet, or a single violation (violationId) when the control has more than one. Taiga raises one initiative and adds it to the end of the product's queue, exactly as a finding fix does. The violation stays listed while the work is under way: only the next assessment can record that the documents no longer show it. Starts paid work; ask the person first.",
+		description: "Ask for the fix of a product's policy violations: name a control to cover every violation recorded against it that has no initiative yet, or a single violation (violationId) when the control has more than one. Taiga raises one initiative and adds it to the end of the product's queue, exactly as a finding fix does. The violation stays listed while the work is under way: only the next assessment can record that the documents no longer show it. Starts paid work.",
 		inputSchema: z.object({
 			productId,
 			controlId: z.string().min(1).max(40).optional().describe("The control's identifier, e.g. SEC-3.4"),
@@ -4755,8 +4842,13 @@ const ENVIRONMENT_FIELDS = [
 	"isProtected",
 	"url"
 ];
-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)`);
+const environmentId = idInput("environment", "taiga_list_environments lists them; a product ID is not one");
+/** The windows the pages offer, as the schema's own values rather than a number checked afterwards. */
+const windowDays = z.literal([
+	30,
+	60,
+	90
+]).optional().describe("Days to look back: 30, 60 or 90 (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);
 /** A part that may fail on its own without failing the read: null and the reason, or the value. */
@@ -4828,22 +4920,30 @@ function registerObserveTools(server, client) {
 			...note ? { note } : {}
 		});
 	}));
+	server.registerTool("taiga_list_environments", {
+		title: "List a product's environments",
+		description: "The places a product's software runs (development, staging, production or its own ladder), each with its ID, type, order and App URL. The environment IDs taiga_get_delivery_metrics, taiga_get_monitoring and taiga_update_environment take. taiga_get_deployments lists them too, beside what runs where.",
+		inputSchema: z.object({ productId }),
+		annotations: READ_ONLY
+	}, (params) => runTool(async () => {
+		const { rows, more } = await allEnvironments(client, params.productId);
+		return toolResult({
+			data: pickFields(rows, ENVIRONMENT_FIELDS),
+			...more ? { more: "More environments than this answer reads; the rest were left out." } : {},
+			...rows.length === 0 ? { note: "No environment is defined yet; taiga_define_environment adds one." } : {}
+		});
+	}));
 	server.registerTool("taiga_get_delivery_metrics", {
 		title: "Get delivery metrics",
 		description: "DORA's five software delivery metrics for one environment (the one marked production, as the page reports them), computed from its deployment history over the last 30, 60 or 90 days: deployment frequency, lead time and failed deployment recovery time (throughput), change-failure rate and rework rate (instability), each with its trend against the window before, and a performance band for all but rework rate, which DORA has published none for. Failures and recoveries are read from deployments, not incidents. A trend built on fewer than ten deployments is approximate; a metric no deployment fed says so instead of showing a number. Previews and checks do not count.",
 		inputSchema: z.object({
 			productId,
 			environmentId,
-			windowDays: windowDays("30, 60 or 90")
+			windowDays
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
 		const days = params.windowDays ?? 30;
-		if (![
-			30,
-			60,
-			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", {
@@ -4852,7 +4952,7 @@ function registerObserveTools(server, client) {
 		inputSchema: z.object({
 			productId,
 			environmentId: environmentId.optional(),
-			windowDays: windowDays("30, 60 or 90")
+			windowDays
 		}),
 		annotations: READ_ONLY
 	}, (params) => runTool(async () => {
@@ -4862,11 +4962,6 @@ function registerObserveTools(server, client) {
 			...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_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)),
@@ -4892,7 +4987,7 @@ function registerObserveTools(server, client) {
 	if (!client.hasCapability("products:write")) return;
 	server.registerTool("taiga_define_environment", {
 		title: "Define an environment",
-		description: "Add a place a product's software runs: development, staging, production or whatever ladder it uses. Deployments are recorded against an environment, monitoring is reported per environment, and plans read where the work will run. Describing one gives Taiga no access to it: the pipeline deploys, Taiga learns what happened from source control. Member-level work. Give it its App URL afterwards with taiga_update_environment, which is all monitoring needs to start checking. Changes the product's setup for everybody; ask the person first.",
+		description: "Add a place a product's software runs: development, staging, production or whatever ladder it uses. Deployments are recorded against an environment, monitoring is reported per environment, and plans read where the work will run. Describing one gives Taiga no access to it: the pipeline deploys, Taiga learns what happened from source control. Member-level work. Give it its App URL afterwards with taiga_update_environment, which is all monitoring needs to start checking. Changes the product's setup for everybody.",
 		inputSchema: z.object({
 			productId,
 			name: z.string().trim().min(1).max(100).describe("What the team calls it, e.g. staging"),
@@ -4908,7 +5003,7 @@ function registerObserveTools(server, client) {
 	}));
 	server.registerTool("taiga_update_environment", {
 		title: "Update an environment",
-		description: "Rename an environment, change its kind, or set its public App URL (null clears it). The App URL is all monitoring needs: once it is saved, Taiga checks the app's availability every few minutes on its own. Marking an environment production makes it the one delivery metrics report on. Changes the product's setup for everybody; ask the person first.",
+		description: "Rename an environment, change its kind, or set its public App URL (null clears it). The App URL is all monitoring needs: once it is saved, Taiga checks the app's availability every few minutes on its own. Marking an environment production makes it the one delivery metrics report on. Changes the product's setup for everybody.",
 		inputSchema: z.object({
 			environmentId,
 			name: z.string().trim().min(1).max(100).optional().describe("A new name"),
@@ -4967,11 +5062,11 @@ function registerProductDocumentWrites(server, client) {
 			productId,
 			type: reviewableType
 		}),
-		annotations: WRITE
+		annotations: OPERATE
 	}, (params) => runTool(async () => toolResult((await client.markProductDocumentReviewed(params.productId, params.type)).data)));
 	if (canRead) server.registerTool("taiga_regenerate_product_document", {
 		title: "Regenerate a product document",
-		description: "Ask an agent to generate one product document again from the documents it is derived from, for one marked outdated or one that needs another pass. The Specification comes from the Discovery conversation and the Look & Feel from its concepts, both in the web. The documents Discovery requires are regenerated while it is open only: a finished Discovery locks them, and reopening it is done in the web. The optional Service Blueprint can be generated whenever someone wants one. The result is published as the new version, and the documents generated from it are marked outdated in turn. Runs an agent in the background: this returns the job; taiga_wait_for_job says when it is done. Ask the person first.",
+		description: "Ask an agent to generate one product document again from the documents it is derived from, for one marked outdated or one that needs another pass. The Specification comes from the Discovery conversation and the Look & Feel from its concepts, both in the web. The documents Discovery requires are regenerated while it is open only: a finished Discovery locks them, and reopening it is done in the web. The optional Service Blueprint can be generated whenever someone wants one. The result is published as the new version, and the documents generated from it are marked outdated in turn. Runs an agent in the background: this returns the job; taiga_wait_for_job says when it is done.",
 		inputSchema: z.object({
 			productId,
 			type: generatedType
@@ -4990,13 +5085,13 @@ function registerProductDocumentWrites(server, client) {
 	}));
 	server.registerTool("taiga_generate_product_documents", {
 		title: "Generate the remaining product documents",
-		description: "Generate remaining: every document the product still needs, and every one marked outdated, in the order they build on each other, one after another (each next one starts when the one before it is published). Refused (CONFLICT) while a document is already being generated. On an imported product, it queues every unpublished document. Runs agents in the background: this returns the jobs it started (jobIds); taiga_stop_generating_documents stops the run. Ask the person first.",
+		description: "Generate remaining: every document the product still needs, and every one marked outdated, in the order they build on each other, one after another (each next one starts when the one before it is published). Refused (CONFLICT) while a document is already being generated. On an imported product, it queues every unpublished document. Runs agents in the background: this returns the jobs it started (jobIds); taiga_stop_generating_documents stops the run.",
 		inputSchema: z.object({ productId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => toolResult((await client.generateRemainingDocuments(params.productId)).data)));
 	server.registerTool("taiga_stop_generating_documents", {
 		title: "Stop generating product documents",
-		description: "Stop a Generate remaining run: every document of it still being generated is cancelled and nothing after them starts; published documents stay. An empty list means no run was going. Interrupts agent work; ask the person first.",
+		description: "Stop a Generate remaining run: every document of it still being generated is cancelled and nothing after them starts; published documents stay. An empty list means no run was going. Interrupts agent work.",
 		inputSchema: z.object({ productId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => toolResult((await client.stopGeneratingDocuments(params.productId)).data)));
@@ -19738,6 +19833,13 @@ const GITHUB_REPOSITORY_FIELDS = [
 	"language"
 ];
 const repositoryId = idInput("repository link", "taiga_list_product_repositories gives it; a GitHub repository id is not one");
+/** Round-robin over lists: the first of each, then the second of each, and so on. */
+function interleave(lists) {
+	const out = [];
+	const longest = Math.max(0, ...lists.map((list) => list.length));
+	for (let index = 0; index < longest; index++) for (const list of lists) if (index < list.length) out.push(list[index]);
+	return out;
+}
 function registerRepositoryTools(server, client) {
 	if (client.hasCapability("products:read")) {
 		server.registerTool("taiga_list_product_repositories", {
@@ -19746,7 +19848,11 @@ function registerRepositoryTools(server, client) {
 			inputSchema: z.object({ productId }),
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult(pickFields((await client.listProductRepositories(params.productId)).data, LINK_FIELDS));
+			const result = await client.listProductRepositories(params.productId);
+			return toolResult({
+				data: pickFields(result.data, LINK_FIELDS),
+				truncated: result.nextCursor !== null
+			});
 		}));
 		server.registerTool("taiga_list_repository_branches", {
 			title: "List a repository's branches",
@@ -19759,16 +19865,17 @@ function registerRepositoryTools(server, client) {
 		}, (params) => runTool(async () => {
 			const result = await client.listRepositoryBranches(params.productId, params.repositoryId);
 			return toolResult({
-				branches: result.data,
+				data: result.data,
 				truncated: result.truncated
 			});
 		}));
 	}
 	if (client.hasCapability("vcs:read")) server.registerTool("taiga_list_linkable_repositories", {
 		title: "Find a repository to link",
-		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.",
+		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. Name the GitHub account (account: its login, the owner in owner/repo, or installationId) to read only its repositories; without one it reads every connected account and takes rows from each in turn, so one account cannot fill the page. 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"),
+			account: z.string().trim().min(1).max(140).optional().describe("The GitHub account login (the owner in owner/repo), case-insensitive"),
 			installationId: idInput("GitHub account", "this tool lists them").optional(),
 			...pagination
 		}),
@@ -19777,10 +19884,11 @@ function registerRepositoryTools(server, client) {
 		const installations = (await client.listGithubInstallations()).data;
 		const accounts = pickFields(installations, INSTALLATION_FIELDS);
 		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;
+		const login = params.account?.split("/")[0].toLowerCase();
+		const chosen = installations.filter((i) => (!params.installationId || i.id === params.installationId) && (!login || String(i.accountLogin ?? "").toLowerCase() === login));
 		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_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 });
+		if (chosen.length > 1 && params.cursor !== void 0) return toolError("VALIDATION_ERROR", "A cursor pages one account: name it (account or installationId).", { accounts });
 		const max = params.limit ?? 25;
 		const rows = (data) => pickFields(data, GITHUB_REPOSITORY_FIELDS);
 		if (chosen.length === 1) {
@@ -19800,18 +19908,18 @@ function registerRepositoryTools(server, client) {
 			q: params.query,
 			limit: max
 		})));
-		const found = pages.flatMap((p) => rows(p.data));
+		const found = interleave(pages.map((p) => rows(p.data)));
 		const cut = found.length > max || pages.some((p) => p.nextCursor);
 		return toolResult({
 			accounts,
 			repositories: page(found.slice(0, max), null),
-			...cut ? { more: "More than the limit across accounts: name an installationId, or narrow the query." } : {}
+			...cut ? { more: "More than the limit across accounts: name an account, or narrow the query." } : {}
 		});
 	}));
 	if (!client.hasCapability("vcs:manage")) return;
 	server.registerTool("taiga_link_repository", {
 		title: "Link a repository to a product",
-		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.",
+		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.",
 		inputSchema: z.object({
 			productId,
 			githubRepositoryId: idInput("GitHub repository", "taiga_list_linkable_repositories gives it"),
@@ -19826,7 +19934,7 @@ function registerRepositoryTools(server, client) {
 	}));
 	server.registerTool("taiga_set_repository_branch", {
 		title: "Choose the branch Taiga works on",
-		description: "Choose the branch of a product's repository that Taiga branches from and opens its pull requests against (taiga_list_repository_branches lists them), or null to follow the repository's default again. A protected branch is not refused, but Taiga may not be able to merge into it: the answer says when it is protected. Optionally a label for the link. Ask the person first.",
+		description: "Choose the branch of a product's repository that Taiga branches from and opens its pull requests against (taiga_list_repository_branches lists them), or null to follow the repository's default again. A protected branch is not refused, but Taiga may not be able to merge into it: the answer says when it is protected. Optionally a label for the link.",
 		inputSchema: z.object({
 			productId,
 			repositoryId,
@@ -19847,7 +19955,7 @@ function registerRepositoryTools(server, client) {
 	}));
 	server.registerTool("taiga_unlink_repository", {
 		title: "Unlink a repository from a product",
-		description: "Unlink a repository from a product. Without one, the product can still have documents and initiatives but no changes: nothing is planned against code, built or swept. The repository itself is untouched, and a repository Taiga created for the product cannot be unlinked. To swap it for another, use taiga_link_repository with replacesRepositoryId instead. Ask the person first.",
+		description: "Unlink a repository from a product. Without one, the product can still have documents and initiatives but no changes: nothing is planned against code, built or swept. The repository itself is untouched, and a repository Taiga created for the product cannot be unlinked. To swap it for another, use taiga_link_repository with replacesRepositoryId instead.",
 		inputSchema: z.object({
 			productId,
 			repositoryId
@@ -20063,7 +20171,7 @@ function registerSetupTools(server, client) {
 		}, (params) => runTool(async () => toolResult(pickFields([(await client.createFactory({ name: params.name })).data], FACTORY_FIELDS)[0])));
 		server.registerTool("taiga_rename_factory", {
 			title: "Rename a factory",
-			description: "Rename a factory. Its products, members, knowledge and instructions stay as they are, but its slug follows the new name, so links to the factory change. Ask the person first.",
+			description: "Rename a factory. Its products, members, knowledge and instructions stay as they are, but its slug follows the new name, so links to the factory change.",
 			inputSchema: z.object({
 				factoryId,
 				name: z.string().trim().min(1).max(255).describe("The new name")
@@ -20081,7 +20189,7 @@ function registerSetupTools(server, client) {
 		}, (params) => runTool(async () => toolResult((await client.previewProductMove(params.productId, params.factoryId)).data)));
 		server.registerTool("taiga_move_product", {
 			title: "Move a product to another factory",
-			description: "Move a product to another factory. Access follows the factory, so this changes who can reach the product (taiga_preview_product_move says who); the product's own knowledge files are re-filed onto the new factory, and factory knowledge and instructions stay with the factory that owns them. Refused (CONFLICT) while a plan or build is in flight: stopLine: true stops the line first and then moves, which interrupts that work. Ask the person first.",
+			description: "Move a product to another factory. Access follows the factory, so this changes who can reach the product (taiga_preview_product_move says who); the product's own knowledge files are re-filed onto the new factory, and factory knowledge and instructions stay with the factory that owns them. Refused (CONFLICT) while a plan or build is in flight: stopLine: true stops the line first and then moves, which interrupts that work.",
 			inputSchema: z.object({
 				productId,
 				factoryId: factoryId.describe("The factory to move it to"),
@@ -20105,7 +20213,7 @@ function registerSetupTools(server, client) {
 	if (!client.hasCapability("products:write")) return;
 	server.registerTool("taiga_create_product", {
 		title: "Create a product",
-		description: "Create a product in a factory, the way New product does. It starts one of two ways, chosen now and not later: scratch, where Discovery is a conversation that writes the specification (held in the web), or import (projectType brownfield), where Taiga reads an existing repository and drafts the documents from the code: link the repository (taiga_link_repository; linking is for owners and admins, so a member asks one), then taiga_start_import. Also what Taiga builds for it: its infrastructure code and its CI/CD pipelines, each following the organization unless decided here; when one is off, deploymentNotes says in a sentence how that half is done today. Material the product should be built from is worth adding before Discovery starts (taiga_add_knowledge with the productId): what is added first shapes the specification.",
+		description: "Create a product in a factory, the way New product does. It starts one of two ways, chosen now and not later: scratch (afterwards projectType greenfield), where Discovery is a conversation that writes the specification (held in the web), or import (projectType brownfield), where Taiga reads an existing repository and drafts the documents from the code: link the repository (taiga_link_repository; linking is for owners and admins, so a member asks one), then taiga_start_import. Also what Taiga builds for it: its infrastructure code and its CI/CD pipelines, each following the organization unless decided here; when one is off, deploymentNotes says in a sentence how that half is done today. Material the product should be built from is worth adding before Discovery starts (taiga_add_knowledge with the productId): what is added first shapes the specification.",
 		inputSchema: z.object({
 			factoryId,
 			name: z.string().trim().min(1).max(255).describe("The product name"),
@@ -20129,7 +20237,7 @@ function registerSetupTools(server, client) {
 	}));
 	server.registerTool("taiga_update_product", {
 		title: "Change a product's settings",
-		description: "Change a product's name (its slug follows the name, so links to the product change) or what Taiga builds for it: its infrastructure code and CI/CD pipelines (null returns one to the organization default), the sentence on how a half Taiga does not build is done today, and whether it inherits the organization's design standards (null follows the default for how the product started). Later plans read the new answer; work already planned is not redone. Autonomy is taiga_set_product_autonomy. Ask the person first.",
+		description: "Change a product's name (its slug follows the name, so links to the product change) or what Taiga builds for it: its infrastructure code and CI/CD pipelines (null returns one to the organization default), the sentence on how a half Taiga does not build is done today, and whether it inherits the organization's design standards (null follows the default for how the product started). Later plans read the new answer; work already planned is not redone. Autonomy is taiga_set_product_autonomy.",
 		inputSchema: z.object({
 			productId,
 			name: z.string().trim().min(1).max(255).optional().describe("A new name"),
@@ -20152,7 +20260,7 @@ function registerSetupTools(server, client) {
 	}));
 	server.registerTool("taiga_refresh_reality_documents", {
 		title: "Refresh a product's documents from its code",
-		description: "Derive the reality documents again from the code on the branch Taiga works on (the link's effectiveBranch: the chosen branch, or the repository's default): all of them, or the ones named (with what they are derived from). For a document the import misread, refresh it rather than importing again; unchanged sections are not republished. Runs an agent in the background and returns the job; taiga_wait_for_job says when it is done. Ask the person first.",
+		description: "Derive the reality documents again from the code on the branch Taiga works on (the link's effectiveBranch: the chosen branch, or the repository's default): all of them, or the ones named (with what they are derived from). For a document the import misread, refresh it rather than importing again; unchanged sections are not republished. Runs an agent in the background and returns the job; taiga_wait_for_job says when it is done.",
 		inputSchema: z.object({
 			productId,
 			docTypes: z.array(z.enum(REALITY_DERIVED_DOCUMENT_TYPES)).min(1).max(REALITY_DERIVED_DOCUMENT_TYPES.length).optional().describe("The documents to refresh; omit for all")
@@ -20174,14 +20282,14 @@ function registerSetupTools(server, client) {
 	}));
 	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.",
+		description: "Reopen a finished product's Discovery so its documents can be amended; finish it again afterwards. Nothing built from them is undone.",
 		inputSchema: z.object({ productId }),
 		annotations: OPERATE
 	}, (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",
-		description: "Start the import of a product created to import a codebase: Taiga reads its linked repository and derives the full document set from the code, each document citing the files it came from. Importing is one decision; the rest runs by itself. The scanners then sweep the repository, the documents are assessed against the organization's policies, and the first initiatives are planned when Discovery is finished. Refused for a product started from scratch (the choice is made at creation), without a linked repository, or while an import runs. Runs agents in the background and returns the job; taiga_wait_for_job says when it is done (it takes a while). Ask the person first.",
+		description: "Start the import of a product created to import a codebase: Taiga reads its linked repository and derives the full document set from the code, each document citing the files it came from. Importing is one decision; the rest runs by itself. The scanners then sweep the repository, the documents are assessed against the organization's policies, and the first initiatives are planned when Discovery is finished. Refused for a product started from scratch (the choice is made at creation), without a linked repository, or while an import runs. Runs agents in the background and returns the job; taiga_wait_for_job says when it is done (it takes a while).",
 		inputSchema: z.object({ productId }),
 		annotations: OPERATE
 	}, (params) => runTool(async () => {
@@ -20545,14 +20653,29 @@ function withStrictInputs(server) {
 		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 ? {
+		const described = {
 			...config,
+			description: `${writeNotice(name, config.annotations)}${config.description ?? ""}`
+		};
+		return register(name, schema ? {
+			...described,
 			inputSchema: schema.strict()
-		} : config, withHint);
+		} : described, withHint);
 	});
 	return server;
 }
 /**
+* What a tool's annotations say, in its description's first words (PRO-2778).
+* Annotations are for the client: Claude Code does not show them to the
+* model, so an agent read 79 tools without knowing which ones write. A tool
+* with none is refused here, so no tool reaches the catalogue unclassified.
+*/
+function writeNotice(name, annotations) {
+	if (!annotations || annotations.readOnlyHint === void 0) throw new Error(`Tool ${name}: annotations must say whether it is read-only`);
+	if (annotations.readOnlyHint) return "";
+	return annotations.destructiveHint ? "Acts on paid or shared work: ask the person first. " : "Writes. ";
+}
+/**
 * Register all MCP tools, resources and prompts based on the API key's effective capabilities.
 * Only tools matching the key's scopes are registered -- the AI assistant
 * never sees tools it can't use.
@@ -20586,15 +20709,16 @@ const SERVER_INSTRUCTIONS = [
 		"**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.",
+		"instructions, the outline of 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: sections by id with",
+		"taiga_get_document or taiga_get_product_document (sections: [] is any document's outline), 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.",
+		"(stopping, pausing) or changes what others read (publishing, resolving, settings, repositories). Such a",
+		"tool says so first in its description; a client that prompts on destructive tools does part of it.",
 		"",
 		"**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.",