@taiga-ai/mcp-server 0.6.0 → 0.7.0-dev.396

package/dist/index.js

@@ -95,6 +95,7 @@ var TaigaClient = class {
 		const params = new URLSearchParams();
 		if (opts?.factoryId) params.set("factoryId", opts.factoryId);
 		if (opts?.status) params.set("status", opts.status);
+		if (opts?.slug) params.set("slug", opts.slug);
 		if (opts?.repository) params.set("repository", opts.repository);
 		if (opts?.repositoryHost) params.set("repositoryHost", opts.repositoryHost);
 		if (opts?.limit) params.set("limit", String(opts.limit));
@@ -145,12 +146,14 @@ var TaigaClient = class {
 	}
 	async listProductDocuments(productId, opts) {
 		const params = new URLSearchParams();
+		if (opts?.origin) params.set("origin", opts.origin);
 		if (opts?.limit) params.set("limit", String(opts.limit));
 		const qs = params.toString();
 		return this.request("GET", `/products/${seg(productId)}/documents${qs ? `?${qs}` : ""}`);
 	}
-	async getProductDocument(productId, type) {
-		return this.request("GET", `/products/${seg(productId)}/documents/${seg(type)}`);
+	async getProductDocument(productId, type, origin) {
+		const qs = origin ? `?${new URLSearchParams({ origin })}` : "";
+		return this.request("GET", `/products/${seg(productId)}/documents/${seg(type)}${qs}`);
 	}
 	async listBacklogItems(productId, opts) {
 		const params = new URLSearchParams();
@@ -178,6 +181,9 @@ var TaigaClient = class {
 	async listBuildRunSteps(id) {
 		return this.request("GET", `/builds/${seg(id)}/steps`);
 	}
+	async getFactory(id) {
+		return this.request("GET", `/factories/${seg(id)}`);
+	}
 	async listFactories(opts) {
 		const params = new URLSearchParams();
 		if (opts?.limit) params.set("limit", String(opts.limit));
@@ -189,7 +195,7 @@ var TaigaClient = class {
 //#region src/config.ts
 const envSchema = z.object({
 	TAIGA_API_KEY: z.string().min(1),
-	TAIGA_API_URL: z.string().default("https://api.taiga.app")
+	TAIGA_API_URL: z.string().default("https://api.eu.tai.ga")
 });
 /** Null when TAIGA_API_KEY is missing or empty: it is the one setting with no default. */
 function readConfig() {
@@ -213,6 +219,871 @@ const READ_ONLY = {
 	openWorldHint: false
 };
 //#endregion
+//#region ../../packages/types/dist/tenants.js
+const TENANT_DOCUMENT_TYPES = [
+	"policy_security",
+	"policy_data",
+	"policy_sdlc",
+	"policy_ops",
+	"policy_tic",
+	"policy_risk",
+	"policy_architecture",
+	"policy_supply_chain",
+	"policy_cloud_governance",
+	"business_goals",
+	"design_standards",
+	"brand_standards",
+	"tone_of_voice",
+	"tenant_instructions"
+];
+/** The nine policy documents: the tenant documents that define controls. */
+const POLICY_TYPES = [
+	"policy_security",
+	"policy_data",
+	"policy_sdlc",
+	"policy_ops",
+	"policy_tic",
+	"policy_risk",
+	"policy_architecture",
+	"policy_supply_chain",
+	"policy_cloud_governance"
+];
+const EU_COUNTRIES = [
+	{
+		code: "AT",
+		name: "Austria"
+	},
+	{
+		code: "BE",
+		name: "Belgium"
+	},
+	{
+		code: "BG",
+		name: "Bulgaria"
+	},
+	{
+		code: "HR",
+		name: "Croatia"
+	},
+	{
+		code: "CY",
+		name: "Cyprus"
+	},
+	{
+		code: "CZ",
+		name: "Czechia"
+	},
+	{
+		code: "DK",
+		name: "Denmark"
+	},
+	{
+		code: "EE",
+		name: "Estonia"
+	},
+	{
+		code: "FI",
+		name: "Finland"
+	},
+	{
+		code: "FR",
+		name: "France"
+	},
+	{
+		code: "DE",
+		name: "Germany"
+	},
+	{
+		code: "GR",
+		name: "Greece"
+	},
+	{
+		code: "HU",
+		name: "Hungary"
+	},
+	{
+		code: "IE",
+		name: "Ireland"
+	},
+	{
+		code: "IT",
+		name: "Italy"
+	},
+	{
+		code: "LV",
+		name: "Latvia"
+	},
+	{
+		code: "LT",
+		name: "Lithuania"
+	},
+	{
+		code: "LU",
+		name: "Luxembourg"
+	},
+	{
+		code: "MT",
+		name: "Malta"
+	},
+	{
+		code: "NL",
+		name: "Netherlands"
+	},
+	{
+		code: "PL",
+		name: "Poland"
+	},
+	{
+		code: "PT",
+		name: "Portugal"
+	},
+	{
+		code: "RO",
+		name: "Romania"
+	},
+	{
+		code: "SK",
+		name: "Slovakia"
+	},
+	{
+		code: "SI",
+		name: "Slovenia"
+	},
+	{
+		code: "ES",
+		name: "Spain"
+	},
+	{
+		code: "SE",
+		name: "Sweden"
+	}
+];
+/** Countries available during closed beta. Expand as we open new markets. */
+const BETA_COUNTRIES = ["FI"];
+EU_COUNTRIES.filter((c) => BETA_COUNTRIES.includes(c.code));
+Object.fromEntries(EU_COUNTRIES.map((c) => [c.code, "eu"]));
+//#endregion
+//#region ../../packages/types/dist/factories.js
+const FACTORY_DOCUMENT_TYPES = ["factory_instructions"];
+//#endregion
+//#region ../../packages/types/dist/products.js
+const PRODUCT_STATUSES = [
+	"draft",
+	"active",
+	"archived"
+];
+const PRODUCT_DOCUMENT_TYPES = [
+	"specification",
+	"architecture",
+	"technology_decisions",
+	"data_flow",
+	"privacy_assessment",
+	"threat_model",
+	"risk_register",
+	"user_flow",
+	"service_blueprint",
+	"ui_direction",
+	"codebase_snapshot",
+	"product_instructions"
+];
+/**
+* The document types the codebase-intelligence agent can derive from a repo --
+* the valid values for a single-document reality refresh (PRO-1141).
+*
+* Mirrors the agent's DocumentDerivation registry, which is the source of
+* truth: everything in PRODUCT_DOCUMENT_TYPES except `ui_direction` (a human's
+* recorded choice) and `product_instructions` (free-form text the user writes).
+* The two lists are pinned to each other by
+* apps/agents/codebase-intelligence/tests/test_reality_doc_types_sync.py.
+* If they drift anyway, the failure is uneven: a subset request that mixes a
+* drifted type with real ones reports it in the run's `errors` map, but a
+* request naming ONLY drifted types derives nothing and fails the job after
+* exhausting retries ("Codebase analysis produced no documents"), and a
+* Python-side addition missing from this list is rejected with a 400 by the
+* refresh route's schema before any job exists.
+*/
+const REALITY_DERIVED_DOCUMENT_TYPES = [
+	"codebase_snapshot",
+	"specification",
+	"user_flow",
+	"architecture",
+	"technology_decisions",
+	"data_flow",
+	"privacy_assessment",
+	"threat_model",
+	"risk_register",
+	"service_blueprint"
+];
+/**
+* Human-readable document names, for text the SERVER has to compose -- inbox
+* item titles in particular, which are stored strings and cannot reach the web
+* app's i18n.
+*
+* Kept in `@taiga/types` rather than in the API so there is one list rather
+* than a backend copy quietly drifting from the UI's. Matches the web's
+* PIPELINE_DISPLAY_NAMES (apps/web/src/lib/pipeline-display-names.ts); change
+* both together or neither.
+*/
+const PRODUCT_DOCUMENT_DISPLAY_NAMES = {
+	specification: "Specification",
+	user_flow: "User Flows",
+	architecture: "Architecture",
+	technology_decisions: "Tech Decisions",
+	data_flow: "Data Flow",
+	privacy_assessment: "DPIA",
+	threat_model: "Threat Model",
+	risk_register: "Risk Register",
+	service_blueprint: "Service Blueprint"
+};
+const PRODUCT_DOCUMENT_ORIGINS = ["plan", "reality"];
+const TURN_EVENT_TRIGGERS = [
+	"defined",
+	"plan_started",
+	"plan_completed",
+	"plan_failed",
+	"plan_approved",
+	"plan_rejected",
+	"build_started",
+	"pr_opened",
+	"pr_ready",
+	"build_completed",
+	"build_failed",
+	"build_stopped",
+	"pr_merged",
+	"pr_closed",
+	"edited",
+	"disposition_changed",
+	"archived",
+	"unarchived"
+];
+/**
+* The two blocking states are NOT the same kind of blocker, and collapsing them
+* into one list is what caused a bug in each direction (PRO-1028, PRO-1039).
+* They are separate constants so the difference is data a reader can see rather
+* than a comment a reader can miss.
+*/
+/**
+* GLOBAL blockers: at most one per project, at any position. `active` is held
+* by `uq_product_queue_active`, so an entry in this state blocks the whole
+* queue WHEREVER it sits -- `reposition` lets a queued entry be dragged in
+* front of the active one, and starting a second run then violates that index.
+*/
+const QUEUE_GLOBAL_BLOCKING_STATES = ["active"];
+/**
+* POSITIONAL blockers: they stop what is BEHIND them and nothing in front.
+* `halted` blocks by existing, which is how halt-on-failure works without a
+* separate paused flag -- but only for the entries queued after it. That is
+* what the UI has always promised, and it gives a halt a second exit: move it
+* down and the rest of the queue carries on.
+*/
+const QUEUE_POSITIONAL_BLOCKING_STATES = ["halted"];
+[...QUEUE_GLOBAL_BLOCKING_STATES, ...QUEUE_POSITIONAL_BLOCKING_STATES];
+Object.keys({
+	/**
+	* A PERSON stopped the plan (PRO-1144). Distinct from `planning_failed`
+	* because the two leave the initiative in the same state and mean opposite
+	* things: one is the agent falling over, this is somebody deciding.
+	*
+	* Halting is still right -- nothing should restart behind the back of a
+	* person who just stopped it -- but calling their decision a failure is not.
+	* Same wording as the initiative's own cancel copy (PRO-1071), so the two
+	* surfaces describe one event the same way.
+	*/
+	planning_cancelled: {
+		message: "Planning was cancelled, so the queue stopped here.",
+		params: [],
+		clearedWhen: "planning is retried, or a re-plan replaces it",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/** The plan the entry needs could not be produced. */
+	planning_failed: {
+		message: "Planning failed for this initiative, so the queue stopped here.",
+		params: [],
+		clearedWhen: "the initiative leaves planningStatus \"failed\" (a retry or a re-plan)",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/**
+	* Nobody was running the plan: the worker was lost (PRO-1040, PRO-1521).
+	*
+	* The queue's wording for a plan that failed with cause `worker_lost` --
+	* reaped on a dead heartbeat, or found at 'planning' with no live job by the
+	* reconciler, which fails it with that cause on the tick that notices
+	* (`armPlanning` writes the status and creates the job in ONE transaction,
+	* so that shape is never a race). One of three halts that mirror
+	* `PLAN_FAILURE_CAUSES` one-to-one; see `PLAN_FAILURE_HALT`.
+	*/
+	planning_stalled: {
+		message: "Planning stopped without finishing, so the queue stopped here.",
+		params: [],
+		clearedWhen: "planning is retried, or a re-plan replaces it",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/** The run errored out. */
+	run_failed: {
+		message: "The run failed, so the queue stopped here.",
+		params: [],
+		clearedWhen: "the run is retried (back to in-flight) or replaced by a re-plan",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/**
+	* A person stopped the run. Previously invisible: the halt check listed
+	* `failed` and `closed` by hand and silently missed this, so a stopped run
+	* left its entry active forever with no reason shown.
+	*/
+	run_stopped: {
+		message: "The run was stopped, so the queue stopped here.",
+		params: [],
+		clearedWhen: "the run is resumed (back to in-flight) or replaced by a re-plan",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/**
+	* The run reached `completed` with nothing that could merge.
+	*
+	* `completed` carries two meanings -- merged, and "the review loop converged
+	* with nothing left to push". The queue advances on MERGES, so treating the
+	* second as success planned the next entry against a main that never got
+	* this one, which is why the cause exists.
+	*
+	* It is NARROWER than that now (PRO-1123). The second meaning is itself two
+	* states, and an open pull request waiting on a reviewer is the ordinary
+	* handoff, not a fault: `isAwaitingMerge` routes it away from here and the
+	* queue leaves that entry active. What still reaches this cause is a run that
+	* finished with no pull request at all, or one already closed.
+	*/
+	run_unmerged: {
+		message: "The run finished without a pull request to merge, so the queue stopped here.",
+		params: [],
+		clearedWhen: "a pull request appears and merges, or a re-plan replaces the run",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/** The pull request was closed without merging. */
+	pr_closed: {
+		message: "The pull request was closed without merging, so the queue stopped here.",
+		params: [],
+		clearedWhen: "a re-plan replaces the abandoned run",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/**
+	* The project asked the queue to STOP at the plan (PRO-1295), and it has.
+	*
+	* Distinct from `armed_start_missing`, which is the same observable state --
+	* planned, unarmed, no run -- reached by accident rather than on purpose.
+	* Telling a person "the run never started" when they configured exactly that
+	* describes their own decision as a fault, and the two need different copy
+	* for the same reason `planning_cancelled` is not `planning_failed`.
+	*
+	* `auto` is honest here: this clears the moment a run appears, which is what
+	* pressing Run after reading the plan does. No grace period either -- the
+	* accidental case waits five minutes in case a run is merely slow to be
+	* created, but a deliberate stop has nothing to wait for.
+	*/
+	awaiting_plan_review: {
+		message: "The plan is ready and waiting for you to read it, so the queue stopped here.",
+		params: [],
+		clearedWhen: "the run starts, which is what reading the plan and pressing Run does",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/**
+	* Planning finished and armed, but the run never appeared. Work that went
+	* wrong is every other cause; this is work that never began, and without it
+	* the entry waits forever for a merge that has no pull request to come from.
+	*/
+	armed_start_missing: {
+		message: "Planning finished but the run never started, so the queue stopped here.",
+		params: [],
+		clearedWhen: "a run appears for the plan, or a re-plan re-arms it",
+		exits: [
+			"auto",
+			"reorder",
+			"remove"
+		]
+	},
+	/**
+	* Activation was refused, and the refusal is a decision a person owes: an
+	* unsettled dependency, an unchosen UI direction, an agent already on the
+	* item. Deliberately NOT auto-clearing. Re-deriving it every tick would flip
+	* the entry queued/halted forever and log a refusal each time, which is how
+	* the codebase already ruled on this before the causes were data.
+	*/
+	activation_refused: {
+		message: "{message}",
+		params: ["message"],
+		clearedWhen: "never on its own; the refusal names something a person has to settle",
+		exits: [
+			"resume",
+			"reorder",
+			"remove"
+		]
+	},
+	/**
+	* The person who queued it was erased, so there is no principal to run as.
+	* Fail closed rather than run as somebody who did not ask (PRO-949), and
+	* there is nothing to observe that would change that.
+	*/
+	queued_by_erased: {
+		message: "The person who queued this is no longer in the organisation, so it was not started.",
+		params: [],
+		clearedWhen: "never on its own; there is no principal left to run as",
+		exits: ["remove"]
+	}
+}).filter((c) => c !== "awaiting_plan_review" && c !== "armed_start_missing");
+//#endregion
+//#region ../../packages/types/dist/build.js
+const BUILD_RUN_STATUSES = [
+	"pending",
+	"cloning",
+	"implementing",
+	"hardening",
+	"pushing",
+	"ci_checking",
+	"ci_fixing",
+	"needs_review",
+	"reviewing",
+	"completed",
+	"failed",
+	"stopped",
+	"closed"
+];
+/**
+* Status -> disposition, as a `satisfies`-checked const map (rather than a
+* switch) so the assignment is exhaustive at compile time AND the narrow
+* per-status literal types survive for type-level derivation below
+* (BuildRunActiveStatus / BuildRunTerminalStatus).
+*/
+const RUN_DISPOSITION = {
+	pending: "in_flight",
+	cloning: "in_flight",
+	implementing: "in_flight",
+	hardening: "in_flight",
+	pushing: "in_flight",
+	ci_checking: "in_flight",
+	ci_fixing: "in_flight",
+	needs_review: "gated",
+	reviewing: "in_flight",
+	completed: "succeeded",
+	failed: "failed",
+	stopped: "stopped",
+	closed: "rejected"
+};
+/** How the run stands. Exhaustive via the RUN_DISPOSITION map. */
+function runDisposition(status) {
+	return RUN_DISPOSITION[status];
+}
+/**
+* Statuses where the coding agent (or review worker) is actively executing.
+* Single source of truth shared by the tenant build feed's `active=true` filter
+* (api) and the dashboard's "running" detection (web), which must agree.
+* = in_flight minus 'pending' (queued is not yet executing).
+*/
+const BUILD_RUN_ACTIVE_STATUSES = BUILD_RUN_STATUSES.filter((s) => runDisposition(s) === "in_flight" && s !== "pending");
+BUILD_RUN_STATUSES.filter((s) => runDisposition(s) !== "in_flight");
+[...BUILD_RUN_ACTIVE_STATUSES.filter((s) => s !== "reviewing")];
+[...TURN_EVENT_TRIGGERS];
+//#endregion
+//#region ../../packages/types/dist/maintenance.js
+/**
+* The kinds whose remediation is a CODE change rather than a version bump
+* (PRO-1384).
+*
+* Shared rather than duplicated per side, because the two sides disagreeing is
+* a silent dead feature: the API decides whether a remediation is ACCEPTED and
+* the web decides whether the button is OFFERED, and when this split lived only
+* in the API the client kept gating on `recommendedVersion` -- which a code
+* finding never has -- so the endpoint was reachable and unreachable at the
+* same time.
+*
+* A dependency is fixed by moving to a published version, so the absence of one
+* is a real blocker. A code finding has no version by construction.
+*/
+const CODE_REMEDIATION_KINDS = [
+	"secret",
+	"sast",
+	"iac_misconfig"
+];
+new Map(Object.entries({
+	deps: ["vulnerable_dependency", "outdated_dependency"],
+	secrets: ["secret"],
+	sast: ["sast"],
+	iac: ["iac_misconfig"]
+}).flatMap(([scanner, kinds]) => kinds.map((kind) => [kind, scanner])));
+new Set(CODE_REMEDIATION_KINDS);
+//#endregion
+//#region ../../packages/types/dist/design-tokens.js
+/**
+* The brand grounding contract (PRO-929).
+*
+* A tenant's brand can come from more than one place -- the internal
+* `design_standards` document authored in Design Standards, or a linked
+* design-system repository, or (later) Figma Variables. Whichever source is
+* authoritative, every consumer downstream wants the same thing: the resolved
+* CSS custom properties the sandboxed artifact runtime reads.
+*
+* This module holds that vocabulary so the producers and the consumer cannot
+* drift. The web token bridge maps the internal document's Material-3-flavoured
+* keys onto these names; the API's repository reader lifts them straight out of
+* a design system's own theme files (a shadcn-convention design system already
+* speaks this vocabulary, so there is nothing to translate). Both must aim at
+* one list, which is why the list lives here rather than beside either of them
+* -- the same single-source rule PRO-847 applied to standing directions.
+*/
+/**
+* The CSS custom properties the artifact runtime consumes.
+*
+* Deliberately the shadcn convention rather than a Taiga invention: it is what
+* the sandboxed runtime's Tailwind bridge already reads, and what a generated
+* application's own theme will use, so a concept previewed in these variables
+* is previewed in the same names the built product will carry.
+*/
+const ARTIFACT_CSS_VARIABLES = [
+	"--background",
+	"--foreground",
+	"--card",
+	"--card-foreground",
+	"--popover",
+	"--popover-foreground",
+	"--primary",
+	"--primary-foreground",
+	"--primary-hover",
+	"--primary-hover-foreground",
+	"--secondary",
+	"--secondary-foreground",
+	"--muted",
+	"--muted-foreground",
+	"--accent",
+	"--accent-foreground",
+	"--destructive",
+	"--destructive-foreground",
+	"--success",
+	"--success-foreground",
+	"--warning",
+	"--warning-foreground",
+	"--border",
+	"--input",
+	"--ring",
+	"--radius"
+];
+/** What the artifact document carries them as. */
+const ARTIFACT_SCALE_FRAME_NAMES = [
+	{
+		source: "--spacing",
+		frame: "--ds-spacing",
+		theme: "--spacing"
+	},
+	{
+		source: "--font-mono",
+		frame: "--ds-font-mono",
+		theme: "--font-mono"
+	},
+	{
+		source: "--text-xs",
+		frame: "--ds-text-xs",
+		theme: "--text-xs"
+	},
+	{
+		source: "--text-sm",
+		frame: "--ds-text-sm",
+		theme: "--text-sm"
+	},
+	{
+		source: "--text-base",
+		frame: "--ds-text-base",
+		theme: "--text-base"
+	},
+	{
+		source: "--text-lg",
+		frame: "--ds-text-lg",
+		theme: "--text-lg"
+	},
+	{
+		source: "--text-xl",
+		frame: "--ds-text-xl",
+		theme: "--text-xl"
+	},
+	{
+		source: "--text-2xl",
+		frame: "--ds-text-2xl",
+		theme: "--text-2xl"
+	},
+	{
+		source: "--text-3xl",
+		frame: "--ds-text-3xl",
+		theme: "--text-3xl"
+	},
+	{
+		source: "--radius-sm",
+		frame: "--ds-radius-sm",
+		theme: "--radius-sm"
+	},
+	{
+		source: "--radius-md",
+		frame: "--ds-radius-md",
+		theme: "--radius-md"
+	},
+	{
+		source: "--radius-lg",
+		frame: "--ds-radius-lg",
+		theme: "--radius-lg"
+	},
+	{
+		source: "--radius-xl",
+		frame: "--ds-radius-xl",
+		theme: "--radius-xl"
+	},
+	{
+		source: "--radius-2xl",
+		frame: "--ds-radius-2xl",
+		theme: "--radius-2xl"
+	},
+	{
+		source: "--ease-out",
+		frame: "--ds-ease-out",
+		theme: "--ease-out"
+	},
+	{
+		source: "--ease-spring",
+		frame: "--ds-ease-spring",
+		theme: "--ease-spring"
+	},
+	{
+		source: "--default-transition-duration",
+		frame: "--ds-duration",
+		theme: "--default-transition-duration"
+	},
+	{
+		source: "--duration-normal",
+		frame: "--ds-duration-entrance",
+		theme: null
+	}
+].map((token) => token.frame);
+[...ARTIFACT_CSS_VARIABLES, ...ARTIFACT_SCALE_FRAME_NAMES];
+new Set(ARTIFACT_CSS_VARIABLES.filter((name) => name !== "--radius"));
+Object.freeze({
+	productKinds: true,
+	applicationOwnership: true
+});
+//#endregion
+//#region ../../packages/types/dist/document-types-for-kind.js
+/**
+* What a thing with no users of its own does not have.
+*
+* A library, an infrastructure module and a pipeline share one fact: their
+* consumers are other products, not people. That is what decides all four
+* exclusions, and it is why the three kinds share a list rather than each
+* having their own -- three identical lists are three chances to change one.
+*
+*   - `user_flow`: a journey through screens. There are no screens and there
+*     is no journey; the ux-planning agent asked for one invents both.
+*   - `privacy_assessment`: a GDPR Article 35 DPIA. Its sections are the legal
+*     basis for processing, the data subjects affected, retention, how each
+*     data-subject right is served, and an approval decision. A module has no
+*     data subjects and is not a controller, so every one of those sections is
+*     written from nothing. (A library that DOES touch personal data is still
+*     covered: the data flow below is kept, and the threat model reads it.)
+*   - `service_blueprint`: frontstage and backstage of a SERVICE, divided by a
+*     line of visibility that only exists where a customer is looking.
+*   - `ui_direction`: the look and the navigation. A Terraform module offered
+*     a look-and-feel wizard is the clearest single symptom of PRO-1866.
+*
+* The `data_flow` is deliberately KEPT, against the ticket's shorter list.
+* Two reasons, and both are about the documents that remain rather than about
+* the data flow itself. The threat model is STRIDE over trust boundaries and
+* data stores, and the data flow is where those come from -- dropping it
+* leaves the threat model and the risk register standing but ungrounded, which
+* is a worse outcome than a document nobody wanted. And a data flow is not an
+* application concept: a module's state file, provider credentials and remote
+* backend cross trust boundaries, a pipeline moves artifacts and secrets
+* between them, and a library receives and returns data it does not own.
+*
+* The technology decisions, architecture, threat model and risk register are
+* kept for every kind. Each describes the thing itself, and a consumer of a
+* library has more need of them, not less.
+*/
+const NO_USERS_OF_ITS_OWN = [
+	"user_flow",
+	"privacy_assessment",
+	"service_blueprint",
+	"ui_direction"
+];
+Object.freeze({
+	/** The kind every product was before the column existed. Nothing is excluded. */
+	application: [],
+	/** Code other products depend on, shipped as a published package. */
+	library: NO_USERS_OF_ITS_OWN,
+	/** A Terraform module, a Helm chart: consumed by other products' infrastructure. */
+	infrastructure_module: NO_USERS_OF_ITS_OWN,
+	/** A reusable workflow, an action, a build template. */
+	pipeline: NO_USERS_OF_ITS_OWN
+});
+Object.freeze({
+	user_flow: {
+		required: ["specification"],
+		optional: []
+	},
+	architecture: {
+		required: ["specification"],
+		optional: ["user_flow"]
+	},
+	technology_decisions: {
+		required: ["specification", "architecture"],
+		optional: []
+	},
+	data_flow: {
+		required: ["specification", "architecture"],
+		optional: []
+	},
+	privacy_assessment: {
+		required: ["specification", "architecture"],
+		optional: ["data_flow"]
+	},
+	threat_model: {
+		required: [
+			"specification",
+			"architecture",
+			"privacy_assessment"
+		],
+		optional: ["data_flow"]
+	},
+	risk_register: {
+		required: ["specification"],
+		optional: [
+			"privacy_assessment",
+			"threat_model",
+			"technology_decisions",
+			"architecture"
+		]
+	},
+	service_blueprint: {
+		required: [
+			"specification",
+			"user_flow",
+			"architecture"
+		],
+		optional: ["ui_direction"]
+	}
+});
+//#endregion
+//#region src/tools/catalogue.ts
+/**
+* What exists, from the one place that knows: the shared types package.
+*
+* Tool descriptions are what the model reads to decide what to call, and a
+* description that names a document type the catalogue lacks sends it down a
+* dead end (the walk-through that led here found `policy_acceptable_use` and
+* `policy_ip` named in a description and nowhere else). Every list of types,
+* origins and statuses a tool shows is derived from these constants, and a
+* test holds the descriptions to them.
+*/
+/**
+* Display names for every product document type. The reviewable nine come
+* from the shared map the web uses; the three the web never asks a person to
+* review are named here, and the record type keeps the two sets complete.
+*/
+const PRODUCT_DOCUMENT_NAMES = {
+	...PRODUCT_DOCUMENT_DISPLAY_NAMES,
+	ui_direction: "Look & Feel",
+	codebase_snapshot: "Codebase Snapshot",
+	product_instructions: "Product Instructions"
+};
+function productDocumentName(type) {
+	return PRODUCT_DOCUMENT_NAMES[type] ?? type;
+}
+/** The organization documents that are not policies: goals, standards, voice, instructions. */
+const OTHER_TENANT_DOCUMENT_TYPES = TENANT_DOCUMENT_TYPES.filter((type) => !POLICY_TYPES.includes(type));
+/** `a, b, c` for a description. */
+function named(types) {
+	return types.join(", ");
+}
+/**
+* The two document timelines of a product (ADR-017), in the words the tools
+* and the server instructions use. One place, so the list tool, the read
+* tool and the instructions cannot explain them three different ways.
+*/
+const ORIGIN_MEANING = {
+	plan: "plan: the discovery documents, authored intent. Every greenfield product has them; they say what is meant to be built.",
+	reality: "reality: derived from the code on the main branch, what is actually built. A brownfield product has them from its import; a greenfield product gets them once its first initiative is done (a merged pull request marks it done) or the repository is pushed to, and they refresh as code lands."
+};
+/**
+* Which timeline is a product's own (the API's documentOriginForSettings):
+* an imported product has no plan chain by design, so its documents are on
+* the reality side; everything else starts on the plan side. Derived from the
+* same settings key the API reads, so the two cannot disagree.
+*/
+function isImportedProduct(product) {
+	const settings = product?.settings;
+	return typeof settings === "object" && settings !== null && settings.projectType === "brownfield";
+}
+/**
+* The document types no derivation ever writes: a person records or writes
+* them, so they live on the plan side of every product, imported or not.
+*/
+const PLAN_ONLY_DOCUMENT_TYPES = PRODUCT_DOCUMENT_TYPES.filter((type) => !REALITY_DERIVED_DOCUMENT_TYPES.includes(type));
+/**
+* The timeline a read should default to: the plan side for a type only a
+* person writes, else the product's own side (reality for an imported
+* product, plan for every other).
+*/
+function defaultOriginFor(product, type) {
+	if (type !== void 0 && PLAN_ONLY_DOCUMENT_TYPES.includes(type)) return "plan";
+	return isImportedProduct(product) ? "reality" : "plan";
+}
+/**
+* Where an imported product's import got to (`settings.importStatus`, written
+* by the API: pending, analyzing, complete, cancelled, failed). Unknown values
+* read as "not known", never as a promise.
+*/
+function importStatusOf(product) {
+	const settings = product?.settings;
+	if (typeof settings !== "object" || settings === null) return null;
+	const status = settings.importStatus;
+	return typeof status === "string" ? status : null;
+}
+/** Why a side of the timeline is empty, for a list or a miss that shows one. */
+function emptyOriginNote(origin, product) {
+	const imported = isImportedProduct(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 "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.";
+		default: return "No reality documents: the import derives them from the code, and none have been published.";
+	}
+}
+//#endregion
 //#region src/tools/errors.ts
 /** A successful tool result: one JSON text block the model reads. */
 function toolResult(value) {
@@ -263,17 +1134,6 @@ async function runTool(handler) {
 	}
 }
 //#endregion
-//#region src/tools/inputs.ts
-/**
-* A document type as the API names one: policy_security, factory_instructions,
-* specification. An identifier, never a path: the value is interpolated into
-* the route, and a type that carried a slash would reach a different
-* document's route than the tool's description promises. The API's own enum
-* stays the source of truth for which identifiers exist (it answers 400 with
-* the valid list); this only rules out what could not be a type at all.
-*/
-const documentType = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/, "A document type is a lowercase identifier such as policy_security");
-//#endregion
 //#region src/tools/remote.ts
 const SCP_LIKE = /^(?:[^@\s/]+@)?([^:\s/]+):([^\s]+)$/;
 function parseRemote(remote) {
@@ -335,37 +1195,63 @@ function webOrigin(url) {
 	}
 }
 //#endregion
-//#region src/tools/summarize.ts
-/**
-* Strip heavy content from list responses to avoid context window bloat.
-*
-* List endpoints return summaries (id, name, description, metadata).
-* Get endpoints return the full content.
-*
-* This keeps list calls cheap (~100 tokens per item) and lets the AI
-* selectively load full content only for the items it needs.
-*/
-/** Fields to strip from list responses -- these contain the bulk content. */
-const HEAVY_FIELDS = [
-	"content",
-	"data",
-	"sections"
-];
+//#region src/tools/sections.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The `sections` map of a document, or null when the document is not section-shaped. */
+function sectionsOf(data) {
+	return isRecord(data.sections) ? data.sections : null;
+}
+/** The text of one section, or null when the section does not exist. */
+function sectionContent(sections, sectionId) {
+	const section = sections[sectionId];
+	if (section === void 0 || section === null) return null;
+	if (typeof section === "string") return section;
+	return isRecord(section) && typeof section.content === "string" ? section.content : "";
+}
+/** The map with one section's text replaced (or the section added); every other section untouched. */
+function applySectionEdit(sections, sectionId, content) {
+	const prior = sections[sectionId];
+	return {
+		...sections,
+		[sectionId]: isRecord(prior) ? {
+			...prior,
+			content
+		} : { content }
+	};
+}
 /**
-* Remove heavy content fields from each item in an array.
-* Preserves all metadata (id, name, description, type, dates, etc).
+* A document for reading, without its provenance: the top-level `derivedFrom`
+* tree and `outdated` source list (PRO-2359), and each section's own
+* `derivedFrom` (PRO-2158). They say which documents shaped this one, which
+* the editor needs and a reader does not; `source` and `priority` stay, the
+* server instructions explain them.
 */
-function summarizeList(items) {
-	return items.map((item) => {
-		const summary = { ...item };
-		for (const field of HEAVY_FIELDS) if (field in summary) delete summary[field];
-		return summary;
-	});
+function stripProvenance(doc) {
+	const { derivedFrom: _derivedFrom, outdated: _outdated, ...rest } = doc;
+	if (!isRecord(rest.data)) return rest;
+	const sections = sectionsOf(rest.data);
+	if (!sections) return rest;
+	const stripped = Object.fromEntries(Object.entries(sections).map(([id, section]) => {
+		if (!isRecord(section)) return [id, section];
+		const { derivedFrom: _sectionDerivedFrom, ...keep } = section;
+		return [id, keep];
+	}));
+	return {
+		...rest,
+		data: {
+			...rest.data,
+			sections: stripped
+		}
+	};
 }
+//#endregion
+//#region src/tools/summarize.ts
 /**
-* Keep only the named fields of each item. For lists whose rows carry prose
-* (a backlog item's description, a run's metrics) that `summarizeList`'s
-* fixed field names would not catch.
+* Keep only the named fields of each item. List tools return summaries (the
+* fields a model needs to pick an item) and get tools return everything;
+* this is how a list drops the prose and the provenance trees.
 */
 function pickFields(items, fields) {
 	return items.map((item) => {
@@ -386,6 +1272,21 @@ const PRODUCT_SUMMARY_FIELDS = [
 	"kind",
 	"discoveryStep"
 ];
+/**
+* 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
+* tree, the data key count or the reviewer's name.
+*/
+const DOCUMENT_SUMMARY_FIELDS$1 = [
+	"type",
+	"origin",
+	"version",
+	"isDraft",
+	"hasDraft",
+	"stage",
+	"reviewedAt",
+	"updatedAt"
+];
 /** The API's page ceiling (paginationSchema in apps/api). */
 const PAGE_SIZE = 100;
 /**
@@ -394,6 +1295,8 @@ const PAGE_SIZE = 100;
 * matches is not a resolution the model can act on anyway.
 */
 const RESOLVE_PAGE_LIMIT = 10;
+const productId = z.string().uuid().describe("Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products");
+const originInput = z.enum(PRODUCT_DOCUMENT_ORIGINS).optional().describe(`Which timeline. ${ORIGIN_MEANING.plan} ${ORIGIN_MEANING.reality} Omit it to read the product's own timeline: reality for an imported product, plan for every other, and always plan for the documents a person writes (Look & Feel, Product Instructions).`);
 /**
 * Every product linked to the repository, page by page, until the API runs
 * out or the cap is hit. A page that fails fails the call, like every other
@@ -421,6 +1324,82 @@ async function linkedProducts(client, repository, repositoryHost) {
 		truncated: true
 	};
 }
+/** A document list row as the model sees it: the summary fields plus a display name and the staleness fact. */
+function documentSummaries(rows) {
+	const typed = rows;
+	return pickFields(typed, DOCUMENT_SUMMARY_FIELDS$1).map((picked, index) => {
+		const outdated = typed[index].outdated;
+		const fact = picked.isDraft !== false ? void 0 : outdated === null ? false : Array.isArray(outdated?.sources) ? outdated.sources.length > 0 : void 0;
+		return {
+			type: picked.type,
+			name: productDocumentName(String(picked.type)),
+			...picked,
+			...fact === void 0 ? {} : { outdated: fact }
+		};
+	});
+}
+/** The one sentence for a side the API would not list, with what it said. */
+function unlistableNote(origin, reason) {
+	return `The ${origin} side could not be listed (${reason instanceof TaigaApiError ? `${reason.status} ${reason.code ?? ""}`.trim() : "the request failed"}).`;
+}
+/**
+* Both timelines of a product's documents, each a list of summaries, with
+* which one is the product's own and a note for an empty side. The product
+* decides what an empty side means (imported or not, how far its import got),
+* so a caller that already holds it passes it in.
+*/
+async function documentTimelines(client, id, product) {
+	const loaded = product ?? (await client.getProduct(id)).data;
+	const settled = await Promise.allSettled(PRODUCT_DOCUMENT_ORIGINS.map((o) => client.listProductDocuments(id, {
+		origin: o,
+		limit: PAGE_SIZE
+	})));
+	if (settled.every((result) => result.status === "rejected")) throw settled[0].reason;
+	const sides = {};
+	const unlistable = {};
+	PRODUCT_DOCUMENT_ORIGINS.forEach((o, index) => {
+		const result = settled[index];
+		if (result.status === "fulfilled") sides[o] = documentSummaries(result.value.data);
+		else {
+			sides[o] = null;
+			unlistable[o] = unlistableNote(o, result.reason);
+		}
+	});
+	const notes = PRODUCT_DOCUMENT_ORIGINS.flatMap((o) => {
+		const side = sides[o];
+		if (!side) return [unlistable[o]];
+		return side.length === 0 ? [emptyOriginNote(o, loaded)] : [];
+	});
+	return {
+		projectType: isImportedProduct(loaded) ? "brownfield" : "greenfield",
+		defaultOrigin: defaultOriginFor(loaded),
+		plan: sides.plan ?? null,
+		reality: sides.reality ?? null,
+		unlistable,
+		notes
+	};
+}
+const isPublished = (row) => row.isDraft === false;
+/** `specification (v2), architecture (draft)` for one side. */
+function sideList(rows) {
+	return rows.map((row) => `${String(row.type)} (${isPublished(row) ? `v${String(row.version)}` : "draft"})`).join(", ");
+}
+/** What a missed document read should say: where the type does live, and what each side holds. */
+function describeMiss(type, wanted, timelines, product) {
+	const name = productDocumentName(type);
+	const other = wanted === "plan" ? "reality" : "plan";
+	const parts = [`No published ${wanted} ${name} (${type}) for this product.`];
+	const rows = (side) => timelines[side] ?? [];
+	if (rows(other).some((row) => row.type === type && isPublished(row))) parts.push(`It is published on the ${other} side: call again with origin '${other}'.`);
+	else for (const side of [wanted, other]) if (rows(side).some((row) => row.type === type && !isPublished(row))) parts.push(`A draft of it exists on the ${side} side, unpublished.`);
+	for (const o of PRODUCT_DOCUMENT_ORIGINS) {
+		const side = timelines[o];
+		const label = `${o[0].toUpperCase()}${o.slice(1)} documents`;
+		if (side === null) parts.push(timelines.unlistable[o]);
+		else parts.push(side.length > 0 ? `${label}: ${sideList(side)}.` : emptyOriginNote(o, product));
+	}
+	return parts.join(" ");
+}
 function registerProductTools(server, client) {
 	if (client.hasCapability("factories:read")) server.registerTool("taiga_list_factories", {
 		title: "List factories",
@@ -433,14 +1412,10 @@ function registerProductTools(server, client) {
 	if (client.hasCapability("products:read")) {
 		server.registerTool("taiga_list_products", {
 			title: "List products",
-			description: "List products in the organization. Use this to find a product by name; inside a git checkout, taiga_resolve_product finds it from the remote URL instead. Can filter by factory; a status filter also exists but no longer distinguishes anything (see its description).",
+			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.",
 			inputSchema: {
 				factoryId: z.string().uuid().optional().describe("Filter by factory ID -- get factory IDs from taiga_list_factories"),
-				status: z.enum([
-					"draft",
-					"active",
-					"archived"
-				]).optional().describe("Filter by status. Taiga no longer surfaces product status in its UI (PRO-543), so every product is currently \"draft\" and filtering by \"active\" or \"archived\" returns nothing. Omit this unless you are working with data set through the API directly."),
+				status: z.enum(PRODUCT_STATUSES).optional().describe("Filter by status: draft until the product finishes setup in Taiga, active after that, archived when retired."),
 				limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)")
 			},
 			annotations: READ_ONLY
@@ -449,11 +1424,22 @@ function registerProductTools(server, client) {
 		}));
 		server.registerTool("taiga_get_product", {
 			title: "Get product",
-			description: "Get one product in full: 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.",
-			inputSchema: { productId: z.string().uuid().describe("Product ID -- get from taiga_resolve_product (from a git remote) or taiga_list_products") },
+			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.",
+			inputSchema: {
+				productId: productId.optional(),
+				slug: z.string().max(63).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "A slug is lowercase words joined by hyphens").optional().describe("Product slug, as it appears in Taiga URLs -- an alternative to productId")
+			},
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult((await client.getProduct(params.productId)).data);
+			if (params.productId && params.slug) return toolError("VALIDATION_FAILED", "Pass productId or slug, not both: they could name two products.");
+			if (params.productId) return toolResult((await client.getProduct(params.productId)).data);
+			if (!params.slug) return toolError("VALIDATION_FAILED", "Pass productId or slug.");
+			const [product] = (await client.listProducts({
+				slug: params.slug,
+				limit: 1
+			})).data;
+			if (!product) return toolError("NOT_FOUND", `No product you can see has the slug "${params.slug}". taiga_list_products shows the ones you can.`);
+			return toolResult(product);
 		}));
 		server.registerTool("taiga_resolve_product", {
 			title: "Resolve product from git remote",
@@ -474,57 +1460,61 @@ function registerProductTools(server, client) {
 		}));
 		server.registerTool("taiga_list_product_documents", {
 			title: "List product documents",
-			description: "List documents for a specific product (names and types only). Product documents are generated during intake: specification (requirements), architecture (system design), technology decisions, data flow, privacy assessment, threat model (security risks), risk register, user flow, and service blueprint. Use taiga_get_product_document to read the full content.",
-			inputSchema: {
-				productId: z.string().uuid().describe("Product ID -- get from taiga_list_products"),
-				limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)")
-			},
+			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.`,
+			inputSchema: { productId },
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult(summarizeList((await client.listProductDocuments(params.productId, { limit: params.limit })).data));
+			const { unlistable: _unlistable, ...timelines } = await documentTimelines(client, params.productId);
+			return toolResult(timelines);
 		}));
 		server.registerTool("taiga_get_product_document", {
 			title: "Get product document",
-			description: "Get the full content of a specific product document. Use this when you need to understand what to build (specification), how the system is designed (architecture), what security risks exist (threat model), or what technology choices were made (technology_decisions). Types: specification, architecture, technology_decisions, data_flow, privacy_assessment, threat_model, risk_register, user_flow, service_blueprint, ui_direction, codebase_snapshot, and product_instructions (the product's standing instructions).",
+			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 read that finds nothing says which documents and timelines the product does have.",
 			inputSchema: {
-				productId: z.string().uuid().describe("Product ID -- get from taiga_list_products"),
-				type: documentType.describe("Document type -- get available types from taiga_list_product_documents. Common: specification, architecture, threat_model, technology_decisions")
+				productId,
+				type: z.enum(PRODUCT_DOCUMENT_TYPES).describe("Document type -- taiga_list_product_documents shows which ones the product has"),
+				origin: originInput
 			},
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult((await client.getProductDocument(params.productId, params.type)).data);
+			let product;
+			if (!params.origin) product = (await client.getProduct(params.productId)).data;
+			const origin = params.origin ?? defaultOriginFor(product, params.type);
+			try {
+				return toolResult(stripProvenance((await client.getProductDocument(params.productId, params.type, origin)).data));
+			} catch (error) {
+				if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
+				product ??= (await client.getProduct(params.productId)).data;
+				const timelines = await documentTimelines(client, params.productId, product);
+				return toolError("NOT_FOUND", describeMiss(params.type, origin, timelines, product));
+			}
 		}));
 	}
 }
 //#endregion
-//#region src/tools/sections.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** The `sections` map of a document, or null when the document is not section-shaped. */
-function sectionsOf(data) {
-	return isRecord(data.sections) ? data.sections : null;
-}
-/** The text of one section, or null when the section does not exist. */
-function sectionContent(sections, sectionId) {
-	const section = sections[sectionId];
-	if (section === void 0 || section === null) return null;
-	if (typeof section === "string") return section;
-	return isRecord(section) && typeof section.content === "string" ? section.content : "";
+//#region src/tools/documents.ts
+/**
+* What a document row needs to say for the model to pick one and read it in
+* full. Not the content, not who wrote it.
+*/
+const DOCUMENT_SUMMARY_FIELDS = [
+	"type",
+	"name",
+	"description",
+	"version",
+	"isDraft",
+	"hasDraft",
+	"updatedAt"
+];
+const summaries = (rows) => pickFields(rows, DOCUMENT_SUMMARY_FIELDS);
+/** What a lookup behind a miss said when it failed, so an unknown stays unknown. */
+function failedLookup(what, reason) {
+	return `${what} could not be checked (${reason instanceof TaigaApiError ? `${reason.status} ${reason.code ?? ""}`.trim() : "the request failed"}).`;
 }
-/** The map with one section's text replaced (or the section added); every other section untouched. */
-function applySectionEdit(sections, sectionId, content) {
-	const prior = sections[sectionId];
-	return {
-		...sections,
-		[sectionId]: isRecord(prior) ? {
-			...prior,
-			content
-		} : { content }
-	};
+/** `a (v3), b (v1)` for a not-found message. */
+function publishedList(rows) {
+	return rows.filter((row) => row.isDraft === false).map((row) => `${row.type} (v${String(row.version)})`).join(", ");
 }
-//#endregion
-//#region src/tools/documents.ts
 const DRAFT_WRITE = {
 	readOnlyHint: false,
 	destructiveHint: false,
@@ -539,7 +1529,7 @@ const PUBLISH = {
 };
 const sectionId = z.string().min(1).describe("Section id -- the keys of `data.sections` in taiga_get_document, e.g. summary, scope, apiDesign. An id that does not exist yet adds a section.");
 const sectionContentInput = z.string().describe("The full new Markdown text of the section; it replaces the old text");
-const tenantDocumentType = documentType.describe("Document type (e.g. policy_security, policy_sdlc) -- see taiga_list_documents");
+const tenantDocumentType = z.enum(TENANT_DOCUMENT_TYPES).describe(`Document type: a policy (${named(POLICY_TYPES)}) or ${named(OTHER_TENANT_DOCUMENT_TYPES)}`);
 /** Everything the model needs back from a write, without the content it already holds. */
 function documentSummary(doc) {
 	const { data, ...rest } = doc;
@@ -592,19 +1582,33 @@ function registerDocumentTools(server, client) {
 	if (client.hasCapability("tenant:documents:read")) {
 		server.registerTool("taiga_list_documents", {
 			title: "List company documents",
-			description: "List company-level policy documents (names and types only). Policies define security, data privacy, SDLC, operations, architecture, and compliance rules that apply across all factories and products. Use taiga_get_document with the document type to read the full policy content.",
+			description: `List the organization's documents as summaries (type, name, description, version, draft state). The ${POLICY_TYPES.length} policies (${named(POLICY_TYPES)}) define the security, data privacy, SDLC, operations, architecture and compliance rules that apply across all factories and products; the other documents (${named(OTHER_TENANT_DOCUMENT_TYPES)}) carry goals, standards, voice and standing instructions. Use taiga_get_document with the type to read one in full.`,
 			inputSchema: { limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)") },
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult(summarizeList((await client.listTenantDocuments(params)).data));
+			const result = await client.listTenantDocuments(params);
+			return toolResult(summaries(result.data));
 		}));
 		server.registerTool("taiga_get_document", {
 			title: "Get company document",
-			description: "Get the full content of a company policy document. Use this when you need to understand security requirements, data handling rules, architecture standards, or compliance controls that apply to your code. Types: policy_security, policy_data, policy_sdlc, policy_ops, policy_tic, policy_risk, policy_architecture, policy_supply_chain, policy_cloud_governance, policy_acceptable_use, policy_ip.",
-			inputSchema: { type: documentType.describe("Document type -- get available types from taiga_list_documents. Common: policy_security, policy_data, policy_sdlc, policy_architecture") },
+			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: { type: tenantDocumentType },
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult((await client.getTenantDocument(params.type)).data);
+			try {
+				return toolResult(stripProvenance((await client.getTenantDocument(params.type)).data));
+			} 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 })]);
+				const parts = [`No published ${params.type}.`];
+				if (draft.status === "fulfilled") parts.push(draft.value.data ? "A draft exists; taiga_publish_document publishes it once the person asks." : "There is no draft either.");
+				else parts.push(failedLookup("The draft", draft.reason));
+				if (all.status === "fulfilled") {
+					const published = publishedList(all.value.data);
+					parts.push(published ? `Published documents: ${published}.` : "Nothing is published yet.");
+				} else parts.push(failedLookup("The published list", all.reason));
+				return toolError("NOT_FOUND", parts.join(" "));
+			}
 		}));
 	}
 	if (client.hasCapability("tenant:documents:read") && client.hasCapability("tenant:documents:write")) {
@@ -634,25 +1638,36 @@ function registerDocumentTools(server, client) {
 	if (client.hasCapability("factories:read")) {
 		server.registerTool("taiga_list_factory_documents", {
 			title: "List factory documents",
-			description: "List documents for a specific factory (names and types only). A factory has one document: its instructions, the factory's free-form standing guidance (domain context, tech preferences, conventions) that applies to every product it owns. Use taiga_get_factory_document to read the full content.",
+			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: {
 				factoryId: z.string().uuid().describe("Factory ID -- get from taiga_list_factories"),
 				limit: z.number().int().min(1).max(100).optional().describe("Max results (default 25)")
 			},
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult(summarizeList((await client.listFactoryDocuments(params.factoryId, { limit: params.limit })).data));
+			const result = await client.listFactoryDocuments(params.factoryId, { limit: params.limit });
+			return toolResult(summaries(result.data));
 		}));
 		server.registerTool("taiga_get_factory_document", {
 			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.",
+			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: {
 				factoryId: z.string().uuid().describe("Factory ID -- get from taiga_list_factories"),
-				type: documentType.describe("Document type -- get available types from taiga_list_factory_documents. The factory instructions document is `factory_instructions`.")
+				type: z.enum(FACTORY_DOCUMENT_TYPES).default("factory_instructions").describe("Document type")
 			},
 			annotations: READ_ONLY
 		}, (params) => runTool(async () => {
-			return toolResult((await client.getFactoryDocument(params.factoryId, params.type)).data);
+			try {
+				return toolResult(stripProvenance((await client.getFactoryDocument(params.factoryId, params.type)).data));
+			} catch (error) {
+				if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
+				await client.getFactory(params.factoryId);
+				const detail = await client.getFactoryDocumentDraft(params.factoryId, params.type).then((draft) => draft.data ? "A draft exists; taiga_publish_factory_document publishes it once the person asks." : "There is no draft either: write one with taiga_update_factory_document, then publish it when the person asks.").catch((reason) => {
+					if (reason instanceof TaigaApiError && reason.status === 404) throw reason;
+					return failedLookup("The draft", reason);
+				});
+				return toolError("NOT_FOUND", `This factory has no published ${params.type} yet. ${detail}`);
+			}
 		}));
 	}
 	if (client.hasCapability("factories:read") && client.hasCapability("factories:documents:write")) {
@@ -663,7 +1678,7 @@ function registerDocumentTools(server, client) {
 			publish: () => client.publishFactoryDocument(factoryId, type)
 		});
 		const factoryId = z.string().uuid().describe("Factory ID -- get from taiga_list_factories");
-		const factoryDocumentType = documentType.describe("Document type (`factory_instructions`)");
+		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",
 			description: "Replace the text of one section of a factory's instructions, in its draft. The instructions document has one section, `instructions`. Does not publish: products keep following the published version until taiga_publish_factory_document is called. Read the current text with taiga_get_factory_document first. Use this when the factory conventions, domain context or tech preferences need updating while working on the codebase.",
@@ -812,12 +1827,69 @@ function registerAllTools(server, client) {
 	registerBuildTools(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.",
+	"",
+	"**Company documents** (taiga_list_documents / taiga_get_document):",
+	`The ${POLICY_TYPES.length} policies (${named(POLICY_TYPES)}) carry the security, data, SDLC, operations and`,
+	`architecture rules that apply to all code. The other documents (${named(OTHER_TENANT_DOCUMENT_TYPES)})`,
+	"carry the business goals, design and brand standards, tone of voice and standing instructions.",
+	"Read the relevant policy BEFORE writing code that touches security, data handling or infrastructure.",
+	"",
+	"**Factory instructions** (taiga_list_factory_documents / taiga_get_factory_document):",
+	"A factory's standing guidance: domain context (ubiquitous language, entities, business rules),",
+	"tech preferences (approved stack, patterns) and conventions. Read these to understand HOW this factory",
+	"builds software. A factory that has not written any yet has none; that is normal.",
+	"",
+	"**Product documents** (taiga_list_product_documents / taiga_get_product_document):",
+	`${Object.entries(PRODUCT_DOCUMENT_NAMES).map(([type, name]) => `${name} (${type})`).join(", ")}.`,
+	"A product has two timelines of these, and the list shows both:",
+	`- ${ORIGIN_MEANING.plan}`,
+	`- ${ORIGIN_MEANING.reality}`,
+	"An imported (brownfield) product has no generated discovery chain: its derived documents are on the",
+	"reality side, while the documents a person writes (Look & Feel, Product Instructions) are on the plan",
+	"side of every product. Omit origin on a read and the server picks the right side (the list reports the",
+	"product's own as defaultOrigin). To understand",
+	"what to build, read the plan where there is one; to understand the code you are changing, read reality",
+	"when it exists, the ground truth for architecture, data flow and threats as built.",
+	"",
+	"**Backlog and runs** (taiga_list_backlog_items / taiga_get_backlog_item / taiga_list_builds / taiga_get_build):",
+	"The product's initiatives with their acceptance criteria, and what Taiga's coding agent already built",
+	"for them: runs, steps, commits and pull requests.",
+	"",
+	"**Sections.** Policies and instructions are maps of sections. Each section carries its text and two",
+	"provenance fields you can read past: `source` says where the text originally came from (template:",
+	"Taiga's standard text; overlay-<id>: a jurisdiction or industry overlay; cloud-preset:<providers>:",
+	"rendered for the organization's cloud providers; any other tag names the derivation that wrote the",
+	"text; a hand edit keeps the source it had) and",
+	"`priority: core` marks the sections every organization keeps. Neither changes what the section",
+	"requires of you.",
+	"",
+	"Workflow: inside a git checkout, start with taiga_resolve_product on the remote URL to find the product.",
+	"Otherwise 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.",
+	"",
+	"When you notice a policy or factory instructions are outdated, fix the section with",
+	"taiga_update_document or taiga_update_factory_document. That saves a draft nobody follows yet;",
+	"publish it with taiga_publish_document or taiga_publish_factory_document only when the person asks.",
+	"This keeps the knowledge base accurate for everyone."
+].join("\n");
+//#endregion
 //#region src/index.ts
 async function main() {
 	const config = readConfig();
 	if (!config) {
 		console.error("Error: TAIGA_API_KEY environment variable is required.");
-		console.error("Create an API key at https://app.taiga.app/settings/api-keys");
+		console.error("Create one at https://eu.tai.ga under Settings > Account > API keys.");
 		process.exit(1);
 	}
 	const client = new TaigaClient({
@@ -833,35 +1905,7 @@ async function main() {
 	const server = new McpServer({
 		name: "taiga",
 		version: SERVER_VERSION
-	}, { instructions: [
-		"You have access to Taiga -- a policy-aware software development platform.",
-		"Taiga provides your organization's engineering knowledge base:",
-		"",
-		"**Company policies** (taiga_list_documents / taiga_get_document):",
-		"Security, data privacy, SDLC, architecture, and compliance rules that apply to all code.",
-		"Read the relevant policy BEFORE writing code that touches security, data handling, or infrastructure.",
-		"",
-		"**Factory instructions** (taiga_list_factory_documents / taiga_get_factory_document):",
-		"A factory's standing guidance: domain context (ubiquitous language, entities, business rules),",
-		"tech preferences (approved stack, patterns), and conventions. Read these to understand HOW this factory builds software.",
-		"",
-		"**Product documents** (taiga_list_product_documents / taiga_get_product_document):",
-		"Specification (what to build), architecture (how it's designed), threat model (security risks),",
-		"technology decisions, and data flow. Read these to understand the specific product.",
-		"",
-		"**Backlog and runs** (taiga_list_backlog_items / taiga_get_backlog_item / taiga_list_builds / taiga_get_build):",
-		"The product's initiatives with their acceptance criteria, and what Taiga's coding agent already built",
-		"for them: runs, steps, commits and pull requests.",
-		"",
-		"Workflow: Inside a git checkout, start with taiga_resolve_product on the remote URL to find the product.",
-		"Otherwise 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.",
-		"",
-		"When you notice a policy or factory instructions are outdated, fix the section with",
-		"taiga_update_document or taiga_update_factory_document. That saves a draft nobody follows yet;",
-		"publish it with taiga_publish_document or taiga_publish_factory_document only when the person asks.",
-		"This keeps the knowledge base accurate for everyone."
-	].join("\n") });
+	}, { instructions: SERVER_INSTRUCTIONS });
 	registerAllTools(server, client);
 	const toolCount = introspection.capabilities.length;
 	console.error(`Taiga MCP server started (${toolCount} capabilities, user: ${introspection.email}, role: ${introspection.role})`);