@soederpop/luca 0.0.23 → 0.0.26

package/AGENTS.md

@@ -36,7 +36,7 @@ On the frontend the browser container is perfect for highly reactive, stateful w
 - The container is intended to provide a collection of blessed, approved, audited modules that we've built and curated together.  It is intended to be the primary API and interface through the system  
 - The container should provide you with everything you need, and you should not need to be importing dependencies or other modules.  If you find yourself stuck by this constraint, raise this concern, and we can work on finding a way to bring in a feature or client
 - When trying to find paths in the project, use `container.paths.resolve()` or `container.paths.join()` instead of `import { resolve } from 'path'`
-- **NEVER import from `fs`, `path`, or other Node builtins when the container provides equivalents.** Use `container.feature('fs')` for file operations, `container.paths` for path operations. This applies to command handlers, scripts, and any code that has access to a container. The only exception is inside feature implementations themselves (e.g. `proc.ts`, `fs.ts`) where you ARE building the container primitive — those may use Node builtins directly since they can't depend on themselves.
+- **NEVER import from `fs`, `path`, or other Node builtins when the container provides equivalents.** Use `container.feature('fs')` for file operations, `container.paths` for path operations. This applies everywhere — command handlers, scripts, and feature implementations alike. If a container feature wraps the functionality, use it.
 
 ## Container Utilities
 

package/CLAUDE.md

@@ -31,12 +31,17 @@ On the frontend the browser container is perfect for highly reactive, stateful w
 
 **IMPORTANT NOTE** When trying to investigate features, clients, servers, etc, see if these tools can help you first instead of searching for files and reading them that way.  If youw ant to understand what they do, vs how theyre actually implemented
 
+## OpenAI Tool Schemas (Zod → JSON Schema)
+
+**OpenAI requires `required` to list ALL property keys in `properties`**, even optional ones. Zod's `toJSONSchema()` only puts non-optional fields in `required`, which OpenAI rejects with "Missing 'X'" errors. The `assistant.addTool()` method handles this automatically by always setting `required: Object.keys(properties)`. Do NOT use `z.any()` or `z.record(z.any())` in tool schemas — Zod v4's `toJSONSchema()` cannot serialize `z.any()` and will throw `schema._zod is undefined`. Use concrete types like `z.string()` instead (e.g. accept a JSON string and parse it at runtime).
+
 ## Coding style and guidelines
 
 - The container is intended to provide a collection of blessed, approved, audited modules that we've built and curated together.  It is intended to be the primary API and interface through the system  
 - The container should provide you with everything you need, and you should not need to be importing dependencies or other modules.  If you find yourself stuck by this constraint, raise this concern, and we can work on finding a way to bring in a feature or client
 - When trying to find paths in the project, use `container.paths.resolve()` or `container.paths.join()` instead of `import { resolve } from 'path'`
-- **NEVER import from `fs`, `path`, or other Node builtins when the container provides equivalents.** Use `container.feature('fs')` for file operations, `container.paths` for path operations. This applies to command handlers, scripts, and any code that has access to a container. The only exception is inside feature implementations themselves (e.g. `proc.ts`, `fs.ts`) where you ARE building the container primitive — those may use Node builtins directly since they can't depend on themselves.
+- **`paths.join()` vs `paths.resolve()` gotcha:** `paths.join()` always prepends `container.cwd` — even if you pass an absolute path as the first arg. Use `paths.resolve(absolutePath, 'sub')` when the base is already absolute (e.g. `os.tmpdir`). `resolve` respects absolute first args just like Node's `path.resolve`.
+- **NEVER import from `fs`, `path`, or other Node builtins when the container provides equivalents.** Use `container.feature('fs')` for file operations, `container.paths` for path operations. This applies everywhere — command handlers, scripts, and feature implementations alike. If a container feature wraps the functionality, use it.
 
 ## Container Utilities
 

package/assistants/codingAssistant/hooks.ts

@@ -1,3 +1,2 @@
 export function started() {
-	console.log('Assistant started!')
 }

package/assistants/lucaExpert/CORE.md

@@ -0,0 +1,37 @@
+# Luca Framework Expert
+
+You are a Luca framework expert. You have deep knowledge of the container architecture, its features, clients, servers, commands, and how to build with them. Your job is to help people understand, use, and build on the Luca framework.
+
+You have powerful tools to explore the framework at runtime — use them liberally before answering questions. Don't guess when you can look it up.
+
+## Your Tools
+
+### Discovery & Documentation
+
+- **readSkill** — Read the SKILL.md learning guide and follow referenced documentation. Start here when orienting yourself.
+- **readDoc** — Read any document from the docs/ folder: examples, tutorials, API references, scaffolds. Use `list` mode to browse what's available in a category, or `read` mode to get the full content.
+- **lucaDescribe** — Run `luca describe` to get live documentation for any feature, client, server, or specific method/getter. This is generated from the actual source code and is always current. Use dot notation (`fs.readFile`, `ui.banner`) to drill into specific members.
+
+### Live Code Execution
+
+- **lucaEval** — Execute JavaScript/TypeScript in a live container sandbox. All features are available as top-level variables (fs, git, proc, vm, etc). The last expression's value is returned. For async code, put the await call as the last expression.
+
+### Deep Research
+
+- **askCodingAssistant** — Delegate deep codebase research to the coding assistant, who has ripgrep, cat, ls, sed, and awk at its disposal. Use this when you need to understand implementation details, trace code paths, or find patterns across files that the documentation doesn't cover.
+
+## How to Work
+
+1. **Start with describe.** When asked about any feature, client, or server — run `lucaDescribe` first. It's the fastest path to accurate information.
+2. **Consult docs for depth.** Use `readDoc` to pull up examples, tutorials, and API docs when you need patterns, best practices, or complete working code.
+3. **Eval to verify.** When uncertain about behavior, run it. `lucaEval` gives you a live container — test the actual API rather than speculating.
+4. **Delegate research.** When you need to understand how something is implemented (not just how to use it), ask the codingAssistant to dig into the source.
+5. **Read the SKILL.md** via `readSkill` when you need to orient a user to the framework's learning path.
+
+## Response Style
+
+- Lead with working code examples when possible
+- Reference specific methods and their signatures
+- Explain the "why" behind patterns, not just the "what"
+- When a user's approach conflicts with framework conventions, explain the idiomatic way and why it matters
+- Be concise but thorough — framework users need precision

package/assistants/lucaExpert/hooks.ts

@@ -0,0 +1,9 @@
+import type { Assistant } from '@soederpop/luca/agi'
+
+declare global {
+	var assistant: Assistant
+}
+
+export function started() {
+	console.log('Luca Expert assistant started')
+}

package/assistants/lucaExpert/tools.ts

@@ -0,0 +1,177 @@
+import { z } from 'zod'
+import type { Assistant, AGIContainer } from '@soederpop/luca/agi'
+
+declare global {
+	var assistant: Assistant
+	var container: AGIContainer
+}
+
+const proc = () => container.feature('proc')
+const fs = () => container.feature('fs')
+
+// ---------------------------------------------------------------------------
+// readSkill — Read the SKILL.md and progressively discover referenced docs
+// ---------------------------------------------------------------------------
+
+export const schemas = {
+	readSkill: z.object({
+		section: z.string().default('').describe(
+			'Section to focus on (e.g. "Phase 1", "Phase 2", "Key Concepts"). Leave empty for the full SKILL.md.'
+		),
+	}).describe('Read the SKILL.md learning guide for the Luca framework. Use this to orient yourself or a user to how the framework is learned and used.'),
+
+	readDoc: z.object({
+		mode: z.enum(['list', 'read']).describe(
+			'"list" to browse available documents in a category, "read" to get full content of a specific document'
+		),
+		category: z.string().default('').describe(
+			'Document category: examples, tutorials, apis, apis/features/node, apis/features/agi, apis/features/web, apis/clients, apis/servers, challenges, prompts, scaffolds, sessions, bootstrap. Leave empty when using mode "read".'
+		),
+		path: z.string().default('').describe(
+			'Relative path within docs/ to read (e.g. "examples/fs.md", "tutorials/00-bootstrap.md"). Required when mode is "read". Leave empty when using mode "list".'
+		),
+	}).describe('Browse and read documentation from the docs/ folder — examples, tutorials, API references, scaffolds, and more.'),
+
+	lucaDescribe: z.object({
+		args: z.string().describe(
+			'Arguments to pass to luca describe. Examples: "fs", "git", "features", "clients", "servers", "fs.readFile", "ui.banner", "express --options", "fs --methods", "fs git --examples"'
+		),
+	}).describe('Run the luca describe CLI to get live, source-generated documentation for any feature, client, server, or specific method/getter. This is always current.'),
+
+	lucaEval: z.object({
+		code: z.string().describe(
+			'JavaScript/TypeScript code to run in a live container. All features available as top-level vars (fs, git, proc, vm, etc). The last expression value is returned. For async: put the await expression on the last line.'
+		),
+	}).describe('Execute code in a live Luca container sandbox. Use this to test APIs, verify behavior, and prototype ideas. Top-level await is supported — put async calls as the last expression to capture their result.'),
+
+	askCodingAssistant: z.object({
+		question: z.string().describe(
+			'A research question for the coding assistant. Be specific about what you want to find: file paths, function implementations, patterns, class hierarchies, etc.'
+		),
+	}).describe('Delegate deep codebase research to the coding assistant who has ripgrep, cat, ls, sed, and awk. Use for implementation details, tracing code paths, or finding patterns the docs do not cover.'),
+}
+
+export function readSkill({ section }: z.infer<typeof schemas.readSkill>): string {
+	const skillPath = 'docs/bootstrap/SKILL.md'
+
+	if (!fs().exists(skillPath)) {
+		return 'SKILL.md not found at docs/bootstrap/SKILL.md'
+	}
+
+	const content = fs().readFile(skillPath)
+
+	if (!section || !section.trim()) return content
+
+	// Extract section by heading match
+	const lines = content.split('\n')
+	const sectionLines: string[] = []
+	let capturing = false
+	let sectionLevel = 0
+
+	for (const line of lines) {
+		const headingMatch = line.match(/^(#{1,6})\s+(.*)/)
+
+		if (headingMatch) {
+			const level = headingMatch[1].length
+			const title = headingMatch[2]
+
+			if (capturing && level <= sectionLevel) break
+
+			if (title.toLowerCase().includes(section.toLowerCase())) {
+				capturing = true
+				sectionLevel = level
+			}
+		}
+
+		if (capturing) sectionLines.push(line)
+	}
+
+	return sectionLines.length > 0
+		? sectionLines.join('\n')
+		: `Section "${section}" not found in SKILL.md. Available sections:\n${lines.filter(l => l.startsWith('#')).join('\n')}`
+}
+
+export function readDoc({ mode, category, path: docPath }: z.infer<typeof schemas.readDoc>): string {
+	if (mode === 'list') {
+		const dir = category ? `docs/${category}` : 'docs'
+
+		if (!fs().exists(dir)) {
+			return `Directory "${dir}" not found. Available top-level categories:\n${fs().readdirSync('docs').join('\n')}`
+		}
+
+		const entries = fs().readdirSync(dir)
+		return `Contents of ${dir}/:\n${entries.join('\n')}`
+	}
+
+	// mode === 'read'
+	if (!docPath) {
+		return 'Error: path is required when mode is "read". Use mode "list" to browse available docs first.'
+	}
+
+	const fullPath = docPath.startsWith('docs/') ? docPath : `docs/${docPath}`
+
+	if (!fs().exists(fullPath)) {
+		return `Document not found: ${fullPath}`
+	}
+
+	return fs().readFile(fullPath)
+}
+
+export function lucaDescribe({ args }: z.infer<typeof schemas.lucaDescribe>): string {
+	try {
+		return proc().exec(`bun run src/cli/cli.ts describe ${args}`)
+	} catch (err: any) {
+		return `Error running luca describe ${args}: ${err.message || err}`
+	}
+}
+
+export async function lucaEval({ code }: z.infer<typeof schemas.lucaEval>): Promise<string> {
+	try {
+		const vm = container.feature('vm')
+		const { result, console: calls } = await vm.runCaptured(code, {
+			container,
+			fs: container.feature('fs'),
+			git: container.feature('git'),
+			proc: container.feature('proc'),
+			vm,
+			ui: container.feature('ui'),
+			os: container.feature('os'),
+			grep: container.feature('grep'),
+			networking: container.feature('networking'),
+		})
+
+		const parts: string[] = []
+
+		if (calls.length > 0) {
+			const consoleLines = calls.map(c => {
+				const prefix = c.method === 'log' ? '' : `[${c.method}] `
+				return prefix + c.args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' ')
+			})
+			parts.push(consoleLines.join('\n'))
+		}
+
+		if (result === undefined) {
+			parts.push('(undefined)')
+		} else if (result === null) {
+			parts.push('(null)')
+		} else if (typeof result === 'string') {
+			parts.push(result)
+		} else {
+			try { parts.push(JSON.stringify(result, null, 2)) } catch { parts.push(String(result)) }
+		}
+
+		return parts.join('\n')
+	} catch (err: any) {
+		return `Eval error: ${err.message || err}`
+	}
+}
+
+export async function askCodingAssistant({ question }: z.infer<typeof schemas.askCodingAssistant>): Promise<string> {
+	try {
+		const sub = await assistant.subagent('codingAssistant')
+		const answer = await sub.ask(question)
+		return answer
+	} catch (err: any) {
+		return `Error asking coding assistant: ${err.message || err}`
+	}
+}

package/commands/build-bootstrap.ts

@@ -41,6 +41,30 @@ async function buildBootstrap(options: z.infer<typeof argsSchema>, context: Cont
 		}
 	}
 
+	// 3. Collect docs/examples/*.md
+	const examples: Record<string, string> = {}
+	const examplesDir = 'docs/examples'
+	if (fs.exists(examplesDir)) {
+		const exampleFiles = (await fs.readdir(examplesDir)).filter((f: string) => f.endsWith('.md'))
+		for (const file of exampleFiles) {
+			const content = await fs.readFileAsync(`${examplesDir}/${file}`)
+			examples[file] = content
+			console.log(`   example/${file}: ${content.length} chars`)
+		}
+	}
+
+	// 4. Collect docs/tutorials/*.md
+	const tutorials: Record<string, string> = {}
+	const tutorialsDir = 'docs/tutorials'
+	if (fs.exists(tutorialsDir)) {
+		const tutorialFiles = (await fs.readdir(tutorialsDir)).filter((f: string) => f.endsWith('.md'))
+		for (const file of tutorialFiles) {
+			const content = await fs.readFileAsync(`${tutorialsDir}/${file}`)
+			tutorials[file] = content
+			console.log(`   tutorial/${file}: ${content.length} chars`)
+		}
+	}
+
 	const escapeForTemplate = (s: string) => s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
 
 	const fileEntries = Object.entries(entries).map(([name, content]) =>
@@ -51,9 +75,17 @@ async function buildBootstrap(options: z.infer<typeof argsSchema>, context: Cont
 		`  ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
 	).join(',\n')
 
+	const exampleEntries = Object.entries(examples).map(([name, content]) =>
+		`  ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
+	).join(',\n')
+
+	const tutorialEntries = Object.entries(tutorials).map(([name, content]) =>
+		`  ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
+	).join(',\n')
+
 	const output = `// Auto-generated bootstrap content
 // Generated at: ${new Date().toISOString()}
-// Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
+// Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap
 
@@ -64,6 +96,14 @@ ${fileEntries}
 export const bootstrapTemplates: Record<string, string> = {
 ${templateEntries}
 }
+
+export const bootstrapExamples: Record<string, string> = {
+${exampleEntries}
+}
+
+export const bootstrapTutorials: Record<string, string> = {
+${tutorialEntries}
+}
 `
 
 	fs.ensureFolder('src/bootstrap')

package/docs/TABLE-OF-CONTENTS.md

@@ -120,7 +120,6 @@
 - [OpenAICodex (features.openaiCodex)](./apis/features/agi/openai-codex.md)
 - [OpenAPI (features.openapi)](./apis/features/agi/openapi.md)
 - [SemanticSearch (features.semanticSearch)](./apis/features/agi/semantic-search.md)
-- [SkillsLibrary (features.skillsLibrary)](./apis/features/agi/skills-library.md)
 - [ContainerLink (features.containerLink)](./apis/features/node/container-link.md)
 - [ContentDb (features.contentDb)](./apis/features/node/content-db.md)
 - [DiskCache (features.diskCache)](./apis/features/node/disk-cache.md)

package/docs/apis/clients/rest.md

@@ -40,7 +40,7 @@ Send a PATCH request.
 | `data` | `any` |  | Request body |
 | `options` | `AxiosRequestConfig` |  | Additional axios request config |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 
 
@@ -56,7 +56,7 @@ Send a PUT request.
 | `data` | `any` |  | Request body |
 | `options` | `AxiosRequestConfig` |  | Additional axios request config |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 
 
@@ -72,7 +72,7 @@ Send a POST request.
 | `data` | `any` |  | Request body |
 | `options` | `AxiosRequestConfig` |  | Additional axios request config |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 
 
@@ -88,7 +88,7 @@ Send a DELETE request.
 | `params` | `any` |  | Query parameters |
 | `options` | `AxiosRequestConfig` |  | Additional axios request config |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 
 
@@ -104,7 +104,7 @@ Send a GET request.
 | `params` | `any` |  | Query parameters |
 | `options` | `AxiosRequestConfig` |  | Additional axios request config |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 
 

package/docs/apis/features/agi/assistant.md

@@ -1,6 +1,6 @@
 # Assistant (features.assistant)
 
-An Assistant is a combination of a system prompt and tool calls that has a conversation with an LLM. You define an assistant by creating a folder with CORE.md (system prompt), tools.ts (tool implementations), and hooks.ts (event handlers).
+An Assistant is a wrapper around an LLM chat thread where you supply a system prompt and tools. You can optionally use a folder to load the system prompt (CORE.md), tool implementations (tools.ts), and event hooks (hooks.ts) from disk. The AssistantsManager feature will automatically discover any assistant definitions that live on disk in your project.
 
 ## Usage
 

package/docs/apis/features/agi/conversation-history.md

@@ -1,14 +1,14 @@
 # ConversationHistory (features.conversationHistory)
 
-Persists conversations to disk using the diskCache feature (cacache). Each conversation is stored as a JSON blob keyed by ID, with metadata stored alongside for efficient listing and search without loading full message arrays.
+A queryable store, backed by the file system, for maintaining conversation history and easily restoring it. Each conversation is stored as a JSON record keyed by ID, with lightweight metadata stored alongside for efficient listing and search without loading full message arrays.
 
 ## Usage
 
 ```ts
 container.feature('conversationHistory', {
-  // Custom cache directory for conversation storage
+  // Directory for conversation storage
   cachePath,
-  // Namespace prefix for cache keys to isolate datasets
+  // Namespace prefix to isolate datasets
   namespace,
 })
 ```
@@ -17,8 +17,8 @@ container.feature('conversationHistory', {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `cachePath` | `string` | Custom cache directory for conversation storage |
-| `namespace` | `string` | Namespace prefix for cache keys to isolate datasets |
+| `cachePath` | `string` | Directory for conversation storage |
+| `namespace` | `string` | Namespace prefix to isolate datasets |
 
 ## Methods
 
@@ -307,8 +307,7 @@ Delete all conversations matching a thread prefix.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `diskCache` | `DiskCache` |  |
-| `namespace` | `string` |  |
+| `namespace` | `string` | The namespace prefix used for key isolation |
 
 ## Events (Zod v4 schema)
 

package/docs/apis/features/agi/conversation.md

@@ -1,6 +1,6 @@
 # Conversation (features.conversation)
 
-A self-contained conversation with OpenAI that supports streaming, tool calling, and message state management.
+An observable conversation class that enables long-running chat threads with an LLM. Supports streaming responses, tool calling with automatic handler dispatch, message state management, and context window compaction. Works with both local (Ollama) and remote (OpenAI) backends.
 
 ## Usage
 

package/docs/apis/features/agi/semantic-search.md

@@ -1,6 +1,6 @@
 # SemanticSearch (features.semanticSearch)
 
-No description provided
+A vector search engine backed by SQLite that indexes documents with embeddings for semantic, keyword, and hybrid search. Supports local GGUF embedding models and configurable chunking strategies for splitting documents into searchable segments.
 
 ## Usage
 

package/docs/bootstrap/CLAUDE.md

@@ -32,7 +32,7 @@ The `luca` binary is available in the path. Key commands:
 1. **Discover** — Run `luca describe features`, `luca describe clients`, `luca describe servers` to see what's available. Then `luca describe <name>` for full docs on any helper, or `luca describe <name>.<member>` to drill into a specific method or getter. This is your first move, always. (See `.claude/skills/luca-framework/SKILL.md` for the full mental model.)
 2. **Build** — Run `luca scaffold <type> --tutorial` before creating a new helper. It covers the full guide for that type.
 3. **Prototype** — Use `luca eval "expression"` to test container code before wiring up full handlers. Reach for eval when you're stuck — it gives you full runtime access.
-4. **Reference** — Browse `.claude/skills/luca-framework/references/api-docs/` for pre-generated API docs
+4. **Reference** — Browse `.claude/skills/luca-framework/references/` for pre-generated API docs, runnable examples, and tutorials
 
 ## Project Structure
 

package/docs/bootstrap/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: Using the luca framework
-description: Learn the luca container — discover what's available with luca describe, build new helpers with luca scaffold, and prototype with luca eval
+description: The @soederpop/luca framework, when you see a project with docs/ commands/ features/ luca.cli.ts endpoints/ folders, or @soederpop/luca is in the package.json, or the user is asking you to develop a new Luca feature, use this skill to learn about the APIs and how to learn the framework at runtime.  The luca cli bundles all of the documentation in a searchable, progressively learnable interface designed for students and AI assistants alike
 ---
 # Luca: Learning the Container
 
 The Luca framework `@soederpop/luca` ships a `luca` binary — a bun-based CLI for a dependency injection container. This project is based on it if this skill is present. The container auto-discovers modules in `commands/`, `clients/`, `servers/`, `features/`, and `endpoints/` folders.
 
+The `luca` cli loads typescript modules in through its VM which injects a `container` global that is a singleton object from which you can learn about, and access all different kinds of utils and Helpers (features, clients, servers, commands, and compositions thereof)
+
 There are three things to learn, in this order:
 
 1. **Discover** what the container can do — `luca describe`
 2. **Build** new helpers when your project needs them — `luca scaffold`
 3. **Prototype** and debug with live code — `luca eval`
-
+4. **Write Runnable Markdown** a great usecase is `luca run markdown.md` where the markdown codeblocks are executed inside the Luca VM.
 ---
 
 ## Phase 1: Discover with `luca describe`
@@ -248,4 +250,6 @@ This is useful inside commands and scripts where you need introspection data pro
 
 ## Reference
 
-See `references/api-docs/` for the full pre-generated API reference for every built-in feature, client, and server.
+- `references/api-docs/` — full pre-generated API reference for every built-in feature, client, and server
+- `references/examples/` — runnable example docs for each feature (e.g. `fs.md`, `git.md`, `proc.md`)
+- `references/tutorials/` — step-by-step tutorials covering the container, helpers, commands, endpoints, and more

package/docs/bootstrap/templates/luca-cli.ts

@@ -22,4 +22,9 @@
 export async function main(container: any) {
   // Discover project-level helpers (commands/, features/, endpoints/)
   await container.helpers.discoverAll()
+
+  // Handle unknown commands gracefully instead of silently failing
+  container.onMissingCommand(async ({ phrase }: { phrase: string }) => {
+    container.command('help').dispatch()
+  })
 }

package/docs/mcp/readme.md

@@ -17,7 +17,7 @@ import { Server, servers, ServerStateSchema } from '@soederpop/luca'
 import { commands, CommandOptionsSchema } from '@soederpop/luca'
 ```
 
-Never import from `fs`, `path`, `crypto`, or other Node builtins. Never import third-party packages in consumer code. The only exception is inside helper implementations themselves — a feature that wraps a library may import it.
+Never import from `fs`, `path`, `crypto`, or other Node builtins. Never import third-party packages in consumer code. If a container feature wraps the functionality, use it.
 
 ## Zod v4
 

package/docs/tutorials/00-bootstrap.md

@@ -140,6 +140,24 @@ luca eval "grep.search('.', 'TODO')"
 | Full container overview?       | `container.inspectAsText()`            |
 | CLI docs for a helper?         | `luca describe <name>`                 |
 
+## Gotchas
+
+### `paths.join()` vs `paths.resolve()`
+
+`container.paths.join()` and `container.paths.resolve()` are Node's `path.join` and `path.resolve` curried with `container.cwd`. This means `paths.join()` always prepends `cwd` — even if you pass an absolute path as the first argument.
+
+```js
+// WRONG — paths.join will prepend cwd to the absolute tmpdir path
+const bad = container.paths.join(os.tmpdir, 'mydir')
+// => "/your/project/tmp/mydir" (not what you want)
+
+// RIGHT — paths.resolve respects absolute first args
+const good = container.paths.resolve(os.tmpdir, 'mydir')
+// => "/tmp/mydir"
+```
+
+**Rule of thumb:** Use `paths.join()` for project-relative paths, `paths.resolve()` when the base is already absolute.
+
 ## What's Next
 
 - [The Container](./02-container.md) — deep dive into state, events, and lifecycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.23",
+  "version": "0.0.26",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",
@@ -48,7 +48,7 @@
     "clean": "rm -rf dist build package",
     "build:web": "bun run scripts/build-web.ts",
     "build:introspection": "bun run src/cli/cli.ts introspect",
-    "compile": "bun run build:introspection && bun run build:scaffolds && bun run build:bootstrap && bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
+    "compile": "bun run build:introspection && bun run build:scaffolds && bun run build:bootstrap && bash scripts/stamp-build.sh && bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build:scaffolds": "bun run src/cli/cli.ts build-scaffolds",
     "build:bootstrap": "bun run src/cli/cli.ts build-bootstrap",

package/scripts/stamp-build.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Stamps git SHA, branch, and date into src/cli/build-info.ts before compile
+SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+cat > src/cli/build-info.ts <<EOF
+// Generated at compile time — do not edit manually
+export const BUILD_SHA = '${SHA}'
+export const BUILD_BRANCH = '${BRANCH}'
+export const BUILD_DATE = '${DATE}'
+EOF

package/scripts/test-docs-reader.ts

@@ -0,0 +1,10 @@
+import container from  '@soederpop/luca/agi'
+
+const reader = container.feature('docsReader', {
+	contentDb: (await container.docs.load())
+})
+
+const resp = await reader.ask('What tutorials are available? What are they about?')
+
+console.log(resp)
+

package/src/agi/container.server.ts

@@ -6,10 +6,11 @@ import { ElevenLabsClient } from '../clients/elevenlabs'
 import { ClaudeCode } from './features/claude-code'
 import { OpenAICodex } from './features/openai-codex'
 import { Conversation } from './features/conversation'
-import { SkillsLibrary } from './features/skills-library'
 import { ConversationHistory } from './features/conversation-history'
 import { Assistant } from './features/assistant'
 import { AssistantsManager } from './features/assistants-manager'
+import { DocsReader } from './features/docs-reader'
+import { SkillsLibrary } from './features/skills-library'
 import { SemanticSearch } from '@soederpop/luca/node/features/semantic-search'
 import { ContentDb } from '@soederpop/luca/node/features/content-db'
 
@@ -20,10 +21,11 @@ export {
 	ClaudeCode,
 	OpenAICodex,
 	Conversation,
-	SkillsLibrary,
 	ConversationHistory,
 	Assistant,
 	AssistantsManager,
+	DocsReader,
+	SkillsLibrary,
 	SemanticSearch,
 	ContentDb,
 	NodeContainer,
@@ -42,10 +44,11 @@ export interface AGIFeatures extends NodeFeatures {
 	conversation: typeof Conversation
 	claudeCode: typeof ClaudeCode
 	openaiCodex: typeof OpenAICodex
-	skillsLibrary: typeof SkillsLibrary
 	conversationHistory: typeof ConversationHistory
 	assistant: typeof Assistant
 	assistantsManager: typeof AssistantsManager
+	docsReader: typeof DocsReader
+	skillsLibrary: typeof SkillsLibrary
 }
 
 export interface ConversationFactoryOptions {
@@ -73,7 +76,6 @@ export class AGIContainer<
 	openai!: OpenAIClient
 	claudeCode?: ClaudeCode
 	openaiCodex?: OpenAICodex
-	skillsLibrary?: SkillsLibrary
 	conversationHistory?: ConversationHistory
 	docs!: ContentDb
 
@@ -114,10 +116,11 @@ const container = new AGIContainer()
 	.use(ClaudeCode)
 	.use(OpenAICodex)
 	.use(Conversation)
-	.use(SkillsLibrary)
 	.use(ConversationHistory)
 	.use(Assistant)
 	.use(AssistantsManager)
+	.use(DocsReader)
+	.use(SkillsLibrary)
 	.use(SemanticSearch)
 
 container.docs = container.feature('contentDb', {