@chipmobilesdk/rn-ai 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,55 +1,71 @@
-# Changelog — @chipmobilesdk/rn-ai
-
-## [0.2.0] — 2026-11-01
-
-Fixes a chat or quota call that could hang forever, and errors that never
-reached the app. **No code change is required.**
-
-### Fixed
-
-- **Every network call has a time limit.** The chat stream had none, and
-  neither did the config or quota fetch, so on a stalled mobile connection
-  `useAiChat` stayed in `loading`/`streaming` and `useAiQuota` in `loading`
-  until the user gave up — and with no cached config, one hung fetch blocked
-  every call. New `timeouts: { connectMs, idleMs, configMs, quotaMs }` option
-  (defaults 30 s, 30 s, 10 s, 10 s). The idle limit restarts on every chunk.
-- **No error is swallowed.** Every chat path ended in `.catch(() => undefined)`,
-  so a transport that threw (an invalid URL from remote config, for example)
-  left the UI in `loading` with nothing to show. Such failures now arrive as
-  `AiError('internal')`. The remote `recovery` block is type-checked when
-  parsed, so a mistyped value can no longer throw inside the XHR callback.
-- **A cancelled or replaced request stays silent.** A token or config failure
-  that landed after `cancel()` (or after the next `send()`) still called
-  `onError` and flipped that screen to `error`. The client now routes every
-  callback through one guard (nothing after cancel, exactly one of
-  `onDone`/`onError`), and `useAiChat` and `useAiQuota` drop callbacks from
-  older requests.
-
-### Changed
-
-- A stalled stream, a timed-out quota fetch and a dropped connection (status 0)
-  report `upstream-error` with `recoverable: true`; status 0 was
-  `recoverable: false`.
-
-### Added
-
-- `AiClientConfig.timeouts` and the `AiTimeouts` type.
-
-## 0.1.0 — 2026-07-05
-
-Initial release (feature `005-azure-ai-gateway`).
-
-- `createAiClient` — config-driven gateway client: cache-first app behavior
-  config (ETag/TTL), token acquisition via `@chipmobilesdk/rn-auth`
-  (`resourceKey`), SSE streaming over zero-dependency XHR transport.
-- Multimodal chat requests: `text`, `image` (base64), `audio` (wav/mp3).
-- Silent endpoint re-route on designated `404`/`410` signals (max 1 retry);
-  one automatic fresh-token retry on `401`; no automatic retry on `429`.
-- `useAiChat` (idle/loading/streaming/done/error/rate-limited + accumulated
-  text + `retryAt`) and `useAiQuota` hooks.
-- Typed `AiError` codes and `ai.*` message keys with English defaults.
-- Per-app kill switch honored (`features.aiEnabled`).
-
-Adoption: additive — no changes required in existing apps. Requires an
-`ai-gateway` resource entry in the rn-auth config and a registered app on the
-gateway platform.
+# @chipmobilesdk/rn-ai
+
+## 0.2.1
+
+### Patch Changes
+
+- Packaging only; no code change. The package no longer declares `engines.node`: a
+  React Native package does not run on Node, so the field only produced install
+  warnings in apps on another Node version. rn-i18n's command-line tooling does run
+  on Node; its README's compatibility table states the version it needs. ([#14](https://github.com/operationd8979/chip-mobile-sdk/pull/14))
+
+## [0.2.0] — 2026-11-01
+
+Fixes a chat or quota call that could hang forever, and errors that never
+reached the app. **No code change is required.**
+
+### Fixed
+
+- **Every network call has a time limit.** The chat stream had none, and
+  neither did the config or quota fetch, so on a stalled mobile connection
+  `useAiChat` stayed in `loading`/`streaming` and `useAiQuota` in `loading`
+  until the user gave up — and with no cached config, one hung fetch blocked
+  every call. New `timeouts: { connectMs, idleMs, configMs, quotaMs }` option
+  (defaults 30 s, 30 s, 10 s, 10 s). The idle limit restarts on every chunk.
+- **No error is swallowed.** Every chat path ended in `.catch(() => undefined)`,
+  so a transport that threw (an invalid URL from remote config, for example)
+  left the UI in `loading` with nothing to show. Such failures now arrive as
+  `AiError('internal')`. The remote `recovery` block is type-checked when
+  parsed, so a mistyped value can no longer throw inside the XHR callback.
+- **A cancelled or replaced request stays silent.** A token or config failure
+  that landed after `cancel()` (or after the next `send()`) still called
+  `onError` and flipped that screen to `error`. The client now routes every
+  callback through one guard (nothing after cancel, exactly one of
+  `onDone`/`onError`), and `useAiChat` and `useAiQuota` drop callbacks from
+  older requests.
+
+### Changed
+
+- A stalled stream, a timed-out quota fetch and a dropped connection (status 0)
+  report `upstream-error` with `recoverable: true`; status 0 was
+  `recoverable: false`.
+
+### Added
+
+- `AiClientConfig.timeouts` and the `AiTimeouts` type.
+
+## 0.1.1 — 2026-08-01
+
+### Changed
+
+- The package now ships its agent skill (`skills/`), which consuming apps
+  copy in with `scripts/sync-sdk-skills.mjs`. No code change.
+
+## 0.1.0 — 2026-07-05
+
+Initial release (feature `005-azure-ai-gateway`).
+
+- `createAiClient` — config-driven gateway client: cache-first app behavior
+  config (ETag/TTL), token acquisition via `@chipmobilesdk/rn-auth`
+  (`resourceKey`), SSE streaming over zero-dependency XHR transport.
+- Multimodal chat requests: `text`, `image` (base64), `audio` (wav/mp3).
+- Silent endpoint re-route on designated `404`/`410` signals (max 1 retry);
+  one automatic fresh-token retry on `401`; no automatic retry on `429`.
+- `useAiChat` (idle/loading/streaming/done/error/rate-limited + accumulated
+  text + `retryAt`) and `useAiQuota` hooks.
+- Typed `AiError` codes and `ai.*` message keys with English defaults.
+- Per-app kill switch honored (`features.aiEnabled`).
+
+Adoption: additive — no changes required in existing apps. Requires an
+`ai-gateway` resource entry in the rn-auth config and a registered app on the
+gateway platform.

package/README.md

@@ -1,151 +1,151 @@
-# @chipmobilesdk/rn-ai
-
-AI gateway client for ChipMobileSdk-family React Native apps. Streams
-multimodal (text + image + audio in, text out) AI responses through the
-platform gateway with per-user rate limiting — apps never talk to Azure
-OpenAI directly and hold no AI credentials.
-
-> **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
-
-- **Version**: `0.2.x` (see [CHANGELOG](CHANGELOG.md))
-- **Entrypoint**: `@chipmobilesdk/rn-ai`
-- **Native code**: none
-
-- Contract: [rn-ai-public-api](../../specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md)
-- Gateway API: [gateway-api](../../specs/005-azure-ai-gateway/contracts/gateway-api.md)
-- Behavior config: [app-behavior-config](../../specs/005-azure-ai-gateway/contracts/app-behavior-config.md)
-
-## Install
-
-```bash
-npm install @chipmobilesdk/rn-ai @chipmobilesdk/rn-auth
-```
-
-Peers: `react >=19`, `react-native >=0.85`, `@chipmobilesdk/rn-auth >=0.2.0`.
-**Zero runtime dependencies**; streaming uses React Native's standard
-`XMLHttpRequest` (no native code, Hermes-compatible, iOS + Android).
-
-## Setup
-
-1. Add the gateway resource to your rn-auth config:
-
-```ts
-resources: [
-  { key: 'ai-gateway', scopes: ['api://aiapp-gateway/AI.Access'] },
-]
-```
-
-2. Create the client (one per app):
-
-```ts
-import { createAiClient } from '@chipmobilesdk/rn-ai';
-import { auth } from './auth/setup';
-
-export const aiClient = createAiClient({
-  appId: 'scan-food',
-  configUrl: 'https://<config-host>/appconfig/config/scan-food.json',
-  resourceKey: 'ai-gateway',
-  auth,
-  // storage: inject a persistent AiConfigCache for offline launches
-});
-```
-
-3. Use the hooks:
-
-```tsx
-import { useAiChat, useAiQuota } from '@chipmobilesdk/rn-ai';
-import { aiClient } from './ai/setup';
-
-const { send, cancel, status, text, error, retryAt } = useAiChat(aiClient);
-const { quota } = useAiQuota(aiClient);
-
-send({
-  messages: [{
-    role: 'user',
-    content: [
-      { type: 'text', text: 'What dish is this? Estimate calories.' },
-      { type: 'image', mimeType: 'image/jpeg', dataBase64: photoBase64 },
-    ],
-  }],
-});
-```
-
-## Runtime behavior
-
-- **Config-driven endpoint**: resolved lazily on the first quota or chat
-  request. A fresh cache entry is used immediately; a stale entry is used
-  immediately and revalidated in the background with its ETag. With no cache,
-  the first operation waits for the config request, for at most `configMs`.
-  Designated `404`/`410`
-  responses invalidate config and retry against the refreshed endpoint.
-- **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
-  on `401`, reacquires a token and retries once.
-- **Timeouts**: every network call is bounded. Override any of them with
-  `createAiClient({ timeouts: { ... } })`:
-
-  | | Default | Fails with |
-  |---|---|---|
-  | `connectMs` — chat request sent → headers | 30 s | `upstream-error`, `recoverable: true` |
-  | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `recoverable: true` |
-  | `configMs` — behavior-config fetch | 10 s | stale cache if any, else `config-unavailable` |
-  | `quotaMs` — quota fetch | 10 s | `upstream-error`, `recoverable: true` |
-
-  The gateway sends headers only after the model answers, so `connectMs` also
-  covers time to first token. A dropped connection (HTTP status 0) is likewise
-  `upstream-error` with `recoverable: true`.
-- **Callbacks**: each `chat()` delivers exactly one of `onDone` / `onError`,
-  and nothing after `cancel()`. An unexpected exception anywhere on the way
-  (including in your own `onDelta`) is reported as `internal`, never dropped.
-- **Rate limits**: `429` surfaces as `status: 'rate-limited'` with `retryAt`;
-  the SDK never hammers and never enforces limits locally (display only).
-- **Typed errors** (`AiError.code`): `auth-invalid`, `not-entitled`,
-  `user-blocked`, `app-unknown`, `rate-limited`, `upstream-busy`,
-  `payload-too-large`, `modality-not-allowed`, `config-unavailable`,
-  `upstream-error`, `internal`.
-- **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
-
-## Public API
-
-Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
-`transport/`, `core/`, `react/`, and `diagnostics/` paths are not public.
-
-- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`
-- Chat: `ChatRequest`, `ChatMessage`, `ContentPart`, `ChatStreamHandlers`,
-  `ChatHandle`, `Usage`
-- Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
-  `AiConfigCache`, `QuotaSnapshot`
-- React: `useAiChat`, `useAiQuota`, `AiChatStatus`, `UseAiChatResult`,
-  `UseAiQuotaResult`
-- Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
-  `aiMessage`, `AiMessageKey`
-
-## App responsibilities
-
-- **AI disclosure (store policy)**: user text/images/audio are processed by
-  the platform's AI service. Update your privacy policy, Apple App Privacy,
-  and Google Play Data Safety before shipping, and disclose AI processing
-  in-app (POL-005/006 in the feature spec).
-- Camera/microphone permissions for capture UIs are yours; the SDK only
-  accepts already-captured data and adds no permissions.
-- Respect `payload-too-large` (default cap 10 MB/request) by resizing images
-  and bounding audio length.
-
-## Compatibility
-
-React ≥19 · React Native ≥0.85 (Hermes) · iOS + Android · Node ≥22.11 for
-tooling.
-
-The repository contains `src/screens/AiDemoScreen.tsx` and its component test.
-The current demo sidebar does not expose that screen yet, so it must be wired
-into `ScreenKey`, `Sidebar`, and `ActiveScreen` before it is reachable in-app.
-
-## Validation
-
-Run from the repository root:
-
-```bash
-npm run typecheck:ai
-npm run pack:ai
-npm run validate:ai
-```
+# @chipmobilesdk/rn-ai
+
+AI gateway client for ChipMobileSdk-family React Native apps. Streams
+multimodal (text + image + audio in, text out) AI responses through the
+platform gateway with per-user rate limiting — apps never talk to Azure
+OpenAI directly and hold no AI credentials.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: see [CHANGELOG](CHANGELOG.md)
+- **Entrypoint**: `@chipmobilesdk/rn-ai`
+- **Native code**: none
+
+- Contract: [rn-ai-public-api](../../specs/005-azure-ai-gateway/contracts/rn-ai-public-api.md)
+- Gateway API: [gateway-api](../../specs/005-azure-ai-gateway/contracts/gateway-api.md)
+- Behavior config: [app-behavior-config](../../specs/005-azure-ai-gateway/contracts/app-behavior-config.md)
+
+## Install
+
+```bash
+npm install @chipmobilesdk/rn-ai @chipmobilesdk/rn-auth
+```
+
+Peers: `react >=19`, `react-native >=0.85`, `@chipmobilesdk/rn-auth >=0.2.0`.
+**Zero runtime dependencies**; streaming uses React Native's standard
+`XMLHttpRequest` (no native code, Hermes-compatible, iOS + Android).
+
+## Setup
+
+1. Add the gateway resource to your rn-auth config:
+
+```ts
+resources: [
+  { key: 'ai-gateway', scopes: ['api://aiapp-gateway/AI.Access'] },
+]
+```
+
+2. Create the client (one per app):
+
+```ts
+import { createAiClient } from '@chipmobilesdk/rn-ai';
+import { auth } from './auth/setup';
+
+export const aiClient = createAiClient({
+  appId: 'scan-food',
+  configUrl: 'https://<config-host>/appconfig/config/scan-food.json',
+  resourceKey: 'ai-gateway',
+  auth,
+  // storage: inject a persistent AiConfigCache for offline launches
+});
+```
+
+3. Use the hooks:
+
+```tsx
+import { useAiChat, useAiQuota } from '@chipmobilesdk/rn-ai';
+import { aiClient } from './ai/setup';
+
+const { send, cancel, status, text, error, retryAt } = useAiChat(aiClient);
+const { quota } = useAiQuota(aiClient);
+
+send({
+  messages: [{
+    role: 'user',
+    content: [
+      { type: 'text', text: 'What dish is this? Estimate calories.' },
+      { type: 'image', mimeType: 'image/jpeg', dataBase64: photoBase64 },
+    ],
+  }],
+});
+```
+
+## Runtime behavior
+
+- **Config-driven endpoint**: resolved lazily on the first quota or chat
+  request. A fresh cache entry is used immediately; a stale entry is used
+  immediately and revalidated in the background with its ETag. With no cache,
+  the first operation waits for the config request, for at most `configMs`.
+  Designated `404`/`410`
+  responses invalidate config and retry against the refreshed endpoint.
+- **Auth**: acquires tokens via rn-auth (`requestAccessToken('ai-gateway')`);
+  on `401`, reacquires a token and retries once.
+- **Timeouts**: every network call is bounded. Override any of them with
+  `createAiClient({ timeouts: { ... } })`:
+
+  | | Default | Fails with |
+  |---|---|---|
+  | `connectMs` — chat request sent → headers | 30 s | `upstream-error`, `recoverable: true` |
+  | `idleMs` — silence between two stream chunks | 30 s | `upstream-error`, `recoverable: true` |
+  | `configMs` — behavior-config fetch | 10 s | stale cache if any, else `config-unavailable` |
+  | `quotaMs` — quota fetch | 10 s | `upstream-error`, `recoverable: true` |
+
+  The gateway sends headers only after the model answers, so `connectMs` also
+  covers time to first token. A dropped connection (HTTP status 0) is likewise
+  `upstream-error` with `recoverable: true`.
+- **Callbacks**: each `chat()` delivers exactly one of `onDone` / `onError`,
+  and nothing after `cancel()`. An unexpected exception anywhere on the way
+  (including in your own `onDelta`) is reported as `internal`, never dropped.
+- **Rate limits**: `429` surfaces as `status: 'rate-limited'` with `retryAt`;
+  the SDK never hammers and never enforces limits locally (display only).
+- **Typed errors** (`AiError.code`): `auth-invalid`, `not-entitled`,
+  `user-blocked`, `app-unknown`, `rate-limited`, `upstream-busy`,
+  `payload-too-large`, `modality-not-allowed`, `config-unavailable`,
+  `upstream-error`, `internal`.
+- **Copy keys**: `ai.*` defaults in `aiMessages` — map through your i18n.
+
+## Public API
+
+Everything is exported from `@chipmobilesdk/rn-ai`; internal `config/`,
+`transport/`, `core/`, `react/`, and `diagnostics/` paths are not public.
+
+- Client: `createAiClient`, `AiClient`, `AiClientConfig`, `TokenProvider`
+- Chat: `ChatRequest`, `ChatMessage`, `ContentPart`, `ChatStreamHandlers`,
+  `ChatHandle`, `Usage`
+- Behavior and cache: `AppBehaviorConfig`, `AiBehaviorState`, `BehaviorState`,
+  `AiConfigCache`, `QuotaSnapshot`
+- React: `useAiChat`, `useAiQuota`, `AiChatStatus`, `UseAiChatResult`,
+  `UseAiQuotaResult`
+- Diagnostics and copy: `AiError`, `AiErrorCode`, `isAiError`, `aiMessages`,
+  `aiMessage`, `AiMessageKey`
+
+## App responsibilities
+
+- **AI disclosure (store policy)**: user text/images/audio are processed by
+  the platform's AI service. Update your privacy policy, Apple App Privacy,
+  and Google Play Data Safety before shipping, and disclose AI processing
+  in-app (POL-005/006 in the feature spec).
+- Camera/microphone permissions for capture UIs are yours; the SDK only
+  accepts already-captured data and adds no permissions.
+- Respect `payload-too-large` (default cap 10 MB/request) by resizing images
+  and bounding audio length.
+
+## Compatibility
+
+React ≥19 · React Native ≥0.85 (Hermes) · iOS + Android · Node ≥22.11 for
+tooling.
+
+The repository contains `src/screens/AiDemoScreen.tsx` and its component test.
+The current demo sidebar does not expose that screen yet, so it must be wired
+into `ScreenKey`, `Sidebar`, and `ActiveScreen` before it is reachable in-app.
+
+## Validation
+
+Run from the repository root:
+
+```bash
+npm run typecheck --workspace @chipmobilesdk/rn-ai
+npm run pack:check --workspace @chipmobilesdk/rn-ai
+npm run validate
+```

package/package.json

@@ -1,43 +1,36 @@
-{
-	"name": "@chipmobilesdk/rn-ai",
-	"version": "0.2.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/config",
-		"src/transport",
-		"src/core",
-		"src/react",
-		"src/diagnostics",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"@chipmobilesdk/rn-auth": ">=0.2.0",
-		"react": ">=19",
-		"react-native": ">=0.85"
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-ai",
+	"version": "0.2.1",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:check": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"@chipmobilesdk/rn-auth": ">=0.2.0",
+		"react": ">=19",
+		"react-native": ">=0.85"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-ai/SKILL.md

@@ -1,57 +1,56 @@
----
-name: sdk-rn-ai
-description: "AI chat and quota via @chipmobilesdk/rn-ai: createAiClient, useAiChat, useAiQuota, streaming status, AI error codes. Use when adding an AI chat feature, showing quota, or handling AI request failures and cancellation."
-metadata:
-  package: "@chipmobilesdk/rn-ai"
-  packageVersion: "0.1.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-ai
-
-Client and React hooks for AI chat backed by the gateway, including quota reporting
-and a typed error model.
-
-## Use this when
-
-- Adding an AI chat screen or message composer
-- Displaying remaining quota
-- Handling AI request failure, cancellation, or streaming state
-- Localising AI-related user messages
-
-## The app owns more than you expect
-
-This package deliberately does not handle everything. The README has an
-`## App responsibilities` section listing what the consuming app must implement —
-read it before assuming a behaviour is built in.
-
-## Cancellation is required, not optional
-
-`useAiChat` exposes streaming status. An in-flight request MUST be cancelled when the
-screen unmounts, otherwise the response resolves against a dead component. Verify
-teardown on every screen that uses it.
-
-## Public API (v0.2.0)
-
-Runtime:
-
-- `createAiClient(...)` — transport-level client
-- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
-- `useAiQuota(...)` → `UseAiQuotaResult`
-- `AiError`, `isAiError` — narrow before reading `AiErrorCode`
-- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
-
-Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:
-
-| Need | Section |
-|---|---|
-| First integration | `## Install`, `## Setup` |
-| Streaming, retries, timeouts | `## Runtime behavior` |
-| Full export list | `## Public API` |
-| What the app must implement | `## App responsibilities` |
-| Version/peer constraints | `## Compatibility` |
+---
+name: sdk-rn-ai
+description: "AI chat and quota via @chipmobilesdk/rn-ai: createAiClient, useAiChat, useAiQuota, streaming status, AI error codes. Use when adding an AI chat feature, showing quota, or handling AI request failures and cancellation."
+metadata:
+  package: "@chipmobilesdk/rn-ai"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-ai
+
+Client and React hooks for AI chat backed by the gateway, including quota reporting
+and a typed error model.
+
+## Use this when
+
+- Adding an AI chat screen or message composer
+- Displaying remaining quota
+- Handling AI request failure, cancellation, or streaming state
+- Localising AI-related user messages
+
+## The app owns more than you expect
+
+This package deliberately does not handle everything. The README has an
+`## App responsibilities` section listing what the consuming app must implement —
+read it before assuming a behaviour is built in.
+
+## Cancellation is required, not optional
+
+`useAiChat` exposes streaming status. An in-flight request MUST be cancelled when the
+screen unmounts, otherwise the response resolves against a dead component. Verify
+teardown on every screen that uses it.
+
+## Public API
+
+Runtime:
+
+- `createAiClient(...)` — transport-level client
+- `useAiChat(...)` → `UseAiChatResult`, with `AiChatStatus` for state
+- `useAiQuota(...)` → `UseAiQuotaResult`
+- `AiError`, `isAiError` — narrow before reading `AiErrorCode`
+- `aiMessages`, `aiMessage` — user-facing strings keyed by `AiMessageKey`
+
+Use `aiMessage` for anything shown to the user. Never render `AiError.message` directly.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-ai/README.md`:
+
+| Need | Section |
+|---|---|
+| First integration | `## Install`, `## Setup` |
+| Streaming, retries, timeouts | `## Runtime behavior` |
+| Full export list | `## Public API` |
+| What the app must implement | `## App responsibilities` |
+| Version/peer constraints | `## Compatibility` |