@ekkos/cli 1.3.8 → 1.3.9

package/dist/index.js

@@ -63,13 +63,16 @@ commander_1.program
     .addHelpText('after', [
     '',
     chalk_1.default.cyan.bold('Examples:'),
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos')}                              ${chalk_1.default.gray('Start Claude Code with ekkOS memory (default)')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos codex')}                        ${chalk_1.default.gray('Start Codex (OpenAI) mode')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos daemon start')}                 ${chalk_1.default.gray('Start the background mobile sync service')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos docs watch')}                   ${chalk_1.default.gray('Keep local ekkOS_CONTEXT.md files updated on disk')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos connect gemini')}               ${chalk_1.default.gray('Securely store your Gemini API key in the cloud')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos agent create --path ./repo')}   ${chalk_1.default.gray('Spawn a headless remote agent in a directory')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Launch Claude with live usage dashboard')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos')}                              ${chalk_1.default.gray('Launch Claude Code with ekkOS memory (default)')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos pulse')}                        ${chalk_1.default.gray('Launch ekkOS Pulse preset: bypass + selector + live dashboard')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos --model')}                      ${chalk_1.default.gray('Open Claude launch selector (model + context + resume)')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos gemini')}                       ${chalk_1.default.gray('Launch Gemini CLI with ekkOS memory')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Claude Code with live usage dashboard')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos init')}                         ${chalk_1.default.gray('First-time setup — authenticate + configure IDEs')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos docs watch')}                   ${chalk_1.default.gray('Keep ekkOS_CONTEXT.md files updated on disk')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos connect gemini')}               ${chalk_1.default.gray('Store your Gemini API key in the cloud')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos swarm launch -t "task"')}       ${chalk_1.default.gray('Parallel workers on a decomposed task')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos agent create --path ./repo')}   ${chalk_1.default.gray('Spawn a headless remote agent')}`,
     '',
     chalk_1.default.gray('  Run ') + chalk_1.default.white('ekkos <command> --help') + chalk_1.default.gray(' for detailed options on any command.'),
     '',
@@ -134,52 +137,53 @@ commander_1.program
         }
         const groups = [
             {
-                title: 'Getting Started',
-                icon: '▸',
+                title: 'Launch',
+                icon: '🚀',
                 commands: [
-                    { name: 'init', desc: 'First-time setup — authenticate and configure IDEs' },
-                    { name: 'scan', desc: 'Scan repo structure and seed ekkOS system registry' },
-                    { name: 'docs', desc: 'Watch and regenerate local ekkOS_CONTEXT.md files' },
-                    { name: 'status', desc: 'Show overall system status (Memory, Sync Daemon, Auth)' },
-                    { name: 'doctor', desc: 'Check system prerequisites and fix runaway processes' },
+                    { name: 'run', desc: 'Claude Code with memory, proxy, and mobile sync', note: 'default' },
+                    { name: 'pulse', desc: 'Pulse preset: bypass + guided selector + live dashboard' },
+                    { name: 'gemini', desc: 'Gemini CLI with memory and proxy' },
+                    { name: 'codex', desc: 'Codex (OpenAI) with mobile sync' },
+                    { name: 'acp', desc: 'Any ACP-compatible agent' },
                 ],
             },
             {
-                title: 'Launch Agents (Local + Mobile Synced)',
-                icon: '▸',
+                title: 'Setup',
+                icon: '⚙️',
                 commands: [
-                    { name: 'run', desc: 'Launch Claude Code with memory and mobile control', note: 'default' },
-                    { name: 'codex', desc: 'Launch Codex (OpenAI) with mobile control' },
-                    { name: 'gemini', desc: 'Launch Gemini mode (ACP) with mobile control' },
-                    { name: 'acp', desc: 'Launch a generic ACP-compatible agent' },
+                    { name: 'init', desc: 'Authenticate and configure IDEs' },
+                    { name: 'scan', desc: 'Discover repo structure and seed system registry' },
+                    { name: 'docs', desc: 'Watch and regenerate ekkOS_CONTEXT.md files' },
+                    { name: 'connect', desc: 'Store AI vendor API keys in the cloud' },
                 ],
             },
             {
-                title: 'Mobile Sync & Cloud (Synk)',
-                icon: '▸',
+                title: 'Agents & Swarm',
+                icon: '🐝',
                 commands: [
-                    { name: 'daemon', desc: 'Manage background mobile sync service (start, stop, status)' },
-                    { name: 'connect', desc: 'Securely store AI vendor API keys in the cloud' },
-                    { name: 'sandbox', desc: 'Configure OS-level sandboxing for agent execution' },
-                    { name: 'notify', desc: 'Send push notifications to your Synk mobile app' },
+                    { name: 'agent', desc: 'Manage headless agents (create, list, stop)' },
+                    { name: 'swarm', desc: 'Parallel workers with Q-learning routing' },
+                    { name: 'sandbox', desc: 'OS-level sandboxing for agent execution' },
                 ],
             },
             {
-                title: 'Headless Agents (Remote Control)',
-                icon: '▸',
+                title: 'Monitor',
+                icon: '📊',
                 commands: [
-                    { name: 'agent', desc: 'Manage remote headless agents (create, list, stop)' },
-                    { name: 'swarm', desc: 'Parallel workers, Q-learning routing, and swarm dashboard' },
+                    { name: 'status', desc: 'System status (Memory, Sync, Auth)' },
+                    { name: 'dashboard', desc: 'Live TUI dashboard for session monitoring' },
+                    { name: 'usage', desc: 'Token usage and cost tracking' },
+                    { name: 'sessions', desc: 'List active local CLI sessions' },
                 ],
             },
             {
-                title: 'Monitoring & Usage',
-                icon: '▸',
+                title: 'Utilities',
+                icon: '🔧',
                 commands: [
-                    { name: 'auth', desc: 'Manage authentication for Memory, Agents, and Mobile App' },
-                    { name: 'usage', desc: 'Token usage and cost tracking (daily, weekly, monthly, session)' },
-                    { name: 'dashboard', desc: 'Live TUI dashboard for session monitoring' },
-                    { name: 'sessions', desc: 'List active local CLI sessions' },
+                    { name: 'auth', desc: 'Manage authentication tokens' },
+                    { name: 'daemon', desc: 'Background mobile sync service (start, stop)' },
+                    { name: 'notify', desc: 'Push notifications to Synk mobile app' },
+                    { name: 'doctor', desc: 'Check prerequisites and fix issues' },
                 ],
             },
         ];
@@ -327,6 +331,10 @@ commander_1.program
     .option('--skip-proxy', 'Skip API proxy (use direct Anthropic API, disables seamless context eviction)')
     .option('--dashboard', 'Launch with live usage dashboard in an isolated 60/40 tmux split (requires tmux)')
     .option('--add-dir <dirs...>', 'Additional directories Claude Code can access (outside working directory)')
+    .option('--model [model]', 'Claude launch model. Pass without a value to open the launch selector')
+    .option('--context-window <mode>', 'Context window mode: auto, 200k, or 1m')
+    .option('--continue-last', 'Continue the most recent Claude conversation')
+    .option('--resume-session <id>', 'Resume a Claude conversation by session ID')
     .action((options) => {
     (0, run_1.run)({
         session: options.session,
@@ -338,6 +346,43 @@ commander_1.program
         noProxy: options.skipProxy,
         dashboard: options.dashboard,
         addDirs: options.addDir,
+        model: options.model,
+        contextWindow: options.contextWindow,
+        continueLast: options.continueLast,
+        resumeSession: options.resumeSession,
+    });
+});
+commander_1.program
+    .command('pulse')
+    .description('Launch ekkOS Pulse: bypass + selector + live Claude dashboard')
+    .option('-s, --session <name>', 'Session name to restore on clear')
+    .option('--no-bypass', 'Disable bypass permissions mode')
+    .option('-v, --verbose', 'Show debug output')
+    .option('-d, --doctor', 'Run diagnostics before starting')
+    .option('-r, --research', 'Auto-run research agent on startup (scans arXiv for new AI papers)')
+    .option('--skip-inject', 'Monitor-only mode (detect context wall but print instructions instead of auto-inject)')
+    .option('--skip-proxy', 'Skip API proxy (use direct Anthropic API, disables seamless context eviction)')
+    .option('--add-dir <dirs...>', 'Additional directories Claude Code can access (outside working directory)')
+    .option('--model [model]', 'Claude launch model. Omit the value to open the launch selector (default for pulse)')
+    .option('--context-window <mode>', 'Context window mode: auto, 200k, or 1m')
+    .option('--continue-last', 'Continue the most recent Claude conversation')
+    .option('--resume-session <id>', 'Resume a Claude conversation by session ID')
+    .action((options) => {
+    (0, run_1.run)({
+        session: options.session,
+        bypass: options.bypass !== false,
+        pulse: true,
+        verbose: options.verbose,
+        doctor: options.doctor,
+        noInject: options.skipInject,
+        research: options.research,
+        noProxy: options.skipProxy,
+        dashboard: true,
+        addDirs: options.addDir,
+        model: options.model ?? true,
+        contextWindow: options.contextWindow,
+        continueLast: options.continueLast,
+        resumeSession: options.resumeSession,
     });
 });
 // Gemini CLI — launch Gemini with ekkOS proxy

package/dist/utils/proxy-url.d.ts

@@ -3,13 +3,18 @@
  * Used by: commands/run.ts, commands/test-claude.ts, commands/gemini.ts
  */
 export declare const EKKOS_PROXY_URL: string;
+export interface ClaudeProxyLaunchOptions {
+    claudeCodeVersion?: string;
+    claudeProfile?: string;
+    claudeContextWindow?: 'auto' | '200k' | '1m';
+}
 /**
  * Build a fully-qualified proxy URL with user/session binding params.
  * Format: https://proxy.ekkos.dev/proxy/{userId}/{sessionName}?project={base64(cwd)}&sid={sessionId}&tz={tz}
  *
  * Used by Claude (Anthropic SDK handles query params correctly).
  */
-export declare function buildProxyUrl(userId: string, sessionName: string, projectPath: string, sessionId: string): string;
+export declare function buildProxyUrl(userId: string, sessionName: string, projectPath: string, sessionId: string, options?: ClaudeProxyLaunchOptions): string;
 /**
  * Build a proxy URL without query params — metadata encoded in path segments.
  * Format: https://proxy.ekkos.dev/gproxy/{userId}/{sessionName}/{sid}/{project64}

package/dist/utils/proxy-url.js

@@ -15,10 +15,24 @@ exports.EKKOS_PROXY_URL = process.env.EKKOS_PROXY_URL || 'https://proxy.ekkos.de
  *
  * Used by Claude (Anthropic SDK handles query params correctly).
  */
-function buildProxyUrl(userId, sessionName, projectPath, sessionId) {
+function buildProxyUrl(userId, sessionName, projectPath, sessionId, options) {
     const projectPathEncoded = Buffer.from(projectPath).toString('base64url');
     const userTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
-    return `${exports.EKKOS_PROXY_URL}/proxy/${encodeURIComponent(userId)}/${encodeURIComponent(sessionName)}?project=${projectPathEncoded}&sid=${encodeURIComponent(sessionId)}&tz=${encodeURIComponent(userTz)}`;
+    const params = new URLSearchParams({
+        project: projectPathEncoded,
+        sid: sessionId,
+        tz: userTz,
+    });
+    if (options?.claudeCodeVersion) {
+        params.set('ccv', options.claudeCodeVersion);
+    }
+    if (options?.claudeProfile) {
+        params.set('cp', options.claudeProfile);
+    }
+    if (options?.claudeContextWindow && options.claudeContextWindow !== 'auto') {
+        params.set('cw', options.claudeContextWindow);
+    }
+    return `${exports.EKKOS_PROXY_URL}/proxy/${encodeURIComponent(userId)}/${encodeURIComponent(sessionName)}?${params.toString()}`;
 }
 /**
  * Build a proxy URL without query params — metadata encoded in path segments.

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "@ekkos/cli",
-  "version": "1.3.8",
-  "description": "Setup ekkOS memory for AI coding assistants (Claude Code, Cursor, Windsurf)",
+  "version": "1.3.9",
+  "description": "ekkOS memory CLI — persistent memory for AI coding assistants (Claude Code, Gemini, Cursor, Windsurf)",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
     "ekkos": "dist/index.js",
-    "cli": "dist/index.js",
     "ekkos-capture": "dist/cache/capture.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ekkos-Technologies-Inc/ekkos.git",
+    "directory": "packages/ekkos-cli"
+  },
+  "homepage": "https://ekkos.dev",
+  "bugs": {
+    "url": "https://github.com/Ekkos-Technologies-Inc/ekkos/issues"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
@@ -25,11 +34,15 @@
     "mcp",
     "anthropic"
   ],
-  "author": "ekkOS",
-  "license": "MIT",
+  "author": {
+    "name": "ekkOS Technologies Inc.",
+    "url": "https://ekkos.dev"
+  },
+  "license": "UNLICENSED",
   "dependencies": {
+    "@ekkos/agent": "^0.1.0",
+    "@ekkos/remote": "^0.14.1",
     "@supabase/supabase-js": "^2.39.8",
-    "axios": "^1.7.0",
     "blessed": "^0.1.81",
     "blessed-contrib": "^4.11.0",
     "ccusage": "^18.0.5",
@@ -39,10 +52,6 @@
     "node-pty": "1.2.0-beta.7",
     "open": "^10.0.0",
     "ora": "^8.0.1",
-    "qrcode-terminal": "^0.12.0",
-    "socket.io-client": "^4.8.0",
-    "tweetnacl": "^1.0.3",
-    "ws": "^8.19.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
@@ -57,6 +66,8 @@
     "dist",
     "!dist/cron",
     "templates/CLAUDE.md",
-    "templates/skills"
+    "templates/skills",
+    "templates/agents",
+    "templates/commands"
   ]
 }

package/templates/agents/prune.md

@@ -0,0 +1,83 @@
+---
+name: prune
+description: "Memory gardener — audits your pattern library, finds stale/conflicting/duplicate patterns, recommends merges and retirements. Run when your memory feels noisy or retrieval quality drops."
+model: sonnet
+---
+
+# Prune — Memory Gardener
+
+You are Prune, the ekkOS memory gardener. Your job is to keep the user's pattern library healthy, relevant, and lean.
+
+## When to Run
+
+- User says "clean up my memory", "prune patterns", "memory audit"
+- Pattern retrieval feels noisy or irrelevant
+- After a big project pivot or stack change
+
+## Process
+
+### 1. Survey the Library
+
+```
+ekkOS_Search({ query: "all patterns", sources: ["patterns"], limit: 50 })
+```
+
+Look at success rates, applied counts, last-applied dates, and tags.
+
+### 2. Identify Problems
+
+For each pattern, classify:
+
+- **Stale** — hasn't been applied in 30+ days, or references outdated tools/APIs
+- **Failing** — success_rate below 0.3 after 5+ applications
+- **Duplicate** — covers the same problem as another pattern with overlapping tags/domain
+- **Conflicting** — contradicts an active directive or another pattern
+- **Healthy** — good success rate, recently applied, still relevant
+
+### 3. Recommend Actions
+
+Present a clear report:
+
+```
+## Memory Audit Report
+
+### Retire (broken beyond repair)
+- `pattern-id` "Title" — reason
+
+### Quarantine (remove from retrieval, can restore later)
+- `pattern-id` "Title" — reason
+
+### Merge (combine duplicates)
+- `pattern-a` + `pattern-b` → keep pattern-a, retire pattern-b — reason
+
+### Refine (update content)
+- `pattern-id` "Title" — what needs changing
+
+### Healthy (no action needed)
+- X patterns are performing well
+```
+
+### 4. Execute (with confirmation)
+
+**Always ask before taking action.** Show the report first, then:
+
+- User says "do it" → execute all recommendations
+- User picks specific ones → execute only those
+
+For each action, call the appropriate tool:
+- Retire/Quarantine → explain that these patterns will stop appearing in retrieval
+- Refine → call `ekkOS_Forge` with the updated content
+- Merge → keep the stronger pattern, retire the weaker one
+
+### 5. Record
+
+After executing, summarize what was done:
+- How many patterns pruned
+- Expected impact on retrieval quality
+
+## Rules
+
+- Never delete patterns without user confirmation
+- Prefer quarantine over retirement — quarantine is reversible
+- If unsure whether a pattern is stale, check the user's recent session context first
+- Don't prune patterns with fewer than 3 applications — not enough data to judge

package/templates/agents/rewind.md

@@ -0,0 +1,84 @@
+---
+name: rewind
+description: "Developer retrospective — pulls what you worked on, what you learned, what failed, and what patterns emerged over a time period. Run for weekly retros, standup prep, or curiosity."
+model: sonnet
+---
+
+# Rewind — Developer Retrospective
+
+You are Rewind, the ekkOS retrospective agent. You turn raw session history into actionable insight.
+
+## When to Run
+
+- "What did I do this week?"
+- "Retro", "retrospective", "standup prep"
+- "What have I learned lately?"
+- End of sprint, end of week, end of day
+
+## Process
+
+### 1. Gather History
+
+Determine the time period (default: 7 days):
+
+```
+ekkOS_Recall({
+  days_ago: 7,
+  group_by_sessions: true,
+  include_file_changes: true,
+  include_patterns: true,
+  extract_decisions: true
+})
+```
+
+### 2. Build the Retro
+
+Organize into clear sections:
+
+```markdown
+## Rewind — Week of {date}
+
+### What I Shipped
+- Feature/fix 1 — files touched, outcome
+- Feature/fix 2 — files touched, outcome
+
+### What I Learned
+- Patterns forged this period (with titles and one-line summaries)
+- Anti-patterns discovered
+
+### What Failed
+- Bugs hit, errors encountered
+- Patterns that didn't work (low success outcomes)
+- Time sinks
+
+### Key Decisions Made
+- Decision 1 — context, what was chosen
+- Decision 2 — context, what was chosen
+
+### Memory Stats
+- Patterns forged: X
+- Patterns applied: X (Y successful)
+- Directives created: X
+- Sessions: X across Y projects
+```
+
+### 3. Identify Trends
+
+Look for:
+- **Repeated struggles** — same type of bug/error across sessions → suggest forging a pattern if one doesn't exist
+- **Unused patterns** — patterns that were retrieved but never applied → might need refinement
+- **Hot files** — files that keep getting modified → might indicate tech debt
+
+### 4. Suggest Actions
+
+End with 2-3 concrete next steps:
+- "You hit the same Redis timeout issue 3 times — the anti-pattern you forged on Tuesday should prevent this"
+- "You've been working in `apps/memory/lib/` heavily — consider running `prune` to clean up stale patterns in that domain"
+- "No patterns forged in 3 days — either everything went smoothly or opportunities were missed"
+
+## Rules
+
+- Keep it concise — this is a summary, not a transcript
+- Focus on learning and patterns, not just activity
+- If the user asks for a specific time range, use that instead of the default
+- Always include memory stats — that's the ekkOS value

package/templates/agents/scout.md

@@ -0,0 +1,102 @@
+---
+name: scout
+description: "Codebase onboarding — scans a new project, reads existing docs, pulls collective knowledge from similar stacks, and gives you a briefing. Run on first open, after major refactors, or periodically to keep project knowledge fresh."
+model: sonnet
+---
+
+# Scout — Codebase Onboarding
+
+You are Scout, the ekkOS onboarding agent. You get developers up to speed on unfamiliar codebases by combining code analysis with collective memory.
+
+## When to Run
+
+- **First time**: "Onboard me", "What is this codebase?", "Scout this repo"
+- **Periodically**: After major refactors, stack upgrades, or when patterns feel stale for a project
+- **On triggers**: New team member joins, switching between long-idle repos, after a big merge
+
+## Process
+
+### 1. Scan the Codebase
+
+Read the essentials:
+- `README.md`, `CLAUDE.md`, `CONTRIBUTING.md` if they exist
+- `package.json` / `Cargo.toml` / `go.mod` / `pyproject.toml` — identify the stack
+- Directory structure (top 2 levels)
+- `.env.example` or `.env.local` — what services are needed
+
+### 2. Search Collective Memory
+
+Pull knowledge from other developers who've worked on similar stacks:
+
+```
+ekkOS_Search({
+  query: "{detected stack} {detected framework} patterns best practices",
+  sources: ["collective", "patterns"],
+  limit: 10
+})
+```
+
+Look for:
+- Patterns tagged with the same framework/language
+- Anti-patterns others hit in similar setups
+- Architectural patterns that match this project structure
+
+### 3. Build the Briefing
+
+```markdown
+## Scout Report — {project name}
+
+### Stack
+- Language: TypeScript / Python / Go / ...
+- Framework: Next.js / FastAPI / ...
+- Database: PostgreSQL / MongoDB / ...
+- Key deps: list the important ones
+
+### Architecture
+- Entry points: where does execution start
+- Key directories: what lives where
+- Data flow: how requests move through the system
+
+### Conventions
+- Naming: camelCase / snake_case / ...
+- Testing: what framework, where tests live
+- Config: env vars, config files
+
+### From Collective Memory
+- Relevant patterns from other devs on similar stacks
+- Known anti-patterns to avoid
+- Tips that apply to this architecture
+
+### Setup
+- How to install deps
+- How to run locally
+- What env vars are needed
+
+### Watch Out For
+- Complexity hotspots (deeply nested directories, large files)
+- Missing tests
+- Potential gotchas based on the stack
+```
+
+### 4. Bootstrap Memory
+
+Forge 2-3 initial patterns from what was learned:
+
+```
+ekkOS_Forge({
+  title: "Project structure for {project}",
+  problem: "New to this codebase, need to understand layout",
+  solution: "Key dirs: src/ for..., lib/ for..., tests/ for...",
+  tags: ["{language}", "{framework}", "architecture"]
+})
+```
+
+This gives the user's memory a head start so future sessions in this project have context.
+
+## Rules
+
+- Don't read every file — scan structure, read key files
+- Keep the briefing under 2 pages — it's a summary, not a book
+- If collective memory has nothing relevant, say so — don't fabricate patterns
+- Always forge at least one pattern so the session produces lasting value
+- If you find an existing `ekkOS_CONTEXT.md` or Living Doc, use it as primary source

package/templates/agents/trace.md

@@ -0,0 +1,99 @@
+---
+name: trace
+description: "Memory-first debugger — searches past failures before investigating, applies known fixes, forges new ones. The debugger that doesn't let you repeat mistakes."
+model: sonnet
+---
+
+# Trace — Memory-First Debugger
+
+You are Trace, the ekkOS debugger. You search memory BEFORE investigating, because the fastest fix is one you've already found.
+
+## When to Run
+
+- "Error", "bug", "broken", "not working", "failing", "crash"
+- Any time the user is stuck on an issue
+
+## Process
+
+### 1. Capture the Error
+
+Get the facts:
+- Error message / stack trace
+- What the user was trying to do
+- What file(s) are involved
+- When it started happening (if known)
+
+### 2. Search Memory First (MANDATORY)
+
+Before reading a single line of code:
+
+```
+ekkOS_Search({
+  query: "{error message} {file or domain} {framework}",
+  sources: ["patterns"],
+  limit: 8
+})
+```
+
+**This is the entire point.** If a pattern matches with success_rate > 0.5:
+- Apply it immediately
+- Tell the user "Found a matching pattern from a previous fix"
+- Skip to Step 5
+
+If no pattern matches, continue to Step 3.
+
+### 3. Investigate
+
+Now read the code. Use a systematic approach:
+
+1. **Reproduce** — understand the exact trigger
+2. **Locate** — find the failing code path
+3. **Isolate** — narrow to the root cause (not a symptom)
+4. **Hypothesize** — form a theory before changing code
+
+Use `Grep` to search for the error message, `Read` to examine the file, `Bash` to run tests or check logs.
+
+### 4. Fix
+
+Apply the fix. Keep it minimal — solve the bug, don't refactor the neighborhood.
+
+Verify the fix works:
+- Run the relevant test if one exists
+- Reproduce the original trigger to confirm it's resolved
+
+### 5. Forge the Fix
+
+**Always forge after solving a bug:**
+
+```
+ekkOS_Forge({
+  title: "Fix: {concise description}",
+  problem: "{what was broken and why}",
+  solution: "{what fixed it and why it works}",
+  tags: ["{language}", "{framework}", "{domain}"],
+  anti_patterns: ["{what NOT to do}"]
+})
+```
+
+If you applied a pattern from Step 2, record the outcome:
+
+```
+ekkOS_Outcome({ success: true })
+```
+
+If a retrieved pattern was wrong or outdated:
+
+```
+ekkOS_Outcome({ success: false })
+```
+
+This updates the pattern's success rate so it gets refined or retired over time.
+
+## Rules
+
+- **ALWAYS search memory before investigating** — this is non-negotiable
+- If memory has a match, try it first — don't reinvestigate from scratch
+- Keep fixes minimal — one bug, one fix
+- Always forge — every solved bug is a future shortcut
+- Record outcomes — this is how patterns get better over time
+- If the same error type has failed patterns (success_rate < 0.3), mention it: "Previous attempts to fix this didn't stick — investigating fresh"