Add context and explanations to README

Author: max-lt

README.md

@@ -35,112 +35,137 @@ Common operations: `list` (`ls`), `get`, `create`, `delete` (`rm`)
 
 ## Workers
 
+Workers are serverless functions deployed to the edge.
+
 ```bash
 ow workers list
 ow workers create my-api -d "REST API"
 ow workers get my-api
+
+# Deploy a single file
 ow workers deploy my-api ./worker.ts -m "Initial deploy"
-ow workers upload my-app ./dist      # Upload folder with assets
-ow workers link my-api --env my-env  # Link environment
+
+# Deploy a folder with worker.js + static assets (SvelteKit, etc.)
+ow workers upload my-app ./dist
+
 ow workers delete my-api
 ```
 
 Supported file types: `.js`, `.ts`, `.wasm`
 
 ## Environments
 
-Manage variables, secrets, and resource bindings.
+Environments group configuration for your workers: variables, secrets, and bindings to resources.
 
 ```bash
 ow env list
 ow env create my-env -d "Production"
 ow env get my-env
 
-# Variables and secrets
+# Variables (plain text, visible in logs)
 ow env set my-env API_URL "https://api.example.com"
+
+# Secrets (encrypted, masked in output)
 ow env set my-env API_KEY "secret" --secret
+
 ow env unset my-env OLD_VAR
 
-# Bind resources
+# Bindings connect resources to your worker code (accessible via env.CACHE, env.DB, etc.)
 ow env bind my-env CACHE my-kv --type kv
 ow env bind my-env DB my-db --type database
 ow env bind my-env ASSETS my-storage --type assets
 
+# Link environment to a worker
+ow workers link my-api --env my-env
+
 ow env delete old-env
 ```
 
 ## Storage
 
-S3-compatible storage (R2, MinIO, AWS S3).
+S3-compatible object storage for files, images, and static assets.
 
 ```bash
 ow storage list
+
+# Platform-managed storage
 ow storage create my-storage
+
+# Bring your own S3/R2 bucket
 ow storage create my-s3 --provider s3 \
   --bucket my-bucket \
   --endpoint https://xxx.r2.cloudflarestorage.com \
   --access-key-id AKIA... \
   --secret-access-key ...
+
 ow storage delete my-storage
 ```
 
 ## KV
 
-Key-value namespaces for caching and sessions.
+Fast key-value store for caching, sessions, and feature flags.
 
 ```bash
 ow kv list
-ow kv create cache -d "API cache"
-ow kv get cache
-ow kv delete cache
+ow kv create my-kv -d "API cache"
+ow kv get my-kv
+ow kv delete my-kv
 ```
 
 ## Databases
 
-SQL database bindings.
+SQL databases for persistent data. Query with `env.DB.execute()` in your worker.
 
 ```bash
 ow databases list
+
+# Platform-managed database
 ow databases create my-db
+
+# Bring your own Postgres
 ow databases create my-pg --provider postgres \
   --connection-string "postgres://user:pass@host/db"
+
 ow databases delete my-db
 ```
 
 ## Aliases
 
-The CLI supports multiple backends via aliases. Config is stored in `~/.openworkers/config.json`.
+Aliases let you manage multiple backends (production, staging, local) from the same CLI.
 
 ```bash
-# API backend (hosted or self-hosted)
+# API backend (hosted platform)
 ow alias set prod --api https://dash.openworkers.com
+
+# API backend (self-hosted, skip TLS verification)
 ow alias set dev --api http://localhost:8080 --insecure
 
-# DB backend (direct PostgreSQL, for migrations)
+# DB backend (direct PostgreSQL access for migrations)
 ow alias set local --db postgres://user:pass@localhost/ow --user admin@example.com
 
-# Manage aliases
 ow alias list
 ow alias set-default prod
 ow alias rm old-alias
 ```
 
-Use an alias by prefixing commands:
+Prefix any command with an alias name:
 
 ```bash
 ow workers list           # Uses default alias
 ow prod workers list      # Uses 'prod' alias
-ow local migrate run      # Uses 'local' alias
+ow dev workers get my-api # Uses 'dev' alias
 ```
 
+Config stored in `~/.openworkers/config.json`.
+
 ## Migrations
 
-Database schema migrations (requires DB alias).
+Database schema migrations for self-hosted deployments. Requires a DB alias.
 
 ```bash
 ow local migrate status    # Show pending migrations
-ow local migrate run       # Apply migrations
-ow local migrate baseline  # Mark all as applied (existing DB)
+ow local migrate run       # Apply pending migrations
+ow local migrate baseline  # Mark all as applied (for existing databases)
 ```
 
 ## Config File