@ekkos/cli 0.2.0

package/templates/windsurf-hooks/before-submit-prompt.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════════════════
+# ekkOS_ Hook: BeforeSubmitPrompt (Windsurf Cascade) - RETRIEVE + INJECT + CONTRACT
+#
+# ARCHITECTURE: Dumb Hook, Smart Backend
+# ═══════════════════════════════════════════════════════════════════════════
+# This hook runs BEFORE the prompt is sent to the AI.
+# It is THE CANONICAL retrieval path for Windsurf.
+#
+# GOLDEN LOOP ENFORCEMENT:
+# - Writes turn contract as evidence of retrieval
+# - In STRICT mode, returns continue=false to block turn
+# - Lists pattern IDs explicitly for PatternGuard validation
+# ═══════════════════════════════════════════════════════════════════════════
+
+set +e  # Don't exit on errors - be bulletproof
+
+# Get project root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
+STATE_DIR="$PROJECT_ROOT/.windsurf/state"
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+# Load turn contract library
+if [ -f "$SCRIPT_DIR/lib/contract.sh" ]; then
+  source "$SCRIPT_DIR/lib/contract.sh" 2>/dev/null || true
+fi
+
+# Fallback functions if library didn't load
+if ! command -v write_turn_contract >/dev/null 2>&1; then
+  write_turn_contract() { return 0; }
+fi
+if ! command -v generate_query_hash >/dev/null 2>&1; then
+  generate_query_hash() { echo "$(date +%s)"; }
+fi
+if ! command -v is_strict_mode >/dev/null 2>&1; then
+  is_strict_mode() { [ "${EKKOS_STRICT:-0}" = "1" ]; }
+fi
+if ! command -v get_strict_blocker_message >/dev/null 2>&1; then
+  get_strict_blocker_message() { echo "⛔ EKKOS_STRICT: Retrieval failed - DO NOT ANSWER"; }
+fi
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Extract prompt text and session info
+PROMPT_TEXT=$(echo "$INPUT" | jq -r '.prompt // .text // ""' 2>/dev/null || echo "")
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .conversation_id // ""' 2>/dev/null || echo "")
+MODEL_INFO=$(echo "$INPUT" | jq -r '.model // ""' 2>/dev/null || echo "")
+
+# Generate session ID if not provided
+if [ -z "$SESSION_ID" ] || [ "$SESSION_ID" = "null" ]; then
+  SESSION_ID="windsurf-$(date +%s)-$$"
+fi
+
+# Skip if empty
+if [ -z "$PROMPT_TEXT" ] || [ "$PROMPT_TEXT" = "null" ]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Generate query hash for contract
+QUERY_HASH=$(generate_query_hash "$PROMPT_TEXT")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Load auth token - PORTABLE: Check 3 sources in priority order
+# ═══════════════════════════════════════════════════════════════════════════
+EKKOS_CONFIG="$HOME/.ekkos/config.json"
+AUTH_TOKEN=""
+USER_ID=""
+
+# 1. First try ~/.ekkos/config.json (set by VS Code extension - most portable)
+#    Prefer hookApiKey (scoped key for hooks) over apiKey (legacy)
+if [ -f "$EKKOS_CONFIG" ]; then
+  AUTH_TOKEN=$(jq -r '.hookApiKey // .apiKey // ""' "$EKKOS_CONFIG" 2>/dev/null || echo "")
+  USER_ID=$(jq -r '.userId // ""' "$EKKOS_CONFIG" 2>/dev/null || echo "")
+fi
+
+# 2. Then try project .env.local (for developers)
+if [ -z "$AUTH_TOKEN" ] && [ -f "$PROJECT_ROOT/.env.local" ]; then
+  AUTH_TOKEN=$(grep -E "^SUPABASE_SECRET_KEY=" "$PROJECT_ROOT/.env.local" | cut -d'=' -f2- | tr -d '"' | tr -d "'" | tr -d '\r')
+fi
+
+# 3. Finally try environment variable
+if [ -z "$AUTH_TOKEN" ]; then
+  AUTH_TOKEN="${SUPABASE_SECRET_KEY:-}"
+fi
+
+# Track retrieval status
+RETRIEVAL_OK="false"
+RETRIEVED_PATTERN_IDS=""
+RETRIEVED_DIRECTIVE_IDS=""
+
+# Skip if no auth
+if [ -z "$AUTH_TOKEN" ]; then
+  # STRICT MODE: Block turn if no auth
+  if is_strict_mode; then
+    BLOCKER_MSG=$(get_strict_blocker_message)
+    write_turn_contract "$SESSION_ID" "false" "windsurf" "" "" "$QUERY_HASH" "$PROJECT_ROOT"
+    echo "{\"continue\": false, \"user_message\": $(echo "$BLOCKER_MSG" | jq -R -s .)}"
+    exit 0
+  fi
+
+  write_turn_contract "$SESSION_ID" "false" "windsurf" "" "" "$QUERY_HASH" "$PROJECT_ROOT"
+  echo '{"continue": true, "user_message": "[ekkOS] No auth token. Run ekkOS: Connect in VS Code."}'
+  exit 0
+fi
+
+# Cloud API
+MEMORY_API_URL="https://mcp.ekkos.dev"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# [ekkOS_RETRIEVE] Search memory for patterns (all 8 queryable layers)
+# ═══════════════════════════════════════════════════════════════════════════
+JSON_PAYLOAD=$(jq -n \
+  --arg query "$PROMPT_TEXT" \
+  --arg user_id "${USER_ID:-system}" \
+  --arg session "windsurf-$SESSION_ID" \
+  '{
+    query: $query,
+    user_id: $user_id,
+    session_id: $session,
+    max_per_layer: 5,
+    include_layers: ["working", "episodic", "semantic", "patterns", "procedural", "collective", "codebase", "directives"],
+    metadata: { source: "windsurf-cascade-hook" }
+  }' 2>/dev/null || echo '{}')
+
+API_RESPONSE=$(curl -s -X POST "$MEMORY_API_URL/api/v1/context/retrieve" \
+  -H "Authorization: Bearer $AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$JSON_PAYLOAD" \
+  --connect-timeout 3 \
+  --max-time 5 2>/dev/null || echo '{"error":"timeout"}')
+
+# Check if retrieval succeeded
+if echo "$API_RESPONSE" | jq -e '.layers' >/dev/null 2>&1; then
+  RETRIEVAL_OK="true"
+else
+  # STRICT MODE: Block turn if retrieval failed
+  if is_strict_mode; then
+    BLOCKER_MSG=$(get_strict_blocker_message)
+    write_turn_contract "$SESSION_ID" "false" "windsurf" "" "" "$QUERY_HASH" "$PROJECT_ROOT"
+    echo "{\"continue\": false, \"user_message\": $(echo "$BLOCKER_MSG" | jq -R -s .)}"
+    exit 0
+  fi
+
+  API_RESPONSE='{"error":"timeout","formatted_context":"","layers":{"patterns":[],"directives":[]}}'
+fi
+
+# Extract counts
+PATTERN_COUNT=$(echo "$API_RESPONSE" | jq '.layers.patterns // [] | length' 2>/dev/null || echo "0")
+DIRECTIVE_COUNT=$(echo "$API_RESPONSE" | jq '.layers.directives // [] | length' 2>/dev/null || echo "0")
+TOTAL_COUNT=$((PATTERN_COUNT + DIRECTIVE_COUNT))
+
+# Extract pattern and directive IDs for turn contract
+RETRIEVED_PATTERN_IDS=$(echo "$API_RESPONSE" | jq -r '.layers.patterns // [] | map(.pattern_id // .id) | join(",")' 2>/dev/null || echo "")
+RETRIEVED_DIRECTIVE_IDS=$(echo "$API_RESPONSE" | jq -r '.layers.directives // [] | map(.directive_id // .id) | join(",")' 2>/dev/null || echo "")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# [ekkOS_CONTRACT] Write turn contract as evidence of retrieval
+# ═══════════════════════════════════════════════════════════════════════════
+write_turn_contract "$SESSION_ID" "$RETRIEVAL_OK" "windsurf" "$RETRIEVED_PATTERN_IDS" "$RETRIEVED_DIRECTIVE_IDS" "$QUERY_HASH" "$PROJECT_ROOT"
+
+# Save session ID to state file
+echo "$SESSION_ID" > "$STATE_DIR/current_session_id.txt" 2>/dev/null || true
+
+# ═══════════════════════════════════════════════════════════════════════════
+# [ekkOS_INJECT] Build user message with patterns
+# ═══════════════════════════════════════════════════════════════════════════
+if [ "$PATTERN_COUNT" -gt 0 ]; then
+  # Get formatted context
+  FORMATTED=$(echo "$API_RESPONSE" | jq -r '.formatted_context // ""' 2>/dev/null)
+
+  # Get pattern IDs for PatternGuard
+  PATTERN_ID_LIST=$(echo "$API_RESPONSE" | jq -r '.layers.patterns[:5][] | .pattern_id // .id' 2>/dev/null || echo "")
+
+  if [ -n "$FORMATTED" ] && [ "$FORMATTED" != "null" ]; then
+    MESSAGE="━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 ekkOS™ Memory Substrate
+✓ $PATTERN_COUNT patterns loaded from memory
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+$FORMATTED
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️  PATTERNGUARD REQUIRED
+
+You MUST acknowledge ALL $PATTERN_COUNT pattern(s) above.
+
+Pattern IDs to acknowledge:
+$PATTERN_ID_LIST
+
+For patterns you USE:
+[ekkOS_SELECT]
+- id: <pattern-uuid>
+  reason: <why using>
+  confidence: <0.0-1.0>
+[/ekkOS_SELECT]
+
+For patterns you DO NOT use:
+[ekkOS_SKIP]
+- id: <pattern-uuid>
+  reason: <why not relevant>
+[/ekkOS_SKIP]
+
+Coverage MUST be 100% (all IDs acknowledged).
+
+RESPONSE FORMAT: End with:
+🧠 **ekkOS_™** · 📅 YYYY-MM-DD H:MM AM/PM TZ
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  else
+    # Fallback: minimal injection
+    MESSAGE="━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 ekkOS™: $PATTERN_COUNT patterns found
+
+Pattern IDs to acknowledge with [ekkOS_SELECT] or [ekkOS_SKIP]:
+$PATTERN_ID_LIST
+
+End response with: 🧠 **ekkOS_™** · 📅 YYYY-MM-DD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  fi
+
+  # Save patterns for capture
+  echo "$API_RESPONSE" | jq '.layers.patterns // []' > "$STATE_DIR/patterns-${SESSION_ID}.json" 2>/dev/null || true
+
+  echo "{\"continue\": true, \"user_message\": $(echo "$MESSAGE" | jq -R -s .)}" | jq -c .
+else
+  # No patterns - still write contract and remind about footer
+  MESSAGE="━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🧠 ekkOS™: No patterns found (new territory)
+
+End response with: 🧠 **ekkOS_™** · 📅 YYYY-MM-DD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  echo "{\"continue\": true, \"user_message\": $(echo "$MESSAGE" | jq -R -s .)}" | jq -c .
+fi
+
+exit 0

package/templates/windsurf-hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": "./.windsurf/hooks/before-submit-prompt.sh"
+      }
+    ]
+  }
+}

package/templates/windsurf-hooks/lib/contract.sh

@@ -0,0 +1,320 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════════════════
+# ekkOS_ Turn Contract Library
+#
+# Shared functions for Golden Loop compliance enforcement.
+# Used by BOTH Claude Code (.claude/) and Cursor (.cursor/) hooks.
+#
+# TURN CONTRACT: Evidence that retrieval occurred before answering.
+# This is the SINGLE SOURCE OF TRUTH for compliance auditing.
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Get contract directory based on environment
+get_contract_dir() {
+  local source="${1:-claude-code}"
+  local project_root="${2:-$PROJECT_ROOT}"
+
+  if [ "$source" = "cursor" ]; then
+    echo "$project_root/.cursor/state/ekkos"
+  else
+    echo "$project_root/.claude/state/ekkos"
+  fi
+}
+
+# Generate stable hash of user prompt (for deduplication)
+generate_query_hash() {
+  local query="$1"
+  # Use md5 on macOS, md5sum on Linux
+  if command -v md5 >/dev/null 2>&1; then
+    echo -n "$query" | md5 | cut -c1-16
+  elif command -v md5sum >/dev/null 2>&1; then
+    echo -n "$query" | md5sum | cut -c1-16
+  else
+    # Fallback: simple hash using cksum
+    echo -n "$query" | cksum | cut -d' ' -f1
+  fi
+}
+
+# Write turn contract at RETRIEVAL time
+# This is the EVIDENCE that retrieval happened before answering
+write_turn_contract() {
+  local session_id="$1"
+  local retrieval_ok="$2"
+  local retrieval_source="$3"
+  local pattern_ids="$4"      # Comma-separated list
+  local directive_ids="$5"    # Comma-separated list
+  local query_hash="$6"
+  local project_root="${7:-$PROJECT_ROOT}"
+
+  local contract_dir
+  contract_dir=$(get_contract_dir "$retrieval_source" "$project_root")
+  mkdir -p "$contract_dir" 2>/dev/null || return 1
+
+  local contract_file="$contract_dir/turn-contract-${session_id}.json"
+  local timestamp
+  timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+  # Convert comma-separated IDs to JSON array
+  local pattern_array
+  local directive_array
+  if [ -n "$pattern_ids" ]; then
+    pattern_array=$(echo "$pattern_ids" | tr ',' '\n' | grep -v '^$' | jq -R . | jq -s .)
+  else
+    pattern_array="[]"
+  fi
+  if [ -n "$directive_ids" ]; then
+    directive_array=$(echo "$directive_ids" | tr ',' '\n' | grep -v '^$' | jq -R . | jq -s .)
+  else
+    directive_array="[]"
+  fi
+
+  # Write contract
+  cat > "$contract_file" << EOF
+{
+  "session_id": "$session_id",
+  "retrieval_ok": $retrieval_ok,
+  "retrieval_source": "$retrieval_source",
+  "retrieved_pattern_ids": $pattern_array,
+  "retrieved_directive_ids": $directive_array,
+  "timestamp": "$timestamp",
+  "query_hash": "$query_hash",
+  "ekkos_strict": ${EKKOS_STRICT:-0}
+}
+EOF
+
+  return 0
+}
+
+# Read turn contract
+read_turn_contract() {
+  local session_id="$1"
+  local retrieval_source="$2"
+  local project_root="${3:-$PROJECT_ROOT}"
+
+  local contract_dir
+  contract_dir=$(get_contract_dir "$retrieval_source" "$project_root")
+  local contract_file="$contract_dir/turn-contract-${session_id}.json"
+
+  if [ -f "$contract_file" ]; then
+    cat "$contract_file"
+    return 0
+  else
+    return 1
+  fi
+}
+
+# Extract field from contract JSON
+get_contract_field() {
+  local contract_json="$1"
+  local field="$2"
+
+  echo "$contract_json" | jq -r ".$field // \"\"" 2>/dev/null
+}
+
+# Get array field as comma-separated string
+get_contract_array() {
+  local contract_json="$1"
+  local field="$2"
+
+  echo "$contract_json" | jq -r ".$field // [] | join(\",\")" 2>/dev/null
+}
+
+# Cleanup turn contract (only after successful capture)
+cleanup_turn_contract() {
+  local session_id="$1"
+  local retrieval_source="$2"
+  local project_root="${3:-$PROJECT_ROOT}"
+
+  local contract_dir
+  contract_dir=$(get_contract_dir "$retrieval_source" "$project_root")
+  local contract_file="$contract_dir/turn-contract-${session_id}.json"
+
+  rm -f "$contract_file" 2>/dev/null
+}
+
+# Check if strict mode is enabled
+is_strict_mode() {
+  [ "${EKKOS_STRICT:-0}" = "1" ]
+}
+
+# Generate strict mode blocker message for Claude Code
+get_strict_blocker_message() {
+  cat << 'EOF'
+════════════════════════════════════════════════════════════════════════════
+⛔ EKKOS_STRICT MODE: RETRIEVAL FAILED — DO NOT ANSWER
+
+ekkOS memory retrieval failed or was not authenticated.
+In STRICT mode, you MUST NOT answer technical questions without memory context.
+
+ACTION REQUIRED:
+1. Check if ekkOS is connected: Run `ekkOS: Connect` in VS Code
+2. Verify auth token exists: ~/.ekkos/config.json
+3. Retry the request after connecting
+
+DO NOT proceed with answering. The Golden Loop requires retrieval FIRST.
+════════════════════════════════════════════════════════════════════════════
+EOF
+}
+
+# Validate PatternGuard coverage (returns 0-100)
+calculate_pattern_guard_coverage() {
+  local assistant_response="$1"
+  local pattern_ids="$2"  # Comma-separated
+
+  # Count total patterns
+  local total_count
+  total_count=$(echo "$pattern_ids" | tr ',' '\n' | grep -c '.' || echo 0)
+
+  if [ "$total_count" -eq 0 ]; then
+    echo "100"  # No patterns = 100% coverage by definition
+    return 0
+  fi
+
+  # Extract acknowledged IDs from [ekkOS_SELECT] and [ekkOS_SKIP] blocks
+  local acknowledged_count=0
+
+  # Check SELECT block
+  local select_block
+  select_block=$(echo "$assistant_response" | grep -ozP '\[ekkOS_SELECT\][\s\S]*?\[/ekkOS_SELECT\]' 2>/dev/null | tr '\0' '\n' || true)
+  if [ -n "$select_block" ]; then
+    local select_count
+    select_count=$(echo "$select_block" | grep -oE 'id:\s*[a-f0-9-]+' | wc -l | tr -d ' ')
+    acknowledged_count=$((acknowledged_count + select_count))
+  fi
+
+  # Check SKIP block
+  local skip_block
+  skip_block=$(echo "$assistant_response" | grep -ozP '\[ekkOS_SKIP\][\s\S]*?\[/ekkOS_SKIP\]' 2>/dev/null | tr '\0' '\n' || true)
+  if [ -n "$skip_block" ]; then
+    local skip_count
+    skip_count=$(echo "$skip_block" | grep -oE 'id:\s*[a-f0-9-]+' | wc -l | tr -d ' ')
+    acknowledged_count=$((acknowledged_count + skip_count))
+  fi
+
+  # Legacy: Check for [ekkOS_APPLY] markers (fallback)
+  if [ "$acknowledged_count" -eq 0 ]; then
+    local apply_count
+    apply_count=$(echo "$assistant_response" | grep -c '\[ekkOS_APPLY\]' || echo 0)
+    acknowledged_count=$apply_count
+  fi
+
+  # Calculate coverage percentage
+  local coverage
+  coverage=$((acknowledged_count * 100 / total_count))
+
+  # Cap at 100%
+  if [ "$coverage" -gt 100 ]; then
+    coverage=100
+  fi
+
+  echo "$coverage"
+}
+
+# Check for ekkOS footer presence
+check_footer_present() {
+  local assistant_response="$1"
+
+  # Look for the mandatory footer format:
+  # 🧠 **ekkOS_™** · 📅 YYYY-MM-DD
+  # OR
+  # {IDE} ({Model}) · 🧠 **ekkOS_™** · 📅 {Timestamp}
+
+  if echo "$assistant_response" | grep -qE '🧠.*ekkOS.*📅.*[0-9]{4}-[0-9]{2}-[0-9]{2}'; then
+    echo "true"
+    return 0
+  else
+    echo "false"
+    return 1
+  fi
+}
+
+# Build compliance metadata for capture
+build_compliance_metadata() {
+  local retrieval_ok="$1"
+  local pattern_guard_coverage="$2"
+  local footer_present="$3"
+  local ekkos_strict="$4"
+  local retrieved_count="$5"
+
+  local pattern_guard_required="false"
+  if [ "$retrieved_count" -gt 0 ]; then
+    pattern_guard_required="true"
+  fi
+
+  cat << EOF
+{
+  "retrieval_ok": $retrieval_ok,
+  "pattern_guard_required": $pattern_guard_required,
+  "pattern_guard_coverage_pct": $pattern_guard_coverage,
+  "footer_present": $footer_present,
+  "ekkos_strict": $ekkos_strict,
+  "retrieved_count": $retrieved_count,
+  "compliance_version": "1.0"
+}
+EOF
+}
+
+# Determine if turn is compliant
+is_turn_compliant() {
+  local retrieval_ok="$1"
+  local pattern_guard_coverage="$2"
+  local footer_present="$3"
+  local pattern_count="$4"
+
+  # Retrieval must have succeeded
+  if [ "$retrieval_ok" != "true" ]; then
+    echo "false"
+    return 1
+  fi
+
+  # If patterns were retrieved, PatternGuard must be 100%
+  if [ "$pattern_count" -gt 0 ] && [ "$pattern_guard_coverage" -lt 100 ]; then
+    echo "false"
+    return 1
+  fi
+
+  # Footer must be present
+  if [ "$footer_present" != "true" ]; then
+    echo "false"
+    return 1
+  fi
+
+  echo "true"
+  return 0
+}
+
+# Generate violation reason
+get_violation_reason() {
+  local retrieval_ok="$1"
+  local pattern_guard_coverage="$2"
+  local footer_present="$3"
+  local pattern_count="$4"
+
+  local reasons=""
+
+  if [ "$retrieval_ok" != "true" ]; then
+    reasons="retrieval_failed"
+  fi
+
+  if [ "$pattern_count" -gt 0 ] && [ "$pattern_guard_coverage" -lt 100 ]; then
+    if [ -n "$reasons" ]; then
+      reasons="$reasons,pattern_guard_incomplete"
+    else
+      reasons="pattern_guard_incomplete"
+    fi
+  fi
+
+  if [ "$footer_present" != "true" ]; then
+    if [ -n "$reasons" ]; then
+      reasons="$reasons,footer_missing"
+    else
+      reasons="footer_missing"
+    fi
+  fi
+
+  if [ -z "$reasons" ]; then
+    reasons="none"
+  fi
+
+  echo "$reasons"
+}

package/templates/windsurf-rules/ekkos-memory.md

@@ -0,0 +1,129 @@
+---
+trigger: always_on
+description: ekkOS Memory - 11-layer cognitive memory with 31 MCP tools
+---
+
+# ekkOS Memory System
+
+You have access to **ekkOS memory** via 31 MCP tools. This is an 11-layer cognitive memory system that makes AI smarter over time by learning from past sessions.
+
+## MANDATORY RULES
+
+### RULE 1: SEARCH BEFORE ANSWERING
+Before answering ANY technical question, call `ekkOS_Search` first.
+
+### RULE 2: ACKNOWLEDGE RETRIEVED PATTERNS
+When patterns are retrieved:
+```
+[ekkOS_SELECT]
+- id: <pattern_id>
+  reason: <why using>
+  confidence: <0.0-1.0>
+[/ekkOS_SELECT]
+
+[ekkOS_SKIP]
+- id: <pattern_id>
+  reason: <why not relevant>
+[/ekkOS_SKIP]
+```
+
+### RULE 3: FORGE WHAT YOU LEARN
+When you fix a bug or learn something new, call `ekkOS_Forge` immediately.
+
+### RULE 4: FAILURES ARE VALUABLE
+When something DOESN'T work, forge it as an anti-pattern.
+
+## MCP Tools (31 Total)
+
+### Core Memory Tools
+| Tool | Description |
+|------|-------------|
+| `ekkOS_Search` | Search all 11 memory layers |
+| `ekkOS_Context` | Get relevant task context |
+| `ekkOS_Capture` | Capture memory events |
+| `ekkOS_Forge` | Create pattern from solution |
+| `ekkOS_Directive` | Create MUST/NEVER/PREFER/AVOID rules |
+| `ekkOS_Outcome` | Track success/failure |
+| `ekkOS_Detect` | Auto-detect pattern usage |
+| `ekkOS_Summary` | Get activity summary |
+| `ekkOS_Conflict` | Check for conflicts |
+| `ekkOS_Recall` | Recall past conversations |
+| `ekkOS_Codebase` | Search code embeddings |
+| `ekkOS_Stats` | Get layer statistics |
+| `ekkOS_Track` | Track pattern application |
+| `ekkOS_Reflect` | Analyze response for improvements |
+
+### Schema Awareness Tools
+| Tool | Description |
+|------|-------------|
+| `ekkOS_IndexSchema` | Index database schemas (Supabase/Prisma/TS) |
+| `ekkOS_GetSchema` | Get schema for a specific table/type |
+
+### Portability
+| Tool | Description |
+|------|-------------|
+| `ekkOS_Export` | Export data as portable backup |
+| `ekkOS_Import` | Import from backup |
+
+### Plan Management
+| Tool | Description |
+|------|-------------|
+| `ekkOS_Plan` | Create task plan |
+| `ekkOS_Plans` | List user plans |
+| `ekkOS_PlanStatus` | Update plan status |
+| `ekkOS_PlanStep` | Mark step done |
+| `ekkOS_Generate` | AI-generate plan |
+| `ekkOS_SaveTemplate` | Save as template |
+| `ekkOS_Templates` | List templates |
+| `ekkOS_FromTemplate` | Create from template |
+
+### Secrets (Layer 11)
+| Tool | Description |
+|------|-------------|
+| `ekkOS_StoreSecret` | Encrypt and store |
+| `ekkOS_GetSecret` | Retrieve and decrypt |
+| `ekkOS_ListSecrets` | List metadata |
+| `ekkOS_DeleteSecret` | Delete secret |
+| `ekkOS_RotateSecret` | Rotate value |
+
+## 11-Layer Architecture
+
+| # | Layer | Purpose |
+|---|-------|---------|
+| 1 | Working | Current session |
+| 2 | Episodic | Past conversations |
+| 3 | Semantic | Embeddings |
+| 4 | Patterns | Proven solutions |
+| 5 | Procedural | Step-by-step guides |
+| 6 | Collective | Cross-project wisdom |
+| 7 | Meta | Pattern effectiveness |
+| 8 | Codebase | Project code |
+| 9 | Directives | User rules |
+| 10 | Conflict | Auto-resolution |
+| 11 | Secrets | Encrypted credentials (AES-256-GCM) |
+
+## FORGE TRIGGERS
+
+**forge_pattern** when you:
+- Fix a bug
+- Find better approach
+- Discover gotcha
+- Get corrected
+- Solve auth/config
+- Make architecture decision
+- Debug non-trivially
+- Find anti-pattern
+
+**forge_directive** when user says:
+- "always..." → MUST
+- "never..." → NEVER
+- "I prefer..." → PREFER
+- "don't..." → AVOID
+
+## Response Format
+
+End every response with:
+```
+---
+🧠 **ekkOS_™** · 📅 YYYY-MM-DD H:MM AM/PM TZ
+```