kodelyth-ecc 2.23.1 → 2.24.0

package/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.0 — the update notice now tells you why (October 2026)
+
+The CLI has always polled npm for new versions and cached the answer for 24
+hours. That monthly touchpoint was spent on almost nothing: the result surfaced
+only in the interactive menu, as a version number and an install command.
+
+```
+Update to v2.23.2
+npm i -g kodelyth-ecc  (installs new version)
+```
+
+A version number is a nag. It states a fact and gives no reason to act on it.
+
+### It now links what changed
+
+```
+Update to v2.24.0
+what changed: github.com/sifxprime/kodelyth-ecc/releases/tag/v2.24.0
+```
+
+`check()` returns a `releaseNotes` URL alongside the version, so every consumer
+gets it without doing its own string building.
+
+### doctor surfaces it too
+
+A second natural touchpoint — `doctor` is run deliberately, usually when
+somebody is already paying attention:
+
+```
+! version — v2.23.2 installed, v2.24.0 available
+    → npm i -g kodelyth-ecc    what changed: .../releases/tag/v2.24.0
+```
+
+### Cache-only, on purpose
+
+The new `cachedCheck()` reads the 24-hour cache and never touches the network.
+`doctor` is the command people reach for when something is **already** wrong, so
+it must not wait on the registry — and an unreachable npm is not a fact about
+the health of your install. A cold or stale cache yields nothing and the row is
+simply absent, rather than reported as a warning. A check that fires on "I could
+not reach the network" teaches people to ignore the output.
+
+`run()` stays synchronous and takes the result as a parameter, so it remains
+testable and `doctor` adds no latency.
+
+Verified across every state: a newer version warns with the link, being current
+passes, a stale cache is ignored, a corrupt cache leaves `doctor` working on its
+11 checks, and a cold cache omits the row.
+
+### What this does not do
+
+No nagging on every command. Nothing auto-updates. Nothing blocks.
+
+**647 tests passing.**
+
+## v2.23.2 — the README leads with the product, not the badges (October 2026)
+
+No change to the toolkit. The README **is** the npm landing page, and npm only
+re-renders it on publish, so this exists to make the rewrite actually reach
+anyone.
+
+### What changed
+
+It opened with a logo, a 900px hero and **21 shields — 35 lines before a single
+word of what this is**. Someone arriving from npm search had to scroll past a
+wall of badges to learn whether they cared.
+
+The strongest thing in the file was buried too: the routing transcript, where
+
+```
+You:   "I've been staring at this NullPointerException for two hours,
+        I'm losing my mind."
+
+AI:    → Routing to debug-detective
+```
+
+explains the product faster than any paragraph could, and sat at line 55.
+
+The first screen is now: logo, one-line claim, that transcript, `npx
+kodelyth-ecc`, and the platform list. Badges and hero follow below a rule.
+
+**Nothing was cut.** All 1,100+ lines and every badge are intact — just no
+longer first.
+
+### Corrected while reading
+
+The comparison tables still claimed 194 skills, 97 slash commands and "22+"
+quality hooks in three places. Actual: 196, 103, 44. Those tables make direct
+claims against other kits, so wrong numbers there cost more than anywhere else.
+
+Verified: 82 code fences balanced, 19 `div`s balanced, zero stale figures left,
+and a line-by-line diff against the previous file confirming no content lost.
+
+**647 tests passing.**
+
 ## v2.23.1 — the shop window said the wrong numbers (October 2026)
 
 No change to the toolkit. This exists because npm metadata only refreshes when

package/README.md

@@ -5,7 +5,38 @@
   <img src="brand/ecc-lockup-light.svg" alt="Kodelyth ECC — Elite Code Crew" width="440"/>
 </picture>
 
-<br><br>
+
+</div>
+
+### Describe your problem in plain words. The right specialist shows up.
+
+No agent names to memorise. No prompt engineering. Nothing leaves your machine.
+
+```
+You:   "I've been staring at this NullPointerException for two hours,
+        I'm losing my mind."
+
+AI:    → Routing to debug-detective (your error + frustration matches the bug-tracking signal)
+
+       That kind of bug is exhausting — let's trace it properly so we
+       fix the root cause, not the symptom.
+
+       First, can you share the full stack trace and...
+```
+
+You never typed `use debug-detective`. You did not have to — ECC read the intent,
+picked the specialist out of 70, and told you which one it chose and why.
+
+```bash
+npx kodelyth-ecc
+```
+
+Works on **macOS, Linux and Windows** with Claude Code, Windsurf, Cursor, Codex CLI,
+Google Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi and Gemini CLI.
+
+---
+
+<div align="center">
 
 <img src="social/readme-hero.svg" alt="Kodelyth ECC — AI Agent Toolkit" width="900"/>
 
@@ -31,6 +62,7 @@
 ![Codebase Graph](https://img.shields.io/badge/Codebase%20Graph-158%20languages-green)
 ![Interactive CLI](https://img.shields.io/badge/CLI-interactive%20menu-blue)
 
+
 </div>
 
 **Kodelyth ECC** is a production-grade AI coding toolkit — **70 specialist agents (incl. an 8-agent devil-mode adversarial crew), 196 skills, 103 commands**, a god-tier **semantic intent-routing system**, local self-learning memory, MCP server, swarm orchestrator, and an observability dashboard — all local, zero telemetry.
@@ -48,23 +80,13 @@ Works with **Claude Code**, **Windsurf**, **Cursor**, **Codex CLI**, **Google An
 
 ---
 
-## Why ECC ≠ Another Agent Collection
-
-Most "AI agent kits" are folders of markdown files you have to remember the names of. **ECC is infrastructure** — a layered system where intent routing, compound memory, parallel orchestration, and quality hooks all reinforce each other.
-
-```
-You:   "I've been staring at this NullPointerException for two hours,
-        I'm losing my mind."
-
-AI:    → Routing to debug-detective (your error + frustration matches the bug-tracking signal)
+You never typed `use debug-detective`. You didn't have to. The toolkit read the intent, picked the specialist, and announced the routing. Next time you can invoke it directly — but you don't have to remember names to get senior-grade help.
 
-       That kind of bug is exhausting — let's trace it properly so we
-       fix the root cause, not the symptom.
+---
 
-       First, can you share the full stack trace and...
-```
+## Why ECC ≠ Another Agent Collection
 
-You never typed `use debug-detective`. You didn't have to. The toolkit read the intent, picked the specialist, and announced the routing. Next time you can invoke it directly — but you don't have to remember names to get senior-grade help.
+Most "AI agent kits" are folders of markdown files you have to remember the names of. **ECC is infrastructure** — a layered system where intent routing, compound memory, parallel orchestration, and quality hooks all reinforce each other.
 
 ### The Layer Stack
 
@@ -76,7 +98,7 @@ You never typed `use debug-detective`. You didn't have to. The toolkit read the
 | **103 commands** | Slash workflows (`/tdd`, `/arena`, `/devil-mode`, `/team-review`) | Limited or none |
 | **8 parallel commands** | Fire 3-8 agents simultaneously, aggregate results | Rare |
 | **Compound memory** | BM25 local recall + auto-inject + project lessons | Cloud-only or absent |
-| **22+ hooks** | Quality gates, secret scan, project-DNA detection | Often missing |
+| **44 hook entries** | Quality gates, secret scan, project-DNA detection | Often missing |
 | **11 IDE platforms** | Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi, Gemini CLI (13 install targets) | 1-2 platforms typical |
 | **Zero telemetry** | Everything stays on your disk; verifiable | Many kits phone home |
 
@@ -85,15 +107,15 @@ You never typed `use debug-detective`. You didn't have to. The toolkit read the
 | Feature | **Kodelyth ECC** | `agency-agents` | `awesome-claude-agents` | Generic prompt libs |
 |---|---|---|---|---|
 | Specialist agents | **70** | ~30 | ~20 | Varies |
-| Skills as separate layer | ✅ 194 | ❌ | ❌ | ❌ |
-| Slash commands | ✅ 97 | Some | Some | ❌ |
+| Skills as separate layer | ✅ 196 | ❌ | ❌ | ❌ |
+| Slash commands | ✅ 103 | Some | Some | ❌ |
 | **Parallel multi-agent commands** | ✅ 8 (incl. `/devil-mode`) | ❌ | ❌ | ❌ |
 | **Intent routing (plain language → agent)** | ✅ 10-tier rule | ❌ | ❌ | ❌ |
 | **Local BM25 self-learning memory** | ✅ | ❌ | ❌ | ❌ |
 | **Compound learning from corrections** | ✅ `tasks/lessons.md` | ❌ | ❌ | ❌ |
 | **Adversarial / red-team agents** | ✅ 8 (devil-mode) | ❌ | ❌ | ❌ |
 | **Adversarial build/attack loop** | ✅ `/arena` — scored, verified, converges | ❌ | ❌ | ❌ |
-| Quality hooks | ✅ 22+ | Some | ❌ | ❌ |
+| Quality hooks | ✅ 44 | Some | ❌ | ❌ |
 | IDE platforms | **11** (Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi, Gemini CLI) | 1-2 | 1 | Varies |
 | Telemetry | ❌ none | Varies | ❌ | Varies |
 | Test coverage | ✅ 647 tests | ❌ | ❌ | ❌ |
@@ -262,7 +284,7 @@ npx kodelyth-ecc --bundle red-team        # Security engineer — devil-mode + a
 npx kodelyth-ecc --bundle enterprise      # Compliance / audit team — SBOM, license, supply chain
 ```
 
-Each bundle installs the full ECC toolkit (all 70 agents, 196 skills, 103 commands, 22+ hooks), adds a `BUNDLE.md` cheat sheet, and biases the AI toward audience-fit workflows on every session.
+Each bundle installs the full ECC toolkit (all 70 agents, 196 skills, 103 commands, 44 hook entries), adds a `BUNDLE.md` cheat sheet, and biases the AI toward audience-fit workflows on every session.
 
 Combine with any target:
 

package/VERSION

@@ -1 +1 @@
-2.23.1
+2.24.0

package/bin/kodelyth-ecc.js

@@ -707,7 +707,23 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
 
 if (args[0] === 'doctor') {
   const { run, PASS, WARN, FAIL } = require(path.join(ROOT, 'scripts', 'doctor-health.js'));
-  const report = run();
+
+  // Cache-only, deliberately. doctor is what people run when something is
+  // already wrong, so it must not wait on the registry — and an unreachable npm
+  // is not a fact about the health of their install. The cache is warmed by the
+  // interactive menu; a cold one yields null and the version row is simply
+  // absent.
+  let update;
+  try {
+    const { cachedCheck } = require(path.join(ROOT, 'scripts', 'cli', 'update-check.js'));
+    const vf = path.join(ROOT, 'VERSION');
+    const current = fs.existsSync(vf)
+      ? fs.readFileSync(vf, 'utf8').trim()
+      : require(path.join(ROOT, 'package.json')).version;
+    update = cachedCheck(current) || undefined;
+  } catch { /* never let a version hint break the health check */ }
+
+  const report = run({ update });
   if (args.includes('--json')) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
     process.exit(report.summary.fail > 0 ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.23.1",
+  "version": "2.24.0",
   "description": "Production-grade AI coding toolkit — 70 agents (incl. devil-mode adversarial crew), 196 skills, 103 commands, parallel multi-agent commands, semantic intent routing, self-learning memory, and a built-in MCP server (16 tools / 6 prompts / 377 resources) that bridges to Claude Desktop, LangGraph, AutoGen, CrewAI, and OpenAI Agents SDK. Works on macOS, Linux and Windows with Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, RooCode, Aider, Kimi, and Gemini CLI.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",

package/scripts/cli/menu.js

@@ -47,7 +47,9 @@ async function buildOptions({ ROOT }) {
   if (update.updateAvailable) {
     opts.push({
       label: `Update to v${update.latest}`,
-      hint:  'npm i -g kodelyth-ecc  (installs new version)',
+      // Say what it is AND where to read what changed. A version number alone
+      // is a nag; a reason is an invitation.
+      hint:  `what changed: ${update.releaseNotes || 'github.com/sifxprime/kodelyth-ecc/releases'}`,
       run:   () => runUpdate(),
       badge: 'NEW',
     });

package/scripts/cli/update-check.js

@@ -54,7 +54,19 @@ function cmpVersion(a, b) {
   return 0;
 }
 
-// Public: returns { current, latest, updateAvailable, cached } or nulls on failure.
+/**
+ * Where to read what actually changed in a given version.
+ *
+ * "update available: v2.23.2" is a nag — it tells you a number and no reason.
+ * A link to the release notes turns the same notice into something worth acting
+ * on, which is the whole point of owning a monthly touchpoint.
+ */
+function releaseNotesUrl(version) {
+  if (!version) return null;
+  return `https://github.com/sifxprime/kodelyth-ecc/releases/tag/v${version}`;
+}
+
+// Public: returns { current, latest, updateAvailable, cached, releaseNotes } or nulls on failure.
 async function check({ current, force = false } = {}) {
   if (!force) {
     const c = readCache();
@@ -63,6 +75,7 @@ async function check({ current, force = false } = {}) {
         current, latest: c.latest,
         updateAvailable: c.latest && cmpVersion(c.latest, current) > 0,
         cached: true,
+        releaseNotes: releaseNotesUrl(c.latest),
       };
     }
   }
@@ -72,7 +85,30 @@ async function check({ current, force = false } = {}) {
     current, latest,
     updateAvailable: !!(latest && cmpVersion(latest, current) > 0),
     cached: false,
+    releaseNotes: releaseNotesUrl(latest),
+  };
+}
+
+/**
+ * Cache-only read. No network, no promise, no timeout — safe to call from a
+ * synchronous command.
+ *
+ * doctor uses this rather than check(): it is the command people run when
+ * something is already wrong, so it must never wait on the registry. The cache
+ * is warmed by the interactive menu, which does hit the network. A cold cache
+ * simply yields null and the version row does not appear, which is correct —
+ * "I could not reach npm" is not a fact about the health of your install.
+ */
+function cachedCheck(current) {
+  const c = readCache();
+  if (!c || !c.latest) return null;
+  return {
+    current,
+    latest: c.latest,
+    updateAvailable: cmpVersion(c.latest, current) > 0,
+    cached: true,
+    releaseNotes: releaseNotesUrl(c.latest),
   };
 }
 
-module.exports = { check, cmpVersion };
+module.exports = { check, cachedCheck, cmpVersion, releaseNotesUrl };

package/scripts/doctor-health.js

@@ -155,7 +155,29 @@ function checkCodebaseGraph() {
 
 // ── Runner ───────────────────────────────────────────────────────────────────
 
-function run() {
+/**
+ * Whether the installed version is current.
+ *
+ * Takes a pre-fetched result rather than doing its own network call, so run()
+ * stays synchronous and testable, and doctor never blocks on the registry. When
+ * nothing was fetched — offline, timed out, caller did not bother — this is
+ * silently absent rather than a warning. "Could not reach npm" is not a health
+ * problem with the user's install, and reporting it as one trains people to
+ * ignore the output.
+ */
+function checkVersion(update) {
+  if (!update || !update.latest) return null;
+  if (!update.updateAvailable) {
+    return { status: PASS, detail: `v${update.current} is the latest` };
+  }
+  return {
+    status: WARN,
+    detail: `v${update.current} installed, v${update.latest} available`,
+    fix: `npm i -g kodelyth-ecc    what changed: ${update.releaseNotes || 'github.com/sifxprime/kodelyth-ecc/releases'}`,
+  };
+}
+
+function run({ update } = {}) {
   const checks = [
     check('binaries',            checkBinaries),
     check('install-target',      checkInstallTarget),
@@ -169,6 +191,11 @@ function run() {
     check('terse',               checkTerse),
     check('codebase-graph',      checkCodebaseGraph),
   ];
+
+  // Appended rather than inlined: it is the only check that depends on the
+  // network, and it drops out entirely when no result was supplied.
+  const version = checkVersion(update);
+  if (version) checks.push({ id: 'version', ...version });
   const summary = {
     total: checks.length,
     pass: checks.filter(c => c.status === PASS).length,
@@ -178,4 +205,4 @@ function run() {
   return { checks, summary };
 }
 
-module.exports = { run, PASS, WARN, FAIL };
+module.exports = { run, checkVersion, PASS, WARN, FAIL };