Initial commit

agent-ready/visibility.mdx

@@ -0,0 +1,85 @@
+---
+title: 'Visibility'
+description: 'Show different content to humans and AI agents'
+icon: 'eye'
+---
+
+The `Visibility` component lets a single page serve two audiences: humans reading on the web and AI agents processing the Markdown output. Content marked `for="humans"` appears on the rendered page but is excluded from Markdown exports. Content marked `for="agents"` is hidden on the web but included in Markdown.
+
+This means you can write conversational, UI-centric instructions for humans and structured, machine-readable instructions for AI — without maintaining two separate pages.
+
+## How it works
+
+Mintlify serves every page at two URLs:
+
+- `https://docs.example.com/page` — the rendered site, for humans
+- `https://docs.example.com/page.md` — the raw Markdown, for AI agents
+
+`Visibility` controls what appears at each URL.
+
+## Example
+
+```mdx
+<Visibility for="humans">
+  <Steps>
+    <Step title="Open the dashboard">
+      Navigate to [dashboard.example.com](https://dashboard.example.com) and sign in.
+    </Step>
+    <Step title="Create an API key">
+      Go to **Settings → API Keys** and click **New key**.
+    </Step>
+  </Steps>
+</Visibility>
+
+<Visibility for="agents">
+  To authenticate, send a POST request to `/v1/auth/token` with the user's
+  email and password in the request body. The response includes a bearer token
+  valid for 24 hours. Pass this token as `Authorization: Bearer <token>` on
+  all subsequent requests.
+</Visibility>
+```
+
+Human readers see the step-by-step UI walkthrough. AI agents processing the Markdown get the direct API instructions instead.
+
+## Props
+
+<ResponseField name="for" type='"humans" | "agents"' required>
+  - `"humans"` — visible on the rendered web page, excluded from `.md` export
+  - `"agents"` — hidden on the rendered web page, included in `.md` export
+</ResponseField>
+
+## When to use it
+
+<Columns cols={2}>
+  <Card title="Onboarding flows" icon="person-walking-arrow-right">
+    Show UI screenshots and button clicks to humans. Give agents the equivalent API calls.
+  </Card>
+  <Card title="Configuration guides" icon="sliders">
+    Show a visual settings panel to humans. Give agents the equivalent JSON or CLI flags.
+  </Card>
+  <Card title="Error messages" icon="triangle-exclamation">
+    Show a friendly explanation to humans. Give agents structured error codes and remediation steps.
+  </Card>
+  <Card title="Conceptual pages" icon="lightbulb">
+    Include rich diagrams and narrative for humans. Provide a concise structured summary for agents.
+  </Card>
+</Columns>
+
+## Combining with Prompt
+
+`Visibility` and `Prompt` complement each other well. Use `Visibility` to give agents structured context, then use `Prompt` to give human readers a prompt they can use to ask an AI about that same content.
+
+```mdx
+<Visibility for="agents">
+  ## Authentication schema
+  - Method: Bearer token
+  - Header: `Authorization: Bearer <token>`
+  - Token TTL: 86400 seconds
+  - Refresh endpoint: POST /v1/auth/refresh
+</Visibility>
+
+<Prompt description="Ask about authentication" icon="lock">
+  Explain how authentication works in this API and show me example code for
+  getting a token and making an authenticated request.
+</Prompt>
+```