kodelyth-ecc 1.4.1 → 1.5.0

package/wiki/FAQ.md

@@ -4,139 +4,225 @@
 
 ## General
 
-### Is this really free?
+### What is Kodelyth ECC?
 
-Yes. MIT license. No paid tier, no API key required, no usage limits. The tool itself is free — you pay only for whatever AI platform you use (Claude Code, Antigravity, etc.) through Anthropic or Google directly.
+ECC (Enhanced Coding Companion) is a production-grade AI coding toolkit. It gives your AI coding tool 59 specialist agents, 188 skills, 80 slash commands, 18+ automation hooks, and a local self-learning memory system. Works with Claude Code, Windsurf, Cursor, Codex CLI, Antigravity, and OpenCode.
 
-### Does it work with any language?
+### Is it free?
 
-Yes. The agents are language-agnostic. There are also language-specific rule bundles (TypeScript, Python, Go, Rust, Java, Kotlin, C++, Dart, PHP, Swift, Perl, web) that can be installed via profiles.
+Yes. MIT license. No usage restrictions. No paid tier. No telemetry. No cloud dependency.
 
-### How is this different from just using Claude Code alone?
+### Does it work with any AI model?
 
-Out of the box, Claude Code is a general-purpose assistant. Kodelyth ECC adds:
-- 53 specialist agents that are deeply opinionated in their domains
-- Automated hooks that run quality checks without you asking
-- Slash commands for repeatable workflows
-- Domain knowledge skills that stay active for the session
-- Always-on principles (no emoji, budget-first model selection, SVG over decoration)
+Agents and skills are model-agnostic markdown files. They work with Claude, GPT, Gemini, Llama, and any other model your AI tool uses. The memory system is also model-agnostic.
+
+### Do I need to configure anything after install?
+
+No. Hooks, rules, and memory injection activate automatically. You don't need to configure anything to get the core features.
 
 ---
 
 ## Installation
 
-### Install fails with "permission denied"
+### What's the easiest way to install?
 
 ```bash
-chmod +x install.sh
-./install.sh
+npx kodelyth-ecc
 ```
 
-### Install fails on Windows
-
-Use PowerShell (not Command Prompt):
-
-```powershell
-Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
-.\install.ps1
-```
+Requires Node 18+. Runs on any OS.
 
-### How do I update to a new version?
+### What install targets are available?
 
-```bash
-cd kodelyth-ecc
-git pull
-./install.sh
-```
+| Target | What it installs to |
+|---|---|
+| `claude-home` (default) | `~/.claude/` — Claude Code global |
+| `antigravity` | `~/.config/google-gemini/` or Antigravity dir |
+| `windsurf-project` | `.windsurf/` in current project |
+| `windsurf-home` | `~/.codeium/windsurf/` global |
+| `cursor-project` | `.cursor/` in current project |
+| `codex-home` | `~/.codex/` |
+| `opencode` | `~/.opencode/` |
 
-The install script is idempotent — safe to run multiple times.
+### What are install profiles?
 
-### How do I uninstall?
+Profiles install language-specific rule modules:
 
-Claude Code:
 ```bash
-rm -rf ~/.claude/agents ~/.claude/skills ~/.claude/hooks ~/.claude/commands ~/.claude/rules
+npx kodelyth-ecc --profile nextjs        # TypeScript rules
+npx kodelyth-ecc --profile python-api    # Python rules
+npx kodelyth-ecc --profile fullstack     # TypeScript + Python + Go
+npx kodelyth-ecc --profile mobile        # Kotlin + Swift
+npx kodelyth-ecc --profile backend       # Go + Python + Java
 ```
 
-Antigravity:
-```bash
-rm -rf your-project/.agent/
-```
+### Can I install to multiple targets?
+
+Yes. Run the installer multiple times with different `--target` flags.
 
 ---
 
 ## Agents
 
-### How do I use an agent?
+### Do I have to know agent names?
 
-```
-use agent-name
-```
+No. The intent routing rule (`rules/common/agent-intent-routing.md`) analyzes every message you type and routes to the right agent automatically. You can also explicitly invoke agents:
 
-Example:
 ```
 use debug-detective
-use kodelyth-advisor
-use security-reviewer
+@code-reviewer
+invoke security-reviewer
 ```
 
-### Which agent should I use first?
+### How do I know which agent handled my request?
 
-If you're not sure, always start with:
+ECC always acknowledges routing explicitly:
 
 ```
-use kodelyth-advisor
+→ Routing to debug-detective
+Tip: type "use debug-detective" to invoke directly next time.
 ```
 
-It will assess your situation and direct you to the right agent or skill.
+### Can I add my own agents?
+
+Yes. Create a markdown file with YAML frontmatter in `~/.claude/agents/`. See [CONTRIBUTING.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/CONTRIBUTING.md) for the template.
+
+### What's the difference between planner and pair-programmer?
+
+`planner` creates a full implementation plan (PRD, architecture, task list) before writing any code. `pair-programmer` is your pre-code thinking partner — it catches wrong approaches, missing edge cases, and premature optimizations before a line is written. Use `pair-programmer` first for critical decisions, then `planner` for the full breakdown.
+
+---
+
+## Memory System
+
+### What is the self-learning memory?
+
+The memory system (v1.4.0+) captures problems and solutions from your past sessions and recalls them when relevant in future sessions. It runs locally at `~/.kodelyth/memory/` with zero cloud involvement.
+
+### How does memory capture work?
+
+ECC never auto-stores anything. The Stop hook runs `extract.js` at session end, extracts learning candidates using heuristics, and writes them to `pending-review.jsonl`. You review and confirm:
+
+```bash
+node scripts/memory/cli.js list          # see what's pending
+/memory review-pending                   # review in your AI session
+/memory remember "title" --approach "..." --tags a,b
+```
+
+### What is auto-recall?
+
+Auto-recall (v1.4.1) fires a `UserPromptSubmit` hook on every meaningful prompt. It runs BM25 search against your memory and injects relevant matches into the AI's context before it responds. No commands needed.
+
+### How does repeat suppression work?
+
+Each session tracks which memory IDs were already surfaced (stored in `~/.kodelyth/memory/session-surfaced-<id>.json`). If the same memory was shown earlier in the session, it is not shown again. Different topics in the same session will still surface their relevant memories.
+
+### What prompts does auto-recall skip?
+
+Auto-recall skips:
+- Empty prompts
+- Trivial one-word responses (`ok`, `yes`, `no`, `thanks`, `cool`, `done`)
+- Agent/command invocations starting with `use`, `@`, `/`, or `invoke`
+- Prompts under 12 characters
+- Prompts with fewer than 2 meaningful tokens after stop-word removal
 
-### Can I use multiple agents in one session?
+### Can I use memory without Claude Code?
 
-Yes. You can delegate to agents sequentially or in parallel. Example:
+Manual memory (`/memory remember`, `/memory search`) works everywhere. Auto-recall via `UserPromptSubmit` hook only fires in Claude Code — other platforms don't currently expose a pre-prompt hook. Session-start injection works in all platforms.
 
+### Where is memory stored?
+
+Default: `~/.kodelyth/memory/`
+
+Override: `export KODELYTH_MEMORY_DIR=/your/path`
+
+### How do I search my memory?
+
+```bash
+node scripts/memory/cli.js search "stripe webhook"
+/memory recall stripe webhook
 ```
-use pair-programmer    ← think through the approach first
-use tdd-guide          ← write tests
-use code-reviewer      ← review the implementation
-use security-reviewer  ← check for vulnerabilities
+
+### How do I delete a memory?
+
+```bash
+node scripts/memory/cli.js forget <memory-id>
 ```
 
+Soft-delete — the entry is marked deleted but not removed from the log file.
+
 ---
 
-## Google Antigravity
+## Hooks
 
-### Do hooks work in Antigravity?
+### What hooks run automatically?
 
-Antigravity does not have a hook execution engine. Hook behavior is approximated via `.agent/rules/kodelyth-always-on.md` which auto-loads every session and enforces the same principles (test reminders, branch naming, model selection).
+| Hook | When | What it does |
+|---|---|---|
+| `memory/inject-start.js` | Session start | Injects relevant memories into context |
+| `memory/auto-recall.js` | Every prompt | Real-time BM25 memory check per message |
+| `memory/capture-stop.js` | Session end | Extracts learning candidates to pending review |
+| `hooks/test-reminder` | After editing code | Reminds you to write tests |
+| `hooks/smart-suggest` | After response | Suggests the next logical agent |
+| `hooks/branch-name-check` | Before `git checkout -b` | Enforces branch naming convention |
 
-### Do I need to say anything to Antigravity to activate ECC?
+### How do I disable a hook?
 
-No. After install, `.agent/rules/kodelyth-always-on.md` is loaded automatically every session. ECC is always active.
+```bash
+export ECC_DISABLED_HOOKS=kodelyth:smart-suggest,kodelyth:test-reminder
+```
 
-### Which Antigravity model should I use for daily work?
+### Do hooks slow down my session?
 
-**Gemini 3.1 Pro (Low)** for everyday coding tasks. Switch to **Gemini 3.1 Pro (High)** for complex features or multi-file refactoring. Use **Claude Sonnet 4.6 Thinking** for agent-heavy or reasoning tasks.
+No. All hooks are async with a 5-second timeout. They write to stderr (advisory only) and never block tool execution.
 
 ---
 
-## Contributing
+## Platform Questions
 
-### How do I contribute a new agent?
+### Does ECC work with Windsurf?
 
-See [CONTRIBUTING.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/CONTRIBUTING.md).
+Yes. Use `--target windsurf-project` or `--target windsurf-home`. The installer generates a `.windsurfrules` file that Cascade auto-loads.
 
-Agents must follow the Kodelyth Standard:
-- GOD-level persona (decade-experienced specialist)
-- Model-agnostic (no model field in frontmatter)
-- Production-grade examples
-- No emoji in output — SVG badges or plain text only
+### Does ECC work with Google Antigravity?
 
-### How do I report a security issue?
+Yes. Use `--target antigravity`. Rules are flattened for Antigravity's required format.
 
-Email **sifxprime@kodelyth.com** with subject `[SECURITY] kodelyth-ecc — <description>`.
+### Does memory work with cloud-AI platforms like Antigravity?
 
-See [SECURITY.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/SECURITY.md) for full policy.
+Manual memory commands (`/memory remember`, `/memory search`) work everywhere. Auto-extract from past sessions requires local session files — cloud platforms that store sessions server-side don't support this. The `UserPromptSubmit` auto-recall hook also requires Claude Code currently.
 
 ---
 
-## Built and maintained by [Kodelyth](https://github.com/sifxprime) — [@sifxprime](https://github.com/sifxprime)
+## Troubleshooting
+
+### My agent isn't responding to intent routing
+
+Check that `rules/common/agent-intent-routing.md` is installed. Run:
+
+```bash
+ls ~/.claude/rules/common/
+```
+
+If missing, re-run `npx kodelyth-ecc`.
+
+### Memory isn't being injected
+
+Check the `hooks/memory/inject-start.js` hook is installed and listed in `hooks.json`. Verify `KODELYTH_MEMORY_DIR` points to a directory with memory entries.
+
+### Tests are failing after install
+
+Run the test suite to verify installation:
+
+```bash
+cd ~/.claude  # or your install directory
+npm test
+```
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/CONTRIBUTING.md) for agent, skill, command, and hook templates.
+
+Branch naming: `feat/`, `fix/`, `docs/`, `refactor/`, `test/`, `chore/`

package/wiki/Home.md

@@ -1,50 +1,113 @@
-# Kodelyth ECC — Wiki
+# Kodelyth ECC Wiki
 
-> Production-grade AI coding agent toolkit for Claude Code, Google Antigravity, Cursor, Codex, and OpenCode.
+**Kodelyth Enhanced Coding Companion** — production-grade AI coding toolkit for Claude Code, Windsurf, Cursor, Codex CLI, Antigravity, and OpenCode.
 
-**Version:** 1.1.0 | **License:** MIT | **Author:** [Kodelyth / @sifxprime](https://github.com/sifxprime)
+**Version:** 1.4.1 | **License:** MIT | **Author:** [Kodelyth / @sifxprime](https://github.com/sifxprime)
 
 ---
 
-## Quick Navigation
+## What is Kodelyth ECC?
+
+ECC is a collection of 59 battle-tested agents, 188 skills, 80 commands, 18+ hooks, and 16 rules that make any AI coding tool dramatically more capable. It installs into your AI tool's config directory and activates automatically on every session.
+
+Three things make ECC genuinely different from other AI config setups:
 
-| Page | Description |
-|------|-------------|
-| [Installation Guide](Installation-Guide) | Install on any platform in 30 seconds |
-| [Agent Reference](Agent-Reference) | All 53 specialist agents explained |
-| [Skill Reference](Skill-Reference) | All 185 skills and how to load them |
-| [Hook Reference](Hook-Reference) | 18+ automated hooks that run in background |
-| [Platform Support](Platform-Support) | Claude Code, Antigravity, Cursor, Codex, OpenCode |
-| [FAQ](FAQ) | Common questions answered |
+**1. God-Tier Intent Routing** — every message you type is analyzed across 10 priority tiers and 50+ trigger patterns. The right specialist activates automatically. You don't need to know agent names.
+
+**2. Local Self-Learning Memory** — ECC captures problems and solutions from your sessions and recalls them when relevant. Completely local. BM25 full-text search. Zero cloud. Zero telemetry.
+
+**3. Auto Chat Detection** — on every meaningful prompt, ECC automatically checks your memory for relevant past solutions and injects them into the AI's context before it responds. No commands needed. The AI just knows.
 
 ---
 
-## What is Kodelyth ECC?
+## Quick Install
 
-Kodelyth ECC is a collection of 53 specialist AI agents, 185 knowledge skills, 79 slash commands, and 18+ automated hooks — all free, all open source, MIT licensed.
+```bash
+# Any machine with Node 18+  (recommended)
+npx kodelyth-ecc
 
-Instead of one generic AI assistant doing everything, you get a team:
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash
 
-- A **debugger** that never guesses and traces every bug to its root cause
-- A **security reviewer** that catches OWASP Top 10 before you commit
-- A **UX reviewer** that enforces WCAG 2.1 AA without touching your design
-- A **pair programmer** that catches the wrong approach before you write a line
-- A **migration guide** with full playbooks for React, Next.js, Python, Node, TypeScript, Java
+# Windows PowerShell
+irm https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.ps1 | iex
 
-All working together. All free.
+# GitHub (no npm)
+npx github:sifxprime/kodelyth-ecc
+```
 
 ---
 
-## Install
+## What Gets Installed
 
-```bash
-git clone https://github.com/sifxprime/kodelyth-ecc.git
-cd kodelyth-ecc
-./install.sh
+| Component | Count | Where |
+|---|---|---|
+| Agents | 59 | `~/.claude/agents/` |
+| Skills | 188 | `~/.claude/skills/` |
+| Commands | 80 | `~/.claude/commands/` |
+| Hooks | 18+ | `~/.claude/hooks/` |
+| Rules | 16 | `~/.claude/rules/` |
+| Memory hooks | 3 | `~/.claude/hooks/memory/` |
+
+---
+
+## Intent Routing — How It Works
+
+```
+You type:  "there's a bug in the auth middleware"
+ECC:       → Routing to debug-detective
+
+You type:  "this test fails every third run"
+ECC:       → Routing to flake-hunter
+
+You type:  "I need to cut the v2.0 release"
+ECC:       → Routing to release-captain
+
+You type:  "add Stripe webhooks"
+           └─ Memory auto-recall fires → finds past solution
+              injects context before AI responds
 ```
 
-See [Installation Guide](Installation-Guide) for full options.
+---
+
+## Wiki Pages
+
+| Page | What it covers |
+|---|---|
+| [Installation Guide](Installation-Guide) | All install methods, targets, profiles, and options |
+| [Agent Reference](Agent-Reference) | All 59 agents — purpose, trigger patterns, when to use |
+| [Skill Reference](Skill-Reference) | All major skills and how to invoke them |
+| [Hook Reference](Hook-Reference) | All hooks — when they fire and what they do |
+| [Platform Support](Platform-Support) | Per-platform capabilities, limitations, and configs |
+| [FAQ](FAQ) | Common questions including memory system |
+
+---
+
+## Quick Decision Table
+
+| Situation | Agent to use |
+|---|---|
+| Bug with stack trace | `debug-detective` |
+| Bug with no error (silent fail) | `silent-failure-hunter` |
+| Build or type error | `build-error-resolver` |
+| Security concern | `security-reviewer` |
+| Code review before commit | `code-reviewer` |
+| Planning a new feature | `planner` or `pair-programmer` |
+| API breaking change check | `api-guardian` |
+| Frontend UX / accessibility | `ux-reviewer` |
+| Flaky tests | `flake-hunter` |
+| Cut a release | `release-captain` |
+| Broken git state | `git-rescue` |
+| "Works on my machine" | `env-debugger` |
+| Dependency conflicts | `dependency-doctor` |
+| Memory / past solutions | `kodelyth-memory` |
+| Don't know which agent | `kodelyth-advisor` |
 
 ---
 
-Built with care. Powered by **Kodelyth**.
+## Links
+
+- **Repository:** [github.com/sifxprime/kodelyth-ecc](https://github.com/sifxprime/kodelyth-ecc)
+- **npm:** [npmjs.com/package/kodelyth-ecc](https://www.npmjs.com/package/kodelyth-ecc)
+- **Changelog:** [CHANGELOG.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/CHANGELOG.md)
+- **License:** MIT — free forever