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

# MINTLIFY WORKFLOW PROMPT

# Prompt: Set up the Mintlify llms.txt + llms-full.txt workflow

> Paste this whole file into a Claude Code session at the repo root. It is
> self-contained — the agent does not need this conversation's history.

***

## Goal

This Mintlify docs project (CreatorDB API docs) needs `llms.txt` and
`llms-full.txt` files at the project root that:

1. Are auto-generated from the OpenAPI spec and the `docs.json` navigation,
   not hand-maintained.
2. Follow the format conventions established in `scripts/generate-llms-full.mjs`
   and the current `llms-full.txt` (see "Format conventions" below).
3. Stay fresh automatically — regenerate on every change to
   `api-v3/api-v3.yaml`, `docs.json`, or any `.mdx` referenced in
   `docs.json`.
4. Override Mintlify's default auto-generated versions, which group entries
   in an order we don't want and produce flat, ungrouped indexes.

You will be extending an existing generator, **not** starting from scratch.

## What already exists

* **`scripts/generate-llms-full.mjs`** — ESM Node script. Parses
  `api-v3/api-v3.yaml`, groups endpoints by tag, renders each one with a
  parameters table, curl example, recursive bullet-list response shape
  (with inline type signatures), and truncated example JSON. Emits
  warnings for missing credit costs, undocumented params, and missing
  `200` responses. Static HEADER / CONCEPTS / APPENDICES blocks frame
  the generated output. Single dep: `yaml`. Editorial knobs (credit
  costs, tag order, shape aliases, source-slug overrides) are in lookup
  tables at the top of the file. Read this file before changing anything.
* **`scripts/package.json`** — Just `yaml` and a `build` script.
* **`Makefile`** — `make refresh-llms` runs the generator. `make verify-llms`
  runs it and fails if the committed files would change (drift check for CI).
* **`llms-full.txt`** — current generated output. \~3,500 lines / \~115 KB,
  covers all 42 endpoints. Read enough of it to internalize the format.
* **`llms.txt`** — currently a hand-maintained index, \~100 lines. The
  workflow needs to start generating this too.

## Why not use Mintlify's auto-generated llms files

Mintlify auto-generates `llms.txt` and `llms-full.txt` from `docs.json`
nav and serves them at the deployed site. We want to override those because:

* The default `llms.txt` is one flat `## Docs` list — no grouping by
  section (API reference vs. concepts vs. app guides vs. FAQs).
* Some entries have truncated descriptions ending in `…` mid-sentence.
* A few entries have no description at all.
* The default `llms-full.txt` doesn't inline OpenAPI content — endpoints
  collapse to a `/api-v3/api-v3.yaml get /path` directive line that's a
  dead pointer in a static text file.
* Mintlify components (`<Tabs>`, `<Frame>`, `<Card>`, etc.) leak through
  raw, breaking heading hierarchy.

A static file at the project root overrides Mintlify's generated one.
That is what we are doing.

## Format conventions (treat as binding)

### `llms-full.txt`

Already implemented. Don't change without reason. Specifically:

* One **top-of-file orientation block**: base URL, auth header, content type,
  pagination semantics, timestamp convention, country-code format, "no sandbox"
  warning, common response envelope. First \~30 lines.
* Endpoints **grouped by tag** in a fixed order: Instagram, TikTok, YouTube,
  Sponsor / Brand, Natural Language Search, Account.
* Each endpoint has: `### METHOD /path — Title` heading, two-line meta
  block (`Source: …md` then `Credits: N` on the next line), one-paragraph
  purpose, parameters table (for simple query params) or bullet list (for
  complex schemas), curl example, **recursive bullet-list response shape**
  with inline type signatures (Claude-platform-docs style: ` - \`field:
  type\` `with description on the next indented line, recursing into
  nested objects and array items down to a depth limit), truncated example
  JSON (arrays capped at 2 items +`"… N more items"`sentinel). Endpoints
  are separated by blank lines, **not**`---\` rules.
* **Shape aliases** (`SHAPE_ALIASES` map): TikTok and YouTube `/audience`
  endpoints reference Instagram's instead of repeating identical shapes.
* **Appendices** at the end. The 250-row country-code table and 770-row
  industry list are linked out, not inlined.
* App user guides and FAQs are **not** included — those belong in a
  separate `llms-full-app.txt` if needed.

### `llms.txt`

Not yet implemented. Build it to match these rules:

* Standard format: `# Title`, optional `> tagline`, then bulleted lists
  under H2 section headings.
* Group entries under named sections instead of one flat `## Docs`:
  * `## API Reference` — every endpoint, grouped by platform sub-bullets
    or sub-headings (Instagram, TikTok, YouTube, Sponsor, NLS, Account).
  * `## Concepts` — auth, custom search filters, NL search guide, error
    codes, credit usage, quickstart, introduction.
  * `## Reference Tables` — country codes, language codes, industry list,
    YT/IG categories.
  * `## OpenAPI Specs` — link to canonical spec(s). Cull duplicates; the
    current file lists 5 ambiguously-named specs.
* Every entry has a non-empty description. Drop trailing `…` truncations —
  rewrite shorter or use the OpenAPI summary directly.
* URLs end in `.md` so an agent following them gets raw markdown, not HTML.

## Tasks

1. **Add `scripts/generate-llms-index.mjs`** (or extend the existing
   generator — your call) that emits `llms.txt`. Pull endpoint titles and
   descriptions from `api-v3/api-v3.yaml` (reuse the spec parser already
   in `generate-llms-full.mjs` — factor it into a shared module if cleaner).
   Pull non-endpoint entries by walking `docs.json` and reading frontmatter
   `title` + `description` from each referenced `.mdx`. Skip pages tagged
   for the app/extension guides — those belong in a separate index if at all.

2. **Update `scripts/package.json`** with whatever new build script you add
   (e.g., `build:full`, `build:index`, `build:all`).

3. **Update the `Makefile`** so `make refresh-llms` regenerates both files.
   `make verify-llms` should fail on drift in either file.

4. **Add a CI workflow** (`.github/workflows/llms-refresh.yml` or similar)
   that:
   * Triggers on push to main affecting `api-v3/api-v3.yaml`, `docs.json`,
     or any `.mdx` under `api-v3/` or `api-reference/`.
   * Runs `make refresh-llms`.
   * Commits the regenerated files back to the branch (or opens a PR if
     pushing to main directly is restricted — check the repo's branch
     protection rules first).
   * On PRs (not push), runs `make verify-llms` instead of regenerating,
     so the PR fails fast when the committed files are stale.

5. **Verify the override actually works.** Mintlify's deploy preview should
   serve the static `llms.txt` and `llms-full.txt` from the project root,
   not its auto-generated ones. Confirm by deploying a preview branch and
   `curl`-ing both URLs on the preview domain. If Mintlify ignores the
   static file, escalate — there may be a config flag in `docs.json`.

## Constraints and traps

* Don't change `llms-full.txt` output unless asked — current consumers
  (downstream LLM clients, possibly cached) depend on the format. If you
  refactor the generator, run `make refresh-llms` and confirm the diff is
  empty before committing.
* Don't pull in heavy deps. The generator currently uses one (`yaml`) and
  Node built-ins. Stay there. No bundlers, no TypeScript build step.
* Keep the script ESM Node, plain `.mjs`. Matches the existing
  `internal/ai-context/scripts/` convention.
* The existing `Makefile` has two targets that hardcode an absolute path
  to a different developer's home (`/Users/debbywang/...`). Do NOT
  replicate that pattern — use relative paths from the Makefile's directory.
* Path-with-space gotcha: this repo lives at `…/API test/…` (literal space).
  Bash `cd` and Make `$(dir $(abspath ...))` need quoting / careful handling.
  Test on this exact path before declaring done.
* If `docs.json` references `.mdx` files that have no frontmatter, the
  current Mintlify build still works but `llms.txt` would have empty
  descriptions. Decide: either skip those pages, fail loudly, or use the
  first `# H1` as a fallback. Pick the option that keeps the index honest.

## How to verify when done

* `make refresh-llms` produces both files with a clean exit.
* `make verify-llms` exits 0 immediately after `refresh-llms`.
* `git diff --stat` after running shows updates in both files when the
  spec changes, none otherwise.
* The new `llms.txt` has section headings (`## API Reference`, etc.),
  every entry has a description, and URLs end in `.md`.
* `llms-full.txt` is byte-identical to the pre-change version unless you
  intentionally changed the format (and got sign-off).
* The CI workflow runs successfully on a test PR that modifies the spec.

Begin by reading `scripts/generate-llms-full.mjs` end-to-end and the first
\~150 lines of the current `llms-full.txt`. Then read `docs.json` and pick
3–5 representative `.mdx` files to understand the frontmatter conventions.
Don't write any code until you can summarize the format rules in your own
words.