Skip to main content

​
Mintlify — exact click / paste steps (Weston)

Do this once. Content already lives in the monorepo at apps/docs-mintlify/. You are connecting Mintlify to GitHub so every PR updates the live docs site.

​
DUAL PROJECT? Fix in 5 minutes

If Mintlify shows two deployments or GitHub “connected” twice, follow docs/ops/mintlify-dual-project-fix.md — keep git-synced apps/docs-mintlify, delete the starter Knowledge base project.

​
DONE (2026-08-02 — docs saga closed)

apps/docs-mintlify/ is canonical (ADR-0015). Git sync PASS, starter project deleted, DNS → Mintlify, Vercel docs-web/nelson-docs deleted, Fumadocs apps/docs removed. Live: https://docs.nelsonandassociatesinc.com → Mintlify (cname.mintlify.builders). Content SoT = this directory on main.

​
Prior incident (2026-07-28)

DNS was cut to Mintlify before Git pointed at apps/docs-mintlify — public saw starter “Knowledge base” content. CNAME was restored to Fumadocs. Do not repeat.

​
Desktop steps (60 seconds — org owner browser)

Cloud Browserbase has no Mintlify SSO — only you can finish Git Settings on Desktop Chrome.
  1. Open https://app.mintlify.com/onboarding (or https://mintlify.com/start).
  2. Sign in (Google / email — whatever owns the Nelson Mintlify org).
  3. From Mintlify (not GitHub Settings alone): Manage GitHub access / Add GitHub repo.
  4. When GitHub asks which account: Nelson-Associates-Inc (not westonnelson personal).
  5. Repo access → Only select → nelson-associates-platform → Install/Save.
  6. Back in Mintlify Git Settings, set:
  1. Wait until the file tree shows docs.json / MDX (not empty “Syncing navigation” forever — see below).
  2. Reply in chat:
Domain cutover (docs.* → Mintlify) is a separate step after that reply.

​
1) Create / sign in

  1. Open https://mintlify.com/start (or https://dashboard.mintlify.com).
  2. Sign in with the GitHub / Google account that owns Nelson-Associates-Inc.

​
2) Connect the repo (org, not personal)

Mintlify must see Nelson-Associates-Inc, not westonnelson/*. If the picker only lists westonnelson/... repos:
  1. In Mintlify, tap Manage GitHub access (or open
    https://github.com/apps/mintlify/installations/new ).
  2. On the GitHub install screen, under Install / Authorize, choose the organization Nelson-Associates-Inc (not “westonnelson” personal).
  3. Repository access → Only select repositories →
    nelson-associates-platform → Install / Save.
  4. If GitHub says an org owner must approve: you are the owner — approve it.
  5. Return to Mintlify → Add GitHub repo again. You should now see
    Nelson-Associates-Inc/nelson-associates-platform.
If you landed on personal “Installed GitHub Apps”
(github.com/settings/installations): tap Switch context →
Nelson-Associates-Inc → then Installations → Mintlify → Configure → add nelson-associates-platform. Do not confuse this with pending permission requests for Claude / Cloudflare Workers — those are separate.

​
GitHub App installed on org but Mintlify still broken

GitHub shows a purple warning: do not install Mintlify only through GitHub. Installing on the org from GitHub settings does not attach your Mintlify account. You must finish from Mintlify:
  1. Leave GitHub (leave the org install in place — do not Uninstall).
  2. Open https://app.mintlify.com/onboarding (or dashboard).
  3. Tap Add GitHub repo / Manage GitHub access from Mintlify.
  4. When GitHub asks which account: pick Nelson-Associates-Inc.
  5. Select nelson-associates-platform → path apps/docs-mintlify.

​
Enterprise / org-restricted third-party apps (common failure)

If you authorize Mintlify and it still only lists westonnelson/*:
  1. Open (org owner):
    https://github.com/organizations/Nelson-Associates-Inc/settings/installations
  2. Confirm Mintlify is listed under the org, not only under personal.
  3. If Mintlify is missing:
    https://github.com/apps/mintlify/installations/new
    → choose Nelson-Associates-Inc → Only select → nelson-associates-platform.
  4. If the org blocks third-party apps:
    https://github.com/organizations/Nelson-Associates-Inc/settings/oauth_application_policy
    → allow / approve Mintlify (or temporarily set policy so owners can install GitHub Apps without a request queue).
  5. Do not Revoke/Uninstall after a successful org install — that returns you to personal-only repo lists.

​
Why Cloud Agents cannot click this for you

Mintlify + GitHub App install requires your logged-in browser session as org owner. Probed 2026-07-28 via Browserbase + persisted context: Mintlify landed on /login, GitHub showed signed-out marketing home — no Weston SSO cookies in that context. Local “Claude started debugging this browser” on your Mac is a different session — it is not this Cloud Agent. After you reply mintlify: connected, this agent can Browserbase-verify the .mintlify.site deploy and (with Cloudflare API from Vercel env) apply DNS only when you paste Mintlify’s exact records / say GO. When Mintlify asks for the GitHub repository, use:
When it asks for the docs directory / root path, paste exactly:
(Mintlify monorepo docs also accept a leading slash, e.g. /apps/docs-mintlify — no trailing slash either way.) Deploy branch (scaffold is on main):

​
If the editor says “Syncing navigation” / empty file tree

That banner means Mintlify is git-syncing apps/docs-mintlify (reading docs.json + MDX from the configured branch/path). It is not building the producer portal and cannot fix agency.* mobile UI.
  1. Git Settings → enable docs.json is in a subdirectory → path apps/docs-mintlify (or /apps/docs-mintlify) → Save.
  2. Confirm deployment branch is main.
  3. If the file tree stays empty: editor Settings → Danger zone → Reset editor (discards unpublished editor drafts; forces resync from Git). See https://www.mintlify.com/docs/editor/settings#reset-editor
Baseline docs already exist on origin/main. Learn/Guides nav expands when that content merges to main — it is not required to unblock a stuck empty sync if the subdirectory path is wrong. Scope boundary: Mintlify = public docs only. Producer portal mobile = separate Browserbase session on agency.nelsonandassociatesinc.com, not this dashboard / web agent.

​
3) Project name (optional)

​
4) Custom domain (after G0 — do not cut DNS early)

In Mintlify → Settings → Custom domain, add:
Mintlify shows verification TXT records plus a CNAME. Official pattern (values are exact in your dashboard):
Order (zero-downtime):
  1. Add both TXT records in Cloudflare (zone nelsonandassociatesinc.com).
  2. Keep proxy DNS only (grey cloud) for the docs CNAME when you switch it.
  3. Wait until Mintlify marks TXT verified / TLS pre-provisioned.
  4. Only then change docs CNAME from cname.vercel-dns.com → cname.mintlify.builders (or whatever Mintlify shows).
  5. Click Verify / Retry validation in Mintlify.
Do not point docs at Mintlify before G0 proves content on the *.mintlify.site URL. Today Fumadocs on Vercel remains live until that proof. Paste Mintlify’s panel values into chat (or say GO DNS MINTLIFY with the exact records) and the Cloud Agent can write Cloudflare DNS via API.

​
5) What you do NOT need to do

  • Do not paste MDX into the Mintlify web editor as source of truth.
  • Do not create a second docs repo.
  • Vercel nelson-docs / docs-web is deleted (G6 2026-08-02). Do not recreate.

​
6) When you’re done, reply in chat with

Then this agent will Browserbase-verify the live docs surface and continue the glossary / Search Console → BQ keyword loop.

​
Why this matters (your vision)

Mintlify becomes the agentic + SEO docs surface: glossary and guides that rank in Google, feed llms.txt/agents, and deep-link into quote CTAs for auto / home / life / small business across the 19-state agency footprint — with GA4 / Search Console demand looping into BigQuery so we write the next article from real queries, not guesses.