lattice-graph 0.4.0 → 0.5.1

package/README.md

@@ -19,16 +19,16 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
 </p>
 
-Lattice builds a knowledge graph of your codebase that coding agents query instead of grep and file reading. Agents get precise, scoped context — a flow's call tree, a function's callers, the impact of a change — in minimal tokens. No more reading entire files to understand three functions.
+Lattice builds a knowledge graph of your codebase that coding agents query instead of grep and file reading. Agents get precise, scoped context - a flow's call tree, a function's callers, the impact of a change - in minimal tokens. No more reading entire files to understand three functions.
 
 ## The Problem
 
 Coding agents today dump raw source code into their context windows. They grep for keywords, read whole files, and hope the relevant code is somewhere in the noise. This causes:
 
-- **Context rot** — stale file contents from earlier exploration steps degrade attention
-- **Token waste** — reading 500-line files to understand 20-line functions
-- **Terminology mismatch** — searching "checkout timeout" fails when the code calls it `chargeCard`
-- **Cold start** — every conversation starts from zero with no understanding of the codebase
+- **Context rot** - stale file contents from earlier exploration steps degrade attention
+- **Token waste** - reading 500-line files to understand 20-line functions
+- **Terminology mismatch** - searching "checkout timeout" fails when the code calls it `chargeCard`
+- **Cold start** - every conversation starts from zero with no understanding of the codebase
 
 ## The Solution
 
@@ -103,7 +103,7 @@ lattice code charge                 # read just the function source to edit
 
 ## Tags
 
-Lattice uses four tags placed in comments directly above function definitions. Tags capture what the AST cannot — business flow entry points, external system boundaries, and invisible runtime connections.
+Lattice uses four tags placed in comments directly above function definitions. Tags capture what the AST cannot - business flow entry points, external system boundaries, and invisible runtime connections.
 
 | Tag | Purpose | Example |
 |-----|---------|---------|
@@ -114,7 +114,7 @@ Lattice uses four tags placed in comments directly above function definitions. T
 
 **What you tag:** Route handlers, CLI commands, cron jobs, external API calls, database operations, event publishers, event consumers.
 
-**What you don't tag:** Everything else. Intermediate functions, callers, callees, types — all derived automatically from the call graph.
+**What you don't tag:** Everything else. Intermediate functions, callers, callees, types - all derived automatically from the call graph.
 
 ### Syntax rules
 
@@ -137,7 +137,7 @@ FLOW: checkout
                                    send_confirmation
 ```
 
-`create_order`, `charge`, `save_order` — none of these need tags. Their flow membership is derived.
+`create_order`, `charge`, `save_order` - none of these need tags. Their flow membership is derived.
 
 ### Async job dispatch patterns
 
@@ -162,11 +162,11 @@ def process_ingest_vacancies(data, services):
 
 With these tags, `lattice flow ingest-vacancies` shows the complete chain from the API route through the queue to the worker, including normalization and indexing. Without the `emits`/`handles` tags, the flow tree stops at the queue submission.
 
-**Key rule:** Worker handlers, Lambda consumers, and background job processors are NOT separate flows — they are the receiving side of an async dispatch. Tag them with `@lattice:handles`, not `@lattice:flow`.
+**Key rule:** Worker handlers, Lambda consumers, and background job processors are NOT separate flows - they are the receiving side of an async dispatch. Tag them with `@lattice:handles`, not `@lattice:flow`.
 
 ### Tags and protocols/interfaces
 
-When using dependency injection or protocol-based dispatch, place `emits` tags on the function that the flow actually passes through — not on a concrete implementation behind an interface:
+When using dependency injection or protocol-based dispatch, place `emits` tags on the function that the flow actually passes through - not on a concrete implementation behind an interface:
 
 ```python
 # Good: tag is on the function the flow reaches
@@ -271,11 +271,11 @@ Affected flows: checkout
 
 Instead of grepping and reading files, an agent using Lattice follows this flow:
 
-1. **Orient** — `lattice overview` to understand the project landscape
-2. **Locate** — `lattice flow <name>` to see the relevant call tree
-3. **Understand** — `lattice context <symbol>` for a specific function's neighborhood
-4. **Scope** — `lattice impact <symbol>` to know what's affected by a change
-5. **Edit** — `lattice code <symbol>` to read only the function being modified
+1. **Orient** - `lattice overview` to understand the project landscape
+2. **Locate** - `lattice flow <name>` to see the relevant call tree
+3. **Understand** - `lattice context <symbol>` for a specific function's neighborhood
+4. **Scope** - `lattice impact <symbol>` to know what's affected by a change
+5. **Edit** - `lattice code <symbol>` to read only the function being modified
 
 Total context consumed: ~200-500 tokens instead of 5,000-50,000 from reading files.
 
@@ -303,22 +303,22 @@ lattice lint --unresolved           # show unresolved reference details
 ```
 
 The linter detects:
-- **Missing tags** — route handlers without `@lattice:flow`, external calls without `@lattice:boundary`
-- **Invalid tags** — tags on classes instead of functions, missing values
-- **Typos** — `@lattice:flow chekout` when `checkout` exists elsewhere
-- **Orphaned events** — emits without handlers, handlers without emitters
-- **Stale tags** — boundary tags on functions that no longer call the package
+- **Missing tags** - route handlers without `@lattice:flow`, external calls without `@lattice:boundary`
+- **Invalid tags** - tags on classes instead of functions, missing values
+- **Typos** - `@lattice:flow chekout` when `checkout` exists elsewhere
+- **Orphaned events** - emits without handlers, handlers without emitters
+- **Stale tags** - boundary tags on functions that no longer call the package
 
 ## How It Works
 
 1. **LSP servers** (`typescript-language-server` for TypeScript, `zubanls` for Python) provide type-checked symbol and call information
-2. **Combined edge strategies** — both `outgoingCalls` and `references` are used to maximize edge coverage across files
+2. **Combined edge strategies** - both `outgoingCalls` and `references` are used to maximize edge coverage across files
 3. **Tag scanner** reads `@lattice:` comments and associates them with the function below
 4. **Graph builder** inserts everything into a SQLite database with nodes, edges, and tags
 5. **Event synthesis** creates invisible edges from `@lattice:emits` to `@lattice:handles` nodes, connecting async flows
 6. **CLI queries** traverse the graph and return compact, scoped results
 
-The graph is stored at `.lattice/graph.db` — a single SQLite file.
+The graph is stored at `.lattice/graph.db` - a single SQLite file.
 
 ## Configuration
 
@@ -408,7 +408,7 @@ lattice build && lattice lint   # after adding/changing tags
 }
 ```
 
-The hooks remind the agent to try Lattice before falling back to traditional tools. They don't block — they guide.
+The hooks remind the agent to try Lattice before falling back to traditional tools. They don't block - they guide.
 
 ## Requirements
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "lattice-graph",
-	"version": "0.4.0",
-	"description": "Knowledge graph CLI for coding agents — navigate code through flows, not grep.",
+	"version": "0.5.1",
+	"description": "Knowledge graph CLI for coding agents - navigate code through flows, not grep.",
 	"module": "src/main.ts",
 	"type": "module",
 	"bin": {

package/src/commands/build.ts

@@ -82,4 +82,4 @@ function buildLanguageConfigs(config: LatticeConfig): readonly LanguageConfig[]
 	return configs;
 }
 
-export { executeBuild };
+export { buildLanguageConfigs, executeBuild };

package/src/commands/init.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { err, ok, type Result } from "../types/result.ts";
 
@@ -27,6 +27,17 @@ function executeInit(projectRoot: string): Result<string, string> {
 			writeFileSync(tomlPath, toml);
 		}
 
+		// Append Lattice section to CLAUDE.md (skip if already present)
+		const claudeDir = join(projectRoot, ".claude");
+		const claudeMdPath = join(claudeDir, "CLAUDE.md");
+		mkdirSync(claudeDir, { recursive: true });
+		const existing = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, "utf-8") : "";
+		if (!existing.includes("## Code Navigation")) {
+			const snippet = generateClaudeSnippet(languages);
+			const separator = existing.length > 0 && !existing.endsWith("\n\n") ? "\n\n" : "";
+			appendFileSync(claudeMdPath, `${separator}${snippet}`);
+		}
+
 		// Check LSP server availability
 		const warnings = checkLspAvailability(languages);
 		const message = ["Initialized Lattice project", ...warnings].join("\n");
@@ -66,7 +77,7 @@ function detectLanguages(projectRoot: string): readonly string[] {
 	return languages;
 }
 
-/** Detects the source root — uses "src" if it exists, otherwise ".". */
+/** Detects the source root - uses "src" if it exists, otherwise ".". */
 function detectRoot(projectRoot: string): string {
 	const srcPath = `${projectRoot}/src`;
 	try {
@@ -111,4 +122,135 @@ function checkLspAvailability(languages: readonly string[]): readonly string[] {
 	return warnings;
 }
 
-export { executeInit };
+const PYTHON_EXAMPLE = `\`\`\`bash
+# 1. Orient: what flows exist?
+lattice overview
+
+# 2. Locate: find the relevant flow
+lattice flow user-registration
+
+# Output:
+# register (app/auth/routes.py:45)
+#   → validate_input (app/auth/validation.py:12)
+#   → create_user (app/auth/service.py:30)
+#     → hash_password (app/auth/crypto.py:8)
+#     → insert_user (app/storage/postgres.py:55) [postgres]
+#   → send_welcome_email (app/notifications/email.py:20) [sendgrid]
+
+# 3. Understand: zoom into the function you suspect
+lattice context create_user
+
+# 4. Scope: check what breaks if you change it
+lattice impact create_user
+
+# 5. Read: get just that function's source
+lattice code create_user
+
+# 6. Edit: use Read/Edit tools on app/auth/service.py:30
+\`\`\`
+
+### Symbol format
+
+Unique names work directly. Ambiguous names need file qualification.
+
+\`\`\`bash
+lattice context create_user                       # unique name
+lattice context app/auth/service.py::create_user  # file::function
+lattice context app/models.py::User.save          # file::Class.method
+\`\`\``;
+
+const TYPESCRIPT_EXAMPLE = `\`\`\`bash
+# 1. Orient: what flows exist?
+lattice overview
+
+# 2. Locate: find the relevant flow
+lattice flow checkout
+
+# Output:
+# handleCheckout (src/api/checkout.ts:25)
+#   → validateCart (src/cart/validation.ts:12)
+#   → createOrder (src/orders/service.ts:40)
+#     → insertOrder (src/db/orders.ts:18) [postgres]
+#     → chargePayment (src/payments/stripe.ts:30) [stripe]
+#   → sendConfirmation (src/notifications/email.ts:55) [sendgrid]
+
+# 3. Understand: zoom into the function you suspect
+lattice context createOrder
+
+# 4. Scope: check what breaks if you change it
+lattice impact createOrder
+
+# 5. Read: get just that function's source
+lattice code createOrder
+
+# 6. Edit: use Read/Edit tools on src/orders/service.ts:40
+\`\`\`
+
+### Symbol format
+
+Unique names work directly. Ambiguous names need file qualification.
+
+\`\`\`bash
+lattice context createOrder                          # unique name
+lattice context src/orders/service.ts::createOrder   # file::function
+\`\`\``;
+
+const GO_EXAMPLE = `\`\`\`bash
+# 1. Orient: what flows exist?
+lattice overview
+
+# 2. Locate: find the relevant flow
+lattice flow create-order
+
+# Output:
+# HandleCreateOrder (internal/api/orders.go:35)
+#   → ValidateRequest (internal/api/validation.go:20)
+#   → CreateOrder (internal/service/orders.go:45)
+#     → InsertOrder (internal/repo/orders.go:28) [postgres]
+#     → PublishEvent (internal/events/publisher.go:15) [nats]
+
+# 3. Understand: zoom into the function you suspect
+lattice context CreateOrder
+
+# 4. Scope: check what breaks if you change it
+lattice impact CreateOrder
+
+# 5. Read: get just that function's source
+lattice code CreateOrder
+
+# 6. Edit: use Read/Edit tools on internal/service/orders.go:45
+\`\`\`
+
+### Symbol format
+
+Unique names work directly. Ambiguous names need file qualification.
+
+\`\`\`bash
+lattice context CreateOrder                                # unique name
+lattice context internal/service/orders.go::CreateOrder    # file::function
+lattice context internal/api/server.go::Server.Handle      # file::Struct.Method
+\`\`\``;
+
+/** Generates a CLAUDE.md snippet with language-appropriate few-shot examples. */
+function generateClaudeSnippet(languages: readonly string[]): string {
+	const primary = languages[0] ?? "typescript";
+	const example =
+		primary === "python" ? PYTHON_EXAMPLE : primary === "go" ? GO_EXAMPLE : TYPESCRIPT_EXAMPLE;
+
+	return `## Code Navigation
+
+This project uses **Lattice** for codebase navigation. Use Lattice before reading files or Grep.
+
+### Example: full workflow
+
+${example}
+
+### After code changes
+
+\`\`\`bash
+lattice update
+\`\`\`
+`;
+}
+
+export { executeInit, generateClaudeSnippet };

package/src/commands/lint.ts

@@ -4,7 +4,7 @@ import type { LintIssue, LintResult } from "../types/lint.ts";
 
 /**
  * Runs all lint checks against the built knowledge graph.
- * Does not modify the database — reports only.
+ * Does not modify the database - reports only.
  *
  * @param db - An open Database handle (readonly)
  * @param config - Lattice configuration
@@ -51,7 +51,7 @@ function checkInvalidTags(db: Database, issues: LintIssue[]): void {
 			file: row.file,
 			line: row.line_start,
 			symbol: row.name,
-			message: `@lattice:${row.tag_kind} tag on a ${row.node_kind} — tags should only be on functions or methods`,
+			message: `@lattice:${row.tag_kind} tag on a ${row.node_kind} - tags should only be on functions or methods`,
 		});
 	}
 }
@@ -66,7 +66,7 @@ function checkTypos(db: Database, issues: LintIssue[]): void {
 	const commons = tagCounts.filter((t) => t.cnt > 1);
 
 	for (const single of singletons) {
-		// Require longer names for typo detection — short names like "s3" and "sqs" are distinct
+		// Require longer names for typo detection - short names like "s3" and "sqs" are distinct
 		const minLength = 4;
 		if (single.value.length < minLength) continue;
 
@@ -95,7 +95,7 @@ function checkTypos(db: Database, issues: LintIssue[]): void {
 					file: tagNode.file,
 					line: tagNode.line_start,
 					symbol: tagNode.name,
-					message: `@lattice:${single.kind} "${single.value}" — did you mean "${bestMatch.value}"? (used ${bestMatch.cnt} times elsewhere)`,
+					message: `@lattice:${single.kind} "${single.value}" - did you mean "${bestMatch.value}"? (used ${bestMatch.cnt} times elsewhere)`,
 				});
 			}
 		}
@@ -119,7 +119,7 @@ function checkOrphanedEvents(db: Database, issues: LintIssue[]): void {
 			file: row.file,
 			line: row.line_start,
 			symbol: row.name,
-			message: `@lattice:emits "${row.value}" has no handler — no @lattice:handles "${row.value}" found`,
+			message: `@lattice:emits "${row.value}" has no handler - no @lattice:handles "${row.value}" found`,
 		});
 	}
 
@@ -138,7 +138,7 @@ function checkOrphanedEvents(db: Database, issues: LintIssue[]): void {
 			file: row.file,
 			line: row.line_start,
 			symbol: row.name,
-			message: `@lattice:handles "${row.value}" has no emitter — no @lattice:emits "${row.value}" found`,
+			message: `@lattice:handles "${row.value}" has no emitter - no @lattice:emits "${row.value}" found`,
 		});
 	}
 }
@@ -178,7 +178,7 @@ function checkStaleBoundaryTags(db: Database, issues: LintIssue[]): void {
 				file: tag.file,
 				line: tag.line_start,
 				symbol: tag.name,
-				message: `@lattice:boundary "${tag.value}" may be stale — no external calls found in this function`,
+				message: `@lattice:boundary "${tag.value}" may be stale - no external calls found in this function`,
 			});
 		}
 	}
@@ -217,7 +217,7 @@ function checkMissingBoundaryTags(db: Database, issues: LintIssue[]): void {
 }
 
 /**
- * Checks for flow entry points with zero callees — the flow tree is just the root node.
+ * Checks for flow entry points with zero callees - the flow tree is just the root node.
  * This typically indicates dynamic dispatch, decorated functions, or missing event connections.
  */
 function checkDeadEndFlows(db: Database, issues: LintIssue[]): void {
@@ -246,7 +246,7 @@ function checkDeadEndFlows(db: Database, issues: LintIssue[]): void {
 				file: entry.file,
 				line: entry.line_start,
 				symbol: entry.name,
-				message: `Flow "${entry.flow_name}" entry point has no callees — the call tree may be incomplete. If this function dispatches through a queue or dynamic dispatch, add @lattice:emits/@lattice:handles tags.`,
+				message: `Flow "${entry.flow_name}" entry point has no callees - the call tree may be incomplete. If this function dispatches through a queue or dynamic dispatch, add @lattice:emits/@lattice:handles tags.`,
 			});
 		}
 	}

package/src/commands/populate.ts

@@ -22,38 +22,38 @@ function executePopulate(db: Database, _config: LatticeConfig): string {
 	return sections.join("\n\n");
 }
 
-/** Outputs the tag spec — what each tag means and the syntax rules. */
+/** Outputs the tag spec - what each tag means and the syntax rules. */
 function tagSpecSection(): string {
 	return `## Lattice Tag Specification
 
 Four tags, placed in comments directly above function definitions:
 
-- \`@lattice:flow <name>\` — Flow entry point. Where execution begins for a business operation. Route handlers, CLI commands, cron jobs, queue consumers.
-- \`@lattice:boundary <system>\` — External boundary. Where code leaves the codebase. API calls, database queries, cache operations, third-party SDKs.
-- \`@lattice:emits <event>\` — Event emission. Publishes to a queue, event bus, or notification system.
-- \`@lattice:handles <event>\` — Event consumption. Subscribes to or processes events. Must match a corresponding emits tag.
+- \`@lattice:flow <name>\` - Flow entry point. Where execution begins for a business operation. Route handlers, CLI commands, cron jobs, queue consumers.
+- \`@lattice:boundary <system>\` - External boundary. Where code leaves the codebase. API calls, database queries, cache operations, third-party SDKs.
+- \`@lattice:emits <event>\` - Event emission. Publishes to a queue, event bus, or notification system.
+- \`@lattice:handles <event>\` - Event consumption. Subscribes to or processes events. Must match a corresponding emits tag.
 
 Rules:
 - Place the tag comment directly above the function definition, no blank lines between
 - Names are kebab-case: \`checkout\`, \`user-registration\`, \`order.created\`, \`aws-s3\`
 - Multiple values: \`# @lattice:flow checkout, payment\`
-- Do NOT tag intermediate functions — only entry points and boundaries. Everything in between is derived from the call graph automatically.`;
+- Do NOT tag intermediate functions - only entry points and boundaries. Everything in between is derived from the call graph automatically.`;
 }
 
 /** Few-shot examples showing correct tagging across different scenarios. */
 function examplesSection(): string {
 	return `## Examples
 
-### Python — FastAPI route with boundary and events
+### Python - FastAPI route with boundary and events
 
 \`\`\`python
 # @lattice:flow checkout
 @app.post("/api/checkout")
 def handle_checkout(req):
-    order = create_order(req)       # no tag — derived from call graph
+    order = create_order(req)       # no tag - derived from call graph
     return order
 
-def create_order(req):              # no tag — derived from call graph
+def create_order(req):              # no tag - derived from call graph
     charge(req.amount, req.token)
     save_order(req)
     emit_order_created(req.order_id)
@@ -75,7 +75,7 @@ def send_confirmation(event):
     sendgrid.send(event.order_id)
 \`\`\`
 
-### TypeScript — Express route with database boundary
+### TypeScript - Express route with database boundary
 
 \`\`\`typescript
 // @lattice:flow user-registration
@@ -90,7 +90,7 @@ async function createUser(data: CreateUserInput): Promise<User> {
 }
 \`\`\`
 
-### Python — Celery task as entry point
+### Python - Celery task as entry point
 
 \`\`\`python
 # @lattice:flow invoice-generation
@@ -108,7 +108,7 @@ def render_invoice(order):
 \`\`\``;
 }
 
-/** Brief project summary from the graph — just enough context, not a file listing. */
+/** Brief project summary from the graph - just enough context, not a file listing. */
 function projectSummarySection(db: Database): string {
 	const lines: string[] = ["## This Project", ""];
 
@@ -148,15 +148,15 @@ Follow these steps in order. Do not skip validation steps.
 
 ### Step 1: Tag entry points
 
-Read the source files and identify all entry points — route handlers, CLI commands, cron jobs, queue consumers, event listeners. Add \`@lattice:flow <name>\` above each one.
+Read the source files and identify all entry points - route handlers, CLI commands, cron jobs, queue consumers, event listeners. Add \`@lattice:flow <name>\` above each one.
 
-Use domain names for flows: "checkout", "user-registration", "invoice-generation" — not function names.
+Use domain names for flows: "checkout", "user-registration", "invoice-generation" - not function names.
 
 ### Step 2: Tag boundaries
 
-Identify all functions that call external systems — APIs, databases, caches, file storage, third-party SDKs. Add \`@lattice:boundary <system>\` above each one.
+Identify all functions that call external systems - APIs, databases, caches, file storage, third-party SDKs. Add \`@lattice:boundary <system>\` above each one.
 
-Use the external system name: "stripe", "postgres", "redis", "s3" — not the function or library name.
+Use the external system name: "stripe", "postgres", "redis", "s3" - not the function or library name.
 
 ### Step 3: Tag async dispatch (queues, Lambda, Celery)
 
@@ -165,7 +165,7 @@ If the codebase submits work to a queue (SQS, RabbitMQ), invokes Lambda function
 - Add \`@lattice:emits job.<name>\` on the function that submits/invokes the async work
 - Add \`@lattice:handles job.<name>\` on the function that processes the work on the other side
 
-Important: Worker handlers and Lambda consumers are NOT separate flows — they are the receiving side of an async dispatch. Tag them with \`@lattice:handles\`, not \`@lattice:flow\`.
+Important: Worker handlers and Lambda consumers are NOT separate flows - they are the receiving side of an async dispatch. Tag them with \`@lattice:handles\`, not \`@lattice:flow\`.
 
 Place \`emits\` tags on the function the flow actually passes through, not on a concrete implementation behind a protocol or interface.
 

package/src/commands/update.ts

@@ -5,7 +5,7 @@ import { discoverFiles } from "../files.ts";
 import { checkSchemaVersion } from "../graph/database.ts";
 import type { LatticeConfig } from "../types/config.ts";
 import { isOk, ok, type Result } from "../types/result.ts";
-import { executeBuild } from "./build.ts";
+import { buildLanguageConfigs, executeBuild } from "./build.ts";
 
 /** Statistics from an incremental update. */
 type UpdateStats = {
@@ -58,13 +58,14 @@ async function executeUpdate(
 	}
 	const lastBuild = Number.parseInt(metaRow.value, 10);
 
-	// Discover files
-	const extensions = [".ts", ".tsx"];
-	const sourceRoots = config.typescript?.sourceRoots ?? [config.root];
+	// Discover files across all configured languages
+	const languageConfigs = buildLanguageConfigs(config);
 	const allFiles: string[] = [];
-	for (const srcRoot of sourceRoots) {
-		const absRoot = resolve(projectRoot, srcRoot);
-		allFiles.push(...discoverFiles(absRoot, extensions, config.exclude));
+	for (const lang of languageConfigs) {
+		for (const srcRoot of lang.sourceRoots) {
+			const absRoot = resolve(projectRoot, srcRoot);
+			allFiles.push(...discoverFiles(absRoot, lang.extensions, config.exclude));
+		}
 	}
 
 	// Find changed files

package/src/extract/tag-scanner.ts

@@ -48,7 +48,7 @@ function scanTags(source: string, nodes: readonly Node[], language?: string): Ta
 		// Skip tags that are inside a function body and point to the SAME function
 		// (these are @lattice: mentions in string literals, not real tags).
 		// Tags between functions (e.g., above a decorated function whose predecessor's
-		// range overlaps) are fine — the target will be a different, later function.
+		// range overlaps) are fine - the target will be a different, later function.
 		const containingNode = candidateNodes.find(
 			(n) => tagLine > n.lineStart && tagLine <= n.lineEnd,
 		);
@@ -75,7 +75,7 @@ function scanTags(source: string, nodes: readonly Node[], language?: string): Ta
 
 		for (const value of values) {
 			if (!NAME_PATTERN.test(value)) {
-				errors.push(`Line ${tagLine}: invalid tag name '${value}' — must be lowercase kebab-case`);
+				errors.push(`Line ${tagLine}: invalid tag name '${value}' - must be lowercase kebab-case`);
 				continue;
 			}
 

package/src/graph/queries.ts

@@ -132,7 +132,7 @@ function getCallees(db: Database, nodeId: string): readonly Node[] {
 
 /**
  * Returns all transitive callers of a node (upstream traversal).
- * Used for impact analysis — "what is affected if I change this?"
+ * Used for impact analysis - "what is affected if I change this?"
  *
  * @param db - An open Database handle
  * @param nodeId - The full node ID to analyze

package/src/lsp/builder.ts

@@ -1,5 +1,5 @@
 import type { Database } from "bun:sqlite";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { scanTags } from "../extract/tag-scanner.ts";
 import { discoverFiles } from "../files.ts";
@@ -40,7 +40,7 @@ type BuildStats = {
 	readonly durationMs: number;
 };
 
-const VENDOR_VENV = join(import.meta.dir, "..", "..", "vendor", "venv");
+const LATTICE_HOME = join(process.env.HOME ?? process.env.USERPROFILE ?? ".", ".lattice");
 
 const LANGUAGE_EXTENSIONS: Record<string, readonly string[]> = {
 	typescript: [".ts", ".tsx"],
@@ -65,9 +65,9 @@ function resolveLspServer(
 		return { command, args: ["--stdio"], languageId: "typescript" };
 	}
 	if (language === "python") {
-		const zubanls = resolveZuban();
-		if (!zubanls) return undefined;
-		return { command: zubanls, args: [], languageId: "python" };
+		const zuban = resolveZuban();
+		if (!zuban) return undefined;
+		return { command: zuban, args: ["server"], languageId: "python" };
 	}
 	if (language === "go") {
 		const goplsBin = resolveGopls();
@@ -77,65 +77,86 @@ function resolveLspServer(
 	return undefined;
 }
 
-/** Finds or installs zubanls. Returns the binary path, or undefined if installation fails. */
+/** Finds or installs zuban. Returns the binary path, or undefined if installation fails. */
 function resolveZuban(): string | undefined {
 	const isWindows = process.platform === "win32";
 	const binDir = isWindows ? "Scripts" : "bin";
-	const binName = isWindows ? "zubanls.exe" : "zubanls";
+	const binName = isWindows ? "zuban.exe" : "zuban";
+	const venvPath = join(LATTICE_HOME, "venv");
 
-	// 1. Check vendored venv (installed by a previous build)
-	const vendored = join(VENDOR_VENV, binDir, binName);
+	const vendored = join(venvPath, binDir, binName);
 	if (existsSync(vendored)) return vendored;
 
-	// 2. Check system PATH
-	const system = Bun.which("zubanls");
+	const system = Bun.which("zuban");
 	if (system) return system;
 
-	// 3. Auto-install into vendored venv
 	return installZuban();
 }
 
-/** Creates a venv and pip-installs zuban. Returns zubanls path or undefined on failure. */
+/** Installs zuban into ~/.lattice/venv. Tries uv first, falls back to pip. */
 function installZuban(): string | undefined {
 	const isWindows = process.platform === "win32";
 	const binDir = isWindows ? "Scripts" : "bin";
-	const binName = isWindows ? "zubanls.exe" : "zubanls";
+	const binName = isWindows ? "zuban.exe" : "zuban";
+	const venvPath = join(LATTICE_HOME, "venv");
 
-	const python = Bun.which("python3") ?? Bun.which("python");
-	if (!python) {
-		console.error("Python not found. Install Python 3 to enable Python support.");
-		return undefined;
-	}
+	mkdirSync(LATTICE_HOME, { recursive: true });
 
 	console.log("Installing Python language server (zuban)...");
 
-	const venvResult = Bun.spawnSync([python, "-m", "venv", VENDOR_VENV], {
-		stdout: "ignore",
-		stderr: "pipe",
-	});
-	if (venvResult.exitCode !== 0) {
-		console.error(`Failed to create venv: ${venvResult.stderr.toString()}`);
-		return undefined;
-	}
+	const uv = Bun.which("uv");
+	if (uv) {
+		const result = Bun.spawnSync([uv, "venv", venvPath], {
+			stdout: "ignore",
+			stderr: "pipe",
+		});
+		if (result.exitCode !== 0) {
+			console.error(`Failed to create venv: ${result.stderr.toString()}`);
+			return undefined;
+		}
+		const uvPip = Bun.spawnSync(
+			[uv, "pip", "install", "zuban", "--python", join(venvPath, binDir, "python3")],
+			{ stdout: "ignore", stderr: "pipe" },
+		);
+		if (uvPip.exitCode !== 0) {
+			console.error(`Failed to install zuban: ${uvPip.stderr.toString()}`);
+			return undefined;
+		}
+	} else {
+		const python = Bun.which("python3") ?? Bun.which("python");
+		if (!python) {
+			console.error("Python not found. Install Python 3 or uv to enable Python support.");
+			return undefined;
+		}
 
-	const pip = join(VENDOR_VENV, binDir, isWindows ? "pip.exe" : "pip");
-	const pipResult = Bun.spawnSync([pip, "install", "zuban", "--quiet"], {
-		stdout: "ignore",
-		stderr: "pipe",
-	});
-	if (pipResult.exitCode !== 0) {
-		console.error(`Failed to install zuban: ${pipResult.stderr.toString()}`);
-		return undefined;
+		const venvResult = Bun.spawnSync([python, "-m", "venv", venvPath], {
+			stdout: "ignore",
+			stderr: "pipe",
+		});
+		if (venvResult.exitCode !== 0) {
+			console.error(`Failed to create venv: ${venvResult.stderr.toString()}`);
+			return undefined;
+		}
+
+		const pip = join(venvPath, binDir, isWindows ? "pip.exe" : "pip");
+		const pipResult = Bun.spawnSync([pip, "install", "zuban", "--quiet"], {
+			stdout: "ignore",
+			stderr: "pipe",
+		});
+		if (pipResult.exitCode !== 0) {
+			console.error(`Failed to install zuban: ${pipResult.stderr.toString()}`);
+			return undefined;
+		}
 	}
 
-	const zubanls = join(VENDOR_VENV, binDir, binName);
-	if (!existsSync(zubanls)) {
-		console.error("zubanls not found after installation");
+	const zuban = join(venvPath, binDir, binName);
+	if (!existsSync(zuban)) {
+		console.error("zuban not found after installation");
 		return undefined;
 	}
 
 	console.log("done");
-	return zubanls;
+	return zuban;
 }
 
 /** Resolves gopls binary path from GOBIN or GOPATH/bin. */
@@ -264,7 +285,7 @@ async function buildGraph(opts: BuildGraphOptions): Promise<BuildStats> {
 				fileDataList.push({ filePath, relativePath, nodesWithPos });
 			}
 
-			// Phase 2a: outgoingCalls — gopls doesn't support this over stdio, so skip for Go
+			// Phase 2a: outgoingCalls - gopls doesn't support this over stdio, so skip for Go
 			if (langConfig.language !== "go")
 				for (const fd of fileDataList) {
 					for (const nwp of fd.nodesWithPos) {
@@ -290,12 +311,12 @@ async function buildGraph(opts: BuildGraphOptions): Promise<BuildStats> {
 							allEdges.push(...edges);
 							allExternalCalls.push(...externalCalls);
 						} catch {
-							// outgoingCalls not supported by this server — skip silently
+							// outgoingCalls not supported by this server - skip silently
 						}
 					}
 				}
 
-			// Phase 2b: references — "who references each function?"
+			// Phase 2b: references - "who references each function?"
 			const nodesByFile = new Map<string, readonly Node[]>();
 			for (const fd of fileDataList) {
 				nodesByFile.set(
@@ -335,7 +356,7 @@ async function buildGraph(opts: BuildGraphOptions): Promise<BuildStats> {
 							allEdges.push({ sourceId: caller.id, targetId: nwp.node.id, kind: "calls" });
 						}
 					} catch {
-						// references not supported by this server — skip silently
+						// references not supported by this server - skip silently
 					}
 				}
 			}

package/src/lsp/calls.ts

@@ -99,7 +99,7 @@ function extractGoModuleName(uri: string): string | undefined {
 /**
  * Checks if a URI points to a type-only package (not a runtime dependency).
  * Type definition packages (@types/*, typescript, bun-types) are filtered out.
- * Actual library .d.ts stubs (e.g., stripe/index.d.ts) are kept — they represent runtime deps.
+ * Actual library .d.ts stubs (e.g., stripe/index.d.ts) are kept - they represent runtime deps.
  */
 function isTypeDeclaration(uri: string): boolean {
 	// TypeScript type-only packages

package/src/lsp/client.ts

@@ -81,7 +81,7 @@ async function createLspClient(opts: LspClientOptions): Promise<LspClient> {
 			try {
 				const msg = JSON.parse(body) as JsonRpcMessage;
 				if (msg.method && msg.id !== undefined) {
-					// Server-initiated request — reply with null to unblock the server
+					// Server-initiated request - reply with null to unblock the server
 					const reply = JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: null });
 					const replyHeader = `Content-Length: ${Buffer.byteLength(reply)}\r\n\r\n`;
 					proc.stdin?.write(replyHeader + reply);

package/src/main.ts

@@ -37,7 +37,7 @@ import {
 import type { Node } from "./types/graph.ts";
 import { isOk, unwrap } from "./types/result.ts";
 
-const VERSION = "0.4.0";
+const VERSION = "0.5.0";
 
 const program = new Command();
 program.name("lattice").description("Knowledge graph CLI for coding agents").version(VERSION);
@@ -269,17 +269,14 @@ program
 		const nodes = resolveSymbol(db, symbol);
 
 		if (nodes.length === 0) {
+			printUnknownSymbolError(db, symbol);
 			db.close();
-			console.log(`Unknown symbol: ${symbol}`);
 			process.exit(1);
 		}
 
 		if (nodes.length > 1) {
+			printAmbiguousSymbolError(nodes);
 			db.close();
-			console.log("Ambiguous symbol. Matches:");
-			for (const n of nodes) {
-				console.log(`  ${n.id}`);
-			}
 			process.exit(1);
 		}
 
@@ -459,15 +456,12 @@ function resolveOne(db: Database, symbol: string): Node {
 	const nodes = resolveSymbol(db, symbol);
 	if (nodes.length === 0) {
 		db.close();
-		console.error(`Unknown symbol: ${symbol}`);
+		printUnknownSymbolError(db, symbol);
 		process.exit(1);
 	}
 	if (nodes.length > 1) {
 		db.close();
-		console.error("Ambiguous symbol. Matches:");
-		for (const n of nodes) {
-			console.error(`  ${n.id}`);
-		}
+		printAmbiguousSymbolError(nodes);
 		process.exit(1);
 	}
 	const node = nodes[0];
@@ -479,6 +473,41 @@ function resolveOne(db: Database, symbol: string): Node {
 	return node;
 }
 
+function printUnknownSymbolError(db: Database, symbol: string): void {
+	console.error(`Unknown symbol: ${symbol}\n`);
+	console.error("Symbol format:");
+	console.error("  function_name                      unique name (if unambiguous)");
+	console.error("  src/file.ts::functionName           file::function");
+	console.error("  src/file.py::Class.method           file::Class.method\n");
+
+	const similar = findSimilarSymbols(db, symbol);
+	if (similar.length > 0) {
+		console.error("Did you mean:");
+		for (const s of similar) {
+			console.error(`  ${s}`);
+		}
+	}
+}
+
+function printAmbiguousSymbolError(nodes: readonly Node[]): void {
+	console.error("Ambiguous symbol. Qualify with file path:\n");
+	for (const n of nodes) {
+		console.error(`  lattice context ${n.id}`);
+	}
+}
+
+function findSimilarSymbols(db: Database, symbol: string): readonly string[] {
+	const lower = symbol.toLowerCase();
+	const parts = lower.split(".");
+	const name = parts[parts.length - 1] ?? lower;
+
+	const rows = db
+		.query("SELECT id, name FROM nodes WHERE LOWER(name) LIKE ? LIMIT 5")
+		.all(`%${name}%`) as { id: string; name: string }[];
+
+	return rows.map((r) => r.id);
+}
+
 /** Builds a flow tree by recursively following call edges from a root node. */
 function buildFlowTree(
 	db: Database,

package/src/types/result.ts

@@ -32,7 +32,7 @@ function isErr<T, E>(result: Result<T, E>): result is Err<E> {
 
 /**
  * Extracts the data from an Ok result or throws on Err.
- * Only use at program boundaries — prefer pattern matching elsewhere.
+ * Only use at program boundaries - prefer pattern matching elsewhere.
  *
  * @param result - The result to unwrap
  * @returns The data inside the Ok variant