@softspark/ai-toolkit 1.3.14 → 1.4.0

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 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)
 - [AI Toolkit Architecture](kb/reference/architecture-overview.md)
@@ -575,6 +576,294 @@ What `uninstall` does:
 
 ---
 
+## kb/procedures/release-verification-sop.md
+
+---
+title: "SOP: Release Verification"
+category: procedures
+service: ai-toolkit
+tags: [sop, verification, release, smoke-test, install, update, qa]
+version: "1.1.0"
+created: "2026-04-08"
+last_updated: "2026-04-08"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, and eject from user perspective."
+---
+
+# SOP: Release Verification
+
+End-to-end smoke test after installing or updating `@softspark/ai-toolkit`.
+Verifies all critical paths from the user's perspective.
+
+**Use this SOP when:**
+- After `npm install -g @softspark/ai-toolkit@latest`
+- After `ai-toolkit update`
+- Before tagging a new version (`git tag`)
+- Before publishing to npm (`npm publish`)
+- As a smoke test in CI/CD
+
+**Prerequisites:**
+- Node.js >= 18, Python 3, `bats`, git
+- `@softspark/ai-toolkit` installed globally
+
+**Time:** 10-15 minutes (full), 2 minutes (quick checklist)
+
+---
+
+## Quick Checklist (TL;DR)
+
+9 commands — if all pass, the release is ready:
+
+```bash
+# Pre-commit (Phase 0)
+python3 scripts/generate_agents_md.py > AGENTS.md   # 1. Regenerate artifacts
+python3 scripts/generate_llms_txt.py > llms.txt      # 2. Regenerate llms.txt
+python3 scripts/validate.py --strict                 # 3. Validation passed?
+npm test                                             # 4. All tests passed?
+
+# Post-install verification (Phases 1-7)
+ai-toolkit --version                                 # 5. Version OK?
+ai-toolkit status                                    # 6. Status OK?
+ai-toolkit doctor                                    # 7. Health check passed?
+ai-toolkit install --dry-run                         # 8. Global install OK?
+python3 scripts/audit_skills.py --ci                 # 9. Security audit clean?
+```
+
+---
+
+## Phase 0: Pre-Commit & Pre-Push (2 min)
+
+Run these commands **before every commit and push to main**. CI validates
+counts but does NOT auto-regenerate — you must do it locally.
+
+```bash
+# 1. Regenerate generated 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
+
+# 2. Validate everything (catches stale counts, missing assets)
+python3 scripts/validate.py --strict
+
+# 3. Security audit
+python3 scripts/audit_skills.py --ci
+
+# 4. Run tests
+npm test
+
+# 5. Stage and commit
+git add AGENTS.md llms.txt llms-full.txt
+git add -p  # stage your other changes
+git commit -m "feat: your change description"
+```
+
+**Why local?** Branch protection on `main` requires PRs and status checks.
+CI cannot push directly to `main`, so generated artifacts must be committed
+by the developer as part of their PR.
+
+**One-liner (copy-paste):**
+```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 && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+```
+
+---
+
+## Phase 1: CLI & Version (1 min)
+
+```bash
+ai-toolkit --version
+ai-toolkit --help
+which ai-toolkit
+```
+
+**Verify:**
+- [ ] `--version` returns correct semver (e.g., `1.4.0`)
+- [ ] `--help` displays full command list without errors
+- [ ] `which` points to global npm bin path
+
+---
+
+## Phase 2: Global Install & Status (2 min)
+
+```bash
+ai-toolkit install --dry-run
+ai-toolkit status
+```
+
+**Verify `--dry-run`:**
+- [ ] Agents >= 40
+- [ ] Skills >= 80
+- [ ] Hooks merged into settings.json
+- [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
+
+**Verify `status`:**
+- [ ] Version matches expected
+- [ ] Profile: minimal/standard/strict
+- [ ] Modules: list of installed modules
+- [ ] Latest: up to date / update available
+
+---
+
+## Phase 3: Doctor Health Check (1 min)
+
+```bash
+ai-toolkit doctor
+```
+
+**Expected sections (all OK):**
+- Environment: node, bash, python3, bats
+- Global Install: .claude exists, agents/skills symlinks (0 broken), settings.json hooks
+- Hook Scripts: all present and executable
+- Hook Configuration: 12 events registered
+- Generated Artifacts: AGENTS.md, llms.txt, llms-full.txt
+- Planned Assets: plugin.json, benchmarks, plugin packs
+- Benchmark Freshness: < 30 days
+- Stale Rules: all healthy
+
+**Verify:**
+- [ ] `Errors: 0 | Warnings: 0`
+- [ ] `HEALTH CHECK PASSED`
+
+If doctor detects problems: `ai-toolkit doctor --fix` auto-repairs
+(broken symlinks, non-executable hooks, missing scripts, missing llms-full.txt).
+
+---
+
+## Phase 4: Local Install (2 min)
+
+```bash
+mkdir -p /tmp/ai-toolkit-verify && cd /tmp/ai-toolkit-verify
+git init -q
+ai-toolkit install --local --editors all --dry-run
+cd - && rm -rf /tmp/ai-toolkit-verify
+```
+
+**Verify "Project-local" section:**
+- [ ] Would create: CLAUDE.md
+- [ ] Would create: .claude/settings.local.json
+- [ ] Would inject: .claude/constitution.md
+- [ ] Editors: all 8 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity)
+- [ ] Would generate configs for each editor (legacy + directory-based)
+- [ ] Would install: .git/hooks/pre-commit
+- [ ] Would inject language rules (auto-detected)
+
+**Also test auto-detect (no --editors flag):**
+```bash
+ai-toolkit install --local --dry-run
+# → Editors: none (empty project has no existing configs)
+```
+
+---
+
+## Phase 5: Validation & Security Audit (3 min)
+
+```bash
+python3 scripts/validate.py --strict
+python3 scripts/audit_skills.py --ci
+```
+
+**Verify validate.py:**
+- [ ] Agents >= 40, Skills >= 80, Tests >= 350
+- [ ] Hook events: 12, Hook scripts: >= 20
+- [ ] Plugin packs >= 10, KB documents >= 20
+- [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
+
+**Verify audit_skills.py:**
+- [ ] `HIGH: 0` (MUST be zero — CI fails otherwise)
+- [ ] `WARN: 0`
+- [ ] `INFO: N` (acceptable — broad-access skills: orchestrate, swarm, teams)
+
+---
+
+## Phase 6: Tests (3-5 min)
+
+```bash
+npm test
+```
+
+**Verify:**
+- [ ] Bats runs tests in parallel (4 jobs)
+- [ ] All `ok` — zero `not ok`
+- [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
+      install, kb, mcp, readme, profiles, uninstall, validate
+
+**Key test areas:**
+- Guards: rm -rf, DROP TABLE, git push --force blocked
+- Install: idempotent, profiles, --only/--skip, orphan cleanup
+- Eject: real files (not symlinks), inlined rules
+- Uninstall: removes toolkit, preserves user content
+
+---
+
+## Phase 7: Eject (1 min)
+
+```bash
+mkdir -p /tmp/ai-toolkit-eject-test
+cd /tmp/ai-toolkit-eject-test
+ai-toolkit eject
+cd - && rm -rf /tmp/ai-toolkit-eject-test
+```
+
+**Verify:**
+- [ ] Agents copied as real files (not symlinks)
+- [ ] Skills copied as real directories
+- [ ] Rules inlined into CLAUDE.md
+- [ ] constitution.md and ARCHITECTURE.md copied
+
+---
+
+## Troubleshooting
+
+### `ai-toolkit: command not found`
+
+```bash
+npm install -g @softspark/ai-toolkit
+# or check PATH:
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+### Doctor: broken symlinks
+
+```bash
+ai-toolkit doctor --fix    # auto-repair
+ai-toolkit update          # or full re-install
+```
+
+### Tests fail: missing bats
+
+```bash
+brew install bats-core     # macOS
+npm install -g bats        # cross-platform
+```
+
+### validate.py: stale counts
+
+README badges don't match the current agents/skills/tests counts.
+Update README.md and re-run.
+
+### Eject: missing skills
+
+```bash
+ai-toolkit update          # re-link missing symlinks
+ai-toolkit eject /tmp/test # retry
+```
+
+---
+
+## Success Criteria
+
+| Area | Criterion |
+|------|-----------|
+| CLI | `--version` correct, `--help` full list, `status` current |
+| Health | `doctor`: 0 errors, 0 warnings, PASSED |
+| Install | `--dry-run` correct counts, `--local` all configs |
+| Quality | `validate.py --strict`: PASSED |
+| Security | `audit_skills.py --ci`: 0 HIGH |
+| Tests | `npm test`: N/N passed, 0 failures |
+| Eject | Standalone .claude/ with real files |
+| Guards | Destructive commands blocked |
+
+---
+
 ## kb/reference/agents-catalog.md
 
 ---
@@ -934,7 +1223,7 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.3.14"
+version: "1.4.0"
 created: "2026-03-23"
 last_updated: "2026-04-08"
 description: "Architecture of ai-toolkit: directory layout, global install model, skill tiers, and integration with projects."
@@ -944,7 +1233,7 @@ description: "Architecture of ai-toolkit: directory layout, global install model
 
 ## Purpose
 
-Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, and Augment). Provides specialized agents, skills (slash commands + knowledge), expanded lifecycle hooks, persona presets, and experimental opt-in plugin packs that teams can adopt separately from the default global install.
+Shared, project-agnostic AI development toolkit for Claude Code (and compatible assistants like Cursor, Windsurf, Copilot, Gemini, Cline, Roo Code, Aider, Augment, and Google Antigravity). Provides specialized agents, skills (slash commands + knowledge), expanded lifecycle hooks, persona presets, and experimental opt-in plugin packs that teams can adopt separately from the default global install.
 
 ## Design Principles
 
@@ -1034,14 +1323,19 @@ Machine (global)                              Project (local)
 
 **`ai-toolkit update`** — re-apply after `npm install -g @softspark/ai-toolkit@latest` or after `add-rule` / `remove-rule`. Same as `install` but semantically correct for update flows.
 
-**`ai-toolkit install --local`** (or `update --local`) — run per project, creates `CLAUDE.md` template + `.claude/settings.local.json` (only if missing, initialized with MCP defaults), and injects `constitution.md` + Copilot + Cline + Roo Code + Aider configs into local `.claude/` (preserves existing user content). Installs `--local` git hooks as a fallback for quality gates. Hooks are global-only — not merged into project settings.
+**`ai-toolkit install --local`** — run per project. Always installs Claude Code configs (CLAUDE.md, settings.local.json, constitution.md, language rules). Editor configs are opt-in via `--editors`:
+- `--editors all` — install all 8 editors (Cursor, Windsurf, Cline, Roo, Aider, Augment, Copilot, Antigravity)
+- `--editors cursor,aider` — install only selected editors
+- (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
+
+Each editor gets both legacy single-file format (for backwards compat) and new directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.cline/rules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Hooks are global-only — not merged into project settings.
 
 ## CLI Commands
 
 | Command | Target | What it does |
 |---------|--------|-------------|
 | `install` | `~/.claude/` | First-time: per-file symlinks + JSON merge + marker injection + rules |
-| `install --local` | `./` | Also set up project-local: `CLAUDE.md` + `settings.local.json` + constitution + Copilot + Cline + Roo + Aider + Git Hooks (hooks stay global-only) |
+| `install --local` | `./` | Claude Code configs + editors via `--editors` (auto-detect or explicit) |
 | `update` | `~/.claude/` | Re-apply after npm update or after add-rule/remove-rule |
 | `update --local` | `./` | Re-apply + refresh project-local configs |
 | `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
@@ -1051,13 +1345,20 @@ Machine (global)                              Project (local)
 | `doctor` | toolkit | Install health, hooks, benchmark freshness, and artifact drift diagnostics |
 | `benchmark-ecosystem` | toolkit | Benchmark snapshot for official Claude Code and external ecosystem repos |
 | `evaluate` | toolkit | Skill quality report |
-| `cursor-rules` | `./` | Generates `.cursorrules` |
-| `windsurf-rules` | `./` | Generates `.windsurfrules` |
+| `cursor-rules` | `./` | Generates `.cursorrules` (legacy) |
+| `cursor-mdc` | `./` | Generates `.cursor/rules/*.mdc` (recommended) |
+| `windsurf-rules` | `./` | Generates `.windsurfrules` (legacy) |
+| `windsurf-dir-rules` | `./` | Generates `.windsurf/rules/*.md` |
 | `copilot-instructions` | `./` | Generates `.github/copilot-instructions.md` |
 | `gemini-md` | `./` | Generates `GEMINI.md` |
-| `cline-rules` | `./` | Generates `.clinerules` |
+| `cline-rules` | `./` | Generates `.clinerules` (legacy) |
+| `cline-dir-rules` | `./` | Generates `.cline/rules/*.md` |
 | `roo-modes` | `./` | Generates `.roomodes` |
+| `roo-dir-rules` | `./` | Generates `.roo/rules/*.md` |
 | `aider-conf` | `./` | Generates `.aider.conf.yml` |
+| `conventions-md` | `./` | Generates `CONVENTIONS.md` (Aider auto-loaded) |
+| `augment-dir-rules` | `./` | Generates `.augment/rules/ai-toolkit-*.md` |
+| `antigravity-rules` | `./` | Generates `.agent/rules/` + `.agent/workflows/` |
 | `agents-md` | toolkit | Regenerates `AGENTS.md` |
 | `llms-txt` | `./` | Generates `llms.txt` |
 | `generate-all` | `./` | Generates all platform configs at once |
@@ -1109,6 +1410,23 @@ Skills that spawn real parallel agents use:
 
 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` must be set for Agent Teams (tmux-based) support.
 
+## Quality Guardrails
+
+### Anti-Rationalization Tables
+15 core skills include `## Common Rationalizations` tables — domain-specific excuses with rebuttals that prevent agent drift. Skills: `/review`, `/debug`, `/refactor`, `/tdd`, `/plan`, `/docs`, `/analyze`, `security-patterns`, `testing-patterns`, `api-patterns`, `ci-cd-patterns`, `clean-code`, `performance-profiling`, `git-mastery`, `database-patterns`.
+
+### Confidence Scoring & LLM-as-Judge (`/review`)
+Review findings include per-issue confidence scores (1-10) and severity tiers (critical/major/minor/nit). A self-evaluation pass after review checks for anchoring bias, assumption vs verification, and calibrates confidence.
+
+### Agent Verification Checklists
+10 agents have `## Verification Checklist` — domain-specific exit criteria: `code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.
+
+### Skill Reference Routing
+7 core skills include `## Related Skills` suggesting follow-up skills: `/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.
+
+### Intent Capture Interview (`/onboard`)
+Step 0 interview — 5 questions to capture undocumented project intent before setup.
+
 ## Component Relationships
 
 ```
@@ -1557,15 +1875,15 @@ tags:
 doc_type: plan
 status: completed
 created: "2026-04-07"
-last_updated: "2026-04-07"
+last_updated: "2026-04-09"
 completion: "100%"
 description: "Implementation plan for features identified from competitive analysis of everything-claude-code and claude-mem. Focus on learning system, language rules, advanced hooks, MCP templates, and rag-mcp integration. COMPLETED: 8/9 features shipped (1 skipped). See kb/reference/ for permanent documentation."
 ---
 
 # Plan: Competitive Features — ai-toolkit
 
-**Status:** :yellow_circle: IN PROGRESS
-**Completion:** 100% (9/9 features)
+**Status:** :white_check_mark: COMPLETED
+**Completion:** 100% (8/9 features, 1 skipped)
 **Started:** 2026-04-07
 **Estimated Completion:** 2026-06-15
 **Source:** Competitive analysis of `affaan-m/everything-claude-code` (ECC) + `thedotmack/claude-mem`
@@ -1574,7 +1892,7 @@ description: "Implementation plan for features identified from competitive analy
 
 ## 1. Objective
 
-Strengthen ai-toolkit's competitive position by implementing 10 features from competitive analysis while maintaining our advantages (clean architecture, 9 editors, personas, safety constitution).
+Strengthen ai-toolkit's competitive position by implementing 10 features from competitive analysis while maintaining our advantages (clean architecture, 11 editors, personas, safety constitution).
 
 **Key design principle:** ai-toolkit is a **generic toolkit** — it does NOT know about rag-mcp or any specific consumer. Consumers (like rag-mcp) use ai-toolkit's public API (`inject-rule`, `inject-hook`, `merge-hooks`) to add their own rules and hooks.
 
@@ -1683,11 +2001,11 @@ app/rules/
 | `tests/test_rules.py` | CREATE | Tests |
 
 **Success Criteria:**
-- [ ] 13 languages × 5 rule files created
-- [ ] `ai-toolkit install --local` auto-detects language and injects rules
-- [ ] Manual override: `ai-toolkit install --local --lang typescript`
-- [ ] validate.py checks rules format
-- [ ] Tests: >=13 (one per language)
+- [x] 13 languages × 5 rule files created (70 files: 13 dirs × 5 + 5 common)
+- [x] `ai-toolkit install --local` auto-detects language and injects rules (two-phase: marker files + extension scan)
+- [x] Manual override: `ai-toolkit install --local --lang typescript` (with aliases: go→golang, c++→cpp, cs→csharp)
+- [ ] validate.py checks rules format (not yet implemented)
+- [ ] Tests: >=13 (no test_rules file yet)
 
 ---
 
@@ -1722,11 +2040,11 @@ app/rules/
 | `tests/test_hooks.py` | EDIT | Tests for new hooks |
 
 **Success Criteria:**
-- [ ] 6 new hooks created and registerable
-- [ ] guard-config blocks config edits unless `--force`
-- [ ] mcp-health pings configured MCP servers on session start
-- [ ] All hooks optional (enable/disable in settings.json)
-- [ ] Tests: >=6 (one per hook)
+- [x] 5/6 new hooks created and registerable (observe-session.sh not in app/hooks — lives in rag-mcp as consumer)
+- [x] guard-config blocks config edits unless `--force`
+- [x] mcp-health pings configured MCP servers on session start
+- [x] All hooks optional (enable/disable in settings.json)
+- [x] Tests: 89 hook tests in test_hooks.bats
 
 ---
 
@@ -1783,10 +2101,10 @@ ai-toolkit mcp show github         # Show config details
 | `tests/test_mcp_templates.py` | CREATE | Validate JSON schemas |
 
 **Success Criteria:**
-- [ ] 25 MCP template configs created
-- [ ] `ai-toolkit mcp add <name>` merges into .mcp.json
-- [ ] `ai-toolkit mcp list` shows all available
-- [ ] Tests: >=5 (schema validation)
+- [x] 25 MCP template configs created
+- [x] `ai-toolkit mcp add <name>` merges into .mcp.json
+- [x] `ai-toolkit mcp list` shows all available
+- [x] Tests: 15 in test_mcp_manager.bats
 
 ---
 
@@ -1894,11 +2212,11 @@ All entries are tagged with "_source": "<source-name>" for idempotent updates.
 | `add-rule <file.md>` | `~/.ai-toolkit/rules/` | File copy + re-inject all | Yes |
 
 **Success Criteria:**
-- [ ] `inject-hook ./my-hooks.json` merges hooks with auto-derived `_source` tag
-- [ ] `remove-hook my-hooks` strips all entries with that `_source`
-- [ ] Re-running is idempotent (update, not duplicate)
-- [ ] Existing ai-toolkit hooks (`_source: "ai-toolkit"`) are never touched
-- [ ] Tests: >=6 (inject, remove, idempotent, coexistence, malformed input, missing file)
+- [x] `inject-hook ./my-hooks.json` merges hooks with auto-derived `_source` tag
+- [x] `remove-hook my-hooks` strips all entries with that `_source`
+- [x] Re-running is idempotent (update, not duplicate)
+- [x] Existing ai-toolkit hooks (`_source: "ai-toolkit"`) are never touched
+- [x] Tests: 17 in test_inject_hook.bats
 
 ---
 
@@ -1993,13 +2311,13 @@ ai-toolkit status                              # Show installed modules
 ```
 
 **Success Criteria:**
-- [ ] manifest.json defines all modules with dependencies
-- [ ] install --modules allows granular selection
-- [ ] install --auto-detect detects language from project files
-- [ ] state.json tracks what's installed
-- [ ] update only changes modified files (content hash)
-- [ ] Backward compatible with existing install
-- [ ] Tests: >=10
+- [x] manifest.json defines all modules with dependencies
+- [x] install --modules allows granular selection
+- [x] install --auto-detect detects language from project files (two-phase: markers + extensions)
+- [x] state.json tracks what's installed
+- [x] update only changes modified files (content hash)
+- [x] Backward compatible with existing install
+- [x] Tests: 35 across test_install.bats, test_install_flags.bats, test_install_state.bats
 
 ---
 
@@ -2038,10 +2356,10 @@ context: fork
    - **Recommendation** with confidence level
 
 **Success Criteria:**
-- [ ] `/council` invocable
-- [ ] 4 perspectives generated
-- [ ] Structured output with recommendation
-- [ ] Tests: >=2
+- [x] `/council` invocable
+- [x] 4 perspectives generated
+- [x] Structured output with recommendation
+- [ ] Tests: dedicated council tests not yet written
 
 ---
 
@@ -2058,9 +2376,9 @@ context: fork
 - Consistency checks (before outputting content, verify voice match)
 
 **Success Criteria:**
-- [ ] Skill auto-loads when writing docs/content
-- [ ] Anti-trope list prevents generic LLM rhetoric
-- [ ] Tests: >=2
+- [x] Skill auto-loads when writing docs/content
+- [x] Anti-trope list prevents generic LLM rhetoric
+- [ ] Tests: dedicated brand-voice tests not yet written
 
 ---
 
@@ -2079,10 +2397,10 @@ context: fork
 5. Optionally hand off to verification
 
 **Success Criteria:**
-- [ ] `/introspect` invocable when agent is stuck
-- [ ] Classifies failure pattern
-- [ ] Suggests recovery action
-- [ ] Tests: >=2
+- [x] `/introspect` invocable when agent is stuck
+- [x] Classifies failure pattern
+- [x] Suggests recovery action
+- [ ] Tests: dedicated introspect tests not yet written
 
 ---
 
@@ -2123,10 +2441,7 @@ docs/
 ```
 
 **Success Criteria:**
-- [ ] Documentation site deployed (GitHub Pages or Vercel)
-- [ ] Covers: installation, skills, agents, hooks, CLI reference
-- [ ] Auto-generated from existing CLAUDE.md/README.md content
-- [ ] Tests: Build passes
+- :no_entry: SKIPPED — README/CLAUDE.md sufficient, no documentation site needed
 
 ---
 
@@ -2172,7 +2487,7 @@ npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
 | Metric | Before | Target |
 |--------|--------|--------|
 | Skills | 88 | ~91 (+3 new skills) |
-| Hooks | 14 | 20 (+6) |
+| Hooks | 14 | 21 (+7, observe-session in rag-mcp) |
 | Language rules | ~8 (pattern skills) | 70 (13 langs × 5 + 5 common) |
 | MCP templates | 0 | 25 |
 | Install granularity | 3 profiles | 3 profiles + module-level |
@@ -2203,12 +2518,14 @@ npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
 
 ---
 
-## 9. Next Actions
+## 9. Remaining Gaps
 
-1. [ ] **Create `app/rules/common/` (5 files)** — Start with common rules
-2. [ ] **Create `app/mcp-templates/` (25 configs)** — Quick win, high impact
-3. [ ] **Create 6 new hooks** — Independent, can parallelize
-4. [ ] Review and approve this plan
+All major features shipped. Outstanding items:
+
+1. [ ] `validate.py` does not check rules format (1.1)
+2. [ ] No dedicated `test_rules` test file (1.1)
+3. [ ] No dedicated tests for council, brand-voice, introspect skills (3.1-3.3)
+4. [x] `observe-session.sh` lives in rag-mcp (consumer), not ai-toolkit — by design
 
 ---
 
@@ -2218,7 +2535,7 @@ None — all features are independent of external systems.
 
 ---
 
-**Last Updated:** 2026-04-07
+**Last Updated:** 2026-04-09
 
 ---
 
@@ -3371,13 +3688,16 @@ The `common/` directory uses the same structure except `frameworks.md` is replac
 
 ## Auto-Detection
 
-`--local` automatically enables language auto-detection. `scripts/install_steps/detect_language.py` scans the current directory for known marker files and selects matching language modules:
+`--local` automatically enables language auto-detection. `scripts/install_steps/detect_language.py` uses two-phase detection and merges results from both:
 
 ```bash
 ai-toolkit install --local     # auto-detects language (--auto-detect is implied)
 ```
 
-Detection logic (first match wins when multiple markers are present):
+### Phase 1: Marker files (config-level signals)
+
+Scans for configuration files defined in each module's `auto_detect` list in `manifest.json`:
+
 1. `package.json` or `tsconfig.json` → TypeScript
 2. `go.mod` → Go
 3. `Cargo.toml` → Rust
@@ -3391,7 +3711,13 @@ Detection logic (first match wins when multiple markers are present):
 11. `*.csproj` or `*.sln` → C#
 12. `CMakeLists.txt` or `Makefile` → C++
 
-Common rules are always injected regardless of detected language.
+### Phase 2: Source file extensions (actual code presence)
+
+Scans top-level files and one directory level deep for source file extensions (`.py`, `.ts`, `.go`, `.rs`, `.java`, `.kt`, `.swift`, `.dart`, `.cs`, `.php`, `.cpp`, `.rb`, etc.). Skips dependency/build directories (`node_modules`, `venv`, `dist`, `build`, etc.) for speed.
+
+This catches cases where marker files are misleading — e.g., a Python project with a `package.json` only for its npm CLI wrapper will correctly detect both Python (via `.py` files) and TypeScript (via `package.json`).
+
+Both phases contribute; results are merged and deduplicated. Common rules are always injected regardless of detected language.
 
 ## Installation
 
@@ -3399,13 +3725,18 @@ Common rules are always injected regardless of detected language.
 # Auto-detect language from project files (default with --local)
 ai-toolkit install --local
 
-# Explicitly select a language
+# Explicitly select a language (implies --local, disables auto-detect)
 ai-toolkit install --local --lang typescript
 
+# Multiple languages
+ai-toolkit install --local --lang go,python
+
 # Skip auto-detect, install specific modules only
 ai-toolkit install --local --modules core,agents
 ```
 
+The `--lang` flag accepts comma-separated language names and converts them to `rules-<lang>` modules. Common aliases are supported: `go` → `golang`, `c++` → `cpp`, `c#`/`cs` → `csharp`. Using `--lang` implies `--local` and disables auto-detection.
+
 Language rules are injected into the project `CLAUDE.md` between named markers:
 
 ```
@@ -4095,7 +4426,7 @@ title: "AI Toolkit - Skills Catalog"
 category: reference
 service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
-version: "1.3.14"
+version: "1.4.0"
 created: "2026-03-23"
 last_updated: "2026-04-08"
 description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
@@ -4263,6 +4594,62 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 |-------|-----------|--------|
 | **hive-mind** | `skills/hive-mind/` | Multi-agent aggregation, consensus, swarm patterns |
 
+## Quality Guardrails
+
+### Anti-Rationalization Tables
+
+15 core skills include `## Common Rationalizations` — domain-specific tables of excuses and rebuttals that prevent agent drift and shortcut-taking:
+
+| Skill | Example rationalization blocked |
+|-------|---------------------------------|
+| `/review` | "Small change, quick scan is enough" |
+| `/debug` | "It must be a library bug" |
+| `/refactor` | "It works, don't touch it" |
+| `/tdd` | "Too simple to test" |
+| `/plan` | "Planning is wasted time, just start coding" |
+| `/docs` | "The code is self-documenting" |
+| `/analyze` | "The linter is green, the code is fine" |
+| `security-patterns` | "It's an internal API, security doesn't matter" |
+| `testing-patterns` | "Tests slow down development" |
+| `api-patterns` | "We'll version the API later" |
+| `ci-cd-patterns` | "Manual deploys give us more control" |
+| `clean-code` | "It's readable enough" |
+| `performance-profiling` | "It feels slow, let me optimize this function" |
+| `git-mastery` | "One big commit is simpler" |
+| `database-patterns` | "We'll add indexes later when it's slow" |
+
+### Confidence Scoring (`/review`)
+
+The `/review` skill outputs structured findings with:
+- **Severity**: critical / major / minor / nit
+- **Confidence score**: 1-10 per finding with calibration guide
+- **Evidence requirement**: each finding must include file:line + reasoning
+
+### Self-Evaluation — LLM-as-Judge (`/review`)
+
+After completing a review, the agent performs a self-evaluation pass:
+1. Verify vs assume — did I read actual code for each finding?
+2. Check the inverse — if X is a problem, is NOT-X also a problem elsewhere?
+3. Detect anchoring bias — did early findings bias toward similar patterns?
+4. Check unhappy paths — error handling, edge cases, failure modes
+5. Calibrate confidence — overconfident? re-examine weakest finding
+
+### Agent Verification Checklists
+
+10 key agents include `## Verification Checklist` — exit criteria before presenting results:
+`code-reviewer`, `test-engineer`, `security-auditor`, `debugger`, `backend-specialist`, `frontend-specialist`, `database-architect`, `performance-optimizer`, `devops-implementer`, `documenter`.
+
+### Skill Reference Routing
+
+7 core skills include `## Related Skills` sections suggesting logical follow-up skills:
+`/review`, `/debug`, `/plan`, `/refactor`, `/tdd`, `/docs`, `/analyze`.
+
+### Intent Capture Interview (`/onboard`)
+
+Step 0 interview before setup — 5 targeted questions to capture undocumented project intent, customizing the generated `CLAUDE.md`.
+
+---
+
 ## Advanced Features
 
 ### Effort Levels