Customware AI

Build AI features through the Customware AI Gateway. Use AI SDK on the Hono backend and AI Elements in the React Router SPA when a chat UI is needed.

Preflight security rule: Treat

.env

and every

.env.*

file as inaccessible. Do not read, list, search, preview, or request permission for them. Only a runtime command using

node --env-file=.env ...

may reference

.env

, and that command must not print environment values.

This is the single skill for the complete integration. Do not install or ask the agent to use a separate AI Elements skill; the relevant AI Elements guidance is adapted into this skill's references.

Read First

Always read references/gateway-backend.md.
Always read references/models.md.
For chat or other conversational UI, read references/ai-elements-ui.md.
For server tools, tool-backed chat, or any AI action that fetches live app data, read references/tool-usage.md.
For card-style AI UI, tool-rendered UI, typed message parts, or streamed custom UI state, read references/generative-ui.md.
For AI UI, read references/ai-elements-catalog.md, select the needed components, then read only those linked files under
```
references/components/
```
. Open a component's linked example files only while implementing it. Never load the entire components folder or all examples.
For JSON or other typed output, read references/structured-output.md.
When starting from bundled code, read references/examples.md.
Before finishing any implementation, read and follow references/verification.md.

Non-Negotiables

Call the Customware AI Gateway only from server code. Browser code calls the app's own Hono endpoint.
Read the gateway secret only from
```
CUSTOMWARE_AI_GATEWAY_KEY
```
.
Never expose the key through
```
VITE_*
```
, browser bundles, API responses, logs, HTML, or client-side state.
Never read
```
.env
```
or any
```
.env.*
```
file with a file/tool read, and never request permission to do so. Never run
```
cat
```
,
```
head
```
,
```
tail
```
,
```
sed
```
,
```
awk
```
,
```
rg
```
,
```
grep
```
,
```
ls
```
,
```
stat
```
, or any other command against
```
.env
```
. The only allowed reference is a check command whose argument is exactly
```
node --env-file=.env ...
```
; that command must not print environment variables. Never inspect the key by printing
```
printenv
```
, request headers, or provider objects. Log only non-sensitive pass/fail evidence.
Hardcode the Customware gateway base URL in server code. Do not add a gateway URL environment variable.

Use this exact adapter base URL:

https://app.customware.ai/api/orgs/${orgId}/projects/${projectId}/ai/v1

Always use the real Customware
```
orgId
```
and
```
projectId
```
. Never use placeholders or accept them from the browser for each request.
Use
```
@openrouter/ai-sdk-provider
```
; do not use provider-specific SDKs or call OpenRouter directly.
Do not pass a preset, provider routing, fallback model list, metadata, trace id, or OpenRouter user id. The gateway owns these controls.
Default to
```
google/gemini-3-flash-preview
```
unless the user selects another model or the task clearly requires one of the documented alternatives.
Keep the chosen model id and provider options in one server-owned module/constant. Routes and services must import that value; do not duplicate model literals or add a model catalog/picker when the feature does not require user choice.
If the user names or changes a model during development, send a live
```
hi
```
request through that exact model before finishing.
If the feature generates JSON, run the one-key structured-output check before finishing.
Match the requested JSON field names and shape exactly. Define one shared Zod contract in a neutral shared module/package (for example
```
shared/contracts/
```
) that both app and server may import; the browser must never import from
```
server/
```
, and the schema/enums must never be duplicated. Product-requested limits, such as a 20,000-character input bound, are valid when documented by the feature.
Any upstream AI failure must become a generic, user-safe error at the app boundary; never render raw transport/provider errors.
Keep database access server-owned. Never execute arbitrary model-written SQL. If a feature needs database access, let the model choose a structured tool input and let the server build the read-only, parameterized query from allowlisted filters, tables, or query helpers.
AI Elements works in the React Router client-only SPA. Do not introduce Next.js or App Router route handlers. Generated
```
"use client"
```
directives are harmless React boundary markers and do not require Next.js.
Use pnpm only. Install AI Elements through the bundled installer, which runs non-interactive
```
pnpm dlx shadcn@latest add ... --yes
```
commands and isolates registry-matched primitives from the template's existing UI contracts.

Workflow

Inspect the generated app and identify its package manager, Hono entry point, React Router structure, and real Customware org/project ids.
Read the relevant references listed above.
Add
```
ai
```
,
```
@ai-sdk/react
```
,
```
@openrouter/ai-sdk-provider
```
, and
```
zod
```
with pnpm only when missing. Complete this dependency install before running the AI Elements installer or any live check.
Add a focused server provider helper using
```
CUSTOMWARE_AI_GATEWAY_KEY
```
and the fixed gateway URL.
Add the Hono endpoint before static-file serving and SPA fallback routes. In this React Router SPA, do not export
```
HydrateFallback
```
from a non-root route; use the template’s existing root fallback only.
Keep the model and its reasoning configuration server-owned. If the UI offers model selection, validate it against the small allow-list in references/models.md.
For chat, install only the selected AI Elements with
```
scripts/install-ai-elements.mjs
```
, then connect
```
useChat
```
to the app's Hono endpoint.
For structured output, use the current AI SDK
```
generateText
```
with
```
Output.object
```
and a Zod schema.
For tool calling, define the tool on the server with
```
tool({ inputSchema, execute })
```
, keep the action boundary server-owned, and use a bounded multi-step setting such as
```
stopWhen: stepCountIs(5)
```
when the model must answer after the tool result.
For
```
PromptInputSubmit
```
, allow the Stop action while status is
```
submitted
```
or
```
streaming
```
; do not pass an input-empty disabled condition that disables Stop after the submitted input is cleared.
Run the mandatory live checks and browser-level UI verification in references/verification.md from the target project, then run the app's normal type/check/build command. If interactive verification fails, inspect the actual page/console from the project-local script before claiming the app is broken.
Lazy-load client AI UI with
```
React.lazy
```
/dynamic import at the route or pane boundary. Keep server-only AI SDK calls (
```
streamText
```
,
```
generateText
```
, tools) and the gateway provider server-only;
```
DefaultChatTransport
```
is the supported client transport for
```
useChat
```
. Do not lazy-load server code into the browser. Treat a large AI UI bundle warning as a real performance issue and isolate heavy Streamdown/AI Elements code from the initial chunk.

Version-aware API usage

Package APIs can change. When usage is uncertain, inspect the installed packages in the target project's

node_modules/

before coding:

Read
```
.d.ts
```
files for the type contract and available props/returns.
Read the actual
```
.js
```
/
```
.mjs
```
implementation for runtime behavior and defaults.
Apply this to
```
ai
```
,
```
@ai-sdk/react
```
,
```
@openrouter/ai-sdk-provider
```
, and installed AI Elements components. The installed version and source take precedence over copied examples or stale docs.

Copy-Ready Examples

Use
```
assets/ai-chat/
```
for a minimal streaming chat.
Use
```
assets/sql-tool-chat/
```
for tool-backed chat with visible tool state and a safe read-only SQL pattern.
Use
```
assets/generative-ui-chat/
```
for tool-driven end-user card UI inside chat.
Use
```
assets/email-parser/
```
for internal server-only typed JSON generation.
Copy only the files needed by the target feature, adapt their import paths, and supply the real org/project ids where the route or service is mounted.
Treat assets as starting code, not files to execute inside the skill repository.

Boundaries

Use
```
customware-support-widget
```
instead when the request is only to embed the existing support agent widget.
Do not build a second browser-to-gateway path alongside the Hono path.
Do not silently replace an unavailable user-selected model with another model.
Do not create a second key, per-project key, or direct OpenRouter key in the generated app.
Do not display, mask, copy, or otherwise surface
```
CUSTOMWARE_AI_GATEWAY_KEY
```
in the UI. It is not an AI Elements environment-variable display use case.

customware-ai

NPX Install

Tags

SKILL.md Content