From 2daba71ee42f6aa5c2bd2242357bf4c420c84afb Mon Sep 17 00:00:00 2001 From: harryalbert Date: Thu, 20 Aug 2026 09:33:55 -0400 Subject: [PATCH 1/7] Document single-prompt Factory MCP onboarding Add a copy-pasteable agent prompt that bootstraps Factory MCP installation and hands onboarding to the guidance published by the server. Update the feature summary, onboarding examples, and tool reference for factory creation. Co-Authored-By: Warp --- src/content/docs/factories/factory-mcp.mdx | 33 ++++++++++++++++++---- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 66598499..bac92450 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -1,8 +1,8 @@ --- title: Factory MCP description: >- - Connect any coding agent to your team's factories to send in work, continue - tasks locally, and hand results back. + Connect any coding agent to create and operate your team's factories, send in + work, continue tasks locally, and hand results back. sidebar: label: "Factory MCP" --- @@ -16,7 +16,7 @@ The factory keeps a single record of each task throughout. Whether a change happ * **Send work in** - Turn anything from your local session into a factory task: a bug you found, review feedback, or a half-finished change. * **Continue a task locally** - Pull a task's context into your own checkout, work with your own tools, and return the result to the same task. * **Stay in sync** - List and search tasks, read a task's conversation, and message its [foreman](/factories/factory-agents/), the agent that orchestrates each task inside the factory. -* **Create a factory** - Set up a new factory when you know the team, repositories, and source-control details. +* **Create a factory** - Let your coding agent guide you through choosing a team, code forge, repositories, factory agents, and integrations. Factory MCP is one of several ways work enters a factory, alongside Slack, GitHub, GitLab, Linear, and Jira. See [connect your factory](/factories/connect-your-factory/) for all intake paths and [how Warp Factories work](/factories/how-factories-work/) for how tasks move through a factory. @@ -26,6 +26,24 @@ Factory MCP is one of several ways work enters a factory, alongside Slack, GitHu There is nothing to configure. When your account has access, Warp connects agent sessions to Factory MCP and handles authentication for you. +### Set up with your coding agent + +Paste this prompt into a coding agent that can run commands and configure MCP servers: + +```text +Set up a Warp Factory for me. Read https://docs.warp.dev/factories/factory-mcp.md, follow the setup instructions for your coding environment to connect to and authenticate with Factory MCP, then use Factory MCP to onboard me. +``` + +Your agent will: + +1. Check whether Factory MCP is already available. +2. Add `https://app.warp.dev/api/v1/mcp/factory` using its own MCP configuration mechanism. +3. Open the browser-based Warp authorization flow. +4. Verify the Factory MCP tools are available. +5. Use the onboarding guidance published by Factory MCP to help you select a team, repositories, factory agents, and optional integrations before creating the factory. + +Some MCP clients load newly added servers only when a new session starts. If a reload is required, the agent will tell you how to resume onboarding after the server becomes available. + ### In other MCP clients Factory MCP is a streamable HTTP server at `https://app.warp.dev/api/v1/mcp/factory`. Point any MCP client that supports remote servers at that URL; on first connect, the client opens a browser so you can sign in and approve access. @@ -76,8 +94,9 @@ Factory MCP exposes a small set of tools that your agent calls on your behalf. Y * "Send this bug to the factory, including my branch." * "What's the status of the checkout-flow task?" * "Pull down ENG-123 so we can finish it here." +* "Set up a Warp Factory for me." -The rest of this page describes what happens behind those prompts. +For factory creation, the server-provided onboarding guidance walks the agent through team selection, code-forge authorization, repositories, agent roles, optional integrations, creation, and verification. The rest of this page describes what happens behind these prompts. ## Send new work to a factory @@ -112,7 +131,11 @@ Your MCP client fetches the full input schemas from the server, and tool results | Tool | What it does | | --- | --- | | `list_factories` | Lists the factories you can access. | -| `create_factory` | Creates a factory for a team, with its repositories and source-control details. | +| `list_teams` | Lists the teams that can own a new factory. | +| `list_forge_repositories` | Lists repositories available through a team's connected GitHub or GitLab account. | +| `start_connection` | Starts or checks setup for GitHub, GitLab, Slack, Linear, or Jira. | +| `get_connection_status` | Checks whether a browser authorization flow completed. | +| `create_factory` | Creates a factory with the selected repositories, integrations, and optional factory agents. | | `list_tasks` | Lists the tasks in one factory, with filters such as creator, stage, and date. | | `search_task` | Searches task titles across all factories you can access. | | `get_task` | Reads a task's status, run history, and outputs. Accepts a task ID or a reference such as a URL, issue, pull request, or branch. With `start_working=true`, also returns local setup guidance. | From 50387abd68f23bde88fdd3a647b09a9952ccbef5 Mon Sep 17 00:00:00 2001 From: harryalbert Date: Thu, 20 Aug 2026 11:25:55 -0400 Subject: [PATCH 2/7] Document coding-agent MCP setup lifecycles Co-Authored-By: Warp --- src/content/docs/factories/factory-mcp.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index bac92450..a6583aeb 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -37,12 +37,18 @@ Set up a Warp Factory for me. Read https://docs.warp.dev/factories/factory-mcp.m Your agent will: 1. Check whether Factory MCP is already available. -2. Add `https://app.warp.dev/api/v1/mcp/factory` using its own MCP configuration mechanism. +2. If it is not available, identify the coding environment and add `https://app.warp.dev/api/v1/mcp/factory` using that client's current MCP configuration mechanism. 3. Open the browser-based Warp authorization flow. 4. Verify the Factory MCP tools are available. 5. Use the onboarding guidance published by Factory MCP to help you select a team, repositories, factory agents, and optional integrations before creating the factory. -Some MCP clients load newly added servers only when a new session starts. If a reload is required, the agent will tell you how to resume onboarding after the server becomes available. +#### Guidance for coding agents +Before configuring anything, the agent should identify its coding environment and use that client's current MCP management mechanism. If it is unsure how the client manages MCP servers, it should check the client's help or official documentation rather than guess. + +* **Warp:** Factory MCP is built in. Use the existing connection instead of adding another server. +* **Claude Code:** A server added after the session starts is not available to that running session. After adding Factory MCP, tell the user to exit and resume the same conversation from the same directory with `claude --continue`. Once resumed, complete authentication through the client's MCP controls if needed, then continue onboarding without asking the user to restate their goal. +* **Codex:** Add Factory MCP as a remote HTTP server, use Codex's built-in OAuth flow, and confirm the server is active through its MCP controls before onboarding. Only ask the user to restart or resume if the configured server is not available to the current session. +* **Other MCP clients:** Add the remote server using the client's supported configuration and authentication flow. If the client cannot load a newly added server into the current session, explain how to restart or resume while preserving the onboarding context when possible. ### In other MCP clients From 5bbeedff1817e62abd3a05e497c4966a91b29ea9 Mon Sep 17 00:00:00 2001 From: harryalbert Date: Thu, 20 Aug 2026 14:04:49 -0400 Subject: [PATCH 3/7] Make Claude MCP scope explicit Co-Authored-By: Warp --- src/content/docs/factories/factory-mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index a6583aeb..bdefee45 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -57,7 +57,7 @@ Factory MCP is a streamable HTTP server at `https://app.warp.dev/api/v1/mcp/fact With Claude Code: ```bash -claude mcp add --transport http warp-factory https://app.warp.dev/api/v1/mcp/factory +claude mcp add --transport http --scope local warp-factory https://app.warp.dev/api/v1/mcp/factory ``` In clients that use the `mcpServers` JSON format, such as Cursor: From 784951fcb902867ca880436d9444c75385cd835c Mon Sep 17 00:00:00 2001 From: harryalbert Date: Fri, 21 Aug 2026 10:21:54 -0400 Subject: [PATCH 4/7] Document zero-account Factory MCP onboarding Co-Authored-By: Warp --- src/content/docs/factories/factory-mcp.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index bdefee45..d4ac014c 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -38,15 +38,15 @@ Your agent will: 1. Check whether Factory MCP is already available. 2. If it is not available, identify the coding environment and add `https://app.warp.dev/api/v1/mcp/factory` using that client's current MCP configuration mechanism. -3. Open the browser-based Warp authorization flow. +3. Open the browser-based Warp authorization flow, where you can log in or create a Warp account. 4. Verify the Factory MCP tools are available. -5. Use the onboarding guidance published by Factory MCP to help you select a team, repositories, factory agents, and optional integrations before creating the factory. +5. Use the onboarding guidance published by Factory MCP to create or join your first team conversationally, complete browser-based Stripe funding if required, and select repositories, factory agents, and optional integrations before creating the factory. #### Guidance for coding agents Before configuring anything, the agent should identify its coding environment and use that client's current MCP management mechanism. If it is unsure how the client manages MCP servers, it should check the client's help or official documentation rather than guess. * **Warp:** Factory MCP is built in. Use the existing connection instead of adding another server. -* **Claude Code:** A server added after the session starts is not available to that running session. After adding Factory MCP, tell the user to exit and resume the same conversation from the same directory with `claude --continue`. Once resumed, complete authentication through the client's MCP controls if needed, then continue onboarding without asking the user to restate their goal. +* **Claude Code:** A server added after the session starts is not available to that running session. After adding Factory MCP, tell the user to exit and resume the same conversation from the same directory with `claude --continue`. Once resumed, complete authentication through the client's MCP controls if needed; a user without a Warp account can create one in that browser flow. Then continue onboarding without asking the user to restate their goal. * **Codex:** Add Factory MCP as a remote HTTP server, use Codex's built-in OAuth flow, and confirm the server is active through its MCP controls before onboarding. Only ask the user to restart or resume if the configured server is not available to the current session. * **Other MCP clients:** Add the remote server using the client's supported configuration and authentication flow. If the client cannot load a newly added server into the current session, explain how to restart or resume while preserving the onboarding context when possible. @@ -102,7 +102,7 @@ Factory MCP exposes a small set of tools that your agent calls on your behalf. Y * "Pull down ENG-123 so we can finish it here." * "Set up a Warp Factory for me." -For factory creation, the server-provided onboarding guidance walks the agent through team selection, code-forge authorization, repositories, agent roles, optional integrations, creation, and verification. The rest of this page describes what happens behind these prompts. +For factory creation, the server-provided onboarding guidance handles a user starting without a Warp account or team: browser signup returns to MCP authorization, the agent offers discoverable teams or asks what to call a new one, and any required Stripe checkout is verified before code-forge authorization, repositories, agent roles, optional integrations, creation, and connection testing. The rest of this page describes what happens behind these prompts. ## Send new work to a factory @@ -137,7 +137,10 @@ Your MCP client fetches the full input schemas from the server, and tool results | Tool | What it does | | --- | --- | | `list_factories` | Lists the factories you can access. | -| `list_teams` | Lists the teams that can own a new factory. | +| `list_teams` | Lists current memberships and first-time joinable team choices. | +| `create_team` | Creates the authenticated user's first team with a confirmed name. | +| `join_team` | Joins a team selected from the first-time discovery choices. | +| `get_team_funding_status` | Checks first-team credit readiness and returns the browser checkout step when required. | | `list_forge_repositories` | Lists repositories available through a team's connected GitHub or GitLab account. | | `start_connection` | Starts or checks setup for GitHub, GitLab, Slack, Linear, or Jira. | | `get_connection_status` | Checks whether a browser authorization flow completed. | From 7b7eedf4963702f527384315bf173fbb23741b1d Mon Sep 17 00:00:00 2001 From: harryalbert Date: Fri, 21 Aug 2026 11:43:15 -0400 Subject: [PATCH 5/7] Clarify browser checkout in Factory onboarding Co-Authored-By: Warp --- src/content/docs/factories/factory-mcp.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index d4ac014c..2a5f50d9 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -102,7 +102,7 @@ Factory MCP exposes a small set of tools that your agent calls on your behalf. Y * "Pull down ENG-123 so we can finish it here." * "Set up a Warp Factory for me." -For factory creation, the server-provided onboarding guidance handles a user starting without a Warp account or team: browser signup returns to MCP authorization, the agent offers discoverable teams or asks what to call a new one, and any required Stripe checkout is verified before code-forge authorization, repositories, agent roles, optional integrations, creation, and connection testing. The rest of this page describes what happens behind these prompts. +For factory creation, the server-provided onboarding guidance handles a user starting without a Warp account or team: browser signup returns to MCP authorization, the agent offers discoverable teams or asks what to call a new one, and any required Stripe checkout is completed before code-forge authorization, repositories, agent roles, optional integrations, creation, and connection testing. The rest of this page describes what happens behind these prompts. ## Send new work to a factory From 89a7d80f24f5268218f5adbf1c3e1d4b7434169b Mon Sep 17 00:00:00 2001 From: harryalbert Date: Fri, 21 Aug 2026 13:51:44 -0400 Subject: [PATCH 6/7] update list of tools --- src/content/docs/factories/factory-mcp.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 2a5f50d9..85642186 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -74,7 +74,7 @@ In clients that use the `mcpServers` JSON format, such as Cursor: For Codex and other clients, follow the [client's own remote-server instructions](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server) with the same URL. -For unattended automation, skip the browser flow and authenticate with a [Warp API key](/reference/cli/api-keys/) instead. Create the key for a least-privilege cloud agent rather than your personal account, and pass it as a bearer token: +For unattended operation of an existing factory, skip the browser flow and authenticate with a [Team API key](/reference/cli/api-keys/). Pass it as a bearer token: ```json { @@ -89,6 +89,8 @@ For unattended automation, skip the browser flow and authenticate with a [Warp A } ``` +Team API keys cannot use the onboarding tools that select or create a team, check first-team funding, discover repositories, or connect providers. Use browser sign-in or a Personal API key for those setup steps. + :::caution Factory MCP has no read-only or per-factory scopes: a connected client acts with the full permissions of the account or agent it authenticates as. Store API keys in your client's secret storage, never in a repository. ::: @@ -133,10 +135,13 @@ Sending work to a factory means you're no longer watching it. To be notified whe ## Tool reference Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the factory's [factory dashboard](/factories/factory-dashboard/). +The onboarding tools from `list_teams` through `get_connection_status` require browser sign-in or a Personal API key. Team API keys are for operating an existing factory and cannot use these setup tools. | Tool | What it does | | --- | --- | | `list_factories` | Lists the factories you can access. | +| `get_factory_file_schema` | Returns the current schemas for Factory configuration files. | +| `validate_factory_files` | Validates a complete Factory file tree without saving or applying it. | | `list_teams` | Lists current memberships and first-time joinable team choices. | | `create_team` | Creates the authenticated user's first team with a confirmed name. | | `join_team` | Joins a team selected from the first-time discovery choices. | From 56f677dccc46e73467e5100451824a7896738f90 Mon Sep 17 00:00:00 2001 From: harryalbert Date: Fri, 21 Aug 2026 15:26:56 -0400 Subject: [PATCH 7/7] address comments --- src/components/AgentOnly.astro | 11 ++++++ src/content/docs/factories/factory-mcp.mdx | 37 ++++++++++--------- src/integrations/docs-markdown-integration.js | 9 +++++ .../docs-markdown-integration.test.js | 31 ++++++++++++++++ 4 files changed, 70 insertions(+), 18 deletions(-) create mode 100644 src/components/AgentOnly.astro create mode 100644 src/integrations/docs-markdown-integration.test.js diff --git a/src/components/AgentOnly.astro b/src/components/AgentOnly.astro new file mode 100644 index 00000000..3aec7aed --- /dev/null +++ b/src/components/AgentOnly.astro @@ -0,0 +1,11 @@ +--- +/** + * Content for agent-readable Markdown that should not render in the docs UI. + * This is a presentation boundary, not an access-control boundary: the inert + * template remains visible in the page's HTML source. + */ +--- + + diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 85642186..91880dca 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -6,6 +6,7 @@ description: >- sidebar: label: "Factory MCP" --- +import AgentOnly from '@components/AgentOnly.astro'; Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories, in both directions: the agent you already work with — in Warp or in any MCP-capable tool — can send work to a factory, or take work over from one by pulling a task down, continuing it locally, and handing the result back. @@ -31,25 +32,29 @@ There is nothing to configure. When your account has access, Warp connects agent Paste this prompt into a coding agent that can run commands and configure MCP servers: ```text -Set up a Warp Factory for me. Read https://docs.warp.dev/factories/factory-mcp.md, follow the setup instructions for your coding environment to connect to and authenticate with Factory MCP, then use Factory MCP to onboard me. +Set up a factory for me. Read https://docs.warp.dev/factories/factory-mcp.md, follow the setup instructions for your coding environment to connect to and authenticate with Factory MCP, then use Factory MCP to onboard me. ``` + -Your agent will: +## Coding-agent setup guidance + +After the user pastes the prompt: 1. Check whether Factory MCP is already available. 2. If it is not available, identify the coding environment and add `https://app.warp.dev/api/v1/mcp/factory` using that client's current MCP configuration mechanism. -3. Open the browser-based Warp authorization flow, where you can log in or create a Warp account. -4. Verify the Factory MCP tools are available. -5. Use the onboarding guidance published by Factory MCP to create or join your first team conversationally, complete browser-based Stripe funding if required, and select repositories, factory agents, and optional integrations before creating the factory. +3. Open the browser-based Warp authorization flow, where the user can log in or create a Warp account. +4. Verify that the Factory MCP tools are available. +5. Guide the user through the choices needed to create their factory. -#### Guidance for coding agents -Before configuring anything, the agent should identify its coding environment and use that client's current MCP management mechanism. If it is unsure how the client manages MCP servers, it should check the client's help or official documentation rather than guess. +Before configuring anything, identify the coding environment and use that client's current MCP management mechanism. If you are unsure how the client manages MCP servers, check its help or official documentation rather than guessing. * **Warp:** Factory MCP is built in. Use the existing connection instead of adding another server. -* **Claude Code:** A server added after the session starts is not available to that running session. After adding Factory MCP, tell the user to exit and resume the same conversation from the same directory with `claude --continue`. Once resumed, complete authentication through the client's MCP controls if needed; a user without a Warp account can create one in that browser flow. Then continue onboarding without asking the user to restate their goal. -* **Codex:** Add Factory MCP as a remote HTTP server, use Codex's built-in OAuth flow, and confirm the server is active through its MCP controls before onboarding. Only ask the user to restart or resume if the configured server is not available to the current session. +* **Claude Code:** A server added after the session starts is not available to that running session. After adding Factory MCP, tell the user to exit and resume the same conversation from the same directory with `claude --continue`. Once resumed, complete authentication through the client's MCP controls if needed, then continue without asking the user to restate their goal. +* **Codex:** Add Factory MCP as a remote HTTP server, use Codex's built-in OAuth flow, and confirm the server is active through its MCP controls before onboarding. Ask the user to restart or resume only if the configured server is unavailable to the current session. * **Other MCP clients:** Add the remote server using the client's supported configuration and authentication flow. If the client cannot load a newly added server into the current session, explain how to restart or resume while preserving the onboarding context when possible. + + ### In other MCP clients Factory MCP is a streamable HTTP server at `https://app.warp.dev/api/v1/mcp/factory`. Point any MCP client that supports remote servers at that URL; on first connect, the client opens a browser so you can sign in and approve access. @@ -74,7 +79,7 @@ In clients that use the `mcpServers` JSON format, such as Cursor: For Codex and other clients, follow the [client's own remote-server instructions](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server) with the same URL. -For unattended operation of an existing factory, skip the browser flow and authenticate with a [Team API key](/reference/cli/api-keys/). Pass it as a bearer token: +Automation that runs without a person present, such as a CI pipeline or a headless server, can't complete the browser sign-in. For those cases, authenticate with an [agent API key](/reference/cli/api-keys/) instead, passed as a bearer token: ```json { @@ -89,8 +94,6 @@ For unattended operation of an existing factory, skip the browser flow and authe } ``` -Team API keys cannot use the onboarding tools that select or create a team, check first-team funding, discover repositories, or connect providers. Use browser sign-in or a Personal API key for those setup steps. - :::caution Factory MCP has no read-only or per-factory scopes: a connected client acts with the full permissions of the account or agent it authenticates as. Store API keys in your client's secret storage, never in a repository. ::: @@ -102,9 +105,7 @@ Factory MCP exposes a small set of tools that your agent calls on your behalf. Y * "Send this bug to the factory, including my branch." * "What's the status of the checkout-flow task?" * "Pull down ENG-123 so we can finish it here." -* "Set up a Warp Factory for me." - -For factory creation, the server-provided onboarding guidance handles a user starting without a Warp account or team: browser signup returns to MCP authorization, the agent offers discoverable teams or asks what to call a new one, and any required Stripe checkout is completed before code-forge authorization, repositories, agent roles, optional integrations, creation, and connection testing. The rest of this page describes what happens behind these prompts. +* "Set up a factory for me." ## Send new work to a factory @@ -135,13 +136,13 @@ Sending work to a factory means you're no longer watching it. To be notified whe ## Tool reference Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the factory's [factory dashboard](/factories/factory-dashboard/). -The onboarding tools from `list_teams` through `get_connection_status` require browser sign-in or a Personal API key. Team API keys are for operating an existing factory and cannot use these setup tools. +The onboarding tools from `list_teams` through `get_connection_status` require browser sign-in or a personal API key. Agent API keys are for operating an existing factory and cannot use these setup tools. | Tool | What it does | | --- | --- | | `list_factories` | Lists the factories you can access. | -| `get_factory_file_schema` | Returns the current schemas for Factory configuration files. | -| `validate_factory_files` | Validates a complete Factory file tree without saving or applying it. | +| `get_factory_file_schema` | Returns the current schemas for factory configuration files. | +| `validate_factory_files` | Validates a complete factory file tree without saving or applying it. | | `list_teams` | Lists current memberships and first-time joinable team choices. | | `create_team` | Creates the authenticated user's first team with a confirmed name. | | `join_team` | Joins a team selected from the first-time discovery choices. | diff --git a/src/integrations/docs-markdown-integration.js b/src/integrations/docs-markdown-integration.js index 76c43d7e..6963f108 100644 --- a/src/integrations/docs-markdown-integration.js +++ b/src/integrations/docs-markdown-integration.js @@ -18,6 +18,8 @@ export default function docsMarkdownIntegration() { }; } +export { convertHtmlToMarkdown }; + const turndown = createMarkdownConverter(); async function generateMarkdownFiles(outputRoot) { @@ -86,6 +88,7 @@ function convertHtmlToMarkdown(html) { if (!title || !contentRoot) return ''; const clone = /** @type {HTMLElement} */ (contentRoot.cloneNode(true)); + expandAgentOnlyTemplates(clone); sanitizeRoot(clone); const markdownBody = turndown.turndown(clone.innerHTML).trim(); const llmsDirective = @@ -104,6 +107,12 @@ function convertHtmlToMarkdown(html) { return `${sections.join('\n\n').trim()}\n`; } +function expandAgentOnlyTemplates(root) { + for (const template of root.querySelectorAll('template[data-agent-only]')) { + const content = /** @type {HTMLTemplateElement} */ (template).content; + template.replaceWith(content.cloneNode(true)); + } +} function sanitizeRoot(root) { for (const selector of [ 'script', diff --git a/src/integrations/docs-markdown-integration.test.js b/src/integrations/docs-markdown-integration.test.js new file mode 100644 index 00000000..551a3ffa --- /dev/null +++ b/src/integrations/docs-markdown-integration.test.js @@ -0,0 +1,31 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { convertHtmlToMarkdown } from './docs-markdown-integration.js'; + +test('includes inert agent-only templates in generated Markdown', () => { + const html = ` + + + +
+

Test page

+
+

Visible guidance.

+ +

Search-only chrome.

+
+
+ + + `; + + const markdown = convertHtmlToMarkdown(html); + + assert.match(markdown, /Visible guidance\./); + assert.match(markdown, /## Agent setup/); + assert.match(markdown, /Restart the coding agent after installing MCP\./); + assert.doesNotMatch(markdown, /Search-only chrome\./); +});