@sxl-studio/bridge 1.5.1 → 1.7.0

package/dist/agent-recipes.js

@@ -96,6 +96,130 @@ export const RECIPE_INDEX = {
                 "render this spec as a figma flow",
             ],
         },
+        {
+            recipeId: "variable-usage",
+            userPhrases: [
+                "сколько раз используется accent.medium",
+                "where is this variable used",
+                "посчитай где используется переменная",
+                "render a page with all usages of accent.medium",
+                "найди все объекты с переменной",
+                "show me everywhere this token appears",
+                "выведи на страницу все места где встречается переменная",
+            ],
+        },
+        {
+            recipeId: "audit-coverage",
+            userPhrases: [
+                "проверь везде ли подкреплены переменные",
+                "найди объекты без переменных",
+                "audit raw values without variables",
+                "review the file for missing bindings",
+                "где hex заливки вместо токенов",
+                "найди объекты с дефолтными цветами",
+            ],
+        },
+        {
+            recipeId: "find-unused",
+            userPhrases: [
+                "какие переменные у меня не используются",
+                "find unused variables",
+                "which styles are dead",
+                "почисть неиспользуемые токены",
+                "найди мёртвые стили",
+            ],
+        },
+        {
+            recipeId: "bulk-variables",
+            userPhrases: [
+                "создай набор переменных по этому списку",
+                "import these variables in bulk",
+                "bulk create variables from spec",
+                "обнови переменные пакетно",
+                "перепривяжи алиасы переменных",
+                "rebind aliases from old token to new",
+                "найди дубликаты переменных и слей их",
+                "dedupe variables across collections",
+                "приведи коллекцию в алфавитный порядок",
+                "reorder variables alphabetically",
+            ],
+        },
+        {
+            recipeId: "auto-bind-from-audit",
+            userPhrases: [
+                "примени предложенные переменные к аудиту",
+                "apply variable coverage suggestions",
+                "автопривяжи переменные где есть подсказки",
+                "fix the audit by binding suggested variables",
+                "convert audit suggestions into bindings",
+            ],
+        },
+        {
+            recipeId: "bulk-styles",
+            userPhrases: [
+                "создай набор стилей по этому списку",
+                "import these paint/text/effect styles in bulk",
+                "bulk create paint styles from spec",
+                "обнови стили пакетно",
+                "найди дубликаты стилей и слей их",
+                "dedupe styles across the file",
+                "перепривяжи стили со старого на новый",
+                "rebind style consumers from one style to another",
+                "примени предложенные стили к аудиту",
+                "apply style coverage suggestions",
+            ],
+        },
+        {
+            recipeId: "style-drift",
+            userPhrases: [
+                "проверь дрейф стилей и переменных",
+                "audit style drift vs variables",
+                "стили рассинхронизированы с токенами",
+                "find paint styles that drifted from variables",
+                "сверь PaintStyle со списком ожидаемых цветов",
+                "verify styles against expected colors",
+            ],
+        },
+        {
+            recipeId: "mockup-builder",
+            userPhrases: [
+                "собери макет страницы из компонентов",
+                "build a mockup from existing components",
+                "сделай дашборд из карточек",
+                "render a screen using design system components",
+                "lay out cards in auto-layout",
+                "сложи макет из WCard и WButton",
+                "render a list of N cards from this dataset",
+                "построй продуктовую страницу по описанию",
+                "assemble a settings screen from existing components",
+            ],
+        },
+        {
+            recipeId: "bulk-compositions",
+            userPhrases: [
+                "сгенерируй все компоненты дизайн-системы",
+                "regenerate every WAccordion / WButton from JSON",
+                "пересобери компоненты по композициям",
+                "apply all SXL compositions in this workspace",
+                "обнови компоненты после правок в JSON",
+                "rebuild every composition that drifted",
+                "перегенерируй все компоненты после очистки файла",
+                "fresh-bake the design system from compositions",
+            ],
+        },
+        {
+            recipeId: "composition-drift",
+            userPhrases: [
+                "проверь рассинхрон композиций и компонентов",
+                "audit composition drift",
+                "какие компоненты не соответствуют JSON",
+                "find compositions that drifted from Figma",
+                "сверь tokens/components с реальными ComponentSet",
+                "verify SXL compositions still match the Figma design system",
+                "какие компоненты потерялись",
+                "show compositions whose tracked component was deleted",
+            ],
+        },
     ],
     decideBetween: [
         {
@@ -118,6 +242,76 @@ export const RECIPE_INDEX = {
             use_compose_with_variables_when: "goal is to generate a reusable Figma component with variable bindings from a design URL",
             use_doc_composition_when: "goal is to render a documentation frame from an existing composition file",
         },
+        {
+            between: ["variable-usage", "audit-coverage"],
+            use_variable_usage_when: "user names a specific variable and wants to know where / how often / 'покажи все места'",
+            use_audit_coverage_when: "user wants to know which nodes are NOT bound to variables (e.g. raw hex / dimensions)",
+        },
+        {
+            between: ["audit-coverage", "find-unused"],
+            use_audit_coverage_when: "the goal is finding nodes that lack a variable / style binding (where to ADD bindings)",
+            use_find_unused_when: "the goal is finding variables / styles that nothing references (what to DELETE)",
+        },
+        {
+            between: ["audit-coverage", "auto-bind-from-audit"],
+            use_audit_coverage_when: "user wants the LIST of missing bindings (no writes)",
+            use_auto_bind_from_audit_when: "user wants to APPLY the suggested variables (canvas write — apply_coverage_suggestions)",
+        },
+        {
+            between: ["bulk-variables", "doc-tokens"],
+            use_bulk_variables_when: "user wants to create / merge / refactor Figma Variables in bulk (one spec → many writes)",
+            use_doc_tokens_when: "user wants to render existing token values into a Figma doc frame",
+        },
+        {
+            between: ["bulk-styles", "bulk-variables"],
+            use_bulk_styles_when: "the targets are Figma local STYLES (PaintStyle / TextStyle / EffectStyle) — fillStyleId / textStyleId / effectStyleId fields",
+            use_bulk_variables_when: "the targets are Figma VARIABLES (boundVariables, valuesByMode)",
+        },
+        {
+            between: ["bulk-styles", "audit-coverage"],
+            use_bulk_styles_when: "user wants to ADD / MERGE / REFACTOR styles, or apply find_style_coverage_misses suggestions",
+            use_audit_coverage_when: "user only wants the LIST of nodes missing styleId / variable bindings (no writes)",
+        },
+        {
+            between: ["style-drift", "audit-coverage"],
+            use_style_drift_when: "user wants to verify EXISTING styles match the source of truth (variables / token snapshot)",
+            use_audit_coverage_when: "user wants to find nodes that have NO style binding at all",
+        },
+        {
+            between: ["style-drift", "find-unused"],
+            use_style_drift_when: "the goal is to detect rendered values that drifted from the source of truth",
+            use_find_unused_when: "the goal is to delete styles that nothing references",
+        },
+        {
+            between: ["mockup-builder", "doc-component"],
+            use_mockup_builder_when: "user wants to ASSEMBLE a screen / dashboard / list from many existing components in auto-layout",
+            use_doc_component_when: "user wants to DOCUMENT a single component (title + variants matrix + props table)",
+        },
+        {
+            between: ["mockup-builder", "compose-with-variables"],
+            use_mockup_builder_when: "the goal is to compose existing components into a layout (consumer)",
+            use_compose_with_variables_when: "the goal is to generate / refactor the COMPONENT itself from a design URL (producer)",
+        },
+        {
+            between: ["mockup-builder", "doc-flow"],
+            use_mockup_builder_when: "user wants a SINGLE auto-layout screen built from components (not a series of pages)",
+            use_doc_flow_when: "user wants a STORY of multiple pages / screens stacked side-by-side with captions",
+        },
+        {
+            between: ["bulk-compositions", "compose-with-variables"],
+            use_bulk_compositions_when: "the composition JSON files already exist in the plugin workspace (`tokens/components/W*.json`) and you want to (re)build many components in one call",
+            use_compose_with_variables_when: "the composition JSON does NOT exist yet — you start from a Figma URL, export composition JSON, and generate one component",
+        },
+        {
+            between: ["bulk-compositions", "composition-drift"],
+            use_bulk_compositions_when: "the user wants to WRITE (generate / apply) compositions",
+            use_composition_drift_when: "the user only wants to KNOW which compositions are out of sync (read-only)",
+        },
+        {
+            between: ["composition-drift", "style-drift"],
+            use_composition_drift_when: "the unit of comparison is a composition JSON ↔ Figma ComponentSet",
+            use_style_drift_when: "the unit of comparison is a local PaintStyle ↔ Variable / token snapshot",
+        },
     ],
     forbidden: [
         "Calling use_figma with a hand-written figma.* script when an SXL Bridge tool covers the task.",
@@ -419,4 +613,447 @@ export const RECIPE_VARIABLE_PALETTE = {
     ],
     doneCriteria: "One card per target variable next to the template; each swatch is bound to its variable; no use_figma script was used.",
 };
+export const RECIPE_VARIABLE_USAGE = {
+    id: "variable-usage",
+    title: "Find usages of a Figma variable (count + visualize)",
+    version: 1,
+    userPhrases: [
+        "сколько раз используется accent.medium",
+        "where is this variable used",
+        "посчитай где используется переменная",
+        "render a page with all usages of accent.medium",
+        "найди все объекты с переменной",
+        "выведи на страницу все места где встречается переменная",
+    ],
+    decideBetween: [
+        {
+            between: ["variable-usage", "audit-coverage"],
+            hint: "If user wants to find missing bindings (no variable assigned) → audit-coverage. If user names a variable and asks 'where is it used' → variable-usage.",
+        },
+    ],
+    context: "analyze_variable_usage returns a token-friendly summary (counts only). For the full node list, use find_variable_usages with cursor pagination. To visualize the result on the canvas, call render_variable_usage_page (creates a fresh page with cloned references). All three resolve transitive aliases — a variable that aliases the target counts as a usage and is included in target.aliasChain.",
+    preferredTools: [
+        "get_variables",
+        "analyze_variable_usage",
+        "find_variable_usages",
+        "render_variable_usage_page",
+    ],
+    forbidden: [
+        "Writing a use_figma script that walks node.boundVariables manually — analyze_variable_usage already does it (with alias resolution).",
+        "Calling find_variable_usages without limit/cursor for huge files — pagination keeps the agent fast and cheap.",
+        "Cloning nodes by hand into a new page — use render_variable_usage_page (chunked + auto-layout).",
+    ],
+    steps: [
+        "Identify the variable (variableId is best). If only a name, get_variables narrows it down.",
+        "Call analyze_variable_usage { variable, scope: 'page'|'file' } first — small response, decides next step.",
+        "If user wants details: find_variable_usages { variable, scope, limit }, optionally paginate via the returned cursor.",
+        "If user wants visualization: render_variable_usage_page { variable, scope: 'file', maxClones }. Confirm writesAllowed first via get_plugin_status.",
+    ],
+    doneCriteria: "Agent returned a count + breakdown (analyze) or a paginated record list (find) or created a 'Usage: <variable>' page (render). Transitive aliases included in target.aliasChain.",
+};
+export const RECIPE_AUDIT_COVERAGE = {
+    id: "audit-coverage",
+    title: "Audit nodes that lack a variable / style binding",
+    version: 1,
+    userPhrases: [
+        "проверь везде ли подкреплены переменные",
+        "найди объекты без переменных",
+        "audit raw values without variables",
+        "review the file for missing bindings",
+        "где hex заливки вместо токенов",
+    ],
+    decideBetween: [
+        {
+            between: ["audit-coverage", "find-unused"],
+            hint: "audit-coverage finds where to ADD bindings (raw values). find-unused finds variables/styles to DELETE.",
+        },
+    ],
+    context: "audit_variable_coverage returns SUMMARY only (counts + topOffenders). When `suggest=true` (default) the plugin matches every raw value against existing local variables; the suggestion in topOffenders / details lets the agent propose batch_bind_variables payloads. Style coverage (audit_style_coverage) reports nodes where neither a styleId nor a variable is bound.",
+    preferredTools: [
+        "audit_variable_coverage",
+        "find_variable_coverage_misses",
+        "audit_style_coverage",
+        "find_style_coverage_misses",
+        "batch_bind_variables",
+    ],
+    forbidden: [
+        "Walking the document manually with use_figma — audit_* tools cover the case (chunked, alias-aware).",
+        "Applying suggested bindings without user confirmation — coverage suggestions can be wrong on intentional raw values.",
+        "Running on scope='file' first when 'page' is enough — start narrow, widen on demand.",
+    ],
+    steps: [
+        "Start narrow: audit_variable_coverage { scope: 'page' } — confirm magnitude.",
+        "If acceptable, widen: scope: 'file'.",
+        "For details / fix-up: find_variable_coverage_misses { limit, cursor } — assemble a batch_bind_variables payload from suggestion entries.",
+        "For style coverage do the same with audit_style_coverage / find_style_coverage_misses.",
+    ],
+    doneCriteria: "Agent returned a summary (and optionally a batch_bind_variables proposal) without using use_figma. Coverage gaps are quantified per property and per page.",
+};
+export const RECIPE_BULK_VARIABLES = {
+    id: "bulk-variables",
+    title: "Bulk create / dedupe / rebind / reorder Figma Variables",
+    version: 1,
+    userPhrases: [
+        "создай набор переменных по этому списку",
+        "import these variables in bulk",
+        "bulk create variables from spec",
+        "обнови переменные пакетно",
+        "перепривяжи алиасы переменных",
+        "rebind aliases from old token to new",
+        "найди дубликаты переменных и слей их",
+        "dedupe variables across collections",
+        "приведи коллекцию в алфавитный порядок",
+        "reorder variables alphabetically",
+    ],
+    decideBetween: [
+        {
+            between: ["bulk-variables", "doc-tokens"],
+            hint: "If the user wants to render existing token values as documentation, switch to doc-tokens.",
+        },
+        {
+            between: ["bulk-variables", "auto-bind-from-audit"],
+            hint: "auto-bind-from-audit applies suggestions from audit_variable_coverage; bulk-variables operates on the variables themselves (CRUD + alias refactors).",
+        },
+    ],
+    context: "Phase B 'thick' commands cover four recurring refactors: (1) declarative bulk import / update via import_variable_spec, (2) duplicate detection + merge via dedupe_variables, (3) alias rewrites across modes via rebind_variable_aliases, (4) read-only ordering analysis via analyze_variable_order. All write commands accept a dry-run mode that returns the exact plan without touching Figma — agents should ALWAYS preview first and surface the plan to the user before committing.",
+    preferredTools: [
+        "get_variables",
+        "import_variable_spec",
+        "dedupe_variables",
+        "rebind_variable_aliases",
+        "analyze_variable_order",
+        "batch_bind_variables",
+    ],
+    forbidden: [
+        "Calling create_variable / set_variable_mode_value in a loop for 5+ items — use import_variable_spec.",
+        "Hand-writing a rebinding loop with rename_variable + set_variable_mode_value — use rebind_variable_aliases.",
+        "Treating analyze_variable_order as a write command — Figma Plugin API does not expose stable variable reordering, so this is diff-only.",
+        "Skipping dryRun on dedupe / rebind / import — always preview before committing.",
+        "Using use_figma scripts to traverse local variables — get_variables + Phase B tools cover the case.",
+    ],
+    steps: [
+        "Read the user's intent: bulk create vs dedupe vs rebind vs reorder. Each maps to one Phase B tool.",
+        "For BULK CREATE / UPDATE: pass spec.collections[] to import_variable_spec with dryRun: true first. The response lists added / updated / skipped variables and unresolved aliases. Re-call without dryRun to commit.",
+        "For DEDUPE: dedupe_variables { strategy: 'byName' | 'byDefaultModeValue' } — default is dry-run. Confirm the proposed survivor with the user, then re-call with apply: true.",
+        "For ALIAS REBIND: rebind_variable_aliases { mappings: [{ fromVariableId, toVariableId }], dryRun: true } first. The response counts how many valuesByMode entries would change. Re-call with dryRun: false to commit.",
+        "For ORDER: analyze_variable_order { collectionId, strategy } — read-only analysis. Return the moves[] to the user; manual reorder in the Variables panel is required.",
+    ],
+    doneCriteria: "Agent produced a single Phase B call (or two: dryRun preview + commit) that the plugin executed; the user has the diff before any write. No use_figma / batch loops were used.",
+};
+export const RECIPE_AUTO_BIND_FROM_AUDIT = {
+    id: "auto-bind-from-audit",
+    title: "Auto-apply audit_variable_coverage suggestions",
+    version: 1,
+    userPhrases: [
+        "примени предложенные переменные к аудиту",
+        "apply variable coverage suggestions",
+        "автопривяжи переменные где есть подсказки",
+        "fix the audit by binding suggested variables",
+        "convert audit suggestions into bindings",
+    ],
+    decideBetween: [
+        {
+            between: ["auto-bind-from-audit", "audit-coverage"],
+            hint: "audit-coverage produces the diagnosis (no writes); auto-bind-from-audit applies the prescribed variable. Always run audit first, confirm, then auto-bind.",
+        },
+    ],
+    context: "find_variable_coverage_misses returns suggestions per node + property: { nodeId, property, suggestion: { variableId, variableName } }. apply_coverage_suggestions translates that array into setBoundVariableForPaint / setBoundVariableForEffect / setBoundVariable writes. Default mode is dry-run — agent receives a preview the user can sign off on. Commit happens only when dryRun: false.",
+    preferredTools: [
+        "audit_variable_coverage",
+        "find_variable_coverage_misses",
+        "apply_coverage_suggestions",
+        "batch_bind_variables",
+    ],
+    forbidden: [
+        "Applying suggestions blindly without showing them to the user — coverage suggestions can be wrong on intentional raw values.",
+        "Calling bind_variable in a loop for each suggestion — apply_coverage_suggestions handles paths like fills[0].color / effects[2].color in one round-trip.",
+        "Skipping the dry-run preview — apply_coverage_suggestions is destructive (it writes bindings on the canvas).",
+    ],
+    steps: [
+        "Run find_variable_coverage_misses { scope: 'page' | 'file', limit, withSuggestion: true }. Filter entries that have a non-null suggestion.",
+        "Build the suggestions[] array: { nodeId, property, variableId } per entry.",
+        "Call apply_coverage_suggestions with dryRun: true (default). Surface the preview[] to the user.",
+        "On confirmation, re-call apply_coverage_suggestions with dryRun: false to commit. Canvas write — Dev Mode is blocked.",
+    ],
+    doneCriteria: "Bindings prescribed by the audit are applied to the canvas; the response reports applied / failed counts. No use_figma scripts were used.",
+};
+export const RECIPE_BULK_STYLES = {
+    id: "bulk-styles",
+    title: "Bulk create / dedupe / rebind LOCAL Figma styles + apply coverage suggestions (Phase C)",
+    version: 1,
+    userPhrases: [
+        "создай набор стилей по этому списку",
+        "import these paint / text / effect styles in bulk",
+        "bulk create paint styles from spec",
+        "обнови стили пакетно",
+        "найди дубликаты стилей и слей их",
+        "dedupe styles across the file",
+        "перепривяжи стили со старого на новый",
+        "rebind style consumers from one style to another",
+        "примени предложенные стили к аудиту",
+        "apply style coverage suggestions",
+        "конвертируй raw paints в стили",
+    ],
+    decideBetween: [
+        {
+            between: ["bulk-styles", "bulk-variables"],
+            hint: "bulk-styles wraps Figma local STYLES (fillStyleId / textStyleId / effectStyleId). For Figma VARIABLES (boundVariables / valuesByMode) use bulk-variables instead.",
+        },
+        {
+            between: ["bulk-styles", "audit-coverage"],
+            hint: "audit-coverage only LISTS missing bindings. bulk-styles applies them (apply_style_coverage_suggestions) and refactors styles in bulk.",
+        },
+        {
+            between: ["bulk-styles", "style-drift"],
+            hint: "style-drift verifies that styles match the source of truth (read-only). bulk-styles modifies styles or their consumers.",
+        },
+    ],
+    context: "Phase C 'thick' commands cover four recurring style refactors: (1) declarative bulk import / update via import_style_spec (PaintStyle + TextStyle + EffectStyle), (2) duplicate detection + merge via dedupe_styles (byName | bySignature), (3) bulk styleId rewriting on consumer nodes via rebind_style_consumers, (4) converting find_style_coverage_misses into setStyleId* writes via apply_style_coverage_suggestions. All write commands accept dry-run / preview mode that returns the plan WITHOUT touching Figma — agent should ALWAYS preview first and surface the diff to the user before committing.",
+    preferredTools: [
+        "get_local_styles",
+        "import_style_spec",
+        "dedupe_styles",
+        "rebind_style_consumers",
+        "find_style_coverage_misses",
+        "apply_style_coverage_suggestions",
+    ],
+    forbidden: [
+        "Calling create_paint_style / create_text_style / create_effect_style in a loop for 5+ items — use import_style_spec.",
+        "Hand-writing a styleId rewriting loop with set_fill_style / set_stroke_style — use rebind_style_consumers.",
+        "Skipping dryRun on dedupe_styles / rebind_style_consumers / apply_style_coverage_suggestions — always preview before committing.",
+        "Using use_figma scripts to traverse local styles — get_local_styles + Phase C tools cover the case.",
+        "Applying coverage suggestions blindly — coverage suggestions can be wrong on intentional raw values.",
+    ],
+    steps: [
+        "Read the user's intent: bulk create vs dedupe vs rebind consumers vs auto-bind from audit. Each maps to one Phase C tool.",
+        "For BULK CREATE / UPDATE: build spec.{paintStyles, textStyles, effectStyles}[] and call import_style_spec with dryRun: true first. SOLID paints accept `color: '#rrggbb[aa]'` shortcut. Re-call without dryRun to commit.",
+        "For DEDUPE: dedupe_styles { strategy: 'byName' | 'bySignature', styleType?: 'PAINT' | 'TEXT' | 'EFFECT' | 'ALL' } — default is dry-run. Confirm the proposed survivor (style with most consumers wins), then re-call with apply: true.",
+        "For STYLE REBIND: rebind_style_consumers { mappings: [{ fromStyleId, toStyleId }], dryRun: true } first. The response counts (node, field) pairs that would change. Re-call with dryRun: false to commit.",
+        "For AUTO-BIND FROM AUDIT: find_style_coverage_misses → assemble suggestions[{ nodeId, property, styleId }] → apply_style_coverage_suggestions { suggestions, dryRun: true }. Style assignments are PER-NODE (PaintStyle covers the whole fills[] array), so duplicates by (nodeId, field) land in skipped[]. Surface preview, then re-call with dryRun: false.",
+    ],
+    doneCriteria: "Agent produced a Phase C call (or two: dryRun preview + commit) that the plugin executed; the user approved the diff before any write. No use_figma / set_*_style loops were used.",
+};
+export const RECIPE_STYLE_DRIFT = {
+    id: "style-drift",
+    title: "Audit drift between local Paint styles and the source of truth (Phase C)",
+    version: 1,
+    userPhrases: [
+        "проверь дрейф стилей и переменных",
+        "audit style drift vs variables",
+        "стили рассинхронизированы с токенами",
+        "find paint styles that drifted from variables",
+        "сверь PaintStyle со списком ожидаемых цветов",
+        "verify styles against expected colors",
+    ],
+    decideBetween: [
+        {
+            between: ["style-drift", "audit-coverage"],
+            hint: "style-drift verifies EXISTING style values vs source of truth. audit-coverage finds nodes WITHOUT a style binding.",
+        },
+        {
+            between: ["style-drift", "bulk-styles"],
+            hint: "style-drift is READ-ONLY (Dev Mode safe). When drift is found and the user wants to fix it, switch to bulk-styles → import_style_spec to overwrite the drifted style values.",
+        },
+    ],
+    context: "audit_style_drift compares local PaintStyles to the source of truth in two modes: byName-vs-variables (auto-pairs styles with like-named local Variables) or explicit ({ styleId, expectedColor } expectations from a token snapshot). Returns findings[] (drift > tolerance) and skipped[] (styles that couldn't be compared — non-SOLID, non-COLOR variable, etc.). NO canvas writes — fully Dev-Mode-compatible.",
+    preferredTools: ["audit_style_drift", "get_variables", "import_style_spec"],
+    forbidden: [
+        "Walking PaintStyles + Variables manually with use_figma — audit_style_drift covers it (alias-aware).",
+        "Setting tolerance > 0 silently — when fuzzy matching is enabled, surface the value to the user.",
+        "Treating findings[] as canonical: skipped[] entries (no matching variable, non-SOLID paint, etc.) often need a follow-up question.",
+    ],
+    steps: [
+        "Decide the comparison source: token-driven workflow → byName-vs-variables; token snapshot from the transformer → explicit.",
+        "Call audit_style_drift { request: { mode: 'byName-vs-variables' } } (or explicit + expectations[]) with optional tolerance.",
+        "Surface findings[] grouped by source. For each, show actualColor → expectedColor + delta. Surface skipped[] separately.",
+        "If user wants to fix drift: build an import_style_spec.paintStyles[] payload that overrides the drifted values, dryRun first, then commit.",
+    ],
+    doneCriteria: "Agent produced a deterministic drift report. No canvas writes happened during the audit. If the user requested a fix, a follow-up import_style_spec was issued with explicit dryRun preview.",
+};
+export const RECIPE_FIND_UNUSED = {
+    id: "find-unused",
+    title: "Find unused local variables and styles",
+    version: 1,
+    userPhrases: [
+        "какие переменные у меня не используются",
+        "find unused variables",
+        "which styles are dead",
+        "почисть неиспользуемые токены",
+        "найди мёртвые стили",
+    ],
+    context: "find_unused_variables walks the file once, building two reference sets: bindings on every node + alias targets in any variable mode. unused = local variables \\ referenced. find_unused_styles does the equivalent for paint/text/effect styles. Both are read-only.",
+    preferredTools: [
+        "find_unused_variables",
+        "find_unused_styles",
+        "batch_delete_variables",
+    ],
+    forbidden: [
+        "Deleting variables / styles without explicit user confirmation — false positives are possible (e.g. variables used only in published libraries).",
+        "Running unused detection without explaining the scan boundary — it covers the current document only.",
+    ],
+    steps: [
+        "Run find_unused_variables / find_unused_styles — return the lists.",
+        "Confirm with the user which entries to remove (group by collection / styleType for clarity).",
+        "If approved: batch_delete_variables for variables; styles need manual removal (no batch tool yet).",
+    ],
+    doneCriteria: "Agent returned a deterministic list of unused variables / styles. Deletions only happened after explicit confirmation.",
+};
+export const RECIPE_MOCKUP_BUILDER = {
+    id: "mockup-builder",
+    title: "Assemble a mockup screen from existing design-system components (Phase D)",
+    version: 1,
+    userPhrases: [
+        "собери макет страницы из компонентов",
+        "build a mockup from existing components",
+        "сделай дашборд из карточек",
+        "render a screen using design system components",
+        "lay out cards in auto-layout",
+        "сложи макет из WCard и WButton",
+        "render a list of N cards from this dataset",
+        "построй продуктовую страницу по описанию",
+        "assemble a settings screen from existing components",
+    ],
+    decideBetween: [
+        {
+            between: ["mockup-builder", "doc-component"],
+            hint: "mockup-builder ASSEMBLES a screen from many components; doc-component DOCUMENTS a single component (variants + props).",
+        },
+        {
+            between: ["mockup-builder", "compose-with-variables"],
+            hint: "mockup-builder is the consumer (lays out instances); compose-with-variables is the producer (creates / refactors the component itself).",
+        },
+        {
+            between: ["mockup-builder", "doc-flow"],
+            hint: "mockup-builder = single auto-layout screen; doc-flow = multiple pages stacked side-by-side as a story.",
+        },
+    ],
+    context: "Phase D: thick orchestration over `figma.createInstance / setProperties / setBoundVariableForPaint / loadFontAsync`. Pipeline: (1) `find_components` to discover ids / keys + componentPropertyDefinitions; (2) `build_mockup` to assemble an auto-layout container from a declarative item tree (`instance | section | spacer | text`) with property / text / fill-binding overrides; (3) `apply_mockup_dataset` when the same template needs to be cloned per-row from a structured list.",
+    preferredTools: [
+        "find_components",
+        "build_mockup",
+        "apply_mockup_dataset",
+        "get_variables",
+    ],
+    forbidden: [
+        "Calling use_figma to write a hand-rolled `figma.createInstance(...) / setProperties(...)` loop when build_mockup covers the assembly.",
+        "Guessing component names instead of running find_components first — the user's file may have arbitrary local names.",
+        "Skipping dryRun for build_mockup / apply_mockup_dataset — always preview the resolved plan before writing to canvas.",
+        "Hand-coding fill colours when a Figma Variable is available — use fillBindings { variableId } so the mockup picks up theme switches automatically.",
+        "Loading fonts manually — build_mockup loads fonts on demand with a safe Inter Regular fallback.",
+        "Assuming property names like `size#123:0` — pass the human key (`size`); the plugin maps to the internal `name#defId` suffix via `componentProperties`.",
+    ],
+    steps: [
+        "Run find_components { query | prefix?, includeProperties: true, kind?: 'COMPONENT' | 'COMPONENT_SET', limit?: 50 } to enumerate available components. Cache the (id, name, propertyDefinitions, defaultVariantId) list.",
+        "If the user wants library components, set includeRemoteInstances: true so library components instantiated in this file are included; otherwise stay local-only.",
+        "Decide the layout: VERTICAL stack of sections, HORIZONTAL row of cards, or WRAP grid. Pick itemSpacing / padding to match the user's intent (e.g. 16px gutters).",
+        "Build the items[] tree. Use `instance` for components (one of componentId | componentKey | componentName), `section` for nested auto-layout frames, `spacer` for explicit gaps, `text` for bare TEXT layers (TEXT styles can be applied via textStyleId).",
+        "For property / text / fill overrides on instances: pass `properties` (human keys), `textOverrides[]` (layerName + value), `fillBindings[]` (variableId; optional layerName when only one child should receive the fill).",
+        "Call build_mockup { ..., dryRun: true } first. The plugin returns a resolved plan with per-item ok/error. If any errors → fix the spec, do not commit.",
+        "Re-call build_mockup without dryRun to write to canvas. Capture rootNodeId for downstream tools (e.g. document the mockup, run audit_variable_coverage on it).",
+        "If the user wants N cards from a dataset, leave one template instance inside the mockup (kind: 'instance'), then call apply_mockup_dataset { templateNodeId, rows[], dryRun: true } → preview → commit. removeTemplate: true deletes the placeholder after cloning.",
+    ],
+    doneCriteria: "Agent produced one (or a sequence of) Phase D calls (find_components → build_mockup [dryRun → commit] → optional apply_mockup_dataset) that the plugin executed without use_figma. The user approved each diff before commit. The mockup uses real components by id/key (not duplicated geometry) and binds Figma Variables instead of raw hex when a variable is available.",
+};
+export const RECIPE_BULK_COMPOSITIONS = {
+    id: "bulk-compositions",
+    title: "Bulk generate / apply many composition files in one call (Phase E)",
+    version: 1,
+    userPhrases: [
+        "сгенерируй все компоненты дизайн-системы",
+        "regenerate every WAccordion / WButton / WInput from JSON",
+        "пересобери компоненты по композициям",
+        "apply all SXL compositions in this workspace",
+        "обнови компоненты после правок в JSON",
+        "rebuild every composition that drifted",
+        "перегенерируй все компоненты после очистки файла",
+        "fresh-bake the design system from compositions",
+    ],
+    decideBetween: [
+        {
+            between: ["bulk-compositions", "compose-with-variables"],
+            use_bulk_compositions_when: "the composition JSON files already exist in the plugin workspace (`tokens/components/W*.json`) and you want to (re)build many components in one call",
+            use_compose_with_variables_when: "the composition JSON does NOT exist yet — you start from a Figma URL, export composition JSON, and generate one component",
+        },
+        {
+            between: ["bulk-compositions", "composition-drift"],
+            use_bulk_compositions_when: "the user wants to WRITE (generate / apply) compositions",
+            use_composition_drift_when: "the user only wants to KNOW which compositions are out of sync (read-only)",
+        },
+        {
+            between: ["bulk-compositions", "doc-component"],
+            use_bulk_compositions_when: "the goal is to (re)build the actual COMPONENT in Figma from composition JSON",
+            use_doc_component_when: "the goal is to render a documentation FRAME for an existing component",
+        },
+    ],
+    context: "Phase E thick orchestration around `handleGenerateComposition` / `handleApplyComposition`. Discovers every `$type:composition` file in the plugin workspace (same source as `list_compositions`), filters by `fileIds | names | prefix`, then runs the per-file pipeline with per-item error isolation (`continueOnError: true` by default). `operation: 'auto'` mirrors the manual UX (apply if a tracked component already exists, otherwise generate); `'generate'` forces a fresh ComponentSet rebuild; `'apply'` forces apply onto an existing component. `dryRun: true` returns the resolved plan WITHOUT touching the canvas — Dev Mode safe.",
+    preferredTools: [
+        "list_compositions",
+        "audit_composition_drift",
+        "bulk_generate_compositions",
+    ],
+    forbidden: [
+        "Calling generate_composition / apply_composition in a hand-written loop for 3+ files — use bulk_generate_compositions to keep per-item error isolation, progress events, and idempotency.",
+        "Using bulk_generate_compositions with `operation: 'apply'` against compositions that have no diff-id tracking entry — the handler will fall back to `generate` per item; if the user explicitly asked for apply-only, run audit_composition_drift first to confirm tracking exists.",
+        "Skipping dryRun when the user expects a preview — agent must surface the resolved plan (file count, expected variant counts, errors) before committing canvas writes.",
+        "Operating on every composition without filters when the user only mentioned a single component family — pass `prefix: 'WAccordion'` / `names: [...]` to keep the run small and idempotent.",
+        "Interpreting `success: true, variantsCreated: 0` as a failure — that's normal idempotent behaviour for `apply` when nothing changed.",
+    ],
+    steps: [
+        "Discover what's in the workspace: read `sxl://compositions/index` (or call list_compositions) to get the full set of composition files + names.",
+        "(Optional) Run audit_composition_drift first when the user is unsure which components actually drifted. Use the report to build the `fileIds` filter for the next step.",
+        "Pick filter scope: `fileIds: [...]` for surgical re-builds, `prefix: 'W'` for a whole DS family, `names: ['WButton', 'WInput']` for a curated list. Omit all filters only when the user explicitly asked to rebuild everything.",
+        "Pick operation: `auto` (default — manual UX), `generate` (force rebuild — use after structural changes / corrupted tracking), `apply` (force apply onto existing — use only when tracking is healthy).",
+        "Call bulk_generate_compositions { ..., dryRun: true } first. The plugin returns the resolved plan with per-item composition name + parse status. If any errors → fix the JSON / config, do not commit.",
+        "Re-call without dryRun to commit. Capture summary { total, processed, created, updated, failed, elapsedMs } and surface it to the user.",
+        "On per-item failures, the run continues by default. Group `items[].errors` by composition for the user; if `continueOnError: false` was set, only `items` up to the first failure are present.",
+    ],
+    doneCriteria: "Agent produced one or two bulk_generate_compositions calls (dryRun → commit) that touched only the requested compositions. Per-item errors were surfaced; failures did not silently rebuild the wrong components. No hand-written generate/apply loops were issued.",
+};
+export const RECIPE_COMPOSITION_DRIFT = {
+    id: "composition-drift",
+    title: "Audit drift between composition JSON files and Figma components (Phase E)",
+    version: 1,
+    userPhrases: [
+        "проверь рассинхрон композиций и компонентов",
+        "audit composition drift",
+        "какие компоненты не соответствуют JSON",
+        "find compositions that drifted from Figma",
+        "сверь tokens/components с реальными ComponentSet",
+        "verify SXL compositions still match the Figma design system",
+        "какие компоненты потерялись",
+        "show compositions whose tracked component was deleted",
+    ],
+    decideBetween: [
+        {
+            between: ["composition-drift", "bulk-compositions"],
+            use_composition_drift_when: "user wants the LIST of out-of-sync compositions (read-only — Dev Mode safe)",
+            use_bulk_compositions_when: "user wants to FIX the drift (write — bulk_generate_compositions { fileIds: drifted, operation: 'generate' })",
+        },
+        {
+            between: ["composition-drift", "style-drift"],
+            use_composition_drift_when: "the unit of comparison is a composition JSON ↔ Figma ComponentSet",
+            use_style_drift_when: "the unit of comparison is a local PaintStyle ↔ Variable / token snapshot",
+        },
+        {
+            between: ["composition-drift", "find-unused"],
+            use_composition_drift_when: "the goal is to verify EXISTING compositions still match the Figma scene",
+            use_find_unused_when: "the goal is to clean up dangling local variables / styles (different unit)",
+        },
+    ],
+    context: "audit_composition_drift compares every `$type:composition` file in the plugin workspace against the Figma component it tracked in `diff-id.compositions`. Per-composition status: `linked` (tracking entry valid + Figma node matches), `unlinked` (no tracking — never generated), `drift` (Figma node renamed / variant count mismatch / wrong type), `missing` (tracking points to a deleted node). Findings include human-readable `reason`. Fully Dev-Mode-compatible — never touches the canvas.",
+    preferredTools: ["audit_composition_drift", "list_compositions", "bulk_generate_compositions"],
+    forbidden: [
+        "Walking diff-id.json + Figma scene tree manually with use_figma — audit_composition_drift covers it.",
+        "Treating `unlinked` as drift — it just means the composition was never generated. Surface it as a separate bucket.",
+        "Auto-fixing without confirmation — drift can mean the designer intentionally renamed the Figma component; ask before running bulk_generate_compositions.",
+    ],
+    steps: [
+        "Run audit_composition_drift with appropriate filters: `prefix: 'W'` for the whole DS, `names: [...]` for a curated list, no filters for the full workspace.",
+        "Group findings by status (linked / unlinked / drift / missing) and surface counts to the user.",
+        "For each `drift` / `missing` finding, surface: composition name, fileId, status, reason, expected vs actual variant count, tracked componentSetId.",
+        "If user wants to fix drift: call bulk_generate_compositions { fileIds: [drift+missing fileIds], operation: 'generate', dryRun: true } first → preview → commit.",
+        "For `unlinked` findings: ask whether to generate them as new components (bulk_generate_compositions { operation: 'auto' }) or leave them.",
+    ],
+    doneCriteria: "Agent returned a deterministic drift report with per-composition status. No canvas writes happened during the audit. If the user approved a fix, a follow-up bulk_generate_compositions was issued with explicit dryRun preview.",
+};
 //# sourceMappingURL=agent-recipes.js.map