@taiga-ai/mcp-server 0.10.0-rc.405 → 0.11.0-dev.410

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.10.0-rc.405",
+  "version": "0.11.0-dev.410",
   "description": "MCP server for Taiga -- gives AI assistants access to documents and products",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,10 @@
   },
   "devDependencies": {
     "@tsconfig/strictest": "^2.0.8",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.20.1",
+    "mdast-util-from-markdown": "^2.1.0",
+    "mdast-util-to-markdown": "^2.2.0",
     "rolldown": "^1.2.3",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"

package/src/client.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { readFileSync } from 'node:fs';
-import { TaigaApiError, TaigaClient } from './client.js';
+import { TaigaApiError, TaigaClient, withoutTenant } from './client.js';
 
 // Read independently of src/version.ts, so the test checks the real file.
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };
@@ -150,6 +150,46 @@ describe('TaigaClient', () => {
   // Introspection -- the foundation for capability-gated tool registration
   // -------------------------------------------------------------------------
 
+  describe('withoutTenant', () => {
+    it('drops tenantId at every depth and keeps an own __proto__ key as data', () => {
+      const parsed = JSON.parse(
+        '{"__proto__": {"x": 1}, "tenantId": "t", "a": {"tenantId": "t", "b": [{"tenantId": "t", "c": 1}, 2, null]}, "d": "s"}'
+      ) as Record<string, unknown>;
+
+      const out = withoutTenant(parsed) as Record<string, unknown>;
+
+      expect(JSON.stringify(out)).not.toContain('tenantId');
+      expect(out.a).toEqual({ b: [{ c: 1 }, 2, null] });
+      expect(out.d).toBe('s');
+      expect(Object.prototype.hasOwnProperty.call(out, '__proto__')).toBe(true);
+      expect(Object.getPrototypeOf(out)).toBe(Object.prototype);
+      expect((out as { x?: unknown }).x).toBeUndefined();
+    });
+
+    it('walks a body nested deeper than a recursive copy could', () => {
+      const depth = 20_000;
+      const nested = JSON.parse(`${'{"a":['.repeat(depth)}{"tenantId":"t","v":1}${']}'.repeat(depth)}`) as unknown;
+
+      const out = withoutTenant(nested);
+
+      // Walked, not stringified: JSON.stringify recurses and would overflow where the copy did not.
+      let cursor: unknown = out;
+      for (let level = 0; level < depth; level += 1) {
+        expect(Object.keys(cursor as object)).toEqual(['a']);
+        cursor = (cursor as { a: unknown[] }).a[0];
+      }
+      expect(cursor).toEqual({ v: 1 });
+    });
+
+    it('keeps key order, which is the order sections render in', () => {
+      const out = withoutTenant({ z: 1, tenantId: 't', a: { y: 2, x: [3, { tenantId: 't', w: 4 }] }, m: 5 });
+
+      expect(Object.keys(out)).toEqual(['z', 'a', 'm']);
+      expect(Object.keys(out.a)).toEqual(['y', 'x']);
+      expect(out.a.x).toEqual([3, { w: 4 }]);
+    });
+  });
+
   describe('introspection', () => {
     it('should return and store the introspection result', async () => {
       const expected = {

package/src/client.ts

@@ -2,11 +2,45 @@ import type { ApiKeyIntrospection } from '@taiga/types';
 import { SERVER_VERSION } from './version.js';
 
 /**
- * A non-2xx answer from the Taiga API. Carries the status and the API's own
- * `code` and `message` so a tool can hand the model something it can act on
- * (a 400 from the publish gate names the section that still holds template
- * residue) instead of one opaque string.
+ * The same value without any `tenantId`, at any depth. Build run and step
+ * rows carry one; the key is scoped to one tenant already, so the id is
+ * never something the model acts on. Applied to every response here, once,
+ * so no tool, resource or prompt can hand it over by forgetting to; only
+ * the key's own introspection keeps it, typed and never handed over.
+ *
+ * An explicit stack rather than recursion: a document body a person stored
+ * can nest as deep as JSON.parse allows, and a walk must not overflow where
+ * the parse did not. Every key is defined as a data property, so an own
+ * "__proto__" key stays a key instead of becoming the copy's prototype.
  */
+export function withoutTenant<T>(value: T): T {
+  const root: { out?: unknown } = {};
+  // Siblings keep their order and nested values are copied in full: see the loop.
+  const pending: { source: unknown; target: object; key: string | number }[] = [
+    { source: value, target: root, key: 'out' },
+  ];
+  while (pending.length > 0) {
+    const { source, target, key } = pending.pop()!;
+    let copy: unknown = source;
+    // Children are pushed last-first so they pop first-first: key order is
+    // meaning in a section map (the order sections render in) and must survive.
+    if (Array.isArray(source)) {
+      copy = new Array(source.length);
+      for (let index = source.length - 1; index >= 0; index -= 1) {
+        pending.push({ source: source[index], target: copy as object, key: index });
+      }
+    } else if (source !== null && typeof source === 'object') {
+      copy = {};
+      const entries = Object.entries(source as Record<string, unknown>).filter(([inner]) => inner !== 'tenantId');
+      for (let index = entries.length - 1; index >= 0; index -= 1) {
+        pending.push({ source: entries[index]![1], target: copy as object, key: entries[index]![0] });
+      }
+    }
+    Object.defineProperty(target, key, { value: copy, enumerable: true, writable: true, configurable: true });
+  }
+  return root.out as T;
+}
+
 export class TaigaApiError extends Error {
   readonly status: number;
   readonly code: string | undefined;
@@ -87,7 +121,7 @@ export class TaigaClient {
     this.apiKey = opts.apiKey;
   }
 
-  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  private async request<T>(method: string, path: string, body?: unknown, keep?: { tenantId: true }): Promise<T> {
     const url = `${this.baseUrl}/v1${path}`;
     const headers: Record<string, string> = {
       Authorization: `Bearer ${this.apiKey}`,
@@ -108,7 +142,8 @@ export class TaigaClient {
       throw new TaigaApiError(method, path, response.status, text);
     }
 
-    return response.json() as Promise<T>;
+    const parsed = (await response.json()) as T;
+    return keep ? parsed : withoutTenant(parsed);
   }
 
   // ---------------------------------------------------------------------------
@@ -116,7 +151,10 @@ export class TaigaClient {
   // ---------------------------------------------------------------------------
 
   async introspect(): Promise<ApiKeyIntrospection> {
-    const result = await this.request<{ data: ApiKeyIntrospection }>('GET', '/auth/introspect');
+    // The key's own identity keeps its tenant: typed so, and never handed to the model.
+    const result = await this.request<{ data: ApiKeyIntrospection }>('GET', '/auth/introspect', undefined, {
+      tenantId: true,
+    });
     this.introspection = result.data;
     return result.data;
   }
@@ -312,7 +350,10 @@ export class TaigaClient {
   }
 
   /** A person's move on the line board: the column dropped into, and what to follow there. */
-  async transitionInitiative(itemId: string, body: { state: string; afterId?: string | null | undefined }) {
+  async transitionInitiative(
+    itemId: string,
+    body: { state: string; afterId?: string | null | undefined; archived?: boolean | undefined }
+  ) {
     return this.request<{ data: unknown }>('PUT', `/backlog/${seg(itemId)}/state`, body);
   }
 

package/src/server.integration.test.ts

@@ -1073,6 +1073,30 @@ describe('MCP server integration', () => {
       expect(parseToolResult(result)).toEqual({ ...run, steps: [step] });
     });
 
+    it('should drop tenantId from every response at the client, so a run, its steps, an item and a list row never carry it', async () => {
+      const tenanted = { ...run, tenantId: 'tenant-1' };
+      const tenantedStep = { ...step, tenantId: 'tenant-1', verification: { tenantId: 'tenant-1', ok: true } };
+      const { client } = await bootMcpPair({
+        capabilities: ['products:read', 'backlog:read'],
+        routes: {
+          [`/v1/builds/${BUILD_ID}`]: { data: tenanted },
+          [`/v1/builds/${BUILD_ID}/steps`]: { data: [tenantedStep] },
+          [`/v1/backlog/${ITEM_ID}`]: { data: { ...item, tenantId: 'tenant-1' } },
+        },
+      });
+
+      const build = parseToolResult(
+        await client.callTool({ name: 'taiga_get_build', arguments: { buildId: BUILD_ID } })
+      );
+      expect(build).toEqual({ ...run, steps: [{ ...step, verification: { ok: true } }] });
+      expect(JSON.stringify(build)).not.toContain('tenantId');
+
+      const got = parseToolResult(
+        await client.callTool({ name: 'taiga_get_backlog_item', arguments: { itemId: ITEM_ID } })
+      );
+      expect(got).toEqual(item);
+    });
+
     it('should refuse a fractional limit before any request, as the API would after one', async () => {
       const { client, fetchSpy } = await bootMcpPair({ capabilities: ['backlog:read', 'products:read'] });
       const before = fetchSpy.mock.calls.length;
@@ -2638,7 +2662,24 @@ describe('MCP server integration', () => {
       backlogItemId: ITEM_ID,
       version: 1,
       status: 'active',
-      steps: [{ id: 'step-1', planId: PLAN_ID, title: 'Add the route', writes: ['src/routes/login.ts'] }],
+      tenantId: 'tenant-1',
+      steps: [
+        {
+          id: 'step-1',
+          planId: PLAN_ID,
+          tenantId: 'tenant-1',
+          orderIndex: 1,
+          title: 'Add the route',
+          description: 'Three paragraphs of planner prose the summary must not carry',
+          layer: 'api',
+          dependencies: [],
+          filePaths: ['src/routes/login.ts'],
+          writes: ['src/routes/login.ts'],
+          reads: [],
+          createsResources: ['aws_rds_cluster.main'],
+          createdAt: '2026-10-08T00:00:00.000Z',
+        },
+      ],
     };
     const run = {
       id: BUILD_ID,
@@ -2876,6 +2917,58 @@ describe('MCP server integration', () => {
       expect(outcomeOf(result)).toMatchObject({ state: 'todo' });
     });
 
+    it('should archive an initiative where it stands and bring it back, through the same move', async () => {
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: {
+            data: { ...item, state: 'canceled', status: 'canceled', archivedAt: '2026-10-08T06:00:00.000Z' },
+          },
+        },
+      });
+
+      const filed = await client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'canceled', archived: true },
+      });
+
+      expect(filed.isError).toBeFalsy();
+      expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'canceled', archived: true });
+      expect(outcomeOf(filed)).toMatchObject({ state: 'canceled', archivedAt: '2026-10-08T06:00:00.000Z' });
+
+      fetchSpy.mockClear();
+      vi.stubGlobal('fetch', fetchSpy);
+      await client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'todo', archived: false },
+      });
+      expect(sentBody(fetchSpy, 'PUT', `/backlog/${ITEM_ID}/state`)).toEqual({ state: 'todo', archived: false });
+    });
+
+    it("should pass on the API's refusal to archive an initiative that is on the line", async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {
+          [`PUT /v1/backlog/${ITEM_ID}/state`]: refusal(
+            409,
+            'CONFLICT',
+            'Take this initiative off the line before archiving it.'
+          ),
+        },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_move_backlog_item',
+        arguments: { itemId: ITEM_ID, state: 'done', archived: true },
+      });
+
+      expect(result.isError).toBe(true);
+      expect(outcomeOf(result)).toEqual({
+        error: 'CONFLICT',
+        message: 'Take this initiative off the line before archiving it.',
+      });
+    });
+
     it('should offer exactly the columns a person may drop into, and refuse build', async () => {
       const { client, fetchSpy } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
 
@@ -2936,7 +3029,32 @@ describe('MCP server integration', () => {
       });
 
       const found = await client.callTool({ name: 'taiga_get_plan', arguments: { itemId: ITEM_ID } });
-      expect(outcomeOf(found)).toEqual(plan);
+      // A summary by default: the step's prose, timestamps and planId stay behind.
+      expect(outcomeOf(found)).toEqual({
+        id: PLAN_ID,
+        backlogItemId: ITEM_ID,
+        version: 1,
+        status: 'active',
+        steps: [
+          {
+            id: 'step-1',
+            orderIndex: 1,
+            title: 'Add the route',
+            layer: 'api',
+            dependencies: [],
+            writes: ['src/routes/login.ts'],
+            reads: [],
+            createsResources: ['aws_rds_cluster.main'],
+          },
+        ],
+      });
+
+      const full = await client.callTool({ name: 'taiga_get_plan', arguments: { itemId: ITEM_ID, full: true } });
+      const { tenantId: _t, ...planWithoutTenant } = plan;
+      expect(outcomeOf(full)).toEqual({
+        ...planWithoutTenant,
+        steps: plan.steps.map(({ tenantId: _s, ...step }) => step),
+      });
 
       const none = await client.callTool({ name: 'taiga_get_plan', arguments: { itemId: OTHER_ITEM } });
       expect(none.isError).toBe(true);

package/src/tools/backlogs.ts

@@ -38,11 +38,25 @@ const ITEM_OUTCOME_FIELDS = [
   'planningStatus',
   'needsHumanCause',
   'needsHumanDetail',
+  'archivedAt',
   'lifecycle',
 ] as const;
 
 const itemId = z.string().uuid().describe('Backlog item ID -- get from taiga_list_backlog_items');
 
+/** The plan without its steps' prose: enough to approve it or say what a run will do. */
+const PLAN_SUMMARY_FIELDS = ['id', 'backlogItemId', 'version', 'status', 'createdAt'] as const;
+const PLAN_STEP_SUMMARY_FIELDS = [
+  'id',
+  'orderIndex',
+  'title',
+  'layer',
+  'dependencies',
+  'writes',
+  'reads',
+  'createsResources',
+] as const;
+
 const outcome = (item: unknown) => toolResult(pickFields([item as Record<string, unknown>], ITEM_OUTCOME_FIELDS)[0]);
 
 /**
@@ -125,17 +139,27 @@ function registerBacklogReads(server: McpServer, client: TaigaClient) {
     {
       title: 'Get the active plan',
       description:
-        "Get an initiative's active plan with its steps: what each step changes, the files it writes and reads, " +
-        'its layer and dependencies. Read this before taiga_approve_plan or taiga_reject_plan, and to see what ' +
-        'a run will do. NOT_FOUND when the initiative has no active plan yet (planningStatus says whether one ' +
-        'is being generated).',
-      inputSchema: { itemId },
+        "Get an initiative's active plan with its steps, in order: each step's title, layer, dependencies " +
+        '(the orderIndex of the steps it builds on), the files it writes and reads and the resources it creates. ' +
+        'That is enough to ' +
+        'approve or reject it (taiga_approve_plan, taiga_reject_plan) and to say what a run will do; pass ' +
+        "full: true for each step's complete instructions, several thousand tokens on a large plan. NOT_FOUND " +
+        'when the initiative has no active plan yet (planningStatus says whether one is being generated).',
+      inputSchema: {
+        itemId,
+        full: z.boolean().optional().describe("Carry each step's complete instructions (default false: a summary)"),
+      },
       annotations: READ_ONLY,
     },
     (params) =>
       runTool(async () => {
-        const result = await client.getActivePlan(params.itemId);
-        return toolResult(result.data);
+        const plan = (await client.getActivePlan(params.itemId)).data as Record<string, unknown>;
+        if (params.full) return toolResult(plan);
+        const steps = Array.isArray(plan.steps) ? (plan.steps as Record<string, unknown>[]) : [];
+        return toolResult({
+          ...pickFields([plan], PLAN_SUMMARY_FIELDS)[0],
+          steps: pickFields(steps, PLAN_STEP_SUMMARY_FIELDS),
+        });
       })
   );
 }
@@ -186,7 +210,10 @@ function registerBacklogWrites(server: McpServer, client: TaigaClient) {
         'initiative state machine refuses a move that is not allowed (CONFLICT: build cannot be dropped ' +
         'into, an initiative being planned cannot leave plan). A move into queue or plan starts paid work and ' +
         'needs products:write on the key; a key without it is refused here. Ask the person before a move that ' +
-        `starts work (queue, plan) or closes a pull request (${PR_CLOSING_STATES.join(', ')} from build).`,
+        `starts work (queue, plan) or closes a pull request (${PR_CLOSING_STATES.join(', ')} from build). ` +
+        'archived: true files the initiative where it stands (pass its current column as state; from any column ' +
+        'off the line, never from plan or build) and archived: false brings it back; an archived initiative is left ' +
+        'out of lists unless includeArchived asks for it.',
       inputSchema: {
         itemId,
         state: z.enum(INITIATIVE_TRANSITION_STATES).describe('The column to move into'),
@@ -196,6 +223,10 @@ function registerBacklogWrites(server: McpServer, client: TaigaClient) {
           .nullable()
           .optional()
           .describe('The initiative to follow in that column; null for the head; omit to keep rank order'),
+        archived: z
+          .boolean()
+          .optional()
+          .describe('true files the initiative where it stands, false brings it back; omit to leave as is'),
       },
       annotations: OPERATE,
     },

package/src/tools/markdown.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { fence, renderDocument } from './markdown.js';
+import { fence, nestHeadings, renderDocument } from './markdown.js';
 
 describe('fence', () => {
   it('is one backtick longer than the longest run inside the body, four at least', () => {
@@ -48,6 +48,172 @@ describe('renderDocument', () => {
     );
   });
 
+  it('tracks fences as CommonMark does: indented, longer closers, info strings, and headings indented up to three spaces', () => {
+    const body = [
+      '````',
+      '```',
+      '# inside a four-tick fence: a three-tick line does not close it',
+      '`````',
+      '## after a five-tick closer',
+      '   ```sh',
+      '# indented opener',
+      '   ```',
+      '  ## indented heading',
+      '    # four spaces is code, not a heading',
+      '```',
+      '```sh',
+      '# an opener-with-info inside an open fence is not its closer',
+      '```',
+      '## out again',
+      '```json``` is not a fence opener',
+      '## still a heading',
+      '~~~',
+      '```',
+      '# backticks inside a tilde fence',
+      '~~~',
+      '## last',
+    ].join('\n');
+
+    expect(nestHeadings(body)).toBe(
+      [
+        '````',
+        '```',
+        '# inside a four-tick fence: a three-tick line does not close it',
+        '`````',
+        '### after a five-tick closer',
+        '   ```sh',
+        '# indented opener',
+        '   ```',
+        '  ### indented heading',
+        '    # four spaces is code, not a heading',
+        '```',
+        '```sh',
+        '# an opener-with-info inside an open fence is not its closer',
+        '```',
+        '### out again',
+        '```json``` is not a fence opener',
+        '### still a heading',
+        '~~~',
+        '```',
+        '# backticks inside a tilde fence',
+        '~~~',
+        '### last',
+      ].join('\n')
+    );
+  });
+
+  it("edits by the parser's offsets: CRLF and lone CR line endings, a tab after a container marker, an empty heading, an HTML block, deep nesting", () => {
+    expect(nestHeadings('```\r\n# in\r\n```\r\n# out')).toBe('```\r\n# in\r\n```\r\n### out');
+    expect(nestHeadings('x\ry\n# h\n## i')).toBe('x\ry\n### h\n### i');
+    expect(nestHeadings('>\t# q\n-\t# x')).toBe('>\t### q\n-\t### x');
+    expect(nestHeadings('#\n##\n# x')).toBe('###\n###\n### x');
+    // A heading-shaped line inside an HTML block is HTML to a CommonMark reader, so it stays.
+    expect(nestHeadings('<details>\n<summary>s</summary>\n## inside\n</details>\n\n## after')).toBe(
+      '<details>\n<summary>s</summary>\n## inside\n</details>\n\n### after'
+    );
+    // Deeper than a recursive walk could take: nested quotes, which the
+    // parser handles in milliseconds (nested list markers it does not).
+    const deep = `${'> '.repeat(20_000)}# deep`;
+    expect(nestHeadings(deep)).toBe(`${'> '.repeat(20_000)}### deep`);
+  });
+
+  it('turns a setext heading into the ATX heading one level down, inside a quote too, and leaves a thematic break alone', () => {
+    expect(nestHeadings('> Quoted\n> ---\ntext\n\n---\n\nAfter\n===')).toBe('> ### Quoted\ntext\n\n---\n\n### After');
+    // Serialized from the parsed content: a quote's prefix on a continuation
+    // line, a hard line break, a leading # that is not an ATX marker, a
+    // trailing # run that would read as a closing sequence, inline markup.
+    expect(nestHeadings('> A\n> B\n> ---')).toBe('> ### A B');
+    expect(nestHeadings('> > A\n> > B\n> > ===')).toBe('> > ### A B');
+    expect(nestHeadings('Title\\\ntwo\n---')).toBe('### Title two');
+    expect(nestHeadings('#1 priority\n===')).toBe('### #1 priority');
+    expect(nestHeadings('Title ##\n---')).toBe('### Title #\\#');
+    expect(nestHeadings('*em* and `code` [l](u)\n===')).toBe('### *em* and `code` [l](u)');
+  });
+
+  it('reads containers as CommonMark does: a fence in a list item, headings in list items and quotes, a setext heading', () => {
+    const body = [
+      '- ```md',
+      '  # literal inside a fence that a list item opened',
+      '  ```',
+      '- ## in a list item',
+      '> ## quoted',
+      '>     # indented code inside a quote',
+      'Setext',
+      '======',
+      'Two line',
+      'setext two',
+      '---',
+      '## atx after',
+    ].join('\n');
+
+    expect(nestHeadings(body)).toBe(
+      [
+        '- ```md',
+        '  # literal inside a fence that a list item opened',
+        '  ```',
+        '- ### in a list item',
+        '> ### quoted',
+        '>     # indented code inside a quote',
+        '### Setext',
+        '### Two line setext two',
+        '### atx after',
+      ].join('\n')
+    );
+  });
+
+  it("nests a section body's own headings under the section heading, leaving fenced code alone", () => {
+    const rendered = renderDocument({
+      name: 'Threat Model',
+      type: 'threat_model',
+      data: {
+        sections: {
+          overview: {
+            content: [
+              '# Overview',
+              'Text.',
+              '## Attack vectors',
+              '##### Deep',
+              '###### Deepest stays',
+              '```md',
+              '# not a heading',
+              '```',
+              '~~~',
+              '## nor this',
+              '~~~',
+              '## After the fences',
+              '#hashtag is not a heading',
+            ].join('\n'),
+          },
+        },
+      },
+    });
+
+    expect(rendered.text).toBe(
+      [
+        '# Threat Model',
+        '',
+        'type: threat_model',
+        '',
+        '## overview',
+        '',
+        '### Overview',
+        'Text.',
+        '### Attack vectors',
+        '###### Deep',
+        '###### Deepest stays',
+        '```md',
+        '# not a heading',
+        '```',
+        '~~~',
+        '## nor this',
+        '~~~',
+        '### After the fences',
+        '#hashtag is not a heading',
+        '',
+      ].join('\n')
+    );
+  });
+
   it('carries what sits beside the sections as JSON, so nothing is lost', () => {
     const rendered = renderDocument({
       name: 'Design Standards',

package/src/tools/markdown.ts

@@ -1,3 +1,6 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toMarkdown } from 'mdast-util-to-markdown';
+import type { Heading, Node, Parent, PhrasingContent } from 'mdast';
 import { isRecord, sectionContent, sectionsOf } from './sections.js';
 
 /**
@@ -29,7 +32,7 @@ export function renderDocument(doc: Record<string, unknown>): { mimeType: string
   for (const id of Object.keys(sections)) {
     const content = sectionContent(sections, id);
     if (content === null) continue;
-    lines.push('', `## ${sectionTitle(sections[id], id)}`, '', content.trim());
+    lines.push('', `## ${sectionTitle(sections[id], id)}`, '', nestHeadings(content.trim()));
   }
   const { sections: _sections, ...rest } = data;
   const other = Object.fromEntries(Object.entries(rest).filter(([, value]) => !isEmpty(value)));
@@ -57,6 +60,64 @@ const isEmpty = (value: unknown) =>
   (Array.isArray(value) && value.length === 0) ||
   (isRecord(value) && Object.keys(value).length === 0);
 
+/**
+ * A section body's own headings, one level down, so they sit under the
+ * section heading instead of beside it: a derived document writes each
+ * section with its own H2. A CommonMark parser says what is a heading, so
+ * fenced code, indented code, list items and block quotes are read as a
+ * reader's renderer reads them, and a heading-shaped line inside an HTML
+ * block is HTML, not a heading, and stays. Every heading lands at least one
+ * level under the section's H2, so an H1 and an H2 both become H3 and the
+ * rest move one down, H6 at most: an ATX heading (the # kind, an empty one
+ * included) takes the marks it needs; a setext heading (underlined)
+ * becomes the ATX heading of that depth, serialized from its parsed
+ * content (so a quote's prefix, a hard line break or a trailing # run are
+ * handled as Markdown, not as text). The edits go by the parser's
+ * character offsets, so no line counting of ours can disagree with its own.
+ */
+export function nestHeadings(body: string): string {
+  const edits: { start: number; end: number; text: string }[] = [];
+  // An explicit stack, and no spread into push: a body of thousands of
+  // nested quotes, or a list of very many items, must not overflow a walk.
+  const pending: Node[] = [fromMarkdown(body)];
+  while (pending.length > 0) {
+    const node = pending.pop()!;
+    if (
+      node.type === 'heading' &&
+      node.position?.start.offset !== undefined &&
+      node.position.end.offset !== undefined
+    ) {
+      const start = node.position.start.offset;
+      const end = node.position.end.offset;
+      const heading = node as Heading;
+      const target = nestedDepth(heading.depth);
+      const atx = /^#{1,6}(\s|$)/.test(body.slice(start, start + 7));
+      if (atx && target > heading.depth) edits.push({ start, end: start, text: '#'.repeat(target - heading.depth) });
+      else if (!atx) edits.push({ start, end, text: atxOf(target, heading.children) });
+    }
+    if ('children' in node) for (const child of (node as Parent).children) pending.push(child);
+  }
+  let out = body;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) {
+    out = `${out.slice(0, edit.start)}${edit.text}${out.slice(edit.end)}`;
+  }
+  return out;
+}
+
+/** Under the section's H2: at least H3, one level down otherwise, H6 at most. */
+const nestedDepth = (depth: number): Heading['depth'] => Math.min(6, Math.max(3, depth + 1)) as Heading['depth'];
+
+/** An ATX heading of this depth from parsed content, its line breaks turned into spaces: an ATX heading is one line. */
+function atxOf(depth: Heading['depth'], children: PhrasingContent[]): string {
+  const oneLine = (nodes: PhrasingContent[]): PhrasingContent[] =>
+    nodes.map((child) => {
+      if (child.type === 'break') return { type: 'text', value: ' ' };
+      if (child.type === 'text') return { ...child, value: child.value.replace(/\r\n|\r|\n/g, ' ') };
+      return 'children' in child ? { ...child, children: oneLine(child.children as PhrasingContent[]) } : child;
+    });
+  return toMarkdown({ type: 'heading', depth, children: oneLine(children) }).trimEnd();
+}
+
 /** The section's title when it carries one, else its id. */
 function sectionTitle(section: unknown, id: string): string {
   return isRecord(section) && typeof section.title === 'string' && section.title.trim() ? section.title.trim() : id;