@contentful/experience-design-system-cli 2.38.0 → 2.38.1-dev-build-6d903339.0

package/skills/generate-tokens.md

@@ -0,0 +1,194 @@
+# Generate Tokens — Classification Skill
+
+## Purpose
+
+Classify every raw token from the input into a DTCG token tree. Output one JSON tool call per line to stdout. The CLI reads your stdout and writes each token and group directly to the pipeline database — you do not produce a JSON file.
+
+---
+
+## Prerequisites — Input
+
+All input is embedded inline in the prompt before this file:
+
+- **Raw token source** — the original source file as-is. This may be any format: SCSS/CSS variable declarations, a JavaScript/TypeScript token module, a JSON object, a Style Dictionary config, Tailwind config, or any other token definition format the project uses. Read it as you would any source file.
+- **Token-name sidecar** — if provided, maps raw names to DTCG paths (read-only context). Use these as authoritative path assignments when present.
+
+---
+
+## Target schema
+
+The CLI assembles your output into a DTCG token tree. Each `set_group` call produces an intermediate group node; each `set_token` call produces a leaf with `$type` and `$value`. You do not produce JSON directly — emit tool calls and the CLI writes the rows.
+
+---
+
+## Output protocol
+
+Emit one JSON object per line. The CLI parses lines starting with `{`. Lines not starting with `{` are treated as prose and ignored — use them freely for reasoning.
+
+**Two tool calls:**
+
+```
+{"tool":"set_group","path":"<dot.notation.path>","description":"<optional>"}
+
+{"tool":"set_token","path":"<dot.notation.path>","type":"<DTCG type>","value":<value>,"description":"<reason>"}
+```
+
+Every leaf token must have an explicit `$type` — do not rely on group-level inheritance. Intermediate nodes (groups) must NOT have a `type` field.
+
+**Rules:**
+- Emit exactly one JSON object per line. No multi-line JSON.
+- Every intermediate group must have a `set_group` call.
+- Every leaf token must have a `set_token` call.
+- `path` is dot-notation from root, e.g. `colors.brand.primary` — no leading dots or slashes.
+- `type` must be one of the 13 valid DTCG types (see table below).
+- `value` must be valid JSON — string, number, array, or object depending on the type. Do NOT quote complex values.
+- Emit `set_group` calls before the `set_token` calls under them.
+- `description` on `set_token` documents your reasoning — always include it.
+
+---
+
+## Valid types
+
+Exactly **13** valid DTCG `$type` values:
+
+| type | Typical values |
+|---|---|
+| `color` | `"#0066ff"`, `"rgb(0,102,255)"` |
+| `dimension` | `"8px"`, `"1rem"`, `"0.5em"` |
+| `fontFamily` | `"Inter, sans-serif"` |
+| `fontWeight` | `400`, `"bold"` |
+| `duration` | `"200ms"`, `"0.3s"` |
+| `cubicBezier` | `[0.42, 0, 0.58, 1]` |
+| `number` | `1.5`, `100` |
+| `strokeStyle` | `"solid"`, `"dashed"` |
+| `border` | `{"width":"1px","style":"solid","color":"#000"}` |
+| `transition` | `{"duration":"200ms","timingFunction":[0.42,0,0.58,1],"delay":"0ms"}` |
+| `shadow` | `{"offsetX":"0px","offsetY":"4px","blur":"8px","spread":"0px","color":"#00000026"}` |
+| `gradient` | `[{"color":"#000","position":0},{"color":"#fff","position":1}]` |
+| `typography` | `{"fontFamily":"Inter","fontSize":"16px","fontWeight":400,"lineHeight":1.5,"letterSpacing":"0px"}` |
+
+---
+
+## Mapping guidance — Type resolution
+
+For each token value, determine the DTCG `$type` by reading the value and its context:
+
+| Value pattern | Type |
+|---|---|
+| Starts with `#`, `rgb(`, `hsl(`, `rgba(` | `color` |
+| Ends with `px`, `rem`, `em`, `%`, `vw`, `vh` | `dimension` |
+| `cubic-bezier(...)` or 4-element array | `cubicBezier` |
+| Ends with `ms` or `s` (animation/transition) | `duration` |
+| Font family name string | `fontFamily` |
+| Numeric `100`–`900`, or `bold`/`normal`/`light` | `fontWeight` |
+| Multi-property shadow value | `shadow` |
+| Multi-property border value | `border` |
+| `solid`, `dashed`, `dotted` alone | `strokeStyle` |
+| Composite font shorthand | `typography` |
+| Unitless number | `number` |
+
+When a token's type is ambiguous from its value alone, use its name as context (e.g. `$spacing-*` → `dimension`, `$duration-*` → `duration`). Document your reasoning in `description`. If no type fits, use `number` with a `"WARNING: type unknown"` description.
+
+Resolve variable references: if a value references another variable (e.g. SCSS `$black` in `rgba($black, 0.6)`, or a JS alias), substitute the referenced value before classifying.
+
+---
+
+## Grouping
+
+Organize tokens into a nested DTCG hierarchy that reflects their semantic purpose:
+
+1. Examine naming patterns and existing structure in the source (variable prefixes, object nesting, file-level categories).
+2. **For already-nested sources (JS/TS objects, JSON, Style Dictionary)**: derive paths directly from the source key hierarchy — lowercase each key segment and join with dots. Do NOT reorganize, rename, or flatten unless the original key is purely implementation-specific (e.g. `DEFAULT` as a single-child wrapper can be elided). The source structure IS the path. Example: `tokens[SPACING].DEFAULT.8` → `spacing.8`; `tokens[COLOR].text.standard` → `color.text.standard`; `tokens[SHADOW].level.1` → `shadow.level.1`.
+3. For flat names (SCSS variables, CSS custom properties): strip leading `--` or `$`; replace `-` and `_` separators with `.` to form nested paths. Use the first meaningful segment as the top-level group.
+4. If neither rule applies, propose a grouping strategy: by kind (`colors`, `spacing`, `typography`), by semantic role (`brand`, `semantic`, `neutral`), or hybrid.
+5. Emit a `set_group` call for every intermediate node before emitting any `set_token` calls under it.
+
+**Determinism rule**: Identical source input MUST produce identical paths on every run. Never invent synonyms, abbreviations, or alternative hierarchies for keys that already exist in the source. If `primary` is the key, the path segment is `primary` — not `brand-primary`, `main`, or `accent`.
+
+If the token-name sidecar is provided, use it as authoritative path assignments — it maps raw names to DTCG dot-notation paths already.
+
+---
+
+## Value handling
+
+Most values pass through as strings. For composite types, parse the raw string into the required JSON structure:
+
+**`border`** — parse `1px solid #ccc` into:
+```json
+{"width":"1px","style":"solid","color":"#cccccc"}
+```
+
+**`shadow`:**
+```json
+{"offsetX":"0px","offsetY":"4px","blur":"8px","spread":"0px","color":"#00000026"}
+```
+
+**`transition`:**
+```json
+{"duration":"200ms","delay":"0ms","timingFunction":[0.42,0,0.58,1]}
+```
+
+**`gradient`** — array of color stops:
+```json
+[{"color":"#000","position":0},{"color":"#fff","position":1}]
+```
+
+---
+
+## Examples
+
+Input (SCSS):
+```scss
+$brand-primary: #0066ff;
+$spacing-sm: 8px;
+$anim-speed: 200ms;
+$black: #1a1a1a;
+$overlay: rgba($black, 0.6);
+```
+
+Output:
+```
+Analyzing SCSS variables: 5 tokens across color, spacing, duration, and composite color categories.
+$overlay references $black — resolving to rgba(26, 26, 26, 0.6).
+{"tool":"set_group","path":"colors","description":"Brand and UI color tokens"}
+{"tool":"set_group","path":"colors.brand","description":"Brand palette"}
+{"tool":"set_token","path":"colors.brand.primary","type":"color","value":"#0066ff","description":"Brand primary color"}
+{"tool":"set_token","path":"colors.neutral.black","type":"color","value":"#1a1a1a","description":"Base black neutral"}
+{"tool":"set_token","path":"colors.neutral.overlay","type":"color","value":"rgba(26, 26, 26, 0.6)","description":"Semi-transparent overlay; $black variable resolved to #1a1a1a"}
+{"tool":"set_group","path":"spacing","description":"Spacing scale"}
+{"tool":"set_token","path":"spacing.sm","type":"dimension","value":"8px","description":"Small spacing step"}
+{"tool":"set_group","path":"motion","description":"Animation timing"}
+{"tool":"set_group","path":"motion.duration","description":"Duration values"}
+{"tool":"set_token","path":"motion.duration.speed","type":"duration","value":"200ms","description":"Standard animation speed"}
+```
+
+---
+
+## Edge cases
+
+- **Empty input** — emit nothing; the CLI will report 0 tokens stored.
+- **Path collision** — two raw tokens resolve to the same dot-notation path: append `_2`, `_3` to disambiguate, and add a `description` warning.
+- **Unrecognizable value** — no heuristic matches and `inferredKind` is invalid → use `number` with a warning in `description`.
+- **Complex composite value** — parse raw string into the required JSON structure; if parsing is ambiguous, use a best-effort parse and document in `description`.
+
+---
+
+## Validation step — Pre-emit checklist
+
+Before emitting any tool calls, verify:
+
+1. Every raw token in the input has exactly one `set_token` call.
+2. Every intermediate group has a `set_group` call.
+3. All `type` values are from the 13 valid DTCG types.
+4. `value` is valid JSON for the given type (string for color/dimension/etc., object for border/shadow/etc., array for gradient/cubicBezier).
+5. All `path` values use dot-notation with no leading dots or slashes.
+6. No duplicate paths.
+7. `set_group` calls precede the `set_token` calls under them.
+
+After the run, the developer can validate with:
+
+```
+experience-design-system-cli print validate --tokens <out-path>
+```
+
+Re-run or iterate on any tokens flagged by warnings until validation passes.

package/skills/map-tokens.md

@@ -0,0 +1,102 @@
+# Map Tokens — Token Restriction Narrowing Skill
+
+## Purpose
+
+For every design-category, token-typed prop already present in the generated CDF, decide whether there is concrete evidence to narrow it to a restricted subset (`$token.allowed`). Output one JSON tool call per line to stdout — the CLI reads it and writes each decision directly to the pipeline database. You do not write any files.
+
+This is a narrowing fallback, not a classification step: it does not re-classify props or touch anything that isn't already a design-category `token` prop. It also does not name a candidate universe — the universe is implicit, every token in the library whose type matches the prop's `$token.kind`. Your only job is to decide, from source evidence, whether that universe should be narrowed further.
+
+Default-path resolution is deterministic and happens in the CLI before this skill runs. A resolved `$default` is not model input for a mapping decision and never asks you to emit a mapping — a default alone does not restrict the allowed list.
+
+---
+
+## Input
+
+All input is embedded inline in the prompt before this file:
+
+- **Generated CDF so far** — design-category, token-typed props only, grouped by component. Every prop shown here already has `$type: "token"` and `$category: "design"`; you do not need to re-verify either.
+- **Token path index** — one or more sections, each a flat list of `path · type` lines (one leaf token per line, `$value` omitted). Every section is pre-scoped: a section titled with a `$token.kind` contains every leaf token of that type and no others; a prop with that `$token.kind` draws its candidates only from the matching section. The "full tree" section — present only when at least one prop has no `$token.kind` — lists every leaf token, unscoped. Never mix candidates across sections.
+- **Component source references** — the real file text for each component (bounded/truncated), rendered inline as a fenced code block, so you can look for an explicit restriction: a comment naming the valid tokens, or code that validates the prop against a fixed list of token paths. Content from files the component's own file imports (siblings) is inlined the same way, one hop deep — token-resolution logic often lives one file away from the component itself. When more sibling files were found than could be inlined, or a property has a use that fell outside the excerpt shown, the prompt says so explicitly; treat that as unknown evidence, not absence. **You have no filesystem access and no tools — a citation path is a label only, never something to open.** When a component's source couldn't be read (moved/deleted since extraction), there is no source evidence to narrow from — skip the prop.
+
+If no token path index is provided, there is nothing to narrow against — do not emit any tool calls.
+
+---
+
+## Decision tree
+
+For each design-category, token-typed prop shown in the "Generated CDF so far" section:
+
+1. **Prop type is a union of variant names** (e.g. `'primary' | 'secondary'`)? That prop should not be a `token` at all — the component receives a name and resolves it, which is the `enum` case in the classification step. Do not narrow it; narrowing cannot repair a wrong type. Emit nothing, and note in a prose line that it looks misclassified.
+2. **A default value or `tokenReference` is the prop's default, not a restriction.** `padding = tokens.spacingM` or a structured `tokenReference` tells you which token the prop *starts* on — it does not say the author may choose no other. Narrowing to that single path would leave the marketer one option, which is worse than no list. On its own, this evidence yields no tool call. If you narrow on other grounds (step 3), the default's path must be in the list.
+3. **Look for an explicit restriction** in the component source or its siblings: a comment naming the valid tokens, or code that validates/maps the prop against a fixed list of token paths (an allowlist array, a `satisfies` over specific token keys). If found, emit `$token.allowed` as the evidenced subset, scoped to tokens of the prop's `$token.kind`.
+4. **No explicit restriction?** Emit nothing. Omitting the list means "any token of this kind," which is correct and live — a guessed list is worse than none because it freezes the author's choices.
+5. **No plausible candidates at all** (no index entries of the prop's `$token.kind`)? Skip the prop.
+
+---
+
+## Output protocol
+
+Emit one JSON object per line. The CLI parses lines starting with `{`; anything else is prose, ignored by the parser — use it freely for reasoning.
+
+```
+{"tool":"map_token_prop","component":"<ComponentName>","prop":"<propName>","token_allowed":["colors.brand.primary","colors.brand.secondary"]}
+```
+
+Rules:
+
+- Emit exactly one JSON object per line. No multi-line JSON.
+- Only emit a call for a prop that appears in the "Generated CDF so far" section.
+- `token_allowed` is required and must be non-empty. If there's nothing to narrow to, emit no call at all.
+- Every path in `token_allowed` must be an individual **leaf** path that exists verbatim in the token path index section matching the prop's `$token.kind` (or the "full tree" section, for a prop with no `$token.kind`). Never emit a group/prefix path (e.g. `colors.brand`) — the index has no entry for groups, only leaves. Never invent a path, and never substitute a variant/enum name for a real token path; if you can't find a matching path, omit that entry.
+- No `$value` is provided in this step — reason from paths and `$type` only.
+
+---
+
+## Examples
+
+### Explicit restriction — narrow
+
+```ts
+interface ButtonProps {
+  /** Accepts only the brand colour tokens: colors.brand.primary or colors.brand.secondary. */
+  accentColor?: string;
+}
+const ACCENT_TOKENS = ['colors.brand.primary', 'colors.brand.secondary'] as const;
+```
+
+```
+accentColor is restricted to two named tokens by the doc comment and the ACCENT_TOKENS allowlist
+{"tool":"map_token_prop","component":"Button","prop":"accentColor","token_allowed":["colors.brand.primary","colors.brand.secondary"]}
+```
+
+### No restriction evidence — emit nothing
+
+`bgColor` is interpolated generically, with no comment or allowlist naming specific tokens, and no default. Any color token remains valid:
+
+```
+bgColor has no restriction evidence in source — any color token remains valid, so no tool call
+```
+
+---
+
+## Checklist
+
+Before emitting any tool calls, verify:
+
+1. Every `map_token_prop` call targets a prop that appears in the "Generated CDF so far" section.
+2. Every path in `token_allowed` is a leaf path that exists verbatim in the token path index, and matches the prop's `$token.kind` — no group/prefix paths, no variant names, nothing invented.
+3. `token_allowed` is never empty.
+4. Every emitted list includes the prop's own default token when it has one.
+5. No list was emitted on the strength of a default alone, and none targets a prop whose type is a union of variant names.
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing design tokens in the target Contentful space" JSON block listing tokens already present in the target space (by name + DTCG type).
+
+Prefer restricting to existing tokens over proposing new ones:
+
+1. When the source has restriction evidence AND a candidate maps semantically to an existing token by name/type, favor the existing token in the emitted `token_allowed` list.
+2. Never emit a `token_allowed` entry that contradicts the "path exists verbatim" rule above — the existing-tokens block is guidance, not a substitute for the token path index. If a token appears in the existing-entities list but not in the token path index, do not use it.
+3. If none of the existing tokens fit and the source's evidence is specific, proceed as usual — the diff will surface the new proposal.

package/skills/select-components.md

@@ -0,0 +1,235 @@
+# Analyze Select — Agent Component Selection Skill
+
+## Purpose
+
+Review the extracted React/Next.js component(s) provided below and decide whether each belongs in **Contentful Experience Orchestration** as a Component Type. The input is a JSON array — you may receive 1–N components in a single message. Output one JSON tool call per input component to stdout, named after the component. Tool calls may appear in any order.
+
+---
+
+## What is Contentful Experience Orchestration?
+
+Contentful Experience Orchestration is a Contentful product that enables **designers, developers, and marketers** to compose and manage digital experiences in Contentful. Component Types are used at every layer of the design system:
+
+- **Atoms** — low-level UI primitives: icons, buttons, inputs, badges
+- **Molecules** — composed UI units: cards, search fields, modals, navigation items
+- **Organisms** — larger sections: heroes, banners, footers, press release lists, parallax sections
+
+All three levels are valid Component Types in Contentful Experience Orchestration. Designers and developers compose atoms into molecules, molecules into organisms. Marketers then configure content and design values on any of these.
+
+The entity being defined — a **Component Type** — is the schema that tells Contentful what is configurable for this component. It defines design properties, content properties, and slots. Even a component with only a few configurable props is a valid Component Type.
+
+---
+
+## The one rule: is this the author-facing UI component?
+
+**Accept** the component if it is the component that directly defines the author-facing UI surface — regardless of whether it is an atom, molecule, or organism, and regardless of whether it has many or few configurable props. A footer icon with two props (`icon`, `label`) is just as valid as a parallax hero with fifteen props.
+
+**Reject** the component if its primary purpose is framework or data-loading infrastructure rather than the author-facing UI surface:
+
+- It is a React hook (name starts `use` or `Use`)
+- It is a pure context provider with no visual output
+- It is a Ninetailed/personalization platform wrapper (its job is routing to variants, not rendering content)
+- It is a data-fetch wrapper that loads data for a sibling renderer and then forwards that data into the sibling renderer
+- It is an analytics/event-tracking component (fires events, renders nothing)
+- It is a security or infrastructure utility (no UI at all)
+
+---
+
+## What NOT to use as a rejection reason
+
+These are **not** valid reasons to reject a component:
+
+| Invalid reason                                     | Why it is wrong                                                                                                           |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| "Only atoms/low-level"                             | Atoms are first-class Component Types in Contentful Experience Orchestration                                              |
+| "Tightly coupled to a parent component"            | Contentful Experience Orchestration handles composition at the experience layer                                           |
+| "Has A/B testing or personalization-related props" | These props are classified as `state` or excluded in the generate step — their presence does not disqualify the component |
+| "Has no marketer-configurable props"               | Marketers are not the only users; designers and developers configure components too                                       |
+| "Domain-specific or feature-level"                 | Press releases, newsrooms, search — all valid content components                                                          |
+| "Server-side or SSR"                               | Server components that render visible UI are valid                                                                        |
+| "Few configurable props"                           | One or two props is fine                                                                                                  |
+
+---
+
+## Reject only these categories
+
+| Category                                    | Why                                                                                                                                                                 |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **React hooks**                             | `useXxx` / `UseXxx` — functions, not renderable components. Zero visual output.                                                                                     |
+| **Pure context providers**                  | Wrap children to pass context but render no UI themselves                                                                                                           |
+| **A/B testing or personalization wrappers** | Components whose _entire purpose_ is routing users to content variants or tracking experiment participation — they render no UI of their own                        |
+| **Data-fetch wrappers**                     | Components whose job is to load or resolve data for a sibling renderer. Even if they eventually return visible UI, the sibling renderer is the real Component Type. |
+| **Analytics and event tracking**            | Components that only fire analytics events and render nothing visible                                                                                               |
+| **Security utilities**                      | Non-visual security primitives with no rendered output                                                                                                              |
+
+> **Variant routing rule**: Reject a component if its entire purpose is deciding _which_ content variant to show — that is framework infrastructure, not a Component Type. Do **not** reject a component merely because it _contains_ some A/B testing or personalization-related props — those props are handled as `state` in the generate step.
+
+> **Data-fetch wrapper rule**: Reject a component if it imports or calls a generated query hook, loads data, and then forwards that data into a sibling renderer. The sibling renderer is the Component Type; the data-loader wrapper is not.
+
+> **Utility-wrapper rule**: Reject a component if **all three** of the following are true:
+>
+> 1. It has no props that meaningfully shape user-facing content (no text strings, headings, image URLs, links, body content, rich text, or media references).
+> 2. The props it does have are purely structural or behavioral — e.g., `container`, `target`, `as`, `asChild`, render-prop callbacks, internal `ref` forwarding, focus/portal targets, debug toggles, or `children` only.
+> 3. It is a utility wrapper rather than a composable content surface. Concrete examples to reject under this rule: `Portal`, `SrOnly` (screen-reader-only wrappers), `FocusTrap`, `ErrorBoundary`, `Suspense` fallbacks, debug-only wrappers, and provider-shaped components whose only job is to forward children.
+>
+> Use `reject_component` with a reason like `"Utility wrapper — no authorable content surface"` or `"Structural-only component — no user-shaping props"`. This rule is additive to the categories above; do **not** use it to reject a component that has even one author-shaping prop (e.g., a `label`, `title`, `text`, `href`, `src`, or `richText` prop) — those still belong as Component Types per the "one rule" above.
+
+## Using `selectionContext`
+
+If the input includes `selectionContext`, treat it as the only repo-level context you may use. It is already bounded to the customer-provided project files and may include:
+
+- the component source file
+- sibling files in the same folder
+- import/export summaries
+- resolver or registry references
+- one likely parent usage site
+
+Use that bounded context to distinguish the author-facing renderer from infrastructure wrappers. In particular:
+
+- If the component imports a sibling renderer and mainly forwards fetched data into it, reject the wrapper and prefer the sibling renderer.
+- If sibling files show a presentation-focused renderer with the real authoring props, that renderer is the Component Type.
+- Resolver or parent-usage references help show how the repo treats the component, but they do not override the renderer-vs-wrapper rule.
+- Do not assume access to any files outside `selectionContext`.
+
+---
+
+## Output protocol
+
+Emit one JSON object on a single line. Lines not starting with `{` are ignored by the parser — use them freely for reasoning.
+
+**Two tool calls — emit exactly one per input component:**
+
+```
+{"tool":"select_component","name":"<ComponentName>","reason":"<brief reason>","confidence":<1-5>}
+
+{"tool":"reject_component","name":"<ComponentName>","reason":"<brief reason>","confidence":<1-5>}
+```
+
+**Rules:**
+
+- Emit exactly one JSON object per line. No multi-line JSON. No markdown fences.
+- Emit exactly one tool call per input component. Tool calls may appear in any order.
+- The `name` must match a component name from the input array exactly.
+- `reason` is a brief phrase documenting your decision.
+- `confidence` is your certainty (1–5) that the decision is correct:
+  - **5** — obvious case, no doubt (clear UI atom, or clear infrastructure with no visual output)
+  - **4** — likely correct, minor ambiguity
+  - **3** — uncertain, borderline component (few props, ambiguous purpose, could go either way)
+  - **2** — low confidence, guessing
+  - **1** — very unsure, human review strongly recommended
+- Emit prose lines (not starting with `{`) to log your reasoning before the final tool call.
+
+---
+
+## Examples
+
+```
+Analytics — fires analytics events, no visual output
+{"tool":"reject_component","name":"Analytics","reason":"analytics tracker — no visual output"}
+```
+
+```
+CanaryToken — security utility, no visual output
+{"tool":"reject_component","name":"CanaryToken","reason":"security utility — no visual output"}
+```
+
+```
+ClientExperience — personalization wrapper whose entire purpose is routing users to content variants
+{"tool":"reject_component","name":"ClientExperience","reason":"variant routing wrapper — entire purpose is A/B routing, not rendering UI"}
+```
+
+```
+ComponentMarker — experimentation marker component, no visual output
+{"tool":"reject_component","name":"ComponentMarker","reason":"experimentation marker — no visual output"}
+```
+
+```
+ComponentTracker — variant attribution tracker, no visual output
+{"tool":"reject_component","name":"ComponentTracker","reason":"variant attribution tracker — no visual output"}
+```
+
+```
+Refresh — client-side route refresh utility for personalization platform, no visual output
+{"tool":"reject_component","name":"Refresh","reason":"personalization route refresh utility — no visual output"}
+```
+
+```
+ServerExperience — server-side variant routing wrapper, no visual output
+{"tool":"reject_component","name":"ServerExperience","reason":"server-side variant routing wrapper — no visual output"}
+```
+
+```
+UseHelpNavigation — React hook, not a renderable component
+{"tool":"reject_component","name":"UseHelpNavigation","reason":"React hook — not a renderable component"}
+```
+
+```
+Providers — React context provider with no visual output
+{"tool":"reject_component","name":"Providers","reason":"pure context provider — no visual output"}
+```
+
+```
+HeroBannerGql — fetch wrapper that loads data and forwards it into HeroBanner
+It may eventually return visible UI, but the author-facing component is HeroBanner, not HeroBannerGql.
+{"tool":"reject_component","name":"HeroBannerGql","reason":"data-fetch wrapper — loads data for a sibling renderer rather than defining the author-facing UI surface"}
+```
+
+```
+FooterIcon — atom: renders an icon with optional label in the footer
+{"tool":"select_component","name":"FooterIcon","reason":"UI atom — renders icon with configurable icon and label"}
+```
+
+```
+FeedbackModal — modal dialog with visibility state
+{"tool":"select_component","name":"FeedbackModal","reason":"modal UI component with configurable visibility and content"}
+```
+
+```
+ActiveFilters — renders active filter chips with remove controls
+{"tool":"select_component","name":"ActiveFilters","reason":"filter UI component — renders visible filter chips"}
+```
+
+```
+FullSizeBarNoContent — full-width text bar with link; has some personalization state props
+The personalization props (hideContentForPersonalization, componentId) are state props handled in the generate step.
+The component renders real visual UI — a bar with text, chevron, and link.
+{"tool":"select_component","name":"FullSizeBarNoContent","reason":"content bar UI — renders visible bar with configurable text, link, and design"}
+```
+
+```
+ParallaxComponent — parallax marketing section; has some A/B testing props alongside real content props
+The A/B testing props (abmFallback, abmLinkedFromAccount) are state props, not the component's primary purpose.
+The component renders a parallax section with title, subtitle, and visual effects.
+{"tool":"select_component","name":"ParallaxComponent","reason":"marketing section UI — renders parallax content with configurable title, subtitle, and design"}
+```
+
+```
+NewsroomLandingPressReleases — press release list with pagination and locale
+{"tool":"select_component","name":"NewsroomLandingPressReleases","reason":"content list UI — renders press releases with configurable locale and pagination"}
+```
+
+```
+ServerHelpNavigation — server-side navigation with configurable search visibility and locale
+{"tool":"select_component","name":"ServerHelpNavigation","reason":"navigation UI — renders help navigation with configurable locale and search toggle"}
+```
+
+```
+TextImageCard — card with rich text and background image
+{"tool":"select_component","name":"TextImageCard","reason":"content card UI — configurable rich text, image, and layout"}
+```
+
+```
+SearchInput — search field with dropdown
+{"tool":"select_component","name":"SearchInput","reason":"search UI — configurable placeholder and state"}
+```
+
+---
+
+## Existing entities in the target space
+
+The preamble may include an "Existing components in the target Contentful space" JSON block and a rolled-up token summary. Use them as **signal, not as a filter**. Rules:
+
+1. Never let a name overlap force a decision. Acceptance is still driven purely by "does the codebase component render visible, authorable UI?" — a name match does not auto-accept, and a name conflict does not auto-reject.
+2. When a codebase component appears to correspond to an existing space component (name overlap, semantic overlap in the description), note it in your `reason` — e.g. `"accepted; likely maps to existing space component 'Button'"`. This surfaces the mapping for downstream review.
+3. When the space is mature (many existing components, dozens of tokens) and the codebase has thin wrappers with no visible UI difference, lean harder toward rejecting the wrappers. Extra noise in a mature space is more costly than in an empty one.
+4. When no overlap exists, the acceptance decision is unchanged from the rules above.

package/dist/src/tui/import/spawn-v1-import.d.ts

@@ -1,29 +0,0 @@
-interface StepResult {
-    step: string;
-    status: 'complete' | 'failed' | 'skipped';
-    durationMs?: number;
-    reason?: string;
-    detail?: Record<string, unknown>;
-    error?: string;
-}
-interface PipelineResult {
-    session: string;
-    project: string;
-    steps: StepResult[];
-    cycleError?: {
-        report: string[];
-    };
-}
-export interface SpawnV1ImportOptions {
-    project?: string;
-    tokens?: string;
-    onProgress?: (line: string) => void;
-}
-export interface SpawnV1ImportResult {
-    exitCode: number;
-    result?: PipelineResult;
-    stdout: string;
-    stderr: string;
-}
-export declare function spawnV1Import(options?: SpawnV1ImportOptions): Promise<SpawnV1ImportResult>;
-export {};

package/dist/src/tui/import/terminal-input.d.ts

@@ -1,2 +0,0 @@
-export declare function stopReadingTerminal(): Promise<void>;
-export declare function startReadingTerminal(): void;

package/legacy/dist/src/import/agent-model-resolve.d.ts

@@ -1,27 +0,0 @@
-/**
- * Resolution chain for the combined `--agent` override on `experiences import`.
- *
- * The wizard path previously hard-defaulted `--agent` to `'claude'` at the
- * commander layer, which (a) shadowed the stored `credentials.json` value when
- * the user passed no flag, and (b) made it impossible to distinguish "user
- * explicitly passed --agent claude" from "user passed nothing". The combined
- * flag accepts either `agent:model` or `agent model`.
- *
- * These helpers produce the resolved values to feed into `WizardApp` /
- * the import wizard:
- *
- *   1. CLI flag wins when provided.
- *   2. Otherwise, the value persisted in `credentials.json` (written by
- *      `experiences setup`) is used.
- *   3. Otherwise, the built-in default (currently `'claude'`) is used for
- *      the agent. Model has no default — agents pick a small/fast model
- *      themselves when no model is included in `--agent`.
- */
-/** Built-in fallback agent when neither a flag nor a stored preference is set. */
-export declare const DEFAULT_AGENT = "claude";
-export declare function parseAgentModel(value: string | undefined): {
-    agent?: string;
-    model?: string;
-};
-export declare function resolveAgent(flagValue: string | undefined, storedValue: string | undefined): string;
-export declare function resolveModel(flagValue: string | undefined, storedValue: string | undefined): string | undefined;

package/legacy/dist/src/import/command.d.ts

@@ -1,2 +0,0 @@
-import type { Command } from 'commander';
-export declare function registerImportCommand(program: Command): void;

package/legacy/dist/src/import/composition-options.d.ts

@@ -1,7 +0,0 @@
-export type CompositionOptionInput = {
-    prompt?: string[];
-};
-export type CompositionForwardingOptions = {
-    promptOverrides?: string[];
-};
-export declare function buildCompositionForwardingOptions(options: CompositionOptionInput): CompositionForwardingOptions;