@zabaca/lattice 0.1.2 → 0.3.0

package/README.md

@@ -67,23 +67,98 @@ VOYAGE_MODEL=voyage-3
 LOG_LEVEL=info
 ```
 
-### 4. Sync Your Documents
+### 4. Initialize Claude Code Integration
+
+Install Lattice slash commands for Claude Code:
+
+```bash
+lattice init              # For this project only
+# or
+lattice init --global     # For all projects (~/.claude/commands/)
+```
+
+### 5. Launch Claude Code
+
+```bash
+claude
+```
+
+### 6. Research a Topic
+
+Use the `/research` command to search existing knowledge or create new documentation:
 
 ```bash
-# Sync all markdown files with frontmatter
-lattice sync
+/research "knowledge graphs"
+```
+
+This will:
+- Search your existing docs for related content
+- Present findings and ask if you need new research
+- Create organized documentation if requested
+
+### 7. Sync & Search
 
-# Sync specific paths
-lattice sync ./docs ./notes
+After creating or updating documents, sync to the graph and search:
 
-# Check what would change without syncing
-lattice sync --dry-run
+```bash
+/graph-sync                    # Extract entities and sync
+lattice search "your query"    # Semantic search
+```
+
+---
+
+## Using /research
+
+The `/research` command provides an AI-assisted research workflow.
+
+### Searching Existing Research
+
+```bash
+/research "semantic search"
+```
+
+Claude will:
+1. Search your docs using semantic similarity
+2. Read and summarize relevant findings
+3. Ask if existing research answers your question
+
+### Creating New Research
+
+```bash
+/research "new topic to explore"
+```
+
+If no existing docs match, Claude will:
+1. Perform web research
+2. Create a new topic directory (`docs/new-topic/`)
+3. Generate README.md index and research document
+4. Remind you to run `/graph-sync`
+
+### Batch Syncing
+
+`/graph-sync` doesn't need to run after each research session. It identifies all documents needing sync:
+
+```bash
+# After multiple research sessions
+/graph-sync
+
+# Shows: "4 documents need syncing"
+# Extracts entities and syncs all at once
 ```
 
 ---
 
 ## CLI Commands
 
+### `lattice init`
+
+Install Claude Code slash commands for Lattice.
+
+```bash
+lattice init              # Install to .claude/commands/ (current project)
+lattice init --global     # Install to ~/.claude/commands/ (all projects)
+```
+
 ### `lattice sync`
 
 Synchronize documents to the knowledge graph.
@@ -108,13 +183,12 @@ lattice status --verbose        # Include detailed change information
 
 ### `lattice search`
 
-Search the knowledge graph.
+Semantic search across the knowledge graph.
 
 ```bash
-lattice search --semantic "query"    # Semantic search using embeddings
-lattice search --keyword "term"      # Keyword-based search
-lattice search --type concept        # Filter by entity type
-lattice search --limit 10            # Limit results
+lattice search "query"                    # Search all entity types
+lattice search --label Technology "query" # Filter by entity label
+lattice search --limit 10 "query"         # Limit results (default: 20)
 ```
 
 ### `lattice stats`

package/commands/entity-extract.md

@@ -0,0 +1,163 @@
+---
+description: Extract entities from existing document and add to frontmatter
+argument-hint: file-path
+model: haiku
+---
+
+Extract entities and relationships from the markdown file "$ARGUMENTS" and update its frontmatter.
+
+## IMPORTANT: Always Re-Extract
+
+Even if the document already has frontmatter with entities:
+- **RE-READ** the entire document content
+- **RE-EXTRACT** entities based on CURRENT content
+- **REPLACE** existing entities with fresh extraction
+- **DO NOT skip** because "entities already exist"
+
+The goal is to ensure entities reflect the document's CURRENT state, not preserve stale metadata from previous extractions.
+
+## Process
+
+1. **Verify file exists**:
+   - Check if "$ARGUMENTS" exists
+   - If not, inform user and suggest the correct path
+   - Verify it's a markdown file
+
+2. **Read and analyze the document**:
+   - Read the full content of the file
+   - Check for existing frontmatter
+   - Analyze document context and purpose
+
+3. **Extract entities** by identifying:
+   - **Technologies**: Languages, frameworks, databases, libraries, tools mentioned
+   - **Concepts**: Patterns, methodologies, theories, architectural approaches
+   - **Tools & Services**: Software, platforms, applications referenced
+   - **Processes**: Workflows, procedures, methodologies described
+   - **Organizations**: Companies, teams, projects mentioned
+
+   Guidelines:
+   - Focus on 3-10 most significant entities for the document
+   - Use specific names (e.g., "PostgreSQL" not "database")
+   - Prefer proper nouns and technical terms
+   - Entities should be directly relevant to the document's focus
+
+4. **Generate document summary**:
+   - Create a 2-3 sentence summary (50-100 words) that captures:
+     - The document's main purpose/topic
+     - Key technologies or concepts covered
+     - Primary conclusions or recommendations (if any)
+
+   Summary guidelines:
+   - Write in third person
+   - Include key terms that enable semantic search
+   - Focus on what the document IS ABOUT, not just what it contains
+   - Make it suitable for embedding generation
+
+   Example:
+   ```yaml
+   summary: >
+     Research on integrating multiple messaging platforms (Slack, Teams, Discord)
+     into a unified API. Covers platform API comparisons, recommended tech stack
+     (NestJS, PostgreSQL, Redis), and a phased implementation approach for
+     bi-directional message synchronization.
+   ```
+
+5. **Extract relationships** between entities:
+   - **REFERENCES**: This entity references/relates to another entity
+
+   Use `source: this` when the document itself references an entity.
+   Use entity names as source/target when entities reference each other.
+
+6. **Determine entity types** (choose most appropriate):
+   - `Topic`: Research domains (usually auto-derived from directory)
+   - `Technology`: Programming languages, frameworks, databases
+   - `Concept`: Patterns, theories, methodologies
+   - `Tool`: Software, services, platforms
+   - `Process`: Workflows, procedures, methodologies
+   - `Person`: People
+   - `Organization`: Companies, teams, projects
+
+7. **Update frontmatter**:
+   - If frontmatter exists: **REPLACE** entities and relationships with fresh extraction
+   - If no frontmatter: Create new frontmatter block
+   - Preserve existing fields like `created`, `status`, `topic` (but update `updated` date)
+   - **Replace** the `summary`, `entities` and `relationships` sections entirely
+   - If no topic field exists, derive it from the directory name
+     (e.g., `docs/claude-code/file.md` -> `topic: claude-code`)
+
+   Frontmatter template:
+   ```yaml
+   ---
+   created: YYYY-MM-DD
+   updated: YYYY-MM-DD
+   status: complete|ongoing|draft
+   topic: auto-derived-from-directory
+   summary: >
+     2-3 sentence summary capturing the document's purpose, key topics,
+     and conclusions. Written in third person with key terms for semantic search.
+   entities:
+     - name: EntityName
+       type: Topic|Technology|Concept|Tool|Process|Person|Organization
+       description: Brief description of entity and its role in this document
+     - name: AnotherEntity
+       type: Concept
+       description: Another entity description
+   relationships:
+     - source: this
+       relation: REFERENCES
+       target: MainTopic
+     - source: EntityA
+       relation: REFERENCES
+       target: EntityB
+   graph:
+     domain: detected-domain
+   ---
+   ```
+
+8. **Entity naming consistency**:
+   - Check if similar entities exist in other documents
+   - Use exact same names when referring to same entities
+   - Be specific: "React" not "React library"
+   - Use canonical names (e.g., "TypeScript" not "TS")
+
+9. **Relationship guidelines**:
+   - Start with "source: this" for primary entity the document covers
+   - Include 3-7 key relationships
+   - Relationships should help build knowledge graph connections
+   - Avoid redundant relationships
+
+10. **Validate and auto-fix** (retry loop):
+    After saving, run validation:
+
+    ```bash
+    lattice validate 2>&1 | grep -A10 "$ARGUMENTS"
+    ```
+
+    **If validation reports errors for this file:**
+    1. Parse the error message to identify the issue
+    2. Fix the frontmatter:
+       - **Invalid entity type** (e.g., "Platform", "Feature"): Change to valid type
+       - **Invalid relation** (e.g., "AFFECTS", "ENABLES"): Change to valid relation
+       - **String instead of object**: Reformat to proper object structure
+    3. Save the fixed frontmatter
+    4. Re-run validation
+    5. Repeat until validation passes (max 3 attempts)
+
+    **Valid entity types:** `Topic`, `Technology`, `Concept`, `Tool`, `Process`, `Person`, `Organization`, `Document`
+
+    **Valid relations:** `REFERENCES`
+
+11. **Confirmation**:
+    - Show the file path
+    - Show the generated summary
+    - List extracted entities with types
+    - List extracted relationships
+    - Confirm validation passed (or show fixes made)
+
+## Important Notes
+
+- **Preserve existing content**: Do not modify the markdown content itself, only the frontmatter
+- **YAML validity**: Ensure all YAML is properly formatted
+- **Replace strategy**: Always replace entities/relationships with fresh extraction (don't merge with old)
+- **Be selective**: Focus on entities that would be valuable for knowledge graph connections
+- **Descriptions**: Write descriptions from the perspective of how the entity is used/discussed in THIS document

package/commands/graph-sync.md

@@ -0,0 +1,117 @@
+---
+description: Extract entities from modified docs and sync to graph
+model: sonnet
+---
+
+Identify modified documents, extract entities from them, and sync to the knowledge graph.
+
+## Process
+
+### Step 1: Check What Needs Syncing
+
+Run the status command to identify modified documents:
+
+```bash
+lattice status
+```
+
+This will show:
+- **New** documents not yet in the graph
+- **Updated** documents that have changed since last sync
+
+If no documents need syncing, report that and exit.
+
+### Step 2: Run Entity Extraction (Parallel Execution)
+
+For each new or updated document identified:
+
+1. Use the **Task subagent pattern** with Haiku model for parallel execution
+2. Launch multiple Task agents simultaneously (one per document)
+3. Each agent should:
+   - Invoke `/entity-extract <path>`
+   - Follow expanded instructions
+   - Extract entities and update frontmatter
+   - Report completion
+
+**Example Task agent invocation:**
+```
+Task(
+  subagent_type="general-purpose",
+  model="haiku",
+  prompt="Use /entity-extract docs/topic/document.md to extract entities. Follow all instructions and report completion."
+)
+```
+
+**For multiple documents, launch agents in parallel:**
+```
+// In a single message, launch multiple Task tool calls:
+Task(subagent_type="general-purpose", model="haiku", prompt="/entity-extract docs/topic-a/README.md ...")
+Task(subagent_type="general-purpose", model="haiku", prompt="/entity-extract docs/topic-b/notes.md ...")
+Task(subagent_type="general-purpose", model="haiku", prompt="/entity-extract docs/topic-c/README.md ...")
+```
+
+This is much faster than sequential execution for multiple documents.
+
+### Step 3: Sync to Graph
+
+After all entity extractions are complete:
+
+```bash
+lattice sync
+```
+
+**Note:** The sync command validates frontmatter schema and will fail with errors if:
+- Entities are malformed (strings instead of objects with `name`/`type`)
+- Relationships are malformed (strings instead of objects with `source`/`relation`/`target`)
+
+If sync fails due to schema errors, the entity extraction didn't follow the correct format.
+
+This will:
+- Update document nodes in FalkorDB
+- Generate embeddings for semantic search
+- Create entity relationships
+- Update the sync manifest
+
+### Step 4: Report Results
+
+Summarize what was processed:
+- Number of documents with entity extraction
+- Entities extracted per document
+- Graph sync statistics (added, updated, unchanged)
+- Any errors encountered
+
+## Example Output
+
+```
+## Entity Extraction
+
+Processed 3 documents:
+
+1. docs/american-holidays/README.md
+   - 4 entities extracted
+   - 3 relationships defined
+
+2. docs/american-holidays/thanksgiving-vs-christmas.md
+   - 8 entities extracted
+   - 5 relationships defined
+
+3. docs/bun-nestjs/notes.md
+   - 5 entities extracted
+   - 4 relationships defined
+
+## Graph Sync
+
+- Added: 2
+- Updated: 1
+- Unchanged: 126
+- Duration: 1.2s
+```
+
+## Important Notes
+
+- **Parallel execution** - Launch all entity extractions simultaneously for speed
+- Entity extraction runs per-document for quality
+- Graph sync is incremental (only processes changes)
+- Safe to run frequently - won't duplicate or corrupt data
+- If extraction fails on a doc, other agents continue - report all errors at end
+- **Batch syncing**: You don't need to run after each `/research` - run once after multiple sessions

package/commands/research.md

@@ -0,0 +1,183 @@
+---
+description: Research a topic - searches existing docs, asks before new research
+argument-hint: topic-query
+model: sonnet
+---
+
+Research the topic "$ARGUMENTS" by first checking existing documentation, then performing new research if needed.
+
+## Process
+
+### Step 1: Search Existing Research
+
+Run semantic search to find related documents:
+
+```bash
+lattice search "$ARGUMENTS" --limit 10
+```
+
+### Step 2: Review Search Results
+
+Review the top results from the semantic search:
+
+1. **Read top results** regardless of path - high similarity may indicate related content
+2. **Path/title matching** is a bonus signal, not a filter
+3. **Don't dismiss** high-similarity docs just because path doesn't match query
+4. Use judgment after reading - the doc content determines relevance, not the filename
+
+**Calibration notes:**
+- Exact topic matches often show 30-40% similarity
+- Unrelated docs can sometimes show 60%+ similarity
+- Read the actual content to determine true relevance
+
+For each promising result:
+- Read the document
+- Check if it answers the user's question
+- Note relevant sections
+
+### Step 3: Present Findings to User
+
+Summarize what you found in existing docs:
+- What topics are covered
+- Quote relevant sections if helpful
+- Identify gaps in existing research
+
+Ask the user: **"Does this existing research cover your question?"**
+
+### Step 4: Ask About New Research
+
+Use AskUserQuestion to ask:
+- **"Should I perform new research on this topic?"**
+- Options:
+  - Yes, research and create new docs
+  - Yes, research and update existing docs
+  - No, existing research is sufficient
+
+If user says **No** → Done, conversation complete.
+
+### Step 5: Perform Research (if requested)
+
+If user wants new research:
+1. Use WebSearch to find current information
+2. Gather and synthesize findings
+3. Focus on what's missing from existing docs
+
+### Step 6: Determine Topic and Filename
+
+**Identify the topic directory:**
+- Check if a relevant `docs/{topic-name}/` directory already exists
+- If not, derive a new topic name from the query (kebab-case)
+
+**Derive the research filename:**
+Auto-derive from the specific focus of the query:
+
+| Query | Topic Dir | Research File |
+|-------|-----------|---------------|
+| "tesla model s value retention" | `tesla-model-s/` | `value-retention.md` |
+| "bun vs node performance" | `bun-nodejs/` | `performance-comparison.md` |
+| "graphql authentication patterns" | `graphql/` | `authentication-patterns.md` |
+
+**Filename guidelines:**
+- Use kebab-case
+- Be descriptive of the specific research focus
+- Avoid generic names like `notes.md` or `research.md`
+- Keep it concise (2-4 words)
+
+### Step 7: Create/Update Files
+
+#### For NEW Topics (directory doesn't exist)
+
+Create TWO files:
+
+**1. `docs/{topic-name}/README.md`** (index):
+```markdown
+---
+created: [TODAY'S DATE]
+updated: [TODAY'S DATE]
+status: active
+topic: {topic-name}
+summary: >
+  Brief description of the topic area for semantic search.
+---
+
+# {Topic Title}
+
+Brief description of what this topic covers.
+
+## Documents
+
+| Document | Description |
+|----------|-------------|
+| [{Research Title}](./{research-filename}.md) | Brief description |
+
+## Related Research
+
+- [Related Topic](../related-topic/)
+```
+
+**2. `docs/{topic-name}/{research-filename}.md`** (content):
+```markdown
+---
+created: [TODAY'S DATE]
+updated: [TODAY'S DATE]
+status: complete
+topic: {topic-name}
+summary: >
+  Detailed summary of this specific research for semantic search.
+---
+
+# {Research Title}
+
+## Purpose
+
+What this research addresses.
+
+## Key Findings
+
+- Finding 1
+- Finding 2
+
+## [Content sections as needed...]
+
+## Sources
+
+1. [Source](URL)
+```
+
+#### For EXISTING Topics (directory exists)
+
+**1. Create** `docs/{topic-name}/{research-filename}.md` with content template above
+
+**2. Update** `docs/{topic-name}/README.md`:
+- Add new row to the Documents table
+- Update the `updated` date in frontmatter
+
+### Step 8: Confirmation
+
+After creating files, confirm:
+- Topic directory path
+- README.md created/updated
+- Research file created with name
+- Remind user to run `/graph-sync` to extract entities
+
+## Important Notes
+
+- **Do NOT** auto-run entity extraction - use `/graph-sync` separately
+- **Always create README.md** for new topics (lightweight index)
+- **Always create separate research file** (never put research content in README)
+- Use kebab-case for all directory and file names
+- Include today's date in YYYY-MM-DD format
+- Always cite sources with URLs
+- Cross-link to related research topics when relevant
+
+## File Structure Standard
+
+```
+docs/{topic-name}/
+├── README.md              # Index: links to docs, brief overview
+├── {research-1}.md        # Specific research
+├── {research-2}.md        # Additional research
+└── {research-n}.md        # Expandable as needed
+```
+
+This structure allows topics to grow organically while keeping README as a clean navigation index.

package/dist/cli.js

@@ -2385,98 +2385,65 @@ Relationship Types (${stats.relationshipTypes.length}):`);
       process.exit(1);
     }
   });
-  program.command("search").description("Search for nodes in the graph or perform semantic search").option("-l, --label <label>", "Filter by node label").option("-n, --name <name>", "Filter by name (substring match)").option("-s, --semantic <query>", "Perform semantic/vector search on documents").option("--limit <n>", "Limit results", "20").action(async (options) => {
+  program.command("search <query>").description("Semantic search across the knowledge graph").option("-l, --label <label>", "Filter by entity label (e.g., Technology, Concept, Document)").option("--limit <n>", "Limit results", "20").action(async (query, options) => {
     let app;
     try {
       app = await NestFactory3.createApplicationContext(AppModule, {
         logger: ["error"]
       });
       const graph = app.get(GraphService);
-      if (options.semantic) {
-        const embedding = app.get(EmbeddingService);
-        const limit2 = Math.min(parseInt(options.limit, 10), 100);
-        try {
-          const queryEmbedding = await embedding.generateEmbedding(options.semantic);
-          const results2 = await graph.vectorSearchAll(queryEmbedding, limit2);
-          console.log(`
-=== Semantic Search Results for "${options.semantic}" ===
-`);
-          if (results2.length === 0) {
-            console.log(`No results found with semantic search.
-`);
-            await app.close();
-            process.exit(0);
-          }
-          results2.forEach((result2, idx) => {
-            console.log(`${idx + 1}. [${result2.label}] ${result2.name}`);
-            if (result2.title) {
-              console.log(`   Title: ${result2.title}`);
-            }
-            if (result2.description && result2.label !== "Document") {
-              const desc = result2.description.length > 80 ? result2.description.slice(0, 80) + "..." : result2.description;
-              console.log(`   ${desc}`);
-            }
-            console.log(`   Similarity: ${(result2.score * 100).toFixed(2)}%`);
-          });
-          console.log();
-          await app.close();
-          process.exit(0);
-        } catch (semanticError) {
-          const errorMsg = semanticError instanceof Error ? semanticError.message : String(semanticError);
-          console.error("Semantic search error:", errorMsg);
-          if (errorMsg.includes("no embeddings") || errorMsg.includes("vector")) {
-            console.log(`
-Note: Semantic search requires embeddings to be generated first.`);
-            console.log(`Run 'lattice sync' to generate embeddings for documents.
-`);
-          }
-          await app.close();
-          process.exit(1);
-        }
-      }
-      let cypher;
+      const embedding = app.get(EmbeddingService);
       const limit = Math.min(parseInt(options.limit, 10), 100);
-      if (options.label && options.name) {
-        const escapedLabel = options.label.replace(/`/g, "\\`");
-        const escapedName = options.name.replace(/'/g, "\\'");
-        cypher = `MATCH (n:\`${escapedLabel}\`) WHERE n.name CONTAINS '${escapedName}' RETURN n LIMIT ${limit}`;
-      } else if (options.label) {
-        const escapedLabel = options.label.replace(/`/g, "\\`");
-        cypher = `MATCH (n:\`${escapedLabel}\`) RETURN n LIMIT ${limit}`;
-      } else if (options.name) {
-        const escapedName = options.name.replace(/'/g, "\\'");
-        cypher = `MATCH (n) WHERE n.name CONTAINS '${escapedName}' RETURN n LIMIT ${limit}`;
+      const queryEmbedding = await embedding.generateEmbedding(query);
+      let results;
+      if (options.label) {
+        const labelResults = await graph.vectorSearch(options.label, queryEmbedding, limit);
+        results = labelResults.map((r) => ({
+          name: r.name,
+          label: options.label,
+          title: r.title,
+          score: r.score
+        }));
       } else {
-        cypher = `MATCH (n) RETURN n LIMIT ${limit}`;
+        results = await graph.vectorSearchAll(queryEmbedding, limit);
       }
-      const result = await graph.query(cypher);
-      const results = result.resultSet || [];
+      const labelSuffix = options.label ? ` (${options.label})` : "";
       console.log(`
-=== Search Results (${results.length} nodes) ===
+=== Semantic Search Results for "${query}"${labelSuffix} ===
 `);
       if (results.length === 0) {
-        console.log(`No nodes found matching criteria.
+        console.log(`No results found.
+`);
+        if (options.label) {
+          console.log(`Tip: Try without --label to search all entity types.
 `);
+        }
         await app.close();
         process.exit(0);
       }
-      results.forEach((row) => {
-        const node = row[0];
-        const labels = (node.labels || []).join(", ");
-        const name = node.properties?.name || "unnamed";
-        console.log(`[${labels}] ${name}`);
-        if (node.properties?.description) {
-          console.log(`  Description: ${node.properties.description}`);
+      results.forEach((result, idx) => {
+        console.log(`${idx + 1}. [${result.label}] ${result.name}`);
+        if (result.title) {
+          console.log(`   Title: ${result.title}`);
         }
-        if (node.properties?.importance) {
-          console.log(`  Importance: ${node.properties.importance}`);
+        if (result.description && result.label !== "Document") {
+          const desc = result.description.length > 80 ? result.description.slice(0, 80) + "..." : result.description;
+          console.log(`   ${desc}`);
         }
+        console.log(`   Similarity: ${(result.score * 100).toFixed(2)}%`);
       });
       console.log();
       await app.close();
       process.exit(0);
     } catch (error) {
-      console.error("Error:", error instanceof Error ? error.message : String(error));
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      console.error("Error:", errorMsg);
+      if (errorMsg.includes("no embeddings") || errorMsg.includes("vector")) {
+        console.log(`
+Note: Semantic search requires embeddings to be generated first.`);
+        console.log(`Run 'lattice sync' to generate embeddings for documents.
+`);
+      }
       if (app)
         await app.close();
       process.exit(1);
@@ -2699,8 +2666,88 @@ function registerOntologyCommand(program) {
     }
   });
 }
+// src/commands/init.command.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path.dirname(__filename2);
+var COMMANDS = ["research.md", "graph-sync.md", "entity-extract.md"];
+function registerInitCommand(program) {
+  program.command("init").description("Install Claude Code slash commands for Lattice").option("-g, --global", "Install to ~/.claude/commands/ (available in all projects)").action(async (options) => {
+    try {
+      const targetDir = options.global ? path.join(homedir(), ".claude", "commands") : path.join(process.cwd(), ".claude", "commands");
+      let commandsSourceDir = path.resolve(__dirname2, "..", "commands");
+      try {
+        await fs.access(commandsSourceDir);
+      } catch {
+        commandsSourceDir = path.resolve(__dirname2, "..", "..", "commands");
+      }
+      try {
+        await fs.access(commandsSourceDir);
+      } catch {
+        console.error("Error: Commands source directory not found at", commandsSourceDir);
+        console.error("This may indicate a corrupted installation. Try reinstalling @zabaca/lattice.");
+        process.exit(1);
+      }
+      await fs.mkdir(targetDir, { recursive: true });
+      let copied = 0;
+      let skipped = 0;
+      const installed = [];
+      for (const file of COMMANDS) {
+        const sourcePath = path.join(commandsSourceDir, file);
+        const targetPath = path.join(targetDir, file);
+        try {
+          await fs.access(sourcePath);
+          try {
+            await fs.access(targetPath);
+            const sourceContent = await fs.readFile(sourcePath, "utf-8");
+            const targetContent = await fs.readFile(targetPath, "utf-8");
+            if (sourceContent === targetContent) {
+              skipped++;
+              continue;
+            }
+          } catch {}
+          await fs.copyFile(sourcePath, targetPath);
+          installed.push(file);
+          copied++;
+        } catch (err) {
+          console.error(`Warning: Could not copy ${file}:`, err instanceof Error ? err.message : String(err));
+        }
+      }
+      console.log();
+      console.log(`\u2705 Lattice commands installed to ${targetDir}`);
+      console.log();
+      if (copied > 0) {
+        console.log(`Installed ${copied} command(s):`);
+        installed.forEach((f) => {
+          const name = f.replace(".md", "");
+          console.log(`  - /${name}`);
+        });
+      }
+      if (skipped > 0) {
+        console.log(`Skipped ${skipped} unchanged command(s)`);
+      }
+      console.log();
+      console.log("Available commands in Claude Code:");
+      console.log("  /research <topic>    - AI-assisted research workflow");
+      console.log("  /graph-sync          - Extract entities and sync to graph");
+      console.log("  /entity-extract      - Extract entities from a single document");
+      console.log();
+      if (!options.global) {
+        console.log("\uD83D\uDCA1 Tip: Use 'lattice init --global' to install for all projects");
+      }
+      process.exit(0);
+    } catch (error) {
+      console.error("Error:", error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  });
+}
 // src/main.ts
-program.name("lattice").description("Human-initiated, AI-powered knowledge graph for markdown documentation").version("0.1.0");
+program.name("lattice").description("Human-initiated, AI-powered knowledge graph for markdown documentation").version("0.3.0");
+registerInitCommand(program);
 registerSyncCommand(program);
 registerStatusCommand(program);
 registerQueryCommands(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zabaca/lattice",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Human-initiated, AI-powered knowledge graph for markdown documentation",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "commands",
     "README.md"
   ],
   "scripts": {