@ngxtm/devkit 3.15.0 → 3.17.0

package/merged-commands/graphql-architect.md

@@ -1,182 +1,97 @@
 ---
 name: graphql-architect
-description: Master modern GraphQL with federation, performance optimization,
-  and enterprise security. Build scalable schemas, implement advanced caching,
-  and design real-time systems. Use PROACTIVELY for GraphQL architecture or
-  performance optimization.
-metadata:
-  model: opus
+description: Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.
+triggers:
+  - GraphQL
+  - Apollo Federation
+  - GraphQL schema
+  - API graph
+  - GraphQL subscriptions
+  - Apollo Server
+  - schema design
+  - GraphQL resolvers
+  - DataLoader
+role: architect
+scope: design
+output-format: schema
 ---
 
-## Use this skill when
+# GraphQL Architect
 
-- Working on graphql architect tasks or workflows
-- Needing guidance, best practices, or checklists for graphql architect
+Senior GraphQL architect specializing in schema design and distributed graph architectures with deep expertise in Apollo Federation 2.5+, GraphQL subscriptions, and performance optimization.
 
-## Do not use this skill when
+## Role Definition
 
-- The task is unrelated to graphql architect
-- You need a different domain or tool outside this scope
+You are a senior GraphQL architect with 10+ years of API design experience. You specialize in Apollo Federation, schema-first design, and building type-safe API graphs that scale across teams and services. You master resolvers, DataLoader patterns, and real-time subscriptions.
 
-## Instructions
+## When to Use This Skill
 
-- Clarify goals, constraints, and required inputs.
-- Apply relevant best practices and validate outcomes.
-- Provide actionable steps and verification.
-- If detailed examples are required, open `resources/implementation-playbook.md`.
+- Designing GraphQL schemas and type systems
+- Implementing Apollo Federation architectures
+- Building resolvers with DataLoader optimization
+- Creating real-time GraphQL subscriptions
+- Optimizing query complexity and performance
+- Setting up authentication and authorization
 
-You are an expert GraphQL architect specializing in enterprise-scale schema design, federation, performance optimization, and modern GraphQL development patterns.
+## Core Workflow
 
-## Purpose
+1. **Domain Modeling** - Map business domains to GraphQL type system
+2. **Design Schema** - Create types, interfaces, unions with federation directives
+3. **Implement Resolvers** - Write efficient resolvers with DataLoader patterns
+4. **Secure** - Add query complexity limits, depth limiting, field-level auth
+5. **Optimize** - Performance tune with caching, persisted queries, monitoring
 
-Expert GraphQL architect focused on building scalable, performant, and secure GraphQL systems for enterprise applications. Masters modern federation patterns, advanced optimization techniques, and cutting-edge GraphQL tooling to deliver high-performance APIs that scale with business needs.
-
-## Capabilities
+## Reference Guide
 
-### Modern GraphQL Federation and Architecture
+Load detailed guidance based on context:
 
-- Apollo Federation v2 and Subgraph design patterns
-- GraphQL Fusion and composite schema implementations
-- Schema composition and gateway configuration
-- Cross-team collaboration and schema evolution strategies
-- Distributed GraphQL architecture patterns
-- Microservices integration with GraphQL federation
-- Schema registry and governance implementation
-
-### Advanced Schema Design and Modeling
-
-- Schema-first development with SDL and code generation
-- Interface and union type design for flexible APIs
-- Abstract types and polymorphic query patterns
-- Relay specification compliance and connection patterns
-- Schema versioning and evolution strategies
-- Input validation and custom scalar types
-- Schema documentation and annotation best practices
-
-### Performance Optimization and Caching
-
-- DataLoader pattern implementation for N+1 problem resolution
-- Advanced caching strategies with Redis and CDN integration
-- Query complexity analysis and depth limiting
-- Automatic persisted queries (APQ) implementation
-- Response caching at field and query levels
-- Batch processing and request deduplication
-- Performance monitoring and query analytics
-
-### Security and Authorization
-
-- Field-level authorization and access control
-- JWT integration and token validation
-- Role-based access control (RBAC) implementation
-- Rate limiting and query cost analysis
-- Introspection security and production hardening
-- Input sanitization and injection prevention
-- CORS configuration and security headers
-
-### Real-Time Features and Subscriptions
-
-- GraphQL subscriptions with WebSocket and Server-Sent Events
-- Real-time data synchronization and live queries
-- Event-driven architecture integration
-- Subscription filtering and authorization
-- Scalable subscription infrastructure design
-- Live query implementation and optimization
-- Real-time analytics and monitoring
-
-### Developer Experience and Tooling
-
-- GraphQL Playground and GraphiQL customization
-- Code generation and type-safe client development
-- Schema linting and validation automation
-- Development server setup and hot reloading
-- Testing strategies for GraphQL APIs
-- Documentation generation and interactive exploration
-- IDE integration and developer tooling
-
-### Enterprise Integration Patterns
-
-- REST API to GraphQL migration strategies
-- Database integration with efficient query patterns
-- Microservices orchestration through GraphQL
-- Legacy system integration and data transformation
-- Event sourcing and CQRS pattern implementation
-- API gateway integration and hybrid approaches
-- Third-party service integration and aggregation
-
-### Modern GraphQL Tools and Frameworks
-
-- Apollo Server, Apollo Federation, and Apollo Studio
-- GraphQL Yoga, Pothos, and Nexus schema builders
-- Prisma and TypeGraphQL integration
-- Hasura and PostGraphile for database-first approaches
-- GraphQL Code Generator and schema tooling
-- Relay Modern and Apollo Client optimization
-- GraphQL mesh for API aggregation
-
-### Query Optimization and Analysis
-
-- Query parsing and validation optimization
-- Execution plan analysis and resolver tracing
-- Automatic query optimization and field selection
-- Query whitelisting and persisted query strategies
-- Schema usage analytics and field deprecation
-- Performance profiling and bottleneck identification
-- Caching invalidation and dependency tracking
-
-### Testing and Quality Assurance
-
-- Unit testing for resolvers and schema validation
-- Integration testing with test client frameworks
-- Schema testing and breaking change detection
-- Load testing and performance benchmarking
-- Security testing and vulnerability assessment
-- Contract testing between services
-- Mutation testing for resolver logic
-
-## Behavioral Traits
-
-- Designs schemas with long-term evolution in mind
-- Prioritizes developer experience and type safety
-- Implements robust error handling and meaningful error messages
-- Focuses on performance and scalability from the start
-- Follows GraphQL best practices and specification compliance
-- Considers caching implications in schema design decisions
-- Implements comprehensive monitoring and observability
-- Balances flexibility with performance constraints
-- Advocates for schema governance and consistency
-- Stays current with GraphQL ecosystem developments
-
-## Knowledge Base
-
-- GraphQL specification and best practices
-- Modern federation patterns and tools
-- Performance optimization techniques and caching strategies
-- Security considerations and enterprise requirements
-- Real-time systems and subscription architectures
-- Database integration patterns and optimization
-- Testing methodologies and quality assurance practices
-- Developer tooling and ecosystem landscape
-- Microservices architecture and API design patterns
-- Cloud deployment and scaling strategies
-
-## Response Approach
-
-1. **Analyze business requirements** and data relationships
-2. **Design scalable schema** with appropriate type system
-3. **Implement efficient resolvers** with performance optimization
-4. **Configure caching and security** for production readiness
-5. **Set up monitoring and analytics** for operational insights
-6. **Design federation strategy** for distributed teams
-7. **Implement testing and validation** for quality assurance
-8. **Plan for evolution** and backward compatibility
-
-## Example Interactions
-
-- "Design a federated GraphQL architecture for a multi-team e-commerce platform"
-- "Optimize this GraphQL schema to eliminate N+1 queries and improve performance"
-- "Implement real-time subscriptions for a collaborative application with proper authorization"
-- "Create a migration strategy from REST to GraphQL with backward compatibility"
-- "Build a GraphQL gateway that aggregates data from multiple microservices"
-- "Design field-level caching strategy for a high-traffic GraphQL API"
-- "Implement query complexity analysis and rate limiting for production safety"
-- "Create a schema evolution strategy that supports multiple client versions"
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Schema Design | `references/schema-design.md` | Types, interfaces, unions, enums, input types |
+| Resolvers | `references/resolvers.md` | Resolver patterns, context, DataLoader, N+1 |
+| Federation | `references/federation.md` | Apollo Federation, subgraphs, entities, directives |
+| Subscriptions | `references/subscriptions.md` | Real-time updates, WebSocket, pub/sub patterns |
+| Security | `references/security.md` | Query depth, complexity analysis, authentication |
+| REST Migration | `references/migration-from-rest.md` | Migrating REST APIs to GraphQL |
+
+## Constraints
+
+### MUST DO
+- Use schema-first design approach
+- Implement proper nullable field patterns
+- Use DataLoader for batching and caching
+- Add query complexity analysis
+- Document all types and fields
+- Follow GraphQL naming conventions (camelCase)
+- Use federation directives correctly
+- Provide example queries for all operations
+
+### MUST NOT DO
+- Create N+1 query problems
+- Skip query depth limiting
+- Expose internal implementation details
+- Use REST patterns in GraphQL
+- Return null for non-nullable fields
+- Skip error handling in resolvers
+- Hardcode authorization logic
+- Ignore schema validation
+
+## Output Templates
+
+When implementing GraphQL features, provide:
+1. Schema definition (SDL with types and directives)
+2. Resolver implementation (with DataLoader patterns)
+3. Query/mutation/subscription examples
+4. Brief explanation of design decisions
+
+## Knowledge Reference
+
+Apollo Server, Apollo Federation 2.5+, GraphQL SDL, DataLoader, GraphQL Subscriptions, WebSocket, Redis pub/sub, schema composition, query complexity, persisted queries, schema stitching, type generation
+
+## Related Skills
+
+- **Backend Developer** - Resolver implementation and data access
+- **API Designer** - REST-to-GraphQL migration strategies
+- **Microservices Architect** - Service boundary definition
+- **Frontend Developer** - Client query optimization
+- **Database Optimizer** - Query efficiency and N+1 prevention

package/merged-commands/graphql.md

@@ -1,7 +1,8 @@
 ---
 name: graphql
-description: "GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper controls, clients can craft queries that bring down your server.  This skill covers schema design, resolvers, DataLoader for N+1 prevention, federation for microservices, and client integration with Apollo/urql. Key insight: GraphQL is a contract. The schema is the API documentation. Design it carefully."
+description: "GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper co..."
 source: vibeship-spawner-skills (Apache 2.0)
+risk: unknown
 ---
 
 # GraphQL
@@ -66,3 +67,6 @@ Normalized cache with type policies
 ## Related Skills
 
 Works well with: `backend`, `postgres-wizard`, `nextjs-app-router`, `react-patterns`
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/haskell-pro.md

@@ -5,6 +5,8 @@ description: Expert Haskell engineer specializing in advanced type systems, pure
   type-level programming, concurrency, and architecture guidance.
 metadata:
   model: sonnet
+risk: unknown
+source: community
 ---
 
 ## Use this skill when

package/merged-commands/helm-chart-scaffolding.md

@@ -1,6 +1,8 @@
 ---
 name: helm-chart-scaffolding
-description: Design, organize, and manage Helm charts for templating and packaging Kubernetes applications with reusable configurations. Use when creating Helm charts, packaging Kubernetes applications, or implementing templated deployments.
+description: "Design, organize, and manage Helm charts for templating and packaging Kubernetes applications with reusable configurations. Use when creating Helm charts, packaging Kubernetes applications, or impl..."
+risk: unknown
+source: community
 ---
 
 # Helm Chart Scaffolding

package/merged-commands/helpdesk-automation.md

@@ -0,0 +1,171 @@
+---
+name: helpdesk-automation
+description: "Automate HelpDesk tasks via Rube MCP (Composio): list tickets, manage views, use canned responses, and configure custom fields. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# HelpDesk Automation via Rube MCP
+
+Automate HelpDesk ticketing operations through Composio's HelpDesk toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active HelpDesk connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `helpdesk`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `helpdesk`
+3. If connection is not ACTIVE, follow the returned auth link to complete HelpDesk authentication
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. List and Browse Tickets
+
+**When to use**: User wants to retrieve, browse, or paginate through support tickets
+
+**Tool sequence**:
+1. `HELPDESK_LIST_TICKETS` - List tickets with sorting and pagination [Required]
+
+**Key parameters**:
+- `silo`: Ticket folder - 'tickets', 'archive', 'trash', or 'spam' (default: 'tickets')
+- `sortBy`: Sort field - 'createdAt', 'updatedAt', or 'lastMessageAt' (default: 'createdAt')
+- `order`: Sort direction - 'asc' or 'desc' (default: 'desc')
+- `pageSize`: Results per page, 1-100 (default: 20)
+- `next.value`: Timestamp cursor for forward pagination
+- `next.ID`: ID cursor for forward pagination
+- `prev.value`: Timestamp cursor for backward pagination
+- `prev.ID`: ID cursor for backward pagination
+
+**Pitfalls**:
+- Pagination uses cursor-based approach with timestamp + ID pairs
+- Forward pagination requires both `next.value` and `next.ID` from previous response
+- Backward pagination requires both `prev.value` and `prev.ID`
+- `silo` determines which folder to list from; default is active tickets
+- `pageSize` max is 100; default is 20
+- Archived and trashed tickets are in separate silos
+
+### 2. Manage Ticket Views
+
+**When to use**: User wants to see saved agent views for organizing tickets
+
+**Tool sequence**:
+1. `HELPDESK_LIST_VIEWS` - List all agent views [Required]
+
+**Key parameters**: (none required)
+
+**Pitfalls**:
+- Views are predefined saved filters configured by agents in the HelpDesk UI
+- View definitions include filter criteria that can be used to understand ticket organization
+- Views cannot be created or modified via API; they are managed in the HelpDesk UI
+
+### 3. Use Canned Responses
+
+**When to use**: User wants to list available canned (template) responses for tickets
+
+**Tool sequence**:
+1. `HELPDESK_LIST_CANNED_RESPONSES` - Retrieve all predefined reply templates [Required]
+
+**Key parameters**: (none required)
+
+**Pitfalls**:
+- Canned responses are predefined templates for common replies
+- They may include placeholder variables that need to be filled in
+- Canned responses are managed through the HelpDesk UI
+- Response content may include HTML formatting
+
+### 4. Inspect Custom Fields
+
+**When to use**: User wants to view custom field definitions for the account
+
+**Tool sequence**:
+1. `HELPDESK_LIST_CUSTOM_FIELDS` - List all custom field definitions [Required]
+
+**Key parameters**: (none required)
+
+**Pitfalls**:
+- Custom fields extend the default ticket schema with organization-specific data
+- Field definitions include field type, name, and validation rules
+- Custom fields are configured in the HelpDesk admin panel
+- Field values appear on tickets when the field has been populated
+
+## Common Patterns
+
+### Ticket Browsing Pattern
+
+```
+1. Call HELPDESK_LIST_TICKETS with desired silo and sortBy
+2. Process the returned page of tickets
+3. Extract next.value and next.ID from the response
+4. Call HELPDESK_LIST_TICKETS with those cursor values for next page
+5. Continue until no more cursor values are returned
+```
+
+### Ticket Folder Navigation
+
+```
+Active tickets:  silo='tickets'
+Archived:        silo='archive'
+Trashed:         silo='trash'
+Spam:            silo='spam'
+```
+
+### Cursor-Based Pagination
+
+```
+Forward pagination:
+  - Use next.value (timestamp) and next.ID from response
+  - Pass as next.value and next.ID parameters in next call
+
+Backward pagination:
+  - Use prev.value (timestamp) and prev.ID from response
+  - Pass as prev.value and prev.ID parameters in next call
+```
+
+## Known Pitfalls
+
+**Cursor Pagination**:
+- Both timestamp and ID are required for cursor navigation
+- Cursor values are timestamps in ISO 8601 date-time format
+- Mixing forward and backward cursors in the same request is undefined behavior
+
+**Silo Filtering**:
+- Tickets are physically separated into silos (folders)
+- Moving tickets between silos is done in the HelpDesk UI
+- Each silo query is independent; there is no cross-silo search
+
+**Read-Only Operations**:
+- Current Composio toolkit provides list/read operations
+- Ticket creation, update, and reply operations may require additional tools
+- Check RUBE_SEARCH_TOOLS for any newly available tools
+
+**Rate Limits**:
+- HelpDesk API has per-account rate limits
+- Implement backoff on 429 responses
+- Keep page sizes reasonable to avoid timeouts
+
+**Response Parsing**:
+- Response data may be nested under `data` or `data.data`
+- Parse defensively with fallback patterns
+- Ticket IDs are strings
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List tickets | HELPDESK_LIST_TICKETS | silo, sortBy, order, pageSize |
+| List views | HELPDESK_LIST_VIEWS | (none) |
+| List canned responses | HELPDESK_LIST_CANNED_RESPONSES | (none) |
+| List custom fields | HELPDESK_LIST_CUSTOM_FIELDS | (none) |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-components-content.md

@@ -0,0 +1,91 @@
+---
+name: hig-components-content
+version: 1.0.0
+description: ">"
+  Apple Human Interface Guidelines for content display components. Use this skill when the user asks about
+  "charts component", "collection view", "image view", "web view", "color well", "image well",
+  "activity view", "lockup", "data visualization", "content display", displaying images, rendering
+  web content, color pickers, or presenting collections of items in Apple apps.
+  Also use when the user says "how should I display charts", "what's the best way to show images",
+  "should I use a web view", "how do I build a grid of items", "what component shows media",
+  or "how do I present a share sheet".
+  Cross-references: hig-foundations for color/typography/accessibility, hig-patterns for data
+  visualization patterns, hig-components-layout for structural containers, hig-platforms for
+  platform-specific component behavior.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Content Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Adapt to different sizes and contexts.** Content components must work across screen sizes, orientations, and multitasking configurations. Use Auto Layout and size classes.
+
+2. **Make content accessible.** Charts need audio graph support. Images need alt text. Collections need proper VoiceOver navigation order. All content components need labels and descriptions.
+
+3. **Maintain visual hierarchy.** Use spacing, sizing, and grouping to establish clear information hierarchy. Primary content should be visually prominent.
+
+4. **Use system components first.** Evaluate UICollectionView, SwiftUI Charts, WKWebView before building custom. System components come with built-in accessibility and platform adaptation.
+
+5. **Respect platform conventions.** A collection on tvOS uses large lockups with parallax. The same collection on iOS uses compact cells with touch targets. On visionOS, content gains depth and hover effects.
+
+6. **Handle empty states.** Show a meaningful empty state with guidance on how to populate it, not a blank screen.
+
+7. **Optimize for performance.** Use lazy loading, cell reuse, pagination, and prefetching for large datasets.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [charts.md](references/charts.md) | Charts | Swift Charts, bar/line/area/point marks, chart accessibility, audio graphs |
+| [collections.md](references/collections.md) | Collections | Grid/list layouts, compositional layout, selection, reordering, diffable data sources |
+| [image-views.md](references/image-views.md) | Image Views | Aspect ratio handling, content modes, SF Symbol images, accessibility |
+| [image-wells.md](references/image-wells.md) | Image Wells | Drag-and-drop image selection, macOS-specific, placeholder content |
+| [color-wells.md](references/color-wells.md) | Color Wells | Color selection UI, system color picker, custom color spaces |
+| [web-views.md](references/web-views.md) | Web Views | WKWebView, SFSafariViewController, navigation controls, content restrictions |
+| [activity-views.md](references/activity-views.md) | Activity Views | Share sheets, activity items, custom activities, action extensions |
+| [lockups.md](references/lockups.md) | Lockups | Image+text elements, tvOS card layouts, focus effects, shelf layouts |
+
+## Component Selection Guide
+
+| Content Need | Recommended Component | Platform Notes |
+|---|---|---|
+| Visualizing quantitative data | Charts (Swift Charts) | iOS 16+, macOS 13+, watchOS 9+ |
+| Browsing a grid or list of items | Collection View | Compositional layout for complex arrangements |
+| Displaying a single image | Image View | Support aspect ratio fitting; provide accessibility description |
+| Selecting an image via drag or browse | Image Well | macOS primarily; use image pickers on iOS |
+| Selecting a color | Color Well | Triggers system color picker; macOS, iOS 14+ |
+| Showing web content inline | Web View (WKWebView) | Use SFSafariViewController for external browsing |
+| Sharing content to other apps | Activity View | System share sheet with configurable activity types |
+| Content card (image + text) | Lockup | Primarily tvOS; adaptable to other platforms |
+
+## Output Format
+
+1. **Component recommendation with rationale**, referencing the relevant HIG reference file.
+2. **Configuration guidance** -- key properties and setup.
+3. **Accessibility requirements** for the recommended component.
+4. **Platform-specific notes** for targeted platforms.
+
+## Questions to Ask
+
+1. What type of content? (Quantitative data, images, web content, browsable collection, share action?)
+2. Which platforms?
+3. Static or dynamic content?
+4. How much content? (Few items vs hundreds/thousands affects component choice and optimization.)
+
+## Related Skills
+
+- **hig-foundations** -- Color, typography, accessibility, and image guidelines
+- **hig-patterns** -- Data visualization, sharing, and loading patterns
+- **hig-components-layout** -- Structural containers (scroll views, lists, split views) hosting content
+- **hig-platforms** -- Platform-specific component behavior (lockups on tvOS, web views on macOS)
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-components-controls.md

@@ -0,0 +1,93 @@
+---
+name: hig-components-controls
+version: 1.0.0
+description: ">-"
+  Apple HIG guidance for selection and input controls including pickers, toggles,
+  sliders, steppers, segmented controls, combo boxes, text fields, text views,
+  labels, token fields, virtual keyboards, rating indicators, and gauges. Use
+  this skill when the user says "picker or segmented control," "how should my
+  form look," "what keyboard type should I use," "toggle vs checkbox," or asks
+  about picker design, toggle, switch, slider, stepper, text field, text input,
+  segmented control, combo box, label, token field, virtual keyboard, rating
+  indicator, gauge, form design, input validation, or control state management.
+  Cross-references: hig-components-menus, hig-components-dialogs,
+  hig-components-search.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Selection and Input Controls
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Clear current state.** Users must always see what is selected. Toggles show on/off, segmented controls highlight the active segment, pickers display the current selection.
+
+2. **Prefer standard system controls.** Built-in controls provide consistency and accessibility. Custom controls introduce a learning curve and may break assistive features.
+
+3. **Toggles for binary states.** On or off. In Settings-style screens, changes take effect immediately. In modal forms, changes commit on confirmation.
+
+4. **Segmented controls for mutually exclusive options.** 2-5 items, roughly equal importance, short labels.
+
+5. **Sliders for continuous values.** When precise numeric input is not critical. Provide min/max labels or icons for range endpoints.
+
+6. **Pickers for long option lists.** Too many options for a segmented control. Works well for dates, times, structured data.
+
+7. **Steppers for small, precise adjustments.** Increment/decrement in fixed steps. Display current value next to the stepper with reasonable min/max bounds.
+
+8. **Text fields for short, single-line input.** Text views for multi-line. Configure keyboard type to match expected input (email, URL, number).
+
+9. **Combo boxes: text input + selection list.** macOS. Type a value or choose from a predefined list when custom values are valid.
+
+10. **Token fields: discrete values as visual tokens.** macOS. For email recipients, tags, or collections of discrete items.
+
+11. **Gauges and rating indicators display values.** Gauges show a value within a range. Rating indicators show ratings (often stars). Display-only; use interactive variants for input.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [controls.md](references/controls.md) | General controls | States, affordance, system controls |
+| [toggles.md](references/toggles.md) | Toggles | On/off, immediate effect |
+| [segmented-controls.md](references/segmented-controls.md) | Segmented controls | 2-5 options, equal weight |
+| [sliders.md](references/sliders.md) | Sliders | Continuous range, min/max labels |
+| [steppers.md](references/steppers.md) | Steppers | Fixed steps, bounded values |
+| [pickers.md](references/pickers.md) | Pickers | Dates, times, long option sets |
+| [combo-boxes.md](references/combo-boxes.md) | Combo boxes | macOS, type or select, custom values |
+| [text-fields.md](references/text-fields.md) | Text fields | Short input, keyboard types, validation |
+| [text-views.md](references/text-views.md) | Text views | Multi-line, comments, descriptions |
+| [labels.md](references/labels.md) | Labels | Placement, VoiceOver support |
+| [token-fields.md](references/token-fields.md) | Token fields | macOS, chips, tags, recipients |
+| [virtual-keyboards.md](references/virtual-keyboards.md) | Virtual keyboards | Email, URL, number keyboard types |
+| [rating-indicators.md](references/rating-indicators.md) | Rating indicators | Star ratings, display-only |
+| [gauges.md](references/gauges.md) | Gauges | Level indicators, range display |
+
+## Output Format
+
+1. **Control recommendation with rationale** and why alternatives are less suitable.
+2. **State management** -- how the control communicates current state and whether changes apply immediately or on confirmation.
+3. **Validation approach** -- when to show errors and how to communicate rules.
+4. **Accessibility** -- labels, traits, hints for VoiceOver.
+
+## Questions to Ask
+
+1. What type of data? (Boolean, choice from fixed set, numeric, free-form text?)
+2. How many options?
+3. Which platforms? (Combo boxes and token fields are macOS-only)
+4. Settings screen or inline form?
+
+## Related Skills
+
+- **hig-components-menus** -- Buttons and pop-up buttons complementing selection controls
+- **hig-components-dialogs** -- Sheets and popovers containing forms
+- **hig-components-search** -- Search fields sharing text input patterns
+- **hig-inputs** -- Keyboard, pointer, gesture interactions with controls
+- **hig-foundations** -- Typography, color, layout for control styling
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.