powersync-ja · michaelbarnes · Apr 8, 2026 · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -9,6 +9,6 @@ That file includes:
 
 **Do not** assume Supabase, assume self-hosted Docker, or skip CLI steps unless the user **explicitly** opts out.
 
-**`powersync login`** authenticates the CLI to **PowerSync Cloud** only (personal access token). It is **not** how you “log in” to a **self-hosted** PowerSync service. Self-hosted doesnt not require login
+**`powersync login`** is **PowerSync Cloud only**. Self-hosted does not use it — see `skills/powersync/references/powersync-cli.md` § “Authentication”.
 
 When editing files under `skills/powersync/`, preserve and strengthen playbook language so agents cannot reasonably treat references as optional recipes.
diff --git a/skills/powersync/AGENTS.md b/skills/powersync/AGENTS.md
@@ -12,26 +12,16 @@ Use this skill to onboard a project onto PowerSync without trial-and-error. Trea
 | Use the **PowerSync CLI** to scaffold, link (if cloud hosted), and deploy (`references/powersync-cli.md`) | Hand-write `service.yaml` / `sync-config.yaml` from scratch or invent compose files **unless** the user explicitly says they cannot use the CLI |
 | **Stop and ask** when a step needs credentials or interactive Cloud login you cannot perform | Silently build an alternate stack (e.g. manual Docker) without user confirmation |
 | Complete **backend readiness** (deployed sync config, auth, publication) **before** app code | Start React/client integration while sync is still unconfigured |
+| Use **Sync Streams** (`config: edition: 3`) for new projects | Generate legacy Sync Rules YAML for new projects |
 
 If the user wants a shortcut, they must **say so explicitly** (e.g. “I can’t use the CLI, give dashboard steps only”).
 
 
 ## Always Use the PowerSync CLI
 
-**The [PowerSync CLI](https://docs.powersync.com/tools/cli.md) is the default tool for all PowerSync operations.** Do not manually create config files, do not direct users to the dashboard, and do not write service.yaml or sync-config.yaml from scratch. The CLI handles all of this.
+**The [PowerSync CLI](https://docs.powersync.com/tools/cli.md) is the default tool for all PowerSync operations.** Do not manually create config files, do not direct users to the dashboard, and do not write `service.yaml` or `sync-config.yaml` from scratch. Only fall back to manual config or dashboard instructions when the user explicitly says they can't use the CLI.
 
-What the CLI does — use it instead of doing these things manually:
-
-- **Create a Cloud instance:** `powersync init cloud` → `powersync link cloud --create --project-id=<id>` (scaffolds config, creates the instance, and links it in one flow)
-- **Link an existing Cloud instance:** `powersync pull instance --project-id=<id> --instance-id=<id>` (downloads config to local files)
-- **Create a local self-hosted instance:** `powersync init self-hosted` → `powersync docker configure` → `powersync docker start` (spins up a full local PowerSync stack via Docker — no manual Docker setup needed)
-- **Deploy config:** `powersync deploy service-config`, `powersync deploy sync-config` (validates and deploys — don't copy-paste YAML to a dashboard)
-- **Generate client schema:** `powersync generate schema --output=ts` (generates TypeScript schema from deployed sync config — don't write it by hand)
-- **Generate dev tokens:** `powersync generate token --subject=user-1` (for local testing — don't hardcode JWTs)
-
-Only fall back to manual config or dashboard instructions when the user explicitly says they can't use the CLI.
-
-Full CLI reference: `references/powersync-cli.md` — **always load this file** when setting up or modifying a PowerSync instance.
+**Always load `references/powersync-cli.md`** when setting up or modifying a PowerSync instance — it contains the full command reference for Cloud, self-hosted, and Docker workflows.
 
 ## Onboarding Playbook
 
@@ -50,6 +40,17 @@ When the task is to add PowerSync to an app, follow this sequence in order:
 
 Do not start client-side debugging while the PowerSync service is still unconfigured. If the UI is stuck on `Syncing...`, the default diagnosis is incomplete backend setup, not a frontend bug.
 
+## Install Latest Dependencies
+
+Always install PowerSync packages with `@latest` to get critical fixes and the most current API:
+
+```bash
+npm install @powersync/web@latest        # or react-native, node, etc.
+npm install @journeyapps/wa-sqlite@latest
+```
+
+Never omit `@latest` for `@powersync/*` and `@journeyapps/*` packages. These packages release frequently and older cached versions can be missing critical fixes or new APIs the sync config depends on.
+
 ## Critical Footguns
 
 These apply to all paths. Domain-specific pitfalls are documented in the relevant reference files — only load those when working on that domain.
@@ -138,92 +139,17 @@ If the backend is Supabase, also load `references/supabase-auth.md`.
 
 ### Path 3: Self-Hosted + CLI (Recommended)
 
-**Not Cloud:** do not use **`powersync login`** as the way to “log in” to self-hosted — that command stores a **PowerSync Cloud** PAT. Self-hosted uses **`powersync init self-hosted`**, **`powersync docker configure`**, **`powersync docker start`**, and the service’s **`PS_ADMIN_TOKEN`** for admin API access.
-
-Load `references/powersync-cli.md`, `references/powersync-service.md`, and `references/sync-config.md`. Prefer the CLI for Docker runs (`powersync docker run`, `powersync docker reset`), schema generation, and any supported self-hosted operations. See [PowerSync CLI](https://docs.powersync.com/tools/cli.md).
+Load `references/powersync-cli.md`, `references/powersync-service.md`, and `references/sync-config.md`. Prefer the CLI for Docker runs (`powersync docker run`, `powersync docker reset`), schema generation, and any supported self-hosted operations. Remember: **`powersync login` is Cloud-only** — see `references/powersync-cli.md` § “Authentication” for self-hosted auth.
 
 ### Path 4: Self-Hosted + Manual Docker
 
 Only when the CLI cannot be used. Load `references/powersync-service.md` and `references/sync-config.md`. If the backend is **not** Supabase, also load `references/custom-backend.md`.
 
-## Architecture
-
-```mermaid
-flowchart LR
-
-  subgraph BACKEND["Your Backend"]
-    direction TB
-    DB["Backend Database (Postgres | MongoDB | MySQL | Supabase | …)"]
-    API["Backend API (Your server / cloud functions)"]
-    API -- "Applies writes" --> DB
-  end
-
-  subgraph PS_SERVICE["PowerSync Service"]
-    direction TB
-    SYNC["Partial Sync (sync rules filter data per user)"]
-  end
-
-  subgraph APP["Your App"]
-    direction TB
-    SDK["PowerSync SDK"]
-    SQLITE["In-app SQLite (local replica — reads are instant)"]
-    QUEUE["Upload Queue (offline write buffer)"]
-    UI["UI"]
-    SDK --- SQLITE
-    SDK --- QUEUE
-    SQLITE <--> UI
-    QUEUE <--> UI
-  end
-
-  DB -- "Replicates changes (CDC / logical replication)" --> PS_SERVICE
-  PS_SERVICE -- "Streams changes (real-time sync)" --> SDK
-  QUEUE -- "Uploads writes (when connectivity resumes)" --> API
-```
+## Architecture, Routing, SDK Tables & Key Rules
+
+These are defined once in **SKILL.md** — refer there for:
 
-Key rule: **client writes never go through PowerSync**. They go from the app's upload queue to your backend API. PowerSync handles the read and sync path only.
-
-## What to Load for Your Task
-
-| Task | Start with | Load on demand |
-|------|-----------|----------------|
-| Supabase + PowerSync | `references/onboarding-supabase.md` | `references/supabase-auth.md`, `references/sync-config.md`, SDK files (when writing app code) |
-| Custom backend (non-Supabase) | `references/onboarding-custom.md` | `references/custom-backend.md`, `references/sync-config.md`, SDK files (when writing app code) |
-| New project setup | `references/powersync-cli.md` + `references/powersync-service.md` | `references/sync-config.md`, SDK files (when writing app code) |
-| Self-hosting / service config | `references/powersync-service.md` + `references/powersync-cli.md` | `references/sync-config.md` |
-| Writing sync config | `references/sync-config.md` | — |
-| Debugging sync issues | `references/powersync-debug.md` | — |
-| Attachments | `references/attachments.md` | — |
-| Architecture overview | This file is sufficient | `references/powersync-overview.md` for deep links |
-
-## SDK Reference Files
-
-### JavaScript / TypeScript
-
-Always load `references/sdks/powersync-js.md` for any JS/TS project, then load the applicable framework file.
-
-| Framework | Load when… | File |
-|-----------|-----------|------|
-| React / Next.js | React web app, Next.js, or **any Vite + React project** (load before package install — contains required `vite.config.ts` with `optimizeDeps.exclude` and `worker.format: 'es'`) | `references/sdks/powersync-js-react.md` |
-| React Native / Expo | React Native, Expo, or Expo Go | `references/sdks/powersync-js-react-native.md` |
-| Vue / Nuxt | Vue or Nuxt | `references/sdks/powersync-js-vue.md` |
-| Node.js / Electron | Node.js CLI/server or Electron | `references/sdks/powersync-js-node.md` |
-| TanStack | TanStack Query or TanStack DB | `references/sdks/powersync-js-tanstack.md` |
-
-### Other SDKs
-
-| Platform | Load when… | File |
-|----------|-----------|------|
-| Dart / Flutter | Dart / Flutter | `references/sdks/powersync-dart.md` |
-| .NET | .NET | `references/sdks/powersync-dotnet.md` |
-| Kotlin | Kotlin | `references/sdks/powersync-kotlin.md` |
-| Swift | Swift / iOS / macOS | `references/sdks/powersync-swift.md` |
-
-## Key Rules to Apply Without Being Asked
-
-- Use Sync Streams for new projects. Sync Rules are legacy.
-- Never define the `id` column in a PowerSync table schema; it is created automatically.
-- Use `column.integer` for booleans and `column.text` for ISO date strings.
-- `connect()` is fire-and-forget. Use `waitForFirstSync()` if you need readiness.
-- `transaction.complete()` is mandatory or the upload queue stalls permanently.
-- `disconnectAndClear()` is required on logout or user switch when local data must be wiped.
-- A 4xx response from `uploadData` blocks the upload queue permanently; return 2xx for validation errors.
+- **Architecture diagram** — shows the read/sync path (PowerSync Service → SDK) and write path (upload queue → your backend API)
+- **"What to Load for Your Task"** table — maps tasks to starter files and on-demand files
+- **SDK Reference Files** tables — maps frameworks/platforms to reference files
+- **"Key Rules to Apply Without Being Asked"** — `id` column, `connect()`, `transaction.complete()`, `disconnectAndClear()`, 4xx upload handling
diff --git a/skills/powersync/SKILL.md b/skills/powersync/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: powersync
-description: Guided onboarding and best practices for building applications with PowerSync — Cloud and self-hosted setup, sync configuration, client SDK usage, backend integration (Supabase, custom Postgres, MongoDB, MySQL, MSSQL), and debugging.
+description: Guided onboarding and best practices for building applications with PowerSync — Cloud and self-hosted setup, sync configuration, client SDK usage, backend integration (Supabase, custom Postgres, MongoDB, MySQL, MSSQL), and debugging. Use this skill whenever the user mentions PowerSync, offline-first sync, local-first architecture, sync rules, sync streams, uploadData, fetchCredentials, real-time data replication, or wants to add offline-capable sync to a mobile or web app — even if they don't explicitly name PowerSync.
 license: MIT
 compatibility: Works with any skills-compatible agent. Some references include CLI commands requiring the @powersync/cli package.
 metadata:
@@ -14,7 +14,7 @@ metadata:
 
 Use this skill to onboard a project onto PowerSync without trial-and-error. Treat this as a guided workflow first and a reference library second.
 
-**Agents:** Follow **[AGENTS.md](AGENTS.md)** in full — including **Agent compliance** (ask Cloud vs self-hosted, ask backend if unspecified, CLI-first, no silent shortcuts). **`powersync login`** is **PowerSync Cloud only** (PAT); self-hosted does not use it.
+**Agents: Read [AGENTS.md](AGENTS.md) before proceeding.** It contains the mandatory compliance rules and onboarding playbook. The Quick Rules below are a reminder, not a substitute. **`powersync login`** is **PowerSync Cloud only** (PAT); self-hosted does not use it.
 
 ## Quick Rules
 
@@ -34,6 +34,7 @@ Use this skill to onboard a project onto PowerSync without trial-and-error. Trea
 | Self-hosting / service config | `references/powersync-service.md` + `references/powersync-cli.md` | `references/sync-config.md` |
 | Writing sync config | `references/sync-config.md` | — |
 | Debugging sync issues | `references/powersync-debug.md` | — |
+| Raw Tables (advanced) | `references/raw-tables.md` | — |
 | Attachments | `references/attachments.md` | — |
 | Architecture overview | `references/powersync-overview.md` | — |
 
@@ -50,6 +51,7 @@ Always load `references/sdks/powersync-js.md` for any JS/TS project, then load t
 | Vue / Nuxt | `references/sdks/powersync-js-vue.md` | |
 | Node.js / Electron | `references/sdks/powersync-js-node.md` | |
 | TanStack | `references/sdks/powersync-js-tanstack.md` | |
+| Drizzle / Kysely ORM | `references/sdks/powersync-js-orm.md` | Project uses Drizzle or Kysely |
 
 ### Other SDKs
 

diff --git a/skills/powersync/references/attachments.md b/skills/powersync/references/attachments.md
@@ -7,6 +7,17 @@ metadata:
 
 # PowerSync Attachments
 
+> **Load this when** the app needs file uploads/downloads (images, documents, media) synced alongside PowerSync data.
+
+## Table of Contents
+- [How It Works](#how-it-works)
+- [Package Setup](#package-setup)
+- [Schema Setup](#schema-setup)
+- [Storage Adapters](#storage-adapters)
+- [Initialize the Attachment Queue](#initialize-the-attachment-queue)
+- [Upload / Delete / Access Files](#upload-a-file)
+- [Error Handling](#error-handling)
+
 PowerSync handles file attachments using a **metadata + storage provider** pattern: structured metadata syncs through PowerSync while actual files live in a purpose-built storage system (S3, Supabase Storage, Cloudflare R2, etc.). An offline-first queue manages uploads, downloads, and retries automatically in the background.
 
 | Resource | Description |

diff --git a/skills/powersync/references/custom-backend.md b/skills/powersync/references/custom-backend.md
@@ -7,6 +7,15 @@ metadata:
 
 # Custom Backend for PowerSync
 
+> **Load this when** building a PowerSync integration without Supabase — custom auth, custom backend API, or any non-Supabase database.
+
+## Table of Contents
+- [Architecture Recap](#architecture-recap)
+- [1. Custom JWT Auth](#1-custom-jwt-auth)
+- [2. Backend API for uploadData](#2-backend-api-for-uploaddata)
+- [3. Client-Side Connector](#3-client-side-connector-custom-backend)
+- [Common Pitfalls](#common-pitfalls)
+
 Use this file when building a PowerSync integration **without Supabase** — your own auth and a backend API that receives writes from the client's upload queue.
 
 For **source database setup** (Postgres replication, MongoDB replica set, MySQL binlog, MSSQL CDC), see `references/powersync-service.md` § "Source Database Setup".

diff --git a/skills/powersync/references/onboarding-custom.md b/skills/powersync/references/onboarding-custom.md
@@ -7,6 +7,8 @@ metadata:
 
 # Custom Backend + PowerSync Onboarding
 
+> **Load this when** onboarding an app onto PowerSync with a non-Supabase backend (custom Postgres, MongoDB, MySQL, MSSQL).
+
 Use this recipe when onboarding any app onto PowerSync with a **non-Supabase backend** — your own database, your own auth, and your own backend API. Works for all platforms (web, React Native, Flutter, Kotlin, Swift, .NET, etc.) and both Cloud and self-hosted.
 
 **CLI-first.** See `references/powersync-cli.md`. Fall back to the dashboard (Cloud) or manual Docker config (self-hosted) only if the CLI is unavailable or the user explicitly prefers it.

diff --git a/skills/powersync/references/onboarding-supabase.md b/skills/powersync/references/onboarding-supabase.md
@@ -7,6 +7,8 @@ metadata:
 
 # Supabase + PowerSync Cloud Onboarding
 
+> **Load this when** onboarding an app onto PowerSync Cloud with a Supabase backend.
+
 Use this recipe when onboarding any app onto PowerSync Cloud with a Supabase backend. This works for all platforms (web, React Native, Flutter, Kotlin, Swift, .NET, etc.).
 
 **CLI-first.** See `references/powersync-cli.md`. Fall back to the dashboard only if the CLI is unavailable or the user explicitly prefers it.
@@ -81,13 +83,17 @@ Only after Phase 2 is complete.
     ```
     Or write manually — but never define the `id` column (it is automatic).
 
-11. **Implement the backend connector.** See `references/supabase-auth.md` § "fetchCredentials()" for the Supabase-specific implementation. For `uploadData`, Supabase users can write directly to Supabase via the client library or use Edge Functions.
+11. **Implement the backend connector.** See `references/supabase-auth.md` § "fetchCredentials()" and § "uploadData()" for complete implementations including error handling strategy.
+
+    **Auth prerequisite:** `fetchCredentials()` requires an active Supabase session. Call `db.connect(connector)` only after the user has signed in. For apps without a sign-in screen, enable anonymous auth in Supabase Dashboard → Authentication → Providers → Anonymous.
 
 12. **Initialize PowerSync and connect.**
     - `connect()` is fire-and-forget — use `waitForFirstSync()` if you need readiness.
     - Use `disconnectAndClear()` on logout or user switch.
 
-13. **Switch reads to local SQLite** and test offline behavior.
+13. **Development tokens** (optional, for testing without user auth): After deploying, run `powersync generate token --subject=<user-id>` to get a short-lived JWT. On PowerSync Cloud, this works immediately after deploy — no extra `client_auth` config needed. Do not use dev tokens in production.
+
+14. **Switch reads to local SQLite** and test offline behavior.
 
 ## If the App Is Stuck on `Syncing...`
 

diff --git a/skills/powersync/references/powersync-cli.md b/skills/powersync/references/powersync-cli.md
@@ -7,6 +7,20 @@ metadata:
 
 # PowerSync CLI
 
+> **Load this when** setting up, deploying, or managing any PowerSync instance (Cloud or self-hosted). This is the primary tool for all PowerSync operations.
+
+## Table of Contents
+- [Recommended Defaults for Agents](#recommended-defaults-for-agents)
+- [Installation](#installation)
+- [Instance Resolution](#how-the-cli-resolves-instance-information)
+- [Authentication](#authentication)
+- [Config Files](#config-files)
+- [Cloud Usage](#cloud-usage)
+- [Self-Hosted Usage](#self-hosted-usage)
+- [Docker Commands](#docker-commands-reference)
+- [Common Commands](#common-commands)
+- [Development Tokens](#development-tokens)
+
 The PowerSync CLI manages Cloud and self-hosted PowerSync instances from the command line. It supports local config management, schema generation, development token generation, deployment, and more. See [this](https://docs.powersync.com/tools/cli.md) for any information not supplied in this document about the CLI.
 
 ## Recommended Defaults for Agents

diff --git a/skills/powersync/references/powersync-debug.md b/skills/powersync/references/powersync-debug.md
@@ -7,6 +7,8 @@ metadata:
 
 # PowerSync Debug
 
+> **Load this when** troubleshooting sync issues, stuck "Syncing..." states, JWT errors, or replication problems.
+
 These are debugging steps most frequently recommended by PowerSync, with an explanation of what problem each step helps identify and why it works.
 
 Make sure to understand the [PowerSync Architecture](references/powersync-overview.md) before debugging.

diff --git a/skills/powersync/references/powersync-overview.md b/skills/powersync/references/powersync-overview.md
@@ -7,6 +7,8 @@ metadata:
 
 # PowerSync Architecture Overview
 
+> **Load this when** you need to understand how PowerSync's components fit together before diving into implementation.
+
 Guidance for understanding all the moving components of PowerSync. For information about the vision of PowerSync, see [PowerSync Philosophy](https://docs.powersync.com/intro/powersync-philosophy.md)
 
 ## Architecture

diff --git a/skills/powersync/references/powersync-service.md b/skills/powersync/references/powersync-service.md
@@ -7,6 +7,16 @@ metadata:
 
 # PowerSync Service
 
+> **Load this when** configuring the PowerSync service itself — self-hosting, Docker, source database connections, bucket storage, or authentication setup.
+
+## Table of Contents
+- [Sync Config](#sync-config)
+- [Service Configuration (Self-hosted)](#service-configuration-self-hosted)
+- [PowerSync Cloud Setup](#powersync-cloud-setup)
+- [Source Database Setup](#source-database-setup)
+- [App Backend](#app-backend)
+- [Authentication](#authentication)
+
 Guidance for configuring PowerSync Service, sync config, and database replication.
 
 Critical warnings for fast setup: