@@ -5,20 +5,19 @@ This workflow regenerates toolkit JSON and opens a PR with the changes. It can b
 ## What it does
 
 1. Builds the toolkit docs generator.
-2. Generates toolkit JSON in `toolkit-docs-generator/data/toolkits` using the Engine tool metadata and summary endpoints.
+2. Generates toolkit JSON in `toolkit-docs-generator/data/toolkits` using the experience API's public tool catalog, which serves tool definitions and toolkit branding in one anonymous read.
 3. Syncs integrations sidebar navigation from the generated JSON.
 4. Creates or updates a PR on the stable `automation/toolkit-docs` branch if any files changed. Later runs overwrite that open PR with the latest generated docs.
 
 ## Inputs and secrets
 
 Required secrets:
 
-- `ENGINE_API_URL`
-- `ENGINE_API_KEY`
 - `ANTHROPIC_API_KEY`
 
 Optional secrets:
 
+- `PUBLIC_CATALOG_URL` (falls back to `https://experience.arcade.dev/api`; set it to run against staging)
 - `ANTHROPIC_MODEL` (falls back to `claude-sonnet-4-6`)
 - `ANTHROPIC_EDITOR_MODEL` (falls back to `claude-sonnet-4-6`)
 
 
@@ -1,5 +1,5 @@
 name: Generate toolkit docs
-# Description: Generate toolkit JSON from Engine API, then sync sidebar navigation.
+# Description: Generate toolkit JSON from the public tool catalog, then sync sidebar navigation.
 # Flow:
 # 1) Generate toolkit JSON into toolkit-docs-generator/data/toolkits
 # 2) Sync integrations sidebar _meta.tsx from toolkit-docs-generator/data/toolkits
@@ -65,9 +65,7 @@ jobs:
             --skip-unchanged \
             --preserve-last-known-good \
             --verbose \
-            --api-source tool-metadata \
-            --tool-metadata-url "$ENGINE_API_URL" \
-            --tool-metadata-key "$ENGINE_API_KEY" \
+            --api-source public-catalog \
             --llm-provider anthropic \
             --llm-model "$ANTHROPIC_MODEL" \
             --llm-api-key "$ANTHROPIC_API_KEY" \
@@ -85,8 +83,10 @@ jobs:
           echo "succeeded=true" >>"$GITHUB_OUTPUT"
         working-directory: toolkit-docs-generator
         env:
-          ENGINE_API_URL: ${{ secrets.ENGINE_API_URL }}
-          ENGINE_API_KEY: ${{ secrets.ENGINE_API_KEY }}
+          # Unset in normal runs: the generator defaults to the production
+          # experience API, which needs no credentials. Set the secret to
+          # point a run at staging or a local BFF.
+          PUBLIC_CATALOG_URL: ${{ secrets.PUBLIC_CATALOG_URL }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
           ANTHROPIC_MODEL: ${{ secrets.ANTHROPIC_MODEL || 'claude-sonnet-4-6' }}
           # Stronger model for the secret-coherence editor. Keeps
 
@@ -19,14 +19,13 @@ flowchart TD
     manual["Manual run<br/>workflow_dispatch"] --> generate
     porter["Porter deploy succeeded<br/>repository_dispatch"] --> generate
 
-    engine["Engine API<br/>/v1/tool_metadata"] -->|"tools, parameters, auth, secrets"| generate
+    catalog["Public tool catalog (experience API)<br/>public/tool_catalog + public/tools"] -->|"tools, parameters, auth, secrets,<br/>category, label, icon, docsLink, flags"| generate
     previous["data/toolkits/*.json<br/>previous run"] -->|"signatures and curation hashes"| generate
 
     generate["generate --all --skip-unchanged"] --> changed{"Changed since<br/>last run?"}
     changed -->|no| skipped["Left untouched"]
     changed -->|yes| merger
 
-    design["@arcadeai/design-system<br/>TOOLKITS"] -->|"category, label, icon, docsLink, flags"| merger
     author["Docs author"] -->|"writes and reviews in a PR"| curation
     curation["curation/toolkit/<br/>chunks/*.mdx<br/>imports/*.mdx<br/>pages/**/*.mdx"] -->|"documentationChunks, customImports, subPages"| merger
     anthropic["Anthropic"] -->|"code examples, summaries, secret edits"| merger
@@ -47,11 +46,18 @@ flowchart TD
 ```
 
 Each field in a toolkit JSON file comes from exactly one of those inputs. The
-Engine API owns everything about a tool, the design system owns everything about
-a toolkit's placement and identity, `curation/` owns hand-authored prose, and the
-LLM owns code examples and summaries. When a source fails, the merger falls back
-to the previous run's file rather than inventing a value, and reports what it
-recovered.
+public catalog owns everything about a tool and about a toolkit's placement and
+identity, `curation/` owns hand-authored prose, and the LLM owns code examples
+and summaries. When a source fails, the merger falls back to the previous run's
+file rather than inventing a value, and reports what it recovered.
+
+The catalog is one read for both halves. The experience API joins the engine's
+operational catalog to design-system branding before the generator sees it, so
+tools and branding always describe the same snapshot. The generator no longer
+reads `@arcadeai/design-system` itself except through the deprecated engine
+sources. When the experience API's branding read fails it returns
+`metadata: null` for a toolkit; the merger substitutes defaults and flags it,
+and `--require-complete` fails the run instead.
 
 `curation/` is the one input a person edits directly. Those Markdown and MDX
 files live in this repository and merge like any other change, so a prose edit
@@ -66,9 +72,8 @@ it. The sidebar sync writes navigation only, and never touches toolkit JSON.
 
 ### Data sources
 
-- `EngineApiSource` fetches tool metadata from the Engine API.
-- `ArcadeApiSource` fetches tool metadata from the Arcade API.
-- `DesignSystemMetadataSource` loads toolkit metadata from `@arcadeai/design-system`.
+- `PublicCatalogApiSource` fetches tools and toolkit branding from the public
+  tool catalog on the experience API, serving both from one cached snapshot.
 - `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
@@ -138,7 +143,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/public-catalog-api.ts` — tools and toolkit branding from the public catalog
 - `src/sources/markdown-curation.ts` — Markdown and MDX curation compiler
   ([format reference](CURATION.md))
 - `src/sources/toolkit-data-source.ts` — unified data source
 
@@ -251,8 +251,7 @@ generation PR, or generate that one toolkit with Engine credentials and run
 ```bash
 ../node_modules/.bin/tsx src/cli/index.ts generate \
   --providers "GoogleFlights" \
-  --tool-metadata-url "$ENGINE_API_URL" \
-  --tool-metadata-key "$ENGINE_API_KEY" \
+  --api-url "$ARCADE_API_URL" \
   --custom-sections ./curation \
   --skip-examples --skip-summary --skip-secret-coherence \
   --output data/toolkits
 
@@ -11,36 +11,45 @@ This guide explains how Arcade generates toolkit JSON, how the GitHub workflow r
 
 ## Data sources
 
-The generator merges three inputs into one JSON output per toolkit:
+The generator merges two inputs into one JSON output per toolkit:
 
-- **Engine API** for tool definitions, auth requirements, and scopes
-- **Arcade design system** for metadata (category, icons, flags)
+- **Public tool catalog** on the experience API for tool definitions, auth
+  requirements, scopes, and toolkit branding (category, label, icon, docs link,
+  pro/BYOC flags) in a single anonymous read
 - **Custom sections file** (optional) for preserved or curated docs content
 
 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 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.
+The catalog lives at `https://experience.arcade.dev/api` by default; override it
+with `--api-url` or `PUBLIC_CATALOG_URL`. The generator fetches one
+complete snapshot from `public/tool_catalog` and `public/tools`, then reuses it
+for change detection, progress calculation, and generation so a run cannot
+compare different API states. Only changed toolkits are regenerated.
+
+The design-system package (`@arcadeai/design-system`) is only consulted by the
+deprecated engine sources. When the experience API cannot reach the design
+system it returns `metadata: null` for a toolkit, and the merger falls back to
+default branding and flags the toolkit; `--require-complete` turns that into a
+hard failure instead.
 
 ## GitHub workflow: generate and sync
 
 The workflow file is `/.github/workflows/generate-toolkit-docs.yml`.
 It runs these steps:
 
 1. Type-check and test the toolkit docs generator.
-2. Generate toolkit JSON using `toolkit-docs-generator` and the Engine API.
+2. Generate toolkit JSON using `toolkit-docs-generator` and the public tool catalog.
 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`
 - `ANTHROPIC_API_KEY` for examples, summaries, and secret-coherence edits
 
 Optional secrets:
 
+- `PUBLIC_CATALOG_URL` (defaults to `https://experience.arcade.dev/api`; set it
+  to point a run at staging or a local BFF)
 - `ANTHROPIC_MODEL` (defaults to `claude-sonnet-4-6` in the workflow)
 - `ANTHROPIC_EDITOR_MODEL` (defaults to `claude-sonnet-4-6` in the workflow)
 
@@ -107,8 +116,7 @@ The summary generator is configured to **never list OAuth scopes** in the genera
 ```bash
 pnpm dlx tsx src/cli/index.ts generate \
   --providers "Github" \
-  --tool-metadata-url "$ENGINE_API_URL" \
-  --tool-metadata-key "$ENGINE_API_KEY" \
+  --api-source public-catalog \
   --llm-provider openai \
   --llm-model gpt-4.1-mini \
   --llm-api-key "$OPENAI_API_KEY" \
@@ -121,7 +129,7 @@ pnpm dlx tsx src/cli/index.ts generate \
 ## Architecture at a glance
 
 - **CLI**: `toolkit-docs-generator/src/cli/index.ts`
-- **Sources**: `src/sources` for Engine API, mock data, and design system metadata
+- **Sources**: `src/sources` for the public catalog, mock data, and the deprecated engine APIs
 - **Merger**: `src/merger/data-merger.ts` merges tools, metadata, and custom sections
 - **Generator**: `src/generator/json-generator.ts` writes JSON and `index.json`
 - **Verifier**: `src/generator/output-verifier.ts` validates output and index consistency
@@ -133,13 +141,15 @@ Run these commands from the `toolkit-docs-generator` directory. Invoke `tsx` by
 path because this directory has no package for `pnpm exec`; the sidebar sync
 command below runs from the repo root instead.
 
+`--api-source public-catalog` is spelled out below because a bare run with no
+catalog or engine environment variables falls back to the mock fixtures.
+
 Generate a single toolkit:
 
 ```bash
 pnpm dlx tsx src/cli/index.ts generate \
   --providers "Github:1.0.0" \
-  --tool-metadata-url "$ENGINE_API_URL" \
-  --tool-metadata-key "$ENGINE_API_KEY" \
+  --api-source public-catalog \
   --llm-provider openai \
   --llm-model gpt-4.1-mini \
   --llm-api-key "$OPENAI_API_KEY" \
@@ -152,8 +162,7 @@ Generate all toolkits:
 pnpm dlx tsx src/cli/index.ts generate \
   --all \
   --skip-unchanged \
-  --tool-metadata-url "$ENGINE_API_URL" \
-  --tool-metadata-key "$ENGINE_API_KEY" \
+  --api-source public-catalog \
   --llm-provider openai \
   --llm-model gpt-4.1-mini \
   --llm-api-key "$OPENAI_API_KEY" \
@@ -165,8 +174,7 @@ Generate without LLM output:
 ```bash
 pnpm dlx tsx src/cli/index.ts generate \
   --providers "Asana:0.1.3" \
-  --tool-metadata-url "$ENGINE_API_URL" \
-  --tool-metadata-key "$ENGINE_API_KEY" \
+  --api-source public-catalog \
   --skip-examples \
   --skip-summary \
   --output data/toolkits
@@ -231,8 +239,10 @@ deletes it and rebuilds `index.json`.
 - `--all` generate all toolkits
 - `--providers` generate a subset of toolkits
 - `--skip-unchanged` only write changed toolkits
-- `--api-source` select `tool-metadata` (default with Engine creds), `list-tools`
-  (only with the explicit flag), or `mock`
+- `--api-source` select `public-catalog` or `mock`. Auto-detects
+  `public-catalog` when `PUBLIC_CATALOG_URL` is set, and `mock` otherwise
+- `--api-url` public catalog base URL including path prefix
+  (default `https://experience.arcade.dev/api`, or `PUBLIC_CATALOG_URL`)
 - `--previous-output` compare against a previous output directory
 - `--custom-sections` load an authoritative Markdown/MDX curation directory
 - `--skip-examples`, `--skip-summary` disable LLM steps
@@ -298,5 +308,5 @@ message and the third, because those are two separate things to fix.
 ## Troubleshooting
 
 - **Nothing regenerated**: `--skip-unchanged` exits early when tool definitions did not change.
-- **Missing metadata**: the generator falls back to the metadata JSON file when design system metadata is unavailable.
+- **Missing metadata**: when the catalog returns `metadata: null` for a toolkit the merger substitutes defaults and warns. Re-run once the experience API's design-system read recovers, or use `--require-complete` to fail instead of publishing defaults.
 - **Verify output fails**: run `pnpm dlx tsx src/cli/index.ts verify-output --output data/toolkits` and fix the reported mismatch.
@@ -1,43 +1,75 @@
-export type ApiSource = "list-tools" | "tool-metadata" | "mock";
+export type ApiSource = "public-catalog" | "mock";
 
 type ApiSourceOptions = {
   apiSource?: string;
-  toolMetadataUrl?: string;
-  toolMetadataKey?: string;
+  apiUrl?: string;
 };
 
-export const resolveApiSource = (options: ApiSourceOptions): ApiSource => {
-  // Explicit source takes precedence
-  if (options.apiSource) {
-    const source = options.apiSource.toLowerCase();
-    if (source === "list-tools") {
-      return "list-tools";
-    }
-    if (source === "engine") {
-      return "tool-metadata";
-    }
-    if (source === "tool-metadata") {
-      return "tool-metadata";
-    }
-    if (source === "mock") {
-      return "mock";
-    }
-    throw new Error(
-      `Invalid --api-source "${options.apiSource}". Use "list-tools", "tool-metadata", or "mock".`
-    );
+const EXPLICIT_API_SOURCES: Record<string, ApiSource> = {
+  "public-catalog": "public-catalog",
+  public: "public-catalog",
+  mock: "mock",
+};
+
+const resolveExplicitApiSource = (apiSource: string): ApiSource => {
+  const resolved = EXPLICIT_API_SOURCES[apiSource.toLowerCase()];
+  if (resolved) {
+    return resolved;
   }
 
-  // Auto-detect based on provided Engine credentials only.
-  // List-tools endpoint must be explicitly selected via --api-source list-tools.
-  const hasToolMetadataKey = !!(
-    options.toolMetadataKey ?? process.env.ENGINE_API_KEY
-  );
-  const hasToolMetadataUrl = !!(
-    options.toolMetadataUrl ?? process.env.ENGINE_API_URL
+  throw new Error(
+    `Invalid --api-source "${apiSource}". Use "public-catalog" or "mock".`
   );
+};
+
+/**
+ * Pick a source from the environment when --api-source is omitted.
+ *
+ * An explicitly configured URL means the caller wants live data. With nothing
+ * set, stay on fixtures rather than reaching out to the network behind the
+ * caller's back, even though the public catalog needs no credentials and
+ * carries its own default URL.
+ */
+const resolveAutoDetectedApiSource = (options: ApiSourceOptions): ApiSource => {
+  const hasApiUrl = resolveApiBaseUrl(options.apiUrl) !== undefined;
 
-  if (hasToolMetadataKey && hasToolMetadataUrl) {
-    return "tool-metadata";
+  if (hasApiUrl) {
+    return "public-catalog";
   }
+
   return "mock";
 };
+
+/**
+ * Treat a blank value as absent.
+ *
+ * An unset GitHub Actions secret still reaches the job as `""`, and `??` would
+ * accept that as a real base URL and build a relative `/public/tool_catalog`
+ * that fetch cannot parse. The nightly wires PUBLIC_CATALOG_URL from an
+ * optional secret, so this is the normal case, not an edge case.
+ */
+const blankToUndefined = (value: string | undefined): string | undefined => {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+};
+
+/**
+ * The catalog now lives on the experience API, whose paths hang off `/api`
+ * rather than the engine's `/v1`. An engine host would build a URL that 404s,
+ * so ARCADE_API_URL and ENGINE_API_URL are deliberately not consulted here.
+ */
+export const resolveApiBaseUrlFromEnv = (): string | undefined =>
+  blankToUndefined(process.env.PUBLIC_CATALOG_URL);
+
+/** The configured base URL, or undefined when neither flag nor env supplies one. */
+export const resolveApiBaseUrl = (
+  apiUrl: string | undefined
+): string | undefined => blankToUndefined(apiUrl) ?? resolveApiBaseUrlFromEnv();
+
+export const resolveApiSource = (options: ApiSourceOptions): ApiSource => {
+  if (options.apiSource) {
+    return resolveExplicitApiSource(options.apiSource);
+  }
+
+  return resolveAutoDetectedApiSource(options);
+};