@softspark/ai-toolkit 1.4.2 → 1.5.1

package/llms-full.txt

@@ -15,6 +15,7 @@
 - [No Hardcoded Counts in Secondary Docs](kb/best-practices/no-hardcoded-counts.md)
 - [How-To Guides](kb/howto/README.md)
 - [SOP: Claude Toolkit Maintenance](kb/procedures/maintenance-sop.md)
+- [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
 - [SOP: Release Verification](kb/procedures/release-verification-sop.md)
 - [Agents Catalog](kb/reference/agents-catalog.md)
 - [Anti-Pattern Registry Format](kb/reference/anti-pattern-registry-format.md)
@@ -84,6 +85,7 @@
 - **git-mastery**: Loaded when user asks about advanced Git workflows or history rewriting
 - **grill-me**: Stress-test a plan or design through relentless Socratic questioning, walking down each decision branch until reaching shared understanding. Use when user wants to stress-test a plan, get grilled, validate assumptions, or mentions 'grill me'.
 - **health**: Report service and infrastructure health status
+- **hipaa-validate**: Validate code against HIPAA policy: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references
 - **hive-mind**: Loaded when orchestrating multi-agent swarms or consensus workflows
 - **hook-creator**: Creates new Claude Code hooks with guided workflow, strict conventions, and validation
 - **index**: Index codebase into the knowledge base
@@ -272,9 +274,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "1.0.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-04-02"
+last_updated: "2026-04-09"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -291,18 +293,30 @@ cd /path/to/new-project
 ai-toolkit install --local
 ```
 
-This creates/updates:
+By default, `--local` installs Claude Code configs only:
 - `CLAUDE.md` — project-specific rules template (only if missing)
 - `.claude/settings.local.json` — MCP servers, env vars, permissions (only if missing, initialized with MCP defaults)
 - `.claude/constitution.md` — toolkit constitution **injected** via markers (preserves user content)
-- `.github/copilot-instructions.md` — GitHub Copilot rules (marker-injected)
-- `.clinerules` — Cline rules (marker-injected)
-- `.roomodes` — Roo Code custom modes (generated)
-- `.aider.conf.yml` — Aider configuration (generated)
-- `.git/hooks/pre-commit` — Safety fallback for quality gates (generated)
+
+To also install editor configs, use `--editors`:
+
+```bash
+ai-toolkit install --local --editors all                  # all supported editors
+ai-toolkit install --local --editors cursor,aider         # specific editors only
+```
+
+Supported editors: `cursor`, `windsurf`, `cline`, `roo`, `aider`, `augment`, `copilot`, `antigravity`.
+
+To restrict which language rules are injected into `CLAUDE.md`, use `--lang`:
+
+```bash
+ai-toolkit install --local --lang python,typescript
+```
 
 **Note:** Hooks are global-only — merged into `~/.claude/settings.json` by `ai-toolkit install`. Project-local `--local` does not install hooks; any legacy `.claude/hooks.json` is removed automatically.
 
+**Input validation (v1.4.2):** `--only`, `--skip`, `--editors`, and `--lang` are validated on input; an invalid value exits with a clear error before any changes are made.
+
 Then edit `CLAUDE.md`:
 ```markdown
 # My Project
@@ -359,11 +373,14 @@ ai-toolkit update
 `update` is a semantic alias for `install` — use it for all re-apply flows. Supports the same flags:
 
 ```bash
-ai-toolkit update --only agents,hooks   # re-apply only specific components
-ai-toolkit update --local               # also refresh project-local Copilot + Cline + Roo + Aider
-ai-toolkit update --list                # dry-run: show what would change
+ai-toolkit update --only agents,hooks                  # re-apply only specific components
+ai-toolkit update --local                              # refresh project-local Claude Code configs; auto-detects editors from existing project files (no --editors needed)
+ai-toolkit update --local --editors cursor,windsurf   # override auto-detection and target specific editors
+ai-toolkit update --list                               # dry-run: show what would change
 ```
 
+When running `update --local`, the CLI inspects existing config files (e.g. `.cursor/rules`, `.aider.conf.yml`) to determine which editors are present and refreshes only those — no flags required.
+
 ---
 
 ## Register a Rule from Another Repo
@@ -502,15 +519,14 @@ ai-toolkit benchmark-ecosystem --offline   # benchmark snapshot
 Changes propagate instantly to all machines via symlinks. After any change:
 
 ```bash
-scripts/validate.py           # must pass before commit
-npm test                      # must pass before commit
+npm run generate:all          # FIRST: regenerate AGENTS.md, llms.txt, all platform configs
+scripts/validate.py           # then validate — must pass before commit
+npm test                      # then test — must pass before commit
 ```
 
-If you added/removed agents or skills, also regenerate derived artifacts:
-
-```bash
-npm run generate:all          # regenerates AGENTS.md, llms.txt, all platform configs
-```
+Run `generate:all` before validate and test so that generated artifacts are current when
+the metadata contract tests run. Committing without regenerating first causes artifact
+drift and fails CI.
 
 ## Release Checklist
 
@@ -541,7 +557,17 @@ npm test            # full bats suite including metadata contracts and CLI tests
 The metadata contract tests (`tests/test_metadata_contracts.bats`) catch drift
 automatically. If they fail, fix the stale numbers before continuing.
 
-### 5. Commit and tag
+### 5. Check for artifact drift
+
+```bash
+git diff --stat
+```
+
+Review the diff to confirm that all generated files (`AGENTS.md`, `llms.txt`, platform
+configs) reflect the current state. If `generate:all` produced unexpected changes,
+investigate before staging.
+
+### 6. Commit and tag
 
 ```bash
 git add -A
@@ -576,6 +602,288 @@ What `uninstall` does:
 
 ---
 
+## kb/procedures/release-preparation-sop.md
+
+---
+title: "SOP: Release Preparation"
+category: procedures
+service: ai-toolkit
+tags: [sop, release, version, publish, changelog, semver]
+version: "1.5.0"
+created: "2026-04-10"
+last_updated: "2026-04-10"
+description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag."
+---
+
+# SOP: Release Preparation
+
+Complete checklist for preparing a new `@softspark/ai-toolkit` release.
+Run this **before** tagging. After tagging and publishing, run the
+[Release Verification SOP](release-verification-sop.md) to smoke-test.
+
+**Pipeline:**
+```
+Release Preparation (this SOP) → git tag → CI publish → Release Verification SOP
+```
+
+**Time:** 5-10 minutes
+
+---
+
+## Quick Checklist (TL;DR)
+
+```bash
+# 1. Decide version bump
+#    patch (1.4.2 → 1.4.3): bugfix, typo, doc fix
+#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag
+#    major (1.4.2 → 2.0.0): breaking change
+
+# 2. Sync version across all files
+python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
+
+# 3. Write CHANGELOG.md entry
+# 4. Regenerate artifacts
+python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_llms_txt.py > llms.txt
+python3 scripts/generate_llms_txt.py --full > llms-full.txt
+
+# 5. Validate + audit + test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+
+# 6. Commit + tag + push
+git add -A && git commit -m "chore: release vX.Y.Z"
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+---
+
+## Phase 1: Determine Version Bump
+
+Follow [Semantic Versioning](https://semver.org/):
+
+| Change Type | Bump | Examples |
+|-------------|------|---------|
+| Bugfix, typo, doc-only | **patch** | Fix install flag, correct description |
+| New feature, skill, agent, flag | **minor** | Add `/hipaa-validate`, add `--output json` |
+| Breaking CLI change, removed skill, config format change | **major** | Rename `install` to `setup`, remove skill |
+
+**Rule:** When in doubt, bump minor.
+
+---
+
+## Phase 2: Sync Version in All Files
+
+The canonical version lives in `package.json`. These files **must** match:
+
+### Mandatory sync (every release)
+
+| File | Field | How to update |
+|------|-------|---------------|
+| `package.json` | `"version": "X.Y.Z"` | Edit directly |
+| `manifest.json` | `"version": "X.Y.Z"` | Edit directly |
+| `app/.claude-plugin/plugin.json` | `"version": "X.Y.Z"` | Edit directly |
+
+### Auto-synced (no manual action)
+
+| File | Mechanism |
+|------|-----------|
+| `package-lock.json` | Regenerated by `npm install --package-lock-only` |
+
+### Conditional sync (only if the doc was modified in this release)
+
+| File | Field | When to update |
+|------|-------|---------------|
+| `kb/procedures/maintenance-sop.md` | frontmatter `version:` | If SOP content changed |
+| `kb/reference/skills-catalog.md` | frontmatter `version:` | If skills added/removed |
+| `kb/reference/agents-catalog.md` | frontmatter `version:` | If agents added/removed |
+| `kb/reference/hooks-catalog.md` | frontmatter `version:` | If hooks changed |
+| `kb/reference/architecture-overview.md` | frontmatter `version:` | If architecture changed |
+| `kb/reference/distribution-model.md` | frontmatter `version:` | If install model changed |
+| `kb/reference/global-install-model.md` | frontmatter `version:` | If install model changed |
+
+> **Note:** KB `version:` fields track the **document version**, not the toolkit version.
+> Only bump them when the document content actually changes in this release.
+
+### Count sync (if skills/agents/hooks changed)
+
+| File | What to check |
+|------|---------------|
+| `package.json` | `"description"` — skill/agent count |
+| `README.md` | Badge counts, "What You Get" table |
+| `app/ARCHITECTURE.md` | Section headings with counts |
+
+> **Tip:** `validate.py --strict` and `npm test` (metadata contract tests) catch
+> count drift automatically. If tests pass, counts are correct.
+
+### Verification command
+
+After syncing, verify all mandatory files match:
+
+```bash
+VERSION=$(python3 -c "import json; print(json.load(open('package.json'))['version'])")
+echo "Target: $VERSION"
+echo "manifest.json:     $(python3 -c "import json; print(json.load(open('manifest.json'))['version'])")"
+echo "plugin.json:       $(python3 -c "import json; print(json.load(open('app/.claude-plugin/plugin.json'))['version'])")"
+echo "package-lock.json: $(python3 -c "import json; print(json.load(open('package-lock.json'))['version'])")"
+```
+
+All four must print the same version. If not, fix before proceeding.
+
+---
+
+## Phase 3: Write CHANGELOG Entry
+
+Add entry at the top of `CHANGELOG.md` (after the header, before previous release):
+
+```markdown
+## vX.Y.Z — Short Title (YYYY-MM-DD)
+
+### Added
+- **Feature name** — description
+
+### Changed
+- **What changed** — old behavior → new behavior
+
+### Fixed
+- **Bug description** — what was broken and how it's fixed
+
+### Removed
+- **What was removed** — migration path if any
+```
+
+**Rules:**
+- Use **bold** for feature names
+- Start descriptions with a verb (Added, Changed, Fixed, Removed)
+- Reference skill names with backticks and slash: `/hipaa-validate`
+- Include script names: `scripts/hipaa_scan.py`
+- Include count changes: `Skill count: 91 → 92`
+- Date format: `YYYY-MM-DD`
+- Title: short, descriptive, no version number repetition
+
+---
+
+## Phase 4: Regenerate Artifacts
+
+```bash
+python3 scripts/generate_agents_md.py > AGENTS.md
+python3 scripts/generate_llms_txt.py > llms.txt
+python3 scripts/generate_llms_txt.py --full > llms-full.txt
+```
+
+Check if anything actually changed:
+
+```bash
+git diff --stat AGENTS.md llms.txt llms-full.txt
+```
+
+If no diff, the artifacts are already current. If there is a diff, stage them.
+
+---
+
+## Phase 5: Validate, Audit, Test
+
+Run the full quality gate:
+
+```bash
+python3 scripts/validate.py --strict
+python3 scripts/audit_skills.py --ci
+npm test
+```
+
+**Expected results:**
+- `validate.py`: `Errors: 0 | Warnings: 0 | VALIDATION PASSED`
+- `audit_skills.py`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
+- `npm test`: `1..N` with zero `not ok`
+
+**One-liner:**
+```bash
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+```
+
+**If tests fail:** Fix the issue, do NOT skip. Common failures:
+- Stale counts → re-run `generate:all` or fix README/ARCHITECTURE
+- Missing frontmatter → add to new KB docs
+- Broken symlink → `ai-toolkit doctor --fix`
+
+---
+
+## Phase 6: Commit
+
+Stage all release files:
+
+```bash
+git add package.json manifest.json app/.claude-plugin/plugin.json
+git add package-lock.json
+git add CHANGELOG.md
+git add AGENTS.md llms.txt llms-full.txt
+git add -p  # review and stage any other changes
+```
+
+Commit:
+
+```bash
+git commit -m "chore: release vX.Y.Z"
+```
+
+---
+
+## Phase 7: Tag and Push
+
+```bash
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+This triggers `.github/workflows/publish.yml` which:
+1. Runs `validate.py --strict`
+2. Runs `npm test`
+3. Publishes to npm as `@softspark/ai-toolkit@X.Y.Z`
+
+**After CI completes:** Run the [Release Verification SOP](release-verification-sop.md)
+to smoke-test the published package.
+
+---
+
+## Rollback
+
+If a bad release was published:
+
+```bash
+# Unpublish from npm (within 72h)
+npm unpublish @softspark/ai-toolkit@X.Y.Z
+
+# Or deprecate (preferred — doesn't break existing installs)
+npm deprecate @softspark/ai-toolkit@X.Y.Z "Known issue: <description>. Use vA.B.C instead."
+
+# Delete tag
+git tag -d vX.Y.Z
+git push origin --delete vX.Y.Z
+```
+
+---
+
+## Checklist Summary
+
+| # | Step | Command / Action | Pass Criteria |
+|---|------|-----------------|---------------|
+| 1 | Version bump type | Decide patch/minor/major | — |
+| 2 | `package.json` version | Edit `"version"` | Matches target |
+| 3 | `manifest.json` version | Edit `"version"` | Matches target |
+| 4 | `plugin.json` version | Edit `"version"` | Matches target |
+| 5 | `package-lock.json` | `npm install --package-lock-only` | Matches target |
+| 6 | Count sync | Check `package.json` description, README | `validate.py` passes |
+| 7 | CHANGELOG.md | Add release entry | Entry exists for vX.Y.Z |
+| 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_llms_txt.py` | No unexpected diff |
+| 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
+| 10 | Security audit | `audit_skills.py --ci` | 0 HIGH |
+| 11 | Tests | `npm test` | All pass |
+| 12 | Commit | `git commit` | Clean working tree |
+| 13 | Tag | `git tag vX.Y.Z` | Tag exists |
+| 14 | Push | `git push origin main --tags` | CI triggered |
+
+---
+
 ## kb/procedures/release-verification-sop.md
 
 ---
@@ -871,9 +1179,9 @@ title: "AI Toolkit - Agents Catalog"
 category: reference
 service: ai-toolkit
 tags: [agents, catalog, roles, ai-development]
-version: "1.3.10"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-03-25"
+last_updated: "2026-04-09"
 description: "Complete catalog of specialized agents with roles, models, and use cases."
 ---
 
@@ -1223,9 +1531,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.4.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-04-08"
+last_updated: "2026-04-09"
 description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
 ---
 
@@ -1397,7 +1705,7 @@ Three tiers determine how to approach a task:
 
 | Type | Field | Invocation | Count |
 |------|-------|-----------|-------|
-| Task | `disable-model-invocation: true` | User via `/skill` only | 28 |
+| Task | `disable-model-invocation: true` | User via `/skill` only | 29 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
 | Knowledge | `user-invocable: false` | Claude auto-loads | 32 |
 
@@ -2546,9 +2854,9 @@ title: "Distribution Model"
 category: reference
 service: ai-toolkit
 tags: [architecture, distribution, symlinks, npm, install]
-version: "1.0.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-03-28"
+last_updated: "2026-04-09"
 description: "Reference description of how ai-toolkit is delivered and propagated on a developer machine."
 ---
 
@@ -2794,9 +3102,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, local-setup]
-version: "1.0.0"
+version: "1.4.2"
 created: "2026-03-26"
-last_updated: "2026-03-28"
+last_updated: "2026-04-09"
 description: "Reference description of the global install target, local project setup, and command responsibilities in ai-toolkit."
 ---
 
@@ -2814,8 +3122,10 @@ That means one machine-level install provides agents, skills, hooks, and rules t
 |---------|--------|---------|
 | `ai-toolkit install` | `~/.claude/` | first-time machine setup |
 | `ai-toolkit update` | `~/.claude/` | re-apply after package or rule changes |
-| `ai-toolkit install --local` | current project | create local `CLAUDE.md`, `.claude/settings.local.json`, and inject constitution + Copilot + Cline + Roo Code + Aider configs. Installs git hooks fallback. |
-| `ai-toolkit update --local` | current project | refresh those local project files |
+| `ai-toolkit install --local` | current project | Claude Code configs only (CLAUDE.md, settings, constitution, language rules). Add `--editors all` for other tools, or `--editors cursor,aider` for specific ones. Auto-detects editors from existing project files when `--editors` is omitted. |
+| `ai-toolkit install --local --lang <lang>` | current project | explicit language selection for rules (e.g. `--lang typescript`, `--lang go,python`); auto-detected when omitted |
+| `ai-toolkit install --modules <list>` | `~/.claude/` | selective module install (e.g. `--modules core,agents,rules-typescript`) |
+| `ai-toolkit update --local` | current project | refresh project configs; auto-detects editors from existing files |
 | `ai-toolkit add-rule` | `~/.ai-toolkit/rules/` | register a global rule |
 | `ai-toolkit remove-rule` | `~/.ai-toolkit/rules/` | unregister a global rule |
 
@@ -2836,6 +3146,8 @@ These files still stay local to a repository:
 - `.clinerules`
 - `.roomodes`
 - `.aider.conf.yml`
+- `.augment/rules/ai-toolkit-*.md`
+- `.agent/rules/*.md` and `.agent/workflows/*.md` (Google Antigravity)
 - `.git/hooks/pre-commit` (fallback)
 - project-specific documentation or safety overlays
 
@@ -3060,9 +3372,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.1.0"
+version: "1.4.2"
 created: "2026-03-27"
-last_updated: "2026-04-07"
+last_updated: "2026-04-09"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -3437,7 +3749,7 @@ Set in `.claude/settings.local.json`:
 
 **Hook script not found:**
 ```bash
-ls ~/.ai-toolkit/hooks/     # should list 12 .sh files (plus _profile-check.sh helper)
+ls ~/.ai-toolkit/hooks/     # should list 21 .sh files (plus _profile-check.sh helper)
 ai-toolkit update            # re-copies scripts
 ```
 
@@ -4426,9 +4738,9 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.4.0"
+version: "1.4.2"
 created: "2026-03-23"
-last_updated: "2026-04-08"
+last_updated: "2026-04-09"
 description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
 ---
 
@@ -4444,7 +4756,7 @@ All functionality is unified under skills. Task and hybrid skills are user-invoc
 | **2 — Multi-agent workflow** | `/workflow <type>` | Cross-cutting task with known pattern |
 | **3 — Custom parallelism** | `/orchestrate`, `/swarm` | No predefined workflow matches |
 
-## Task Skills (28)
+## Task Skills (29)
 
 Task skills execute a specific action. Invoked via slash commands. `disable-model-invocation: true`.
 
@@ -4478,6 +4790,7 @@ Task skills execute a specific action. Invoked via slash commands. `disable-mode
 | **health** | `/health` | medium | Check health of project services (auto-detect) |
 | **prd-to-issues** | `/prd-to-issues` | medium | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
 | **skill-audit** | `/skill-audit` | medium | Scan skills and agents for security risks: dangerous patterns, secrets, excessive permissions |
+| **hipaa-validate** | `/hipaa-validate` | medium | Scan codebase for HIPAA compliance issues: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references |
 
 ## Hybrid Skills (31)
 

package/llms.txt

@@ -15,6 +15,7 @@
 - [No Hardcoded Counts in Secondary Docs](kb/best-practices/no-hardcoded-counts.md)
 - [How-To Guides](kb/howto/README.md)
 - [SOP: Claude Toolkit Maintenance](kb/procedures/maintenance-sop.md)
+- [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
 - [SOP: Release Verification](kb/procedures/release-verification-sop.md)
 - [Agents Catalog](kb/reference/agents-catalog.md)
 - [Anti-Pattern Registry Format](kb/reference/anti-pattern-registry-format.md)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.2",
+  "version": "1.5.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "1.4.2",
-  "description": "Professional-grade AI coding toolkit: 91 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
+  "version": "1.5.1",
+  "description": "Professional-grade AI coding toolkit: 92 skills, 44 agents, multi-platform support (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, Google Antigravity), machine-enforced safety constitution, persona presets, skill security auditor, expanded lifecycle hooks, 11 plugin packs, and benchmark tooling.",
   "keywords": [
     "claude",
     "claude-code",

package/scripts/install.py

@@ -257,6 +257,56 @@ def parse_args(argv: list[str]) -> dict:
     return cfg
 
 
+# ---------------------------------------------------------------------------
+# Input validation
+# ---------------------------------------------------------------------------
+
+VALID_COMPONENTS = {"agents", "skills", "hooks", "rules", "constitution", "architecture"}
+VALID_LANGS = {"python", "typescript", "golang", "go", "rust", "java", "kotlin",
+               "swift", "ruby", "php", "dart", "cpp", "csharp", "c++", "c#", "cs",
+               "common"}
+
+
+def validate_args(cfg: dict) -> None:
+    """Validate parsed arguments — exit non-zero on invalid values."""
+    from install_steps.ai_tools import ALL_EDITORS
+
+    errors: list[str] = []
+
+    # Validate --only components
+    if cfg["only"]:
+        for c in cfg["only"].split(","):
+            c = c.strip()
+            if c and c not in VALID_COMPONENTS:
+                errors.append(f"Unknown component in --only: '{c}' (valid: {', '.join(sorted(VALID_COMPONENTS))})")
+
+    # Validate --skip components
+    if cfg["skip"]:
+        for c in cfg["skip"].split(","):
+            c = c.strip()
+            if c and c not in VALID_COMPONENTS:
+                errors.append(f"Unknown component in --skip: '{c}' (valid: {', '.join(sorted(VALID_COMPONENTS))})")
+
+    # Validate --editors
+    if cfg["editors"] and cfg["editors"] != "all":
+        for e in cfg["editors"].split(","):
+            e = e.strip()
+            if e and e not in ALL_EDITORS:
+                errors.append(f"Unknown editor: '{e}' (valid: {', '.join(ALL_EDITORS)}, all)")
+
+    # Validate --lang
+    if cfg["lang"]:
+        for l in cfg["lang"].split(","):
+            l = l.strip()
+            if l and l.lower() not in VALID_LANGS:
+                errors.append(f"Unknown language: '{l}' (valid: {', '.join(sorted(VALID_LANGS - {'c++', 'c#', 'cs', 'go', 'common'}))})")
+
+    if errors:
+        for e in errors:
+            print(f"Error: {e}")
+        sys.exit(1)
+
+
 # ---------------------------------------------------------------------------
 # Dependency check
 # ---------------------------------------------------------------------------
@@ -408,6 +458,7 @@ def _get_toolkit_version() -> str:
 
 def main() -> None:
     cfg = parse_args(sys.argv[1:])
+    validate_args(cfg)
 
     # Handle --status early exit
     if cfg["status"]: