@zabaca/lattice 0.2.0 → 0.3.1

package/README.md

@@ -1,88 +1,132 @@
 # @zabaca/lattice
 
-**Human-initiated, AI-powered knowledge graph for markdown documentation**
+**Build a knowledge base with Claude Code — using your existing subscription**
 
 [![npm version](https://img.shields.io/npm/v/@zabaca/lattice.svg)](https://www.npmjs.com/package/@zabaca/lattice)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+Lattice turns your markdown documentation into a searchable knowledge graph. Unlike other GraphRAG tools that require separate LLM APIs, **Lattice uses Claude Code for entity extraction** — so you're already paying for it.
+
+## The Workflow
+
+```bash
+/research "knowledge graphs"   # Find existing docs or create new research
+/graph-sync                    # Extract entities & sync (automatic)
+lattice search "your query"    # Semantic search your knowledge base
+```
+
+That's it. Two commands to build a knowledge base.
 
 ---
 
-## Features
+## Why Lattice?
 
-- **Knowledge Graph Sync** - Automatically sync entities and relationships from markdown frontmatter to a graph database
-- **Semantic Search** - AI-powered search using Voyage AI embeddings for intelligent document discovery
-- **Entity Extraction** - Define entities (concepts, technologies, patterns) directly in your documentation
-- **Relationship Mapping** - Model connections between entities with typed relationships (USES, IMPLEMENTS, DEPENDS_ON)
-- **FalkorDB Backend** - High-performance graph database built on Redis for fast queries
-- **Incremental Sync** - Smart change detection syncs only modified documents
-- **CLI Interface** - Simple commands for sync, search, validation, and migration
+| Feature | Lattice | Other GraphRAG Tools |
+|---------|---------|---------------------|
+| **LLM for extraction** | Your Claude Code subscription | Separate API key + costs |
+| **Setup time** | 5 minutes | 30+ minutes |
+| **Containers** | 1 (FalkorDB) | 2-3 (DB + vector + graph) |
+| **API keys needed** | 1 (Voyage AI for embeddings) | 2-3 (LLM + embedding + rerank) |
+| **Workflow** | `/research` → `/graph-sync` | Custom scripts |
 
 ---
 
-## Quick Start
+## Quick Start (5 Minutes)
+
+### What You Need
 
-### 1. Install Lattice
+- **Claude Code** (you probably already have it)
+- **Docker** (for FalkorDB)
+- **Voyage AI API key** ([get one here](https://www.voyageai.com/) - embeddings only, ~$0.01/1M tokens)
+
+### 1. Install & Start
 
 ```bash
-npm install -g @zabaca/lattice
+bun add -g @zabaca/lattice                    # Install CLI
+docker run -d -p 6379:6379 falkordb/falkordb  # Start database
+export VOYAGE_API_KEY=your-key-here           # Set API key
+lattice init --global                         # Install Claude Code commands
 ```
 
-Or with bun:
+### 2. Start Researching
 
 ```bash
-bun add -g @zabaca/lattice
+claude                        # Launch Claude Code
+/research "your topic"        # Find or create documentation
+/graph-sync                   # Build knowledge graph (automatic)
+lattice search "your query"   # Semantic search
 ```
 
-### 2. Start FalkorDB
+### That's It!
 
-Using Docker Compose:
+The `/research` command will:
+- Search your existing docs for related content
+- Ask if you need new research
+- Create organized documentation with AI assistance
 
-```bash
-# Create docker-compose.yaml (see Infrastructure section)
-docker-compose up -d
-```
+The `/graph-sync` command will:
+- Detect all new/changed documents
+- Extract entities using Claude Code (your subscription)
+- Sync to FalkorDB for semantic search
+
+---
 
-Or pull and run directly:
+## Using /research
+
+The `/research` command provides an AI-assisted research workflow.
+
+### Searching Existing Research
 
 ```bash
-docker run -d -p 6379:6379 falkordb/falkordb:latest
+/research "semantic search"
 ```
 
-### 3. Configure Environment
+Claude will:
+1. Search your docs using semantic similarity
+2. Read and summarize relevant findings
+3. Ask if existing research answers your question
 
-Create a `.env` file in your project root:
+### Creating New Research
 
 ```bash
-# FalkorDB Connection
-FALKORDB_HOST=localhost
-FALKORDB_PORT=6379
-FALKORDB_GRAPH_NAME=lattice
+/research "new topic to explore"
+```
 
-# Embedding Provider (Voyage AI)
-VOYAGE_API_KEY=your-voyage-api-key-here
-VOYAGE_MODEL=voyage-3
+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`
 
-# Logging
-LOG_LEVEL=info
-```
+### Batch Syncing
 
-### 4. Sync Your Documents
+`/graph-sync` doesn't need to run after each research session. It identifies all documents needing sync:
 
 ```bash
-# Sync all markdown files with frontmatter
-lattice sync
+# After multiple research sessions
+/graph-sync
 
-# Sync specific paths
-lattice sync ./docs ./notes
-
-# Check what would change without syncing
-lattice sync --dry-run
+# Shows: "4 documents need syncing"
+# Extracts entities and syncs all at once
 ```
 
 ---
 
-## CLI Commands
+## CLI Reference
+
+The Lattice CLI runs behind the scenes. You typically won't use it directly — the Claude Code slash commands handle everything.
+
+<details>
+<summary><b>CLI Commands (Advanced)</b></summary>
+
+### `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`
 
@@ -92,18 +136,14 @@ Synchronize documents to the knowledge graph.
 lattice sync [paths...]         # Sync specified paths or current directory
 lattice sync --force            # Force re-sync (rebuilds entire graph)
 lattice sync --dry-run          # Preview changes without applying
-lattice sync --verbose          # Show detailed output
-lattice sync --watch            # Watch for changes and auto-sync
-lattice sync --no-embeddings    # Skip embedding generation
 ```
 
 ### `lattice status`
 
-Show the current sync status and pending changes.
+Show documents that need syncing.
 
 ```bash
-lattice status                  # Show documents that need syncing
-lattice status --verbose        # Include detailed change information
+lattice status                  # Show new/changed documents
 ```
 
 ### `lattice search`
@@ -111,17 +151,7 @@ lattice status --verbose        # Include detailed change information
 Semantic search across the knowledge graph.
 
 ```bash
-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`
-
-Display graph statistics.
-
-```bash
-lattice stats                   # Show node/edge counts and graph metrics
+lattice search "query"          # Search all entity types
 ```
 
 ### `lattice validate`
@@ -139,9 +169,10 @@ Display the derived ontology from your documents.
 
 ```bash
 lattice ontology                # Show entity types and relationship types
-lattice ontology --format json  # Output as JSON
 ```
 
+</details>
+
 ---
 
 ## Configuration
@@ -150,75 +181,43 @@ lattice ontology --format json  # Output as JSON
 
 | Variable | Description | Default |
 |----------|-------------|---------|
+| `VOYAGE_API_KEY` | Voyage AI API key for embeddings | *required* |
 | `FALKORDB_HOST` | FalkorDB server hostname | `localhost` |
 | `FALKORDB_PORT` | FalkorDB server port | `6379` |
-| `FALKORDB_GRAPH_NAME` | Name of the graph database | `lattice` |
-| `VOYAGE_API_KEY` | Voyage AI API key for embeddings | *required* |
-| `VOYAGE_MODEL` | Voyage AI model to use | `voyage-3` |
-| `LOG_LEVEL` | Logging verbosity (debug, info, warn, error) | `info` |
 
-### Frontmatter Schema
+<details>
+<summary><b>How It Works (Technical Details)</b></summary>
 
-Lattice extracts knowledge from YAML frontmatter in your markdown files:
+### Entity Extraction
+
+When you run `/graph-sync`, Claude Code extracts entities from your documents and writes them to YAML frontmatter. The Lattice CLI then syncs this to FalkorDB.
 
 ```yaml
 ---
-title: Document Title
-description: Brief description of the document
-created: 2024-01-15
-updated: 2024-01-20
-
 entities:
   - name: React
     type: technology
     description: JavaScript library for building user interfaces
-  - name: Component Architecture
-    type: pattern
-    description: Modular UI building blocks
 
 relationships:
   - source: React
     target: Component Architecture
-    type: IMPLEMENTS
-  - source: React
-    target: Virtual DOM
-    type: USES
+    relation: REFERENCES
 ---
-
-# Document content here...
 ```
 
-### Entity Types
-
-Common entity types (you can define your own):
+You don't need to write this manually — Claude Code handles it automatically.
 
-- `concept` - Abstract ideas and principles
-- `technology` - Tools, frameworks, and libraries
-- `pattern` - Design patterns and architectural approaches
-- `service` - External services and APIs
-- `component` - System components and modules
-- `person` - People and contributors
-- `organization` - Companies and teams
-
-### Relationship Types
-
-Common relationship types:
-
-- `USES` - Entity A uses Entity B
-- `IMPLEMENTS` - Entity A implements Entity B
-- `DEPENDS_ON` - Entity A depends on Entity B
-- `EXTENDS` - Entity A extends Entity B
-- `CONTAINS` - Entity A contains Entity B
-- `RELATED_TO` - General relationship
-- `SUPERSEDES` - Entity A replaces Entity B
+</details>
 
 ---
 
 ## Infrastructure
 
-### Docker Compose
+<details>
+<summary><b>Docker Compose (Alternative Setup)</b></summary>
 
-Create `docker-compose.yaml`:
+If you prefer Docker Compose over a single `docker run` command:
 
 ```yaml
 version: '3.8'
@@ -226,44 +225,31 @@ version: '3.8'
 services:
   falkordb:
     image: falkordb/falkordb:latest
-    container_name: lattice-falkordb
     ports:
       - "6379:6379"
     volumes:
       - falkordb-data:/data
-    environment:
-      - FALKORDB_ARGS=--requirepass ""
     restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 3
 
 volumes:
   falkordb-data:
-    driver: local
 ```
 
-Start the database:
-
 ```bash
 docker-compose up -d
 ```
 
-### Kubernetes (k3s)
+</details>
+
+<details>
+<summary><b>Kubernetes (k3s)</b></summary>
 
 For production deployments, use the provided k3s manifests:
 
 ```bash
-# Create namespace
 kubectl apply -f infra/k3s/namespace.yaml
-
-# Deploy storage
 kubectl apply -f infra/k3s/pv.yaml
 kubectl apply -f infra/k3s/pvc.yaml
-
-# Deploy FalkorDB
 kubectl apply -f infra/k3s/deployment.yaml
 kubectl apply -f infra/k3s/service.yaml
 
@@ -274,9 +260,14 @@ kubectl apply -f infra/k3s/nodeport-service.yaml
 kubectl apply -f infra/k3s/ingress.yaml
 ```
 
+</details>
+
 ---
 
-## Development
+## Contributing
+
+<details>
+<summary><b>Development Setup</b></summary>
 
 ### Prerequisites
 
@@ -287,64 +278,25 @@ kubectl apply -f infra/k3s/ingress.yaml
 ### Setup
 
 ```bash
-# Clone the repository
 git clone https://github.com/Zabaca/lattice.git
 cd lattice
-
-# Install dependencies
 bun install
-
-# Copy environment configuration
 cp .env.example .env
-# Edit .env with your settings
-
-# Start FalkorDB
 docker-compose -f infra/docker-compose.yaml up -d
 ```
 
 ### Running Locally
 
 ```bash
-# Development mode
-bun run dev
-
-# Run CLI commands during development
-bun run lattice sync
-bun run lattice status
-
-# Run tests
-bun test
-
-# Build for production
-bun run build
-```
-
-### Project Structure
-
-```
-lattice/
-├── src/
-│   ├── commands/       # CLI command implementations
-│   ├── embedding/      # Voyage AI embedding service
-│   ├── graph/          # FalkorDB graph operations
-│   ├── query/          # Query builders and parsers
-│   ├── sync/           # Document sync logic
-│   ├── utils/          # Shared utilities
-│   ├── app.module.ts   # NestJS application module
-│   ├── cli.ts          # CLI entry point
-│   └── main.ts         # Main application entry
-├── infra/
-│   ├── docker-compose.yaml
-│   └── k3s/            # Kubernetes manifests
-├── examples/           # Usage examples
-└── dist/               # Build output
+bun run dev              # Development mode
+bun test                 # Run tests
+bun run build            # Build for production
 ```
 
----
-
-## API Usage
+</details>
 
-Lattice can also be used programmatically:
+<details>
+<summary><b>Programmatic API</b></summary>
 
 ```typescript
 import { NestFactory } from '@nestjs/core';
@@ -352,16 +304,11 @@ import { AppModule } from '@zabaca/lattice';
 
 async function main() {
   const app = await NestFactory.createApplicationContext(AppModule);
-
-  // Get services
   const syncService = app.get(SyncService);
-  const graphService = app.get(GraphService);
 
-  // Sync documents
   const result = await syncService.sync({
     paths: ['./docs'],
-    force: false,
-    dryRun: false
+    force: false
   });
 
   console.log(`Synced ${result.added} new documents`);
@@ -370,18 +317,10 @@ async function main() {
 }
 ```
 
----
-
-## Contributing
+</details>
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
 ---
 
 ## License
@@ -390,8 +329,4 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
-## Acknowledgments
-
-- [FalkorDB](https://www.falkordb.com/) - High-performance graph database
-- [Voyage AI](https://www.voyageai.com/) - State-of-the-art embeddings
-- [NestJS](https://nestjs.com/) - Progressive Node.js framework
+Built with [FalkorDB](https://www.falkordb.com/), [Voyage AI](https://www.voyageai.com/), and [Claude Code](https://claude.ai/code)

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

@@ -257,7 +257,7 @@ class GraphService {
       this.logger.log(`Created vector index on ${label}.${property} with ${dimensions} dimensions`);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      if (!errorMessage.includes("already exists")) {
+      if (!errorMessage.includes("already indexed")) {
         this.logger.error(`Failed to create vector index: ${errorMessage}`);
         throw error;
       }
@@ -339,10 +339,10 @@ class GraphService {
     return String(value);
   }
   parseStats(result) {
-    if (!Array.isArray(result) || result.length < 2) {
+    if (!Array.isArray(result) || result.length < 3) {
       return;
     }
-    const statsStr = result[1];
+    const statsStr = result[2];
     if (!statsStr || typeof statsStr !== "string") {
       return;
     }
@@ -2473,9 +2473,14 @@ Note: Semantic search requires embeddings to be generated first.`);
       const outgoing = [];
       results.forEach((row) => {
         const [source, rel, target] = row;
-        const sourceName = source.properties?.name || "unknown";
-        const targetName = target.properties?.name || "unknown";
-        const relType = rel.type || "UNKNOWN";
+        const sourceObj = Object.fromEntries(source);
+        const targetObj = Object.fromEntries(target);
+        const relObj = Object.fromEntries(rel);
+        const sourceProps = Object.fromEntries(sourceObj.properties || []);
+        const targetProps = Object.fromEntries(targetObj.properties || []);
+        const sourceName = sourceProps.name || "unknown";
+        const targetName = targetProps.name || "unknown";
+        const relType = relObj.type || "UNKNOWN";
         if (sourceName === name) {
           outgoing.push(`  -[${relType}]-> ${targetName}`);
         } else {
@@ -2666,8 +2671,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.2.0",
+  "version": "0.3.1",
   "description": "Human-initiated, AI-powered knowledge graph for markdown documentation",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "commands",
     "README.md"
   ],
   "scripts": {