@korajs/cli 0.6.0 → 1.0.0-beta.0

package/templates/svelte-tailwind/vite.config.ts

@@ -1,7 +1,7 @@
-import tailwindcss from '@tailwindcss/vite'
-import { svelte } from '@sveltejs/vite-plugin-svelte'
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import tailwindcss from '@tailwindcss/vite'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
 

package/templates/svelte-tailwind-sync/AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this project. Humans: this is useful for you too.
+
+## What this project is
+
+This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
+
+## Golden rules
+
+1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
+2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
+3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
+4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
+5. **Surface mutation errors.** Fire-and-forget mutate calls swallow errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
+7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
+
+## Data API cheat sheet
+
+```ts
+await app.ready
+const rec = await app.todos.insert({ title: 'x' })   // defaults and .auto() fields applied
+await app.todos.update(rec.id, { completed: true })  // partial update, changed fields only
+await app.todos.delete(rec.id)
+const one = await app.todos.findById(rec.id)
+const unsubscribe = app.todos
+  .where({ completed: false })
+  .orderBy('createdAt', 'desc')
+  .subscribe((rows) => {/* fires immediately, then on every change */})
+```
+
+Schema example (`src/schema.ts`):
+
+```ts
+import { defineSchema, t } from 'korajs'
+
+export default defineSchema({
+  version: 1,
+  collections: {
+    todos: {
+      fields: {
+        title: t.string(),
+        completed: t.boolean().default(false),
+        tags: t.array(t.string()).default([]),
+        priority: t.enum(['low', 'medium', 'high']).default('medium'),
+        createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
+      },
+      indexes: ['completed', 'createdAt'],
+    },
+  },
+})
+```
+
+If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+
+## Project conventions
+
+- Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
+
+## Commands
+
+- `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
+- `npm run build` type-checks and builds for production.
+- `npx kora doctor` diagnoses a broken setup.
+- DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
+
+## Sync and auth
+
+Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
+
+## Svelte bindings
+
+Kora's Svelte package exposes store-based bindings from `@korajs/svelte`, wired through the provider set up in the app entry. Queries are reactive stores that read synchronously from the local database; mutations expose error state that must be surfaced in the UI. Avoid loading spinners for local reads.

package/templates/svelte-tailwind-sync/src/App.svelte

@@ -1,69 +1,65 @@
 <script lang="ts">
-	import { createAuthStore } from '@korajs/auth/svelte'
-	import { createSyncStatusStore } from '@korajs/svelte'
-	import {
-		AlertCircle,
-		CheckCircle2,
-		Circle,
-		ClipboardList,
-		Loader2,
-		Plus,
-		Trash2,
-		Wifi,
-		WifiOff,
-	} from '@lucide/svelte'
-	import { createTodosStores } from './modules/todos/useTodos'
+import { createAuthStore } from '@korajs/auth/svelte'
+import { createSyncStatusStore } from '@korajs/svelte'
+import {
+	AlertCircle,
+	CheckCircle2,
+	Circle,
+	ClipboardList,
+	Loader2,
+	Plus,
+	Trash2,
+	Wifi,
+	WifiOff,
+} from '@lucide/svelte'
+import { createTodosStores } from './modules/todos/useTodos'
 
-	type Filter = 'all' | 'active' | 'completed'
+type Filter = 'all' | 'active' | 'completed'
 
-	const syncStatus = createSyncStatusStore()
-	const auth = createAuthStore()
-	const todos = createTodosStores()
-	const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } = todos
+const syncStatus = createSyncStatusStore()
+const auth = createAuthStore()
+const todos = createTodosStores()
+const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } = todos
 
-	let filter = $state<Filter>('all')
-	let input = $state('')
+const filter = $state<Filter>('all')
+let input = $state('')
 
-	const filteredTodos = $derived(
-		filter === 'active'
-			? $activeTodos
-			: filter === 'completed'
-				? $completedTodos
-				: $allTodos,
-	)
+const filteredTodos = $derived(
+	filter === 'active' ? $activeTodos : filter === 'completed' ? $completedTodos : $allTodos,
+)
 
-	const syncBadge = $derived.by(() => {
-		const s = $syncStatus.status
-		const pending = $syncStatus.pendingOperations ?? 0
-		const map: Record<string, { icon: typeof Wifi; color: string; label: string }> = {
-			connected: { icon: Wifi, color: 'text-emerald-400', label: 'Connected' },
-			syncing: { icon: Wifi, color: 'text-amber-400', label: 'Syncing' },
-			synced: { icon: Wifi, color: 'text-emerald-400', label: 'Synced' },
-			offline: { icon: WifiOff, color: 'text-gray-500', label: 'Offline' },
-			error: { icon: AlertCircle, color: 'text-red-400', label: 'Error' },
-		}
-		return { ...(map[s] ?? map.offline), pending }
-	})
-
-	function handleSubmit(event: SubmitEvent): void {
-		event.preventDefault()
-		const title = input.trim()
-		if (!title) return
-		addTodo.mutate({ title })
-		input = ''
+const syncBadge = $derived.by(() => {
+	const s = $syncStatus.status
+	const pending = $syncStatus.pendingOperations ?? 0
+	const map: Record<string, { icon: typeof Wifi; color: string; label: string }> = {
+		connected: { icon: Wifi, color: 'text-emerald-400', label: 'Connected' },
+		syncing: { icon: Wifi, color: 'text-amber-400', label: 'Syncing' },
+		synced: { icon: Wifi, color: 'text-emerald-400', label: 'Synced' },
+		offline: { icon: WifiOff, color: 'text-gray-500', label: 'Offline' },
+		error: { icon: AlertCircle, color: 'text-red-400', label: 'Error' },
 	}
+	return { ...(map[s] ?? map.offline), pending }
+})
 
-	function clearCompleted(): void {
-		for (const todo of $completedTodos) {
-			deleteTodo.mutate(todo.id)
-		}
-	}
+function handleSubmit(event: SubmitEvent): void {
+	event.preventDefault()
+	const title = input.trim()
+	if (!title) return
+	addTodo.mutate({ title })
+	input = ''
+}
 
-	function emptyMessage(f: Filter): string {
-		if (f === 'all') return 'No tasks yet. Add one above!'
-		if (f === 'active') return 'All caught up! No active tasks.'
-		return 'No completed tasks yet.'
+function clearCompleted(): void {
+	for (const todo of $completedTodos) {
+		deleteTodo.mutate(todo.id)
 	}
+}
+
+function emptyMessage(f: Filter): string {
+	if (f === 'all') return 'No tasks yet. Add one above!'
+	if (f === 'active') return 'All caught up! No active tasks.'
+	return 'No completed tasks yet.'
+}
 </script>
 
 <div class="min-h-screen bg-gray-950 text-gray-100">

package/templates/svelte-tailwind-sync/src/Root.svelte

@@ -1,11 +1,11 @@
 <script lang="ts">
-	import type { AuthClient } from '@korajs/auth'
-	import type { KoraAppLike } from '@korajs/svelte'
-	import AuthProvider from '@korajs/auth/svelte/AuthProvider.svelte'
-	import KoraProvider from '@korajs/svelte/KoraProvider.svelte'
-	import App from './App.svelte'
+import type { AuthClient } from '@korajs/auth'
+import AuthProvider from '@korajs/auth/svelte/AuthProvider.svelte'
+import type { KoraAppLike } from '@korajs/svelte'
+import KoraProvider from '@korajs/svelte/KoraProvider.svelte'
+import App from './App.svelte'
 
-	let { kora, authClient }: { kora: KoraAppLike; authClient: AuthClient } = $props()
+const { kora, authClient }: { kora: KoraAppLike; authClient: AuthClient } = $props()
 </script>
 
 <AuthProvider client={authClient}>

package/templates/svelte-tailwind-sync/src/modules/todos/useTodos.ts

@@ -1,4 +1,4 @@
-import { getCollection, createMutation, createQueryStore } from '@korajs/svelte'
+import { createMutation, createQueryStore, getCollection } from '@korajs/svelte'
 import { derived } from 'svelte/store'
 import {
 	type CreateTodoInput,

package/templates/svelte-tailwind-sync/vite.config.ts

@@ -1,7 +1,7 @@
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import tailwindcss from '@tailwindcss/vite'
 import { svelte } from '@sveltejs/vite-plugin-svelte'
+import tailwindcss from '@tailwindcss/vite'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
 

package/templates/tauri-react/AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this project. Humans: this is useful for you too.
+
+## What this project is
+
+This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
+
+## Golden rules
+
+1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
+2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
+3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
+4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
+5. **Surface mutation errors.** Fire-and-forget mutate calls swallow errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
+7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
+
+## Data API cheat sheet
+
+```ts
+await app.ready
+const rec = await app.todos.insert({ title: 'x' })   // defaults and .auto() fields applied
+await app.todos.update(rec.id, { completed: true })  // partial update, changed fields only
+await app.todos.delete(rec.id)
+const one = await app.todos.findById(rec.id)
+const unsubscribe = app.todos
+  .where({ completed: false })
+  .orderBy('createdAt', 'desc')
+  .subscribe((rows) => {/* fires immediately, then on every change */})
+```
+
+Schema example (`src/schema.ts`):
+
+```ts
+import { defineSchema, t } from 'korajs'
+
+export default defineSchema({
+  version: 1,
+  collections: {
+    todos: {
+      fields: {
+        title: t.string(),
+        completed: t.boolean().default(false),
+        tags: t.array(t.string()).default([]),
+        priority: t.enum(['low', 'medium', 'high']).default('medium'),
+        createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
+      },
+      indexes: ['completed', 'createdAt'],
+    },
+  },
+})
+```
+
+If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+
+## Project conventions
+
+- Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
+
+## Commands
+
+- `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
+- `npm run build` type-checks and builds for production.
+- `npx kora doctor` diagnoses a broken setup.
+- DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
+
+## Sync and auth
+
+Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
+
+## React bindings
+
+```tsx
+import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/react'
+
+const todos = useCollection('todos')
+const rows = useQuery(orderedTodos(todos))            // reactive, no loading state for local data
+const addTodo = useMutation((data) => todos.insert(data))
+addTodo.mutate({ title: 'x' })                        // fire-and-forget; errors land in addTodo.error
+await addTodo.mutateAsync({ title: 'x' })             // throws on failure; use when you need the error
+const status = useSyncStatus()                        // status.status, status.pendingOperations
+```
+
+Rules: always render `mutation.error` somewhere. The app must work under React StrictMode (the framework's hooks are StrictMode-safe; keep `<StrictMode>` in `src/main.tsx`). `useQuery` returns data synchronously from the local store, so do not add loading spinners for local reads.
+
+## Tauri specifics
+
+This app runs inside Tauri with native SQLite storage through the bundled plugin. Web-only APIs (OPFS) are not the storage path here; do not add browser-storage assumptions. Use `npm run tauri dev` for the desktop shell and consult https://korajs.dev/guide/tauri-desktop.md before changing storage or plugin configuration.

package/templates/vue-basic/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this project. Humans: this is useful for you too.
+
+## What this project is
+
+This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
+
+## Golden rules
+
+1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
+2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
+3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
+4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
+5. **Surface mutation errors.** Fire-and-forget mutate calls swallow errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
+7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
+
+## Data API cheat sheet
+
+```ts
+await app.ready
+const rec = await app.todos.insert({ title: 'x' })   // defaults and .auto() fields applied
+await app.todos.update(rec.id, { completed: true })  // partial update, changed fields only
+await app.todos.delete(rec.id)
+const one = await app.todos.findById(rec.id)
+const unsubscribe = app.todos
+  .where({ completed: false })
+  .orderBy('createdAt', 'desc')
+  .subscribe((rows) => {/* fires immediately, then on every change */})
+```
+
+Schema example (`src/schema.ts`):
+
+```ts
+import { defineSchema, t } from 'korajs'
+
+export default defineSchema({
+  version: 1,
+  collections: {
+    todos: {
+      fields: {
+        title: t.string(),
+        completed: t.boolean().default(false),
+        tags: t.array(t.string()).default([]),
+        priority: t.enum(['low', 'medium', 'high']).default('medium'),
+        createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
+      },
+      indexes: ['completed', 'createdAt'],
+    },
+  },
+})
+```
+
+If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+
+## Project conventions
+
+- Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
+
+## Commands
+
+- `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
+- `npm run build` type-checks and builds for production.
+- `npx kora doctor` diagnoses a broken setup.
+- DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
+
+## Sync and auth
+
+Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
+
+## Vue bindings
+
+```ts
+import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/vue'
+
+const todos = useCollection('todos')
+const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
+const addTodo = useMutation((data) => todos.insert(data))
+```
+
+Rules: always surface the mutation's error state in the UI. `useQuery` reads synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

package/templates/vue-basic/src/modules/todos/useTodos.ts

@@ -1,5 +1,5 @@
-import { computed } from 'vue'
 import { useCollection, useMutation, useQuery } from '@korajs/vue'
+import { computed } from 'vue'
 import {
 	type CreateTodoInput,
 	type UpdateTodoStatusInput,

package/templates/vue-sync/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this project. Humans: this is useful for you too.
+
+## What this project is
+
+This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
+
+## Golden rules
+
+1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
+2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
+3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
+4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
+5. **Surface mutation errors.** Fire-and-forget mutate calls swallow errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
+7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
+
+## Data API cheat sheet
+
+```ts
+await app.ready
+const rec = await app.todos.insert({ title: 'x' })   // defaults and .auto() fields applied
+await app.todos.update(rec.id, { completed: true })  // partial update, changed fields only
+await app.todos.delete(rec.id)
+const one = await app.todos.findById(rec.id)
+const unsubscribe = app.todos
+  .where({ completed: false })
+  .orderBy('createdAt', 'desc')
+  .subscribe((rows) => {/* fires immediately, then on every change */})
+```
+
+Schema example (`src/schema.ts`):
+
+```ts
+import { defineSchema, t } from 'korajs'
+
+export default defineSchema({
+  version: 1,
+  collections: {
+    todos: {
+      fields: {
+        title: t.string(),
+        completed: t.boolean().default(false),
+        tags: t.array(t.string()).default([]),
+        priority: t.enum(['low', 'medium', 'high']).default('medium'),
+        createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
+      },
+      indexes: ['completed', 'createdAt'],
+    },
+  },
+})
+```
+
+If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+
+## Project conventions
+
+- Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
+
+## Commands
+
+- `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
+- `npm run build` type-checks and builds for production.
+- `npx kora doctor` diagnoses a broken setup.
+- DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
+
+## Sync and auth
+
+Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
+
+## Vue bindings
+
+```ts
+import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/vue'
+
+const todos = useCollection('todos')
+const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
+const addTodo = useMutation((data) => todos.insert(data))
+```
+
+Rules: always surface the mutation's error state in the UI. `useQuery` reads synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

package/templates/vue-sync/src/main.ts

@@ -37,7 +37,11 @@ createApp({
 			{ client: authClient, fallback: h('div', 'Restoring session...') },
 			{
 				default: () =>
-					h(KoraProvider, { app: kora, fallback: h('div', 'Loading...') }, { default: () => h(App) }),
+					h(
+						KoraProvider,
+						{ app: kora, fallback: h('div', 'Loading...') },
+						{ default: () => h(App) },
+					),
 			},
 		),
 }).mount('#app')

package/templates/vue-sync/src/modules/todos/useTodos.ts

@@ -1,5 +1,5 @@
-import { computed } from 'vue'
 import { useCollection, useMutation, useQuery } from '@korajs/vue'
+import { computed } from 'vue'
 import {
 	type CreateTodoInput,
 	type UpdateTodoStatusInput,

package/templates/vue-tailwind/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this project. Humans: this is useful for you too.
+
+## What this project is
+
+This is a **Kora.js** application: an offline-first app where all data lives in a local SQLite database (WASM + OPFS in the browser) and optionally syncs across devices through a Kora sync server. Offline is the normal state, not an error state. Full docs: https://korajs.dev and machine-readable index at https://korajs.dev/llms.txt (complete docs in one file: https://korajs.dev/llms-full.txt).
+
+## Golden rules
+
+1. **The schema is the source of truth.** All collections are defined in `src/schema.ts` with `defineSchema` and the `t.*` field builders. To add or change data shapes, edit the schema first; types flow from it automatically. Never hand-write types for records.
+2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
+3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
+4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
+5. **Surface mutation errors.** Fire-and-forget mutate calls swallow errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
+7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
+
+## Data API cheat sheet
+
+```ts
+await app.ready
+const rec = await app.todos.insert({ title: 'x' })   // defaults and .auto() fields applied
+await app.todos.update(rec.id, { completed: true })  // partial update, changed fields only
+await app.todos.delete(rec.id)
+const one = await app.todos.findById(rec.id)
+const unsubscribe = app.todos
+  .where({ completed: false })
+  .orderBy('createdAt', 'desc')
+  .subscribe((rows) => {/* fires immediately, then on every change */})
+```
+
+Schema example (`src/schema.ts`):
+
+```ts
+import { defineSchema, t } from 'korajs'
+
+export default defineSchema({
+  version: 1,
+  collections: {
+    todos: {
+      fields: {
+        title: t.string(),
+        completed: t.boolean().default(false),
+        tags: t.array(t.string()).default([]),
+        priority: t.enum(['low', 'medium', 'high']).default('medium'),
+        createdAt: t.timestamp().auto(), // set automatically; never pass it on insert
+      },
+      indexes: ['completed', 'createdAt'],
+    },
+  },
+})
+```
+
+If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+
+## Project conventions
+
+- Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
+
+## Commands
+
+- `npm run dev` starts everything: Vite dev server (port 5173), local sync server (port 3001), and the schema watcher.
+- `npm run build` type-checks and builds for production.
+- `npx kora doctor` diagnoses a broken setup.
+- DevTools overlay: press Ctrl+Shift+K (Cmd+Shift+K on macOS) in the running app to inspect operations, merges, and sync status.
+
+## Sync and auth
+
+Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })`. In dev, the sync URL is derived from the page host and proxied by Vite; in production set `VITE_SYNC_URL`. Auth (if present in this template) uses `@korajs/auth`; the client is created in `src/auth.ts`. Local writes work without sign-in; sync requires the server to accept the connection.
+
+## Vue bindings
+
+```ts
+import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/vue'
+
+const todos = useCollection('todos')
+const rows = useQuery(orderedTodos(todos))   // readonly reactive ref
+const addTodo = useMutation((data) => todos.insert(data))
+```
+
+Rules: always surface the mutation's error state in the UI. `useQuery` reads synchronously from the local store, so avoid loading spinners for local data. The Kora context is provided by the `KoraProvider` component wired in `src/main.ts`.

package/templates/vue-tailwind/src/App.vue

@@ -1,12 +1,5 @@
 <script setup lang="ts">
-import {
-	CheckCircle2,
-	Circle,
-	ClipboardList,
-	Loader2,
-	Plus,
-	Trash2,
-} from 'lucide-vue-next'
+import { CheckCircle2, Circle, ClipboardList, Loader2, Plus, Trash2 } from 'lucide-vue-next'
 import { computed, ref } from 'vue'
 import { useTodos } from './modules/todos/useTodos'
 

package/templates/vue-tailwind/src/modules/todos/useTodos.ts

@@ -1,5 +1,5 @@
-import { computed } from 'vue'
 import { useCollection, useMutation, useQuery } from '@korajs/vue'
+import { computed } from 'vue'
 import {
 	type CreateTodoInput,
 	type UpdateTodoStatusInput,