@knowledgine/cli 0.6.1 → 0.6.3

package/dist/templates/skills/knowledgine-recall/references.js

@@ -0,0 +1,207 @@
+export const REFERENCES = {
+    "search-strategy.md": `# Search Strategy
+
+How to choose the right search mode and build an effective recall workflow.
+
+---
+
+## Mode Selection
+
+### Keyword Mode
+
+Uses SQLite FTS5 full-text search. Matches documents containing the exact words.
+
+**Best for**:
+- Exact error messages (e.g., \`"SQLITE_ERROR: no such module: vec0"\`)
+- Function or variable names (e.g., \`"capture_knowledge"\`, \`"KnowledgeRepository"\`)
+- File paths (e.g., \`"packages/core/src"\`)
+- Version strings or identifiers
+
+**Limitations**:
+- Does not match synonyms ("fix" will not match "resolve")
+- Case-insensitive but word-boundary sensitive
+- Phrase order matters in multi-word queries
+
+**Example**:
+\`\`\`
+search_knowledge(query: "ENOENT no such file or directory", mode: "keyword")
+\`\`\`
+
+### Semantic Mode
+
+Uses vector embeddings to match by meaning. Finds related content even without shared words.
+
+**Best for**:
+- Conceptual queries (e.g., "how to handle authentication errors")
+- When you know what you want but not the exact terms
+- Exploring a topic without a specific error message
+- Cross-language or paraphrase matching
+
+**Requirements**:
+- Knowledge base must have been initialized with \`--semantic\` flag
+- Falls back to keyword if embeddings are unavailable
+
+**Example**:
+\`\`\`
+search_knowledge(query: "user authentication token expiry", mode: "semantic")
+\`\`\`
+
+### Hybrid Mode
+
+Combines keyword and semantic scores. Returns the best of both modes.
+
+**Best for**:
+- Most general-purpose searches
+- When you are unsure which mode is better
+- Complex queries mixing exact terms and concepts
+
+**Example**:
+\`\`\`
+search_knowledge(query: "TypeScript null safety database repository", mode: "hybrid")
+\`\`\`
+
+---
+
+## Workflow Patterns
+
+### Pattern 1: Error-first Search
+
+When encountering an error:
+
+1. Copy the exact error message
+2. Run keyword search with the error message
+3. If no results, extract the key noun from the error and try again
+4. If still no results, try semantic search with the symptom description
+
+\`\`\`
+Error: "Cannot find module '@knowledgine/core'"
+→ keyword: "Cannot find module @knowledgine/core"
+→ keyword: "module resolution"
+→ semantic: "TypeScript module not found build error"
+\`\`\`
+
+### Pattern 2: Context Discovery
+
+When starting work on an unfamiliar area:
+
+1. Search by file path: \`keyword: "src/commands/setup.ts"\`
+2. Search by component name: \`keyword: "setupCommand"\`
+3. Search by topic: \`semantic: "MCP configuration setup"\`
+
+### Pattern 3: Decision Lookup
+
+Before making an architectural choice:
+
+1. Search for past decisions: \`keyword: "design-decision <topic>"\`
+2. Search for related patterns: \`semantic: "<concept> pattern implementation"\`
+3. Check entity connections: use \`get_entity_graph\` for related components
+
+---
+
+## Result Interpretation
+
+| Score | Meaning |
+|-------|---------|
+| > 0.9 | Very strong match — highly likely relevant |
+| 0.7–0.9 | Good match — review for applicability |
+| 0.5–0.7 | Weak match — may or may not be relevant |
+| < 0.5 | Marginal — usually skip unless no better results |
+
+For keyword mode, results are ranked by BM25 relevance score (FTS5).
+For semantic mode, results are ranked by cosine similarity of embeddings.
+`,
+    "query-tips.md": `# Query Tips
+
+How to formulate effective search queries for different situations.
+
+---
+
+## General Principles
+
+1. **Specificity wins** — Specific queries outperform vague ones
+   - Bad:  \`"error"\`
+   - Good: \`"TypeError cannot read properties of undefined"\`
+
+2. **Use nouns and identifiers** — Verbs and adjectives add noise
+   - Bad:  \`"how to fix the broken thing when null"\`
+   - Good: \`"null check repository getById"\`
+
+3. **Error messages are gold** — Paste them verbatim for keyword mode
+
+4. **Concepts use natural language** — For semantic mode, describe the situation
+   - \`"what approach did we use for caching database results"\`
+
+---
+
+## Query Templates by Situation
+
+### Error Message
+\`\`\`
+// Paste the exact error message
+keyword: "<exact error text>"
+
+// If too long, use the unique part
+keyword: "SQLITE_CONSTRAINT UNIQUE"
+\`\`\`
+
+### File or Component
+\`\`\`
+keyword: "<filename without extension>"
+keyword: "<ClassName> OR <functionName>"
+\`\`\`
+
+### Design Topic
+\`\`\`
+semantic: "<component> architecture decision"
+keyword: "design-decision <topic>"
+\`\`\`
+
+### Past Problem
+\`\`\`
+semantic: "<symptom description in plain language>"
+hybrid: "<technology> <problem noun>"
+\`\`\`
+
+### Pattern Search
+\`\`\`
+keyword: "pattern <concept>"
+semantic: "reusable pattern for <problem type>"
+\`\`\`
+
+---
+
+## When First Query Returns Nothing
+
+Try these fallback strategies in order:
+
+1. **Broaden the query** — Remove specific identifiers, keep nouns
+   - \`"SQLITE_ERROR: table notes has no column 'embedding'"\`
+   - → \`"sqlite migration column"\`
+
+2. **Switch modes** — If keyword failed, try semantic and vice versa
+
+3. **Synonym query** — Use related terms
+   - \`"authentication"\` → \`"auth session token login"\`
+
+4. **Tag-based query** — Search by tag category
+   - \`"bug-fix typescript"\`
+   - \`"design-decision database"\`
+
+5. **Accept no results** — Not every problem has been captured before.
+   After solving it, use knowledgine-capture to record the solution.
+
+---
+
+## Limit Guidance
+
+| Situation | Recommended limit |
+|-----------|-------------------|
+| Quick lookup (known topic) | 3–5 |
+| General exploration | 10 (default) |
+| Building full context | 15–20 |
+| Finding rare entries | 20+ |
+
+Higher limits slow down search marginally; prefer lower limits when query is precise.
+`,
+};
+//# sourceMappingURL=references.js.map

package/dist/templates/skills/knowledgine-recall/references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-recall/references.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAA2B;IAChD,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GvB;IAEC,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4FlB;CACA,CAAC"}

package/dist/templates/skills/knowledgine-recall/skill-md.d.ts

@@ -0,0 +1,2 @@
+export declare const SKILL_MD = "---\nname: knowledgine-recall\ndescription: >\n  Search the local knowledge base for past solutions, design decisions, and patterns\n  before starting work. Invoke when facing an error or exception, when approaching an\n  unfamiliar area of the codebase, or when considering implementation approaches.\n  Prevents re-solving already-solved problems and surfaces relevant context proactively.\n---\n# knowledgine-recall\n\n## Purpose\n\nSearch accumulated project knowledge before solving problems from scratch. The knowledge\nbase contains past bug fixes, design decisions, troubleshooting records, and patterns\ngathered across all previous sessions. Searching first avoids duplicate work and surfaces\nwarnings about known pitfalls.\n\n## When to Use\n\n- **Error or exception encountered** \u2014 Search for the exact error message or key terms\n- **Unfamiliar code area** \u2014 Search for context about the component or module\n- **Implementation choice** \u2014 Search for past decisions on the same topic\n- **Considering a library or approach** \u2014 Search for known gotchas or prior art\n- **Starting work on a file** \u2014 Search for related notes about that file path\n\n## When NOT to Use\n\n- Purely mechanical tasks with no ambiguity (renaming a variable, formatting)\n- When you have already searched and found no relevant results within this session\n- Do not call recall on every single action \u2014 use judgment\n\n## How to Search (MCP Tool)\n\nUse the `search_knowledge` MCP tool:\n\n```\nsearch_knowledge(\n  query: string,          // Search query \u2014 see query tips below\n  mode: \"keyword\"         // \"keyword\" | \"semantic\" | \"hybrid\"\n       | \"semantic\"       //   keyword: exact text match (fast, precise)\n       | \"hybrid\",        //   semantic: meaning-based (requires embeddings)\n                          //   hybrid:   combines both (best results)\n  limit?: number          // Max results (default 10)\n)\n```\n\n## How to Search (CLI Alternative)\n\n```bash\nknowledgine recall \"<query>\"                    # keyword search\nknowledgine recall \"<query>\" --mode semantic    # semantic search\nknowledgine recall \"<query>\" --mode hybrid      # hybrid search\n```\n\n## Choosing Search Mode\n\n| Situation | Mode |\n|-----------|------|\n| You have an exact error message | `keyword` |\n| You remember specific function or variable names | `keyword` |\n| You know the concept but not the exact wording | `semantic` |\n| General exploration of a topic | `hybrid` |\n| Embeddings not available (FTS5-only setup) | `keyword` (only option) |\n\n## Step-by-Step Instructions\n\n1. **Identify the query** \u2014 Extract the key terms from the problem (see search-strategy.md)\n2. **Choose mode** \u2014 keyword for precise terms, semantic or hybrid for concepts\n3. **Call search_knowledge** \u2014 Pass query, mode, limit (5\u201310 is usually sufficient)\n4. **Evaluate results** \u2014 Read the returned notes for relevance\n5. **Apply findings** \u2014 Use relevant past solutions or decisions to inform your work\n6. **Capture if new** \u2014 If you discover a new solution, use knowledgine-capture to save it\n\n## Best Practices\n\n- Search before proposing a solution, not after\n- Use the actual error message text as a query \u2014 it is the most targeted search\n- Try multiple queries if the first returns no results\n- Combine recall + suggest at session start for comprehensive context\n\n## Reference Files\n\n- See `search-strategy.md` for when to use keyword vs semantic vs hybrid\n- See `query-tips.md` for how to formulate effective queries\n";
+//# sourceMappingURL=skill-md.d.ts.map

package/dist/templates/skills/knowledgine-recall/skill-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md.d.ts","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-recall/skill-md.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ,kiHAoFpB,CAAC"}

package/dist/templates/skills/knowledgine-recall/skill-md.js

@@ -0,0 +1,86 @@
+export const SKILL_MD = `---
+name: knowledgine-recall
+description: >
+  Search the local knowledge base for past solutions, design decisions, and patterns
+  before starting work. Invoke when facing an error or exception, when approaching an
+  unfamiliar area of the codebase, or when considering implementation approaches.
+  Prevents re-solving already-solved problems and surfaces relevant context proactively.
+---
+# knowledgine-recall
+
+## Purpose
+
+Search accumulated project knowledge before solving problems from scratch. The knowledge
+base contains past bug fixes, design decisions, troubleshooting records, and patterns
+gathered across all previous sessions. Searching first avoids duplicate work and surfaces
+warnings about known pitfalls.
+
+## When to Use
+
+- **Error or exception encountered** — Search for the exact error message or key terms
+- **Unfamiliar code area** — Search for context about the component or module
+- **Implementation choice** — Search for past decisions on the same topic
+- **Considering a library or approach** — Search for known gotchas or prior art
+- **Starting work on a file** — Search for related notes about that file path
+
+## When NOT to Use
+
+- Purely mechanical tasks with no ambiguity (renaming a variable, formatting)
+- When you have already searched and found no relevant results within this session
+- Do not call recall on every single action — use judgment
+
+## How to Search (MCP Tool)
+
+Use the \`search_knowledge\` MCP tool:
+
+\`\`\`
+search_knowledge(
+  query: string,          // Search query — see query tips below
+  mode: "keyword"         // "keyword" | "semantic" | "hybrid"
+       | "semantic"       //   keyword: exact text match (fast, precise)
+       | "hybrid",        //   semantic: meaning-based (requires embeddings)
+                          //   hybrid:   combines both (best results)
+  limit?: number          // Max results (default 10)
+)
+\`\`\`
+
+## How to Search (CLI Alternative)
+
+\`\`\`bash
+knowledgine recall "<query>"                    # keyword search
+knowledgine recall "<query>" --mode semantic    # semantic search
+knowledgine recall "<query>" --mode hybrid      # hybrid search
+\`\`\`
+
+## Choosing Search Mode
+
+| Situation | Mode |
+|-----------|------|
+| You have an exact error message | \`keyword\` |
+| You remember specific function or variable names | \`keyword\` |
+| You know the concept but not the exact wording | \`semantic\` |
+| General exploration of a topic | \`hybrid\` |
+| Embeddings not available (FTS5-only setup) | \`keyword\` (only option) |
+
+## Step-by-Step Instructions
+
+1. **Identify the query** — Extract the key terms from the problem (see search-strategy.md)
+2. **Choose mode** — keyword for precise terms, semantic or hybrid for concepts
+3. **Call search_knowledge** — Pass query, mode, limit (5–10 is usually sufficient)
+4. **Evaluate results** — Read the returned notes for relevance
+5. **Apply findings** — Use relevant past solutions or decisions to inform your work
+6. **Capture if new** — If you discover a new solution, use knowledgine-capture to save it
+
+## Best Practices
+
+- Search before proposing a solution, not after
+- Use the actual error message text as a query — it is the most targeted search
+- Try multiple queries if the first returns no results
+- Combine recall + suggest at session start for comprehensive context
+
+## Reference Files
+
+- See \`search-strategy.md\` for when to use keyword vs semantic vs hybrid
+- See \`query-tips.md\` for how to formulate effective queries
+`;
+//# sourceMappingURL=skill-md.js.map

package/dist/templates/skills/knowledgine-recall/skill-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-recall/skill-md.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFvB,CAAC"}

package/dist/templates/skills/knowledgine-suggest/references.d.ts

@@ -0,0 +1,2 @@
+export declare const REFERENCES: Record<string, string>;
+//# sourceMappingURL=references.d.ts.map

package/dist/templates/skills/knowledgine-suggest/references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-suggest/references.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuH7C,CAAC"}

package/dist/templates/skills/knowledgine-suggest/references.js

@@ -0,0 +1,121 @@
+export const REFERENCES = {
+    "context-patterns.md": `# Context Patterns
+
+How to extract effective context signals from your current work to generate meaningful
+knowledge suggestions.
+
+---
+
+## Context Signal Types
+
+### 1. File Path Context
+
+The file path is often the most precise context signal. It encodes module, feature area,
+and component type simultaneously.
+
+**How to use**:
+- Pass the file path to \`find_related(filePath: "<path>")\` directly
+- Extract path segments for search queries
+
+**Examples**:
+| File Path | Extracted Query |
+|-----------|-----------------|
+| \`src/commands/setup.ts\` | \`"setup command configuration"\` |
+| \`packages/core/src/config/config-loader.ts\` | \`"config loader configuration"\` |
+| \`packages/ingest/src/plugins/github.ts\` | \`"github ingest plugin"\` |
+
+### 2. Task Description Context
+
+Transform the task description into a knowledge query by extracting nouns and
+technical terms.
+
+**Pattern**:
+\`\`\`
+Task: "Add support for TOML config files in the setup command"
+Query: "TOML configuration setup"
+Query: "config file format"
+\`\`\`
+
+**Pattern**:
+\`\`\`
+Task: "Fix the entity extraction pipeline to handle empty documents"
+Query: "entity extraction empty document"
+Query: "edge case null handling entity"
+\`\`\`
+
+### 3. Error Message Context
+
+When starting work to fix a specific error, use the error as the primary signal.
+
+**Pattern**:
+\`\`\`
+Error: "SQLITE_ERROR: table entities has no column 'confidence'"
+Query keyword: "SQLITE_ERROR entities column"
+Query keyword: "migration entities table"
+\`\`\`
+
+### 4. Feature Area Context
+
+When working on a broad feature, search for the feature domain.
+
+**Examples**:
+| Feature Area | Context Query |
+|-------------|---------------|
+| Authentication | \`"authentication session token"\` |
+| Search | \`"search_knowledge FTS5 semantic"\` |
+| Ingest pipeline | \`"ingest plugin markdown"\` |
+| MCP server | \`"MCP server start file watcher"\` |
+
+---
+
+## Multi-Signal Queries
+
+Combine 2–3 signals for more targeted results:
+
+\`\`\`
+// File + task
+query: "config-loader TOML parsing"
+
+// Component + problem type
+query: "KnowledgeRepository null safety"
+
+// Technology + pattern
+query: "sqlite migration schema change"
+\`\`\`
+
+---
+
+## Using find_related for Graph Traversal
+
+After finding an initial relevant note, use \`find_related\` to discover connected notes:
+
+\`\`\`
+// Found note ID "abc123" about config loading
+find_related(noteId: "abc123", limit: 10, maxHops: 2)
+
+// Or search by the current file path directly
+find_related(filePath: "packages/core/src/config/config-loader.ts", limit: 10)
+\`\`\`
+
+**maxHops guidance**:
+| maxHops | Effect |
+|---------|--------|
+| 1 | Direct references only — fast, focused |
+| 2 | One degree of separation — good default |
+| 3 | Broader graph — use for open-ended exploration |
+
+---
+
+## Suggest vs Recall Decision Guide
+
+| Situation | Use |
+|-----------|-----|
+| You have a specific error message | knowledgine-recall |
+| You know exactly what to search for | knowledgine-recall |
+| You are starting work, unsure what is relevant | knowledgine-suggest |
+| You want to discover what you don't know | knowledgine-suggest |
+| You have a file path but no specific query | knowledgine-suggest |
+| You want both targeted + exploratory | suggest first, then recall |
+`,
+};
+//# sourceMappingURL=references.js.map

package/dist/templates/skills/knowledgine-suggest/references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-suggest/references.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAA2B;IAChD,qBAAqB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqHxB;CACA,CAAC"}

package/dist/templates/skills/knowledgine-suggest/skill-md.d.ts

@@ -0,0 +1,2 @@
+export declare const SKILL_MD = "---\nname: knowledgine-suggest\ndescription: >\n  Get contextual knowledge suggestions based on the current work context \u2014 the file\n  being edited, the task being performed, or the error being investigated. Invoke at\n  the start of a work session, when opening a new file, or when beginning a feature.\n  Surfaces relevant past knowledge proactively without requiring a specific query.\n---\n# knowledgine-suggest\n\n## Purpose\n\nSurface relevant knowledge from the knowledge base based on contextual signals extracted\nfrom the current work, rather than a specific search query. Suggest combines search and\ngraph traversal to bring forward knowledge you might not know to search for.\n\n## When to Use\n\n- **Starting a session** \u2014 Get context about the area you will work in\n- **Opening a new file** \u2014 Discover past knowledge about that component\n- **Beginning a feature** \u2014 Find related patterns and past decisions\n- **Before making changes** \u2014 Check for warnings or prior art on the topic\n- **Exploring an unfamiliar module** \u2014 Find related entities and notes\n\n## When NOT to Use\n\n- When you already have a specific query in mind (use knowledgine-recall instead)\n- When working on trivial mechanical tasks with no design ambiguity\n- After already calling suggest for the same file in the same session\n\n## How to Get Suggestions (MCP Tools)\n\n### Step 1: Search by context\n\n```\nsearch_knowledge(\n  query: string,   // Derived from file path, task description, or component name\n  mode: \"hybrid\",  // Hybrid gives best results for context-based queries\n  limit: 10\n)\n```\n\n### Step 2: Find related notes (if you have a note ID or file path)\n\n```\nfind_related(\n  noteId?: string,    // ID of a relevant note found in step 1\n  filePath?: string,  // Current file path being worked on\n  limit?: number,     // Max results (default 10)\n  maxHops?: number    // Graph traversal depth (default 2)\n)\n```\n\n## How to Get Suggestions (CLI Alternative)\n\n```bash\nknowledgine suggest \"<context description>\"\nknowledgine suggest --file src/commands/setup.ts\n```\n\n## Extracting Context\n\nThe quality of suggestions depends on the context you provide. Extract signals from:\n\n| Signal | Example |\n|--------|---------|\n| Current file path | `src/commands/setup.ts` |\n| Component or class name | `SetupCommand`, `KnowledgeRepository` |\n| Task description | `\"add TOML config support to setup command\"` |\n| Feature area | `\"MCP configuration\", \"entity extraction\"` |\n| Error message | `\"TypeError: Cannot set properties of undefined\"` |\n\n## Step-by-Step Instructions\n\n1. **Extract context signals** from the current task (see context-patterns.md)\n2. **Build a query** \u2014 Combine the most specific signals into a search query\n3. **Call search_knowledge** with mode: \"hybrid\" and the derived query\n4. **Review results** \u2014 Read the top 3\u20135 most relevant notes\n5. **Traverse related notes** \u2014 Call find_related with a relevant noteId or the current filePath\n6. **Summarize findings** \u2014 Note any relevant warnings, patterns, or decisions found\n7. **Proceed informed** \u2014 Use the discovered context to guide your implementation\n\n## Best Practices\n\n- Run suggest once at session start for the primary area of work\n- Combine with knowledgine-recall for targeted queries as specific issues arise\n- Prioritize notes tagged with `bug-fix` or `troubleshooting` \u2014 they contain warnings\n- Notes tagged `design-decision` are especially valuable before making changes\n\n## Reference Files\n\n- See `context-patterns.md` for how to extract effective context from your current work\n";
+//# sourceMappingURL=skill-md.d.ts.map

package/dist/templates/skills/knowledgine-suggest/skill-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md.d.ts","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-suggest/skill-md.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ,onHA4FpB,CAAC"}

package/dist/templates/skills/knowledgine-suggest/skill-md.js

@@ -0,0 +1,94 @@
+export const SKILL_MD = `---
+name: knowledgine-suggest
+description: >
+  Get contextual knowledge suggestions based on the current work context — the file
+  being edited, the task being performed, or the error being investigated. Invoke at
+  the start of a work session, when opening a new file, or when beginning a feature.
+  Surfaces relevant past knowledge proactively without requiring a specific query.
+---
+# knowledgine-suggest
+
+## Purpose
+
+Surface relevant knowledge from the knowledge base based on contextual signals extracted
+from the current work, rather than a specific search query. Suggest combines search and
+graph traversal to bring forward knowledge you might not know to search for.
+
+## When to Use
+
+- **Starting a session** — Get context about the area you will work in
+- **Opening a new file** — Discover past knowledge about that component
+- **Beginning a feature** — Find related patterns and past decisions
+- **Before making changes** — Check for warnings or prior art on the topic
+- **Exploring an unfamiliar module** — Find related entities and notes
+
+## When NOT to Use
+
+- When you already have a specific query in mind (use knowledgine-recall instead)
+- When working on trivial mechanical tasks with no design ambiguity
+- After already calling suggest for the same file in the same session
+
+## How to Get Suggestions (MCP Tools)
+
+### Step 1: Search by context
+
+\`\`\`
+search_knowledge(
+  query: string,   // Derived from file path, task description, or component name
+  mode: "hybrid",  // Hybrid gives best results for context-based queries
+  limit: 10
+)
+\`\`\`
+
+### Step 2: Find related notes (if you have a note ID or file path)
+
+\`\`\`
+find_related(
+  noteId?: string,    // ID of a relevant note found in step 1
+  filePath?: string,  // Current file path being worked on
+  limit?: number,     // Max results (default 10)
+  maxHops?: number    // Graph traversal depth (default 2)
+)
+\`\`\`
+
+## How to Get Suggestions (CLI Alternative)
+
+\`\`\`bash
+knowledgine suggest "<context description>"
+knowledgine suggest --file src/commands/setup.ts
+\`\`\`
+
+## Extracting Context
+
+The quality of suggestions depends on the context you provide. Extract signals from:
+
+| Signal | Example |
+|--------|---------|
+| Current file path | \`src/commands/setup.ts\` |
+| Component or class name | \`SetupCommand\`, \`KnowledgeRepository\` |
+| Task description | \`"add TOML config support to setup command"\` |
+| Feature area | \`"MCP configuration", "entity extraction"\` |
+| Error message | \`"TypeError: Cannot set properties of undefined"\` |
+
+## Step-by-Step Instructions
+
+1. **Extract context signals** from the current task (see context-patterns.md)
+2. **Build a query** — Combine the most specific signals into a search query
+3. **Call search_knowledge** with mode: "hybrid" and the derived query
+4. **Review results** — Read the top 3–5 most relevant notes
+5. **Traverse related notes** — Call find_related with a relevant noteId or the current filePath
+6. **Summarize findings** — Note any relevant warnings, patterns, or decisions found
+7. **Proceed informed** — Use the discovered context to guide your implementation
+
+## Best Practices
+
+- Run suggest once at session start for the primary area of work
+- Combine with knowledgine-recall for targeted queries as specific issues arise
+- Prioritize notes tagged with \`bug-fix\` or \`troubleshooting\` — they contain warnings
+- Notes tagged \`design-decision\` are especially valuable before making changes
+
+## Reference Files
+
+- See \`context-patterns.md\` for how to extract effective context from your current work
+`;
+//# sourceMappingURL=skill-md.js.map

package/dist/templates/skills/knowledgine-suggest/skill-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-md.js","sourceRoot":"","sources":["../../../../src/templates/skills/knowledgine-suggest/skill-md.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4FvB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledgine/cli",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,9 +25,9 @@
     "log-symbols": "^7.0.1",
     "ora": "^9.3.0",
     "smol-toml": "^1.6.1",
-    "@knowledgine/core": "0.6.1",
-    "@knowledgine/mcp-server": "0.6.1",
-    "@knowledgine/ingest": "0.6.1"
+    "@knowledgine/core": "0.6.3",
+    "@knowledgine/mcp-server": "0.6.3",
+    "@knowledgine/ingest": "0.6.3"
   },
   "files": [
     "dist",