From 6e6f076ef9609fa4f0e8df23a09c81ae582bb551 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 31 Oct 2026 10:12:11 -0700 Subject: [PATCH 1/2] Add mint agent setup to agent-only setup instructions Surface `mint agent setup` in the site-wide markdown instructions and as an optional step in the agent setup workflow snippet. Agents are told to offer the command and to pass --agent, because without a TTY it configures every detected agent. DOC-456 Co-Authored-By: Claude Opus 5.5 --- docs.json | 1 + snippets/agent-setup-workflow.mdx | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs.json b/docs.json index 2c6a8c609..66a765cf4 100644 --- a/docs.json +++ b/docs.json @@ -22,6 +22,7 @@ "instructions": [ "When working in a Mintlify project, run `mint instructions` for current step-by-step instructions for common tasks. If the command is unknown, run `npx mint@latest instructions`.", "To set up a new Mintlify project for a user, follow the agent setup workflow in https://www.mintlify.com/docs/quickstart.md.", + "To connect a coding agent to a Mintlify project, offer to run `mint agent setup --agent ` in the project directory. It installs Mintlify skills and adds the admin MCP server to the agent's configuration, then the user completes OAuth sign-in. See https://www.mintlify.com/docs/cli/commands.md#mint-agent-setup.", "For plans and pricing, see https://www.mintlify.com/pricing.md." ] }, diff --git a/snippets/agent-setup-workflow.mdx b/snippets/agent-setup-workflow.mdx index f74b8265c..fc95f3e34 100644 --- a/snippets/agent-setup-workflow.mdx +++ b/snippets/agent-setup-workflow.mdx @@ -5,15 +5,16 @@ If the user asks you to set up Mintlify, a documentation site, or a local Mintli 1. Run `node --version` and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release. 2. Run `mint --version`. If the command is unavailable, install the CLI with `npm i -g mint` or `pnpm add -g mint`. If the command succeeds, run `mint update`. Then run `mint instructions new-site` for current setup guidance, and `mint instructions` to list topics for later tasks. 3. Run `mint status` before starting authentication. If it already shows an organization, keep the existing session and do not create another account. -4. Run `mint login` if the user has an account. Otherwise, don't create an account now. You can publish without one using `mint deploy` in step 9, and the user creates their account when they claim the site. Don't run `mint signup` for the user: when an agent runs it, it prints the [agent signup guide](https://mintlify.com/auth.md) and exits without sending a verification email. If the user wants their own GitHub repository connected from the start, send them to web onboarding at [mintlify.com/start](https://mintlify.com/start). +4. Run `mint login` if the user has an account. Otherwise, don't create an account now. You can publish without one using `mint deploy` in step 10, and the user creates their account when they claim the site. Don't run `mint signup` for the user: when an agent runs it, it prints the [agent signup guide](https://mintlify.com/auth.md) and exits without sending a verification email. If the user wants their own GitHub repository connected from the start, send them to web onboarding at [mintlify.com/start](https://mintlify.com/start). 5. After `mint login`, run `mint status` again. Confirm that it reports their email, organization, and subdomain. If the organization exists but no subdomain appears, ask the user to finish selecting or connecting a GitHub repository in the onboarding browser tab, then retry. 6. If the user has an existing documentation repository, clone or open it. Preserve its content. For a new local project, scaffold into a new, empty directory with either `mint new --name --theme ` or `mint new --template `. Ask which theme or template they want if they have not specified one. Do not use `--force` on a directory containing user files. 7. Run `mint dev --no-open` from the directory containing `docs.json` as a background process. Confirm the local URL loads, report it to the user, and stop the process when it is no longer needed. 8. Run `mint validate` and `mint broken-links`. Fix issues caused by your changes before continuing. -9. Publish when the user asks for a live site. +9. Offer to connect the user's coding agent to the project. If they agree and Node.js is v22.20 or newer, run `mint agent setup --agent ` from the project directory, where `` is `claude-code`, `codex`, or `cursor`. It installs Mintlify skills and adds the [admin MCP](/ai/mintlify-mcp) to the agent's project configuration. Pass `--agent` because without an interactive terminal the command configures every agent it detects. The user completes OAuth sign-in in the agent afterward. See [`mint agent setup`](/cli/commands#mint-agent-setup). +10. Publish when the user asks for a live site. - **Logged in with a Git repository:** commit and push the changes. A push to the production branch triggers a deployment. Do not overwrite an existing repository with starter content. - **No account:** from the directory containing `docs.json`, run `mint deploy --subdomain `, choosing a short name based on the project. Follow the steps it prints: clone the hosted repository into a separate directory, copy the docs into its root, commit, and push to `main` with the write token as an `Authorization: Bearer` header for that Git command only. Never show the token to the user, put it in a remote URL, or change the user's own Git remotes. See [Agent signup](/cli/agent-signup). -10. Verify that `https://.mintlify.site` loads before reporting that deployment is complete. If you logged in, run `mint status` to get the subdomain. If you used `mint deploy`, use the URL it printed, then hand the site to the user: +11. Verify that `https://.mintlify.site` loads before reporting that deployment is complete. If you logged in, run `mint status` to get the subdomain. If you used `mint deploy`, use the URL it printed, then hand the site to the user: - Tell them the site expires unless they claim it. - Ask for the email address that should own it. Never invent one. - Run `mint claim --email ` from the same directory and share the claim link. From ed902cba49c0c7e38b2b2a213dd0ff2c1fbabb27 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sat, 31 Oct 2026 10:22:27 -0700 Subject: [PATCH 2/2] Clarify Node.js requirement and post-deploy steps in agent workflow Flag the v22.20 requirement for step 9 up front in step 1, and split step 11 by publish path so logged-in users aren't sent through the claim flow. Both found by testing quickstart.md with Claude Code. DOC-456 Co-Authored-By: Claude Opus 5.5 --- snippets/agent-setup-workflow.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/snippets/agent-setup-workflow.mdx b/snippets/agent-setup-workflow.mdx index fc95f3e34..b8bca923a 100644 --- a/snippets/agent-setup-workflow.mdx +++ b/snippets/agent-setup-workflow.mdx @@ -2,7 +2,7 @@ If the user asks you to set up Mintlify, a documentation site, or a local Mintlify project, complete the following workflow yourself. Ask the user only for information or approvals you cannot supply. We recommend CLI onboarding. Web onboarding at [mintlify.com/start](https://mintlify.com/start) is also available if the user prefers it or you cannot run terminal commands. -1. Run `node --version` and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release. +1. Run `node --version` and confirm it reports Node.js v20.17.0 or newer, preferring an LTS release. Note whether it is v22.20 or newer, which step 9 requires. 2. Run `mint --version`. If the command is unavailable, install the CLI with `npm i -g mint` or `pnpm add -g mint`. If the command succeeds, run `mint update`. Then run `mint instructions new-site` for current setup guidance, and `mint instructions` to list topics for later tasks. 3. Run `mint status` before starting authentication. If it already shows an organization, keep the existing session and do not create another account. 4. Run `mint login` if the user has an account. Otherwise, don't create an account now. You can publish without one using `mint deploy` in step 10, and the user creates their account when they claim the site. Don't run `mint signup` for the user: when an agent runs it, it prints the [agent signup guide](https://mintlify.com/auth.md) and exits without sending a verification email. If the user wants their own GitHub repository connected from the start, send them to web onboarding at [mintlify.com/start](https://mintlify.com/start). @@ -14,11 +14,9 @@ If the user asks you to set up Mintlify, a documentation site, or a local Mintli 10. Publish when the user asks for a live site. - **Logged in with a Git repository:** commit and push the changes. A push to the production branch triggers a deployment. Do not overwrite an existing repository with starter content. - **No account:** from the directory containing `docs.json`, run `mint deploy --subdomain `, choosing a short name based on the project. Follow the steps it prints: clone the hosted repository into a separate directory, copy the docs into its root, commit, and push to `main` with the write token as an `Authorization: Bearer` header for that Git command only. Never show the token to the user, put it in a remote URL, or change the user's own Git remotes. See [Agent signup](/cli/agent-signup). -11. Verify that `https://.mintlify.site` loads before reporting that deployment is complete. If you logged in, run `mint status` to get the subdomain. If you used `mint deploy`, use the URL it printed, then hand the site to the user: - - Tell them the site expires unless they claim it. - - Ask for the email address that should own it. Never invent one. - - Run `mint claim --email ` from the same directory and share the claim link. - - When they return the code shown after they sign in, run `mint claim --code `. +11. Verify that `https://.mintlify.site` loads before reporting that deployment is complete. + - **Logged in with a Git repository:** run `mint status` to get the subdomain. Skip the claim steps. + - **No account:** use the URL that `mint deploy` printed, then hand the site to the user. Tell them the site expires unless they claim it. Ask for the email address that should own it, and never invent one. Run `mint claim --email ` from the same directory and share the claim link. When they return the code shown after they sign in, run `mint claim --code `. Have the user complete browser actions only for claiming a site, OAuth approval, and connecting or authorizing GitHub. Keep ownership of the terminal workflow and resume after each user action. For command flags and troubleshooting, use the [CLI command reference](/cli/commands).