Integrate AI Kit

Copy the selected AI packages

Copy ../ai/packages/ai/core and the feature package you selected into packages/ai/. Keep their package names, such as @workspace/ai and @workspace/ai-chat, so the source imports continue to resolve.

mkdir -p packages/ai
cp -R ../ai/packages/ai/core packages/ai/core
cp -R ../ai/packages/ai/chat packages/ai/chat

Do not copy ../ai/pnpm-lock.yaml. Merge the required entries from AI Kit's pnpm-workspace.yaml into Core Kit's catalogs, then run pnpm install from Core Kit so pnpm resolves one version per dependency.

Copy dependencies from the selected package's package.json rather than installing every provider. For example, the chat package lists its model and web-search providers in ../ai/packages/ai/chat/package.json.

Merge the database schema

Copy only the schema files used by the selected template into packages/db/src/schema/. Do not replace Core Kit's auth.ts, billing.ts, or the existing migration history.

AI Kit groups template tables into PostgreSQL schemas such as chat, rag, and image. The files reference Core Kit's existing user table, so authenticated and anonymous Core users can own AI data without a second identity system.

Merge the exports into the existing index:

export * from "./auth";
export * from "./billing";
export * from "./chat";

AI Kit's credit example defines a customer table in customer.ts. Core billing already defines its own customer, so do not copy that file unchanged. Choose one design:

• Rename the AI table and exports to a dedicated ai_credit or credit-ledger model if credits are separate.
• Replace deductCredits with plan or entitlement checks if AI usage belongs to a Core subscription.
• Remove the credit middleware and UI if the feature is unlimited.

RAG also requires the PostgreSQL vector extension. Use a database image or hosted provider with pgvector, enable CREATE EXTENSION vector, and include that change in the migration review.

Generate a new migration from the combined schema:

pnpm with-env pnpm --filter @workspace/db db:generate
pnpm with-env pnpm --filter @workspace/db db:migrate

Review the generated SQL before applying it to an existing production database. It should add the selected AI tables and schemas, not recreate Core auth tables.

Replace the demo AI route with the selected routers

Core Kit already mounts aiRouter at /api/ai in packages/api/src/index.ts. AI Kit uses the same mount point, so preserve Core's Hono app and replace the small packages/api/src/modules/ai/router.ts implementation with the selected nested routers.

For chat, port:

../ai/packages/api/src/modules/ai/chat.ts
../ai/packages/api/src/modules/ai/router.ts

Then add the selected workspace packages to packages/api/package.json. Keep Core Kit's existing middleware.ts, and port only the AI-specific deductCredits logic if you kept credits. Core's enforceAuth already resolves the session and sets c.var.user.

Keep provider SDKs and provider keys in the server-side AI packages. Browser components should only call the Hono API.

Port the web feature

Copy the selected route group and feature module from AI Kit:

../ai/apps/web/src/app/[locale]/(apps)/chat
../ai/apps/web/src/modules/chat

Chat also imports shared AI application components from ../ai/apps/web/src/modules/common. Copy the components reached by the feature's imports, but adapt them to Core's existing app layout, navigation, auth client, query provider, theme, and UI package. Do not replace Core's root layout.

Use Core's authenticated dashboard when the AI feature is part of the product. A typical destination is:

apps/web/src/app/[locale]/dashboard/(user)/chat
apps/web/src/modules/ai/chat

Moving the files is optional, but keeping AI product features under the dashboard makes Core authorization and navigation boundaries explicit.

Merge the selected app dependencies from ../ai/apps/web/package.json. In particular, persisted chat uses @ai-sdk/react on the client while provider SDKs remain dependencies of the server-side AI package.

Port the AI elements imported by the feature from ../ai/packages/ui/web/src/components/ai-elements and merge the ai translation namespace from ../ai/packages/i18n/src/translations. Add each new @workspace/ai* package to Core's INTERNAL_PACKAGES list in apps/web/next.config.ts so Next.js transpiles workspace source.

Voice also runs @workspace/ai-voice as a separate LiveKit worker. Copying its web screen does not deploy that worker.

Merge environment validation

Copy variable definitions, not .env files. Add only the providers and tools used by your selected feature to:

1. apps/web/.env.example
2. apps/web/env.config.ts
3. The relevant package env.ts presets
4. apps/web/turbo.json for variables required by build or dev tasks
5. Your deployment environment

For a Gateway-backed chat, the minimal provider variable is:

AI_GATEWAY_API_KEY=""

Attachments also need the existing Core storage variables. Web search needs the key for the strategy you enable, such as TAVILY_API_KEY, BRAVE_SEARCH_API_KEY, EXA_API_KEY, or FIRECRAWL_API_KEY.

Do not expose provider keys with NEXT_PUBLIC_.

Verify the integrated slice

Run the checks from the Core repository:

pnpm install
pnpm lint
pnpm --filter web build

Then verify the behavior that crosses package boundaries:

1. Sign in with a normal Core account and, if enabled, an anonymous account.
2. Send a request and confirm the response streams.
3. Reload and confirm persisted content still belongs to the same user.
4. Try to request another user's chat directly and expect an authorization failure.
5. Upload an attachment if the selected feature uses storage.
6. Confirm rate limits and plan or credit checks fail before invoking a paid provider.