@voltro/cli 0.1.0

package/templates/agent-docs/introduction.md

@@ -0,0 +1,438 @@
+# Introduction
+
+> Scaffold a Voltro project and boot it locally in under a minute.
+
+
+
+---
+
+<!-- source: en/intro/getting-started.md -->
+## Getting started
+
+_Scaffold a Voltro project and boot it locally in under a minute._
+
+Voltro is an AI-first, multi-tenant, reactive full-stack framework. You write your backend through file conventions for queries, mutations, actions, streams, workflows, and agents; hooks for reactive data; automatic live updates to every connected client over a single WebSocket.
+
+This guide gets you from zero to a running stack in under a minute.
+
+## Prerequisites
+
+- **Node.js 24+** — Voltro relies on the `--experimental-strip-types` flag and modern ESM behaviour.
+- **pnpm 10+** — workspaces, fast installs, deterministic lockfiles.
+- **Postgres 16+** *(optional)* — Voltro's dev mode runs against an in-memory store by default; switch to Postgres when you want logical replication-backed subscriptions, durable workflows, or to mirror production locally.
+
+## Scaffold a project
+
+`create-project` runs **inside an existing pnpm workspace** — it walks up from your current directory looking for `pnpm-workspace.yaml` and writes the project into that workspace's `apps/` directory. Run it from the root of your workspace:
+
+```bash
+pnpx voltro create-project acme \
+  --api api-backend \
+  --web frontend-landing \
+  --port-range 5190-5199
+```
+
+This creates `apps/acme/` inside the workspace with an `api/` (Voltro backend) and a `web/` (landing page) app. The project name is kebab-cased (so `Acme` becomes `acme`). The `--port-range` is recorded in `project.json` so every new app added later gets a unique port without you thinking about it.
+
+## Boot it
+
+Install and run from the **workspace root** — there is no top-level `acme/` directory to `cd` into; the project lives under `apps/acme/`:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+The dev orchestrator boots every app in parallel with HMR. By default:
+
+- `api` listens on `:4000` (RPC over WebSocket on `/ws`)
+- `web` listens on the first port in your range (e.g. `5190`)
+- The framework dashboard auto-launches on `:5179` (set `VOLTRO_DASHBOARD=off` to skip it)
+
+Open the web app's URL in a browser — anything you edit in `apps/acme/api/` or `apps/acme/web/src/` hot-reloads.
+
+## What you just got
+
+- File-based **queries** (`*.query.ts`) and **mutations** (`*.mutation.ts`) — no manual registration
+- **Streams** (`*.stream.ts`) for one-shot server-to-client element feeds
+- **Reactive subscriptions** wired to Postgres logical replication (or in-memory CDC for the dev store)
+- **Multi-tenancy** as a runtime primitive — drop the `tenant()` mixin on a table and the runtime scopes reads + flags cross-tenant writes
+- **Durable workflows** via `@effect/workflow` — long-running jobs survive deploys and crashes
+- **AI primitives** wrapping the Vercel AI SDK, plus a tool-calling convention
+- **End-to-end type safety** from your Postgres schema to your React components, no codegen step
+
+## Next steps
+
+- [Why Voltro?](/docs/intro/why-voltro) — the bigger picture + what we won't build
+- [Concepts](/docs/intro/concepts) — the vocabulary behind the framework
+- [File conventions](/docs/intro/file-conventions) — what `*.query.ts`, `*.mutation.ts`, etc. actually do
+- [Data overview](/docs/data/overview) — queries, mutations, actions, streams in five minutes
+
+
+
+---
+
+<!-- source: en/intro/why-voltro.md -->
+## Why Voltro?
+
+_The wager Voltro is making — reactive, multi-tenant, AI-first as primitives instead of libraries you bolt on._
+
+Most frameworks make you re-derive the same primitives every time: auth, tenants, audit logs, billing, real-time updates, background jobs. Voltro ships them as first-class composable primitives so you can spend your time on what makes YOUR product different.
+
+## The wager
+
+AI agents will increasingly write your code. The frameworks that win are the ones that give agents a **stable, opinionated surface** to target — not a thousand decisions every project re-litigates.
+
+Voltro is deliberately opinionated about boring things (HTTP, state, transport, schema) so the only decisions left are the ones that matter for your product.
+
+## Where Voltro fits
+
+| You're building... | Voltro is a good fit when... |
+|---|---|
+| A multi-tenant SaaS | You want tenant isolation enforced by the runtime, not "by hope" in app code |
+| A real-time collaboration app | Live data should be the default, not a feature flag |
+| An AI agent product | Tool calling, RAG, streaming, durability should be primitives |
+| A control plane | You need durable workflows + audit logs + RBAC out of the box |
+
+## Where Voltro is a bad fit
+
+- **You need an existing JS/TS ecosystem feature on day one.** Voltro is pre-release; APIs change.
+- **You're publishing to a CDN-only edge.** Voltro is a stateful, long-running runtime — Vercel, Fly, Railway, Render, or self-host on a Node 24 box.
+- **You want a visual ORM / GUI builder.** The CLI + your editor + LLMs are the editor.
+
+## What we won't do
+
+- **Lock you in.** Self-hosting is fully supported. Cloud is the premium tier of the same open-core runtime, not a fork.
+- **Multi-runtime grab-bag.** Effect-TS end-to-end — no Restate, no Temporal, no Inngest, not even opt-in.
+- **Magic.** Every file convention is documented; every generated file lives in `.framework/` and you can read it.
+- **Codegen you have to remember to run.** Schema flows from your tables to your React components automatically via Vite's module graph.
+
+## Where to read next
+
+- [Getting started](/docs/intro/getting-started) — scaffold + boot in under a minute
+- [Concepts](/docs/intro/concepts) — the mental models behind the primitives
+- [File conventions](/docs/intro/file-conventions) — what files do what
+
+
+
+---
+
+<!-- source: en/intro/concepts.md -->
+## Concepts
+
+_The core mental models behind Voltro: projects, apps, descriptors, executors, reactivity, streams, workflows, and runtime context._
+
+This page is the map before the territory. It names the framework concepts you will see everywhere else in the docs and explains how they fit together.
+
+## Project, Apps, And APIs
+
+A **project** is the deployable unit under `apps/<projectName>/`. It can contain multiple apps:
+
+- an `api` app: backend procedures, database schema, workflows, plugins
+- a `web` app: pages, layouts, React hooks, SSR/static rendering
+- optional sibling apps: dashboards, docs, admin panels, extra APIs
+
+A web app talks to one or more API apps through names configured in `app.config.ts`:
+
+```ts
+apis: {
+  app: { package: '@app/api' },
+  billing: { package: '@app/billing-api' },
+}
+```
+
+The first argument to client hooks is that API name:
+
+```tsx
+useSubscription('app', 'todos.list', {})
+useMutation('billing', 'invoices.pay')
+```
+
+## RPC Tags
+
+Every procedure descriptor declares a globally unique `name`. That name is the **RPC tag**:
+
+```ts
+defineQuery({ name: 'todos.list', /* ... */ })
+defineMutation({ name: 'todos.create', /* ... */ })
+defineAction({ name: 'support.ping', /* ... */ })
+defineStream({ name: 'agent.run', /* ... */ })
+```
+
+Hooks use the API name plus RPC tag. There is no hand-written client SDK per endpoint.
+
+## Descriptor And Server Executor
+
+Procedures are split into two files:
+
+| File | Purpose |
+|---|---|
+| `*.query.ts`, `*.mutation.ts`, `*.action.ts`, `*.stream.ts` | Browser-safe descriptor: name, schema, metadata. |
+| `*.query.server.ts`, `*.mutation.server.ts`, `*.action.server.ts`, `*.stream.server.ts` | Server-only executor: database, SDKs, secrets, side effects. |
+
+This keeps the wire contract importable from the client while server code stays server-only.
+
+## The Main Primitives
+
+| Primitive | Use it for | Client hook | Durable? | Reactive? |
+|---|---|---|---|---|
+| Query | Live reads and views | `useSubscription` | Reads durable state | Yes |
+| Mutation | Atomic database writes | `useMutation().mutate` | Yes | Triggers queries |
+| Action | One-shot side effects and external I/O | `useAction().run` | Request-scoped | No |
+| Stream | One-shot server-to-client element feeds | `useAgentStream` | No, unless you persist | No |
+| Workflow | Long-running multi-step work | Started from server code | Yes | Via the rows it writes |
+
+Decision shortcut:
+
+- Need live data on screen? Query.
+- Need one atomic database commit? Mutation.
+- Need HTTP/email/payment/upload/AI one-shot? Action.
+- Need progressive tokens/progress/log events? Stream.
+- Need retry/resume across crashes or deploys? Workflow.
+
+> **Beyond the core hooks.** These five are the data layer. The
+> **[Schema-driven UI](/docs/ui/overview)** section builds *on* them: `<AutoForm>`
+> binds to a mutation, `<DataTable>` to a query, and a toolbox of bound hooks —
+> `useCan`, `useUndo`, `usePreview`, `useProvenance`, `useAsyncValidation`,
+> `useOutbox`, `useWindowedSubscription`, … — covers the rest. Full list:
+> [Schema-driven UI → Client utilities](/docs/ui/client-utilities/use-can).
+
+## Reactivity
+
+Voltro is reactive end-to-end. A component subscribes to a query; the server keeps it live.
+
+```tsx
+const { data: todos } = useSubscription('app', 'todos.list', {})
+```
+
+When a mutation commits, the runtime emits change events. Queries whose `source` matches the changed table can update automatically.
+
+```ts
+defineQuery({ name: 'todos.list', source: 'todos', /* ... */ })
+defineMutation({ name: 'todos.create', target: { table: 'todos', op: 'insert' }, /* ... */ })
+```
+
+There is no `refetch` as the normal path. The subscription lives for the lifetime of the component.
+
+## Streams Are Not Subscriptions
+
+Queries stream **subscription events**: an initial snapshot, then deltas when durable state changes.
+
+Streams emit **plain elements** and then finish:
+
+```tsx
+const run = useAgentStream('app', 'agent.run')
+run.start({ prompt })
+```
+
+Use streams for transient output: LLM tokens, progress updates, import logs. If the result must survive reloads, write rows and expose them through a query.
+
+## Runtime Context
+
+Server executors receive `ctx`:
+
+```ts
+export default async (input, ctx) => {
+  const subject = ctx.request.subject
+  const rows = await ctx.store.query(/* ... */)
+}
+```
+
+Important pieces:
+
+- `ctx.request.subject`: the authenticated user, API key, system actor, or anonymous subject
+- `ctx.store`: typed data store with tenant/audit/soft-delete mixin behavior
+- `ctx.cache`: async cache facade
+- Effect services: actions and streams can return `Effect`s and use platform services such as `HttpClient`
+
+## Tenant Scoping
+
+Tables with the `tenant()` mixin are scoped by the runtime using `ctx.request.subject.tenantId`. Query executors do not need to repeat that predicate. Mutations should still validate any tenant IDs that arrive in input.
+
+## Generated Files
+
+Voltro discovers files and writes generated glue such as `rpcGroup.generated.ts` or `.framework/*`. Treat those as build artifacts. Edit descriptors, server executors, schema, pages, and config instead.
+
+## Where To Go Next
+
+- [File conventions](/docs/intro/file-conventions) - exact suffixes and discovery rules
+- [Data overview](/docs/data/overview) - queries, mutations, actions, streams
+- [Runtime context](/docs/reference/runtime-context) - what `ctx` contains
+- [Workflows](/docs/workflows/overview) - durable work
+- [AI streaming](/docs/ai/streaming) - transient vs persisted streams
+
+
+
+---
+
+<!-- source: en/intro/installation.md -->
+## Installation
+
+_Prerequisites, supported Node versions, and the three ways to install the Voltro CLI._
+
+## Prerequisites
+
+| Tool | Version | Why |
+|---|---|---|
+| Node.js | 24.x or newer | `--experimental-strip-types`, native ESM, `node:test`. |
+| pnpm | 10.x or newer | Workspace + lockfile semantics Voltro's scaffolder targets. |
+| Postgres | 16.x or newer | Optional for dev; required in production for logical replication-backed subscriptions. |
+
+You don't need Docker for dev — Voltro ships an in-memory store. You'll want Docker (or a managed Postgres) when you turn on persistence.
+
+## Three ways to install
+
+### 1. `pnpx` (recommended)
+
+The CLI runs from the registry without a global install:
+
+```bash
+pnpx voltro create-project my-app
+```
+
+This is the smallest blast radius — `pnpx` fetches the latest CLI release into the local cache and discards it after.
+
+### 2. Per-project dependency
+
+Once your project exists, the CLI is already a `dependency` of the `api` app's `package.json`, so:
+
+```bash
+pnpm --filter @my-app/api exec voltro dev
+```
+
+The api template's own `dev` script is `voltro dev .`, so `pnpm dev` in the app runs the CLI directly. If your workspace ships a turbo dev pipeline, `pnpm dev` at the repo root delegates to it. You rarely call the filtered form directly.
+
+### 3. Global install
+
+```bash
+pnpm add -g @voltro/cli
+voltro version
+```
+
+Convenient for jumping between projects from any directory. Downside: the global binary can drift away from the version pinned in your project — pin it in `~/.npmrc` or use a version manager if you go this route.
+
+## Verifying the install
+
+```bash
+voltro version
+voltro list-templates
+```
+
+The second command prints the app templates the CLI can scaffold. You'll see the `api-backend*` templates (`api-backend`, `api-backend-mail`, `api-backend-mariadb`, `api-backend-storage`) and the `frontend-*` templates (`frontend-blank`, `frontend-docs`, `frontend-landing`) — that's everything in place.
+
+## Editor setup
+
+Voltro ships an `AGENTS.md` file at the root of every scaffolded project. AI coding agents (Claude Code, Cursor, GitHub Copilot Chat) automatically read it for project-specific guidance — file conventions, schema DSL, common patterns. You don't need to do anything to enable it.
+
+For VSCode, the recommended extensions are:
+
+- `dbaeumer.vscode-eslint`
+- `bradlc.vscode-tailwindcss`
+- `vivaxy.vscode-conventional-commits`
+
+Tailwind v4 needs no config — Voltro's Vite plugin auto-discovers the content from the module graph.
+
+## Test utilities
+
+`@voltro/testing` is a separate, public package — it is **not** bundled into a scaffolded project. The moment you write your first test, add it (and `vitest`) as a **devDependency** of the app you're testing:
+
+```bash
+pnpm --filter @my-app/api add -D @voltro/testing vitest
+```
+
+`voltro test` then runs vitest against the current app. See the [Testing](/docs/testing/overview) section for the full surface — `makeTestContext`, the deterministic mocks, the workflow runner, and the dialect-parity harness.
+
+## Next
+
+- [Getting started](/docs/intro/getting-started) — actually scaffold a project
+- [Concepts](/docs/intro/concepts) — the vocabulary behind the framework
+- [File conventions](/docs/intro/file-conventions) — what `*.query.ts` etc. mean
+
+
+
+---
+
+<!-- source: en/intro/file-conventions.md -->
+## File conventions
+
+_The dot-suffix file conventions Voltro uses for procedure descriptors, server executors, workflows, agents, schemas, and pages._
+
+Voltro replaces router and registry config with **filesystem conventions**. Drop a file with the right suffix, the CLI's discovery walker picks it up, and the exports are wired into the runtime on the next boot. No manual registration, no import barrels to maintain.
+
+## The api side (`apps/*/api/`)
+
+| Suffix | What it is | Wired into |
+|---|---|---|
+| `*.query.ts` | Browser-safe reactive query descriptor: `defineQuery({ name, source, input, output })`. | Typed RPC group + client metadata. |
+| `*.query.server.ts` | Server executor for the matching query descriptor. | Reactive subscription runtime. |
+| `*.mutation.ts` | Browser-safe mutation descriptor: `defineMutation({ name, target, input, output, error })`. | Typed RPC group + auto-optimistic metadata. |
+| `*.mutation.server.ts` | Server executor for the matching mutation descriptor. | Transactional mutation runner. |
+| `*.action.ts` | Browser-safe action descriptor: `defineAction({ name, input, output, error })`. | Typed RPC group. |
+| `*.action.server.ts` | Server executor for the matching action descriptor. | Non-transactional action runner. |
+| `*.stream.ts` | Browser-safe one-shot stream descriptor: `defineStream({ name, input, element, error })`. | Typed streaming RPC group. |
+| `*.stream.server.ts` | Server executor returning an Effect `Stream`. | Plain server-to-client element streams. |
+| `*.workflow.tsx` | A durable Effect workflow. Survives restarts. | `@effect/workflow` runtime. |
+| `*.agent.tsx` | Browser-safe AI agent **descriptor**: `defineAgent({ name, input })`. Codegen-typed routes. | Agent runtime + client types. |
+| `*.agent.server.tsx` | Server agent **executor**: `defineAgentExecutor(descriptor, { system, tools, model, maxSteps })`. | Agent runtime. |
+| `*.tool.tsx` | A tool an agent can call. Schema + handler. | Agent runtime. |
+| `*.webhook.tsx` | Outgoing webhook spec (target, retry, schema). | Webhook delivery worker. |
+| `*.entity.ts` | Database table — one table per file: `table()` + columns + mixins. Re-exported from a `database/index.ts` barrel. | Migrations + the runtime data store. |
+| `*.config.ts` | App-level config (`app.config.ts`, `tsconfig.json`, etc.). | The CLI. |
+
+Procedure descriptors are intentionally separate from server executors. Descriptor files are safe for browser imports and codegen; `.server.ts` files can import the database, file system, SDK clients, secrets, and other server-only modules. Each descriptor has exactly one matching `.server.ts` file with the same primitive suffix. Workflows follow the same split: a browser-safe `*.workflow.tsx` descriptor (importing `workflow` from `@voltro/workflow/define`) paired with a `*.workflow.server.tsx` executor.
+
+The browser-safe rule is **transitive**, and that is where it usually breaks. The codegen pulls every descriptor (and every workflow descriptor) value-level into `rpcGroup.generated.ts`, which the web client loads — so a descriptor plus *everything it imports* must stay free of server-only code (`node:*`, the `database` handle, `@voltro/ai`, cluster, plugins, `@voltro/protocol/session`). The classic mistake is not a literal `import 'node:crypto'` but a descriptor importing a shared typed-error or helper from a `lib/` file that *also* imports the database — which drags the whole schema graph into the browser bundle. Keep typed errors, Schemas, and pure helpers in files with zero server imports; put DB-backed guards in `.server.ts`. A leak shows up as the web app fetching hundreds of modules / tens of MB on first load, or crashing with `Module "node:crypto" has been externalized for browser compatibility`.
+
+## The web side (`apps/*/web/`)
+
+| Path | What it is |
+|---|---|
+| `src/pages/*.tsx` | A page. URL is the file path; `[id].tsx` -> `/:id`, `[...slug].tsx` -> catch-all. |
+| `src/pages/layout.tsx` | Outer layout — wraps every page. |
+| `src/pages/error.tsx` | Error boundary for the whole subtree. |
+| `src/pages/not-found.tsx` | Fallback rendered when no page matches. |
+| `src/pages/loading.tsx` | Pending UI shown while loaders resolve. |
+| `src/pages/(group)/` | Route group — does not contribute a URL segment, but layout/error files inside still apply. |
+| `src/*.island.tsx` | A client-side hydration island (split chunk). Used in `interactive: 'islands'` pages. |
+
+Each page can opt into a render strategy via two exports:
+
+```tsx
+// src/pages/blog/[slug].tsx
+export const renderMode = 'isr' as const           // 'static' | 'spa' | 'ssr' | 'isr'
+export const interactive = 'islands' as const      // 'none' | 'islands' | 'full'
+```
+
+- `renderMode` controls when the HTML is produced (build vs. request).
+- `interactive` controls how much JS ships (`'none'` strips it all, `'full'` hydrates the page, `'islands'` hydrates only `.island.tsx` files).
+
+## Discovery in practice
+
+```text
+apps/acme/api/
+├── queries/
+│   ├── notes.list.query.ts
+│   └── notes.list.query.server.ts       -> notes.list query
+├── mutations/
+│   ├── notes.create.mutation.ts
+│   ├── notes.create.mutation.server.ts  -> notes.create mutation
+│   ├── notes.update.mutation.ts
+│   └── notes.update.mutation.server.ts  -> notes.update mutation
+├── streams/
+│   ├── ticker.stream.ts
+│   └── ticker.stream.server.ts          -> ticker stream
+├── workflows/
+│   └── notes.summarise.workflow.tsx     -> notes.summarise workflow
+└── database/
+    ├── users.entity.ts                  -> users table
+    ├── todos.entity.ts                  -> todos table
+    └── index.ts                         -> databaseHandle + re-exports
+```
+
+`voltro dev` writes `rpcGroup.generated.ts` beside the api source. It imports descriptor files only, lifts them into an `RpcGroup`, and exports descriptor metadata for the client. Web apps consume the mounted api with `useSubscription`, `useMutation`, `useAction`, or `useAgentStream` from `@voltro/client`.
+
+## Anti-patterns
+
+- **Don't put two procedure descriptors with the same `name`.** The CLI fails the boot — fix the name collision.
+- **Don't import `.server.ts` files from your web app.** Use the generated client. Importing the server module straight into the browser bundle leaks server-only deps (Postgres driver, secret keys).
+- **Don't move generated files in `.framework/` into the user source tree.** They're disposable; the CLI rewrites them on every boot.