@soederpop/luca 0.0.2

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

@@ -0,0 +1,387 @@
+# SemanticSearch (features.semanticSearch)
+
+No description provided
+
+## Usage
+
+```ts
+container.feature('semanticSearch', {
+  // Path to the SQLite database file
+  dbPath,
+  // GGUF model name
+  embeddingModel,
+  // Where to generate embeddings
+  embeddingProvider,
+  // How to split documents
+  chunkStrategy,
+  // Token limit per chunk for fixed strategy
+  chunkSize,
+  // Overlap ratio for fixed strategy
+  chunkOverlap,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dbPath` | `string` | Path to the SQLite database file |
+| `embeddingModel` | `string` | GGUF model name |
+| `embeddingProvider` | `string` | Where to generate embeddings |
+| `chunkStrategy` | `string` | How to split documents |
+| `chunkSize` | `number` | Token limit per chunk for fixed strategy |
+| `chunkOverlap` | `number` | Overlap ratio for fixed strategy |
+
+## Methods
+
+### initDb
+
+**Returns:** `Promise<void>`
+
+
+
+### insertDocument
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `doc` | `DocumentInput` | ✓ | Parameter doc |
+
+`DocumentInput` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+
+**Returns:** `void`
+
+
+
+### insertChunk
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `chunk` | `Chunk` | ✓ | Parameter chunk |
+
+`Chunk` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `section` | `string` |  |
+| `headingPath` | `string` |  |
+| `seq` | `number` |  |
+| `content` | `string` |  |
+| `contentHash` | `string` |  |
+| `embedding` | `Float32Array` | ✓ | Parameter embedding |
+
+**Returns:** `void`
+
+
+
+### removeDocument
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pathId` | `string` | ✓ | Parameter pathId |
+
+**Returns:** `void`
+
+
+
+### getStats
+
+**Returns:** `IndexStatus`
+
+
+
+### embed
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `texts` | `string[]` | ✓ | Parameter texts |
+
+**Returns:** `Promise<number[][]>`
+
+
+
+### ensureModel
+
+**Returns:** `Promise<void>`
+
+
+
+### disposeModel
+
+**Returns:** `Promise<void>`
+
+
+
+### getDimensions
+
+**Returns:** `number`
+
+
+
+### chunkDocument
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `doc` | `DocumentInput` | ✓ | Parameter doc |
+
+`DocumentInput` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+| `strategy` | `'section' | 'fixed' | 'document'` |  | Parameter strategy |
+
+**Returns:** `Chunk[]`
+
+
+
+### search
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `SearchOptions` |  | Parameter options |
+
+`SearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `limit` | `number` |  |
+| `model` | `string` |  |
+| `where` | `Record<string, any>` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### vectorSearch
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `SearchOptions` |  | Parameter options |
+
+`SearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `limit` | `number` |  |
+| `model` | `string` |  |
+| `where` | `Record<string, any>` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### hybridSearch
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | Parameter query |
+| `options` | `HybridSearchOptions` |  | Parameter options |
+
+`HybridSearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `ftsWeight` | `number` |  |
+| `vecWeight` | `number` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### deepSearch
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `_query` | `string` | ✓ | Parameter _query |
+| `_options` | `SearchOptions` |  | Parameter _options |
+
+`SearchOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `limit` | `number` |  |
+| `model` | `string` |  |
+| `where` | `Record<string, any>` |  |
+
+**Returns:** `Promise<SearchResult[]>`
+
+
+
+### indexDocuments
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `docs` | `DocumentInput[]` | ✓ | Parameter docs |
+
+`DocumentInput[]` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+
+**Returns:** `Promise<void>`
+
+
+
+### reindex
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pathIds` | `string[]` |  | Parameter pathIds |
+
+**Returns:** `Promise<void>`
+
+
+
+### removeStale
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `currentPathIds` | `string[]` | ✓ | Parameter currentPathIds |
+
+**Returns:** `void`
+
+
+
+### needsReindex
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `doc` | `DocumentInput` | ✓ | Parameter doc |
+
+`DocumentInput` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `pathId` | `string` |  |
+| `model` | `string` |  |
+| `title` | `string` |  |
+| `slug` | `string` |  |
+| `meta` | `Record<string, any>` |  |
+| `content` | `string` |  |
+| `sections` | `Array<{ heading: string; headingPath: string; content: string; level: number }>` |  |
+
+**Returns:** `boolean`
+
+
+
+### status
+
+**Returns:** `IndexStatus`
+
+
+
+### close
+
+**Returns:** `Promise<void>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `db` | `Database` |  |
+| `dimensions` | `number` |  |
+
+## Events (Zod v4 schema)
+
+### dbReady
+
+Event emitted by SemanticSearch
+
+
+
+### modelLoaded
+
+Event emitted by SemanticSearch
+
+
+
+### modelDisposed
+
+Event emitted by SemanticSearch
+
+
+
+### indexed
+
+Event emitted by SemanticSearch
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `indexed` | `number` | Count of indexed documents |
+| `embedded` | `number` | Count of documents with embeddings |
+| `lastIndexedAt` | `any` | ISO timestamp of last indexing |
+| `dbReady` | `boolean` | Whether SQLite is initialized |
+
+## Examples
+
+**features.semanticSearch**
+
+```ts
+const search = container.feature('semanticSearch', {
+ dbPath: '.contentbase/search.sqlite',
+ embeddingProvider: 'local',
+})
+await search.initDb()
+await search.indexDocuments(docs)
+const results = await search.hybridSearch('how does authentication work')
+```
+

package/docs/apis/features/agi/skills-library.md

@@ -0,0 +1,216 @@
+# SkillsLibrary (features.skillsLibrary)
+
+No description provided
+
+## Usage
+
+```ts
+container.feature('skillsLibrary', {
+  // Path to project-level skills directory
+  projectSkillsPath,
+  // Path to user-level global skills directory
+  userSkillsPath,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `projectSkillsPath` | `string` | Path to project-level skills directory |
+| `userSkillsPath` | `string` | Path to user-level global skills directory |
+
+## Methods
+
+### load
+
+Loads both project and user skill collections from disk. Gracefully handles missing directories.
+
+**Returns:** `Promise<SkillsLibrary>`
+
+
+
+### list
+
+Lists all skills from both collections. Project skills come first.
+
+**Returns:** `SkillEntry[]`
+
+
+
+### find
+
+Finds a skill by name. Project skills take precedence over user skills.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The skill name to find (case-insensitive) |
+
+**Returns:** `SkillEntry | undefined`
+
+
+
+### search
+
+Searches skills by substring match against name and description.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | `string` | ✓ | The search query |
+
+**Returns:** `SkillEntry[]`
+
+
+
+### getSkill
+
+Gets a skill by name. Alias for find().
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The skill name |
+
+**Returns:** `SkillEntry | undefined`
+
+
+
+### create
+
+Creates a new SKILL.md file in the specified collection. Maintains the directory-per-skill structure (skill-name/SKILL.md).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `skill` | `{
+			name: string
+			description: string
+			body: string
+			meta?: Record<string, unknown>
+		}` | ✓ | The skill to create |
+| `target` | `'project' | 'user'` |  | Which collection to write to (default: 'project') |
+
+**Returns:** `Promise<SkillEntry>`
+
+
+
+### update
+
+Updates an existing skill's content or metadata.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The skill name to update |
+| `updates` | `{
+			description?: string
+			body?: string
+			meta?: Record<string, unknown>
+		}` | ✓ | Fields to update |
+
+**Returns:** `Promise<SkillEntry>`
+
+
+
+### remove
+
+Removes a skill by name, deleting its SKILL.md and cleaning up the directory.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The skill name to remove |
+
+**Returns:** `Promise<boolean>`
+
+
+
+### toConversationTools
+
+Converts all skills into ConversationTool format for use with Conversation. Each skill becomes a tool that returns its instruction body when invoked.
+
+**Returns:** `Record<string, ConversationTool>`
+
+
+
+### toSystemPromptBlock
+
+Generates a markdown block listing all available skills with names and descriptions. Suitable for injecting into a system prompt.
+
+**Returns:** `string`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `projectCollection` | `Collection` | Returns the project-level contentbase Collection, lazily initialized. |
+| `userCollection` | `Collection` | Returns the user-level contentbase Collection, lazily initialized. |
+| `isLoaded` | `boolean` | Whether the skills library has been loaded. |
+| `skillNames` | `string[]` | Array of all skill names across both collections. |
+
+## Events (Zod v4 schema)
+
+### loaded
+
+Event emitted by SkillsLibrary
+
+
+
+### skillCreated
+
+Event emitted by SkillsLibrary
+
+
+
+### skillUpdated
+
+Event emitted by SkillsLibrary
+
+
+
+### skillRemoved
+
+Event emitted by SkillsLibrary
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `loaded` | `boolean` | Whether both collections have been loaded |
+| `projectSkillCount` | `number` | Number of skills in the project collection |
+| `userSkillCount` | `number` | Number of skills in the user-level collection |
+| `totalSkillCount` | `number` | Total number of skills across both collections |
+
+## Examples
+
+**features.skillsLibrary**
+
+```ts
+const skills = container.feature('skillsLibrary')
+await skills.load()
+
+// List and search
+const allSkills = skills.list()
+const matches = skills.search('code review')
+
+// Create a new skill
+await skills.create({
+ name: 'summarize',
+ description: 'Summarize a document',
+ body: '## Instructions\nRead the document and produce a concise summary.'
+})
+```
+

package/docs/apis/features/node/container-link.md

@@ -0,0 +1,133 @@
+# ContainerLink (features.containerLink)
+
+ContainerLink (Web-side) — WebSocket client that connects to a node host. Connects to a ContainerLink host over WebSocket. The host can evaluate code in this container, and the web side can emit structured events to the host. The web side can NEVER eval code in the host — trust is strictly one-way.
+
+## Usage
+
+```ts
+container.feature('containerLink', {
+  // Port for the WebSocket server
+  port,
+  // Interval in ms between heartbeat pings
+  heartbeatInterval,
+  // Max missed pongs before disconnecting a client
+  maxMissedHeartbeats,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `port` | `number` | Port for the WebSocket server |
+| `heartbeatInterval` | `number` | Interval in ms between heartbeat pings |
+| `maxMissedHeartbeats` | `number` | Max missed pongs before disconnecting a client |
+
+## Methods
+
+### connect
+
+Connect to the host WebSocket server and perform registration.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `hostUrl` | `string` |  | Override the configured host URL |
+
+**Returns:** `Promise<this>`
+
+
+
+### disconnect
+
+Disconnect from the host.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `reason` | `string` |  | Optional reason string |
+
+**Returns:** `void`
+
+
+
+### emitToHost
+
+Send a structured event to the host container.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `eventName` | `string` | ✓ | Name of the event |
+| `data` | `any` |  | Optional event data |
+
+**Returns:** `void`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isConnected` | `boolean` | Whether currently connected to the host. |
+| `token` | `string | undefined` | The auth token received from the host. |
+| `hostId` | `string | undefined` | The host container's UUID. |
+
+## Events (Zod v4 schema)
+
+### connected
+
+Event emitted by ContainerLink
+
+
+
+### disconnected
+
+Event emitted by ContainerLink
+
+
+
+### evalRequest
+
+Event emitted by ContainerLink
+
+
+
+### reconnecting
+
+Event emitted by ContainerLink
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `connectionCount` | `number` | Number of currently connected web containers |
+| `port` | `number` | Port the WebSocket server is listening on |
+| `listening` | `boolean` | Whether the WebSocket server is listening |
+
+## Examples
+
+**features.containerLink**
+
+```ts
+const link = container.feature('containerLink', {
+ enable: true,
+ hostUrl: 'ws://localhost:8089',
+})
+await link.connect()
+
+// Send events to the host
+link.emitToHost('click', { x: 100, y: 200 })
+
+// Listen for eval requests before they execute
+link.on('evalRequest', (code, requestId) => {
+ console.log('Host is evaluating:', code)
+})
+```
+