@compr/opscontext-mcp 2.0.0

package/dist/audit.d.ts

@@ -0,0 +1,23 @@
+export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass";
+export interface AuditRecord {
+    ts: string;
+    event: AuditEvent;
+    actor: string;
+    payload: Record<string, unknown>;
+    prev_hash: string;
+    hash: string;
+}
+export declare function appendAudit(event: AuditEvent, payload: Record<string, unknown>, actor?: string): AuditRecord;
+export declare function readAuditLog(): AuditRecord[];
+export interface IntegrityReport {
+    ok: boolean;
+    total: number;
+    breakAtIndex: number | null;
+    breakReason: string | null;
+}
+export declare function verifyChain(): IntegrityReport;
+export declare function filterByRange(records: AuditRecord[], since?: string, until?: string): AuditRecord[];
+export declare function toCsv(records: AuditRecord[]): string;
+export declare function resetCacheForTest(): void;
+export declare function safeAppend(event: AuditEvent, payload: Record<string, unknown>, actor?: string): void;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.js

@@ -0,0 +1,163 @@
+// 🔒 LOCKED [AUDIT-CHAIN] — 2026-06-10
+// ⛔ NEVER change the canonical serialization in computeHash() — key order,
+//    field names, JSON.stringify behavior, or genesis hash value. Any change
+//    breaks verification of every audit log written by an older client.
+// ⛔ NEVER swap SHA-256 for a different hash without a migration path.
+// ⛔ NEVER catch errors inside appendAudit() — silent failures defeat the
+//    entire compliance story. Use safeAppend() at call sites if you need
+//    failure isolation; appendAudit() must surface problems loudly.
+// WHY: This is the SOC2 CC7.2 / ISO 27001 A.12.4.1 compliance bedrock. The
+//    audit log is the foundation that licence-signature verification,
+//    compliance reporting, and enforcement telemetry all build on. Any
+//    silent break here destroys evidence value across years of records.
+// FIX: If you need to evolve the record format, version the chain
+//    (add a "v":2 field) and keep verifyChain() backward-compatible by
+//    dispatching on the v field. Don't mutate the v=1 contract.
+//
+// Tamper-evident audit log — hash-chained JSONL at ~/.contextengine/audit.log.
+//
+// Compliance basis: SOC2 CC7.2 (audit logging), ISO 27001 A.12.4.1 (event logs).
+//
+// Records every state-changing operation. Each line carries the SHA-256 hash
+// of the previous line's canonical content, so mutation of any historical
+// record breaks chain verification at that index.
+import { existsSync, mkdirSync, readFileSync, appendFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+const GENESIS_HASH = "0".repeat(64);
+function auditDir() {
+    // CONTEXTENGINE_HOME lets tests run against a temp dir without touching ~/.contextengine
+    return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
+}
+function auditPath() {
+    return join(auditDir(), "audit.log");
+}
+function ensureDir() {
+    const dir = auditDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function readLastHash() {
+    const path = auditPath();
+    if (!existsSync(path))
+        return GENESIS_HASH;
+    const data = readFileSync(path, "utf-8");
+    const lines = data.split("\n").filter(Boolean);
+    if (lines.length === 0)
+        return GENESIS_HASH;
+    try {
+        const last = JSON.parse(lines[lines.length - 1]);
+        return last.hash;
+    }
+    catch {
+        return GENESIS_HASH;
+    }
+}
+function computeHash(prevHash, ts, event, actor, payload) {
+    // Canonical serialization — keys in fixed order so independent verifiers get
+    // the same bytes regardless of how the record object was originally built.
+    const canonical = JSON.stringify({ prev_hash: prevHash, ts, event, actor, payload });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+let cachedLastHash = null;
+export function appendAudit(event, payload, actor = "system") {
+    ensureDir();
+    if (cachedLastHash === null)
+        cachedLastHash = readLastHash();
+    const ts = new Date().toISOString();
+    const hash = computeHash(cachedLastHash, ts, event, actor, payload);
+    const record = { ts, event, actor, payload, prev_hash: cachedLastHash, hash };
+    appendFileSync(auditPath(), JSON.stringify(record) + "\n");
+    cachedLastHash = hash;
+    return record;
+}
+export function readAuditLog() {
+    const path = auditPath();
+    if (!existsSync(path))
+        return [];
+    const data = readFileSync(path, "utf-8");
+    return data
+        .split("\n")
+        .filter(Boolean)
+        .map((line, i) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            throw new Error(`Corrupt audit line ${i + 1}: not valid JSON`);
+        }
+    });
+}
+export function verifyChain() {
+    let records;
+    try {
+        records = readAuditLog();
+    }
+    catch (e) {
+        return {
+            ok: false,
+            total: 0,
+            breakAtIndex: null,
+            breakReason: e instanceof Error ? e.message : String(e),
+        };
+    }
+    let prev = GENESIS_HASH;
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        if (r.prev_hash !== prev) {
+            return {
+                ok: false,
+                total: records.length,
+                breakAtIndex: i,
+                breakReason: `prev_hash mismatch at index ${i}`,
+            };
+        }
+        const expected = computeHash(prev, r.ts, r.event, r.actor, r.payload);
+        if (r.hash !== expected) {
+            return {
+                ok: false,
+                total: records.length,
+                breakAtIndex: i,
+                breakReason: `hash mismatch at index ${i} (record tampered)`,
+            };
+        }
+        prev = r.hash;
+    }
+    return { ok: true, total: records.length, breakAtIndex: null, breakReason: null };
+}
+export function filterByRange(records, since, until) {
+    return records.filter((r) => {
+        if (since && r.ts < since)
+            return false;
+        if (until && r.ts > until)
+            return false;
+        return true;
+    });
+}
+export function toCsv(records) {
+    const header = "ts,event,actor,payload,prev_hash,hash";
+    const rows = records.map((r) => {
+        const payload = JSON.stringify(r.payload).replace(/"/g, '""');
+        return `${r.ts},${r.event},${r.actor},"${payload}",${r.prev_hash},${r.hash}`;
+    });
+    return [header, ...rows].join("\n");
+}
+// Test-only — flush in-memory chain cache so a fresh path is re-read.
+export function resetCacheForTest() {
+    cachedLastHash = null;
+}
+// Safe wrapper that never throws into hot paths. Use this from production
+// call sites so a failed audit append cannot break a learning save or
+// session write.
+export function safeAppend(event, payload, actor = "system") {
+    try {
+        appendAudit(event, payload, actor);
+    }
+    catch (e) {
+        // Last-resort surface — stderr only, never throw upward.
+        process.stderr.write(`[ContextEngine] audit append failed: ${e instanceof Error ? e.message : String(e)}\n`);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/cache.d.ts

@@ -0,0 +1,15 @@
+import type { Chunk } from "./ingest.js";
+import type { EmbeddedChunk } from "./embeddings.js";
+/**
+ * Try to load cached embeddings. Returns null if cache is stale or missing.
+ */
+export declare function loadCache(chunks: Chunk[]): EmbeddedChunk[] | null;
+/**
+ * Save embeddings to disk cache.
+ */
+export declare function saveCache(chunks: Chunk[], embedded: EmbeddedChunk[]): void;
+/**
+ * Clear the embedding cache.
+ */
+export declare function clearCache(): boolean;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync } from "fs";
+import { resolve, join } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+/**
+ * Embedding cache — persists vectors to disk so restart is instant.
+ *
+ * Cache key: SHA-256 hash of all chunk contents (sorted).
+ * If chunks haven't changed, we skip the entire embedding step.
+ *
+ * File: ~/.contextengine/embedding-cache.json
+ * Format: { hash, vectors: [[...float32 values]], chunks: [{source,section,lineStart,lineEnd}] }
+ *
+ * On a typical 555-chunk dataset:
+ * - First run: ~15s (model load + embed)
+ * - Cached restart: ~200ms (read JSON + reconstruct Float32Arrays)
+ */
+const CACHE_DIR = resolve(homedir(), ".contextengine");
+const CACHE_FILE = join(CACHE_DIR, "embedding-cache.json");
+const CACHE_VERSION = 2;
+/**
+ * Compute a hash of all chunk contents to detect changes.
+ * Uses source+section+content concatenated.
+ */
+function computeChunkHash(chunks) {
+    const hasher = createHash("sha256");
+    for (const c of chunks) {
+        hasher.update(`${c.source}\0${c.section}\0${c.content}\0`);
+    }
+    return hasher.digest("hex");
+}
+/**
+ * Try to load cached embeddings. Returns null if cache is stale or missing.
+ */
+export function loadCache(chunks) {
+    if (!existsSync(CACHE_FILE))
+        return null;
+    try {
+        const raw = readFileSync(CACHE_FILE, "utf-8");
+        const cache = JSON.parse(raw);
+        // Version check
+        if (cache.version !== CACHE_VERSION) {
+            console.error("[ContextEngine] 💾 Cache version mismatch — will re-embed");
+            return null;
+        }
+        // Hash check — have chunks changed?
+        const currentHash = computeChunkHash(chunks);
+        if (cache.hash !== currentHash) {
+            console.error("[ContextEngine] 💾 Cache stale (chunks changed) — will re-embed");
+            return null;
+        }
+        // Count check
+        if (cache.vectors.length !== chunks.length) {
+            console.error("[ContextEngine] 💾 Cache count mismatch — will re-embed");
+            return null;
+        }
+        // Reconstruct EmbeddedChunk[] from cache
+        const result = [];
+        for (let i = 0; i < chunks.length; i++) {
+            result.push({
+                chunk: chunks[i],
+                vector: new Float32Array(cache.vectors[i]),
+            });
+        }
+        console.error(`[ContextEngine] 💾 Loaded ${result.length} cached embeddings (instant!)`);
+        return result;
+    }
+    catch (err) {
+        console.error("[ContextEngine] ⚠ Cache read failed:", err.message);
+        return null;
+    }
+}
+/**
+ * Save embeddings to disk cache.
+ */
+export function saveCache(chunks, embedded) {
+    try {
+        if (!existsSync(CACHE_DIR)) {
+            mkdirSync(CACHE_DIR, { recursive: true });
+        }
+        const cache = {
+            hash: computeChunkHash(chunks),
+            version: CACHE_VERSION,
+            chunkCount: chunks.length,
+            timestamp: new Date().toISOString(),
+            chunkKeys: chunks.map((c) => ({
+                source: c.source,
+                section: c.section,
+                lineStart: c.lineStart,
+                lineEnd: c.lineEnd,
+            })),
+            vectors: embedded.map((ec) => Array.from(ec.vector)),
+        };
+        writeFileSync(CACHE_FILE, JSON.stringify(cache));
+        const sizeKB = Math.round(statSync(CACHE_FILE).size / 1024);
+        console.error(`[ContextEngine] 💾 Saved ${embedded.length} embeddings to cache (${sizeKB} KB)`);
+    }
+    catch (err) {
+        console.error("[ContextEngine] ⚠ Cache write failed:", err.message);
+    }
+}
+/**
+ * Clear the embedding cache.
+ */
+export function clearCache() {
+    try {
+        if (existsSync(CACHE_FILE)) {
+            unlinkSync(CACHE_FILE);
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/claude-integration.d.ts

@@ -0,0 +1,95 @@
+import type { KnowledgeSource } from "./config.js";
+export type SkillInstallScope = "global" | "project";
+export interface InstallSkillOpts {
+    scope?: SkillInstallScope;
+    cwd?: string;
+    force?: boolean;
+}
+export interface InstallSkillResult {
+    ok: boolean;
+    installedTo: string;
+    source: string;
+    message: string;
+    alreadyInstalled?: boolean;
+}
+/**
+ * Locate the bundled skill directory regardless of how the package was
+ * installed. Walks up from the running CLI to find the package root.
+ */
+export declare function locateBundledSkill(cliDistDir: string): string;
+export declare function installSkill(bundledSkillDir: string, opts?: InstallSkillOpts): InstallSkillResult;
+export interface ManagedBlockInput {
+    projectName: string;
+    topLearnings: Array<{
+        id: string;
+        category: string;
+        rule: string;
+        project?: string;
+    }>;
+    policySummary: {
+        secretPatternCount: number;
+        secretPatternIds: string[];
+        docCoverageCount: number;
+        deployVerifyHostCount: number;
+        bypassTokenCount: number;
+    } | null;
+    recentBlocks: Array<{
+        ts: string;
+        check: string;
+        reason: string;
+    }>;
+    generatedAt: string;
+}
+/**
+ * Build the managed-block content. Pure function — easy to test, never
+ * touches the filesystem.
+ *
+ * The format is intentionally compact: Claude Code's CLAUDE.md is loaded
+ * into every session's context, so each byte costs token budget. Aim for
+ * <500 tokens (~2000 chars) of content between the markers.
+ */
+export declare function buildManagedBlock(input: ManagedBlockInput): string;
+/**
+ * Write the managed block into CLAUDE.md. Idempotent: if markers exist,
+ * replace the content between them. Otherwise append at end.
+ *
+ * Returns the modified file content (for testing) AND writes it to disk.
+ */
+export interface SyncResult {
+    ok: boolean;
+    mode: "replaced-existing-block" | "appended-new-block" | "created-new-file";
+    filePath: string;
+    bytesWritten: number;
+}
+export declare function syncClaudeMd(filePath: string, blockContent: string): SyncResult;
+export declare const _markers: {
+    BEGIN_MARKER: string;
+    END_MARKER: string;
+};
+/**
+ * Walk Claude Code's per-project auto-memory directories and surface every
+ * .md file as a knowledge source. The structure is:
+ *   ~/.claude/projects/<project-slug>/memory/MEMORY.md
+ *   ~/.claude/projects/<project-slug>/memory/feedback_*.md
+ *   ~/.claude/projects/<project-slug>/memory/project_*.md
+ *   ... etc
+ *
+ * The <project-slug> is Claude Code's URL-safe encoding of an absolute path
+ * (slashes become hyphens, leading hyphen). We display the decoded path for
+ * readability in source names.
+ *
+ * Read-only: this function never modifies anything under ~/.claude/.
+ */
+export declare function discoverClaudeMemory(opts?: {
+    home?: string;
+}): KnowledgeSource[];
+/**
+ * Decode Claude Code's project slug back into a readable path.
+ * Encoding: leading hyphen, slashes → hyphens. e.g.
+ *   -Users-yan-Projects-INVOK-fr → /Users/yan/Projects/INVOK-fr
+ *
+ * Not perfectly reversible (a dir literally named "foo-bar" looks the same
+ * as a path /foo/bar) but good enough for the display label.
+ */
+export declare function decodeClaudeProjectSlug(slug: string): string;
+//# sourceMappingURL=claude-integration.d.ts.map

package/dist/claude-integration.js

@@ -0,0 +1,247 @@
+// 🔒 LOCKED [CLAUDE-INTEGRATION] — 2026-06-11
+// ⛔ NEVER change the BEGIN/END managed-block markers without a migration
+//    path. Users will have these markers committed in their CLAUDE.md
+//    files; changing the format silently doubles the block (old marker
+//    stays in place, new marker appended fresh).
+// ⛔ NEVER include rule content that could be sensitive (raw command lines,
+//    file paths with secrets, etc.) in the managed block — CLAUDE.md is
+//    committed to git. Emit IDs + categories + short descriptions only.
+// WHY: OpsContext-managed sections in CLAUDE.md are the highest-leverage
+//    integration with Claude Code — CLAUDE.md is loaded at every session
+//    start natively, so OpsContext's most-relevant intel lands in the
+//    agent's context with zero MCP roundtrip.
+// FIX: If the managed-block format needs to evolve, add a version line
+//    inside the marker and have the rewriter accept both old and new
+//    versions during a deprecation window.
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from "fs";
+import { join, dirname, resolve } from "path";
+import { homedir } from "os";
+/**
+ * Locate the bundled skill directory regardless of how the package was
+ * installed. Walks up from the running CLI to find the package root.
+ */
+export function locateBundledSkill(cliDistDir) {
+    // dist/cli.js → ../skills/opscontext/
+    return resolve(cliDistDir, "..", "skills", "opscontext");
+}
+export function installSkill(bundledSkillDir, opts = {}) {
+    const scope = opts.scope ?? defaultScope(opts.cwd ?? process.cwd());
+    const target = scope === "global"
+        ? join(homedir(), ".claude", "skills", "opscontext")
+        : join(opts.cwd ?? process.cwd(), ".claude", "skills", "opscontext");
+    const sourceSkillFile = join(bundledSkillDir, "SKILL.md");
+    const targetSkillFile = join(target, "SKILL.md");
+    if (!existsSync(sourceSkillFile)) {
+        return {
+            ok: false,
+            installedTo: target,
+            source: bundledSkillDir,
+            message: `Bundled skill not found at ${sourceSkillFile}. Reinstall @compr/opscontext-mcp.`,
+        };
+    }
+    if (existsSync(targetSkillFile) && !opts.force) {
+        return {
+            ok: true,
+            installedTo: target,
+            source: bundledSkillDir,
+            alreadyInstalled: true,
+            message: `Skill already installed at ${target}. Pass --force to overwrite.`,
+        };
+    }
+    mkdirSync(target, { recursive: true });
+    writeFileSync(targetSkillFile, readFileSync(sourceSkillFile, "utf-8"));
+    return {
+        ok: true,
+        installedTo: target,
+        source: bundledSkillDir,
+        message: `✅ Installed opscontext skill → ${targetSkillFile}`,
+    };
+}
+function defaultScope(cwd) {
+    // If the project has its own .claude/ dir, install there. Otherwise global.
+    return existsSync(join(cwd, ".claude")) ? "project" : "global";
+}
+// ---------------------------------------------------------------------------
+// B. CLAUDE.md auto-managed section
+// ---------------------------------------------------------------------------
+const BEGIN_MARKER = "<!-- BEGIN: managed by OpsContext (regenerated by `opscontext sync-claude-md`; manual edits to this block are overwritten) -->";
+const END_MARKER = "<!-- END: managed by OpsContext -->";
+/**
+ * Build the managed-block content. Pure function — easy to test, never
+ * touches the filesystem.
+ *
+ * The format is intentionally compact: Claude Code's CLAUDE.md is loaded
+ * into every session's context, so each byte costs token budget. Aim for
+ * <500 tokens (~2000 chars) of content between the markers.
+ */
+export function buildManagedBlock(input) {
+    const lines = [];
+    lines.push(BEGIN_MARKER);
+    lines.push(`## OpsContext snapshot for ${input.projectName}`);
+    lines.push("");
+    lines.push(`_Regenerated ${input.generatedAt}. Run \`opscontext sync-claude-md\` to refresh._`);
+    lines.push("");
+    // Top learnings — the recall hits the agent's context every session
+    if (input.topLearnings.length > 0) {
+        lines.push("### Top operational rules for this project");
+        for (const l of input.topLearnings) {
+            // Short ID + category prefix so the agent can cite it back; rule is the
+            // user-facing memory. Limit rule to one line to keep token budget low.
+            const rule = l.rule.replace(/\s+/g, " ").trim().slice(0, 180);
+            lines.push(`- [\`${l.id}\` · ${l.category}] ${rule}`);
+        }
+        lines.push("");
+    }
+    // Active policy gates — what the pre-commit hook will block
+    if (input.policySummary) {
+        lines.push("### Active policy gates (`.contextengine/policy.json`)");
+        const p = input.policySummary;
+        const parts = [];
+        if (p.secretPatternCount > 0) {
+            parts.push(`${p.secretPatternCount} secret pattern(s): ${p.secretPatternIds.slice(0, 5).join(", ")}${p.secretPatternIds.length > 5 ? "…" : ""}`);
+        }
+        if (p.docCoverageCount > 0)
+            parts.push(`${p.docCoverageCount} doc-coverage rule(s)`);
+        if (p.deployVerifyHostCount > 0)
+            parts.push(`${p.deployVerifyHostCount} deploy-verify host(s)`);
+        if (p.bypassTokenCount > 0)
+            parts.push(`${p.bypassTokenCount} bypass token(s)`);
+        if (parts.length === 0)
+            parts.push("policy.json present but no active rules");
+        for (const p2 of parts)
+            lines.push(`- ${p2}`);
+        lines.push("");
+    }
+    else {
+        lines.push("### Policy");
+        lines.push("- No `.contextengine/policy.json` in this repo. Run `opscontext policy validate <file>` to author one.");
+        lines.push("");
+    }
+    // Recent compliance events — show the agent what was blocked
+    if (input.recentBlocks.length > 0) {
+        lines.push("### Recent hook blocks (last 3, from `~/.contextengine/audit.log`)");
+        for (const b of input.recentBlocks) {
+            const ts = b.ts.split("T")[0];
+            lines.push(`- ${ts} — \`${b.check}\` blocked: ${b.reason}`);
+        }
+        lines.push("");
+    }
+    lines.push(END_MARKER);
+    return lines.join("\n");
+}
+export function syncClaudeMd(filePath, blockContent) {
+    let mode;
+    let nextContent;
+    if (!existsSync(filePath)) {
+        mode = "created-new-file";
+        nextContent = `# CLAUDE.md\n\n${blockContent}\n`;
+    }
+    else {
+        const current = readFileSync(filePath, "utf-8");
+        const beginIdx = current.indexOf(BEGIN_MARKER);
+        const endIdx = current.indexOf(END_MARKER);
+        if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+            // Replace the block + its trailing newline if present
+            const afterEnd = endIdx + END_MARKER.length;
+            const trailingNewline = current[afterEnd] === "\n" ? 1 : 0;
+            nextContent =
+                current.slice(0, beginIdx) +
+                    blockContent +
+                    current.slice(afterEnd + trailingNewline) +
+                    // ensure we don't end up with stray blanks at boundary
+                    (current[beginIdx - 1] === "\n" ? "" : "\n");
+            mode = "replaced-existing-block";
+        }
+        else {
+            // Append at end, with a leading newline if file doesn't end in one
+            const sep = current.endsWith("\n") ? "" : "\n";
+            nextContent = current + sep + "\n" + blockContent + "\n";
+            mode = "appended-new-block";
+        }
+    }
+    // Always ensure the file ends with a single newline (POSIX convention) so
+    // a repeat sync with the same input is a true no-op.
+    if (!nextContent.endsWith("\n"))
+        nextContent += "\n";
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, nextContent);
+    return {
+        ok: true,
+        mode,
+        filePath,
+        bytesWritten: Buffer.byteLength(nextContent),
+    };
+}
+// Exported for tests
+export const _markers = { BEGIN_MARKER, END_MARKER };
+// ---------------------------------------------------------------------------
+// C. Claude Code auto-memory discovery
+// ---------------------------------------------------------------------------
+/**
+ * Walk Claude Code's per-project auto-memory directories and surface every
+ * .md file as a knowledge source. The structure is:
+ *   ~/.claude/projects/<project-slug>/memory/MEMORY.md
+ *   ~/.claude/projects/<project-slug>/memory/feedback_*.md
+ *   ~/.claude/projects/<project-slug>/memory/project_*.md
+ *   ... etc
+ *
+ * The <project-slug> is Claude Code's URL-safe encoding of an absolute path
+ * (slashes become hyphens, leading hyphen). We display the decoded path for
+ * readability in source names.
+ *
+ * Read-only: this function never modifies anything under ~/.claude/.
+ */
+export function discoverClaudeMemory(opts = {}) {
+    const home = opts.home ?? homedir();
+    const root = join(home, ".claude", "projects");
+    if (!existsSync(root))
+        return [];
+    const sources = [];
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    for (const slug of entries) {
+        const memDir = join(root, slug, "memory");
+        if (!existsSync(memDir))
+            continue;
+        let files;
+        try {
+            files = readdirSync(memDir);
+        }
+        catch {
+            continue;
+        }
+        const displayPath = decodeClaudeProjectSlug(slug);
+        for (const f of files) {
+            if (!f.endsWith(".md"))
+                continue;
+            const filePath = join(memDir, f);
+            sources.push({
+                name: `Claude memory — ${displayPath} — ${f}`,
+                path: filePath,
+                type: "markdown",
+            });
+        }
+    }
+    return sources;
+}
+/**
+ * Decode Claude Code's project slug back into a readable path.
+ * Encoding: leading hyphen, slashes → hyphens. e.g.
+ *   -Users-yan-Projects-INVOK-fr → /Users/yan/Projects/INVOK-fr
+ *
+ * Not perfectly reversible (a dir literally named "foo-bar" looks the same
+ * as a path /foo/bar) but good enough for the display label.
+ */
+export function decodeClaudeProjectSlug(slug) {
+    if (!slug.startsWith("-"))
+        return slug;
+    // Replace the leading hyphen with a slash, leave the rest as-is for
+    // the display label.
+    return "/" + slug.slice(1);
+}
+//# sourceMappingURL=claude-integration.js.map

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * ContextEngine CLI — standalone tool access + MCP server.
+ *
+ * Usage:
+ *   contextengine                     Start MCP server (stdio transport)
+ *   contextengine init                Scaffold project for ContextEngine (mcp.json, docs, hooks)
+ *   contextengine search <query>      Search across all indexed knowledge
+ *   contextengine list-sources        Show all indexed sources with chunk counts
+ *   contextengine list-projects       Discover and analyze all projects
+ *   contextengine list-learnings      List all permanent learnings
+ *   contextengine save-learning        Save a learning (terminal fallback for MCP)
+ *   contextengine score [project]     AI-readiness score (writes SCORE.md to each project)
+ *   contextengine audit               Run compliance audit across all projects
+ *   contextengine help                Show this message
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map