appduct 0.14.0 → 0.15.1

package/README.md

@@ -1,202 +1,68 @@
-[![Appduct][appduct-banner]][repo]
+<a href="https://callstackincubator.github.io/appduct/"><img src="https://raw.githubusercontent.com/callstackincubator/appduct/main/.github/assets/readme-banner.png" alt="Appduct by Callstack. Your app is an MCP server now: your agent calls its functions over MCP, on iOS, Android, React Native, Flutter and web." width="100%" /></a>
 
-### Drive app tools without shipping debug UI
+# Appduct CLI, MCP server and test client
 
-[![MIT license][license-badge]][license] [![npm downloads][npm-downloads-badge]][npm-downloads] [![PRs Welcome][prs-welcome-badge]][prs-welcome]
+Call tools inside a running iOS, Android, React Native, Flutter or Web app from your terminal, an AI agent or a test suite. The `appduct` package connects to apps that have an Appduct SDK installed and tools registered.
 
-The `appduct` package is the operator/agent side of Appduct: a CLI and an MCP server, backed by a long-lived background daemon that holds your device sessions. You use it to list and call the tools a connected app has registered — from a terminal, from an agent, or from a test suite — instead of driving the app through a hidden debug menu.
+## Requirements
 
-## Why use this package
-
-- **One daemon, many devices.** It auto-spawns on first use, serves every device on one `wss://` port, and survives Metro reloads, backgrounding, and network flaps by suspending and resuming sessions instead of dying with them.
-- **Same surface for humans and agents.** The CLI (`sessions`, `tools`, `events`, ...) and `appduct mcp` use the same RPC methods, so an agent sees the tools a human operator does.
-- **Hardened control plane.** The CLI and MCP server never touch sockets, keys, or state files directly — everything goes through a Unix-domain-socket RPC surface gated by filesystem permissions (see [`docs/SECURITY.md`][security]).
-- **Fits production-minded apps.** The app only exposes what you register; trust boundaries are pins and TLS, and production deployments can gate tools with policy and audit every call.
+- Node 20 or newer.
+- An Appduct-enabled app. Choose an [SDK setup guide](https://callstackincubator.github.io/appduct/start/introduction/#packages), or [try a playground](https://callstackincubator.github.io/appduct/start/playground/).
+- For automatic device delivery: Xcode for an iOS Simulator, or `adb` for Android. Physical devices can use a QR code; Web pages use their URL.
 
 ## Getting started
 
+Install the CLI:
+
 ```bash
 npm install -g appduct
-appduct sessions link --scheme myapp --qr
 ```
 
-`sessions link` needs your app's deep-link scheme: pass `--scheme` (the app's `expo.scheme`, or its bare-RN equivalent), or set `"scheme"` once in `~/.appduct/config.json` and omit the flag. Without either, the command exits with a usage error.
-
-Scan the QR (or open the deep link) in an Appduct-enabled app, then:
+With your app running, connect from its project directory:
 
 ```bash
-appduct tools ls
-appduct tools call sum --input '{"a":2,"b":3}'
-```
-
-That's the whole loop. There is no host process to start — `appduct` auto-spawns its daemon the first time any command needs it.
-
-## Commands
-
-Every command is `appduct <noun> <verb> [selector] [args]`, the same shape as `appduct daemon run|start|stop|status`:
-
-| Command | Role |
-| --- | --- |
-| `appduct init [--scheme <s>] [--ios-app-id <id>] [--android-app-id <id>] [--force]` | set up an app directory: write `.appduct/config.json`, print the MCP snippet |
-| `appduct keygen [--out <path>] [--force]` | generate a daemon private key, print its app pin |
-| `appduct sessions ls` | list sessions: alias, state, device, tool count |
-| `appduct sessions link [--ttl <s>] [--qr] [--open android\|ios-sim\|ios-device] [--device <id>] [--app-id <id>] [--scheme <s>]` | mint a pending session and print its deep link |
-| `appduct sessions revoke [selector]` | revoke a session |
-| `appduct tools ls [selector] [--full] [--group <name>] [--filter <text>] [--limit <n>] [--offset <n>]` | list a session's tools (one call signature + description per line) |
-| `appduct tools ls [selector] --groups` | list a session's tool groups with their tool counts |
-| `appduct tools describe [selector] <name>` | show one tool's full schema |
-| `appduct tools call [selector] <name> --input '<json>' [--timeout <ms>]` | call a tool |
-| `appduct events ls [selector] [--name <glob>] [--limit <n>] [--offset <n>]` | list the events the app declares, one signature line each; an exact `--name` prints the full payload schema; `--limit`/`--offset` page a long list, ending with a `Showing n of total events (offset o).` line when events were left out; `--json` carries the full descriptors, with `total` counting matches before paging |
-| `appduct events tail [selector] [--follow]` | stream the events the app posts with `postEvent`; `--json` emits NDJSON |
-| `appduct events since [selector] <cursor>` | one-shot pull the events retained since `<cursor>`; `--json` emits NDJSON |
-| `appduct daemon run\|start\|stop\|status` | daemon lifecycle |
-| `appduct mcp [--scheme <s>]` | start a stdio MCP server proxying connected apps' tools to MCP clients |
-| `appduct doctor <artifact> [--assert-present\|--assert-absent]` | release-gate step: report or assert whether a built `.app`/`.ipa`/`.apk`/`.aab` contains Appduct |
-
-Every command that targets a session accepts an optional `selector` (a session id or an alias from `appduct sessions ls`); omit it when exactly one session is active. Global flags: `--json` (machine-readable output; compact by default, one line), `--pretty` (indent `--json` output, and JSON values embedded in human output, 2 spaces — never NDJSON event lines), `--verbose` (include the `meta` block — `command`, `timestamp`, `duration_ms` — omitted by default in both human and `--json` output), `--no-color`, `--state-dir <path>` (default `~/.appduct`), `--daemon-restart` (on a daemon/CLI version mismatch, restart the daemon even though that drops live sessions and unclaimed links — `APPDUCT_DAEMON_RESTART=1` and `config.json`'s `restartDaemonOnVersionMismatch` do the same for every command, and `--no-daemon-restart` overrules both for one). Run `appduct <noun> --help` for the exact flags any of its verbs takes.
-
-`--timeout` on `tools call` is clamped to 1,000–600,000 ms and can only **shorten** the deadline, never extend it past the app's own timer: the app aborts the handler at the tool's declared `timeoutMs`, or 10 seconds for a tool that declares none, regardless of what the caller asks for. If a tool needs more room, declare `timeoutMs` on its registration.
-
-### `appduct tools ls`: a signature per tool
-
-`appduct tools ls` prints one call signature plus a one-line description per tool, not the full schema — cheap to read even against an app that registers hundreds of tools:
-
-```
-Tools
-  seed_cart(items: int, sku?: string, clear?: bool = true) -> { added: int, cartId: string }
-    Fill the cart with test items for the current user.
-  set_flag(name: "dark_mode" | "new_checkout", enabled: bool)  [prompt]
-    Toggle a feature flag.
-
-Run `appduct tools describe <name>` for a tool's full schema.
+appduct sessions link --qr
 ```
 
-A signature is derived straight from the tool's JSON Schema: required params are `name: type`, optional ones `name?: type` (with `= <default>` when the schema declares a short one), and `-> type` is the result when the tool declares an `output_schema`. `...` anywhere means the schema shape wasn't one this renderer could summarize — the tool's full schema (`appduct tools describe <name>`) still has it. A `[prompt]`/`[deny]` tag follows a tool whose effective policy isn't `"allow"`.
+Scan the QR code with the device's camera. The app needs a URL scheme, which the CLI can discover from static project files; use `--scheme myapp` if needed. A physical device must be on the same local network as your computer.
 
-Use `--filter <text>` to narrow the listing to tools whose name or description contains `<text>` (case-insensitive), and `--limit <n>`/`--offset <n>` to page through it; a truncated listing prints a trailing `Showing n of total tools (offset o). Narrow with --filter <text> or page with --offset <n>.` line so you know more were left out. `appduct tools ls --json` returns `{ tools, total, groups }` — `total` is the count after `--group`/`--filter` but before `--limit`/`--offset`. `appduct tools describe <name>` (a single tool) is unaffected by any of this and always returns the bare tool descriptor; passing `--group`, `--groups`, `--filter`, `--limit` or `--offset` with `describe` is a usage error.
+For a simulator, Android device or Web page, choose one of these paths instead:
 
-### Tool groups
-
-When the app puts its tools in groups ([`docs/TOOLS.md`](../../docs/TOOLS.md#group-tools-in-a-large-app)), `appduct tools ls` lists them under group headings, with subgroups indented under their parent and ungrouped tools last:
-
-```
-Tools
-  cart
-    add_item(sku: string, quantity: number)
-      Add a product to the cart
-  checkout
-    begin_checkout()
-      Start checkout with the current cart
-    checkout/payment
-      pay_with_card(card: string)
-        Pay for the order with a test card
-  (ungrouped)
-    reset_app()
-      Clear all local data
-```
-
-On a large app, start with `--groups` to see what there is, then list one group:
-
-```
-$ appduct tools ls --groups
-Groups
-  cart                12
-  checkout             8
-    checkout/payment   3
-  (ungrouped)          2
-
-22 tools in total. Run `appduct tools ls --group <name>` to list one group's tools.
-
-$ appduct tools ls --group checkout
+```bash
+appduct sessions link --open ios-sim
+appduct sessions link --open android --app-id com.example.shop
+appduct sessions link --open web http://localhost:5173/
 ```
 
-`--group checkout` lists `checkout` and all of its subgroups; `--group checkout/payment` lists only that subgroup. Matching is by whole name and case-sensitive, so `--group checkout` never matches a `checkoutx` group. `--group` combines with `--filter`, `--limit` and `--offset`. When a listing without `--group` is cut short, the footer names the top-level groups to narrow to: `Showing 5 of 22 tools (offset 0). Narrow with --group <name> (groups: cart 12, checkout 8) or --filter <text>, or page with --offset <n>.` A group that is not one or two `/`-separated names of letters, digits, `_` and `-` (for example `checkout/` or `a/b/c`) is a usage error. With `--json`, each tool carries its `group` — `null` for an ungrouped tool, exactly the value `groups` uses for its own ungrouped row — and `groups` lists every group with its count, whatever `--group` or `--filter` you passed.
-
-### The deep-link scheme
-
-`appduct sessions link`, `appduct mcp`, and the MCP `appduct_connect` tool all resolve the scheme the same way, first match wins:
-
-1. `--scheme <s>`
-2. the `APPDUCT_SCHEME` environment variable
-3. the nearest `.appduct/config.json` that declares a `scheme`, walking up from the working directory (a file without that key doesn't stop the walk; the walk skips `~/.appduct` and the active state dir, so global config is never mistaken for a project's)
-4. `scheme` in `<state-dir>/config.json`
-5. a static-file project probe, tried in this order (no walk-up — an app root is where you run these commands):
-   1. `<cwd>/app.json`'s `expo.scheme` — a string, or the first entry of an array
-   2. **Android**: `app/build.gradle.kts` or `app/build.gradle`'s `appductScheme` manifest placeholder (`manifestPlaceholders["appductScheme"] = "myapp"` or `manifestPlaceholders.appductScheme = "myapp"`), then `app/src/main/AndroidManifest.xml`'s first `<data android:scheme>` inside an intent filter that also declares `android.intent.action.VIEW`
-   3. **iOS**: any `Info.plist` up to two levels below the app root (excluding `Pods`, `build`, `node_modules`, `DerivedData`) for the first `CFBundleURLSchemes` entry, then xcodegen's `project.yml` for the same key under `info.properties.CFBundleURLTypes`
-6. otherwise an error naming every location above
-
-In an Expo app root, none of this needs configuring; a plain Xcode or Gradle app root doesn't either, once its `Info.plist`/`AndroidManifest.xml`/`build.gradle` already declares deep links. These probes never execute `app.config.js`/`app.config.ts`, `xcodebuild`, `plutil`, or a Gradle evaluation — each is a plain, defensively-parsed read of a static project file. If your project uses dynamic config, or the probes can't make sense of your setup, use `--scheme`, `APPDUCT_SCHEME`, or `appduct init --scheme <s>` instead.
-
-**Disagreement is never guessed away.** If more than one native probe resolves to a different scheme (say, an `android/` and an `ios/` tree in the same repo declaring different values), resolution fails with a usage error naming every conflicting source instead of picking one.
-
-`appduct init`, run in an app root, writes `.appduct/config.json` (mode `0600`, in a `0700` directory) with the discovered scheme and prints the MCP server entry to paste, plus the `import "@appduct/react-native/auto"` reminder. It never generates keys or touches daemon state.
-
-`init` only looks at `--scheme` and the static-file discovery in step 5 above (`app.json`, then the native probes), plus whatever the file already records — it deliberately ignores `APPDUCT_SCHEME` and does not walk up to a parent `.appduct/config.json`, since baking either into a committed file would be wrong (a shell variable that happened to be exported, or a parent project's scheme silently copied into a sub-package). `--json`'s `source` field reports which input won: `"--scheme"`, `"app.json"`, one of the four native-probe names (`"android-gradle"`, `"android-manifest"`, `"ios-info-plist"`, `"ios-project-yml"`), or `"already-recorded"`.
-
-It's idempotent and safe to re-run:
-
-- A plain re-run keeps whatever scheme is already recorded. If discovery has since found a different value, the result carries a `note` rather than failing.
-- `--scheme <different>` needs `--force` to replace a recorded scheme; `--force` on its own re-adopts `app.json`'s value.
-- `--force` merges into the existing JSON rather than truncating it.
-
-`--ios-app-id <id>` and `--android-app-id <id>` write `appId.ios` and `appId.android` into the same file — the installed app ids that `--open android`, `--open ios-device` and `appduct_connect` need (see [Delivering the link to a device](#delivering-the-link-to-a-device)). They're two flags rather than one because the platforms' ids don't always match, and `init` never guesses one from the other. Like `--scheme`, replacing an id that's already recorded needs `--force`.
-
-A project `.appduct/config.json` holds client-side settings only — it can never redirect the state directory, key, or policy (`--state-dir` / `APPDUCT_STATE_DIR` do that). **Do not point `--state-dir` at a project `.appduct/` directory you commit** — the state dir is where the daemon keeps `key.pem` and its audit log, and a committed one would publish a private key. The two directories share a name and nothing else.
-
-`appduct mcp` is the one exception to step 6: it starts even with no scheme, because it's still useful for proxying tools to a session paired another way. Only `appduct_connect` fails, and its error names every location tried.
-
-### Delivering the link to a device
-
-`--open` hands the freshly minted deep link straight to a device, so nothing has to scan a QR code:
-
-| `--open` | Mechanism | Address in the link |
-| --- | --- | --- |
-| `android` | `adb reverse tcp:<port> tcp:<port>`, then `adb shell am start -a android.intent.action.VIEW -d '<link>' -p <app-id>` | `127.0.0.1` (the port is forwarded onto the device) |
-| `ios-sim` | `xcrun simctl openurl <udid> <link>` | `127.0.0.1` (the simulator shares the host's network) |
-| `ios-device` **(experimental)** | `xcrun devicectl device process launch --device <udid> [--terminate-existing] --payload-url <link> <app-id>` | the machine's detected LAN address — there's no `adb reverse` equivalent on iOS |
-
-With no `--device`, every target requires exactly one device and errors naming each candidate rather than picking one arbitrarily: `android` counts attached devices (`ANDROID_SERIAL` disambiguates), `ios-sim` counts booted simulators, and `ios-device` counts connected iOS devices only — `devicectl` lists every device the Mac has ever paired, so disconnected phones and non-iOS ones are filtered out first.
-
-**`android` and `ios-device` need the installed app's id** — the Android package name or the iOS bundle id. Pass `--app-id <id>` (`appId` over MCP), or record it once in `.appduct/config.json` with `appduct init --android-app-id <id> --ios-app-id <id>`. Without one the command fails before minting anything. Naming the app is what keeps Android from showing an "Open with" chooser when more than one installed app declares your scheme — `adb` would report success, and the session would never be claimed. `ios-sim` needs no app id (`simctl openurl` has no equivalent), and passing one with it is an error. The id may contain only letters, digits, `.`, `_` and `-`, and must start with a letter or digit.
-
-#### `--open ios-device` (experimental)
-
-This is the only automated path for a wired iPhone or iPad — otherwise you're scanning a QR code by hand. It relies on `xcrun devicectl`'s undocumented `--payload-url` flag, which can't be verified in CI, so treat a failure here as a reason to fall back to the QR flow rather than as a bug in your app.
-
-It needs all of:
-
-- **iOS 17 or newer** on the device, and **Xcode 15 or newer** on the host (`devicectl` doesn't exist before that). For iOS 16 and below, use the QR/deep-link flow instead.
-- The device **paired and trusted** by this Mac, with **Developer Mode** enabled on it (Settings → Privacy & Security → Developer Mode).
-- A **development-signed build of your app already installed** — `devicectl` launches an installed app, it doesn't install one.
-- The phone and this machine **on the same network**, reachable at the address the link advertises. `appduct sessions link` prints it on its `Endpoint` line (`--json`: `endpoint.address`); `advertisedIp` in `config.json` overrides detection. If no routable address is found, detection falls back to `127.0.0.1` — which a phone can't reach — so `ios-device` refuses to deliver such a link and tells you to set `advertisedIp`.
-- The app's **bundle id** — see [Delivering the link to a device](#delivering-the-link-to-a-device) for how to supply it.
+The Web command prints a URL to open. Once connected, list tools and call one your app registered:
 
 ```bash
-appduct sessions link --scheme myapp --open ios-device --app-id com.example.myapp
+appduct tools ls
+appduct tools call seed_cart --input '{"items":3}'
 ```
 
-Two things worth knowing before you rely on this:
+The SDK quick starts register this example tool, which returns `{"added":3}`. Appduct starts its background service automatically.
 
-- **What happens when the app is already running hasn't been verified on hardware.** If delivery to an already-running app does nothing, pass **`--relaunch`** (`relaunch: true` over MCP) — it kills the running instance first. Appduct copes with the restart either way; a delivered link supersedes a held session.
-- **A physical iPhone is never auto-detected.** `appduct_connect` called without a `target` only considers booted simulators and attached Android devices, and `appduct sessions link` without `--open` doesn't look for a device at all — a paired iPhone is often someone's personal phone, so it has to be asked for explicitly.
+## Common commands
 
-## MCP setup (Claude Code, Cursor, and similar)
+| Command | What you can do |
+| --- | --- |
+| `appduct init` | Record your project's scheme and app ids, and print MCP configuration. |
+| `appduct sessions ls` | Find connected sessions and their aliases. |
+| `appduct tools ls` | Find registered tools; use `--groups` or `--group cart` for larger registries. |
+| `appduct tools describe seed_cart` | Read a tool's full schema. |
+| `appduct tools call seed_cart --input '{"items":3}'` | Call a tool. |
+| `appduct events ls` | Find the events the app declares. |
+| `appduct events tail --follow` | Watch events the app posts. |
+| `appduct sessions revoke` | Disconnect a session. |
+| `appduct daemon status` | Inspect the background service. |
+| `appduct doctor build/Shop.ipa --assert-absent` | Check that a built app excludes Appduct. |
 
-Add `appduct mcp` to the agent's MCP server config — no separate server process to manage, it auto-spawns the daemon the same way the CLI does:
+Run `appduct <command> --help` for flags, or read the [CLI reference](https://callstackincubator.github.io/appduct/reference/cli/). Use `--json` for scripts.
 
-```json
-{
-  "mcpServers": {
-    "appduct": {
-      "command": "appduct",
-      "args": ["mcp"]
-    }
-  }
-}
-```
+## Connect an agent
 
-An MCP server is usually launched with a working directory you don't control, so `app.json` discovery may not apply. On a machine with more than one app, make the entry self-contained by naming the scheme in it — which is exactly what `appduct init` prints:
+Add this entry to your agent's MCP configuration, replacing `myapp` with your app's scheme:
 
 ```json
 {
@@ -209,123 +75,44 @@ An MCP server is usually launched with a working directory you don't control, so
 }
 ```
 
-Once configured, an agent reaches the connected app's tools through three built-in tools that work like the CLI:
-
-| Tool | Does what | CLI equivalent |
-| --- | --- | --- |
-| `appduct_list_tools` | Lists the app's tools as one-line signatures, with each tool's group and policy, plus the app's groups with counts. Returns 50 at a time unless given `limit`; takes `group`, `filter` and `offset`. | `appduct tools ls` |
-| `appduct_describe_tool` | Shows one tool's full input and output schema. | `appduct tools describe <name>` |
-| `appduct_call_tool` | Calls a tool by `name` with `args`, with progress and errors preserved. | `appduct tools call` |
+The agent can connect a device, list your app's tools, inspect their schemas and call them. App tools are reached through `appduct_list_tools`, `appduct_describe_tool` and `appduct_call_tool`; event and connection tools are available too. See [Use Appduct with an agent](https://callstackincubator.github.io/appduct/guides/agents/) for client setup and approval policy.
 
-The app's tools don't show up as MCP tools of their own. An app with hundreds of tools still adds only these three to the agent's tool list, and that list doesn't change when tools register or a device connects. With more than one device connected, each of the three needs `selector`: the session alias or id from `appduct sessions ls`.
+## Call tools from tests
 
-Your MCP client asks permission for `appduct_call_tool` as a single tool, so choosing "always allow" there approves every tool the app registers, destructive ones included. To keep a person approving those calls, set `policy.destructive` to `"prompt"` in the state directory's `config.json`. Each call to a tool marked `destructiveHint` then shows an approval prompt in clients that support it, and is denied in clients that don't. A destructive tool without that annotation falls under `policy.default` instead.
+<a id="test-runners-appductclient"></a>
 
-Set this before you connect: the daemon reads `config.json` only when it starts, so changing it later takes `appduct daemon stop`. That disconnects every device, which then has to link again, and leaves a running `appduct mcp` without a daemon, so restart the MCP server in your client as well.
-
-Five more built-in tools cover what the app's own tools can't. `appduct_connect` mints a link and, by default, delivers it to whichever `android`/`ios-sim` device it detects — pass `target`/`device` to choose, or `target: "none"` to force the human flow — falling back to a QR code, plus instructions to show it, only when there's nothing to deliver to. Delivering to `android` (chosen or detected) needs `appId`, resolved the same way as `--app-id` (see [Delivering the link to a device](#delivering-the-link-to-a-device)); passing it with `target: "ios-sim"` or `"none"` is an error. `appduct_wait_for_session` then waits for that session to be claimed. `target: "ios-device"` reaches a paired physical iPhone or iPad, with `appId` and the [prerequisites above](#--open-ios-device-experimental) — it's experimental and never auto-detected, so an agent has to ask for it by name.
-
-The other three give an agent a pull surface over `postEvent()`-pushed app events. `appduct_list_events` lists the events the app declared (`appduct events ls`) as signatures with descriptions, plus the payload schema when `name` is an exact name, so an agent learns the names before it waits on one. `appduct_events` drains everything retained since a cursor, and `appduct_wait_for_event` blocks for the next event whose name matches `name`, a whole-name glob (`*` waits for any name) — checking what's already retained before waiting live — rejecting with `tool_timeout` if none arrives in time.
-
-## Test runners: `appduct/client`
-
-A thin typed wrapper over the same daemon RPC the CLI and MCP server use — for a Jest/Vitest/Detox spec that drives a running app without spawning `appduct tools call ... --json` and parsing stdout:
+Install `appduct` as a dev dependency of your test project. With the app connected:
 
 ```ts
 import { connect } from "appduct/client";
 
-// auto-spawns the daemon and picks the single session, or pass { selector: "pixel-8" } to target one explicitly
 const app = await connect();
-
-await app.tools();                                  // ListedToolDescriptor[]; an ungrouped tool's group is null
-const { total } = await app.call("sum", { a: 2, b: 3 });
-const { payload } = await app.waitForEvent("checkout_done", { timeoutMs: 5_000 });
-app.close();
-```
-
-Errors surface as an `AppductError` whose `type` preserves the daemon's wire error type verbatim, so a test can assert on it directly instead of string-matching stderr:
-
-```ts
-await expect(app.call("checkout", {})).rejects.toMatchObject({ type: "policy_denied" });
-```
-
-Pair a simulator/emulator in a `globalSetup` without shelling out, via `link`/`waitForSession`:
-
-```ts
-import { link, waitForSession } from "appduct/client";
-
-const { sessionId } = await link({ target: "ios-sim" });
-const app = await waitForSession(sessionId, { timeoutMs: 60_000 });
-```
-
-`app.call`'s tool name and args/result types can't be inferred automatically — tools are registered by the connected app at runtime — so declare your own tool map once for typed calls throughout a suite:
-
-```ts
-type Tools = {
-  sum: { args: { a: number; b: number }; result: { total: number } };
-};
-
-const app = await connect<Tools>();
-const { total } = await app.call("sum", { a: 2, b: 3 }); // typed
-```
-
-`waitForEvent`'s first argument is a whole-name glob (`*` waits for any name, `"cart.*"` for any name starting with `cart.`). It first drains the daemon's per-session retained buffer for an already-arrived match before falling back to a live wait, so it's safe to call after the action that emits the event. Pass `since` (the `cursor` from a previous `app.events()`/`waitForEvent()` call) to skip events already handled, and `payloadMaxBytes` to cap the resolved event's payload the same way `app.events()` does — without it the payload always comes back whole:
-
-```ts
-const { events, cursor } = await app.events();               // pull: what already happened
-const next = await app.waitForEvent("checkout_done", { since: cursor });
-const capped = await app.waitForEvent("checkout_done", { payloadMaxBytes: 1024 }); // check `truncated` before reading `payload`
-```
-
-For everything else, the package exports `runCli` and the command handlers from [`src/index.ts`](https://github.com/callstackincubator/appduct/blob/main/packages/appduct/src/index.ts), so you can embed the same behavior in Node or Bun scripts without shelling out.
-
-## Keys and pins
-
-You can skip this entirely while your app has no `cliPins` configured — the zero-config default, in any build type. The daemon auto-generates its own `key.pem` the first time it starts if one isn't already there (mode `0600`) and prints its `sha256/...` fingerprint on that first run; `appduct sessions link` carries that fingerprint on the deep link for the app to pick up. See [`docs/SECURITY.md`][security]'s "Trust modes" for what that does and doesn't protect.
-
-For a build that should trust only a key you embedded ahead of time, generate one explicitly:
-
-```bash
-appduct keygen
+try {
+  const result = await app.call("seed_cart", { items: 3 });
+  // result: { added: 3 }
+} finally {
+  app.close();
+}
 ```
 
-This writes an unencrypted PEM private key (PKCS#8) to `<state-dir>/key.pem` by default (override with `--out`; add `--force` to overwrite) and prints the exact `sha256/...` SPKI fingerprint your app should place into `cliPins`. It runs non-interactively, so it's safe to call from CI or a setup script.
-
-`appduct sessions link`'s deep link is `<scheme>:///?appduct=<payload>&pin=<sha256/...>`. The `appduct` param is the binary v2 bootstrap payload (address, session id, token, expiry); `pin` is a separate, out-of-band query param carrying the daemon's current SPKI fingerprint for apps that want to pick it up. An app build with embedded `cliPins` ignores `pin` outright — embedded pins always win, in every build type. A build with no embedded pins trusts it for that one session.
-
-## Daemon lifecycle
-
-The daemon auto-starts the first time any CLI or MCP command needs it — you don't normally run `appduct daemon start` yourself. It writes state to `<state-dir>/` (`daemon.sock`, `daemon.pid`, `daemon.log`, `daemon.log.1`, `events.log`, `events.log.1`, `key.pem`, `config.json`, `audit/`), holds a single-instance lock via the pidfile, and runs independently of any one device's connection, so a reload or crash on the device side never costs you the daemon process.
-
-Use `appduct daemon status` to see what's running (version, pid, `wssPort`, pinned keys, live sessions, effective policy, and the audit log's retention window, file count, size, and failure counters) and `appduct daemon stop` to shut it down explicitly.
-
-Because the daemon outlives the CLI that started it, upgrading Appduct would otherwise leave the old daemon serving your commands. Every CLI/MCP process compares its version with the daemon's on its first command and replaces a stale daemon when nothing would be lost; when there is something at stake — connected sessions, or an unexpired link nobody has scanned yet — the command stops instead, naming both versions, until you run `appduct daemon stop` or pass `--daemon-restart`. A daemon newer than your CLI is left alone with a warning, so a project-local install never downgrades a global one's daemon.
-
-No log grows without bound: `audit/<YYYY-MM-DD>.jsonl` files older than `auditRetentionDays` (default 30) are pruned at daemon start and once a day after, a `daemon.log` over `daemonLogMaxBytes` (default 10 MiB) is rotated to `daemon.log.1` when a daemon is next spawned, and `events.log` is rotated to `events.log.1` as soon as it passes `eventsLogMaxBytes` (default 10 MiB). `events.log` records the daemon's own events (links, sessions, tool registries and tool calls), one JSON line each, for debugging Appduct itself; your app's events are never written to it. All three are `config.json` keys — see [`ARCHITECTURE.md` §3][architecture].
-
-## Release gate: `appduct doctor`
-
-Appduct's inclusion in a build is controlled entirely by autolinking exclusion (see [`docs/BUILD-VARIANTS.md`][build-variants]) — there's no runtime `debuggable` check to catch a pipeline that forgot to exclude the package. `doctor` checks the built artifact itself, not the config you think produced it:
-
-```bash
-appduct doctor ./build/MyApp.ipa --assert-absent
-appduct doctor ./build/app-release.apk --assert-absent
-```
+The client also pairs devices, waits for sessions, reads events and supports a typed tool map. Failures reject with an `AppductError` whose `type` names the error. See [Test setup](https://callstackincubator.github.io/appduct/guides/cli/#drive-the-app-from-a-test-suite) and the [client reference](https://callstackincubator.github.io/appduct/reference/cli/#appductclient).
 
-Exit codes, what it inspects per platform, and the marker-only detection rules on both platforms are documented in `appduct doctor --help`; CI wiring lives in `.github/workflows/test.yaml`.
+<a id="the-deep-link-scheme"></a>
 
-## Related packages
+## Things to know
 
-- **[@appduct/react-native](https://github.com/callstackincubator/appduct/blob/main/packages/react-native/README.md)** — native app client + Expo plugin.
-- **[@appduct/shared](https://github.com/callstackincubator/appduct/blob/main/packages/shared/README.md)** — wire protocol v2 types used by this package and the React Native client.
+- **Select a session when several are connected.** Pass an alias or session id from `appduct sessions ls`; the CLI won't guess.
+- **Declare longer timeouts in the app.** `tools call --timeout` can shorten a deadline, but it can't extend the app's timer. See [Long-running tools](https://callstackincubator.github.io/appduct/guides/writing-tools/#long-running-tools).
+- **Keep project settings and private state separate.** `appduct init` writes project settings to `.appduct/config.json`. The daemon keeps its key and logs in `~/.appduct`; don't commit that directory.
+- **Pin builds you distribute.** `appduct keygen` prints a pin to embed in the app. See [Security](https://callstackincubator.github.io/appduct/guides/security/) for trust, policy and key rotation.
+- **Reconnect after stopping the daemon.** `appduct daemon stop` disconnects apps. Config changes require a restart; see [Service configuration](https://callstackincubator.github.io/appduct/reference/cli/#background-service-state-dirconfigjson).
 
-## Documentation
+## Learn more
 
-- [Architecture][architecture]
-- [Wire protocol][protocol]
-- [Security model & key rotation][security]
-- [Build variants][build-variants]
-- [Monorepo README](https://github.com/callstackincubator/appduct/blob/main/README.md)
+- [CLI guide](https://callstackincubator.github.io/appduct/guides/cli/): devices, events and scripting
+- [CLI reference](https://callstackincubator.github.io/appduct/reference/cli/): commands, configuration, MCP tools and client API
+- SDKs: [iOS](https://callstackincubator.github.io/appduct/install/ios/), [Android](https://callstackincubator.github.io/appduct/install/android/), [React Native](https://callstackincubator.github.io/appduct/install/react-native/), [Flutter](https://callstackincubator.github.io/appduct/install/flutter/), [Web](https://callstackincubator.github.io/appduct/install/web/)
+- [Build variants](https://callstackincubator.github.io/appduct/guides/build-variants/): inclusion and artifact checks
 
 ## Made with ❤️ at Callstack
 
@@ -333,18 +120,4 @@ Exit codes, what it inspects per platform, and the marker-only detection rules o
 
 Like the project? ⚛️ [Join the team](https://callstack.com/careers/?utm_campaign=Senior_RN&utm_source=github&utm_medium=readme) who does amazing stuff for clients and drives React Native Open Source! 🔥
 
-[appduct-banner]: https://img.shields.io/badge/Appduct-callstack%2Fincubator-111827?style=for-the-badge&logo=github&logoColor=white
-[repo]: https://github.com/callstackincubator/appduct
 [callstack-readme-with-love]: https://callstack.com/?utm_source=github.com&utm_medium=referral&utm_campaign=appduct&utm_term=readme-with-love
-[architecture]: https://github.com/callstackincubator/appduct/blob/main/docs/ARCHITECTURE.md
-[protocol]: https://github.com/callstackincubator/appduct/blob/main/docs/PROTOCOL.md
-[security]: https://github.com/callstackincubator/appduct/blob/main/docs/SECURITY.md
-[build-variants]: https://github.com/callstackincubator/appduct/blob/main/docs/BUILD-VARIANTS.md
-[license-badge]: https://img.shields.io/npm/l/appduct?style=for-the-badge
-[license]: https://github.com/callstackincubator/appduct/blob/main/LICENSE
-[npm-downloads-badge]: https://img.shields.io/npm/dm/appduct?style=for-the-badge
-[npm-downloads]: https://www.npmjs.com/package/appduct
-[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
-[prs-welcome]: https://github.com/callstackincubator/appduct/pulls
-[chat-badge]: https://img.shields.io/discord/426714625279524876.svg?style=for-the-badge
-[chat]: https://discord.gg/xgGt7KAjxv

package/dist/artifact-inspect.d.ts

@@ -1,8 +1,8 @@
 /**
- * `appduct doctor` (docs/tasks/08-appduct-doctor.md): the artifact-level replacement for the
- * runtime `debuggable`/`#if DEBUG` gate removed elsewhere in opt-in hardening. Given a built
- * `.app`/`.ipa`/`.apk`/`.aab`, decide whether Appduct's native code actually shipped inside it —
- * not whether the config that's supposed to have produced it looks right.
+ * `appduct doctor`: the artifact-level replacement for the runtime `debuggable`/`#if DEBUG` gate
+ * removed elsewhere in opt-in hardening. Given a built `.app`/`.ipa`/`.apk`/`.aab`, decide whether
+ * Appduct's native code actually shipped inside it — not whether the config that's supposed to have
+ * produced it looks right.
  *
  * The one property everything here is built around: **never report "absent" because a tool was
  * missing or the artifact couldn't be read.** That failure mode is strictly worse than not having
@@ -14,31 +14,30 @@
  * Detection strategy, and why no single signal is authoritative on either platform:
  *
  * - iOS: `present` is decided by real-code-only symbols alone, exactly like Android below —
- *   `AppductCoreMarker` (`packages/native/ios/Sources/AppductCore/Real/AppductCoreMarker.swift`,
- *   docs/tasks/14-native-core-extraction.md), an `@objc` class compiled only into the real
- *   implementation, never into the SwiftPM package's `Stub/` branch, so its presence cannot be
- *   confused with a stub build. `RCTNativeAppduct` (`RCT_EXPORT_MODULE`, see
- *   `packages/react-native/ios/RCTNativeAppduct.mm`) is kept as a second real-code signal for
- *   artifacts built before the marker existed. Both are Objective-C runtime metadata — they live in
- *   `__objc_classname`/`__objc_data`, and `strip`/release optimization leaves them alone because
- *   removing them would break `+[NSObject class]`-based dispatch. (A build that dead-strips the whole
- *   translation unit for lack of `-ObjC`/`-force_load` could still drop them — these signals assume
- *   the module actually links into the binary, which is the thing being checked in the first
- *   place.) The plugin-authored `Info.plist` keys
- *   (`AppductCliPins`/`AppductTrust`/`AppductAllowPrivateLanOnly`, docs/tasks/00-overview.md
- *   "Native config keys the plugin writes") are reported as a corroborating signal only and can no
- *   longer flip `present` to `true` on their own — an app author can write these keys by hand (or a
- *   future stub could ship them) without the real implementation being present, exactly the reason
- *   the Android signals below aren't all treated as equally authoritative either.
+ *   `AppductCoreMarker` (`packages/native/ios/Sources/AppductCore/Real/AppductCoreMarker.swift`),
+ *   an `@objc` class compiled only into the real implementation, never into the SwiftPM package's
+ *   `Stub/` branch, so its presence cannot be confused with a stub build. `RCTNativeAppduct`
+ *   (`RCT_EXPORT_MODULE`, see `packages/react-native/ios/RCTNativeAppduct.mm`) is kept as a second
+ *   real-code signal for artifacts built before the marker existed. Both are Objective-C runtime
+ *   metadata — they live in `__objc_classname`/`__objc_data`, and `strip`/release optimization
+ *   leaves them alone because removing them would break `+[NSObject class]`-based dispatch. (A
+ *   build that dead-strips the whole translation unit for lack of `-ObjC`/`-force_load` could still
+ *   drop them — these signals assume the module actually links into the binary, which is the thing
+ *   being checked in the first place.) The plugin-authored `Info.plist` keys
+ *   (`AppductCliPins`/`AppductTrust`/`AppductAllowPrivateLanOnly`) are reported as a corroborating
+ *   signal only and can no longer flip `present` to `true` on their own — an app author can write
+ *   these keys by hand (or a future stub could ship them) without the real implementation being
+ *   present, exactly the reason the Android signals below aren't all treated as equally
+ *   authoritative either.
  * - Android: the primary signal is `AppductNativeMarker`
  *   (`packages/native/android/core/src/main/java/com/callstack/appduct/AppductNativeMarker.kt`,
  *   vendored into `@appduct/react-native` at `android/core/src/main/java/...`), a marker class with no
  *   other purpose. Its fully-qualified name is kept unminified and unremoved by a `-keep` rule in
  *   `consumer-rules.pro` (same vendoring path), shipped to every consuming app via `consumerProguardFiles`
  *   (see `../build.gradle`) — R8 applies it regardless of whether the app used the Expo config plugin or
- *   bare-RN autolinking, and regardless of whether the app authored any keep rules of its own
- *   (docs/tasks/10-android-detection-keep-rule.md). This is the only Android signal guaranteed to survive
- *   minification in every supported consumer setup.
+ *   bare-RN autolinking, and regardless of whether the app authored any keep rules of its own.
+ *   This is the only Android signal guaranteed to survive minification in every supported consumer
+ *   setup.
  *
  *   Two more signals are kept as fallbacks for artifacts built before this marker existed: the
  *   `com.callstack.appduct` package string in the dex string pool (and its pre-rename spelling,
@@ -56,30 +55,34 @@
  * a real inclusion to "absent" just because one check missed — but the Info.plist keys signal cannot
  * flip it to `true` by itself, matching Android's marker-only rule below (a stub that ships the same
  * plist keys without the real implementation is exactly the failure mode this guards against, even
- * though no such stub exists yet as of Phase 1 of docs/tasks/14-native-core-extraction.md).
+ * though no such stub exists yet).
  *
  * On Android, `present` is decided by the keep-rule marker alone, not an OR across all three
  * signals. The other two are reported in `signals` for corroboration/debugging but cannot flip
  * `present` to `true` on their own: `android/build.gradle`'s `APPDUCT_ENABLED`-gated vendored
- * source-directory swap (`core` vs `core-noop`, docs/tasks/14-native-core-extraction.md; previously a
- * `src/debug`/`src/release-stub` swap, see docs/tasks/00-overview.md's "Revisited
- * post-implementation") compiles a genuine no-op `AppductPackage` into a default release build at
- * the *same* fully-qualified name the real one uses (required so the shared, non-variant-aware
+ * source-directory swap (`core` vs `core-noop`; previously a `src/debug`/`src/release-stub` swap)
+ * compiles a genuine no-op `AppductPackage` into a default release build at the *same*
+ * fully-qualified name the real one uses (required so the shared, non-variant-aware
  * `PackageList.java` still resolves), and the config plugin writes the same manifest meta-data
  * regardless of variant (Expo mods edit the single merged manifest, not a per-variant one). Both
  * fallback signals therefore fire on that harmless stub exactly as they would on the real module, and
  * can no longer prove inclusion by themselves.
  *
- * `appduct doctor` is strictly better than the runtime check it replaces (docs/tasks/00-overview.md
- * "What we give up, deliberately"). The keep-rule marker closes the previously-documented gap where a
- * bare-RN app with no config plugin and no keep rule could evade both older Android signals under R8
- * minification (docs/tasks/10-android-detection-keep-rule.md) — that gap applied to builds produced before
- * this library shipped the marker/keep rule; an app that pins an older `@appduct/react-native` version
- * still lacks it, and doctor cannot detect inclusion on such a build at all.
+ * Flutter: the Dart core writes `appduct-dart-core/` into the AOT snapshot only when
+ * `appductEnabled` is true; that string in `libapp.so` / `App.framework/App` is a third
+ * authoritative signal on both platforms. The native shim is in every Flutter build and proves
+ * nothing, so doctor reports on the Dart core alone.
+ *
+ * `appduct doctor` is strictly better than the runtime check it replaces: it runs in CI, before
+ * distribution, against the thing actually shipped. The keep-rule marker closes the
+ * previously-documented gap where a bare-RN app with no config plugin and no keep rule could evade
+ * both older Android signals under R8 minification — that gap applied to builds produced before
+ * this library shipped the marker/keep rule; an app that pins an older `@appduct/react-native`
+ * version still lacks it, and doctor cannot detect inclusion on such a build at all.
  */
 export type ArtifactPlatform = "ios" | "android";
 export type ArtifactFormat = "app" | "ipa" | "apk" | "aab";
-export type DetectionSignal = "ios-core-marker-symbol" | "ios-objc-class-symbol" | "ios-info-plist-keys" | "android-keep-rule-marker" | "android-dex-package-symbol" | "android-manifest-meta-data-keys";
+export type DetectionSignal = "ios-core-marker-symbol" | "ios-objc-class-symbol" | "ios-info-plist-keys" | "android-keep-rule-marker" | "android-dex-package-symbol" | "android-manifest-meta-data-keys" | "flutter-dart-core-marker";
 export type ArtifactInspection = {
     platform: ArtifactPlatform;
     format: ArtifactFormat;
@@ -97,10 +100,6 @@ export type ExecBufferResult = {
  * corrupt-archive failure without needing either condition to be true on the machine running the
  * tests. */
 export type ExecBufferFn = (command: string, args: string[]) => Promise<ExecBufferResult>;
-/** Real subprocess execution via `execFile`, buffered as raw bytes. `maxBuffer` is generous (an
- * artifact's full decompressed contents are read into memory at once — see {@link readZipEntries})
- * since real `.ipa`/`.apk`/`.aab` files can run into the hundreds of MB. */
-export declare const defaultExecBuffer: ExecBufferFn;
 export type InspectArtifactOptions = {
     exec?: ExecBufferFn;
 };