> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelsonandassociatesinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CONNECT

# 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](https://app.mintlify.com/onboarding)** (or [https://mintlify.com/start](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:

```
repo: Nelson-Associates-Inc/nelson-associates-platform
branch: main
docs.json in subdirectory: ON
path: apps/docs-mintlify
```

7. Wait until the file tree shows `docs.json` / MDX (not empty “Syncing
   navigation” forever — see below).
8. Reply in chat:

```
mintlify: connected
domain: pending
```

Domain cutover (`docs.*` → Mintlify) is a **separate** step after that reply.

***

## 1) Create / sign in

1. Open **[https://mintlify.com/start](https://mintlify.com/start)** (or [https://dashboard.mintlify.com](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](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](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](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](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](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:

```
Nelson-Associates-Inc/nelson-associates-platform
```

When it asks for the **docs directory / root path**, paste exactly:

```
apps/docs-mintlify
```

(Mintlify monorepo docs also accept a leading slash, e.g. `/apps/docs-mintlify` —
no trailing slash either way.)

**Deploy branch** (scaffold is on `main`):

```
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](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)

```
Nelson & Associates Docs
```

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

In Mintlify → **Settings → Custom domain**, add:

```
docs.nelsonandassociatesinc.com
```

Mintlify shows verification **TXT** records plus a **CNAME**. Official pattern
(values are exact in your dashboard):

```text theme={null}
TXT   | _acme-challenge.docs | <value from Mintlify dashboard>
TXT   | _cf-custom-hostname.docs | <value from Mintlify dashboard>
CNAME | docs | cname.mintlify.builders
```

**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

```
mintlify: connected
domain: pending|verified
```

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.