@taiga-ai/mcp-server 0.6.0-rc.393 → 0.7.0-dev.395

package/src/tools/catalogue.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import {
+  FACTORY_DOCUMENT_TYPES,
+  POLICY_TYPES,
+  PRODUCT_DOCUMENT_TYPES,
+  PRODUCT_STATUSES,
+  TENANT_DOCUMENT_TYPES,
+} from '@taiga/types';
+import { TaigaClient } from '../client.js';
+import { registerAllTools } from './index.js';
+import { SERVER_INSTRUCTIONS } from './instructions.js';
+import { PRODUCT_DOCUMENT_NAMES } from './catalogue.js';
+
+/**
+ * What the model reads must match what exists. The walk-through that led to
+ * this file found two policy types named in a description that no tenant
+ * has; a model that follows a description into a type the API refuses learns
+ * to stop asking.
+ */
+
+const ALL_CAPABILITIES = [
+  'products:read',
+  'factories:read',
+  'factories:documents:write',
+  'tenant:documents:read',
+  'tenant:documents:write',
+  'backlog:read',
+];
+
+async function allTools() {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: { userId: 'u', tenantId: 't', email: 'e', role: 'owner', capabilities: ALL_CAPABILITIES },
+      }),
+      text: async () => '',
+    })
+  );
+  const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'k' });
+  await taigaClient.introspect();
+  const server = new McpServer({ name: 't', version: '0' });
+  registerAllTools(server, taigaClient);
+  const client = new Client({ name: 'c', version: '0' });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await Promise.all([server.connect(st), client.connect(ct)]);
+  return (await client.listTools()).tools;
+}
+
+/** Every `policy_*` token in a text. */
+const policyTokens = (text: string) => [...new Set(text.match(/\bpolicy_[a-z_]+\b/g) ?? [])];
+
+describe('tool descriptions against the catalogue', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('names no policy type the catalogue lacks, in any description or schema', async () => {
+    const tools = await allTools();
+    const text = JSON.stringify(tools) + SERVER_INSTRUCTIONS;
+
+    for (const token of policyTokens(text)) {
+      expect(TENANT_DOCUMENT_TYPES as readonly string[], token).toContain(token);
+    }
+  });
+
+  it('names every policy where the company documents are explained', async () => {
+    const tools = await allTools();
+    const list = tools.find((t) => t.name === 'taiga_list_documents')!;
+    const get = tools.find((t) => t.name === 'taiga_get_document')!;
+    const typeEnum = (get.inputSchema.properties as Record<string, { enum?: string[] }>).type!.enum;
+
+    for (const type of POLICY_TYPES) {
+      expect(list.description, type).toContain(type);
+      expect(SERVER_INSTRUCTIONS, type).toContain(type);
+    }
+    expect(typeEnum).toEqual([...TENANT_DOCUMENT_TYPES]);
+  });
+
+  it('offers exactly the product statuses, product document types and origins the API has', async () => {
+    const tools = await allTools();
+    const props = (name: string) =>
+      tools.find((t) => t.name === name)!.inputSchema.properties as Record<string, { enum?: string[] }>;
+
+    expect(props('taiga_list_products').status!.enum).toEqual([...PRODUCT_STATUSES]);
+    expect(props('taiga_get_product_document').type!.enum).toEqual([...PRODUCT_DOCUMENT_TYPES]);
+    expect(props('taiga_get_product_document').origin!.enum).toEqual(['plan', 'reality']);
+    expect(props('taiga_get_factory_document').type!.enum).toEqual([...FACTORY_DOCUMENT_TYPES]);
+  });
+
+  it('has a display name for every product document type, the one the web uses', () => {
+    expect(Object.keys(PRODUCT_DOCUMENT_NAMES).sort()).toEqual([...PRODUCT_DOCUMENT_TYPES].sort());
+    // apps/web/src/lib/documentTypes.ts: "Look & Feel", not "UI Direction".
+    expect(PRODUCT_DOCUMENT_NAMES.ui_direction).toBe('Look & Feel');
+  });
+
+  it('explains both timelines and the section metadata in the server instructions', () => {
+    expect(SERVER_INSTRUCTIONS).toMatch(/plan: .*discovery/);
+    expect(SERVER_INSTRUCTIONS).toMatch(/reality: .*merged pull request/);
+    for (const term of ['`source`', '`priority: core`', 'overlay-<id>', 'cloud-preset:<providers>', 'brownfield']) {
+      expect(SERVER_INSTRUCTIONS).toContain(term);
+    }
+    // Nothing writes a `user` source: a hand edit keeps the source it had.
+    expect(SERVER_INSTRUCTIONS).not.toMatch(/user: edited/);
+  });
+});

package/src/tools/catalogue.ts

@@ -0,0 +1,165 @@
+/**
+ * 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.
+ */
+import {
+  FACTORY_DOCUMENT_TYPES,
+  POLICY_TYPES,
+  PRODUCT_DOCUMENT_DISPLAY_NAMES,
+  PRODUCT_DOCUMENT_ORIGINS,
+  PRODUCT_DOCUMENT_TYPES,
+  PRODUCT_STATUSES,
+  REALITY_DERIVED_DOCUMENT_TYPES,
+  TENANT_DOCUMENT_TYPES,
+  type ProductDocumentOrigin,
+  type ProductDocumentType,
+  type TenantDocumentType,
+} from '@taiga/types';
+
+export {
+  FACTORY_DOCUMENT_TYPES,
+  POLICY_TYPES,
+  PRODUCT_DOCUMENT_ORIGINS,
+  PRODUCT_DOCUMENT_TYPES,
+  PRODUCT_STATUSES,
+  TENANT_DOCUMENT_TYPES,
+};
+export type { ProductDocumentOrigin };
+
+/**
+ * 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.
+ */
+export const PRODUCT_DOCUMENT_NAMES: Record<ProductDocumentType, string> = {
+  ...PRODUCT_DOCUMENT_DISPLAY_NAMES,
+  // "Look & Feel" is what the web calls it (apps/web/src/lib/documentTypes.ts);
+  // an agent and a person should name the same document the same way.
+  ui_direction: 'Look & Feel',
+  codebase_snapshot: 'Codebase Snapshot',
+  product_instructions: 'Product Instructions',
+};
+
+export function productDocumentName(type: string): string {
+  return (PRODUCT_DOCUMENT_NAMES as Record<string, string>)[type] ?? type;
+}
+
+/** The organization documents that are not policies: goals, standards, voice, instructions. */
+export const OTHER_TENANT_DOCUMENT_TYPES: readonly TenantDocumentType[] = TENANT_DOCUMENT_TYPES.filter(
+  (type) => !(POLICY_TYPES as readonly string[]).includes(type)
+);
+
+/** `a, b, c` for a description. */
+export function named(types: readonly string[]): string {
+  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.
+ */
+export const ORIGIN_MEANING: Record<ProductDocumentOrigin, string> = {
+  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.
+ */
+export function isImportedProduct(product: ProductSettingsView | null | undefined): boolean {
+  const settings = product?.settings;
+  return (
+    typeof settings === 'object' &&
+    settings !== null &&
+    (settings as { projectType?: unknown }).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.
+ */
+export const PLAN_ONLY_DOCUMENT_TYPES: readonly ProductDocumentType[] = PRODUCT_DOCUMENT_TYPES.filter(
+  (type) => !(REALITY_DERIVED_DOCUMENT_TYPES as readonly string[]).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).
+ */
+export function defaultOriginFor(
+  product: ProductSettingsView | null | undefined,
+  type?: ProductDocumentType
+): ProductDocumentOrigin {
+  if (type !== undefined && PLAN_ONLY_DOCUMENT_TYPES.includes(type)) return 'plan';
+  return isImportedProduct(product) ? 'reality' : 'plan';
+}
+
+/** The product settings the notes read: the import marker and where the import got to. */
+export interface ProductSettingsView {
+  settings?: unknown;
+}
+
+/**
+ * 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: ProductSettingsView | null | undefined): string | null {
+  const settings = product?.settings;
+  if (typeof settings !== 'object' || settings === null) return null;
+  const status = (settings as { importStatus?: unknown }).importStatus;
+  return typeof status === 'string' ? status : null;
+}
+
+/** Why a side of the timeline is empty, for a list or a miss that shows one. */
+export function emptyOriginNote(
+  origin: ProductDocumentOrigin,
+  product: ProductSettingsView | null | undefined
+): string {
+  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.';
+    // generating_docs is the retired name for the same in-flight state
+    // (PRO-1161); rows that predate it can still carry it.
+    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.';
+  }
+}

package/src/tools/documents.ts

@@ -2,10 +2,40 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { TaigaApiError, type TaigaClient, type TaigaDocument } from '../client.js';
 import { READ_ONLY } from './annotations.js';
+import {
+  FACTORY_DOCUMENT_TYPES,
+  OTHER_TENANT_DOCUMENT_TYPES,
+  POLICY_TYPES,
+  TENANT_DOCUMENT_TYPES,
+  named,
+} from './catalogue.js';
 import { runTool, toolError, toolResult } from './errors.js';
-import { applySectionEdit, sectionContent, sectionsOf } from './sections.js';
-import { documentType } from './inputs.js';
-import { summarizeList } from './summarize.js';
+import { applySectionEdit, sectionContent, sectionsOf, stripProvenance } from './sections.js';
+import { pickFields } from './summarize.js';
+
+/**
+ * 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'] as const;
+
+const summaries = (rows: unknown[]) => pickFields(rows as Record<string, unknown>[], DOCUMENT_SUMMARY_FIELDS);
+
+/** What a lookup behind a miss said when it failed, so an unknown stays unknown. */
+function failedLookup(what: string, reason: unknown): string {
+  const said = reason instanceof TaigaApiError ? `${reason.status} ${reason.code ?? ''}`.trim() : 'the request failed';
+  return `${what} could not be checked (${said}).`;
+}
+
+/** `a (v3), b (v1)` for a not-found message. */
+function publishedList(rows: unknown[]): string {
+  // The list routes return the latest draft rows beside the published ones,
+  // and a draft named as published sends the model into a second miss.
+  return (rows as { type: string; version: unknown; isDraft: boolean }[])
+    .filter((row) => row.isDraft === false)
+    .map((row) => `${row.type} (v${String(row.version)})`)
+    .join(', ');
+}
 
 const DRAFT_WRITE = {
   readOnlyHint: false,
@@ -26,9 +56,9 @@ const sectionId = z
       '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)}`);
 
 /**
  * The read, save and publish calls for one document scope. The tools are the
@@ -100,10 +130,11 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       {
         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.',
+          "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)'),
         },
@@ -112,8 +143,7 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       (params) =>
         runTool(async () => {
           const result = await client.listTenantDocuments(params);
-          const summaries = summarizeList(result.data as Record<string, unknown>[]);
-          return toolResult(summaries);
+          return toolResult(summaries(result.data));
         })
     );
 
@@ -122,23 +152,47 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       {
         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.',
+          "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: documentType.describe(
-            'Document type -- get available types from taiga_list_documents. ' +
-              'Common: policy_security, policy_data, policy_sdlc, policy_architecture'
-          ),
+          type: tenantDocumentType,
         },
         annotations: READ_ONLY,
       },
       (params) =>
         runTool(async () => {
-          const result = await client.getTenantDocument(params.type);
-          return toolResult(result.data);
+          try {
+            const result = await client.getTenantDocument(params.type);
+            return toolResult(stripProvenance(result.data));
+          } catch (error) {
+            if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
+            // Best effort, each part on its own: a failed lookup must not turn
+            // a miss into an outage, nor blank the part that did answer.
+            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(' '));
+          }
         })
     );
   }
@@ -199,9 +253,10 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       {
         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 " +
+          "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'),
@@ -212,8 +267,7 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       (params) =>
         runTool(async () => {
           const result = await client.listFactoryDocuments(params.factoryId, { limit: params.limit });
-          const summaries = summarizeList(result.data as Record<string, unknown>[]);
-          return toolResult(summaries);
+          return toolResult(summaries(result.data));
         })
     );
 
@@ -224,20 +278,43 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
         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.',
+          '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 () => {
-          const result = await client.getFactoryDocument(params.factoryId, params.type);
-          return toolResult(result.data);
+          try {
+            const result = await client.getFactoryDocument(params.factoryId, params.type);
+            return toolResult(stripProvenance(result.data));
+          } catch (error) {
+            if (!(error instanceof TaigaApiError) || error.status !== 404) throw error;
+            // A factory that does not exist answers the same 404 as one with
+            // nothing published, and the draft route does not check the
+            // factory for a break-glass key: read the factory first, so its
+            // 404 propagates as the factory missing rather than as "nothing
+            // published yet".
+            await client.getFactory(params.factoryId);
+            // The draft route answers 200 with null for a visible factory
+            // with no draft, so its 404 is also the factory out of scope and
+            // propagates. Any other failure is named.
+            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: unknown) => {
+                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}`);
+          }
         })
     );
   }
@@ -254,7 +331,10 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       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',

package/src/tools/instructions.ts

@@ -0,0 +1,65 @@
+import {
+  OTHER_TENANT_DOCUMENT_TYPES,
+  ORIGIN_MEANING,
+  POLICY_TYPES,
+  PRODUCT_DOCUMENT_NAMES,
+  named,
+} from './catalogue.js';
+
+/**
+ * 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.
+ */
+export 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');