@hiver/skills 1.0.2 → 1.0.4

package/collections/common/skills/discuss-problem/SKILL.md

@@ -36,8 +36,8 @@ Help the user to grill down on a problem to its core discussing all sorts of the
 
 1. Take input from the user related to the problem they want to discuss or grill down
 2. If the problem is related to building a new feature, check with the user if prototype designs are available
-3. If Figma designs are available, use the Figma MCP tool to get the prototype details and analyze them
-4. Keep asking if the user has more Figma designs available until all designs are provided; keep using the Figma MCP tool to load them into memory
+3. If Figma designs are available, use the claude Figma desktop MCP tool to get the prototype details and analyze them
+4. Keep asking if the user has more Figma designs available until all designs are provided; keep using the claude Figma desktop MCP tool to load them into memory
 5. Analyze the problem statement in context of the current codebase — use read and search tools to explore, never write tools
 6. Ask the right questions until you are clear on the problem statement
 7. Go through the codebase and figure out how the problem can be solved — discussion only

package/collections/extension/skills/build-component/references/icons.md

@@ -1,8 +1,81 @@
 # Icons
 
-- **Use MUI icons only** - import from `@mui/icons-material` or `@hiver/hiver-ui-kit` icons
-- **For SVG icons**: Import SVG files directly and use them in `<img>` tags
-  - Import SVG files: `import iconName from 'path/to/icon.svg'`
-  - Use in component: `<img src={iconName} alt="description" />`
-  - Example: `import AILogo from '../assets/ai_logo.svg'` then `<img src={AILogo} alt="AI Copilot" />`
-- **Do not import icons from other packages** (no FontAwesome, Heroicons, etc.)
+How to import from `@hiver/hiver-ui-kit`:
+
+```js
+import { brandIcons, icons } from '@hiver/hiver-ui-kit';
+// <brandIcons.Star />
+// <icons.AccountCircle />
+```
+
+## Resolution priority
+
+When a Figma design contains an icon, resolve it in this order:
+
+1. **User-provided SVG asset** — if the user supplied an `.svg` file, import it directly:
+   ```js
+   import iconName from 'path/to/icon.svg';
+   <img src={iconName} alt="description" />
+   ```
+2. **`brandIcons`** — Hiver-designed icons (see "Brand icon catalog" below).
+3. **`icons`** — curated MUI icons re-exported from hui-kit (see "MUI icon catalog" below).
+4. **`@mui/icons-material`** — **last resort only**, when the icon is not in the design system **and** the user has not provided an asset.
+5. **Never** import icons from FontAwesome, Heroicons, or any other third-party icon library.
+
+## How to match a Figma icon to a code name
+
+1. **Prefer the Figma layer/component name** if the design exposes one (e.g. a layer named `Brand/Star` → `brandIcons.Star`).
+2. **Otherwise, match visually** against the catalog sheets embedded below. Each icon is rendered with its exact export name underneath.
+3. The export name is what you use in code — including any typos preserved from the design system (see Notes).
+
+## Brand icon catalog (`brandIcons`)
+
+![Brand icons catalog](./icons/brand-icons.png)
+
+**Hiver Logo**
+- `Logo`
+
+**Brand icons** (box 20×20, live area 18×18, stroke 1.4)
+- `SharedMailbox`, `Analytics`, `EmailTemplates`, `Settings`, `HiverAlerts`, `Activity`, `AutoAssignment`, `Workload`, `Lable`, `Permalink`
+- `Star`, `Edit`, `Filters`, `HiverChat`, `AircallPhone`, `Aavatar`, `Unassigned`, `Mine`, `Team`, `Pending`
+- `Closed`, `Tags`, `Crown`, `Dashboard`, `DashboardInactive`, `SharedInboxNav`, `SharedInboxNavInactive`, `SharedLabel`, `SharedLabelInactive`, `KnowledgeBase`
+- `KnowledgeBaseInactive`, `Connector`, `ConnectorInactive`, `SettingsNav`, `SettingsNavInactive`, `UserRole`, `UserRoleInactive`
+
+**Activity icons** (box 20×20, live area 16×16, stroke 1.4)
+- `Status`, `Tag`, `Inbox`, `AlertTriangle`, `EnvelopeDownload`, `ActivityStar`, `EnvelopeUpload`, `Envelope`, `ActivityEdit`, `CloseCircle`, `CheckAction`, `UserCheck`
+
+**Settings icons** (box 24×24, live area 22×22, stroke 1.4)
+- `AdminPanel`, `Sliders`, `Compass`, `SwitchAccount`, `Gift`, `MessageCircle`, `LifeBuoy`
+
+## MUI icon catalog (`icons`)
+
+![MUI icons catalog](./icons/mui-icons.png)
+
+- `AccountCircle`, `Add`, `Alarm`, `Close`, `Phone`, `ArchiveOutlined`, `ArrowBack`, `ArrowBackIos`, `ArrowDropDown`, `ArrowDropUp`, `ArrowForward`
+- `ArrowOutward`, `CalendarToday`, `CalendarTodayOutlined`, `CalendarTodayOutlinedIcon`, `Cancel`, `CancelOutlined`, `CheckCircle`, `ChevronRightOutlined`, `CodeSharp`, `DeleteOutline`, `DownloadOutlined`
+- `DragIndicator`, `EditOutlined`, `Error`, `ErrorOutline`, `GroupsOutlined`, `InfoOutlined`, `LabelOutlined`, `Link`, `LockOutlined`, `MailOutlined`, `MicNone`
+- `MoreVert`, `NotificationsOutlined`, `OpenInNew`, `Pause`, `PersonOutline`, `PersonOutlined`, `PlayArrow`, `Public`, `Search`, `Settings`, `SettingsOutlined`
+- `StickyNote2Outlined`, `ThumbDownAlt`, `ThumbDownOffAlt`, `ThumbUpAlt`, `ThumbUpOffAlt`, `TimerOutlined`, `TrackChanges`, `UnarchiveOutlined`, `Voicemail`, `Warning`, `WarningAmber`
+- `ArrowRightAlt`, `Delete`, `Email`, `Favorite`
+
+## Notes — Figma → code gotchas
+
+- **Typos preserved in exports** — these match the Figma names, so map literally; do not auto-correct:
+  - `Lable` (not `Label`)
+  - `Aavatar` (not `Avatar`)
+- **`Edit` collision** — three similar icons:
+  - `brandIcons.Edit` — pen-on-paper brand icon (yellow accent)
+  - `brandIcons.ActivityEdit` — green envelope with a pen, activity style
+  - `icons.EditOutlined` — plain MUI outlined pencil
+- **`Settings` collision** — five similar names:
+  - `brandIcons.Settings`, `brandIcons.SettingsNav`, `brandIcons.SettingsNavInactive`
+  - `icons.Settings`, `icons.SettingsOutlined`
+  Pick by Figma category section and visual.
+- **`Star` collision**:
+  - `brandIcons.Star` — yellow filled brand star
+  - `brandIcons.ActivityStar` — purple activity star
+- **`Tag` vs `Tags`**:
+  - `brandIcons.Tags` — brand (plural, box 20×20 live 18×18)
+  - `brandIcons.Tag` — activity (singular, box 20×20 live 16×16)
+- **Inactive variants** — many brand icons have `*Inactive` siblings (`DashboardInactive`, `SharedInboxNavInactive`, `SharedLabelInactive`, `KnowledgeBaseInactive`, `ConnectorInactive`, `SettingsNavInactive`, `UserRoleInactive`). Use the inactive variant for the unselected/disabled state of a nav item.
+- **`UserCheck`** — present in `brandIcons` exports but not visible on the current Figma sheet. Use it if a design clearly needs it; otherwise prefer the activity-style icons documented above.

package/collections/extension/skills/build-component/typography/variants.md

@@ -1,6 +1,10 @@
 # Typography reference (`@hiver/hiver-ui-kit`)
 
-Map Figma text styles to `<Typography variant="...">`. Font family is **Open Sans**. Match by fontSize + fontWeight (regular 400, medium 500, semiBold 600, bold 700).
+Map Figma text styles to `<Typography variant="...">`. Match by fontSize + fontWeight (regular 400, medium 500, semiBold 600, bold 700).
+
+**Font families:**
+- Legacy variants (`h1_*`–`h5_*`, `body0_5_*`–`body4_*`, `caption1_*`, `caption2_*`, `overline_medium`, `overline_semiBold`, `buttonLarge`/`buttonMedium`/`buttonSmall`, `chip`) use **Open Sans**.
+- 2026 tokens (`body_lg_*`–`body_xs_*`, `heading_lg_*`–`heading_sm_*`, `display_lg_*`/`display_md_*`, `caption_regular`/`caption_medium`, `overline_regular`) use **Inter**.
 
 ## Heading variants
 
@@ -68,12 +72,68 @@ Map Figma text styles to `<Typography variant="...">`. Font family is **Open San
 | `buttonSmall` | 12 | 500 | 20px | 0.4px |
 | `chip` | 12 | 500 | 12px | 0.4px |
 
+## Typography 2026 tokens (Inter)
+
+Canonical 2026 design tokens. Use these for new UI built against the 2026 design system. Font family is **Inter**.
+
+### Display
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `display_lg_semiBold` | 28 | 600 | 36px | 0.01em |
+| `display_lg_bold` | 28 | 700 | 36px | 0.01em |
+| `display_md_semiBold` | 24 | 600 | 32px | 0.01em |
+| `display_md_bold` | 24 | 700 | 32px | 0.01em |
+
+### Heading
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `heading_lg_medium` | 20 | 500 | 28px | -0.005em |
+| `heading_lg_semiBold` | 20 | 600 | 28px | -0.005em |
+| `heading_md_medium` | 18 | 500 | 28px | -0.005em |
+| `heading_md_semiBold` | 18 | 600 | 28px | -0.005em |
+| `heading_sm_medium` | 16 | 500 | 22px | -0.005em |
+| `heading_sm_semiBold` | 16 | 600 | 22px | -0.005em |
+
+### Body
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `body_lg_regular` | 16 | 400 | 24px | -0.005em |
+| `body_lg_medium` | 16 | 500 | 24px | -0.005em |
+| `body_lg_semiBold` | 16 | 600 | 24px | -0.005em |
+| `body_md_regular` | 14 | 400 | 20px | -0.005em |
+| `body_md_medium` | 14 | 500 | 20px | -0.005em |
+| `body_md_semiBold` | 14 | 600 | 20px | -0.005em |
+| `body_sm_regular` | 13 | 400 | 19px | -0.005em |
+| `body_sm_medium` | 13 | 500 | 19px | -0.005em |
+| `body_sm_semiBold` | 13 | 600 | 19px | -0.005em |
+| `body_xs_regular` | 12 | 400 | 18px | -0.005em |
+| `body_xs_medium` | 12 | 500 | 18px | -0.005em |
+| `body_xs_semiBold` | 12 | 600 | 18px | -0.005em |
+
+### Caption & overline (2026)
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing | Notes |
+|---------|----------|------------|------------|---------------|-------|
+| `caption_regular` | 12 | 400 | 14px | 0.01em | |
+| `caption_medium` | 12 | 500 | 14px | 0.01em | |
+| `overline_regular` | 12 | 400 | 14px | 0.01em | UPPERCASE |
+
+> Note: a 2026 `overline_medium` token also exists in the theme (Inter, 12 / 500 / 14px / 0.01em / UPPERCASE) and shares its name with the legacy Open Sans `overline_medium` (11 / 500 / 18px). The 2026 spread is applied after the legacy block, so the Inter version wins at runtime — use accordingly.
+
 ## Usage
 
 ```jsx
 <Typography variant="h2_medium">Section title</Typography>
 <Typography variant="body1_regular">Body text</Typography>
 <Typography variant="caption1_medium" color="text.secondary">Caption</Typography>
+
+// 2026 tokens
+<Typography variant="heading_lg_semiBold">Page title</Typography>
+<Typography variant="body_md_regular">Body text</Typography>
+<Typography variant="display_lg_bold">Hero</Typography>
 ```
 
-**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match.
+**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match. For new 2026 designs, prefer the Inter tokens.

package/collections/web/skills/build-component/references/icons.md

@@ -1,8 +1,81 @@
 # Icons
 
-- **Use MUI icons only** - import from `@mui/icons-material` or `@hiver/hiver-ui-kit` icons
-- **For SVG icons**: Import SVG files directly and use them in `<img>` tags
-  - Import SVG files: `import iconName from 'path/to/icon.svg'`
-  - Use in component: `<img src={iconName} alt="description" />`
-  - Example: `import AILogo from '../assets/ai_logo.svg'` then `<img src={AILogo} alt="AI Copilot" />`
-- **Do not import icons from other packages** (no FontAwesome, Heroicons, etc.)
+How to import from `@hiver/hiver-ui-kit`:
+
+```js
+import { brandIcons, icons } from '@hiver/hiver-ui-kit';
+// <brandIcons.Star />
+// <icons.AccountCircle />
+```
+
+## Resolution priority
+
+When a Figma design contains an icon, resolve it in this order:
+
+1. **User-provided SVG asset** — if the user supplied an `.svg` file, import it directly:
+   ```js
+   import iconName from 'path/to/icon.svg';
+   <img src={iconName} alt="description" />
+   ```
+2. **`brandIcons`** — Hiver-designed icons (see "Brand icon catalog" below).
+3. **`icons`** — curated MUI icons re-exported from hui-kit (see "MUI icon catalog" below).
+4. **`@mui/icons-material`** — **last resort only**, when the icon is not in the design system **and** the user has not provided an asset.
+5. **Never** import icons from FontAwesome, Heroicons, or any other third-party icon library.
+
+## How to match a Figma icon to a code name
+
+1. **Prefer the Figma layer/component name** if the design exposes one (e.g. a layer named `Brand/Star` → `brandIcons.Star`).
+2. **Otherwise, match visually** against the catalog sheets embedded below. Each icon is rendered with its exact export name underneath.
+3. The export name is what you use in code — including any typos preserved from the design system (see Notes).
+
+## Brand icon catalog (`brandIcons`)
+
+![Brand icons catalog](./icons/brand-icons.png)
+
+**Hiver Logo**
+- `Logo`
+
+**Brand icons** (box 20×20, live area 18×18, stroke 1.4)
+- `SharedMailbox`, `Analytics`, `EmailTemplates`, `Settings`, `HiverAlerts`, `Activity`, `AutoAssignment`, `Workload`, `Lable`, `Permalink`
+- `Star`, `Edit`, `Filters`, `HiverChat`, `AircallPhone`, `Aavatar`, `Unassigned`, `Mine`, `Team`, `Pending`
+- `Closed`, `Tags`, `Crown`, `Dashboard`, `DashboardInactive`, `SharedInboxNav`, `SharedInboxNavInactive`, `SharedLabel`, `SharedLabelInactive`, `KnowledgeBase`
+- `KnowledgeBaseInactive`, `Connector`, `ConnectorInactive`, `SettingsNav`, `SettingsNavInactive`, `UserRole`, `UserRoleInactive`
+
+**Activity icons** (box 20×20, live area 16×16, stroke 1.4)
+- `Status`, `Tag`, `Inbox`, `AlertTriangle`, `EnvelopeDownload`, `ActivityStar`, `EnvelopeUpload`, `Envelope`, `ActivityEdit`, `CloseCircle`, `CheckAction`, `UserCheck`
+
+**Settings icons** (box 24×24, live area 22×22, stroke 1.4)
+- `AdminPanel`, `Sliders`, `Compass`, `SwitchAccount`, `Gift`, `MessageCircle`, `LifeBuoy`
+
+## MUI icon catalog (`icons`)
+
+![MUI icons catalog](./icons/mui-icons.png)
+
+- `AccountCircle`, `Add`, `Alarm`, `Close`, `Phone`, `ArchiveOutlined`, `ArrowBack`, `ArrowBackIos`, `ArrowDropDown`, `ArrowDropUp`, `ArrowForward`
+- `ArrowOutward`, `CalendarToday`, `CalendarTodayOutlined`, `CalendarTodayOutlinedIcon`, `Cancel`, `CancelOutlined`, `CheckCircle`, `ChevronRightOutlined`, `CodeSharp`, `DeleteOutline`, `DownloadOutlined`
+- `DragIndicator`, `EditOutlined`, `Error`, `ErrorOutline`, `GroupsOutlined`, `InfoOutlined`, `LabelOutlined`, `Link`, `LockOutlined`, `MailOutlined`, `MicNone`
+- `MoreVert`, `NotificationsOutlined`, `OpenInNew`, `Pause`, `PersonOutline`, `PersonOutlined`, `PlayArrow`, `Public`, `Search`, `Settings`, `SettingsOutlined`
+- `StickyNote2Outlined`, `ThumbDownAlt`, `ThumbDownOffAlt`, `ThumbUpAlt`, `ThumbUpOffAlt`, `TimerOutlined`, `TrackChanges`, `UnarchiveOutlined`, `Voicemail`, `Warning`, `WarningAmber`
+- `ArrowRightAlt`, `Delete`, `Email`, `Favorite`
+
+## Notes — Figma → code gotchas
+
+- **Typos preserved in exports** — these match the Figma names, so map literally; do not auto-correct:
+  - `Lable` (not `Label`)
+  - `Aavatar` (not `Avatar`)
+- **`Edit` collision** — three similar icons:
+  - `brandIcons.Edit` — pen-on-paper brand icon (yellow accent)
+  - `brandIcons.ActivityEdit` — green envelope with a pen, activity style
+  - `icons.EditOutlined` — plain MUI outlined pencil
+- **`Settings` collision** — five similar names:
+  - `brandIcons.Settings`, `brandIcons.SettingsNav`, `brandIcons.SettingsNavInactive`
+  - `icons.Settings`, `icons.SettingsOutlined`
+  Pick by Figma category section and visual.
+- **`Star` collision**:
+  - `brandIcons.Star` — yellow filled brand star
+  - `brandIcons.ActivityStar` — purple activity star
+- **`Tag` vs `Tags`**:
+  - `brandIcons.Tags` — brand (plural, box 20×20 live 18×18)
+  - `brandIcons.Tag` — activity (singular, box 20×20 live 16×16)
+- **Inactive variants** — many brand icons have `*Inactive` siblings (`DashboardInactive`, `SharedInboxNavInactive`, `SharedLabelInactive`, `KnowledgeBaseInactive`, `ConnectorInactive`, `SettingsNavInactive`, `UserRoleInactive`). Use the inactive variant for the unselected/disabled state of a nav item.
+- **`UserCheck`** — present in `brandIcons` exports but not visible on the current Figma sheet. Use it if a design clearly needs it; otherwise prefer the activity-style icons documented above.

package/collections/web/skills/build-component/typography/variants.md

@@ -1,6 +1,10 @@
 # Typography reference (`@hiver/hiver-ui-kit`)
 
-Map Figma text styles to `<Typography variant="...">`. Font family is **Open Sans**. Match by fontSize + fontWeight (regular 400, medium 500, semiBold 600, bold 700).
+Map Figma text styles to `<Typography variant="...">`. Match by fontSize + fontWeight (regular 400, medium 500, semiBold 600, bold 700).
+
+**Font families:**
+- Legacy variants (`h1_*`–`h5_*`, `body0_5_*`–`body4_*`, `caption1_*`, `caption2_*`, `overline_medium`, `overline_semiBold`, `buttonLarge`/`buttonMedium`/`buttonSmall`, `chip`) use **Open Sans**.
+- 2026 tokens (`body_lg_*`–`body_xs_*`, `heading_lg_*`–`heading_sm_*`, `display_lg_*`/`display_md_*`, `caption_regular`/`caption_medium`, `overline_regular`) use **Inter**.
 
 ## Heading variants
 
@@ -68,12 +72,68 @@ Map Figma text styles to `<Typography variant="...">`. Font family is **Open San
 | `buttonSmall` | 12 | 500 | 20px | 0.4px |
 | `chip` | 12 | 500 | 12px | 0.4px |
 
+## Typography 2026 tokens (Inter)
+
+Canonical 2026 design tokens. Use these for new UI built against the 2026 design system. Font family is **Inter**.
+
+### Display
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `display_lg_semiBold` | 28 | 600 | 36px | 0.01em |
+| `display_lg_bold` | 28 | 700 | 36px | 0.01em |
+| `display_md_semiBold` | 24 | 600 | 32px | 0.01em |
+| `display_md_bold` | 24 | 700 | 32px | 0.01em |
+
+### Heading
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `heading_lg_medium` | 20 | 500 | 28px | -0.005em |
+| `heading_lg_semiBold` | 20 | 600 | 28px | -0.005em |
+| `heading_md_medium` | 18 | 500 | 28px | -0.005em |
+| `heading_md_semiBold` | 18 | 600 | 28px | -0.005em |
+| `heading_sm_medium` | 16 | 500 | 22px | -0.005em |
+| `heading_sm_semiBold` | 16 | 600 | 22px | -0.005em |
+
+### Body
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing |
+|---------|----------|------------|------------|---------------|
+| `body_lg_regular` | 16 | 400 | 24px | -0.005em |
+| `body_lg_medium` | 16 | 500 | 24px | -0.005em |
+| `body_lg_semiBold` | 16 | 600 | 24px | -0.005em |
+| `body_md_regular` | 14 | 400 | 20px | -0.005em |
+| `body_md_medium` | 14 | 500 | 20px | -0.005em |
+| `body_md_semiBold` | 14 | 600 | 20px | -0.005em |
+| `body_sm_regular` | 13 | 400 | 19px | -0.005em |
+| `body_sm_medium` | 13 | 500 | 19px | -0.005em |
+| `body_sm_semiBold` | 13 | 600 | 19px | -0.005em |
+| `body_xs_regular` | 12 | 400 | 18px | -0.005em |
+| `body_xs_medium` | 12 | 500 | 18px | -0.005em |
+| `body_xs_semiBold` | 12 | 600 | 18px | -0.005em |
+
+### Caption & overline (2026)
+
+| Variant | fontSize | fontWeight | lineHeight | letterSpacing | Notes |
+|---------|----------|------------|------------|---------------|-------|
+| `caption_regular` | 12 | 400 | 14px | 0.01em | |
+| `caption_medium` | 12 | 500 | 14px | 0.01em | |
+| `overline_regular` | 12 | 400 | 14px | 0.01em | UPPERCASE |
+
+> Note: a 2026 `overline_medium` token also exists in the theme (Inter, 12 / 500 / 14px / 0.01em / UPPERCASE) and shares its name with the legacy Open Sans `overline_medium` (11 / 500 / 18px). The 2026 spread is applied after the legacy block, so the Inter version wins at runtime — use accordingly.
+
 ## Usage
 
 ```jsx
 <Typography variant="h2_medium">Section title</Typography>
 <Typography variant="body1_regular">Body text</Typography>
 <Typography variant="caption1_medium" color="text.secondary">Caption</Typography>
+
+// 2026 tokens
+<Typography variant="heading_lg_semiBold">Page title</Typography>
+<Typography variant="body_md_regular">Body text</Typography>
+<Typography variant="display_lg_bold">Hero</Typography>
 ```
 
-**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match.
+**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match. For new 2026 designs, prefer the Inter tokens.

package/dist/cli.js

@@ -239,6 +239,15 @@ function getAgentMeta(collectionName, agentName) {
     dependencies: Array.isArray(fm.dependencies) ? fm.dependencies : []
   };
 }
+function findCollectionsContaining(name, type) {
+  const matches = [];
+  for (const col of listCollections()) {
+    const { skills, agents } = scanCollection(col);
+    if (type === "skill" && skills.includes(name)) matches.push(col);
+    if (type === "agent" && agents.includes(name)) matches.push(col);
+  }
+  return matches;
+}
 function resolveDependencies(selected, selectedCollections) {
   const installedNames = /* @__PURE__ */ new Set([
     ...selected.skills.map((s) => s.name),
@@ -341,34 +350,8 @@ function Add({ directSkills }) {
   const [selectedType, setSelectedType] = useState3(null);
   const [toInstall, setToInstall] = useState3({ skills: [], agents: [] });
   const [results, setResults] = useState3({ skills: 0, agents: 0, deps: [] });
+  const [directMissing, setDirectMissing] = useState3([]);
   const destRoot = process.cwd();
-  useEffect(() => {
-    if (directSkills && directSkills.length > 0 && targetKey) {
-      installByName(directSkills, targets[targetKey], destRoot).then((res) => {
-        setResults(res);
-        setStep(STEPS.DONE);
-      });
-    }
-  }, [targetKey]);
-  async function installByName(names, targetConfig, dest) {
-    const collections = listCollections();
-    let skillCount = 0;
-    let agentCount = 0;
-    for (const name of names) {
-      for (const col of collections) {
-        const { skills, agents } = scanCollection(col);
-        if (skills.includes(name)) {
-          if (await installSkill(col, name, targetConfig, dest)) skillCount++;
-          break;
-        }
-        if (agents.includes(name)) {
-          if (await installAgent(col, name, targetConfig, dest)) agentCount++;
-          break;
-        }
-      }
-    }
-    return { skills: skillCount, agents: agentCount, deps: [] };
-  }
   function getAvailableTypes(col) {
     const { skills, agents } = scanCollection(col);
     const types = [];
@@ -378,11 +361,29 @@ function Add({ directSkills }) {
   }
   function handleTargetSelect(key) {
     setTargetKey(key);
-    if (directSkills && directSkills.length > 0) return;
     setStep(STEPS.COLLECTIONS);
   }
   function handleCollectionSelect(col) {
     setSelectedCollection(col);
+    if (directSkills && directSkills.length > 0) {
+      const { skills, agents } = scanCollection(col);
+      const skillItems = [];
+      const agentItems = [];
+      const missing = [];
+      for (const name of directSkills) {
+        if (skills.includes(name)) skillItems.push({ collection: col, name });
+        else if (agents.includes(name)) agentItems.push({ collection: col, name });
+        else missing.push(`${name} (not in ${col})`);
+      }
+      setDirectMissing(missing);
+      setToInstall({ skills: skillItems, agents: agentItems });
+      if (skillItems.length === 0 && agentItems.length === 0) {
+        setStep(STEPS.DONE);
+      } else {
+        setStep(STEPS.INSTALLING);
+      }
+      return;
+    }
     setToInstall({ skills: [], agents: [] });
     const types = getAvailableTypes(col);
     if (types.length === 1) {
@@ -466,8 +467,24 @@ function Add({ directSkills }) {
     );
   }
   if (step === STEPS.COLLECTIONS) {
-    const collections = listCollections();
+    let collections = listCollections();
+    if (directSkills && directSkills.length > 0) {
+      const union = /* @__PURE__ */ new Set();
+      for (const name of directSkills) {
+        for (const c of findCollectionsContaining(name, "skill")) union.add(c);
+        for (const c of findCollectionsContaining(name, "agent")) union.add(c);
+      }
+      collections = collections.filter((c) => union.has(c));
+    }
     const items = collections.map((c) => ({ label: c, value: c }));
+    if (items.length === 0) {
+      setTimeout(() => exit(), 100);
+      return /* @__PURE__ */ jsxs4(ErrorMsg, { children: [
+        "None of: ",
+        directSkills.join(", "),
+        " found in any collection."
+      ] });
+    }
     return /* @__PURE__ */ jsx3(
       Select,
       {
@@ -530,6 +547,10 @@ function Add({ directSkills }) {
   if (step === STEPS.DONE) {
     setTimeout(() => exit(), 100);
     return /* @__PURE__ */ jsxs4(Box3, { flexDirection: "column", marginTop: 1, children: [
+      directMissing.length > 0 && /* @__PURE__ */ jsx3(Box3, { marginBottom: 1, children: /* @__PURE__ */ jsxs4(ErrorMsg, { children: [
+        "Not found in any collection: ",
+        directMissing.join(", ")
+      ] }) }),
       results.deps.length > 0 && /* @__PURE__ */ jsxs4(Box3, { flexDirection: "column", marginBottom: 1, children: [
         /* @__PURE__ */ jsx3(Info, { children: "Auto-installed dependencies:" }),
         results.deps.map((d) => /* @__PURE__ */ jsxs4(Text4, { color: "cyan", children: [
@@ -690,88 +711,161 @@ function hasChanges(localContent, latestContent) {
 import { jsx as jsx7, jsxs as jsxs7 } from "react/jsx-runtime";
 var STEPS2 = {
   TARGET: "target",
-  CHECKING: "checking",
+  COLLECTION: "collection",
+  ITEMS: "items",
+  RESOLVE: "resolve",
   CONFIRM: "confirm",
   DONE: "done"
 };
-function Update() {
+function detectType(name, targetConfig, destRoot) {
+  const skillPath = path3.join(destRoot, targetConfig.skillsDir, name, "SKILL.md");
+  if (fs3.existsSync(skillPath)) return "skill";
+  const agentPath = path3.join(destRoot, targetConfig.agentsDir, `${name}.md`);
+  if (fs3.existsSync(agentPath)) return "agent";
+  return null;
+}
+function Update({ directSkills }) {
   const { exit } = useApp3();
   const [step, setStep] = useState4(STEPS2.TARGET);
   const [targetKey, setTargetKey] = useState4(null);
-  const [changedItems, setChangedItems] = useState4([]);
+  const [selectedCollection, setSelectedCollection] = useState4(null);
+  const [queue, setQueue] = useState4([]);
   const [currentIdx, setCurrentIdx] = useState4(0);
+  const [currentPatch, setCurrentPatch] = useState4(null);
   const [updatedCount, setUpdatedCount] = useState4(0);
   const [skippedCount, setSkippedCount] = useState4(0);
+  const [installedCount, setInstalledCount] = useState4(0);
+  const [missingNames, setMissingNames] = useState4([]);
+  const [directInfo, setDirectInfo] = useState4([]);
   const destRoot = process.cwd();
-  function findSource(name, type) {
-    for (const col of listCollections()) {
-      const { skills, agents } = scanCollection(col);
-      if (type === "skill" && skills.includes(name)) return { collection: col };
-      if (type === "agent" && agents.includes(name)) return { collection: col };
+  function handleTargetSelect(key) {
+    setTargetKey(key);
+    if (directSkills && directSkills.length > 0) {
+      const targetConfig = targets[key];
+      const info = [];
+      const missing = [];
+      for (const name of directSkills) {
+        let type = detectType(name, targetConfig, destRoot);
+        let installed = type !== null;
+        if (!type) {
+          if (findCollectionsContaining(name, "skill").length > 0) type = "skill";
+          else if (findCollectionsContaining(name, "agent").length > 0) type = "agent";
+        }
+        if (!type) {
+          missing.push(name);
+          continue;
+        }
+        const cols = findCollectionsContaining(name, type);
+        if (cols.length === 0) {
+          missing.push(name);
+          continue;
+        }
+        info.push({ name, type, installed, collections: cols });
+      }
+      setMissingNames(missing);
+      setDirectInfo(info);
+      if (info.length === 0) {
+        setStep(STEPS2.DONE);
+        return;
+      }
     }
-    return null;
+    setStep(STEPS2.COLLECTION);
   }
-  useEffect2(() => {
-    if (step !== STEPS2.CHECKING) return;
-    const targetConfig = targets[targetKey];
-    const installed = listInstalled(targetConfig, destRoot);
-    const changed = [];
-    for (const skillName of installed.skills) {
-      const source = findSource(skillName, "skill");
-      if (!source) continue;
-      const localFile = path3.join(destRoot, targetConfig.skillsDir, skillName, "SKILL.md");
-      const latestFile = path3.join(getCollectionsDir(), source.collection, "skills", skillName, "SKILL.md");
-      if (!fs3.existsSync(localFile) || !fs3.existsSync(latestFile)) continue;
-      const localContent = fs3.readFileSync(localFile, "utf-8");
-      const latestContent = fs3.readFileSync(latestFile, "utf-8");
-      if (hasChanges(localContent, latestContent)) {
-        changed.push({
-          name: skillName,
-          type: "skill",
-          collection: source.collection,
-          patch: computeDiff("SKILL.md", localContent, latestContent)
-        });
+  function handleCollectionSelect(collection) {
+    setSelectedCollection(collection);
+    if (directSkills && directSkills.length > 0) {
+      const items = [];
+      const skipped = [];
+      for (const entry of directInfo) {
+        if (entry.collections.includes(collection)) {
+          items.push({ name: entry.name, type: entry.type, installed: entry.installed });
+        } else {
+          skipped.push(`${entry.name} (not in ${collection})`);
+        }
       }
-    }
-    for (const agentName of installed.agents) {
-      const source = findSource(agentName, "agent");
-      if (!source) continue;
-      const localFile = path3.join(destRoot, targetConfig.agentsDir, `${agentName}.md`);
-      const latestFile = path3.join(getCollectionsDir(), source.collection, "agents", `${agentName}.md`);
-      if (!fs3.existsSync(localFile) || !fs3.existsSync(latestFile)) continue;
-      const localContent = fs3.readFileSync(localFile, "utf-8");
-      const latestContent = fs3.readFileSync(latestFile, "utf-8");
-      if (hasChanges(localContent, latestContent)) {
-        changed.push({
-          name: agentName,
-          type: "agent",
-          collection: source.collection,
-          patch: computeDiff(`${agentName}.md`, localContent, latestContent)
-        });
+      if (skipped.length > 0) {
+        setMissingNames((prev) => [...prev, ...skipped]);
+      }
+      setQueue(items);
+      setCurrentIdx(0);
+      if (items.length === 0) {
+        setStep(STEPS2.DONE);
+      } else {
+        setStep(STEPS2.RESOLVE);
       }
+    } else {
+      setStep(STEPS2.ITEMS);
     }
-    setChangedItems(changed);
-    if (changed.length === 0) {
+  }
+  function handleItemsSubmit(values) {
+    const items = values.map((v) => {
+      const [type, name] = v.split(":");
+      return { name, type, installed: true };
+    });
+    setQueue(items);
+    setCurrentIdx(0);
+    if (items.length === 0) {
       setStep(STEPS2.DONE);
     } else {
-      setCurrentIdx(0);
-      setStep(STEPS2.CONFIRM);
+      setStep(STEPS2.RESOLVE);
     }
-  }, [step]);
-  function handleTargetSelect(key) {
-    setTargetKey(key);
-    setStep(STEPS2.CHECKING);
+  }
+  useEffect2(() => {
+    if (step !== STEPS2.RESOLVE) return;
+    const item = queue[currentIdx];
+    if (!item) {
+      setStep(STEPS2.DONE);
+      return;
+    }
+    processItem(item);
+  }, [step, currentIdx]);
+  async function processItem(item) {
+    const targetConfig = targets[targetKey];
+    const collection = selectedCollection;
+    if (!item.installed) {
+      if (item.type === "skill") {
+        await installSkill(collection, item.name, targetConfig, destRoot);
+      } else {
+        await installAgent(collection, item.name, targetConfig, destRoot);
+      }
+      setInstalledCount((c) => c + 1);
+      advance();
+      return;
+    }
+    let localFile;
+    let latestFile;
+    if (item.type === "skill") {
+      localFile = path3.join(destRoot, targetConfig.skillsDir, item.name, "SKILL.md");
+      latestFile = path3.join(getCollectionsDir(), collection, "skills", item.name, "SKILL.md");
+    } else {
+      localFile = path3.join(destRoot, targetConfig.agentsDir, `${item.name}.md`);
+      latestFile = path3.join(getCollectionsDir(), collection, "agents", `${item.name}.md`);
+    }
+    if (!fs3.existsSync(localFile) || !fs3.existsSync(latestFile)) {
+      advance();
+      return;
+    }
+    const localContent = fs3.readFileSync(localFile, "utf-8");
+    const latestContent = fs3.readFileSync(latestFile, "utf-8");
+    if (!hasChanges(localContent, latestContent)) {
+      setSkippedCount((c) => c + 1);
+      advance();
+      return;
+    }
+    const filename = item.type === "skill" ? "SKILL.md" : `${item.name}.md`;
+    setCurrentPatch(computeDiff(filename, localContent, latestContent));
+    setStep(STEPS2.CONFIRM);
   }
   function handleConfirm(yes) {
-    const item = changedItems[currentIdx];
+    const item = queue[currentIdx];
     const targetConfig = targets[targetKey];
     if (yes) {
       if (item.type === "skill") {
-        const src = path3.join(getCollectionsDir(), item.collection, "skills", item.name);
+        const src = path3.join(getCollectionsDir(), selectedCollection, "skills", item.name);
         const dest = path3.join(destRoot, targetConfig.skillsDir, item.name);
         fs3.copySync(src, dest, { overwrite: true });
       } else {
-        const src = path3.join(getCollectionsDir(), item.collection, "agents", `${item.name}.md`);
+        const src = path3.join(getCollectionsDir(), selectedCollection, "agents", `${item.name}.md`);
         const dest = path3.join(destRoot, targetConfig.agentsDir, `${item.name}.md`);
         fs3.copySync(src, dest, { overwrite: true });
       }
@@ -779,39 +873,119 @@ function Update() {
     } else {
       setSkippedCount((c) => c + 1);
     }
-    if (currentIdx + 1 < changedItems.length) {
+    advance();
+  }
+  function advance() {
+    setCurrentPatch(null);
+    if (currentIdx + 1 < queue.length) {
       setCurrentIdx((i) => i + 1);
+      setStep(STEPS2.RESOLVE);
     } else {
       setStep(STEPS2.DONE);
     }
   }
   if (step === STEPS2.TARGET) {
-    return /* @__PURE__ */ jsx7(Select, { items: targetList, onSelect: handleTargetSelect, onBack: () => exit(), message: "Which target to update?" });
+    return /* @__PURE__ */ jsx7(
+      Select,
+      {
+        items: targetList,
+        onSelect: handleTargetSelect,
+        onBack: () => exit(),
+        message: "Which target to update?"
+      }
+    );
+  }
+  if (step === STEPS2.COLLECTION) {
+    let collectionNames;
+    if (directSkills && directSkills.length > 0) {
+      const union = /* @__PURE__ */ new Set();
+      for (const entry of directInfo) {
+        for (const c of entry.collections) union.add(c);
+      }
+      collectionNames = listCollections().filter((c) => union.has(c));
+    } else {
+      collectionNames = listCollections();
+    }
+    const items = collectionNames.map((c) => ({ label: c, value: c }));
+    return /* @__PURE__ */ jsx7(
+      Select,
+      {
+        items,
+        onSelect: handleCollectionSelect,
+        onBack: () => setStep(STEPS2.TARGET),
+        message: "Pick collection to update from:"
+      }
+    );
+  }
+  if (step === STEPS2.ITEMS) {
+    const targetConfig = targets[targetKey];
+    const installed = listInstalled(targetConfig, destRoot);
+    const { skills, agents } = scanCollection(selectedCollection);
+    const items = [
+      ...installed.skills.filter((name) => skills.includes(name)).map((name) => ({
+        label: `${name} (skill)`,
+        value: `skill:${name}`,
+        checked: false
+      })),
+      ...installed.agents.filter((name) => agents.includes(name)).map((name) => ({
+        label: `${name} (agent)`,
+        value: `agent:${name}`,
+        checked: false
+      }))
+    ];
+    if (items.length === 0) {
+      setTimeout(() => exit(), 100);
+      return /* @__PURE__ */ jsxs7(Info, { children: [
+        'No installed skills/agents from "',
+        selectedCollection,
+        '" under ',
+        targetConfig.skillsDir,
+        "/."
+      ] });
+    }
+    return /* @__PURE__ */ jsx7(
+      MultiSelect,
+      {
+        items,
+        onSubmit: handleItemsSubmit,
+        onBack: () => setStep(STEPS2.COLLECTION),
+        message: `Select skills/agents from "${selectedCollection}" to update:`
+      }
+    );
   }
-  if (step === STEPS2.CHECKING) {
-    return /* @__PURE__ */ jsx7(Text8, { color: "yellow", children: "Checking for updates..." });
+  if (step === STEPS2.RESOLVE) {
+    return /* @__PURE__ */ jsx7(Text8, { color: "yellow", children: "Checking..." });
   }
   if (step === STEPS2.CONFIRM) {
-    const item = changedItems[currentIdx];
+    const item = queue[currentIdx];
     return /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", children: [
       /* @__PURE__ */ jsxs7(Warning, { children: [
         item.name,
-        ": local differs from latest"
+        ": local differs from ",
+        selectedCollection
       ] }),
-      /* @__PURE__ */ jsx7(DiffView, { patch: item.patch }),
+      /* @__PURE__ */ jsx7(DiffView, { patch: currentPatch }),
       /* @__PURE__ */ jsx7(Box7, { marginTop: 1, children: /* @__PURE__ */ jsx7(Confirm, { message: `Update ${item.name}?`, onConfirm: handleConfirm }) })
     ] });
   }
   if (step === STEPS2.DONE) {
     setTimeout(() => exit(), 100);
-    if (changedItems.length === 0) {
-      return /* @__PURE__ */ jsx7(Success, { children: "All installed skills are up to date." });
-    }
-    return /* @__PURE__ */ jsxs7(Success, { children: [
-      updatedCount,
-      " updated, ",
-      skippedCount,
-      " skipped"
+    if (queue.length === 0 && missingNames.length === 0) {
+      return /* @__PURE__ */ jsx7(Success, { children: "Nothing to update." });
+    }
+    return /* @__PURE__ */ jsxs7(Box7, { flexDirection: "column", children: [
+      missingNames.length > 0 && /* @__PURE__ */ jsxs7(ErrorMsg, { children: [
+        "Skipped: ",
+        missingNames.join(", ")
+      ] }),
+      /* @__PURE__ */ jsxs7(Success, { children: [
+        updatedCount,
+        " updated, ",
+        installedCount,
+        " installed, ",
+        skippedCount,
+        " skipped"
+      ] })
     ] });
   }
   return null;
@@ -914,7 +1088,7 @@ function Help() {
   const commands = [
     { name: "add [skills...]", desc: "Install skills/agents (interactive if no args)" },
     { name: "list", desc: "List all available skills and agents" },
-    { name: "update", desc: "Update installed skills to latest version" },
+    { name: "update [skills...]", desc: "Update installed skills (interactive if no args)" },
     { name: "remove <skills>", desc: "Remove installed skills/agents" },
     { name: "help", desc: "Show this help message" }
   ];
@@ -923,6 +1097,7 @@ function Help() {
     "npx @hiver/skills add discuss-problem create-prd",
     "npx @hiver/skills list",
     "npx @hiver/skills update",
+    "npx @hiver/skills update build-component",
     "npx @hiver/skills remove discuss-problem"
   ];
   return /* @__PURE__ */ jsxs9(Box9, { flexDirection: "column", marginTop: 1, marginBottom: 1, children: [
@@ -959,7 +1134,7 @@ function App() {
     case "list":
       return /* @__PURE__ */ jsx9(List, {});
     case "update":
-      return /* @__PURE__ */ jsx9(Update, {});
+      return /* @__PURE__ */ jsx9(Update, { directSkills: restArgs.length > 0 ? restArgs : null });
     case "remove":
       if (restArgs.length === 0) {
         return /* @__PURE__ */ jsxs9(Text10, { color: "red", children: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiver/skills",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Shared Claude Code skills & agents for Hiver teams",
   "type": "module",
   "bin": {