@claude-collective/cli 0.21.0 → 0.25.1

package/CHANGELOG.md

@@ -5,6 +5,180 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.25.1] - 2026-02-13
+
+### Changed
+
+- **Code formatting** — Prettier applied across 21 files (wizard components, tests, schemas, docs).
+
+## [0.25.0] - 2026-02-12
+
+### Added
+
+- **Multi-source skill selection** — New Sources step between Build and Confirm lets users choose between recommended (public) and custom skill sources per technology. Source grid displays variant cards for each available source with installed indicators. Customize view shows per-skill source options.
+- **Source settings management** — `G` hotkey opens settings panel to add/remove extra skill sources with URL validation. Sources persist to `.claude-src/config.yaml`.
+- **Source switching in `cc edit`** — Edit command detects source changes and applies archive/restore for Local↔Public transitions via `source-switcher.ts`. Shows `~ skillId (From → To)` for source switches.
+- **Bound skill search** — Search pill in source grid triggers immediate search across configured extra marketplaces on Space. Results appear in modal overlay with keyboard navigation. Selected results become bound skills persisted in config.
+- **BoundSkill types and schema** — `BoundSkill`, `BoundSkillCandidate`, `SkillAlias` types with Zod `boundSkillSchema` for config persistence. `boundSkills` field added to `ProjectSourceConfig`.
+- **Multi-source loader** — `tagExtraSources` enriches resolved skills with available sources from configured marketplaces. `searchExtraSources` queries all extra sources for skills matching a subcategory alias.
+- **Installed skill indicators** — Dimmed `✓` prefix on skill tags for already-installed technologies.
+- **Scroll viewport spec** — UX spec for wizard grid navigation with viewport-based scrolling.
+
+### Fixed
+
+- **Uninstall plugin removal resilient** — `claudePluginUninstall` wrapped in inner try-catch so directory removal proceeds even if Claude CLI plugin unregister fails.
+- **Config skills array restored** — Fixed skill-to-agent compilation when `skills` array was missing from project config.
+
+### Changed
+
+- **SkillId format tightened** — `${SkillIdPrefix}-${string}-${string}` now enforces 3+ segments.
+- **Architecture docs updated** for multi-source features.
+
+## [0.24.7] - 2026-02-12
+
+### Added
+
+- **Sources step in wizard flow** — New step between Build and Confirm lets users choose between recommended skills (verified by Claude Collective) or customizing skill sources per technology. Wizard tabs updated to 5 steps.
+- **Edit command starts at Build step** — `cc edit` now skips Intro/Stack and opens directly at the Build step with currently installed skills pre-populated via new `populateFromSkillIds` store action.
+
+### Changed
+
+- **Parse boundary error handling hardened across 11 files** — All `verbose()` calls for malformed user-facing data (project config, local skills, default mappings, skill metadata) promoted to `warn()` so errors are visible without `--verbose`. Bare `JSON.parse` in skill import wrapped in try/catch. Empty `catch {}` in permission checker now warns on malformed `settings.json`. Manual frontmatter parsing in `compile.ts` replaced with `parseFrontmatter()` utility. Missing `name` field in project config now falls back to directory name with a warning.
+- **Marketplace list JSON parsing hardened** — `claudePluginMarketplaceList` now validates JSON parse and array type before returning.
+
+### Refactored
+
+- **Replaced pseudo-agents pattern with `populateFromSkillIds`** — Stack selection no longer constructs fake agent objects to feed into `populateFromStack`. New `populateFromSkillIds` store action maps skill IDs directly to domain/subcategory selections with warnings for missing or unresolvable skills.
+
+## [0.24.6] - 2026-02-12
+
+### Changed
+
+- **Codebase-wide comment cleanup** — Removed AI-generated banner separators (`// ====...`), obvious JSDoc that restated function/variable names, file-level header comments, and verbose multi-line blocks across 150+ files (~5,600 lines removed). Comments explaining WHY, boundary casts, edge cases, and TODOs preserved.
+- **Standardized JSDoc on all type definitions** — All exported types in `src/cli/types/` now use consistent `/** */` JSDoc format. Union grouping comments kept as `//`. Obvious property comments removed, meaningful annotations (`@default`, deprecation, logic notes) preserved.
+- **Unused imports cleaned up** — Removed unused `beforeEach` in `plugin-finder.test.ts` and unused `readdir` in `agent-recompiler.test.ts`.
+
+## [0.24.5] - 2026-02-11
+
+### Added
+
+- **Command tests for all 12 previously untested CLI commands** — ~158 new tests across 9 test files covering config:set-project, config:unset-project, version (index), version:set, version:bump, new:skill, new:agent, import:skill, update, uninstall, init, and edit. Total test count: 1512 passing (up from ~1344).
+- **Vitest auto-mocks for fs and logger** — Manual mock files (`src/cli/utils/__mocks__/fs.ts`, `logger.ts`) replace inline `vi.mock()` factory functions across 15 existing test files. `clearMocks: true` enabled globally.
+- **Vitest test projects** — Config split into 3 projects (`unit`, `integration`, `commands`) for clearer test organization and selective running.
+
+### Changed
+
+- **`docs/architecture.md` expanded** to comprehensive reference covering project structure, data flow, domain organization, type system, Zod validation, CLI commands, wizard components, test infrastructure, utility patterns, and conventions.
+- **`docs/index.md` updated** with bibles section and UX research section.
+
+### Removed
+
+- **21 outdated documentation files removed** — Completed migration plans (Commander.js→oclif), implemented feature plans (skill-id normalization, Phase 7 wizard redesign, init refactor), superseded research (integration testing, oclif ecosystem evaluation, CLI improvements), and resolved UX research. `cli-command-testing-plan.md` also removed (all tests implemented). Bibles and active UX research retained.
+
+## [0.24.4] - 2026-02-11
+
+### Changed
+
+- **`lib/` restructured into domain subdirectories** — 62 files moved from flat `lib/` into 8 domain-organized subdirectories: `configuration/`, `loading/`, `matrix/`, `plugins/`, `skills/`, `agents/`, `stacks/`, `installation/`. Each domain has a barrel `index.ts` for clean imports. Cross-cutting files (`compiler`, `resolver`, `schemas`, etc.) remain at `lib/` root. ~140 import paths updated across commands, components, hooks, and tests.
+
+## [0.24.3] - 2026-02-11
+
+### Changed
+
+- **AJV replaced with Zod for all schema validation** — `schema-validator.ts` and `plugin-validator.ts` rewritten to use Zod `.safeParse()`. AJV and ajv-formats dependencies removed (23 packages pruned). Strict validation schemas added for `cc validate`: `metadataValidationSchema`, `stackConfigValidationSchema`, `skillFrontmatterValidationSchema`, `agentFrontmatterValidationSchema`.
+- **JSON Schema files now generated from Zod** — `scripts/generate-json-schemas.ts` uses `z.toJSONSchema()` (Zod v4 native) to generate 10 schema files from Zod source of truth. Hand-maintained JSON schemas and symlinks to claude-subagents removed. New npm scripts: `generate:schemas`, `generate:schemas:check`.
+- **YAML `$schema` references use local relative paths** — All 18 `agent.yaml` files switched from remote `raw.githubusercontent.com` URLs to `# yaml-language-server: $schema=` comments with relative paths. Schema reference added to `config/skills-matrix.yaml`. VS Code YAML validation now works offline.
+
+## [0.24.2] - 2026-02-11
+
+### Changed
+
+- **Type definitions co-located into `src/cli/types/`** — 4 scattered type files (`src/types.ts`, `src/cli/types.ts`, `src/cli/types-matrix.ts`, `src/cli/types-stacks.ts`) consolidated into 6 domain-organized files + barrel index under `src/cli/types/`. All 60+ consumer imports updated. Unused imports cleaned up.
+
+## [0.24.1] - 2026-02-11
+
+### Fixed
+
+- **Stack config now respects user customizations** — `buildLocalConfig` generates stack config from the user's actual skill selections instead of hardcoding the original stack definition. Customizations like swapping `commander` for `oclif` are now preserved.
+- **Subcategory key `cli` corrected to `cli-framework`** in `stacks.yaml` to match the `CategoryPath` format used in production metadata files.
+- **Parse boundaries hardened** — All YAML/JSON parse boundaries now warn or throw with context on failure: `parseFrontmatter` includes file path in warnings, `loadAllAgents`/`loadProjectAgents` catch and warn on invalid `agent.yaml`, `config-saver` uses Zod validation, `versioning` wraps `parseYaml` in try/catch, `matrix-loader` warns on invalid skill alias mappings.
+
+### Changed
+
+- **Test structure reorganized** — Component tests co-located with source files. Integration tests grouped in `lib/__tests__/integration/`. Compilation pipeline tests rewritten to use `createTestSource()` instead of external repo dependency.
+- **Shared test factories added** — `createMockCategory()`, `createMockResolvedStack()`, `createComprehensiveMatrix()`, `createBasicMatrix()` in `helpers.ts` reduce ~300 lines of duplicate fixture code.
+- **17 previously untested lib files now have unit tests** — compiler, matrix-loader, stacks-loader, defaults-loader, config-saver, skill-plugin-compiler, plugin-info, plugin-finder, plugin-version, output-validator, schema-validator, installation, skill-fetcher, agent-fetcher, skill-metadata, matrix-health-check, stack-installer.
+- **Error path and user journey test coverage expanded** — 12 error path tests for loader functions, 8 edit-recompile journey tests, 17 install-compile journey tests.
+
+## [0.24.0] - 2026-02-11
+
+### Changed
+
+- **Type system rewrite** — All `interface` declarations replaced with `type` aliases. `Skill` now extends `SkillDefinition` via intersection. Agent types composed from `BaseAgentFields` shared base. Inline `//` comments converted to JSDoc on type fields.
+- **`SkillAlias` renamed to `SkillDisplayName`** — `ResolvedSkill.alias` → `displayName`, `CategoryDefinition.name` → `displayName`. `SkillRef` union eliminated — all post-resolution sites use `SkillId` directly.
+- **`stack` is the single source of truth for skill assignment** — `skills` flat list, `agent_skills` per-agent overrides, and `preload_patterns` removed from `ProjectConfig`. When no predefined stack is selected, a stack is auto-generated from wizard selections.
+- **Config always uses `SkillAssignment` objects** — `SkillEntry` union (`string | SkillAssignment`) eliminated. Config YAML `skills` entries are always `{ id }` objects.
+- **`ProjectConfig.agents` narrowed** from `string[]` to `AgentName[]`. `getAgentsForSkill()` return type narrowed to `AgentName[]`.
+- **Remaining `Object.entries`/`Object.keys` replaced** with `typedEntries`/`typedKeys` across all files. `Record<string, X>` narrowed to `Record<SkillId|AgentName|Subcategory, X>` where keys are known.
+- **`loadProjectConfig` renamed** to `loadProjectSourceConfig` in `config.ts` to disambiguate from `project-config.ts` version.
+- **Format functions consolidated** — `formatSourceOrigin`/`formatAgentsSourceOrigin` merged into `formatOrigin(type, origin)`.
+- **`KEY_SUBCATEGORIES` deduplicated** — moved from `resolver.ts` and `stacks-loader.ts` into `consts.ts`.
+
+### Removed
+
+- **`name` field** from `SkillDefinition`, `Skill`, `ResolvedSkill`, `SkillOption` — `displayName` (formerly alias) replaces it. `extractDisplayName()` removed from `loader.ts`.
+- **`custom_agents` infrastructure** — `custom-agent-resolver.ts` deleted entirely. `CustomAgentConfig` type, validation, resolution, and compilation code paths removed.
+- **`agent_skills` config mechanism** — redundant with `stack`. All read/write/validation paths removed.
+- **`preload_patterns` config field** — redundant with `SkillAssignment.preloaded`.
+- **Dead `ProjectConfig` fields** — `philosophy`, `principles`, `tags`, `framework`, `hooks`.
+- **Dead `SkillFrontmatter` fields** — `agent`, `argument-hint`, `context`, `disable-model-invocation`, `user-invocable`, `allowed-tools`.
+- **Dead `PluginManifest` fields** — `homepage`, `license`, `repository`, `mcpServers`.
+- **`ResolvedSkill.recommendedBy` and `requiredBy`** — unused inverse relationship fields.
+- **`MarketplaceFetchResult.cacheKey`** — set but never read.
+- **`CompileConfig.claude_md`** — always empty string.
+- **`CompileMode` type and `getDirs()` function** — single-value enum.
+- **`LoadedProjectConfig.isLegacy`** — always `false`.
+- **`AgentYamlConfig.skills`** — parsed but never read.
+- **Dead `skill-agent-mappings.ts` code** — ~170 lines of hardcoded fallbacks, `shouldPreloadSkill`, `extractCategoryKey`, `hasAgentSkillsOverride`, `isSkillAssignedToAgent`, `normalizeAgentSkills`, `resolveAgentsForSkill`.
+- **Dead `resolver.ts` functions** — `resolveStackSkills`, `getStackSkillIds`, `flattenAgentSkills`, `expandSkillIdIfDirectory`, `normalizeSkillEntry`, unused interfaces.
+- **Unused `compileAllAgents()` `_config` parameter**.
+- **Dead wizard store actions/state** — `setDomainSelection`, `setSkillSource`, `setCurrentRefineIndex`, `setCurrentDomainIndex`, `toggleShowDescriptions`, `setFocus`, `currentRefineIndex`, `skillSources`.
+- **Dead wizard component code** — `shouldShowSubcategory()` (always true), unused props, redundant computations.
+- **~2,100 lines of redundant test code** for deleted features.
+
+## [0.23.0] - 2026-02-10
+
+### Added
+
+- **Zod runtime validation at all parse boundaries** — 30+ schemas in `schemas.ts` using bridge pattern (`z.ZodType<ExistingType>`) validate every `JSON.parse` and `parseYaml` call in production code. Eliminates all production `as T` casts at deserialization boundaries. Lenient loader schemas use `.passthrough()` at parse boundaries; strict schemas for validation.
+- **Typed object utilities** — `typedEntries<K,V>()` and `typedKeys<K>()` in `typed-object.ts` replace all `Object.entries/keys` boundary casts with type-safe helpers.
+- **Named type aliases** — `SkillRef`, `SubcategorySelections`, `DomainSelections`, `CategoryMap`, `ResolvedSubcategorySkills` in `types-matrix.ts` for recurring composite types.
+- **Scalar union types** — `ModelName` (`"sonnet" | "opus" | "haiku" | "inherit"`) and `PermissionMode` unions added to `types-matrix.ts`.
+- **Testing strategy document** — `testing-strategy.md` with conventions for test categories, co-location rules, Ink component testing, keyboard simulation timing, and fixture organization.
+
+### Changed
+
+- **Extended type narrowing across 33 library files** — `Record<string, X>` narrowed to `Record<AgentName|SkillId|Subcategory, X>` where keys are known. Function signatures narrowed for `compileAgent`, `compileAgentForPlugin`, `getPluginSkillIds`, `fetchSkills`, `buildStackProperty`, `buildAgentSkills`, `validateBuildStep`, `populateFromStack`. Return types narrowed for `CompiledStackPlugin`, `StackInstallResult`, `RecompileAgentsResult`.
+- **Replaced manual array operations with Remeda utilities** — `unique()`, `uniqueBy()`, `countBy()`, `sumBy()`, `sortBy()`, `indexBy()`, `mapToObj()`, `pipe()`, `flatMap()`, `filter()`, `mapValues()`, `difference()`, `groupBy()` across 20+ files.
+- **`types.ts` interface fields narrowed** — `SkillDefinition.canonicalId` to `SkillId`, `AgentDefinition`/`AgentConfig` model/permission fields to `ModelName`/`PermissionMode`, `ProjectConfig.stack` to `ResolvedSubcategorySkills`. Inline `//` comments converted to JSDoc.
+- **Wizard components and store narrowed** — Store selections use `DomainSelections`/`SubcategorySelections`, components use `typedEntries`/`typedKeys`.
+
+### Dependencies
+
+- Added `zod` v4.3.6 — runtime schema validation
+- Added `remeda` v2.33.6 — tree-shakeable TypeScript-first utility functions
+
+## [0.22.0] - 2026-02-09
+
+### Changed
+
+- **Union types for skill IDs, categories, agents, and domains** - Added `SkillId`, `CategoryPath`, `SkillAlias`, `AgentName`, `Domain`, `Subcategory` template literal and union types to `types-matrix.ts` as the single source of truth. All interface fields and function parameters across the codebase now use strict union types instead of `string`.
+- **Narrowed production function signatures** - 27 production files updated: `matrix-resolver`, `skill-agent-mappings`, `resolver`, `wizard-store`, `step-build`, `category-grid`, and others. Type assertions (`as SkillId`, etc.) used only at data entry boundaries (YAML parsing, CLI input, `Object.keys()`).
+- **Normalized skill ID format enforced at compile time** - `SkillId` = `` `${SkillIdPrefix}-${string}` `` prevents old-format IDs like `"react (@vince)"` at the type level. All test files updated to use `domain-subcategory-name` format.
+- **Removed test constants** - `TEST_SKILLS`, `TEST_CATEGORIES`, `PLACEHOLDER_SKILLS`, `TEST_AUTHOR` removed from test helpers — union types provide compile-time safety, making string constants redundant.
+- **`CategoryDefinition.id`** narrowed from `string` to `Subcategory`.
+- **`SkillEntry`** narrowed from `string | SkillAssignment` to `SkillId | SkillAssignment`.
+
 ## [0.21.0] - 2026-02-09
 
 ### Changed

package/README.md

@@ -31,29 +31,31 @@ requires node 18+ and [Claude Code](https://docs.anthropic.com/en/docs/claude-co
 
 ## commands
 
-```bash
-cc init              # interactive setup - pick skills, configure agents
-cc edit              # modify your skill selection
-cc compile           # recompile agents after changes
-cc list              # show what's installed
-cc config            # manage settings
-cc validate          # check your setup is correct
-cc new skill         # create a custom skill
-cc new agent         # create a custom agent
-cc import skill      # import a skill from a remote source
-cc update            # update local skills from source
-cc uninstall         # remove Claude Collective from project
-cc doctor            # diagnose setup issues
-cc eject             # eject skills/agent partials for customization
-cc build marketplace # generate marketplace.json
-cc build plugins     # build plugins
-cc build stack       # build stacks
-cc version           # show/manage versions
-cc diff              # show skill differences
-cc search            # search for skills
-cc info              # show skill information
-cc outdated          # check outdated skills
-```
+| command             | what it does                                                  |
+| ------------------- | ------------------------------------------------------------- |
+| `init`              | interactive setup - pick skills, configure agents             |
+| `edit`              | modify your skill selection                                   |
+| `compile`           | recompile agents after changes                                |
+| `update`            | update local skills from source                               |
+| `list`              | show what's installed                                         |
+| `doctor`            | diagnose setup issues                                         |
+| `search`            | search for skills                                             |
+| `info <skill>`      | show skill details                                            |
+| `diff`              | show skill differences vs source                              |
+| `outdated`          | check for outdated skills                                     |
+| `validate`          | check your setup is correct                                   |
+| `new skill`         | create a custom skill                                         |
+| `new agent`         | create a custom agent                                         |
+| `import skill`      | import a skill from a remote source                           |
+| `eject`             | eject skills/agent partials for customization                 |
+| `uninstall`         | remove Claude Collective from project                         |
+| `config`            | manage settings (show, get, set-project, unset-project, path) |
+| `version`           | show/manage plugin versions (show, set, bump)                 |
+| `build marketplace` | generate marketplace.json                                     |
+| `build plugins`     | build individual skill plugins                                |
+| `build stack`       | build a stack plugin                                          |
+
+every command supports `--dry-run` and `--source` flags. run `npx @claude-collective/cli <command> --help` for full options.
 
 ## how skills work
 
@@ -90,7 +92,7 @@ each stack includes agents like `web-developer`, `api-developer`, `web-reviewer`
 **as a plugin** (recommended for personal use):
 
 ```bash
-cc init
+npx @claude-collective/cli init
 # interactive wizard lets you choose: plugin mode, local mode, or marketplace setup
 # plugin mode installs to ./.claude/plugins/claude-collective/
 ```
@@ -98,7 +100,7 @@ cc init
 **locally in your project** (for team sharing):
 
 ```bash
-cc init
+npx @claude-collective/cli init
 # select "local" mode in the wizard
 # installs to ./.claude/ in your repo
 ```
@@ -106,7 +108,7 @@ cc init
 **your own marketplace** (for orgs):
 
 ```bash
-cc init
+npx @claude-collective/cli init
 # select "marketplace" mode in the wizard
 # scaffolds a marketplace you can customize and host
 ```
@@ -116,11 +118,23 @@ cc init
 if the existing skills don't cover what you need:
 
 ```bash
-cc new skill my-custom-skill
+npx @claude-collective/cli new skill my-custom-skill
 ```
 
 this scaffolds the structure. a skill is just markdown with examples - no special tooling required.
 
+## architecture
+
+built with TypeScript (strict mode), oclif for commands, Ink (React) for terminal UI, Zod for runtime validation, and Zustand for wizard state. the core pipeline:
+
+```
+source resolution → skill loading → matrix merging → wizard selection → config generation → agent compilation → installation
+```
+
+the codebase is organized into domain-driven library modules (`agents/`, `configuration/`, `loading/`, `matrix/`, `plugins/`, `skills/`, `stacks/`, `installation/`) with barrel exports. agents are compiled from YAML definitions + markdown partials through Liquid templates.
+
+see [docs/architecture.md](./docs/architecture.md) for the full reference.
+
 ## links
 
 - [skills repository](https://github.com/claude-collective/skills) - all the skills and stacks

package/config/skills-matrix.yaml

@@ -1,3 +1,4 @@
+# yaml-language-server: $schema=../src/schemas/skills-matrix.schema.json
 # =============================================================================
 # skills-matrix.yaml
 # Full skills matrix for CLI data-driven architecture
@@ -18,7 +19,7 @@ categories:
   # ─────────────────────────────────────────────────────────────────
   framework:
     id: framework
-    name: Framework
+    displayName: Framework
     description: Core UI framework (React, Vue, Angular, SolidJS)
     domain: web
     exclusive: true
@@ -27,7 +28,7 @@ categories:
 
   meta-framework:
     id: meta-framework
-    name: Meta-Framework
+    displayName: Meta-Framework
     description: Full-stack framework (Next.js, Remix, Nuxt)
     domain: web
     exclusive: true
@@ -36,7 +37,7 @@ categories:
 
   styling:
     id: styling
-    name: Styling
+    displayName: Styling
     description: CSS approach (SCSS Modules, Tailwind)
     domain: web
     exclusive: true
@@ -45,7 +46,7 @@ categories:
 
   client-state:
     id: client-state
-    name: Client State Management
+    displayName: Client State Management
     description: UI state, forms, local data (Zustand, Redux, MobX)
     domain: web
     exclusive: true
@@ -54,7 +55,7 @@ categories:
 
   server-state:
     id: server-state
-    name: Server State / Data Fetching
+    displayName: Server State / Data Fetching
     description: API data caching (React Query, SWR)
     domain: web
     exclusive: true
@@ -63,7 +64,7 @@ categories:
 
   forms:
     id: forms
-    name: Forms & Validation
+    displayName: Forms & Validation
     description: Form handling and schema validation
     domain: web
     exclusive: false
@@ -72,7 +73,7 @@ categories:
 
   testing:
     id: testing
-    name: Testing
+    displayName: Testing
     description: Unit, integration, and E2E testing
     domain: web
     exclusive: false
@@ -81,7 +82,7 @@ categories:
 
   ui-components:
     id: ui-components
-    name: UI Component Library
+    displayName: UI Component Library
     description: Pre-built component systems (Radix, shadcn)
     domain: web
     exclusive: false
@@ -90,7 +91,7 @@ categories:
 
   mocking:
     id: mocking
-    name: API Mocking
+    displayName: API Mocking
     description: Mock Service Worker for development and testing
     domain: web
     exclusive: false
@@ -99,7 +100,7 @@ categories:
 
   error-handling:
     id: error-handling
-    name: Error Handling
+    displayName: Error Handling
     description: Error boundaries, result types, and error patterns
     domain: web-extras
     parent_domain: web
@@ -109,7 +110,7 @@ categories:
 
   i18n:
     id: i18n
-    name: Internationalization
+    displayName: Internationalization
     description: i18n libraries (next-intl, react-intl, vue-i18n)
     domain: web
     exclusive: true
@@ -118,7 +119,7 @@ categories:
 
   file-upload:
     id: file-upload
-    name: File Upload
+    displayName: File Upload
     description: File upload patterns and handling
     domain: web-extras
     parent_domain: web
@@ -128,7 +129,7 @@ categories:
 
   files:
     id: files
-    name: Files & Images
+    displayName: Files & Images
     description: Image handling and file processing
     domain: web-extras
     parent_domain: web
@@ -138,7 +139,7 @@ categories:
 
   utilities:
     id: utilities
-    name: Utilities
+    displayName: Utilities
     description: Utility libraries (date-fns, native JS patterns)
     domain: web-extras
     parent_domain: web
@@ -148,7 +149,7 @@ categories:
 
   realtime:
     id: realtime
-    name: Realtime
+    displayName: Realtime
     description: WebSockets, SSE, and real-time communication
     domain: web-extras
     parent_domain: web
@@ -158,7 +159,7 @@ categories:
 
   animation:
     id: animation
-    name: Animation
+    displayName: Animation
     description: Animation libraries and CSS animations
     domain: web-extras
     parent_domain: web
@@ -168,7 +169,7 @@ categories:
 
   pwa:
     id: pwa
-    name: Progressive Web App
+    displayName: Progressive Web App
     description: Service workers, offline-first patterns, and PWA features
     domain: web-extras
     parent_domain: web
@@ -178,7 +179,7 @@ categories:
 
   accessibility:
     id: accessibility
-    name: Accessibility
+    displayName: Accessibility
     description: WCAG compliance, ARIA, and keyboard navigation
     domain: web-extras
     parent_domain: web
@@ -188,7 +189,7 @@ categories:
 
   web-performance:
     id: web-performance
-    name: Web Performance
+    displayName: Web Performance
     description: Bundle optimization, render performance, and code splitting
     domain: web
     exclusive: false
@@ -200,7 +201,7 @@ categories:
   # ─────────────────────────────────────────────────────────────────
   api:
     id: api
-    name: API Framework
+    displayName: API Framework
     description: Backend framework (Hono, Express, Fastify)
     domain: api
     exclusive: true
@@ -209,7 +210,7 @@ categories:
 
   database:
     id: database
-    name: Database ORM
+    displayName: Database ORM
     description: Database access layer (Drizzle, Prisma)
     domain: api
     exclusive: true
@@ -218,7 +219,7 @@ categories:
 
   auth:
     id: auth
-    name: Authentication
+    displayName: Authentication
     description: Auth solution (Better Auth, Auth.js)
     domain: api
     exclusive: true
@@ -227,7 +228,7 @@ categories:
 
   observability:
     id: observability
-    name: Observability
+    displayName: Observability
     description: Logging, monitoring, error tracking
     domain: api
     exclusive: false
@@ -236,7 +237,7 @@ categories:
 
   analytics:
     id: analytics
-    name: Analytics
+    displayName: Analytics
     description: Product analytics and tracking
     domain: api
     exclusive: false
@@ -245,7 +246,7 @@ categories:
 
   email:
     id: email
-    name: Email
+    displayName: Email
     description: Transactional email (Resend, Sendgrid)
     domain: api
     exclusive: true
@@ -254,7 +255,7 @@ categories:
 
   performance:
     id: performance
-    name: Performance
+    displayName: Performance
     description: API performance patterns and optimization
     domain: api
     exclusive: false
@@ -266,7 +267,7 @@ categories:
   # ─────────────────────────────────────────────────────────────────
   mobile-framework:
     id: mobile-framework
-    name: Mobile Framework
+    displayName: Mobile Framework
     description: Native mobile framework (React Native, Expo)
     domain: mobile
     exclusive: true
@@ -278,7 +279,7 @@ categories:
   # ─────────────────────────────────────────────────────────────────
   monorepo:
     id: monorepo
-    name: Monorepo
+    displayName: Monorepo
     description: Monorepo tooling (Turborepo, Nx)
     domain: shared
     exclusive: true
@@ -287,7 +288,7 @@ categories:
 
   tooling:
     id: tooling
-    name: Build Tooling
+    displayName: Build Tooling
     description: ESLint, Prettier, TypeScript, Vite
     domain: shared
     exclusive: false
@@ -296,7 +297,7 @@ categories:
 
   security:
     id: security
-    name: Security
+    displayName: Security
     description: Authentication security patterns and best practices
     domain: shared
     exclusive: false
@@ -305,7 +306,7 @@ categories:
 
   methodology:
     id: methodology
-    name: Methodology
+    displayName: Methodology
     description: Development methodology and engineering principles
     domain: shared
     exclusive: false
@@ -314,7 +315,7 @@ categories:
 
   research:
     id: research
-    name: Research
+    displayName: Research
     description: Codebase investigation and research methodology
     domain: shared
     exclusive: false
@@ -323,7 +324,7 @@ categories:
 
   reviewing:
     id: reviewing
-    name: Code Review
+    displayName: Code Review
     description: Code review patterns and guidance
     domain: shared
     exclusive: false
@@ -332,7 +333,7 @@ categories:
 
   ci-cd:
     id: ci-cd
-    name: CI/CD
+    displayName: CI/CD
     description: Continuous integration and deployment pipelines
     domain: shared
     exclusive: false
@@ -344,7 +345,7 @@ categories:
   # ─────────────────────────────────────────────────────────────────
   cli-framework:
     id: cli-framework
-    name: CLI Framework
+    displayName: CLI Framework
     description: CLI application framework (Commander, oclif)
     domain: cli
     exclusive: true
@@ -353,7 +354,7 @@ categories:
 
   cli-prompts:
     id: cli-prompts
-    name: CLI Prompts
+    displayName: CLI Prompts
     description: Interactive prompts and UI
     domain: cli
     exclusive: true
@@ -362,7 +363,7 @@ categories:
 
   cli-testing:
     id: cli-testing
-    name: CLI Testing
+    displayName: CLI Testing
     description: CLI testing utilities
     domain: cli
     exclusive: false