docs(install-command): align docs with current implementation

Author: codeaholicguy

CHANGELOG.md

@@ -5,6 +5,15 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Install Command** - Added `ai-devkit install` to apply project configuration from `.ai-devkit.json`
+  - Supports `--config <path>` for custom config file locations
+  - Supports `--overwrite` for non-interactive full overwrite mode
+  - Installs environments, phases, and skills in a single run with summary output
+
 ## [0.14.0] - 2026-02-21
 
 ### Changed

docs/ai/design/feature-install-command.md

@@ -14,8 +14,8 @@ feature: install-command
 ```mermaid
 graph TD
   User[User: ai-devkit install] --> InstallCommand
-  InstallCommand --> ConfigManager[ConfigManager: read .ai-devkit.json]
-  ConfigManager --> Validator[InstallConfig Validator]
+  InstallCommand --> ConfigLoader[Config Service: load .ai-devkit.json]
+  ConfigLoader --> Validator[Config Util Validator]
   Validator --> Reconciler[Install Reconciler]
   Reconciler --> Confirmer[Overwrite Confirmation Prompt]
   Reconciler --> EnvSetup[TemplateManager.setupMultipleEnvironments]
@@ -44,7 +44,7 @@ graph TD
 interface DevKitInstallConfig {
   version: string;
   environments: EnvironmentCode[];
-  initializedPhases: Phase[];
+  phases: Phase[];
   skills?: Array<{
     registry: string;
     name: string;
@@ -67,7 +67,7 @@ interface DevKitInstallConfig {
 - `ai-devkit install`
 - Optional follow-up flags (proposed):
   - `--config <path>` (default `.ai-devkit.json`)
-  - `--yes` (auto-confirm overwrite prompts for automation)
+  - `--overwrite` (overwrite all existing artifacts without additional prompts)
 
 **Internal interfaces (proposed):**
 
@@ -91,11 +91,12 @@ async function reconcileAndInstall(config: ValidatedInstallConfig, options: Inst
 **What are the major building blocks?**
 
 1. `packages/cli/src/commands/install.ts` (new): top-level command execution.
-2. `packages/cli/src/lib/InstallConfig.ts` (new): schema validation and normalization.
-3. `packages/cli/src/lib/InstallOrchestrator.ts` (new): reconcile and apply installation.
-4. `packages/cli/src/lib/Config.ts` (update): persist/read `skills` metadata.
-5. `packages/cli/src/lib/SkillManager.ts` (update): on successful `addSkill`, sync skill entry into `.ai-devkit.json`.
-6. `packages/cli/src/cli.ts` (update): register `install` command and options.
+2. `packages/cli/src/services/config/config.service.ts` (new): load config file from disk.
+3. `packages/cli/src/util/config.ts` (new): schema validation and normalization.
+4. `packages/cli/src/services/install/install.service.ts` (new): reconcile and apply installation.
+5. `packages/cli/src/lib/Config.ts` (update): persist/read `skills` metadata.
+6. `packages/cli/src/lib/SkillManager.ts` (update): on successful `addSkill`, sync skill entry into `.ai-devkit.json`.
+7. `packages/cli/src/cli.ts` (update): register `install` command and options.
 
 ## Design Decisions
 

docs/ai/implementation/feature-install-command.md

@@ -10,20 +10,22 @@ feature: install-command
 ## Development Setup
 
 - Implemented in `packages/cli` using existing command architecture (`commander`).
-- No new external dependencies required.
+- Uses `zod` for schema-based config validation.
 - Feature reuses existing managers: `ConfigManager`, `TemplateManager`, `SkillManager`.
 
 ## Code Structure
 
 - `packages/cli/src/commands/install.ts`
   - New CLI handler for `ai-devkit install`.
   - Handles config loading, report output, and process exit code.
-- `packages/cli/src/lib/InstallConfig.ts`
-  - Validates and normalizes install config file data.
-  - Supports backward-compatible skill shape (`name` and legacy `skill` key).
-- `packages/cli/src/lib/InstallOrchestrator.ts`
+- `packages/cli/src/services/config/config.service.ts`
+  - Loads and parses config file JSON from disk.
+- `packages/cli/src/util/config.ts`
+  - Validates and normalizes install config data using Zod.
+  - Supports skill shape normalization (`name` and legacy `skill` key).
+- `packages/cli/src/services/install/install.service.ts`
   - Reconciles desired state and applies environment/phase/skill installation.
-  - Implements overwrite and strict-failure policy.
+  - Implements overwrite and warning-based partial-failure policy.
 - `packages/cli/src/types.ts`
   - Adds optional `skills` metadata to `DevKitConfig`.
 - `packages/cli/src/lib/Config.ts`
@@ -40,9 +42,7 @@ feature: install-command
 - `ai-devkit install`
 - Options:
   - `--config <path>`: alternate config file path (default `.ai-devkit.json`)
-  - `--overwrite`: allow replacing existing artifacts
-  - `--yes`: auto-confirm overwrite when `--overwrite` is set
-  - `--strict`: return exit code `1` when any skill installation fails
+  - `--overwrite`: overwrite all existing artifacts without additional prompts
 
 ### Reconcile Behavior
 
@@ -56,7 +56,6 @@ feature: install-command
 - `1` for invalid/missing config.
 - `1` for environment/phase failures.
 - `0` for successful run and for skill-only partial failures.
-- `1` for skill failures when `--strict` is enabled.
 
 ## Error Handling
 

docs/ai/planning/feature-install-command.md

@@ -13,7 +13,7 @@ feature: install-command
 
 - [x] Milestone 1: Requirements/design approved for `ai-devkit install`.
 - [x] Milestone 2: Core install flow (config read + env/phase reconcile) implemented.
-- [ ] Milestone 3: Skill install integration + tests + docs completed.
+- [x] Milestone 3: Skill install integration + tests + docs completed.
 
 ## Task Breakdown
 
@@ -29,23 +29,23 @@ feature: install-command
 ### Phase 2: Core Features
 
 - [x] Task 2.1: Implement environment setup from `environments` using `TemplateManager`.
-- [x] Task 2.2: Implement phase setup from `initializedPhases` using `TemplateManager`.
+- [x] Task 2.2: Implement phase setup from `phases` using `TemplateManager`.
 - [x] Task 2.3: Add idempotent handling for existing artifacts.
 - [x] Task 2.4: Add `--overwrite` behavior and conflict messaging.
 
 ### Phase 3: Skills Integration
 
 - [x] Task 3.1: Implement skills install loop from config skills entries.
 - [x] Task 3.2: Deduplicate skill entries by `registry + name`.
-- [x] Task 3.3: Add partial-failure handling and optional `--strict` exit behavior.
+- [x] Task 3.3: Add partial-failure handling with warning-only skill failures.
 - [x] Task 3.4: Update config types/read-write paths for optional `skills` field.
 
 ### Phase 4: Validation & Docs
 
 - [x] Task 4.1: Unit tests for config validation and normalization.
 - [x] Task 4.2: Integration tests for full `ai-devkit install` happy path.
 - [x] Task 4.3: Integration tests for missing config, invalid config, and partial failures.
-- [ ] Task 4.4: Update README/CLI help/changelog with usage examples.
+- [x] Task 4.4: Update README/CLI help/changelog with usage examples.
 
 ## Dependencies
 
@@ -72,8 +72,8 @@ graph TD
 - Phase 1: completed
 - Phase 2: completed
 - Phase 3: completed
-- Phase 4: in progress (`4.4` pending)
-- Remaining estimate: 0.5 day
+- Phase 4: completed
+- Remaining estimate: 0 day
 
 ## Risks & Mitigation
 
@@ -82,7 +82,7 @@ graph TD
 - Risk: Existing `.ai-devkit.json` files lack `skills`.
   - Mitigation: keep field optional and treat as empty array.
 - Risk: Skill installs fail because of network/registry issues.
-  - Mitigation: continue on error, collect warnings, return non-zero only in `--strict` mode.
+  - Mitigation: continue on error and collect warnings with clear per-skill failure details.
 - Risk: Overwrite policy causes accidental template replacement.
   - Mitigation: default skip existing artifacts unless `--overwrite` is enabled.
 

docs/ai/requirements/feature-install-command.md

@@ -80,17 +80,17 @@ feature: install-command
 
 **How will we know when we're done?**
 
-- [ ] `ai-devkit install` command is available and documented.
-- [ ] Command loads `.ai-devkit.json` from CWD by default.
-- [ ] Command applies configured environments (command/context templates).
-- [ ] Command applies configured `initializedPhases` templates.
-- [ ] Command installs configured skills using existing skill installation flow.
-- [ ] Command prints final summary with installed/skipped/failed counts.
-- [ ] Command returns non-zero exit code for invalid/missing config.
-- [ ] Command returns exit code `0` for partial skill-install failures and emits warnings with failure details.
-- [ ] Re-running command is safe and does not duplicate work.
-- [ ] `ai-devkit skill add` persists installed skill metadata into `.ai-devkit.json`.
-- [ ] Existing artifacts trigger user confirmation before overwrite.
+- [x] `ai-devkit install` command is available and documented.
+- [x] Command loads `.ai-devkit.json` from CWD by default.
+- [x] Command applies configured environments (command/context templates).
+- [x] Command applies configured `phases` templates.
+- [x] Command installs configured skills using existing skill installation flow.
+- [x] Command prints final summary with installed/skipped/failed counts.
+- [x] Command returns non-zero exit code for invalid/missing config.
+- [x] Command returns exit code `0` for partial skill-install failures and emits warnings with failure details.
+- [x] Re-running command is safe and does not duplicate work.
+- [x] `ai-devkit skill add` persists installed skill metadata into `.ai-devkit.json`.
+- [x] Existing artifacts trigger user confirmation before overwrite.
 
 ## Constraints & Assumptions
 

docs/ai/testing/feature-install-command.md

@@ -15,14 +15,19 @@ feature: install-command
 
 ## Unit Tests
 
-### `InstallConfig` Validation
+### Config Validation (`util/config.ts`)
 
 - [x] Normalizes duplicated environments/phases/skills.
 - [x] Accepts legacy `skills[].skill` and normalizes to `name`.
-- [x] Fails for missing config file.
 - [x] Fails for unsupported environment values.
 - [x] Fails for invalid skill entries.
 
+### Config Loading (`services/config/config.service.ts`)
+
+- [x] Fails for missing config file.
+- [x] Fails for invalid JSON parsing.
+- [x] Returns resolved config path and parsed data on success.
+
 ### `install` Command Handler
 
 - [x] Returns exit code `1` when config loading fails.
@@ -48,24 +53,24 @@ Executed on February 23, 2026:
 
 ```bash
 npm run test -- --runInBand \
-  src/__tests__/lib/InstallConfig.test.ts \
+  src/__tests__/util/config.test.ts \
   src/__tests__/commands/install.test.ts \
+  src/__tests__/services/config/config.service.test.ts \
   src/__tests__/lib/Config.test.ts \
   src/__tests__/lib/SkillManager.test.ts \
   src/__tests__/commands/init.test.ts
 ```
 
-Result: `5 passed, 5 total` test suites and `79 passed, 79 total` tests.
+Result: targeted suites pass locally (command/config/config-service/config-manager/init/skill-manager coverage).
 
 ## Manual Testing
 
 Pending manual verification:
 
 - [ ] `ai-devkit install` in a repo with existing `.ai-devkit.json`.
 - [ ] `ai-devkit install --overwrite` prompt and overwrite behavior.
-- [ ] `ai-devkit install --strict` non-zero behavior when skill install fails.
+- [ ] `ai-devkit install` with skill install failure path and warning output.
 
 ## Outstanding Gaps
 
-- README/changelog examples for `ai-devkit install` are not yet added.
 - End-to-end filesystem and network-backed integration tests are still pending.

packages/cli/README.md

@@ -46,6 +46,12 @@ ai-devkit init
 # Initialize project from YAML/JSON template
 ai-devkit init --template ./ai-devkit.init.yaml
 
+# Install/reconcile project setup from .ai-devkit.json
+ai-devkit install
+
+# Overwrite all existing install artifacts without extra prompts
+ai-devkit install --overwrite
+
 # Add a development phase
 ai-devkit phase requirements