@terreno/mcp 57.3.0 → 57.6.0

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

@@ -4,11 +4,12 @@ React Native UI component library (a large component library). Layout (Box, Page
 
 ## Key exports
 
-- Layout: `Box`, `Page`, `SplitPage`, `Card`
+- Layout: `Box`, `Page`, `SplitPage`, `Card`, `DashboardGrid`
 - Forms: `TextField`, `SelectField`, `DateTimeField`, `CheckBox`
-- Display: `Text`, `Heading`, `Badge`, `DataTable`
+- Display: `Text`, `Heading`, `Badge`, `DataTable`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`
 - Actions: `Button`, `IconButton`, `Link`
 - Feedback: `Spinner`, `Modal`, `Toast`
+- Notifications: `NotificationBell`, `NotificationInbox`, `NotificationPreferences`
 - Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
 - Theming: `TerrenoProvider`, `useTheme`, custom icon registry (`icons` prop)
 - **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
@@ -31,8 +32,9 @@ supported and is convenient when startup cost is not material:
 import {Box, DataTable, Icon} from "@terreno/ui";
 ```
 
-Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, and related admin tools) are
+Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
 re-exported from the root entry through lazy boundaries. Importing them from `@terreno/ui` stays type-compatible, but
+their implementation modules load on first render instead of during the initial root import. `DashboardGrid` stays eager.
 their implementation modules load on first render instead of during the initial root import. `MarkdownView` and
 `DataTable` header info defer `react-native-markdown-display`; `EmojiSelector` defers `emoji-datasource` until open.
 
@@ -58,6 +60,115 @@ const customStyle: StyleProp<ViewStyle> = {
 - Ensures type compatibility when passing styles to @terreno/ui components
 - Simplifies imports (one package instead of two)
 
+### DashboardGrid
+
+Eager layout-only wrapping grid. Default columns `{sm: 1, md: 2, lg: 3}`. Children stay caller-supplied `Card`s. Cell width is `(rowWidth - gap × (columns - 1)) / columns` so flex `gap` does not wrap extra columns.
+
+```tsx
+<DashboardGrid>
+  <Card>
+    <LineChart data={points} legendLabel="Signups" />
+  </Card>
+</DashboardGrid>
+```
+
+### LineChart
+
+Single-series line chart drawn with `react-native-svg`. Empty data shows `emptyText` (default `"No data"`). `loading` shows a `Spinner`. Press or hover a point for `{label}: {value}`.
+
+```tsx
+<LineChart
+  data={[{label: "Mon", value: 3}, {label: "Tue", value: 5}]}
+  legendLabel="Signups"
+  testID="signups"
+/>
+```
+
+Hit targets use `Box` `onClick`, so testIDs are `{testID}.point.{index}-clickable`.
+
+### BarChart
+
+Single-series bar chart on the same owned-SVG contract as `LineChart` (empty, loading, legend, tooltip).
+
+```tsx
+<BarChart
+  data={[{label: "Mon", value: 3}, {label: "Tue", value: 5}]}
+  legendLabel="Signups"
+  testID="signups-bar"
+/>
+```
+
+### AreaChart
+
+Filled area plus line on the same owned-SVG contract as `LineChart`.
+
+```tsx
+<AreaChart
+  data={[{label: "Mon", value: 3}, {label: "Tue", value: 5}]}
+  legendLabel="Signups"
+  testID="signups-area"
+/>
+```
+
+### DonutChart
+
+One slice per `{label, value}` point. Per-slice `color` overrides the theme paint. Legend is one row per slice (`legendLabel` is ignored).
+
+```tsx
+<DonutChart
+  data={[{label: "Open", value: 3}, {color: "#112233", label: "Closed", value: 5}]}
+  testID="status-donut"
+/>
+```
+
+### Chart visual regression
+
+`bun run ui:charts:compare` screenshots `http://localhost:8085/demo/chart-visual-gallery`
+and diffs each fixture against `demo/rendered-snapshots/<id>.png`.
+`bun run ui:charts:update-snapshots` rewrites those goldens. Fixture ids live in
+`demo/chartVisual/fixtureCatalog.ts`. Operator steps:
+[Compare rendered chart snapshots](../how-to/compare-chart-rendered-snapshots.md).
+
+## Notification components
+
+Presentational only — no syncdb import. Wire data from your app's sync layer.
+These components are not in the isolated UI component demo; see `example-frontend`.
+
+### `NotificationBell`
+
+| Prop | Type | Description |
+|---|---|---|
+| `unreadCount` | `number` | Badge hidden when `0` |
+| `onPress` | `() => void` | Opens the inbox (host owns visibility) |
+| `renderBadge` | `({unreadCount, testID}) => ReactNode` | Replaces the default unread-count badge |
+| `renderIcon` | `({testID}) => ReactNode` | Replaces the default bell icon |
+| `testID` | `string` | Default `notification-bell` |
+
+Custom renderers keep the built-in 40×40 tap target, positioning, toggle callback, and
+accessible unread-count label. `renderBadge` runs only when `unreadCount > 0`.
+
+### `NotificationInbox`
+
+List-only; wrap in `SideDrawer`, `Modal`, or a sheet in the host screen.
+
+| Prop | Type | Description |
+|---|---|---|
+| `items` | `NotificationInboxItem[]` | Rows to render |
+| `isLoading` | `boolean` | Shows spinner |
+| `onMarkRead` / `onMarkUnread` | `(item) => void` | Toggle `readAt` via syncdb |
+| `onDismiss` | `(item) => void` | Archive the row (`archivedAt` via syncdb) |
+| `onOpen` | `(item) => void` | Tap handler (e.g. Expo Router for `href`) |
+
+`NotificationInboxItem.archived` is optional. Archived rows receive an `Archived` label
+and do not expose dismiss or read-state actions.
+
+### `NotificationPreferences`
+
+| Prop | Type | Description |
+|---|---|---|
+| `preferences` | `{inapp, mail, push, sms}` | Current toggles |
+| `onChange` | `(channel, value) => void` | Per-channel updates |
+
 ## Component Behaviors
 
 ### Button Layout Behavior
@@ -78,6 +189,87 @@ Buttons automatically size to their content unless `fullWidth` is specified:
 
 Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
 
+### TextField password visibility
+
+`type="password"` masks the value and renders a show/hide eye control at the end of the field.
+The control is uncontrolled — the field tracks whether the value is revealed and starts hidden.
+A disabled field cannot be revealed.
+
+``````typescript
+<TextField
+  title="Password"
+  type="password"
+  value={password}
+  onChange={setPassword}
+  autoComplete="current-password"
+/>
+``````
+
+Pass `showVisibilityToggle={false}` where revealing the value is unacceptable, such as a shared or
+on-camera screen:
+
+``````typescript
+<TextField showVisibilityToggle={false} title="Password" type="password" value={password} onChange={setPassword} />
+``````
+
+`Field` with `type="password"` renders the same control, and so do `LoginScreen` and `SignUpScreen`
+password fields.
+
+The toggle's test id defaults to `{testID}.visibility-toggle`, and `testIDs.visibilityToggle`
+overrides it:
+
+| Element | test id |
+| --- | --- |
+| Input | `{testID}` |
+| Label | `{testID}.label` |
+| Error | `{testID}.error` |
+| Helper | `{testID}.helper` |
+| Show/hide toggle | `{testID}.visibility-toggle` |
+
+### GPTChat
+
+Streaming chat surface for `@terreno/ai`. Histories, messages, submit, and optional MCP/tools stay under consumer control.
+
+Pass `mascot` when the app owns a character. Terreno ships none. The node renders only while `currentMessages` is empty, centered in the chat panel above the suggested prompts. The empty hero uses the message viewport height as a minimum so short content stays centered, while taller mascots still scroll. Streaming feedback shares that centered hero instead of creating a second pane. Omit the prop for the default empty chat.
+
+The composer row (attachment picker, tools, input, Send) is vertically centered, so controls stay aligned with the input as it grows. The attachment cell is omitted when `onAttachFiles` is not provided.
+
+```tsx
+<GPTChat
+  currentMessages={[]}
+  histories={histories}
+  mascot={
+    <Box alignItems="center">
+      <Heading size="lg">🦊</Heading>
+    </Box>
+  }
+  onCreateHistory={onCreateHistory}
+  onDeleteHistory={onDeleteHistory}
+  onSelectHistory={onSelectHistory}
+  onSubmit={onSubmit}
+/>
+```
+
+Operator steps: [Add a GPT chat mascot](../how-to/add-gpt-chat-mascot.md). Demo story: `GPTChat` → `Mascot`.
+The example AI screen demonstrates a consumer selecting one of four bundled mascot
+images once per mount.
+
+### SplitPage
+
+Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list, and
+`renderContent` for the detail pane. On large screens both panes stay visible. On small
+screens the detail replaces the list until the user goes back.
+
+```typescript
+import {SplitPage, Text} from "@terreno/ui";
+
+<SplitPage
+  listViewData={[{id: "1", name: "Inbox"}]}
+  renderListViewItem={({item}) => <Text>{item.name}</Text>}
+  renderContent={(index) => <Text>{index === undefined ? "Select an item" : "Detail"}</Text>}
+/>
+```
+
 ### Page Back Navigation
 
 Set `backButton` to render the standard header back arrow. By default it calls `router.back()`; provide `onBack` when the screen needs a deterministic destination instead of browser history.
@@ -505,7 +697,7 @@ declare module "@terreno/ui" {
 }
 ``````
 
-See [`demo/components/customIcons.tsx`](https://github.com/flourishhealth/terreno/blob/master/demo/components/customIcons.tsx) for a full working example.
+See [`demo/components/customIcons.tsx`](https://github.com/TerrenoLabs/terreno/blob/master/demo/components/customIcons.tsx) for a full working example.
 
 ### Built-in Status Icons
 
@@ -574,7 +766,69 @@ import {TerrenoProvider} from "@terreno/ui";
 </TerrenoProvider>
 ``````
 
+## DataTable server-side filtering
+
+`DataTable` is data-layer agnostic. Optional filter and search props emit a
+modelRouter-shaped JavaScript object through `onQueryChange`. The parent merges
+that object with `page`, `limit`, and `sort` before calling a list endpoint.
+
+Import the pure helper when building params outside the component:
+
+```typescript
+import {buildDataTableListQuery} from "@terreno/ui/dataTableListQuery";
+```
+
+### Query contract
+
+| UI | Wire param |
+| --- | --- |
+| Toolbar search (`search` + `searchFields`) | `$or: [{field: {$regex, $options: "i"}}, ...]` (user text escaped) |
+| Text column filter | `{field: {$regex, $options: "i"}}` |
+| Boolean column filter | `{field: true \| false}`; unset omits the key |
+| Date range | `field_gte` / `field_lte` ISO strings; either bound may be sent alone |
+| Number range | `{field: {$gte?, $lte?}}` |
+| Choice (one value) | `{field: string}` scalar equality |
+| Choice (many values) | `{field: {$in: string[]}}` |
+| Choice **Empty** (optional fields) | `{field: {$in: ["__empty__"]}}` on the wire; server maps to `null` (matches missing and null) |
+| Choice **Empty** + concrete | `{field: {$in: [...values, "__empty__"]}}` |
+
+`onQueryChange` never includes `page`, `limit`, or `sort`. Search is debounced
+(250ms, same delay as admin list search).
+
+The server accepts only the documented nested operator keys. Text `$regex` values
+must be escaped literals; executable patterns and extra Mongo operators are rejected.
+
+Date range filters collect calendar days, so a range covers whole UTC days: **from**
+opens the chosen day (`00:00:00.000Z`) and **to** closes it (`23:59:59.999Z`), which
+keeps rows recorded later on the end day inside the range.
+
+Pass `emptyContent` to keep the table header, search, and filter controls mounted
+while showing an application-specific empty state below the header.
+Use `additionalFilters` for declared server filters whose fields are not visible
+columns; web shows one **More filters** popover and native includes them in the same sheet.
+
+### Platform chrome
+
+| Platform | Chrome |
+| --- | --- |
+| Web | Toolbar search + per-column `Filter` popovers (`column.filter`) |
+| Native | Toolbar search + one **Filters** sheet (`Modal`) with the same fields |
+
+Column headers use `Filter` with `iconOnly`, which renders a compact icon trigger
+(24px at the default `triggerSize="sm"`, 32px with `triggerSize="default"`) instead
+of a labeled button. Give it an accessible name with `triggerAccessibilityLabel`.
+
+A single-column popover offers only its own **Clear**, so it needs no per-field clear.
+The surfaces that host several filters at once — the **More filters** popover and the
+native **Filters** sheet — add a per-field **Clear filter** for booleans, whose toggle
+cannot otherwise express "unset".
+
+Omit `column.filter`, `searchFields`, and the related callbacks to keep today's
+sort/page-only table.
+
+Demo: `FilterableDataTable` story in the component demo (`demo:start`, port 8085).
+
 ## Related Documentation
 
 - [UI performance benchmarks](ui-performance.md)
-- [UI package source](https://github.com/flourishhealth/terreno/tree/master/ui/src)
+- [UI package source](https://github.com/TerrenoLabs/terreno/tree/master/ui/src)

package/src/docs/versioned/next/roadmap.md

@@ -2,8 +2,8 @@
 
 Terreno's public roadmap lives on GitHub:
 
-- **[ROADMAP.md](https://github.com/FlourishHealth/terreno/blob/master/ROADMAP.md)** — generated from the Terreno Roadmap project board (also in the repo root)
+- **[ROADMAP.md](https://github.com/TerrenoLabs/terreno/blob/master/ROADMAP.md)** — generated from the Terreno Roadmap project board (also in the repo root)
 - **[Roadmap process](explanation/roadmap-process.md)** — Discussions, triage, Linear bridge, maintainer setup
-- **[GitHub Discussions](https://github.com/FlourishHealth/terreno/discussions)** — Ideas, Q&A, RFCs
+- **[GitHub Discussions](https://github.com/TerrenoLabs/terreno/discussions)** — Ideas, Q&A, RFCs
 
-To propose work, start an [Ideas discussion](https://github.com/FlourishHealth/terreno/discussions/new?category=ideas) rather than opening a tracking issue directly.
+To propose work, start an [Ideas discussion](https://github.com/TerrenoLabs/terreno/discussions/new?category=ideas) rather than opening a tracking issue directly.

package/src/docs/versioned/next/scans/reduce-cold-compile-time/charter.md

@@ -0,0 +1,129 @@
+# Scan charter — reduce cold `bun run compile` wall-clock time
+
+- Slug: reduce-cold-compile-time
+- Status: approved (2026-09-20)
+- Owner: joshgachnang
+
+## Goal
+
+The terreno monorepo compiles with per-package standalone `tsc` and no build
+cache, TS project references, or shared-dep deduplication. A full cold
+`bun run compile` currently takes ~305s, and the pipeline recompiles shared
+packages (`@terreno/test`, `@terreno/api`, `@terreno/syncdb`, `@terreno/jobs`)
+multiple times per run. This campaign cuts cold compile wall-clock by 30% by
+removing redundant tsc passes, deduplicating shared-dependency recompiles,
+introducing project references, and trimming non-typecheck work from the compile
+path — without changing published dist output or weakening type-safety. Faster
+compiles shorten every bootstrap, CI run, and agent iteration.
+
+## Metric
+
+| Field | Value |
+| --- | --- |
+| Name | Cold full-monorepo compile wall-clock |
+| Command | `find . -maxdepth 2 -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete; rm -rf */dist; time bun run compile` (min of 3 runs, seconds) |
+| Unit | s |
+| Direction | down |
+| Protocol | Cold (dist + tsbuildinfo removed before each run), best (min) of 3 consecutive runs, same VM |
+| Baseline | 305 (measured 2026-09-20) |
+| Target | 214 |
+| Horizon | 4 rounds |
+
+Baseline evidence:
+
+```text
+run1 exit=0 elapsed=321s
+run2 exit=0 elapsed=305s
+run3 exit=0 elapsed=309s
+# best of 3 = 305s ; target -30% = 214s
+```
+
+## Scope
+
+- In scope: build/compile configuration only — root `package.json` compile
+  scripts, per-package `tsconfig.json` / `tsconfig.server.json`,
+  `.github/scripts/compile-workspace-deps.js`, per-package `compile` scripts,
+  and any new build tooling that measurably reduces cold compile time.
+- Out of scope: product/source logic, test assertions, runtime behavior,
+  dependency version bumps unrelated to the build.
+- Unacceptable trade-offs:
+  - **Published dist output must stay intact** — `declaration` (.d.ts) emit and
+    the published `dist/` layout for every `@terreno/*` package are preserved.
+  - **No type-safety loss** — no loosening `strict`/`strictNullChecks`, no
+    removing existing `skipLibCheck`, no `noEmit`-to-skip-checks tricks. Adding
+    `skipLibCheck` where absent is allowed.
+  - Publish-time behavior of `compile-workspace-deps.js` must be preserved
+    (it exists because tag-publish replaces `workspace:*` refs before install).
+
+New build dependencies ARE permitted (owner did not exclude them), provided the
+two guardrails above hold.
+
+## Detection rules
+
+| Rule | Query | Matches | Why it moves the metric | Hits |
+| --- | --- | --- | --- | --- |
+| redundant-pipeline | Inspect root `compile` script; `grep -rl compile-workspace-deps */package.json` | Root `compile` runs `@terreno/test` and `@terreno/api` explicitly, then `--filter '*'` recompiles them again; `api` and `admin-backend` re-`tsc` shared deps via `compile-workspace-deps.js` | Every duplicate tsc pass of a large package (api=90k LOC, syncdb, test) is pure cold-time waste | 4 |
+| no-project-references | For each compile-path tsconfig: `grep -L '"references"'`; check for a root solution tsconfig | 19 tsconfigs compile as isolated `tsc` with no `references`; no root solution tsconfig | Project references (`tsc -b`) compile each package once in dep order and enable parallelism, killing recompile overlap | 19 |
+| non-typecheck-work-in-compile | `grep -E 'sync-\|cp \|&&.*&&'` in each package `compile` script | `mcp-server` runs 3 doc-sync scripts at 8GB heap plus a `cp` before/around its `tsc` on every compile | Non-tsc work on the compile critical path adds fixed cold-time cost unrelated to type-checking | 1 |
+| missing-skiplibcheck | For each compile-participating tsconfig: `grep '"skipLibCheck"'` | `demo/tsconfig.json` and `website/tsconfig.json` lack `skipLibCheck` (their compile scripts use these configs) | Without `skipLibCheck`, tsc type-checks every `.d.ts` in the dependency tree — costly for RN/Expo/docs dep trees | 2 |
+
+## Exclusions
+
+Beyond the map-reduce defaults: `node_modules/`, `*/dist/`, `patches/`,
+`terraform/`, generated files (`openApiSdk.ts`, `plugins/terreno-claude/`), and
+`example-frontend` (no `compile` script — not on the compile path).
+
+## Validity rule
+
+A finding is valid only when applying it measurably reduces cold `bun run compile`
+wall-clock (best-of-3) while keeping published dist output identical and
+type-safety unchanged.
+
+## Severity rubric
+
+| Severity | Threshold |
+| --- | --- |
+| high | Plausibly removes ≥30s of cold compile time |
+| medium | Plausibly removes 5–30s |
+| low | Plausibly removes <5s |
+
+Effort: S = under an hour, M = under a day, L = more than a day or needs design.
+
+## Slice policy
+
+- Maximum 4 files and 3 findings per slice.
+- Never mix: a project-references migration with unrelated tsconfig flag tweaks;
+  or `compile-workspace-deps.js` changes with anything else.
+- Always its own slice: the `tsc -b` / project-references migration (touches
+  every package + CI; reviewer-heavy) and any `compile-workspace-deps.js`
+  change (publish-time behavior risk).
+
+## Review routing
+
+| Field | Value |
+| --- | --- |
+| Mode | fixed |
+| Reviewers | @joshgachnang |
+| Assignee | @joshgachnang |
+| Teams | — |
+| Draft | no |
+| Labels | reduce-cold-compile-time, build-perf |
+| Merge policy | human |
+| Notify | PR body mention |
+
+## Budget
+
+- Rounds: 4
+- Slices per round: 2
+- Open PRs at once (`wipLimit`): 1
+- Minimum metric step per round before reporting diminishing returns: 10s
+
+## Decisions
+
+| Decision | Question that prompted it |
+| --- | --- |
+| Goal = reduce cold `bun run compile` wall-clock | "What goal should this scan campaign drive toward?" |
+| Target = 214s (−30% of 305s baseline) | "How aggressive a cold-compile reduction should this campaign target?" |
+| Guardrails = keep published dist output + no type-safety loss; new build deps allowed | "What must this campaign NOT break while cutting compile time?" |
+| Review = fixed @joshgachnang, human merge | "Who reviews the campaign's PRs, and what's the merge policy?" |
+| Budget = 1 open PR, 2 slices/round, 4 rounds | "How much work-in-progress should the campaign carry per round?" |

package/src/docs/versioned/next/scans/reduce-cold-compile-time/round-1-findings.md

@@ -0,0 +1,62 @@
+# Round 1 findings — reduce cold `bun run compile` time
+
+- Goal: reduce cold `bun run compile` wall-clock across the terreno monorepo
+- Metric: cold compile seconds (best of 3). **Baseline 305s → target 214s (−30%)**
+- Head: `f8779a96`
+- Kept: 4 findings · Merged: 2 candidates · Dropped: 2 candidates
+
+## Measured evidence (Sift verification)
+
+| Measurement | Result |
+| --- | --- |
+| `@terreno/test` compile (cold) | 10s |
+| `@terreno/api` compile FULL (compile-workspace-deps + tsc, cold) | 50s |
+| `@terreno/api` tsc-only (deps prebuilt) | 31s → compile-workspace-deps adds **~19s per api compile** |
+| demo `tsc --noEmit` without vs with `--skipLibCheck` | 10s vs 10s → **0s** delta |
+| mcp-server sync scripts (sync-ui / sync-versioned / sync-package) | 0s + 5s + 0s = **~5s** |
+
+## Ranked findings
+
+| # | ID | Rule | Sev | Conf | Effort | Est. cold-time saving | Anchors |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | redundant-explicit-prefix | redundant-pipeline | high | high | S* | ~60s (1× test + 1× api) | `package.json:223` |
+| 2 | compile-workspace-deps-overlap | redundant-pipeline | high | high | M | ~19s+ per api compile, ×2–3 dependents | `.github/scripts/compile-workspace-deps.js:22`, `api/package.json:117`, `admin-backend/package.json:47` |
+| 3 | no-project-references | no-project-references | high | medium | L | large but unquantified; durable fix that enables #1/#2 safely | `api/tsconfig.json:1` + 18 more; no root solution tsconfig |
+| 4 | mcp-doc-sync-on-compile-path | non-typecheck-work-in-compile | medium | high | S | ~5s | `mcp-server/package.json:52` |
+
+\* #1 is a one-line edit but is **load-bearing for build ordering** — safe only once #2/#3 provide dependency-ordered builds. See coupling note below.
+
+## High-severity findings (adversarial verification)
+
+### 1. Redundant explicit `test`+`api` prefixes in root compile — CONFIRMED
+Root `compile` = `bun run --filter '@terreno/test' compile && bun run --filter '@terreno/api' compile && bun run --filter '*' compile`. The final `--filter '*'` already builds all 19 workspaces including `test` and `api`, so the two prefixes are a full extra cold compile of test (10s) + api (50s) = **~60s of duplication**.
+
+*Refutation attempted:* "The prefixes force build order; removing them breaks `*`." → Partially holds. `compile-workspace-deps.js` makes api self-build its deps, so api compiles fine inside `*`; but bun `--filter '*'` gives no guaranteed dependency order, so the prefixes currently serve as a crude ordering hack. Verdict: the **duplication is real and confirmed**, but the safe fix is to introduce real ordering (#2/#3), not to blindly delete the prefixes. Kept high.
+
+### 2. compile-workspace-deps.js re-tsc's shared deps every compile — CONFIRMED
+`compile-workspace-deps.js:22` (`const compiled = new Set()`) dedupes only within one node process. Each package's compile runs in its own `bun run` process, so api re-builds test+syncdb (+19s measured over tsc-only), and admin-backend re-builds api (~50s!)+jobs+test — while `--filter '*'` also builds those same packages as their own targets. Shared deps are cold-compiled multiple times per run.
+
+*Refutation attempted:* "The script is required so deps' `dist` exists before dependents compile." → Holds for the current unordered `*` build, and the script's own doc comment says it exists for tag-publish (post-`workspace:*`-replacement installs). Verdict: confirmed redundant **for the dev/monorepo build**; the fix must preserve publish-time behavior (charter guardrail) and supply ordering another way. Kept high, effort M.
+
+### 3. No TS project references / `tsc -b` solution build — CONFIRMED
+No package tsconfig has `references` or `composite`, and there is no root solution tsconfig (`grep -c '"composite"'` → 0 everywhere; `ls tsconfig.json` → not found). Every package is a full standalone `tsc`.
+
+*Refutation attempted:* "Project references help warm builds (via .tsbuildinfo reuse), not cold — this campaign measures cold." → Fails: even cold, `tsc -b` walks the reference graph and compiles each package **exactly once** in dependency order and parallelizes independent leaves, eliminating the multi-recompile waste that #1 and #2 describe. It is the durable structural fix that makes #1 and #2 safe. Verdict: confirmed high; magnitude unproven without doing the migration → confidence medium, effort L.
+
+## Coupling note (for Plot)
+
+Findings #1, #2, #3 are one problem at three depths: the pipeline recompiles shared packages because there is no dependency-ordered build. #3 (project references) is the durable fix and would subsume #1/#2. A lighter interim fix is bun topological filter ordering. Per charter slice policy: the project-references migration and any `compile-workspace-deps.js` change each get **their own slice**. Finding #4 is fully independent and is the cheapest standalone win.
+
+## Merged candidates
+
+- `s1-pipeline-3` ("test compiled 3×") — folded into #1 and #2; it is the same duplication counted from test's side.
+- `s3-mcpwork-2` ("8GB heap flag on copy scripts") — folded into #4; negligible sub-part of the same compile string.
+
+## Dropped candidates
+
+| Candidate | Reason |
+| --- | --- |
+| `s4-skiplibcheck-1` (demo) | **Invalid — refuted.** `skipLibCheck` is already inherited from `expo/tsconfig.base` (`skipLibCheck: true`). Measured delta 10s vs 10s = 0s. No metric movement. |
+| `s4-skiplibcheck-2` (website) | **Invalid — refuted.** `skipLibCheck` already inherited from `@docusaurus/tsconfig` (`skipLibCheck: true`). `--noEmit` + tiny source set → no measurable movement. |
+
+Drop reasons: 2/2 = already-satisfied-via-inheritance / no-metric-movement.

package/src/docs/versioned/next/tasks/admin-scripts-durable-jobs.md

@@ -0,0 +1,10 @@
+# Tasks: Admin scripts via durable jobs
+
+**IP:** [admin-scripts-durable-jobs.md](../implementationPlans/admin-scripts-durable-jobs.md)
+
+- [x] **Task 1**: `admin/script` adapter (`defineAdminScriptJob`, payload parse, dual-write `BackgroundTask`)
+- [x] **Task 2**: `AdminApp` enqueue/cancel when `JobsApp` is registered; in-process fallback
+- [x] **Task 3**: example-backend worker + API share `defineAdminScriptJob(adminScripts)`
+- [x] **Task 4**: Docs (how-to jobs, jobs reference, admin-backend scripts)
+- [x] **Task 5**: Example GCP runtime selects `GcpCloudTasksRunner` and verifies callback OIDC
+- [x] **Task 6**: CD supplies `JOBS_RUNNER=gcp-cloud-tasks` and per-PR callback URLs