bluekiwi 1.2.4 → 2.0.0

package/dist/assets/skills/bk-design/SKILL.md

@@ -1,426 +1,589 @@
 ---
 name: bk-design
-description: BlueKiwi workflow design skill. Takes a natural language goal and designs a structured workflow, then registers it on the server. This skill should be used when the user says "/bk-design", "create workflow", "design new workflow", or wants to build a new BlueKiwi workflow from scratch.
+description: Create, update, export, and apply BlueKiwi design systems from the registry through MCP tools. Use when the user says "/bk-design", asks to create a design system, apply a registered design system, export a design system skill, or update brand/design tokens in BlueKiwi.
 user_invocable: true
 ---
 
-# BlueKiwi Workflow Design
+# BlueKiwi Design System
 
-Design a structured workflow from a natural language goal and register it on the BlueKiwi server.
+Use BlueKiwi's design-system registry through MCP tools. Do not write directly
+to the database or call raw HTTP APIs when MCP tools are available.
 
-**Which creation skill to use?**
+## Core Concepts
 
-- **`/bk-design`** (this one) — start from a natural-language goal, design the node structure from scratch.
-- **`/bk-import`** — the user already has an external resource (GitHub repo, URL, local skill, pasted text) to convert into a workflow.
-- **`/bk-improve`** — there's already a registered workflow that needs a better version.
+A BlueKiwi design system is a versioned registry resource containing:
 
-## Argument Handling
+- metadata: title, slug, description, status
+- taxonomy metadata: category and surface (`web`, `slides`, `docs`, `image`,
+  `video`, or `audio`)
+- schema and split token JSON (`color_tokens`, `typography_tokens`,
+  `component_tokens`)
+- guidelines markdown
+- SKILL.md-compatible markdown
+- component documents for React, pure HTML/CSS, Tailwind CSS, and shadcn/ui
+  components
+- assets such as CSS, templates, references, logos, or images
 
-- `/bk-design` → Ask for the goal via AskUserQuestion.
-- `/bk-design <goal>` → Start designing from the provided goal.
+## Required Interaction Gate
 
-## Core Principles
+If the user invokes `bk-design` without explicitly saying what operation they
+want, ask an `AskUserQuestion` before using mutation tools. The first question
+must classify the intent:
 
-- One node = **one agent action**. Split overly large chunks.
-- `node_type: "action"` = regular agent step; auto-advances unless `hitl: true`.
-- `node_type: "gate"` = user decision point; always pauses for human approval.
-- `node_type: "loop"` = repeating step; set `loop_back_to` to the target step order.
-- `hitl: true` = action node that requires explicit human approval before advancing. Default: `false`.
-- `visual_selection: true` = gate node where the agent renders an HTML UI and the user makes a selection by clicking (instead of typing). Only valid on `gate` nodes. Default: `false`.
+- create a design system
+- update a design system
+- delete a design system
+- load or export a design system
 
-## Execution Steps
+Use `AskUserQuestion` for selection and confirmation steps whenever the next
+action would create, update, or delete registry data. Do not infer destructive
+intent from vague wording.
 
-### Step 1: Understand the Goal
+### Non-Negotiable Operation Protocol
 
-Extract the goal from arguments. If none, ask via AskUserQuestion:
+Follow this order for every `bk-design` invocation:
 
-- header: "What to build?"
-- "What task would you like to automate? Please describe in detail."
-- options: ["Competitor analysis", "Code review", "Report generation", "Type my own"]
+1. Determine intent: create, update, delete, load, export, seed, or apply.
+2. If intent is missing or ambiguous, ask `AskUserQuestion` and stop until the
+   user answers.
+3. For create/update/delete, call `list_design_systems` before choosing a
+   target or deciding whether the registry is empty.
+4. For create, compare the request with existing title, slug, category,
+   surface, description, and version family. If any system is plausibly
+   related, ask whether to create a new system or create a new version.
+5. For update/delete, ask the user to choose the target system from the loaded
+   list before any mutation.
+6. Ask whether the operation applies to the whole system or a category/entry.
+7. Show the selected target and intended tool call in plain language, then ask
+   for confirmation before destructive or broad replacement operations.
+8. Run `lint_design_system` after substantial create/update work. Resolve
+   errors before saying the system is ready.
 
-If "Type my own" → accept free-text goal input.
+Do not call `create_design_system`, `update_design_system`,
+`create_design_system_version`, `delete_design_system`,
+`update_design_system_section`, `delete_design_system_section`,
+`upsert_design_system_section_entry`, `delete_design_system_section_entry`,
+`upsert_design_component`, `delete_design_component`,
+`add_design_system_asset`, or `delete_design_system_asset` until the required
+selection gates above are satisfied.
 
-### Step 2: Check for Existing Workflows
+### AskUserQuestion Templates
 
-Call `list_workflows` to check for similar existing workflows.
+Use short, concrete choices. Prefer three to five options. Always include a
+free-form custom option when design direction is involved.
 
-If a similar one is found, ask via AskUserQuestion:
+Intent question:
 
-- header: "Existing workflow"
-- "'{title}' already exists. Create a new one or improve the existing one?"
-- options: ["Create new", "Improve existing (switch to /bk-improve)"]
+- "What do you want to do with BlueKiwi design systems?"
+- Options: Create, Update, Delete, Load/Export
 
-If "Improve existing" → switch to `/bk-improve` flow.
+Create relationship question after `list_design_systems`:
 
-### Step 3: Select Folder
+- "I found related design systems. Should I create a new version or a separate
+  system?"
+- Options: New Version, Separate System, Show Details
 
-Call `list_folders` to get the folder list.
+Target question for update/delete:
 
-Ask via AskUserQuestion:
+- "Which design system should I modify?"
+- Options should include title, slug, version, category, surface, and active
+  marker when available.
 
-- header: "Save location"
-- "Which folder should this be saved in?"
-- options: folder name list (up to 4) + "My Workspace (default)"
+Scope question:
 
-### Step 4: Design Workflow Structure
+- "What scope should this operation affect?"
+- Options: Whole System, Colors, Typography, Components, One Component,
+  Guidelines/Skill, Assets
 
-Analyze the goal and design the nodes. **Every node instruction must satisfy the Instruction Depth Standard below before proceeding to Step 5.**
+Depth question for create or material visual update:
 
-**Node structure example:**
+- "How detailed should the design-system process be?"
+- Options: LoFi Fast Draft, HiFi Recommended Directions
 
-```json
-{
-  "title": "Clarify Goal",
-  "instruction": "## Goal Clarification\n\nExtract precise requirements before any work begins:\n\n1. Read the user's stated goal word by word and list every ambiguity.\n2. For each ambiguity, formulate one closed-ended question (yes/no or multiple choice).\n3. Ask the questions one at a time — never batch them.\n\n**Output**: A numbered list of confirmed constraints and success criteria.\n**Verification**: Every ambiguity is resolved; no open questions remain.",
-  "node_type": "action",
-  "hitl": false,
-  "order": 1
-}
-```
-
-Show the design to the user:
-
-```
-Designed workflow: <title>
-━━━━━━━━━━━━━━━━━━━━━━━━━
-1. [Clarify Goal]     action
-2. [Collect Data]     action
-3. [Run Analysis]     action
-4. [Review Results]   gate ← pauses for human approval
-5. [Generate Report]  action
-━━━━━━━━━━━━━━━━━━━━━━━━━
-5 steps total
-```
-
-Ask via AskUserQuestion:
-
-- header: "Confirm"
-- "Create the workflow with this structure?"
-- options: ["Create", "Edit", "Cancel"]
-
-If "Edit" → accept modification input and redesign.
+Generation mode question:
 
-### Step 5: Register Workflow
-
-Call `create_workflow`:
+- "How should I generate the system?"
+- Options: Guided Category Loop, Automatic Draft
+
+Confirmation question:
+
+- "Confirm this change before I write to BlueKiwi."
+- Options: Apply Change, Revise Plan, Cancel
+
+### Required Dialogue Scenarios
+
+Use these scenarios as behavioral tests when deciding whether to ask or act:
+
+- User says only `/bk-design` or "design system": ask the intent question and
+  stop. Do not call mutation tools.
+- User says "make a design system" without enough product context: call
+  `list_design_systems`, ask whether related systems should become a new
+  version or a separate system when applicable, then run the depth and
+  generation mode questions.
+- User says "update the colors": call `list_design_systems`, ask the target
+  system, ask whether the scope is the full palette or specific tokens, load
+  the current colors, then confirm the intended scoped tool call.
+- User says "delete this design system" without a concrete id or slug: call
+  `list_design_systems`, ask the target, ask whether to delete the selected
+  version or full family, then confirm before deletion.
+- User says "use the current design system": call `get_active_design_system`.
+  If one is set, confirm whether to use it. If none is set, call
+  `list_design_systems` and ask the user to choose one.
+- User asks for an automatic HiFi design system: show three tailored
+  recommendations unless they explicitly asked you to choose automatically.
+  If they asked you to choose, state the selected direction and assumptions,
+  draft the system, ask for feedback, then write only after approval unless the
+  user already gave explicit permission to write automatically.
+
+### Design Depth Gate
+
+Before creating or materially updating design tokens, typography, or
+components, ask whether the user wants a LoFi or HiFi design-system process.
+
+- LoFi: create a practical, lightweight token/component set from the user's
+  stated requirements. Keep the questionnaire short and optimize for speed.
+- HiFi: run a richer design exploration before writing registry data. Read
+  `references/hifi-design-playbook.md` and `references/craft-rules.md` first.
+  Use them as the local basis for recommendations, auto-generation, quality
+  checks, and feedback loops.
+
+For HiFi, show at least three recommended design directions before generation.
+Each recommendation should include:
+
+- visual concept and product fit
+- color palette direction
+- typography direction
+- component style direction
+- tradeoffs or constraints
+
+Always allow a custom user request as an option alongside recommendations.
+
+If the user asks you to proceed automatically, select the strongest direction
+from `references/hifi-design-playbook.md` based on the user's product context,
+state the assumptions, generate the complete design-system draft, summarize the
+result by category, and ask for feedback before writing registry mutations.
+
+### Generation Mode Gate
+
+After the user chooses LoFi or HiFi, ask how to generate the design system:
+
+- guided loop: ask category-by-category questions, then create tokens,
+  typography, and components from explicit user direction
+- automatic draft: generate the whole initial design system automatically, then
+  ask for feedback and revise in follow-up loops
+
+For guided loops, ask what component families to include before generating
+component specs. Offer a practical checklist such as:
+
+- foundations: colors, typography, spacing, radius, shadows, motion
+- controls: button, input, textarea, checkbox, radio, switch, select, slider
+- navigation: tabs, breadcrumb, menu, sidebar, pagination
+- feedback: alert, toast, badge, progress, skeleton
+- layout/data: card, table, dialog, drawer, accordion, tooltip, popover
+- domain-specific components requested by the user
+
+For automatic drafts, generate a complete first pass, summarize the design
+system by category, then ask for feedback before final registry mutation.
+
+### Design Direction Synthesis
+
+For HiFi recommendations, do not paste external skill instructions into the
+answer or the registry. Use `references/hifi-design-playbook.md` and
+`references/craft-rules.md` to synthesize BlueKiwi-native recommendations.
+The recommendations must be tailored to the product context and should not
+sound like generic theme names.
+
+Each direction must include:
+
+- target user and product fit
+- palette with semantic roles, not only color names
+- typography roles and rationale
+- component coverage preset or custom component plan
+- density, radius, motion, and accessibility stance
+- known tradeoff
+
+If the user chooses automatic generation, select one direction yourself based
+on the request, state the assumptions, generate a full draft, and ask for
+feedback before writing. If the user explicitly says to write automatically
+without another approval round, still run lint after writing and summarize any
+warnings.
+
+### Create Gate
+
+For create intent:
+
+1. Call `list_design_systems` first.
+2. If an existing design system appears related by product, brand, slug, or
+   domain, ask whether to create a new version of that system or create a
+   separate new design system.
+3. If the user chooses versioning, use `create_design_system_version`.
+4. If the user chooses a separate system, use `create_design_system`.
+5. Run the Design Depth Gate and Generation Mode Gate before creating tokens,
+   typography, or component documents.
+
+### Update Gate
+
+For update intent:
+
+1. Call `list_design_systems`.
+2. Ask the user to choose the design system to update from the list.
+3. Ask whether to update the whole design system or a specific design category.
+4. If category-level, offer categories such as colors, typography/fonts,
+   components, guidelines, skill, schema, tokens, or assets.
+5. Show the relevant list or current section value, then ask the user to
+   confirm the target before applying changes.
+6. Use section or component tools for scoped changes. Use full
+   `update_design_system` only for metadata or intentional whole-payload edits.
+7. If the update changes tokens, typography, or components materially, run the
+   Design Depth Gate and Generation Mode Gate before applying the update.
+
+### Delete Gate
+
+For delete intent:
+
+1. Call `list_design_systems`.
+2. Ask the user to choose the design system to delete.
+3. Ask whether to delete only the selected version, the full version family, a
+   single component, or a single asset.
+4. Confirm the selected target before calling any delete tool.
+
+## Tool Map
+
+- `list_design_systems` — find relevant systems.
+- `get_design_system` — load metadata, active payload, and assets.
+- `list_design_system_events` — inspect recent change/provenance events for
+  one design system after updates, version changes, or rollback.
+- `get_active_design_system` — load the current user's active design-system
+  context.
+- `set_active_design_system` — pin a visible system as the active context.
+- `clear_active_design_system` — clear the active context.
+- MCP resources — read-heavy lookups expose `bk://design-systems/<id>/DESIGN.md`
+  and `bk://active/design-system/DESIGN.md` when the client supports resources.
+  Prefer these resources for applying an existing design system to generation
+  work.
+- `create_design_system` — create a new registry item.
+- `seed_design_systems` — seed the built-in BlueKiwi design-system library into
+  the current user's `[Design Seeds]` folder. Use it when the registry is empty
+  or the user asks for starter/reference systems.
+- `update_design_system` — update metadata or active payload.
+- `create_design_system_version` — publish a new active version.
+- `list_design_system_versions` — list active and inactive versions in one
+  family before update, rollback, or comparison decisions.
+- `diff_design_system_versions` — compare two versions and inspect metadata,
+  token, component, markdown, and asset changes.
+- `activate_design_system_version` — activate an existing version in its
+  family. Use this for rollback only after listing versions, comparing the
+  target, and confirming with the user.
+- `delete_design_system` — delete one version or a full version family.
+- `get_design_system_section` — load one category such as colors,
+  typography, components, guidelines, skill, or assets.
+- `update_design_system_section` — replace or shallow-merge one category.
+- `delete_design_system_section` — clear one category.
+- `get_design_system_section_entry` — load one keyed token/spec from an
+  object category.
+- `upsert_design_system_section_entry` — create or replace one keyed
+  token/spec inside a category.
+- `delete_design_system_section_entry` — delete one keyed token/spec.
+- `get_design_component` — load one component by name with normalized docs.
+- `upsert_design_component` — create or replace one component spec by name.
+- `delete_design_component` — delete one component spec by name.
+- `lint_design_system` — run deterministic checks for token coverage, contrast,
+  component states, shadcn/Tailwind metadata, and agent-readability gaps.
+- `add_design_system_asset` — attach a small text/base64 asset.
+- `delete_design_system_asset` — remove obsolete source assets.
+- `export_design_system` — export `json`, `skill`, `design`, `bundle`,
+  `package`, or `adapters` format. `bundle` returns `DESIGN.md`, `SKILL.md`,
+  `design-package.json`, split token files, component docs, text assets,
+  implementation adapters, and lint results in one payload. `package` returns
+  the same files with `format: "package"` for import/apply workflows.
+  `adapters` returns Tailwind config, shadcn registry JSON, React component
+  scaffolds, HTML/CSS preview kit, and CSS custom properties.
+- `analyze_design_system_package` — inspect a package before import. Returns
+  summary metadata, token/component/asset counts, editable related existing
+  systems, and recommended `create` vs `version` mode.
+- `import_design_system_package` — import a BlueKiwi package export into the
+  registry. Use `mode: "create"` for a separate system, or `mode: "version"`
+  with `target_design_system_id` after the user chooses an existing family.
+
+## Flow: Use an Existing Design System
+
+1. Call `get_active_design_system` first when the user asks to "use the design
+   system" without naming one. If active exists, confirm whether to use it.
+2. Call `list_design_systems`.
+3. If the list is empty and the user wants recommendations or starter systems,
+   ask whether to seed the built-in library. If approved, call
+   `seed_design_systems`, then call `list_design_systems` again.
+4. Select the most relevant system by user request, project name, category,
+   surface, or slug.
+5. Ask whether to set the chosen system as active if it will guide follow-up
+   work. If approved, call `set_active_design_system`.
+6. Call `get_design_system`, or read `bk://active/design-system/DESIGN.md` when
+   the active context is already set and MCP resources are available.
+7. Apply the loaded tokens and guidelines to the current work.
+8. If the user requests portable output, call `export_design_system` with
+   `format: "skill"`.
+
+## Flow: Create a New Design System
+
+Collect the minimum viable context:
+
+- brand or product name
+- audience and usage medium
+- category and surface
+- tone and design principles
+- color direction
+- typography direction
+- component needs
+- hard prohibitions
+
+Then call `create_design_system` with:
 
 ```json
 {
-  "title": "<workflow title>",
-  "description": "<goal summary>",
-  "version": "1.0",
-  "folder_id": <selected folder id>,
-  "nodes": [...]
+  "title": "Example Design System",
+  "slug": "example-design-system",
+  "description": "Short purpose statement",
+  "category": "Education",
+  "surface": "web",
+  "schema": {
+    "version": "1.0",
+    "mediums": ["web", "slides", "docs"]
+  },
+  "tokens": {
+    "color": {},
+    "typography": {},
+    "spacing": {},
+    "components": {}
+  },
+  "color_tokens": {},
+  "typography_tokens": {},
+  "component_tokens": {
+    "LessonCard": {
+      "framework": "shadcn",
+      "style_system": "shadcn/ui + Tailwind CSS",
+      "description": "Compact lesson module card.",
+      "dependencies": ["@radix-ui/react-slot", "class-variance-authority"],
+      "install": ["npx shadcn@latest add card button"],
+      "props": [
+        {
+          "name": "title",
+          "type": "string",
+          "description": "Lesson title"
+        }
+      ],
+      "variants": ["default", "active"],
+      "states": ["default", "hover", "focus-visible", "disabled", "loading"],
+      "tailwind": {
+        "classes": ["rounded-lg", "border", "bg-card", "text-card-foreground"],
+        "theme_tokens": ["--card", "--card-foreground"]
+      },
+      "shadcn": {
+        "registry_items": ["card", "button"],
+        "dependencies": ["lucide-react"]
+      },
+      "preview": {
+        "html": "<article class=\"lesson-card\"><h3>Prompt Design</h3></article>",
+        "css": ".lesson-card{border:1px solid #D8CCB8;padding:16px}"
+      },
+      "source": {
+        "react": "export function LessonCard({ title }) { return <article>{title}</article>; }"
+      },
+      "usage": "Use inside workshop outlines and curriculum dashboards.",
+      "assets": ["LessonCard.tsx", "lesson-card.css"]
+    }
+  },
+  "guidelines_markdown": "## Principles\n...",
+  "skill_markdown": "Use this design system when..."
 }
 ```
 
-<HARD-RULE>
-Immediately validate the `create_workflow` result before doing anything else:
-
-- If the response includes `node_verification`, require `node_verification.mismatch === false`.
-- If `nodes` were supplied to `create_workflow`, treat that call as the only allowed initial node creation step.
-- Never append the same planned nodes after `create_workflow(nodes=[...])` because an older server response showed `data.nodes=[]`.
-- If verification fails, STOP and investigate. Do not continue with `append_node` or `insert_node`.
-  </HARD-RULE>
-
-### Step 6: Report Result + Open in Browser
-
-On success, open the workflow detail page in the browser:
-
-```bash
-open "${WEBUI_URL}/workflows/${WORKFLOW_ID}"
-```
-
-`WEBUI_URL` = the `webui_url` field returned by `create_workflow`.
-
-Then display:
-
-```
-✅ Workflow registered
-Name: <title> (ID: <id>)
-Steps: <n>
-Version: 1.0
-🔗 ${WEBUI_URL}/workflows/${WORKFLOW_ID}
-
-Type `/bk-start` to execute it now.
-```
-
-## Node Type Reference
-
-### action — Auto-executing agent step
-
-- `auto_advance=1` (automatic). The agent executes the instruction, saves the result, and automatically proceeds to the next step.
-- Set `hitl: true` to require human approval after execution. Use only for security-sensitive or irreversible operations.
-
-### gate — User decision point
-
-- `auto_advance=0`. Must receive a user response before proceeding.
-- Set `visual_selection: true` to have the agent render an HTML UI where the user selects by clicking.
-- Used for final result review, direction choices, approval/rejection, etc.
-
-### loop — Conditional repetition
-
-- `auto_advance=0`. Repeats the same step until the termination condition is met.
-- `loop_back_to`: target step_order to loop back to. Usually points to itself (self-loop).
-- **The instruction MUST include a clear termination condition** so the agent can decide `loop_continue=true/false`.
-
-**Loop node design patterns:**
-
-```json
-{
-  "title": "Clarifying Questions",
-  "node_type": "loop",
-  "loop_back_to": 4,
-  "instruction": "Ask one question at a time. Use multiple choice when possible.\n\nGather:\n- Purpose: What problem does this feature solve?\n- Constraints: Tech stack, performance, security limitations?\n- Success criteria: What defines completion?\n\nTermination: End when purpose, scope, constraints, and success criteria are all clear."
-}
-```
+## Flow: Load by Category
+
+Prefer category tools when the user asks for a specific part of a design
+system:
+
+- colors or palette: `get_design_system_section` with `section: "colors"`
+- fonts or typography: `get_design_system_section` with
+  `section: "typography"`
+- components: `get_design_system_section` with `section: "components"`
+- one component: `get_design_component` with the component `name`
+- guidelines: `get_design_system_section` with `section: "guidelines"`
+- portable agent docs: `export_design_system` with `format: "design"`
+- portable design package: `export_design_system` with `format: "package"`
+- implementation handoff: `export_design_system` with `format: "adapters"`
+
+## Category Operation Matrix
+
+Use the narrowest MCP tool that matches the user's scope:
+
+| User scope | Read tool | Create/update tool | Delete tool |
+| --- | --- | --- | --- |
+| Whole system metadata | `get_design_system` | `update_design_system` | `delete_design_system` |
+| New version | `get_design_system` | `create_design_system_version` | `delete_design_system` |
+| Colors/palette | `get_design_system_section` | `upsert_design_system_section_entry` or `update_design_system_section` | `delete_design_system_section_entry` or `delete_design_system_section` |
+| Typography/fonts | `get_design_system_section` | `upsert_design_system_section_entry` or `update_design_system_section` | `delete_design_system_section_entry` or `delete_design_system_section` |
+| Foundations/tokens | `get_design_system_section` | `upsert_design_system_section_entry` or `update_design_system_section` | `delete_design_system_section_entry` or `delete_design_system_section` |
+| Component catalog | `get_design_system_section` | `update_design_system_section` with `mode: "merge"` | `delete_design_system_section` |
+| One component | `get_design_component` | `upsert_design_component` | `delete_design_component` |
+| Guidelines | `get_design_system_section` | `update_design_system_section` | `delete_design_system_section` |
+| Skill instructions | `get_design_system_section` | `update_design_system_section` | `delete_design_system_section` |
+| Assets | `get_design_system_section` | `add_design_system_asset` | `delete_design_system_asset` |
+
+Use full `update_design_system` only for metadata edits or when the user has
+confirmed a whole-system replacement. For all category work, load the current
+section first, summarize the current entries, ask the user to confirm the
+entry or category, then use the scoped tool.
+
+## Component Planning Checklist
+
+When generating or materially updating components, ask which families to
+include unless the user chose automatic generation. In automatic mode, choose a
+preset from the HiFi playbook and state it.
+
+Recommended base catalog:
+
+- Controls: Button, Input, Textarea, Select, Checkbox, RadioGroup, Switch,
+  Slider
+- Navigation: Tabs, Breadcrumb, DropdownMenu, Sidebar, Pagination
+- Feedback: Alert, Toast, Badge, Progress, Skeleton
+- Layout/Data: Card, Table, Dialog, Drawer, Accordion, Tooltip, Popover
+- Developer utility: CodeBlock, CopyButton, CommandPalette, StatusBadge
+- Domain-specific: create names that match the user's product domain
+
+Every component document should include framework/style-system, description,
+props, variants, states, usage, static preview HTML/CSS, and source or
+integration metadata for React, plain HTML/CSS, Tailwind CSS, or shadcn/ui.
+
+## Flow: Update a Design System
+
+For metadata edits, call `update_design_system`.
+
+For category edits, do not send the full design-system payload unless the user
+explicitly asks to replace everything:
+
+- Add or update a color: `upsert_design_system_section_entry` with
+  `section: "colors"` and the token name as `key`.
+- Add or update a typography role: `upsert_design_system_section_entry` with
+  `section: "typography"`.
+- Add or update multiple colors/fonts/components at once:
+  `update_design_system_section` with `mode: "merge"`.
+- Replace a full category intentionally: `update_design_system_section` with
+  `mode: "replace"` after summarizing the impact.
+- Clear a category: `delete_design_system_section`.
+- Delete one token/spec: `delete_design_system_section_entry`.
+
+For component edits, use `get_design_component`, `upsert_design_component`,
+and `delete_design_component`. Treat the web UI as a read-only viewer for
+component documents. Add/update/delete component documents through MCP tools,
+not by expecting a visual editor in BlueKiwi.
+
+Before finalizing a HiFi system or a substantial update, call
+`lint_design_system`. Resolve `error` issues before presenting the result as
+ready. Summarize `warning` issues and ask whether to fix them now or leave them
+as intentional tradeoffs.
+
+For Tailwind or shadcn/ui components, include enough integration metadata for
+another agent to copy the component into a target project:
+
+- `framework`: `tailwind` or `shadcn`
+- `style_system`: for example `Tailwind CSS` or `shadcn/ui + Tailwind CSS`
+- `dependencies`: npm packages required by the component
+- `install`: commands such as `npx shadcn@latest add button card`
+- `tailwind`: class names, plugins, content paths, theme tokens, config notes
+- `shadcn`: registry items, style, base color, aliases, Radix/Base UI choice
+- `preview.html` and `preview.css`: static browser preview for BlueKiwi viewer
+- `source.react`: TSX source to copy into the application
+
+When the user asks to apply a design system to a target React/Tailwind/shadcn
+project, call `export_design_system` with `format: "adapters"` and use the
+generated files instead of reconstructing config by hand.
+
+For a meaningful published revision, call `create_design_system_version` so the
+previous active version remains in history.
+
+For package imports:
+
+1. Call `analyze_design_system_package` on the package payload.
+2. Show the summary, counts, related systems, and recommended mode. Ask whether
+   to import as a separate system or as a new version of a related existing
+   system; default to the recommendation unless the user overrides it.
+3. For a separate system, confirm title, slug, category, and surface before
+   calling `import_design_system_package` with `mode: "create"`.
+4. For a version, ask the target system, confirm the version label, then call
+   `import_design_system_package` with `mode: "version"` and
+   `target_design_system_id`.
+5. Run `lint_design_system` on the imported system and summarize warnings.
+
+Before creating a version from an existing system, call
+`list_design_system_versions` when the user asks about history, rollback,
+comparison, or an older version. After creating a new version, call
+`diff_design_system_versions` against the source and new version when the user
+needs a change summary or when the update is broad.
+
+For rollback:
+
+1. Call `list_design_system_versions`.
+2. Ask which version to restore.
+3. Call `diff_design_system_versions` from the current active version to the
+   selected target.
+4. Summarize what will change and ask for confirmation.
+5. Call `activate_design_system_version`.
+6. If the restored version should guide follow-up work, ask whether to call
+   `set_active_design_system` for that version.
+7. Call `list_design_system_events` if the user asks who changed the system or
+   why the current version differs from an older one.
+
+Never overwrite a user's established design rules without first summarizing the
+change and asking for confirmation.
+
+## Flow: Delete
+
+Use `delete_design_system` only when the user explicitly asks to remove a
+design system.
+
+- Delete the current version only: `family: false` or omit `family`.
+- Delete all versions in the family: `family: true`.
+- Delete assets separately with `delete_design_system_asset`.
+- Delete a single component with `delete_design_component`.
+
+## Flow: Add Assets
+
+Use `add_design_system_asset` for small text assets:
+
+- CSS: `kind="css"`, `mime_type="text/css"`, `content_text`
+- React source: `kind="template"`, `mime_type="text/tsx"` or `text/jsx`
+- HTML component: `kind="template"`, `mime_type="text/html"`
+- Tailwind config/docs: `kind="reference"`, `mime_type="application/json"` or
+  `text/markdown`
+- shadcn source or registry notes: `kind="template"` or `kind="reference"`
+- reference: `kind="reference"`, `mime_type="text/markdown"`
+
+Base64 assets are limited by the server and should be used sparingly.
+Use `delete_design_system_asset` to remove stale component source files.
+
+## Flow: Export
+
+Use:
 
 ```json
 {
-  "title": "Design Section Presentation",
-  "node_type": "loop",
-  "loop_back_to": 7,
-  "instruction": "Present the design section by section.\nEach section scales with complexity: a few sentences if simple, 200-300 words if nuanced.\nCover: architecture, components, data flow, error handling, testing.\nAfter each section, ask the user for confirmation.\n\nTermination: End when all design sections have been approved by the user."
+  "design_system_id": 123,
+  "format": "design"
 }
 ```
 
-**When to use loop nodes:**
-
-- Information gathering (question → answer repetition)
-- Section-by-section presentation/review (present → approve repetition)
-- Iterative refinement (result → feedback → revision repetition)
-
-## Node Design Guidelines
-
-- 3–7 steps is ideal. Consider splitting if more than 10.
-- Use `node_type: "gate"` before the final step to let the user review results.
-- Use `node_type: "loop"` when a step needs iterative user interaction. Always include a clear termination condition in the instruction.
-- Use `hitl: true` on `action` nodes only when the step requires explicit human judgment mid-flow (e.g., security-sensitive operations, irreversible actions).
-- Use `visual_selection: true` on `gate` nodes when the selection is best expressed visually — e.g., choosing a layout, picking a chart type, selecting a UI template. The agent must call `set_visual_html` with interactive HTML before executing the step; the user's click supplies the response.
-- For nodes requiring external API calls, specify `credential_id`. Create credentials first with `/bk-credential`.
-
-## Instruction Depth Standard
-
-<HARD-RULE>
-Before calling `create_workflow`, verify every node instruction satisfies ALL of the following:
-
-1. **Role/context** (first line or heading): who or what performs this step — e.g., "## Market Analyst", "You are acting as a senior code reviewer"
-2. **Numbered sub-steps**: at minimum 2 explicit steps describing HOW to perform the action, not just WHAT to produce
-3. **Output specification**: exactly what is produced — file path + format, structured data shape, or required fields
-4. **Verification**: one line stating how to confirm the step succeeded
-5. **Loop nodes only**: termination condition as the final line — "Termination: end when X"
-
-**Minimum instruction length: 80 words.** If an instruction is shorter, it is not specific enough — expand it.
-</HARD-RULE>
-
-### Anti-patterns → Prescriptive Rewrites
-
-| ❌ Vague — do not write    | ✅ Prescriptive — write this instead                                                                                                                                                           |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "Analyze the data."        | "Read the CSV at `data/input.csv`. Compute row count, null counts per column, and value distributions for numeric columns. Output a summary table to `data/eda-summary.md`."                   |
-| "Review the results."      | "Check each output against the success criteria from Step 1. Build a pass/fail table with one evidence line per criterion. Flag any criterion below threshold in red."                         |
-| "Ask the user what to do." | "Present exactly 3 options via bk-options (sm): A) proceed as-is, B) revise the output, C) abort. Include a one-sentence consequence for each option."                                         |
-| "Generate a report."       | "Create `docs/report-YYYY-MM-DD.md` with sections: Executive Summary (3 bullets), Findings (numbered, each with evidence), Recommendations (priority-ordered), Next Steps (owner + deadline)." |
-| "Search the web."          | "Run a web search for each of the 3 queries listed. For each result, record: source URL, publication date, key claim (1 sentence). Discard results older than 12 months."                      |
-
-### Instruction Templates by Node Type
-
-**action — data / research step:**
-
-```
-## <Expert Role>
-
-<One sentence: what this step accomplishes and why it matters here.>
-
-1. <First concrete action — tool call, file read, calculation>
-2. <Second concrete action — transformation, filtering, aggregation>
-3. <Third action if needed>
-
-**Output**: <Exact file path or data structure>
-**Verification**: <Command or check that confirms success>
-```
-
-**gate — user decision:**
-
-```
-<Brief context: what was just produced and what the user must decide.>
-
-Present options using bk-options (size=sm):
-- A) <Option> — <one-sentence consequence>
-- B) <Option> — <one-sentence consequence>
-- C) <Option> — <one-sentence consequence>
-
-Mark the recommended option with `data-recommended`.
-```
-
-**loop — iterative interaction:**
-
-```
-## <Role>
-
-<What is being iterated and why iteration is needed.>
-
-Each iteration:
-1. <What to present or ask>
-2. <How to process the response>
-3. <How to update state>
-
-**Termination**: End when <specific, measurable condition>.
-```
-
-#### VS Component Selection Guide
-
-When designing a `visual_selection: true` gate node, specify which `bk-*` components the agent should use in the node instruction. This keeps VS screens consistent and prevents vague "make a selection UI" instructions.
-
-<HARD-RULE>
-- VS content shown to the user must be written in the user's language.
-- Labels, option descriptions, helper text, slider units, ranking item names, and matrix axis labels must all follow the user's language.
-- Keep component class names and JSON keys in their canonical English forms (`bk-options`, `selections`, `values`, `ranking`, `matrix`, `comment`, `fields`, `option_comments`).
-</HARD-RULE>
-
-**Dialog size directive** — optional first line of the HTML: `<!-- @bk size=sm|md|lg|xl|full -->`. Default is `sm` (single-column choices). Step up to `md` (cards, code-compare), `lg` (pros-cons, ranking, timeline), `xl` (mockups, matrix, side-by-side wireframes), or `full` (dashboard previews, complex layouts) whenever content benefits from horizontal space.
-
-**Component → Use Case mapping:**
-
-| Component         | Recommended size | Best for                                                       |
-| ----------------- | ---------------- | -------------------------------------------------------------- |
-| `bk-options`      | `sm`             | Mutually exclusive choices with descriptions (A/B/C decisions) |
-| `bk-cards`        | `md`             | Visual previews (layout, chart type, UI template selection)    |
-| `bk-checklist`    | `sm`             | Feature toggles, multi-select from a list                      |
-| `bk-code-compare` | `lg`             | Comparing code approaches side by side                         |
-| `bk-slider`       | `sm`             | Budget allocation, confidence levels, thresholds               |
-| `bk-input`        | `sm`             | Short rationale, constraint, owner, or one-line change request |
-| `bk-textarea`     | `sm` or `md`     | Long-form feedback, revision request, reviewer memo            |
-| `bk-ranking`      | `md`             | Priority ordering (requirements, features)                     |
-| `bk-matrix`       | `xl`             | Urgency/importance mapping, risk assessment                    |
-| `bk-split`        | `xl`             | Two-option comparison (A vs B)                                 |
-| `bk-pros-cons`    | `lg`             | Pros and cons review                                           |
-| `bk-mockup`       | `xl` or `full`   | UI wireframe / layout previews                                 |
-| `bk-timeline`     | `lg`             | Roadmap / milestone review                                     |
-
-**Instruction template patterns:**
-
-```text
-Present the alternatives using bk-options with data-recommended on the suggested choice.
-(dialog: sm — default, no directive needed)
-```
-
-```text
-Show the layout candidates using bk-cards (size=md), then add a bk-slider named "confidence" (0-100, unit "%").
-Start the HTML with: <!-- @bk size=md -->
-```
-
-```text
-If the user may want to approve with edits, add a bk-textarea with data-name="comment" and data-response-key="comment" so they can leave a global memo.
-```
-
-```text
-If a specific option requires justification or revision notes, add data-requires-comment to that selectable item.
-Use data-comment-name="change_request" when the memo should be persisted into response.fields.change_request.
-```
-
-**Feedback-friendly gate design rules:**
-
-- For review/approval gates, default to **selection + memo**, not selection alone.
-- If one option means "approve with edits", make that option require a comment.
-- Use `bk-input` for short structured constraints (owner, budget cap, deadline).
-- Use `bk-textarea` for open-ended revision requests or free-form reviewer notes.
-- When designing downstream steps, explicitly instruct the agent to parse and honor `comment`, `fields`, and `option_comments`, not just `selections`.
-
-```text
-Collect optional capabilities with bk-checklist and ask the user to rank the top three priorities using bk-ranking.
-(dialog: sm or md — omit directive or use <!-- @bk size=md -->)
-```
-
-```text
-Compare the two implementation approaches using bk-code-compare (size=lg), then capture risk posture in a bk-matrix (size=xl).
-If both appear on the same screen, use the larger size: <!-- @bk size=xl -->
-```
-
-```text
-Show a UI wireframe mockup or dashboard layout preview using bk-mockup with inline styles.
-Start the HTML with: <!-- @bk size=xl --> or <!-- @bk size=full -->
-Place two mockup cards side by side using display:grid;grid-template-columns:1fr 1fr.
-```
-
-### Attachments
-
-- Use node attachments for scripts, reference docs, prompts, and config files that the agent should load during execution.
-- Add attachments only after the workflow and target node exist, using `upload_attachment(workflow_id, node_id, filename, content)`.
-- Prefer text-based files so the execution skill can download and use their contents directly.
-- Mention the attachment by filename in the node instruction when the agent is expected to read it.
-- Keep attachments node-specific. Shared reusable logic belongs in an instruction template or a separate workflow step, not duplicated across many nodes.
-- Use binary attachments only when necessary. Execution agents may only inspect their metadata unless the task explicitly requires the binary asset.
-
-## Node Modification Strategy
-
-<HARD-RULE>
-- Before any structural edit, refresh the current workflow structure from the server and use the latest node ids / step orders as the source of truth.
-- Update a single node → `update_node(workflow_id, node_id, ...only changed fields such as title, instruction, node_type, hitl, visual_selection, loop_back_to, credential_id, instruction_id)`
-- Append a node (at the end) → `append_node(workflow_id, title, instruction, node_type, hitl?, visual_selection?, loop_back_to?, credential_id?, instruction_id?)`
-- Insert a node (in the middle) → `insert_node(workflow_id, after_step=N, title, instruction, node_type, hitl?, visual_selection?, loop_back_to?, credential_id?, instruction_id?)`
-- Delete a node → `remove_node(workflow_id, node_id)`
-- Never use `update_workflow(nodes=[...])` for full replacement unless a complete redesign is intended
-- After every `append_node` or `insert_node`, inspect the returned `node_verification`.
-- If `node_verification.mismatch === true`, STOP immediately and do not continue issuing more structural edits from the current plan snapshot.
-</HARD-RULE>
-
-## Inline vs Template Instructions
-
-Nodes can have two types of instructions:
-
-- **Template reference**: Node has `instruction_id` set. References a shared instruction template. Use `update_instruction` to modify the template — affects all nodes that reference it.
-- **Inline instruction**: Node has no `instruction_id` and stores text directly in the `instruction` field. Use `update_node(workflow_id, node_id, instruction="new text")` to modify — affects only that node.
-
-```
-# Update inline instruction — affects only this node
-update_node(workflow_id=67, node_id=109, instruction="new instruction text")
-
-# Update instruction template — affects all referencing nodes
-update_instruction(instruction_id=5, content="new template text")
-```
-
-## Folder & Workflow Organization
-
-Triggered when the user says "move workflow", "change folder", "organize", or "create folder".
-
-### Move an Existing Workflow to a Different Folder
-
-1. Call `list_workflows` to identify the target workflow (or use the name the user mentioned).
-2. Call `list_folders` to get the folder list.
-3. Ask via AskUserQuestion:
-   - header: "Move to"
-   - "Which folder should '{workflow title}' be moved to?"
-   - options: folder name list + "My Workspace (default)"
-4. Call `move_workflow`:
-   ```json
-   { "workflow_id": <id>, "folder_id": <destination folder id> }
-   ```
-5. Report: `✅ Moved '{workflow title}' → '{folder name}'`
-
-### Create a Standalone Folder
-
-1. Ask for name and optional visibility (`personal` / `group` / `public`).
-2. Call `create_folder`:
-   ```json
-   { "name": "<name>", "description": "<desc>", "visibility": "personal" }
-   ```
-3. Report: `✅ Folder '{name}' created.`
-
-### Rename a Folder
-
-Call `update_folder`:
-
-```json
-{ "folder_id": <id>, "name": "<new name>" }
-```
-
-### Delete an Empty Folder
-
-Call `delete_folder`:
-
-```json
-{ "folder_id": <id> }
-```
-
-> Note: `delete_folder` fails with `FOLDER_NOT_EMPTY` if the folder contains any workflows, instructions, or sub-folders. Empty the folder first. Credentials are not filed in folders and do not affect this check.
+`format: "design"` returns DESIGN.md documentation for agent lookup. If MCP
+resources are available, read `bk://design-systems/<id>/DESIGN.md` for the same
+agent-facing view without invoking extra mutation-capable tools. Use
+`format: "skill"` when the user specifically needs a portable SKILL.md. Use
+`format: "adapters"` when another agent needs implementation files for
+React/Tailwind/shadcn/HTML. Use `format: "package"` when another agent needs a
+portable import/apply package with `design-package.json`, or `format: "bundle"`
+when a legacy consumer expects that name for the whole payload.
+
+## Safety
+
+- Do not invent a registered design system. If lookup returns no match, say so.
+- Do not expose raw API keys or credentials in design-system assets.
+- Preserve existing tokens unless the user explicitly asks to replace them.
+- Keep generated design rules concrete enough for another agent to apply.