@condorinst/mobile-bridge 0.22.0 → 0.23.0

package/README.md

@@ -1,27 +1,24 @@
 # @condorinst/mobile-bridge
 
-Canonical TypeScript SDK for the JS↔Native bridge of the Condor white-label
-mobile app.
+The SDK for the **Home of the Condor Canvas app**: a self-contained web page
+that the app shows inside a sandboxed iframe after login. The page talks to the
+app — device list, live light readings, history, permissions, language — with
+`BridgeClient`, and the package's CLI builds, checks, tests and publishes it.
 
-> **Purpose:** give the JavaScript code that runs inside the white-label app's
-> WebView a typed, runtime-validated, testable API to talk to the native
-> Flutter side — versioned handshake, observation of keys emitted by the
-> background, commands to the foreground service, and hooks into native
-> screens (Settings).
+## Building a Home — person or AI agent
 
-## Reading this with an AI agent?
+Start at **[`AGENTS.md`](AGENTS.md)**: the rules, the boot sequence to copy, the
+browser harness, the validation loop, and which document owns each subject. It
+is written once for both audiences.
 
-Start at **[`AGENTS.md`](AGENTS.md)** — the contract in one screen — then
-`docs/agent-guide.md`. Both ship inside the npm tarball, so after
-`npm install` they are on disk at
-`node_modules/@condorinst/mobile-bridge/`, readable with no network access.
-
-Over the network, every document is plain text at a pinned, unauthenticated
-URL. `llms.txt` is the index:
+Everything ships inside the npm tarball, so after `npm install` it is on disk at
+`node_modules/@condorinst/mobile-bridge/`, readable with no network. Over the
+network, every document is plain text at a pinned, unauthenticated URL;
+`llms.txt` is the index and `llms-full.txt` has every document in one file:
 
 ```
-https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/llms.txt
-https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.22.0/llms-full.txt   # every doc in one file
+https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.23.0/llms.txt
+https://cdn.jsdelivr.net/npm/@condorinst/mobile-bridge@0.23.0/llms-full.txt
 ```
 
 The machine-readable contract — keys, commands, limits, capability matrix — is
@@ -32,315 +29,30 @@ The machine-readable contract — keys, commands, limits, capability matrix —
 > application and returns no readable text. Use the jsDelivr URLs above, or
 > Bitbucket's `raw/` file URLs.
 
-## New here, as a human?
-
-You are almost certainly building the **client bundle** that renders as the
-app's Home. That means `BridgeClient`:
-
-```typescript
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
-// ack.nativeVersion is your capability signal. ack.accepted is always true.
-
-BridgeClient.on(BRIDGE_KEYS.userDevice, (devices) => render(devices));
-const result = await BridgeClient.requestUserDevices(); // resends until the list arrives
-if (result.status === 'timeout') renderEmptyState();
-```
-
-Develop it in the browser with the harness, which runs the bundle under the
-same sandbox and shell as the app:
-
-```bash
-npx condor-mobile-bridge dev -i dist/index.html --scenario cold-start
-```
-
-Then read the [Client Guide](docs/client-guide.md) — _"Build your White Label
-Home"_ — and copy the runnable [`examples/minimal-home`](examples/minimal-home).
-
-The `Bridge` singleton shown under *Quickstart* below is the **legacy,
-shell-side** API. It talks to the native layer directly and is not reachable
-from a sandboxed client bundle. If you are the client, you want `BridgeClient`.
-
 ## Installation
 
 ```bash
-npm install @condorinst/mobile-bridge
-```
-
-The published package ships a prebuilt `dist/` (ESM + CJS + type
-declarations) — **no build toolchain is required on your side**.
-
-> **Versioning during the pilot.** The package is on `0.x` (beta). Pin
-> `"@condorinst/mobile-bridge": "^0.22.0"`. Under semver, while on `0.x` a
-> caret range auto-updates **patches only** (`0.22.x`); moving to `0.23.0` is
-> an intentional opt-in. `1.0.0` is reserved for production.
-
-## Quickstart (legacy, shell-side `Bridge`)
-
-> **Not for client bundles.** This is the API the Condor shell uses to talk to
-> the native layer. A client bundle cannot reach it from the sandbox — use
-> `BridgeClient` (above, and in the next section).
-
-```typescript
-import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-// Versioned handshake with the native side (can be called at any time;
-// recommended on the client's DOMContentLoaded)
-const ack = await Bridge.handshake({ clientVersion: '1.0.0' });
-console.log('Native bridge:', ack.nativeVersion, 'accepted:', ack.accepted);
-
-// Subscribe to an observable key coming from the background
-const unsubscribe = Bridge.on(BRIDGE_KEYS.deviceConnection, (payload) => {
-  console.log('Device:', payload);
-});
-
-// Command: enable real-time for one device
-Bridge.send('realTime', { serialNo: 1234, value: true });
-
-// Native hook: open the app's native Settings screen
-Bridge.openSettings();
-
-// Cleanup
-unsubscribe();
-```
-
-> The recommended model for white-label clients is **`BridgeClient`** (sandbox
-> iframe), not the legacy `Bridge`. See below.
-
-## Sandbox iframe — `BridgeClient` + `BridgeShell`
-
-The recommended model isolates the external client code inside an
-`<iframe sandbox="allow-scripts">`, communicating over `window.postMessage`
-with schema-validated messages and a default-deny policy.
-
-### For the external client — `BridgeClient`
-
-API **identical** to the legacy `Bridge`, but over a postMessage transport.
-The client imports it and never notices it is sandboxed:
-
-```typescript
-import { BridgeClient, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-const ack = await BridgeClient.handshake({ clientVersion: '1.0.0' });
-console.log('Shell:', ack.shellVersion, 'accepted:', ack.accepted);
-
-const unsubscribe = BridgeClient.on(BRIDGE_KEYS.userDevice, (payload) => {
-  console.log('Devices:', payload);
-});
-
-BridgeClient.send('realTime', { serialNo: 1234, value: true });
-BridgeClient.openSettings();
-
-// System back button: report whether you can go back, and react to the OS back.
-BridgeClient.reportNavigation(currentView !== 'home'); // call on every route change
-BridgeClient.onBack(() => goToPreviousPage());          // fired only when you reported true
-```
-
-The `reportNavigation` / `onBack` pair lets your page own the Android back
-button — walking your in-page navigation before the app leaves the Home. Opt-in;
-skip it and the app just stays on Home when back is pressed. See
-[docs/bridge-contract.md](docs/bridge-contract.md).
-
-**Differences vs `Bridge`:**
-- Does not expose `mockEmit`, `installDevPanel`, `isMock`, `getMockState` —
-  dev/mock APIs live only on the shell.
-- `handshake` resolves with `{ shellVersion, nativeVersion, accepted }`. Since
-  0.17.0 the shell relays `nativeVersion` into the iframe — it is the only
-  capability signal you get, and it is `null` when the shell could not reach
-  the native side and against shells older than 0.6.0. `accepted` is always `true`; never branch on it.
-- Commands not allowed by the `ShellPolicy` are silently dropped (with a
-  `console.warn`). The external client has no visibility into which commands
-  do or do not exist.
-
-### For the Condor-controlled shell — `BridgeShell`
-
-```typescript
-import { BridgeShell, BRIDGE_KEYS, type ShellPolicy } from '@condorinst/mobile-bridge';
-
-const iframe = document.getElementById('client-frame') as HTMLIFrameElement;
-
-const policy: ShellPolicy = {
-  readOnlyKeys: [
-    BRIDGE_KEYS.userDevice,
-    BRIDGE_KEYS.deviceConnection,
-    BRIDGE_KEYS.deviceLightSensors,
-    BRIDGE_KEYS.realTime,
-  ],
-  allowedCommands: ['userDevice', 'realTime', 'openSettings'],
-  requiresConfirmation: ['syncTime', 'deleteMemory'],
-  deniedCommands: ['dfu'],
-};
-
-const shell = new BridgeShell({
-  iframe,
-  policy,
-  onConfirmationRequest: async ({ command, args }) => {
-    return await showConfirmationModal(command, args); // shell UI
-  },
-});
-
-// Layer 1 — bootstrap with an override prefix.
-//
-// Use bootstrapClientIframe(clientPath) when HTML comes over HTTP:
-await shell.bootstrapClientIframe('https://api.condor.example/whitelabel/bundle.html');
-//
-// Use bootstrapClientIframeWithHtml(htmlString) when the HTML is already in
-// memory — required for an asset bundled at file:// (Android WebView cannot
-// fetch over file://), a build-time inlined bundle, etc:
-declare const __CLIENT_HTML__: string; // e.g. via esbuild.define
-await shell.bootstrapClientIframeWithHtml(__CLIENT_HTML__);
-
-// Layer 2 — iframe attestation.
-const verify = await shell.verifySandbox();
-if (!verify.ok) {
-  // Abort the boot — Layer 1 failed.
-  throw new Error('Sandbox compromised: bridges still reachable from iframe.');
-}
-
-// From here on, BridgeShell routes postMessage ↔ native Bridge
-// automatically. Nothing else to do at boot.
-```
-
-### Layered defense (propagation of the native channel into the iframe)
-
-| Layer | Where | What it does |
-|---|---|---|
-| **1** | `BridgeShell.bootstrapClientIframe` | `srcdoc` with a prefix that deletes `window.CondorNative`, `window.flutter_inappwebview` and `window.CondorBridge` before any client script runs. Defense in depth only: the WebView injects the channel into every frame, so a child iframe created by the client gets it back (and on iOS `window.webkit.messageHandlers` cannot be locked). |
-| **2** | `BridgeShell.verifySandbox` + `BridgeClient` handler | Round-trip `postMessage` to attest the iframe state (`nativeChannelReachable` since 0.18.0). |
-| **3** | (Native side) | Shell nonce, stamped on every outgoing message via `Bridge.setOutgoingStamp`, validated natively. **This is the guarantee.** |
-| **4** | (Fallback if 1+2 fail) | Dual `InAppWebView` — shell and client in separate WebViews. |
-
-## Dev harness — `condor-mobile-bridge dev`
-
-```bash
-npx condor-mobile-bridge dev -i dist/index.html [--scenario cold-start] [--port 5173]
-```
-
-Serves the bundle (an `index.html`, a `dist/` folder or a `.zip`) at
-`http://localhost:5173` inside a sandboxed iframe, behind the real
-`BridgeShell` with the app's policy and CSP, and a simulated native side. The
-input is re-read on every reload.
-
-Scenarios reproduce device behaviour a naive mock hides: `default`,
-`cold-start` (requests lost while the app's background service starts),
-`no-devices` (`userDevice` never answers), `shared-serial` (two devices, one
-`serialNo`) and `offline`. The page's console (`[condor dev]`) logs what was
-sent, answered and dropped.
-
-With your own dev server, mount the same harness from the **host** page:
-
-```ts
-import { createDevHarness } from '@condorinst/mobile-bridge/dev';
-const html = await (await fetch('/bundle/index.html')).text();
-await createDevHarness({ html, scenario: 'no-devices', mount: document.getElementById('device')! });
-```
-
-Never import `@condorinst/mobile-bridge/dev` into the bundle itself: `validate`
-fails it with `dev-harness-bundled`.
-
-## Publish CLI — `condor-mobile-bridge canvas`
-
-```bash
-npx condor-mobile-bridge canvas publish dist/index.html --version 1.4.0   # validate, confirm, publish
-npx condor-mobile-bridge canvas list
-npx condor-mobile-bridge canvas revoke <bundleId> --fallback-version 1.3.0
-```
-
-Publishes the bundle of your company in the Condor Canvas app, through the same
-endpoints and login as the Condor web admin: company id, user id, password
-(prompted without echo, never stored) and the two-factor code when your company
-uses one. It needs a **manager** user and an interactive terminal. A publish goes
-**live at once** for every user of the company — use a test company first. The
-API is production by default (`--env dev` is for Condor staff; `--base-url`
-overrides). Details: `docs/device-testing.md`.
-
-## Build CLI — `condor-mobile-bridge build`
-
-Generates the **self-contained `.zip` bundle** that the white-label app
-consumes. The app injects the client HTML via `iframe.srcdoc` (origin `null`,
-no base URL) → **relative references do not resolve** and the CSP blocks
-external fetches; therefore the `.zip` must contain **a single `index.html`**
-with inline JS/CSS and media as `data:` URIs.
-
-The CLI does this from your build's `dist/`: it reads `index.html`, **inlines**
-`<script src>` (escaping `</script>`) and `<link rel=stylesheet>`, resolves CSS
-`url()` and local `<img>`/icons to `data:` URIs, and packs a `.zip` with
-`index.html` at the root. External refs (`https://…`) are **preserved** (and
-blocked by the app's CSP at runtime).
-
-```bash
-npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip
-```
-
-| Option | Description |
-|---|---|
-| `-i, --html <path>` | Input HTML (e.g. `dist/index.html`). Required. |
-| `-o, --out <path>` | Output `.zip` (default: `dist/whitelabel-bundle.zip`). |
-| `--max-bytes <n>` | **Warning** threshold in bytes (default: `2097152` = 2 MB). |
-
-Output (for registering the bundle with the backend — `bundleSize`/`bundleHash`):
-
-```
-Built dist/bundle.zip
-  entry: index.html (123.4 KB self-contained)
-  bundleSize (zip): 45678 bytes
-  bundleHash (zip): sha256-<hex>
+npm install @condorinst/mobile-bridge@^0.23.0
 ```
 
-The hash is **deterministic** (fixed mtime on the zip entry) — the same input
-produces the same `bundleHash`. Above the threshold, the CLI **warns** (does
-not block): remember that **the app rejects** a `.zip` larger than 2 MB and
-falls back to the mock.
+The package ships a prebuilt `dist/` (ESM + CJS + type declarations); no build
+toolchain of ours is needed on your side.
 
-> ⚠️ **Constraint: single-chunk build.** The inliner is post-build and assumes
-> a `dist` with **one JS + one CSS + assets**. Builds with **code-splitting /
-> ES modules** that `import` across chunks **break** in `srcdoc` (the imports
-> do not resolve). Configure your build to emit a single file:
-> - **Vite:** `vite-plugin-singlefile` (or `build.rollupOptions.output.inlineDynamicImports: true` + `manualChunks: undefined`).
-> - **CRA:** build without code-splitting (no `React.lazy`/dynamic `import()` in routes), single bundle.
->
-> Inlining inflates `data:` media by ~33% (base64) — size against the 2 MB limit.
+## The CLI
 
-## Key catalog (strictly typed)
-
-Mirrors the JS-facing side of the native foreground com keys. The strings here
-are what the JS receives via `window.CondorBridge.emit(key, payload)`.
-
-| `BRIDGE_KEYS.*` | Wire (JS) | Typed payload | Typical direction |
-|---|---|---|---|
-| `pingPong` | `'pingPong'` | `PingPongPayload = { data: 'ping' \| 'pong' }` | bidirectional |
-| `userDevice` | `'userDevice'` | `UserDevicePayload = { lastUpdate, devicesConfig[], devicesTelemetry[], devicesUserConfig[] }` | BG → JS |
-| `deviceLightSensors` | `'deviceLightSensors'` | `DeviceLightSensorsPayload` — discriminated by `type`: `{ serialNo, type: 'actlumus', data: LightSensorsActlumus1Data }` \| `{ serialNo, type: 'actlumus2', data: LightSensorsActlumus2Data }`. `data` carries the derived spectrum **and** the raw channels (`light_sensor_*`, native ≥ 0.16.0) | BG → JS |
-| `syncTime` | `'syncTime'` | `SyncTimeAckPayload = { serialNo, success }` | JS → BG (cmd) / BG → JS (ack) |
-| `realTime` | `'realTime'` | `RealTimeAckPayload = { serialNo, success, value }` | JS → BG (cmd) / BG → JS (state) |
-| `deleteMemory` | `'deleteMemory'` | `DeleteMemoryAckPayload = { serialNo, success }` | JS → BG (cmd) / BG → JS (ack) |
-| `deviceNotification` | `'deviceNotification'` | `DeviceNotificationPayload = { serialNo, isConnect, message, messageCode, isError }` | BG → JS |
-| `deviceConnection` | `'deviceConnection'` | `DeviceConnectionPayload = { serialNo, isConnect }` | BG → JS (status); JS → BG (`{type, serialNo}`, permissive) |
-| `sensorLog` | `'sensorLog'` | `SensorLogPayload` | BG → JS |
-| `dfu` | `'dfu'` | `Record<string, unknown>` (fallback) | BG → JS |
-| `systemStatus` | `'systemStatus'` | `SystemStatusPayload = { bluetooth, internet, permission, hasDevices, missingOptionalPermissions[], missingEssentialPermissions[], deviceSyncError }` | native → JS (on change + snapshot after handshake) |
-| `navigationBack` | `'navigationBack'` | `NavigationBackPayload = {}` (OS back pressed) | BG → JS (via `BridgeClient.onBack`) |
-| `language` | `'language'` | `LanguagePayload = { deviceLocale, appLanguage, resolvedLanguage }` | native → JS (on change + snapshot after handshake) |
-
-**Automatic inference on `Bridge.on`:**
-
-```typescript
-Bridge.on(BRIDGE_KEYS.realTime, (payload) => {
-  // payload: RealTimeAckPayload — type-safe!
-  console.log(payload.serialNo, payload.success, payload.value);
-});
-```
-
-**`Bridge.send` commands** remain permissive (heterogeneous shapes per type).
-The client passes `Record<string, unknown>`.
+| Command | Does | Documented in |
+| --- | --- | --- |
+| `npx condor-mobile-bridge dev -i dist/index.html` | runs your page in a browser harness that behaves like the app | `docs/device-testing.md` |
+| `npx condor-mobile-bridge build -i dist/index.html -o dist/bundle.zip` | inlines your build into one `index.html` and zips it | `docs/device-testing.md` |
+| `npx condor-mobile-bridge validate -i dist/bundle.zip --strict` | applies the app's gates and lints for blocked APIs | `docs/device-testing.md` |
+| `npx condor-mobile-bridge canvas publish \| list \| revoke` | publishes your bundle to your company (interactive login) | `docs/device-testing.md` |
 
 ## Versioning policy (semver)
 
-- **PATCH** (`0.22.x`): bugfix with no API change.
+- **PATCH** (`0.23.x`): bugfix with no API change.
 - **MINOR** (`0.x.0`): new observable key, new command, backward-compatible API.
   > While on `0.x`, a minor bump may carry breaking changes (semver treats
-  > pre-1.0 minors as breaking). Pin `^0.22.0` to stay on safe patches.
+  > pre-1.0 minors as breaking). Pin `^0.23.0` to stay on safe patches.
 - **MAJOR** (`x.0.0`): incompatible schema change (key rename, payload shape
   change, public API change). `1.0.0` marks the production-stable contract.
 
@@ -349,155 +61,11 @@ declares `clientVersion`. This release does **not** enforce hard semver
 validation — the native side accepts any `clientVersion`. Real validation will
 land once there are 2+ versions in the field.
 
-## Host detection
-
-The package detects automatically:
-
-- **Android / iOS** — `window.CondorNative`, a JavaScript channel registered with
-  `webview_flutter` (`addJavaScriptChannel('CondorNative')`). Messages are sent as a
-  JSON string. Takes precedence when present.
-- **Android / iOS (legacy)** — `window.flutter_inappwebview` (via the `flutter_inappwebview`
-  package). Still supported for the transition; will be removed in a future minor.
-- **Browser outside the app** (dev/test): **mock mode** activates automatically
-  for `Bridge`. A client bundle (`BridgeClient`) runs in the browser only
-  through the `dev` harness.
-
-## Mock mode (shell-side `Bridge`)
-
-> For code that uses the legacy `Bridge` directly — the shell, tests,
-> Storybook. A client bundle uses `BridgeClient`, which has no mock of its own:
-> develop it with `condor-mobile-bridge dev` (above).
-
-When the package runs outside the Flutter WebView (regular browser, Vite dev
-server, Storybook), the adapter activates mock mode automatically. You can
-develop in the browser without building the APK.
-
-```typescript
-import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-if (Bridge.isMock) {
-  // Subscribe to a listener as usual
-  Bridge.on(BRIDGE_KEYS.deviceConnection, (payload) => {
-    console.log('Device:', payload);
-  });
-
-  // Simulate the native side sending an event
-  Bridge.mockEmit(BRIDGE_KEYS.deviceConnection, {
-    serialNo: 1234,
-    connected: true,
-  });
-}
-```
+## Shell side (Condor)
 
-### Handshake in mock is EXPLICIT
-
-```typescript
-// In mock, handshake does NOT resolve by itself — the client/test responds.
-const ackPromise = Bridge.handshake({ clientVersion: '1.0.0' });
-
-if (Bridge.isMock) {
-  Bridge.mockEmit('handshake-ack', {
-    nativeVersion: '0.1.0',
-    accepted: true,
-  });
-}
-
-const ack = await ackPromise;
-```
-
-Design decision: it forces tests to be intentional about the native state. In
-real mode (inside the Flutter WebView), the ack arrives naturally from native.
-
-### `Bridge.send` in mock
-
-Messages sent via `Bridge.send` (or helpers like `openSettings`) are recorded
-in an internal FIFO buffer (cap 100) + `console.debug`. Inspect via
-`Bridge.getMockState()`:
-
-```typescript
-Bridge.send('realTime', { enabled: true });
-
-const state = Bridge.getMockState();
-console.log(state.messages);
-// → [{ handlerName: 'CondorBridge', payload: {...}, timestamp: ... }]
-console.log(state.subscriberKeys);
-// → ['deviceConnection']
-```
-
-## Dev panel (shell-side `Bridge`)
-
-> The `dev` harness installs this panel for you. Call `installDevPanel` yourself
-> only when hosting `Bridge` directly.
-
-An opt-in HTML panel to inspect the bridge in the browser during development.
-
-```typescript
-import { Bridge } from '@condorinst/mobile-bridge';
-
-if (Bridge.isMock) {
-  Bridge.installDevPanel({
-    position: 'bottom-right',   // 'bottom-right' | 'bottom-left' | 'top-*'
-    maxMessages: 20,            // last N shown
-    theme: 'dark',              // 'dark' | 'light'
-    startCollapsed: false,
-  });
-}
-```
-
-Contents:
-
-- Header with a "MOCK" badge, sent counter, minimize button.
-- Sent log — last N messages (timestamp, type, truncated payload).
-- Trigger emit — dropdown of `BRIDGE_KEYS` + JSON textarea + "Emit" button
-  (fires `Bridge.mockEmit`) + "Clear sent" button.
-
-Idempotent — calling `installDevPanel` again replaces the previous panel.
-Throws if called in real mode (`!Bridge.isMock`).
-
-### Auto-respond toggle
-
-To close the full loop in the browser (client clicks a button → native
-responds → subscriber fires), pass a **policy** that maps `send` to `emit`.
-The package provides the **mechanism** (checkbox UI + hook); you provide the
-**policy** (app-specific mappings).
-
-```typescript
-import { Bridge, BRIDGE_KEYS } from '@condorinst/mobile-bridge';
-
-if (Bridge.isMock) {
-  Bridge.installDevPanel({
-    startAutoRespondEnabled: true, // default false
-    autoRespondDelayMs: 50,        // default 50 (simulates IPC)
-    onSendForAutoRespond(msg) {
-      const payload = msg.payload as { type?: string };
-      switch (payload?.type) {
-        case 'handshake':
-          return {
-            key: 'handshake-ack',
-            payload: { nativeVersion: '0.1.0 (mock)', accepted: true },
-          };
-        case 'ping':
-          return {
-            key: BRIDGE_KEYS.pingPong,
-            payload: { data: 'pong' },
-          };
-        default:
-          return null; // do not auto-respond to this send
-      }
-    },
-  });
-}
-```
-
-Behavior:
-
-- The toggle appears in the panel **only when** `onSendForAutoRespond` is
-  passed — without a policy, the panel keeps the manual-emit UX.
-- The toggle state persists in memory for the panel's lifetime. Re-install
-  resets to `startAutoRespondEnabled`.
-- Errors thrown by the policy or the internal `triggerEmit` are caught and
-  logged (`console.error`) — they do not destabilize the bridge.
-- Use `BRIDGE_KEYS` to avoid string-magic in the mappings.
+`BridgeShell`, the legacy `Bridge` singleton, mock mode and the dev panel are
+for Condor's app shell, not for client bundles:
+[`docs/shell-integration.md`](docs/shell-integration.md).
 
 ## Local development (SDK contributors)
 
@@ -510,25 +78,6 @@ npm run test         # vitest run
 npm run build        # tsup (ESM + CJS + types in dist/)
 ```
 
-## Further reading
-
-Every file below ships in the npm tarball, so these relative links resolve
-inside `node_modules/@condorinst/mobile-bridge/` as well as in the repository.
-
-| Document | What it answers |
-| --- | --- |
-| [`AGENTS.md`](./AGENTS.md) | The contract in one screen. Start here if you are, or are using, an AI agent. |
-| [`llms.txt`](./llms.txt) | Index of every document, with absolute pinned URLs. |
-| [Agent guide](./docs/agent-guide.md) | Step-by-step construction of a client Home. |
-| [Bridge contract](./docs/bridge-contract.md) | Every key, command, error shape and capability, by native version. |
-| [`contract/bridge-contract.json`](./contract/bridge-contract.json) | The same, as JSON. |
-| [Limits](./docs/limits.md) | Every hard limit, and what happens when you cross it. |
-| [Troubleshooting](./docs/troubleshooting.md) | Why a command did nothing. |
-| [Client guide](./docs/client-guide.md) | Narrative walkthrough — build your White Label Home. |
-| [Pilot onboarding](./docs/pilot-onboarding.md) | Checklist: zero to a delivered bundle. |
-| [`examples/minimal-home`](./examples/minimal-home) | A runnable client in ~160 lines. |
-| [CHANGELOG](./CHANGELOG.md) | When each capability landed — the precise record for version checks. |
-
 ## License
 
 Proprietary — Condor Instruments. See [LICENSE](./LICENSE).