@voltro/cli 0.1.0

package/templates/apps/api-ai/README.md

@@ -0,0 +1,105 @@
+# {{projectName}} / {{appName}}
+
+Voltro AI backend scaffold (template: **api-ai**) — a **RAG support
+agent** over a docs knowledge base. It exercises the framework's AI
+surface end-to-end: auto-embedded docs, a retrieval tool, a real agent
+model loop, and a structured-output action.
+
+## Boot
+
+```bash
+pnpm install                # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+The app **boots and discovers every primitive with zero infra and no AI
+key** (`store: 'memory'`). You only need a provider key to actually RUN
+the agent / the summarize action — see below.
+
+## What it demonstrates
+
+| File | Primitive | What it shows |
+|---|---|---|
+| `app.config.ts` | app + env | `store: 'memory'` zero-infra boot; AI env declared in the manifest. |
+| `database/schema.ts` | schema + `vectorEmbedding()` | A `docs` table that auto-embeds `body` on every write (adds the `embedding` vector column + HNSW index). |
+| `tools/searchDocs.tool.tsx` | `defineTool` | A retrieval tool the agent calls: `nearestNeighbours(query, k)` over `docs`, errors → `[]`. |
+| `agents/support.agent.tsx` | `defineAgent` (descriptor) | Browser-safe wire contract (`name`, `input`). |
+| `agents/support.agent.server.tsx` | `defineAgentExecutor` (executor) | System prompt + `tools: { searchDocs }` + `maxSteps`; model inherited from env. |
+| `actions/summarize.action.ts` / `.server.tsx` | `defineAction` + `generateObject` | Structured output — a typed `{ title, summary, keyPoints, sentiment }` object. |
+| `seeds/docs.seed.ts` | `defineSeed` | Idempotent boot seed of sample docs (auto-embedded on insert). |
+
+The framework SYNTHESIZES two routes from the agent descriptor — you
+write neither:
+
+- **`support.send`** — an action that appends the user turn and streams
+  the assistant turn (delta-persisted to `agent_messages`).
+- **`support.messages`** — a reactive query over `agent_messages` that
+  streams the turns (including the live streaming row) to the client.
+
+The thread tables (`agent_threads`, `agent_messages`) are auto-provided
+and auto-migrated because this app ships an `*.agent.tsx` — no schema
+file needed.
+
+## AI provider — env
+
+`@voltro/ai` reads the provider/model/key from env. All are OPTIONAL for
+booting; they're only needed to RUN the model. Put them in `.env`:
+
+```bash
+AI_PROVIDER=openai                 # e.g. 'openai' | 'anthropic'
+AI_MODEL=gpt-4o-mini               # any chat model the provider exposes
+AI_API_KEY=sk-...                  # provider key
+# @voltro/ai also accepts the provider-standard var:
+#   OPENAI_API_KEY=...   /   ANTHROPIC_API_KEY=...
+```
+
+Editing `.env` hard-restarts `voltro dev` automatically. Run `voltro env`
+to see the resolved manifest.
+
+### Embedding model + dimensions
+
+`vectorEmbedding({ from: 'body', model: 'text-embedding-3-small',
+dimensions: 1536 })` in `database/schema.ts` embeds with OpenAI's
+`text-embedding-3-small` (1536-wide). If you switch to a different
+embedding model, change `dimensions` to match its output width (e.g.
+768 / 3072) — the vector column size must line up or inserts/queries
+won't align.
+
+> `store: 'memory'` keeps the vector column but ANN falls back to a
+> sequential scan (correct, just unindexed). Switch to `store:
+> 'postgres'` for a real pgvector HNSW index.
+
+## Backfilling embeddings
+
+The seed runs on first boot. If it ran BEFORE you set an AI key, the doc
+rows exist but their `embedding` column is empty (the auto-embed had no
+provider). Set a key, then fill the gaps:
+
+```bash
+voltro embeddings backfill docs --text body --vector embedding
+# add --model <m> if you changed the embedding model from the default
+```
+
+This (re-)embeds existing rows the `vectorEmbedding()` mixin missed —
+the same command to use after a model change.
+
+## Trying it
+
+Once a key is set, drive the synthesized routes from a web client (or
+the dashboard's invoke surface):
+
+```ts
+// mint a thread id, subscribe to the live feed, then send a turn
+const threadId = `thread_${crypto.randomUUID().replace(/-/g, '')}`
+const { data: messages } = useSubscription('app', ['support.messages', { threadId }], { threadId })
+const send = useAction('app', 'support.send')
+await send.run({ threadId, order: messages?.length ?? 0, prompt: 'How do I reset my password?' })
+```
+
+The agent calls `searchDocs`, retrieves the relevant doc, and answers
+from it — the assistant bubble streams in as `support.messages` re-fires.
+
+Drop more `*.agent.tsx`, `*.tool.tsx`, `*.action.ts`, `*.seed.ts`, or
+schema files anywhere in this tree — discovery is by file convention.

package/templates/apps/api-ai/actions/summarize.action.server.tsx

@@ -0,0 +1,32 @@
+// `support.summarize` — EXECUTOR (server-only).
+//
+// Calls `@voltro/ai`'s `generateObject`, which constrains the model
+// output to the `SummaryResult` Effect Schema (converted to JSON Schema
+// for the provider, then decoded back so brands/refinements hold). A
+// provider failure or malformed output surfaces as a typed `AiError`
+// (`reason: 'generation' | 'decode'`) on the Effect failure channel —
+// declare it on the descriptor's `error:` to surface it typed to the
+// client, or `Effect.catchTag('AiError', …)` to handle it here.
+//
+// The provider is read from env (AI_PROVIDER / AI_MODEL + the key var)
+// because we don't pass `provider`. No key → the call fails with an
+// `AiError`; the app still BOOTS and discovers this action regardless.
+
+import { Effect } from 'effect'
+import { generateObject } from '@voltro/ai'
+import { SummaryResult } from './summarize.action'
+
+const execute = (input: { text: string }) =>
+  Effect.gen(function* () {
+    const { object } = yield* generateObject({
+      schema: SummaryResult,
+      system:
+        'Summarise the given support text. Produce a short title, a 1-2 sentence ' +
+        'summary, the key points as a list, and the overall sentiment.',
+      prompt:    input.text,
+      maxTokens: 500,
+    })
+    return object
+  })
+
+export default execute

package/templates/apps/api-ai/actions/summarize.action.ts

@@ -0,0 +1,33 @@
+// `support.summarize` — DESCRIPTOR (browser-safe).
+//
+// A `generateObject` example: take a free-text support thread / document
+// and produce STRUCTURED output (a typed summary object) instead of prose.
+// AI inference is external I/O → an action, not a mutation.
+//
+// The `output` Schema is exported separately so the server executor can
+// reuse the SAME schema to constrain `generateObject` — one source of
+// truth for the shape the model must satisfy AND the wire output. Schema
+// values are browser-safe, so re-importing it server-side is fine.
+
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+// The structured shape the model must emit. Top-level `Schema.Struct`
+// (generateObject requires a JSON `object` at the root — an array/scalar
+// must be wrapped in a field, as `keyPoints` is here).
+export const SummaryResult = Schema.Struct({
+  title:     Schema.String,
+  summary:   Schema.String,
+  keyPoints: Schema.Array(Schema.String),
+  sentiment: Schema.Literal('positive', 'neutral', 'negative'),
+})
+export type SummaryResult = Schema.Schema.Type<typeof SummaryResult>
+
+export const summarize = defineAction({
+  name:  'support.summarize',
+  input: Schema.Struct({
+    // The raw text to summarise (a support thread, a doc, a transcript).
+    text: Schema.String,
+  }),
+  output: SummaryResult,
+})

package/templates/apps/api-ai/agents/support.agent.server.tsx

@@ -0,0 +1,31 @@
+// `support` agent — EXECUTOR (server-only).
+//
+// `defineAgentExecutor` binds the behaviour to the descriptor: the system
+// prompt, the tools the model may call, the per-agent model, and the
+// max LLM↔tool round-trips. Default-exported; the framework pairs it with
+// `support.agent.tsx` by basename at boot.
+//
+// MODEL + KEY: we DON'T hardcode a model or key here. Omitting `model`
+// makes the agent inherit the provider from env — `AI_PROVIDER` /
+// `AI_MODEL` and the provider's standard key var (OPENAI_API_KEY /
+// ANTHROPIC_API_KEY / AI_API_KEY). That keeps the secret server-side and
+// lets the same template run against any provider via `.env`. See README.
+
+import { defineAgentExecutor } from '@voltro/ai'
+import { support } from './support.agent'
+import { searchDocs } from '../tools/searchDocs.tool'
+
+export default defineAgentExecutor(support, {
+  system: (input) =>
+    [
+      'You are a friendly, precise support agent for this product.',
+      'Answer ONLY from the knowledge base. ALWAYS call the `searchDocs`',
+      'tool first to retrieve relevant docs, then answer using their',
+      'content. If the docs do not cover the question, say so plainly',
+      'instead of guessing.',
+      `Reply in this locale: ${input.locale ?? 'en'}.`,
+    ].join(' '),
+  tools:    { searchDocs },
+  // No `model` → inherit AI_PROVIDER / AI_MODEL + the key var from env.
+  maxSteps: 6,
+})

package/templates/apps/api-ai/agents/support.agent.tsx

@@ -0,0 +1,27 @@
+// `support` agent — DESCRIPTOR (browser-safe).
+//
+// `defineAgent` from `@voltro/ai/agent` declares ONLY the wire contract:
+// the agent's `name` and `input` schema. This file is value-imported into
+// `rpcGroup.generated.ts`, so it must stay browser-safe — it imports
+// nothing server-only (no `@voltro/ai` main entry, no database, no tools).
+//
+// The framework SYNTHESIZES two routes from this descriptor:
+//   - `support.send`     — an action: appends the user turn + streams the
+//                          assistant turn (delta-persisted to agent_messages).
+//   - `support.messages` — a reactive query over agent_messages: streams the
+//                          turns (incl. the live streaming row) to the client.
+//
+// Behaviour (system prompt, tools, model + key, maxSteps) lives in the
+// paired server executor: `support.agent.server.tsx`.
+
+import { defineAgent } from '@voltro/ai/agent'
+import { Schema } from 'effect'
+
+export const support = defineAgent({
+  name:  'support',
+  input: Schema.Struct({
+    prompt: Schema.String,
+    // Optional locale to steer the system prompt's reply language.
+    locale: Schema.optional(Schema.String),
+  }),
+})

package/templates/apps/api-ai/app.config.ts

@@ -0,0 +1,57 @@
+// Backend app for the {{projectName}} project. Read by `voltro dev`.
+//
+// This is the AI template: a RAG support agent over a docs knowledge
+// base. It demonstrates the framework's AI surface end-to-end —
+// `vectorEmbedding()` auto-embedding on the `docs` table, a `defineTool`
+// the agent calls to retrieve docs, a real `defineAgent` /
+// `defineAgentExecutor` model loop, and a `generateObject` action for
+// structured output.
+//
+// `store: 'memory'` is the dev-friendly default — fast startup, no
+// docker. The app BOOTS and DISCOVERS every primitive with zero infra
+// and zero AI key. To actually RUN the agent / the summarize action you
+// need a provider key (see README): AI_PROVIDER / AI_MODEL + the
+// provider's key var (OPENAI_API_KEY / ANTHROPIC_API_KEY / …).
+//
+// NOTE on memory store: the `vector` column is stored but ANN falls back
+// to a sequential scan (correct, just unindexed). Switch to `'postgres'`
+// for a real pgvector HNSW index.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Typed environment — declare your env once; it's validated at boot (fail-fast)
+// and read on the server via `serverEnv` / `getSecret` from '@voltro/env/server'.
+// `access` is required: 'public' (browser-safe) or 'secret' (server-only, never
+// bundled). Run `voltro env` to see the manifest. See the Environment docs.
+//
+// The AI provider is read by `@voltro/ai` from the standard env vars
+// below. They're declared here purely so they show up in `voltro env`
+// and `.env.example`; `@voltro/ai` reads its own values at call time.
+// All optional — the app boots without them; only RUNNING the model needs them.
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  AI_PROVIDER: envVar.string({
+    access: 'public',
+    optional: true,
+    description: "AI provider id, e.g. 'openai' | 'anthropic'. Falls back to the @voltro/ai default.",
+    example: 'openai',
+  }),
+  AI_MODEL: envVar.string({
+    access: 'public',
+    optional: true,
+    description: "Model id, e.g. 'gpt-4o-mini' | 'claude-3-5-haiku-latest'.",
+    example: 'gpt-4o-mini',
+  }),
+  AI_API_KEY: envVar.string({
+    access: 'secret',
+    optional: true,
+    description:
+      "Provider API key. @voltro/ai also accepts the provider-standard var (OPENAI_API_KEY / ANTHROPIC_API_KEY).",
+  }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+}

package/templates/apps/api-ai/database/schema.ts

@@ -0,0 +1,67 @@
+// Schema for the {{projectName}} AI backend.
+//
+// Tables are auto-discovered: every exported `table(...)` in this file
+// (or any `*.entity.ts` / `*.schema.ts` file) is registered by
+// `voltro dev` — no manual barrel. `actors` + `tenants` are the
+// framework's core tables: the built-in `audit()` / `tenant()` /
+// `softDelete()` mixins reference them, so they must be declared (the
+// CLI wires them into the mixin registry once it finds them).
+//
+// The agent thread tables (`agent_threads`, `agent_messages`) are
+// auto-provided + auto-migrated by the framework because this app ships
+// an `*.agent.tsx` — you do NOT declare them here.
+
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  vectorEmbedding,
+  type InferRow,
+} from '@voltro/database'
+
+// ---------- Core tables (required by the audit / tenant mixins) ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+})
+
+export const tenants = table('tenants', {
+  id:   id(),
+  name: text(),
+})
+
+// ---------- Knowledge base ----------
+//
+// `vectorEmbedding({ from: 'body', ... })` adds an `embedding` vector
+// column + an HNSW index over it, and registers a re-embed hook that
+// calls `@voltro/ai`'s `embed` on every insert/update of `body` — so a
+// plain `ctx.store.insert('docs', { title, body })` auto-embeds, no app
+// code. Query it with `database.docs.nearestNeighbours(queryString, k)`
+// (the string overload is valid because this table carries the mixin —
+// the runtime embeds the query string before searching).
+//
+// `dimensions` MUST match the model's output width. 1536 =
+// text-embedding-3-small (OpenAI). If you point AI_MODEL at a different
+// embedding model, change this to match (e.g. 768 / 3072) or the vector
+// width won't line up.
+export const docs = table('docs', {
+  id:    id({ prefix: 'doc' }),
+  title: text(),
+  body:  text(),
+})
+  .with(
+    vectorEmbedding({
+      from:       'body',
+      model:      'text-embedding-3-small',
+      dimensions: 1536,
+    }),
+  )
+  // Opt into the matcher engine so subscriptions over `docs` re-fire on write.
+  .reactive()
+
+export type Doc = InferRow<typeof docs>
+
+export const database = databaseHandle({ actors, tenants, docs })

package/templates/apps/api-ai/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/ai": "0.1.0",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-ai/seeds/docs.seed.ts

@@ -0,0 +1,67 @@
+// Seed a few sample knowledge-base docs so the RAG agent has something
+// to retrieve on first boot.
+//
+// `lifecycle: 'boot'` runs this once per `voltro dev` boot, re-running
+// only when the seed file's content fingerprint changes. `upsertByUnique`
+// keys on `title`, so re-runs UPDATE rather than duplicate — idempotent.
+//
+// The `docs` table carries `vectorEmbedding({ from: 'body' })`, so each
+// insert/update AUTO-EMBEDS the body via `@voltro/ai`'s `embed` — no
+// embedding code here. NOTE: that embed needs a provider key
+// (AI_PROVIDER / AI_MODEL + the key var). Without one the rows still seed
+// (title + body persist) but the `embedding` column stays empty; run
+// `voltro embeddings backfill docs --text body --vector embedding`
+// after setting a key to fill them in. See the README.
+
+import { defineSeed } from '@voltro/database'
+
+const SAMPLE_DOCS: ReadonlyArray<{ title: string; body: string }> = [
+  {
+    title: 'Resetting your password',
+    body:
+      'To reset your password, open Settings → Security and click "Reset password". ' +
+      'You will receive an email with a one-time link valid for 30 minutes. If the ' +
+      'link expires, request a new one from the same screen. Passwords must be at ' +
+      'least 12 characters and include a number and a symbol.',
+  },
+  {
+    title: 'Inviting teammates',
+    body:
+      'Admins can invite teammates from the Members page. Enter the teammate\'s email ' +
+      'and pick a role (Viewer, Member, or Admin). Invites expire after 7 days. A ' +
+      'pending invite can be revoked or resent from the same list. Billing is per ' +
+      'active seat — a revoked invite is never charged.',
+  },
+  {
+    title: 'Exporting your data',
+    body:
+      'You can export all of your workspace data from Settings → Data → Export. ' +
+      'We generate a downloadable ZIP of newline-delimited JSON, one file per table. ' +
+      'Large workspaces are processed in the background; you get an email with the ' +
+      'download link when it is ready. Export links expire after 24 hours.',
+  },
+  {
+    title: 'API rate limits',
+    body:
+      'The API allows 100 requests per minute per API key by default. Exceeding the ' +
+      'limit returns HTTP 429 with a Retry-After header. Enterprise plans can request ' +
+      'a higher limit. Use exponential backoff on 429 responses; do not retry 4xx ' +
+      'errors other than 429.',
+  },
+]
+
+export default defineSeed({
+  id:        'docs',
+  name:      'Sample knowledge-base docs',
+  lifecycle: 'boot',
+  steps: ({ step }) => [
+    step('seed-docs', async ({ upsertByUnique }) => {
+      let rowsTouched = 0
+      for (const doc of SAMPLE_DOCS) {
+        await upsertByUnique('docs', { title: doc.title }, { title: doc.title, body: doc.body })
+        rowsTouched += 1
+      }
+      return { rowsTouched }
+    }),
+  ],
+})

package/templates/apps/api-ai/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-ai",
+  "kind": "api",
+  "summary": "RAG support agent over a docs knowledge base: vectorEmbedding() docs + a search tool + a real defineAgent/defineAgentExecutor model loop + a generateObject action. Boots zero-infra (store: memory); needs an AI key only to RUN the agent.",
+  "tags": ["api", "ai", "rag", "agent", "embeddings", "tools"]
+}

package/templates/apps/api-ai/tests/summarize.test.ts

@@ -0,0 +1,50 @@
+// Unit test with `@voltro/testing`. `support.summarize` is descriptor-pinned:
+// its executor calls `generateObject` (a real model inference), which a unit
+// harness can't provide — so we do NOT run the executor. Instead we assert the
+// wire CONTRACT that both the client and the model are bound to: the action's
+// name, and that `SummaryResult` (the shared schema constraining the model's
+// output AND the RPC output) decodes a valid object and rejects a bad one.
+//
+// This is the meaningful hermetic test for an AI action — the schema is the
+// single source of truth the model must satisfy; pinning it catches an
+// accidental shape change without a model in the loop. Run with `voltro test`.
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { summarize, SummaryResult } from '../actions/summarize.action'
+
+describe('support.summarize (action descriptor)', () => {
+  it('declares the expected wire name', () => {
+    expect(summarize.name).toBe('support.summarize')
+  })
+
+  it('accepts a valid { text } input and rejects a malformed one', () => {
+    const decode = Schema.decodeUnknownSync(summarize.input)
+    expect(decode({ text: 'a support thread' })).toEqual({ text: 'a support thread' })
+    expect(() => decode({})).toThrow() // missing text
+  })
+
+  it('decodes a valid SummaryResult', () => {
+    const decode = Schema.decodeUnknownSync(SummaryResult)
+    const ok = decode({
+      title: 'Refund request',
+      summary: 'The customer wants a refund for a late order.',
+      keyPoints: ['order was late', 'requests refund'],
+      sentiment: 'negative',
+    })
+    expect(ok.sentiment).toBe('negative')
+    expect(ok.keyPoints).toEqual(['order was late', 'requests refund'])
+  })
+
+  it('rejects a SummaryResult whose sentiment is outside the literal union', () => {
+    const decode = Schema.decodeUnknownSync(SummaryResult)
+    expect(() =>
+      decode({
+        title: 'x',
+        summary: 'y',
+        keyPoints: [],
+        sentiment: 'furious', // not 'positive' | 'neutral' | 'negative'
+      }),
+    ).toThrow()
+  })
+})

package/templates/apps/api-ai/tools/searchDocs.tool.tsx

@@ -0,0 +1,60 @@
+// `searchDocs` — the retrieval tool the support agent calls.
+//
+// Tool shape (the `*.tool.tsx` convention): a named `defineTool(...)`
+// DESCRIPTOR with the Schema-typed `input` / `output` and NO body, plus
+// a default-exported `(input, ctx) => …` handler. The framework wires
+// the default export onto the descriptor at discovery time, and the
+// agent's `tools: { searchDocs }` imports the SAME module instance.
+//
+// This file is SERVER-ONLY — it's referenced from the agent EXECUTOR
+// (`support.agent.server.tsx`), never from a browser-loaded descriptor,
+// so importing the `database` handle here is safe.
+//
+// The handler does vector retrieval: `database.docs.nearestNeighbours(
+// query, k)` returns the k nearest docs (each row gets a synthetic
+// `distance`). Because `docs` carries `vectorEmbedding()`, the STRING
+// overload is valid — the runtime embeds `query` before searching. Any
+// failure (no AI key, embed error) is caught → empty array, so a tool
+// hiccup surfaces to the model as "no results" instead of aborting the
+// whole agent turn.
+
+import { defineTool } from '@voltro/ai'
+import type { AppContext } from '@voltro/runtime'
+import { Schema } from 'effect'
+import { database } from '../database/schema'
+
+const MAX_RESULTS = 5
+const SNIPPET_LEN = 280
+
+export const searchDocs = defineTool({
+  name:        'searchDocs',
+  description:
+    'Search the support knowledge base for documents relevant to a question. ' +
+    'Returns up to 5 results, each with a title and a short snippet of the body.',
+  input:  Schema.Struct({ query: Schema.String }),
+  output: Schema.Array(
+    Schema.Struct({ title: Schema.String, snippet: Schema.String }),
+  ),
+})
+
+export default async (
+  { query }: { query: string },
+  ctx: AppContext,
+): Promise<ReadonlyArray<{ title: string; snippet: string }>> => {
+  try {
+    const rows = await ctx.store.query(
+      database.docs.nearestNeighbours(query, MAX_RESULTS).descriptor,
+    )
+    return rows.map((row) => {
+      const body = String((row as { body?: unknown }).body ?? '')
+      return {
+        title:   String((row as { title?: unknown }).title ?? ''),
+        snippet: body.length > SNIPPET_LEN ? `${body.slice(0, SNIPPET_LEN)}…` : body,
+      }
+    })
+  } catch {
+    // No AI key / embed failure / cold table → degrade to "no results"
+    // rather than aborting the agent's tool loop.
+    return []
+  }
+}

package/templates/apps/api-ai/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/apps/api-auth/.env

@@ -0,0 +1,17 @@
+# DEV-ONLY environment for the {{projectName}} api.
+#
+# `voltro dev` loads this file into the process environment at boot, BEFORE the
+# env-validation gate and BEFORE plugins activate.
+#
+# VOLTRO_SESSION_SECRET is the HMAC key that signs + verifies the session
+# cookie. authRoutesPlugin signs sessions with it; voltroPasswordStrategy
+# verifies them — they MUST share the same secret (app.config.ts reads this
+# one value and passes it to both).
+#
+# ⚠️  PUBLIC, DEV-ONLY placeholder shipped with the template. NEVER use it in
+#     production — generate a real one and set it in your deployment's secrets:
+#
+#         openssl rand -hex 32
+#
+#     Rotating it invalidates every existing session (users must sign in again).
+VOLTRO_SESSION_SECRET=devonly0011223344556677889900aabbccddeeff00112233445566778899aabb