codymaster 4.6.0 → 5.2.0

package/CHANGELOG.md

@@ -4,12 +4,80 @@ All notable changes to this project will be documented in this file.
 
 Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 
+## [Unreleased]
+
+### 🚀 Improvements — Zero-Token Skill Discovery
+- Removed LLM token waste on skill search by porting deterministic tech-stack parsing natively into `src/indexer/skills.ts`.
+- Introduced `cm index skills` CLI command to compile `.cm/project-skills.md` locally.
+- Updated Fission framework (`cm-project-bootstrap`, `cm-skill-index`, `AGENTS.md`) to prioritize zero-token local indexes over massive community directory sweeps.
+
+### 🚀 Improvements — CodyMaster v6.0 "Self-Evolving Brain"
+
+- **Smart Brain Router** — `src/smart-brain-router.ts` adds a zero-cost keyword-based classifier that dynamically selects the optimal memory tiers for incoming tasks, reducing token waste by up to 60-80% for simple tasks.
+- **Skill Execution Cache** — `src/skill-execution-cache.ts` introduces an FTS5-backed warm cache for successful execution chains (effectiveness >= 0.70), skipping BM25 and LLM selection entirely for recurring task patterns.
+- **Per-Tier Adaptive Token Budgeting** — Enhanced `src/token-budget.ts` controls budgets natively per memory tier and visually outputs budget and savings reports.
+- **Evolution Engine (Skill Evolver)** — `src/skill-evolver.ts` brings true autonomy. CodyMaster now auto-repairs and auto-generates `SKILL.md` files locally with three modes: `FIX` (adds warnings to broken skills), `DERIVED` (clones highly successful fallback paths), and `CAPTURED` (creates new skills completely autonomously when a task completes without predefined skills). Ships with anti-loop protection and automatic `.md` backups.
+- **Learning Promoter** — `src/learning-promoter.ts` scans working memory for recurring failures or patterns (reinforced >= 3 times) and automatically promotes them into permanent `cm-learned-*` skills.
+- **New CLI Tools** — `cm smart plan/tiers`, `cm token report/savings`, and a full `cm evolve` lifecycle toolkit (`status`, `run`, `history`, `rollback`, `candidates`, `promote`).
+- **Comprehensive Testing** — Extensively covered the new architectures with 62 new testing scenarios (system currently sits at 302 passed tests natively).
+
+### 🚀 Improvements — OpenViking De-scope
+
+- Removed OpenViking auto-installation from `install.sh` and `scripts/postinstall.js`; CodyMaster now keeps the normal install path focused on the supported Node-first stack.
+- Updated runtime/config/docs guidance so `storage.backend: viking` is treated as a deprecated experimental path instead of a default-facing feature.
+- Removed the remaining OpenViking runtime backend, demo script, and dedicated tests; legacy `storage.backend: viking` configs now warn and fall back to SQLite.
+
+### 🚀 Improvements — Advisory Loop Productization
+
+- Added `cm advisory report`, `cm advisory metrics`, and `cm advisory handoff` so operators can inspect execution analyses, review per-skill quality, and generate structured recovery notes for `cm-skill-health` / `cm-skill-evolution`.
+- `selectTopSkills()` now uses recorded `skill_metrics` as a quality-weighted boost for optional step ranking, while mandatory `always` steps remain unchanged.
+- Added `src/advisory-handoff.ts` as the shared contract between analyzer output and self-healing workflows; the handoff can be emitted as Markdown or JSON.
+- Exposed the advisory loop to MCP clients via `cm_advisory_report`, `cm_advisory_metrics`, and `cm_advisory_handoff` in `src/mcp-context-server.ts`.
+- Added workflow and API docs for the advisory loop under `docs/workflows/advisory-loop.md` and `docs/api/api-reference.md`.
+
+## [5.1.0] - 2026-04-11
+
+### 🚀 Improvements — SkillsBench Intelligence + Ecosystem Reach
+
+- **Intelligent Skill Selection (`selectTopSkills`)** — `src/skill-chain.ts` now applies SkillsBench research findings at runtime. Each chain execution dynamically selects the top-3 most relevant skills for the current task (scored by BM25 token overlap + mandatory-step priority bonus). Result: 2-3 focused skills → **+18.6pp** improvement vs 4+ loaded statically (+5.9pp). Chains with >3 mandatory steps still execute fully with a performance advisory logged to stderr. New exported functions: `scoreStepRelevance()`, `selectTopSkills()`.
+
+- **`cm mcp-serve` command** — New `src/cli/commands/mcp-serve.ts` registers `cm mcp-serve [--project <path>] [--print-config]`. Spawns `dist/mcp-context-server.js` over stdio with SIGINT/SIGTERM forwarding. `--print-config` prints ready-to-paste JSON config for **Goose** and **Claude Desktop**, enabling one-command ecosystem integration. Goose extension config: `{ "type": "stdio", "cmd": "npx", "args": ["codymaster", "mcp-serve"] }`.
+
+- **CodyBench v0.1** — New `cm bench` command backed by `src/codybench/` scaffolding. Three eval suites with A/B comparison (with vs without CodyMaster): `tdd-regression` (bug catch rate), `token-efficiency` (savings vs documented 78% claim), `memory-retention` (SQLite recall hit rate). Runner: `claude-code`. Judge: automated (mean/min/max/stddev). Results written to `codybench/reports/`. Methodology mirrors Goose's transparent benchmark publication strategy.
+
+- **NLI Memory Interface (`cm_memory_write` + `cm_natural`)** — MCP server now exposes **15 tools** (up from 13). `cm_memory_write` persists a learning to SQLite with auto-detected category (arch_decision / bug_fix / user_pref / code_pattern / context), configurable scope (session/project/global), TTL, and importance. `cm_natural` is a natural language router: "remember that…" → write, "forget about…" → decay, "what did we learn about…" → FTS5 query. Zero new npm dependencies; pattern matching via regex.
+
+- **Goose integration guide** — `docs/integrations/goose.md` — step-by-step tutorial: install CodyMaster → `cm mcp-serve --print-config` → paste YAML config into Goose → test with `cm_natural`. Tool reference table included.
+
+- **GitHub community templates** — `.github/ISSUE_TEMPLATE/` now includes `good-first-skill.md` (with SkillsBench 12-point quality checklist), `benchmark-needed.md` (CodyBench eval request), `skill-improvement.md` (rubric-based improvement proposal).
+
+- **Version bump** — `package.json` version: `5.0.0` → `5.1.0`. CLI command count: 18 → 20 (`mcp-serve`, `bench`). MCP tool count: 13 → 15.
+
+## [4.8.0] - 2026-04-10
+
+### 🚀 Improvements — Documentation site & README accuracy
+
+- **VitePress documentation** — Rebuilt `docs/` as a browsable site with sidebar IA (Getting Started, Architecture, Operations, Skills Library, API, Resources). Config: `docs/.vitepress/config.mts`. Local preview: `npm run docs:dev`; production build: `npm run docs:build`.
+- **Skills index** — Documented all **56** bundled `skills/cm-*/SKILL.md` packs with category pages under `docs/skills/`.
+- **API hub** — Added `docs/api/api-reference.md` (CLI + dashboard + browse daemon + MCP tools) aligned to `src/mcp-context-server.ts` (**13** MCP tools).
+- **README refresh (all languages)** — Version badges bumped to **4.8.0**; broken `docs/` links replaced; CLI examples updated to match `src/cli/command-registry.ts` (no fictional `cm continuity` / `cm list` commands). License callouts aligned to **ISC** (`package.json`).
+- **npm scripts** — `docs:dev`, `docs:build`, `docs:preview` for maintainers.
+
+## [4.7.0] - 2026-04-02
+
+### 🚀 Improvements — Zero-Touch Installation & Advanced Pipeline
+
+- **Zero-Touch CLI Installation** — `install.sh` and `scripts/postinstall.js` overhauled to automatically activate the `cm` CLI. The script supports `--auto` for non-interactive `npm install -g codymaster`, while NPM seamlessly executes `npm link` or global install.
+- **OpenViking Core Feature** — Integrated OpenViking installation via `pip/pip3` natively into the installation process. Both `bash install.sh --all` and `npm i codymaster` will now automatically set up the OpenViking daemon, unlocking true semantic vector graph memory out-of-the-box.
+- **Skill Chain Auto-Dispatch** — Inspired by OpenSpace orchestrations, `cm-skill-chain` received a massive upgrade. Re-introduced the missing `auto` command enabling intelligent task detection, auto-selection of tools, and 100% automated handoffs between multi-agent sequences without human intervention.
+- **Systematic Auto-healing** — Enhancements to `postinstall.js` for automatic fallbacks across different OS privileges and execution environments.
+
 ## [4.6.0] - 2026-04-02
 
 ### 🚀 Improvements — OpenViking Backend (Real Implementation)
 
-- **`VikingBackend` — real implementation** — `src/backends/viking-backend.ts` implements all 11 `StorageBackend` methods by calling the [OpenViking REST API](https://github.com/volcengine/OpenViking) (default: `http://localhost:1933`). Replaces the placeholder stub from v4.5.5.
-- **`VikingHttpClient`** — New `src/backends/viking-http-client.ts`: thin fetch-based HTTP client wrapping OpenViking's `/write`, `/read`, `/ls`, `/search`, `/abstract`, `/overview`, `/health`, `/mkdir` endpoints. Zero new npm dependencies (uses Node.js built-in `fetch`).
+- `**VikingBackend` — real implementation** — `src/backends/viking-backend.ts` implements all 11 `StorageBackend` methods by calling the [OpenViking REST API](https://github.com/volcengine/OpenViking) (default: `http://localhost:1933`). Replaces the placeholder stub from v4.5.5.
+- `**VikingHttpClient`** — New `src/backends/viking-http-client.ts`: thin fetch-based HTTP client wrapping OpenViking's `/write`, `/read`, `/ls`, `/search`, `/abstract`, `/overview`, `/health`, `/mkdir` endpoints. Zero new npm dependencies (uses Node.js built-in `fetch`).
 - **URI layout in OpenViking workspace:** `learnings/<id>.json`, `decisions/<id>.json`, `indexes/<resource>/<level>.md`, `skill-outputs/<sessionId>/<id>.json`.
 - **Semantic vector search** — `queryLearnings()` and `queryDecisions()` now call OpenViking's `/search` endpoint, which uses embedding-based vector similarity. Finds related memories even when query terms don't match exactly (e.g. "async timeout" matches "network latency spike").
 - **Auto L0/L1 via engine** — `getL0Abstract()` and `getL1Overview()` call OpenViking's `/abstract` and `/overview` endpoints. No manual `cm continuity index` needed with Viking backend.
@@ -23,10 +91,10 @@ Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 
 ### 🚀 Improvements — StorageBackend Interface (OpenViking Swap Path)
 
-- **`StorageBackend` interface** — New `src/storage-backend.ts` defines an 11-method abstraction over CodyMaster's persistent memory store. Swapping storage engines is now a config change, not a code rewrite.
-- **`SqliteBackend`** — Thin wrapper around `context-db.ts`. Zero logic duplication; all existing callers untouched. New callers use `getBackend(projectPath)` for polymorphism.
-- **`VikingBackend` stub** — All methods throw a descriptive `NotImplementedError` with step-by-step install instructions for `@openviking/client`. Explicit swap path documented.
-- **`getBackend(projectPath)` factory** — Reads `.cm/config.yaml → storage.backend` (`sqlite` | `viking`). Defaults to `sqlite` when config is absent or malformed.
+- `**StorageBackend` interface** — New `src/storage-backend.ts` defines an 11-method abstraction over CodyMaster's persistent memory store. Swapping storage engines is now a config change, not a code rewrite.
+- `**SqliteBackend`** — Thin wrapper around `context-db.ts`. Zero logic duplication; all existing callers untouched. New callers use `getBackend(projectPath)` for polymorphism.
+- `**VikingBackend` stub** — All methods throw a descriptive `NotImplementedError` with step-by-step install instructions for `@openviking/client`. Explicit swap path documented.
+- `**getBackend(projectPath)` factory** — Reads `.cm/config.yaml → storage.backend` (`sqlite` | `viking`). Defaults to `sqlite` when config is absent or malformed.
 - **Config template updated** — `cm continuity init` now writes a `storage:` section to `.cm/config.yaml` with the backend switch commented out.
 - **Zero breaking changes** — `context-db.ts` and all existing callers unchanged. StorageBackend is additive.
 - **Test suite expanded** — `test/storage-backend.test.ts` (23 tests): factory defaults, config-driven dispatch, SqliteBackend full roundtrip, VikingBackend error messages. Total: **178 passed · 16 skipped · 0 failed**.
@@ -74,7 +142,6 @@ Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
   - `cm-skill-evolution` — 3-mode evolution engine (FIX/DERIVED/CAPTURED) with version DAG and lineage tracking. Auto-patches degraded skills.
   - `cm-skill-search` — BM25 + health-score ranking for intelligent skill discovery.
   - `cm-skill-share` — Export/import skills across teams and machines with version integrity.
-- **🏢 cm-frappe-agent** — Full-stack Frappe/ERPNext development agent with 7-layer architecture: doctypes, workflows, REST APIs, permissions, fixtures, performance optimization, and production deploys.
 - **🚀 Growth Hacking Engine** — `cm-growth-hacking` generates complete conversion systems (Bottom Sheet + Calendar CTA + Tracking) with industry auto-detection.
 - **cm-auto-publisher** — Publishing automation bridge: AI agents → Content Factory Router → any Astro site.
 - **cm-clean-code** — TRIZ-powered code hygiene gate: dead code detection, duplicate elimination, naming analysis.
@@ -89,7 +156,6 @@ Categories: 🚀 **Improvements** | 🐛 **Bug Fixes** | 🔒 **Security**
 - **OpenSpec Protocol Upgrade** — Enhanced integration with Fission-AI OpenSpec format (`openspec/changes/[initiative]/proposal.md`) for seamless context handoffs to downstream skills (`cm-planning` & `cm-execution`).
 - **Skill Evolution Engine** — Successfully executed automated self-healing mechanisms (Mode: FIX) for `cm-tdd` and `cm-debugging` after health monitor alerts.
 
-
 ## [4.3.0] - 2026-03-27
 
 ### 🚀 Improvements

package/README.md

@@ -1,22 +1,10 @@
-<div align="center">
-
 [English](README.md) | [Tiếng Việt](README-vi.md) | [中文](README-zh.md) | [Русский](README-ru.md) | [한국어](README-ko.md) | [हिन्दी](README-hi.md)
 
 # 🧠 CodyMaster
 
 ### Your AI Agent is smart. CodyMaster makes it *wise*.
 
-**68+ Skills · 18 Commands · 1 Plugin · 7+ Platforms · 6 Languages**
-
-<p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-4.6.0-blue.svg?cacheSeconds=2592000" />
-  <img alt="Skills" src="https://img.shields.io/badge/skills-68+-success.svg" />
-  <img alt="Platforms" src="https://img.shields.io/badge/platforms-7+-orange.svg" />
-  <img alt="Open Source" src="https://img.shields.io/badge/license-MIT-purple.svg" />
-  <a href="https://github.com/tody-agent/codymaster#readme" target="_blank">
-    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
-  </a>
-</p>
+**60+ Skills · 20+ Commands · 1 Plugin · 8+ Platforms · 6 Languages · v6.0.0**
 
 ```
     ( . \ --- / . )
@@ -28,11 +16,11 @@
   Your smart coding companion.
 ```
 
-![CodyMaster Kanban Dashboard](assets/images/dashboard.png)
+CodyMaster Kanban Dashboard
 
-### 🌟 If CodyMaster saves you time, give it a [Star](https://github.com/tody-agent/codymaster)! 🌟
+[![Discord](https://img.shields.io/badge/Discord-Join-7289da?logo=discord&logoColor=white)](https://discord.gg/codymaster)
 
-</div>
+### 🌟 If CodyMaster saves you time, give it a [Star](https://github.com/tody-agent/codymaster)! 🌟
 
 ---
 
@@ -42,14 +30,16 @@ You installed an AI coding agent. It's *brilliant*. It writes code faster than a
 
 But then reality hits:
 
-| 😤 What Actually Happens                                                            | 💀 The Real Cost                               |
-| ----------------------------------------------------------------------------------- | ---------------------------------------------- |
+
+| 😤 What Actually Happens                                                     | 💀 The Real Cost                               |
+| ---------------------------------------------------------------------------- | ---------------------------------------------- |
 | AI designs**differently every single time** — same brand, 3 different styles | Clients think you're 3 different companies     |
-| AI fixes one bug,**silently breaks 5 other things**                           | You redo the same work 3-4 times               |
-| AI**forgets everything** between sessions                                     | You re-explain the same codebase every morning |
-| AI writes zero tests, zero docs                                                     | Your codebase becomes a house of cards         |
+| AI fixes one bug,**silently breaks 5 other things**                          | You redo the same work 3-4 times               |
+| AI**forgets everything** between sessions                                    | You re-explain the same codebase every morning |
+| AI writes zero tests, zero docs                                              | Your codebase becomes a house of cards         |
 | You install 15 different skills —**none of them talk to each other**         | Frankenstein toolkit with zero synergy         |
-| Deploy to production =**deploy and pray** 🙏                                  | Broken deploys at 2 AM, no rollback            |
+| Deploy to production =**deploy and pray** 🙏                                 | Broken deploys at 2 AM, no rollback            |
+
 
 > *"AI gave me 100 hands. But without discipline, those hands created chaos."*
 > — **Tody Le**, Head of Product · 10+ years · Creator of CodyMaster
@@ -71,12 +61,14 @@ graph TD
     A --> E["🔒 DevOps Engineer<br/><i>cm-safe-deploy · cm-secret-shield · cm-security-gate · cm-identity-guard</i>"]
     A --> F["📝 Technical Writer<br/><i>cm-dockit · cm-content-factory · cm-auto-publisher</i>"]
     A --> G["📈 Growth Marketer<br/><i>cm-ads-tracker · cm-cro-methodology · cm-growth-hacking</i>"]
-    A --> H["🏭 Enterprise Dev<br/><i>cm-frappe-agent · cm-booking-calendar · cm-google-form</i>"]
+    A --> H["🏭 Enterprise Dev<br/><i>cm-booking-calendar · cm-google-form</i>"]
     style A fill:#fbc531,stroke:#e1b12c,color:#2f3640,stroke-width:3px
     classDef team fill:#2f3640,stroke:#dcdde1,stroke-width:1px,color:#fff;
     class B,C,D,E,F,G,H team;
 ```
 
+
+
 ---
 
 ## ⚡ What Makes CodyMaster Different
@@ -105,6 +97,8 @@ graph LR
     class A,B,C,D,E,F,G,H,I,J,K,L phase;
 ```
 
+
+
 ### 🧠 The Unified Brain: 5-Tier Memory + Smart Spine
 
 Your AI doesn't just execute — it **understands and remembers** using a multi-scale, 5-Tier + Smart Spine architecture that persists across sessions and machines:
@@ -116,18 +110,21 @@ Your AI doesn't just execute — it **understands and remembers** using a multi-
 5. **Structural Memory (`cm-codeintell`)** — AST-based CodeGraph. Up to 95% token compression for full codebase context.
 
 🦴 **Smart Spine (v4.6+)** — The nervous system connecting all 5 tiers:
+
 - **SQLite + FTS5** — BM25-ranked keyword search replaces flat JSON scans.
-- **Progressive Loading (L0/L1/L2)** — Context loaded at cheapest sufficient depth. 78% token savings.
+- **Progressive Loading (L0/L1/L2)** & **Smart Brain Router** — Context loaded at cheapest sufficient depth via a robust task classifier. Up to **80% token savings** on standard workflows.
+- **Skill Execution Cache** — Warm FTS5 cache tracks successful agent skill chains. Matches bypass token-heavy LLM decision loops for instant task resolution.
 - **cm:// URI Scheme** — Skills request context by URI, not file paths.
 - **Token Budget** — 200k window pre-allocated by category. No more silent overflow.
 - **Context Bus** — Skills share outputs in real-time within a chain.
-- **MCP Server** — 7 tools exposed to Claude Desktop and any MCP client.
-- **OpenViking Backend (optional)** — Swap SQLite for [OpenViking](https://github.com/volcengine/OpenViking): true vector semantic search, auto L0/L1/L2 generation, session compression. One config line: `storage.backend: viking`.
+- **MCP Server** — 18 tools exposed to Claude Desktop, Goose, and any MCP client (`src/mcp-context-server.ts`). Includes memory tools (`cm_memory_write`, `cm_natural`) plus advisory JSON surfaces (`cm_advisory_report`, `cm_advisory_metrics`, `cm_advisory_handoff`).
+- **Intelligent Skill Selection** — `selectTopSkills()` dynamically picks the 2-3 most task-relevant skills per chain execution. Backed by SkillsBench research: 2-3 focused skills = **+18.6pp** vs 4+ loaded statically.
+- **SQLite-first memory stack** — CodyMaster ships a supported default path built on SQLite + FTS5, token-budgeted context loading, and optional `qmd` / code intelligence layers. The older OpenViking path has been removed from the runtime.
 
 ☁️ **The Cloud Brain (`cm-notebooklm`)**
 High-value knowledge and design patterns are synced to NotebookLM, providing a universal, cross-machine "Soul" for your project. Auto-generate podcasts and flashcards to onboard human developers alongside the AI.
 
-📖 [Read the full Knowledge Architecture →](docs/architecture/knowledge-architecture.md)
+📖 [CodyMaster Brain & memory model →](docs/architecture/codymaster-brain.md)
 
 ### 🛡️ Multi-Layer Protection (Your Codebase Won't Get Destroyed)
 
@@ -153,6 +150,8 @@ flowchart LR
     style G fill:#4cd137,stroke:#44bd32,color:#fff
 ```
 
+
+
 > **Result:** Zero leaked secrets. Zero wrong-account deploys. Zero "worked on my machine" failures.
 
 ### 🎨 Design System Builder — Even From Old Products
@@ -161,7 +160,7 @@ Got a legacy product with no design system? **cm-design-system** scans your webs
 
 ### 📝 Zero Documentation? No Problem.
 
-Don't know what the old code does? **`cm-dockit`** reads your entire codebase and generates:
+Don't know what the old code does? `**cm-dockit`** reads your entire codebase and generates:
 
 - 📚 Technical architecture docs
 - 📖 User guides & SOPs
@@ -173,50 +172,51 @@ Don't know what the old code does? **`cm-dockit`** reads your entire codebase an
 
 ### 💡 Strategic Brainstorming (Design Thinking + 9 Windows)
 
-Before diving into code for complex requests, **`cm-brainstorm-idea`** evaluates your product using multi-dimensional analysis (Tech, Product, Design, Business). It generates 2-3 qualified options using the 9 Windows (TRIZ) framework and provides a visual UI Preview via **Pencil.dev** or **Google Stitch** to validate the direction before detailed planning. 
-
-📖 [Read more about the UI Preview Phase →](docs/workflows/brainstorm-ui-preview.md)
+Before diving into code for complex requests, `**cm-brainstorm-idea`** evaluates your product using multi-dimensional analysis (Tech, Product, Design, Business). It generates 2-3 qualified options using the 9 Windows (TRIZ) framework and provides a visual UI Preview via **Pencil.dev** or **Google Stitch** to validate the direction before detailed planning. 
 
+📖 [TRIZ-parallel workflow & UI preview handoff →](docs/architecture/triz-parallel-engine.md)
 
 ### 🏭 AI Content Factory v2.0 & Visual Dashboard
 
-Need to scale content? **`cm-content-factory`** is a self-learning, multi-agent content engine. It automatically researches, writes, audits (SEO & Persuasion), and deploys high-converting articles with the Content Mastery framework (StoryBrand + Cialdini) to guarantee conversion.
+Need to scale content? `**cm-content-factory`** is a self-learning, multi-agent content engine. It automatically researches, writes, audits (SEO & Persuasion), and deploys high-converting articles with the Content Mastery framework (StoryBrand + Cialdini) to guarantee conversion.
 
 Track it all on the **Visual Dashboard** (`cm-dashboard`): No more guessing. Track every task, every agent, every deployment on a real-time Kanban board. Pipeline progress, token tracker, event log — all on one screen.
 
-### 🧬 Self-Healing AI (Skills That Fix Themselves)
+### 🧬 Self-Healing Skills (Recovery, Search, and Evolution)
 
-CodyMaster doesn't just run skills — it **watches them, scores them, and heals them automatically.**
+CodyMaster ships a dedicated self-healing skill family for keeping the skill library usable as the repo evolves.
 
-- **`cm-skill-health`** monitors every invocation: success rate, token usage, error patterns.
-- **`cm-skill-evolution`** auto-patches degraded skills (Mode: FIX) when health scores drop below threshold.
-- **`cm-skill-search`** uses BM25 ranking to find the right skill for any task.
-- **`cm-skill-share`** exports & imports skills across teams and machines.
+- `**cm-skill-health`** audits a skill's real health from shipped signals: docs drift, broken references, retro notes, validation, and gates.
+- `**cm-skill-evolution`** (Skill Evolver) completes the autonomy loop with three modes: `FIX`, `DERIVED`, and `CAPTURED`. It modifies, clones, and generates new skills automatically based on analyzer recommendations, paired with anti-loop protection and `.md` backups.
+- `**cm-learning-promoter`** searches your database for recurring task struggles and automatically graduates them into permanently coded skills (`cm-learned-*`) when appropriately reinforced.
+- `**cm advisory report` / `metrics` / `handoff`** turn execution telemetry into a reviewable operator loop before any skill repair begins. 
+- Integrated Evolution commands (`cm evolve run/status/promote`) give immediate insight into all mutations.
+- `**cm-skill-chain` Auto-Dispatch** — sequence dispatching remains automated with task detection and multi-step handoffs.
+- `**cm-skill-search`** finds the best skill through `cm suggest`, skill indexes, and repo search.
+- `**cm-skill-share`** packages a skill safely across repos and machines without dropping companion files.
 
-> **Think of it like an immune system for your AI toolkit.** Skills that break get healed. Skills that work well get reinforced. Dead skills get archived.
-
-### 🏢 Enterprise-Ready: Frappe/ERPNext Full-Stack
-
-Building on Frappe Framework? **`cm-frappe-agent`** is a 7-layer architecture agent covering the entire Frappe lifecycle — from `bench new-app` to production deploys. Custom doctypes, workflows, REST APIs, permissions, fixtures, and performance optimization — all battle-tested.
+> **Think of it like an immune system for your AI toolkit.** First inspect the telemetry, then diagnose the skill, then repair it deliberately, then capture the learning.
 
 ### 🚀 Growth Hacking Engine
 
-Need popups, booking flows, or lead capture? **`cm-growth-hacking`** generates complete conversion systems: Bottom Sheet + Calendar CTA + Tracking. Auto-detects industry, selects the right pattern, wires up **`cm-booking-calendar`** for appointments and **`cm-ads-tracker`** for pixel tracking. Zero dependencies.
+Need popups, booking flows, or lead capture? `**cm-growth-hacking`** generates complete conversion systems: Bottom Sheet + Calendar CTA + Tracking. Auto-detects industry, selects the right pattern, wires up `**cm-booking-calendar`** for appointments and `**cm-ads-tracker**` for pixel tracking. Zero dependencies.
 
 ---
 
 ## 🆚 Scattered Skills vs CodyMaster
 
-|                            | 😵 15 Random Skills                         | 🧠 CodyMaster                                                         |
-| -------------------------- | ------------------------------------------- | --------------------------------------------------------------------- |
-| **Integration**      | Each skill is standalone, no shared context | 68+ skills that chain, share memory, and communicate                   |
-| **Lifecycle**        | Covers coding only                          | Covers Idea → Design → Code → Test → Deploy → Docs → Learn      |
-| **Memory**           | Forgets everything between sessions         | 5-tier Unified Brain: Sensory → Working → Long-term → Semantic → Structural + Cloud Brain. Optional **OpenViking** backend for vector search + auto memory compression. |
-| **Safety**           | YOLO deploys                                | 4-layer protection: TDD → Security → Isolation → Multi-gate deploy |
-| **Design**           | Random UI every time                        | Extracts & enforces design system + visual preview                    |
-| **Documentation**    | "Maybe write a README later"                | Auto-generates complete docs, SOPs, API refs from code                |
-| **Self-improvement** | Static — what you install is what you get  | Self-healing: monitors health → auto-patches → reinforces winners   |
-| **Maintenance**      | Update 15 repos separately                  | One `npm i -g codymaster` updates everything                        |
+
+|                      | 😵 15 Random Skills                         | 🧠 CodyMaster                                                                                                                                                           |
+| -------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Integration**      | Each skill is standalone, no shared context | 68+ skills that chain, share memory, and communicate                                                                                                                    |
+| **Lifecycle**        | Covers coding only                          | Covers Idea → Design → Code → Test → Deploy → Docs → Learn                                                                                                              |
+| **Memory**           | Forgets everything between sessions         | 5-tier Unified Brain: Sensory → Working → Long-term → Semantic → Structural + Cloud Brain, powered by SQLite + FTS5 by default with optional local semantic layers like `qmd`. |
+| **Safety**           | YOLO deploys                                | 4-layer protection: TDD → Security → Isolation → Multi-gate deploy                                                                                                      |
+| **Design**           | Random UI every time                        | Extracts & enforces design system + visual preview                                                                                                                      |
+| **Documentation**    | "Maybe write a README later"                | Auto-generates complete docs, SOPs, API refs from code                                                                                                                  |
+| **Self-improvement** | Static — what you install is what you get   | Advisory-driven self-healing: inspect telemetry → diagnose → repair with FIX / DERIVED / CAPTURED                                                                     |
+| **Maintenance**      | Update 15 repos separately                  | One `npm i -g codymaster` updates everything                                                                                                                            |
+
 
 ---
 
@@ -245,20 +245,70 @@ If you prefer:
 
 ## 🚀 1-Minute Install
 
-### 1. Install AI Skills (All Platforms)
+### ✨ NEW: Claude Desktop Plugin (Zero Terminal Required)
 
-One command installs all 68+ skills to your environment. Supports Claude Code, Gemini CLI, Cursor, Aider, Windsurf, Cline, OpenCode, and more:
+The easiest way to install CodyMaster — no npm, no terminal, no setup.
 
+**Claude Desktop / Claude Cowork:**
+
+Run the auto-installer to inject the MCP Servers into your Claude Desktop config automatically:
+
+```bash
+npx codymaster mcp-serve --install-claude
+```
+
+All 68+ skills will be wired up instantly via MCP stdio. Remember to restart Claude Desktop to load the new config.
+
+---
+
+### 2. Install AI Skills (All Other Platforms)
+
+CodyMaster uses **Native Plugin Extensions** for zero-friction installation. No bash scripts, no manual folder copying. Select your platform below:
+
+**Claude Code CLI:**
 ```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/tody-agent/codymaster/main/install.sh) --all
+claude plugin marketplace add tody-agent/codymaster
+claude plugin install cm@codymaster --scope user
 ```
 
-*For Cursor IDE users, you can also just type `/add-plugin cody-master` in your agent chat.*
+**Cursor (in Agent Chat):**
+```text
+/add-plugin cody-master
+```
 
-### 2. Install Mission Control Dashboard (Optional but Recommended)
+**Gemini CLI / Google Antigravity:**
+```bash
+gemini extensions install https://github.com/tody-agent/codymaster
+```
+*(Progressive disclosure: Add `@~/.gemini/antigravity/skills/cm-skill-index/SKILL.md` to your `GEMINI.md` to save tokens)*
+
+**OpenCode / OpenClaw:**
+Tell your agent:
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/tody-agent/codymaster/main/.opencode/INSTALL.md
+```
+
+**Codex:**
+Tell your agent:
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/tody-agent/codymaster/main/.codex/INSTALL.md
+```
+
+### 3. Install Mission Control Dashboard (Optional but Recommended)
 
 Visualize your progress, manage tasks, and track your 10x coding streak with Cody the Hamster 🐹.
 
+**Both are official:** install **per project** (no `-g`) or **globally**.
+
+Per project — keeps the CLI version with the repo (use `npx` so you do not need `cm` on your PATH):
+
+```bash
+npm install codymaster
+npx cm
+```
+
+Global — type `cm` from any directory:
+
 ```bash
 npm install -g codymaster
 cm
@@ -281,49 +331,96 @@ The CLI will greet you and keep you organized on your long coding sessions!
 │  ○ 🧩  Browse Skills
 ```
 
-</details>
+---
+
+## Use with Goose
+
+CodyMaster works as a [Goose](https://block.github.io/goose/) MCP extension, giving Goose persistent memory, skill orchestration, and token management.
+
+**3-step setup:**
+
+```bash
+# 1. Install CodyMaster
+npm install -g codymaster
+
+# 2. Get your Goose config snippet
+cm mcp-serve --print-config
+
+# 3. Paste the output into your Goose config (~/.config/goose/config.yaml)
+```
+
+See [full Goose integration guide](docs/integrations/goose.md) for details.
+
+---
+
+## 🎯 Real-World Use Cases
+
+> **Tip:** Start any session with `/cm:start <your goal>` and CodyMaster will pick the right skills automatically.
+
+
+| Scenario                                   | Skills Used                                                                      | What You Say                         |
+| ------------------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------ |
+| 🐛 **Fix a bug without breaking anything** | `cm-debugging` → `cm-tdd` → `cm-quality-gate`                                    | *"Debug this crash"*                 |
+| 🚀 **Ship a feature safely**               | `cm-planning` → `cm-tdd` → `cm-code-review` → `cm-safe-deploy`                   | *"Build the login flow"*             |
+| 🎨 **Build a new UI from scratch**         | `cm-ux-master` → `cm-design-system` → `cm-ui-preview`                            | *"Design the dashboard page"*        |
+| 🔒 **Deploy to production**                | `cm-secret-shield` → `cm-security-gate` → `cm-identity-guard` → `cm-safe-deploy` | *"Deploy to prod"*                   |
+| 📝 **Understand a legacy codebase**        | `cm-codeintell` → `cm-dockit`                                                    | *"What does this code do?"*          |
+| 📈 **Launch a landing page**               | `cm-brainstorm-idea` → `cm-cro-methodology` → `cm-content-factory`               | *"Build a landing page for my SaaS"* |
+| 🌍 **Add multi-language support**          | `cm-safe-i18n`                                                                   | *"Add Vietnamese and Japanese"*      |
+| 🔄 **Start a new project**                 | `cm-project-bootstrap` → `cm-planning`                                           | *"Bootstrap a Next.js SaaS"*         |
+| 🧠 **Resume after a break**                | `cm-continuity` → `cm-status`                                                    | *"What was I working on?"*           |
+| 🏭 **Scale SEO content**                   | `cm-content-factory` → `cm-auto-publisher` → `cm-ads-tracker`                    | *"Create 20 articles for my blog"*   |
+
 
 ---
 
-## 🧰 The 68+ Skill Arsenal
+## 🧰 The 60+ Skill Arsenal
 
-| Domain                    | Skills                                                                                                                                                          |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🔧 **Engineering**   | `cm-tdd` `cm-debugging` `cm-quality-gate` `cm-test-gate` `cm-code-review` `cm-clean-code`                                                                             |
-| ⚙️ **Operations**  | `cm-safe-deploy` `cm-identity-guard` `cm-secret-shield` `cm-security-gate` `cm-git-worktrees` `cm-terminal` `cm-safe-i18n`                                             |
+
+| Domain               | Skills                                                                                                                                        |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🔧 **Engineering**   | `cm-tdd` `cm-debugging` `cm-quality-gate` `cm-test-gate` `cm-code-review` `cm-clean-code`                                                     |
+| ⚙️ **Operations**    | `cm-safe-deploy` `cm-identity-guard` `cm-secret-shield` `cm-security-gate` `cm-git-worktrees` `cm-terminal` `cm-safe-i18n`                    |
 | 🎨 **Product & UX**  | `cm-planning` `cm-design-system` `cm-ux-master` `cm-ui-preview` `cm-project-bootstrap` `cm-jtbd` `cm-brainstorm-idea` `cm-dockit` `cm-readit` |
-| 📈 **Growth & CRO**    | `cm-content-factory` `cm-auto-publisher` `cm-ads-tracker` `cm-cro-methodology` `cm-growth-hacking` `cm-booking-calendar` `cm-google-form`                                                                                                   |
-| 🏢 **Enterprise**  | `cm-frappe-agent` `cm-reactor` `cm-notebooklm`                                                                                                  |
-| 🧬 **Self-Healing**   | `cm-skill-health` `cm-skill-evolution` `cm-skill-search` `cm-skill-share` `cm-skill-chain` `cm-skill-mastery` `cm-skill-index`             |
-| 🎯 **Orchestration** | `cm-execution` `cm-continuity` `cm-deep-search` `cm-codeintell` `cm-how-it-work`             |
-| 🖥️ **Workflow**    | `cm-start` `cm-dashboard` `cm-status`                                                                                                                     |
+| 📈 **Growth & CRO**  | `cm-content-factory` `cm-auto-publisher` `cm-ads-tracker` `cm-cro-methodology` `cm-growth-hacking` `cm-booking-calendar` `cm-google-form`     |
+| 🏢 **Enterprise**    | `cm-reactor` `cm-notebooklm`                                                                                                                  |
+| 🧬 **Self-Healing**  | `cm-skill-health` `cm-skill-evolution` `cm-skill-search` `cm-skill-share` `cm-skill-chain` `cm-skill-mastery` `cm-skill-index`                |
+| 🎯 **Orchestration** | `cm-execution` `cm-continuity` `cm-deep-search` `cm-codeintell` `cm-how-it-work`                                                              |
+| 🖥️ **Workflow**     | `cm-start` `cm-dashboard` `cm-status`                                                                                                         |
+
 
 ---
 
 ## 🎮 Commands
 
+Run `cm --help` (or `node dist/index.js --help` from a clone) for the **authoritative** list. Highlights from `src/cli/command-registry.ts`:
+
 ```
-cm                          → Quick menu with Cody 🐹
-cm task add "..."           → Add a task
-cm task list                → View tasks
-cm status                   → Project health
-cm dashboard                → Open Mission Control
-cm list                     → Browse 68+ skills
-cm profile                  → Your stats & achievements
-cm deploy <env>             → Record deployment
-cm continuity index         → Regenerate L0 memory indexes
-cm continuity budget        → Show token budget allocation
-cm continuity bus           → View context bus state
-cm continuity mcp           → Print MCP server config
-cm continuity migrate       → Migrate JSON → SQLite
-cm continuity export        → Export SQLite → JSON
-cm resolve <uri>            → Resolve any cm:// URI
-
-# OpenViking backend (optional — semantic vector search)
-pip install openviking && openviking start
-# Then set storage.backend: viking in .cm/config.yaml
+cm, codymaster              → CLI entry
+cm status                   → Task & project summary
+cm task <cmd> [args...]     → Task management
+cm project <cmd> [args...]  → Project management
+cm deploy <cmd> [args...]   → Deploy / rollback / history / changelog
+cm dashboard [start|stop|status|open|url] → Mission Control (default :6969)
+cm agent [status|memory|brain|learn]      → Working memory / learnings
+cm brain                    → Continuity + next actions
+cm chain <cmd> [args...]    → Skill chain execution
+cm config [key] [value]   → Config helper
+cm open                     → Open dashboard in browser
+cm browse …                 → Local Playwright browse daemon (QA)
+cm guardian …               → Destructive-command / path checks
+cm index skills             → Zero-Token tech stack and skill local indexer
+cm sprint …                 → Sprint pipeline + .cm/sprint
+cm design-studio [init|status]
+cm distro validate …        → Validate skill pack layout
 ```
 
+**Memory, bus, budgets, `cm://` resolution:** use the **MCP context server** — see [docs/api/api-reference.md](docs/api/api-reference.md).
+
+**Engineering (browse, guardian, sprint):** [docs/workflows/engineering-pipeline.md](docs/workflows/engineering-pipeline.md) · [docs/browse-daemon.md](docs/browse-daemon.md) · [docs/workflows/guardian-hooks.md](docs/workflows/guardian-hooks.md) · [docs/architecture/servers-and-mcp.md](docs/architecture/servers-and-mcp.md)
+
+Legacy configs that still say `storage.backend: viking` are automatically routed back to SQLite.
+
 **Slash Commands (inside AI agents):**
 
 ```
@@ -349,8 +446,9 @@ pip install openviking && openviking start
 ## 📚 Resources
 
 - 🌍 [Website](https://cody.todyle.com) — Overview & demos
-- 📖 [Documentation](https://cody.todyle.com/docs) — Full deep-dive
-- 🛠️ [Skills Reference](skills/) — Browse all 68+ SKILL.md files
+- 📖 [Documentation (site)](https://cody.todyle.com/docs) — Hosted deep-dive
+- 📘 [Documentation (repo)](docs/index.md) — Markdown source; run `npm run docs:dev` for VitePress
+- 🛠️ [Skills Reference](skills/) — Browse **56** bundled `cm-`* SKILL.md packs (profiles/installer can add more)
 - 📖 [Our Story](https://cody.todyle.com/story) — Why this exists
 
 ---
@@ -361,13 +459,12 @@ pip install openviking && openviking start
 2. Fork → Create `skills/cm-your-skill/SKILL.md`
 3. Submit a Pull Request
 
+CI runs `npm ci` and `npm run test:gate:kit` on pushes and pull requests (see `.github/workflows/ci.yml`).
+
 ---
 
-<div align="center">
+*ISC License — Free to use, modify, and distribute.*   
 
-*MIT License — Free to use, modify, and distribute.* `<br/>`
 **Built with ❤️ for the vibe coding community.**
 
 *"CodyMaster" = "Code Đi" (Vietnamese: "Go code!") — just start building.*
-
-</div>