@contentful/experience-design-system-cli 2.26.6-dev-build-ef7b167.0 → 2.26.6-dev-build-8dec003.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.26.6-dev-build-ef7b167.0",
+  "version": "2.26.6-dev-build-8dec003.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -44,7 +44,7 @@
     "commander": "^13.1.0",
     "ink": "^4.4.1",
     "react": "^18.3.1",
-    "react-devtools-core": "^4.28.5",
+    "react-devtools-core": "^4.19.1",
     "react-dom": "^18.3.1",
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
@@ -56,7 +56,7 @@
     "@contentful/experience-design-system-generation": "workspace:*",
     "@tsconfig/node24": "^24.0.4",
     "@types/node": "^24.0.3",
-    "@types/react": "^18.3.31",
+    "@types/react": "^18.3.24",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",

package/dist/src/index.js

@@ -118,6 +118,16 @@ function parseToolCallLines(stdout) {
       if (typeof rec.reason === "string")
         call.reason = rec.reason;
       calls.push(call);
+    } else if (tool === "exclude_prop") {
+      if (typeof rec.prop !== "string" || !rec.prop) {
+        warnings.push("exclude_prop missing prop name \u2014 skipped");
+        continue;
+      }
+      calls.push({
+        tool: "exclude_prop",
+        prop: rec.prop,
+        reason: typeof rec.reason === "string" ? rec.reason : ""
+      });
     } else if (tool === "classify_component") {
       const call = { tool: "classify_component" };
       if (typeof rec.description === "string")
@@ -373,7 +383,7 @@ var init_agent_runner = __esm({
     "use strict";
     init_agent_names();
     VALID_SELECT_TOOL_NAMES = /* @__PURE__ */ new Set(["select_component", "reject_component"]);
-    VALID_TOOL_NAMES = /* @__PURE__ */ new Set(["classify_prop", "classify_component", "classify_slot"]);
+    VALID_TOOL_NAMES = /* @__PURE__ */ new Set(["classify_prop", "exclude_prop", "classify_component", "classify_slot"]);
     VALID_TOKEN_TOOL_NAMES = /* @__PURE__ */ new Set(["set_token", "set_group"]);
     VALID_CDF_TYPES = /* @__PURE__ */ new Set(["string", "richtext", "media", "enum", "token", "boolean"]);
     VALID_CATEGORIES = /* @__PURE__ */ new Set(["content", "design", "state"]);
@@ -542,26 +552,28 @@ All input data is provided inline below \u2014 do not read any additional files.
 
 Do NOT write any files or emit any JSON blobs. Instead, emit one JSON object per line to stdout for each classification decision. The CLI reads your stdout line by line and writes each decision directly to the pipeline database.
 
-The three tool calls you may emit are:
+The four tool calls you may emit are:
 
 \`\`\`
 {"tool":"classify_component","description":"<optional component-level description>","rationale":{"description":"<why this component is classified the way it is>","props":"<why these props were chosen>","slots":"<why these slots were chosen>"}}
 
 {"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<short customer-facing description>","reason":"<full internal rationale; not customer-facing>","values":["a","b"],"token_kind":"color","default":"<value>"}
 
+{"tool":"exclude_prop","prop":"<propName>","reason":"<why excluded>"}
+
 {"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<reason>","rationale":"<why this slot was kept in the catalog>"}
 \`\`\`
 
 Rules:
 - Emit exactly one JSON object per line. No multi-line JSON. No markdown fences around the lines.
-- Every prop in the input must have exactly one classify_prop call.
+- Every prop in the input must have exactly one call: either classify_prop or exclude_prop.
 - Every slot in the input must have exactly one classify_slot call.
 - Valid cdf_type values: string, richtext, media, enum, token, boolean
 - Valid cdf_category values: content, design, state
 - For enum type, always include "values" (non-empty string array).
 - For token type, always include "token_kind" (DTCG $type, e.g. "color").
 - href and URL props \u2192 cdf_type "string", cdf_category "content". Do NOT use cdf_type "link" \u2014 it is not valid.
-- Framework internals (ref, event handlers, test IDs) \u2192 classify_prop, cdf_type "string" (or "boolean" if the raw type is boolean), cdf_category "state".
+- Framework internals (ref, event handlers, test IDs) \u2192 exclude_prop.
 - CSS design props (className, style, styles, positional/geometric props: top, bottom, left, right, rotation, offset, etc.) \u2192 classify_prop, cdf_type: "string", cdf_category: "design".
 - On classify_component, "rationale" fields are operator-facing (read-only) but may surface in customer-facing exports. The "rationale.description" field is subject to the description content rules in the skill prompt (no internal initiative names). "rationale.props" and "rationale.slots" describe your reasoning about scope; "classify_slot.rationale" explains why each slot was kept.
 - On classify_prop, "reason" is REQUIRED and is the LLM's internal rationale \u2014 shown to the developer reviewing the import, never to end-users. "description" is the customer-facing copy and is subject to the description content rules in the skill prompt. Keep them distinct: "description" is short and customer-facing; "reason" explains your reasoning in detail.
@@ -8720,11 +8732,16 @@ function applyToolCalls(db, sessionId2, componentId, componentName, calls, incom
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const warnings = [...incomingWarnings];
   let classified = 0;
+  let excluded = 0;
   let slots = 0;
   const updateProp = db.prepare(
     `UPDATE raw_props SET cdf_type = ?, cdf_category = ?, cdf_token_kind = ?, required = ?, description = ?, rationale = ?
      WHERE session_id = ? AND component_id = ? AND name = ?`
   );
+  const clearProp = db.prepare(
+    `UPDATE raw_props SET cdf_type = 'excluded', cdf_category = NULL, cdf_token_kind = NULL, rationale = ?
+     WHERE session_id = ? AND component_id = ? AND name = ?`
+  );
   const deleteAllowedValues = db.prepare(
     `DELETE FROM raw_prop_allowed_values WHERE session_id = ? AND component_id = ? AND prop_name = ?`
   );
@@ -8801,6 +8818,9 @@ function applyToolCalls(db, sessionId2, componentId, componentName, calls, incom
           ).run(storedDefault, sessionId2, componentId, call.prop);
         }
         classified++;
+      } else if (call.tool === "exclude_prop") {
+        clearProp.run(call.reason || null, sessionId2, componentId, call.prop);
+        excluded++;
       } else if (call.tool === "classify_slot") {
         const slotRequired = call.required !== void 0 ? call.required ? 1 : 0 : 1;
         const slotChanges = updateSlot.run(
@@ -8840,7 +8860,7 @@ function applyToolCalls(db, sessionId2, componentId, componentName, calls, incom
     db.exec("ROLLBACK");
     throw e;
   }
-  return { classified, slots, warnings };
+  return { classified, excluded, slots, warnings };
 }
 function getOrCreateSession(db, sessionFlag, sessionName, _hints) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -9315,8 +9335,6 @@ function loadCDFComponents(db, sessionId2) {
   ).all(sessionId2);
   if (components.length === 0) return [];
   const props = db.prepare(
-    // Guards against stale rows in session DBs persisted before props
-    // were guaranteed to always be classified into content/design/state.
     `SELECT component_id, name, required, default_value, description,
               cdf_type, cdf_category, cdf_token_kind, position
        FROM raw_props
@@ -28468,6 +28486,11 @@ function formatToolCall(obj) {
       const cat = String(obj["cdf_category"] ?? "");
       return `    ${c.green("+")}  ${prop}  ${c.dim(`${type}  ${cat}`)}`;
     }
+    case "exclude_prop": {
+      const prop = String(obj["prop"] ?? "");
+      const reason = typeof obj["reason"] === "string" ? obj["reason"] : "";
+      return `    ${c.dim("\u2013")}  ${prop}  ${c.dim(reason)}`;
+    }
     case "classify_slot": {
       const slot = String(obj["slot"] ?? "");
       const desc = typeof obj["description"] === "string" ? obj["description"] : "";
@@ -30973,6 +30996,7 @@ async function runOneComponent(agent, model, db, sessionId2, component, tokensIn
       return {
         componentName: component.name,
         classified: 0,
+        excluded: 0,
         slots: 0,
         warnings: [],
         failed: false,
@@ -30988,6 +31012,7 @@ async function runOneComponent(agent, model, db, sessionId2, component, tokensIn
       return {
         componentName: component.name,
         classified: 0,
+        excluded: 0,
         slots: 0,
         warnings: [`${component.name}: source changed but human edits preserved`],
         failed: false,
@@ -31056,6 +31081,7 @@ ${outputBuf}`);
       return {
         componentName: component.name,
         classified: 0,
+        excluded: 0,
         slots: 0,
         warnings: [],
         failed: true,
@@ -31080,6 +31106,7 @@ ${outputBuf}`);
     return {
       componentName: component.name,
       classified: applied.classified,
+      excluded: applied.excluded,
       slots: applied.slots,
       warnings: applied.warnings,
       failed: false,
@@ -31089,6 +31116,7 @@ ${outputBuf}`);
   return {
     componentName: component.name,
     classified: 0,
+    excluded: 0,
     slots: 0,
     warnings: [],
     failed: true,
@@ -31314,11 +31342,12 @@ async function runGenerateSkill(skill, opts, verbose = false) {
       }
     }
     const totalClassified = generated.reduce((s, r) => s + r.classified, 0);
+    const totalExcluded = generated.reduce((s, r) => s + r.excluded, 0);
     const totalRenamedSlots = componentResults.reduce((s, r) => s + r.renamedSlotsCount, 0);
     const allOk = failed.length === 0;
     const cachedNote = cachedResults.length > 0 ? c.dim(`  (${cachedResults.length} cached)`) : "";
     process.stderr.write(
-      (allOk ? c.green("\u2713") : c.yellow("\u26A0")) + `  ${generated.length + cachedResults.length}/${componentResults.length} components` + cachedNote + c.dim(`  ${totalClassified} classified`) + "\n"
+      (allOk ? c.green("\u2713") : c.yellow("\u26A0")) + `  ${generated.length + cachedResults.length}/${componentResults.length} components` + cachedNote + c.dim(`  ${totalClassified} classified, ${totalExcluded} excluded`) + "\n"
     );
     process.stdout.write(`renamed-slots: ${totalRenamedSlots}
 `);

package/dist/src/session/db.d.ts

@@ -28,6 +28,7 @@ export declare function getPipelineDbPath(): string;
 export declare function openPipelineDb(dbPath?: string): DatabaseSync;
 export interface ApplyToolCallsResult {
     classified: number;
+    excluded: number;
     slots: number;
     warnings: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experience-design-system-cli",
-  "version": "2.26.6-dev-build-ef7b167.0",
+  "version": "2.26.6-dev-build-8dec003.0",
   "description": "Contentful Experiences design system import CLI",
   "license": "MIT",
   "type": "module",
@@ -34,26 +34,26 @@
     "commander": "^13.1.0",
     "ink": "^4.4.1",
     "react": "^18.3.1",
-    "react-devtools-core": "^4.28.5",
+    "react-devtools-core": "^4.19.1",
     "react-dom": "^18.3.1",
     "svelte": "^5.56.4",
     "ts-morph": "^27.0.2",
     "typescript": "^5.9.3",
-    "@contentful/experience-design-system-types": "2.26.6-dev-build-ef7b167.0"
+    "@contentful/experience-design-system-types": "2.26.6-dev-build-8dec003.0"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
     "@types/node": "^24.0.3",
-    "@types/react": "^18.3.31",
+    "@types/react": "^18.3.24",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.6",
     "ink-testing-library": "^4.0.0",
     "typescript-eslint": "^8.67.0",
     "vitest": "^4.0.16",
-    "@contentful/experience-design-system-extraction": "2.26.6-dev-build-ef7b167.0",
-    "@contentful/experience-design-system-client": "2.26.6-dev-build-ef7b167.0",
-    "@contentful/experience-design-system-generation": "2.26.6-dev-build-ef7b167.0"
+    "@contentful/experience-design-system-client": "2.26.6-dev-build-8dec003.0",
+    "@contentful/experience-design-system-generation": "2.26.6-dev-build-8dec003.0",
+    "@contentful/experience-design-system-extraction": "2.26.6-dev-build-8dec003.0"
   },
   "repository": {
     "type": "git",

package/skills/generate-components.md

@@ -72,21 +72,21 @@ The CLI assembles your output into CDF (Component Definition Format), a JSON sch
 
 Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not starting with `{` are treated as prose and ignored by the parser — use them freely for reasoning.
 
-**Three tool calls:**
+**Four tool calls:**
 
 ```
-{"tool":"classify_component","description":"<required: one-sentence description of the component>","rationale":{"description":"<why this component is classified this way>","props":"<why these props were classified the way they were, including which ones were made unattached and why>","slots":"<why these slots were chosen / excluded>"}}
+{"tool":"classify_component","description":"<required: one-sentence description of the component>","rationale":{"description":"<why this component is classified this way>","props":"<why these props were chosen / excluded>","slots":"<why these slots were chosen / excluded>"}}
 
 {"tool":"classify_prop","prop":"<propName>","cdf_type":"<type>","cdf_category":"<category>","required":<bool>,"description":"<short customer-facing description>","reason":"<full internal rationale; not customer-facing>","values":["a","b"],"token_kind":"color","default":"<value>"}
 
+{"tool":"exclude_prop","prop":"<propName>","reason":"<why excluded>"}
+
 {"tool":"classify_slot","slot":"<slotName>","required":<bool>,"allowed_components":["ComponentName"],"description":"<short customer-facing description>","rationale":"<why this slot was kept / its role>"}
 ```
 
-Every prop — including framework internals, DOM/accessibility pass-through, and props with no clean flat representation — must produce a `classify_prop` call. Props that are not marketer-configurable are classified with `cdf_category: "state"`: they still ship in the CDF (visible in review, editable if someone wants to override the category), but stay unattached from the content/design editing surfaces by default. See "Valid cdf_category values" below for exactly what falls into `state`.
-
 **Rules:**
 - Emit exactly one JSON object per line. No multi-line JSON.
-- Every prop in the input must produce exactly one `classify_prop` call. There is no drop path — a prop you can't meaningfully type still gets `cdf_type: "string"`, `cdf_category: "state"`, with the reasoning in `reason`.
+- Every prop in the input must produce exactly one call: `classify_prop` OR `exclude_prop`.
 - Every slot must produce exactly one `classify_slot` call.
 - Emit `classify_component` once at the start (required). The `description` field is **required** — always provide a brief description of the component's purpose.
 - `values` is required for `cdf_type: "enum"` — must be a non-empty string array.
@@ -135,7 +135,7 @@ Exactly **6** valid types:
 |---|---|
 | `content` | Data the component *displays* — what a copywriter or editor fills in: text, labels, headings, body copy, rich text, images, media, URLs, link targets, counts, locale |
 | `design` | Values that control *how the component looks* — what a designer sets: color, size (sm/md/lg), variant (primary/secondary/ghost), layout orientation, alignment, background, visual toggles (imageOnLeft, enableEffect), design tokens |
-| `state` | Two groups, both unattached from the content/design editing surfaces by default: (1) runtime behavioral or interactive flags — disabled, loading, expanded, isOpen, isSearchVisible, preview, identifiers used for analytics/tracking (componentId, sectionKey, componentName); (2) props that aren't marketer-configurable at all — framework internals, DOM/accessibility pass-through, callbacks, refs, and any type with no clean flat representation. |
+| `state` | Runtime behavioral or interactive flags — not visible in the editor's design or content panel: disabled, loading, expanded, isOpen, isSearchVisible, preview, identifiers used for analytics/tracking (componentId, sectionKey, componentName) |
 
 The pre-classified `category` in the raw input is a starting point — correct it when it is wrong. Contentful uses this category to decide where the property appears in the editor UI, so accuracy matters.
 
@@ -145,21 +145,21 @@ The pre-classified `category` in the raw input is a starting point — correct i
 
 For each `RawPropDefinition`, apply in order:
 
-1. **Framework / DOM / accessibility pass-through?** → `classify_prop`, `cdf_type: "string"` (or `"boolean"` if the raw type is boolean), `cdf_category: "state"`. These are escape hatches for developers, not configurable surfaces for marketers — unattaching them keeps the ExO editor's content/design panels free of noise, without dropping them from the CDF. Always route here:
+1. **Framework / DOM / accessibility pass-through?** → `exclude_prop`. These are escape hatches for developers, not configurable surfaces for marketers. Exposing them in the ExO editor adds noise that obscures the props that actually carry intent. Always exclude:
    - Framework internals: `ref`, `innerRef`, event handlers (any `onSomething`), `testId`, `data-testid`, `key`
    - DOM pass-through: `className`, `class`, `classes`, `classNames`, `rootClassName`, `prefixCls`, `style`, `styles`, `id`, `role`, `tabIndex`, `htmlFor`, `for`, `slot`, `is`, `lang`, `dir`, `hidden`, `draggable`, `spellCheck`, `contentEditable`, `inputMode`, `autoComplete`, `autoFocus`, `translate`, `part`, `exportparts`
    - Accessibility pass-through: any `aria-*` or `ariaSomething` prop (including bare `aria` as an aria-attributes object), `aria-label`, `aria-hidden`, `aria-describedby`, `aria-controls`
    - Data attributes: any `data-*` prop
    - **Polymorphic component props**: `as`, `element`, `component` (when typed as an HTML tag string or component reference) — these change rendered HTML, not marketer-visible behavior
    - **Framework theming / pass-through escape hatches**: PrimeVue's `dt` / `pt` / `ptOptions` / `unstyled`, MUI/Chakra-style `sx`, anything explicitly typed as a developer "override" / "passthrough" object
-   - **Important caveat**: only route here when the prop is one of these *as the bare HTML attribute or framework-internal pass-through*. Compound names like `fileName`, `displayName`, `dataset`, `dataSource`, `roleDescription`, `idLabel` are not pass-through — classify them normally.
-2. **Common semantic props — classify per their real nature, not as unattached.** The LLM has been over-routing these into `state` because they sound like framework internals; they are not. Classify each per the rest of this tree:
+   - **Important caveat**: only exclude when the prop is one of these *as the bare HTML attribute or framework-internal pass-through*. Compound names like `fileName`, `displayName`, `dataset`, `dataSource`, `roleDescription`, `idLabel` are not pass-through — classify them normally.
+2. **Common semantic props — DO classify, do not exclude.** The LLM has been over-excluding these because they sound like framework internals; they are not. Classify each per the rest of this tree:
    - `icon` / `leftIcon` / `rightIcon` / `prefixIcon` / `suffixIcon` — slot or `string` (icon name); see slot guidance below
-   - `items` / `options` / `actions` / `links` — usually array content; if the element shape is simple, classify as `string` (comma-separated names/IDs) and note in `description`. Only fall back to `cdf_category: "state"` when elements are deep nested objects with no flat representation.
-   - `value` (the bare prop, not `modelValue`) — content prop, usually `string` (or `enum` if from a fixed set). Note: Vue's `modelValue` / `modelModifiers` are pre-classified as pass-through because they're v-model framework wiring — keep them in `state`.
+   - `items` / `options` / `actions` / `links` — usually array content; if the element shape is simple, classify as `string` (comma-separated names/IDs) and note in `description`. Only exclude when elements are deep nested objects with no flat representation.
+   - `value` (the bare prop, not `modelValue`) — content prop, usually `string` (or `enum` if from a fixed set). Note: Vue's `modelValue` / `modelModifiers` are excluded by pre-classify because they're v-model framework wiring.
    - `name` — content prop, usually `string`. Treat it as semantic component data, not as a DOM pass-through.
    - `form` (when not the literal `<form>` HTML attribute) — typically content; classify as `string` unless it's a complex form-config object
-   - `inputId` / `componentId` — these CAN be content (anchor IDs, marketer-set tracking refs). Classify as `string`, `cdf_category: "content"` when the type is a plain string. Only fall back to `state` if the prop is clearly internal (e.g. typed as a generated React ID).
+   - `inputId` / `componentId` — these CAN be content (anchor IDs, marketer-set tracking refs). Classify as `string`, `cdf_category: "content"` when the type is a plain string. Only exclude if the prop is clearly internal (e.g. typed as a generated React ID).
    - `accessibleNameRef` / `accessibleDescriptionRef` (web components) — these are ID references for a11y wiring; classify as `string`, `cdf_category: "state"` (behavioral wiring, not design or content).
    - `eventDetails` / similar telemetry props — `cdf_category: "state"`.
 3. **Positional/geometric design prop?** (`top`, `bottom`, `left`, `right`, `rotation`, `offset`, `zIndex`) → `classify_prop`, `cdf_type: "string"`, `cdf_category: "design"`.
@@ -169,13 +169,13 @@ For each `RawPropDefinition`, apply in order:
 7. **Raw type is `string` / `number` / `boolean`?** → For `boolean`, use `cdf_type: "boolean"` with `default: true` or `false` (native boolean). For `number`, use `cdf_type: "string"` with `default` as the numeric value as a string (e.g. `"0"`). For `string`, use `cdf_type: "string"`.
 8. **Media/image type** (`ImageProps`, `MediaSource`, asset types)? → `cdf_type: "media"`.
 9. **Rich text / markup** (`ReactNode` used as content, HTML string)? → `cdf_type: "richtext"`.
-10. **Complex type — resolve before falling back to unattached** (see below).
+10. **Complex type — resolve before excluding** (see below).
 
 ---
 
-## Resolving complex types — do not fall back to unattached without reasoning
+## Resolving complex types — do not exclude without reasoning
 
-A prop with a complex TypeScript type is **not automatically unattached**. Many props that appear complex carry real marketer-configurable information. Before falling back to `cdf_category: "state"`, ask: *"Could a marketer set this value in Contentful?"* If yes, classify it as `content` or `design`.
+A prop with a complex TypeScript type is **not automatically excluded**. Many props that appear complex carry real marketer-configurable information. Before excluding, ask: *"Could a marketer set this value in Contentful?"* If yes, classify it.
 
 **Common resolvable patterns:**
 
@@ -184,25 +184,25 @@ A prop with a complex TypeScript type is **not automatically unattached**. Many
 | `'primary' \| 'secondary' \| 'ghost'` (union of literals) | → `enum`, extract `values` |
 | `HeadingSize` / `ButtonVariant` / any named type that is clearly a finite set of visual options | → `enum`, infer likely values from the prop name and context (e.g. `['sm', 'md', 'lg']` for size, `['primary', 'secondary']` for variant). Document your inference in `description`. |
 | `Variant` / `variant` prop | Usually a visual design variant. → `enum`, `cdf_category: "design"`. Infer values from context. |
-| `Section[]` / array of custom items where the structure is unclear | → `string`, `cdf_category: "state"` only if the array elements are complex objects with no obvious flat representation. If items are simple (title, label, id), consider representing as `string` (a comma-separated IDs or keys) or note in `description` why. |
-| `ExperienceConfiguration<Variant>` / deep generic | Personalization config — → `string`, `cdf_category: "state"`, reason: `"personalization configuration — framework internal"` |
-| `React.Dispatch<...>` / setter | State setter — → `string`, `cdf_category: "state"`, reason: `"React state setter — framework internal"` |
-| `React.RefObject<...>` / `ref` | → `string`, `cdf_category: "state"`, reason: `"ref — framework internal"` |
-| `() => void` / callback | → `string`, `cdf_category: "state"`, reason: `"callback function — framework internal"` |
+| `Section[]` / array of custom items where the structure is unclear | → `exclude_prop` only if the array elements are complex objects with no obvious flat representation. If items are simple (title, label, id), consider representing as `string` (a comma-separated IDs or keys) or note in `description` why. |
+| `ExperienceConfiguration<Variant>` / deep generic | Personalization config — → `exclude_prop`, reason: `"personalization configuration — framework internal"` |
+| `React.Dispatch<...>` / setter | State setter — → `exclude_prop`, reason: `"React state setter — framework internal"` |
+| `React.RefObject<...>` / `ref` | → `exclude_prop`, reason: `"ref — framework internal"` |
+| `() => void` / callback | → `exclude_prop`, reason: `"callback function — framework internal"` |
 | `ReactNode` used as a slot-like prop (children, `icon`, `footer`) | → classify as a `slot` if it represents an injectable area, or `richtext` if it is inline markup content |
 | `boolean` with a name like `hideChevron`, `imageOnLeft`, `enableBackgroundColorEffect` | → `boolean`, `cdf_category: "design"`, `default: true` or `false` — these control visual appearance |
 | `boolean` with a name like `preview`, `hideContentForPersonalization` | → `boolean`, `cdf_category: "state"`, `default: false` — these control behavior |
 | `string` used as a `componentId`, `sectionKey`, `componentName` | → `string`, `cdf_category: "state"` — these are identifiers for tracking/lookup |
 | `string` locale (e.g. `locale: string`) | → `string`, `cdf_category: "state"` — locale is a behavioral/routing value |
 
-**When to fall back to `cdf_category: "state"` on a complex type (never drop the prop):**
+**When to finally exclude:**
 - The type is a callback signature or event handler
 - The type is a React ref
 - The type is a React state setter (`Dispatch`)
 - The type is a deep generic used for personalization/A-B testing platform config (e.g. `ExperienceConfiguration<T>`)
 - The type is an array of rich objects where no flat representation makes sense for a marketer
 
-In every one of these cases you still emit `classify_prop` — pick `cdf_type: "boolean"` when the raw type is boolean, otherwise `cdf_type: "string"` — with `cdf_category: "state"` and the reasoning in `reason`. If you classify a prop as `state` when it could have carried real content or design meaning, the marketer loses the ability to configure it in Contentful. Prefer classifying with a reasonable inference over falling back to `state`.
+If you exclude a prop that could have been classified, the marketer loses the ability to configure it in Contentful. Prefer classifying with a reasonable inference over excluding.
 
 ---
 
@@ -228,8 +228,8 @@ Rules for nested objects:
 - Flatten to max depth 2 (e.g., `item_nested_deep` is acceptable, deeper is not)
 - Each leaf field gets its own classify_prop call with underscore-joined name
 - Apply the same classification rules as top-level props
-- If the object has > 10 fields, classify the most important 10 normally and classify the rest `cdf_type: "string"`, `cdf_category: "state"` (still one call per field — never fewer calls than fields)
-- If the object type cannot be resolved (opaque generic, imported interface without visible fields), classify the parent prop `cdf_type: "string"`, `cdf_category: "state"`, reason: "opaque nested type"
+- If the object has > 10 fields, classify the most important 10 and exclude the rest
+- If the object type cannot be resolved (opaque generic, imported interface without visible fields), exclude the parent prop with reason "opaque nested type"
 
 ---
 
@@ -307,17 +307,17 @@ Input:
 Output:
 ```
 Starting Button classification — 5 props, 1 slot
-{"tool":"classify_component","description":"Primary action button with variant and state support","rationale":{"description":"Button is an atom — a single interactive control that triggers an action. It carries a label, a small set of visual variants, and a disabled flag, which is the minimal surface a marketer needs to configure a call-to-action.","props":"Kept label (content), variant (enum, design), disabled (boolean, state), and className (string, design escape hatch). Classified onClick as unattached (state) because it is an event handler — framework-internal and not configurable in Contentful.","slots":"Kept the icon slot as optional because the button renders correctly without it and the icon is purely decorative."}}
+{"tool":"classify_component","description":"Primary action button with variant and state support","rationale":{"description":"Button is an atom — a single interactive control that triggers an action. It carries a label, a small set of visual variants, and a disabled flag, which is the minimal surface a marketer needs to configure a call-to-action.","props":"Kept label (content), variant (enum, design), disabled (boolean, state), and className (string, design escape hatch). Excluded onClick because it is an event handler — framework-internal and not configurable in Contentful.","slots":"Kept the icon slot as optional because the button renders correctly without it and the icon is purely decorative."}}
 label is a required string content prop
 {"tool":"classify_prop","prop":"label","cdf_type":"string","cdf_category":"content","required":true,"description":"Button label text"}
 variant is a string union — enum type, category design
 {"tool":"classify_prop","prop":"variant","cdf_type":"enum","cdf_category":"design","required":false,"values":["primary","secondary","ghost"],"default":"primary","description":"Visual variant"}
 disabled is a boolean state prop — raw category says design, correcting to state
 {"tool":"classify_prop","prop":"disabled","cdf_type":"boolean","cdf_category":"state","required":false,"default":false,"description":"Disables the button"}
-onClick is an event handler — framework internal, unattached rather than dropped
-{"tool":"classify_prop","prop":"onClick","cdf_type":"string","cdf_category":"state","required":false,"description":"Not exposed for content or design editing.","reason":"event handler — framework internal"}
+onClick is an event handler — framework internal
+{"tool":"exclude_prop","prop":"onClick","reason":"event handler — framework internal"}
 className is a DOM pass-through — developers wire CSS, marketers never set this
-{"tool":"classify_prop","prop":"className","cdf_type":"string","cdf_category":"state","required":false,"description":"Not exposed for content or design editing.","reason":"DOM pass-through — not a marketer-configurable surface"}
+{"tool":"exclude_prop","prop":"className","reason":"DOM pass-through — not a marketer-configurable surface"}
 icon slot is clearly optional (decorative leading icon)
 {"tool":"classify_slot","slot":"icon","required":false,"description":"Optional leading icon","rationale":"Icon is a decorative leading glyph — optional because the button reads cleanly without it, but kept as a slot so marketers can inject a brand-specific icon component when desired."}
 ```
@@ -381,8 +381,8 @@ href is a URL string — cdf_type string (not link), category content
 
 ## Edge cases
 
-- **Prop with unresolvable type** (generics, intersection, callback) → `classify_prop`, `cdf_type: "string"`, `cdf_category: "state"`, reason `"complex type — not representable in CDF"`.
-- **Component with zero content/design props** → still emit `classify_component`, and still emit one `classify_prop` per prop even if every single one lands in `state`. The `$properties` object is never empty as long as the component has props.
+- **Prop with unresolvable type** (generics, intersection, callback) → `exclude_prop` with reason `"complex type — not representable in CDF"`.
+- **Component with zero classified props after exclusions** → still emit `classify_component`. The DB entry will have an empty `$properties` object.
 - **tokenReference present but not in sidecar** → `cdf_type: "token"`, omit `token_kind`, add `description` warning.
 - **Slot not in DB** → skipped with a warning; does not abort the run.
 - **Prop not in DB** → skipped with a warning; does not abort the run.
@@ -391,14 +391,14 @@ href is a URL string — cdf_type string (not link), category content
 
 Before emitting any tool calls, verify:
 
-1. Every prop in the input has exactly one `classify_prop` call
+1. Every prop in the input has exactly one `classify_prop` or `exclude_prop` call
 2. Every slot has exactly one `classify_slot` call
 3. `classify_component` is emitted exactly once
 4. Every `cdf_type: "enum"` has a non-empty `values` array
 5. Every `cdf_type: "token"` has `token_kind` (or a warning in `description` if lookup failed)
 6. No `cdf_type: "link"` — all href/url props use `string`
 7. `required` values are JSON booleans, not strings
-8. Framework, DOM, accessibility, and data-* pass-through props are classified `cdf_category: "state"` (unattached), not dropped — `className`/`classes`/`classNames`/`rootClassName`/`prefixCls`, `style`, `id`, `role`, `tabIndex`, `aria-*` (and bare `aria`), `data-*`, polymorphic `as`/`element`/`component`, framework theming `dt`/`pt`/`ptOptions`/`unstyled`/`sx`. Discrete positional/geometric props (`top`, `bottom`, `left`, `right`, `rotation`, etc.) ARE classified as `string` design props. Common semantic props (`icon`, `items`, `actions`, `options`, `value`, `name`, `form`, `inputId`, `componentId`) are NOT routed to `state` by default — classify them per their content/design/state nature.
+8. Framework, DOM, accessibility, and data-* pass-through props are excluded — `className`/`classes`/`classNames`/`rootClassName`/`prefixCls`, `style`, `id`, `role`, `tabIndex`, `aria-*` (and bare `aria`), `data-*`, polymorphic `as`/`element`/`component`, framework theming `dt`/`pt`/`ptOptions`/`unstyled`/`sx`. Discrete positional/geometric props (`top`, `bottom`, `left`, `right`, `rotation`, etc.) ARE classified as `string` design props. Common semantic props (`icon`, `items`, `actions`, `options`, `value`, `name`, `form`, `inputId`, `componentId`) are NOT excluded — classify them per their content/design/state nature.
 9. No `cdf_type: "link"` used — `link` is reserved and rejected by the CLI parser
 10. No `cdf_type: "number"` used — this is not a supported type; use `"string"` with numeric defaults. `cdf_type: "boolean"` IS valid — use it for boolean toggle props.
 11. `classify_component` includes a `rationale` object with all three sub-fields (`rationale.description`, `rationale.props`, `rationale.slots`) populated as non-empty strings.
@@ -417,9 +417,9 @@ Re-run or re-iterate on any components flagged by warnings until the output pass
 
 ## CRITICAL: Zero-output is a failure
 
-You MUST produce exactly one classify_prop call per input prop for this component. A response
-with zero classify_prop calls means the component will be pushed with no properties at all —
-this is never acceptable.
+You MUST produce at least one classify_prop call for this component. A response with zero
+classify_prop/exclude_prop calls means the component will be pushed with no configurable
+properties — this is never acceptable.
 
 If you are genuinely uncertain about every prop, classify each as:
 {"tool":"classify_prop","prop":"<name>","cdf_type":"string","cdf_category":"content","required":false,"description":"Uncertain classification — review recommended"}