# AI chat, OpenRouter and removal URL: https://ship-and-scale.vercel.app/docs/integrations/ai Enable the optional streaming chat example, understand its credits and remove it without breaking the foundation. ## Optional module and provider cost [#optional-module-and-provider-cost] AI is optional and defaults off for a new buyer. The module supplies streaming chat, saved conversations, title search and per-request provider usage accounting. It uses a server-only OpenRouter key through the AI SDK. The model has no tools, project files or workspace database credentials. Every workspace receives 100 credits once when the module is installed/when that workspace is created. One completed response costs one credit. Credits do not renew, expire, refill with subscriptions or move between workspaces. OpenRouter funding is separate: a workspace can have template credits while the provider account cannot fund another request. ## Obtain an OpenRouter key [#obtain-an-openrouter-key] Follow the [OpenRouter token guide](/docs/accounts/openrouter) to create your account, find the key and save it in the root `.env`. The guide covers both enabling AI in your first Kickstart and adding it to an existing managed installation. AI needs `OPENROUTER_API_KEY` and `AI_ENABLED=true`. Keep `AI_ENABLED=false` if you're skipping it. The key remains on the server; don't put it in browser code or email functions. ## Enable and install [#enable-and-install] For a new installation, full Kickstart installs the AI module when enabled, subject to the other required service checks. For an existing managed installation, save the AI settings, then run: ```sh npm run kickstart:ai -- --check npm run kickstart:ai ``` Run each command separately and continue only when its checks pass. The scoped installer checks target identity, the matching receipt, migration checksums, project keys and OpenRouter configuration before applying AI migrations. It saves `AI_ENABLED=true` after installation. It doesn't provision Stripe or reset balances. Restart the app after changes. For production, update the AI runtime variables through the supported deployment workflow. The read-only key/model check sends no generation and cannot prove a successful response. Test a real chat message separately; provider usage costs apply. ## Customize prompts, model and context [#customize-prompts-model-and-context] `lib/ai/config.mjs` defines `DEFAULT_AI_MODEL`, `aiConfig`, `SYSTEM_PROMPT` and context helpers. Change the system prompt to your product domain while preserving truthful access claims. For example, a notes-writing assistant can help draft text supplied in the conversation, but it cannot claim to read stored notes unless you implement an authorized retrieval path. The current system prompt requests concise plain text. That is an instruction to the model, not an output filter, and it does not rewrite historical saved messages. Context is server-loaded and bounded: messages have a 4,000-character input limit, context is bounded to 16,000 characters and ten completed turns, and generation is limited to 1,024 output tokens/90 seconds. Character counts are not token counts. Keep limits in their canonical code/database locations. The initial grant lives in versioned AI SQL; do not maintain a second editable subscription-credit table in the frontend. ## Chat, history and request identity [#chat-history-and-request-identity] New chat begins blank without creating an empty database record. First send creates the saved conversation and request. History opens a centered searchable dialog, with cursor pagination and literal case-insensitive title search. Messages scroll independently from the input; Enter sends and Shift+Enter adds a line. Request UUIDs and server leases prevent replay from starting another provider call or reserving twice. The saved output and credit charge commit together. User and assistant UI IDs remain distinct during streaming. Test reload and history after a successful completion rather than relying only on a visible streamed response. ## Stop, retry and failures [#stop-retry-and-failures] Stop, timeout, provider failure and abandoned requests release reservations. Provider charges may still occur and are recorded independently when returned. Late accounting can fill missing usage without changing an already terminal credit result. Scheduled recovery handles abandoned reservations; it is an AI-specific job, not a general queue. At most one generation streams per conversation and three per workspace, with ten attempts/member/workspace/minute. Stopping does not erase an attempt from the rate-limit window. At zero available credits, another generation must not start. Subscription renewal, membership changes and setup reruns cannot refill the balance. ## Disable without deleting history [#disable-without-deleting-history] Set `AI_ENABLED=false` and restart/redeploy. Navigation and new provider requests stop, while stored history and balances remain. Re-enabling does not grant another 100 credits. This is useful when you want to pause the example while retaining data; it is not full source/schema removal. ## Remove the example [#remove-the-example] There is no shipped one-command removal tool in this snapshot. Work in a reviewed source copy: 1. Remove AI navigation and chat-specific shell layout logic from `components/dashboard/app-shell.tsx`, plus the dashboard layout's AI flag wiring. 2. Remove `app/dashboard/chat`, `app/api/ai`, `app/preview/chat`, `components/ai`, `lib/ai`, and AI-only tests/scripts. 3. Remove the OpenRouter probe, AI imports and AI verification step from kickstart; remove `scripts/kickstart/ai.mjs`, `install-ai.mjs`, the `kickstart:ai` script and AI environment/deployment fields. 4. Uninstall the AI packages and update the lockfile: ```sh npm uninstall ai @ai-sdk/react @openrouter/ai-sdk-provider ``` 5. Preserve released migrations/checksums. For an installed database, write an additive cleanup migration: unschedule only `forma-ai-recovery`, remove the `on_workspace_created_ai` organization trigger before its data/functions, then remove AI-specific RPCs/tables. Keep shared extensions and permissions used by billing or other modules. 6. Search remaining source for AI imports/identifiers, run static/build checks, then verify signup, workspace creation/switching, notes, Checkout and Portal. Do not remove billing resources or alter the organization model. Historical onboarding interests can stay stored; the AI choice already follows the feature flag. A source-only build after removal does not prove hosted trigger cleanup or real billing acceptance. The cleanup migration must be reviewed against the installed schema before execution. ## Verify and diagnose [#verify-and-diagnose] Use the dedicated hosted AI tests and an explicitly authorized paid provider request to check first response/history, provider failure/refund, zero credits, concurrency and late settlement. Key validation alone does not prove provider funding. This manual did not spend provider credits or exercise Stop/Retry, clean hosted removal or real billing afterward. Record those results separately from local documentation checks.