agent-context: fix wrong claims and API docs gaps in Mintlify skill

agent-context/context/skills/mintlify/reference/api-docs.md

@@ -4,29 +4,35 @@ Setting up API documentation with OpenAPI, AsyncAPI, and MDX manual pages.
 
 ## OpenAPI setup
 
-Add your OpenAPI spec to `docs.json`:
+Spec requirements:
+- OpenAPI 3.0 or 3.1, in JSON or YAML, stored in the repo or hosted at a public URL.
+- `$ref` supports internal references only. External references are not supported.
+- Include a `servers` field with the API base URL. Without it, the playground falls back to simple mode because it can't send requests.
+- Define `components.securitySchemes` and `security` to get auth inputs in the playground.
 
-```json
-"api": {
-  "openapi": "openapi.json"
-}
-```
-
-Multiple specs:
+Add an `openapi` field to a navigation element (tab, group, anchor, and so on) to generate endpoint pages there. With no `pages`, every endpoint in the spec gets a page:
 
 ```json
-"api": {
-  "openapi": ["openapi/v1.json", "openapi/v2.json"]
+"navigation": {
+  "tabs": [
+    { "tab": "API reference", "openapi": "openapi.json" }
+  ]
 }
 ```
 
-Reference individual endpoints in navigation:
+- The value can be a path, a URL, an array of specs, or an object: `{ "source": "openapi.json", "directory": "api-reference" }`. `directory` sets where generated pages live (default `api-reference`).
+- To mix endpoints with other pages, set `openapi` on the element and list endpoints in `pages` as `METHOD /path`. Child elements inherit the parent's spec unless they set their own.
+- To pull an endpoint from a specific spec without a default, use `"/path/to/spec.json POST /users"` as the page entry.
+- `api.openapi` in `docs.json` accepts the same values.
+- Hosted spec URLs don't trigger a redeploy when the spec changes. Call the trigger deployment API from the spec's CI to keep docs current.
+- Use `mint dev --local-schema` to preview a spec served from `http://localhost`. Production requires HTTPS URLs.
+- Generated pages take `title` from the operation `summary` (or method and path), `description` from `description`, and show a deprecated label when `deprecated: true`.
 
 ```json
 {
   "group": "Users",
   "openapi": "openapi.json",
-  "pages": ["GET /users", "POST /users", "GET /users/{id}"]
+  "pages": ["users/overview", "GET /users", "POST /users", "GET /users/{id}"]
 }
 ```
 
@@ -87,26 +93,50 @@ paths:
             curl https://api.example.com/users
 ```
 
-## MDX manual API pages
+## MDX pages from an OpenAPI spec
 
-For endpoints without an OpenAPI spec:
+Create an MDX page per endpoint to control its metadata, content, and position while keeping the generated reference. The method and path must exactly match the spec.
 
 ```yaml
 ---
-title: "Create user"
-api: "POST https://api.example.com/users"
+title: "Get users"
+openapi: "openapi/users.json GET /users"
 ---
 ```
 
-Or with a base URL configured in `docs.json`:
+- Always include the spec file path when the repo contains more than one spec. Mintlify uploads every spec in the repo, even unreferenced ones, and `openapi: "GET /users"` without a path can resolve to the wrong spec.
+- Webhooks (OpenAPI 3.1): `openapi: "openapi.json webhook orderUpdated"`, where the name matches a key in `webhooks`.
+- Data models: `openapi-schema: "openapi.json OrderItem"` renders a `components.schemas` entry. The file path is optional unless schema names collide across specs.
+- Generate MDX files from a spec with `npx @mintlify/scraping@latest openapi-file <path-to-spec> -o <folder>`.
 
-```yaml
+## MDX manual API pages
+
+For endpoints without an OpenAPI spec, set `api` in frontmatter and document parameters and responses with `ParamField` and `ResponseField`:
+
+```mdx
 ---
 title: "Create user"
-api: "POST /users"
+api: "POST /users/{userId}"
 ---
+
+<ParamField path="userId" type="string" required>
+  Unique identifier for the user.
+</ParamField>
+
+<ParamField body="email" type="string" required>
+  User's email address.
+</ParamField>
+
+<ResponseField name="id" type="string" required>
+  ID of the created user.
+</ResponseField>
 ```
 
+- `api` takes a full URL (`POST https://api.example.com/users`, ignores `api.mdx.server`) or a relative path (requires `api.mdx.server` in `docs.json`). Wrap path parameters in `{}`.
+- Wrap request and response code samples in `<RequestExample>` and `<ResponseExample>` to show them in the right sidebar.
+- `playground` frontmatter (`interactive`, `simple`, `none`) overrides `api.playground.display` for the page.
+- `authMethod` frontmatter (`bearer`, `basic`, `key`, `none`) overrides `api.mdx.auth.method` for the page. `none` disables auth.
+
 ## AsyncAPI
 
 For WebSocket and event-driven APIs:
@@ -162,6 +192,7 @@ Control the API playground behavior in `docs.json`:
 - `examples.prefill`: Pre-fill playground fields with spec example values. Default: `false`.
 - `examples.autogenerate`: Generate code samples from API specs. Default: `true`.
 - `mdx.auth.method`: `"bearer"`, `"basic"`, `"key"`, `"cobo"`.
+- `mdx.auth.name`: Header name for the API key, such as `x-api-key`. Required with `"key"`.
 
 ### Runtime server variables
 
@@ -191,4 +222,23 @@ Every parameter in the playground has a clickable anchor link. Hover over a para
 
 ## Custom endpoint pages
 
-Use the `x-mint` extension in your OpenAPI spec to customize individual endpoint pages (metadata, playground behavior, additional content) while keeping all API documentation in one file. Alternatively, create individual MDX pages for full per-page control.
+Use the `x-mint` extension on an operation to customize its generated page while keeping everything in the spec. For full per-page control, create MDX pages from the spec instead.
+
+- `x-mint.metadata`: Any frontmatter field except `openapi` (for example `title`, `sidebarTitle`, `description`). Includes `playground`, `groups`, and `public`, so `{"playground": "auth", "groups": ["admin"], "public": true}` makes the page public while limiting the playground to authenticated `admin` users.
+- `x-mint.content`: MDX (any Mintlify component) rendered before the generated reference.
+- `x-mint.href`: Custom URL for the generated page.
+- `x-mint.playground.expand`: `false` collapses nested object fields in the playground (see OpenAPI extensions above).
+- `x-mint.pre` / `x-mint.post` (on any schema): Arrays of strings rendered as pills before or after the parameter name.
+
+```json
+"/users": {
+  "get": {
+    "summary": "Get users",
+    "x-mint": {
+      "metadata": { "title": "List all users", "sidebarTitle": "List users" },
+      "content": "## Prerequisites\n\n<Note>Requires an admin API key.</Note>",
+      "href": "/api-reference/users/list"
+    }
+  }
+}
+```

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

@@ -24,7 +24,7 @@ Available on all commands.
 
 - `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 links inside `<Snippet>` components.
 - `mint a11y` — Accessibility checks (alt text, color contrast). `--skip-contrast` or `--skip-alt-text` to narrow scope.
-- `mint test` — Scan content for code blocks and generate unit tests that validate them. Requires `mint login`. Interactive; only pages in the `docs.json` navigation appear for selection. Writes generated test projects to `tests/mint-test/<run-id>/` and run reports/history to `.mintlify/test/`. Add both paths to `.gitignore` to avoid committing test artifacts. When a previous run report exists, the next interactive run offers **Update tests** (rerun the same pages with the same agent and model), **Review last test run** (browse saved results without running anything), or **Start a brand new test** (pick an agent and pages from scratch).
+- `mint test` — Scan content for code blocks and generate unit tests that validate them, run by a local coding agent. Requires `mint login` and the agent SDK installed in the project: `npm install @anthropic-ai/claude-agent-sdk @anthropic-ai/sdk @modelcontextprotocol/sdk` (Claude, default) or `npm install @openai/codex-sdk` (Codex). Interactive; only pages in the `docs.json` navigation appear for selection. Writes generated test projects to `tests/mint-test/<run-id>/` and run reports/history to `.mintlify/test/`. Add both paths to `.gitignore` to avoid committing test artifacts. When a previous run report exists, the next interactive run offers **Update tests** (rerun the same pages with the same agent and model), **Review last test run** (browse saved results without running anything), or **Start a brand new test** (pick an agent and pages from scratch). Exits `0` when every test passes, `1` otherwise.
 - `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.
 
@@ -38,7 +38,7 @@ Available on all commands.
 
 ## Analytics
 
-Query documentation analytics from the terminal. Requires `mint login`. All `mint analytics` subcommands share these flags: `--subdomain`, `--from <YYYY-MM-DD>` (default: seven days ago, or `mint config set dateFrom`), `--to <YYYY-MM-DD>` (default: today, or `mint config set dateTo`), `--format` (`table`, `plain`, `json`, or `graph`; default: `plain`, or `json` in AI/CI environments).
+Query documentation analytics from the terminal. Requires `mint login` and a Pro or Enterprise plan. All `mint analytics` subcommands share these flags: `--subdomain`, `--from <YYYY-MM-DD>` (default: seven days ago, or `mint config set dateFrom`), `--to <YYYY-MM-DD>` (default: today, or `mint config set dateTo`), `--format` (`table`, `plain`, `json`, or `graph`; default: `plain`, or `json` in AI/CI environments).
 
 - `mint analytics stats` — Top-line KPIs for a date range: views, visitors, searches, feedback, assistant usage. Human and agent traffic reported separately. `--page` filters to a page path.
 - `mint analytics search` — Search queries with hit counts, click-through rates, top clicked page, and last searched date. `--query` filters by substring; `--page` filters to queries where the given page was the top clicked result.

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

@@ -131,12 +131,17 @@ Numbered step-by-step procedures.
 </Steps>
 ```
 
+Steps props:
+- `titleSize` (string, default: "p"): Size of all step titles: `"p"`, `"h2"`, `"h3"`, or `"h4"`.
+
 Step props:
-- `title` (string): Step title.
+- `title` (string, required): Step title. Supports inline Markdown.
 - `icon` (string): Icon name.
 - `iconType` (string): Font Awesome style.
 - `stepNumber` (number): Override automatic numbering.
-- `titleSize` (string, default: "p"): `"p"`, `"h2"`, or `"h3"`.
+- `titleSize` (string, default: "p"): `"p"`, `"h2"`, `"h3"`, or `"h4"`.
+- `id` (string): Custom anchor ID.
+- `noAnchor` (boolean, default: false): Hide the step's anchor link.
 
 ## Tabs
 
@@ -320,10 +325,13 @@ Display icons inline.
 <Icon icon="rocket" size={24} color="#3B82F6" />
 
 Text with <Icon icon="check" iconType="solid" /> inline icon.
+
+<Icon src="/images/my-icon.svg" />
 ```
 
-Props:
-- `icon` (string, required): Font Awesome, Lucide, or Tabler icon name, a single emoji, a URL, or a file path.
+Props (one of `icon` or `src` is required):
+- `icon` (string): Font Awesome, Lucide, or Tabler icon name (matching `icons.library`), or a single emoji.
+- `src` (string): Path to an image in the project or an external image URL. Use instead of `icon` for custom images.
 - `iconType` (string): Font Awesome style.
 - `size` (number): Pixel size.
 - `color` (string): Hex color. Not applied to emoji icons.

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

@@ -60,7 +60,7 @@ The SKILL.md file lists common frontmatter fields. Here is the complete set. All
 | `icon` | string | Lucide, Font Awesome, or Tabler icon name. Also accepts a single emoji, a URL, or a file path. |
 | `iconType` | string | Font Awesome icon style: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`. |
 | `tag` | string | Label next to page title in sidebar (e.g., "NEW"). |
-| `hidden` | boolean | Remove from sidebar. Page still accessible by URL. Also excludes the page from search, sitemaps, external indexing, AI context, and `llms.txt`. Remove the field (or set `false`) to make a page visible again. |
+| `hidden` | boolean | Remove from sidebar. Page still accessible by URL. Also excludes the page from search, sitemaps, external indexing, AI context, and `llms.txt`. To make a page visible again, remove the field entirely. Do not set `false`. |
 | `noindex` | boolean | Exclude from site search, sitemaps, search engine indexing, and AI assistant context. Still visible in navigation. |
 | `searchable` | boolean | At the page level, only `searchable: false` has an effect: excludes the page from site search and AI assistant context while keeping it indexable externally and visible in navigation. Does not override `hidden: true`. Pages with `searchable: false` still appear in `llms.txt` and `llms-full.txt`. |
 | `boost` | number | Multiply the page's in-product search ranking. Values above 1 prioritize, between 0 and 1 de-prioritize. No effect when `searchable: false`. |
@@ -70,7 +70,7 @@ The SKILL.md file lists common frontmatter fields. Here is the complete set. All
 | `hideApiMarker` | boolean | Hide the HTTP method badge next to the page title in the sidebar. |
 | `contextual` | object | Override the site-wide contextual menu (`options`, `display`) for this page. `options: []` disables it. |
 | `groups` | string[] | Limit the page to users in specific groups. With authentication, restricts access. With standalone personalization, only controls navigation visibility. Users can still open the page by direct URL. |
-| `mode` | string | Page layout: `default`, `wide`, `custom`, `frame`, `center`. |
+| `mode` | string | Page layout: `default`, `wide`, `custom`, `frame`, `center`, `assistant`. |
 | `keywords` | array | Search terms for internal search and SEO. |
 | `api` | string | API endpoint for interactive playground (e.g., `"POST /users"`). |
 | `openapi` | string | OpenAPI endpoint reference (e.g., `"GET /endpoint"`). |
@@ -113,6 +113,12 @@ mode: "frame"
 title: "Page title"
 mode: "center"
 ---
+
+# Assistant: full-screen assistant chat replaces page content (all themes; requires the assistant enabled)
+---
+title: "Ask AI"
+mode: "assistant"
+---
 ```
 
 ## Theme

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

@@ -171,12 +171,12 @@ Appear on all pages regardless of active section:
         { "anchor": "Changelog", "icon": "list", "href": "/changelog" }
       ],
       "languages": [
-        { "language": "en", "default": true },
-        { "language": "es" }
+        { "language": "en", "default": true, "href": "https://example.com/docs" },
+        { "language": "es", "href": "https://example.com/es/docs" }
       ],
       "versions": [
-        { "version": "v2", "default": true },
-        { "version": "v1" }
+        { "version": "v2", "default": true, "href": "https://example.com/docs" },
+        { "version": "v1", "href": "https://v1.example.com/docs" }
       ],
       "products": [
         { "product": "Core API", "icon": "server" },
@@ -191,8 +191,8 @@ Global element properties:
 - `global.tabs`: Each entry requires `tab` (string) and `href`. Optional: `icon`, `iconType`, `hidden`.
 - `global.anchors`: Each entry requires `anchor` (string) and `href`. Optional: `icon`, `iconType`, `color.light`, `color.dark`, `hidden`.
 - `global.dropdowns`: Each entry requires `dropdown` (string) and `href`. Optional: `icon`, `iconType`, `hidden`.
-- `global.languages`: Each entry requires `language` (code string). Optional: `default`, `hidden`, `href`.
-- `global.versions`: Each entry requires `version` (string). Optional: `default`, `hidden`, `href`.
+- `global.languages`: Each entry requires `language` (code string) and `href`. Optional: `default`, `hidden`.
+- `global.versions`: Each entry requires `version` (string) and `href`. Optional: `default`, `hidden`.
 - `global.products`: Each entry requires `product` (string). Optional: `description`, `icon`, `iconType`.
 
 ## Dropdowns