fix: give hand-authored toolkit prose a source home in curation/

.github/workflows/generate-toolkit-docs.yml

@@ -70,6 +70,7 @@ jobs:
             --llm-concurrency 15 \
             --exclude-file ./remove-toolkits.txt \
             --ignore-file ./skip-toolkits.txt \
+            --custom-sections ./curation \
             --output data/toolkits
         working-directory: toolkit-docs-generator
         env:

biome.jsonc

@@ -133,6 +133,7 @@
       "!node_modules",
       "!public",
       "!toolkit-docs-generator/data/toolkits",
+      "!toolkit-docs-generator/curation",
       "!scripts",
       "!agents",
       "!.vscode",

package.json

@@ -65,6 +65,7 @@
     "swagger-ui-react": "5.32.6",
     "tailwindcss-animate": "1.0.7",
     "unist-util-visit": "5.1.0",
+    "yaml": "2.8.3",
     "zod": "4.3.6"
   },
   "devDependencies": {

toolkit-docs-generator/ARCHITECTURE.md

@@ -12,7 +12,7 @@ The generator does **not** render HTML. It produces structured JSON and optional
 
 1. Fetch tool definitions from the Engine API or Arcade API.
 2. Load toolkit metadata from the design system or mock metadata.
-3. Load custom sections from JSON files (optional).
+3. Compile hand-authored Markdown and MDX curation (optional).
 4. Merge all data into `MergedToolkit` objects.
 5. Write a JSON file per toolkit and an `index.json` file.
 6. Optionally verify output and compute diffs.
@@ -24,7 +24,10 @@ The generator does **not** render HTML. It produces structured JSON and optional
 - `EngineApiSource` fetches tool metadata from the Engine API.
 - `ArcadeApiSource` fetches tool metadata from the Arcade API.
 - `DesignSystemMetadataSource` loads toolkit metadata from `@arcadeai/design-system`.
-- `CustomSectionsFileSource` loads custom documentation chunks from a JSON file.
+- `MarkdownCurationSource` compiles documentation chunks, import declarations,
+  and subpages from the configured curation directory. When configured, that
+  directory is globally authoritative: a missing toolkit directory means the
+  toolkit has no authored curation.
 - `CombinedToolkitDataSource` merges tools and metadata into one interface.
 
 ### Merger
@@ -90,6 +93,7 @@ public, read-only values configured through these Vercel environment variables:
 ## Key files
 
 - `src/sources/engine-api.ts` — tool metadata from Engine API
+- `src/sources/markdown-curation.ts` — Markdown and MDX curation compiler
 - `src/sources/toolkit-data-source.ts` — unified data source
 - `src/merger/data-merger.ts` — merge pipeline
 - `src/generator/json-generator.ts` — output writer

toolkit-docs-generator/README.md

@@ -232,12 +232,26 @@ deletes it and rebuilds `index.json`.
 - `--api-source` select `tool-metadata` (default with Engine creds), `list-tools`
   (only with the explicit flag), or `mock`
 - `--previous-output` compare against a previous output directory
-- `--custom-sections` load curated docs sections
+- `--custom-sections` load an authoritative Markdown/MDX curation directory
 - `--skip-examples`, `--skip-summary` disable LLM steps
 - `--skip-secret-coherence` disable the stale-reference scan + coverage fill (see the Secret coherence section)
 - `--llm-editor-provider`, `--llm-editor-model`, `--llm-editor-api-key` configure the secret-coherence editor (Sonnet 4.6 by default)
 - `--no-verify-output` skip output verification
 
+## Authored curation
+
+Store authored content below `curation/<toolkit>/`. Put injectable sections in
+`chunks/*.mdx`, import declarations in `imports/*.mdx`, and rich subpages in
+`pages/**/*.mdx`. Each file begins with YAML frontmatter for structured placement
+metadata; its body is the Markdown or MDX that readers see. Import files use
+`type: import` and contain one ESM import declaration.
+
+When `--custom-sections` is set, the directory is authoritative for every
+toolkit. Removing the final curation file for a toolkit clears that toolkit's
+authored prose on the next generation run. Invalid frontmatter, invalid MDX,
+unknown tool targets, symlinks, unsafe subpage paths, and leftover JSON curation
+fail generation instead of silently falling back to stale generated content.
+
 ## Troubleshooting
 
 - **Nothing regenerated**: `--skip-unchanged` exits early when tool definitions did not change.

toolkit-docs-generator/curation/airtableapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/arcadeengineapi/chunks/001-secrets.mdx

@@ -0,0 +1,15 @@
+---
+type: section
+location: custom_section
+position: after
+header: "## Secrets"
+---
+## Secrets
+
+This MCP Server requires the `ARCADE_API_KEY` secret to be configured. Learn how to [configure secrets](/guides/create-tools/tool-basics/create-tool-secrets).
+
+### Getting your Arcade API Key
+
+To use the Arcade Engine API MCP Server, you need an Arcade API key. This key authenticates your requests to the Arcade Engine.
+
+Learn how to create and manage your Arcade API keys in the [API Keys documentation](/get-started/setup/api-keys).

toolkit-docs-generator/curation/arcadeengineapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/asana/chunks/001-auth-after-markdown.mdx

@@ -0,0 +1,6 @@
+---
+type: markdown
+location: auth
+position: after
+---
+The Arcade Asana MCP Server uses the [Asana auth provider](/references/auth-providers/asana) to connect to users' Asana accounts.

toolkit-docs-generator/curation/asanaapi/chunks/001-auth.mdx

@@ -0,0 +1,8 @@
+---
+type: markdown
+location: auth
+position: after
+header: "## Auth"
+---
+The AsanaApi MCP Server uses the Auth Provider with id `arcade-asana` to connect to users' AsanaApi accounts. In order to use the MCP Server, you will need to configure the `arcade-asana` auth provider.
+For detailed information on configuring the Asana OAuth provider with Arcade, see the [Asana Auth Provider documentation](/references/auth-providers/asana).

toolkit-docs-generator/curation/asanaapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/ashbyapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/boxapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/brightdata/chunks/001-secrets.mdx

@@ -0,0 +1,29 @@
+---
+type: section
+location: custom_section
+position: after
+header: "## Secrets"
+---
+## Secrets
+
+This tool requires the following secrets:
+
+- `BRIGHTDATA_API_KEY`
+- `BRIGHTDATA_ZONE`
+
+### Auth
+
+The Arcade Bright Data MCP Server uses [Bright Data](https://brightdata.com/) to access proxy networks and web scraping infrastructure.
+
+**Global Environment Variables:**
+
+- `BRIGHTDATA_API_KEY`: Your Bright Data API key. You can generate this from your [Bright Data dashboard](https://brightdata.com/cp/zones) under Account Settings → API Access.
+
+- `BRIGHTDATA_ZONE`: Your Bright Data zone name (e.g., `residential_proxy1`). This is the zone identifier you created in your Bright Data dashboard under Proxies & Scraping Infrastructure → Zones.
+
+**How to get your credentials:**
+
+1. **API Key**: Navigate to your [Bright Data Control Panel](https://brightdata.com/cp) → Settings → API Access → Generate API Token
+2. **Zone**: Go to Zones section in your dashboard, find your zone name in the format shown in the zone username: `brd-customer-{customer_id}-zone-{zone_name}`
+
+For more details, see the [Bright Data API Documentation](https://docs.brightdata.com/api-reference).

toolkit-docs-generator/curation/calendlyapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/clickup/chunks/001-taskpriority.mdx

@@ -0,0 +1,12 @@
+---
+type: section
+location: custom_section
+position: after
+header: "## TaskPriority"
+---
+## TaskPriority
+
+- **URGENT**: `URGENT`
+- **HIGH**: `HIGH`
+- **NORMAL**: `NORMAL`
+- **LOW**: `LOW`

toolkit-docs-generator/curation/clickup/chunks/002-taskorderby.mdx

@@ -0,0 +1,11 @@
+---
+type: section
+location: custom_section
+position: after
+header: "## TaskOrderBy"
+---
+## TaskOrderBy
+
+- **CREATED**: `created`
+- **UPDATED**: `updated`
+- **DUE_DATE**: `due_date`

toolkit-docs-generator/curation/clickup/chunks/003-commentresolution.mdx

@@ -0,0 +1,10 @@
+---
+type: section
+location: custom_section
+position: after
+header: "## CommentResolution"
+---
+## CommentResolution
+
+- **SET_AS_RESOLVED**: `resolved`
+- **SET_AS_UNRESOLVED**: `unresolved`

toolkit-docs-generator/curation/clickupapi/chunks/001-auth.mdx

@@ -0,0 +1,8 @@
+---
+type: markdown
+location: auth
+position: after
+header: "## Auth"
+---
+The ClickupApi MCP Server uses the Auth Provider with id `arcade-clickup` to connect to users' ClickupApi accounts. In order to use the MCP Server, you will need to configure the `arcade-clickup` auth provider.
+For detailed information on configuring the ClickUp OAuth provider with Arcade, see the [ClickUp Auth Provider documentation](/references/auth-providers/clickup).

toolkit-docs-generator/curation/clickupapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/confluence/chunks/001-auth-after-markdown.mdx

@@ -0,0 +1,7 @@
+---
+type: markdown
+location: auth
+position: after
+---
+The Arcade Confluence MCP Server uses the [Atlassian auth provider](/references/auth-providers/atlassian) to connect to users' Atlassian accounts.
+---

toolkit-docs-generator/curation/cursoragentsapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/customerioapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/customeriopipelinesapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/customeriotrackapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/datadogapi/chunks/001-authentication.mdx

@@ -0,0 +1,29 @@
+---
+type: section
+location: before_available_tools
+position: after
+header: "## Authentication"
+---
+## Authentication
+
+The Arcade Datadog API MCP Server requires three environment variables to authenticate with the [Datadog API](https://docs.datadoghq.com/api/latest/):
+
+- `DATADOG_API_KEY`
+- `DATADOG_APPLICATION_KEY`
+- `DATADOG_BASE_URL`
+
+**How to obtain your credentials:**
+
+1. Log in to your [Datadog dashboard](https://app.datadoghq.com/)
+2. Navigate to **Organization Settings** (click your profile icon in the bottom left)
+3. Go to **API Keys** → click **New Key** → provide a name and click **Create Key**
+4. Go to **Application Keys** → click **New Key** → provide a name and click **Create Key**
+5. Determine your **Base URL** based on your Datadog site (check the URL in your browser):
+   - US1: `api.datadoghq.com`
+   - US3: `api.us3.datadoghq.com`
+   - US5: `api.us5.datadoghq.com`
+   - EU1: `api.datadoghq.eu`
+   - AP1: `api.ap1.datadoghq.com`
+   - GOV: `api.ddog-gov.com`
+
+For more details, see the [Datadog API and Application Keys documentation](https://docs.datadoghq.com/account_management/api-app-keys/).

toolkit-docs-generator/curation/datadogapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/dropbox/chunks/001-auth-after-markdown.mdx

@@ -0,0 +1,6 @@
+---
+type: markdown
+location: auth
+position: after
+---
+The Arcade Dropbox MCP Server uses the [Dropbox auth provider](/references/auth-providers/dropbox) to connect to users' Dropbox accounts.

toolkit-docs-generator/curation/e2b/chunks/001-auth-after-markdown.mdx

@@ -0,0 +1,8 @@
+---
+type: markdown
+location: auth
+position: after
+---
+The Arcade E2B MCP Server uses [E2B](https://e2b.dev/) to run code in a sandboxed environment.
+**Global Environment Variables:**
+- `E2B_API_KEY`: Your [E2B](https://e2b.dev/) API key.

toolkit-docs-generator/curation/exaapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/figma/chunks/001-auth-after-markdown.mdx

@@ -0,0 +1,9 @@
+---
+type: markdown
+location: auth
+position: after
+---
+<Callout type="warning" title="Private OAuth app requirement">
+The `projects:read` scope is **ONLY available in private Figma OAuth apps**. This scope is required for the navigation tools (`GetTeamProjects` and `GetProjectFiles`). 
+If you need these navigation tools, you must create a private OAuth app through your Figma organization settings. All other tools work with public OAuth apps.
+</Callout>

toolkit-docs-generator/curation/figmaapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/firecrawl/chunks/001-auth-after-markdown.mdx

@@ -0,0 +1,8 @@
+---
+type: markdown
+location: auth
+position: after
+---
+The Arcade Firecrawl MCP Server uses [Firecrawl](https://www.firecrawl.dev/) to scrape, crawl, and map websites.
+**Global Environment Variables:**
+- `FIRECRAWL_API_KEY`: Your [Firecrawl](https://www.firecrawl.dev/) API key.

toolkit-docs-generator/curation/freshserviceapi/imports/001.mdx

@@ -0,0 +1,4 @@
+---
+type: import
+---
+import StarterToolInfo from "@/app/_components/starter-tool-info";

toolkit-docs-generator/curation/github/chunks/001-description-after-warning.mdx

@@ -0,0 +1,12 @@
+---
+type: warning
+location: description
+position: after
+---
+<Callout type="warning">
+  **Critical**: This MCP Server is built for **GitHub Apps**, not OAuth Apps.
+
+  You **must** create a GitHub App (not an OAuth App) to use this server properly. 
+
+  👉 [Complete GitHub App Setup Guide](/references/auth-providers/github)
+</Callout>

toolkit-docs-generator/curation/github/chunks/002-description-after-info.mdx

@@ -0,0 +1,8 @@
+---
+type: info
+location: description
+position: after
+---
+<Callout type="info">
+  **Configuration**: On Arcade Cloud, these tools work out of the box. Self-hosted and GitHub Enterprise Server users can set the `GITHUB_SERVER_URL` secret in Arcade Dashboard. See [Secrets Setup](#secrets-setup) below.
+</Callout>