@korajs/cli 0.6.0 → 1.0.0-beta.0

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

@@ -0,0 +1,87 @@
+# 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.

package/templates/react-tailwind-sync/src/App.tsx

@@ -80,6 +80,8 @@ export function App() {
 					</div>
 				)}
 
+				<ClockErrorBanner status={status} />
+
 				{/* Stats */}
 				<div className="grid grid-cols-3 gap-4 mb-8">
 					<StatCard label="Total" value={allTodos.length} color="text-gray-300" />
@@ -216,6 +218,7 @@ function SyncBadge({ status }: { status: { status: string; pendingOperations?: n
 		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' },
+		'clock-error': { icon: AlertCircle, color: 'text-red-400', label: 'Clock error' },
 	}
 
 	const { icon: Icon, color, label } = config[s] ?? config.offline!
@@ -233,6 +236,31 @@ function SyncBadge({ status }: { status: { status: string; pendingOperations?: n
 	)
 }
 
+/**
+ * Shown when sync is paused because this device's clock is set too far ahead.
+ * Local changes keep saving; they sync automatically once the clock is fixed.
+ */
+function ClockErrorBanner({
+	status,
+}: {
+	status: { status: string; clockSkewMs?: number | null }
+}) {
+	if (status.status !== 'clock-error') return null
+	const skew = status.clockSkewMs
+	const minutes =
+		typeof skew === 'number' && Number.isFinite(skew) ? Math.round(Math.abs(skew) / 60000) : null
+	return (
+		<div className="mb-4 rounded-lg border border-amber-400/40 bg-amber-400/10 px-4 py-3 text-sm text-amber-200">
+			<strong>
+				This device's clock looks wrong{minutes !== null ? ` (about ${minutes} min ahead)` : ''}.
+			</strong>{' '}
+			Your changes are safe on this device, but they can't be shared with your other devices until
+			the clock is corrected. Open your device's Settings, find Date & Time, and turn on "Set
+			automatically", then return here.
+		</div>
+	)
+}
+
 function StatCard({ label, value, color }: { label: string; value: number; color: string }) {
 	return (
 		<div className="rounded-lg border border-gray-800 bg-gray-900 p-4">

package/templates/svelte-basic/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-basic/src/App.svelte

@@ -1,44 +1,40 @@
 <script lang="ts">
-	import { createTodosStores } from './modules/todos/useTodos'
+import { createTodosStores } from './modules/todos/useTodos'
 
-	type Filter = 'all' | 'active' | 'completed'
+type Filter = 'all' | 'active' | 'completed'
 
-	const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } =
-		createTodosStores()
+const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } =
+	createTodosStores()
 
-	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,
+)
 
-	function handleSubmit(event: SubmitEvent): void {
-		event.preventDefault()
-		const title = input.trim()
-		if (!title) return
-		addTodo.mutate({ title })
-		input = ''
-	}
+function handleSubmit(event: SubmitEvent): void {
+	event.preventDefault()
+	const title = input.trim()
+	if (!title) return
+	addTodo.mutate({ title })
+	input = ''
+}
 
-	function clearCompleted(): void {
-		for (const todo of $completedTodos) {
-			deleteTodo.mutate(todo.id)
-		}
+function clearCompleted(): void {
+	for (const todo of $completedTodos) {
+		deleteTodo.mutate(todo.id)
 	}
+}
 
-	function formatTime(timestamp: number): string {
-		const date = new Date(timestamp)
-		const now = new Date()
-		if (date.toDateString() === now.toDateString()) {
-			return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
-		}
-		return date.toLocaleDateString([], { month: 'short', day: 'numeric' })
+function formatTime(timestamp: number): string {
+	const date = new Date(timestamp)
+	const now = new Date()
+	if (date.toDateString() === now.toDateString()) {
+		return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
 	}
+	return date.toLocaleDateString([], { month: 'short', day: 'numeric' })
+}
 </script>
 
 <div class="app">

package/templates/svelte-basic/src/Root.svelte

@@ -1,9 +1,9 @@
 <script lang="ts">
-	import type { KoraAppLike } from '@korajs/svelte'
-	import KoraProvider from '@korajs/svelte/KoraProvider.svelte'
-	import App from './App.svelte'
+import type { KoraAppLike } from '@korajs/svelte'
+import KoraProvider from '@korajs/svelte/KoraProvider.svelte'
+import App from './App.svelte'
 
-	let { kora }: { kora: KoraAppLike } = $props()
+const { kora }: { kora: KoraAppLike } = $props()
 </script>
 
 <KoraProvider app={kora}>

package/templates/svelte-basic/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-basic/vite.config.ts

@@ -1,6 +1,6 @@
-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 type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
 

package/templates/svelte-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-sync/src/App.svelte

@@ -1,48 +1,44 @@
 <script lang="ts">
-	import { createAuthStore } from '@korajs/auth/svelte'
-	import { createSyncStatusStore } from '@korajs/svelte'
-	import { createTodosStores } from './modules/todos/useTodos'
+import { createAuthStore } from '@korajs/auth/svelte'
+import { createSyncStatusStore } from '@korajs/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,
+)
 
-	function handleSubmit(event: SubmitEvent): void {
-		event.preventDefault()
-		const title = input.trim()
-		if (!title) return
-		addTodo.mutate({ title })
-		input = ''
-	}
+function handleSubmit(event: SubmitEvent): void {
+	event.preventDefault()
+	const title = input.trim()
+	if (!title) return
+	addTodo.mutate({ title })
+	input = ''
+}
 
-	function clearCompleted(): void {
-		for (const todo of $completedTodos) {
-			deleteTodo.mutate(todo.id)
-		}
+function clearCompleted(): void {
+	for (const todo of $completedTodos) {
+		deleteTodo.mutate(todo.id)
 	}
+}
 
-	function formatTime(timestamp: number): string {
-		const date = new Date(timestamp)
-		const now = new Date()
-		if (date.toDateString() === now.toDateString()) {
-			return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
-		}
-		return date.toLocaleDateString([], { month: 'short', day: 'numeric' })
+function formatTime(timestamp: number): string {
+	const date = new Date(timestamp)
+	const now = new Date()
+	if (date.toDateString() === now.toDateString()) {
+		return date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
 	}
+	return date.toLocaleDateString([], { month: 'short', day: 'numeric' })
+}
 </script>
 
 <div class="app">

package/templates/svelte-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-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/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/src/App.svelte

@@ -1,30 +1,26 @@
 <script lang="ts">
-	import { CheckCircle2, Circle, ClipboardList, Plus, Trash2 } from '@lucide/svelte'
-	import { createTodosStores } from './modules/todos/useTodos'
+import { CheckCircle2, Circle, ClipboardList, Plus, Trash2 } from '@lucide/svelte'
+import { createTodosStores } from './modules/todos/useTodos'
 
-	type Filter = 'all' | 'active' | 'completed'
+type Filter = 'all' | 'active' | 'completed'
 
-	const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } =
-		createTodosStores()
+const { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo } =
+	createTodosStores()
 
-	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,
+)
 
-	function handleSubmit(event: SubmitEvent): void {
-		event.preventDefault()
-		const title = input.trim()
-		if (!title) return
-		addTodo.mutate({ title })
-		input = ''
-	}
+function handleSubmit(event: SubmitEvent): void {
+	event.preventDefault()
+	const title = input.trim()
+	if (!title) return
+	addTodo.mutate({ title })
+	input = ''
+}
 </script>
 
 <div class="min-h-screen bg-gray-950 text-gray-100">

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

@@ -1,9 +1,9 @@
 <script lang="ts">
-	import type { KoraAppLike } from '@korajs/svelte'
-	import KoraProvider from '@korajs/svelte/KoraProvider.svelte'
-	import App from './App.svelte'
+import type { KoraAppLike } from '@korajs/svelte'
+import KoraProvider from '@korajs/svelte/KoraProvider.svelte'
+import App from './App.svelte'
 
-	let { kora }: { kora: KoraAppLike } = $props()
+const { kora }: { kora: KoraAppLike } = $props()
 </script>
 
 <KoraProvider app={kora}>

package/templates/svelte-tailwind/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,