lightsparkdev · coreymartin · Feb 5, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,8 @@
+# Grid Docs Environment Variables
+# Copy this file to .env and fill in the values
+# DO NOT commit .env to the repository
+
+# Central Icons React Library License
+# Get your license key from https://www.npmjs.com/package/@central-icons-react/all
+# Required for npm run build:icons
+CENTRAL_LICENSE_KEY=your-license-key-here
diff --git a/.gitignore b/.gitignore
@@ -39,3 +39,12 @@ cli/dist/
 # Figma design tokens (local reference only)
 mintlify/tokens/
 
+# Development reference files
+refs/
+figma-*.md
+
+# Cursor IDE rules (personal config)
+.cursor/rules/
+
+# Personal todo files
+TODO-*.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -155,6 +155,46 @@ Webhooks use **P-256 ECDSA signatures** in the `X-Grid-Signature` header for ver
 - Use relative paths for internal links
 - The mintlify subdirectory has its own CLAUDE.md with additional guidance
 
+### Mintlify CLI Version (Important)
+
+**Use Mintlify CLI version 4.2.284** for local development. Newer versions (e.g., 4.2.312) have a bug where the API reference pages render blank when using the palm theme with OpenAPI auto-generation.
+
+**Requires Node.js LTS (v20 or v22)** - Mintlify does not support Node 25+. If you have a newer Node version installed, use Node 22 LTS:
+
+```bash
+# Install Node 22 via Homebrew (if needed)
+brew install node@22
+
+# Run mint dev with Node 22
+export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
+cd mintlify && mint dev
+
+# Or add to ~/.zshrc to make permanent:
+# export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
+```
+
+```bash
+# Check current version
+mintlify --version
+
+# If needed, install the working version
+npm install -g mintlify@4.2.284 --force
+```
+
+### Troubleshooting: API Reference Not Showing
+
+If the API reference pages appear blank (only showing title and navigation, no endpoint details):
+
+1. **Restart the dev server** - hot reload sometimes fails:
+   ```bash
+   pkill -f "mint.*dev"
+   cd mintlify && mint dev
+   ```
+
+2. **Check CLI version** - ensure you're on 4.2.284 (see above)
+
+3. **Verify OpenAPI spec** - run `mint openapi-check openapi.yaml` in the mintlify folder
+
 ### Documentation Philosophy
 
 - **Document just enough** for user success - balance between too much and too little
@@ -163,6 +203,30 @@ Webhooks use **P-256 ECDSA signatures** in the `X-Grid-Signature` header for ver
 - **Check existing patterns** for consistency before making changes
 - **Search before adding** - look for existing information before creating new content
 
+### CSS Styling Tips (Mintlify Overrides)
+
+When overriding Mintlify's default styles in `mintlify/styles/base.css`:
+
+- **Tailwind utility classes are hard to override directly** - Classes like `mb-3.5` have high specificity. Even with `!important` and complex selectors, they often won't budge.
+
+- **Workaround: Use negative margins on sibling elements** - Instead of reducing `margin-bottom` on an element, add negative `margin-top` to the following sibling. This achieves the same visual effect.
+
+- **Test selectors with visible properties first** - If a style isn't applying, add `border: 2px solid red !important;` to confirm the selector is matching. If the border shows, the selector works but something else is overriding your property.
+
+- **HeadlessUI portal elements** - Mobile nav and modals render inside `#headlessui-portal-root`. Use this in selectors for higher specificity: `#headlessui-portal-root #mobile-nav ...`
+
+- **Mobile nav lives in `#mobile-nav`** - Target mobile-specific styles with `#mobile-nav` or `div#mobile-nav` selectors to avoid affecting desktop sidebar.
+
+- **Negative margins for edge-to-edge layouts** - To break out of parent padding (e.g., make nav items edge-to-edge), use negative margins equal to the parent's padding, then add your own padding inside.
+
+### MDX Component Limitations
+
+- **`React.useEffect` breaks the MDX parser** - Mintlify uses acorn to parse MDX, and it chokes on `useEffect`. Avoid using hooks that require cleanup or side effects.
+
+- **`React.useState` works fine** - Simple state management is supported.
+
+- **Keep components simple** - If you need complex interactivity, consider using CSS-only solutions or restructuring to avoid problematic hooks.
+
 ## Environments
 
 - **Production**: `https://api.lightspark.com/grid/2025-10-13`

diff --git a/mintlify/api-reference/authentication.mdx b/mintlify/api-reference/authentication.mdx
@@ -1,5 +1,7 @@
 ---
 title: "Authentication"
+icon: "/images/icons/key2.svg"
+"og:image": "/images/og/og-api-reference.png"
 ---
 import { topLevelProductName } from '/snippets/variables.mdx'
 

diff --git a/mintlify/api-reference/environments.mdx b/mintlify/api-reference/environments.mdx
@@ -1,5 +1,7 @@
 ---
 title: 'Environments'
+icon: "/images/icons/globe.svg"
+"og:image": "/images/og/og-api-reference.png"
 ---
 import { topLevelProductName } from '/snippets/variables.mdx'
 

diff --git a/mintlify/api-reference/terminology.mdx b/mintlify/api-reference/terminology.mdx
@@ -1,6 +1,8 @@
 ---
 title: "Core Concepts"
 description: "Core concepts and terminology for the Grid API"
+icon: "/images/icons/file-text.svg"
+"og:image": "/images/og/og-api-reference.png"
 ---
 
 import Terminology from '/snippets/terminology.mdx';

diff --git a/mintlify/developer-resources/samples.mdx b/mintlify/developer-resources/samples.mdx
@@ -1,12 +1,13 @@
 ---
 title: "Samples"
+icon: "/images/icons/github.svg"
 ---
 
 <Note>
 Explore end-to-end sample apps and snippets in our public repository.
 </Note>
 
-<Card title="Grid Samples on GitHub" icon="github" href="https://github.com/lightsparkdev/grid-api/tree/main/samples">
+<Card title="Grid Samples on GitHub" icon="/images/icons/github.svg" href="https://github.com/lightsparkdev/grid-api/tree/main/samples">
 Browse runnable examples for quickstarts and integrations.
 </Card>
 

diff --git a/mintlify/docs.json b/mintlify/docs.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://mintlify.com/docs.json",
-  "theme": "mint",
+  "theme": "palm",
   "name": "Grid API Documentation",
   "description": "The Grid API enables modern financial institutions to easily send and receive global payments.  The following documentation helps developers understand the Grid API and how to integrate with it.",
   "colors": {
@@ -17,53 +17,57 @@
   "fonts": {
     "heading": {
       "family": "Suisse Intl",
-      "source": "/fonts/suisse-intl/SuisseIntl-Medium.woff2",
-      "format": "woff2",
       "weight": 500
     },
     "body": {
       "family": "Suisse Intl",
-      "source": "/fonts/suisse-intl/SuisseIntl-Regular.woff2",
-      "format": "woff2",
       "weight": 400
     }
   },
-  "favicon": "/favicon.svg",
+  "favicon": {
+    "light": "/favicon-dark.svg",
+    "dark": "/favicon-light.svg"
+  },
   "navigation": {
     "tabs": [
       {
-        "tab": "Home",
-        "pages": ["index"]
-      },
-      {
-        "tab": "Platform Overview",
-        "pages": [
+        "tab": "Get started",
+        "groups": [
           {
-            "group": "Introduction",
+            "group": "Overview",
             "pages": [
+              "index",
               "platform-overview/introduction/what-is-grid",
+              "platform-overview/capabilities",
+              "platform-overview/use-cases",
               "platform-overview/introduction/faq"
             ]
           },
           {
-            "group": "Core Concepts",
+            "group": "Core concepts",
             "pages": [
               "platform-overview/core-concepts/entities",
               "platform-overview/core-concepts/quote-system",
               "platform-overview/core-concepts/account-model",
               "platform-overview/core-concepts/transaction-lifecycle",
-              "platform-overview/core-concepts/currencies-and-rails"
+              "platform-overview/core-concepts/currencies-and-rails",
+              "platform-overview/configuration"
             ]
           }
         ]
       },
       {
         "tab": "Payouts & B2B",
-        "pages": [
-          "payouts-and-b2b/index",
-          "payouts-and-b2b/terminology",
-          "payouts-and-b2b/onboarding/implementation-overview",
-          "payouts-and-b2b/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "payouts-and-b2b/index",
+              "payouts-and-b2b/terminology",
+              "payouts-and-b2b/onboarding/implementation-overview",
+              "payouts-and-b2b/quickstart"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -101,11 +105,16 @@
       },
       {
         "tab": "Ramps",
-        "pages": [
-          "ramps/index",
-          "ramps/terminology",
-          "ramps/onboarding/implementation-overview",
-          "ramps/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "ramps/index",
+              "ramps/terminology",
+              "ramps/onboarding/implementation-overview",
+              "ramps/quickstart"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -141,11 +150,16 @@
       },
       {
         "tab": "Rewards",
-        "pages": [
-          "rewards/index",
-          "rewards/terminology",
-          "rewards/developer-guides/implementation-overview",
-          "rewards/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "rewards/index",
+              "rewards/terminology",
+              "rewards/developer-guides/implementation-overview",
+              "rewards/quickstart"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -179,11 +193,16 @@
       },
       {
         "tab": "Global P2P",
-        "pages": [
-          "global-p2p/index",
-          "global-p2p/terminology",
-          "global-p2p/getting-started/implementation-overview",
-          "global-p2p/quickstart",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "global-p2p/index",
+              "global-p2p/terminology",
+              "global-p2p/getting-started/implementation-overview",
+              "global-p2p/quickstart"
+            ]
+          },
           {
             "group": "Onboarding",
             "pages": [
@@ -247,28 +266,33 @@
   "navbar": {
     "links": [
       {
-        "label": "Github",
+        "label": "GitHub",
         "href": "https://github.com/lightsparkdev/grid-api",
         "icon": "github"
+      },
+      {
+        "label": "Contact sales",
+        "href": "https://www.lightspark.com/contact"
       }
-    ],
-    "primary": {
-      "type": "button",
-      "label": "Contact Sales",
-      "href": "https://lightspark.com/grid#signup"
-    }
+    ]
+  },
+  "modeToggle": {
+    "default": "light",
+    "isHidden": false
   },
   "contextual": {
     "options": ["copy", "view", "chatgpt", "claude"]
   },
-  "footer": {
-    "socials": {
-      "x": "https://x.com/lightspark",
-      "github": "https://github.com/lightsparkdev",
-      "linkedin": "https://linkedin.com/company/lightspark-group"
+  "seo": {
+    "metatags": {
+      "og:image": "/images/og/og-fallback-bg.png",
+      "og:image:width": "1200",
+      "og:image:height": "630"
     }
   },
+  "footer": {},
   "head": {
+    "raw": "<style>#header:empty,#page-title:empty{display:none!important}</style><script>if(location.pathname==='/'||location.pathname==='/index'||location.pathname===''){document.write('<style>header#header,#page-title,#page-context-menu-button,#page-context-menu,.eyebrow,#pagination,[class*=\"space-y-2\"]>*{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important;margin:0!important;padding:0!important}</style>');document.documentElement.classList.add('is-homepage');}</script><style>html.is-homepage #pagination,body.is-homepage #pagination,html.is-homepage #footer,body.is-homepage #footer,html.is-homepage header#header,body.is-homepage header#header,html.is-homepage #page-title,body.is-homepage #page-title,html.is-homepage #page-context-menu-button,body.is-homepage #page-context-menu-button,html.is-homepage #page-context-menu,body.is-homepage #page-context-menu,html.is-homepage .eyebrow,body.is-homepage .eyebrow{display:none!important;visibility:hidden!important;height:0!important;overflow:hidden!important}</style>",
     "links": [
       {
         "rel": "preload",

diff --git a/mintlify/favicon-dark.svg b/mintlify/favicon-dark.svg
diff --git a/mintlify/favicon-light.svg b/mintlify/favicon-light.svg
diff --git a/mintlify/favicon.svg b/mintlify/favicon.svg
diff --git a/mintlify/global-p2p/country-support.mdx b/mintlify/global-p2p/country-support.mdx
@@ -1,6 +1,7 @@
 ---
 title: "Supported Countries"
 description: "Grid availability and payment support"
+icon: "/images/icons/globe.svg"
 ---
 import CountrySupport from '/snippets/country-support.mdx';
 

diff --git a/mintlify/global-p2p/getting-started/implementation-overview.mdx b/mintlify/global-p2p/getting-started/implementation-overview.mdx
@@ -1,6 +1,8 @@
 ---
 title: "Implementation Overview"
 description: "High-level implementation plan for configuring, onboarding, funding, and moving money"
+icon: "/images/icons/code.svg"
+"og:image": "/images/og/og-global-p2p.png"
 ---
 This page gives you a 10,000‑ft view of an end‑to‑end implementation. It is intentionally generalized because the flow supports multiple customer types and external account types (e.g., CLABE, IBAN, US accounts, UPI). The detailed guides that follow provide concrete fields, edge cases, and step‑by‑step instructions.
 

diff --git a/mintlify/global-p2p/getting-started/platform-configuration.mdx b/mintlify/global-p2p/getting-started/platform-configuration.mdx
@@ -1,6 +1,8 @@
 ---
 title: "Platform Configuration"
 description: "Configuring credentials, webhooks and currencies for your platform global P2P payments"
+icon: "/images/icons/settings-gear2.svg"
+"og:image": "/images/og/og-global-p2p.png"
 ---
 import PlatformConfigAPI from '/snippets/platform-config-currency-api-webhooks.mdx';
 import { topLevelProductName } from '/snippets/variables.mdx';