@soederpop/luca 0.0.32 → 0.0.35

package/docs/apis/features/node/ui.md

@@ -20,7 +20,7 @@ Parse markdown text and render it for terminal display using marked-terminal.
 |------|------|----------|-------------|
 | `text` | `string` | ✓ | The markdown string to parse and render |
 
-**Returns:** `void`
+**Returns:** `string | Promise<string>`
 
 
 
@@ -64,7 +64,7 @@ Creates an interactive wizard using inquirer prompts. This method provides a con
 | `questions` | `any[]` | ✓ | Array of inquirer question objects |
 | `initialAnswers` | `any` |  | Pre-populated answers to skip questions or provide defaults |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 ```ts
 // Basic wizard
@@ -109,7 +109,7 @@ Prompt the user with a single text input question.
 |------|------|----------|-------------|
 | `question` | `string` | ✓ | The question message to display |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 
 
@@ -124,7 +124,7 @@ Opens text in the user's external editor for editing. This method integrates wit
 | `text` | `string` | ✓ | The initial text content to edit |
 | `extension` | `any` |  | File extension for syntax highlighting (default: ".ts") |
 
-**Returns:** `void`
+**Returns:** `Promise<unknown>`
 
 ```ts
 // Edit code snippet
@@ -153,7 +153,7 @@ Generates ASCII art from text using the specified font. This method converts reg
 | `text` | `string` | ✓ | The text to convert to ASCII art |
 | `font` | `Fonts` | ✓ | The figlet font to use (see fonts property for available options) |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Create a banner
@@ -191,7 +191,7 @@ Creates a styled banner with ASCII art and color gradients. This method combines
 | `font` | `any` | The figlet font to use for ASCII art generation |
 | `colors` | `any` | Array of colors for the gradient effect |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Classic patriotic banner
@@ -229,7 +229,7 @@ Dedent and format a tagged template literal using endent. Strips leading indenta
 |------|------|----------|-------------|
 | `args` | `any[]` | ✓ | Tagged template literal arguments |
 
-**Returns:** `void`
+**Returns:** `string`
 
 
 
@@ -245,7 +245,7 @@ Applies color gradients to text with configurable direction. This method creates
 | `lineColors` | `Color[]` |  | Array of colors to cycle through in the gradient |
 | `direction` | `"horizontal" | "vertical"` |  | Gradient direction: 'horizontal' or 'vertical' |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Horizontal rainbow effect
@@ -281,7 +281,7 @@ Applies horizontal color gradients character by character. This method creates c
 | `text` | `string` | ✓ | The text to apply horizontal gradients to |
 | `lineColors` | `Color[]` |  | Array of colors to cycle through |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Rainbow effect across characters
@@ -310,7 +310,7 @@ Applies vertical color gradients line by line. This method creates color transit
 | `text` | `string` | ✓ | The text to apply vertical gradients to (supports newlines) |
 | `lineColors` | `Color[]` |  | Array of colors to cycle through for each line |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Patriotic vertical gradient
@@ -342,7 +342,7 @@ Pads text on the left to reach the specified length. This utility method adds pa
 | `length` | `number` | ✓ | The desired total length after padding |
 | `padChar` | `any` |  | The character to use for padding (default: " ") |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Number alignment
@@ -375,7 +375,7 @@ Pads text on the right to reach the specified length. This utility method adds p
 | `length` | `number` | ✓ | The desired total length after padding |
 | `padChar` | `any` |  | The character to use for padding (default: " ") |
 
-**Returns:** `void`
+**Returns:** `string`
 
 ```ts
 // Create aligned table columns
@@ -409,7 +409,7 @@ const menuItem = ui.padRight('Coffee', 20, '.') + '$3.50';
 |----------|------|-------------|
 | `colors` | `typeof colors` | Provides access to the full chalk colors API. Chalk provides extensive color and styling capabilities including: - Basic colors: red, green, blue, yellow, etc. - Background colors: bgRed, bgGreen, etc. - Styles: bold, italic, underline, strikethrough - Advanced: rgb, hex, hsl color support Colors and styles can be chained for complex formatting. |
 | `colorPalette` | `string[]` | Gets the current color palette used for automatic color assignment. The color palette is a predefined set of hex colors that are automatically assigned to named entities in a cycling fashion. This ensures consistent color assignment across the application. |
-| `randomColor` | `any` | Gets a random color name from the available chalk colors. This provides access to a randomly selected color from chalk's built-in color set. Useful for adding variety to terminal output or testing. |
+| `randomColor` | `string | undefined` | Gets a random color name from the available chalk colors. This provides access to a randomly selected color from chalk's built-in color set. Useful for adding variety to terminal output or testing. |
 | `fonts` | `string[]` | Gets an array of available fonts for ASCII art generation. This method provides access to all fonts available through figlet for creating ASCII art. The fonts are automatically discovered and cached on first access for performance. **Font Discovery:** - Fonts are loaded from figlet's built-in font collection - Results are cached in state to avoid repeated file system access - Returns comprehensive list of available font names |
 
 ## State (Zod v4 schema)

package/docs/apis/servers/express.md

@@ -39,25 +39,27 @@ container.server('express', {
 
 ### start
 
+Start the Express HTTP server. A runtime `port` overrides the constructor option and is written to state so `server.port` always reflects reality.
+
 **Parameters:**
 
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `options` | `StartOptions` |  | Parameter options |
+| `options` | `StartOptions` |  | Optional runtime overrides for port and host |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
 ### stop
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
 ### configure
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
@@ -85,6 +87,32 @@ container.server('express', {
 
 
 
+### reloadEndpoint
+
+Reload a mounted endpoint by its file path. Re-reads the module through the helpers VM loader so the next request picks up the new handlers.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✓ | Absolute path to the endpoint file |
+
+**Returns:** `Promise<Endpoint | null>`
+
+
+
+### useEndpointModules
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `modules` | `EndpointModule[]` | ✓ | Parameter modules |
+
+**Returns:** `Promise<this>`
+
+
+
 ### serveOpenAPISpec
 
 **Parameters:**
@@ -113,9 +141,9 @@ container.server('express', {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `express` | `any` |  |
-| `hooks` | `any` |  |
-| `app` | `any` |  |
+| `express` | `typeof express` |  |
+| `hooks` | `{ create: (app: Express, server: Server) => Express; beforeStart: (options: any, server: Server) => any }` |  |
+| `app` | `Express` |  |
 
 ## State (Zod v4 schema)
 

package/docs/apis/servers/mcp.md

@@ -102,7 +102,7 @@ Register an MCP prompt. Prompts are reusable message templates that AI clients c
 
 Configure the MCP protocol server and register all protocol handlers. Called automatically before start() if not already configured.
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
@@ -135,7 +135,7 @@ Start the MCP server with the specified transport.
 | `transport` | `any` | 'stdio' for CLI integration, 'http' for remote access |
 | `port` | `any` | Port for HTTP transport (default 3001) |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
@@ -143,7 +143,7 @@ Start the MCP server with the specified transport.
 
 Stop the MCP server and close all connections.
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 

package/docs/apis/servers/websocket.md

@@ -1,6 +1,6 @@
 # WebsocketServer (servers.websocket)
 
-WebSocket server built on the `ws` library with optional JSON message framing. Manages WebSocket connections, tracks connected clients, and bridges messages to Luca's event bus. When `json` mode is enabled, incoming messages are automatically JSON-parsed (with `.toString()` for Buffer data) and outgoing messages via `send()` / `broadcast()` are JSON-stringified. When `json` mode is disabled, raw message data is emitted as-is and `send()` / `broadcast()` still JSON-stringify for safety.
+WebSocket server built on the `ws` library with optional JSON message framing. Manages WebSocket connections, tracks connected clients, and bridges messages to Luca's event bus. When `json` mode is enabled, incoming messages are automatically JSON-parsed (with `.toString()` for Buffer data) and outgoing messages via `send()` / `broadcast()` are JSON-stringified. When `json` mode is disabled, raw message data is emitted as-is and `send()` / `broadcast()` still JSON-stringify for safety. Supports ask/reply semantics when paired with the Luca WebSocket client. The server can `ask(ws, type, data)` a connected client and await a typed response, or handle incoming asks from clients by listening for messages with a `requestId` and replying via `send(ws, { replyTo, data })`. Requests time out if no reply arrives within the configurable window.
 
 ## Usage
 
@@ -33,7 +33,7 @@ container.server('websocket', {
 |------|------|----------|-------------|
 | `message` | `any` | ✓ | Parameter message |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
@@ -46,25 +46,51 @@ container.server('websocket', {
 | `ws` | `any` | ✓ | Parameter ws |
 | `message` | `any` | ✓ | Parameter message |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
+
+
+
+### ask
+
+Send a request to a specific client and wait for a correlated response. The client is expected to reply with a message whose `replyTo` matches the `requestId` of this message.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `ws` | `any` | ✓ | The WebSocket client to ask |
+| `type` | `string` | ✓ | A string identifying the request type |
+| `data` | `any` |  | Optional payload |
+| `timeout` | `any` |  | How long to wait (default 10 000 ms) |
+
+**Returns:** `Promise<R>`
+
+```ts
+ws.on('connection', async (client) => {
+ const info = await ws.ask(client, 'identify')
+ console.log('Client says:', info)
+})
+```
 
 
 
 ### start
 
+Start the WebSocket server. A runtime `port` overrides the constructor option and is written to state before the underlying `ws.Server` is created, so the server binds to the correct port.
+
 **Parameters:**
 
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `options` | `StartOptions` |  | Parameter options |
+| `options` | `StartOptions` |  | Optional runtime overrides for port and host |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
 ### stop
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
@@ -72,8 +98,8 @@ container.server('websocket', {
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `wss` | `any` |  |
-| `port` | `any` |  |
+| `wss` | `BaseServer` |  |
+| `port` | `number` | The port this server will bind to. Defaults to 8081 if not set via constructor options or start(). |
 
 ## Events (Zod v4 schema)
 
@@ -123,5 +149,22 @@ ws.on('message', (data, client) => {
  console.log('Received:', data)
  ws.broadcast({ echo: data })
 })
+
+// ask/reply: request info from a connected client
+ws.on('connection', async (client) => {
+ const info = await ws.ask(client, 'identify')
+ console.log('Client says:', info)
+})
+```
+
+
+
+**ask**
+
+```ts
+ws.on('connection', async (client) => {
+ const info = await ws.ask(client, 'identify')
+ console.log('Client says:', info)
+})
 ```
 

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/` 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
 

package/docs/bootstrap/SKILL.md

@@ -18,7 +18,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
 
@@ -70,6 +70,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
@@ -85,7 +97,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.
 
 ---
 
@@ -232,7 +246,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.
@@ -248,8 +262,80 @@ 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 |

package/docs/examples/feature-as-tool-provider.md

@@ -0,0 +1,143 @@
+---
+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.

package/docs/examples/python.md

@@ -86,6 +86,47 @@ 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.