diff --git a/poc-onboarding.mdx b/poc-onboarding.mdx
new file mode 100644
index 000000000..45326d258
--- /dev/null
+++ b/poc-onboarding.mdx
@@ -0,0 +1,463 @@
+---
+title: "Proof of concept onboarding"
+description: "Set up a Mintlify proof of concept step by step: connect your repository, migrate sample content, publish a change, turn on the assistant, and measure the result."
+keywords: ["POC", "proof of concept", "trial", "evaluation", "enterprise onboarding", "pilot"]
+noindex: true
+---
+
+This guide takes you from nothing to a working Mintlify documentation site that your team can evaluate. Follow the steps in order. Each one tells you what to do, who you need from your team, and how long it takes.
+
+You do not need to be a developer to finish this guide. Two steps need someone with GitHub or IT access for a short time. You can do everything else yourself in a browser.
+
+
+ You have a dedicated Mintlify contact for the duration of your proof of concept (POC). If a step doesn't match what you see on screen, or you get stuck for more than a few minutes, message your shared Slack channel or email [support@mintlify.com](mailto:support@mintlify.com) instead of working around it.
+
+
+## How Mintlify fits together
+
+Three things, and knowing which is which makes every step below easier to follow:
+
+1. **Your repository** is the source of truth. Your documentation is `.mdx` files and one `docs.json` configuration file in Git. Nothing is stored in a proprietary format.
+2. **The dashboard** at [app.mintlify.com](https://app.mintlify.com) is the control plane, where you write, configure, and publish.
+3. **Your live site** is what readers see.
+
+The web editor sits between them. When you publish, it writes to your repository for you, so nobody has to run a Git command who doesn't want to.
+
+## What you'll have at the end
+
+
+
+ A real site at your own URL, running a representative sample of your content.
+
+
+
+ Your team editing and publishing pages, with review before anything goes live.
+
+
+
+ An assistant answering questions from your documentation, with analytics showing what people asked and where your content gaps are.
+
+
+
+ Single sign-on, access controls, and audit logging configured or confirmed.
+
+
+
+## Before you begin
+
+### People you'll need
+
+Line these people up before you start. Nothing here needs full-time involvement, but a missing GitHub administrator can stall the POC for days.
+
+| Who | What they do | When | Time needed |
+|---|---|---|---|
+| Documentation owner | Runs the POC and completes most steps. This is probably you. | Throughout | A few hours total |
+| GitHub administrator | Approves the Mintlify GitHub App on your repository. | Step 1 | 15 minutes, once |
+| Designer or brand owner | Supplies logo files, color codes, and fonts. | Step 5 | 30 minutes, once |
+| Identity or IT administrator | Configures single sign-on, authentication, and DNS records. | Step 7 | 1 to 2 hours, optional |
+| Decision maker | Reviews the finished POC against your success criteria. | Step 8 | 1 hour |
+
+### What to gather
+
+Collect these before step 3 so you aren't waiting on other teams mid-setup:
+
+- Logo files for light and dark backgrounds, in SVG or PNG. You need both variants, or your logo disappears when a reader switches themes.
+- A favicon. SVG works well.
+- Your brand color codes, as hex values.
+- Font files, or the names of the Google Fonts your marketing site uses.
+- A link to your current documentation site, or an export of its content.
+- Your OpenAPI specification file or URL, if you document an API.
+- Your top 20 to 30 pages by traffic, from your current analytics. See [Choose your sample content](#choose-your-sample-content).
+
+### Pick one thing to prove
+
+Most POCs fail their own review because nobody agreed in advance what a good result looks like. Avoid that by picking a single lever and a single metric under it.
+
+
+
+ Docs shorten time-to-first-success. Metric: activation rate, or time-to-first-integration.
+
+
+
+ Docs answer the questions your support team gets asked repeatedly. Metric: ticket volume in your top category.
+
+
+
+ Findable docs unblock the next thing a customer wants to do. Metric: feature adoption after launch.
+
+
+
+Write down what "good" would look like for that one metric in 90 days, and share it with your Mintlify contact at kickoff.
+
+
+ Record your baseline before you start. If your metric is support tickets, pull the current monthly volume for your top category now. A POC with nothing to compare against produces opinions instead of a decision.
+
+
+Then add two or three practical criteria that the POC itself can settle:
+
+- A writer with no Git experience publishes a page change without help.
+- Our most complex API reference page renders correctly.
+- The assistant answers 8 of our 10 most common support questions correctly, citing the right page.
+- Our identity provider handles dashboard login.
+
+## Step 1: Create your account and connect your repository
+
+
+ Your GitHub administrator needs organization ownership or administrator permissions on the repository to approve the Mintlify GitHub App. Ask them to be available before you begin this step. Without the app installed, your site will not deploy.
+
+
+
+
+ Go to [mintlify.com/start](https://mintlify.com/start) and create an account with your work email address. Use the address you'd use for your real documentation, not a personal one, so it maps to your identity provider later.
+
+
+
+ During onboarding, connect your GitHub account, then create a new repository or select an existing empty one. A repository named `docs` inside your company's GitHub organization is a good default. A private repository is fine.
+
+ Do not select a repository that already contains an application or other files.
+
+
+
+ Your GitHub administrator installs the Mintlify GitHub App and grants it access to that one repository. Select **Only select repositories** rather than granting access to everything.
+
+ See [Install the GitHub App](/deploy/github#install-the-github-app) for the exact permissions the app requests. Send that link to your administrator ahead of time if they want to review the permissions first.
+
+
+ Install the app anyway. GitHub sends an approval request to your organization owners, and the installation completes when they approve it.
+
+ If that approval will take days, you can skip connecting a Git provider during onboarding. Mintlify creates a private repository for you so you can start immediately, and you can move the content to your own repository later from the [Git settings](https://app.mintlify.com/settings/deployment/git-settings) page. See [Clone to your own repository](/deploy/github#clone-to-your-own-repository).
+
+
+
+
+ Mintlify deploys starter content to your repository and publishes it. Your site is live at `https://.mintlify.site`.
+
+ Find the exact URL on the **Overview** page of your [dashboard](https://app.mintlify.com/). Open it to confirm the site loads.
+
+
+
+
+ Use the `.mintlify.site` URL for most of the POC. It is a real, working site you can share internally.
+
+ One exception: if testing authentication is part of your criteria, you need a custom domain or a `*.mintlify.app` subdomain first, because authentication does not work on the default URL or on a custom basepath. Set that up early rather than in the final week. See [step 7](#step-7-loop-in-it-and-security).
+
+
+## Step 2: Invite your team
+
+Add everyone who needs to see or touch the POC from the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard.
+
+Mintlify has three roles. Assign the narrowest one that lets each person do their job:
+
+- **Admin**: Changes organization settings, billing, and integrations. Give this to yourself and one backup.
+- **Editor**: Creates and publishes content. Give this to your writers.
+- **Viewer**: Reads the dashboard and analytics without editing. Give this to reviewers and stakeholders.
+
+See [Roles](/dashboard/roles) for what each role can do in detail.
+
+Invite people using their work email addresses. If you plan to test single sign-on in step 7, mismatched addresses mean their accounts will not link to your identity provider.
+
+For a useful POC, invite at least one writer who has never used Git, one engineer, and the person who will make the buying decision. The first two tell you whether the tool fits your team. The third needs to have seen it work.
+
+## Step 3: Get your content in
+
+### Choose your sample content
+
+Pull your top 20 to 30 pages by traffic from your current analytics, then pick your sample from that list. Starting from real traffic rather than intuition means you evaluate Mintlify on the pages your readers actually use.
+
+From that list, deliberately include the pages that are hardest to move:
+
+- Your most complex API reference page.
+- A page with a large table or a deeply nested list.
+- A page with images, video, or diagrams.
+- A page using custom components or embedded widgets, if you have any.
+- Two or three ordinary guides, so you can judge everyday quality.
+
+A POC built on your simplest pages tells you nothing about the migration you'd actually run. More than 50 pages slows the POC down without teaching you anything new.
+
+### Move the content
+
+
+
+ Ask your Mintlify contact whether a migration is included in your POC, and what the turnaround time is.
+
+ If it is, send them:
+
+ - A link to your current documentation site, or an export of its content.
+ - The list of pages you chose.
+ - Your OpenAPI specification file or URL, if you have an API reference.
+ - Your brand assets from [What to gather](#what-to-gather).
+
+ Mintlify ports the content, checks it, and shares a preview link so you can watch progress. See [Enterprise migrations](/migration-services/enterprise) for how the full migration process works after the POC.
+
+
+
+ Three routes, roughly in order of how clean the result is:
+
+ 1. **Export as Markdown** from your current platform, when it supports that. Mintlify has tooling for [Docusaurus](/migration/docusaurus), [ReadMe](/migration/readme), [GitBook](/migration/gitbook), [Fern](/migration/fern), and [Document360](/migration/document360), plus [manual instructions](/migration/manual) for anything else.
+ 2. **Paste and clean up in the web editor.** Fastest for a handful of ad-hoc pages.
+ 3. **Let an AI tool convert it**, using the Mintlify [skill](/ai/skillmd) and [admin MCP server](/ai/mintlify-mcp) in Claude Code or Cursor.
+
+ Start at [Migrate to Mintlify](/migration) to pick your path.
+
+
+
+ If your content lives in Notion, Confluence, Jira, or a similar tool, connect it rather than copying out of it. Connected apps give the Mintlify agent live context and can trigger automations that keep pages aligned with their source.
+
+ See [Integrations for the agent and automations](/automations/integrations) for the full list and setup.
+
+
+
+### Check the result
+
+Open your site and compare each sample page against the same page on your current documentation. Look for missing images, broken tables, code samples that lost their formatting, and links that go nowhere.
+
+While you're there, run two quick tests on your navigation:
+
+- Can a brand-new user reach their first useful page in two clicks?
+- Do your navigation labels match the words someone would type into a search box? "How to configure auth" gets found. "Authentication configuration" often doesn't.
+
+A no on either one is worth raising now, because your navigation structure lives in `docs.json` and is cheap to change during a POC.
+
+Send anything wrong to your Mintlify contact in one batch rather than one message at a time. Include the page URL and what you expected to see.
+
+## Step 4: Publish a change yourself
+
+This is the step that decides most POCs. If your writers can update documentation without filing a ticket with engineering, the tool works for you. Have someone non-technical do this step, not the most technical person on your team.
+
+
+
+ Go to the [web editor](https://app.mintlify.com/editor). It has three regions: the **Files** panel on the left with your folders and pages, the editing canvas in the middle, and the toolbar across the top.
+
+ Check the branch selector at the top left before you type anything. When it reads **Live site**, you are editing the deployed site directly and anything you publish goes straight to your readers.
+
+
+
+ Open the **Live site** dropdown, switch to the **Branches** tab, and select **New branch**. You're now editing a copy, so nothing you do affects readers until you publish.
+
+ Do this for your first edit even if you plan to publish directly later. It's how you'll work day to day, and it means a practice edit can't embarrass you.
+
+
+
+ Click anywhere and start typing, the same way you would in a document. Type `/` to insert a component such as a callout, steps block, or card. Drag an image file onto the canvas and the editor uploads it and writes the reference for you.
+
+ Now use the two toggles at the top right of the canvas: the eye icon shows the rendered page, and the `` icon shows the Markdown source. Your edit is sitting there in the raw `.mdx`, frontmatter and all.
+
+ This matters more than it looks. There's no hidden layer and nothing proprietary, so a writer in the visual view and an engineer in the repository are editing the same file.
+
+
+
+ Copy the branch's preview link and send it to a teammate. They see your change rendered at a live URL, in context, with nothing to install. This is how review works: draft, send the preview, publish once it's approved.
+
+
+
+ Select **Publish** in the top right. On a branch, publishing opens or updates a pull request. On the live site, it deploys right away.
+
+ Either way, publishing writes a real Git commit. Watch it appear on the **Overview** page of your dashboard, then refresh your site.
+
+
+
+
+
+ No. Publishing creates a Git commit, so CODEOWNERS, required reviews, and branch protection all still apply exactly as they do today. Your engineers review documentation changes the same way they review code. Writers just don't need Git to propose one.
+
+
+
+ They can toggle to the Markdown view with the `` icon and stay there. Same content, same file. People on the same team can work in different views without stepping on each other.
+
+
+
+ They install the [CLI](/cli/install), clone the repository, and run [`mint dev`](/cli/preview) for a local server with hot reload. They can also run `mint broken-links` before pushing, and you can [wire the same checks into CI](/deploy/ci) so a broken link fails the build like a failing test.
+
+
+
+Two things worth testing in the same sitting, because they change how your team works day to day:
+
+- **Per-branch previews.** Every pull request gets its own live URL. Reviewers open a link instead of pasting screenshots into chat. See [Preview deployments](/deploy/preview-deployments).
+- **Updating docs from Slack.** Connect the Mintlify agent to your Slack workspace and ask it to make a change. It opens a pull request for you. See [Add the agent to Slack](/agent/slack#connect-your-slack-workspace).
+
+## Step 5: Apply your branding
+
+Stakeholders judge a POC partly on whether it looks like your product, and a font mismatch is the first thing anyone notices. This takes about 30 minutes and is worth doing before the review in step 8.
+
+Almost all of your branding lives in a handful of keys in `docs.json`, so a full brand change is a configuration edit rather than a stylesheet:
+
+```json docs.json
+{
+ "theme": "luma",
+ "colors": {
+ "primary": "#16A34A",
+ "light": "#07C983",
+ "dark": "#15803D"
+ },
+ "logo": {
+ "light": "/logo/light-logo.svg",
+ "dark": "/logo/dark-logo.svg"
+ },
+ "favicon": "/favicon.svg"
+}
+```
+
+Set `primary` to your main brand color. `light` and `dark` are the accent shades used in dark and light mode, so tune them until links and buttons stay legible against both backgrounds. Add a `fonts` key to load your marketing font. See [Appearance settings](/organize/settings-appearance) for every option, [Themes](/customize/themes) for the available layouts, and [Fonts](/customize/fonts) for custom typefaces.
+
+Then check both modes, because readers pick their own with the switcher in the top bar:
+
+- Your logo needs a light and a dark variant, which is why `logo.light` and `logo.dark` are separate keys.
+- Diagrams drawn as SVGs that use `currentColor` recolor themselves. Raster screenshots don't, so keep paired light and dark versions.
+
+Finally, set a default Open Graph image so links to your docs render a branded card in Slack. Test it in a real Slack message before you share the site widely. See [SEO](/optimize/seo) for the meta tag reference.
+
+If editing a configuration file isn't something you want to do, send your brand assets to your Mintlify contact and ask them to apply it.
+
+## Step 6: Turn on the AI features
+
+### Enable the assistant
+
+Configure the assistant on the [Assistant](https://app.mintlify.com/products/assistant) page of your dashboard:
+
+1. Turn on the assistant status toggle.
+2. Set your support and sales [deflection addresses](/assistant/configure#set-deflection-emails). Do this before you go live. The handoff is what turns a question the assistant can't answer into a clean escalation instead of a dead end.
+3. Add up to three [starter questions](/assistant/configure#add-sample-questions) to steer people toward what the assistant answers well.
+4. Add [search domains](/assistant/configure#search-domains) if your product spans more than one site.
+5. Leave [bot protection](/assistant/configure#bot-protection) on. It's invisible to nearly all real visitors.
+
+To change the assistant's tone or teach it product-specific behavior, see [Customize the assistant](/assistant/customize) and [Assistant skills](/assistant/skills).
+
+### Test it against real questions
+
+Guessing at whether the assistant is good is the most common way to waste a POC. Do this instead:
+
+1. Pull 20 to 30 real questions from your support tickets or community channels over the last month.
+2. Ask each one on your live site using **Ask Assistant** in the top bar.
+3. Check every answer three ways: did it answer, was the answer right, and **which page did it cite?**
+4. Sort the failures. A wrong answer points at a specific page you should fix. A missing answer points at a page you should write.
+
+That third check is the one people skip, and it's the one that turns a vague impression into a specific fix. Review what your team and your users asked on the [Assistant analytics](/analytics/assistant) page, where unanswered and downvoted questions become your content backlog.
+
+
+ The frontmatter `description` is the single biggest lever on whether a page gets retrieved at all, because the assistant reads it first to decide whether a page is relevant. Aim for 130 to 160 characters of plain language, unique on every page. If a page you know is correct never gets cited, its description is usually why.
+
+
+### Put the assistant where your users are
+
+The [assistant widget](/assistant/widget) embeds the same assistant into your product dashboard, marketing site, or support portal. Adding it needs a developer for about an hour, and it's the fastest way to show your support team what deflection looks like in practice.
+
+### Connect your docs to AI tools
+
+Mintlify runs two MCP servers, and they serve opposite audiences:
+
+- The **[search MCP server](/ai/model-context-protocol)** serves your published content to readers inside Claude, Cursor, and ChatGPT. On an authenticated site it respects auth and groups, so each person only retrieves pages their group can see.
+- The **[admin MCP server](/ai/mintlify-mcp)** lets your own docs team draft pages, run checks, and edit content from their AI editor.
+
+For readers who don't use an AI editor, the [contextual menu](/ai/contextual-menu) gives every page a one-click path into ChatGPT, Claude, or Perplexity:
+
+```json docs.json
+{
+ "contextual": {
+ "options": ["copy", "view", "chatgpt", "claude", "perplexity"]
+ }
+}
+```
+
+Mintlify also generates [`llms.txt`](/ai/llmstxt) (a map of your pages), [`skill.md`](/ai/skillmd) (what agents can do with your product, which can take up to 24 hours to appear), and a [Markdown version of every page](/ai/markdown-export). Add `.md` to any page URL to see exactly what an AI consumer receives.
+
+### Automate a maintenance task
+
+Documentation drifts the moment your product moves. [Automations](/automations) run the agent on a schedule, on a push to a repository, or when something happens in a connected tool, and propose the update as a pull request.
+
+Enable one that maps to something you do by hand today. Drafting a changelog and updating docs from code changes are the clearest starting points. Two settings matter:
+
+- **How updates are applied.** Start with **Require review** so the automation opens a change and waits for a human. Move low-risk jobs to automatic once you trust them.
+- **When it runs.** On content updates, on a schedule, or from pushes in a connected repository.
+
+Then read the run history and open a run to see the exact change it proposed. That log is how you tell your team the automation is doing the right thing. See [Manage automations](/automations/manage).
+
+## Step 7: Loop in IT and security
+
+Bring your IT or security team in during the POC rather than after it, so their questions don't surface during procurement. Start with whichever of these appear in your success criteria.
+
+
+ Authentication requires a custom domain or a `*.mintlify.app` subdomain. It does **not** work on the default `.mintlify.site` URL or on a custom basepath such as `yourcompany.com/docs`. If gating your documentation is part of the POC, sort the domain out first rather than discovering this in the final week.
+
+
+**Who can log into your dashboard**
+
+This is your team, not your readers.
+
+- [Single sign-on](/dashboard/sso) with SAML or OIDC, including Okta, Microsoft Entra, and Google Workspace.
+- [SCIM provisioning](/dashboard/scim) to create and remove accounts automatically from your identity provider.
+- [Network access policies](/dashboard/network-access) to restrict dashboard access to your IP ranges.
+- [Audit logs](/dashboard/audit-logs) and [session security](/dashboard/session-security).
+
+**Who can read your documentation**
+
+This is your readers. Set the [authentication](/deploy/authentication-setup) method to private, then pick how people sign in:
+
+- **Password** is the quickest gate to stand up, and fine for a POC.
+- **Mintlify-managed access** makes your dashboard organization the user list, with no extra configuration.
+- **OAuth 2.0** plugs into the identity provider you already run, and is what most teams end up using.
+- **JWT** gives you full programmatic control when your access model is complex.
+
+Authentication controls who gets in the door. [Groups](/deploy/authentication-setup#control-access-with-groups) control who sees what, set per page in frontmatter:
+
+```yaml
+---
+title: "Production runbook"
+groups: ["engineering"]
+---
+```
+
+Test it with two accounts, not one: sign in as someone in the group and confirm the page appears, then as someone who isn't and confirm it doesn't. That's the difference between access control being enforced and being assumed.
+
+
+ A page marked `hidden: true` is only missing from the navigation. Anyone with the URL can still open it, and this page you're reading is a working example of that. Treat hidden as an organization tool. Authentication and groups are the actual gate. See [Hidden pages](/organize/hidden-pages).
+
+
+**Your domain**
+
+Adding a [custom domain](/customize/custom-domain) needs one DNS record from whoever manages your domain, and Mintlify provisions the TLS certificate automatically. During a POC, point a test subdomain such as `docs-preview.yourcompany.com` at the site rather than your live documentation domain.
+
+**Analytics, checks, and compliance**
+
+- Connect your existing [analytics platform](/integrations/analytics/overview) so documentation traffic lands in the tools you already use.
+- Enable [CI checks](/deploy/ci) to catch broken links and accessibility problems before they publish.
+- For security questionnaires, certifications, and contract review, see [Enterprise contracting](/enterprise-contracting).
+
+## Step 8: Review the results
+
+Book an hour with your decision maker. Open with the one metric you picked in [Pick one thing to prove](#pick-one-thing-to-prove) and the baseline you recorded, then walk the evidence you collected.
+
+| What you're checking | Where to check it |
+|---|---|
+| A non-developer can publish independently | Whether step 4 worked without help, and how long it took |
+| Engineers keep their review process | The pull request your editor change opened, with your existing checks on it |
+| Your hardest content survived the move | Your sample pages, compared side by side with your current site |
+| The assistant answers accurately | Your scored question list, including which page each answer cited |
+| Where your content gaps are | Unanswered and downvoted questions in [Assistant analytics](/analytics/assistant) |
+| Readers find what they need | [Traffic](/analytics/traffic), [search](/analytics/search), and [engagement](/analytics/user-engagements) analytics |
+| Readers say it's better | [Page feedback](/optimize/feedback) |
+| Docs stay current without manual work | The run history of the automation you enabled in step 6 |
+| It meets security requirements | Your IT team's sign-off from step 7 |
+
+Bring open questions to your Mintlify contact before the review, not during it.
+
+## A workable timeline
+
+Most POCs run two to three weeks. Compressing this into a few days is possible, but only if your GitHub administrator and brand assets are ready on day one.
+
+| Week | What happens |
+|---|---|
+| Week 1 | Steps 1 and 2: account, repository, and team. Send your content sample to be migrated, or start migrating it. Agree the one metric and record its baseline. If authentication is in scope, start the custom domain now. |
+| Week 2 | Steps 3 to 6: review the migrated content, publish a change yourself, apply branding, turn on the assistant, and enable one automation. Start scoring your assistant test questions. |
+| Week 3 | Steps 7 and 8: IT and security review, then the results review with your decision maker. |
+
+## Getting help
+
+- **Your shared Slack channel**, for anything time-sensitive during the POC.
+- **[support@mintlify.com](mailto:support@mintlify.com)**, for everything else.
+- **[Advanced support](/advanced-support)**, if you want to know what support looks like after the POC.
+
+## After the POC
+
+
+ Everything to configure and verify before your documentation goes live for real.
+