@knowledgine/cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,140 @@
+export const REFERENCES = {
+    "debrief-template.md": `# Debrief Template
+
+Fill in the following template when creating a session debrief capture. Omit sections
+that are not applicable.
+
+---
+
+\`\`\`markdown
+## Session Debrief: <YYYY-MM-DD> — <Main Topic>
+
+### Overview
+<1–2 sentence summary of the session goal and outcome>
+
+### Problems Solved
+<!-- List each significant problem with root cause and solution -->
+- **<Problem title>**
+  - Root cause: <what caused it>
+  - Solution: <what was done>
+  - Files changed: <list of files>
+
+### Decisions Made
+<!-- List architectural or implementation decisions with reasoning -->
+- **<Decision title>**
+  - Options considered: <A, B, C>
+  - Chosen: <option>
+  - Reason: <why>
+
+### Patterns Found
+<!-- Reusable insights or patterns discovered this session -->
+- **<Pattern name>**: <brief description and when to apply>
+
+### Code Changed
+<!-- Summary of what was changed and why -->
+| File | Change | Purpose |
+|------|--------|---------|
+| <path> | <created/modified/deleted> | <why> |
+
+### Open Questions
+<!-- Unresolved items for future sessions -->
+- <Question or uncertainty>
+- <What needs investigation or decision>
+
+### References
+<!-- External sources consulted this session -->
+- <URL or document title>
+\`\`\`
+
+---
+
+## Usage Notes
+
+**Title format**: "Session Debrief: 2026-03-15 — Entity extraction pipeline fix"
+
+**Tags**: Always include \`debrief\`. Add the primary topic area:
+- \`debrief\`, \`bug-fix\` — session primarily fixed bugs
+- \`debrief\`, \`design-decision\` — session was design-focused
+- \`debrief\`, \`refactoring\` — session was refactoring-focused
+- \`debrief\`, \`feature\` — session added new functionality
+
+**Minimum viable debrief**: If time is short, at minimum capture:
+1. What was done (one sentence per task)
+2. Key decisions or gotchas
+3. Open questions
+
+**Separate captures**: For major bugs or decisions, create individual captures first
+(using knowledgine-capture), then reference them in the debrief summary. This
+ensures the individual insights are searchable by type, not only through the debrief.
+`,
+    "example-output.md": `# Example Debrief Output
+
+A concrete example of a well-written session debrief.
+
+---
+
+**Title**: Session Debrief: 2026-03-15 — ESM import resolution and sqlite-vec fix
+
+**Tags**: \`debrief\`, \`bug-fix\`
+
+**Content**:
+\`\`\`markdown
+## Session Debrief: 2026-03-15 — ESM import resolution and sqlite-vec fix
+
+### Overview
+Fixed two build-time failures introduced by upgrading to Node.js 20: ESM import
+extensions were missing in CLI source files, and sqlite-vec native module needed
+recompilation for the new ABI.
+
+### Problems Solved
+
+- **Missing .js extensions in ESM imports**
+  - Root cause: TypeScript source used extensionless imports (e.g., \`import foo from "./foo"\`)
+    which works with CommonJS but fails in strict ESM mode (Node 20 + type: "module").
+  - Solution: Added .js extensions to all relative imports in packages/cli/src/
+    and packages/core/src/. Updated tsconfig to moduleResolution: "NodeNext".
+  - Files changed: ~40 files across cli and core packages
+
+- **sqlite-vec "invalid ELF header" on Node 20**
+  - Root cause: Native .node binary was compiled for Node 18 ABI (NODE_MODULE_VERSION 108).
+    Node 20 uses ABI 115.
+  - Solution: Ran \`npm rebuild\` to recompile sqlite-vec for Node 20. Added ABI version
+    check to CI cache key to prevent recurrence.
+  - Files changed: No source changes; CI workflow updated
+
+### Decisions Made
+
+- **Keep moduleResolution: NodeNext permanently**
+  - Options: Revert to CommonJS, or update to NodeNext
+  - Chosen: NodeNext. ESM is the direction Node.js is heading; reverting would
+    accumulate more migration debt. The .js extension requirement is a one-time cost.
+
+### Patterns Found
+
+- **npm rebuild after Node.js major upgrades**: Any project using native modules must
+  run \`npm rebuild\` after upgrading Node.js major version. Add this to upgrade
+  runbooks. See also: individual capture "sqlite-vec fails after Node.js upgrade".
+
+### Code Changed
+
+| File | Change | Purpose |
+|------|--------|---------|
+| packages/cli/src/**/*.ts | modified | Add .js to all relative imports |
+| packages/core/src/**/*.ts | modified | Add .js to all relative imports |
+| tsconfig.json | modified | moduleResolution: NodeNext |
+| .github/workflows/ci.yml | modified | Add NODE_ABI to cache key |
+
+### Open Questions
+
+- Is there a codemod or lint rule that enforces .js extensions? ESLint import plugin
+  might handle this — investigate for future use.
+- Should the knowledgine init command detect ABI mismatch proactively?
+
+### References
+
+- https://www.typescriptlang.org/docs/handbook/esm-node.html
+- https://nodejs.org/api/esm.html#mandatory-file-extensions
+\`\`\`
+`,
+};
+//# sourceMappingURL=references.js.map

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

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

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

@@ -0,0 +1,2 @@
+export declare const SKILL_MD = "---\nname: knowledgine-debrief\ndescription: >\n  Summarize and record all learnings from the current session at its end. Invoke when\n  the user signals the session is complete, after finishing a major task, or when asked\n  for a session review. Produces a structured knowledge capture covering problems solved,\n  decisions made, patterns found, and open questions.\n---\n# knowledgine-debrief\n\n## Purpose\n\nConsolidate all learnings from the session into the knowledge base before context is\nlost. A debrief transforms the raw events of a session \u2014 bugs fixed, decisions made,\ncode changed \u2014 into durable structured knowledge that future sessions can build on.\n\n## When to Use\n\n- **End of session** \u2014 User says \"done\", \"that's all\", \"let's wrap up\", or similar\n- **After completing a major task** \u2014 Significant feature, complex bug fix, or refactoring\n- **User requests a review** \u2014 \"What did we do today?\", \"Summarize the session\"\n- **Before switching contexts** \u2014 Moving to a completely different area of the codebase\n\n## When NOT to Use\n\n- Mid-session after every small change \u2014 save debrief for meaningful milestones\n- When nothing significant happened (trivial edits only)\n\n## How to Debrief (MCP Tool)\n\nUse `capture_knowledge` to save the session summary:\n\n```\ncapture_knowledge(\n  content: string,    // Full structured debrief using the template\n  title: string,      // \"Session Debrief: <date> \u2014 <main topic>\"\n  tags: string[],     // [\"debrief\", \"<primary-area>\", ...]\n  source?: string     // Optional: session identifier\n)\n```\n\n## Step-by-Step Instructions\n\n1. **Recall the session** \u2014 Review what was worked on (rely on your context window)\n2. **Identify key events** \u2014 Problems solved, decisions made, patterns found\n3. **Draft the debrief** \u2014 Use the structured template from debrief-template.md\n4. **Capture each major learning individually** \u2014 If a bug fix or decision is significant\n   enough to stand alone, capture it separately with the appropriate skill first\n5. **Capture the session summary** \u2014 Save the consolidated debrief note\n6. **Confirm completion** \u2014 Report to the user what was captured\n\n## Debrief Structure\n\nA good debrief contains:\n\n- **Problems Solved** \u2014 What broke and how it was fixed\n- **Decisions Made** \u2014 What was chosen and why\n- **Patterns Found** \u2014 Reusable insights discovered\n- **Code Changed** \u2014 Summary of files modified and purpose\n- **Open Questions** \u2014 Unresolved items for future sessions\n\n## Best Practices\n\n- Write for a future reader with no context from this session\n- Be specific about what changed, not just what was done\n- Open questions are as valuable as answers \u2014 document uncertainty\n- If the session was long, do individual captures for major events before the summary\n\n## Reference Files\n\n- See `debrief-template.md` for the structured template to fill in\n- See `example-output.md` for a concrete example of a well-written debrief\n";
+//# sourceMappingURL=skill-md.d.ts.map

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

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

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

@@ -0,0 +1,74 @@
+export const SKILL_MD = `---
+name: knowledgine-debrief
+description: >
+  Summarize and record all learnings from the current session at its end. Invoke when
+  the user signals the session is complete, after finishing a major task, or when asked
+  for a session review. Produces a structured knowledge capture covering problems solved,
+  decisions made, patterns found, and open questions.
+---
+# knowledgine-debrief
+
+## Purpose
+
+Consolidate all learnings from the session into the knowledge base before context is
+lost. A debrief transforms the raw events of a session — bugs fixed, decisions made,
+code changed — into durable structured knowledge that future sessions can build on.
+
+## When to Use
+
+- **End of session** — User says "done", "that's all", "let's wrap up", or similar
+- **After completing a major task** — Significant feature, complex bug fix, or refactoring
+- **User requests a review** — "What did we do today?", "Summarize the session"
+- **Before switching contexts** — Moving to a completely different area of the codebase
+
+## When NOT to Use
+
+- Mid-session after every small change — save debrief for meaningful milestones
+- When nothing significant happened (trivial edits only)
+
+## How to Debrief (MCP Tool)
+
+Use \`capture_knowledge\` to save the session summary:
+
+\`\`\`
+capture_knowledge(
+  content: string,    // Full structured debrief using the template
+  title: string,      // "Session Debrief: <date> — <main topic>"
+  tags: string[],     // ["debrief", "<primary-area>", ...]
+  source?: string     // Optional: session identifier
+)
+\`\`\`
+
+## Step-by-Step Instructions
+
+1. **Recall the session** — Review what was worked on (rely on your context window)
+2. **Identify key events** — Problems solved, decisions made, patterns found
+3. **Draft the debrief** — Use the structured template from debrief-template.md
+4. **Capture each major learning individually** — If a bug fix or decision is significant
+   enough to stand alone, capture it separately with the appropriate skill first
+5. **Capture the session summary** — Save the consolidated debrief note
+6. **Confirm completion** — Report to the user what was captured
+
+## Debrief Structure
+
+A good debrief contains:
+
+- **Problems Solved** — What broke and how it was fixed
+- **Decisions Made** — What was chosen and why
+- **Patterns Found** — Reusable insights discovered
+- **Code Changed** — Summary of files modified and purpose
+- **Open Questions** — Unresolved items for future sessions
+
+## Best Practices
+
+- Write for a future reader with no context from this session
+- Be specific about what changed, not just what was done
+- Open questions are as valuable as answers — document uncertainty
+- If the session was long, do individual captures for major events before the summary
+
+## Reference Files
+
+- See \`debrief-template.md\` for the structured template to fill in
+- See \`example-output.md\` for a concrete example of a well-written debrief
+`;
+//# sourceMappingURL=skill-md.js.map

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

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

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

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

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

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

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

@@ -0,0 +1,183 @@
+export const REFERENCES = {
+    "entity-types.md": `# Entity Types
+
+The entity types recognized and extracted by knowledgine from knowledge base content.
+
+---
+
+## Core Entity Types
+
+| Type | Description | Examples |
+|------|-------------|---------|
+| \`technology\` | Libraries, frameworks, tools, languages | \`SQLite\`, \`TypeScript\`, \`Node.js\`, \`Zod\` |
+| \`concept\` | Abstract ideas, patterns, architectural concepts | \`caching\`, \`ESM\`, \`FTS5\`, \`semantic search\` |
+| \`project\` | Projects, repositories, products | \`knowledgine\`, \`claude-code\` |
+| \`person\` | Authors, contributors, contacts | Team members, external contributors |
+| \`component\` | Code components, classes, modules | \`KnowledgeRepository\`, \`IngestEngine\` |
+| \`command\` | CLI commands or API operations | \`knowledgine init\`, \`capture_knowledge\` |
+| \`file\` | Source files and paths | \`packages/core/src/config/config-loader.ts\` |
+| \`error\` | Named error types or error messages | \`SQLITE_CONSTRAINT\`, \`ENOENT\` |
+
+---
+
+## Searching for Entities
+
+### By exact name
+\`\`\`
+search_entities(query: "SQLite")
+search_entities(query: "KnowledgeRepository")
+\`\`\`
+
+### By type + name
+\`\`\`
+search_entities(query: "technology sqlite")
+search_entities(query: "concept caching")
+\`\`\`
+
+### By partial name
+\`\`\`
+search_entities(query: "Knowledge")  // matches KnowledgeRepository, knowledgine, etc.
+\`\`\`
+
+---
+
+## Entity Extraction Quality
+
+Entities are extracted automatically from note content using NLP. The quality depends
+on the clarity of the notes. If you notice missing or incorrect entities, use
+\`knowledgine-feedback\` to report them.
+
+**Common extraction issues**:
+- Abbreviations (TS → TypeScript may not be linked)
+- Generic words that happen to be class names (Table, Manager)
+- Multi-word entities where only part is captured
+
+---
+
+## Using Entities for Exploration
+
+Entities serve as navigation hubs in the knowledge graph. A technology entity like
+\`SQLite\` connects to every note that mentions SQLite, allowing you to traverse from
+the entity to all related bug fixes, design decisions, and patterns.
+
+**Exploration pattern**:
+\`\`\`
+1. search_entities(query: "SQLite") → get entity ID
+2. get_entity_graph(entityId: "<id>") → see all connections
+3. find_related(noteId: "<connected note id>") → traverse outward
+\`\`\`
+`,
+    "graph-navigation.md": `# Graph Navigation
+
+How to traverse the knowledge graph effectively using \`get_entity_graph\` and
+\`find_related\`.
+
+---
+
+## Knowledge Graph Structure
+
+The knowledge graph has two node types:
+
+- **Notes** — Individual knowledge entries (bug fixes, decisions, patterns, etc.)
+- **Entities** — Named things extracted from notes (technologies, concepts, people)
+
+**Edge types**:
+- Note → Entity: "this note mentions this entity"
+- Entity → Note: "this entity appears in these notes"
+- Note → Note: "these notes share entities" (implicit through entity connections)
+
+---
+
+## get_entity_graph
+
+Returns the entity and all notes it appears in, plus related entities.
+
+\`\`\`
+get_entity_graph(entityId: "123")
+// Returns: { entity, notes: [...], relatedEntities: [...] }
+
+get_entity_graph(entityName: "SQLite")
+// Look up entity by name then return graph
+\`\`\`
+
+**Use this when you want to**:
+- See every note about a specific technology or concept
+- Discover which other entities co-appear with this entity
+- Get an overview before doing deeper traversal
+
+---
+
+## find_related
+
+Returns notes related to a starting point (note or file path) via shared entities.
+
+\`\`\`
+find_related(noteId: "abc123", limit: 10, maxHops: 2)
+find_related(filePath: "src/commands/setup.ts", limit: 10)
+\`\`\`
+
+**Parameters**:
+- \`noteId\` or \`filePath\`: Starting point for traversal
+- \`limit\`: Maximum notes to return
+- \`maxHops\`: How many edge-traversal steps to allow (1–3)
+
+### maxHops Guide
+
+| maxHops | Meaning | When to use |
+|---------|---------|-------------|
+| 1 | Only notes that share a direct entity with the starting note | Focused lookup |
+| 2 | Notes 2 hops away (share an entity with a 1-hop note) | Default, good balance |
+| 3 | Notes 3 hops away | Open-ended exploration, large graph |
+
+**Higher maxHops returns more results but with lower average relevance.** Start at 1
+or 2 and increase only if the results are too sparse.
+
+---
+
+## Navigation Patterns
+
+### Pattern 1: Technology Deep Dive
+
+\`\`\`
+// Understand everything in the knowledge base about TypeScript
+1. search_entities(query: "TypeScript") → { id: "42", name: "TypeScript" }
+2. get_entity_graph(entityId: "42")
+   → 15 notes mention TypeScript
+   → related entities: ESM, tsconfig, type-safety
+3. find_related(noteId: "<top note id>", maxHops: 2)
+   → Surface adjacent notes
+\`\`\`
+
+### Pattern 2: Component History
+
+\`\`\`
+// Understand the history of the setup command
+1. search_entities(query: "setupCommand") → entity
+2. get_entity_graph(entityId: "<id>") → notes about setupCommand
+3. Filter for design-decision and refactoring notes
+4. Read chronologically to understand evolution
+\`\`\`
+
+### Pattern 3: Cross-Area Connections
+
+\`\`\`
+// Find connections between two components
+1. get_entity_graph(entityName: "IngestEngine") → set A of notes + entities
+2. get_entity_graph(entityName: "KnowledgeRepository") → set B
+3. Inspect overlap in relatedEntities to find bridges
+\`\`\`
+
+---
+
+## Interpreting Results
+
+When \`get_entity_graph\` returns many notes, prioritize by tag:
+
+| Priority | Tags |
+|----------|------|
+| High | \`design-decision\`, \`bug-fix\`, \`troubleshooting\` |
+| Medium | \`pattern\`, \`refactoring\`, \`external-knowledge\` |
+| Lower | Untagged notes |
+`,
+};
+//# sourceMappingURL=references.js.map

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

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

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

@@ -0,0 +1,2 @@
+export declare const SKILL_MD = "---\nname: knowledgine-explain\ndescription: >\n  Explore entities, knowledge graph connections, and design history for unfamiliar\n  components. Invoke when exploring code you did not write, tracing the history of a\n  design decision, or understanding how a named entity (technology, library, project,\n  person) relates to other parts of the knowledge base.\n---\n# knowledgine-explain\n\n## Purpose\n\nTrace the knowledge graph to understand why things are the way they are. Explain uses\nentity search and graph traversal to surface the full context around a component or\nconcept \u2014 not just what exists, but how it connects to other parts of the system and\nwhat decisions shaped it.\n\n## When to Use\n\n- **Exploring unfamiliar code** \u2014 Who wrote what and why? What decisions shaped this?\n- **Understanding design rationale** \u2014 What alternatives were considered?\n- **Tracing knowledge provenance** \u2014 Where did this pattern or approach come from?\n- **Auditing a technology choice** \u2014 Why is this library used here?\n- **Understanding relationships** \u2014 How do components A and B relate?\n\n## When NOT to Use\n\n- When you just need to find a specific past solution (use knowledgine-recall instead)\n- When the entity does not exist in the knowledge base yet\n- For trivial well-known concepts with no project-specific context\n\n## How to Explain (MCP Tools)\n\n### Step 1: Search for entities\n\n```\nsearch_entities(\n  query: string,   // Entity name, technology, concept, or person\n  limit?: number   // Max results (default 10)\n)\n```\n\n### Step 2: Explore entity graph\n\n```\nget_entity_graph(\n  entityId?: string,    // ID from search_entities result\n  entityName?: string   // Or search by name directly\n)\n```\n\n### Step 3: Find related notes\n\n```\nfind_related(\n  noteId?: string,    // A relevant note ID found in earlier steps\n  filePath?: string,  // Or a relevant file path\n  limit?: number,\n  maxHops?: number    // 1\u20133, default 2\n)\n```\n\n## How to Explain (CLI Alternative)\n\n```bash\nknowledgine explain \"<entity name or concept>\"\n```\n\n## Step-by-Step Instructions\n\n1. **Identify the subject** \u2014 What entity, component, or concept do you want to understand?\n2. **Search for the entity** \u2014 Call `search_entities` with the subject name\n3. **Inspect the entity graph** \u2014 Call `get_entity_graph` with the entity ID\n4. **Traverse related notes** \u2014 Call `find_related` for notes that mention this entity\n5. **Synthesize findings** \u2014 Summarize what you learned about the entity's history and connections\n\n## Best Practices\n\n- Start with `search_entities` to discover the exact entity name as stored in the knowledge base\n- Use `get_entity_graph` to map the neighborhood before diving into individual notes\n- Increase `maxHops` gradually \u2014 start at 1, go to 2 or 3 if the immediate neighborhood is sparse\n- Look specifically for notes tagged `design-decision` \u2014 they explain the \"why\"\n\n## Reference Files\n\n- See `entity-types.md` for the entity taxonomy used in knowledgine\n- See `graph-navigation.md` for how to traverse the knowledge graph effectively\n";
+//# sourceMappingURL=skill-md.d.ts.map

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

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

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

@@ -0,0 +1,89 @@
+export const SKILL_MD = `---
+name: knowledgine-explain
+description: >
+  Explore entities, knowledge graph connections, and design history for unfamiliar
+  components. Invoke when exploring code you did not write, tracing the history of a
+  design decision, or understanding how a named entity (technology, library, project,
+  person) relates to other parts of the knowledge base.
+---
+# knowledgine-explain
+
+## Purpose
+
+Trace the knowledge graph to understand why things are the way they are. Explain uses
+entity search and graph traversal to surface the full context around a component or
+concept — not just what exists, but how it connects to other parts of the system and
+what decisions shaped it.
+
+## When to Use
+
+- **Exploring unfamiliar code** — Who wrote what and why? What decisions shaped this?
+- **Understanding design rationale** — What alternatives were considered?
+- **Tracing knowledge provenance** — Where did this pattern or approach come from?
+- **Auditing a technology choice** — Why is this library used here?
+- **Understanding relationships** — How do components A and B relate?
+
+## When NOT to Use
+
+- When you just need to find a specific past solution (use knowledgine-recall instead)
+- When the entity does not exist in the knowledge base yet
+- For trivial well-known concepts with no project-specific context
+
+## How to Explain (MCP Tools)
+
+### Step 1: Search for entities
+
+\`\`\`
+search_entities(
+  query: string,   // Entity name, technology, concept, or person
+  limit?: number   // Max results (default 10)
+)
+\`\`\`
+
+### Step 2: Explore entity graph
+
+\`\`\`
+get_entity_graph(
+  entityId?: string,    // ID from search_entities result
+  entityName?: string   // Or search by name directly
+)
+\`\`\`
+
+### Step 3: Find related notes
+
+\`\`\`
+find_related(
+  noteId?: string,    // A relevant note ID found in earlier steps
+  filePath?: string,  // Or a relevant file path
+  limit?: number,
+  maxHops?: number    // 1–3, default 2
+)
+\`\`\`
+
+## How to Explain (CLI Alternative)
+
+\`\`\`bash
+knowledgine explain "<entity name or concept>"
+\`\`\`
+
+## Step-by-Step Instructions
+
+1. **Identify the subject** — What entity, component, or concept do you want to understand?
+2. **Search for the entity** — Call \`search_entities\` with the subject name
+3. **Inspect the entity graph** — Call \`get_entity_graph\` with the entity ID
+4. **Traverse related notes** — Call \`find_related\` for notes that mention this entity
+5. **Synthesize findings** — Summarize what you learned about the entity's history and connections
+
+## Best Practices
+
+- Start with \`search_entities\` to discover the exact entity name as stored in the knowledge base
+- Use \`get_entity_graph\` to map the neighborhood before diving into individual notes
+- Increase \`maxHops\` gradually — start at 1, go to 2 or 3 if the immediate neighborhood is sparse
+- Look specifically for notes tagged \`design-decision\` — they explain the "why"
+
+## Reference Files
+
+- See \`entity-types.md\` for the entity taxonomy used in knowledgine
+- See \`graph-navigation.md\` for how to traverse the knowledge graph effectively
+`;
+//# sourceMappingURL=skill-md.js.map

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

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

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

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

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

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