docs: migrate Mintlify to Holocron on Cloudflare

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.6
+          bun-version: 1.4.2
 
       - name: Install dependencies
         run: bun install --frozen-lockfile

.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Docs - Build, Deploy and Index
+
+on:
+  pull_request:
+    paths:
+      - apps/docs/**
+      - bun.lock
+      - package.json
+      - patches/**
+      - .github/workflows/docs.yml
+  push:
+    branches: [main]
+    paths:
+      - apps/docs/**
+      - bun.lock
+      - package.json
+      - patches/**
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    defaults:
+      run:
+        working-directory: apps/docs
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.4.2
+      - name: Install dependencies
+        working-directory: .
+        run: bun install --frozen-lockfile
+      - name: Check types
+        run: bun run check-types
+      - name: Build Cloudflare Worker
+        run: bun run build
+      - name: Deploy docs
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && vars.DOCS_CLOUDFLARE_ENABLED == 'true'
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          test -n "$CLOUDFLARE_API_TOKEN" || { echo "CLOUDFLARE_API_TOKEN is required"; exit 1; }
+          test -n "$CLOUDFLARE_ACCOUNT_ID" || { echo "CLOUDFLARE_ACCOUNT_ID is required"; exit 1; }
+          bun run deploy
+      - name: Index published docs in Supermemory
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && vars.DOCS_CLOUDFLARE_ENABLED == 'true'
+        env:
+          DOCS_SITE_URL: ${{ vars.DOCS_SITE_URL }}
+          DOCS_CANONICAL_URL: https://supermemory.ai/docs/
+          DOCS_CONTAINER_TAG: supermemory_docs
+          SUPERMEMORY_API_KEY: ${{ secrets.SUPERMEMORY_DOCS_API_KEY }}
+        run: bun run index-docs

apps/docs/.gitignore

@@ -24,3 +24,8 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .idea
 
 .DS_Store
+
+.holocron-public
+.holocron-openapi.json
+.holocron
+.wrangler

apps/docs/README.md

@@ -1 +1,93 @@
-# supermemory Docs
+# Supermemory docs
+
+Holocron builds the public MDX documentation and OpenAPI reference into a Cloudflare Worker mounted at `/docs/`.
+
+## Development
+
+Use Bun 1.4.2 or newer; older releases fail when applying the compatibility patch's nested files. From the repository root, run `bun install`, then:
+
+```sh
+cd apps/docs
+bun run dev:app
+bun run check-types
+bun run build
+bunx wrangler dev --local --port 3003
+```
+
+The local site is at `http://localhost:3003/docs/`. Assets remain in the existing image, icon, logo, and video directories; preparation copies only public assets into the build input. Preparation downloads the public API specification and adds the existing API-page URLs from `scripts/api-paths.json`.
+
+Preparation also renders page-specific PNG social cards from the original thumbnail background, logo and licensed Geist fonts. The Worker serves these static assets; image previews no longer call Holocron's hosted OG renderer. Frontmatter `og:image` overrides still take precedence.
+
+For a Capy public preview of local Wrangler, pass `--var DOCS_PREVIEW_ORIGIN:https://<exact-preview-host>.capysandbox.net` to `wrangler dev`. This opt-in adapter accepts that exact browser origin only when the runtime request URL is loopback; it does not alter production same-origin checks or trust forwarded-host headers. Production reverse proxies must preserve the public request origin. Without this local-only setting, the assistant rejects the preview proxy's different origin with HTTP 403.
+
+## Production setup
+
+Deployment is disabled until the repository variable `DOCS_CLOUDFLARE_ENABLED` is `true`. PRs always validate the build; enabled production deployments run after pushes to `main` or a manual workflow run on `main`.
+
+Configure these GitHub Actions values:
+
+| Kind | Name | Purpose |
+| --- | --- | --- |
+| Secret | `CLOUDFLARE_API_TOKEN` | Deploy the docs Worker and its static assets. |
+| Variable | `CLOUDFLARE_ACCOUNT_ID` | Select the Cloudflare account. |
+| Variable | `DOCS_SITE_URL` | Direct deployed URL, including `/docs/`, such as `https://supermemory-docs.<account>.workers.dev/docs/`. |
+| Secret | `SUPERMEMORY_DOCS_API_KEY` | Index the public docs in a dedicated Supermemory project. |
+| Variable | `DOCS_CLOUDFLARE_ENABLED` | Set to `true` only after the Worker and indexing credentials are ready. |
+
+Add that same Supermemory key to the Worker as `SUPERMEMORY_API_KEY`, without committing it:
+
+```sh
+bunx wrangler secret put SUPERMEMORY_API_KEY
+```
+
+The Worker uses its `AI` binding for answer generation and `CHAT_RATE_LIMITER` for an approximate per-IP limit of ten questions per minute per Cloudflare location. Workers AI usage is billed to the Cloudflare account.
+
+### Cutover
+
+First deploy and inspect the direct Workers URL while Mintlify remains live. Keep `https://supermemory.ai/docs/` as the canonical URL. Switch the existing `/docs/*` proxy or Cloudflare route to this Worker only after verification; forward the full path without stripping `/docs`. Preserve the rest of the main website. The Wrangler configuration does not change public DNS or routes automatically.
+
+Same-site redirects use relative paths so previews and reverse-proxy deployments keep the browser on the public origin.
+
+The API playground sends requests directly from the browser to the selected API server, not through the docs Worker. Before cutover, deploy the API's exact CORS allowance for `https://supermemory.ai`; arbitrary direct-Worker and preview origins are not allowed by the production API. Verify requests from the canonical website after routing it to the new Worker. Playground keys are transient and are cleared when closing the playground or changing servers.
+
+Mintlify's repository integration does not run Holocron's preparation step, so it cannot fetch the generated OpenAPI file or validate generated API-page links. Its deployment and link checks fail against this migration. Before merging, retire the legacy repository deployment integration and replace any required Mintlify checks with the `Docs - Build, Deploy and Index` build job. Keep the existing Mintlify-hosted site live until the routing cutover is verified.
+
+## Documentation indexing
+
+```text
+main push -> build -> deploy Worker -> fetch llms.txt and each .md export
+                                       -> add new / replace changed pages
+                                       -> wait for processing
+                                       -> remove deleted pages
+```
+
+Only public exported documentation is indexed, including generated API pages. Source code, secrets, and PR previews are not indexed. `taskType: "superrag"` makes the material searchable without building user profiles. Unchanged content is skipped; deleted pages are removed only after the full inventory has synced successfully. If indexing fails, the deployed site remains available and the workflow fails; rerun it to reconcile the index.
+
+Use a separate Supermemory project for documentation so visitor questions cannot retrieve other customer data. The indexing container and assistant both use `supermemory_docs`. The assistant retrieves document chunks, generates a plain-text answer with Workers AI, and returns source links. Questions are not stored as memories.
+
+The header assistant, Ctrl+I/⌘I shortcut, inline page question box, page actions, and code-sample prompts use this same-site backend without adding a standalone assistant page to the original navigation. Conversations live only in the current tab's memory, with up to six prior messages sent for a follow-up. The server validates canonical page URLs, bounded code context, alternating user/assistant history, request size, origin, and the existing rate limit. Closing the drawer preserves the in-tab conversation; “New conversation” clears it. No questions or answers are written to browser storage or indexed as memories.
+
+The original `contextual.options` controls the page-action menu. Markdown copies fetch the same-site `.md` export; MCP and editor actions use the canonical `https://supermemory.ai/docs/mcp` endpoint. The copied `npx -y mcp-remote` command starts a local stdio bridge to that endpoint and does not use Mintlify's hosted MCP service.
+
+Page-helpfulness votes go to the `supermemory_docs_feedback` Cloudflare Analytics Engine dataset. Each event contains only the public page path and a yes/no value; no question, answer, browser identifier or IP is stored. The endpoint applies the same origin validation and rate-limit policy as chat.
+
+`/docs/mcp` keeps public documentation search available to coding agents through a stateless Streamable HTTP MCP server. Its `search_docs` tool uses the same index; the documentation resource exposes the complete Markdown export without an LLM call.
+
+To validate exports without an API key or writes:
+
+```sh
+DOCS_SITE_URL=http://localhost:3003/docs/ \
+DOCS_CANONICAL_URL=https://supermemory.ai/docs/ \
+bun run index-docs --dry-run
+```
+
+`DOCS_CANONICAL_URL` separates the fetch origin from citation URLs, so indexing the direct Worker URL does not leak that hostname into answers. Syncs must run one at a time for a site and container; the production workflow serializes them.
+
+## Compatibility boundaries
+
+- The pinned Holocron dependency uses a committed Bun compatibility patch. Keep that patch applied when installing; revalidate it before upgrading the renderer.
+- Original tabs, nested anchors, SVG strokes, brand images and authored element styling are preserved. Existing page paths and redirects remain stable.
+- Global search covers page titles, headings and public documentation body text. The body index loads from the same-site Markdown inventory on first use and stays in the current tab's memory; search remains local after that download.
+- `api.playground.display: "interactive"` enables browser-side API requests with transient credentials, parameter/body controls and response display. No request credentials are sent to the docs Worker.
+- Recursive filter schemas are expanded until a recursive boundary, which is labeled rather than expanded indefinitely. `/docs/openapi.json` serves the complete recursive specification.
+- The built-in Holocron hosted assistant is disabled. Original assistant entry points use the custom Supermemory-backed documentation backend; real answer verification requires the Worker AI binding, the documentation-only API key, and a populated index.

apps/docs/api-reference/overview.mdx

@@ -1,10 +1,10 @@
 ---
 title: "API reference"
-description: "Interactive reference for the Supermemory HTTP API: ingest, search, profiles, memories, connectors and settings."
+description: "Reference for the Supermemory HTTP API: ingest, search, profiles, memories, connectors and settings."
 icon: "/icons/hugeicons/plug-socket.svg"
 ---
 
-This is the **contract-level** reference for Supermemory: methods, paths, parameters, and the playground.
+This is the **contract-level** reference for Supermemory: methods, paths, parameters, and SDK request examples. The reference is read-only; run requests with an SDK or cURL.
 
 For narrative guides (when to use what, patterns, SDKs), start with the [Quickstart](/quickstart) and [Using supermemory](/ingestion/add-memories).
 

apps/docs/authentication.mdx

@@ -9,7 +9,9 @@ icon: "/icons/hugeicons/key-01.svg"
 
 All API requests require authentication using a Bearer token. Get your API key from the [Developer Platform](https://console.supermemory.ai).
 
-<Snippet file="getting-api-key.mdx" />
+import GettingApiKey from "./snippets/getting-api-key.mdx"
+
+<GettingApiKey />
 
 Include your key in all requests:
 
@@ -117,4 +119,4 @@ curl https://api.supermemory.ai/v3/auth/scoped-key/KEY_ID \
 
 ```json
 { "success": true }
-```
+```

apps/docs/docs.json

@@ -1,6 +1,14 @@
 {
-	"$schema": "https://mintlify.com/docs.json",
+	"$schema": "https://holocron.so/schema.json",
+	"decorativeLines": "none",
+	"assistant": {
+		"enabled": false
+	},
+	"feedback": { "endpoint": "/api/feedback" },
 	"api": {
+		"playground": {
+			"display": "interactive"
+		},
 		"examples": {
 			"defaults": "required",
 			"languages": ["typescript", "python", "bash"],
@@ -64,6 +72,7 @@
 		"library": "lucide"
 	},
 	"logo": {
+		"text": "Docs",
 		"dark": "/logo/dark.svg",
 		"light": "/logo/light.svg"
 	},
@@ -289,7 +298,7 @@
 					{
 						"anchor": "API reference",
 						"icon": "/icons/hugeicons/plug-socket.svg",
-						"openapi": "https://api.supermemory.ai/v4/openapi",
+						"openapi": ".holocron-openapi.json",
 						"pages": [
 							"api-reference/overview",
 							"authentication",
@@ -383,7 +392,8 @@
 									"POST /v3/settings/reset"
 								]
 							}
-						]
+						],
+						"base": "api-reference"
 					}
 				],
 				"tab": "Developer platform"

apps/docs/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

apps/docs/fonts/README.md

@@ -0,0 +1 @@
+These are static 400/600 weight instances of Geist 1.800 from the Google Fonts `ofl/geist/Geist[wght].ttf` distribution. They render social-preview images at build time, without a hosted image renderer or system fonts. The accompanying OFL.txt is the upstream font license.

apps/docs/icons/LICENSE-vscode.txt

@@ -0,0 +1,23 @@
+The VS Code glyph in vscode.svg is from Material Design Icons via Iconify.
+Its color is adapted to currentColor.
+
+Pictogrammers Free License
+--------------------------
+
+This icon collection is released as free, open source, and GPL friendly by
+the Pictogrammers (http://pictogrammers.com/) icon group. You may use it
+for commercial projects, open source projects, or anything really.
+
+Icons: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+Some of the icons are redistributed under the Apache 2.0 license. All other
+icons are either redistributed under their respective licenses or are
+distributed under the Apache 2.0 license.
+
+Fonts: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+All web and desktop fonts are distributed under the Apache 2.0 license. Web
+and desktop fonts contain some icons that are redistributed under the Apache
+2.0 license. All other icons are either redistributed under their respective
+licenses or are distributed under the Apache 2.0 license.
+
+Code: MIT (https://opensource.org/licenses/MIT)
+The MIT license applies to all non-font and non-icon files.