@contentful/experience-design-system-cli 2.43.0-alpha.1 → 2.43.1-dev-build-2edf92d4.0

package/skills/generate-components.md

@@ -30,8 +30,8 @@ All input is embedded inline in the prompt before this file:
 - **Raw component data** — `RawComponentDefinition[]` (one component for this run)
 - **DTCG token data** — full token tree, if provided
 - **Token-name sidecar** — raw CSS custom property name → DTCG dot-notation path, if provided
-- **Component source references** — the real file text for the component's own source, plus up to 5 sibling files (e.g. a co-located `.styles.ts` or `utils.ts`, or a file reached transitively through another sibling — such as a re-exported component's own styles module), if provided. **`sourcePath` is a citation label only, never something to open. Read-only access is limited to supplied invocation artifacts and the exact supplied representation validator command when present; do not read or execute the live repository/source.**
-- A **"uses not shown"** line may accompany these files. The files are bounded excerpts, and this line names the properties with at least one use outside the excerpt budget. Treat those uses as unknown: do not conclude the property is unread or that the shown alternatives are exhaustive.
+- **Component source references** — the real file text for the component's own source, plus up to 5 sibling files (e.g. a co-located `.styles.ts` or `utils.ts`, or a file reached transitively through another sibling — such as a re-exported component's own styles module), if provided. **You have no filesystem access and no tools — `sourcePath` is a citation label only, never something to open.**
+  - A **"uses not shown"** line may accompany these files. The files are excerpts windowed around the property names, and this line names the properties with at least one use that fell outside the excerpt budget. Treat those properties' consumption as unknown: do not classify them `token` on what is shown, and do not conclude they are unread. Unknown resolves to `enum` (or `string`) per "Ambiguity resolves to `enum`".
 
 ```typescript
 interface RawPropDefinition {
@@ -59,18 +59,12 @@ interface RawComponentDefinition {
 }
 ```
 
-The `category` field and deterministic prop buckets are advisory hints. Verify each classification against the declared contract and supplied source evidence. Property names and general domain knowledge are cues for investigation, not proof of a category, value domain, requiredness, or binding behavior. Account for the complete retained inventory; preserve uncertain properties and explain unresolved evidence in `reason`.
+The `category` field on each prop is a pre-classification hint from static analysis heuristics.
+It is correct approximately 80% of the time for simple props. You should:
 
-## Source evidence and uncertainty
-
-- The declared type and contract govern available alternatives and open domains. Copy a finite declared literal union as declared; a union that includes `string` or `number` remains open and must not be narrowed to only its literal members.
-- A closed primitive domain requires evidence of the complete allowed set, such as a closed declared union, an explicit `allowedValues` contract, or source that establishes an exhaustive finite set. A default, one caller, one observed value, a prop name, a partial lookup table, or an existing model is an example or alignment clue; none alone proves the complete set.
-- Preserve the input's declared prop `required` value. Change it only when explicit source evidence establishes the contract. Typical caller presence, a default, empty-render guesses, or model overlap do not establish requiredness.
-- Preserve valid defaults exactly, including `false`, `0`, and the empty string. Do not treat a default as the only permitted value.
-- Source refs and observations are bounded. Missing imports, callers, excerpts, or source files leave those facts unknown; they do not establish that a prop is unused, a component is non-rendering, alternatives are absent, or capture is complete.
-- Keep uncertain properties in the output when evidence is incomplete. State what is unknown in `reason` instead of dropping the property or inventing a domain, requirement, token restriction, or source fact.
-- Decide authorability before choosing a representation. A verified declaration and complete implementation can establish that an input is never read or forwarded; use a reasoned `exclude_prop` for that input even if its type is unknown. Check aliases, rest/spread forwarding, computed access and delegated behavior; unresolved paths prevent that conclusion. Describe the positive implementation evidence, rather than treating an empty use list as proof. Unrelated partial coverage does not invalidate complete local evidence; unknown types or unavailable representations alone never justify exclusion.
-- Existing model summaries are optional alignment context. They may identify a possible match, but source evidence controls the current component's prop names, alternatives, defaults, and requiredness.
+- Trust it for obvious cases (event handlers excluded, text labels as content)
+- Override it when your domain knowledge indicates otherwise
+- NEVER produce zero output — if you disagree with all hints, explain why in descriptions
 
 ---
 
@@ -97,19 +91,13 @@ Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not
 **Rules:**
 
 - Emit exactly one JSON object per line. No multi-line JSON.
-- Root array and record definitions carry complete recursive `items` / `fields` metadata using CDF `$type`, `$required`, `$description`, `$values`, `$items` and `$fields`; preserve exact own keys and true/false requiredness at every node.
-- Defaults are typed JSON values; omit them when unknown, use `default_intent: {"action":"clear"}` to clear a decision, and never execute source expressions or narrow a declared domain from observed/default values.
-- Source graphs and defaults remain independent of advisory shape/category/representation; unsupported deeper or cyclic positions retain source evidence and require an explicit plan with unknown mapper/cardinality context.
-- Proposal stdout is staged typed drafts only; caller readiness and activation are separate.
-- Every property in the host-owned required decision inventory must produce exactly one call: `classify_prop` OR `exclude_prop`, including inputs absent from advisory props.
-- Every retained property requires `classify_prop` with `cdf_category`: `content`, `design` or `state`, and either a supported native `cdf_type` or a supplied source-bound `representation_selection`. Missing both representation choices is an incomplete draft and cannot finish generation.
-- An unresolved draft retains `cdf_category`, description, source identity and a nonblank reason, but omits `required`, defaults and all other representation companions until a representation is chosen; declared requiredness remains source evidence.
+- 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 optional for `cdf_type: "string"` — it must be a non-empty string array for a source-supported closed set of variant names. A default, one caller, or a partial lookup map does not establish the complete set. When no closed set is shown, emit `cdf_type: "string"` without `values`; do not guess.
-- **Do NOT include `values` for `cdf_type: "token"`.** The two property types carry different kinds of list. A string domain's list holds _variant names_ the component accepts (`"primary"`, `"secondary"`). A `token` prop's list holds _design token paths_ (`"color.brand.primary"`), produced by the separate token-mapping step (`$token.allowed`) — never by you. Emitting `values` on a token prop makes the definition invalid.
+- `values` is required for `cdf_type: "enum"` — must be a non-empty string array of the variant names the prop accepts. **There is no legal `enum` with a guessed list.** If the value set is shown to you anywhere in the material below — the type's own declaration, an `allowedValues` list on the raw prop, a variant/lookup map, a default, a sibling excerpt — copy it and emit `enum`. If it is shown nowhere, emit `cdf_type: "string"` and leave `values` off. `string` is an unrestricted enum: the author can still pass the real value. A guessed list silently rejects it.
+- **Do NOT include `values` for `cdf_type: "token"`.** The two property types carry different kinds of list. An `enum` prop's list holds _variant names_ the component accepts (`"primary"`, `"secondary"`). A `token` prop's list holds _design token paths_ (`"color.brand.primary"`), produced by the separate token-mapping step (`$token.allowed`) — never by you. Emitting `values` on a token prop makes the definition invalid.
 - `token_kind` is required for `cdf_type: "token"` — must be a DTCG `$type` string, e.g. `"color"`.
-- `required` must be a JSON boolean (`true`/`false`), not a string. Preserve the input contract's requiredness unless explicit source evidence establishes a different contract.
+- `required` must be a JSON boolean (`true`/`false`), not a string.
 - `description` on `classify_prop` is customer-facing — keep it short and subject to the description content rules below.
 - `reason` on `classify_prop` is **required** and is your internal rationale — shown to the developer reviewing the import, never to end-users. Use it to explain your reasoning in detail. The customer-facing description content rules below apply to `description` only, not to `reason`.
 - `rationale` on `classify_component` is **REQUIRED**. It is an object with three REQUIRED string sub-fields:
@@ -130,50 +118,117 @@ Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not
 
 ## Valid cdf_type values
 
-### Structured inputs represented by model Components
-
-The host supplies compiler-derived `analysisRepresentationCandidates` for each property. When a native property cannot preserve a nested or recursive structure, select that property's `component-model` candidate with:
-
-```json
-{"tool":"classify_prop","prop":"<exact source property>","cdf_category":"content","representation_selection":{"strategy":"component-model","candidateId":"<supplied candidate id>"},"source_revision":"<current sourceRevision>","source_node_id":"<current nodeId>","description":"<what the input supplies>","reason":"<source-grounded choice>"}
-```
-
-This is a representation of the original input, separate from a source-declared composition slot. The host derives compact model definitions, slots, ordering, cardinality, references and reconstruction mappings from the compiler graph. Do not invent model definitions, add `classify_slot` subjects, change the inventory, or encode framework/name-based modeling recipes. A model selection replaces the native `cdf_type` choice; omit native definition companions and `representation_proposal`. Preserve source requiredness, defaults and null/presence distinctions. The host validates the candidate identity and complete local plan; unresolved deployment and rendering requirements remain explicit and do not prevent local definition generation. Missing source coverage or unmapped source nodes still prevent completion.
+Exactly **6** valid types:
 
-Apply these rules to every supplied source pattern:
+| cdf_type   | Use case                                                                   |
+| ---------- | -------------------------------------------------------------------------- |
+| `string`   | Plain text, URLs, href props, numbers (as string), any string-shaped value |
+| `richtext` | Formatted text, HTML, ReactNode used as markup                             |
+| `media`    | Images, videos, media assets                                               |
+| `enum`     | Fixed set of string choices — requires `values`                            |
+| `token`    | Design-token-linked prop — requires `token_kind`                           |
+| `boolean`  | Boolean toggle props (visible, disabled, enabled, etc.)                    |
 
-- Select a native representation when the complete value fits the supported target position. Use Record for scalar-only objects and Array<Record> for arrays of scalar-only objects; preserve the original object/array distinction.
-- Select a supplied component-model candidate for independently editable data that cannot fit native structures. Do not request a Component merely for nullable/optional syntax, an array wrapper or a single-field structural envelope.
-- Represent arrays of model values through ordered slots, reusing model definitions for recursive elements. Retain a grouping boundary when flattening would merge nested arrays or remove nullable/empty element positions.
-- Carry single-field structural envelopes through source-keyed reconstruction metadata. Exact keys, source paths, requiredness, defaults and empty/unset behavior remain in the logical graph and mappings; separately editable fields stay native properties or model Components.
-- Multi-alternative unions retain their real branch choices. Collapsing a union with one nonempty value is an authoring-structure change, not permission to equate distinct null behavior or erase required source inputs.
-- Explain the editable data and unresolved reconstruction requirements in reason. The host validates the source-derived compact plan and creates its definitions; do not prescribe a model count or layout from a component/library name.
-
-Valid local CDF types:
-
-| cdf_type               | Use case                                                |
-| ---------------------- | ------------------------------------------------------- |
-| `string`               | Plain text and string-shaped source values              |
-| `richtext`             | Formatted text, HTML, ReactNode used as markup          |
-| `media`                | Images, videos, media assets                            |
-| `string` with `values` | Fixed declared set of string choices                    |
-| `token`                | Design-token-linked prop — requires `token_kind`        |
-| `boolean`              | Boolean toggle props (visible, disabled, enabled, etc.) |
-
-> Native `number`, `array` and `record` definitions preserve typed values and complete recursive metadata locally; this vocabulary does not prove remote mapper capability.
+> **IMPORTANT: No `number` type.** The design-systems API only supports the `String` design property variant for numeric values. All numeric props must use `cdf_type: "string"` with the number as a string default (e.g. `"0"`, `"100"`). Boolean props can now use `cdf_type: "boolean"` directly.
 
 > **Avoid `link` type for simple URL props.** Props named `href`, `url`, or holding plain URL strings → `cdf_type: "string"`, `cdf_category: "content"`. Reserve `link` for props that hold a reference to another Contentful entry.
 
 ---
 
-### Source domains and token values
+### `enum` versus `token`
+
+Both describe a closed set of choices, but the _contents_ differ, and that is the whole distinction:
+
+|         | What the list holds                     | Example                                          |
+| ------- | --------------------------------------- | ------------------------------------------------ |
+| `enum`  | Variant names the component accepts     | `["primary", "secondary", "ghost"]`              |
+| `token` | Design token paths the prop may bind to | `["color.brand.primary", "color.brand.neutral"]` |
+
+The distinction is **what the component does with the value it receives**. That
+is decidable from source; it is not inferred from the property's name, from the
+component's role, or from the property's TypeScript type.
+
+An `enum` design property is delivered as a plain string, so the component
+receives `variant="primary"` — the value its own code branches on. A `token`
+property is resolved to the token's value _before_ it reaches the component, so
+that same component would receive `variant="#0059c8"` and match no branch.
+
+#### The three-question procedure (closed, ordered)
+
+For every design prop that carries a value (not a boolean), answer these three
+questions **in this order**, from the source shown, and stop at the first answer
+that decides. There is no fourth question.
+
+- **Q1 — Does the component look the value up, switch on it, or compare it against names?**
+  An indexed access (`tokens[fontColor]`, `SPACING[padding]`, a `Record<Variant, Token>`),
+  a `switch (variant)` / `if (variant === 'x')` chain, a `styles[variant]` class lookup,
+  or a vocabulary of its own (`allowedValues`, a literal union) — any of these means
+  the component needs the _name_. A presence check (`if (width)`) or arithmetic on
+  the value is not a lookup.
+  **Yes → `enum`, names in `values`, stop.** No → Q2.
+- **Q2 — Is the value written straight into a style or attribute?**
+  `rx={radius}`, `padding: ${padding}`, `style={{ color }}`, `background: var(${bg})` —
+  the value reaches the renderer without the component resolving it.
+  **No → not `token`; leave this procedure and continue with the type rules.** Yes → Q3.
+- **Q3 — Is there a design-token reference at that use?** Any one of:
+  the parameter default is a token (`radius = tokens.borderRadiusSmall`), the raw prop
+  carries a `tokenReference`, or an inline `tokens.*` / `var(--*)` sits in the same
+  expression. The reference must belong to _this_ prop — a `tokens.*` on some other
+  line of the file, or in a sibling's style object, is not one.
+  **Yes → `token`, stop; resolve `token_kind` from that reference. No → `string`, stop.**
+
+**The raw TypeScript type is not an input to Q1–Q3.** `string`, `number`,
+`string | number`, `stringOrNumber` — none of these answers any question above;
+they say what the compiler accepts, not what the component does with the value.
+"The type accepts any value, the default just happens to be a token reference" is
+a Q3-yes described as a no: a token parameter default _is_ the design-token
+reference Q3 asks for, and the prop is `token`. Equally, a prop named `color` with
+no lookup and no token reference is `string`, however token-like the name.
+
+**Two worked examples — same shape, opposite answers:**
+
+```tsx
+// Divider.tsx
+export const Divider = ({ thickness = tokens.borderWidthDefault, inset = 0 }: DividerProps) => (
+  <hr style={{ borderTopWidth: thickness, marginLeft: inset }} />
+);
+```
+
+- `thickness` — Q1: no lookup. Q2: yes, `borderTopWidth: thickness`. Q3: yes, the
+  parameter default is `tokens.borderWidthDefault`. → **`token`**, `token_kind` from
+  `borderWidthDefault` via the sidecar. Its `string | number` annotation changes nothing.
+- `inset` — Q1: no lookup. Q2: yes, `marginLeft: inset`. Q3: no, the default is the
+  bare number `0` and nothing at this use is a token. → **`string`**, `default: "0"`.
+
+A lookup map from variant names to tokens is evidence **for** `enum`, not against
+it — that is Q1 answering yes. The map exists precisely because the component was
+handed a name it had to resolve itself.
+
+**`token` is earned by Q2 and Q3 together, and only that way.** Cite both lines
+in `reason`: the interpolation and the token reference. Once both are cited, the
+prop is `token` — do not then downgrade it because of its type annotation, because
+the default "could be overridden" (every default can), or because the tie-break
+below exists. Nothing downstream re-derives, corrects, or second-guesses this —
+what you emit is what ships.
+
+**Ambiguity resolves to `enum` — but only when Q1–Q3 cannot be answered, and only
+when you can still cite its values.** The tie-break applies solely when the source
+shown does not let you answer the three questions: the property is interpolated
+in one place and looked up in another, the use sits in a file you cannot see, or
+the source is truncated at the point of use (the "uses not shown" line). In those
+cases emit `enum` if a value set is citable from the source shown, else `cdf_type:
+"string"` per "no legal `enum` with a guessed list" — either way, record the
+ambiguity in `reason`. When the three
+questions _can_ be answered from the source shown, they are answered and the
+tie-break does not apply: a clear Q1-yes is `enum`, a clear Q2-yes + Q3-yes is
+`token`, and a type annotation does not create ambiguity. An `enum` is delivered
+as the plain string the component was written to receive and remains reachable
+from a content-type field; a wrong `token` delivers a resolved value the
+component cannot branch on and is permanently excluded from content-type field
+mapping. That asymmetric cost is why a genuine tie goes to `enum` — it is not a
+reason to call a decided case a tie.
 
-Use string with declared values only for a complete finite declared or enforced domain; partial lookups, observations, defaults and existing models cannot prove completeness.
-A domain with an open alternative remains open even when its known values are also design token names.
-Use `token` only when the source contract consumes a resolved design token value; a lookup vocabulary consumes names and is not itself a token value.
-Preserve all source-supported alternatives and explain unrepresented alternatives for review; do not invent a narrower type to resolve uncertainty.
-For DTCG tokens, look up `$type` and `$token.kind` from supplied token data or the token-name sidecar.
-Do not include `values` when `cdf_type` is `token`; `$token.allowed` is handled by the separate mapping stage.
+---
 
 ## Valid cdf_category values
 
@@ -187,127 +242,362 @@ The pre-classified `category` in the raw input is a starting point — correct i
 
 ---
 
-## Mapping guidance — source semantics
+## Mapping guidance — Classification decision tree
+
+For each `RawPropDefinition`, apply in order:
+
+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.
+
+   **The governing principle:** a prop is pass-through if it is inherited from a base interface the component extends (`React.HTMLAttributes<...>`, `AllHTMLAttributes`, a native element's attribute interface, an ARIA-attributes interface, etc.) or is one of a small set of universal framework hooks, **and the component does not redeclare or give it component-specific meaning**. Test this from the type declaration, not from name-matching against a list — a component that `extends React.HTMLAttributes<HTMLDivElement>` inherits `title`, `lang`, `translate`, `slot`, and dozens more that a fixed list will never enumerate; a component that redeclares one of these with its own type or JSDoc (e.g. its own `title: string` documented as "card heading") has given it new meaning and it is no longer pass-through.
+
+   Always exclude under this principle:
+   - Framework internals: `ref`, `innerRef`, event handlers (any `onSomething`), `testId`, `data-testid`, `key`
+   - Any prop inherited from an HTML-attributes base interface and not redeclared by the component — this replaces any fixed name list. Common examples include `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` — but these are examples of the principle, not an exhaustive list; apply the inheritance test to any prop the examples don't cover.
+   - 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 exclude when the prop is inherited/universal _and unredeclared_. Compound names like `fileName`, `displayName`, `dataset`, `dataSource`, `roleDescription`, `idLabel` are not pass-through — classify them normally. Likewise, a `title` (or any other inherited-attribute name) that the component redeclares with its own type or doc comment is component-specific content, not pass-through — classify it per rule 2 onward, do not exclude it and do not route it through the `title` → `content` correction below.
+
+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 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 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"`.
+4. **`enum` or `token`? — run the three-question procedure first.** Before any type-based rule, for every design prop that carries a value, answer Q1–Q3 from "`enum` versus `token`" above, in order, from the source shown:
+   - **Q1** looked up / switched on / compared / has its own vocabulary → `cdf_type: "enum"`, names in `values`, no `token_kind`. This holds even when every name maps 1:1 to a design token; the map is the component resolving a name it was given.
+   - **Q2** not written straight into a style or attribute → not `token`; continue to rules 5–7.
+   - **Q3** written straight into a style or attribute **and** a token reference at that use (a `tokens.*` parameter default, a `tokenReference`, an inline `tokens.*` / `var(--*)`) → `cdf_type: "token"`, `token_kind` from that reference via the sidecar, no `values`. Interpolated with no token reference at that use → `cdf_type: "string"`.
+   - Q1–Q3 **cannot be answered** from the source shown (unread, truncated, in a file you cannot see, evidence pointing both ways) → `cdf_type: "enum"` (or `string`). See "Ambiguity resolves to `enum`" above.
+
+   **Do not classify on the component's role.** A layout primitive is not automatically a token consumer. Design systems routinely key their primitives on token _names_, and those props are `enum` — the component needs the name to perform its own lookup:
+
+   ```ts
+   // Box.tsx — padding is an enum, despite Box being a layout primitive
+   const { padding } = props; // "spacingXs"
+   getSpacingStyles({ padding }); // → SpacingTable["spacingXs"] → "0.5rem"
+   ```
+
+   Classify that `padding` as `token` and the platform delivers `"0.5rem"`, so `SpacingTable["0.5rem"]` is `undefined` and the spacing silently disappears. A value that is spelled like a token name is still a lookup key (Q1 yes). Curated components with named variant APIs (`Button`, `Tag`, `Badge`, `Avatar`, `Notification`) are `enum` for the same reason. A design system may legitimately produce **zero** token-typed props.
+
+5. **Union of string literals** (e.g. `'a' | 'b' | 'c'`)? → `cdf_type: "enum"`, extract literals into `values`. (Rule 4's Q1 will normally have decided this already — a literal union is the prop's own vocabulary.) This applies even when Component source references show each literal resolving to a design token internally — a resolved token map is evidence about the component's internals, not its interface.
+6. **Raw type is `string`** and prop name is `href`, `url`, or clearly a URL? → `cdf_type: "string"`, `cdf_category: "content"`.
+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"`. **A design prop reaches this rule only after leaving rule 4 at Q2 (not written into a style) or Q3 (written into a style with no token reference at that use).** A prop that answered Q3 yes is already `token` and never arrives here — a `string`, `number`, or `string | number` annotation on it does not bring it back to this rule.
+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 excluding** (see below).
+
+---
+
+## Resolving complex types — do not exclude without reasoning
+
+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:**
+
+| Raw type pattern                                                                                | How to resolve                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'primary' \| 'secondary' \| 'ghost'` (union of literals)                                       | → `enum`, extract `values`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `HeadingSize` / `ButtonVariant` / any named type that is clearly a finite set of visual options | → `enum` if you can cite its values from the source shown (the type's own declaration, a lookup table, a default) — copy them, never invent them. If the source shown does not enumerate the values, this is not the Q1–Q3 ambiguity tie-break — it is the "no legal `enum` with a guessed list" rule: emit `cdf_type: "string"` instead, with the missing evidence noted in `reason`. Do not default to a generic guess like `['sm', 'md', 'lg']` or `['primary', 'secondary']` — those are one design system's vocabulary, not a fallback for missing evidence. |
+| `Variant` / `variant` prop                                                                      | Usually a visual design variant. → `enum`, `cdf_category: "design"`. Same evidence rule as above — cite values from the source shown; do not invent them.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `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 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
+
+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.
+
+---
+
+## Handling nested object props
+
+When a prop has an inline object type (e.g., `item: { url?: string; alt?: string; target?: string }`),
+classify EACH field as a separate prop using underscore notation (parentName_fieldName):
 
-Classify each input from its declared contract and actual consumption, with the supplied renderer reference as context.
-Names, frameworks, known component patterns, inherited shapes and category labels do not establish authorability or exhaustive domains.
-Choose `content`, `design` or `state` from the evidenced responsibility of the input; keep unsupported reasoning explicit.
-Exclude an input only when its source purpose establishes why it cannot be represented by the target contract.
-A ref, event handler or style-shaped input still needs its own source reasoning; do not exclude it from its spelling alone.
-Keep structured/complex alternatives and source defaults in the evidence record when the target format cannot represent them; preserve that capability limit for review.
-Never manufacture requiredness from callers, typical usage or model agreement.
+Input:
+{"name":"item","type":"{ url?: string; alt?: string; linkUrl?: string; target?: string }","required":true}
 
-## Null values and editable representations
+Output:
+{"tool":"classify_prop","prop":"item_url","cdf_type":"string","cdf_category":"content","required":false,"description":"Image source URL"}
+{"tool":"classify_prop","prop":"item_alt","cdf_type":"string","cdf_category":"content","required":false,"description":"Image alt text"}
+{"tool":"classify_prop","prop":"item_linkUrl","cdf_type":"string","cdf_category":"content","required":false,"description":"Navigation URL"}
+{"tool":"classify_prop","prop":"item_target","cdf_type":"enum","cdf_category":"design","required":false,"values":["_blank","_self","_parent","_top"],"description":"Link open behavior"}
 
-Preserve compiler nullability, declared requiredness, source defaults and complete source alternatives independently of the editable representation. Choose the simplest supported type for meaningful editable values. Nullability alone does not require JSON or a model Component.
+Note: Underscore notation is used (not dot-notation) because the backend's `toDisplayName()`
+function splits on `.` and takes only the last segment, producing poor display names. Underscore
+produces display names like "Item Url", "Item Alt" which are more readable in the ExO editor.
 
-- Optional means the input can be omitted; nullable means it can contain explicit null. Do not make a required nullable input optional.
-- Assess defaults, comparisons, forwarding and output behavior using supplied source evidence. If null and omission have equivalent behavior, an optional underlying type can represent that authoring state. Neither a type union, a prop name nor a framework convention proves equivalence.
-- Record each nullable union judgment in `null_handling`: `[{"sourceNodeId":"<nullable-union-node>","handling":"omit-equivalent","reason":"<source behavior supporting equivalence>"}]`. Copy the current property `source_revision` and root `source_node_id` from the supplied identities. Each judgment applies only to its named source union. `distinct` and `unknown` retain meaningful or uncertain null behavior; they do not authorize omission.
-- A supported optional underlying type must still preserve every non-null alternative, finite domain, field and default. Never replace null with empty strings, false, zero or empty collections.
-- Ordinary scalar fields cannot carry null defaults. For established omission equivalence, leave the editable default absent and retain the original null default in source evidence; omission invokes the unchanged source behavior. Explicit incompatible defaults remain validation errors.
-- These are source-bound agent judgments, not compiler proofs. Keep their rationale separate from original source facts. Meaningful or uncertain distinctions require a compatible representation or a precise validation failure; do not discard the property or claim readiness.
+Rules for nested objects:
 
-## Handling structured source properties
+- 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 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"
 
-- Emit one definition for the original source property, retaining exact field keys in `fields` and array item metadata in `items`.
-- Root Array, root Record and direct Array<Record> may use the supported local native profile; retain every declared field and nested/item requiredness.
-- Full source graph/type/census/default/domain evidence is authoritative; advisory shape is optional and cannot establish completeness.
-- Preserve deeper, open-indexed, tuple, union, cyclic, imported and unresolved source evidence with explicit coverage and outcomes; propose generic source-derived alternatives when native mapping is unavailable.
-- Alternate definitions require source revision/node identity, complete field accounting and dependency closure, plus caller-owned mapper/cardinality/readiness context; no draft can authorize activation.
+---
 
 ## Resolving `token_kind`
 
 `token_kind` becomes `$token.kind` in the CDF output — the DTCG `$type` of the token the prop binds to. For a prop that earned `cdf_type: "token"` (Q2 yes, Q3 yes), take the token name cited at Q3 (`tokens.borderRadiusSmall`, `var(--brand-primary)`, a raw `tokenReference`) and resolve it against the inline token data: through the token-name sidecar (raw name → DTCG dot-notation path) when one is provided, otherwise by matching the name to the DTCG tree by spelling (`tokens.borderRadiusSmall` → `border-radius.border-radius-small`); the leaf's `$type` (`"dimension"`) is the `token_kind`. If the name cannot be resolved to a leaf, keep `cdf_type: "token"`, omit `token_kind`, and say so in `description` (`"WARNING: token_kind unknown — <name> not found in token data"`).
 
-**Canonical example — a named variant backed by tokens is still a string domain:**
+**Canonical example — a named variant backed by tokens is still `enum`:**
 
 ```
 Tag.variant has allowedValues ["primary","secondary","warning","negative"] and PillNext.styles.ts
 maps each one to a token (primary→tokens.blue100, warning→tokens.orange100, ...). The mapping is
 internal to the design system — Tag's prop signature accepts the name, not the token. Classifying
-as string with declared values so the author picks "primary" and the component receives "primary".
-{"tool":"classify_prop","prop":"variant","cdf_type":"string","cdf_category":"design","required":false,"values":["primary","secondary","warning","negative"],"default":"primary","description":"Visual variant","reason":"Fully token-backed internally, but the component consumes the variant name. Token classification would deliver a resolved color the component cannot branch on."}
+as enum so the author picks "primary" and the component receives "primary".
+{"tool":"classify_prop","prop":"variant","cdf_type":"enum","cdf_category":"design","required":false,"values":["primary","secondary","warning","negative"],"default":"primary","description":"Visual variant","reason":"Fully token-backed internally, but the component consumes the variant name. Token classification would deliver a resolved color the component cannot branch on."}
 ```
 
 ---
 
+## Category correction rules
+
+The pre-classified `category` is wrong in predictable ways. Correct silently (document in `description`):
+
+- Visual style props (`color`, `size`, `padding`, `spacing`, `variant`, `theme`, `bgColor`, `imageOnLeft`, `enableXxx`) classified as `content` or `state` → `design`
+- Interactive/behavioral state props (`disabled`, `loading`, `expanded`, `selected`, `checked`, `active`, `isOpen`, `isSearchVisible`, `showXxx`, `hideXxx`, `preview`, `componentId`, `sectionKey`, `variantIndex`) classified as `design` or `content` → `state`
+- Text/label/data props (`label`, `description`, `caption`, `text`, `boldText`, `labelText`, `richText`, `backgroundImage`, `link`, `placeholder`, `searchValue`, `total`, `slug`) classified as `design` → `content`. `title` is excluded from this auto-correction — it is one of the most common HTML-inherited attribute names (see the pass-through principle above). Only apply this correction to a `title` prop the component redeclares with its own type or documented, component-specific meaning; a `title` that is bare inherited pass-through was already excluded in rule 1 and never reaches this step.
+- Locale classified as `content` → `state` (it is a behavioral routing value, not editor-filled text)
+
+> **Key question for category**: "Who fills this in?" — A content editor fills in `content`. A designer configures `design`. Neither fills in `state` — it comes from routing, runtime behavior, or component infrastructure.
+
+---
+
 ## Slot classification
 
-`classify_slot` maps to `$slots`; `allowed_components` maps to `$allowedComponents`.
-Preserve the exact original source input name, including render-function names; do not rename an input from observed markup or a familiar pattern.
-Accepted slot decisions are authoritative: false/unresolved suppress export, open removes restrictions, and finite accepts only independently supported declared/enforced restrictions.
-Known names are an address allowlist, not a complete source domain, and observed children do not close an open slot.
-Preserve declared requiredness, including `false`; omit requiredness when its source contract is unknown.
-Detail/category resolutions are recorded for review and never applied as automatic generation facts.
+The `classify_slot` tool call maps to CDF's `$slots` object. Each slot you classify becomes a `$slots` entry; the `allowed_components` field maps to `$allowedComponents` in the output CDF.
+
+For each `RawSlotDefinition`:
+
+- `name` → `slot` field
+- `description` → `description` field
+- `allowedComponents` → `allowed_components` (pass through)
+- `allowed_components` must contain only exact names from the hard allowlist supplied in the prompt; never invent a child from an import, JSX element, type name, icon name, or implementation helper, and omit any child that is not listed.
+- `required`:
+  - `true` if the component does not render correctly without content in this slot (primary content area of a Card, Dialog body, etc.)
+  - `false` if clearly optional (icon slot, footer slot with a default, decorative slot)
+  - Default to `true` when the source gives no signal
+
+**Pre-named slots:** If the input contains a slot whose `name` was already inferred by the pipeline (e.g. `"children"`, `"slot_0"`), treat it as you would any named slot — classify it normally. The pipeline renames empty-named slots to heuristic names before passing them to you; your job is to confirm or enrich the classification (set `required`, `description`, `allowed_components`), not to rename again.
+
+---
 
 ## Examples
 
-A declared input `renderRegion` accepting arbitrary renderable values stays named `renderRegion` with an open slot domain even if one caller passes a single known component.
-A declared `string` alternative alongside literal alternatives stays open; a falsy default such as `false`, `0` or an empty string is preserved as declared.
+### Simple component
+
+Input:
+
+```json
+{
+  "name": "Button",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "category": "content",
+      "required": true
+    },
+    {
+      "name": "variant",
+      "type": "'primary'|'secondary'|'ghost'",
+      "category": "design",
+      "defaultValue": "'primary'"
+    },
+    { "name": "disabled", "type": "boolean", "category": "design" },
+    { "name": "onClick", "type": "()=>void", "category": "state" },
+    { "name": "className", "type": "string" }
+  ],
+  "slots": [{ "name": "icon", "description": "Optional leading icon" }]
+}
+```
+
+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). 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
+{"tool":"exclude_prop","prop":"onClick","reason":"event handler — framework internal"}
+className is a DOM pass-through — developers wire CSS, marketers never set this
+{"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."}
+```
+
+### Component with multiple slots (Card)
+
+Input:
+
+```json
+{
+  "name": "Card",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "category": "content",
+      "required": true
+    },
+    {
+      "name": "elevation",
+      "type": "'flat'|'raised'|'floating'",
+      "category": "design",
+      "defaultValue": "'raised'"
+    }
+  ],
+  "slots": [
+    { "name": "body", "description": "Main card body" },
+    { "name": "footer", "description": "Optional footer area" }
+  ]
+}
+```
+
+Output:
+
+```
+Starting Card classification — 2 props, 2 slots
+{"tool":"classify_component","description":"Container that groups related content with a title, body, and optional footer","rationale":{"description":"Card is a molecule — it composes a title with body and footer slots into a single visual container. Useful as a building block for lists and grids of related content.","props":"Kept title (string, content) as the customer-facing label and elevation (enum, design) for the three visual depth variants. Nothing was excluded — both raw props map cleanly to CDF.","slots":"Kept both body (required, primary content area) and footer (optional, supplementary area). Body is required because a card with no body renders empty; footer is optional because many cards do not need one."}}
+title is a required content string
+{"tool":"classify_prop","prop":"title","cdf_type":"string","cdf_category":"content","required":true,"description":"Card title text"}
+elevation is a finite visual variant — enum, design
+{"tool":"classify_prop","prop":"elevation","cdf_type":"enum","cdf_category":"design","required":false,"values":["flat","raised","floating"],"default":"raised","description":"Visual depth variant"}
+body is the primary content region — required
+{"tool":"classify_slot","slot":"body","required":true,"description":"Main card body content","rationale":"Body is the primary content region of the card. Required because a card with no body renders an empty container, which is never a useful editor state."}
+footer is supplementary and optional
+{"tool":"classify_slot","slot":"footer","required":false,"description":"Optional footer area for actions or metadata","rationale":"Footer is a supplementary region typically used for actions or metadata. Optional because most cards do not need one and the card renders correctly without it."}
+```
+
+### Named type (HeadingSize, ButtonVariant, etc.) — do NOT infer the values
+
+When a prop has a named TypeScript type that is not inlined as a union literal,
+the value set is whatever that type's declaration says. A type _name_ is not
+evidence of its members: `HeadingSize` could be `h1`–`h6`, `sm|md|lg`, or
+`s|m|l|xl`. Guessing picks one design system's vocabulary and is wrong more
+often than it is right, and a wrong name matches no style rule — the author's
+setting silently does nothing.
+
+So: look for the declaration in the source shown. If it is there, copy it. If it
+is not, **emit `string`** — `string` is an unrestricted enum, so the author stays
+unrestricted but correct.
+
+Members visible in the source shown — copy them, do not paraphrase:
+
+```
+titleSize has type HeadingSize; HeadingSize is declared in the excerpt as 'sm' | 'md' | 'lg'
+{"tool":"classify_prop","prop":"titleSize","cdf_type":"enum","cdf_category":"design","required":false,"values":["sm","md","lg"],"description":"Heading size","reason":"Copied from the HeadingSize declaration shown in the excerpt."}
+```
+
+Members NOT visible in the source shown — degrade to `string`:
+
+```
+titleSize has type HeadingSize; HeadingSize is not declared anywhere in the source shown
+no evidence for its members, so no values list — string, not a guess
+{"tool":"classify_prop","prop":"titleSize","cdf_type":"string","cdf_category":"design","required":false,"description":"Heading size","reason":"HeadingSize is not declared in the source shown, so its members cannot be cited. Emitted as string rather than inventing a value list."}
+```
+
+### href prop
+
+```
+href is a URL string — cdf_type string (not link), category content
+{"tool":"classify_prop","prop":"href","cdf_type":"string","cdf_category":"content","required":false,"description":"Navigation URL"}
+```
+
+---
 
 ## Edge cases
 
-- **Unresolved representation** → retain the input with a reasoned `classify_prop`; select a compatible native type or a supplied component-model candidate, and use host validation to identify remaining source limitations; exclude only when its semantics justify exclusion.
+- **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.
-- **Unknown slot** → explicit protocol failure; use only retained source slots.
-- **Unknown property** → explicit protocol failure; preserve exact inventory names.
+- **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.
 
 ## Validation step — Pre-emit checklist
 
 Before emitting any tool calls, verify:
 
-1. Every prop in the input has exactly one `classify_prop` or `exclude_prop` call, using the host-owned required decision inventory rather than the advisory prop list.
-2. Every slot has exactly one `classify_slot` call.
-3. `classify_component` is emitted exactly once with non-empty `rationale.description`, `rationale.props` and `rationale.slots`.
-4. Every finite primitive domain has the complete source-supported alternatives; Missing evidence does not close a domain.
-5. Every token-typed property has a source-supported token kind and no `values`.
-6. `required` is a source-supported JSON boolean; omitted requiredness remains unknown.
-7. Use current supported output types and typed numeric values; do not coerce numbers into strings or infer a ResourceLink contract.
-8. Every slot uses its original source name and authoritative accepted state; unknown restrictions are unset.
-9. Every `classify_slot` has a non-empty rationale; descriptions follow Description content rules.
-10. Input names, structural shapes, framework labels and observed children do not substitute for source reasoning.
-11. Every retained property selects `cdf_type`; nullable unions use explicit source-bound null handling when omission equivalence is needed.
-
-Before finishing, review the component output against this checklist and iterate on any warning the supplied evidence can resolve. Preserve unresolved warnings in the relevant `description` or `reason`; do not invent values.
-
-## Complete source decisions
-
-Use the independent source inventory, including retained inputs absent from advisory props, to account for every subject exactly once.
-Emit exactly one component decision even when there are no properties; accepted source-owned slots account for their original inputs without a conflicting property decision. Such owned inputs are already omitted from the required property inventory. Matching property and slot names alone do not establish ownership; any property still listed requires its own decision.
-Every retained input must select a supported native `cdf_type` or a supplied source-bound `representation_selection`, the required `cdf_category` (`content`, `design` or `state`), and a non-empty source-grounded `reason`. An input without either representation choice remains incomplete and cannot be saved as completed generation.
-Use the underlying editable type for evidence-backed null/omission equivalence with source-bound `null_handling`. If compatibility remains unresolved, retain the selected type and explain the concrete limitation; host validation keeps the component incomplete. Do not invent an arbitrary String representation or claim unsupported mapper capabilities.
-Use reasoned `exclude_prop` only for a source-grounded semantic exclusion, including an input whose verified complete implementation establishes that it is unused; unknown type or missing representation support alone is not an exclusion.
-Defaults remain typed JSON with independent original source evidence; absent intent preserves a known source default, while generation must never set or clear a different known default.
-When a correction is requested, emit decisions only for reported missing/rejected subjects and pending representations; preserve successful decisions, accepted exclusions/slots and the original source.
-Missing or parser-rejected subjects have no accepted semantic decision and may receive a source-grounded exclusion after reconsidering authorability; do not confuse them with accepted pending semantic decisions.
-Pending semantic decisions retain the same property, category, description and source identity; repair only representation metadata and update the reason with concrete evidence or capability limits, without creating a duplicate or replacing the property with an exclusion.
-
-## Host validation and bounded representation repair
-
-The host validates drafts through the canonical source-bound materializer, CDF validation and projection rules; a complete inventory does not establish an admissible representation.
-Per-property feedback reports missing representations, incompatible structure/domain, contradictions with declared/compiler facts, candidate alternatives and explicit capability requirements.
-Inspect supplied source facts before choosing a representation; alternatives are drafts with unapproved mapper/cardinality requirements, and local native support does not prove deployed mapper support.
-When the prompt supplies a representation validator command, run that exact command on the exact final JSON tool-call lines before emitting them. Read only the supplied immutable artifacts; these permissions do not authorize reading or executing live source paths or modifying files. The validator records an invocation-local successful preflight receipt; the host matches it against emitted normalized decisions and independently validates them. Repair validation errors in the same invocation, validate again, and do not alter the validated decisions afterward. A prior draft receipt does not cover changed output.
-If tools are unavailable, report that concrete limitation rather than claim validated completion; host validation always remains authoritative.
-The host keeps one operation deadline and at most five attempts, retaining successful decisions and requesting only missing subjects or pending representation repairs.
-Correction validators already include accepted decisions and pending semantic locks. Submit only the requested decisions. If the inventory is already complete and only preflight is missing, validating empty tool-call input verifies the accepted inventory without replaying its decisions. Use supplied source-derived decision skeletons as structural drafts; choose category, descriptions, reasons and null handling from source evidence. A repeated failure requires inspecting the failed subject's complete source and validator feedback, then reconsidering source-compatible alternatives, rather than replaying the same draft or inventing an exclusion.
-If repair cannot resolve a property, retain its semantic decision and explain the exact source limitation in `reason`; generation remains incomplete. Never force String, narrow an open source domain, drop a field or invent support to satisfy validation. A complete source-derived model may finish local generation while its downstream deployment and rendering requirements remain explicit.
+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 taken from the material shown. A prop whose value set was shown nowhere is `cdf_type: "string"` with no `values` — never an `enum` with a plausible-looking list, and never an `exclude_prop`.
+5. Every `cdf_type: "token"` has `token_kind` (or a warning in `description` if lookup failed) and does **not** have `values` set
+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 excluded per the inheritance principle (rule 1) — any prop inherited from an HTML-attributes base interface and not redeclared by the component, plus `aria-_`(and bare`aria`), `data-\*`, polymorphic `as`/`element`/`component`, framework theming `dt`/`pt`/`ptOptions`/`unstyled`/`sx`. A prop matching an inherited-attribute name (including `title`) that the component redeclares with its own type or meaning is NOT excluded. 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.
+12. Every `classify_slot` includes a non-empty `rationale` string.
+13. `rationale.description` follows the same "Description content rules" as `description` — no internal initiative names (`INTEG-*`, `EDSI`, `DSI`, `M1`, `M2`, wave/phase references, etc.).
+14. Every `cdf_type: "token"` prop cites a line that interpolates its value into a style **and** a token reference at that use (Q2 yes, Q3 yes), and carries no `values`. If you cannot cite both, it is `enum` or `string`; if you can, it is `token` — its type annotation is not a reason to emit `string`.
+15. Every prop whose values are friendly names is `enum` with a non-empty `values` array, even when each name resolves to a design token internally; every prop for which Q1–Q3 could not be answered was emitted as `enum` (or `string`) with the ambiguity stated in `reason`, and no answerable prop was called ambiguous.
+16. Every `enum`'s `values` array is copied from evidence in the material shown — a type declaration, an `allowedValues` list on the raw prop, a variant or lookup map, a default, in the component's own file or in any sibling excerpt — and none of it was invented. Where the value set appears nowhere, the prop is `cdf_type: "string"`, with the reason recorded in `reason`. Do not drop a prop merely because you could not enumerate its values.
+
+After the run completes, the developer can validate the pipeline output with:
+
+```
+experience-design-system-cli print validate --components <out-path>
+```
+
+Re-run or re-iterate on any components flagged by warnings until the output passes validation.
+
+---
+
+## CRITICAL: Zero-output is a failure
+
+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"}
+
+An imperfect classification is infinitely better than no classification. That is
+about **classifying a prop rather than dropping it** — it is not a licence to
+invent a `values` list. The uncertain answer is `cdf_type: "string"`, every time.
 
 ---
 
 ## Existing entities in the target space
 
-The preamble may include an "Existing components in the target Contentful space" JSON block with a `likelyMatch` (a fuzzy-matched space component that may correspond to the codebase component), an `otherComponents` list, and a rolled-up token summary. Treat these as optional alignment context; the current component's declared contract and source evidence govern its classification.
+The preamble may include an "Existing components in the target Contentful space" JSON block with a `likelyMatch` (a fuzzy-matched space component that likely corresponds to the codebase component you're classifying), an `otherComponents` list, and a rolled-up token summary. Use it to align your classifications with what the customer already has.
 
-### When `likelyMatch` is present — record possible alignment for review
+### When `likelyMatch` is present — align rename intent + categories + slot names
 
-Use the context to explain possible alignment during review. It does not establish the current source component's names, categories, slot shape, requiredness, or value domain.
+Your goal is **consistency**: the customer will see the diff between what you propose and what already exists, and every unnecessary category flip or slot-shape mismatch becomes review friction.
 
 1. **Prop names**: `classify_prop.prop` MUST always be the codebase prop name — that's the DB lookup key. When a codebase prop looks like it corresponds to an existing space prop (e.g. codebase `kind` ↔ space `variant`, codebase `text` ↔ space `label`), keep `prop` as the codebase name and put the alignment note in `reason`, e.g. `"looks like existing space prop 'variant' — customer may want to reconcile at review"`. Never rewrite `prop` itself; reconciliation happens downstream, not in this tool call.
-2. **Categories**: classify from the current source evidence. If a likely equivalent space prop uses a different category, note the difference in `reason` for review; the space category does not override the current evidence.
-3. **Slot names**: preserve names from the current component contract. Note a possible match to a space slot in `rationale` when supported.
-4. **Enum values**: preserve the current component's source-supported domain. If it differs from the space's values, cite the difference in `reason` for review; do not bridge the mismatch with guessed values.
+2. **Categories**: match the space's category (`design` / `content`) for equivalent props, even if you'd normally categorize differently. Note the alignment in `reason`.
+3. **Slot names**: match slot IDs / names when the shape is equivalent.
+4. **Enum values**: never invent new values to bridge a mismatch. If the codebase's enum diverges from the space's, classify against your best-effort mapping and cite the divergence in `reason` — this is a signal for human review, not a green light to rewrite the space's enum.
 5. **Never realign silently.** Every classification influenced by the `likelyMatch` MUST cite it in `reason`.
 
 ### When only `otherComponents` is present (no direct match)
@@ -320,22 +610,3 @@ The preamble's "Existing design tokens" section lists tokens (by name + DTCG typ
 
 1. When classifying a `design`-category, `token`-typed prop, prefer binding to an existing token name over inventing a new one. Cite the target token in `reason`.
 2. If no existing token semantically matches, proceed with the current rules — propose a new token. The diff surfaces this for review.
-
-## Richer content representations
-
-The desired CDF vocabulary additionally includes `Integer`, `DateTime`, `Literal`, `RichText`, `JSON` and `ResourceLink`; these are content representations. Local file validity does not establish deployed mapper support.
-
-- `Integer` requires a complete, compiler-established integral source domain; names, a numeric default and observed callers do not prove it.
-- `DateTime` requires a complete source domain of timezone-qualified ISO strings; preserve their spelling and do not convert Date objects or infer semantics from names.
-- `Literal` requires an exact source singleton, `value` and recursive CDF `valueType` in the same call; a default is separate from its intrinsic value and must equal it. Singleton proof does not establish RichText or ResourceLink semantics for an underlying type.
-- `RichText`, `JSON` and `ResourceLink` require `representation_proposal` in the same classification call. Copy the host-supplied `componentId`, `propertyId`, `key`, `sourceRevision` and source-node identities; use `name` equal to the exact source property. Supply independent `declaredConstraints`, `provenConstraints`, `observations`, `judgment`, `desiredType`, complete target `desiredDefinition`, and `compatibility` with `status`, `sourceUseRefs` and `unresolvedRequirements`. Readiness is host-owned and must not be included in the draft.
-- Evidence channels are arrays with exact item shapes: `declaredConstraints` and `provenConstraints` use `[{"nodeId":"<current source node>","statement":"<source-grounded statement>"}]`; `observations` uses `[{"nodeId":"<current source node>","value":"<observed JSON value>"}]`. A JSON value may also be a number, boolean, null, array or object. Use `[]` when no evidence is available, rather than objects or unbound statement strings. Keep the prose judgment separate.
-- `desiredType` must exactly equal the enclosing `cdf_type`, and `desiredDefinition.type` must equal `desiredType`. `desiredDefinition` must carry the same complete target definition, including the description, requiredness and any other selected definition metadata. Do not attach a proposal for a different alternative to a native record or other selected type; choose and validate one coherent representation.
-- A judged-compatible proposal must cite current positive output-flow references. A primitive string is not a RichText document; lowercase `richtext` retains its existing markup projection. JSON requires proven JSON-compatible semantics and an explicitly justified opaque contract, rather than a fallback for unknown or meaningful editable structure.
-- ResourceLink restrictions use `Contentful:Entry` with `allowedTypes`, or `Contentful:Asset`, and the exact same-space source `crn:contentful:::content:spaces/$self/environments/$self`. Keep resource and delivery prerequisites explicit; neither a URL nor a matching name proves a resource identity.
-- RichText and JSON cannot have target defaults; source defaults remain evidence. ResourceLink defaults require a verified delivery contract and remain held. Retain unresolved proposals and source facts instead of inventing proof.
-- When no representation is established, omit `value`, `valueType`, `allowedResources` and `representation_proposal` as well as all other representation companions.
-
-## Discriminated union content representations
-
-`DiscriminatedUnion` is a desired content representation. A `classify_prop` call must carry `discriminator` and every complete recursive CDF `members` definition together. Members are `record` definitions with a required intrinsic `Literal` field at that discriminator key, using typed `value` and recursive `valueType`. Keep every compiler branch, each branch's fields and requiredness, and complete finite domains; do not flatten branches, infer tags from names, coerce tags, or use observed callers as an exhaustive domain. Defaults must match one exact branch. Treat the complete exploration `definition` as one advisory judgment to validate against current compiler evidence. Native positions, target tag lookup/path constraints, mapper support, exclusive branch cardinality and reconstruction remain separate requirements; preserve source-bound model alternatives when native representation cannot preserve them. A final retained property must select a native `cdf_type` or a source-bound component-model candidate; a DiscriminatedUnion decision requires its complete discriminator and members before generation can finish.