@korajs/cli 0.0.0-canary-20261008174129

package/templates/svelte-tailwind-sync/src/main.ts

@@ -0,0 +1,32 @@
+import { createKoraAuthSync } from '@korajs/auth'
+import { createApp as createKoraApp } from 'korajs'
+import { mount } from 'svelte'
+import Root from './Root.svelte'
+import { authClient, completeOAuthCallbackFromLocation } from './auth'
+import schema from './schema'
+import './index.css'
+import koraWorkerUrl from './kora-worker.ts?worker&url'
+
+const syncUrl =
+	import.meta.env.VITE_SYNC_URL ||
+	`${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}//${window.location.host}/kora-sync`
+
+const kora = createKoraApp({
+	schema,
+	sync: {
+		url: syncUrl,
+		authClient: createKoraAuthSync({ authClient, schema }),
+	},
+	store: {
+		workerUrl: koraWorkerUrl,
+	},
+	devtools: import.meta.env.DEV,
+})
+
+kora.ready.then(() => kora.sync?.connect())
+
+void completeOAuthCallbackFromLocation().catch((error) => {
+	console.error('[Kora Auth] OAuth callback failed:', error)
+})
+
+mount(Root, { target: document.getElementById('app')!, props: { kora, authClient } })

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

@@ -0,0 +1,25 @@
+import type { CollectionAccessor } from 'korajs'
+
+export interface CreateTodoInput {
+	title: string
+}
+
+export interface UpdateTodoStatusInput {
+	completed: boolean
+}
+
+export function createTodo(todos: CollectionAccessor, data: CreateTodoInput) {
+	return todos.insert({ title: data.title })
+}
+
+export function updateTodoStatus(
+	todos: CollectionAccessor,
+	id: string,
+	data: UpdateTodoStatusInput,
+) {
+	return todos.update(id, { completed: data.completed })
+}
+
+export function deleteTodo(todos: CollectionAccessor, id: string) {
+	return todos.delete(id)
+}

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

@@ -0,0 +1,5 @@
+import type { CollectionAccessor } from 'korajs'
+
+export function orderedTodos(todos: CollectionAccessor) {
+	return todos.where({}).orderBy('createdAt', 'desc')
+}

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

@@ -0,0 +1,10 @@
+import { t } from 'korajs'
+
+export const todos = {
+	fields: {
+		title: t.string(),
+		completed: t.boolean().default(false),
+		createdAt: t.timestamp().auto(),
+	},
+	indexes: ['completed', 'createdAt'],
+}

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

@@ -0,0 +1,25 @@
+import { createMutation, createQueryStore, getCollection } from '@korajs/svelte'
+import { derived } from 'svelte/store'
+import {
+	type CreateTodoInput,
+	type UpdateTodoStatusInput,
+	createTodo,
+	deleteTodo,
+	updateTodoStatus,
+} from './todo.mutations'
+import { orderedTodos } from './todo.queries'
+
+export function createTodosStores() {
+	const todos = getCollection('todos')
+	const allTodos = createQueryStore(orderedTodos(todos))
+	const addTodo = createMutation((data: CreateTodoInput) => createTodo(todos, data))
+	const toggleTodo = createMutation((id: string, data: UpdateTodoStatusInput) =>
+		updateTodoStatus(todos, id, data),
+	)
+	const removeTodo = createMutation((id: string) => deleteTodo(todos, id))
+
+	const activeTodos = derived(allTodos, ($all) => $all.filter((todo) => !todo.completed))
+	const completedTodos = derived(allTodos, ($all) => $all.filter((todo) => !!todo.completed))
+
+	return { allTodos, activeTodos, completedTodos, addTodo, toggleTodo, deleteTodo: removeTodo }
+}

package/templates/svelte-tailwind-sync/src/schema.ts

@@ -0,0 +1,9 @@
+import { defineSchema } from 'korajs'
+import { todos } from './modules/todos/todo.schema'
+
+export default defineSchema({
+	version: 1,
+	collections: {
+		todos,
+	},
+})

package/templates/svelte-tailwind-sync/src/vite-env.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="svelte" />
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+	readonly DEV: boolean
+	readonly VITE_SYNC_URL?: string
+	readonly VITE_AUTH_URL?: string
+}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv
+}
+
+declare module '*?worker&url' {
+	const url: string
+	export default url
+}
+
+declare module '*?url' {
+	const url: string
+	export default url
+}

package/templates/svelte-tailwind-sync/svelte.config.js

@@ -0,0 +1,5 @@
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
+
+export default {
+	preprocess: vitePreprocess(),
+}

package/templates/svelte-tailwind-sync/tsconfig.json.hbs

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.svelte"],
+  "exclude": ["node_modules"]
+}

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

@@ -0,0 +1,98 @@
+import { copyFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { koraServiceWorker } from '@korajs/cli/vite'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import tailwindcss from '@tailwindcss/vite'
+import type { Plugin } from 'vite'
+import { defineConfig } from 'vite'
+
+function crossOriginIsolation(): Plugin {
+	const embedderPolicy = process.env.KORA_COEP_POLICY || 'credentialless'
+
+	return {
+		name: 'cross-origin-isolation',
+		configureServer(server) {
+			server.middlewares.use((_req, res, next) => {
+				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
+				next()
+			})
+		},
+		configurePreviewServer(server) {
+			server.middlewares.use((_req, res, next) => {
+				res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+				res.setHeader('Cross-Origin-Embedder-Policy', embedderPolicy)
+				next()
+			})
+		},
+	}
+}
+
+function sqliteWasmHotfix(): Plugin {
+	return {
+		name: 'sqlite-wasm-hotfix',
+		apply: 'build',
+		closeBundle() {
+			const assetsDir = resolve('dist', 'assets')
+			if (!existsSync(assetsDir)) return
+
+			for (const file of readdirSync(assetsDir)) {
+				if (/^sqlite3-.+\.wasm$/.test(file)) {
+					copyFileSync(join(assetsDir, file), join(assetsDir, 'sqlite3.wasm'))
+					break
+				}
+			}
+
+			const proxyFile = resolve(
+				'node_modules',
+				'@sqlite.org',
+				'sqlite-wasm',
+				'sqlite-wasm',
+				'jswasm',
+				'sqlite3-opfs-async-proxy.js',
+			)
+			if (existsSync(proxyFile)) {
+				copyFileSync(proxyFile, join(assetsDir, 'sqlite3-opfs-async-proxy.js'))
+			}
+		},
+	}
+}
+
+// koraServiceWorker() (build only, keep it last): precaches the built app shell so the
+// app opens offline, with a "new version available" reload prompt. See @korajs/cli/vite.
+export default defineConfig({
+	plugins: [
+		svelte(),
+		tailwindcss(),
+		crossOriginIsolation(),
+		sqliteWasmHotfix(),
+		koraServiceWorker(),
+	],
+	worker: {
+		format: 'es',
+	},
+	optimizeDeps: {
+		exclude: ['@sqlite.org/sqlite-wasm', '@korajs/store'],
+		include: ['yjs'],
+	},
+	resolve: {
+		dedupe: ['yjs'],
+	},
+	server: {
+		allowedHosts: true,
+		watch: {
+			ignored: ['**/.kora/**', '**/kora/generated/**', '**/*.db', '**/*.db-shm', '**/*.db-wal'],
+		},
+		proxy: {
+			'/kora-sync': {
+				target: 'ws://localhost:3001',
+				ws: true,
+				rewriteWsOrigin: true,
+			},
+			'/auth': {
+				target: 'http://localhost:3001',
+				changeOrigin: true,
+			},
+		},
+	},
+})

package/templates/tauri-react/.env.example

@@ -0,0 +1,27 @@
+# Sync server URL (used by the Tauri app to connect to the sync server)
+# In development, defaults to ws://localhost:3001/kora-sync
+# For production builds, set this to your deployed server URL:
+# VITE_SYNC_URL=wss://your-server.example.com/kora-sync
+
+# Sync server port
+PORT=3001
+
+# Server database
+# Leave DATABASE_URL empty to use SQLite at KORA_SERVER_DB.
+# Set DATABASE_URL for cloud Postgres deployments.
+KORA_SERVER_DB=./.kora/kora-server.db
+DATABASE_URL=
+
+# Operational endpoints (/__kora, /__kora/status, /__kora/events, /__kora/metrics, backups)
+# Set these in production. Use Authorization: Bearer <token> when calling protected endpoints.
+KORA_ADMIN_TOKEN=
+KORA_METRICS_TOKEN=
+KORA_BACKUP_TOKEN=
+
+# Optional sync path
+KORA_SYNC_PATH=/kora-sync
+
+# Auth
+# Set this to enable built-in /auth/* routes and authenticated sync.
+# Generate with: node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
+KORA_AUTH_SECRET=

package/templates/tauri-react/.github/workflows/release-desktop.yml

@@ -0,0 +1,107 @@
+# Build and release desktop binaries for macOS, Windows, and Linux.
+#
+# Trigger: Push a version tag (e.g., v1.0.0) or run manually.
+#
+# Prerequisites:
+#   1. Generate Tauri signing keys:
+#      pnpm tauri signer generate -w ~/.tauri/myapp.key
+#   2. Add secrets to your GitHub repo:
+#      - TAURI_SIGNING_PRIVATE_KEY: Contents of ~/.tauri/myapp.key
+#      - TAURI_SIGNING_PRIVATE_KEY_PASSWORD: Password used during generation
+#   3. (Optional) For macOS notarization:
+#      - APPLE_CERTIFICATE: Base64-encoded .p12 certificate
+#      - APPLE_CERTIFICATE_PASSWORD: Certificate password
+#      - APPLE_SIGNING_IDENTITY: e.g., "Developer ID Application: Your Name (TEAM_ID)"
+#      - APPLE_ID: Apple ID email
+#      - APPLE_PASSWORD: App-specific password
+#      - APPLE_TEAM_ID: Your Apple Developer Team ID
+#
+# After the workflow runs, a GitHub Release is created with installers
+# for all platforms plus an update manifest (latest.json) for auto-updates.
+
+name: Release Desktop
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Version tag (e.g., v1.0.0)'
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: macos-latest
+            args: '--target aarch64-apple-darwin'
+            rust_target: aarch64-apple-darwin
+          - platform: macos-latest
+            args: '--target x86_64-apple-darwin'
+            rust_target: x86_64-apple-darwin
+          - platform: ubuntu-22.04
+            args: ''
+            rust_target: ''
+          - platform: windows-latest
+            args: ''
+            rust_target: ''
+
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies (Linux)
+        if: matrix.platform == 'ubuntu-22.04'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.rust_target }}
+
+      - name: Rust cache
+        uses: swatinem/rust-cache@v2
+        with:
+          workspaces: './src-tauri -> target'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build and release
+        uses: tauri-apps/tauri-action@v0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          # macOS code signing (optional)
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        with:
+          tagName: ${{ github.ref_name || github.event.inputs.tag }}
+          releaseName: '${{ github.ref_name || github.event.inputs.tag }}'
+          releaseBody: 'See the assets below to download and install.'
+          releaseDraft: true
+          prerelease: false
+          args: ${{ matrix.args }}

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 put 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 change a collection's shape, increment `version` and add a `migrations` entry for it (`migrate().addField(...)`): each device migrates its local database on its next open. `npx kora migrate` generates the matching migration for server databases and a transform stub for clients still on the older version.
+
+## 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, arrays as multisets that keep every device's additions and removals, objects per top-level key). 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; [] on the very first render
+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` reads the local store: no network, no spinner. Its very first render returns `[]` before the local query has run; use `useQueryState` when you must tell "loading" from "no rows".
+
+## 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/tauri-react/README.md.hbs

@@ -0,0 +1,183 @@
+# {{projectName}}
+
+A native desktop application built with [Kora.js](https://ehoneahobed.github.io/kora/) and [Tauri](https://tauri.app). Uses native SQLite for fast local storage and syncs data across devices via a lightweight sync server.
+
+## Getting Started
+
+```bash
+pnpm dev
+```
+
+This starts both the sync server and the Tauri desktop app. The first launch compiles the Rust backend (2-5 minutes). Subsequent launches are fast.
+
+On first launch, you'll see a setup screen to enter your sync server URL. For local development, use `ws://localhost:3001/kora-sync` (the local sync server started by `pnpm dev`). You can also skip setup to use the app in local-only mode.
+
+## Project Structure
+
+```
+src/
+  schema.ts          # Schema entry point
+  auth.ts            # Desktop auth client and OAuth callback helpers
+  main.tsx           # Entry point
+  AppShell.tsx       # Setup flow + Kora initialization
+  App.tsx            # Main application UI
+  modules/
+    todos/
+      todo.schema.ts     # Todo collection definition
+      todo.queries.ts    # Reusable todo query builders
+      todo.mutations.ts  # Todo mutation helpers
+      useTodos.ts        # React hook connecting todos to the UI
+  SetupScreen.tsx    # First-launch server configuration
+  sync-config.ts     # Runtime sync URL storage
+  updater.ts         # Auto-update checker
+src-tauri/
+  Cargo.toml         # Rust dependencies (Kora SQLite + updater plugins)
+  tauri.conf.json    # Window, bundle, and updater config
+  capabilities/      # Tauri security permissions
+  src/
+    main.rs          # Rust entry point
+    lib.rs           # Plugin registration
+server.ts            # Kora sync server
+dev.ts               # Dev orchestrator (starts sync + Tauri together)
+kora.config.ts       # Kora configuration
+.github/workflows/
+  release-desktop.yml  # CI/CD for cross-platform builds
+```
+
+In a feature module, `schema` defines data shape, `queries` contain reads only, `mutations` contain
+writes, and `useTodos.ts` is the React binding that exposes todo data and actions to components.
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm dev` | Start sync server + Tauri app together |
+| `pnpm dev:app` | Start Tauri app only (no sync server) |
+| `pnpm dev:server` | Start sync server only |
+| `pnpm build` | Build desktop app for distribution |
+| `pnpm deploy:server` | Deploy sync server to the cloud |
+
+## Distributing to Organizations
+
+This app is designed to be distributed to multiple organizations. Each organization gets the **same binary** and connects to their own sync server.
+
+### 1. Deploy a sync server for each organization
+
+```bash
+pnpm deploy:server
+```
+
+Or deploy manually to any Node.js host. Each org gets their own server (or share one with multi-tenant scoping).
+
+### 2. Build the desktop binary
+
+```bash
+pnpm build
+```
+
+No need to bake in a sync URL — users configure it on first launch.
+
+If you want to pre-configure the URL (e.g., for a specific org):
+
+```bash
+VITE_SYNC_URL=wss://acme-corp.example.com/kora-sync pnpm build
+```
+
+### 3. Set up auto-updates
+
+1. Generate signing keys:
+   ```bash
+   pnpm tauri signer generate -w ~/.tauri/myapp.key
+   ```
+
+2. Add the public key to `src-tauri/tauri.conf.json` under `plugins.updater.pubkey`.
+
+3. Set the update endpoint:
+   ```json
+   "endpoints": ["https://github.com/YOUR_ORG/YOUR_REPO/releases/latest/download/latest.json"]
+   ```
+
+4. Add `TAURI_SIGNING_PRIVATE_KEY` and `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` to your GitHub repo secrets.
+
+5. Push a version tag to trigger a release:
+   ```bash
+   git tag v1.0.0 && git push origin v1.0.0
+   ```
+
+The GitHub Actions workflow builds for macOS, Windows, and Linux, creating a draft release with all installers.
+
+### 4. Distribute installers
+
+Built installers are in `src-tauri/target/release/bundle/`:
+
+| Platform | Output |
+|----------|--------|
+| macOS | `.dmg` and `.app` bundle |
+| Windows | `.msi` and `.exe` installer |
+| Linux | `.deb`, `.rpm`, `.AppImage` |
+
+Share these with your users. Installed apps auto-update when you push new releases.
+
+## First-Launch Experience
+
+When users install and open the app:
+
+1. **Setup screen** asks for the sync server URL
+2. User enters the URL provided by their organization admin
+3. App connects, verifies the server, and saves the URL locally
+4. On subsequent launches, the app connects automatically
+
+Users can also skip setup and use the app offline — they can connect later from the settings gear icon.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VITE_SYNC_URL` | (none) | Pre-configure sync URL at build time |
+| `VITE_AUTH_URL` | derived from sync URL | HTTP URL for `/auth/*` routes |
+| `PORT` | `3001` | Sync server port |
+| `KORA_SERVER_DB` | `./.kora/kora-server.db` | SQLite file used by the sync server when `DATABASE_URL` is empty |
+| `KORA_AUTH_DB` | `./.kora/kora-auth.db` | SQLite file used by OAuth state and linked identities when `DATABASE_URL` is empty |
+| `DATABASE_URL` | (none) | PostgreSQL connection string for production sync server deployments |
+| `KORA_SYNC_PATH` | `/kora-sync` | WebSocket path exposed by the sync server |
+| `KORA_AUTH_SECRET` | (none) | Enables built-in `/auth/*` routes and authenticated sync when set |
+| `KORA_GOOGLE_CLIENT_ID` | (none) | Enables Google OAuth when set with `KORA_GOOGLE_REDIRECT_URI` |
+| `KORA_GOOGLE_CLIENT_SECRET` | (none) | Google OAuth client secret for confidential web clients |
+| `KORA_GOOGLE_REDIRECT_URI` | (none) | OAuth callback URL for loopback, custom scheme, or hosted handoff |
+| `KORA_OAUTH_PKCE` | `true` when no client secret | Enables PKCE for public desktop/mobile OAuth clients |
+| `KORA_ADMIN_TOKEN` | (none) | Protects `/__kora`, `/__kora/status`, and `/__kora/events` |
+| `KORA_METRICS_TOKEN` | (none) | Protects `/__kora/metrics` |
+| `KORA_BACKUP_TOKEN` | (none) | Protects server backup and restore endpoints |
+
+## Authentication
+
+Set `KORA_AUTH_SECRET` to enable built-in auth on the sync server. Generate a secret with:
+
+```bash
+node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
+```
+
+The template creates a desktop auth client, wraps the app in `AuthProvider`, and wires sync with `createKoraAuthSync({ authClient, schema })`. Google OAuth is enabled on the server when `KORA_GOOGLE_CLIENT_ID` and `KORA_GOOGLE_REDIRECT_URI` are set.
+
+For production desktop OAuth, use a loopback callback, custom URL scheme, or hosted handoff that returns `code` and `state` to the app, then complete the flow with `authClient.completeOAuthSignIn('google', { code, state })`. The generated `src/auth.ts` includes the callback completion helper. See the [Authentication Guide](https://ehoneahobed.github.io/kora/guide/authentication#desktop-and-tauri-apps).
+
+## Code Signing
+
+### macOS
+
+For distribution outside the Mac App Store, you need a Developer ID certificate from Apple:
+
+1. Enroll in the [Apple Developer Program](https://developer.apple.com/programs/)
+2. Create a "Developer ID Application" certificate
+3. Add the certificate and credentials to your GitHub secrets (see `.github/workflows/release-desktop.yml`)
+
+### Windows
+
+For SmartScreen trust, get an EV code signing certificate from a provider like DigiCert or Sectigo. Set the certificate in your CI environment.
+
+## Learn More
+
+- [Tauri Desktop Guide](https://ehoneahobed.github.io/kora/guide/tauri-desktop)
+- [Deployment Guide](https://ehoneahobed.github.io/kora/guide/deployment)
+- [Sync Configuration](https://ehoneahobed.github.io/kora/guide/sync-configuration)
+- [Schema Design](https://ehoneahobed.github.io/kora/guide/schema-design)