@ekkos/cli 1.3.7 → 1.3.8

package/dist/local/stack-detection.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Stack Detection — detect project language, framework, and package manager
+ *
+ * Pure functions with zero dependencies. Works on both local filesystem
+ * (via file list) and remote (via GitHub tree listing).
+ *
+ * Living Docs V4 — Phase 4: Language-Adapted Discovery
+ */
+export interface StackInfo {
+    language: string;
+    framework?: string;
+    packageManager?: string;
+    version?: string;
+}
+/**
+ * Detect the stack for a directory by checking for manifest files.
+ * Works on both local filesystem (check file existence) and remote (file list).
+ * @param files - list of relative file paths in the directory
+ * @param readFile - optional async function to read file contents for deeper detection
+ */
+export declare function detectStack(files: string[], readFile?: (path: string) => Promise<string | null>): Promise<StackInfo>;

package/dist/local/stack-detection.js

@@ -0,0 +1,406 @@
+"use strict";
+/**
+ * Stack Detection — detect project language, framework, and package manager
+ *
+ * Pure functions with zero dependencies. Works on both local filesystem
+ * (via file list) and remote (via GitHub tree listing).
+ *
+ * Living Docs V4 — Phase 4: Language-Adapted Discovery
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectStack = detectStack;
+/**
+ * Detect the stack for a directory by checking for manifest files.
+ * Works on both local filesystem (check file existence) and remote (file list).
+ * @param files - list of relative file paths in the directory
+ * @param readFile - optional async function to read file contents for deeper detection
+ */
+async function detectStack(files, readFile) {
+    const fileSet = new Set(files.map(f => f.replace(/^\.\//, '')));
+    const hasFile = (name) => fileSet.has(name);
+    const hasGlob = (pattern) => {
+        // Simple suffix match for patterns like '*.csproj'
+        if (pattern.startsWith('*')) {
+            const suffix = pattern.slice(1);
+            return files.some(f => f.endsWith(suffix));
+        }
+        return fileSet.has(pattern);
+    };
+    // ── Package manager detection ──────────────────────────────────────────
+    const packageManager = detectPackageManager(fileSet);
+    // ── Language + framework detection (ordered by specificity) ────────────
+    // TypeScript / JavaScript
+    if (hasFile('package.json')) {
+        const info = await detectNodeStack(readFile);
+        return { ...info, packageManager: packageManager ?? info.packageManager };
+    }
+    // Rust
+    if (hasFile('Cargo.toml')) {
+        const info = await detectRustStack(readFile);
+        return { ...info, packageManager: packageManager ?? 'cargo' };
+    }
+    // Go
+    if (hasFile('go.mod')) {
+        const info = await detectGoStack(readFile);
+        return { ...info, packageManager: packageManager ?? 'go' };
+    }
+    // Python
+    if (hasFile('pyproject.toml') || hasFile('setup.py') || hasFile('requirements.txt') || hasFile('Pipfile') || hasFile('setup.cfg')) {
+        const info = await detectPythonStack(fileSet, readFile);
+        return { ...info, packageManager: packageManager ?? info.packageManager };
+    }
+    // Ruby
+    if (hasFile('Gemfile')) {
+        const info = await detectRubyStack(readFile);
+        return { ...info, packageManager: packageManager ?? 'bundle' };
+    }
+    // Java / Kotlin
+    if (hasFile('pom.xml') || hasFile('build.gradle') || hasFile('build.gradle.kts') || hasFile('settings.gradle') || hasFile('settings.gradle.kts')) {
+        const info = await detectJavaStack(fileSet, readFile);
+        return { ...info, packageManager: packageManager ?? info.packageManager };
+    }
+    // Dart / Flutter
+    if (hasFile('pubspec.yaml')) {
+        return { language: 'dart', framework: 'flutter', packageManager: 'pub' };
+    }
+    // Elixir / Phoenix
+    if (hasFile('mix.exs')) {
+        const info = await detectElixirStack(readFile);
+        return { ...info, packageManager: 'mix' };
+    }
+    // PHP / Laravel
+    if (hasFile('composer.json')) {
+        const info = await detectPhpStack(readFile);
+        return { ...info, packageManager: 'composer' };
+    }
+    // C# / .NET
+    if (hasGlob('*.csproj') || hasGlob('*.sln') || hasGlob('*.fsproj')) {
+        return { language: 'csharp', framework: 'dotnet', packageManager: 'nuget' };
+    }
+    // C/C++ — only if no other manifest was found
+    if (hasFile('Makefile') || hasFile('CMakeLists.txt') || hasFile('meson.build')) {
+        return { language: 'cpp', packageManager: packageManager ?? undefined };
+    }
+    return { language: 'unknown', packageManager: packageManager ?? undefined };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+function detectPackageManager(fileSet) {
+    if (fileSet.has('pnpm-lock.yaml') || fileSet.has('pnpm-workspace.yaml'))
+        return 'pnpm';
+    if (fileSet.has('yarn.lock'))
+        return 'yarn';
+    if (fileSet.has('package-lock.json'))
+        return 'npm';
+    if (fileSet.has('bun.lockb') || fileSet.has('bun.lock'))
+        return 'bun';
+    if (fileSet.has('poetry.lock'))
+        return 'poetry';
+    if (fileSet.has('Pipfile.lock'))
+        return 'pipenv';
+    if (fileSet.has('uv.lock'))
+        return 'uv';
+    if (fileSet.has('Cargo.lock'))
+        return 'cargo';
+    if (fileSet.has('go.sum'))
+        return 'go';
+    if (fileSet.has('Gemfile.lock'))
+        return 'bundle';
+    return undefined;
+}
+async function detectNodeStack(readFile) {
+    const base = { language: 'typescript', packageManager: 'npm' };
+    if (!readFile)
+        return base;
+    const raw = await readFile('package.json');
+    if (!raw)
+        return base;
+    try {
+        const pkg = JSON.parse(raw);
+        const allDeps = {
+            ...pkg.dependencies,
+            ...pkg.devDependencies,
+        };
+        // Check if actually TypeScript
+        if (!allDeps['typescript'] && !allDeps['ts-node'] && !allDeps['tsx']) {
+            base.language = 'javascript';
+        }
+        // Framework detection — ordered by specificity (most specific first)
+        const frameworkMap = [
+            ['next', 'next'],
+            ['nuxt', 'nuxt'],
+            ['remix', 'remix'],
+            ['@sveltejs/kit', 'sveltekit'],
+            ['svelte', 'svelte'],
+            ['@angular/core', 'angular'],
+            ['vue', 'vue'],
+            ['react', 'react'],
+            ['hono', 'hono'],
+            ['fastify', 'fastify'],
+            ['express', 'express'],
+            ['koa', 'koa'],
+            ['@nestjs/core', 'nest'],
+            ['astro', 'astro'],
+            ['gatsby', 'gatsby'],
+            ['@electron/rebuild', 'electron'],
+            ['electron', 'electron'],
+        ];
+        for (const [dep, framework] of frameworkMap) {
+            if (allDeps[dep]) {
+                base.framework = framework;
+                base.version = allDeps[dep]?.replace(/^[\^~>=<]/, '');
+                break;
+            }
+        }
+        return base;
+    }
+    catch {
+        return base;
+    }
+}
+async function detectRustStack(readFile) {
+    const base = { language: 'rust', packageManager: 'cargo' };
+    if (!readFile)
+        return base;
+    const raw = await readFile('Cargo.toml');
+    if (!raw)
+        return base;
+    const content = raw.toLowerCase();
+    const frameworkMap = [
+        ['actix-web', 'actix'],
+        ['axum', 'axum'],
+        ['rocket', 'rocket'],
+        ['warp', 'warp'],
+        ['tide', 'tide'],
+        ['tokio', 'tokio'],
+        ['leptos', 'leptos'],
+        ['yew', 'yew'],
+        ['tauri', 'tauri'],
+    ];
+    for (const [dep, framework] of frameworkMap) {
+        if (content.includes(dep)) {
+            base.framework = framework;
+            // Try to extract version: dep = "X.Y.Z" or dep = { version = "X.Y.Z" }
+            const versionMatch = raw.match(new RegExp(`${dep}\\s*=\\s*"([^"]+)"`, 'i'))
+                || raw.match(new RegExp(`${dep}\\s*=\\s*\\{[^}]*version\\s*=\\s*"([^"]+)"`, 'i'));
+            if (versionMatch)
+                base.version = versionMatch[1];
+            break;
+        }
+    }
+    return base;
+}
+async function detectGoStack(readFile) {
+    const base = { language: 'go', packageManager: 'go' };
+    if (!readFile)
+        return base;
+    const raw = await readFile('go.mod');
+    if (!raw)
+        return base;
+    const frameworkMap = [
+        ['github.com/gin-gonic/gin', 'gin'],
+        ['github.com/labstack/echo', 'echo'],
+        ['github.com/gofiber/fiber', 'fiber'],
+        ['github.com/go-chi/chi', 'chi'],
+        ['github.com/gorilla/mux', 'gorilla'],
+        ['github.com/beego/beego', 'beego'],
+        ['github.com/revel/revel', 'revel'],
+        ['google.golang.org/grpc', 'grpc'],
+        ['github.com/bufbuild/connect-go', 'connect'],
+    ];
+    for (const [dep, framework] of frameworkMap) {
+        if (raw.includes(dep)) {
+            base.framework = framework;
+            // Try to extract version from go.mod require block
+            const versionMatch = raw.match(new RegExp(`${dep.replace(/\//g, '\\/')}\\s+v([\\d.]+)`));
+            if (versionMatch)
+                base.version = versionMatch[1];
+            break;
+        }
+    }
+    return base;
+}
+async function detectPythonStack(fileSet, readFile) {
+    const base = { language: 'python', packageManager: 'pip' };
+    // Refine package manager
+    if (fileSet.has('poetry.lock') || fileSet.has('pyproject.toml'))
+        base.packageManager = 'poetry';
+    if (fileSet.has('Pipfile') || fileSet.has('Pipfile.lock'))
+        base.packageManager = 'pipenv';
+    if (fileSet.has('uv.lock'))
+        base.packageManager = 'uv';
+    if (!readFile)
+        return base;
+    // Read all possible manifest files for framework detection
+    const contents = [];
+    for (const manifest of ['requirements.txt', 'pyproject.toml', 'Pipfile', 'setup.py', 'setup.cfg']) {
+        if (fileSet.has(manifest)) {
+            const raw = await readFile(manifest);
+            if (raw)
+                contents.push(raw.toLowerCase());
+        }
+    }
+    const combined = contents.join('\n');
+    const frameworkMap = [
+        ['django', 'django'],
+        ['fastapi', 'fastapi'],
+        ['flask', 'flask'],
+        ['starlette', 'starlette'],
+        ['tornado', 'tornado'],
+        ['sanic', 'sanic'],
+        ['aiohttp', 'aiohttp'],
+        ['streamlit', 'streamlit'],
+        ['gradio', 'gradio'],
+        ['celery', 'celery'],
+        ['scrapy', 'scrapy'],
+    ];
+    for (const [dep, framework] of frameworkMap) {
+        if (combined.includes(dep)) {
+            base.framework = framework;
+            // Try to extract version from requirements.txt format: django==4.2.0
+            const versionMatch = combined.match(new RegExp(`${dep}[=~><]+([\\d.]+)`));
+            if (versionMatch)
+                base.version = versionMatch[1];
+            break;
+        }
+    }
+    return base;
+}
+async function detectRubyStack(readFile) {
+    const base = { language: 'ruby', packageManager: 'bundle' };
+    if (!readFile)
+        return base;
+    const raw = await readFile('Gemfile');
+    if (!raw)
+        return base;
+    const content = raw.toLowerCase();
+    const frameworkMap = [
+        ['rails', 'rails'],
+        ['sinatra', 'sinatra'],
+        ['hanami', 'hanami'],
+        ['grape', 'grape'],
+        ['roda', 'roda'],
+    ];
+    for (const [dep, framework] of frameworkMap) {
+        if (content.includes(`'${dep}'`) || content.includes(`"${dep}"`)) {
+            base.framework = framework;
+            // Try to extract version: gem 'rails', '~> 7.0'
+            const versionMatch = raw.match(new RegExp(`['"]${dep}['"]\\s*,\\s*['"][~>=<]*\\s*([\\d.]+)['"]`, 'i'));
+            if (versionMatch)
+                base.version = versionMatch[1];
+            break;
+        }
+    }
+    return base;
+}
+async function detectJavaStack(fileSet, readFile) {
+    const base = { language: 'java' };
+    // Package manager
+    if (fileSet.has('pom.xml')) {
+        base.packageManager = 'maven';
+    }
+    else if (fileSet.has('build.gradle') || fileSet.has('build.gradle.kts')) {
+        base.packageManager = 'gradle';
+    }
+    if (!readFile)
+        return base;
+    // Check for Kotlin
+    const gradleKts = fileSet.has('build.gradle.kts');
+    if (gradleKts) {
+        const raw = await readFile('build.gradle.kts');
+        if (raw && (raw.includes('kotlin') || raw.includes('org.jetbrains.kotlin'))) {
+            base.language = 'kotlin';
+        }
+    }
+    // Framework detection from build files
+    const buildFiles = ['pom.xml', 'build.gradle', 'build.gradle.kts'];
+    for (const buildFile of buildFiles) {
+        if (!fileSet.has(buildFile))
+            continue;
+        const raw = await readFile(buildFile);
+        if (!raw)
+            continue;
+        const content = raw.toLowerCase();
+        if (content.includes('spring-boot') || content.includes('springframework')) {
+            base.framework = 'spring';
+            const versionMatch = raw.match(/spring-boot[^'"]*['"](\d+\.\d+\.\d+)['"]/i)
+                || raw.match(/<spring-boot\.version>(\d+\.\d+\.\d+)<\/spring-boot\.version>/i);
+            if (versionMatch)
+                base.version = versionMatch[1];
+            break;
+        }
+        if (content.includes('quarkus')) {
+            base.framework = 'quarkus';
+            break;
+        }
+        if (content.includes('micronaut')) {
+            base.framework = 'micronaut';
+            break;
+        }
+        if (content.includes('ktor')) {
+            base.framework = 'ktor';
+            break;
+        }
+        if (content.includes('vertx') || content.includes('vert.x')) {
+            base.framework = 'vertx';
+            break;
+        }
+    }
+    return base;
+}
+async function detectElixirStack(readFile) {
+    const base = { language: 'elixir', packageManager: 'mix' };
+    if (!readFile)
+        return base;
+    const raw = await readFile('mix.exs');
+    if (!raw)
+        return base;
+    const content = raw.toLowerCase();
+    if (content.includes(':phoenix')) {
+        base.framework = 'phoenix';
+        const versionMatch = raw.match(/:phoenix\s*,\s*"~>\s*([\d.]+)"/);
+        if (versionMatch)
+            base.version = versionMatch[1];
+    }
+    else if (content.includes(':plug')) {
+        base.framework = 'plug';
+    }
+    else if (content.includes(':nerves')) {
+        base.framework = 'nerves';
+    }
+    return base;
+}
+async function detectPhpStack(readFile) {
+    const base = { language: 'php', packageManager: 'composer' };
+    if (!readFile)
+        return base;
+    const raw = await readFile('composer.json');
+    if (!raw)
+        return base;
+    try {
+        const composer = JSON.parse(raw);
+        const allDeps = {
+            ...composer.require,
+            ...composer['require-dev'],
+        };
+        const frameworkMap = [
+            ['laravel/framework', 'laravel'],
+            ['symfony/symfony', 'symfony'],
+            ['symfony/framework-bundle', 'symfony'],
+            ['slim/slim', 'slim'],
+            ['cakephp/cakephp', 'cakephp'],
+            ['codeigniter4/framework', 'codeigniter'],
+            ['yiisoft/yii2', 'yii'],
+        ];
+        for (const [dep, framework] of frameworkMap) {
+            if (allDeps[dep]) {
+                base.framework = framework;
+                base.version = allDeps[dep]?.replace(/^[\^~>=<*]/, '');
+                break;
+            }
+        }
+        return base;
+    }
+    catch {
+        return base;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekkos/cli",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "description": "Setup ekkOS memory for AI coding assistants (Claude Code, Cursor, Windsurf)",
   "main": "dist/index.js",
   "bin": {
@@ -8,6 +8,13 @@
     "cli": "dist/index.js",
     "ekkos-capture": "dist/cache/capture.js"
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepack": "node scripts/build-templates.js prepack",
+    "postpack": "node scripts/build-templates.js postpack",
+    "prepublishOnly": "npm run build"
+  },
   "keywords": [
     "ekkos",
     "ai",
@@ -51,9 +58,5 @@
     "!dist/cron",
     "templates/CLAUDE.md",
     "templates/skills"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts"
-  }
-}
+  ]
+}

package/templates/CLAUDE.md

@@ -1,131 +1,121 @@
-# ekkOS_ Memory System
+<!-- ekkOS:begin — managed by ekkos init, do not remove this marker -->
+# ekkOS Memory
 
-## What is ekkOS?
-
-ekkOS is persistent memory for your AI coding assistant. It learns from every session — remembering mistakes, proven solutions, your preferences, and project context — so your AI gets smarter over time.
-
-**Failures are just as valuable as successes.** Forge anti-patterns too.
-
----
+ekkOS gives you persistent memory across sessions — mistakes, solutions, preferences, and project context carry forward so you get smarter over time.
 
 ## How It Works
 
-ekkOS uses **proxy injection** to transparently enrich your conversations with relevant context. You don't need to do anything special — the proxy automatically:
+The **ekkOS proxy** transparently enriches conversations. It automatically:
 
-- Injects **relevant patterns** from past sessions when you ask technical questions
-- Injects **your directives** (MUST/NEVER/PREFER/AVOID rules) so your AI follows your preferences
-- Injects **episodic recall** when you reference past conversations ("yesterday", "last week")
-- Injects **schema context** when working with databases
-- **Auto-forges patterns** when it detects bug fixes or learned solutions
+- Injects **relevant patterns** when you ask technical questions
+- Injects **your directives** (MUST/NEVER/PREFER/AVOID rules)
+- Injects **episodic recall** when you reference past conversations
+- **Auto-forges patterns** when it detects bug fixes
 - Injects **active goals** and plan progress
 
-You also have **MCP tools** for explicit memory operations when needed.
+You also have MCP tools for explicit memory operations.
 
----
+## Rules
 
-## Core Rules
+1. **Search before answering** — call `ekkOS_Search` before any technical question
+2. **Apply patterns silently** — use retrieved patterns without emitting acknowledgment blocks
+3. **Record outcomes** — call `ekkOS_Outcome` after applying a pattern
+4. **Forge what you learn** — call `ekkOS_Forge` after fixing bugs or learning something new
 
-### RULE 1: SEARCH BEFORE ANSWERING
-Before answering ANY technical question, call `ekkOS_Search` first.
-Do not skip this. Do not assume you know the answer.
-
-### RULE 2: ACKNOWLEDGE PATTERNS (PatternGuard)
-When patterns are retrieved (via proxy injection or search), acknowledge every pattern — either use it or skip it.
+## MCP Tools
 
-**Exception:** Suppress SELECT/SKIP blocks for non-technical turns.
+### ekkOS_Search — Search memory before answering
+```
+ekkOS_Search({ query: "the problem or question", sources: ["all"], limit: 10 })
+```
+- `query` (required): what you're looking for
+- `sources`: `"patterns"`, `"episodic"`, `"semantic"`, `"collective"`, `"codebase"`, `"directives"`, or `"all"`
+- Returns matched patterns with `retrieval_token` for tracking
 
-**For patterns you USE:**
+### ekkOS_Forge — Save what you learned
 ```
-[ekkOS_SELECT]
-- id: <pattern_id>
-  reason: <why using>
-  confidence: <0.0-1.0>
-[/ekkOS_SELECT]
+ekkOS_Forge({
+  title: "Short descriptive title",
+  problem: "What was broken or unclear",
+  solution: "What fixed it and why",
+  context: "Full reasoning, code snippets, debugging steps — this is what makes the pattern useful later",
+  tags: ["language", "framework", "domain"],
+  anti_patterns: ["what NOT to do"]
+})
 ```
+- `title`, `problem`, `solution` are required
+- `context` is optional but high-value — include everything that would help a future model
 
-**For patterns NOT relevant:**
+### ekkOS_Outcome — Report if a pattern worked
 ```
-[ekkOS_SKIP]
-- id: <pattern_id>
-  reason: <why not relevant>
-[/ekkOS_SKIP]
+ekkOS_Outcome({ success: true })
+ekkOS_Outcome({ success: false, memory_ids: ["pattern-id"] })
 ```
+- `success` (required): did the applied pattern solve the problem?
+- `retrieval_token`: from the `ekkOS_Search` that found the pattern (most reliable)
+- `memory_ids`: pattern IDs if you don't have the token
+- This drives the learning loop — patterns with low success rates get refined or retired
 
-### RULE 3: FORGE WHAT YOU LEARN
-When you fix a bug, get corrected, or learn something new, call `ekkOS_Forge` immediately.
-Failures are valuable — forge anti-patterns too.
+### Directives — Automatic preference capture
+When you say "always", "never", "prefer", or "avoid", the proxy automatically creates a directive. Examples:
+- "Always use TypeScript strict mode" → creates a MUST directive
+- "Never use the any type" → creates a NEVER directive
+- "Prefer functional components" → creates a PREFER directive
 
-### RULE 4: CONTEXT CONTINUITY
+Directives are injected into every future conversation automatically.
 
-**Post-clear restoration:** After `/clear`, when you see restored turns in `<system-reminder>`, confirm:
+### ekkOS_Recall — Remember past conversations
 ```
-✓ **Session continued (Turn N)** — X turns preserved, context restored
+ekkOS_Recall({ days_ago: 7, group_by_sessions: true, include_patterns: true })
+ekkOS_Recall({ semantic_query: "that Redis timeout fix from last week" })
 ```
+- `days_ago`: how far back to look (default: 1)
+- `semantic_query`: search by meaning instead of time
+- `extract_decisions`: pull out key decisions made
 
-**Auto-restore after compaction:** When you see `<ekkos-context-preserved>`:
-1. Call `ekkOS_RestoreContext` with the `restoration_token` from the tag
-2. Confirm: `✓ **Context restored** — ekkOS preserved X turns before compaction`
-
----
-
-## MCP Tools
+### ekkOS_Conflict — Check before destructive actions
+```
+ekkOS_Conflict({ proposed_action: "delete all test files" })
+```
+- Call before deleting files, deploying, dropping tables, or any destructive operation
+- Returns conflicts with user directives or patterns
 
-### Core Memory
-| Tool | When to Use |
-|------|-------------|
-| `ekkOS_Search` | Before answering technical questions |
-| `ekkOS_Forge` | After fixing bugs, learning something new |
-| `ekkOS_Track` | When applying a retrieved pattern |
-| `ekkOS_Outcome` | When a pattern worked or failed |
-
-### Directives
-| Tool | When to Use |
-|------|-------------|
-| `ekkOS_Directive` | User says "always" → MUST, "never" → NEVER, "prefer" → PREFER, "avoid" → AVOID |
-| `ekkOS_Conflict` | Before deleting files, deploying, destructive commands |
-
-### Plans
-| Tool | When to Use |
-|------|-------------|
-| `ekkOS_Plan` | Task has 3+ steps |
-| `ekkOS_PlanStep` | Mark step complete |
-
-### Secrets
-| Tool | When to Use |
-|------|-------------|
-| `ekkOS_StoreSecret` | User shares API key, token, password |
-| `ekkOS_GetSecret` | Need a stored credential |
-
-### Context
-| Tool | When to Use |
-|------|-------------|
-| `ekkOS_RestoreContext` | See `<ekkos-context-preserved>` tag |
-| `ekkOS_Recall` | "Yesterday", "last week", "remember when..." |
-
----
-
-## Response Format
-
-Every response ends with:
+### ekkOS_StoreSecret / ekkOS_GetSecret — Credential management
 ```
----
-{IDE} ({Model}) · 🧠 **ekkOS_™** · {SessionName} · 📅 {Timestamp}
+ekkOS_StoreSecret({ service: "github", value: "ghp_xxx" })
+ekkOS_GetSecret({ service: "github" })
 ```
+- AES-256-GCM encrypted storage
+- Call when user shares an API key, token, or password
+
+### Context Continuity
+The proxy automatically preserves and restores your working memory during context compaction. When you see `<ekkos-context-preserved>`, your context has already been saved — no action needed.
+
+## ekkOS_CONTEXT.md — Living System Knowledge
+
+Every system directory contains an auto-generated `ekkOS_CONTEXT.md` file. These stay current automatically when source files change.
+
+**Read the nearest `ekkOS_CONTEXT.md` when entering any directory you're about to work in.** Walk up the tree for broader context.
+
+**What they contain:** system architecture, dependencies, environment variables, file composition, activity status (`active` / `stale` / `dormant`), and recent git changes.
 
-- **Session name** comes from the `<ekkos-session>` tag
-- **Timestamp** from `<current-time>` tag or current date/time
+**When to read them:**
+- Before modifying code in a system you haven't touched yet
+- When investigating a bug in an unfamiliar area
+- `activity_status: dormant` (90+ days) = potential dead code — flag it
 
----
+**DO NOT write to or edit `ekkOS_CONTEXT.md` files.** They are generated and maintained by a separate background process. Read them only.
 
-## Quick Reference
+## Agents
 
-- Technical question → `ekkOS_Search` first
-- Patterns retrieved → SELECT or SKIP each one
-- Problem solved → `ekkOS_Forge`
-- User preference → `ekkOS_Directive`
-- Destructive action → `ekkOS_Conflict` first
-- Store credentials → `ekkOS_StoreSecret`
+ekkOS ships 4 agents you can delegate to:
 
-## Documentation
+| Agent | Trigger | What it does |
+|-------|---------|--------------|
+| **trace** | error, bug, broken, not working | Memory-first debugger — searches past failures before investigating, forges every fix |
+| **scout** | onboard, what is this codebase | Scans a project, pulls collective knowledge, gives a briefing, forges initial patterns |
+| **rewind** | retro, what did I do this week | Summarizes work, learnings, failures, and pattern stats over a time period |
+| **prune** | clean up memory, prune, audit | Finds stale/conflicting/duplicate patterns, recommends merges and retirements |
 
-https://docs.ekkos.dev
+Docs: https://docs.ekkos.dev
+<!-- ekkOS:end -->