docs: add verified package usage examples

packages/cli/README.md

@@ -188,6 +188,47 @@ Runs the app's tests with `bun test`. Defaults to the `test` profile (config + `
 wrnexus test . --watch
 ```
 
+## Usage
+
+### Create and run a single application
+
+```bash
+bunx @wrnexus/cli create customer-portal
+cd customer-portal
+bun install
+bun run dev
+```
+
+### Add routes and shared UI to an existing app
+
+```bash
+wrnexus generate page reports/monthly
+wrnexus generate api reports/export
+wrnexus generate component report-filter
+wrnexus generate routes
+```
+
+### Create a multi-app workspace and add another app
+
+```bash
+wrnexus workspace company-suite
+cd company-suite
+wrnexus workspace add reports --domain=reports.localhost
+bun install
+wrnexus gateway --port=3000
+```
+
+Open `http://reports.localhost:3000`; the gateway selects `apps/reports` from the
+request host.
+
+### Upgrade with migrations and verification
+
+```bash
+wrnexus update --latest --dry-run
+wrnexus update --latest
+wrnexus doctor
+```
+
 ## Profiles
 
 Pass `--profile=<name>` to `dev`, `build`, `db` (or set `WRNEXUS_PROFILE`) to select a config profile. The CLI publishes `WRNEXUS_PROFILE` so config loaders and the dev child pick it up, and loads that profile's `.env` cascade (`.env`, `.env.local`, `.env.<profile>`, `.env.<profile>.local`) into `process.env`.

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrnexus/cli",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "type": "module",
   "main": "src/index.ts",
   "exports": {

packages/cli/src/update.ts

@@ -288,6 +288,14 @@ const MIGRATIONS: Migration[] = [
       // Explicit no-op: updating @wrnexus/validation is sufficient.
     },
   },
+  {
+    version: "0.2.24",
+    id: "package-usage-documentation",
+    description: "No project-file changes; package usage documentation is expanded",
+    apply() {
+      // Explicit no-op: this release updates package and portal documentation only.
+    },
+  },
 ];
 
 /** Release tooling uses this to require an explicit migration entry per version. */