fix: give hand-authored toolkit prose a source home in curation/ (#1112)

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

documentationChunks, customImports, and subPages have no upstream
source — they lived only inside the generated data/toolkits/*.json and
survived by carry-forward from the previous artifact. --force-regenerate
and --overwrite-output set the previous-output directory to undefined,
silently deleting all hand-authored prose (82 chunks and 2 subpages
across 75 toolkits).

Extract that prose into per-toolkit curation/<toolkitId>.json files and
read them back through --custom-sections, which the merger treats as
authoritative over carry-forward. The nightly workflow now passes
--custom-sections ./curation, so a forced regeneration preserves prose
instead of wiping it.

- custom-sections-file source now loads a directory of per-toolkit files
  (single-file layout still supported)
- scripts/extract-curation.ts is the one-time, re-runnable extractor
- curation/ is excluded from biome like its sibling data/toolkits/
- regression test asserts prose survives --force-regenerate

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix: satisfy the strict generator typecheck in the curation extractor

scripts/ is not type-checked today; #1106 widens the generator project
to cover it, and under exactOptionalPropertyTypes plus
noUncheckedIndexedAccess this PR's files do not compile. Fixing it here
keeps the PR green whichever order the two land in.

- isNonEmptyArray returned boolean, so it narrowed nothing and the
  caller compensated with an 'as DocumentationChunk[]' cast. Making it a
  type predicate narrows properly and lets the cast go.
- previousToolkit is declared optional but --force-regenerate and
  --overwrite-output pass it explicitly as undefined, which
  exactOptionalPropertyTypes rejects. The type now says '| undefined',
  matching what callers actually do — that explicit undefined is the
  exact scenario the prose regression test covers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix: let the curation extractor run from any working directory

The sibling generator scripts (validate-merge, sync-toolkit-sidebar,
check-stale-summaries, report-tool-metadata) resolve data/toolkits
through the shared resolver, which anchors on the repo root. This script
used bare relative paths, so it only worked when invoked from
toolkit-docs-generator/ and failed from the root — two conventions for
the same directory.

Anchor on the script's own location instead, matching how
verify-toolkit-join, sync-toolkit-sidebar, and validate-merge already
use import.meta.url. It now works from either directory. Verified from
both: identical output, 75 files.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix: regenerate toolkits when curation changes

* fix: let curation clear prose and show up in check-changes

When a curation file exists, treat its contents as authoritative so an
empty {} file deletes hand-authored prose instead of carrying it forward.
check-changes now diffs curation against committed artifacts too.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: satisfy strict types in custom-sections-diff test

Use valid MergedToolkit metadata and documentation chunk types so the
generator typecheck passes under the widened tsconfig from main.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: preserve curation provenance

* refactor toolkit curation to MDX

* narrow MDX curation refactor scope

* fix: load default curation during generation

* fix: preserve curated toolkit imports

* fix: fail generation on unknown curated tool targets

Validate curated `tool:` targets before the recoverable merge path so a
mistyped target fails the run instead of landing in preserve-last-known-good
recovery, where the toolkit would keep stale data and drop the chunk while CI
stayed green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

.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": {

pnpm-lock.yaml

@@ -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/ARCHITECTURE.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/README.md

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

toolkit-docs-generator/curation/airtableapi/imports/001.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/chunks/001-secrets.mdx

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

toolkit-docs-generator/curation/arcadeengineapi/imports/001.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.