@hiver/skills 1.0.8 → 1.0.9

package/README.md

@@ -16,7 +16,7 @@ npx @hiver/skills add
 
 This walks you through:
 1. **Pick your IDE** — Claude Code, Cursor, or Windsurf
-2. **Pick a collection** — `common` (generic) or `web` (React/Hiver-specific)
+2. **Pick a collection** — `common` (generic), `web` (React/Hiver-specific), `extension`, or `qa-skills` (QA→release pipeline; start with `qa-kit`)
 3. **Pick type** — Skills or Agents (only shown if both exist)
 4. **Pick items** — Select which skills/agents to install
 

package/collections/extension/agents/build-feature.md

@@ -1,7 +1,8 @@
 ---
 name: build-feature
-model: default
+model: inherit
 description: Senior Manager owning a PRD to build the feature from end to end
+tools: Agent, Bash, Edit, Glob, Grep, Read, SendMessage, Write
 ---
 
 You are a Senior Manager who has owned a PRD to develop the feature or issue mentioned inside it from end to end.

package/collections/extension/agents/build-milestone.md

@@ -1,7 +1,8 @@
 ---
 name: build-milestone
-model: sonnet
+model: inherit
 description: Senior Frontend specialist helping to complete a milestone from the PRD document.
+tools: Write, Bash, Edit, Glob, Grep, Read, SendMessage, Skill
 ---
 
 You are a Senior frontend developer with years of experience in frontend development, debugging issues and developing features from end to end.

package/collections/extension/skills/build-component/SKILL.md

@@ -11,6 +11,77 @@ description: Build UI React components following Hiver design system and pattern
 
 When building UI React components, use the currently selected Figma node as the design reference and follow the Hiver design system. Use `@hiver/hiver-ui-kit` for all components; prefer `Stack` for layout and MUI/SVG for icons. Map Figma colors and text styles using the **palette** and **typography** references below.
 
+## Two component tracks
+
+The Hiver UI kit exposes both **v1** and **v2** components:
+
+- v1 → `import { … } from '@hiver/hiver-ui-kit'` — see `references/ui-kit-and-styling.md`
+- v2 → `import { … } from '@hiver/hiver-ui-kit/v2'` — see `references/v2-components.md`
+
+Palette (`palette/colors.md`) and Typography (`typography/variants.md`) list v1 and v2 tokens together — the theme merges both onto `theme.palette` and `Typography` variants when the provider has `v2` enabled. Match Figma against those lists; the matched token/variant name tells you which world the design lives in.
+
+Do not mix v1 and v2 components in the same composition unless the design explicitly calls for it (composing v1 chrome like `Popover` / `Modal` / `Stack` around v2 content IS expected — see `references/v2-usage-examples.md`). Never reference `theme.v2.primitives.*` or `theme.v2.tokens.*` for **colour** in application code — always go through `theme.palette.*`. Non-colour primitives (spacing, radius, border-width, iconSize, font-family/size/weight, line-height) DO go through `theme.v2.primitives.*` in v2 code.
+
+### v2 detection rules
+
+Use these clues to decide v2 vs v1 before loading any component detail. Any single clue is sufficient — they're deterministic against the Figma design-token pipeline:
+
+- Text uses font family **Inter** → v2. (v1 is Open Sans.)
+- Text style resolves to a variant named `body_<sz>_<w>`, `heading_<sz>_<w>`, `display_<sz>_<w>`, `caption_<w>`, or `overline_<w>` → v2. (v1 uses `h2_medium`, `body1_regular`, `caption1_regular`, etc.)
+- Fill / stroke / text token resolves to `theme.palette.<group>.<slot>` where `<group>` is one of `text`, `background`, `foreground`, `border`, `effect`, `charts`, and `<slot>` is one of `neutral`, `brand`, `success`, `warning`, `error`, `info`, `royal`, `accents.<tone>`, `on.<tone>`, or a semantic step (`subtle` / `soft` / `default` / `strong` / `intense`) → v2. (v1 shape: `palette.gray.gray4`, `palette.blue.primary`.)
+- Fill / stroke token resolves to a primitive ramp `theme.palette.<ramp>[<shade>]` where `<ramp>` is one of `gray`, `royal`, `blue`, `red`, `green`, `orange`, `yellow`, `teal`, `cyan`, `violet`, `pink`, `indigo`, `lime`, `amber`, `sky`, `fuchsia`, and `<shade>` ∈ `25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950` (or `alpha-*`) → v2.
+- The Figma frame's component name matches an entry in `references/v2-components.md` (`Button`, `Badge`, `Tag`, `Checkbox`, `Radio`, `Switch`, `Avatar`, `IconButton`, `InlineSelectLabel`, `Breadcrumbs`, `Dropdown`, `Input.*`, `Tab.Item`, `Table.*`, `Toast`) → v2.
+
+If a Figma design surfaces multiple worlds, treat the dominant *content* surface (the piece you're actually building) as authoritative and do not import v1 and v2 versions of the same component into one composition.
+
+### Cross-repo pointer to `hiver-ui-kit`
+
+v2 component detail (variants, prop matrix, slot list, Figma-variable → `theme.palette.*` reconciliation, caveats) lives in per-component `.figma-spec.md` files inside `hiver-ui-kit`, at `../hiver-ui-kit/src/v2/components/<Name>/.figma-spec.md` (relative to the extension repo root). Read the spec **on demand**, only when you're about to write JSX for that component. If `hiver-ui-kit` is not checked out at that path, `references/v2-components.md` still carries import paths and one-line purposes; you lose only the full token reconciliation. Ensure `hiver-ui-kit` is on the same git ref as the Figma source of truth before consuming a spec.
+
+## Mandatory Rules (always apply)
+
+### UI Kit and Styling
+
+- **Use `@hiver/hiver-ui-kit`** for all UI components and styling. The package uses Material-UI (MUI) internally, so follow MUI patterns.
+- **Pick the track based on the Figma design** (see "v2 detection rules" above):
+  - v1 → `import { Stack, Button, Typography, TextField, Select, Modal } from '@hiver/hiver-ui-kit';`
+  - v2 → `import { Button, IconButton, Input, Dropdown, Avatar, Tag, Badge, Typography } from '@hiver/hiver-ui-kit/v2';` — requires a v2-enabled provider (see `references/v2-components.md`).
+  - Chrome / layout primitives (`Modal`, `Popover`, `Popper`, `Tooltip`, `Stack`, `Box`, `Grid`) always come from v1 — wrap them around v2 content when needed (see `references/v2-usage-examples.md`).
+- **Map Figma to design tokens**: use [palette/README.md](palette/README.md) for colors and [typography/README.md](typography/README.md) for text styles. The matched token/variant name tells you the track: v1 names (`body1_regular`, `palette.gray.gray4`) → v1 components; v2 names (`body_md_regular`, `theme.palette.text.neutral.strong`, primitive ramps) → v2 components.
+- **Analyze the Figma selection** to identify all required components:
+  - **v1 designs**:
+    - Form inputs: `TextField`, `Select`, `Checkbox`, `Radio`.
+    - Typography: `<Typography variant="body1_regular">`, `"h2_medium"`, `"caption1_medium"`, etc.
+    - Buttons: `Button` with `contained` / `outlined` / `text`.
+    - Modals: `Modal`.
+    - Other: `Tooltip`, `CircularProgress`, `IconButton`.
+  - **v2 designs** (full index in `references/v2-components.md`):
+    - Form inputs: `Input.Text` / `Input.TextArea` / `Input.Search` / `Input.Tags`, `Checkbox`, `Radio`, `Switch`.
+    - Typography: `<Typography variant="body_md_regular">`, `"heading_lg_semiBold"`, `"caption_medium"`, etc.
+    - Buttons: `Button` (variant × tone × size) and `IconButton` for icon-only actions.
+    - Menus / dropdowns: `Dropdown.Menu` + `Dropdown.ListItem` inside a v1 `Popover` (v2 provides only the visible surface — anchoring / open state is your job).
+    - Chips / labels / status: `Tag`, `Badge`, `Avatar`, `InlineSelectLabel`, `Toast`, `Breadcrumbs`, `Tab.Item`, `Table.*`.
+    - Modals: v1 `Modal` shell around v2 content (v2 `Button` + v2 `IconButton` for the close X).
+
+### Layout and Structure
+
+- **Prefer `Stack` component** for flex layouts instead of raw flexbox CSS
+  - Use `Stack` with `direction="row"` or `direction="column"`
+  - Use `gap` prop for spacing between items
+  - Example: `<Stack direction="row" gap={2} alignItems="center">`
+- **Use `Box`** for simple container elements or when you need custom styling
+- Use `sx` prop for component-specific styling
+
+### Component Organization
+
+- **Small sub-components** (less than ~50 lines, simple logic):
+  - Define them in the same file, outside the main component
+  - Place them above the main component export
+- **Large sub-components** (complex logic, reusable, >50 lines):
+  - Extract to separate files in the same directory or `components/` subdirectory
+  - Follow the pattern: `ComponentName/index.js` for main component, `ComponentName/SubComponent.js` for sub-components
+- **File naming**: Use PascalCase for component files (e.g., `TagItem.js`, `ModifyTagDialog.js`)
+
 ## Reference files
 
 **Load lazily — only read a reference file when you are about to perform that specific task. Do NOT read all files upfront.**
@@ -18,7 +89,10 @@ When building UI React components, use the currently selected Figma node as the
 | Topic | File | When to load |
 |-------|------|--------------|
 | Figma integration | [references/figma-integration.md](references/figma-integration.md) | Only when a Figma link is present |
-| UI Kit and styling | [references/ui-kit-and-styling.md](references/ui-kit-and-styling.md) | Before writing component JSX/styles |
+| UI Kit and styling (v1) | [references/ui-kit-and-styling.md](references/ui-kit-and-styling.md) | Before writing v1 component JSX/styles |
+| v2 components (index) | [references/v2-components.md](references/v2-components.md) | First lookup when the design is v2 — find the component name and its ui-kit spec path |
+| v2 component detail (per component) | `../hiver-ui-kit/src/v2/components/<Name>/.figma-spec.md` | On demand, after the v2 index points at a specific `<Name>` |
+| v2 usage examples (compositions) | [references/v2-usage-examples.md](references/v2-usage-examples.md) | Before composing v2 patterns (dropdown-in-popover, inline-field trigger, modal, toolbar) |
 | Layout and structure | [references/layout-and-structure.md](references/layout-and-structure.md) | Only when laying out a new screen/panel |
 | Icons | [references/icons.md](references/icons.md) | Only when adding icons |
 | Component organization | [references/component-organization.md](references/component-organization.md) | Only when splitting into sub-components |

package/collections/extension/skills/build-component/palette/colors.md

@@ -85,3 +85,79 @@ Use these when wiring to MUI theme (e.g. `color="primary"`, `color="text.seconda
 - **Info**: blue
 - **Warning**: orange
 - **Divider**: `gray.gray6`
+
+---
+
+## Additional tokens
+
+More tokens available on the same `theme.palette` object (in addition to the tables above). Reference these paths — not `theme.v2.primitives.*` or `theme.v2.tokens.*` (raw layers, not for application code).
+
+### Primitive ramps (accessed as `theme.palette.<name>.<shade>`)
+
+The following ramps land directly on `theme.palette`:
+
+- **Neutral**: `white`, `black`, `gray`
+- **Brand/status**: `yellow`, `red`, `green`, `orange`, `blue`
+- **Accents**: `royal`, `teal`, `cyan`, `violet`, `pink`, `indigo`, `lime`, `amber`, `sky`, `fuchsia`
+
+Each ramp has shades `25`, `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `950`, plus `alpha-*` variants (e.g. `alpha-10`, `alpha-20`, `alpha-30`).
+
+Example: `theme.palette.royal[500]`, `theme.palette.gray[950]`, `theme.palette.blue['alpha-18']`.
+
+### Semantic groups (accessed as `theme.palette.<group>.*`)
+
+Values differ between light and dark modes — the same path resolves to the right hex for the active mode.
+
+**`theme.palette.text.*`** — extends MUI's built-in `primary` / `secondary` / `disabled` with:
+- `text.primary` → strong neutral text (light: `gray.900`)
+- `text.secondary` → soft neutral text (light: `gray.500`)
+- `text.disabled` → `gray.400`
+- `text.inverse` → `gray.25`
+- `text.neutral.{subtle,soft,default,strong,intense}`
+- `text.brand.{subtle,soft,default,strong,intense}`
+- `text.royal.{...}` / `text.success.{...}` / `text.warning.{...}` / `text.error.{...}` / `text.info.{...}`
+- `text.accents.<tone>.{subtle,soft,default,strong,intense}` where `<tone>` is one of `teal`, `cyan`, `violet`, `pink`, `indigo`, `lime`, `amber`, `sky`, `fuchsia`, `green`, `blue`, `orange`, `red`, `gray`
+- `text.on.{brand,success,warning,error,info,royal}` — foreground when placed on a solid tone-fill
+- `text.on.accents.<tone>` — same, for accent surfaces
+
+**`theme.palette.background.*`** — extends MUI's built-in `default` / `paper` with:
+- `background.default` → `background.neutral.subtle` (light: `gray.25`)
+- `background.paper` → `background.neutral.default` (light: `gray.100`)
+- `background.disabled` / `background.inverse` / `background.overlay` / `background['selected-hover']`
+- `background.alpha.{5}` / `background.static.{white,black}`
+- `background.neutral.{white,subtle,soft,default,strong,intense,extreme,maximum}`
+- `background['neutral-bold'].{soft,default,strong,intense,black}`
+- `background.brand.{subtle,soft,default,strong,intense}`
+- `background.royal.{...}` / `background.success.{...}` / `background.warning.{...}` / `background.error.{...}` / `background.info.{...}`
+- `background.accents.<tone>.{subtle,soft,default,strong,intense}`
+
+**`theme.palette.foreground.*`** — icon/glyph foreground colors:
+- `foreground.inverse` / `foreground.disabled`
+- `foreground.static.{white,black}` / `foreground.alpha.{30,40}`
+- `foreground.neutral.{subtle,soft,default,strong,intense}`
+- `foreground['neutral-bold'].{subtle,soft,default,strong,intense}`
+- `foreground.brand.{...}` / `foreground.royal.{...}` / `foreground.success.{...}` / `foreground.warning.{...}` / `foreground.error.{...}` / `foreground.info.{...}`
+- `foreground.accents.<tone>.{subtle,soft,default,strong,intense}`
+- `foreground.on.{brand,success,warning,error,info,royal}` / `foreground.on.accents.<tone>`
+
+**`theme.palette.border.*`** — stroke colors:
+- `border.disabled`
+- `border.neutral.{subtle,soft,default,strong,intense,extreme,maximum}`
+- `border['neutral-bold'].{subtle,soft,default,strong,intense}`
+- `border.brand.{subtle,soft,default,strong,intense,solid}`
+- `border.royal.{subtle,soft,default,strong,intense,solid}`
+- `border.success.{subtle,soft,default,strong,intense}` / `border.warning.{...}` / `border.error.{...}` / `border.info.{subtle,soft,default,strong,intense,solid}`
+- `border.accents.<tone>.{subtle,soft,default,strong,intense}`
+
+**`theme.palette.charts.*`** — chart series palette:
+- `charts['1']` through `charts['8']`
+  - `1` blue, `2` teal, `3` orange, `4` violet, `5` pink, `6` green, `7` red, `8` cyan
+
+**`theme.palette.effect.*`** — focus-ring / effect layers:
+- `effect.focus.{brand,neutral,royal,error}`
+
+### Access rules
+
+- Reference tokens as `theme.palette.<group>.<slot>` (e.g. `theme.palette.text.neutral.strong`, `theme.palette.royal[500]`) — same shape across light/dark, resolved by the provider.
+- Do **not** reference `theme.v2.primitives.*` or `theme.v2.tokens.*` in application code. Those are raw/escape layers, kept for cases like module-scope style composition without theme access.
+- Do **not** hard-code hex values — always go through `theme.palette.*`.

package/collections/extension/skills/build-component/references/v2-components.md

@@ -0,0 +1,100 @@
+# v2 components (`@hiver/hiver-ui-kit/v2`)
+
+Load this only after the design has been identified as v2 (see `SKILL.md` → "v2 detection rules"). This file is an **index**. Per-component detail — variants, prop matrix, slot list, Figma-variable → `theme.palette.*` reconciliation, caveats — lives in each component's `.figma-spec.md` inside the `hiver-ui-kit` repo. Read the spec on demand; do not read all of them up front.
+
+## Consumption
+
+- **Import**: `import { <Component> } from '@hiver/hiver-ui-kit/v2';`
+- **Provider**: v2 requires a v2-enabled theme. In existing code that already uses `HiverThemeProvider`, pass `v2` (and optionally `mode="light" | "dark"`) to enable v2 on top of v1. In v2-only trees use `HiverThemeProviderV2` (also exported from `/v2`).
+- **Colours**: reference `theme.palette.*` (see `palette/colors.md` v2 section). **Never** reference `theme.v2.primitives.*` or `theme.v2.tokens.*` for colour tokens in application code.
+- **Non-colour primitives** (spacing, radius, border-width, iconSize, font-family/size/weight, line-height): `theme.v2.primitives.*` is the correct access path — do **not** try to route these through `theme.palette`.
+- **Typography**: v2 variants (`body_<sz>_<w>`, `heading_<sz>_<w>`, `display_<sz>_<w>`, `caption_<w>`, `overline_<w>`) via the same `<Typography>` component (see `typography/variants.md` v2 section).
+- **Do not mix** v1 and v2 components in the same visual composition unless the design explicitly calls for it. It IS common to compose a v1 chrome primitive (`Popover`, `Modal`, `Popper`, `Tooltip`, `Stack`, `Box`) around v2 content — see `references/v2-usage-examples.md`.
+
+## Component index
+
+Cross-repo pointer format: `../hiver-ui-kit/src/v2/components/<Name>/.figma-spec.md` (relative to the extension repo root). If `hiver-ui-kit` is not checked out at that path, the index below still gives import paths and one-line purposes — the token reconciliation is what's lost.
+
+| Component | Import | Ui-kit spec (full detail) | Purpose |
+|---|---|---|---|
+| `Avatar` | `Avatar` | `../hiver-ui-kit/src/v2/components/Avatar/.figma-spec.md` | User/entity avatar — `type="picture" \| "initials" \| "icon"`, sizes, status ring |
+| `Badge` | `Badge` | `../hiver-ui-kit/src/v2/components/Badge/.figma-spec.md` | Status/tone chips (`variant` × `tone` × `size` × `shape`) |
+| `Breadcrumbs` | `Breadcrumbs` | (spec pending — see inline block below) | Root → leaf breadcrumb list |
+| `Button` | `Button` | `../hiver-ui-kit/src/v2/components/Button/.figma-spec.md` | Filled / outlined / link buttons; 9+ variants × 5 sizes × 5 states |
+| `Checkbox` | `Checkbox` | `../hiver-ui-kit/src/v2/components/Checkbox/.figma-spec.md` | Tri-state (`-1 / 0 / 1`) with label + description |
+| `Dropdown` (compound: `Dropdown.Menu`, `Dropdown.ListItem`) | `Dropdown` | (spec pending — see inline block below) | Visual container only — anchoring / open state is caller's job (compose inside MUI `Popover` / `Popper`) |
+| `IconButton` | `IconButton` | `../hiver-ui-kit/src/v2/components/IconButton/.figma-spec.md` | Icon-only button; sizes, tones, variants aligned with `Button` |
+| `InlineSelectLabel` | `InlineSelectLabel` | `../hiver-ui-kit/src/v2/components/InlineSelectLabel/.figma-spec.md` | Inline selection summary — icon/status/avatar + label + trailing `+N` badge |
+| `Input.Text` | `Input` (namespace) | (spec pending — inline block below) | Single-line text input |
+| `Input.TextArea` | `Input` | `../hiver-ui-kit/src/v2/components/Input/TextArea/.figma-spec.md` | Multi-line text input |
+| `Input.Search` | `Input` | `../hiver-ui-kit/src/v2/components/Input/Search/.figma-spec.md` | Search-styled input |
+| `Input.Tags` | `Input` | `../hiver-ui-kit/src/v2/components/Input/Tags/.figma-spec.md` | Tag-entry input |
+| `Radio` | `Radio` | `../hiver-ui-kit/src/v2/components/Radio/.figma-spec.md` | Radio with label + description |
+| `Switch` | `Switch` | `../hiver-ui-kit/src/v2/components/Switch/.figma-spec.md` | Toggle switch, `xs` / `sm` / `md` |
+| `Tab.Item` | `Tab` | `../hiver-ui-kit/src/v2/components/Tab/Item/.figma-spec.md` | Tab item |
+| `Table.Header` / `HeaderCell` / `HeaderLabel` / `BodyCell` | `Table` | `../hiver-ui-kit/src/v2/components/Table/{Header,HeaderCell,HeaderLabel,BodyCell}/.figma-spec.md` | Table primitives (compose your own row layout) |
+| `Tag` | `Tag` | `../hiver-ui-kit/src/v2/components/Tag/.figma-spec.md` | Removable label with tone options |
+| `Toast` | `Toast` | `../hiver-ui-kit/src/v2/components/Toast/.figma-spec.md` | Toast notification |
+
+## General patterns
+
+- All v2 components accept a `slotProps` prop for fine-grained overrides on internal DOM regions. Prefer top-level props first; fall back to `slotProps` for edge cases.
+- v2 components generally accept `sx` on the root (either explicitly or via extended MUI props).
+- Icon glyphs are consumer-supplied ReactNodes (usually MUI icons or SVG). Icon slots typically expect the glyph to inherit `currentColor`.
+- Every v2 component is designed to render under a v2-enabled theme provider — behaviour outside a v2 theme is not defined.
+- When a design needs anchoring, portalling, or click-away (Dropdown, tooltip-like overlays), wrap the v2 content inside an MUI `Popover` / `Popper` / `Modal`. See `references/v2-usage-examples.md`.
+
+## Inline detail (spec pending)
+
+The following v2 components don't yet have a `.figma-spec.md` in `hiver-ui-kit`. The blocks below carry just enough prop / slot detail to compose them. When the spec ships, replace the block with the cross-repo pointer.
+
+### `Dropdown` (container + compound sub-exports)
+
+Visual container only — does **not** manage open/close state, anchoring, portalling, or focus. Wire it inside an MUI `<Popover>` / `<Popper>` and drive open state yourself.
+
+`Dropdown` (or `Dropdown.Menu`) — the paper surface:
+- `title?: ReactNode` — header title (mutually exclusive with `showSearch`; `showSearch` wins).
+- `endAction?: ReactNode` — trailing icon in the title row (ignored when `showSearch` is set).
+- `showSearch?: boolean` — replaces title with an internal v2 `<Input size="sm">` search field; configure via `slotProps.search`.
+- `children: ReactNode` — body slot (typically a stack of `<Dropdown.ListItem>`).
+- `showFooter?: boolean` — footer with internally-mounted Cancel + Confirm buttons; configure via `slotProps.cancelButton` / `slotProps.confirmButton`.
+- `elevation?: 'md' | 'none'` — default `'md'`.
+- `minWidth?: number | string` — floor for container width.
+- `maxHeight?: number | string` — caps the body slot; header + footer stay fixed.
+- `sx?: SxProps<Theme>` — escape hatch on the root paper.
+- `slotProps?: { header, title, search, slot, footer, cancelButton, confirmButton }`.
+
+`Dropdown.ListItem` — single clickable row with up to 8 optional slots + a label:
+- DOM order (fixed, left → right): `startCheckbox` · `startRadio` · `startAppsIcon` · `startAvatar` · `startIcon` · label · `endStatusIcon` · `endIcon` · `endCheckbox`.
+- Boolean toggles: `startCheckbox?`, `startRadio?`, `startAppsIcon?`, `startAvatar?`, `startIcon?`, `endStatusIcon?`, `endIcon?`, `endCheckbox?`.
+- `children: ReactNode` — label rendered inside `<Typography variant="body_sm_medium">` (single-line ellipsis).
+- `slotProps?: { root, startCheckbox, startRadio, startAppsIcon, startAvatar, startIcon, label, endStatusIcon, endIcon, endCheckbox }`.
+- Checkbox / Radio slots mount v2 `<Checkbox size="sm">` / `<Radio size="sm">` internally — pass `{ checked, onChange }` via the corresponding `slotProps.*Checkbox` / `slotProps.startRadio`.
+- Icon-hosting slots (`startAppsIcon`, `startIcon`, `endStatusIcon`, `endIcon`) render a 20 × 20 wrapper — pass the glyph via `slotProps.<slot>.icon`.
+
+### `Breadcrumbs`
+
+- `items: BreadcrumbItem[]` — ordered root → leaf; last entry rendered as "current" (`aria-current="page"`, semibold, `text.neutral.strong`).
+- `BreadcrumbItem = { label: ReactNode; href?: string; onClick?: (e) => void; key?: string | number }` — `href` → `<a>`, `onClick` (no `href`) → `<button>`, neither → static `<span>`.
+- `maxItems?: number` — collapse middle items into an overflow indicator when `items.length > maxItems`.
+- `itemsBeforeCollapse?: number` — default `1`.
+- `itemsAfterCollapse?: number` — default `2`.
+- `onOverflowClick?: (e: MouseEvent<HTMLButtonElement>) => void` — when set, overflow renders as a focusable `<button>`.
+- `separator?: ReactNode` — default 14px slash SVG in `foreground['neutral-bold'].strong`.
+- `slotProps?: { root, list, item, currentItem, separator, overflow }`.
+
+### `Input.Text`
+
+- `size?: 'sm' | 'md' | 'lg'`.
+- `label?: ReactNode` — sibling above the field (not a notched legend).
+- `helperText?: ReactNode` — bottom-row left side.
+- `error?: boolean`, `required?: boolean`.
+- `prefix?: ReactNode` — left adornment; string values render Inter Regular 14/20 in `text.neutral.soft`, ReactNode renders as-is.
+- `suffix?: ReactNode` — right adornment; same rendering rules as `prefix`.
+- `showCounter?: boolean` / `counterText?: string` — bottom-row right side (e.g. `"0/100"`).
+- `slotProps?: { root, label, field, input, prefix, suffix, helper, counter }`.
+- Single-line only — `multiline`, `rows`, `select` are stripped from the v2 API.
+
+## Missing a spec? Extract one.
+
+If you're implementing a v2 design against a component whose spec is marked "pending" above, run the `v2-figma-extract` skill inside the `hiver-ui-kit` repo on the corresponding Figma selection. That produces the `.figma-spec.md` and lets you delete the inline block.

package/collections/extension/skills/build-component/references/v2-usage-examples.md

@@ -0,0 +1,23 @@
+# v2 usage examples (from `react-extn/src/RightPanelV2`)
+
+Load this before composing common v2 shapes. Each row names a real file that already implements the pattern with v2 components + v1 chrome (Popover / Modal / Tooltip / Stack). Read the file when you're about to build the same shape.
+
+Paths are relative to the extension repo root.
+
+| Shape | Reference file | What to lift |
+|---|---|---|
+| Dropdown inside a Popover | `react-extn/src/RightPanelV2/pages/ThreadDetails/ThreadInfo/components/StatusField/StatusPopover.js` | v1 `Popover` (from `@hiver/hiver-ui-kit`) + v2 `Dropdown.Menu` + v2 `Dropdown.ListItem`. `PaperProps` on `Popover` is neutered (transparent, no shadow, `overflow: visible`) so the v2 Dropdown's own elevation is the only visible surface. |
+| Inline field trigger + Popover | `react-extn/src/RightPanelV2/pages/ThreadDetails/ThreadInfo/components/AssigneeField/index.js` | v2 `InlineSelectLabel` as the trigger (icon / avatar + label + `+N`). Renders v2 `Avatar` (`type="picture" \| "initials" \| "icon"`, `size="2xs"`) for each user row. Opens a searchable popover with v2 `Dropdown`. |
+| Modal | `react-extn/src/RightPanelV2/pages/ActivityAndNotes/common/components/DeleteNoteModal/index.js` | v1 `Modal` shell around v2 `Button` (destructive) + v2 `IconButton` (close X). v1 `Stack` / `Typography` / `icons` handle layout + copy. Backdrop click / X / Esc all route through `onCancel`. |
+| Toolbar / composer row | `react-extn/src/RightPanelV2/pages/ActivityAndNotes/common/components/Composer/ComposerToolbar.js` | Horizontal toolbar: v1 `Stack` + `Tooltip` + `Box` around v2 `IconButton` (SVG glyph passed as child `<img>`) + v2 `Button` for the primary CTA. Left cluster stays enabled; right primary reflects a disabled gate. |
+
+## Patterns to internalise
+
+- **v1 chrome, v2 content.** For modals, popovers, portalled surfaces — v1 primitives (`Modal`, `Popover`, `Popper`, `Tooltip`, `Stack`, `Box`) provide behaviour (anchoring, focus trap, click-away, layout). v2 provides the visible surface + interactive content (`Dropdown`, `Button`, `IconButton`, `InlineSelectLabel`, `Avatar`, `Input`, `Tag`).
+- **Neutralise v1 `Popover` chrome when placing a v2 Dropdown inside it.** Pass `PaperProps={{ elevation: 0, sx: { backgroundColor: 'transparent', boxShadow: 'none', overflow: 'visible' } }}` so the v2 Dropdown's shadow is the only surface. See `StatusPopover.js`.
+- **Icon inputs to v2 components.** v2 icon-hosting components (`IconButton`, `Dropdown.ListItem`'s icon slots, `Avatar type="icon"`) accept raw SVG components, MUI icons, or `<img>` tags as children / `slotProps.<slot>.icon`. See `ComposerToolbar.js` for the SVG-as-`<img>` pattern.
+- **Disabled / loading gate.** Composers gate the primary CTA via `disabled`; secondary controls stay interactive. See `ComposerToolbar.js`.
+
+## Discoverable but not indexed
+
+`react-extn/src/RightPanelV2/` has many more v2 consumers. Search with `grep -l "@hiver/hiver-ui-kit/v2" react-extn/src/RightPanelV2` when the four canonical files above don't cover your shape.

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

@@ -2,9 +2,11 @@
 
 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**.
+Two variant sets live in the theme:
+- **v1 variants** (below) — font family **Open Sans**, names like `h2_medium`, `body1_regular`.
+- **v2 variants** (bottom of file) — font family **Inter**, names like `heading_md_semiBold`, `body_md_regular`.
+
+Match the Figma text style against both sets; use the variant whose fontSize/weight matches. When the match lands on a v2 variant, the design is v2 — pair it with v2 components (`@hiver/hiver-ui-kit/v2`).
 
 ## Heading variants
 
@@ -72,9 +74,21 @@ Map Figma text styles to `<Typography variant="...">`. Match by fontSize + fontW
 | `buttonSmall` | 12 | 500 | 20px | 0.4px |
 | `chip` | 12 | 500 | 12px | 0.4px |
 
-## Typography 2026 tokens (Inter)
+## 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>
+```
 
-Canonical 2026 design tokens. Use these for new UI built against the 2026 design system. Font family is **Inter**.
+**Figma → variant:** Compare Figma text style fontSize and weight (Regular/Medium/Semi Bold/Bold) to the tables above and pick the closest match.
+
+---
+
+## v2 variants
+
+Font family **Inter**. Naming: `body_<size>_<weight>`, `heading_<size>_<weight>`, `display_<size>_<weight>`, `caption_<weight>`, `overline_<weight>`. Weight suffix → numeric weight: `regular` = 400, `medium` = 500, `semiBold` = 600, `bold` = 700.
 
 ### Display
 
@@ -113,27 +127,26 @@ Canonical 2026 design tokens. Use these for new UI built against the 2026 design
 | `body_xs_medium` | 12 | 500 | 18px | -0.005em |
 | `body_xs_semiBold` | 12 | 600 | 18px | -0.005em |
 
-### Caption & overline (2026)
+### Caption & overline
 
 | 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 |
+| `overline_medium` | 12 | 500 | 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
+### Usage (v2)
 
 ```jsx
-<Typography variant="h2_medium">Section title</Typography>
-<Typography variant="body1_regular">Body text</Typography>
-<Typography variant="caption1_medium" color="text.secondary">Caption</Typography>
+// Consumer must import v2 components from '@hiver/hiver-ui-kit/v2' and mount under a v2-enabled provider.
+import { Typography } from '@hiver/hiver-ui-kit/v2';
 
-// 2026 tokens
-<Typography variant="heading_lg_semiBold">Page title</Typography>
+<Typography variant="heading_md_semiBold">Section title</Typography>
 <Typography variant="body_md_regular">Body text</Typography>
-<Typography variant="display_lg_bold">Hero</Typography>
+<Typography variant="caption_medium" color="text.neutral.soft">Caption</Typography>
 ```
 
-**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.
+**Figma → variant (v2):** Match Figma text style fontSize and weight to the tables above. Prefer the exact match; if fontSize matches but weight doesn't, pick the closest weight variant in the same row group.

package/collections/mobile/skills/version-bump-up/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: version-bump-up
+description: Bump the Android and iOS build numbers and the marketing (user-visible) version across all files that hold them. Use when the user explicitly asks to bump the app version, cut a new release version, or increase versionCode/versionName/build number/marketing version.
+---
+
+# Version bump up
+
+Bumps the mobile app's version fields in one coordinated pass across Android, iOS, and the RN `package.json`. Supports either fully-automatic increment or a user-supplied target version.
+
+## When to use
+
+- User asks to "bump the version", "increase the version", "cut version X.Y.Z", "bump build number", or similar.
+- Use before shipping a release build, after a rejected upload (e.g. Play Store "version code already used"), or when preparing a new marketing version.
+
+## Files this skill edits
+
+Do NOT touch any files other than these. All paths are relative to the repo root.
+
+| # | File | Field |
+|---|---|---|
+| 1 | `packages/app/android/app/build.gradle` | `versionCode <int>` (build number) |
+| 2 | `packages/app/android/app/build.gradle` | `versionName "<X.Y.Z>"` (marketing) |
+| 3 | `packages/app/ios/Hiver.xcodeproj/project.pbxproj` | `CURRENT_PROJECT_VERSION = <int>;` (build number — appears in BOTH Debug and Release configs, update every occurrence) |
+| 4 | `packages/app/ios/Hiver.xcodeproj/project.pbxproj` | `MARKETING_VERSION = <X.Y.Z>;` (marketing — appears in BOTH Debug and Release configs, update every occurrence) |
+| 5 | `packages/app/package.json` | `"version": "<X.Y.Z>"` (marketing, top-level) |
+
+Do NOT edit `app.json` unless it also carries a version field — check first, only edit if present.
+
+## Bump modes
+
+Ask the user upfront which mode they want:
+
+### Mode A — Auto increment (default when user says "just bump" / "auto")
+- **Android `versionCode`**: current value + 1.
+- **iOS `CURRENT_PROJECT_VERSION`**: current value + 1. (Android and iOS build numbers are tracked independently; do NOT try to align them.)
+- **Marketing version** (`versionName`, `MARKETING_VERSION`, `package.json` `version`): increment the LAST segment by 1. Example: `2.8.8` → `2.8.9`. This mirrors the team's observed convention. If the user wants a minor bump (`2.8.8` → `2.9.0`) or major bump (`2.8.8` → `3.0.0`), they must use Mode B instead.
+- Both platforms share the same marketing version — read one, verify the others match; if they diverge, surface the divergence to the user before bumping.
+
+### Mode B — Specific version (user provides target)
+Ask for either or both:
+- **Target marketing version** (e.g. `2.9.0`, `3.0.0`) — must be a valid X.Y.Z string.
+- **Target build numbers** — either a single value applied to both platforms, or separate values for Android/iOS.
+
+If the user only gives marketing version, still auto-increment build numbers by +1. If the user only gives build numbers, leave marketing as-is.
+
+## Instructions
+
+1. **Ask which mode** (auto vs. specific). If the user's initial message already answered this, skip.
+2. **Read the current values** from the five locations above. Confirm nothing is diverged unexpectedly (e.g. Android and iOS marketing versions differ). If they diverge, surface it and let the user decide before proceeding.
+3. **Compute the new values** per the mode chosen.
+4. **Show the plan** — a small table of "field: old → new" — and ask for one confirmation before editing. Skip this step only if the user explicitly said "just do it".
+5. **Apply edits** using the `Edit` tool. For the pbxproj file the same field appears twice (Debug + Release) — update BOTH; use `replace_all: true` only when you have verified both occurrences carry the same old value; otherwise do two targeted edits.
+6. **Verify** each edit landed by re-reading the surrounding line, and confirm all five bumps are consistent (marketing version identical across Android/iOS/package.json).
+7. **Report** the final result to the user as a short table. Do NOT commit, do NOT run any build, do NOT push. Leave the working tree dirty for the user to review and commit.
+
+## Guardrails
+
+- Never skip iOS just because "Android is the one failing" (or vice versa). Bumping only one platform silently drifts marketing versions apart — always bump both marketing fields together.
+- Never lower a version. If the user provides a target lower than current, stop and confirm — they may have a reason (e.g. rollback), but it is dangerous by default.
+- Never commit changes; the user reviews and commits.
+- Never edit unrelated version fields (dependency versions in package.json, Gradle plugin versions, Pods versions, etc.).
+- If the pbxproj has more than two occurrences of `CURRENT_PROJECT_VERSION` or `MARKETING_VERSION` (e.g. test target or extensions), ask the user which targets to bump before proceeding — do NOT blindly `replace_all`.
+
+## Common follow-up
+
+After bumping, the user typically wants to commit with a message like `version bumped up to X.Y.Z (android <code>, ios <code>)`. Offer this as a suggestion but do not commit unless asked.

package/collections/qa-skills/README.md

@@ -0,0 +1,103 @@
+# qa-skills — take a Hiver feature from QA to release in one conversation
+
+A collection of QA agents that hand work to each other inside a **single Claude Code chat**. You open
+with one command; the spec, the test plan, the browser run, the bug tickets, the release gate, and
+the automation PR all happen in that same thread.
+
+> **One command to remember: `/qa-kit`.** It gathers your inputs, triages the change, and routes to
+> the right track. Everything else chains automatically.
+
+## Install (via the `@hiver/skills` CLI)
+
+```bash
+npx @hiver/skills add
+# → pick your IDE → pick the "qa-skills" collection → pick "qa-kit"
+```
+
+Picking **`qa-kit`** pulls in the whole suite automatically (it declares the rest as dependencies).
+Then start any QA pass with `/qa-kit`.
+
+Prefer a one-liner?
+
+```bash
+npx @hiver/skills add qa-kit    # installs qa-kit + all its dependencies
+```
+
+## Why one conversation works
+
+Handoffs are **files, not chat messages**. The first agent mints a *run directory* and writes a
+pointer to `qa-output/.current-run`; every agent after that reads it, picks up the shared
+`handoff.json`, does its job, writes its output back, and advances the baton. The chat is the
+conversation; the run directory is the memory — so no agent ever re-asks you what an earlier one
+already knows, and you can hand the thread to a teammate mid-run.
+
+```
+qa-output/<feature>/<run-id>/
+  handoff.json     the baton: who → whom + all context so far
+  tracker.xlsx     source of truth for cases & pass/fail (strict column ownership)
+  steps/  logs/    what each agent produced + a forensic trace of what it did
+  screenshots/     evidence from the browser run
+  trace/report.md  qa-eval's quality verdict, written at the end
+```
+
+## The pipeline
+
+```
+                       you type ► /qa-kit  (orchestrator)
+                                  0 intake → 1 triage → 2 effort + route
+   no spec? ──► hiver-explore ────┤
+               (build a spec)     │
+        UI / mixed ▼              ▼ API / new-API / mixed
+   ┌───────────────────┐   ┌───────────────────┐
+   │ qa-ui-author      │   │ qa-api-author     │
+   │  → qa-ui-run      │   │  → qa-api-run     │
+   │  → qa-bugs        │   │  → qa-bugs        │
+   └─────────┬─────────┘   └───────────────────┘
+             ▼ passing cases
+   ┌───────────────────┐
+   │ playwright-gen    │  specs → run → PR
+   └───────────────────┘
+   qa-eval grades every agent's output at the end → trace/report.md
+```
+
+| Skill | Role | Who calls it |
+|---|---|---|
+| **qa-kit** | Orchestrator / front door — triages (UI · API · new-API · mixed) and routes | **You** (`/qa-kit`) |
+| **hiver-explore** | Builds a Confluence-style spec from help docs + the live UI when there's no PRD | qa-kit, or you |
+| **qa-ui-author** | UI test plan (Word) + Excel tracker — no browser | qa-kit |
+| **qa-ui-run** | Browser first pass — runs the tracker via Claude in Chrome, records ✅/❌/⚠️/⏭️ + screenshots | qa-ui-author |
+| **qa-api-author** | API cases (endpoint, payload, expected) — no live calls | qa-kit |
+| **qa-api-run** | Executes API cases against staging (opt-in, safety-gated) | qa-api-author / flow-capture |
+| **qa-bugs** | Confirmed failures → ClickUp tickets with evidence | qa-ui-run / qa-api-run / you |
+| **playwright-gen** | Passing cases → runnable `.spec.ts`, runs them, opens the automation PR | qa-ui-run, or you |
+| **qa-eval** | Independent judge — grades each agent PASS/DEGRADED/FAIL | auto, at the end |
+
+## Round 1 is Claude's. Round 2 is yours.
+
+The browser first pass clears the repetitive coverage. Two things are handed back to you:
+
+- **⏭️ Skipped cases** — anything needing a typed credential, two accounts at once, a simulated
+  backend failure, or an OAuth handshake. You run these into the tracker's *Testing 2* column (yours alone).
+- **Exploratory testing** — go off-script and find the behaviours no written case predicted.
+
+## The release gate (roadmap)
+
+After manual sign-off, control the LaunchDarkly rollout **in the same chat** — connect the
+LaunchDarkly MCP, or paste the flag JSON and apply the updated enrolment list yourself. This is a
+workflow you run today (bring-your-own MCP), not yet a packaged skill.
+
+## Connectors (all optional — there's always a paste-in fallback)
+
+- **Claude in Chrome** — driving the live, logged-in Hiver tab (required for the browser pass).
+- **ClickUp** — filing bugs · **Atlassian** — pulling the PRD/Confluence spec · **Figma** — UI states the spec misses.
+
+## One prerequisite for the automation step
+
+`playwright-gen` writes and runs real specs inside the **`poc-playwright`** (a.k.a.
+`playwright-hig-automation`) repo, so that repo needs its one-time setup done (`npm install`,
+`npx playwright install chromium`, `npm run auth:all`). Everything before automation runs without it.
+
+---
+
+*A richer, illustrated version of this guide lives in [`qa-suite-guide.html`](./qa-suite-guide.html)
+— open it locally, or host it on GitHub Pages for a shareable link.*