@soederpop/luca 0.0.32 → 0.0.35

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-24T09:09:11.574Z
+// Generated at: 2026-03-27T03:29:28.307Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -25,7 +25,7 @@ There are three things to learn, in this order:
 
 ## Phase 1: Discover with \`luca describe\`
 
-This is your primary tool. Before reading source files, searching for APIs, or writing any code — ask describe. It outputs full documentation for any part of the container: methods, options, events, state, examples.
+This is your primary tool. The \`luca\` binary is a compiled artifact that bundles all introspection data — it is the authority on what the container provides. Run \`luca describe\` first — it outputs full documentation for any part of the container: methods, options, events, state, examples. Reading source can be helpful for additional context if it exists in the project, but the source for built-in helpers may not be present — the binary is always the ground truth.
 
 ### See what's available
 
@@ -77,6 +77,18 @@ luca describe fs git --examples     # just examples for both
 luca describe fs --usage --methods  # combine sections
 \`\`\`
 
+### Get approximate TypeScript types
+
+Need to know the shape of a helper for type-safe code? Use \`--ts\`:
+
+\`\`\`shell
+luca describe fs --ts              # approximate TS interface for fs
+luca describe conversation --ts    # see the conversation feature's type surface
+luca describe rest --ts            # client type shape
+\`\`\`
+
+This outputs a ~95% accurate TypeScript representation based on runtime introspection. If a type looks wrong or a method signature seems off, verify with \`luca eval\` against the live instance.
+
 ### Describe the container itself
 
 \`\`\`shell
@@ -92,7 +104,9 @@ luca describe --help       # full flag reference for describe
 luca help scaffold         # help for any command
 \`\`\`
 
-**Use \`luca describe\` liberally.** It is the fastest, safest way to understand what the container provides. Every feature, client, and server is self-describing — if you know a name, describe will tell you everything about it. Use dot notation (\`ui.banner\`, \`fs.readFile\`) when you need docs on just one method or getter.
+**Use \`luca describe\` liberally.** It is the fastest, safest way to understand what the container provides. Every feature, client, and server is self-describing — if you know a name, describe will tell you everything about it. Use dot notation (\`ui.banner\`, \`fs.readFile\`) when you need docs on just one method or getter. Use \`--ts\` when you need type information for writing code.
+
+> **NOTE:** The \`luca\` binary is compiled and bundles all introspection data. \`luca describe\` reflects what actually ships in the binary — source files for built-in helpers may not exist in your project. Reading source can add context when it's available, but \`luca describe\` and \`luca eval\` are always the authority.
 
 ---
 
@@ -239,7 +253,7 @@ Everything \`luca describe\` outputs is also available at runtime in code:
 \`\`\`js
 container.features.describe('fs')   // markdown docs (same as the CLI)
 feature.introspect()                // structured object: { methods, events, state, options }
-container.inspectAsText()           // full container overview as markdown
+container.introspectAsText()           // full container overview as markdown
 \`\`\`
 
 This is useful inside commands and scripts where you need introspection data programmatically.
@@ -255,11 +269,83 @@ This is useful inside commands and scripts where you need introspection data pro
 - \`luca serve --any-port\` will open on any port
 
 
-## Reference
+## Framework Index
+
+A table of contents for the container. **Run \`luca describe <name>\` for full docs on any item.** Use \`luca describe <name> --ts\` when you need type information. Source may not exist locally for built-in helpers — the compiled binary is the authority.
+
+### Features by Category
+
+| Category | Features | What they do |
+|----------|----------|--------------|
+| **File System & Code** | \`fs\`, \`grep\`, \`fileManager\` | Read/write files, search code, watch for changes |
+| **Process & Shell** | \`proc\`, \`processManager\`, \`secureShell\` | Run commands, manage long-running processes, SSH |
+| **AI Assistants** | \`assistant\`, \`assistantsManager\`, \`conversation\`, \`conversationHistory\`, \`fileTools\` | Build AI assistants, manage conversations, tool calling. \`fileTools\` composes lower-level features (\`fs\`, \`grep\`) into an assistant-ready tool surface — a good example of how features can define tools for assistants (see \`references/examples/feature-as-tool-provider.md\`). |
+| **AI Agent Wrappers** | \`claudeCode\`, \`openaiCodex\`, \`lucaCoder\` | Spawn and manage external AI agent CLIs as subprocesses |
+| **Data & Storage** | \`sqlite\`, \`postgres\`, \`diskCache\`, \`contentDb\`, \`redis\` | Databases, caching, document management |
+| **Networking** | \`networking\`, \`dns\` | Network utilities, DNS |
+| **Google Workspace** | \`googleAuth\`, \`googleDrive\`, \`googleDocs\`, \`googleSheets\`, \`googleCalendar\`, \`googleMail\` | OAuth and Google service wrappers |
+| **Dev Tools** | \`git\`, \`docker\`, \`esbuild\`, \`vm\`, \`python\`, \`packageFinder\` | Version control, containers, bundling, sandboxed execution |
+| **Content & NLP** | \`docsReader\`, \`nlp\`, \`semanticSearch\`, \`skillsLibrary\`, \`jsonTree\`, \`yamlTree\` | Document Q&A, text analysis, semantic search, skills, structured file ingestion |
+| **UI & Output** | \`ui\`, \`ink\`, \`yaml\` | Terminal UI, colors, ascii art, structured data display |
+| **Media & Browser** | \`browserUse\`, \`tts\`, \`downloader\`, \`opener\`, \`telegram\` | Browser automation, text-to-speech, downloads, messaging |
+| **System** | \`os\`, \`vault\`, \`helpers\`, \`introspectionScanner\`, \`containerLink\`, \`repl\`, \`runpod\` | OS info, secrets, runtime introspection, remote container linking |
+
+### Clients
+
+| Client | Purpose |
+|--------|---------|
+| \`openai\` | Chat completions, embeddings, image generation |
+| \`rest\` | Generic HTTP client (GET/POST/PUT/PATCH/DELETE) |
+| \`websocket\` | WebSocket connections |
+| \`elevenlabs\` | Text-to-speech synthesis |
+| \`graph\` | GraphQL queries and mutations |
+
+### Servers
+
+| Server | Purpose |
+|--------|---------|
+| \`express\` | HTTP server with file-based endpoint routing |
+| \`mcp\` | Model Context Protocol server for AI tool exposure |
+| \`websocket\` | WebSocket server with JSON framing |
+| \`ipcSocket\` | Local IPC socket server for inter-process communication |
+
+### Type Discovery
+
+\`luca describe <name> --ts\` outputs an approximate TypeScript representation of any helper as it exists at runtime — ~95% accurate. This is your go-to for writing type-safe code against the container. The binary compiles in the introspection data, so \`--ts\` reflects what actually exists at runtime even when source isn't available. Reading source can provide additional context when it's there.
+
+\`\`\`shell
+luca describe fs --ts              # approximate TS interface for the fs feature
+luca describe conversation --ts    # conversation feature type surface
+luca describe express --ts         # express server type shape
+\`\`\`
+
+If a method signature or return type looks wrong, verify with \`luca eval\`:
+
+\`\`\`shell
+luca eval "typeof container.feature('fs').readFile"
+luca eval "container.feature('fs').readFile('package.json')"
+\`\`\`
+
+### Bundled Examples and Tutorials
+
+The skill directory includes reference material:
+
+- **\`references/examples/\`** — short, focused example docs for individual features (e.g. \`fs.md\`, \`git.md\`, \`proc.md\`)
+- **\`references/tutorials/\`** — longer-form guides covering the container, helpers, commands, endpoints, state/events, assistants, and more
+
+These complement \`luca describe\` — describe gives you the API surface, examples show you patterns in action, and tutorials walk through building things end to end.
+
+**Tip:** Runnable markdown is a great artifact to produce when building with luca. \`luca run doc.md\` executes code blocks inside the Luca VM — useful for both testing and documentation. When prototyping a feature or writing a how-to, consider writing it as a markdown file that can be run.
+
+### Container Primitives
 
-- \`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
+| Primitive | Access | Purpose |
+|-----------|--------|---------|
+| State | \`container.state\`, \`helper.state\` | Observable key-value state on every object |
+| Events | \`container.on()\`, \`helper.on()\` | Event bus on every object |
+| Paths | \`container.paths\` | \`resolve()\`, \`join()\`, \`cwd\` |
+| Utils | \`container.utils\` | \`uuid()\`, \`lodash\`, \`stringUtils\`, \`hashObject()\` |
+| Registries | \`container.features\`, \`.clients\`, \`.servers\` | Discovery and metadata for all helpers |
 `,
   "CLAUDE": `# Luca Project
 
@@ -295,7 +381,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/\` for pre-generated API docs, runnable examples, and tutorials
+4. **Reference** — The skill file (\`.claude/skills/luca-framework/SKILL.md\`) includes a full Framework Index with every feature, client, and server organized by category
 
 ## Project Structure
 
@@ -1433,9 +1519,50 @@ console.log('Install exit code:', result.exitCode)
 
 When no \`installCommand\` is provided, the feature infers the correct command from the detected environment type (e.g., \`uv sync\` for uv, \`pip install -e .\` for venv).
 
+## Persistent Sessions
+
+Start a long-lived Python process where state persists across calls. Ideal for working inside real Python codebases, data analysis, and anything with expensive setup.
+
+\`\`\`ts skip
+const python = container.feature('python', { dir: '/path/to/python-project' })
+await python.enable()
+await python.startSession()
+
+// State persists across calls
+await python.run('x = 42')
+const result = await python.run('print(x * 2)')
+console.log('stdout:', result.stdout) // '84\\n'
+
+// Evaluate expressions and get values back
+const val = await python.eval('x + 1')
+console.log('eval:', val) // 43
+
+// Import project modules (sys.path is set up automatically)
+await python.importModule('json')
+const encoded = await python.call('json.dumps', [{ key: 'value' }], { indent: 2 })
+console.log('call:', encoded)
+
+// Inspect the namespace
+const locals = await python.getLocals()
+console.log('locals:', Object.keys(locals))
+
+// Errors don't crash the session
+const bad = await python.run('raise ValueError("oops")')
+console.log('error:', bad.error) // 'oops'
+
+// Still alive
+const check = await python.run('print("still here")')
+console.log(check.stdout) // 'still here\\n'
+
+// Clean up
+await python.stopSession()
+\`\`\`
+
+See the [Python Sessions tutorial](../tutorials/19-python-sessions.md) for real-world patterns (data pipelines, Django, ML models).
+
 ## Summary
 
-The \`python\` feature bridges Luca and Python by auto-detecting environments, managing dependencies, and providing inline code execution with variable injection. It supports uv, conda, venv, and system Python installations.
+The \`python\` feature bridges Luca and Python by auto-detecting environments, managing dependencies, and providing both stateless execution and persistent sessions. It supports uv, conda, venv, and system Python installations.
 `,
   "yaml.md": `---
 title: "YAML"
@@ -2003,6 +2130,150 @@ Supports pagination via \`pageToken\`, ordering by \`startTime\` or \`updated\`,
 ## Summary
 
 The \`googleCalendar\` feature provides read access to Google Calendar events. Use the convenience methods \`getToday()\` and \`getUpcoming()\` for quick lookups, \`searchEvents()\` for text search, or \`listEvents()\` for full query control. Authentication is handled by \`googleAuth\`. Key methods: \`listCalendars()\`, \`getToday()\`, \`getUpcoming()\`, \`searchEvents()\`, \`listEvents()\`.
+`,
+  "feature-as-tool-provider.md": `---
+title: "Features as Tool Providers for Assistants"
+tags: [feature, tools, assistant, composition, use, setupToolsConsumer]
+lastTested: null
+lastTestPassed: null
+---
+
+# Features as Tool Providers for Assistants
+
+Any feature can expose tools that assistants pick up via \`assistant.use(feature)\`. This is how you compose lower-level container capabilities into an assistant-ready tool surface. The built-in \`fileTools\` feature is the canonical example — it wraps \`fs\` and \`grep\` into a focused set of tools modeled on what coding assistants need.
+
+## The Pattern
+
+A feature becomes a tool provider by defining three things:
+
+1. **\`static tools\`** — a record mapping tool names to Zod schemas with descriptions
+2. **Matching methods** — instance methods whose names match the keys in \`static tools\`
+3. **\`setupToolsConsumer()\`** (optional) — a hook that runs when an assistant calls \`use()\`, perfect for injecting system prompt guidance
+
+When an assistant calls \`assistant.use(feature)\`, the framework:
+- Reads \`static tools\` to register each tool with its schema
+- Routes tool calls to the matching instance methods
+- Calls \`setupToolsConsumer()\` so the feature can configure the assistant (e.g. add system prompt extensions)
+
+## Anatomy of fileTools
+
+Here's the structure of the built-in \`fileTools\` feature (simplified for clarity):
+
+\`\`\`ts
+import { z } from 'zod'
+import { Feature } from '@soederpop/luca/feature'
+
+export class FileTools extends Feature {
+  static { Feature.register(this, 'fileTools') }
+
+  // ── 1. Declare tools with Zod schemas ──────────────────────────
+  static tools = {
+    readFile: {
+      description: 'Read the contents of a file.',
+      schema: z.object({
+        path: z.string().describe('File path relative to the project root'),
+        offset: z.number().optional().describe('Line number to start reading from'),
+        limit: z.number().optional().describe('Maximum number of lines to read'),
+      }),
+    },
+    searchFiles: {
+      description: 'Search file contents for a pattern using ripgrep.',
+      schema: z.object({
+        pattern: z.string().describe('Search pattern (regex supported)'),
+        path: z.string().optional().describe('Directory to search in'),
+        include: z.string().optional().describe('Glob pattern to filter files'),
+      }),
+    },
+    editFile: {
+      description: 'Replace an exact string match in a file.',
+      schema: z.object({
+        path: z.string().describe('File path relative to the project root'),
+        oldString: z.string().describe('The exact text to find and replace'),
+        newString: z.string().describe('The replacement text'),
+      }),
+    },
+    // ... more tools
+  }
+
+  // ── 2. Implement each tool as an instance method ───────────────
+  // Method names must match the keys in static tools exactly.
+  // Each receives the parsed args object and returns a string.
+
+  async readFile(args: { path: string; offset?: number; limit?: number }) {
+    const fs = this.container.feature('fs')
+    const content = await fs.readFileAsync(args.path)
+    // ... handle offset/limit
+    return content
+  }
+
+  async searchFiles(args: { pattern: string; path?: string; include?: string }) {
+    const grep = this.container.feature('grep')
+    const results = await grep.search({ pattern: args.pattern, path: args.path, include: args.include })
+    return JSON.stringify(results.map(r => ({ file: r.file, line: r.line, content: r.content })))
+  }
+
+  async editFile(args: { path: string; oldString: string; newString: string }) {
+    const fs = this.container.feature('fs')
+    const content = await fs.readFileAsync(args.path)
+    const updated = content.replace(args.oldString, args.newString)
+    await fs.writeFileAsync(args.path, updated)
+    return \`Edited \${args.path}\`
+  }
+
+  // ── 3. Configure the assistant when it calls use() ─────────────
+  override setupToolsConsumer(consumer) {
+    // If the consumer is an assistant, inject guidance into its system prompt
+    if (typeof consumer.addSystemPromptExtension === 'function') {
+      consumer.addSystemPromptExtension('fileTools', [
+        '## File Tools',
+        '- All file paths are relative to the project root unless they start with /',
+        '- Use searchFiles to understand code before modifying it',
+        '- Use editFile for surgical changes — prefer it over writeFile',
+      ].join('\\n'))
+    }
+  }
+}
+\`\`\`
+
+## Using It
+
+\`\`\`ts
+const assistant = container.feature('assistant', {
+  systemPrompt: 'You are a coding assistant.',
+  model: 'gpt-4.1-mini',
+})
+
+const fileTools = container.feature('fileTools')
+assistant.use(fileTools)
+await assistant.start()
+
+// The assistant now has readFile, searchFiles, editFile, etc.
+// and its system prompt includes the fileTools guidance.
+console.log(Object.keys(assistant.tools))
+\`\`\`
+
+### Selective tool registration
+
+You can expose only a subset of tools:
+
+\`\`\`ts
+assistant.use(fileTools.toTools({ only: ['readFile', 'searchFiles', 'listDirectory'] }))
+\`\`\`
+
+## Why This Pattern Matters
+
+This is how features compose for AI. Instead of the assistant importing \`fs\` and \`grep\` directly:
+
+- The **feature** owns the tool surface — schemas, descriptions, and implementations in one place
+- The **assistant** gets a curated interface, not raw container access
+- **\`setupToolsConsumer()\`** lets the feature teach the assistant how to use the tools well
+- **\`toTools({ only })\`** lets you scope down what the assistant can do
+
+Any feature you build can follow this same pattern. Define \`static tools\`, implement matching methods, optionally override \`setupToolsConsumer()\`, and assistants can \`use()\` it.
+
+## Summary
+
+Features are the natural place to package tools for assistants. The \`static tools\` record declares the schema, instance methods implement the logic, and \`setupToolsConsumer()\` wires up assistant-specific configuration like system prompt extensions. This keeps tool definitions, implementations, and assistant guidance co-located in a single feature class.
 `,
   "content-db.md": `---
 title: "Content Database"
@@ -2413,96 +2684,6 @@ console.log('Done')
 ## Summary
 
 The ask/reply protocol gives you awaitable request/response over WebSocket without leaving the Luca helper API. The client calls \`ask(type, data)\` and gets back a promise. The server's message handler gets \`reply()\` and \`replyError()\` injected on any message that carries a \`requestId\`. The server can also \`ask()\` a specific client. Timeouts, error propagation, and cleanup of pending requests on disconnect are all handled automatically.
-`,
-  "port-exposer.md": `---
-title: "Port Exposer"
-tags: [portExposer, ngrok, networking, tunnel]
-lastTested: null
-lastTestPassed: null
----
-
-# portExposer
-
-Exposes local HTTP services via ngrok with SSL-enabled public URLs. Useful for development, testing webhooks, and sharing local services with external consumers.
-
-## Overview
-
-The \`portExposer\` feature creates an ngrok tunnel from a local port to a public HTTPS URL. It supports custom subdomains, regional endpoints, basic auth, and OAuth (features that require a paid ngrok plan). Requires ngrok to be installed or available as a dependency, and optionally an auth token for premium features.
-
-## Enabling the Feature
-
-\`\`\`ts
-const exposer = container.feature('portExposer', {
-  port: 3000,
-  enable: true
-})
-console.log('Port Exposer enabled:', exposer.state.get('enabled'))
-\`\`\`
-
-## Exploring the API
-
-\`\`\`ts
-const docs = container.features.describe('portExposer')
-console.log(docs)
-\`\`\`
-
-## Checking Connection State
-
-\`\`\`ts
-const exposer = container.feature('portExposer', { port: 3000 })
-console.log('Connected:', exposer.isConnected())
-\`\`\`
-
-## Exposing a Port
-
-Create a tunnel and get the public URL.
-
-\`\`\`ts skip
-const url = await exposer.expose()
-console.log('Public URL:', url)
-console.log('Connected:', exposer.isConnected())
-\`\`\`
-
-The returned URL is an HTTPS endpoint that forwards traffic to \`localhost:3000\`. The tunnel remains active until \`close()\` is called or the process exits.
-
-## Getting Connection Info
-
-Retrieve a snapshot of the current tunnel state.
-
-\`\`\`ts skip
-await exposer.expose()
-const info = exposer.getConnectionInfo()
-console.log('Public URL:', info.publicUrl)
-console.log('Local port:', info.localPort)
-console.log('Connected at:', info.connectedAt)
-\`\`\`
-
-## Reconnecting with New Options
-
-Close the existing tunnel and re-expose with different settings.
-
-\`\`\`ts skip
-const url1 = await exposer.expose()
-console.log('First URL:', url1)
-
-const url2 = await exposer.reconnect({ port: 8080 })
-console.log('New URL (port 8080):', url2)
-\`\`\`
-
-The \`reconnect\` method calls \`close()\` internally, merges the new options, then calls \`expose()\` again.
-
-## Closing the Tunnel
-
-\`\`\`ts skip
-await exposer.close()
-console.log('Tunnel closed:', !exposer.isConnected())
-\`\`\`
-
-Calling \`close()\` when no tunnel is active is a safe no-op. The \`disable()\` method also closes the tunnel before disabling the feature.
-
-## Summary
-
-The \`portExposer\` feature wraps ngrok to expose local ports as public HTTPS endpoints. It supports connection lifecycle management, reconnection with new options, and event-driven notifications for tunnel state changes. Requires ngrok to be installed.
 `,
   "secure-shell.md": `---
 title: "Secure Shell"
@@ -5175,6 +5356,11 @@ Then anyone (human or AI) can discover your feature:
 \`\`\`typescript
 container.features.describe('sessionManager')
 // Returns the full markdown documentation extracted from your JSDoc
+
+// Quick discovery — list available methods and getters
+const session = container.feature('sessionManager')
+session.$methods  // => ['createSession', ...]
+session.$getters  // => ['activeCount', ...]
 \`\`\`
 
 ## Best Practices
@@ -5205,11 +5391,11 @@ Introspection serves two audiences:
 
 \`\`\`typescript
 // Structured data about the entire container
-const info = container.inspect()
+const info = container.introspect()
 // Returns: registries, enabled features, state schema, available helpers
 
 // Human-readable markdown
-const docs = container.inspectAsText()
+const docs = container.introspectAsText()
 \`\`\`
 
 ## Registry-Level Discovery
@@ -5260,6 +5446,16 @@ const info = fs.introspect()
 const docs = fs.introspectAsText()
 \`\`\`
 
+### Quick Discovery with $getters and $methods
+
+Every helper exposes \`$getters\` and \`$methods\` — string arrays listing what's available on the instance. Useful for quick exploration without parsing the full introspection object:
+
+\`\`\`typescript
+const fs = container.feature('fs')
+fs.$methods  // => ['readFile', 'writeFile', 'walk', 'readdir', ...]
+fs.$getters  // => ['cwd', 'sep', ...]
+\`\`\`
+
 ### What's in the Introspection Data?
 
 - **Class name** and description (from JSDoc)
@@ -5638,6 +5834,408 @@ export async function post(params: any, ctx: EndpointContext) {
   response.end()
 }
 \`\`\`
+`,
+  "19-python-sessions.md": `---
+title: Working with Python Projects
+tags: [python, sessions, persistent, bridge, codebase, interop, data-science]
+---
+
+# Working with Python Projects
+
+Luca's \`python\` feature has two modes: **stateless** execution (fire-and-forget, one process per call) and **persistent sessions** (a long-lived Python process that maintains state across calls). This tutorial focuses on sessions — the mode that lets you actually work inside a Python codebase.
+
+## When to Use Sessions
+
+Stateless \`execute()\` is fine for one-off scripts. But if you need any of these, you want a session:
+
+- **Imports that persist** — load \`pandas\` once, use it across many calls
+- **State that builds up** — query a database, filter results, then export
+- **Working inside a real project** — import your own modules, call your own functions
+- **Expensive setup** — ML model loading, database connections, API client initialization
+
+## Quick Start
+
+\`\`\`ts skip
+const python = container.feature('python', { dir: '/path/to/my-python-project' })
+await python.enable()
+await python.startSession()
+
+// Everything below runs in the same Python process.
+// Variables, imports, and state persist across calls.
+
+await python.run('import pandas as pd')
+await python.run('df = pd.read_csv("data/sales.csv")')
+
+const result = await python.run('print(df.shape)')
+console.log(result.stdout) // '(1000, 12)\\n'
+
+const total = await python.eval('df["revenue"].sum()')
+console.log('Total revenue:', total)
+
+await python.stopSession()
+\`\`\`
+
+## Project Directory
+
+The \`dir\` option tells Luca where the Python project lives. This determines:
+
+1. **sys.path** — the bridge adds the project root (and \`src/\`, \`lib/\` if they exist) so your imports work
+2. **Environment detection** — Luca looks for \`uv.lock\`, \`pyproject.toml\`, \`venv/\`, etc. in this directory
+3. **Working directory** — the bridge process runs with \`cwd\` set to this path
+
+\`\`\`ts skip
+// Explicit project directory
+const python = container.feature('python', { dir: '/Users/me/projects/my-api' })
+
+// Or defaults to wherever luca was invoked from
+const python = container.feature('python')
+\`\`\`
+
+If your project uses a \`src/\` layout (common in modern Python), the bridge automatically adds it to \`sys.path\`:
+
+\`\`\`
+my-project/
+  src/
+    myapp/
+      __init__.py
+      models.py
+  pyproject.toml
+\`\`\`
+
+\`\`\`ts skip
+await python.startSession()
+// This works because src/ was added to sys.path
+await python.importModule('myapp.models', 'models')
+\`\`\`
+
+## Session Lifecycle
+
+### Starting
+
+\`startSession()\` spawns a Python bridge process that talks to Luca over stdin/stdout using a JSON-line protocol. The bridge sets up \`sys.path\` and signals when it's ready.
+
+\`\`\`ts skip
+await python.enable()
+await python.startSession()
+
+console.log(python.state.get('sessionActive')) // true
+console.log(python.state.get('sessionId'))     // uuid
+\`\`\`
+
+### Stopping
+
+\`stopSession()\` kills the bridge process and cleans up. Any pending requests are rejected.
+
+\`\`\`ts skip
+await python.stopSession()
+console.log(python.state.get('sessionActive')) // false
+\`\`\`
+
+### Crash Recovery
+
+If the Python process dies unexpectedly (segfault, killed externally), the feature:
+- Sets \`sessionActive\` to \`false\`
+- Rejects all pending requests
+- Emits a \`sessionError\` event
+
+\`\`\`ts skip
+python.on('sessionError', ({ error, sessionId }) => {
+  console.error('Python session error:', error)
+  // You could restart: await python.startSession()
+})
+\`\`\`
+
+## The Session API
+
+### run(code, variables?)
+
+Execute Python code in the persistent namespace. This is the workhorse method.
+
+\`\`\`ts skip
+// Simple execution
+const result = await python.run('print("hello")')
+// result.ok === true
+// result.stdout === 'hello\\n'
+
+// With variable injection
+const result = await python.run('print(f"Processing {count} items")', { count: 42 })
+
+// Errors don't crash the session
+const bad = await python.run('raise ValueError("oops")')
+// bad.ok === false
+// bad.error === 'oops'
+// bad.traceback === 'Traceback (most recent call last):\\n...'
+
+// Session still alive after error
+const good = await python.run('print("still here")')
+// good.ok === true
+\`\`\`
+
+### eval(expression)
+
+Evaluate a Python expression and return its value to JavaScript.
+
+\`\`\`ts skip
+await python.run('x = [1, 2, 3]')
+const length = await python.eval('len(x)')      // 3
+const doubled = await python.eval('[i*2 for i in x]') // [2, 4, 6]
+\`\`\`
+
+Values are JSON-serialized. Complex types that can't be serialized come back as their \`repr()\` string.
+
+### importModule(name, alias?)
+
+Import a module into the session namespace. The alias defaults to the last segment of the module path.
+
+\`\`\`ts skip
+await python.importModule('json')                    // import json
+await python.importModule('myapp.models', 'models')  // import myapp.models as models
+await python.importModule('os.path')                 // import os.path (available as "path")
+\`\`\`
+
+### call(funcPath, args?, kwargs?)
+
+Call a function by its dotted path in the namespace.
+
+\`\`\`ts skip
+await python.importModule('json')
+const encoded = await python.call('json.dumps', [{ a: 1 }], { indent: 2 })
+// '{\\n  "a": 1\\n}'
+
+// Works with your own functions too
+await python.run('def add(a, b): return a + b')
+const sum = await python.call('add', [3, 4]) // 7
+\`\`\`
+
+### getLocals()
+
+Inspect everything in the session namespace.
+
+\`\`\`ts skip
+await python.run('x = 42')
+await python.importModule('json')
+const locals = await python.getLocals()
+// { x: 42, json: '<module ...>' }
+\`\`\`
+
+### resetSession()
+
+Clear all variables and imports without restarting the process.
+
+\`\`\`ts skip
+await python.run('big_model = load_model()')
+await python.resetSession()
+// big_model is gone, but the session process is still running
+\`\`\`
+
+## Real-World Patterns
+
+### Data Analysis Pipeline
+
+\`\`\`ts skip
+const python = container.feature('python', { dir: '/path/to/analytics' })
+await python.enable()
+await python.startSession()
+
+// Setup
+await python.run('import pandas as pd')
+await python.run('import matplotlib')
+await python.run('matplotlib.use("Agg")')  // headless
+await python.run('import matplotlib.pyplot as plt')
+
+// Load and analyze
+await python.run('df = pd.read_csv("data/events.csv")')
+const shape = await python.eval('list(df.shape)')
+console.log(\`Loaded \${shape[0]} rows, \${shape[1]} columns\`)
+
+const columns = await python.eval('list(df.columns)')
+console.log('Columns:', columns)
+
+// Filter and aggregate
+await python.run(\`
+filtered = df[df["status"] == "completed"]
+summary = filtered.groupby("category")["amount"].agg(["sum", "mean", "count"])
+\`)
+
+const summary = await python.eval('summary.to_dict()')
+console.log('Summary:', summary)
+
+// Generate a chart
+await python.run(\`
+fig, ax = plt.subplots(figsize=(10, 6))
+summary["sum"].plot(kind="bar", ax=ax)
+ax.set_title("Revenue by Category")
+fig.savefig("output/revenue.png", dpi=150, bbox_inches="tight")
+plt.close(fig)
+\`)
+
+await python.stopSession()
+\`\`\`
+
+### Working with a Django Project
+
+\`\`\`ts skip
+const python = container.feature('python', { dir: '/path/to/django-project' })
+await python.enable()
+await python.startSession()
+
+// Django requires this before you can import models
+await python.run(\`
+import os
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
+
+import django
+django.setup()
+\`)
+
+// Now you can work with the ORM
+await python.run('from myapp.models import User, Order')
+
+const userCount = await python.eval('User.objects.count()')
+console.log(\`\${userCount} users in database\`)
+
+const recentOrders = await python.eval(\`
+list(Order.objects.filter(status="pending").values("id", "total", "created_at")[:10])
+\`)
+console.log('Recent pending orders:', recentOrders)
+
+await python.stopSession()
+\`\`\`
+
+### ML Model Interaction
+
+\`\`\`ts skip
+const python = container.feature('python', { dir: '/path/to/ml-project' })
+await python.enable()
+await python.startSession()
+
+// Expensive setup — only happens once
+await python.run(\`
+from transformers import pipeline
+classifier = pipeline("sentiment-analysis")
+print("Model loaded")
+\`)
+
+// Now you can call it cheaply many times
+async function classify(text: string) {
+  return python.call('classifier', [text])
+}
+
+const results = await Promise.all([
+  classify('I love this product!'),
+  classify('Terrible experience.'),
+  classify('It was okay, nothing special.'),
+])
+
+console.log(results)
+// [
+//   [{ label: 'POSITIVE', score: 0.9998 }],
+//   [{ label: 'NEGATIVE', score: 0.9994 }],
+//   [{ label: 'NEGATIVE', score: 0.7231 }],
+// ]
+
+await python.stopSession()
+\`\`\`
+
+### Luca Command That Uses Python
+
+\`\`\`ts skip
+// commands/analyze.ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+export const positionals = ['target']
+export const argsSchema = CommandOptionsSchema.extend({
+  target: z.string().describe('Path to CSV file to analyze'),
+})
+
+async function handler(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const container = context.container as any
+  const python = container.feature('python')
+  await python.enable()
+  await python.startSession()
+
+  try {
+    await python.run('import pandas as pd')
+    await python.run(\`df = pd.read_csv("\${options.target}")\`)
+
+    const shape = await python.eval('list(df.shape)')
+    const dtypes = await python.eval('dict(df.dtypes.astype(str))')
+    const nulls = await python.eval('dict(df.isnull().sum())')
+
+    console.log(\`Rows: \${shape[0]}, Columns: \${shape[1]}\`)
+    console.log('Column types:', dtypes)
+    console.log('Null counts:', nulls)
+  } finally {
+    await python.stopSession()
+  }
+}
+
+export default {
+  description: 'Analyze a CSV file using pandas',
+  argsSchema,
+  handler,
+}
+\`\`\`
+
+\`\`\`bash
+luca analyze data/sales.csv
+\`\`\`
+
+## Stateless vs. Session: Choosing the Right Mode
+
+| | \`execute()\` (stateless) | \`run()\` (session) |
+|---|---|---|
+| Process | Fresh per call | Shared, long-lived |
+| State | None — each call starts clean | Persists across calls |
+| Imports | Re-imported every time | Imported once, reused |
+| Startup cost | ~50-200ms per call | ~200ms once, then ~1ms per call |
+| Use case | One-off scripts, simple eval | Real projects, data pipelines, REPL-like |
+| Error isolation | Perfect — crash is contained | Errors caught, session survives |
+
+Both modes use the same environment detection (uv, conda, venv, system) and respect the same \`dir\` and \`pythonPath\` options.
+
+## Environment Detection
+
+The feature detects Python environments in this order:
+
+1. **Explicit** — \`pythonPath\` option overrides everything
+2. **uv** — \`uv.lock\` or \`pyproject.toml\` present, \`uv run python\` works
+3. **conda** — \`environment.yml\` or \`conda.yml\` present
+4. **venv** — \`venv/\` or \`.venv/\` directory with a Python binary inside
+5. **system** — falls back to \`python3\` or \`python\` on PATH
+
+\`\`\`ts skip
+const python = container.feature('python', { dir: '/path/to/project' })
+await python.enable()
+console.log(python.environmentType) // 'uv' | 'conda' | 'venv' | 'system'
+console.log(python.pythonPath)      // e.g. '/Users/me/.local/bin/uv run python'
+\`\`\`
+
+## Events
+
+The session emits events you can listen to for monitoring and debugging:
+
+\`\`\`ts skip
+python.on('sessionStarted', ({ sessionId }) => {
+  console.log('Session started:', sessionId)
+})
+
+python.on('sessionStopped', ({ sessionId }) => {
+  console.log('Session stopped:', sessionId)
+})
+
+python.on('sessionError', ({ error, sessionId }) => {
+  console.error('Session error:', error)
+})
+\`\`\`
+
+## What's Next
+
+- [Creating Features](./10-creating-features.md) — build your own feature that wraps a Python service
+- [Commands](./08-commands.md) — create CLI commands that leverage Python
+- [Servers and Endpoints](./06-servers.md) — expose Python-powered analysis via HTTP
 `,
   "18-semantic-search.md": `---
 title: Semantic Search
@@ -6432,8 +7030,8 @@ fs.introspectAsText()
 The container itself is introspectable:
 
 \`\`\`js
-container.inspect()          // structured object with all registries, state, events
-container.inspectAsText()    // full markdown overview
+container.introspect()          // structured object with all registries, state, events
+container.introspectAsText()    // full markdown overview
 \`\`\`
 
 ## The REPL
@@ -6468,7 +7066,7 @@ luca eval "grep.search('.', 'TODO')"
 | Structured introspection?      | \`feature.introspect()\`                 |
 | What state does it have?       | \`feature.state.current\`               |
 | What events does it emit?      | \`feature.introspect().events\`          |
-| Full container overview?       | \`container.inspectAsText()\`            |
+| Full container overview?       | \`container.introspectAsText()\`            |
 | CLI docs for a helper?         | \`luca describe <name>\`                 |
 
 ## Gotchas
@@ -7127,10 +7725,10 @@ Discover everything about the container at runtime:
 
 \`\`\`typescript
 // Structured introspection data
-const info = container.inspect()
+const info = container.introspect()
 
 // Human-readable markdown
-const docs = container.inspectAsText()
+const docs = container.introspectAsText()
 \`\`\`
 
 This is what makes Luca especially powerful for AI agents -- they can discover the entire API surface at runtime without reading documentation.