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

package/src/server.integration.test.ts

@@ -88,11 +88,11 @@ function sentBody(fetchSpy: ReturnType<typeof vi.fn>, method: string, pathPart:
 
 function makeFetchRouter(routes: Record<string, unknown>) {
   return vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
-    const path = new URL(url).pathname;
+    const { pathname: path, search } = new URL(url);
     const method = init?.method ?? 'GET';
-    const key = `${method} ${path}`;
-
-    const body = routes[key] ?? routes[path];
+    // Most specific first: a route keyed with its query string (the two
+    // document timelines share a path) wins over one keyed by path alone.
+    const body = routes[`${method} ${path}${search}`] ?? routes[`${method} ${path}`] ?? routes[path];
     if (body !== undefined) {
       return {
         ok: true,
@@ -370,17 +370,33 @@ describe('MCP server integration', () => {
       expect(parseToolResult(result)).toEqual(factories);
     });
 
-    it('should return document content through MCP protocol', async () => {
-      const docs = [{ id: 'd1', title: 'Security Policy' }];
+    it('should list company documents as summaries without content or authorship', async () => {
+      const doc = {
+        ...policyDocument(),
+        description: 'Controls for code and infrastructure',
+        hasDraft: true,
+        createdBy: 'user-1',
+        updatedAt: '2026-10-01T00:00:00.000Z',
+      };
 
       const { client } = await bootMcpPair({
         capabilities: ALL_CAPABILITIES,
-        routes: { 'GET /v1/tenants/current/documents': { data: docs, nextCursor: null } },
+        routes: { 'GET /v1/tenants/current/documents': { data: [doc], nextCursor: null } },
       });
 
       const result = await client.callTool({ name: 'taiga_list_documents', arguments: {} });
 
-      expect(parseToolResult(result)).toEqual(docs);
+      expect(parseToolResult(result)).toEqual([
+        {
+          type: 'policy_security',
+          name: 'Security Policy',
+          description: 'Controls for code and infrastructure',
+          version: 3,
+          isDraft: false,
+          hasDraft: true,
+          updatedAt: '2026-10-01T00:00:00.000Z',
+        },
+      ]);
     });
 
     it('should replace one section of the existing draft and keep the rest', async () => {
@@ -628,7 +644,7 @@ describe('MCP server integration', () => {
 
       const result = await client.callTool({
         name: 'taiga_update_document',
-        arguments: { type: 'policy_nope', sectionId: 'summary', content: 'x' },
+        arguments: { type: 'policy_security', sectionId: 'summary', content: 'x' },
       });
 
       expect(result.isError).toBe(true);
@@ -1040,6 +1056,625 @@ describe('MCP server integration', () => {
     });
   });
 
+  // -------------------------------------------------------------------------
+  // Plan and reality (PRO-2570): the two document timelines, summaries that
+  // say which is which, and misses that say what does exist.
+  // -------------------------------------------------------------------------
+
+  describe('plan and reality documents', () => {
+    const planSpec = {
+      id: 'doc-spec',
+      type: 'specification',
+      version: 2,
+      isDraft: false,
+      hasDraft: false,
+      stage: 'planning',
+      origin: 'plan',
+      dataKeyCount: 7,
+      derivedFrom: { sources: [{ type: 'business_goals', version: 1 }] },
+      outdated: { sources: [{ type: 'business_goals', from: 1, to: 2 }] },
+      createdBy: 'user-1',
+      reviewedAt: '2026-09-30T00:00:00.000Z',
+      reviewedByName: 'Reviewer',
+      updatedAt: '2026-10-01T00:00:00.000Z',
+    };
+    const realityArchitecture = {
+      ...planSpec,
+      id: 'doc-arch',
+      type: 'architecture',
+      version: 1,
+      origin: 'reality',
+      outdated: undefined,
+    };
+    const planList = `GET /v1/products/${PRODUCT_ID}/documents?origin=plan&limit=100`;
+    const realityList = `GET /v1/products/${PRODUCT_ID}/documents?origin=reality&limit=100`;
+    const productRoute = `GET /v1/products/${PRODUCT_ID}`;
+    const greenfield = { data: { id: PRODUCT_ID, name: 'Web', slug: 'web', settings: {} } };
+    const brownfield = {
+      data: { id: PRODUCT_ID, name: 'Legacy', slug: 'legacy', settings: { projectType: 'brownfield' } },
+    };
+
+    it('should list both timelines as summaries and explain the empty one', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [planSpec], nextCursor: null },
+          [realityList]: { data: [], nextCursor: null },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_list_product_documents',
+        arguments: { productId: PRODUCT_ID },
+      });
+
+      expect(result.isError).toBeFalsy();
+      const parsed = parseToolResult(result);
+      expect(parsed.projectType).toBe('greenfield');
+      expect(parsed.defaultOrigin).toBe('plan');
+      expect(parsed.plan).toEqual([
+        {
+          type: 'specification',
+          name: 'Specification',
+          origin: 'plan',
+          version: 2,
+          isDraft: false,
+          hasDraft: false,
+          stage: 'planning',
+          reviewedAt: '2026-09-30T00:00:00.000Z',
+          updatedAt: '2026-10-01T00:00:00.000Z',
+          outdated: true,
+        },
+      ]);
+      expect(parsed.reality).toEqual([]);
+      expect(parsed.notes).toHaveLength(1);
+      expect(parsed.notes[0]).toMatch(/No reality documents yet.*merged pull request/);
+      const origins = fetchSpy.mock.calls
+        .map((c: unknown[]) => new URL(c[0] as string))
+        .filter((u: URL) => u.pathname.endsWith('/documents'))
+        .map((u: URL) => u.searchParams.get('origin'))
+        .sort();
+      expect(origins).toEqual(['plan', 'reality']);
+    });
+
+    it('should read the asked timeline and drop provenance from what it returns', async () => {
+      const doc = {
+        ...realityArchitecture,
+        data: {
+          sections: { overview: { source: 'derived', priority: 'core', content: 'As built', derivedFrom: ['x'] } },
+        },
+      };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [`GET /v1/products/${PRODUCT_ID}/documents/architecture?origin=reality`]: { data: doc } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture', origin: 'reality' },
+      });
+
+      expect(result.isError).toBeFalsy();
+      const parsed = parseToolResult(result);
+      expect(parsed).not.toHaveProperty('derivedFrom');
+      expect(parsed).not.toHaveProperty('outdated');
+      expect(parsed.data.sections.overview).toEqual({ source: 'derived', priority: 'core', content: 'As built' });
+      expect(parsed.origin).toBe('reality');
+    });
+
+    it('should read the plan by default for a greenfield product', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [`GET /v1/products/${PRODUCT_ID}/documents/specification?origin=plan`]: { data: planSpec },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'specification' },
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(sentUrl(fetchSpy, '/documents/specification').searchParams.get('origin')).toBe('plan');
+    });
+
+    it('should say which timeline has the document when the asked one does not', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [planSpec], nextCursor: null },
+          [realityList]: { data: [realityArchitecture], nextCursor: null },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture' },
+      });
+
+      expect(result.isError).toBe(true);
+      const { error, message } = parseToolResult(result);
+      expect(error).toBe('NOT_FOUND');
+      expect(message).toContain('No published plan Architecture (architecture)');
+      expect(message).toContain("It is published on the reality side: call again with origin 'reality'");
+      expect(message).toContain('Plan documents: specification (v2)');
+      expect(message).toContain('Reality documents: architecture (v1)');
+    });
+
+    it('should explain an empty reality timeline when a reality read misses', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [planSpec], nextCursor: null },
+          [realityList]: { data: [], nextCursor: null },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture', origin: 'reality' },
+      });
+
+      expect(parseToolResult(result).message).toMatch(/No reality documents yet.*merged pull request/);
+    });
+
+    it('should read reality by default for an imported product, whose plan side is empty by design', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: brownfield,
+          [`GET /v1/products/${PRODUCT_ID}/documents/architecture?origin=reality`]: { data: realityArchitecture },
+          [planList]: { data: [], nextCursor: null },
+          [realityList]: { data: [realityArchitecture], nextCursor: null },
+        },
+      });
+
+      const read = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture' },
+      });
+      const list = await client.callTool({
+        name: 'taiga_list_product_documents',
+        arguments: { productId: PRODUCT_ID },
+      });
+
+      expect(read.isError).toBeFalsy();
+      expect(sentUrl(fetchSpy, '/documents/architecture').searchParams.get('origin')).toBe('reality');
+      const parsed = parseToolResult(list);
+      expect(parsed.projectType).toBe('brownfield');
+      expect(parsed.defaultOrigin).toBe('reality');
+      expect(parsed.notes).toEqual([
+        expect.stringMatching(/imported.*no discovery chain.*Look & Feel, Product Instructions/),
+      ]);
+    });
+
+    it('should read product instructions from the plan side even on an imported product', async () => {
+      const instructions = {
+        ...planSpec,
+        type: 'product_instructions',
+        data: { sections: { instructions: { content: 'x' } } },
+      };
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: brownfield,
+          [`GET /v1/products/${PRODUCT_ID}/documents/product_instructions?origin=plan`]: { data: instructions },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'product_instructions' },
+      });
+
+      expect(result.isError).toBeFalsy();
+      expect(sentUrl(fetchSpy, '/documents/product_instructions').searchParams.get('origin')).toBe('plan');
+    });
+
+    it('should not call a draft-only row published when a read misses', async () => {
+      const planDraft = { ...planSpec, isDraft: true, version: null };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [planDraft], nextCursor: null },
+          [realityList]: { data: [], nextCursor: null },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'specification', origin: 'plan' },
+      });
+
+      const { message } = parseToolResult(result);
+      expect(message).toContain('A draft of it exists on the plan side, unpublished.');
+      expect(message).toContain('Plan documents: specification (draft).');
+      expect(message).not.toContain('call again with origin');
+    });
+
+    it('should report the API failing when neither side can be listed', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [productRoute]: greenfield },
+      });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        if (!new URL(url).pathname.endsWith('/documents')) return router(url, init);
+        const body = { error: 'Too Many Requests', code: 'RATE_LIMITED', message: 'Slow down' };
+        return { ok: false, status: 429, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture' },
+      });
+
+      expect(parseToolResult(result)).toEqual({ error: 'RATE_LIMITED', message: 'Slow down' });
+    });
+
+    it('should report a product the key cannot see as a product miss, not a document miss', async () => {
+      // No product route: GET /products/:id answers the API's 404.
+      const { client } = await bootMcpPair({ capabilities: ['products:read'] });
+
+      const withOrigin = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture', origin: 'plan' },
+      });
+      const withoutOrigin = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture' },
+      });
+
+      for (const result of [withOrigin, withoutOrigin]) {
+        expect(result.isError).toBe(true);
+        expect(parseToolResult(result)).toEqual({
+          error: 'NOT_FOUND',
+          message: 'The requested resource does not exist',
+        });
+      }
+    });
+
+    it('should name a draft on the other side too', async () => {
+      const planDraft = { ...planSpec, type: 'architecture', isDraft: true, version: null };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [planDraft], nextCursor: null },
+          [realityList]: { data: [], nextCursor: null },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture', origin: 'reality' },
+      });
+
+      expect(parseToolResult(result).message).toContain('A draft of it exists on the plan side, unpublished.');
+    });
+
+    it.each([
+      ['pending', /import has not started/],
+      ['analyzing', /import is running/],
+      ['generating_docs', /import is running/],
+      ['cancelled', /import was cancelled/],
+      ['failed', /import failed/],
+      ['complete', /none have been published/],
+    ])('should say where an import at %s left an empty reality side', async (importStatus, expected) => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: { data: { ...brownfield.data, settings: { projectType: 'brownfield', importStatus } } },
+          [planList]: { data: [], nextCursor: null },
+          [realityList]: { data: [], nextCursor: null },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_list_product_documents',
+        arguments: { productId: PRODUCT_ID },
+      });
+
+      expect(parseToolResult(result).notes[1]).toMatch(expected);
+    });
+
+    it('should read the product once when origin is omitted and the read misses', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [], nextCursor: null },
+          [realityList]: { data: [], nextCursor: null },
+        },
+      });
+
+      await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'architecture' },
+      });
+
+      const productReads = fetchSpy.mock.calls.filter(
+        (c: unknown[]) => new URL(c[0] as string).pathname === `/v1/products/${PRODUCT_ID}`
+      );
+      expect(productReads).toHaveLength(1);
+    });
+
+    it('should mark a current plan document as not outdated, and leave reality rows without the fact', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [{ ...planSpec, outdated: null }], nextCursor: null },
+          [realityList]: { data: [realityArchitecture], nextCursor: null },
+        },
+      });
+
+      const parsed = parseToolResult(
+        await client.callTool({ name: 'taiga_list_product_documents', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(parsed.plan[0].outdated).toBe(false);
+      expect(parsed.reality[0]).not.toHaveProperty('outdated');
+    });
+
+    it('should give a plan draft no staleness fact: it has nothing published to be outdated', async () => {
+      const planDraft = { ...planSpec, isDraft: true, version: null, outdated: null };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: {
+          [productRoute]: greenfield,
+          [planList]: { data: [planDraft], nextCursor: null },
+          [realityList]: { data: [], nextCursor: null },
+        },
+      });
+
+      const parsed = parseToolResult(
+        await client.callTool({ name: 'taiga_list_product_documents', arguments: { productId: PRODUCT_ID } })
+      );
+
+      expect(parsed.plan[0]).not.toHaveProperty('outdated');
+    });
+
+    it('should keep the side that answered when the other cannot be listed', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { [productRoute]: greenfield, [planList]: { data: [planSpec], nextCursor: null } },
+      });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        if (new URL(url).searchParams.get('origin') !== 'reality') return router(url, init);
+        const body = { error: 'Internal Server Error', code: 'INTERNAL', message: 'boom' };
+        return { ok: false, status: 500, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const list = parseToolResult(
+        await client.callTool({ name: 'taiga_list_product_documents', arguments: { productId: PRODUCT_ID } })
+      );
+      const miss = parseToolResult(
+        await client.callTool({
+          name: 'taiga_get_product_document',
+          arguments: { productId: PRODUCT_ID, type: 'architecture', origin: 'plan' },
+        })
+      );
+
+      expect(list.plan).toHaveLength(1);
+      expect(list.reality).toBeNull();
+      expect(list).not.toHaveProperty('unlistable');
+      expect(list.notes).toEqual(['The reality side could not be listed (500 INTERNAL).']);
+      expect(miss.message).toContain('Plan documents: specification (v2).');
+      expect(miss.message).toContain('The reality side could not be listed (500 INTERNAL).');
+    });
+
+    it('should refuse a document type outside the catalogue before any request', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      const before = fetchSpy.mock.calls.length;
+
+      const result = await client.callTool({
+        name: 'taiga_get_product_document',
+        arguments: { productId: PRODUCT_ID, type: 'policy_ip' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+  });
+
+  describe('misses that say what exists', () => {
+    it('should name the draft and the published documents when a company document is not published', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['tenant:documents:read'],
+        routes: {
+          'GET /v1/tenants/current/documents/policy_ops/draft': {
+            data: policyDocument({ type: 'policy_ops', isDraft: true }),
+          },
+          'GET /v1/tenants/current/documents': {
+            data: [policyDocument(), policyDocument({ type: 'tone_of_voice', isDraft: true, version: null })],
+            nextCursor: null,
+          },
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_document', arguments: { type: 'policy_ops' } });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toEqual({
+        error: 'NOT_FOUND',
+        message:
+          'No published policy_ops. A draft exists; taiga_publish_document publishes it once the person asks. ' +
+          'Published documents: policy_security (v3).',
+      });
+    });
+
+    it('should keep the published list when only the draft lookup behind the explanation fails', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['tenant:documents:read'],
+        routes: { 'GET /v1/tenants/current/documents': { data: [policyDocument()], nextCursor: null } },
+      });
+      const router = fetchSpy.getMockImplementation() as (url: string, init: RequestInit) => Promise<unknown>;
+      fetchSpy.mockImplementation(async (url: string, init: RequestInit) => {
+        if (!new URL(url).pathname.endsWith('/draft')) return router(url, init);
+        const body = { error: 'Internal Server Error', code: 'INTERNAL', message: 'boom' };
+        return { ok: false, status: 500, json: async () => body, text: async () => JSON.stringify(body) };
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_document', arguments: { type: 'policy_ops' } });
+
+      expect(parseToolResult(result)).toEqual({
+        error: 'NOT_FOUND',
+        message:
+          'No published policy_ops. The draft could not be checked (500 INTERNAL). Published documents: policy_security (v3).',
+      });
+    });
+
+    it('should say when there is no draft either', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['tenant:documents:read'],
+        routes: {
+          'GET /v1/tenants/current/documents/tone_of_voice/draft': { data: null },
+          'GET /v1/tenants/current/documents': { data: [], nextCursor: null },
+        },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_document', arguments: { type: 'tone_of_voice' } });
+
+      expect(parseToolResult(result).message).toBe(
+        'No published tone_of_voice. There is no draft either. Nothing is published yet.'
+      );
+    });
+
+    it('should tell a factory with no instructions how to get some', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['factories:read'],
+        routes: {
+          [`GET /v1/factories/${FACTORY_ID}`]: { data: { id: FACTORY_ID, name: 'Platform' } },
+          [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions/draft`]: { data: null },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_factory_document',
+        arguments: { factoryId: FACTORY_ID },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).message).toBe(
+        'This factory has no published factory_instructions yet. There is no draft either: write one with ' +
+          'taiga_update_factory_document, then publish it when the person asks.'
+      );
+    });
+
+    it('should report a nonexistent factory as such even when the draft route answers null for it', async () => {
+      // A break-glass key skips the membership check, and the draft route
+      // does not look the factory up: it answers 200 null for an id that
+      // does not exist. The factory read is what says it does not.
+      const { client } = await bootMcpPair({
+        capabilities: ['factories:read'],
+        routes: { [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions/draft`]: { data: null } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_factory_document',
+        arguments: { factoryId: FACTORY_ID },
+      });
+
+      expect(parseToolResult(result)).toEqual({ error: 'NOT_FOUND', message: 'The requested resource does not exist' });
+    });
+
+    it('should report a factory the key cannot see as a factory miss, not an unpublished document', async () => {
+      // No routes at all: the document and the draft route both answer 404.
+      const { client } = await bootMcpPair({ capabilities: ['factories:read'] });
+
+      const result = await client.callTool({
+        name: 'taiga_get_factory_document',
+        arguments: { factoryId: FACTORY_ID },
+      });
+
+      expect(parseToolResult(result)).toEqual({ error: 'NOT_FOUND', message: 'The requested resource does not exist' });
+    });
+
+    it('should point at the draft when a factory has one unpublished', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['factories:read'],
+        routes: {
+          [`GET /v1/factories/${FACTORY_ID}`]: { data: { id: FACTORY_ID, name: 'Platform' } },
+          [`GET /v1/factories/${FACTORY_ID}/documents/factory_instructions/draft`]: {
+            data: { id: 'fd', type: 'factory_instructions', isDraft: true, data: { sections: {} } },
+          },
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_factory_document',
+        arguments: { factoryId: FACTORY_ID },
+      });
+
+      expect(parseToolResult(result).message).toContain('A draft exists; taiga_publish_factory_document');
+    });
+  });
+
+  describe('product by slug', () => {
+    const product = { id: PRODUCT_ID, name: 'Web', slug: 'web', factoryId: FACTORY_ID, settings: {} };
+
+    it('should resolve a slug through the list filter and return the product in full', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { 'GET /v1/products?slug=web&limit=1': { data: [product], nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_product', arguments: { slug: 'web' } });
+
+      expect(result.isError).toBeFalsy();
+      expect(parseToolResult(result)).toEqual(product);
+      expect(sentUrl(fetchSpy, '/v1/products').searchParams.get('slug')).toBe('web');
+    });
+
+    it('should say NOT_FOUND for a slug nobody visible has', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read'],
+        routes: { 'GET /v1/products?slug=nope&limit=1': { data: [], nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_get_product', arguments: { slug: 'nope' } });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toMatchObject({ error: 'NOT_FOUND', message: expect.stringContaining('"nope"') });
+    });
+
+    it('should refuse both identifiers at once rather than pick one', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      const before = fetchSpy.mock.calls.length;
+
+      const result = await client.callTool({
+        name: 'taiga_get_product',
+        arguments: { productId: PRODUCT_ID, slug: 'web' },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result)).toMatchObject({
+        error: 'VALIDATION_FAILED',
+        message: expect.stringContaining('not both'),
+      });
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+
+    it('should ask for one of the two when neither is given', async () => {
+      const { client, fetchSpy } = await bootMcpPair({ capabilities: ['products:read'] });
+      const before = fetchSpy.mock.calls.length;
+
+      const result = await client.callTool({ name: 'taiga_get_product', arguments: {} });
+
+      expect(result.isError).toBe(true);
+      expect(parseToolResult(result).error).toBe('VALIDATION_FAILED');
+      expect(fetchSpy.mock.calls.length).toBe(before);
+    });
+  });
+
   describe('error handling', () => {
     it('should surface API errors as structured MCP error content', async () => {
       // Introspect succeeds, but all other endpoints fail