@terreno/mcp 58.0.1 → 58.0.3

package/CHANGELOG.md

@@ -20,6 +20,37 @@ Upgrade notes for consumer action live in [`mcp-server/src/docs/upgrades/`](mcp-
 
 Unreleased changes live in [`changelog/unreleased/`](changelog/unreleased/). Add one Markdown file per feature (see that directory's README) instead of editing this section.
 
+## [58.0.3] - 2026-11-11
+
+Upgrade note: [`mcp-server/src/docs/upgrades/58.0.3.md`](mcp-server/src/docs/upgrades/58.0.3.md).
+
+### Added
+
+- `fix-code-scanning-alerts` skill: clears every open CodeQL alert on one PR. Fixes close on the master rescan; reviewed false positives go in `.github/code-scanning/dismissals.json` and a workflow dismisses them after merge. CodeQL now also scans pull requests and ignores test files. See `docs/how-to/fix-code-scanning-alerts.md`.
+- **@terreno/syncdb:** `registerTerrenoDevClientDispatch`, `registerTerrenoDevStorage`, and `registerTerrenoDevCommand` for `terreno-mcp-local` dev tooling.
+- **@terreno/mcp-server:** `read_logs` sources `network` and `native`; `dispatch_client_action`, storage read/write, and dev command list/invoke; CDP network capture with header redaction.
+
+### Changed
+
+- Package tests run as concurrent `bun test --shard` processes through `scripts/test-shards.ts` (half the cores by default, `TERRENO_TEST_SHARDS` to override), and `test:coverage` merges the shards' LCOV. CircleCI now pins Bun 1.4.4, the same version as the local toolchain.
+
+### Fixed
+
+- `Avatar` no longer freezes release builds when its image fails to load. The image error handler passed the native error event to `console.warn`, and with Sentry enabled the app hung while turning that event into a breadcrumb. It now logs only the error message.
+- Mongo filters built from request values reject non-string input with 400 instead of running it as a query operator: AI request explorer `model`, observability review `status`, review batch `promptName`, experiment `datasetId`, trace list filters, push-token `platform`, and `loadDocOr404` ids (404). Sync conflict reloads and tombstone lookups match `_id` with `$eq`.
+- Nested-path helpers in `populate`, RBAC field views, and MCP `excludeFields` skip `__proto__`, `constructor`, and `prototype`, so a crafted path can no longer touch `Object.prototype`.
+- Removed polynomial-time regexes from bearer-header parsing, trailing-slash trimming (syncdb, ui `ListDetailLayout`, jobs Cloud Tasks runner, admin route paths), prompt references, judge score ranges, AI JSON fence stripping, and the MCP import parser.
+- Dataset schema validation stops at the first error (`allErrors` off) to bound work on untrusted input.
+- `isTestUser` in `@terreno/ui` matches `nang.io` and `example.com` as the email domain or a subdomain, not as a substring, and always returns a boolean.
+- MCP OAuth metadata responses set an explicit JSON content type.
+- The example app's AI session id comes from `expo-crypto` `randomUUID` instead of `Math.random`.
+
+## [58.0.2] - 2026-11-09
+
+### Fixed
+
+- Patch the remaining critical and high security advisories in Terreno's dependency tree. `@terreno/ui` now asks for `@react-navigation/native` `^7.5.1`, whose `@react-navigation/core` no longer pulls in the vulnerable `decode-uri-component` (#1693). The docs site moves to tinypool 2.2.0 (critical) and serialize-javascript 7.1.4 (#1690, #1691), Metro's stale nested copy no longer brings in image-size 1.x (#1694), and rulesync 43.8.0 drops its pinned zod 4.6.5 (#1695). Dependabot now opens one security PR per advisory instead of one grouped PR per package block (#1689). Expo tooling still carries zod 3.25.76, which has no fixed 3.x release.
+
 ## [58.0.1] - 2026-11-09
 
 ### Added

package/README.md

@@ -91,16 +91,18 @@ Restart the editor, then ask the agent to call `terreno_search_docs` or `applica
   `terreno_get_update_note`, `terreno_ask_update_help`, `terreno_generate_model`,
   `terreno_generate_route`, `terreno_generate_screen`, `terreno_generate_form_fields`,
   `terreno_validate_model_schema`, `terreno_validate_ui_blocks`, `terreno_install_admin`
-- Local `terreno-mcp-local` tools (11): `application_info`, `database_schema`, `database_query`,
+- Local `terreno-mcp-local` tools (15): `application_info`, `database_schema`, `database_query`,
   `read_logs`, `last_error`, `get_syncdb_state`, `syncdb_snapshot`, `syncdb_action`, `evaluate`,
-  `navigate`, `browser`
+  `navigate`, `dispatch_client_action`, `read_local_storage`, `write_local_storage`,
+  `list_dev_commands`, `invoke_dev_command`, `browser`
 - Nine workflow prompts (`terreno_bootstrap`, `terreno_create_crud_feature`, `terreno_upgrade`, and
   more) and `terreno://docs/*` documentation resources on the hosted server
 - Code generators return text with a target path; the agent writes the files
 - Rate limiting: the hosted server allows 120 requests per 60 seconds per client IP by default and
   answers `429` with `Retry-After` beyond that
-- `TERRENO_MCP_EVAL` gate: `evaluate`, `navigate`, `syncdb_action`, and the `browser` `evaluate`
-  action run only when the local server's environment sets `TERRENO_MCP_EVAL=1` (or `true`)
+- `TERRENO_MCP_EVAL` gate: `evaluate`, `navigate`, `syncdb_action`, `dispatch_client_action`,
+  `write_local_storage`, `invoke_dev_command`, and the `browser` `evaluate` action run only when
+  the local server's environment sets `TERRENO_MCP_EVAL=1` (or `true`)
 
 ## Documentation
 

package/dist/docs/templates/bootstrap/frontend/app/_layout.template.tsx

@@ -7,12 +7,14 @@ import {DefaultTheme, ThemeProvider} from "expo-router/react-navigation";
 import type React from "react";
 import {useEffect} from "react";
 import "react-native-reanimated";
+import {registerTerrenoDevStorage} from "@terreno/syncdb";
 import {installDevConsoleLogger} from "@terreno/syncdb/app";
 import {betterAuthClient} from "@/lib/betterAuth";
 import {apiClient} from "@/store/apiClient";
 import {setSyncDbReady, syncDb} from "@/store/syncdb";
 
 installDevConsoleLogger({baseUrl});
+registerTerrenoDevStorage({asyncStorage: true});
 
 export {ErrorBoundary} from "expo-router";
 

package/dist/docs/upgrades/58.0.3.md

@@ -0,0 +1,28 @@
+# Upgrading to 58.0.3
+
+**Action required:** No
+**Affected packages:** None
+
+## Summary
+
+A patch release with bug and security fixes. `Avatar` no longer freezes release builds when its image fails to load. Mongo filters built from request values, nested-path helpers, and several regexes are hardened against untrusted input. Consumers only need to bump their `@terreno/*` versions.
+
+## Breaking changes
+
+None
+
+The only `Changed` entry affects this repository's own test tooling (sharded `bun test` and Bun 1.4.4 on CircleCI). Nothing changes for consumer apps.
+
+## Deprecations
+
+None
+
+## New capabilities
+
+- **@terreno/syncdb:** `registerTerrenoDevClientDispatch`, `registerTerrenoDevStorage`, and `registerTerrenoDevCommand` for `terreno-mcp-local` dev tooling. These are optional.
+- **@terreno/mcp-server:** `read_logs` sources `network` and `native`, client action dispatch, storage read/write, and dev commands.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- In a release build, show an `Avatar` whose `src` fails to load. It falls back to initials and the app stays responsive.

package/dist/docs/versioned/next/explanation/ai-development-loop.md

@@ -15,7 +15,7 @@ flowchart LR
   ASK["1. Ask<br/>terreno_search_docs<br/>terreno_get_component_docs<br/>application_info"]
   GEN["2. Generate<br/>terreno_generate_*<br/>terreno_validate_model_schema"]
   RUN["3. Run<br/>backend dev server<br/>Metro (Expo)"]
-  OBS["4. Observe<br/>read_logs (backend / browser / metro / app)<br/>last_error<br/>get_client_state"]
+  OBS["4. Observe<br/>read_logs (backend / browser / metro / app / network / native)<br/>last_error<br/>get_client_state"]
   FIX["5. Fix<br/>edit, then navigate<br/>browser snapshot + screenshot"]
   ASK --> GEN --> RUN --> OBS --> FIX
   FIX -->|"iterate"| ASK
@@ -79,7 +79,7 @@ The agent reads what the app did.
 
 | Tool | Contributes |
 | --- | --- |
-| `read_logs` | One merged, time-ordered tail from four sources: `backend` (server JSONL), `browser` (web errors and warnings JSONL), `metro` (bundler events), and `app` (the Hermes console over the Chrome DevTools Protocol). Its `connection` field says which live sources are attached. |
+| `read_logs` | One merged, time-ordered tail from six sources: `backend` (server JSONL), `browser` (web errors and warnings JSONL), `metro` (bundler events), `app` (the Hermes console over CDP), `network` (CDP Network events on the same session), and `native` (adb / iOS Simulator log tail when available). Default sources omit `native`. Its `connection` field says which live sources are attached. |
 | `last_error` | The newest error-level entry across the same sources, as the raw line. It includes a stack when the entry carries one. |
 | `get_client_state` | The client data layer in the running app. It reports which `layer` it found (`rtk`, `syncdb`, both, or `none`) and returns the RTK Query cache and auth state, the SyncDB state, or both. `get_rtk_state` is a deprecated alias. |
 | `get_syncdb_state`, `syncdb_snapshot` | SyncDB entities, outbox, conflicts, cursors, and debug events, plus snapshots to compare before and after a change |
@@ -96,13 +96,16 @@ result.
 | --- | --- |
 | `navigate` | Moves a native app to an expo-router path over the same CDP connection the logs use |
 | `browser` | Drives the web app in a headless WebView: open, click, type, scroll, then `snapshot` the rendered page and save a `screenshot` as proof |
-| `evaluate` | Runs a JavaScript expression in the app's Hermes runtime |
+| `dispatch_client_action` | Dispatches a known Redux action on the dev store (prefer over raw `evaluate`) |
+| `read_local_storage` / `write_local_storage` | Read or write AsyncStorage keys registered for MCP dev tooling |
+| `list_dev_commands` / `invoke_dev_command` | List and run app-registered dev-only command handlers |
+| `evaluate` | Runs a JavaScript expression in the app's Hermes runtime when no fixed tool fits |
 | `syncdb_action` | Changes a live SyncDB client: mutate, flush, resync, resolve conflicts, go offline |
 
-`evaluate`, `navigate`, `syncdb_action`, and the `browser` tool's `evaluate` action run code
-or change state inside the app, so they refuse unless the local server was started with
-`TERRENO_MCP_EVAL=1`. Generated editor configuration never sets it. The other `browser`
-actions do not need it.
+`evaluate`, `navigate`, `dispatch_client_action`, `write_local_storage`, `invoke_dev_command`,
+`syncdb_action`, and the `browser` tool's `evaluate` action run code or change state inside the
+app, so they refuse unless the local server was started with `TERRENO_MCP_EVAL=1`. Generated
+editor configuration never sets it. The other `browser` actions do not need it.
 
 After the fix, the loop goes back to Observe. A change is done when the logs and state show
 the new behavior, not when the edit compiles.

package/dist/docs/versioned/next/explanation/dependency-management.md

@@ -69,16 +69,9 @@ JavaScript packages, GitHub Actions, and a few Expo JS-only names may update. Me
 
 ## Dependabot configuration
 
-`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block. That turns off version-update PRs; security updates ignore the limit and still honor `ignore`. Each block's group uses `applies-to: security-updates`, so fixes arrive grouped:
+`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block. That turns off version-update PRs; security updates ignore the limit and still honor `ignore`. Security updates are not grouped: each advisory opens its own PR per block (`github-actions` at `/`, `bun` at `/`, the backend directories, and the frontend directories), so one fix can merge without waiting on another.
 
-| Group | Ecosystem |
-| --- | --- |
-| `github-actions` | `github-actions` at `/` |
-| `root` | `bun` at `/` (root catalog and root tools) |
-| `backend` | `bun` under api, ai, backends, … |
-| `frontend` | `bun` under ui, syncdb, admin-frontend, demo, apps, … |
-
-Frontend ignores catalog-managed names so those fixes land once, in the root catalog. Root ignores fingerprint-skip names, so a security fix for a native/Expo package never opens a PR; handle it by hand in a release. `dependabot-auto-merge.yml` approves patch and minor Dependabot PRs and enables squash auto-merge, so those security PRs merge when required checks pass. A semver-major security PR (or a group containing one) gets no approval or auto-merge and waits for a human. When one fails because the fix needs code changes, fold the bump into the rolling PR ([Update dependencies](../how-to/update-dependencies.md)); never push to the `dependabot/*` branch.
+Frontend ignores catalog-managed names so those fixes land once, in the root catalog. Root ignores fingerprint-skip names, so a security fix for a native/Expo package never opens a PR; handle it by hand in a release. `dependabot-auto-merge.yml` approves patch and minor Dependabot PRs and enables squash auto-merge, so those security PRs merge when required checks pass. A semver-major security PR gets no approval or auto-merge and waits for a human. When one fails because the fix needs code changes, fold the bump into the rolling PR ([Update dependencies](../how-to/update-dependencies.md)); never push to the `dependabot/*` branch.
 
 ## Daily rolling PR
 

package/dist/docs/versioned/next/explanation/roadmap-seed-issues.md

@@ -1451,6 +1451,19 @@ Delete the `@terreno/rtk` package and every Redux dependency from the monorepo.
 
 ---
 
+## syncdb-high-churn-fields
+
+**Title:** `SyncDB: high-churn fields without a sequence claim per write`
+
+**Labels:** `area:api`, `type:feature`  
+**Project fields:** Area=`api`, Target=`Next`, Impact=`Feature`, IP=`syncdb-high-churn-fields`, Status=`Shaping`
+
+A synced document can carry fields that change every few seconds (a gauge, a heartbeat, a progress counter) without each change costing three replicated writes and a round trip through the stream's counter document.
+
+- **Implementation plan:** [syncdb-high-churn-fields.md](https://github.com/TerrenoLabs/terreno/blob/master/docs/implementationPlans/syncdb-high-churn-fields.md)
+
+---
+
 # Shipped, umbrella, and declined IPs
 
 Tracking issues created for IPs that previously lacked a `**Roadmap issue:**` header.

package/dist/docs/versioned/next/explanation/test-isolation.md

@@ -1,6 +1,7 @@
 # Test isolation in Bun suites
 
-`bun test` runs every test file of a package in one process. `mock.module` replaces a
+`bun test` runs every test file of a package, or of one [shard](test-sharding.md) of it,
+in one process. `mock.module` replaces a
 module for that whole process, and `mock.restore()` does not undo it. A test that
 mocks a module can pass on its own, then break other files, or be broken by them,
 when the whole package runs. CI always runs the whole package, so this kind of

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/docs/versioned/next/how-to/update-dependencies.md

@@ -60,4 +60,4 @@ CircleCI attributes a pipeline to the GitHub user whose token pushed it and emai
 
 ## Dependabot security PRs
 
-`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block, so Dependabot opens no version-update PRs. Security updates still open, grouped per block, and skip ignored native/Expo names. `dependabot-auto-merge.yml` approves them and enables squash auto-merge, so a green security PR merges without this skill. A red one gets its bump folded into the rolling PR. A security fix for an ignored native package is a manual release task (`release` + `upgrading-expo`).
+`.github/dependabot.yml` sets `open-pull-requests-limit: 0` on every block, so Dependabot opens no version-update PRs. Security updates still open, one PR per advisory, and skip ignored native/Expo names. `dependabot-auto-merge.yml` approves them and enables squash auto-merge, so a green security PR merges without this skill. A red one gets its bump folded into the rolling PR. A security fix for an ignored native package is a manual release task (`release` + `upgrading-expo`).