@softspark/ai-toolkit 1.2.0 → 1.3.0

package/kb/reference/extension-api.md

@@ -0,0 +1,175 @@
+---
+title: "Extension API Reference"
+category: reference
+service: ai-toolkit
+tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration]
+version: "1.3.0"
+created: "2026-04-07"
+last_updated: "2026-04-07"
+description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and mcp template management."
+---
+
+# Extension API Reference
+
+## Overview
+
+ai-toolkit exposes a generic extension API that lets external tools register their own rules and hooks alongside the toolkit's built-in components. The toolkit has no knowledge of any specific consumer — it only provides the injection mechanism. Consumers call the public CLI commands from their own install scripts.
+
+This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP servers, CI systems, custom tools) use the public API to add their own rules and hooks without modifying toolkit internals.
+
+## Commands
+
+| Command | Target File | Mechanism | Idempotent |
+|---------|-------------|-----------|------------|
+| `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
+| `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
+| `inject-hook <file.json>` | `~/.claude/settings.json` | JSON `_source` tag per entry | Yes |
+| `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source` | Yes |
+| `add-rule <file.md>` | `~/.ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
+| `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
+
+## inject-rule
+
+Injects a Markdown rules file into `~/.claude/CLAUDE.md` between named HTML comment markers.
+
+```bash
+npx @softspark/ai-toolkit inject-rule ./my-tool-rules.md
+```
+
+**Implementation:** `scripts/inject_rule_cli.py` (delegates to `inject_section_cli.py`).
+
+**Markers written:**
+```html
+<!-- TOOLKIT:my-tool-rules START -->
+... content of my-tool-rules.md ...
+<!-- TOOLKIT:my-tool-rules END -->
+```
+
+The block name is derived from the file stem (`my-tool-rules.md` → `my-tool-rules`). Re-running replaces the existing block — no duplicates. Content outside these markers is never modified.
+
+## remove-rule
+
+Strips a previously injected rule block from `~/.claude/CLAUDE.md`.
+
+```bash
+npx @softspark/ai-toolkit remove-rule my-tool-rules
+```
+
+The argument is the block name (file stem used during `inject-rule`). If the block is not present, the command exits 0 silently.
+
+## inject-hook
+
+Injects hook entries from a JSON file into `~/.claude/settings.json`. Every injected entry is tagged with `"_source": "<source-name>"` where the source name is derived from the filename stem.
+
+```bash
+npx @softspark/ai-toolkit inject-hook ./my-tool-hooks.json
+```
+
+**Implementation:** `scripts/inject_hook_cli.py`.
+
+**Input format:**
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "$HOME/.my-tool/hooks/on-start.sh" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{ "type": "command", "command": "$HOME/.my-tool/hooks/on-edit.sh" }]
+      }
+    ]
+  }
+}
+```
+
+**Source name derivation:** `my-tool-hooks.json` → source name `"my-tool-hooks"`. All entries are tagged `"_source": "my-tool-hooks"` in settings.json.
+
+**Idempotency:** Re-running strips all existing entries with the same source name, then appends the new ones. No duplicates accumulate.
+
+**Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or removed by this command. External tools cannot affect the toolkit's own hooks.
+
+## remove-hook
+
+Strips all hook entries from `~/.claude/settings.json` that carry a given `_source` tag.
+
+```bash
+npx @softspark/ai-toolkit remove-hook my-tool-hooks
+```
+
+The argument is the source name (file stem used during `inject-hook`). If no entries with that source are present, the command exits 0 silently.
+
+## mcp add
+
+Merges one or more MCP server templates from `app/mcp-templates/` into the project's `.mcp.json`.
+
+```bash
+ai-toolkit mcp add github                # add a single template
+ai-toolkit mcp add github postgres slack  # add multiple at once
+ai-toolkit mcp list                       # list all available templates
+ai-toolkit mcp show github                # print a template's JSON
+ai-toolkit mcp remove github             # remove an entry from .mcp.json
+```
+
+**Implementation:** `scripts/mcp_manager.py`.
+
+The `add` command merges the `mcpServers` block from the template into `.mcp.json`. If `.mcp.json` does not exist, it is created. If the server name already exists, the entry is overwritten. See [mcp-templates.md](mcp-templates.md) for the full list of available templates.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   ai-toolkit (generic)               │
+│                                                      │
+│  Public Extension API:                               │
+│    inject-rule  <file.md>     → CLAUDE.md            │
+│    remove-rule  <name>        → CLAUDE.md            │
+│    inject-hook  <file.json>   → settings.json        │
+│    remove-hook  <name>        → settings.json        │
+│    add-rule     <file.md>     → rules/ registry      │
+│    mcp add      <template>    → .mcp.json            │
+│                                                      │
+│  Idempotent: markers (rules) / _source tags (hooks)  │
+│  ai-toolkit NEVER calls external services            │
+└──────────────────────────────────────────────────────┘
+                        ▲
+                        │ uses API
+        ┌───────────────┼───────────────┐
+        │               │               │
+   rag-mcp          custom-tool     ci-system
+   (consumer)       (consumer)      (consumer)
+```
+
+## Example: Registering Rules and Hooks from an External Tool
+
+An external tool's install script would call:
+
+```bash
+# Register rules into CLAUDE.md
+npx @softspark/ai-toolkit inject-rule ./rules/my-tool-rules.md
+
+# Register hooks into settings.json
+npx @softspark/ai-toolkit inject-hook ./hooks/my-tool-hooks.json
+
+# Add an MCP server template
+npx @softspark/ai-toolkit mcp add github
+```
+
+To uninstall:
+
+```bash
+npx @softspark/ai-toolkit remove-rule my-tool-rules
+npx @softspark/ai-toolkit remove-hook my-tool-hooks
+```
+
+All operations are idempotent — safe to run on every install or update.
+
+## Related Documentation
+
+- [PATH: kb/reference/hooks-catalog.md] — built-in hooks reference
+- [PATH: kb/reference/mcp-templates.md] — available MCP server templates
+- [PATH: kb/reference/architecture-overview.md] — overall install model

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.0.0"
+version: "1.1.0"
 created: "2026-03-27"
-last_updated: "2026-04-02"
+last_updated: "2026-04-07"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -13,7 +13,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-ai-toolkit provides 15 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.ai-toolkit/hooks/`.
+ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.ai-toolkit/hooks/`.
 
 ## Installation
 
@@ -231,6 +231,76 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 **Action:** Reminds teammate to verify: files modified, tests written, docs updated.
 
+---
+
+## New Hooks (v1.1.0)
+
+### PreToolUse (config guard) — `guard-config.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PreToolUse` |
+| Matcher | `Edit\|Write\|MultiEdit` |
+| Script | `~/.ai-toolkit/hooks/guard-config.sh` |
+| Fires | Before any file write/edit operation |
+
+**Action:** Blocks (exit 2) edits to linter and formatter config files — `.eslintrc`, `.eslintrc.*`, `eslint.config.*`, `.prettierrc`, `.prettierrc.*`, `prettier.config.*`, `tsconfig.json`, `tsconfig.*.json` — unless the request contains an explicit acknowledgment phrase (e.g. "intentionally editing config"). Returns a human-readable explanation to Claude so it can ask the user for confirmation before retrying.
+
+### SessionStart — `mcp-health.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `SessionStart` |
+| Matcher | *(all)* |
+| Script | `~/.ai-toolkit/hooks/mcp-health.sh` |
+| Fires | Session start |
+
+**Action:** Non-blocking (always exits 0). Reads MCP server definitions from `~/.claude/settings.json` and any local `.mcp.json`. For each configured server, checks whether the required runtime command (`npx`, `uvx`, `docker`, etc.) is available in `$PATH`. Emits warnings for any missing runtimes, including install hints (e.g. "npm install -g npx"). Helps surface MCP misconfiguration early without interrupting the session.
+
+### PostToolUse (governance) — `governance-capture.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | *(all)* |
+| Script | `~/.ai-toolkit/hooks/governance-capture.sh` |
+| Fires | After any tool use |
+
+**Action:** Non-blocking (always exits 0). Logs security-sensitive operations (Bash commands, file writes to sensitive paths, large writes) to `~/.ai-toolkit/governance.log` with ISO timestamp, session ID, tool name, and a content excerpt. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### PreCompact — `pre-compact-save.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PreCompact` |
+| Matcher | *(all)* |
+| Script | `~/.ai-toolkit/hooks/pre-compact-save.sh` |
+| Fires | Before context compaction |
+
+**Action:** Saves a timestamped context snapshot to `~/.ai-toolkit/compactions/YYYY-MM-DD_HH-MM-SS.txt`. Captures session ID, working directory, git branch and status, and environment metadata. Provides an audit trail of what was in context at each compaction point. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
+### PreToolUse (commit quality) — `commit-quality.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PreToolUse` |
+| Matcher | `Bash` |
+| Script | `~/.ai-toolkit/hooks/commit-quality.sh` |
+| Fires | Before any Bash command |
+
+**Action:** Non-blocking (always exits 0). Inspects Bash commands containing `git commit`. Extracts the commit message from the `-m` flag and checks it against Conventional Commits format (`type: description`, where type is one of feat/fix/docs/refactor/test/chore/ci/perf/style/revert). Emits an advisory warning if the message does not match — the commit is not blocked, only nudged. Commands without `git commit` or without a `-m` message (e.g. interactive commits) are ignored.
+
+### SessionStart — `session-context.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `SessionStart` |
+| Matcher | *(all)* |
+| Script | `~/.ai-toolkit/hooks/session-context.sh` |
+| Fires | Session start |
+
+**Action:** Captures an environment snapshot to `~/.ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
 ## Runtime Profiles
 
 Set in `.claude/settings.local.json`:
@@ -253,10 +323,14 @@ Set in `.claude/settings.local.json`:
 └── hooks/          # Hook scripts (copied on install)
     ├── _profile-check.sh    # Shared: profile skip logic (sourced by hooks)
     ├── session-start.sh
+    ├── session-context.sh   # NEW: capture session env snapshot
     ├── guard-destructive.sh
     ├── guard-path.sh
+    ├── guard-config.sh      # NEW: block config file edits
+    ├── mcp-health.sh        # NEW: check MCP runtime availability
     ├── user-prompt-submit.sh
     ├── post-tool-use.sh
+    ├── governance-capture.sh # NEW: log security-sensitive operations
     ├── quality-check.sh
     ├── quality-gate.sh
     ├── save-session.sh
@@ -264,22 +338,24 @@ Set in `.claude/settings.local.json`:
     ├── subagent-stop.sh
     ├── track-usage.sh
     ├── pre-compact.sh
+    ├── pre-compact-save.sh  # NEW: timestamped context snapshot
+    ├── commit-quality.sh    # NEW: advisory commit message check
     └── session-end.sh
 
 ~/.claude/settings.json
 └── hooks:          # Hook definitions referencing ~/.ai-toolkit/hooks/
-    ├── SessionStart → session-start.sh
-    ├── Notification → osascript (inline)
-    ├── PreToolUse   → guard-destructive.sh, guard-path.sh
+    ├── SessionStart     → session-start.sh, mcp-health.sh, session-context.sh
+    ├── Notification     → osascript (inline)
+    ├── PreToolUse       → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh
     ├── UserPromptSubmit → user-prompt-submit.sh, track-usage.sh
-    ├── PostToolUse  → post-tool-use.sh
-    ├── Stop         → quality-check.sh, save-session.sh
-    ├── TaskCompleted → quality-gate.sh
-    ├── TeammateIdle → echo (inline)
-    ├── SubagentStart → subagent-start.sh
-    ├── SubagentStop  → subagent-stop.sh
-    ├── PreCompact    → pre-compact.sh
-    └── SessionEnd    → session-end.sh
+    ├── PostToolUse      → post-tool-use.sh, governance-capture.sh
+    ├── Stop             → quality-check.sh, save-session.sh
+    ├── TaskCompleted    → quality-gate.sh
+    ├── TeammateIdle     → echo (inline)
+    ├── SubagentStart    → subagent-start.sh
+    ├── SubagentStop     → subagent-stop.sh
+    ├── PreCompact       → pre-compact.sh, pre-compact-save.sh
+    └── SessionEnd       → session-end.sh
 ```
 
 **Key design decisions:**

package/kb/reference/language-rules.md

@@ -0,0 +1,167 @@
+---
+title: "Language Rules System"
+category: reference
+service: ai-toolkit
+tags: [rules, languages, coding-style, testing, patterns, security]
+version: "1.0.0"
+created: "2026-04-07"
+last_updated: "2026-04-07"
+description: "Reference for the language-specific rules system: 13 languages, 5 categories per language, auto-detection."
+---
+
+# Language Rules System
+
+## Overview
+
+ai-toolkit ships 70 language-specific rule files covering 13 programming languages plus a common set. Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
+
+Rules are distinct from skills: rules are injected as static text into `CLAUDE.md` and are always visible to Claude, whereas skills are loaded contextually by agents.
+
+## File Structure
+
+```
+app/rules/
+├── common/
+│   ├── coding-style.md     # KISS, DRY, YAGNI, immutability
+│   ├── testing.md          # Universal testing standards
+│   ├── git-workflow.md     # Commit conventions
+│   ├── performance.md      # Performance guidelines
+│   └── security.md         # OWASP, input validation
+├── typescript/
+│   ├── coding-style.md     # Strict mode, no-any, naming
+│   ├── testing.md          # Vitest/Jest patterns
+│   ├── patterns.md         # Discriminated unions, utility types
+│   ├── frameworks.md       # React hooks, Next.js, lifecycle
+│   └── security.md         # XSS prevention, sanitization
+├── python/
+│   ├── coding-style.md     # PEP 8, type hints, dataclasses
+│   ├── testing.md          # pytest, fixtures, parametrize
+│   ├── patterns.md         # Python idioms, context managers
+│   ├── frameworks.md       # FastAPI/Django lifecycle, SQLAlchemy
+│   └── security.md         # SQL injection, SSTI prevention
+├── golang/           # same 5-file structure
+├── rust/
+├── java/
+├── kotlin/
+├── swift/
+├── dart/
+├── csharp/
+├── php/
+├── cpp/
+└── ruby/
+```
+
+**Total: 13 languages × 5 files + 5 common = 70 rule files**
+
+## Supported Languages
+
+| Language | Directory | Auto-detect Files |
+|----------|-----------|------------------|
+| Common | `rules/common/` | always included |
+| TypeScript | `rules/typescript/` | `package.json`, `tsconfig.json` |
+| Python | `rules/python/` | `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` |
+| Go | `rules/golang/` | `go.mod` |
+| Rust | `rules/rust/` | `Cargo.toml` |
+| Java | `rules/java/` | `pom.xml`, `build.gradle`, `build.gradle.kts` |
+| Kotlin | `rules/kotlin/` | `build.gradle.kts` |
+| Swift | `rules/swift/` | `Package.swift`, `*.xcodeproj` |
+| Dart | `rules/dart/` | `pubspec.yaml` |
+| C# | `rules/csharp/` | `*.csproj`, `*.sln` |
+| PHP | `rules/php/` | `composer.json` |
+| C++ | `rules/cpp/` | `CMakeLists.txt`, `Makefile`, `*.cpp` |
+| Ruby | `rules/ruby/` | `Gemfile`, `*.gemspec` |
+
+## Rule Categories
+
+| Category | Filename | Content |
+|----------|----------|---------|
+| `coding-style` | `coding-style.md` | Naming, formatting, idiomatic constructs, linter config |
+| `testing` | `testing.md` | Test framework usage, fixture patterns, coverage targets |
+| `patterns` | `patterns.md` | Language-specific design patterns and idioms |
+| `frameworks` | `frameworks.md` | Recommended framework conventions and lifecycle hooks |
+| `security` | `security.md` | Common language-specific vulnerabilities and mitigations |
+
+The `common/` directory uses the same structure except `frameworks.md` is replaced by `git-workflow.md` and `performance.md`.
+
+## Auto-Detection
+
+When `--auto-detect` is passed, `scripts/install_steps/detect_language.py` scans the current directory for known marker files and selects the matching language module:
+
+```bash
+ai-toolkit install --local --auto-detect
+```
+
+Detection logic (first match wins when multiple markers are present):
+1. `package.json` or `tsconfig.json` → TypeScript
+2. `go.mod` → Go
+3. `Cargo.toml` → Rust
+4. `pubspec.yaml` → Dart
+5. `composer.json` → PHP
+6. `Gemfile` → Ruby
+7. `requirements.txt`, `pyproject.toml`, `setup.py`, or `Pipfile` → Python
+8. `pom.xml` or `build.gradle` → Java
+9. `build.gradle.kts` → Kotlin
+10. `Package.swift` → Swift
+11. `*.csproj` or `*.sln` → C#
+12. `CMakeLists.txt` or `Makefile` → C++
+
+Common rules are always injected regardless of detected language.
+
+## Installation
+
+```bash
+# Auto-detect language from project files
+ai-toolkit install --local --auto-detect
+
+# Explicitly select a language
+ai-toolkit install --local --lang typescript
+
+# Install without language rules
+ai-toolkit install --local
+```
+
+Language rules are injected into the project `CLAUDE.md` between named markers:
+
+```
+<!-- TOOLKIT:rules-typescript START -->
+... TypeScript rules content ...
+<!-- TOOLKIT:rules-typescript END -->
+```
+
+Re-running `install --local` is idempotent — existing blocks are replaced, not duplicated.
+
+## Manifest Module Names
+
+Language rules are tracked as modules in `manifest.json`:
+
+| Module | Description |
+|--------|-------------|
+| `rules-common` | Common coding rules (5 files), included in `standard` profile |
+| `rules-typescript` | TypeScript-specific rules |
+| `rules-python` | Python-specific rules |
+| `rules-golang` | Go-specific rules |
+| `rules-rust` | Rust-specific rules |
+| `rules-java` | Java-specific rules |
+| `rules-kotlin` | Kotlin-specific rules |
+| `rules-swift` | Swift-specific rules |
+| `rules-dart` | Dart/Flutter-specific rules |
+| `rules-csharp` | C#/.NET-specific rules |
+| `rules-php` | PHP-specific rules |
+| `rules-cpp` | C++-specific rules |
+| `rules-ruby` | Ruby-specific rules |
+
+## Rules vs Skills
+
+| | Rules | Skills |
+|---|-------|--------|
+| Location | `app/rules/` | `app/skills/` |
+| Delivery | Injected into `CLAUDE.md` text | Loaded from `~/.claude/skills/` |
+| Visibility | Always visible in context | Loaded contextually by agents |
+| Scope | Per-language static guidance | Domain-specific agent behavior |
+| Install | `--local` only | Global install |
+
+## Related Documentation
+
+- [PATH: kb/reference/manifest-install.md] — module-level install granularity
+- [PATH: kb/reference/extension-api.md] — injecting rules from external tools
+- [PATH: kb/reference/architecture-overview.md] — overall install model

package/kb/reference/manifest-install.md

@@ -0,0 +1,165 @@
+---
+title: "Manifest-Driven Install System"
+category: reference
+service: ai-toolkit
+tags: [install, manifest, modules, profiles, auto-detect, state-tracking]
+version: "1.0.0"
+created: "2026-04-07"
+last_updated: "2026-04-07"
+description: "Reference for the manifest-driven install system: 17 modules, 4 profiles, auto-detection, and state tracking in ~/.ai-toolkit/state.json."
+---
+
+# Manifest-Driven Install System
+
+## Overview
+
+ai-toolkit's install system supports module-level granularity on top of the existing profile-based install. Instead of choosing only between minimal/standard/strict, you can select individual modules (specific language rules, MCP templates, etc.) or enable auto-detection of the project language.
+
+All existing `--profile` behavior is preserved and unchanged. The manifest system is an additive opt-in layer.
+
+## Modules
+
+Modules are defined in `manifest.json` at the repository root. There are 17 modules:
+
+| Module | Description | In Profile |
+|--------|-------------|-----------|
+| `core` | Core hooks and essential skills | minimal, standard, strict, full |
+| `agents` | 47 specialized agents | standard, strict, full |
+| `skills` | 90 skills (task, hybrid, knowledge) | standard, strict, full |
+| `rules-common` | Common coding rules (5 files) | standard, strict, full |
+| `rules-typescript` | TypeScript-specific rules (5 files) | auto-detect |
+| `rules-python` | Python-specific rules (5 files) | auto-detect |
+| `rules-golang` | Go-specific rules (5 files) | auto-detect |
+| `rules-rust` | Rust-specific rules (5 files) | auto-detect |
+| `rules-java` | Java-specific rules (5 files) | auto-detect |
+| `rules-kotlin` | Kotlin-specific rules (5 files) | auto-detect |
+| `rules-swift` | Swift-specific rules (5 files) | auto-detect |
+| `rules-dart` | Dart/Flutter-specific rules (5 files) | auto-detect |
+| `rules-csharp` | C#/.NET-specific rules (5 files) | auto-detect |
+| `rules-php` | PHP-specific rules (5 files) | auto-detect |
+| `rules-cpp` | C++-specific rules (5 files) | auto-detect |
+| `rules-ruby` | Ruby-specific rules (5 files) | auto-detect |
+| `mcp-templates` | 25 MCP server config templates | strict, full |
+
+## Profiles
+
+Profiles are predefined module sets. They map directly to `--profile` values:
+
+| Profile | Modules |
+|---------|---------|
+| `minimal` | `core` |
+| `standard` | `core`, `agents`, `skills`, `rules-common` |
+| `strict` | `core`, `agents`, `skills`, `rules-common`, `mcp-templates` |
+| `full` | All modules (same as strict currently; language rules added via `--auto-detect`) |
+
+## CLI
+
+```bash
+# Profile-based install (existing behavior, unchanged)
+ai-toolkit install --profile standard
+
+# Module-based install (new)
+ai-toolkit install --modules core,agents,rules-typescript
+
+# Auto-detect project language and install matching rules
+ai-toolkit install --local --auto-detect
+
+# Show currently installed modules and their state
+ai-toolkit status
+
+# Incremental update (only re-applies modules with changed content)
+ai-toolkit update
+```
+
+### --modules
+
+Accepts a comma-separated list of module names. Can be combined with a profile:
+
+```bash
+# Start from standard profile, also add TypeScript rules
+ai-toolkit install --profile standard --modules rules-typescript
+```
+
+### --auto-detect
+
+Scans the current working directory for marker files and selects the matching language module. Implemented in `scripts/install_steps/detect_language.py`.
+
+Detection markers per module:
+
+| Module | Detected when these files exist |
+|--------|--------------------------------|
+| `rules-typescript` | `package.json` or `tsconfig.json` |
+| `rules-python` | `requirements.txt`, `pyproject.toml`, `setup.py`, or `Pipfile` |
+| `rules-golang` | `go.mod` |
+| `rules-rust` | `Cargo.toml` |
+| `rules-java` | `pom.xml` or `build.gradle` |
+| `rules-kotlin` | `build.gradle.kts` |
+| `rules-swift` | `Package.swift` |
+| `rules-dart` | `pubspec.yaml` |
+| `rules-csharp` | `*.csproj` or `*.sln` |
+| `rules-php` | `composer.json` |
+| `rules-cpp` | `CMakeLists.txt` or `Makefile` |
+| `rules-ruby` | `Gemfile` |
+
+### status
+
+Lists all currently installed modules with version and install timestamp:
+
+```bash
+ai-toolkit status
+# Installed modules (from ~/.ai-toolkit/state.json):
+#   core            v1.3.0   installed 2026-04-07T10:00:00Z
+#   agents          v1.3.0   installed 2026-04-07T10:00:00Z
+#   skills          v1.3.0   installed 2026-04-07T10:00:00Z
+#   rules-common    v1.3.0   installed 2026-04-07T10:00:00Z
+#   rules-typescript v1.3.0  installed 2026-04-07T10:00:00Z
+```
+
+### update
+
+Re-applies installed modules, skipping files whose content hash has not changed since last install. Implemented in `scripts/install_steps/install_state.py`.
+
+## State Tracking
+
+Installed module state is persisted to `~/.ai-toolkit/state.json`:
+
+```json
+{
+  "installed_version": "1.3.0",
+  "installed_modules": ["core", "agents", "skills", "rules-common", "rules-typescript"],
+  "installed_at": "2026-04-07T10:00:00Z",
+  "last_updated": "2026-04-07T10:00:00Z",
+  "file_hashes": {
+    "app/hooks/session-start.sh": "abc123..."
+  }
+}
+```
+
+- `installed_modules` — used by `update` to know which modules to re-apply
+- `file_hashes` — used to skip unchanged files during `update`
+- The file is written after every successful install or update
+
+## Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `manifest.json` | Module and profile definitions |
+| `scripts/install_steps/detect_language.py` | Auto-detect project language from marker files |
+| `scripts/install_steps/install_state.py` | Read/write `~/.ai-toolkit/state.json` |
+
+## Backward Compatibility
+
+Existing `--profile` usage works identically. The manifest system does not change what gets installed when you use `--profile minimal/standard/strict`. It only adds:
+
+1. `--modules` for granular selection
+2. `--auto-detect` for language rules
+3. `state.json` tracking for incremental updates
+4. `status` command to inspect installed state
+
+No existing install scripts or CI configurations need changes.
+
+## Related Documentation
+
+- [PATH: kb/reference/language-rules.md] — language rules structure and auto-detection detail
+- [PATH: kb/reference/mcp-templates.md] — MCP server templates (the `mcp-templates` module)
+- [PATH: kb/reference/architecture-overview.md] — overall install model