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

# SETUP

# NexusFeed Docs Site — Setup Runbook

This folder contains a fully populated Mintlify docs site: 1 config (`docs.json`), 1 landing page, 1 quickstart, 1 auth, 1 verifiability contract, 2 product overviews, 10 carrier SEO pages, 5 state SEO pages, 2 MCP pages. The API Reference tab is auto-generated by Mintlify from `https://api.nexusfeed.dev/openapi.json` — you do not need to write any API reference MDX files.

Target outcome: `https://docs.nexusfeed.dev` live, indexed by Google, ready to be the landing surface for the Show HN post and the 20 cold emails.

**Estimated founder time: 45-75 minutes.** All of it is clicking in web UIs — no coding required past this point.

***

## Part 1 — Create the public GitHub repo (5 min)

Mintlify deploys docs from a GitHub repo. This folder (`docs-site/`) lives inside the private `B2B Agentic Arbitrage Hub` repo for convenience, but the public docs site needs its own public repo.

1. Go to [https://github.com/organizations/NexusFeed/repositories/new](https://github.com/organizations/NexusFeed/repositories/new) (assumes you own the `NexusFeed` org — if not, create it first at [https://github.com/organizations/new](https://github.com/organizations/new), free tier is fine).
2. Repository name: **`nexusfeed-docs`**
3. Description: *Public documentation for NexusFeed — LTL fuel surcharge and ABC liquor license data APIs.*
4. **Public** visibility. No README, no .gitignore, no license (we'll push a populated repo).
5. Click **Create repository**.
6. Note the clone URL: `https://github.com/NexusFeed/nexusfeed-docs.git`

Then, from the project root, push this `docs-site/` folder to the new repo:

```bash theme={null}
cd "c:/Users/ladou/Documents/B2B Agentic Arbitrage Hub/docs-site"
git init
git add .
git commit -m "Initial docs site — 10 carriers, 5 states, verifiability contract"
git branch -M main
git remote add origin https://github.com/NexusFeed/nexusfeed-docs.git
git push -u origin main
```

<details>
  <summary>If <code>git push</code> asks for credentials</summary>

  Use a GitHub personal access token as the password. Create one at [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new) with `repo` scope.
</details>

***

## Part 2 — Connect the repo to Mintlify (10 min)

1. Go to [https://mintlify.com/start](https://mintlify.com/start) and sign in with GitHub.
2. Authorize Mintlify to access the `NexusFeed/nexusfeed-docs` repository (you can grant access to just that one repo).
3. Mintlify will scan the repo and detect `docs.json`. It should auto-deploy a preview URL like `https://nexusfeed.mintlify.app` within 1-2 minutes.
4. Open the preview URL and click through the pages to sanity-check:
   * Home page renders
   * All 10 carrier pages in the sidebar
   * All 5 state pages in the sidebar
   * API Reference tab loads from the live OpenAPI spec
5. If the API Reference tab shows an error, verify `https://api.nexusfeed.dev/openapi.json` loads directly in a browser. It should. If it doesn't, Mintlify can't reach it — check Railway logs and CORS.

<details>
  <summary>If the preview shows broken images</summary>

  The `docs.json` references `/logo/light.svg`, `/logo/dark.svg`, and `/favicon.svg` — these don't exist yet. Mintlify will show a placeholder until you add them. To create quick placeholders:

  ```bash theme={null}
  # Run from docs-site/ folder — requires ImageMagick or just use any SVG
  mkdir -p logo
  # Create a 1-line SVG placeholder that says "NexusFeed"
  echo '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 40"><text x="10" y="28" font-family="sans-serif" font-size="24" font-weight="bold" fill="#0B6FFF">NexusFeed</text></svg>' > logo/light.svg
  echo '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 40"><text x="10" y="28" font-family="sans-serif" font-size="24" font-weight="bold" fill="#FFFFFF">NexusFeed</text></svg>' > logo/dark.svg
  echo '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#0B6FFF"/><text x="50%" y="60%" text-anchor="middle" font-family="sans-serif" font-size="16" font-weight="bold" fill="white">N</text></svg>' > favicon.svg
  git add logo favicon.svg
  git commit -m "Add placeholder logo + favicon"
  git push
  ```

  Replace with real assets once the site is live. Logo should be roughly 200x40px for the navbar.
</details>

***

## Part 3 — Connect the custom domain `docs.nexusfeed.dev` (15 min)

Once the Mintlify preview looks good, point your custom subdomain at it.

### 3a. In Mintlify

1. Open the Mintlify dashboard for the `nexusfeed-docs` project.
2. Go to **Settings → Custom Domain**.
3. Enter `docs.nexusfeed.dev`.
4. Mintlify will show you a CNAME target, typically `cname.vercel-dns.com` or `cname.mintlify.app` — **copy this value**.

### 3b. In Cloudflare

1. Log into Cloudflare and select the `nexusfeed.dev` zone.
2. Go to **DNS → Records**.
3. Click **Add record**:
   * Type: **CNAME**
   * Name: **docs**
   * Target: *(the value from Mintlify, e.g. `cname.mintlify.app`)*
   * Proxy status: **DNS only (gray cloud)** — Mintlify serves its own TLS, so Cloudflare's proxy isn't needed and may cause SSL issues
   * TTL: Auto
4. Save.

### 3c. Verify

Wait 2-5 minutes for DNS propagation, then:

```bash theme={null}
curl -sI https://docs.nexusfeed.dev | head -n 1
```

Expected: `HTTP/2 200`. If you get `404`, wait another minute and retry — Mintlify's TLS provisioning can take a couple of minutes after the CNAME lands.

Also visit `https://docs.nexusfeed.dev` in a browser and confirm:

* The custom domain is shown in the address bar
* The TLS certificate is valid (padlock icon)
* All pages load correctly

***

## Part 4 — Submit to Google Search Console (10 min)

This is the step that turns the docs site from "exists" into "indexed and discoverable via Google."

1. Go to [https://search.google.com/search-console](https://search.google.com/search-console) and sign in.
2. Click **Add property**.
3. Choose **URL prefix** (not Domain) — enter `https://docs.nexusfeed.dev`.
4. Google will ask you to verify ownership. The easiest method is **HTML tag**:
   * Copy the meta tag Google gives you (it looks like `<meta name="google-site-verification" content="...">`).
   * Add it to `docs.json` under a top-level `"metadata"` field, or add an `index.html` override — Mintlify supports custom head tags via a `"metadata"` block like:
     ```json theme={null}
     "metadata": {
       "google-site-verification": "paste_the_content_value_here"
     }
     ```
   * Commit, push, wait for Mintlify to redeploy (\~1 min), then click **Verify** in Google Search Console.
5. Once verified, go to **Sitemaps** in the left sidebar.
6. Mintlify auto-generates `/sitemap.xml`. Enter `sitemap.xml` and click **Submit**.
7. Google will show "Success" and begin crawling. First pages usually appear in the index within 48-72 hours.

### Also submit to Bing Webmaster Tools (5 min, optional but cheap)

1. Go to [https://www.bing.com/webmasters](https://www.bing.com/webmasters).
2. Click **Add site** → enter `https://docs.nexusfeed.dev`.
3. Use the **Import from Google Search Console** option — it auto-verifies using your existing GSC credentials. No separate meta tag needed.
4. Submit the sitemap: `https://docs.nexusfeed.dev/sitemap.xml`.

Bing traffic is a fraction of Google's, but it feeds ChatGPT's web search and Copilot, so it's relevant for AEO.

***

## Part 5 — Sanity-check SEO readiness (5 min)

Before you link to `docs.nexusfeed.dev` from a Show HN post or a cold email, verify:

```bash theme={null}
# Check each of these returns 200 and proper content
curl -sI https://docs.nexusfeed.dev | head -n 1
curl -sI https://docs.nexusfeed.dev/quickstart | head -n 1
curl -sI https://docs.nexusfeed.dev/verifiability | head -n 1
curl -sI https://docs.nexusfeed.dev/carriers/odfl | head -n 1
curl -sI https://docs.nexusfeed.dev/states/california-abc | head -n 1
curl -sI https://docs.nexusfeed.dev/sitemap.xml | head -n 1
```

Then in a browser, open the home page and **View Source** — confirm:

* `<title>` includes "NexusFeed"
* `<meta name="description">` is present with a useful description
* OpenGraph tags exist (`og:title`, `og:description`, `og:image`) so social previews render cleanly

If the OpenGraph image is broken or missing, Mintlify supports a `"og:image"` field in `docs.json` under `"metadata"`. Add a real OG image (1200x630px PNG) — this matters because it's what HN, Twitter, and LinkedIn will show when the link is shared.

***

## Part 6 — Write the Show HN post (90-120 min, separate session)

With the docs site live, this is the next action from the GTM plan. See the plan file at `C:\Users\ladou\.claude\plans\resilient-spinning-scott.md` section 4, Action #2. The skeleton:

* **Title**: "Show HN: Scraping 10 LTL carrier fuel surcharges and 5 state liquor license databases into one MCP server"
* **Length**: 1200-1800 words
* **Narrative**: lead with the Illinois Akamai bypass story (it's the best technical anecdote), move into the 10-carrier breakdown, explain the `_verifiability` contract as the key design decision, close with a "try it" CTA linking to `docs.nexusfeed.dev`.
* **Canonical publish location**: Dev.to or your own `docs.nexusfeed.dev/blog/...` route if you add one.
* **Cross-post**: Hacker News (Show HN), Lobste.rs, r/programming, r/SideProject, r/webscraping, Indie Hackers milestone.
* **Post timing**: Tuesday or Wednesday, 8-10am ET. Avoid weekends and late nights.

***

## Part 7 — Write and send the 20 cold emails (90-120 min, separate session)

See plan file Action #3. The skeleton:

* **List source**: Apollo free tier or Hunter.io. Target 3PL CTOs, freight broker heads-of-engineering, logistics SaaS founders (Loadsmart, Convoy alumni, Flock Freight alumni), liquor compliance software teams (Provi, Sevenfifty).
* **Email format**: 4 sentences, not a pitch, a question. Ends with a link to `docs.nexusfeed.dev`.
* **Delivery**: Manual sends from personal Gmail. No automation, no sequences.
* **Response plan**: Reply within 2 hours to any reply.

***

## Troubleshooting

### "Mintlify build failed"

Check the build log in the Mintlify dashboard. The most common causes:

* Invalid JSON in `docs.json` (trailing commas, unquoted keys)
* A page referenced in `navigation.tabs[].groups[].pages` that doesn't exist as an MDX file
* Frontmatter missing from an MDX file (every page needs `---` block with `title` and `description`)

### "API Reference tab is empty"

Mintlify can't fetch `https://api.nexusfeed.dev/openapi.json`. Check:

* Railway deploy is healthy (visit `https://api.nexusfeed.dev/health`)
* CORS allows Mintlify's origin (should — FastAPI default CORS is permissive for unauthenticated GETs on `/openapi.json`)

### "docs.nexusfeed.dev returns 404 but [www.docs.nexusfeed.dev](http://www.docs.nexusfeed.dev) works"

Cloudflare's proxy is enabled (orange cloud) and interfering with Mintlify's TLS. Switch the CNAME record to **DNS only (gray cloud)**.

### "Google Search Console says 'couldn't verify'"

The meta tag didn't make it into the rendered HTML. Check:

* The `metadata` field is at the top level of `docs.json`, not nested inside `navigation`
* Mintlify has redeployed since you pushed the change
* `View Source` on the home page shows the `<meta name="google-site-verification" ...>` tag

***

## Rollback

If anything goes wrong and you want to pull the site down temporarily:

1. In the Mintlify dashboard → Settings → delete the custom domain `docs.nexusfeed.dev`.
2. In Cloudflare → DNS → delete the `docs` CNAME record.
3. The preview URL `https://nexusfeed.mintlify.app` (or whatever Mintlify assigned) will still work for editing.
4. Re-add the custom domain when ready.

Content rollback is via `git revert` on the `nexusfeed-docs` repo — Mintlify rebuilds automatically on every push.