docs: add verified package usage examples

packages/mobile/README.md

@@ -1,24 +1,83 @@
 # @wrnexus/mobile
 
-SSR-safe access to Capacitor plugins from WrNexus browser code.
+> SSR-safe access to Capacitor plugins from WRNexusJS browser code.
+
+## Overview
+
+`@wrnexus/mobile` keeps optional native imports out of server rendering while giving
+browser-owned modules one consistent registry for Capacitor plugins. During SSR,
+`mobile.isNative()` is `false` and `mobile.platform()` is `"web"`.
+
+## Installation
+
+Install a plugin through the WRNexusJS CLI so the web and native projects stay aligned:
 
 ```bash
-wrnexus mobile add @capacitor/camera
+wrnexus mobile add @capacitor/camera @capacitor/haptics
 ```
 
+## Usage
+
+### Register and invoke a Capacitor plugin
+
+Import Capacitor packages only from browser-owned code, never from API routes or SSR
+helpers.
+
 ```ts
-import { Camera } from "@capacitor/camera";
+import { Camera, CameraResultType } from "@capacitor/camera";
 import { mobile } from "@wrnexus/mobile";
 
-if (mobile.isNative()) {
-  mobile.registerPlugin("Camera", Camera);
-  const photo = await mobile.invoke("Camera", "getPhoto", { resultType: "uri" });
+mobile.registerPlugin("Camera", Camera);
+
+export async function takePhoto() {
+  if (!mobile.isNative()) return null;
+  return mobile.invoke("Camera", "getPhoto", {
+    quality: 85,
+    resultType: CameraResultType.Uri,
+  });
 }
 ```
 
-`isNative()` is false and `platform()` is `web` during SSR. `plugin()` returns
-`undefined` when unavailable; `requirePlugin()` and `invoke()` throw an
-actionable `MobileUnavailableError`.
+### Provide a browser fallback
 
-Import and register Capacitor packages only from browser-owned code. Do not
-import them in server routes, SSR helpers, or other Bun-only modules.
+`whenNative` runs the first callback only in a Capacitor WebView and can return a
+web/SSR-safe fallback everywhere else.
+
+```ts
+import { Haptics, ImpactStyle } from "@capacitor/haptics";
+import { mobile } from "@wrnexus/mobile";
+
+mobile.registerPlugin("Haptics", Haptics);
+
+export const confirmAction = () =>
+  mobile.whenNative(
+    () => mobile.invoke("Haptics", "impact", { style: ImpactStyle.Medium }),
+    () => navigator.vibrate?.(30),
+  );
+```
+
+### Read an optional plugin without throwing
+
+```ts
+import type { NetworkPlugin } from "@capacitor/network";
+import { mobile } from "@wrnexus/mobile";
+
+const network = mobile.plugin<NetworkPlugin>("Network");
+const status = network ? await network.getStatus() : { connected: true, connectionType: "unknown" };
+```
+
+## API
+
+- `registerPlugin(name, instance)` registers a browser-imported plugin.
+- `plugin(name)` returns a plugin or `undefined`; `requirePlugin(name)` throws when absent.
+- `invoke(plugin, method, options?)` calls a registered method and returns its result.
+- `whenNative(native, fallback?)` selects native behavior without breaking SSR.
+- `isNative()` and `platform()` report the current Capacitor environment.
+
+Unavailable required plugins throw `MobileUnavailableError` with an actionable message.
+
+## Requirements / Notes
+
+- Capacitor plugin imports must remain in browser-owned modules.
+- `@wrnexus/mobile` re-exports `native` from `@wrnexus/native` for applications that
+  prefer the higher-level cross-platform capability API.

packages/mobile/package.json

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