matimo 0.1.0-alpha.8 → 0.1.1

package/packages/core/dist/core/skill-registry.js

@@ -0,0 +1,316 @@
+/**
+ * Skill Registry — in-memory store and search for skills
+ *
+ * Mirrors ToolRegistry but for skills. Provides discovery, search, and filtering.
+ * Supports both substring matching (default) and semantic search via pluggable embeddings.
+ */
+import { MatimoError, ErrorCode } from '../errors/matimo-error';
+import { getGlobalMatimoLogger } from '../logging';
+import { TfIdfEmbeddingProvider, cosineSimilarity } from './tfidf-embedding';
+import { parseSkillSections, extractSkillContent, listSkillSections } from './skill-content-parser';
+export class SkillRegistry {
+    constructor() {
+        this.logger = getGlobalMatimoLogger();
+        this.skills = new Map();
+        /** Pluggable embedding provider for semantic search */
+        this.embeddingProvider = null;
+        /** Cached embeddings: skill name → vector */
+        this.embeddings = new Map();
+        /** Whether embeddings need rebuilding */
+        this.embeddingsDirty = true;
+        /** Cached parsed content for selective loading */
+        this.parsedContent = new Map();
+        /**
+         * Get or create the default TF-IDF provider.
+         */
+        this.defaultProvider = null;
+    }
+    /**
+     * Set a custom embedding provider (OpenAI, Cohere, etc.).
+     * If not set, a built-in TF-IDF provider is used as fallback.
+     */
+    setEmbeddingProvider(provider) {
+        this.embeddingProvider = provider;
+        this.embeddingsDirty = true;
+        this.logger.debug('SkillRegistry: custom embedding provider set');
+    }
+    /**
+     * Register a single skill
+     */
+    register(skill) {
+        if (!skill.name) {
+            throw new MatimoError('Skill must have a name', ErrorCode.INVALID_SCHEMA);
+        }
+        this.skills.set(skill.name, skill);
+        this.embeddingsDirty = true;
+        // Cache parsed sections for selective loading
+        if (skill.body) {
+            this.parsedContent.set(skill.name, parseSkillSections(skill.body));
+        }
+        this.logger.debug('SkillRegistry: skill registered', { name: skill.name });
+    }
+    /**
+     * Register multiple skills
+     */
+    registerAll(skills) {
+        for (const skill of skills) {
+            this.register(skill);
+        }
+    }
+    /**
+     * Get a single skill by name
+     */
+    get(name) {
+        return this.skills.get(name);
+    }
+    /**
+     * Get a single skill by name (throws if not found)
+     */
+    getRequired(name) {
+        const skill = this.skills.get(name);
+        if (!skill) {
+            throw new MatimoError(`Skill not found: ${name}`, ErrorCode.TOOL_NOT_FOUND);
+        }
+        return skill;
+    }
+    /**
+     * Get selective skill content — only the sections an agent needs.
+     * This prevents dumping entire SKILL.md files into the LLM context.
+     *
+     * @example
+     * // Get only the error handling section, max 500 tokens
+     * registry.getSkillContent('postgres-query-operations', {
+     *   sections: ['Error Handling'],
+     *   maxTokens: 500,
+     * })
+     */
+    getSkillContent(name, options) {
+        const parsed = this.parsedContent.get(name);
+        if (!parsed)
+            return null;
+        return extractSkillContent(parsed, options);
+    }
+    /**
+     * List all sections of a skill with their token costs.
+     * Agents use this to decide which sections to load.
+     */
+    getSkillSections(name) {
+        const parsed = this.parsedContent.get(name);
+        if (!parsed)
+            return null;
+        return listSkillSections(parsed);
+    }
+    /**
+     * List all skills (Level 1 discovery — minimal context)
+     */
+    list() {
+        return Array.from(this.skills.values()).map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            version: skill.version,
+            license: skill.license,
+            metadata: skill.metadata,
+            source: skill.source,
+        }));
+    }
+    /**
+     * Search skills by keyword, category, difficulty, etc.
+     *
+     * When `options.semantic` is true, uses embedding-based similarity ranking
+     * instead of substring matching. Falls back to built-in TF-IDF if no
+     * external embedding provider is configured.
+     */
+    search(options = {}) {
+        const { query = '', category, difficulty, tags, author, limit = 50, offset = 0 } = options;
+        let results = Array.from(this.skills.values());
+        // Apply filters first (these are always exact/substring)
+        if (category) {
+            results = results.filter((skill) => skill.metadata?.category?.toLowerCase() === category.toLowerCase());
+        }
+        if (difficulty) {
+            results = results.filter((skill) => skill.metadata?.difficulty?.toLowerCase() === difficulty.toLowerCase());
+        }
+        if (tags && tags.length > 0) {
+            const metadataTags = tags.map((t) => t.toLowerCase());
+            results = results.filter((skill) => {
+                const skillTags = (skill.metadata?.tags || '')
+                    .split(',')
+                    .map((t) => t.trim().toLowerCase());
+                return metadataTags.some((tag) => skillTags.includes(tag));
+            });
+        }
+        if (author) {
+            results = results.filter((skill) => skill.metadata?.author?.toLowerCase() === author.toLowerCase());
+        }
+        // Apply query filter (substring or semantic)
+        if (query) {
+            if (options.semantic) {
+                // Semantic search: rank by embedding similarity
+                const scored = this.rankBySimilarity(query, results);
+                // Precompute a map for O(1) lookup by skill name
+                const skillByName = new Map(results.map((skill) => [skill.name, skill]));
+                results = scored
+                    .filter((r) => r.score > 0.1) // Minimum relevance threshold
+                    .sort((a, b) => b.score - a.score)
+                    .map((r) => skillByName.get(r.skill.name))
+                    .filter((skill) => skill !== undefined);
+            }
+            else {
+                // Substring search (original behavior)
+                const lowerQuery = query.toLowerCase();
+                results = results.filter((skill) => {
+                    const nameMatch = skill.name.toLowerCase().includes(lowerQuery);
+                    const descMatch = skill.description.toLowerCase().includes(lowerQuery);
+                    return nameMatch || descMatch;
+                });
+            }
+        }
+        // Pagination
+        const paged = results.slice(offset, offset + limit);
+        return paged.map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            version: skill.version,
+            license: skill.license,
+            metadata: skill.metadata,
+            source: skill.source,
+        }));
+    }
+    /**
+     * Semantic search with relevance scores.
+     * Returns ranked results with cosine similarity scores.
+     *
+     * @example
+     * const results = await registry.semanticSearch('How do I handle Postgres connection pooling?');
+     * // → [{ skill: { name: 'postgres-query-operations', ... }, score: 0.82 }]
+     */
+    async semanticSearch(query, options = {}) {
+        const { limit = 10, minScore = 0.1 } = options;
+        await this.ensureEmbeddings();
+        const provider = this.embeddingProvider || this.getDefaultProvider();
+        const queryEmbedding = await provider.embed(query);
+        const results = [];
+        for (const [name, embedding] of this.embeddings) {
+            const skill = this.skills.get(name);
+            if (!skill)
+                continue;
+            const score = cosineSimilarity(queryEmbedding, embedding);
+            if (score >= minScore) {
+                results.push({
+                    skill: {
+                        name: skill.name,
+                        description: skill.description,
+                        version: skill.version,
+                        license: skill.license,
+                        metadata: skill.metadata,
+                        source: skill.source,
+                    },
+                    score,
+                });
+            }
+        }
+        return results.sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    /**
+     * Get all skills (full definitions)
+     */
+    getAll() {
+        return Array.from(this.skills.values());
+    }
+    /**
+     * Check if a skill exists
+     */
+    has(name) {
+        return this.skills.has(name);
+    }
+    /**
+     * Get the count of registered skills
+     */
+    count() {
+        return this.skills.size;
+    }
+    /**
+     * Clear all skills
+     */
+    clear() {
+        this.skills.clear();
+        this.embeddings.clear();
+        this.parsedContent.clear();
+        this.embeddingsDirty = true;
+    }
+    /**
+     * Remove a skill
+     */
+    remove(name) {
+        this.embeddings.delete(name);
+        this.parsedContent.delete(name);
+        this.embeddingsDirty = true;
+        return this.skills.delete(name);
+    }
+    // ─── Private: Embedding Management ──────────────────────────────────────
+    /**
+     * Ensure embeddings are computed and up-to-date.
+     */
+    async ensureEmbeddings() {
+        if (!this.embeddingsDirty)
+            return;
+        const provider = this.embeddingProvider || this.getDefaultProvider();
+        const skills = Array.from(this.skills.values());
+        // Build text corpus: name + description + metadata tags
+        const texts = skills.map((s) => this.skillToText(s));
+        // If using TF-IDF, refit the vocabulary
+        if (provider instanceof TfIdfEmbeddingProvider) {
+            provider.fit(texts);
+        }
+        const vectors = await provider.embedBatch(texts);
+        this.embeddings.clear();
+        for (let i = 0; i < skills.length; i++) {
+            this.embeddings.set(skills[i].name, vectors[i]);
+        }
+        this.embeddingsDirty = false;
+    }
+    /**
+     * Synchronous ranking using TF-IDF (for the non-async search() method).
+     */
+    rankBySimilarity(query, candidates) {
+        const provider = this.getDefaultProvider();
+        // Build corpus from candidates
+        const texts = candidates.map((s) => this.skillToText(s));
+        provider.fit([...texts, query]); // Include query in vocab
+        const queryVec = provider.embedSync(query);
+        return candidates.map((skill) => {
+            const skillVec = provider.embedSync(this.skillToText(skill));
+            return {
+                skill: {
+                    name: skill.name,
+                    description: skill.description,
+                    version: skill.version,
+                    license: skill.license,
+                    metadata: skill.metadata,
+                    source: skill.source,
+                },
+                score: cosineSimilarity(queryVec, skillVec),
+            };
+        });
+    }
+    getDefaultProvider() {
+        if (!this.defaultProvider) {
+            this.defaultProvider = new TfIdfEmbeddingProvider();
+        }
+        return this.defaultProvider;
+    }
+    /**
+     * Convert a skill into a searchable text string for embedding.
+     */
+    skillToText(skill) {
+        const parts = [skill.name.replace(/-/g, ' '), skill.description];
+        if (skill.metadata?.tags)
+            parts.push(skill.metadata.tags);
+        if (skill.metadata?.category)
+            parts.push(skill.metadata.category);
+        if (skill.allowedTools)
+            parts.push(skill.allowedTools.join(' '));
+        return parts.join(' ');
+    }
+}
+//# sourceMappingURL=skill-registry.js.map

package/packages/core/dist/core/skill-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-registry.js","sourceRoot":"","sources":["../../src/core/skill-registry.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/core/tfidf-embedding.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TF-IDF Embedding Provider — zero-dependency semantic search
+ * (Term Frequency–Inverse Document Frequency)
+ * Provides a lightweight text-to-vector implementation using TF-IDF (Term
+ * Frequency–Inverse Document Frequency) for cosine-similarity ranking. This
+ * is good enough for 10–200 skills. For production enterprise deployments,
+ * plug in an OpenAI/Cohere `EmbeddingProvider` instead.
+ *
+ * No external dependencies — works out of the box.
+ */
+import { EmbeddingProvider } from './types';
+/**
+ * Simple TF-IDF based embedding provider.
+ * Builds a vocabulary from the registered corpus and represents each text as
+ * a TF-IDF weighted vector.
+ */
+export declare class TfIdfEmbeddingProvider implements EmbeddingProvider {
+    private vocabulary;
+    private idf;
+    private corpusSize;
+    private _dimensions;
+    get dimensions(): number;
+    /**
+     * Build the vocabulary and IDF weights from a corpus of documents.
+     * Must be called before `embed()` or `embedBatch()`.
+     */
+    fit(documents: string[]): void;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Synchronous embed for internal use (no async overhead).
+     */
+    embedSync(text: string): number[];
+    /**
+     * Tokenize text into lowercase terms.
+     * Splits on non-alphanumeric characters and filters stopwords.
+     */
+    private tokenize;
+}
+/**
+ * Cosine similarity between two vectors.
+ * Returns a value between -1 and 1 (1 = identical, 0 = orthogonal).
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=tfidf-embedding.d.ts.map

package/packages/core/dist/core/tfidf-embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf-embedding.d.ts","sourceRoot":"","sources":["../../src/core/tfidf-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,GAAG,CAAqC;IAChD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,WAAW,CAAK;IAExB,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;OAGG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IA2BxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAItC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAItD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAsCjC;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAMjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAejE"}

package/packages/core/dist/core/tfidf-embedding.js

@@ -0,0 +1,199 @@
+/**
+ * TF-IDF Embedding Provider — zero-dependency semantic search
+ * (Term Frequency–Inverse Document Frequency)
+ * Provides a lightweight text-to-vector implementation using TF-IDF (Term
+ * Frequency–Inverse Document Frequency) for cosine-similarity ranking. This
+ * is good enough for 10–200 skills. For production enterprise deployments,
+ * plug in an OpenAI/Cohere `EmbeddingProvider` instead.
+ *
+ * No external dependencies — works out of the box.
+ */
+/**
+ * Simple TF-IDF based embedding provider.
+ * Builds a vocabulary from the registered corpus and represents each text as
+ * a TF-IDF weighted vector.
+ */
+export class TfIdfEmbeddingProvider {
+    constructor() {
+        this.vocabulary = new Map();
+        this.idf = new Float64Array(0);
+        this.corpusSize = 0;
+        this._dimensions = 0;
+    }
+    get dimensions() {
+        return this._dimensions;
+    }
+    /**
+     * Build the vocabulary and IDF weights from a corpus of documents.
+     * Must be called before `embed()` or `embedBatch()`.
+     */
+    fit(documents) {
+        this.vocabulary.clear();
+        this.corpusSize = documents.length;
+        // Build vocabulary (unique terms across all documents)
+        const docFrequency = new Map();
+        for (const doc of documents) {
+            const terms = this.tokenize(doc);
+            const uniqueTerms = new Set(terms);
+            for (const term of uniqueTerms) {
+                docFrequency.set(term, (docFrequency.get(term) || 0) + 1);
+            }
+        }
+        // Assign indices and compute IDF
+        let idx = 0;
+        const idfValues = [];
+        for (const [term, df] of docFrequency) {
+            this.vocabulary.set(term, idx++);
+            // Smooth IDF: log((N + 1) / (df + 1)) + 1
+            idfValues.push(Math.log((this.corpusSize + 1) / (df + 1)) + 1);
+        }
+        this._dimensions = idfValues.length;
+        this.idf = new Float64Array(idfValues);
+    }
+    async embed(text) {
+        return this.embedSync(text);
+    }
+    async embedBatch(texts) {
+        return texts.map((t) => this.embedSync(t));
+    }
+    /**
+     * Synchronous embed for internal use (no async overhead).
+     */
+    embedSync(text) {
+        if (this._dimensions === 0) {
+            return [];
+        }
+        const terms = this.tokenize(text);
+        const tf = new Float64Array(this._dimensions);
+        // Count term frequencies
+        for (const term of terms) {
+            const idx = this.vocabulary.get(term);
+            if (idx !== undefined) {
+                tf[idx]++;
+            }
+        }
+        // Normalize TF (sublinear: 1 + log(tf) if tf > 0)
+        for (let i = 0; i < this._dimensions; i++) {
+            if (tf[i] > 0) {
+                tf[i] = (1 + Math.log(tf[i])) * this.idf[i];
+            }
+        }
+        // L2 normalize
+        let norm = 0;
+        for (let i = 0; i < this._dimensions; i++) {
+            norm += tf[i] * tf[i];
+        }
+        norm = Math.sqrt(norm);
+        if (norm > 0) {
+            for (let i = 0; i < this._dimensions; i++) {
+                tf[i] /= norm;
+            }
+        }
+        return Array.from(tf);
+    }
+    /**
+     * Tokenize text into lowercase terms.
+     * Splits on non-alphanumeric characters and filters stopwords.
+     */
+    tokenize(text) {
+        return text
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+    }
+}
+/**
+ * Cosine similarity between two vectors.
+ * Returns a value between -1 and 1 (1 = identical, 0 = orthogonal).
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dot / denominator;
+}
+/** Common English stopwords to exclude from TF-IDF */
+const STOPWORDS = new Set([
+    'a',
+    'an',
+    'the',
+    'and',
+    'or',
+    'but',
+    'in',
+    'on',
+    'at',
+    'to',
+    'for',
+    'of',
+    'with',
+    'by',
+    'from',
+    'is',
+    'it',
+    'as',
+    'be',
+    'was',
+    'are',
+    'this',
+    'that',
+    'not',
+    'do',
+    'if',
+    'so',
+    'no',
+    'up',
+    'my',
+    'we',
+    'he',
+    'she',
+    'they',
+    'you',
+    'me',
+    'us',
+    'all',
+    'can',
+    'had',
+    'has',
+    'have',
+    'will',
+    'would',
+    'could',
+    'should',
+    'may',
+    'might',
+    'shall',
+    'been',
+    'being',
+    'were',
+    'did',
+    'does',
+    'its',
+    'than',
+    'then',
+    'when',
+    'what',
+    'which',
+    'who',
+    'how',
+    'there',
+    'here',
+    'about',
+    'into',
+    'over',
+    'after',
+    'also',
+    'each',
+    'just',
+    'only',
+    'very',
+]);
+//# sourceMappingURL=tfidf-embedding.js.map

package/packages/core/dist/core/tfidf-embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tfidf-embedding.js","sourceRoot":"","sources":["../../src/core/tfidf-embedding.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/core/tool-loader.d.ts

@@ -12,7 +12,9 @@ export declare class ToolLoader {
     private static discoveredPathsCache;
     /**
      * Discover packages using only fs and path (no createRequire needed)
-     * Searches for tools in node_modules/@matimo/* and workspace packages
+     * Searches for tools in node_modules/@matimo/* and workspace packages.
+     * Tries process.cwd() first, then falls back to __dirname-based discovery
+     * (critical for Claude Desktop where cwd may be '/' on macOS).
      */
     private getNodeModulesPath;
     /**

package/packages/core/dist/core/tool-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-loader.d.ts","sourceRoot":"","sources":["../../src/core/tool-loader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAA0B,MAAM,UAAU,CAAC;AAGlE;;;;GAIG;AAEH,qBAAa,UAAU;IACrB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAyB;IAC5D;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc;IAgDlD;;;;;OAKG;IACH,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAkDpE;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc;IAIjD;;;;OAIG;IACH,oBAAoB,IAAI,MAAM,EAAE;IAkFhC;;;OAGG;IACH,MAAM,CAAC,mBAAmB,IAAI,IAAI;IAIlC;;;;OAIG;IACH,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;CAkB5E;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"tool-loader.d.ts","sourceRoot":"","sources":["../../src/core/tool-loader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAA0B,MAAM,UAAU,CAAC;AAGlE;;;;GAIG;AAEH,qBAAa,UAAU;IACrB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAyB;IAC5D;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAqC1B;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc;IAgDlD;;;;;OAKG;IACH,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAkDpE;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc;IAIjD;;;;OAIG;IACH,oBAAoB,IAAI,MAAM,EAAE;IAwFhC;;;OAGG;IACH,MAAM,CAAC,mBAAmB,IAAI,IAAI;IAIlC;;;;OAIG;IACH,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;CAkB5E;AAED,eAAe,UAAU,CAAC"}

package/packages/core/dist/core/tool-loader.js

@@ -11,16 +11,32 @@ import { MatimoError, ErrorCode } from '../errors/matimo-error';
 export class ToolLoader {
     /**
      * Discover packages using only fs and path (no createRequire needed)
-     * Searches for tools in node_modules/@matimo/* and workspace packages
+     * Searches for tools in node_modules/@matimo/* and workspace packages.
+     * Tries process.cwd() first, then falls back to __dirname-based discovery
+     * (critical for Claude Desktop where cwd may be '/' on macOS).
      */
     getNodeModulesPath() {
         try {
-            // Start from current working directory and search upwards
+            // Strategy 1: Walk up from process.cwd()
             let currentPath = process.cwd();
             for (let i = 0; i < 15; i++) {
                 const nodeModules = path.join(currentPath, 'node_modules');
                 if (fs.existsSync(nodeModules)) {
-                    // Verify @matimo scope exists
+                    const matimoScope = path.join(nodeModules, '@matimo');
+                    if (fs.existsSync(matimoScope)) {
+                        return nodeModules;
+                    }
+                }
+                currentPath = path.dirname(currentPath);
+            }
+            // Strategy 2: Walk up from this file's location (__dirname)
+            // When this code is in node_modules/@matimo/core/dist/core/tool-loader.js,
+            // walking up will find the node_modules directory directly.
+            // When in monorepo at packages/core/src/core/, it will find root node_modules.
+            currentPath = __dirname;
+            for (let i = 0; i < 10; i++) {
+                const nodeModules = path.join(currentPath, 'node_modules');
+                if (fs.existsSync(nodeModules)) {
                     const matimoScope = path.join(nodeModules, '@matimo');
                     if (fs.existsSync(matimoScope)) {
                         return nodeModules;
@@ -154,16 +170,23 @@ export class ToolLoader {
                     discoveredPaths.push(coreToolsPath);
                 }
             }
-            // If not found in node_modules, try workspace
+            // If not found in node_modules, try workspace (from cwd and __dirname)
             if (discoveredPaths.length === 0) {
-                let currentPath = process.cwd();
-                for (let i = 0; i < 20; i++) {
-                    const coreToolsPath = path.join(currentPath, 'packages', 'core', 'tools');
-                    if (fs.existsSync(coreToolsPath)) {
-                        discoveredPaths.push(coreToolsPath);
+                const searchRoots = [process.cwd(), __dirname];
+                let found = false;
+                for (const root of searchRoots) {
+                    if (found)
                         break;
+                    let currentPath = root;
+                    for (let i = 0; i < 20; i++) {
+                        const coreToolsPath = path.join(currentPath, 'packages', 'core', 'tools');
+                        if (fs.existsSync(coreToolsPath)) {
+                            discoveredPaths.push(coreToolsPath);
+                            found = true;
+                            break;
+                        }
+                        currentPath = path.dirname(currentPath);
                     }
-                    currentPath = path.dirname(currentPath);
                 }
             }
         }