@claude-collective/cli 0.13.4 → 0.25.1

package/CHANGELOG.md

@@ -5,6 +5,354 @@ 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
+
+- **Removed refine wizard step** - The 5-step wizard flow (approach → stack → build → refine → confirm) is now 4 steps (approach → stack → build → confirm). The refine step for skill source selection has been removed; `refineAction` state and `setRefineAction` action removed from wizard store.
+- **Build step layout** - Domain tabs header shows all selected domains with active domain highlighted; legend row simplified from positioned overlay to inline flex layout.
+
+### Added
+
+- **`web-extras` domain** - 8 categories (error-handling, file-upload, files, utilities, realtime, animation, pwa, accessibility) split from `web` into a new `web-extras` domain to reduce vertical height in the build view.
+- **`parent_domain` field** on `CategoryDefinition` - Sub-domains inherit framework-first filtering from their parent domain (e.g., `web-extras` respects `web`'s framework selection).
+- **`parentDomainSelections` prop** on `StepBuild` - Passes parent domain selections for framework compatibility filtering in sub-domains.
+
+## [0.20.0] - 2026-02-07
+
+### Changed
+
+- **Removed `StackConfig` type** - All consumers (compile, agent-recompiler, resolver, stack-plugin-compiler, loader) now operate directly on `ProjectConfig`. The `StackConfig` interface, `loadStack()`, `loadStackSkills()`, `projectConfigToStackLike()`, `resolveAgentSkills()`, and related conversion helpers have been removed.
+- **Removed global config layer** - The `~/.claude-collective/config.yaml` global config is no longer supported. Config resolution simplifies from `flag > env > project > global > default` to `flag > env > project > default`. The `config:set` and `config:unset` commands (which wrote to global config) have been deleted.
+- **Removed legacy StackConfig detection** - `isLegacyStackConfig()`, `normalizeStackConfig()`, and the legacy format migration branch in `loadProjectConfig()` have been removed. `ProjectConfig` is the only supported format.
+- **Removed StackConfig-based generator functions** - `generateConfigFromSkills`, `generateConfigFromStack`, `mergeStackWithSkills`, and `generateProjectConfigFromStack` removed from config-generator.
+- **Removed `suggested_stacks` from skills matrix** - The field on `SkillsMatrixConfig` and the alias-resolution logic in `resolveSuggestedStacks()` have been removed; stacks are defined in `stacks.yaml`.
+- **Removed deprecated frontmatter field warnings** - `category`, `author`, and `version` warnings in skill frontmatter validation removed (metadata comes from `metadata.yaml`).
+- **Removed deprecated skill extraction functions** - `extractSkillName`, `extractCategory`, `extractAuthor` stubs removed from skill-plugin-compiler.
+- **Removed deprecated `skills` field from `AgentDefinition`** - Skills come from stacks, not agent definitions.
+
+### Removed
+
+- **`config:set` command** - Wrote to removed global config.
+- **`config:unset` command** - Wrote to removed global config.
+- **`test-imports` command** - Hidden debug command no longer needed.
+- **`GlobalConfig` type and helpers** - `loadGlobalConfig`, `saveGlobalConfig`, `getGlobalConfigPath`, `getGlobalConfigDir`.
+- **`"global"` source origin** - Removed from `sourceOrigin` and `AgentsSourceOrigin` union types.
+
+## [0.19.0] - 2026-02-07
+
+### Changed
+
+- **Removed top-level categories from skills matrix** - Top-level categories (`frontend`, `backend`, `setup`, `cli`, `mobile`, `reviewing`, `methodology`, `research`, `shared`, `local`) and the `parent` field on subcategories have been removed. The wizard already operated entirely on the `domain` field; the top-level layer added no value.
+- **Aligned agent mapping patterns with domains** - Category path patterns in skill-agent-mappings renamed: `frontend/*` → `web/*`, `backend/*` → `api/*`, `setup/*` → `infra/*`. YAML defaults and marketplace generator updated to match.
+- **Renamed `frontend/realtime` to `realtime`** - Composite subcategory ID simplified to match the `^[a-z][a-z0-9-]*$` schema pattern.
+- **Stacks alias renamed** - `backend-testing` → `api-testing` in stacks.yaml.
+
+### Added
+
+- **New web categories** - `animation`, `pwa`, `accessibility`, `web-performance` for skills previously bucketed under the removed `frontend` top-level.
+- **New shared categories** - `methodology`, `research`, `reviewing`, `ci-cd` for meta and infrastructure skills.
+
+### Removed
+
+- **`parent` field** from `CategoryDefinition` type and JSON schema.
+- **`getSubcategories()` and `getTopLevelCategories()`** from matrix-resolver (unused in production code).
+
+## [0.18.0] - 2026-02-07
+
+### Added
+
+- **Matrix health check** - New `matrix-health-check` module validates referential integrity of the merged skills matrix at load time, surfacing ghost skill IDs, missing domains, unknown categories, and dangling stack references
+- **Diagnostic logging for alias resolution** - `resolveToCanonicalId` in matrix-loader now accepts a context parameter for verbose-level messages when an ID can't be resolved
+- **Logger `warn()` function** - Always-visible warnings (not gated by verbose mode) for issues like unresolved aliases and missing skill categories
+- **Expanded matrix categories** - Top-level categories (methodology, research, shared, local) and new subcategories: error-handling, i18n, file-upload, files, utilities, frontend/realtime, performance, security
+- **New skill aliases** - `tailwind` → `web-styling-tailwind`, `mobx` → `web-state-mobx`, updated `oclif` → `cli-framework-oclif-ink`
+
+### Changed
+
+- **Dead types removed** - Removed unused types from `types.ts` (`SkillsConfig`, `RegistryConfig`, `AgentsConfig`, `AgentSkillEntry`, `SkillYamlConfig`, `Config`, `PluginCompileOptions`) and `types-matrix.ts` (`WizardState`)
+- **Type disambiguations** - `ProjectConfig` → `ProjectSourceConfig` in config.ts, `SkillPluginOptions`/`StackPluginOptions` → `SkillManifestOptions`/`StackManifestOptions` in plugin-manifest.ts, `ForkedFromMetadata` → `ImportedForkedFromMetadata` in import command, `ValidationResult` → `BuildStepValidation` in step-build
+- **Shared `extractFrontmatter` utility** - Deduplicated three identical copies (output-validator, plugin-validator, schema-validator) into `src/cli/utils/frontmatter.ts`
+- **Shared wizard utilities** - Extracted `getDomainDisplayName` and `getStackName` from wizard.tsx and step-build.tsx into `wizard/utils.ts`
+- **Consolidated `injectForkedFromMetadata`** - Moved from skill-copier.ts and update.tsx into skill-metadata.ts as single source of truth
+- **`parseFrontmatter` import** - skill-plugin-compiler.ts now imports from loader.ts instead of defining its own copy
+- **`LocalResolvedSkill` type** - Extracted named type in local-installer.ts replacing repeated inline object types
+- **Deprecated `WizardResult` removed** - Wizard `onComplete` callback now accepts only `WizardResultV2`
+- **`OutputValidationResult` replaced** - Uses `ValidationResult` from types.ts instead of local duplicate
+- **Matrix alias cleanup** - Removed references to skills not yet created (yargs, clack, inquirer, ink, svelte) from conflicts, alternatives, recommends, and requires
+
+## [0.17.0] - 2026-02-07
+
+### Added
+
+- **Local skill badge in wizard** - Skill tags in the CategoryGrid now show a gray `[L]` badge when the skill has a local override in `.claude/skills/`
+
+### Changed
+
+- **Extract config-merger module** - Config merging logic (identity fields, skills/agents union, stack deep-merge) extracted from `init.tsx` into dedicated `lib/config-merger.ts` with comprehensive tests
+- **Extract local-installer module** - Local installation orchestration (skill copying, config generation, agent compilation) extracted from `init.tsx` into `lib/local-installer.ts`, reducing the command to a thin orchestrator
+- **Deduplicate getCurrentDate** - Removed duplicate `getCurrentDate()` definitions from `import/skill.ts`, `update.tsx`, and `skill-copier.ts` in favor of the canonical export from `lib/versioning.ts`
+- **Graceful missing skill resolution** - `resolveSkillReference` now returns `null` and logs a verbose message instead of throwing when a skill is not found; callers skip missing skills gracefully
+- **Remove synthetic local categories** - Stop injecting fake `local` and `local/custom` category definitions into the skills matrix; local skills use their declared or inherited category
+
+### Fixed
+
+- **Wizard skill count mismatch** - Confirm step now uses `getAllSelectedTechnologies()` instead of `getSelectedSkills()` so the count matches the actual technologies shown
+- **Wizard option tracking** - Build step uses `skill.id` instead of alias for `CategoryOption.id` so selection tracking stays consistent
+- **Multi-skill category pre-population** - Stack pre-population now uses per-skill pseudo-agents so categories with multiple skills (e.g. testing: vitest + playwright-e2e) are all preserved instead of the second overwriting the first
+
+## [0.16.0] - 2026-02-07
+
+### Changed
+
+- **Wizard flow simplified** - Removed the intermediate "stack-options" step; selecting a stack now goes directly to the build step with pre-populated technology selections. Flow is now: approach -> stack -> build -> refine -> confirm
+- **ViewTitle component** - Simplified API from `title` string prop to `children` for flexible composition
+- **Build step header** - Replaced domain tab header with ViewTitle showing "Customise your {Domain} stack"
+- **Build step legend** - Simplified color legend from background-colored badges to plain colored text
+- **CategoryGrid styling** - Skill tags now use border-based styling instead of background colors; removed section header underlines
+
+### Added
+
+- **Accept defaults shortcut** - Press `A` during build step (stack path only) to skip customization and continue with stack defaults
+- **All-domain cycling** - Stack selection now includes all five domains (web, api, cli, mobile, shared) in the build step, even if the stack only covers some
+
+### Fixed
+
+- **Local skill category preservation** - When a local skill overwrites a remote skill, the remote skill's domain-based category is now preserved instead of falling back to "local/custom"
+
+### Removed
+
+- **StepStackOptions component** - Eliminated intermediate step between stack selection and technology customization
+
+## [0.15.0] - 2026-02-07
+
+### Added
+
+- **MenuItem component** - Reusable chevron + label menu item with focused/active states for wizard navigation
+- **ViewTitle component** - Yellow-background title banner for consistent wizard step headings
+- **Global keyboard shortcuts** - `E` toggles expert mode, `P` toggles plugin/local install mode, `D` toggles descriptions (on build step) - available from any wizard step
+
+### Changed
+
+- **Step Approach** - Replaced Select dropdown with custom card-based navigation using arrow keys and Enter
+- **Step Stack** - Replaced Select dropdown with card-based stack selection; Escape for back navigation; focus starts at first stack
+- **Mode toggles** - Expert mode and install mode moved from per-step menu options to persistent global shortcuts shown in layout footer
+- **Build step legend** - Repositioned color legend (active/recommended/discouraged/disabled) above category grid
+
+### Removed
+
+- **Inline keyboard hints** - Removed per-step keyboard hint text (global footer already provides this)
+- **CategoryGrid header/legend** - Moved toggle indicators and legend out of CategoryGrid to parent components
+
+## [0.14.1] - 2026-02-07
+
+### Changed
+
+- **Extract skill-metadata library** - Deduplicated `readForkedFromMetadata`, `getLocalSkillsWithMetadata`, `computeSourceHash`, and `compareSkills` into shared `lib/skill-metadata.ts`, removing ~254 lines from `update.tsx`, `outdated.ts`, and `diff.ts`
+- **Extract config-saver library** - Deduplicated `saveSourceToProjectConfig` into shared `lib/config-saver.ts`, removing duplication from `init.tsx` and `eject.ts`
+- **Extract plugin-manifest-finder library** - Deduplicated `findPluginManifest` into shared `lib/plugin-manifest-finder.ts`, removing duplication from 4 `version/*` command files
+
+### Removed
+
+- **Unused step-build props** - Removed `currentDomainIndex` prop, dead code from SectionProgress removal (unused imports, constants, functions)
+
+## [0.14.0] - 2026-02-07
+
+### Changed
+
+- **WizardLayout component** - Extracted layout wrapper that renders WizardTabs (header), children, and WizardFooter consistently across all wizard steps
+- **Wizard tabs** - Simplified to text-only styling (cyan current, dimmed skipped) with horizontal border lines; renamed "Approach" step to "Intro"; version displayed in tab bar
+- **Build step header** - Redesigned with domain tab navigation and inline toggle indicators for descriptions and expert mode
+- **Wizard footer** - Unified keyboard shortcut hints (navigate, select, continue, back, export) displayed on all steps, replacing per-step footer strings
+
+### Added
+
+- **ASCII art banner** - Init command displays stylized banner on startup
+- **Prettier config** - Added `prettier.config.mjs` for consistent code formatting (printWidth 100)
+
+### Removed
+
+- **Old WizardFooter component** (`wizard-footer.tsx`) - Replaced by centralized footer in WizardLayout
+- **SectionProgress in build step** - Domain progress replaced by domain tab navigation in header
+
+### Fixed
+
+- **Version display** - Fixed broken `import { config } from "process"` (Node's build config, not CLI version); version now prop-drilled from oclif `this.config.version`
+
 ## [0.13.4] - 2026-02-06
 
 ### Fixed
@@ -55,6 +403,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Old `search.ts` command - Replaced with dual-mode `search.tsx` (static + interactive)
 
+[0.21.0]: https://github.com/claude-collective/cli/releases/tag/v0.21.0
+[0.20.0]: https://github.com/claude-collective/cli/releases/tag/v0.20.0
+[0.19.0]: https://github.com/claude-collective/cli/releases/tag/v0.19.0
+[0.18.0]: https://github.com/claude-collective/cli/releases/tag/v0.18.0
+[0.17.0]: https://github.com/claude-collective/cli/releases/tag/v0.17.0
+[0.16.0]: https://github.com/claude-collective/cli/releases/tag/v0.16.0
+[0.15.0]: https://github.com/claude-collective/cli/releases/tag/v0.15.0
+[0.14.1]: https://github.com/claude-collective/cli/releases/tag/v0.14.1
+[0.14.0]: https://github.com/claude-collective/cli/releases/tag/v0.14.0
 [0.13.4]: https://github.com/claude-collective/cli/releases/tag/v0.13.4
 [0.13.3]: https://github.com/claude-collective/cli/releases/tag/v0.13.3
 [0.13.2]: https://github.com/claude-collective/cli/releases/tag/v0.13.2

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