@soederpop/luca 0.0.31 → 0.0.34

package/docs/apis/features/agi/openapi.md

@@ -92,7 +92,7 @@ Convert a single endpoint (by name) to an OpenAI function definition.
 
 Return a compact JSON summary of all endpoints, useful for logging or REPL inspection.
 
-**Returns:** `void`
+**Returns:** `{ title: string, version: string, serverUrl: string, endpointCount: number, endpoints: object[]`
 
 
 
@@ -109,7 +109,7 @@ Return a compact JSON summary of all endpoints, useful for logging or REPL inspe
 
 ## Events (Zod v4 schema)
 
-### loaded
+### started
 
 Event emitted by OpenAPI
 

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

@@ -0,0 +1,227 @@
+# SkillsLibrary (features.skillsLibrary)
+
+Manages a registry of skill locations — folders containing SKILL.md files. Persists known locations to ~/.luca/skills.json and scans them on start. Each skill folder can be opened as a DocsReader for AI-assisted Q&A. Exposes tools for assistant integration via assistant.use(skillsLibrary).
+
+## Usage
+
+```ts
+container.feature('skillsLibrary', {
+  // Override path for skills.json (defaults to ~/.luca/skills.json)
+  configPath,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `configPath` | `string` | Override path for skills.json (defaults to ~/.luca/skills.json) |
+
+## Methods
+
+### start
+
+Start the skills library: read config, scan all locations.
+
+**Returns:** `Promise<SkillsLibrary>`
+
+
+
+### addLocation
+
+Add a new skill location folder and scan it for skills.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `locationPath` | `string` | ✓ | Path to a directory containing skill subfolders with SKILL.md |
+
+**Returns:** `Promise<void>`
+
+
+
+### removeLocation
+
+Remove a skill location and its skills from the library.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `locationPath` | `string` | ✓ | The location path to remove |
+
+**Returns:** `Promise<void>`
+
+
+
+### scanLocation
+
+Scan a location folder for skill subfolders containing SKILL.md.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `locationPath` | `string` | ✓ | Absolute path to scan |
+
+**Returns:** `Promise<void>`
+
+
+
+### list
+
+Return all discovered skills.
+
+**Returns:** `SkillInfo[]`
+
+
+
+### find
+
+Find a skill by name.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `skillName` | `string` | ✓ | Parameter skillName |
+
+**Returns:** `SkillInfo | undefined`
+
+
+
+### createSkillReader
+
+Create a DocsReader for a skill's folder, enabling AI-assisted Q&A.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `skillName` | `string` | ✓ | Name of the skill to create a reader for |
+
+**Returns:** `DocsReader`
+
+
+
+### ensureFolderCreatedWithSkillsByName
+
+Create a tmp directory containing symlinked/copied skill folders by name, suitable for passing to claude --add-dir.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `skillNames` | `string[]` | ✓ | Array of skill names to include |
+
+**Returns:** `string`
+
+
+
+### searchAvailableSkills
+
+Search available skills, optionally filtered by a query string.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `{ query }` | `{ query?: string }` |  | Parameter { query } |
+
+**Returns:** `Promise<string>`
+
+
+
+### loadSkill
+
+Load a skill's full SKILL.md content and metadata.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `{ skillName }` | `{ skillName: string }` | ✓ | Parameter { skillName } |
+
+**Returns:** `Promise<string>`
+
+
+
+### askSkillBasedQuestion
+
+Ask a question about a specific skill using a DocsReader.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `{ skillName, question }` | `{ skillName: string; question: string }` | ✓ | Parameter { skillName, question } |
+
+**Returns:** `Promise<string>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `skills` | `Record<string, SkillInfo>` | Discovered skills keyed by name. |
+| `availableSkills` | `any` |  |
+| `skillsTable` | `Record<string, string>` |  |
+| `configPath` | `string` | Resolved path to the skills.json config file. |
+| `isStarted` | `boolean` | Whether the library has been loaded. |
+
+## Events (Zod v4 schema)
+
+### started
+
+Fired after all skill locations have been scanned
+
+
+
+### locationAdded
+
+Fired when a new skill location is registered
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The absolute path of the added location |
+
+
+
+### skillDiscovered
+
+Fired when a skill is discovered during scanning
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The SkillInfo object |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `loaded` | `boolean` | Whether skill locations have been scanned |
+| `locations` | `array` | Tracked skill location folder paths |
+| `skillCount` | `number` | Total number of discovered skills |
+| `skills` | `object` | Discovered skills keyed by name |
+
+## Examples
+
+**features.skillsLibrary**
+
+```ts
+const lib = container.feature('skillsLibrary')
+await lib.start()
+await lib.addLocation('~/.claude/skills')
+lib.list() // => SkillInfo[]
+const reader = lib.createSkillReader('my-skill')
+```
+

package/docs/apis/features/node/content-db.md

@@ -19,6 +19,32 @@ container.feature('contentDb', {
 
 ## Methods
 
+### renderTree
+
+Render a tree view of the collection directory structure. Built with container.fs so it works without the `tree` binary.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ depth?: number; dirsOnly?: boolean }` |  | Parameter options |
+
+**Returns:** `string`
+
+
+
+### grep
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `string | GrepOptions` | ✓ | Parameter options |
+
+**Returns:** `void`
+
+
+
 ### query
 
 Query documents belonging to a specific model definition.
@@ -228,16 +254,111 @@ Rebuild the entire search index from scratch.
 
 
 
+### getCollectionOverview
+
+Returns a high-level overview of the collection.
+
+**Returns:** `void`
+
+
+
+### listDocuments
+
+List document IDs, optionally filtered by model or glob.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ model?: string; glob?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### readDocument
+
+Read a single document with optional section filtering.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ id: string; include?: string[]; exclude?: string[]; meta?: boolean }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### readMultipleDocuments
+
+Read multiple documents with optional section filtering.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ ids: string[]; include?: string[]; exclude?: string[]; meta?: boolean }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### queryDocuments
+
+Query documents by model with filters, sort, limit.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ model: string; where?: string; sort?: string; limit?: number; offset?: number; select?: string[] }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### searchContent
+
+Grep/text search across the collection.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ pattern: string; caseSensitive?: boolean }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### semanticSearch
+
+Hybrid semantic search with graceful fallback to grep.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ query: string; limit?: number }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
 ## Getters
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `isLoaded` | `any` | Whether the content database has been loaded. |
-| `collection` | `any` | Returns the lazily-initialized Collection instance for the configured rootPath. |
-| `collectionPath` | `any` | Returns the absolute resolved path to the collection root directory. |
+| `isLoaded` | `boolean` | Whether the content database has been loaded. |
+| `collection` | `Collection` | Returns the lazily-initialized Collection instance for the configured rootPath. |
+| `collectionPath` | `string` | Returns the absolute resolved path to the collection root directory. |
 | `models` | `Record<string, ModelDefinition>` | Returns an object mapping model names to their model definitions, sourced from the collection. |
 | `modelNames` | `string[]` | Returns an array of all registered model names from the collection. |
-| `searchIndexStatus` | `any` | Get the current search index status. |
+| `available` | `string[]` | Returns the available document ids in the collection |
+| `modelDefinitionTable` | `Record<string, { description: string; glob: string; routePatterns: string[] }>` |  |
+| `fileTree` | `string` |  |
+| `searchIndexStatus` | `{ exists: boolean; documentCount: number; chunkCount: number; embeddingCount: number; lastIndexedAt: any; provider: any; model: any; dimensions: number; dbSizeBytes: number }` | Get the current search index status. |
 | `queries` | `Record<string, ReturnType<typeof this.query>>` | Returns an object with query builders keyed by model name (singular and plural, lowercased). Provides a convenient shorthand for querying without looking up model definitions manually. |
 
 ## Events (Zod v4 schema)

package/docs/apis/features/node/disk-cache.md

@@ -22,7 +22,7 @@ Retrieve a file from the disk cache and save it to the local disk
 | `outputPath` | `string` | ✓ | The local path where the file should be saved |
 | `isBase64` | `any` |  | Whether the cached content is base64 encoded |
 
-**Returns:** `void`
+**Returns:** `Promise<Buffer | string>`
 
 ```ts
 await diskCache.saveFile('myFile', './output/file.txt')
@@ -42,7 +42,7 @@ Ensure a key exists in the cache, setting it with the provided content if it doe
 | `key` | `string` | ✓ | The cache key to check/set |
 | `content` | `string` | ✓ | The content to set if the key doesn't exist |
 
-**Returns:** `void`
+**Returns:** `Promise<string>`
 
 ```ts
 await diskCache.ensure('config', JSON.stringify(defaultConfig))
@@ -62,7 +62,7 @@ Copy a cached item from one key to another
 | `destination` | `string` | ✓ | The destination cache key |
 | `overwrite` | `boolean` |  | Whether to overwrite if destination exists (default: false) |
 
-**Returns:** `void`
+**Returns:** `Promise<string>`
 
 ```ts
 await diskCache.copy('original', 'backup')
@@ -83,7 +83,7 @@ Move a cached item from one key to another (copy then delete source)
 | `destination` | `string` | ✓ | The destination cache key |
 | `overwrite` | `boolean` |  | Whether to overwrite if destination exists (default: false) |
 
-**Returns:** `void`
+**Returns:** `Promise<string>`
 
 ```ts
 await diskCache.move('temp', 'permanent')
@@ -102,7 +102,7 @@ Check if a key exists in the cache
 |------|------|----------|-------------|
 | `key` | `string` | ✓ | The cache key to check |
 
-**Returns:** `void`
+**Returns:** `Promise<boolean>`
 
 ```ts
 if (await diskCache.has('myKey')) {
@@ -123,7 +123,7 @@ Retrieve a value from the cache
 | `key` | `string` | ✓ | The cache key to retrieve |
 | `json` | `any` |  | Whether to parse the value as JSON (default: false) |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 ```ts
 const text = await diskCache.get('myText')
@@ -144,7 +144,7 @@ Store a value in the cache
 | `value` | `any` | ✓ | The value to store (string, object, or any serializable data) |
 | `meta` | `any` |  | Optional metadata to associate with the cached item |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 ```ts
 await diskCache.set('myKey', 'Hello World')
@@ -164,7 +164,7 @@ Remove a cached item
 |------|------|----------|-------------|
 | `key` | `string` | ✓ | The cache key to remove |
 
-**Returns:** `void`
+**Returns:** `Promise<any>`
 
 ```ts
 await diskCache.rm('obsoleteKey')
@@ -182,7 +182,7 @@ Clear all cached items
 |------|------|----------|-------------|
 | `confirm` | `any` |  | Must be set to true to confirm the operation |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 ```ts
 await diskCache.clearAll(true) // Must explicitly confirm
@@ -237,8 +237,8 @@ const customCache = diskCache.create('/custom/cache/path')
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `cache` | `any` | Returns the underlying cacache instance configured with the cache directory path. |
-| `securely` | `any` | Get encrypted cache operations interface Requires encryption to be enabled and a secret to be provided |
+| `cache` | `ReturnType<typeof this.create>` | Returns the underlying cacache instance configured with the cache directory path. |
+| `securely` | `{ set(name: string, payload: any, meta?: any): Promise<any>; get(name: string): Promise<any> }` | Get encrypted cache operations interface Requires encryption to be enabled and a secret to be provided |
 
 ## State (Zod v4 schema)
 

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

@@ -21,7 +21,7 @@ Downloads a file from a URL and saves it to the specified local path. This metho
 | `url` | `string` | ✓ | The URL to download the file from. Must be a valid HTTP/HTTPS URL. |
 | `targetPath` | `string` | ✓ | The local file path where the downloaded file should be saved. |
 
-**Returns:** `void`
+**Returns:** `Promise<string>`
 
 ```ts
 // Download an image file

package/docs/apis/features/node/file-manager.md

@@ -29,7 +29,7 @@ Matches the file IDs against the pattern(s) provided
 |------|------|----------|-------------|
 | `patterns` | `string | string[]` | ✓ | The patterns to match against the file IDs |
 
-**Returns:** `void`
+**Returns:** `string[]`
 
 
 
@@ -43,7 +43,7 @@ Matches the file IDs against the pattern(s) provided and returns the file object
 |------|------|----------|-------------|
 | `patterns` | `string | string[]` | ✓ | The patterns to match against the file IDs |
 
-**Returns:** `void`
+**Returns:** `(File | undefined)[]`
 
 
 
@@ -63,7 +63,7 @@ Starts the file manager and scans the files in the project.
 |----------|------|-------------|
 | `exclude` | `any` | The patterns to exclude from the scan |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
@@ -83,7 +83,7 @@ Scans the files in the project and updates the file manager state.
 |----------|------|-------------|
 | `exclude` | `any` | The patterns to exclude from the scan |
 
-**Returns:** `void`
+**Returns:** `Promise<this>`
 
 
 
@@ -104,13 +104,13 @@ Watches directories for file changes. Can be called multiple times to add more d
 | `paths` | `any` | Specific directories or globs to watch. Defaults to project directoryIds. |
 | `exclude` | `any` | The patterns to exclude from the watch |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 
 
 ### stopWatching
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 
 
@@ -122,7 +122,7 @@ Watches directories for file changes. Can be called multiple times to add more d
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | Parameter path |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 
 
@@ -134,7 +134,7 @@ Watches directories for file changes. Can be called multiple times to add more d
 |------|------|----------|-------------|
 | `path` | `string` | ✓ | Parameter path |
 
-**Returns:** `void`
+**Returns:** `Promise<void>`
 
 
 
@@ -142,13 +142,13 @@ Watches directories for file changes. Can be called multiple times to add more d
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `fileIds` | `any` | Returns an array of all relative file paths indexed by the file manager. |
-| `fileObjects` | `any` | Returns an array of all file metadata objects indexed by the file manager. |
-| `directoryIds` | `any` | Returns the directory IDs for all of the files in the project. |
-| `uniqueExtensions` | `any` | Returns an array of unique file extensions found across all indexed files. |
-| `isStarted` | `any` | Whether the file manager has completed its initial scan. |
-| `isStarting` | `any` | Whether the file manager is currently performing its initial scan. |
-| `isWatching` | `any` | Whether the file watcher is actively monitoring for changes. |
+| `fileIds` | `string[]` | Returns an array of all relative file paths indexed by the file manager. |
+| `fileObjects` | `File[]` | Returns an array of all file metadata objects indexed by the file manager. |
+| `directoryIds` | `string[]` | Returns the directory IDs for all of the files in the project. |
+| `uniqueExtensions` | `string[]` | Returns an array of unique file extensions found across all indexed files. |
+| `isStarted` | `boolean` | Whether the file manager has completed its initial scan. |
+| `isStarting` | `boolean` | Whether the file manager is currently performing its initial scan. |
+| `isWatching` | `boolean` | Whether the file watcher is actively monitoring for changes. |
 | `watchedPaths` | `string[]` | Returns the list of directories currently being watched. |
 | `watchedFiles` | `Record<string, string[]>` | Returns the directories and files currently being watched by chokidar. |