@soederpop/luca 0.0.2

package/docs/README.md

@@ -0,0 +1,88 @@
+# 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.
+
+## Examples
+
+**Prefix:** `examples`
+
+### Attributes
+
+| 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
+```

package/docs/TABLE-OF-CONTENTS.md

@@ -0,0 +1,157 @@
+# Table of Contents
+
+## Examples
+
+- [contentDb](./examples/content-db.md)
+- [diskCache](./examples/disk-cache.md)
+- [docker](./examples/docker.md)
+- [downloader](./examples/downloader.md)
+- [esbuild](./examples/esbuild.md)
+- [fileManager](./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)
+- [grep](./examples/grep.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)
+- [networking](./examples/networking.md)
+- [nlp](./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)
+- [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)
+- [ui](./examples/ui.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)
+
+## Reports
+
+- [Assistant systemPrompt Bug Fix Verification](./reports/assistant-bugs.md)
+- [Attach Pattern](./reports/attach-pattern-usage.md)
+- [Introspection Audit Results](./reports/introspection-audit-tasks.md)
+
+## Tutorials
+
+- [Getting Started with Luca](./tutorials/01-getting-started.md)
+- [The Container](./tutorials/02-container.md)
+- [Running Scripts and Markdown Notebooks](./tutorials/03-scripts.md)
+- [Features Overview](./tutorials/04-features-overview.md)
+- [State and Events](./tutorials/05-state-and-events.md)
+- [Servers](./tutorials/06-servers.md)
+- [Writing Endpoints](./tutorials/07-endpoints.md)
+- [Writing Commands](./tutorials/08-commands.md)
+- [Using Clients](./tutorials/09-clients.md)
+- [Creating Custom Features](./tutorials/10-creating-features.md)
+- [Contentbase - Markdown as a Database](./tutorials/11-contentbase.md)
+- [Building Assistants](./tutorials/12-assistants.md)
+- [Introspection and Discovery](./tutorials/13-introspection.md)
+- [Type System and Module Augmentation](./tutorials/14-type-system.md)
+- [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)
+
+## Other
+
+- [GraphClient (clients.graph)](./apis/clients/graph.md)
+- [OpenAIClient (clients.openai)](./apis/clients/openai.md)
+- [RestClient (clients.rest)](./apis/clients/rest.md)
+- [WebSocketClient (clients.websocket)](./apis/clients/websocket.md)
+- [Assistant (features.assistant)](./apis/features/agi/assistant.md)
+- [AssistantsManager (features.assistantsManager)](./apis/features/agi/assistants-manager.md)
+- [ClaudeCode (features.claudeCode)](./apis/features/agi/claude-code.md)
+- [Conversation (features.conversation)](./apis/features/agi/conversation.md)
+- [ConversationHistory (features.conversationHistory)](./apis/features/agi/conversation-history.md)
+- [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)
+- [SkillsLibrary (features.skillsLibrary)](./apis/features/agi/skills-library.md)
+- [ContentDb (features.contentDb)](./apis/features/node/content-db.md)
+- [DiskCache (features.diskCache)](./apis/features/node/disk-cache.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)
+- [FileManager (features.fileManager)](./apis/features/node/file-manager.md)
+- [FS (features.fs)](./apis/features/node/fs.md)
+- [Git (features.git)](./apis/features/node/git.md)
+- [GoogleAuth (features.googleAuth)](./apis/features/node/google-auth.md)
+- [GoogleCalendar (features.googleCalendar)](./apis/features/node/google-calendar.md)
+- [GoogleDocs (features.googleDocs)](./apis/features/node/google-docs.md)
+- [GoogleDrive (features.googleDrive)](./apis/features/node/google-drive.md)
+- [GoogleSheets (features.googleSheets)](./apis/features/node/google-sheets.md)
+- [Grep (features.grep)](./apis/features/node/grep.md)
+- [Helpers (features.helpers)](./apis/features/node/helpers.md)
+- [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)
+- [OS (features.os)](./apis/features/node/os.md)
+- [PackageFinder (features.packageFinder)](./apis/features/node/package-finder.md)
+- [Postgres (features.postgres)](./apis/features/node/postgres.md)
+- [ChildProcess (features.proc)](./apis/features/node/proc.md)
+- [ProcessManager (features.processManager)](./apis/features/node/process-manager.md)
+- [Python (features.python)](./apis/features/node/python.md)
+- [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)
+- [Sqlite (features.sqlite)](./apis/features/node/sqlite.md)
+- [Telegram (features.telegram)](./apis/features/node/telegram.md)
+- [TTS (features.tts)](./apis/features/node/tts.md)
+- [UI (features.ui)](./apis/features/node/ui.md)
+- [WebVault (features.vault)](./apis/features/node/vault.md)
+- [VM (features.vm)](./apis/features/node/vm.md)
+- [WindowManager (features.windowManager)](./apis/features/node/window-manager.md)
+- [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)
+- [Esbuild (features.esbuild)](./apis/features/web/esbuild.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)
+- [VM (features.vm)](./apis/features/web/vm.md)
+- [VoiceRecognition (features.voice)](./apis/features/web/voice.md)
+- [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)

package/docs/apis/clients/elevenlabs.md

@@ -0,0 +1,84 @@
+# ElevenLabsClient (clients.elevenlabs)
+
+No description provided
+
+## Usage
+
+```ts
+container.client('elevenlabs', {
+  // Base URL for the client connection
+  baseURL,
+  // Whether to automatically parse responses as JSON
+  json,
+  // ElevenLabs API key (falls back to ELEVENLABS_API_KEY env var)
+  apiKey,
+  // Default voice ID for speech synthesis
+  defaultVoiceId,
+  // Default TTS model ID
+  defaultModelId,
+  // Audio output format (e.g. mp3_44100_128, pcm_16000)
+  outputFormat,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `baseURL` | `string` | Base URL for the client connection |
+| `json` | `boolean` | Whether to automatically parse responses as JSON |
+| `apiKey` | `string` | ElevenLabs API key (falls back to ELEVENLABS_API_KEY env var) |
+| `defaultVoiceId` | `string` | Default voice ID for speech synthesis |
+| `defaultModelId` | `string` | Default TTS model ID |
+| `outputFormat` | `string` | Audio output format (e.g. mp3_44100_128, pcm_16000) |
+
+## Events (Zod v4 schema)
+
+### failure
+
+Emitted when a request fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error object |
+
+
+
+### speech
+
+Emitted after speech synthesis completes
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `object` |  |
+
+
+
+### voices
+
+Emitted after listing voices
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `array` |  |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | Whether the client is currently connected |
+| `requestCount` | `number` | Total number of API requests made |
+| `characterCount` | `number` | Total characters sent for synthesis (tracks billing usage) |
+| `lastRequestTime` | `any` | Timestamp of the last API request |
+
+## Environment Variables
+
+- `ELEVENLABS_API_KEY`

package/docs/apis/clients/graph.md

@@ -0,0 +1,56 @@
+# GraphClient (clients.graph)
+
+No description provided
+
+## Usage
+
+```ts
+container.client('graph', {
+  // Base URL for the client connection
+  baseURL,
+  // Whether to automatically parse responses as JSON
+  json,
+  // The GraphQL endpoint path, defaults to /graphql
+  endpoint,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `baseURL` | `string` | Base URL for the client connection |
+| `json` | `boolean` | Whether to automatically parse responses as JSON |
+| `endpoint` | `string` | The GraphQL endpoint path, defaults to /graphql |
+
+## Events (Zod v4 schema)
+
+### failure
+
+Emitted when a request fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error object |
+
+
+
+### graphqlError
+
+Emitted when GraphQL-level errors are present in the response
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `array` | Array of GraphQL errors |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | Whether the client is currently connected |

package/docs/apis/clients/openai.md

@@ -0,0 +1,69 @@
+# OpenAIClient (clients.openai)
+
+No description provided
+
+## Usage
+
+```ts
+container.client('openai', {
+  // Base URL for the client connection
+  baseURL,
+  // Whether to automatically parse responses as JSON
+  json,
+  // OpenAI API key (falls back to OPENAI_API_KEY env var)
+  apiKey,
+  // OpenAI organization ID
+  organization,
+  // OpenAI project ID
+  project,
+  // Allow usage in browser environments
+  dangerouslyAllowBrowser,
+  // Default model for completions (default: gpt-4o)
+  defaultModel,
+  // Request timeout in milliseconds
+  timeout,
+  // Maximum number of retries on failure
+  maxRetries,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `baseURL` | `string` | Base URL for the client connection |
+| `json` | `boolean` | Whether to automatically parse responses as JSON |
+| `apiKey` | `string` | OpenAI API key (falls back to OPENAI_API_KEY env var) |
+| `organization` | `string` | OpenAI organization ID |
+| `project` | `string` | OpenAI project ID |
+| `dangerouslyAllowBrowser` | `boolean` | Allow usage in browser environments |
+| `defaultModel` | `string` | Default model for completions (default: gpt-4o) |
+| `timeout` | `number` | Request timeout in milliseconds |
+| `maxRetries` | `number` | Maximum number of retries on failure |
+
+## Events (Zod v4 schema)
+
+### failure
+
+Emitted when a request fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error object |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | Whether the client is currently connected |
+| `requestCount` | `number` | Total number of API requests made |
+| `lastRequestTime` | `any` | Timestamp of the last API request |
+| `tokenUsage` | `object` | Cumulative token usage across all requests |
+
+## Environment Variables
+
+- `OPENAI_API_KEY`

package/docs/apis/clients/rest.md

@@ -0,0 +1,41 @@
+# RestClient (clients.rest)
+
+No description provided
+
+## Usage
+
+```ts
+container.client('rest', {
+  // Base URL for the client connection
+  baseURL,
+  // Whether to automatically parse responses as JSON
+  json,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `baseURL` | `string` | Base URL for the client connection |
+| `json` | `boolean` | Whether to automatically parse responses as JSON |
+
+## Events (Zod v4 schema)
+
+### failure
+
+Emitted when a request fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error object |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | Whether the client is currently connected |

package/docs/apis/clients/websocket.md

@@ -0,0 +1,107 @@
+# WebSocketClient (clients.websocket)
+
+No description provided
+
+## Usage
+
+```ts
+container.client('websocket', {
+  // Base URL for the client connection
+  baseURL,
+  // Whether to automatically parse responses as JSON
+  json,
+  // Whether to automatically reconnect on disconnection
+  reconnect,
+  // Base interval in milliseconds between reconnection attempts
+  reconnectInterval,
+  // Maximum number of reconnection attempts before giving up
+  maxReconnectAttempts,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `baseURL` | `string` | Base URL for the client connection |
+| `json` | `boolean` | Whether to automatically parse responses as JSON |
+| `reconnect` | `boolean` | Whether to automatically reconnect on disconnection |
+| `reconnectInterval` | `number` | Base interval in milliseconds between reconnection attempts |
+| `maxReconnectAttempts` | `number` | Maximum number of reconnection attempts before giving up |
+
+## Events (Zod v4 schema)
+
+### failure
+
+Emitted when a request fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error object |
+
+
+
+### message
+
+Emitted when a message is received
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The parsed message data |
+
+
+
+### open
+
+Emitted when the WebSocket connection is established
+
+
+
+### close
+
+Emitted when the WebSocket connection is closed
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `number` | Close code |
+| `arg1` | `string` | Close reason |
+
+
+
+### error
+
+Emitted when a WebSocket error occurs
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+### reconnecting
+
+Emitted when attempting to reconnect
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `number` | Attempt number |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `connected` | `boolean` | Whether the client is currently connected |
+| `connectionError` | `any` | The last connection error, if any |
+| `reconnectAttempts` | `number` | Number of reconnection attempts made |