Harden toolkit-doc generation against destructive failures

toolkit-docs-generator/ARCHITECTURE.md

@@ -58,16 +58,33 @@ It can also verify output consistency with `OutputVerifier`.
 The generator output is consumed by the Next.js app:
 
 - The app loads JSON from `toolkit-docs-generator/data/toolkits/`.
-- Toolkit pages are statically generated using those files.
+- `generateStaticParams` enumerates the toolkit routes and disables unknown dynamic parameters.
 - Custom documentation chunks are rendered as MDX in the UI.
 
 If you need HTML output, add a separate build step in the app. The generator intentionally avoids HTML to keep the pipeline deterministic.
 
-## Static page generation
+## Vercel build
 
-Static generation happens in the app, not in this generator.
+The generator does not run during a Vercel build. The generation workflow commits
+the JSON files and navigation changes through a pull request. Vercel then runs the
+root `pnpm build` command and compiles the committed files with Next.js.
 
-The generator only provides JSON and markdown content. The app turns those into static HTML during its build.
+`app/_lib/toolkit-static-params.ts` enumerates routes from `index.json` and the
+per-toolkit files. `app/_lib/toolkit-data.ts` reads the same files for page
+rendering and the `/api/toolkit-data/[toolkitId]` route. The root layout reads
+request headers, so Vercel reports the docs routes as dynamic even though the
+toolkit parameter set is fixed at build time.
+
+## Search indexing
+
+Search uses an external Algolia crawler. There is no Pagefind or local search
+index build step in this repository. After deployment, the crawler indexes the
+rendered site. `app/_components/algolia-search.tsx` queries that index with the
+public, read-only values configured through these Vercel environment variables:
+
+- `NEXT_PUBLIC_ALGOLIA_APP_ID`
+- `NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY`
+- `NEXT_PUBLIC_ALGOLIA_INDEX_NAME`
 
 ## Key files
 

toolkit-docs-generator/README.md

@@ -19,30 +19,29 @@ The generator merges three inputs into one JSON output per toolkit:
 
 It also reads the previous output when you use `--skip-unchanged` or `--previous-output`.
 
-When `--skip-unchanged` runs against the tool metadata API, the generator calls
-the summary endpoint (`/v1/tool_metadata_summary`) first to decide which toolkits
-need updates. It only fetches full tool metadata from `/v1/tool_metadata` for
-toolkits with version changes. The Engine API guarantees that tool definitions
-do not change unless the toolkit version changes.
+When `--skip-unchanged` runs against the tool metadata API, the generator fetches
+one complete snapshot from `/v1/tool_metadata`. It reuses that snapshot for
+change detection, progress calculation, and generation so a run cannot compare
+different API states. Only changed toolkits are regenerated.
 
 ## GitHub workflow: generate and sync
 
 The workflow file is `/.github/workflows/generate-toolkit-docs.yml`.
 It runs these steps:
 
-1. Generate toolkit JSON using `toolkit-docs-generator` and the Engine API.
-2. Sync sidebar navigation from `toolkit-docs-generator/data/toolkits` to the `_meta.tsx` files.
-3. Create a pull request if there are changes.
+1. Type-check and test the toolkit docs generator.
+2. Generate toolkit JSON using `toolkit-docs-generator` and the Engine API.
+3. Sync sidebar navigation from `toolkit-docs-generator/data/toolkits` to the `_meta.tsx` files.
+4. Create or update a pull request if there are changes.
 
 Required secrets:
 
 - `ENGINE_API_URL`, `ENGINE_API_KEY`
-- `OPENAI_API_KEY` for LLM examples and summaries
+- `ANTHROPIC_API_KEY` for examples, summaries, and secret-coherence edits
 
 Optional secrets:
 
-- `OPENAI_MODEL` (defaults in the workflow)
-- `ANTHROPIC_API_KEY` enables the secret-coherence editor (see below). Without it the workflow still runs; the scanners emit warnings but no LLM edits are applied.
+- `ANTHROPIC_MODEL` (defaults to `claude-sonnet-4-6` in the workflow)
 - `ANTHROPIC_EDITOR_MODEL` (defaults to `claude-sonnet-4-6` in the workflow)
 
 ## Rendering pipeline (docs site)

toolkit-docs-generator/src/cli/generate-flow.ts

@@ -15,6 +15,21 @@ export const collectRemovedToolkitIds = (
       .map((c) => c.toolkitId.toLowerCase())
   );
 
+/**
+ * Protect incremental runs from treating a transient empty API response as a
+ * request to delete every previously generated toolkit.
+ */
+export const assertSafeCurrentToolkitSnapshot = (
+  currentToolkitCount: number,
+  previousToolkitCount: number
+): void => {
+  if (currentToolkitCount === 0 && previousToolkitCount > 0) {
+    throw new Error(
+      `Current toolkit snapshot is empty; refusing to remove all ${previousToolkitCount} existing toolkits.`
+    );
+  }
+};
+
 export interface ProcessingStats {
   totalToolkits: number;
   effectiveSkipped: number;