@soederpop/luca 0.0.5 → 0.0.7

package/docs/README.md

@@ -1,88 +1,60 @@
 # Models
 
-Models define the structure of markdown documents in this collection. Each document is a markdown file with YAML frontmatter (metadata attributes) and a heading-based structure (sections). Models specify the expected frontmatter fields via a schema, named sections that map to `##` headings in the document body, relationships to other models, and computed properties derived at query time.
+## Overview
 
-## Examples
 
-**Prefix:** `examples`
 
-### Attributes
+## Summary
 
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| tags | string[] | optional | `[]` | Arbitrary tags for categorizing the example |
-
-### Example
-
-```markdown
----
-tags: []
----
-# Example Title
 ```
-
----
-
-## Ideas
-
-**Prefix:** `ideas`
-
-### Attributes
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| goal | string | optional | — | Slug of the goal this idea is aligned to |
-| tags | string[] | optional | `[]` | Arbitrary tags for categorizing the idea |
-| status | enum(`spark`, `exploring`, `parked`, `promoted`) | optional | `"spark"` | spark is a new raw idea, exploring means actively thinking about it, parked means on hold, promoted means it became a plan |
-
-### Example
-
-```markdown
----
-tags: []
-status: spark
----
-# Idea Title
-```
-
----
-
-## Reports
-
-**Prefix:** `reports`
-
-### Attributes
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| tags | string[] | optional | `[]` | Arbitrary tags for categorizing the report |
-
-### Example
-
-```markdown
----
-tags: []
----
-# Report Title
-```
-
----
-
-## Tutorials
-
-**Prefix:** `tutorials`
-
-### Attributes
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| tags | string[] | optional | `[]` | Arbitrary tags for categorizing the tutorial |
-
-### Example
-
-```markdown
----
-tags: []
----
-# Tutorial Title
+Collection: /Users/jonathansoeder/@soederpop/luca/docs
+Root: /Users/jonathansoeder/@soederpop/luca/docs
+Items: 169
+
+  Model: Challenge
+    Prefix: challenges
+    Meta: difficulty(enum(`easy`, `medium`, `hard`)), maxTime(number)
+    Sections: (none)
+    Relationships: (none)
+    Documents: 13
+    IDs: challenges/build-a-websocket-server-with-matching-client, challenges/build-a-custom-command, challenges/build-a-caching-proxy, challenges/process-orchestrator, challenges/build-a-file-watcher-pipeline, challenges/grep-audit-report, challenges/build-a-multi-feature-dashboard, challenges/yaml-config-system, challenges/script-runner-with-vm, challenges/build-an-api, challenges/find-confusing-apis, challenges/build-a-rest-server-with-matching-client, challenges/content-db-round-trip
+
+  Model: Example
+    Prefix: examples
+    Meta: tags(string[])
+    Sections: (none)
+    Relationships: (none)
+    Documents: 43
+    IDs: examples/postgres, examples/yaml-tree, examples/grep, examples/ink, examples/git, examples/ink-renderer, examples/esbuild, examples/window-manager, examples/process-manager, examples/runpod, examples/google-auth, examples/port-exposer, examples/downloader, examples/secure-shell, examples/vault, examples/window-manager-layouts, examples/ipc-socket, examples/google-sheets, examples/fs, examples/networking, examples/ink-blocks, examples/ui, examples/opener, examples/nlp, examples/disk-cache, examples/assistant/CORE, examples/vm, examples/google-docs, examples/google-calendar, examples/content-db, examples/yaml, examples/package-finder, examples/os, examples/json-tree, examples/google-drive, examples/telegram, examples/file-manager, examples/repl, examples/python, examples/sqlite, examples/tts, examples/docker, examples/proc
+
+  Model: Idea
+    Prefix: ideas
+    Meta: goal(string), tags(string[]), status(enum(`spark`, `exploring`, `parked`, `promoted`))
+    Sections: (none)
+    Relationships: (none)
+    Documents: 0
+
+  Model: Report
+    Prefix: reports
+    Meta: tags(string[])
+    Sections: (none)
+    Relationships: (none)
+    Documents: 5
+    IDs: reports/introspection-audit-tasks, reports/attach-pattern-usage, reports/code-audit-results, reports/assistant-bugs, reports/luca-mcp-improvements
+
+  Model: Tutorial
+    Prefix: tutorials
+    Meta: tags(string[])
+    Sections: (none)
+    Relationships: (none)
+    Documents: 19
+    IDs: tutorials/08-commands, tutorials/06-servers, tutorials/04-features-overview, tutorials/01-getting-started, tutorials/07-endpoints, tutorials/00-bootstrap, tutorials/10-creating-features, tutorials/13-introspection, tutorials/17-tui-blocks, tutorials/18-semantic-search, tutorials/03-scripts, tutorials/05-state-and-events, tutorials/14-type-system, tutorials/11-contentbase, tutorials/12-assistants, tutorials/02-container, tutorials/15-project-patterns, tutorials/09-clients, tutorials/16-google-features
+
+  Model: Base
+    Prefix: 
+    Meta: (none)
+    Sections: (none)
+    Relationships: (none)
+    Documents: 9
+    IDs: introspection, principles, todos, README, CLI, documentation-audit, introspection-audit, TABLE-OF-CONTENTS, philosophy
 ```

package/docs/TABLE-OF-CONTENTS.md

@@ -1,69 +1,78 @@
 # Table of Contents
 
+## Challenges
+
+- [Build a Caching Proxy](./challenges/build-a-caching-proxy.md)
+- [Build a custom command](./challenges/build-a-custom-command.md)
+- [Build a File Watcher Pipeline](./challenges/build-a-file-watcher-pipeline.md)
+- [Build a Multi-Feature Dashboard](./challenges/build-a-multi-feature-dashboard.md)
+- [Build a REST server with a matching REST Client](./challenges/build-a-rest-server-with-matching-client.md)
+- [Build a websocket server with a matching websocket client](./challenges/build-a-websocket-server-with-matching-client.md)
+- [Build an API](./challenges/build-an-api.md)
+- [Content DB Round-Trip](./challenges/content-db-round-trip.md)
+- [Find Confusing APIs](./challenges/find-confusing-apis.md)
+- [Grep Audit Report](./challenges/grep-audit-report.md)
+- [Process Orchestrator](./challenges/process-orchestrator.md)
+- [Script Runner with VM](./challenges/script-runner-with-vm.md)
+- [YAML Config System](./challenges/yaml-config-system.md)
+
 ## Examples
 
-- [contentDb](./examples/content-db.md)
-- [diskCache](./examples/disk-cache.md)
-- [docker](./examples/docker.md)
-- [downloader](./examples/downloader.md)
+- [Luca Assistant Example](./examples/assistant/CORE.md)
+- [Content Database](./examples/content-db.md)
+- [Disk Cache](./examples/disk-cache.md)
+- [Docker](./examples/docker.md)
+- [Downloader](./examples/downloader.md)
 - [esbuild](./examples/esbuild.md)
-- [fileManager](./examples/file-manager.md)
+- [File Manager](./examples/file-manager.md)
 - [fs](./examples/fs.md)
 - [git](./examples/git.md)
-- [googleAuth](./examples/google-auth.md)
-- [googleCalendar](./examples/google-calendar.md)
-- [googleDocs](./examples/google-docs.md)
-- [googleDrive](./examples/google-drive.md)
-- [googleSheets](./examples/google-sheets.md)
+- [Google Auth](./examples/google-auth.md)
+- [Google Calendar](./examples/google-calendar.md)
+- [Google Docs](./examples/google-docs.md)
+- [Google Drive](./examples/google-drive.md)
+- [Google Sheets](./examples/google-sheets.md)
 - [grep](./examples/grep.md)
-- [ink](./examples/ink.md)
+- [Ink](./examples/ink.md)
 - [Ink Blocks — Poor Man's MDX](./examples/ink-blocks.md)
 - [Feature Registry](./examples/ink-renderer.md)
-- [ipcSocket](./examples/ipc-socket.md)
-- [jsonTree](./examples/json-tree.md)
-- [launcherAppCommandListener](./examples/launcher-app-command-listener.md)
+- [IPC Socket](./examples/ipc-socket.md)
+- [JSON Tree](./examples/json-tree.md)
 - [networking](./examples/networking.md)
-- [nlp](./examples/nlp.md)
-- [opener](./examples/opener.md)
+- [Natural Language Processing](./examples/nlp.md)
+- [Opener](./examples/opener.md)
 - [os](./examples/os.md)
-- [packageFinder](./examples/package-finder.md)
-- [portExposer](./examples/port-exposer.md)
-- [postgres](./examples/postgres.md)
+- [Package Finder](./examples/package-finder.md)
+- [Port Exposer](./examples/port-exposer.md)
+- [PostgreSQL](./examples/postgres.md)
 - [proc](./examples/proc.md)
-- [processManager](./examples/process-manager.md)
-- [python](./examples/python.md)
-- [repl](./examples/repl.md)
-- [runpod](./examples/runpod.md)
-- [secureShell](./examples/secure-shell.md)
-- [sqlite](./examples/sqlite.md)
-- [telegram](./examples/telegram.md)
-- [tts](./examples/tts.md)
+- [Process Manager](./examples/process-manager.md)
+- [Python](./examples/python.md)
+- [REPL](./examples/repl.md)
+- [RunPod GPU Cloud](./examples/runpod.md)
+- [Secure Shell](./examples/secure-shell.md)
+- [SQLite](./examples/sqlite.md)
+- [Telegram Bot](./examples/telegram.md)
+- [Text-to-Speech](./examples/tts.md)
 - [ui](./examples/ui.md)
-- [vault](./examples/vault.md)
+- [Vault](./examples/vault.md)
 - [vm](./examples/vm.md)
-- [windowManager](./examples/window-manager.md)
-- [yaml](./examples/yaml.md)
-- [yamlTree](./examples/yaml-tree.md)
-
-## Ideas
-
-- [DX Improvements for Introspection](./ideas/better-dx-for-introspection.md)
-- [COntainer .use() API](./ideas/container-use-api.md)
-- [Feature Stacks](./ideas/feature-stacks.md)
-- [Helpers Gateway Feature](./ideas/helpers-gateway-feature.md)
-- [Luca CLI Self Sufficiency Demo](./ideas/luca-cli-self-sufficiency-demo.md)
-- [Luca Feature Authoring DX Improvements](./ideas/luca-feature-authoring-dx.md)
-- [Main Server](./ideas/persistent-main-server.md)
-- [Supervisor-Worker Multi-Container Orchestration](./ideas/supervisor-worker-containers.md)
+- [Window Manager](./examples/window-manager.md)
+- [Window Manager Layouts](./examples/window-manager-layouts.md)
+- [YAML](./examples/yaml.md)
+- [YAML Tree](./examples/yaml-tree.md)
 
 ## Reports
 
 - [Assistant systemPrompt Bug Fix Verification](./reports/assistant-bugs.md)
 - [Attach Pattern](./reports/attach-pattern-usage.md)
+- [Code Audit - Container Abstraction Violations](./reports/code-audit-results.md)
 - [Introspection Audit Results](./reports/introspection-audit-tasks.md)
+- [Problem](./reports/luca-mcp-improvements.md)
 
 ## Tutorials
 
+- [Bootstrap: Learning the Container at Runtime](./tutorials/00-bootstrap.md)
 - [Getting Started with Luca](./tutorials/01-getting-started.md)
 - [The Container](./tutorials/02-container.md)
 - [Running Scripts and Markdown Notebooks](./tutorials/03-scripts.md)
@@ -81,9 +90,23 @@
 - [Project Patterns and Recipes](./tutorials/15-project-patterns.md)
 - [Google Features](./tutorials/16-google-features.md)
 - [Building TUI Primitive Blocks](./tutorials/17-tui-blocks.md)
+- [Semantic Search](./tutorials/18-semantic-search.md)
+
+## Bases
+
+- [Luca CLI](./CLI.md)
+- [Models](./README.md)
+- [Table of Contents](./TABLE-OF-CONTENTS.md)
+- [Documentation Audit](./documentation-audit.md)
+- [Introspection](./introspection.md)
+- [Introspection Audit](./introspection-audit.md)
+- [Luca's Philosophy](./philosophy.md)
+- [Random Principles](./principles.md)
+- [todos](./todos.md)
 
 ## Other
 
+- [ElevenLabsClient (clients.elevenlabs)](./apis/clients/elevenlabs.md)
 - [GraphClient (clients.graph)](./apis/clients/graph.md)
 - [OpenAIClient (clients.openai)](./apis/clients/openai.md)
 - [RestClient (clients.rest)](./apis/clients/rest.md)
@@ -96,9 +119,12 @@
 - [DocsReader (features.docsReader)](./apis/features/agi/docs-reader.md)
 - [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)
+- [Dns (features.dns)](./apis/features/node/dns.md)
 - [Docker (features.docker)](./apis/features/node/docker.md)
 - [Downloader (features.downloader)](./apis/features/node/downloader.md)
 - [Esbuild (features.esbuild)](./apis/features/node/esbuild.md)
@@ -115,7 +141,6 @@
 - [Ink (features.ink)](./apis/features/node/ink.md)
 - [IpcSocket (features.ipcSocket)](./apis/features/node/ipc-socket.md)
 - [JsonTree (features.jsonTree)](./apis/features/node/json-tree.md)
-- [LauncherAppCommandListener (features.launcherAppCommandListener)](./apis/features/node/launcher-app-command-listener.md)
 - [Networking (features.networking)](./apis/features/node/networking.md)
 - [NLP (features.nlp)](./apis/features/node/nlp.md)
 - [Opener (features.opener)](./apis/features/node/opener.md)
@@ -128,6 +153,7 @@
 - [Repl (features.repl)](./apis/features/node/repl.md)
 - [Runpod (features.runpod)](./apis/features/node/runpod.md)
 - [SecureShell (features.secureShell)](./apis/features/node/secure-shell.md)
+- [SemanticSearch (features.semanticSearch)](./apis/features/node/semantic-search.md)
 - [Sqlite (features.sqlite)](./apis/features/node/sqlite.md)
 - [Telegram (features.telegram)](./apis/features/node/telegram.md)
 - [TTS (features.tts)](./apis/features/node/tts.md)
@@ -138,7 +164,9 @@
 - [YAML (features.yaml)](./apis/features/node/yaml.md)
 - [YamlTree (features.yamlTree)](./apis/features/node/yaml-tree.md)
 - [AssetLoader (features.assetLoader)](./apis/features/web/asset-loader.md)
+- [ContainerLink (features.containerLink)](./apis/features/web/container-link.md)
 - [Esbuild (features.esbuild)](./apis/features/web/esbuild.md)
+- [Helpers (features.helpers)](./apis/features/web/helpers.md)
 - [Network (features.network)](./apis/features/web/network.md)
 - [Speech (features.speech)](./apis/features/web/speech.md)
 - [WebVault (features.vault)](./apis/features/web/vault.md)
@@ -147,11 +175,14 @@
 - [ExpressServer (servers.express)](./apis/servers/express.md)
 - [MCPServer (servers.mcp)](./apis/servers/mcp.md)
 - [WebsocketServer (servers.websocket)](./apis/servers/websocket.md)
-- [Luca Codebase Reference](./codebase-explainer.md)
-- [Contentbase](./contentbase-readme.md)
-- [Documentation Audit](./documentation-audit.md)
-- [Introspection](./introspection.md)
-- [Introspection Audit](./introspection-audit.md)
-- [Luca's Philosophy](./philosophy.md)
-- [Random Principles](./principles.md)
-- [todos](./todos.md)
+- [Luca Project](./bootstrap/CLAUDE.md)
+- [Luca: Learning the Container at Runtime](./bootstrap/SKILL.md)
+- [Docs](./bootstrap/templates/docs-readme.md)
+- [Luca Development Guide](./mcp/readme.md)
+- [Code Audit](./prompts/audit-codebase-for-failures-to-use-the-container.md)
+- [MCP Test: Build a Command](./prompts/mcp-test-easy-command.md)
+- [Building a Client](./scaffolds/client.md)
+- [Building a Command](./scaffolds/command.md)
+- [Building an Endpoint](./scaffolds/endpoint.md)
+- [Building a Feature](./scaffolds/feature.md)
+- [Building a Server](./scaffolds/server.md)

package/docs/apis/clients/elevenlabs.md

@@ -1,6 +1,6 @@
 # ElevenLabsClient (clients.elevenlabs)
 
-No description provided
+ElevenLabs client — text-to-speech synthesis via the ElevenLabs REST API. Provides methods for listing voices, listing models, and generating speech audio. Audio is returned as a Buffer; use `say()` for a convenience method that writes to disk.
 
 ## Usage
 
@@ -32,6 +32,157 @@ container.client('elevenlabs', {
 | `defaultModelId` | `string` | Default TTS model ID |
 | `outputFormat` | `string` | Audio output format (e.g. mp3_44100_128, pcm_16000) |
 
+## Methods
+
+### beforeRequest
+
+Inject the xi-api-key header before each request.
+
+**Returns:** `void`
+
+
+
+### connect
+
+Validate the API key by listing available models.
+
+**Returns:** `Promise<this>`
+
+```ts
+await el.connect()
+```
+
+
+
+### listVoices
+
+List available voices with optional search and filtering.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{
+    search?: string
+    category?: string
+    voice_type?: string
+    page_size?: number
+    next_page_token?: string
+  }` |  | Query parameters for filtering voices |
+
+**Returns:** `Promise<any>`
+
+```ts
+const voices = await el.listVoices()
+const premade = await el.listVoices({ category: 'premade' })
+```
+
+
+
+### getVoice
+
+Get details for a single voice.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `voiceId` | `string` | ✓ | The voice ID to look up |
+
+**Returns:** `Promise<any>`
+
+```ts
+const voice = await el.getVoice('21m00Tcm4TlvDq8ikWAM')
+console.log(voice.name, voice.settings)
+```
+
+
+
+### listModels
+
+List available TTS models.
+
+**Returns:** `Promise<any[]>`
+
+```ts
+const models = await el.listModels()
+console.log(models.map(m => m.model_id))
+```
+
+
+
+### synthesize
+
+Synthesize speech from text, returning audio as a Buffer.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | ✓ | The text to convert to speech |
+| `options` | `SynthesizeOptions` |  | Voice, model, format, and voice settings overrides |
+
+`SynthesizeOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `voiceId` | `string` |  |
+| `modelId` | `string` |  |
+| `outputFormat` | `string` |  |
+| `voiceSettings` | `ElevenLabsVoiceSettings` |  |
+| `disableCache` | `boolean` |  |
+
+**Returns:** `Promise<Buffer>`
+
+```ts
+const audio = await el.synthesize('Hello world')
+// audio is a Buffer of mp3 data
+
+const custom = await el.synthesize('Hello', {
+ voiceId: '21m00Tcm4TlvDq8ikWAM',
+ voiceSettings: { stability: 0.5, similarityBoost: 0.8 }
+})
+```
+
+
+
+### say
+
+Synthesize speech and write the audio to a file.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | ✓ | The text to convert to speech |
+| `outputPath` | `string` | ✓ | File path to write the audio to |
+| `options` | `SynthesizeOptions` |  | Voice, model, format, and voice settings overrides |
+
+`SynthesizeOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `voiceId` | `string` |  |
+| `modelId` | `string` |  |
+| `outputFormat` | `string` |  |
+| `voiceSettings` | `ElevenLabsVoiceSettings` |  |
+| `disableCache` | `boolean` |  |
+
+**Returns:** `Promise<string>`
+
+```ts
+const path = await el.say('Hello world', './hello.mp3')
+console.log(`Audio saved to ${path}`)
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `apiKey` | `string` | The resolved API key from options or environment. |
+
 ## Events (Zod v4 schema)
 
 ### failure
@@ -46,27 +197,29 @@ Emitted when a request fails
 
 
 
-### speech
+### voices
 
-Emitted after speech synthesis completes
+Emitted after listing voices
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `object` |  |
+| `arg0` | `array` |  |
 
 
 
-### voices
+### speech
 
-Emitted after listing voices
+Emitted after speech synthesis completes
 
 **Event Arguments:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `arg0` | `array` |  |
+| `voiceId` | `string` |  |
+| `text` | `string` |  |
+| `audioSize` | `number` |  |
 
 
 
@@ -81,4 +234,75 @@ Emitted after listing voices
 
 ## Environment Variables
 
-- `ELEVENLABS_API_KEY`
+- `ELEVENLABS_API_KEY`
+
+## Examples
+
+**clients.elevenlabs**
+
+```ts
+const el = container.client('elevenlabs')
+await el.connect()
+const voices = await el.listVoices()
+const audio = await el.synthesize('Hello world')
+// audio is a Buffer of mp3 data
+```
+
+
+
+**connect**
+
+```ts
+await el.connect()
+```
+
+
+
+**listVoices**
+
+```ts
+const voices = await el.listVoices()
+const premade = await el.listVoices({ category: 'premade' })
+```
+
+
+
+**getVoice**
+
+```ts
+const voice = await el.getVoice('21m00Tcm4TlvDq8ikWAM')
+console.log(voice.name, voice.settings)
+```
+
+
+
+**listModels**
+
+```ts
+const models = await el.listModels()
+console.log(models.map(m => m.model_id))
+```
+
+
+
+**synthesize**
+
+```ts
+const audio = await el.synthesize('Hello world')
+// audio is a Buffer of mp3 data
+
+const custom = await el.synthesize('Hello', {
+ voiceId: '21m00Tcm4TlvDq8ikWAM',
+ voiceSettings: { stability: 0.5, similarityBoost: 0.8 }
+})
+```
+
+
+
+**say**
+
+```ts
+const path = await el.say('Hello world', './hello.mp3')
+console.log(`Audio saved to ${path}`)
+```
+