docs: explain which links mint broken-links checks

agent-context/context/skills/mintlify/SKILL.md

@@ -27,7 +27,7 @@ Read these files **only when your task requires them**. They are in the `referen
 
 ## Starting a new docs site
 
-If the user wants a new docs site, wants to publish docs, or has no `docs.json` yet, run this workflow yourself. Ask the user only for information or approvals you cannot supply. Do not send them to a browser-first quickstart when you can run terminal commands.
+If the user wants a new docs site, wants to publish docs, or has no `docs.json` yet, run this workflow yourself. Ask the user only for information or approvals you cannot supply. Recommend CLI onboarding. If the user prefers to onboard in the browser, or you cannot run terminal commands, send them to [mintlify.com/start](https://mintlify.com/start).
 
 1. Check `node --version` (v20.17.0 or newer). Run `mint --version`; if missing, install with `npm i -g mint`. If it's installed, run `mint update`.
 2. Run `mint status`. If it shows an organization, use the existing account. Otherwise, ask whether the user has a Mintlify account. If they do, run `mint login`. If not, ask for first name, last name, company, and email and run `mint signup --firstName <first> --lastName <last> --company <company> --email <email>` as a background process. It waits for email verification. Tell the user to click the verification link and finish onboarding in the browser. Never invent signup details.
@@ -73,18 +73,20 @@ Write access to a Mintlify project. Requires OAuth on first use. Complete authen
 
 Use this server when the user wants to edit their Mintlify content, restructure navigation, or open a pull request. Every content tool takes a `branch` argument: required on edits, `publish`, `discard` and comment writes, optional on reads (defaults to the deploy branch). Nothing is remembered between calls, so pass `branch` every time. Edits on the deploy branch land as unpublished changes until you call `publish`. Edits on any other branch go through a pull request. Project management tool changes apply immediately to the live project without a branch or pull request.
 
-Workflow: use `read`/`search`/`edit_page`/`write_page`/`list_nodes`/`create_node`/`update_node`/`move_node`/`delete_node`/`update_config` with a `branch` to make changes, then call `publish` with the `branch` and a `title` to publish (or `discard` to abandon). Pass the deploy branch to edit it directly. If the project requires a pull request (**Push directly to your deploy branch** is off, branch protection requires pull requests, deploy branch editing is locked, or the connection uses a client or machine-to-machine token), edits to the deploy branch are refused with the reason and change nothing. Call `create_branch` and pass its `branchName` as `branch` instead.
+Workflow: use `read`/`search`/`edit_page`/`write_page`/`list_nodes`/`create_node`/`update_node`/`move_node`/`delete_node`/`update_config` with a `branch` to make changes, then call `publish` with the `branch` and a `title` to publish (or `discard` to abandon). Pass the deploy branch to edit it directly. If the project requires a pull request (**Push directly to your deploy branch** is off, branch protection requires pull requests, deploy branch editing is locked, or the connection uses a client or machine-to-machine token), edits to the deploy branch are refused with the reason and change nothing. Call `create_branch` and pass its `branchName` as `branch` instead. Projects with auto publish turned on have no branches: pass the deploy branch, where edits are committed automatically. `create_branch` and other branches are refused there, and pull request requirements don't apply.
 
 Key tools:
 - **`create_branch`** — Start a new branch off the deploy branch with a `title` that also names its pull request. Returns `branchName` and a branch-level `editorUrl` to preview changes live. On a branch, Mintlify commits edits automatically about 15 seconds after the last change, and the first commit opens a pull request.
 - **`list_branches`** — List existing branches; pass any of them as `branch`. Branches that don't exist are refused.
 - **`list_deployments`** — Discover which project(s) this connection can access.
-- **`read`** / **`search`** — Fetch a page's MDX or search across pages.
+- **`read`** / **`search`**: Fetch a page's MDX or search across pages. `read`, `edit_page` and `write_page` take a page path (such as `guides/setup`) or the last segment of an editor URL, which is the page ID with an optional title in front of it. With a page ID from an editor URL, pass that URL's branch as `branch`. `read` returns a `filePath` to pass as `path` to `edit_page` and `write_page`.
 - **`edit_page`** / **`write_page`**: Apply targeted edits or overwrite a page. `edit_page` takes `oldString` and `newString` for one replacement, or an `edits` list of up to 100 replacements applied in order; if any edit fails, none apply. Both return `notRendered` for markup the editor drops (such as `<script>`, `<style>`, event handlers or JavaScript expressions), with what to use `instead`.
+- **`read_page_history`**: List a page's saved versions on `branch` (newest first, paginate with `cursor`), or pass `versionId` to read that version's MDX. Read-only; to restore a version, pass its `content` to `write_page`.
 - **`read_comments`** / **`add_comment`** / **`suggest_edit`** / **`reply_to_comment`** / **`resolve_comment`**: Read open editor comment threads on a page, start a thread on exact text, propose a tracked-changes suggestion (`oldString` to `newString`; an empty `newString` suggests a deletion; an optional `comment` explains why and is posted as the agent's reply in the suggestion thread) that someone accepts or rejects in the editor, reply as the agent, or resolve threads. Adding, suggesting, replying and resolving require an OAuth session and act on the threads of `branch`; they work on the deploy branch even when edits to it require a pull request.
+- **`read_inbox`**: List the connected user's dashboard inbox on a project (comments and mentions, suggested edits, organization invitations), newest activity first and open items by default. Narrow with `state`, `section`, `filter`, `dateFrom` and `dateTo`; pass `nextCursor` as `cursor` for older items. For an item whose `target.thread` is unresolved and not on a private page, call `read_comments` on `target.thread.filePath` and `reply_to_comment`, both on `target.thread.branch`. Read-only; requires an OAuth session.
 - **`list_nodes`** / **`create_node`** / **`update_node`** / **`move_node`** / **`delete_node`**: Manage the navigation tree. If a `create_node`, `update_node`, `move_node`, or `delete_node` call leaves the navigation invalid (for example, a page at the root next to tabs), the response includes a `navigationErrors` field. Fix these errors before `publish`, because Mintlify can drop invalid nodes from the published navigation. If a page already exists at the `path` on `branch`, `create_node` writes the new content into it, keeps its navigation position, and returns `updated: true`.
 - **`update_config`** — Modify `docs.json` (theme, nav roots, integrations, SEO).
-- **`upload_image`** / **`finalize_image_upload`** — Add a local image to `branch`. Call `upload_image` with the destination `path` (for example, `images/dashboard.png`), `contentType`, and exact `size` in bytes. `PUT` the file bytes to the returned `uploadUrl` with the returned `headers`, then call `finalize_image_upload` with the `uploadId` and the same `path`. Use the returned `src` in MDX or in the `docs.json` `logo` or `favicon` fields. Uploading to an existing `path` replaces the image. Mintlify only accepts SVGs for logos and favicons, so pass `purpose: "logo"` to both tools. Images publish with your other edits on `publish`.
+- **`upload_file`** / **`finalize_file_upload`**: Upload a local file. To add an image to `branch`, call `upload_file` with the destination `path` (for example, `images/dashboard.png`), `contentType`, and exact `size` in bytes. `PUT` the file bytes to the returned `uploadUrl` with the returned `headers`, then call `finalize_file_upload` with the `uploadId` and the same `path`. Use the returned `src` in MDX or in the `docs.json` `logo` or `favicon` fields. Uploading to an existing `path` replaces the image. Mintlify only accepts SVGs for logos and favicons, so pass `purpose: "logo"` to both tools. Images publish with your other edits on `publish`. To write a large page from a local file, call `upload_file` with a `.md` or `.mdx` `path` and `contentType: "text/markdown"` (no `branch` needed), `PUT` the file, then pass the `uploadId` in place of `content` to `write_page` or as `data.uploadId` to `create_node` within 10 minutes; skip `finalize_file_upload`. Each `uploadId` works once.
 - **Project management tools** — Read with `get_deployment_settings`, `get_analytics_report`, `get_workflows`, and `list_repos_and_prs`. Write with `update_deployment_settings`, `manage_custom_domain`, `manage_git_source`, `manage_access_auth`, `manage_workflow`, and `manage_members_sharing`. Pass `subdomain` (required on org-wide connections; read tools also accept `subdomains`, up to 25) and a `request` object whose `action` (or `report`) selects the operation. Writes apply immediately to the live project and return the updated `state`, so confirm the intended change first.
 
 Private pages: `list_nodes` accepts `visibility: "private"` to list the private pages and folders the OAuth user can access (ignores other filters, returns each node's `role`). `read`, `edit_page`, `write_page`, `update_node`, and `delete_node` accept `private-page-<uuid>` or `private-folder-<uuid>` node ids; `create_node` accepts `visibility: "private"` with `data.type: "page"` or `"group"`. Private-page operations require an OAuth session (the admin MCP rejects client and machine-to-machine tokens), need no `branch`, and enforce role requirements: read for reads, editor or higher for writes and updates, manager for deletes. The caller becomes the manager of any node they create.

agent-context/context/skills/mintlify/reference/cli.md

@@ -18,12 +18,12 @@ Available on all commands.
 
 - `mint dev`: Start local preview at localhost:3000. In a directory without `docs.json`, it generates one from the directory structure: root Markdown and MDX files go in an **Introduction** group, each top-level folder becomes a group (nested folders become subgroups, and leading number prefixes such as `01-` are dropped from group names), `index` and `readme` pages sort first, and paths starting with `.` or `_`, `node_modules`, `snippets`, and `.mintignore` entries are skipped. The site name comes from `name` in a `package.json` in the directory or its parent, otherwise the directory name. `--port` sets the port. `--host` exposes the preview on your network so other devices can open it; without it, the preview only accepts connections at `localhost`. `--no-open` skips browser launch. `--groups` mocks user groups (space-separated, e.g. `--groups admin user`). `--signed-in` previews as a signed-in reader with no groups; without `--signed-in` or `--groups`, the preview shows the signed-out view. `--disable-openapi` skips OpenAPI processing. `--disable-prefetch` disables navigation prefetching. `--local-schema` allows locally-hosted OpenAPI files over HTTP. The preview generates each page's OG image from local files at `/_mintlify/og/<page-path>.png` (`index.png` for the home page) and regenerates it on every request. Each page's `og:image` meta tag points to that image unless the page sets a custom `og:image`.
 - `mint og [page]` — Render a page's social preview (OG) image to a PNG using the `docs.json` `thumbnails` settings and page or section `thumbnail` overrides. `page` defaults to `index`. `--preset` (`classic`, `headline`, `minimal`), `--surface` (`brand`, `neutral`), and `--appearance` (`light`, `dark`) try settings without editing `docs.json`. `--output <file>` sets the PNG path (default: a temporary file). `--no-open` skips opening the image; it is also skipped when `CI` is set. Warnings (title too long, missing logo, font load failure, low contrast) don't change the exit code. Exits `1` if `docs.json` is invalid or the page doesn't exist.
-- `mint validate` — Strict build validation; exits non-zero on warnings or errors. `--groups` mocks user groups (space-separated). `--disable-openapi` skips OpenAPI processing. `--local-schema` allows local OpenAPI files.
+- `mint validate` — Strict build validation; exits non-zero on warnings or errors. `--groups` mocks user groups (space-separated). `--disable-openapi` skips OpenAPI processing. `--local-schema` allows local OpenAPI files. `--fix` writes the available automatic fixes to disk, then checks again (up to five fix passes, since one fix can unlock another). Mintlify skips overlapping fixes and any fix that would make a page parse worse than before. Without `--fix`, output reports how many issues `--fix` would fix. Commit or stash changes first so you can review the edits.
 - `mint export`: Export a static site zip for air-gapped deployment. `--output <file>` sets the output path (default: `export.zip`). `--groups` includes restricted pages (space-separated). `--disable-openapi` skips OpenAPI processing. `--base-path <path>` serves the export under a subpath such as `/docs` (letters, numbers, hyphens, and underscores, with `/` between segments); without it, the export must be served from the domain root. The export fails if any page path starts with the base path. `--client-version <version>` builds with a specific Mintlify client release (default: the latest release compatible with the CLI). The export includes a local search index, so search works offline and skips pages hidden from search.
 
 ## Content quality
 
-- `mint broken-links` — Check for broken internal links. `--files <paths...>` limits the check to specific files or globs. `--check-anchors` validates `#` anchors. `--check-external` checks external URLs. `--check-redirects` checks that redirect destinations in `docs.json` resolve. `--check-snippets` checks that snippet import paths resolve. Relative and `#` links inside snippets are checked against each page that renders the snippet.
+- `mint broken-links`: Check for broken internal links. `--files <paths...>` limits the check to specific files or globs. `--check-anchors` validates `#` anchors. `--check-external` checks external URLs. `--check-redirects` checks that redirect destinations in `docs.json` resolve. `--check-snippets` checks that snippet import paths resolve. Checks Markdown links and images, `href` on `<a>` and `<Card>`, and `src` on `<img>` and `<source>`. Paths without a leading `/`, `#`, or `?` (for example, `next` or `./next`) resolve from the page's directory, as in the browser; start with `/` to link from the site root. Inside snippets, these and `#` links are checked against each page that renders the snippet. Reference-style link definitions and `href`/`src` values written as string or static template literals (`href={"/a"}`) are checked; dynamic expressions are skipped.
 - `mint a11y` — Accessibility checks (alt text, color contrast). `--skip-contrast` or `--skip-alt-text` to narrow scope.
 - `mint score [url]` — Score a docs site's AI/agent readiness. Checks llms.txt, MCP discoverability, robots.txt, sitemap, structured data, response latency, and more. Requires `mint login`. Defaults to your configured subdomain. `--format` accepts `table` (default), `plain`, or `json`.
 - `mint format` — Format every `.mdx` file in the current directory and its subdirectories in place. Respects `.gitignore` and Mintlify ignore rules. Commit or stash changes first so you can review the rewrite.
@@ -56,8 +56,8 @@ Query documentation analytics from the terminal. Requires `mint login` and a Pro
 
 ## Project setup
 
-- `mint deploy` — Provision an anonymous docs site without login and print a hosted Git repository URL plus a short-lived write token. The CLI does not upload files: clone the hosted repository into a separate directory, copy `docs.json`, pages, and assets to its root, commit, and push to `main` with the token as an HTTP `Authorization: Bearer` header for that Git operation only. Never put the token in a remote URL, Git config, or public logs. `--subdomain` (required for the first deployment or `--new`), `--org-name`, `--directory` (default: `.`), `--new` creates another site, `--email` also returns a claim link. Rerun from the same directory to reuse the site and get a fresh token. Inside GitHub Actions (`GITHUB_ACTIONS=true`), `mint deploy` skips login and agent credentials: it exchanges the job's OIDC token for a write token and force-pushes the checked-out commit (the `--directory` subtree, or the repository root) to the site's `main`. The workflow needs `permissions: id-token: write`, `--subdomain` is required, and the repository and branch must be trusted for the site, otherwise the deploy fails with a 403.
-- `mint claim` — Claim a site created with `mint deploy`. Run `mint claim --email <email>` to get a claim link, show it to the user, and ask them to sign in and return the displayed code. Then run `mint claim --code <code>`. `--email` and `--code` can't be combined. Run both from the original `mint deploy` directory, or pass `--directory`. The CLI uses its saved credentials; never read or print keychain secrets. Never invent an email address. If Mintlify signup fails, retry the same `--code` command.
+- `mint deploy` — Provision an anonymous docs site without login and print a hosted Git repository URL plus a short-lived write token. The CLI does not upload files: clone the hosted repository into a separate directory, copy `docs.json`, pages, and assets to its root, commit, and push to `main` with the token as an HTTP `Authorization: Bearer` header for that Git operation only. Never put the token in a remote URL, Git config, or public logs. `--subdomain` (required for the first deployment or `--new`), `--org-name`, `--directory` (default: `.`), `--new` creates another site, `--email` also returns a claim link. Rerun from the same directory to reuse the site and get a fresh token. If the CLI can't save credentials to the keyring or the fallback file, `mint deploy` and `mint claim` fail before provisioning or signup. Inside GitHub Actions (`GITHUB_ACTIONS=true`), `mint deploy` skips login and agent credentials: it exchanges the job's OIDC token for a write token and force-pushes the checked-out commit (the `--directory` subtree, or the repository root) to the site's `main`. The workflow needs `permissions: id-token: write`, `--subdomain` is required, and the repository and branch must be trusted for the site, otherwise the deploy fails with a 403.
+- `mint claim` — Claim a site created with `mint deploy`. Run `mint claim --email <email>` to get a claim link, show it to the user, and ask them to sign in and return the displayed code. Then run `mint claim --code <code>`. `--email` and `--code` can't be combined. Run both from the original `mint deploy` directory, or pass `--directory`. The CLI uses its saved credentials from the system keyring, or from `~/.config/mintlify/agent-credentials.json` when the keyring is unavailable; never read or print these secrets. Never invent an email address. If Mintlify signup fails, retry the same `--code` command.
 - `mint new [directory]` — Scaffold a new Mintlify docs site. `--name` and `--theme` set initial config. `--template` selects a pre-defined template. `--force` overwrites an existing directory.
 
 ## Maintenance