@terreno/mcp 58.0.2 → 58.0.3

package/src/docs/versioned/next/explanation/test-sharding.md

@@ -0,0 +1,111 @@
+# Test sharding in Bun suites
+
+Every package runs its tests through `scripts/test-shards.ts`. The runner starts several
+`bun test --shard=<i>/<n>` processes at once, one per shard, and fails when any of them
+fails. Bun 1.4.4 or newer is required: older versions have no `--shard`.
+
+```bash
+cd api
+bun run test:ci                          # shards chosen from the machine's cores
+TERRENO_TEST_SHARDS=1 bun run test:ci    # one unsplit process
+TERRENO_TEST_SHARDS=3 bun run test:ci    # exactly three shards
+bun test ./src/auth.test.ts              # one file, no runner
+```
+
+## Why shards and not `bun test --parallel`
+
+A shard is an ordinary `bun test` process. It loads the preload once, keeps one module
+registry, and starts one in-memory Mongo, exactly as an unsplit run does. A test file sees
+the same world either way. Only the set of files that share its process changes.
+
+`bun test --parallel` gives each file a fresh global. That re-runs the preload's
+`beforeAll` and `afterAll` for every file, so a backend package starts and stops Mongo once
+per file and reloads every module. Measured on `@terreno/api` (169 files, 4 cores): 648 s
+unsplit, 459 s with `--parallel`, 408 s with two shards.
+
+## How many shards
+
+| Source | Shards |
+| --- | --- |
+| `TERRENO_TEST_SHARDS` set | That number |
+| Not set | Half the cores, at least 1, at most 4 |
+
+A backend shard keeps a Bun process and a `mongod` busy, about two cores. More shards than
+half the cores slows every shard down and makes timing-sensitive tests fail.
+
+CircleCI jobs set `TERRENO_TEST_SHARDS` themselves, because a container reports the host's
+cores and not its own CPU limit. Medium jobs (2 vCPU) run 1 shard. `api-ci`, the longest
+test job, runs on `large` (4 vCPU) with 2 shards.
+
+Root `bun run test` and `bun run test:agent` set `TERRENO_TEST_SHARDS=1`: they already run
+every package at the same time.
+
+## Measured speedup
+
+One 4-core machine, every package's `test:ci` run one after another:
+
+| Package | Unsplit | 2 shards |
+| --- | --- | --- |
+| `api` | 648 s | 408 s |
+| `ai` | 314 s | 187 s |
+| `example-backend` | 253 s | 135 s |
+| `admin-frontend` | 142 s | 75 s |
+| `admin-backend` | 124 s | 83 s |
+| `ui` | 95 s | 65 s |
+| All 21 packages | 1849 s | 1163 s |
+
+Packages that finish in a few seconds gain nothing and lose nothing.
+
+## Isolated files
+
+`ai` and `admin-frontend` pass `--isolated` to the runner. After the shards pass, each
+`src/isolated/*.isolated.ts(x)` file runs in a process of its own, as many at a time as there
+are shards. See [Test isolation](test-isolation.md).
+
+## Coverage
+
+`bun run test:coverage` (`scripts/check-coverage.ts`) uses the same shards. Each shard writes
+its own LCOV report. The script merges them, writes `coverage/lcov.info`, and gates the
+merged numbers at 95%.
+
+Line coverage merges exactly: a line counts when any shard ran it. The sharded line figure
+equals the unsplit one.
+
+Function coverage cannot merge exactly. Bun's LCOV has no per-function records, only a found
+and hit count per file, and Bun counts a nested function only after its parent ran, so shards
+disagree on how many functions a file has. The script takes the largest found count and the
+largest hit count for each file. That estimate usually reads low, because functions hit in
+different shards are not added together. It can read high when one shard runs most of a file
+and another shard finds nested functions that nothing calls.
+
+A sharded run that misses 95% is run again as one unsplit process, and the gate uses that
+exact result. A package whose function coverage is near 95% therefore pays for a second pass;
+set `TERRENO_TEST_SHARDS=1` to skip the first. CircleCI gates every package unsplit except
+`api` and `ai`, which run 2 shards.
+
+While shards run, their output is held and printed one shard at a time. The runner prints a
+`[shards] still running` line once a minute so CI does not see a silent job.
+
+## When a test fails only in a shard
+
+Sharding changes which files share a process. A test that passed only because an earlier
+file left something behind now fails. Run the file alone to confirm:
+
+```bash
+bun test ./src/models/configuration.test.ts
+```
+
+Fix the file so it passes alone. The usual causes:
+
+1. **A missing import.** The test reads state that another file's import registered. Import
+   the module in the test.
+2. **A module mock from another file.** A snapshot or assertion matches another file's
+   `mock.module` shape. Register the mock once in the package preload.
+3. **A timing budget.** Shards load the machine. Freeze the clock with `setSystemTime` or give
+   a slow test its own timeout; do not rely on wall-clock windows.
+
+To reproduce the exact process a shard ran, pass the shard to Bun directly:
+
+```bash
+bun test --shard=2/3
+```

package/src/docs/versioned/next/how-to/README.md

@@ -16,6 +16,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 
 - [Create a Terreno app](create-a-terreno-app.md) — Scaffold a full-stack app with `create-terreno-app` (Bun or npm)
 - [Update dependencies](update-dependencies.md) — Daily rolling PR, exercise test, Expo fingerprint freeze
+- [Fix code scanning alerts](fix-code-scanning-alerts.md) — One PR per sweep; fixes close on rescan, reviewed false positives are dismissed after merge
 - [CircleCI](circleci.md) — Dual-run CI on CircleCI (package CI / policy / e2e; deploys later)
 - [Release automation](release-automation.md) — Let agents merge release notes and roadmap updates; publish only merged notes
 - [Set up tests in a Terreno app](set-up-app-tests.md) — Bun backend and frontend tests, Playwright web E2E, Maestro on iOS/Android

package/src/docs/versioned/next/how-to/circleci.md

@@ -49,10 +49,18 @@ list pipelines on the slug above.
 
 ## Bun version is pinned
 
-`install_bun_and_deps` pins Bun with `node/install-bun` `version`. Bun 1.4.4 reports
-lower line coverage than 1.4.2 for the same tests, which fails the 95% package
-coverage gates. Bump the pin together with the local toolchain and re-run
-`bun run test:coverage` in each package first.
+`install_bun_and_deps` pins Bun with `node/install-bun` `version`, currently 1.4.4, the
+same version as the local toolchain and the GitHub workflows. Package tests run through
+`bun test --shard`, which needs 1.4.4 or newer. Bump the pin together with the local
+toolchain and re-run `bun run test:coverage` in each package first: coverage numbers move
+between Bun releases.
+
+## Test shards
+
+Each executor sets `TERRENO_TEST_SHARDS`, the number of concurrent `bun test --shard`
+processes a package's tests use. Medium executors set 1. `api-ci`, the longest test
+job, overrides it to 2 and runs on `large`. See
+[Test sharding](../explanation/test-sharding.md).
 
 ## Bun install is uncached
 

package/src/docs/versioned/next/how-to/debug-with-mcp.md

@@ -1,5 +1,9 @@
 # Debug a Terreno app with MCP
 
+**This is the standard agent workflow** for finding and fixing issues on Terreno apps: run the
+dev stack, call **`terreno-local`** MCP tools to observe and drive the app, edit code, then
+observe again. Installable skill: **`debug-with-mcp`**. SyncDB-only depth: **`debug-syncdb-with-mcp`**.
+
 Use the local MCP server (`terreno-mcp-local`) to go from a symptom to a verified fix without
 pasting logs into the chat. This guide follows one real failure from start to finish, then lists
 what each tool does. Every tool output below was copied unchanged from a real run against
@@ -12,6 +16,11 @@ what each tool does. Every tool output below was copied unchanged from a real ru
 | API returns 500 | `last_error` with `sources: ["backend"]`. The stack is inside `message`. | `read_logs` with `sources: ["backend"]` and `since` to see the requests around it. |
 | API returns 403 (or another 4xx) | `read_logs` with `sources: ["backend"]` and `level: "warn"`. Every `APIError` under 500 is logged at `warn` as `ForbiddenError(403): <title> — <detail>`, so `last_error` does not show it. | `database_query` to compare the document's `ownerId` with the user in the log line. |
 | App crashes on a screen | Web: `last_error` with `sources: ["browser"]`. An uncaught error carries a separate `stack` field. A render error caught by an error boundary has no `stack`; its `message` names the component instead (see [A screen crashes on web](#a-screen-crashes-on-web)). Native: `last_error` with `sources: ["app"]`. | Native: `navigate` to the screen and call `last_error` again. Web: the `browser` tool. |
+| Wrong API URL or status on device | `read_logs` with `sources: ["network"]` after reproducing the tap. | `database_query` or backend logs to compare server truth. |
+| Auth/session oddities (token in storage) | `read_local_storage` with `prefix: "persist:"` or known key names. | `write_local_storage` only with `TERRENO_MCP_EVAL=1` to fix dev keys; prefer fixing app code for prod. |
+| Native-only crash (no Hermes console) | `read_logs` with `sources: ["native"]` (needs `adb` or iOS Simulator). | `last_error` with `sources: ["app"]` when Hermes is attached. |
+| Need a one-off dev action in the app | `list_dev_commands`, then `invoke_dev_command` with `TERRENO_MCP_EVAL=1`. | Register handlers with `registerTerrenoDevCommand` in app code. |
+| Redux state wrong but SyncDB OK | `get_client_state` or `dispatch_client_action` with a known action type. | `syncdb_action` only for collection CRUD, not Redux. |
 | Data looks wrong | `database_query` to read what the server stored. | `get_client_state` (RTK cache) or `get_syncdb_state` (SyncDB) to compare the client's copy. |
 | Screen renders empty | `get_client_state` or `get_syncdb_state` on native. On web, `browser` with `snapshot`. | `read_logs` with `sources: ["backend"]` to check that the list request ran and returned 200. |
 | Bundler fails | The terminal that runs `expo start`. The `metro` source is always empty under Expo CLI 57: the `/events` socket connects but Expo never sends on it. | On native, `read_logs` with `sources: ["app"]` once the app loads again. |
@@ -161,7 +170,7 @@ On web this returns `layer: "none"`:
 ```json
 {
   "connection": "CDP: Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?); Metro events: not connected",
-  "hint": "No client data layer found. For RTK Query, call `registerTerrenoDevStore(store)` from @terreno/rtk in __DEV__. For SyncDB, create the client with `createSyncDb({debug: true})`. Keep the app running; when the MCP process cannot see the app heap, start Metro so CDP can reach Hermes (see `connection`).",
+  "hint": "No client data layer found. For SyncDB, create the client with `createSyncDb({debug: true})`. For custom client actions, call `registerTerrenoDevClientDispatch` from `@terreno/syncdb` in __DEV__. Keep the app running; when the MCP process cannot see the app heap, start Metro so CDP can reach Hermes (see `connection`).",
   "layer": "none",
   "reasons": {
     "rtk": "Error: No debuggable Hermes/React Native target with webSocketDebuggerUrl (is the app running?)",

package/src/docs/versioned/next/how-to/fix-code-scanning-alerts.md

@@ -0,0 +1,43 @@
+# Fix code scanning alerts
+
+Run `/fix-code-scanning-alerts` to clear every open CodeQL alert on one PR. When that PR merges, each alert closes: fixes close when CodeQL rescans `master`, and reviewed false positives are dismissed by a workflow.
+
+```bash
+gh api "repos/{owner}/{repo}/code-scanning/alerts?state=open&per_page=100" --paginate \
+  | jq -s 'add | group_by(.rule.id) | map({rule: .[0].rule.id, count: length})'
+```
+
+## How alerts close
+
+| Lane | In the PR | After merge |
+| --- | --- | --- |
+| Fix | Code change and a regression test | The CodeQL push scan on `master` no longer reports it, so it closes as **fixed** |
+| Dismiss | An entry in `.github/code-scanning/dismissals.json` | `code-scanning-dismissals.yml` dismisses it with the entry's reason and comment |
+
+Dismissals wait for the merge so a reviewer approves each one, and the Security tab never shows an alert closed by an unmerged branch.
+
+## Pieces
+
+- `.github/codeql/codeql-config.yml`: CodeQL configuration. Test files are ignored, so their alerts close on the next `master` scan.
+- `.github/workflows/codeql-analysis.yml`: also runs on pull requests (diff-informed: only changed lines) and on manual dispatch. Dispatch it on a branch for a full scan that proves each fix clears its alert before merge.
+- `.github/code-scanning/dismissals.json`: the dismissal ledger. Each entry has `alert`, `rule`, `path`, `reason` (`false positive`, `won't fix`, or `used in tests`), and a `comment` of 280 characters or fewer.
+- `.github/workflows/code-scanning-dismissals.yml`: runs on `master` when the ledger changes, and on manual dispatch.
+- `scripts/ci/codeScanning/applyDismissals.ts`: applies the ledger. It dismisses an entry only when the live alert is still open and its rule and path still match. A mismatch fails the job.
+
+## Check a ledger locally
+
+```bash
+bun test scripts/ci/codeScanning/
+GITHUB_TOKEN="$(gh auth token)" GITHUB_REPOSITORY=TerrenoLabs/terreno \
+  bun scripts/ci/codeScanning/applyDismissals.ts --dry-run
+```
+
+The dry run must report `mismatched 0`.
+
+## Rate limiting alerts
+
+`js/missing-rate-limiting` flags every Express route because CodeQL only recognizes known limiter libraries. `TerrenoApp` mounts its own limiter before all plugins (see [Rate limiting](rate-limiting.md)), so these alerts go in the ledger as false positives. A route mounted outside `TerrenoApp` has no limiter and needs a real fix.
+
+## Dependabot
+
+Dependabot opens **security PRs only**. Routine upgrades go through [Update dependencies](update-dependencies.md). Every workspace package directory is listed in `.github/dependabot.yml`. Add a new package's directory there when you create it.

package/src/docs/versioned/next/how-to/run-tests-locally.md

@@ -52,6 +52,11 @@ bun run test          # every workspace `test:ci`
 bun run test:agent    # same suites; passing cases suppressed
 ```
 
+Each package's `test`, `test:ci`, `test:agent`, and `test:coverage` scripts split the suite
+into concurrent `bun test --shard` processes, half the cores by default. Set
+`TERRENO_TEST_SHARDS=1` for one unsplit process. See
+[Test sharding](../explanation/test-sharding.md).
+
 Closest package during a red/green cycle:
 
 ```bash

package/src/docs/versioned/next/how-to/set-up-terreno-mcp.md

@@ -1,7 +1,9 @@
 # Set up Terreno MCP
 
 Configure both Terreno servers: the hosted server supplies documentation and generators; the local
-stdio server inspects the app, database, logs, Metro, and SyncDB state.
+stdio server inspects the app, database, logs, Metro, SyncDB state, web and native navigation.
+After setup, invoke **`debug-with-mcp`** (and when applicable **`debug-syncdb-with-mcp`**) for the
+standard diagnostic workflow.
 - **`terreno`** (hosted, Streamable HTTP) supplies documentation search and code generators.
 - **`terreno-local`** (stdio, runs in your repository) reads the app's packages, database, logs,
   Metro, and client state.

package/src/docs/versioned/next/implementationPlans/mcp-agent-debugger-gaps.md

@@ -0,0 +1,257 @@
+# Implementation Plan: MCP Agent Debugger Gaps (Network, Dispatch, Storage, Native Logs, Dev Commands)
+
+**Status:** Complete — Pick landed 2026-11-06  
+**Parent IP:** [mcp-boost-parity.md](mcp-boost-parity.md) (extends the local stdio companion; does not repeat hosted docs/codegen work)  
+**Roadmap:** Area=`mcp`, Target=`Next`, Impact=`Feature`  
+**Created:** 2026-11-05  
+
+## Goal
+
+Close the remaining agent-debugging gaps compared to integrated RN debuggers (for example
+Xerlock): **network traffic**, **structured Redux dispatch**, **local key-value storage
+read/write**, **native platform logs**, and **app-registered dev commands**. Agents already get
+merged console/backend logs, Mongo, SyncDB/RTK state, navigation, and web driving via
+`terreno-mcp-local`; this plan adds the missing observe/act surfaces without building a
+human debugger UI.
+
+## Non-Goals
+
+- On-device **SQLite** inspection outside SyncDB/TinyBase (partial overlap with
+  `get_syncdb_state`; raw `expo-sqlite` is out of scope).
+- **Push notification** simulation, **network throttle**, and **React component tree /
+  profiler** MCP tools (human DevTools + screenshots + `get_client_state` remain the path).
+- **Zustand** as a first-class framework integration (apps may expose Zustand via
+  `registerTerrenoDevCommand` only).
+- Taking **`metro-mcp`** as a dependency (implement on the existing CDP session in
+  `metroDevSession.ts`).
+- New **hosted** (`terreno-mcp`) tools — all work is **`terreno-mcp-local`** plus small
+  **`@terreno/syncdb`** / bootstrap dev hooks.
+
+## Decisions
+
+| # | Question | Decision |
+|---|----------|----------|
+| D1 | Separate `read_network` tool vs extend `read_logs`? | **Extend `read_logs`** with source `network` (chronological merge with other sources when omitted). |
+| D2 | Depend on `metro-mcp` vs in-house? | **In-house** on `mcp-server/src/local/metro/metroDevSession.ts` (same Hermes CDP connection as `app` / `evaluate`). |
+| D3 | Writable local storage in v1? | **Yes** — `write_local_storage` requires `TERRENO_MCP_EVAL=1`; reads are always allowed. |
+| D4 | Build order | **Network → dispatch + storage → native logs → dev commands → docs**. |
+| D5 | React tree snapshot | **Defer** — not in this plan. |
+
+## Architecture
+
+### Tool surface (after this plan)
+
+| Tool | Server | Purpose |
+|------|--------|---------|
+| `read_logs` | local | Existing sources `backend`, `browser`, `metro`, `app`; **add** `network`, `native`. |
+| `last_error` | local | Unchanged; may surface errors from new sources when level is `error`. |
+| `dispatch_client_action` | local | Dispatch a Redux action on `globalThis.__TERRENO_STORE__` via CDP (EVAL-gated). |
+| `read_local_storage` | local | Read AsyncStorage keys (and opt-in SecureStore key names) via dev global adapter. |
+| `write_local_storage` | local | Write one key (EVAL-gated); never writes SecureStore unless app registers an explicit allowlist entry. |
+| `list_dev_commands` | local | List `{name, description, inputSchema}` from `globalThis.__TERRENO_DEV_COMMANDS__`. |
+| `invoke_dev_command` | local | Run a registered handler by name (EVAL-gated). |
+
+Existing tools (`get_client_state`, `syncdb_*`, `evaluate`, `navigate`, `browser`, …) are
+unchanged.
+
+### CDP network capture (D1, D2)
+
+Extend `metroDevSession.ts`:
+
+1. After attaching to the debug target, enable CDP domains **`Runtime`** (existing) and
+   **`Network`**.
+2. Maintain a ring buffer (same cap as console, default 2000) of normalized entries:
+   - `timestamp`, `method`, `url`, `status`, `mimeType`, `durationMs` when available
+   - Request/response **header maps** with **`Authorization`**, **`Cookie`**, and
+     **`set-auth-token`** redacted
+   - Optional truncated **response body** (text only, max 4 KiB per entry; skip binary)
+3. `read_logs` with `sources: ["network"]` (or default merge) maps the ring into the same
+   JSON shape as other sources, with `source: "network"`.
+4. `connection` metadata reuses the existing CDP status block; document that enabling
+   Network shares the single Hermes debugger slot with DevTools contention rules already
+   documented for `app`.
+
+No separate MCP tool name.
+
+### Redux dispatch (D3, D4 phase 2)
+
+`dispatch_client_action`:
+
+```typescript
+// Input (strict JSON schema)
+{
+  type: string;           // required Redux action type
+  payload?: unknown;      // optional JSON-serializable payload
+}
+```
+
+Implementation:
+
+1. Refuse unless `TERRENO_MCP_EVAL=1` (same posture as `evaluate` / `navigate`).
+2. Prefer in-process read of `globalThis.__TERRENO_STORE__` when the MCP process shares the
+   app heap (tests); otherwise CDP `Runtime.evaluate` with a fixed snippet that calls
+   `globalThis.__TERRENO_STORE__?.dispatch({type, payload})` and returns `{ok, error?}`.
+3. Validate `type` is a non-empty string; reject non-JSON-serializable payloads before evaluate.
+4. Tool description tells agents to use `get_client_state` first, then dispatch, then
+   `read_logs` / `get_client_state` again.
+
+Requires `registerTerrenoDevStore(store)` in consumer apps (already in bootstrap /
+`create-terreno-app`).
+
+### Local storage (D3, D4 phase 2)
+
+Dev-only adapter on the app (new **`@terreno/syncdb`** export, wired in bootstrap template and
+`example-frontend`):
+
+```typescript
+registerTerrenoDevStorage({
+  asyncStorage: true,              // default: wire AsyncStorage getAllKeys/getItem/setItem
+  secureStoreKeyAllowlist?: string[]; // optional SecureStore keys readable/writable via MCP
+});
+```
+
+Sets `globalThis.__TERRENO_DEV_STORAGE__` with `{listKeys, get, set}` in `__DEV__` only.
+
+MCP tools:
+
+- **`read_local_storage`**: `{keys?: string[], prefix?: string}` — returns key/value pairs;
+  omit keys to return all keys from `listKeys()` (cap 200 keys, 8 KiB per value in output).
+- **`write_local_storage`**: `{key, value}` — EVAL-gated; rejects keys not allowed (SecureStore
+  keys not on allowlist).
+
+MMKV and custom stores: apps register via `registerTerrenoDevCommand` or extend the adapter in
+app code (document pattern; no MMKV in framework).
+
+### Native logs (D4 phase 3)
+
+Extend `read_logs` with source **`native`**:
+
+| Platform | Mechanism | When unavailable |
+|----------|-----------|------------------|
+| Android emulator/device | `adb logcat -d -t <N>` subprocess; optional `TERRENO_ADB_SERIAL` | Clear status: `adb` not on PATH or no device |
+| iOS Simulator | `xcrun simctl spawn booted log stream --style compact` with timeout/read cap | No booted sim or Xcode tools missing |
+
+Entries use `source: "native"`, plain-text `raw`, parsed `level` when log line matches common
+patterns. **Not** merged into `last_error` unless line matches error heuristics (document
+behavior). Opt-in env **`TERRENO_NATIVE_LOGS=0`** disables subprocess collection (default on).
+
+Web and Metro-only sessions: `native` source returns empty with status note.
+
+### Dev commands (D4 phase 4)
+
+App API ( **`@terreno/syncdb`** ):
+
+```typescript
+registerTerrenoDevCommand({
+  name: "seedTodos",
+  description: "Insert three fixture todos for the signed-in user",
+  inputSchema: { type: "object", properties: { count: { type: "number" } } },
+  handler: async ({count}) => ({created: count ?? 3}),
+});
+```
+
+Registry: `globalThis.__TERRENO_DEV_COMMANDS__` — map of name → `{description, inputSchema,
+handler}` (handlers run only inside the app via CDP evaluate, same as dispatch).
+
+MCP:
+
+- **`list_dev_commands`** — no args; JSON list of `{name, description, inputSchema}`.
+- **`invoke_dev_command`** — `{name, arguments?}`; EVAL-gated; returns JSON-serializable
+  result or structured error.
+
+Example: register one command in `example-frontend` that toggles a feature flag in AsyncStorage
+to prove the loop.
+
+## Notifications
+
+None.
+
+## UI
+
+No user-visible UI. Dev hooks are `__DEV__` only and no-op in production builds.
+
+## Phases
+
+| Phase | Scope | Depends on |
+|-------|-------|------------|
+| 1. Network via CDP | `metroDevSession` Network domain + `read_logs` `network` source | — |
+| 2. Dispatch + storage | `dispatch_client_action`, storage adapter, read/write tools, bootstrap + example | 1 (shares CDP) |
+| 3. Native logs | `read_logs` `native` source, adb/simctl collectors | — (parallel with 2 after 1) |
+| 4. Dev commands | Registry API, `list_dev_commands`, `invoke_dev_command`, example command | 2 (same evaluate path) |
+| 5. Documentation | Reference, how-to, explainer updates; real captured outputs | 1–4 |
+
+## Feature Flags & Migrations
+
+- No data migrations.
+- All new app hooks are stripped or no-op when `!__DEV__`.
+- `TERRENO_MCP_EVAL=1` remains opt-in; bootstrap must not enable it by default.
+- New env vars: `TERRENO_NATIVE_LOGS` (default on), `TERRENO_ADB_SERIAL` (optional).
+
+## Risks
+
+- **CDP load**: Enabling Network increases traffic on the single Hermes session; keep ring caps
+  and body truncation strict.
+- **Secret leakage**: Redact auth headers; never log request bodies that look like JWTs (regex
+  heuristic in normalizer).
+- **Storage writes**: Mis-invoked `write_local_storage` can corrupt auth tokens; tool description
+  and docs warn to prefer `syncdb_action` for synced data.
+- **Native log volume**: Cap lines per `read_logs` call; default `entries` applies per source.
+- **`invoke_dev_command`**: Arbitrary app code — same trust model as `evaluate`; dev-only registry.
+
+## Not Included / Future Work
+
+- SQLite file browser, notification dispatcher, network throttling, React tree/profiler MCP
+  tools, first-party MMKV adapter.
+
+## Files to Create / Modify
+
+| Area | Files |
+|------|--------|
+| CDP | `mcp-server/src/local/metro/metroDevSession.ts`, tests |
+| Logs | `mcp-server/src/local/tools/readLogs.ts`, tests |
+| Runtime tools | `mcp-server/src/local/tools/runtime.ts` or new `clientDispatch.ts`, `localStorage.ts`, `devCommands.ts` |
+| Registry | `syncdb/src/devMcpRegistry.ts` (or split files), `syncdb/src/index.ts`, tests |
+| Bootstrap | `mcp-server/src/docs/templates/bootstrap/frontend/**`, `create-terreno-app` store bootstrap |
+| Example | `example-frontend/app/_layout.tsx`, optional `devCommands.ts` |
+| Docs | `docs/reference/mcp-server.md`, `docs/how-to/debug-with-mcp.md`, `docs/explanation/ai-development-loop.md`, `docs/reference/environment-variables.md`, `mcp-server/README.md` |
+
+## Task List
+
+See [`docs/tasks/mcp-agent-debugger-gaps.md`](../tasks/mcp-agent-debugger-gaps.md).
+
+## E2E tests
+
+| ID | Spec or flow | Layer | Proves | Written in |
+| --- | --- | --- | --- | --- |
+| E1 | `mcp-server/src/local/localServer.e2e.test.ts` (extend) | process | `read_logs` returns at least one `network` entry after CDP mock emits `Network.responseReceived` | Task 1.3 |
+| E2 | `example-frontend/e2e/mcp-network-debug.spec.ts` | browser | A failing API call produces a 403/404 visible via agent workflow documented in how-to (page triggers fetch; test asserts backend log + optional network source when Metro attached in CI) | Task 5.2 |
+
+If CI cannot attach Metro CDP reliably, Task 5.2 records `None — Metro CDP not in CI` and E2
+becomes a manual evidence step in Task 5.1 only; unit/E1 coverage remains required.
+
+**Pick note (2026-11-06):** E2 browser spec not added — Metro CDP is not reliable in CI. E1
+(`localServer.e2e.test.ts`) plus unit tests satisfy automated proof.
+
+## Regression cases
+
+None — no hard-to-automate change
+
+## User guide
+
+None — operator/agent documentation only; no end-user workflow change
+
+## Acceptance Criteria
+
+- [x] `read_logs` documents and returns entries with `source: "network"` when the app performs
+  fetch/XHR over CDP, with auth headers redacted in captured output.
+- [x] `read_logs` documents and returns entries with `source: "native"` on Android (adb) and
+  iOS Simulator when tools are available, with clear status when not.
+- [x] `dispatch_client_action` dispatches a known action in `example-frontend` under
+  `TERRENO_MCP_EVAL=1` and `get_client_state` reflects the new state.
+- [x] `read_local_storage` / `write_local_storage` round-trip a key in `example-frontend` dev
+  build; write refused without `TERRENO_MCP_EVAL=1`.
+- [x] `list_dev_commands` / `invoke_dev_command` list and run the example-frontend registered
+  command with EVAL gate on invoke only.
+- [x] Reference and how-to pages list every new tool and source with real output captured in
+  Task 5.1.
+- [x] `bun run mcp:build`, affected package tests, and `bun run lint` pass.

package/src/docs/versioned/next/reference/environment-variables.md

@@ -121,6 +121,8 @@ Hosting platforms scope variables per environment. Vercel has **Production**, **
 | `TERRENO_PROJECT_ROOT` | `terreno-mcp-local`, `terreno` CLI | ❌ | nearest Terreno project root | No | tooling |
 | `TERRENO_METRO_URL` | `terreno-mcp-local` | ❌ | frontend script port or `http://localhost:8082` | No | tooling |
 | `TERRENO_MCP_EVAL` | `terreno-mcp-local` | ❌ | disabled | No | tooling |
+| `TERRENO_NATIVE_LOGS` | `terreno-mcp-local` `read_logs` source `native` | ❌ | enabled (`0` disables) | No | tooling |
+| `TERRENO_ADB_SERIAL` | `terreno-mcp-local` native Android logs | ❌ | default `adb` device | No | tooling |
 | `TERRENO_WEB_URL` | `terreno` CLI | ❌ | `http://localhost:8082` | No | tooling |
 | `BUN_CHROME_PATH` | Bun WebView | ❌ | browser auto-discovery | No | tooling |
 | `TERRENO_OPENAPI` | `terreno` CLI | ❌ | — | No | tooling |

package/src/docs/versioned/next/reference/mcp-server.md

@@ -159,6 +159,18 @@ privately and are not returned. Start the local MCP with
 See [Debug a Terreno app with MCP](../how-to/debug-with-mcp.md) for examples and
 safety guidance.
 
+### Dev client hooks (`@terreno/syncdb`)
+
+| Tool | EVAL | Registration |
+| --- | --- | --- |
+| `read_logs` / `last_error` | no | sources include **network** and **native** |
+| `dispatch_client_action` | yes | `registerTerrenoDevClientDispatch` |
+| `read_local_storage` / `write_local_storage` | write | `registerTerrenoDevStorage` (reads redact auth-like keys) |
+| `list_dev_commands` / `invoke_dev_command` | invoke | `registerTerrenoDevCommand` |
+
+Network capture redacts `Authorization`, `Cookie`, `Set-Cookie`, and `Set-Auth-Token`.
+Failed requests include the URL from the matching `requestWillBeSent` `requestId`.
+
 ### terreno_search_docs
 
 BM25-style keyword search over markdown bundled with the MCP server: `docs/resources/*.md`, synced Diátaxis docs under `docs/versioned/`, and per-component excerpts derived from `ui-types-documentation.json`. **Prefer this tool before guessing** Terreno APIs (same posture as Laravel Boost `search-docs`).

package/src/docs/versioned/next/reference/test.md

@@ -361,7 +361,10 @@ exist or has no `smoke` script is an error.
 ## Coverage gates
 
 Package CI uses `scripts/check-coverage.ts` (`bun run test:coverage`, default 95%
-functions and lines) as the live gate. Bun 1.4.2+ may exit 1 on bunfig
+functions and lines) as the live gate. It runs the suite as concurrent
+`bun test --shard` processes and gates the merged LCOV; a sharded run below the
+threshold is confirmed with one unsplit pass
+([Test sharding](../explanation/test-sharding.md)). Bun 1.4.2+ may exit 1 on bunfig
 `coverageThreshold` before isolated LCOV merges; the script continues when tests
 reported `0 fail` and then enforces 95% on the merged report. The blocks
 coverage pass sets `--max-concurrency=1`, because Bun's default 20-way run