update readmes

Author: stevensJourney

cli/README.md

@@ -1,6 +1,22 @@
 # powersync
 
-CLI for PowerSync
+Programmatically manage your PowerSync environment.
+
+For an overview, see the docs [here](https://docs.powersync.com/tools/cli).
+
+## Note: Beta Release
+
+This package is currently in a beta release.
+
+## Upgrading from 0.8.0
+
+Version 0.9.0 and above are **not backwards compatible** with 0.8.0. If you are using the previous CLI commands and are not ready to migrate, you can continue using the old version:
+
+```bash
+npm install -g @powersync/cli@0.8.0
+```
+
+Otherwise, refer to the [docs](https://docs.powersync.com/tools/cli) for guidance on migrating to the new version.
 
 [![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
 [![Version](https://img.shields.io/npm/v/@powersync/cli.svg)](https://npmjs.org/package/@powersync/cli)
@@ -66,7 +82,7 @@ Set **`PS_ADMIN_TOKEN`** to your PAT. The CLI uses **`PS_ADMIN_TOKEN`** when set
 
 ```sh
 export PS_ADMIN_TOKEN=your-personal-access-token
-powersync fetch instances --project-id=<project-id>
+powersync fetch instances
 ```
 
 To stop using stored credentials, run **`powersync logout`**. This clears the stored token from the active backend (secure storage or config-file fallback).

packages/cli-core/README.md

@@ -0,0 +1,24 @@
+# @powersync/cli-core
+
+Core types, base commands, and utilities shared across the PowerSync CLI and its plugins.
+
+> **Internal use:** This package is intended for internal use by the PowerSync CLI and its bundled plugins. It is not part of the public API.
+>
+> **Plugin authors:** You can use `@powersync/cli-core` to build your own PowerSync CLI plugins, but treat this package as **experimental and subject to change**. There are no stability guarantees between releases — APIs, types, and base classes may be renamed, restructured, or removed without a deprecation period.
+
+## What's in this package
+
+- Base command classes (`PowerSyncCommand`, `InstanceCommand`, `SelfHostedInstanceCommand`) for building CLI commands and plugins.
+- Shared types (`SelfHostedProject`, `SelfHostedInstanceCommandFlags`, `EnsureConfigOptions`, etc.).
+- YAML helpers (`parseYamlFile`, `parseYamlDocumentPreserveTags`, `stringifyYaml`) for `!env`-aware config parsing.
+- Auth and project resolution utilities used by the CLI and official plugins.
+
+## Usage in plugins
+
+Import from `@powersync/cli-core` when authoring your own plugin:
+
+```ts
+import { SelfHostedInstanceCommand, PowerSyncCommand } from '@powersync/cli-core';
+```
+
+See `@powersync/cli-plugin-docker` for a reference implementation.

packages/editor/README.md

@@ -1,5 +1,7 @@
 # PowerSync CLI Config Studio
 
+> **Private package — not published to npm.** This package is built and bundled into [`@powersync/cli-plugin-config-edit`](../../plugins/config-edit) during the build step (`pnpm --filter editor build` copies the output into `plugins/config-edit/editor-dist/`). It is served at runtime by that plugin when you run `powersync edit config`. It is not intended to be installed or used directly.
+
 The PowerSync CLI Config Studio is the Monaco-powered editor that ships with the `powersync edit config` command. It exposes the two YAML files managed by the CLI (`service.yaml` and `sync-config.yaml`), enforces our official JSON Schemas, and lets you save the result back to your local PowerSync directory without touching the CLI manually.
 
 ## Feature highlights

packages/schemas/README.md

@@ -0,0 +1,5 @@
+# @powersync/cli-schemas
+
+JSON Schema definitions and TypeScript types for PowerSync CLI configuration files (`service.yaml`, `sync-config.yaml`, `cli.yaml`).
+
+> **Internal use:** This package is intended for internal use by the PowerSync CLI, its plugins, and the config editor. It is not part of the public API and may change without notice between releases.

plugins/config-edit/README.md

@@ -0,0 +1,13 @@
+# @powersync/cli-plugin-config-edit
+
+> **Bundled plugin:** This plugin is automatically included in the `powersync` package. You do not need to install it separately — the `powersync edit config` command is available out of the box when you install `powersync`.
+
+PowerSync CLI plugin that launches the Monaco-powered configuration editor for `service.yaml` and `sync-config.yaml`. It serves the `editor` package as a local web app and opens it in your browser.
+
+## Usage
+
+```bash
+powersync edit config --directory ./powersync
+```
+
+See the `editor` package for details on how the editor works and how to develop it locally.

plugins/docker/README.md

@@ -1,5 +1,7 @@
 # @powersync/cli-plugin-docker
 
+> **Bundled plugin:** This plugin is automatically included in the `powersync` package. You do not need to install it separately — all `powersync docker` commands are available out of the box when you install `powersync`.
+
 PowerSync CLI plugin that adds a **docker** topic for self-hosted instances: **configure**, **reset**, **start**, and **stop** using Docker Compose.
 
 ## Commands
@@ -17,7 +19,7 @@ All commands use the same project and directory resolution as the main CLI (e.g.
 
 ## Templates (composable modules)
 
-Templates are organized by **category** and **implementation** (see also [usage-docker.md](../docs/usage-docker.md#how-configure-uses-templates)):
+Templates are organized by **category** and **implementation**:
 
 - **`templates/source-database/`** – Replication source (e.g. **postgres**). Used by **`--database`**.
 - **`templates/bucket-storage/`** – PowerSync bucket metadata (e.g. **postgres**). Used by **`--storage`**.