@zabaca/lattice 1.0.1 → 1.0.3

package/commands/entity-extract.md

@@ -83,7 +83,7 @@ The goal is to ensure entities reflect the document's CURRENT state, not preserv
    - 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`)
+     (e.g., `~/.lattice/docs/claude-code/file.md` -> `topic: claude-code`)
 
    Frontmatter template:
    ```yaml

package/commands/graph-sync.md

@@ -3,7 +3,7 @@ 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.
+Identify modified documents in `~/.lattice/docs/`, extract entities from them, and sync to the knowledge graph.
 
 ## Process
 
@@ -38,16 +38,16 @@ For each new or updated document identified:
 Task(
   subagent_type="general-purpose",
   model="haiku",
-  prompt="Use /entity-extract docs/topic/document.md to extract entities. Follow all instructions and report completion."
+  prompt="Use /entity-extract ~/.lattice/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 ...")
+Task(subagent_type="general-purpose", model="haiku", prompt="/entity-extract ~/.lattice/docs/topic-a/README.md ...")
+Task(subagent_type="general-purpose", model="haiku", prompt="/entity-extract ~/.lattice/docs/topic-b/notes.md ...")
+Task(subagent_type="general-purpose", model="haiku", prompt="/entity-extract ~/.lattice/docs/topic-c/README.md ...")
 ```
 
 This is much faster than sequential execution for multiple documents.
@@ -87,15 +87,15 @@ Summarize what was processed:
 
 Processed 3 documents:
 
-1. docs/american-holidays/README.md
+1. ~/.lattice/docs/american-holidays/README.md
    - 4 entities extracted
    - 3 relationships defined
 
-2. docs/american-holidays/thanksgiving-vs-christmas.md
+2. ~/.lattice/docs/american-holidays/thanksgiving-vs-christmas.md
    - 8 entities extracted
    - 5 relationships defined
 
-3. docs/bun-nestjs/notes.md
+3. ~/.lattice/docs/bun-nestjs/notes.md
    - 5 entities extracted
    - 4 relationships defined
 

package/commands/research.md

@@ -65,7 +65,7 @@ If user wants new research:
 ### Step 6: Determine Topic and Filename
 
 **Identify the topic directory:**
-- Check if a relevant `docs/{topic-name}/` directory already exists
+- Check if a relevant `~/.lattice/docs/{topic-name}/` directory already exists
 - If not, derive a new topic name from the query (kebab-case)
 
 **Derive the research filename:**
@@ -89,7 +89,7 @@ Auto-derive from the specific focus of the query:
 
 Create TWO files:
 
-**1. `docs/{topic-name}/README.md`** (index):
+**1. `~/.lattice/docs/{topic-name}/README.md`** (index):
 ```markdown
 ---
 created: [TODAY'S DATE]
@@ -115,7 +115,7 @@ Brief description of what this topic covers.
 - [Related Topic](../related-topic/)
 ```
 
-**2. `docs/{topic-name}/{research-filename}.md`** (content):
+**2. `~/.lattice/docs/{topic-name}/{research-filename}.md`** (content):
 ```markdown
 ---
 created: [TODAY'S DATE]
@@ -146,9 +146,9 @@ What this research addresses.
 
 #### For EXISTING Topics (directory exists)
 
-**1. Create** `docs/{topic-name}/{research-filename}.md` with content template above
+**1. Create** `~/.lattice/docs/{topic-name}/{research-filename}.md` with content template above
 
-**2. Update** `docs/{topic-name}/README.md`:
+**2. Update** `~/.lattice/docs/{topic-name}/README.md`:
 - Add new row to the Documents table
 - Update the `updated` date in frontmatter
 
@@ -173,7 +173,7 @@ After creating files, confirm:
 ## File Structure Standard
 
 ```
-docs/{topic-name}/
+~/.lattice/docs/{topic-name}/
 ├── README.md              # Index: links to docs, brief overview
 ├── {research-1}.md        # Specific research
 ├── {research-2}.md        # Additional research

package/dist/main.js

@@ -24,12 +24,52 @@ import { Module as Module5 } from "@nestjs/common";
 import { ConfigModule as ConfigModule2 } from "@nestjs/config";
 
 // src/commands/init.command.ts
+import { existsSync as existsSync2, writeFileSync } from "fs";
 import * as fs from "fs/promises";
-import { homedir } from "os";
+import { homedir as homedir2 } from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
 import { Injectable } from "@nestjs/common";
 import { Command, CommandRunner, Option } from "nest-commander";
+
+// src/utils/paths.ts
+import { existsSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var latticeHomeOverride = null;
+function getLatticeHomeInternal() {
+  if (latticeHomeOverride) {
+    return latticeHomeOverride;
+  }
+  return join(homedir(), ".lattice");
+}
+function getLatticeHome() {
+  return getLatticeHomeInternal();
+}
+function getDocsPath() {
+  return join(getLatticeHomeInternal(), "docs");
+}
+function getDatabasePath() {
+  return join(getLatticeHomeInternal(), "lattice.duckdb");
+}
+function getManifestPath() {
+  return join(getLatticeHomeInternal(), ".sync-manifest.json");
+}
+function getEnvPath() {
+  return join(getLatticeHomeInternal(), ".env");
+}
+function ensureLatticeHome() {
+  const home = getLatticeHomeInternal();
+  if (!existsSync(home)) {
+    mkdirSync(home, { recursive: true });
+  }
+  const docsPath = getDocsPath();
+  if (!existsSync(docsPath)) {
+    mkdirSync(docsPath, { recursive: true });
+  }
+}
+
+// src/commands/init.command.ts
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = path.dirname(__filename2);
 var COMMANDS = ["research.md", "graph-sync.md", "entity-extract.md"];
@@ -37,7 +77,20 @@ var COMMANDS = ["research.md", "graph-sync.md", "entity-extract.md"];
 class InitCommand extends CommandRunner {
   async run(_inputs, options) {
     try {
-      const targetDir = options.global ? path.join(homedir(), ".claude", "commands") : path.join(process.cwd(), ".claude", "commands");
+      ensureLatticeHome();
+      const envPath = getEnvPath();
+      if (!existsSync2(envPath)) {
+        writeFileSync(envPath, `# Lattice Configuration
+# Get your API key from: https://www.voyageai.com/
+
+VOYAGE_API_KEY=
+`);
+      }
+      console.log(`\u2705 Lattice home directory: ${getLatticeHome()}`);
+      console.log(`   Documents: ${getDocsPath()}`);
+      console.log(`   Config:    ${envPath}`);
+      console.log();
+      const targetDir = options.global ? path.join(homedir2(), ".claude", "commands") : path.join(process.cwd(), ".claude", "commands");
       let commandsSourceDir = path.resolve(__dirname2, "..", "commands");
       try {
         await fs.access(commandsSourceDir);
@@ -97,7 +150,10 @@ class InitCommand extends CommandRunner {
       console.log();
       if (!options.global) {
         console.log("\uD83D\uDCA1 Tip: Use 'lattice init --global' to install for all projects");
+        console.log();
       }
+      console.log(`\u26A0\uFE0F  Add your Voyage API key to: ${getEnvPath()}`);
+      console.log();
       process.exit(0);
     } catch (error) {
       console.error("Error:", error instanceof Error ? error.message : String(error));
@@ -134,31 +190,13 @@ import { Injectable as Injectable3 } from "@nestjs/common";
 // src/sync/document-parser.service.ts
 import { createHash } from "crypto";
 import { readFile as readFile2 } from "fs/promises";
-import { resolve as resolve2 } from "path";
 import { Injectable as Injectable2, Logger } from "@nestjs/common";
 import { glob } from "glob";
 
-// src/schemas/config.schemas.ts
-import { z } from "zod";
-var DuckDBConfigSchema = z.object({
-  dbPath: z.string().optional(),
-  embeddingDimensions: z.coerce.number().int().positive().default(512)
-});
-var EmbeddingConfigSchema = z.object({
-  provider: z.enum(["openai", "voyage", "nomic", "mock"]).default("voyage"),
-  apiKey: z.string().optional(),
-  model: z.string().min(1).default("voyage-3.5-lite"),
-  dimensions: z.coerce.number().int().positive().default(512)
-});
-var DocsConfigSchema = z.object({
-  projectRoot: z.string().default(process.cwd()),
-  docsPath: z.string().default("docs")
-});
-
 // src/utils/frontmatter.ts
 import matter from "gray-matter";
-import { z as z2 } from "zod";
-var EntityTypeSchema = z2.enum([
+import { z } from "zod";
+var EntityTypeSchema = z.enum([
   "Topic",
   "Technology",
   "Concept",
@@ -168,20 +206,20 @@ var EntityTypeSchema = z2.enum([
   "Organization",
   "Document"
 ]);
-var RelationTypeSchema = z2.enum(["REFERENCES"]);
-var EntitySchema = z2.object({
-  name: z2.string().min(1),
+var RelationTypeSchema = z.enum(["REFERENCES"]);
+var EntitySchema = z.object({
+  name: z.string().min(1),
   type: EntityTypeSchema,
-  description: z2.string().optional()
+  description: z.string().optional()
 });
-var RelationshipSchema = z2.object({
-  source: z2.string().min(1),
+var RelationshipSchema = z.object({
+  source: z.string().min(1),
   relation: RelationTypeSchema,
-  target: z2.string().min(1)
+  target: z.string().min(1)
 });
-var GraphMetadataSchema = z2.object({
-  importance: z2.enum(["high", "medium", "low"]).optional(),
-  domain: z2.string().optional()
+var GraphMetadataSchema = z.object({
+  importance: z.enum(["high", "medium", "low"]).optional(),
+  domain: z.string().optional()
 });
 var validateDateFormat = (dateStr) => {
   const match = dateStr.match(/^(\d{4})-(\d{2})-(\d{2})$/);
@@ -201,15 +239,15 @@ var validateDateFormat = (dateStr) => {
   }
   return day <= daysInMonth[month - 1];
 };
-var FrontmatterSchema = z2.object({
-  created: z2.string().refine(validateDateFormat, "Date must be in YYYY-MM-DD format"),
-  updated: z2.string().refine(validateDateFormat, "Date must be in YYYY-MM-DD format"),
-  status: z2.enum(["draft", "ongoing", "complete"]).optional(),
-  topic: z2.string().optional(),
-  tags: z2.array(z2.string()).optional(),
-  summary: z2.string().optional(),
-  entities: z2.array(EntitySchema).optional(),
-  relationships: z2.array(RelationshipSchema).optional(),
+var FrontmatterSchema = z.object({
+  created: z.string().refine(validateDateFormat, "Date must be in YYYY-MM-DD format"),
+  updated: z.string().refine(validateDateFormat, "Date must be in YYYY-MM-DD format"),
+  status: z.enum(["draft", "ongoing", "complete"]).optional(),
+  topic: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  summary: z.string().optional(),
+  entities: z.array(EntitySchema).optional(),
+  relationships: z.array(RelationshipSchema).optional(),
   graph: GraphMetadataSchema.optional()
 }).passthrough();
 function parseFrontmatter(content) {
@@ -256,15 +294,8 @@ class DocumentParserService {
   logger = new Logger(DocumentParserService.name);
   docsPath;
   constructor() {
-    const config = DocsConfigSchema.parse({
-      projectRoot: process.env.PROJECT_ROOT,
-      docsPath: process.env.DOCS_PATH
-    });
-    if (config.docsPath.startsWith("/")) {
-      this.docsPath = config.docsPath;
-    } else {
-      this.docsPath = resolve2(config.projectRoot, config.docsPath);
-    }
+    ensureLatticeHome();
+    this.docsPath = getDocsPath();
   }
   getDocsPath() {
     return this.docsPath;
@@ -542,6 +573,18 @@ import { Command as Command3, CommandRunner as CommandRunner3, Option as Option2
 import { Injectable as Injectable5, Logger as Logger2 } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 
+// src/schemas/config.schemas.ts
+import { z as z2 } from "zod";
+var DuckDBConfigSchema = z2.object({
+  embeddingDimensions: z2.coerce.number().int().positive().default(512)
+});
+var EmbeddingConfigSchema = z2.object({
+  provider: z2.enum(["openai", "voyage", "nomic", "mock"]).default("voyage"),
+  apiKey: z2.string().optional(),
+  model: z2.string().min(1).default("voyage-3.5-lite"),
+  dimensions: z2.coerce.number().int().positive().default(512)
+});
+
 // src/embedding/embedding.types.ts
 var DEFAULT_EMBEDDING_CONFIG = {
   provider: "voyage",
@@ -789,6 +832,7 @@ EmbeddingService = __legacyDecorateClassTS([
 ], EmbeddingService);
 
 // src/graph/graph.service.ts
+import { existsSync as existsSync3, unlinkSync } from "fs";
 import { DuckDBInstance } from "@duckdb/node-api";
 import { Injectable as Injectable6, Logger as Logger3 } from "@nestjs/common";
 import { ConfigService as ConfigService2 } from "@nestjs/config";
@@ -803,7 +847,8 @@ class GraphService {
   embeddingDimensions;
   constructor(configService) {
     this.configService = configService;
-    this.dbPath = this.configService.get("DUCKDB_PATH") || "./.lattice.duckdb";
+    ensureLatticeHome();
+    this.dbPath = getDatabasePath();
     this.embeddingDimensions = this.configService.get("EMBEDDING_DIMENSIONS") || 512;
   }
   async onModuleDestroy() {
@@ -830,6 +875,11 @@ class GraphService {
   }
   async connect() {
     try {
+      const walPath = `${this.dbPath}.wal`;
+      if (existsSync3(walPath)) {
+        this.logger.warn(`Removing WAL file to prevent HNSW index replay failure`);
+        unlinkSync(walPath);
+      }
       this.instance = await DuckDBInstance.create(this.dbPath, {
         allow_unsigned_extensions: "true"
       });
@@ -855,6 +905,11 @@ class GraphService {
   }
   async disconnect() {
     if (this.connection) {
+      try {
+        await this.connection.run("CHECKPOINT;");
+      } catch {
+        this.logger.debug("Checkpoint failed during disconnect");
+      }
       this.connection.closeSync();
       this.connection = null;
       this.logger.log("Disconnected from DuckDB");
@@ -1329,9 +1384,8 @@ import { Command as Command4, CommandRunner as CommandRunner4, Option as Option3
 
 // src/sync/manifest.service.ts
 import { createHash as createHash2 } from "crypto";
-import { existsSync } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { readFile as readFile3, writeFile } from "fs/promises";
-import { resolve as resolve3 } from "path";
 import { Injectable as Injectable8 } from "@nestjs/common";
 
 // src/schemas/manifest.schemas.ts
@@ -1350,23 +1404,15 @@ var SyncManifestSchema = z4.object({
 });
 
 // src/sync/manifest.service.ts
-function getProjectRoot() {
-  if (process.env.PROJECT_ROOT) {
-    return process.env.PROJECT_ROOT;
-  }
-  return process.cwd();
-}
-
 class ManifestService {
   manifestPath;
   manifest = null;
   constructor() {
-    const docsPath = process.env.DOCS_PATH || "docs";
-    this.manifestPath = resolve3(getProjectRoot(), docsPath, ".sync-manifest.json");
+    this.manifestPath = getManifestPath();
   }
   async load() {
     try {
-      if (existsSync(this.manifestPath)) {
+      if (existsSync4(this.manifestPath)) {
         const content = await readFile3(this.manifestPath, "utf-8");
         this.manifest = SyncManifestSchema.parse(JSON.parse(content));
       } else {
@@ -1852,16 +1898,16 @@ CascadeService = __legacyDecorateClassTS([
 ], CascadeService);
 
 // src/sync/path-resolver.service.ts
-import { existsSync as existsSync2 } from "fs";
-import { isAbsolute, resolve as resolve4 } from "path";
+import { existsSync as existsSync5 } from "fs";
+import { isAbsolute, resolve as resolve2 } from "path";
 import { Injectable as Injectable10 } from "@nestjs/common";
 class PathResolverService {
-  parser;
-  constructor(parser) {
-    this.parser = parser;
+  docsPath;
+  constructor() {
+    this.docsPath = getDocsPath();
   }
   getDocsPath() {
-    return this.parser.getDocsPath();
+    return this.docsPath;
   }
   resolveDocPath(userPath, options = {}) {
     const { requireExists = true, requireInDocs = true } = options;
@@ -1869,28 +1915,12 @@ class PathResolverService {
     if (isAbsolute(userPath)) {
       resolvedPath = userPath;
     } else {
-      const fromCwd = resolve4(process.cwd(), userPath);
-      const fromDocs = resolve4(this.getDocsPath(), userPath);
-      const docsPrefix = "docs/";
-      const strippedFromDocs = userPath.startsWith(docsPrefix) ? resolve4(this.getDocsPath(), userPath.slice(docsPrefix.length)) : null;
-      if (this.isUnderDocs(fromCwd) && existsSync2(fromCwd)) {
-        resolvedPath = fromCwd;
-      } else if (strippedFromDocs && existsSync2(strippedFromDocs)) {
-        resolvedPath = strippedFromDocs;
-      } else if (existsSync2(fromDocs)) {
-        resolvedPath = fromDocs;
-      } else if (this.isUnderDocs(fromCwd)) {
-        resolvedPath = fromCwd;
-      } else if (strippedFromDocs) {
-        resolvedPath = strippedFromDocs;
-      } else {
-        resolvedPath = fromDocs;
-      }
+      resolvedPath = resolve2(this.docsPath, userPath);
     }
     if (requireInDocs && !this.isUnderDocs(resolvedPath)) {
-      throw new Error(`Path "${userPath}" resolves to "${resolvedPath}" which is outside the docs directory (${this.getDocsPath()})`);
+      throw new Error(`Path "${userPath}" resolves to "${resolvedPath}" which is outside the docs directory (${this.docsPath})`);
     }
-    if (requireExists && !existsSync2(resolvedPath)) {
+    if (requireExists && !existsSync5(resolvedPath)) {
       throw new Error(`Path "${userPath}" does not exist (resolved to: ${resolvedPath})`);
     }
     return resolvedPath;
@@ -1914,9 +1944,7 @@ class PathResolverService {
 }
 PathResolverService = __legacyDecorateClassTS([
   Injectable10(),
-  __legacyMetadataTS("design:paramtypes", [
-    typeof DocumentParserService === "undefined" ? Object : DocumentParserService
-  ])
+  __legacyMetadataTS("design:paramtypes", [])
 ], PathResolverService);
 
 // src/sync/sync.service.ts
@@ -2419,7 +2447,7 @@ StatusCommand = __legacyDecorateClassTS([
 ], StatusCommand);
 // src/commands/sync.command.ts
 import { watch } from "fs";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import { Injectable as Injectable13 } from "@nestjs/common";
 import { Command as Command5, CommandRunner as CommandRunner5, Option as Option4 } from "nest-commander";
 class SyncCommand extends CommandRunner5 {
@@ -2545,7 +2573,7 @@ class SyncCommand extends CommandRunner5 {
 `);
     this.watcher = watch(docsPath, { recursive: true }, (event, filename) => {
       if (filename?.endsWith(".md")) {
-        const fullPath = join2(docsPath, filename);
+        const fullPath = join3(docsPath, filename);
         trackedFiles.add(fullPath);
         debouncedSync();
       }
@@ -2920,7 +2948,8 @@ AppModule = __legacyDecorateClassTS([
   Module5({
     imports: [
       ConfigModule2.forRoot({
-        isGlobal: true
+        isGlobal: true,
+        envFilePath: getEnvPath()
       }),
       GraphModule,
       SyncModule,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zabaca/lattice",
-	"version": "1.0.1",
+	"version": "1.0.3",
 	"description": "Human-initiated, AI-powered knowledge graph for markdown documentation",
 	"type": "module",
 	"bin": {