@muskanmeet/invoicing-design-system 0.1.0

package/.local/skills/image-search/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: image-search
+description: Find real web images, logos, and public photos for brand work, reports, and artifacts. Use when you need a few relevant results with a title and image URL you can inspect, present, or download.
+---
+
+# Image Search
+
+Search the public web for real images.
+
+## When to Use
+
+- You need real logos, transparent PNGs, or brand assets from the web
+- You need real-world photos or reference images from the public web
+
+## When NOT to Use
+
+- Generating new images or illustrations (use the `media-generation` skill)
+- General fact lookup or webpage text retrieval (use the `web-search` skill)
+- Extracting brand colors, fonts, and other official tokens from a website (use `extractBranding` first)
+
+## Available Function
+
+### `imageSearch({ query, count })`
+
+Search for public web images and return the raw provider response body.
+
+**Parameters:**
+
+- `query` (str, required): Search text for the desired images
+- `count` (int, optional): Maximum number of results to return
+
+**Returns:** Dict with optional `results` list. For each result, rely on `result.title` and `result.properties?.url`; other provider-specific fields may also be present.
+
+**Example response:**
+
+```json
+{
+  "type": "images",
+  "query": {
+    "original": "mid-century chair",
+    "spellcheck_off": false,
+    "show_strict_warning": false
+  },
+  "results": [
+    {
+      "type": "image_result",
+      "title": "Mid-century chair in walnut",
+      "url": "https://example.com/chairs",
+      "source": "example.com",
+      "page_fetched": "2026-04-17T23:51:41Z",
+      "thumbnail": {
+        "src": "https://imgs.example.com/thumb.jpg",
+        "width": 500,
+        "height": 333
+      },
+      "properties": {
+        "url": "https://imgs.example.com/full.jpg",
+        "placeholder": "https://imgs.example.com/placeholder.jpg",
+        "width": 1200,
+        "height": 800
+      },
+      "meta_url": {
+        "scheme": "https",
+        "netloc": "example.com",
+        "hostname": "example.com",
+        "favicon": "https://example.com/favicon.ico",
+        "path": "› chairs"
+      },
+      "confidence": "high"
+    }
+  ],
+  "extra": {
+    "might_be_offensive": false
+  }
+}
+```
+
+**Example:**
+
+```javascript
+const response = await imageSearch({
+  query: "vintage travel posters",
+  count: 6,
+})
+
+const items = response.results ?? []
+for (const item of items.slice(0, 4)) {
+  console.log(item.title, item.properties?.url)
+}
+```
+
+## Present Results
+
+When showing image results to the user:
+
+1. Pick up to 4 strong results
+2. Download each image URL into `attached_assets/image_search/`
+3. Call `presentAsset({awaitUserInput: false})` for each saved file
+
+```javascript
+const fs = await import('node:fs/promises')
+const path = await import('node:path')
+
+const response = await imageSearch({
+  query: "mid-century chair",
+  count: 4,
+})
+
+const items = (response.results ?? []).slice(0, 4)
+await fs.mkdir('attached_assets/image_search', {recursive: true})
+
+for (const [index, item] of items.entries()) {
+  const imageUrl = item.properties?.url
+  if (!imageUrl) continue
+
+  const download = await fetch(imageUrl)
+  if (!download.ok) continue
+
+  const filePath = path.join(
+    'attached_assets/image_search',
+    'result_' + String(index + 1) + '.jpg',
+  )
+
+  await fs.writeFile(filePath, Buffer.from(await download.arrayBuffer()))
+
+  await presentAsset({
+    filePath,
+    title: item.title ?? 'Image search result',
+    awaitUserInput: false,
+  })
+}
+```
+
+## When called from the slides skill
+
+The slides skill runs `imageSearch` as part of its brand-research steps in `../slides/references/brand_research.md`. That reference owns the order (run `extractBranding` first, use `imageSearch` for the logo only when the first step's logo is missing or low quality, and use `imageSearch` for real-world photos like product / team / venue shots) and the budget (at most 4 `imageSearch` calls per deck).
+
+**Specific real subjects have a special rule.** If `imageSearch` cannot find a clean image of a logo, a named person, a specific real product, a real team, a real venue, or a real event, leave the slot empty and surface the gap to the user. **Do NOT auto-generate a stand-in via `media-generation` without explicit user approval** — a fabricated logo or fake "real" photo for a named entity is exactly the failure mode the research steps exist to prevent. The `media-generation` fallback applies only to **generic, non-specific** visuals (abstract backgrounds, mood imagery, anonymous skylines, generic illustrations). In named-entity decks (product launches, founder profiles, company overviews) the deck subject often makes product, team, and venue slots specific — treat those as real subjects and leave them empty until the user approves a stand-in. Align with `../slides/references/brand_research.md` → "Failures".
+
+Follow these steps rather than improvising the order — these are billable passthrough calls.
+
+## Best Practices
+
+1. Use `imageSearch`, not provider-specific passthrough callbacks, so the implementation can change underneath without changing your code.
+2. For logos, search `"<company> logo png"` or `"<company> logo transparent"` and prefer official domains, press kits, or brand asset pages.
+3. Present a small shortlist of the best results instead of dumping the full response body.
+4. Use `extractBranding` first for official brand tokens, then fall back to `imageSearch` only when the logo is missing, low quality, or clearly wrong.
+5. Keep `count` small when you are manually reviewing results. `4` to `8` is usually enough.
+6. Save chosen image URLs into `attached_assets/` before presenting or reusing them elsewhere.
+7. Remember that `count` is the maximum number of results, not the total number of results. When presenting to the user, there may be less results presented than how many you requested.

package/.local/skills/integrations/.fingerprint

@@ -0,0 +1 @@
+f6328d37bfdad99d3153f7496feb3098

package/.local/skills/integrations/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: integrations
+description: Search and manage Replit integrations including blueprints, connectors, and connections. Use for authentication, databases, payments, and third-party API integrations.
+---
+
+# Integrations Skill
+
+Integrations allow first-class usage of Third-Party (and some First-party) technologies. If the integration exists, you can ask user to "connect" their account (Google, Linear, GitHub, Stripe, etc) to their Replit account, which critically gives you, the Replit Agent, access to new capabilities (e.g. view their Google Sheets, read their Linear issues, setup & access payment systems, etc). You must follow the  steps outlined here to successfully make these "connections".
+
+**Before asking the user for any API key, secret, or credential, always search for a Replit integration first.** Replit integrations handle OAuth and secrets securely, and many common services (Google Sheets, Linear, Stripe, GitHub, OpenAI, etc.) are already supported. Asking the user for credentials when an integration exists adds a lot of unnecessary friction. Users typically do not know about our integration system, you must proactive in suggesting it when it (and only when) it is relevant.
+
+Integrations include blueprints (code templates), connectors (OAuth/API integrations + templates), and connections (already established integrations).
+
+## When to Use
+
+Use this skill when:
+
+- User needs authentication (login, signup, OAuth)
+- User needs database connections (PostgreSQL, MongoDB, etc.)
+- User needs payment processing (Stripe, etc.)
+- User needs third-party API integrations (OpenAI, Notion, GitHub, Linear, etc.)
+- User asks about Replit-specific features and capabilities
+
+## When NOT to Use
+
+As a web search (use web-search skill if available), searching files within the project, media generation (use media-generation skill, including image generation APIs), fetching data to respond to a user's question (use query-integration-data skill).
+
+---
+
+## Integration Lifecycle
+
+There are three types of integrations, and they represent different stages of a lifecycle:
+
+```text
+connector (not_setup)
+    → user completes OAuth via proposeIntegration
+    → connection (not_added)
+        → addIntegration        ← code-side wiring (npm packages, scaffolds, project registration)
+        → proposeIntegration    ← platform-side binding (registers this Repl with connectors so the credential proxy will serve secrets)
+        → now it is a functioning connection (added + authorized, ready to use)
+
+blueprint (not_installed)
+    → addIntegration or proposeIntegration
+    → blueprint (installed, code + packages added to project), ready to use
+```
+
+### Connectors
+
+- An available OAuth/API integration that has **not yet been authorized** by the user
+- Status: `not_setup`
+- Cannot be added directly — must use `proposeIntegration` which allows the user through the OAuth flow
+- Example ID: `connector:ccfg_google-sheet_E42A9F6DA6...`
+
+### Connections
+
+- A connector that has **already been authorized** at the account level
+- Status: `not_added` (authorized at account level but not bound to this Repl) or `added` (active in this Repl)
+- Both `addIntegration` AND `proposeIntegration` are required on first setup — they do orthogonal things:
+  - `addIntegration` does code-side wiring (npm install, scaffolds, project registration). It does NOT touch the platform's connection-state backend.
+  - `proposeIntegration` does platform-side binding (registers this Repl with connectors-v2 as a permitted consumer). Without it the credential proxy at `connectors.replit.com/api/v2/connection` returns nothing for this Repl, even though the underlying credentials exist at the account level.
+- Example ID: `connection:conn_linear_01MG99PAJR6MQ5...`
+
+NOTE: You must not delay calling proposeIntegration even if it waits for the user. You will be blocked and not have access to test the feature you build because you don't have access to real data, real APIs, etc, which is even more inefficient than reaching out to the user as soon as you know you need the integration to get accepted.
+
+### Blueprints
+
+- These are just code templates that install packages and scaffold integration boilerplate
+- Status: `not_installed` or `previously_installed`
+- Use `addIntegration` directly; if `requiresConfirmation` is True, use `proposeIntegration` instead
+- Example ID: `blueprint:javascript_openai`
+
+---
+
+## Available Functions
+
+All functions are available directly in the `code_execution` sandbox. **Always use `console.log()` on return values** — functions execute silently with no output if you don't.
+
+### searchIntegrations(query)
+
+Search for available integrations. **Always run this first.** Try a few different query terms if the first search returns nothing — results depend on keyword matching.
+
+**Returns:** Dict with:
+
+- `integrations`: list of integration objects, each with `id`, `displayName`, `description`, `integrationType`, `status`
+- `askForBlueprintConfirmation`: boolean — if True, blueprint additions in this environment will require user confirmation; expect `requiresConfirmation: True` back from `addIntegration` and be ready to call `proposeIntegration` instead
+
+```javascript
+const results = await searchIntegrations("Google Sheets");
+console.log(results);
+// { integrations: [{ id: 'connector:ccfg_google-sheet_...', displayName: 'Google Sheets',
+//   description: '...', integrationType: 'connector', status: 'not_setup' }], ... }
+
+// Always log — calling without console.log produces no visible output!
+for (const item of results.integrations) {
+  console.log(`${item.id}  type=${item.integrationType}  status=${item.status}`);
+}
+```
+
+**Notes:**
+
+- When the user has not explicitly requested a specific provider, at least search with a generic, capability-focused query to ensure all relevant options are returned. For example, when user asks "build an icon generating app", prefer `searchIntegrations("image generation")` instead of `searchIntegrations("OpenAI image generation")`
+- If a connector has already been authorized by the user or a teammate, it will appear as a `connection` (not a `connector`) in results
+- Try multiple queries if needed: `"stripe"`, `"payments"`, `"stripe payment processing"` may return different results
+- The `id` field is the exact string to pass to subsequent functions
+
+---
+
+### viewIntegration(integrationId)
+
+Fetch full details and the code snippet for an integration without adding it to the project.
+
+**Returns:** Dict with `integrationType`, `integrationId`, `displayName`, `renderedContent`
+
+**Note:** `addIntegration` returns the exact same `renderedContent` blob, so in most cases you don't need to call this separately — just read the result of `addIntegration`. The main reason to call `viewIntegration` first is if you want to inspect the package name, code snippet, or documentation URL before committing to the install.
+
+```javascript
+const info = await viewIntegration("connection:conn_linear_01KG10PAJR6MQ525SQSWEB8QHC");
+console.log(info.renderedContent);  // Same blob you'd get from addIntegration
+```
+
+---
+
+### addIntegration(integrationId)
+
+Add a blueprint or connection to the current project. **Do not use for connectors** (those with `integrationType: connector` and `status: not_setup`) — use `proposeIntegration` for those.
+
+**Returns:** Dict with:
+
+- `success`: boolean
+- `requiresConfirmation`: boolean — if True, call `proposeIntegration` instead
+- `connectionAlreadyAdded`: boolean — if True, the connection is already wired to this project; skip addIntegration but still call proposeIntegration to ensure the platform binding is current (tokens expire, bindings can be stale)
+- `renderedContent`: same XML blob as `viewIntegration`
+- `observations`: list of stringified observation objects (verbose; contains npm install output)
+
+**Side effect:** Automatically installs required packages. This will restart or crash a running dev server — be aware if calling mid-session while the workflow is running.
+
+```javascript
+const result = await addIntegration("connection:conn_linear_01KG10PAJR6MQ525SQSWEB8QHC");
+console.log(result.success);       // true
+console.log(result.observations);  // Contains package installation output as stringified objects
+
+// Handle confirmation requirement
+if (!result.success && result.requiresConfirmation) {
+  proposeIntegration("connection:conn_linear_01KG10PAJR6MQ525SQSWEB8QHC");
+}
+```
+
+**After calling addIntegration:**
+
+- Read `renderedContent` to get the code snippet
+- The snippet handles token refresh and expiry — use it as-is, don't simplify it
+- Never cache the client object the snippet creates — tokens expire
+
+---
+
+### proposeIntegration(integrationId)
+
+Propose a connector to the user. This is a **control-flow operation** — it exits the agent loop immediately and waits for the user to complete OAuth or confirm setup. Nothing after this call will execute in the current loop.
+
+**Returns:** Dict with `success`, `displayName`, `exitLoop` (always True)
+
+**Use for:**
+
+- Connectors with `status: not_setup` (drives OAuth + binding)
+- Connections with `status: not_added` after calling `addIntegration` (drives the binding only)
+- Connections with `status: added` if runtime fails with "not connected" (re-binds / refreshes)
+- Blueprints where `addIntegration` returns `requiresConfirmation: True`
+
+```javascript
+// Always explain to the user what is about to happen before calling this
+// The agent loop exits after this — no further code runs
+const result = await proposeIntegration("connector:ccfg_google-sheet_E42A9F6CA62546F68A1FECA0E8");
+```
+
+**Notes:**
+
+- After the user completes OAuth, the connector becomes a `connection`
+- On the next agent loop, call `addIntegration` with the new `connection:...` ID
+- There is no user-visible message automatically shown when this exits — explain what you're doing in your chat response before calling it
+
+---
+
+## Using the Code Snippet
+
+After `addIntegration` or `viewIntegration`, the `renderedContent` contains a code snippet. Key things to know:
+
+1. **It is not on the filesystem.** Copy it into a new file in your project (e.g., `server/googleSheets.ts`)
+2. **Never cache the client.** Tokens expire. The snippet exports a `getUncachable___Client()` function — call it fresh on every request
+3. **The token refresh logic is correct as-is.** Don't simplify or remove the expiry check
+4. **The snippet uses environment variables** (`REPLIT_CONNECTORS_HOSTNAME`, `REPL_IDENTITY`, `WEB_REPL_RENEWAL`) that Replit injects automatically — no setup needed
+
+---
+
+## Databricks
+
+When the user wants to connect to Databricks, use the `databricks-m2m` connector (not the plain `databricks` connector). The `databricks-m2m` connector provides machine-to-machine access and works in all contexts. Inside a Databricks App, prefer the `databricks` (U2M) connector when available — see the `databricks-app` skill for details.
+
+## Common Pitfalls
+
+- **Not logging results:** `searchIntegrations` and all other functions return silently unless you `console.log()` the output
+- **Calling addIntegration on a connector:** Will fail or behave unexpectedly. Check `integrationType` first
+- **Asking for API keys when a connection exists:** If `searchIntegrations` returns a `connection`, the user is already authenticated at the account level — use `addIntegration` to wire the project, then `proposeIntegration` to bind this Repl to the connection. Both steps are always required.
+- **Caching the client:** The boilerplate snippet is explicit about this. Tokens expire. Always call `getUncachable___Client()` fresh
+- **Package install side effects:** `addIntegration` runs package installation (e.g. npm, uv), which can crash a running dev server. Restart the workflow after adding integrations
+- **Connection added but runtime still fails:** If `addIntegration` succeeds for a `connection` but the app throws "not connected" at runtime, the token may be expired or missing. Call `proposeIntegration` with the same connection ID to trigger re-authorization, then restart the workflow

package/.local/skills/media-generation/.fingerprint

@@ -0,0 +1 @@
+2045a413396b1be9a2f543199b49e281

package/.local/skills/media-generation/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: media-generation
+description: "Generate and retrieve media including AI-generated images and stock images. Use this skill for visual content creation and retrieval. For AI video clips, read `media-generation/video_generation.md`; for music, sound effects, and text-to-speech audio, read `media-generation/audio_generation.md`"
+---
+
+# Media Generation Skill
+
+Generate custom images, and retrieve stock images.
+
+## Available Functions
+
+### generateImage(images, ...)
+
+Generate custom images from text descriptions. Waits for generation to complete before returning.
+
+**Parameters:**
+
+- `images` (list, **required**): A list of image request objects. **This wrapper is always required — even for a single image, pass `images: [{ ... }]`**. Up to 10 images can be generated in a single call. Each dict should have:
+  - `prompt` (required): Text description of the desired image
+  - `outputPath`: File path **must end in `.png`** — this is the only accepted format. `.jpg`, `.jpeg`, `.webp`, and other extensions will cause an error. Defaults to `attached_assets/generated_images/{summary}.png`
+  - `aspectRatio`: Optional, defaults to "1:1". Options: "1:1", "3:4", "4:3", "9:16", "16:9"
+  - `negativePrompt`: Optional, description of what should NOT appear
+  - `summary`: Optional, short 4-5 word description for default filename
+  - `removeBackground`: Optional, defaults to False
+- `overwrite` (bool, default True): Whether to overwrite existing files
+
+**Returns:** Dict with `images` list (each with `filePath` and `description`) and optional `failures` list
+
+**Common Mistakes:**
+
+```javascript
+// WRONG — flat params without images array (causes "images field required" error)
+await generateImage({ prompt: "A mountain landscape", outputPath: "hero.png" });
+
+// CORRECT — always wrap in images: [...], even for a single image
+await generateImage({ images: [{ prompt: "A mountain landscape", outputPath: "hero.png" }] });
+
+// WRONG — .jpg extension is not supported (causes "outputPath must end with .png" error)
+await generateImage({ images: [{ prompt: "A cityscape", outputPath: "city.jpg" }] });
+
+// CORRECT — only .png is accepted
+await generateImage({ images: [{ prompt: "A cityscape", outputPath: "city.png" }] });
+```
+
+**Examples:**
+
+```javascript
+// Single image
+const result = await generateImage({
+    images: [
+        {
+            prompt: "A serene mountain landscape at sunset with snow-capped peaks",
+            outputPath: "src/assets/images/hero.png",
+            aspectRatio: "16:9",
+            negativePrompt: "blurry, low quality",
+        }
+    ]
+});
+console.log(`Image saved to: ${result.images[0].filePath}`);
+
+// Multiple images at once
+const result = await generateImage({
+    images: [
+        { prompt: "A red apple", outputPath: "assets/apple.png" },
+        { prompt: "A yellow banana", outputPath: "assets/banana.png" },
+        { prompt: "An orange", outputPath: "assets/orange.png", removeBackground: true },
+    ]
+});
+for (const img of result.images) {
+    console.log(`Generated: ${img.filePath}`);
+}
+```
+
+### generateImageAsync(images, ...)
+
+Generate images asynchronously. Returns immediately with a workflow ID. Same parameters as `generateImage`.
+
+**Returns:** Dict with `workflowId`, `workflowAlias`, `status`, and `imagePaths`
+
+**Example:**
+
+```javascript
+const result = await generateImageAsync({
+    images: [
+        { prompt: "A complex detailed illustration", outputPath: "assets/illustration.png" },
+    ]
+});
+console.log(`Started workflow: ${result.workflowAlias}`);
+console.log(`Images will be saved to: ${result.imagePaths}`);
+```
+
+### stockImage(description, ...)
+
+Retrieve stock images matching a description.
+
+**Parameters:**
+
+- `description` (str, required): Text description of desired stock image(s)
+- `summary` (str, default "stock_image"): Short description for the filename
+- `limit` (int, default 1): Number of images to retrieve (1-10)
+- `orientation` (str, default "horizontal"): "horizontal", "vertical", or "all"
+
+**Returns:** Dict with `filePaths` list and `query` string
+
+**Example:**
+
+```javascript
+const result = await stockImage({
+    description: "modern office with natural lighting",
+    summary: "office background",
+    limit: 3,
+    orientation: "horizontal"
+});
+for (const path of result.filePaths) {
+    console.log(`Stock image saved to: ${path}`);
+}
+```
+
+## When to Use Each Function
+
+### generateImage / generateImageAsync
+
+- Custom illustrations or graphics not available elsewhere
+- Specific visual concepts or designs
+- Placeholder images for development
+- Creative or artistic content
+- Use `generateImageAsync` when images are not needed immediately
+
+### stockImage
+
+- Professional photography
+- Real-world scenes and people
+- Business and corporate imagery
+- When authenticity is more important than customization
+
+## Aspect Ratio Guidelines
+
+### Images
+
+- **1:1** - Square, good for profile pictures, thumbnails, icons
+- **3:4** - Portrait, good for mobile screens, product images
+- **4:3** - Landscape, good for presentations, desktop displays
+- **9:16** - Vertical, good for mobile stories, tall banners
+- **16:9** - Widescreen, good for hero images, video thumbnails
+
+## Best Practices
+
+1. **Write detailed prompts**: Include style, mood, lighting, colors, and composition
+2. **Use negative prompts**: Exclude unwanted elements like "blurry", "watermark", "text"
+3. **Choose appropriate formats**: Match aspect ratio and media type to intended use
+4. **Consider stock for realism**: Use stock images when you need authentic photography
+5. **Do not over generate**: Only generate multiple images when the user explicitly asks.
+
+## Output Locations
+
+- Generated images: `attached_assets/generated_images/`
+- Stock images: `attached_assets/stock_images/`
+
+## Limitations
+
+- Stock image availability depends on the search query
+- Complex or highly specific prompts may not match exactly
+- Text in generated media is not reliably rendered
+
+## Copyright
+
+- Use this skill to create media assets instead of copying from websites
+- Generated images are created for your use
+- Stock images are licensed for use in your projects
+- Do not download or copy media files from external websites

package/.local/skills/media-generation/audio_generation.md

@@ -0,0 +1,138 @@
+# Audio Generation
+
+## Available Functions
+
+### generateMusic({prompt, ...})
+
+Generate original music from a text prompt and save it as an audio file.
+
+**Parameters:**
+
+- `prompt` (str, required): Description of the desired music
+- `outputPath` (str, optional): Must end in `.mp3` for MP3 output or `.ogg` for Opus output. Defaults to `attached_assets/generated_audio/music_{summary}.mp3`
+- `summary` (str, default "generated_music"): Short description for the filename
+- `durationSeconds` (int, optional): 3-600 seconds. If omitted, the model chooses a length
+- `forceInstrumental` (bool, default True): Generate instrumental music
+- `outputFormat` (str, default "mp3_44100_128"): Audio format
+  - Options are alaw_8000, mp3_22050_32, mp3_24000_48, mp3_44100_128, mp3_44100_192, mp3_44100_32, mp3_44100_64, mp3_44100_96, opus_48000_128, opus_48000_192, opus_48000_32, opus_48000_64, opus_48000_96, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000, pcm_8000, ulaw_8000, wav_16000, wav_22050, wav_24000, wav_32000, wav_44100, wav_48000, wav_8000
+- `overwrite` (bool, default True): Whether to overwrite existing files
+
+**Returns:** Dict with `filePath` and `description` keys
+
+**Example:**
+
+```javascript
+const result = await generateMusic({
+    prompt: "Upbeat electronic background music with warm synths and a steady pulse",
+    summary: "upbeat synth bed",
+    durationSeconds: 30,
+    forceInstrumental: true
+});
+console.log(`Music saved to: ${result.filePath}`);
+```
+
+### generateSoundEffect({prompt, ...})
+
+Generate a short sound effect from a text prompt and save it as an audio file.
+
+**Parameters:**
+
+- `prompt` (str, required): Description of the sound effect
+- `outputPath` (str, optional): Must end in `.mp3` for MP3 output or `.ogg` for Opus output. Defaults to `attached_assets/generated_audio/sound_effect_{summary}.mp3`
+- `summary` (str, default "sound_effect"): Short description for the filename
+- `durationSeconds` (number, optional): 0.5-30 seconds. If omitted, the model chooses a length
+- `loop` (bool, default False): Create a smoothly looping sound effect
+- `promptInfluence` (number, default 0.3): 0-1, higher follows the prompt more closely
+- `outputFormat` (str, default "mp3_44100_128"): Audio format
+- `overwrite` (bool, default True): Whether to overwrite existing files
+
+**Returns:** Dict with `filePath` and `description` keys
+
+**Example:**
+
+```javascript
+const result = await generateSoundEffect({
+    prompt: "Soft futuristic UI confirmation chime, clean and pleasant",
+    summary: "ui confirmation chime",
+    durationSeconds: 1.5
+});
+console.log(`Sound effect saved to: ${result.filePath}`);
+```
+
+### searchVoices({search, ...})
+
+Search available voices for text-to-speech. Use this before `textToSpeech` when you do not know the `voiceId`.
+
+**Parameters:**
+
+- `search` (str, optional): Search by name, description, or labels
+- `pageSize` (int, default 10): Number of voices to return, 1-100
+- `voiceType` (str, optional): "personal", "community", "default", "workspace", "non-default", "non-community", or "saved"
+- `category` (str, optional): "premade", "cloned", "generated", or "professional"
+- `sort` (str, optional): "created_at_unix" or "name"
+- `sortDirection` (str, optional): "asc" or "desc"
+- `nextPageToken` (str, optional): Token for pagination
+
+**Returns:** Dict containing `voices`, `has_more`, and pagination fields.
+
+### textToSpeech({text, voiceId, ...})
+
+Convert text into speech using a selected voice and save it as an audio file.
+
+**Parameters:**
+
+- `text` (str, required): Text to convert into speech
+- `voiceId` (str, required): Voice ID from `searchVoices`
+- `outputPath` (str, optional): Must end in `.mp3` for MP3 output or `.ogg` for Opus output. Defaults to `attached_assets/generated_audio/speech_{summary}.mp3`
+- `summary` (str, default "speech"): Short description for the filename
+- `modelId` (str, default "eleven_multilingual_v2"): Text-to-speech model ID
+- `outputFormat` (str, default "mp3_44100_128"): Audio format
+- `voiceSettings` (object, optional): Per-request voice settings such as `stability`, `similarity_boost`, `style`, `use_speaker_boost`, and `speed`
+- `overwrite` (bool, default True): Whether to overwrite existing files
+
+**Example:**
+
+```javascript
+const voices = await searchVoices({ search: "warm narrator", pageSize: 5 });
+const voiceId = voices.voices[0].voice_id;
+const result = await textToSpeech({
+    text: "Welcome to a faster way to build.",
+    voiceId,
+    summary: "welcome voiceover"
+});
+console.log(`Speech saved to: ${result.filePath}`);
+```
+
+## When to Use Each Function
+
+### generateMusic
+
+- Original background music, loops, jingles, and music beds
+- Instrumental tracks for videos, games, presentations, or apps
+
+### generateSoundEffect
+
+- UI sounds, notification tones, transitions, ambience, and game SFX
+- Short audio moments for motion graphics or interactive experiences
+
+### searchVoices / textToSpeech
+
+- Voiceovers, narration, read-aloud content, and character speech
+- Use `searchVoices` first when the voice ID is not known
+
+## Best Practices
+
+1. **Write detailed prompts**: Include genre, mood, instrumentation, pacing, duration, and intended use
+
+## Output Locations
+
+- Generated audio: `attached_assets/generated_audio/`
+
+## Limitations
+
+- Generated sound effects: 30 seconds maximum
+- Generated music: 600 seconds maximum
+
+## Copyright
+
+- Generated music, sound effects, and speech are created for your use