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

# Editing these docs

> How the Mintlify documentation is structured and previewed.

Documentation is Mintlify, docs-as-code: MDX files in `docs/`, configured by `docs/docs.json`,
versioned alongside the application.

## Preview locally

```bash theme={null}
npm run docs:dev
```

That runs the Mintlify CLI against `docs/` and serves the site at `http://localhost:3000`
with hot reload.

<Warning>
  The CLI is intentionally **not** a devDependency. Installed into this project's
  `node_modules`, `@mintlify/previewing` resolves the app's React 19 instead of its own
  bundled copy and crashes with `Invalid hook call`. The `docs:*` scripts therefore run it
  through `npx --yes mint@latest`, which resolves in an isolated npx cache. The first run
  downloads the CLI; later runs are cached.

  If you prefer a persistent install, `npm i -g mint` also works — just never
  `npm i -D mint` here.
</Warning>

<Note>
  Mintlify requires Node 20.17 or newer. Since Vite 6 already requires a modern Node, any
  environment that can build the app can preview the docs.
</Note>

Before opening a PR:

```bash theme={null}
npm run docs:check   # broken links
```

For a stricter gate — the full build, failing on warnings as well as errors:

```bash theme={null}
cd docs && npx --yes mint@latest validate
```

## Structure

```
docs/
├── docs.json                  Navigation, theme, metadata
├── index.mdx                  Introduction
├── quickstart.mdx
├── development.mdx
├── architecture/
│   ├── overview.mdx
│   ├── data-model.mdx
│   ├── visibility-pipeline.mdx
│   └── scheduling.mdx
├── configuration/
│   ├── environment.mdx
│   ├── ai-providers.mdx
│   └── integrations.mdx
└── contributing/
    ├── workflow.mdx
    └── documentation.mdx
```

## Adding a page

<Steps>
  <Step title="Create the MDX file">
    Put it in the folder matching its section, with frontmatter:

    ```mdx theme={null}
    ---
    title: "Page title"
    description: "One line describing the page."
    ---
    ```
  </Step>

  <Step title="Register it in the navigation">
    Add the path — without the `.mdx` extension, relative to `docs/` — to the right group in
    `docs.json`:

    ```json theme={null}
    {
      "group": "Architecture",
      "pages": ["architecture/overview", "architecture/your-new-page"]
    }
    ```

    Mintlify resolves paths without the extension, so `index.mdx` is `index` and
    `architecture/overview.mdx` is `architecture/overview`. A page that is not listed in
    `docs.json` is not reachable in the sidebar.
  </Step>

  <Step title="Preview and check links">
    ```bash theme={null}
    npm run docs:dev
    npm run docs:check
    ```
  </Step>
</Steps>

## Components available

Mintlify ships MDX components used throughout these pages: `<Card>` / `<CardGroup>`,
`<Steps>` / `<Step>`, `<Accordion>` / `<AccordionGroup>`, `<Tabs>` / `<Tab>`, and the callouts
`<Note>`, `<Tip>`, `<Warning>`, `<Info>` and `<Check>`. Fenced code blocks accept a language
and an optional title:

````mdx theme={null}
```bash Run a batch manually
php artisan weekly:prompt-batch --force
```
````

## Keeping docs accurate

These pages state concrete defaults — scoring weights, model names, schedule times, rate
limits. When you change any of the following, update the corresponding page in the same PR:

| Change                              | Page to update                                                                |
| ----------------------------------- | ----------------------------------------------------------------------------- |
| `config/ai.php` providers or models | [AI providers](/configuration/ai-providers)                                   |
| `config/scoring.php` weights        | [Overview](/architecture/overview), [Environment](/configuration/environment) |
| `routes/console.php` schedule       | [Jobs and scheduling](/architecture/scheduling)                               |
| New `.env` variable                 | [Environment reference](/configuration/environment)                           |
| New model or relationship           | [Data model](/architecture/data-model)                                        |
| New job or command                  | [Visibility pipeline](/architecture/visibility-pipeline)                      |

## Deployment

Mintlify deploys from the repository once the GitHub app is connected to it — pushes to the
default branch publish automatically, with no build step in this project's CI. Connect the repo
and point the project at the `docs/` directory from the Mintlify dashboard.