Readme (#1)

* Docs: refresh README, remove staging URLs, add CI

Add Dashboard API key link and accuracy policy, point API reference to canonical OpenAPI spec, and add basic CI (docs.json validation + link check + staging guard).

* Email now renders cleanly and stays clickable: [[email protected]](mailto:[email protected])

* Fixed the CI failure by removing the unsupported --exclude-mail flag from .github/workflows/ci.yml. lychee v0.21.0 doesn’t recognize it (it only has --include-mail), so this should unblock the link check without changing anything else.

Author: jonathanpopham

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate docs.json is valid JSON
+        run: jq . docs.json > /dev/null
+
+      - name: Disallow staging URLs in docs
+        run: |
+          if rg -n "staging\\." .; then
+            echo "Found staging URLs. Use production URLs or document/allow staging explicitly."
+            exit 1
+          fi
+
+      - name: Link check
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --verbose
+            --no-progress
+            --accept 200,201,202,203,204,206,301,302,303,307,308,429
+            --max-concurrency 8
+            --timeout 20
+            README.md **/*.mdx

README.md

@@ -1,43 +1,47 @@
-# Mintlify Starter Kit
+# Supermodel API Documentation
 
-Use the starter kit to get your docs deployed and ready to customize.
+Source for the Supermodel API docs site: [docs.supermodeltools.com](https://docs.supermodeltools.com).
 
-Click the green **Use this template** button at the top of this repo to copy the Mintlify starter kit. The starter kit contains examples with
+## Get an API key
 
-- Guide pages
-- Navigation
-- Customizations
-- API reference pages
-- Use of popular components
+Get your API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com/) and send it in the `X-Api-Key` header.
 
-**[Follow the full quickstart guide](https://starter.mintlify.com/quickstart)**
+## Quickstart
 
-## Development
+- **Docs**: [docs.supermodeltools.com](https://docs.supermodeltools.com)
+- **OpenAPI spec (canonical)**: [`supermodeltools/openapi-spec`](https://github.com/supermodeltools/openapi-spec) (`openapi.yaml`)
+- **TypeScript SDK**: [`supermodeltools/typescript-sdk`](https://github.com/supermodeltools/typescript-sdk)
+- **MCP Server**: [`supermodeltools/mcp`](https://github.com/supermodeltools/mcp)
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
+## Updating docs and API reference
 
-```
-npm i -g mint
-```
+- **Pages**: edit the MDX files in the repo root (`index.mdx`, `quickstart.mdx`, `authentication.mdx`, `concepts.mdx`).
+- **API Reference**: this site is driven by the public OpenAPI spec in [`supermodeltools/openapi-spec`](https://github.com/supermodeltools/openapi-spec).
 
-Run the following command at the root of your documentation, where your `docs.json` is located:
+## Accuracy policy
 
-```
-mint dev
-```
+- **Production-first**: examples should target `https://api.supermodeltools.com` and the Dashboard at [dashboard.supermodeltools.com](https://dashboard.supermodeltools.com/).
+- **Spec mismatch?** If the API behavior differs from the spec, file an issue on [`supermodeltools/openapi-spec`](https://github.com/supermodeltools/openapi-spec).
+- **Docs issue?** File an issue on this repo.
 
-View your local preview at `http://localhost:3000`.
+## Support
 
-## Publishing changes
+- **Email**: [[email protected]](mailto:[email protected])
 
-Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
+## Local development (docs repo only)
 
-## Need help?
+These instructions are only for previewing changes to `supermodel-api-docs` locally.
 
-### Troubleshooting
+Install the `mint` CLI:
 
-- If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
-- If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
+```bash
+npm i -g mint
+```
+
+Run the dev server from this repo root (where `docs.json` lives):
+
+```bash
+mint dev
+```
 
-### Resources
-- [Mintlify documentation](https://mintlify.com/docs)
+Preview at `http://localhost:3000`.

authentication.mdx

@@ -4,10 +4,10 @@ description: 'How to authenticate your API requests'
 icon: 'key'
 ---
 
-The Supermodel API uses API keys to authenticate requests. You can view and manage your API keys in the [Supermodel Dashboard](https://staging.dashboard.supermodeltools.com/).
+The Supermodel API uses API keys to authenticate requests. You can view and manage your API keys in the [Supermodel Dashboard](https://dashboard.supermodeltools.com/).
 
 <Info>
-  **Using the API Playground**: The interactive playground in this documentation connects to our staging environment. Generate an API key from the [Staging Dashboard](https://staging.dashboard.supermodeltools.com/) to test endpoints directly from these docs.
+  **Using the API Playground**: The interactive playground in this documentation connects to our production API. Generate an API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com/) to test endpoints directly from these docs.
 </Info>
 
 ## Authentication Header
@@ -37,7 +37,7 @@ Here's how to include the headers in a cURL request:
 
 ```bash
 curl --request POST \
-  --url https://staging.api.supermodeltools.com/v1/graphs/dependency \
+  --url https://api.supermodeltools.com/v1/graphs/dependency \
   --header "Idempotency-Key: $(uuidgen)" \
   --header 'X-Api-Key: <your-api-key>' \
   --header 'Content-Type: multipart/form-data' \

docs.json

@@ -1,5 +1,4 @@
 {
-  "$schema": "https://mintlify.com/docs.json",
   "theme": "mint",
   "name": "Supermodel API",
   "colors": {
@@ -38,7 +37,7 @@
       },
       {
         "tab": "API Reference",
-        "openapi": "https://api.supermodeltools.com/supermodel-public.yaml"
+        "openapi": "https://raw.githubusercontent.com/supermodeltools/openapi-spec/main/openapi.yaml"
       }
     ]
   },
@@ -56,14 +55,13 @@
     "primary": {
       "type": "button",
       "label": "Dashboard",
-      "href": "https://supermodeltools.com"
+      "href": "https://dashboard.supermodeltools.com/"
     }
   },
   "footer": {
     "socials": {
-      "x": "https://x.com/mintlify",
-      "github": "https://github.com/mintlify",
-      "linkedin": "https://linkedin.com/company/mintlify"
+      "x": "https://x.com/supermodeltools",
+      "github": "https://github.com/supermodeltools"
     }
   }
 }

index.mdx

@@ -8,7 +8,7 @@ description: 'Welcome to the Supermodel API documentation'
 Supermodel provides a unified graph representation of your codebase, enabling powerful analysis and visualization tools.
 
 <Info>
-  **Try the API Playground**: Each endpoint in our API Reference includes an interactive playground. To use it, you'll need an API key from the [Supermodel Dashboard](https://staging.dashboard.supermodeltools.com/).
+  **Try the API Playground**: Each endpoint in our API Reference includes an interactive playground. To use it, you'll need an API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com/).
 </Info>
 
 ## API Reference

overrides.css

@@ -9,6 +9,33 @@ html.dark, body.dark, .dark {
   --tw-ring-offset-color: #000000 !important;
 }
 
+.dark .bg-background-dark {
+  background-color: #000000 !important;
+}
+
+.dark .bg-background-light {
+  background-color: #000000 !important;
+}
+
+.dark main {
+  background-color: #000000 !important;
+}
+
+.dark nav, .dark aside {
+  background-color: #000000 !important;
+  border-right-color: #1F1F1F !important;
+}
+:root {
+  --bg-dark: #000000 !important;
+  --bg-default: #000000 !important;
+  --bg-background-dark: #000000 !important;
+}
+
+html.dark, body.dark, .dark {
+  background-color: #000000 !important;
+  --tw-ring-offset-color: #000000 !important;
+}
+
 /* Force black on all major layout containers */
 .dark .bg-background-dark {
   background-color: #000000 !important;
@@ -106,13 +133,3 @@ html.dark, body.dark, .dark {
   background-color: #000000 !important;
 }
 
-/* NUKE UNWANTED GLOBAL LINKS */
-a[href^="https://mintlify.com/docs"],
-a[href^="https://mintlify.com/blog"] {
-  display: none !important;
-}
-
-li:has(a[href^="https://mintlify.com/docs"]),
-li:has(a[href^="https://mintlify.com/blog"]) {
-  display: none !important;
-}

quickstart.mdx

@@ -8,7 +8,7 @@ This guide will walk you through generating a **Dependency Graph** from a local
 
 ## Prerequisites
 
-1. **API Key**: You'll need a Supermodel API key. Get one from the [Dashboard](https://staging.dashboard.supermodeltools.com/).
+1. **API Key**: You'll need a Supermodel API key. Get one from the [Dashboard](https://dashboard.supermodeltools.com/).
 2. **Codebase**: A local folder containing the code you want to analyze.
 3. **Tools**: `zip` and `curl` installed on your machine.
 
@@ -27,7 +27,7 @@ Use the `dependency` endpoint to generate a graph of file-level dependencies. Re
 
 ```bash
 curl --request POST \
-  --url https://staging.api.supermodeltools.com/v1/graphs/dependency \
+  --url https://api.supermodeltools.com/v1/graphs/dependency \
   --header "Idempotency-Key: $(uuidgen)" \
   --header 'X-Api-Key: <your-api-key>' \
   --header 'Content-Type: multipart/form-data' \