@terreno/mcp 57.6.1 → 57.8.0

package/dist/docs/versioned/next/reference/api.md

@@ -222,6 +222,7 @@ export const todoRouter = modelRouter("/todos", Todo, {
 ```
 
 Do not add `endpoints: (router) => { router.get(...) }` when an action fits.
+Action config supports `allowAnonymous: true` as a per-action override; it does not change authentication for CRUD or sibling actions.
 
 ## modelRouter array operations
 

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

@@ -239,6 +239,7 @@ secrets and `PUBLIC_API_URL` / `COMMS_WEBHOOK_PUBLIC_URL` as above. See
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
 | `ADMIN_SPA_ENABLED` | example-backend | ❌ | — | No | server |
+| `ANNOUNCEMENTS_UPLOAD_TOKEN` | example-backend `AnnouncementsApp` | ❌ | example deploy: `terreno-example-announcement-upload` | Yes outside the example app | server |
 | `ADMIN_SPA_DIST_DIR` | example-backend Dockerfile | ❌ | — | No | server |
 | `ADMIN_SPA_DEV_PROXY` | admin-spa plugin | ❌ | — | No | server |
 | `ADMIN_SPA_BACKEND_URL` | admin-spa tests | ❌ | — | No | tooling |

package/dist/docs/versioned/next/reference/lifecycle-plugin.md

@@ -14,7 +14,7 @@ loops that invoke those stages; they are not stages and must not appear as `stag
 | `terreno-2-pick` | approved task + branch/state | one implemented slice, then Roast, then the next task | Roast, or Brew when the list is done |
 | `terreno-3-roast` | Pick result + current diff | independent requirement/evidence verdict for the current task | emit Pick if tasks remain, else Brew; never invoke Pick; pass a task-scoped briefing; do not spawn two unconstrained reviewers |
 | `terreno-4-brew` | Roast PASS for every in-scope task + branch/evidence | pushed head + PR + product-CI trigger check + review-bot wait + attached evidence | Taste |
-| `terreno-5-taste` | PR + current state | one current-head reaction; before push: pull latest `master`, re-verify last-run failed tests locally, run root `prepush` when present (otherwise affected-package checks) in a no-context subagent, then watch CI | null or fresh Taste |
+| `terreno-5-taste` | PR + current state | one current-head reaction; before push: fetch latest `master` (merge only when needed), re-verify last-run failed tests locally, run root `prepush` when present (otherwise affected-package checks) in a no-context subagent, then watch CI; invoked directly, repeats bounded reactions until terminal | null or fresh Taste |
 
 Outer loops (not stages):
 
@@ -51,7 +51,7 @@ until async review bots (Bugbot, CodeQL, and similar) on the current head have r
 preferring provider CLI watch hooks or harness event subscriptions over sleep polling.
 Taste then waits in a loop for product CI using GitHub CLI (`gh pr checks --watch`,
 `gh run watch`) or CircleCI CLI (`circleci run watch`) until jobs are terminal or the
-wait times out. Before any push, Taste always pulls latest `master`, records last-run
+wait times out. Before any push, Taste fetches latest `master` (merging it only when needed), records last-run
 failed tests and re-verifies them locally, then spawns a
 fresh subagent with no parent conversation. If the repository root defines a `prepush`
 package script, Taste runs it as the authoritative local gate; otherwise it falls back

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

@@ -148,7 +148,7 @@ the demo compiles. Add a story plus `demoConfig.tsx` registration for new
 components, or an allowlist entry with a specific reason — not "hard to demo".
 The allowlist is limited to shell/providers, React context objects, thin RN
 list wrappers, subcomponents already exercised by a parent story
-(Filter, Table, DateTimeField, HeightField, ConsentFormScreen), and
+(DropdownPanel, Table, DateTimeField, HeightField, ConsentFormScreen), and
 product surfaces that belong in `example-frontend` rather than the isolated
 UI demo (announcements and in-app notifications).
 Standalone picker sheets (`NumberPickerActionSheet`, `DecimalRangeActionSheet`)

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

@@ -226,6 +226,69 @@ overrides it:
 | Helper | `{testID}.helper` |
 | Show/hide toggle | `{testID}.visibility-toggle` |
 
+### DropdownPanel
+
+`DropdownPanel` is the compositional dropdown behind the DataTable filter popovers. A
+trigger opens an anchored panel of arbitrary composed content with an optional
+Apply / Clear / Cancel footer, so it also fits non-filter panels (bulk actions, column
+pickers, sort menus).
+
+``````typescript
+<DropdownPanel
+  label="Filters"
+  onApply={applyDraft}
+  onCancel={resetDraft}
+  onClear={clearDraft}
+  onOpenChange={(isOpen) => isOpen && seedDraft()}
+  width={340}
+>
+  <FilterSelectMenu title="Due date" options={DUE_DATE_OPTIONS} value={dueDate} onChange={setDueDate} />
+  <FilterBoolean title="Urgent tasks only" value={urgentOnly} onChange={setUrgentOnly} />
+</DropdownPanel>
+``````
+
+> `Filter` is the former name and stays exported as a deprecated alias (with `FilterProps`)
+> until Terreno 58. The `FilterSelectMenu` / `FilterBoolean` / `FilterAccordion` /
+> `FilterChangesBadge` controls keep their names.
+
+#### Positioning
+
+The panel never renders inside its parent's clipping or stacking context: on web it is
+portaled to `document.body` with fixed positioning, and on native it is teleported to the
+`TerrenoProvider` portal host (falling back to an inline absolute overlay when no host is
+mounted). `computeDropdownPanelLayout` then anchors it to the measured trigger:
+
+| Situation | Behavior |
+| --- | --- |
+| Panel fits beside the trigger | Left edges line up (`align="start"`) |
+| Left-aligned panel would cross the right viewport edge | Right edges line up instead (`align="auto"`, the default) |
+| Panel is wider than the viewport | Narrowed to the viewport minus the 8px screen margins |
+| Less than 160px below the trigger, and more above | Flipped above the trigger |
+| Content taller than the space on screen | Panel body scrolls; the footer stays pinned |
+
+Pass `align="start"` or `align="end"` to pin the side explicitly, and `maxPanelHeight` to
+cap the height below what the viewport allows.
+
+#### Trigger
+
+The default trigger is a `Button` (or a compact icon trigger with `iconOnly`). Style it
+with `triggerVariant` (any `Button` variant), `triggerSize`, and `fullWidth`, or replace
+it entirely with `renderTrigger` when the design needs chrome the button variants do not
+cover:
+
+``````typescript
+<DropdownPanel
+  fullWidth
+  renderTrigger={({isOpen, toggle}) => <MyPill active={isOpen} onPress={toggle} />}
+  width={300}
+>
+  {fields}
+</DropdownPanel>
+``````
+
+`variant` still sets both the trigger and the Apply button; `triggerVariant` and
+`applyButtonVariant` override each independently.
+
 ### GPTChat
 
 Streaming chat surface for `@terreno/ai`. Histories, messages, submit, and optional MCP/tools stay under consumer control.
@@ -257,9 +320,17 @@ 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
+`renderContent` or children for the detail pane. On large screens both panes stay visible. On small
 screens the detail replaces the list until the user goes back.
 
+`desktopChildrenMinWidth` opts into a minimum pixel width for each desktop child when there
+are one or two children. `narrowViewportChildLabels` opts into a labeled full-width pager on
+the narrow viewport. `narrowBelowWidth` uses that viewport when the window is at or below the
+given pixel width; when omitted, the narrow viewport follows `isNarrowViewport()`. These props
+are web only; the native `SplitPage` ignores them. See `SplitPageProps` for when each prop
+applies and what is ignored.
+`IconButton`'s `backgroundOpacity` tints only that button's background.
+
 ```typescript
 import {SplitPage, Text} from "@terreno/ui";
 
@@ -564,7 +635,7 @@ import {
   mediaQuery,
   mediaQueryLargerThan,
   mediaQuerySmallerThan,
-  isMobileDevice,
+  isNarrowViewport,
 } from "@terreno/ui";
 
 // Read the current breakpoint
@@ -582,9 +653,9 @@ if (mediaQuerySmallerThan("lg")) {
   console.log("Smaller than large");
 }
 
-// Detect mobile
-if (isMobileDevice()) {
-  console.info("Running on mobile device");
+// Current window is below the desktop breakpoint
+if (isNarrowViewport()) {
+  console.info("Narrow viewport");
 }
 ``````
 
@@ -610,7 +681,7 @@ Web (desktop staff):
 
 On web, `sm` (320) and `md` (375) still classify widths below 1024 so layouts can remain accessible.
 
-`isMobileDevice()` is true below the supported desktop floor: native width < 1024 (`xl`), web width < 1024 (`lg`).
+`isNarrowViewport()` is true below the supported desktop floor: native width < 1024 (`xl`), web width < 1024 (`lg`). `isMobileDevice()` is the same check and is deprecated in favor of `isNarrowViewport`.
 
 Responsive `Box` direction props update automatically when the window resizes or a device rotates:
 
@@ -811,10 +882,10 @@ columns; web shows one **More filters** popover and native includes them in the
 
 | Platform | Chrome |
 | --- | --- |
-| Web | Toolbar search + per-column `Filter` popovers (`column.filter`) |
+| Web | Toolbar search + per-column `DropdownPanel` 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
+Column headers use `DropdownPanel` 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`.
 

package/dist/docs/versioned/next/tasks/can-as-permission-seam.md

@@ -4,7 +4,7 @@ IP: [can-as-permission-seam.md](../implementationPlans/can-as-permission-seam.md
 
 ## Phase 1 — `assertAllowed`
 
-- [ ] **Task 1.1**: Helper + unit tests
+- [x] **Task 1.1**: Helper + unit tests
   - Delivers: `assertAllowed` implements legacy `checkPermissions` and `accessControl.can()`; double-gate test (access allow + permissions deny → allow)
   - Files: `api/src/rbac/assertAllowed.ts`, `api/src/rbac/assertAllowed.test.ts`
   - Blocked by: none (can land before MCP adapters; executors wiring waits on unified writes if MCP still duplicates checks)
@@ -12,7 +12,7 @@ IP: [can-as-permission-seam.md](../implementationPlans/can-as-permission-seam.md
 
 ## Phase 2 — Hot path
 
-- [ ] **Task 2.1**: Middleware + executors
+- [x] **Task 2.1**: Middleware + executors
   - Delivers: `permissionMiddleware` and `executeCreate/Update/Delete` call `assertAllowed`; `buildAccessPermissions` not used on requests
   - Files: `api/src/permissions.ts`, `api/src/sync/executors.ts`, `api/src/api.ts`, `api/src/rbac/modelRouterAccess.ts`, tests
   - Blocked by: 1.1; unified-mutation-executors Phase 2 so MCP is included automatically
@@ -20,12 +20,12 @@ IP: [can-as-permission-seam.md](../implementationPlans/can-as-permission-seam.md
 
 ## Phase 3 — Consumers and docs
 
-- [ ] **Task 3.1**: example-backend dual config
+- [x] **Task 3.1**: example-backend dual config
   - Delivers: routers with `access` drop redundant AND `permissions` where RBAC is the intent
   - Files: `example-backend/src/**` model routers
   - Blocked by: 2.1
   - Acceptance: example-backend tests pass
-- [ ] **Task 3.2**: Docs + breaking changelog
+- [x] **Task 3.2**: Docs + breaking changelog
   - Files: `docs/reference/api.md`, `docs/how-to/create-a-model.md`, `docs/implementationPlans/rbac-permissions.md` pointer, changelog
   - Blocked by: 2.1
   - Skills: `update-docs`

package/dist/docs/versioned/next/tasks/collection-registry.md

@@ -4,12 +4,12 @@ IP: [collection-registry.md](../implementationPlans/collection-registry.md)
 
 ## Phase 1 — Dual-write catalog
 
-- [ ] **Task 1.1**: `CollectionRegistry` module
+- [x] **Task 1.1**: `CollectionRegistry` module
   - Delivers: `registerCollection`, `replaceCollectionOptions`, `getCollection`, `listCollections`, `clearCollectionRegistry` with unit tests (unknown path no-op, options replace)
   - Files: `api/src/collectionRegistry.ts`, `api/src/collectionRegistry.test.ts`
   - Blocked by: none
   - Acceptance: bun tests for the module pass without wiring modelRouter
-- [ ] **Task 1.2**: Dual-write from `modelRouter`
+- [x] **Task 1.2**: Dual-write from `modelRouter`
   - Delivers: `modelRouter` / `_buildModelRouter` write the catalog in addition to existing `register*` / `update*`
   - Files: `api/src/api.ts`
   - Blocked by: 1.1
@@ -17,12 +17,12 @@ IP: [collection-registry.md](../implementationPlans/collection-registry.md)
 
 ## Phase 2 — Surfaces read the catalog
 
-- [ ] **Task 2.1**: MCP and realtime views
+- [x] **Task 2.1**: MCP and realtime views
   - Delivers: `getMCPRegistry` / realtime finders read `CollectionRegistry`; arrays in those files removed
   - Files: `api/src/mcp/registry.ts`, `api/src/realtime/registry.ts`, related tests
   - Blocked by: 1.2
   - Acceptance: MCP and realtime tests pass; `updateMCPRegistryOptions` updates the shared record
-- [ ] **Task 2.2**: Sync view + keep validation
+- [x] **Task 2.2**: Sync view + keep validation
   - Delivers: sync lookup uses catalog; `registerSync` validation + index promises still run
   - Files: `api/src/sync/registry.ts`, `api/src/sync/*.test.ts`
   - Blocked by: 1.2
@@ -30,12 +30,12 @@ IP: [collection-registry.md](../implementationPlans/collection-registry.md)
 
 ## Phase 3 — Contract
 
-- [ ] **Task 3.1**: Single writer + clear-all
+- [x] **Task 3.1**: Single writer + clear-all
   - Delivers: `modelRouter` only writes `CollectionRegistry`; wrapper register/update/clear functions; tests that used independent clears updated
   - Files: `api/src/api.ts`, registry wrappers, tests
   - Blocked by: 2.1, 2.2
   - Acceptance: one `replaceCollectionOptions` is enough for MCP+sync options identity
-- [ ] **Task 3.2**: Docs + changelog
+- [x] **Task 3.2**: Docs + changelog
   - Files: `docs/explanation/modular-api-design.md`, `docs/reference/api.md`, changelog
   - Blocked by: 3.1
   - Skills: `update-docs`

package/dist/docs/versioned/next/tasks/demo-workshop.md

@@ -0,0 +1,150 @@
+# Task List: Demo workshop
+
+See: [`docs/implementationPlans/demo-workshop.md`](../implementationPlans/demo-workshop.md)
+
+**RTK deprecation flag:** None
+
+## Instructions for the implementing agent
+
+- Work the frontier: any task whose blockers are complete. The tracer is Task 1.1 (Button).
+- Do not start iOS work, a translation catalog, or an addon API.
+- Docs named on a task ship in that task. Use the `update-docs` skill.
+- UI tasks also use `verify-ui-changes` and `terreno-ui`.
+- Visual tasks use `review-chart-visuals` for the PNG diff workflow, then the new demo how-to.
+- Run the task's verification command before handoff. `bun run lint` and `bun run demo:compile` on every demo task.
+
+## Phase 1: Catalog, snippets, and preview bar
+
+- [x] **Task 1.1**: Button catalog contract
+  - Delivers: Button has a copyable usage snippet, resolvable related links, stable stories, one declarative interaction list, and typed control defaults.
+  - Files: `demo/demoConfig.tsx`, `demo/story-config/Button.config.tsx`, `demo/stories/Button.stories.tsx`, `demo/collectRegisteredStoryRenders.ts`, `demo/app/demo/[component].tsx`, `demo/README.md`
+  - Blocked by: none
+  - Acceptance: a unit test fails when a related name does not resolve, when an excluded story has an empty reason, or when a boolean control defaults to `""`. Button's snippet renders and copies. `showInDemo: false` hides a Button story in demo mode and leaves it on the dev route.
+  - Verification: `bun test demo/collectRegisteredStoryRenders.ts demo/demoConfig` (or the new colocated test), `bun run demo:compile`, and a web demo pass that opens Button, copies the snippet, and follows one related link.
+  - Docs: `demo/README.md` catalog-contract section
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.2**: Search, categories, and related links
+  - Delivers: the home grid and dev index filter by text and category, and every component's related row is links.
+  - Files: `demo/components/DemoHomePage.tsx`, `demo/components/DevHomePage.tsx`, `demo/app/demo/[component].tsx`, story configs whose `related` strings do not resolve, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: searching "button" shows Button; choosing a category hides other categories; a broken related name fails the catalog test; the home grid still does not nest pressables (`demo/components/DemoCard.test.tsx`).
+  - Verification: catalog unit test, `demo/components/DemoCard.test.tsx`, and a web demo pass of search, category filter, and a related link.
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+- [x] **Task 1.3**: Usage snippet on every component
+  - Delivers: every registered story config has `usageExample`, and the component page can copy it.
+  - Files: `demo/story-config/*.config.tsx`, `demo/app/demo/[component].tsx`, `scripts/check-demo-coverage.ts` or a sibling check, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run check:demo-coverage` (or the new snippet check it calls) fails when any registered config lacks a non-empty `usageExample`. The Button page copy control still works.
+  - Verification: the check command, plus one web copy action on a second component (TextField).
+  - Docs: `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [x] **Task 1.4**: Preview toolbar and URL state
+  - Delivers: demo and dev component routes change theme, viewport, background, locale, right-to-left, and reduced motion from the URL. Embeds apply that state and hide the bar.
+  - Files: `demo/components/DemoChrome.tsx`, `demo/app/_layout.tsx`, `demo/app/demo/_layout.tsx`, `demo/app/dev/_layout.tsx`, `demo/contexts/EmbedModeContext.tsx`, `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Blocked by: Task 1.1
+  - Acceptance: Button at a documented query uses the dark remap and the 375 viewport. Consent or date stories that already read locale receive the toolbar locale. Embed hides the bar. Reloading keeps the query.
+  - Verification: a focused demo unit test for query parse/serialize, `bun run demo:compile`, and a web demo pass of the Button query plus one embed URL.
+  - Docs: `docs/how-to/preview-demo.md`, `demo/README.md`
+  - Skills: `update-docs`, `terreno-ui`, `verify-ui-changes`
+
+## Phase 2: Web proof and health
+
+- [ ] **Task 2.1**: Web interaction and axe for Button
+  - Delivers: Playwright runs Button's step list and axe against the Button stories.
+  - Files: `scripts/demo/runWebStoryChecks.ts`, `demo/story-config/Button.config.tsx`, root `package.json` (axe dependency if needed), `.circleci/config.yml`, `.circleci/continue-config.yml`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Blocked by: Task 1.1
+  - Acceptance: the Button interaction steps pass in Chromium. A serious axe violation fails the command. An excluded story with a reason is skipped. The job is required for `ui/**` and `demo/**` pull requests.
+  - Verification: `bun run demo:web-checks --only=Button` (the script this task adds) locally against demo web, then the CircleCI path-filter test if one exists beside `.circleci/`.
+  - Docs: `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 2.2**: Web visual harness for Button
+  - Delivers: one cropped web PNG baseline for each stable Button story, compared with the chart pixel matcher.
+  - Files: `scripts/demo/compareDemoSnapshots.ts`, `demo/rendered-snapshots/web/`, `scripts/charts/compareChartImages.ts` (reuse only), `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`
+  - Blocked by: Task 1.1
+  - Acceptance: `bun run demo:snapshots:compare --only=Button` passes against the new goldens and fails when a golden is missing. Chart compare still passes for the existing chart fixtures.
+  - Verification: the new compare command and `bun run ui:charts:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/ui.md`, `docs/how-to/compare-chart-rendered-snapshots.md` (pointer only)
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.3**: Web proof for every stable story
+  - Delivers: every stable story has interaction steps or an exclusion reason, an axe run, and a web PNG baseline.
+  - Files: `demo/story-config/*.config.tsx`, `demo/stories/*.stories.tsx`, `demo/rendered-snapshots/web/`, the web check and snapshot scripts
+  - Blocked by: Task 2.1, Task 2.2
+  - Acceptance: the web check and snapshot commands, with no `--only`, exit 0. Removing one stable story's golden or steps fails the matching command. Excluded stories name a reason.
+  - Verification: `bun run demo:web-checks` and `bun run demo:snapshots:compare`.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+- [ ] **Task 2.4**: Story health and CI summary
+  - Delivers: the component page shows render, interaction, accessibility, and visual status from `demo/story-health.json`. CI stores that file and writes a check summary.
+  - Files: `demo/app/demo/[component].tsx`, `scripts/demo/writeStoryHealth.ts`, `.circleci/continue-config.yml`, `docs/reference/test.md`
+  - Blocked by: Task 2.3
+  - Acceptance: Button shows a pass row after the web commands. A forced failing story shows fail. A missing health file shows not-run. The CircleCI job summary lists failed story ids. The job does not call `gh pr comment`.
+  - Verification: unit test for health rendering, the web commands, and a CI config test or review that the job uploads artifacts and writes the summary.
+  - Docs: `docs/reference/test.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+## Phase 3: Android
+
+- [ ] **Task 3.1**: Android proof for Button
+  - Delivers: a CircleCI Android emulator job runs Button's steps, accessibility-tree assertions, and a cropped Android PNG.
+  - Files: `.circleci/config.yml`, `.circleci/continue-config.yml`, `scripts/demo/generateMaestroFlows.ts`, `.maestro/flows/demo/generated/`, `demo/rendered-snapshots/android/`, `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`
+  - Blocked by: Task 2.1
+  - Acceptance: Pixel 6 API 34 runs the generated Button flow. The job is required when `ui/**` or `demo/**` changes. A missing Android golden fails the job. Web axe is unchanged.
+  - Verification: the local Maestro command documented in the how-to, against an emulator, for the Button flow. Record the CircleCI job name.
+  - Docs: `docs/how-to/circleci.md`, `docs/how-to/run-tests-locally.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 3.2**: Android proof for every stable story
+  - Delivers: every stable story has an Android flow, accessibility-tree check, and PNG, or an exclusion reason.
+  - Files: generated Maestro flows, `demo/rendered-snapshots/android/`, `demo/story-health.json` writer
+  - Blocked by: Task 3.1, Task 2.3
+  - Acceptance: the Android job without `--only` exits 0. Health on Button includes the Android columns. An excluded story is absent from the Android failure list and its reason is in the summary.
+  - Verification: the Android compare and Maestro commands across the stable catalog.
+  - Docs: `docs/how-to/compare-demo-snapshots.md`, `docs/reference/test.md`
+  - Skills: `update-docs`, `review-chart-visuals`
+
+## Phase 4: Major versions
+
+- [ ] **Task 4.1**: Version manifest and dropdown
+  - Delivers: production stays on the current major, `versions.json` lists released majors and a `preview/<major>` branch, and the top bar dropdown navigates there. The default is the highest released major.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `scripts/ci/netlify-deploy.sh`, `demo/components/DemoChrome.tsx`, `docs/how-to/demo-versions.md`, `.circleci/continue-config.yml`
+  - Blocked by: Task 1.4
+  - Acceptance: a unit test of the manifest builder marks `preview/58` as preview and not current, marks 57 as current, and omits `pr-*` aliases. The dropdown on the home page shows those labels. `versions.json` on the production origin sends CORS headers the aliases can read.
+  - Verification: the manifest unit test, a deploy dry-run, and a web demo pass of the dropdown.
+  - Docs: `docs/how-to/demo-versions.md`, `demo/README.md`
+  - Skills: `update-docs`, `verify-ui-changes`
+
+- [ ] **Task 4.2**: Freeze the previous major and backfill 56
+  - Delivers: moving master from 57 to a later major freezes 57 on alias `v57`. Alias `v56` serves the last master commit whose package major is 56.
+  - Files: `scripts/demo/publishDemoVersions.ts`, `.circleci/continue-config.yml`, `docs/how-to/demo-versions.md`
+  - Blocked by: Task 4.1
+  - Acceptance: a test with a fake deploy history freezes the previous production deploy when the major increases, and leaves 57 updating on ordinary master commits. The backfill command documents the git revision it deployed for 56.
+  - Verification: unit test of the freeze decision, plus the one-time 56 alias deploy recorded in the how-to.
+  - Docs: `docs/how-to/demo-versions.md`
+  - Skills: `update-docs`
+
+- [ ] **Task 4.3**: Docs embeds follow the demo major
+  - Delivers: a 57 docs page embeds the 57 demo. The next docs version embeds the 58 preview when the manifest lists it.
+  - Files: `website/docusaurus.config.ts`, `website/src/components/ComponentDemo/index.tsx`, `docs/how-to/demo-versions.md`, the docs reference page that describes component embeds
+  - Blocked by: Task 4.1
+  - Acceptance: `ComponentDemo` for the 57 docs build requests the 57 demo URL with `?embed=1`. When the manifest has an unreleased preview, the next docs build uses that preview URL. A missing preview falls back to production.
+  - Verification: a website unit test or build-arg test for the URL choice, and `bun run website:build`.
+  - Docs: `docs/how-to/demo-versions.md` and the existing component-embed reference section
+  - Skills: `update-docs`
+
+## Phase 5: MCP catalog
+
+- [ ] **Task 5.1**: Public demo catalog tools
+  - Delivers: `terreno_list_demo_stories` and `terreno_get_demo_story` return Button's snippet, route, story ids, and the version manifest URL.
+  - Files: `demo/demo-catalog.json`, `demo/package.json`, `mcp-server/src/tools.ts`, MCP tests, `docs/reference/mcp-server.md`
+  - Blocked by: Task 1.3, Task 4.1
+  - Acceptance: `terreno_get_demo_story` for Button includes `usageExample` and a `/demo/Button` route. The list tool filters by category. The response points at production `versions.json`. A catalog drift test fails when a registered component is missing from the JSON.
+  - Verification: `cd mcp-server && bun test` for the new tool tests, and `bun run demo:catalog` followed by the drift check.
+  - Docs: `docs/reference/mcp-server.md`, `demo/README.md`
+  - Skills: `update-docs`

package/dist/docs/versioned/next/tasks/describe-model-schema.md

@@ -4,12 +4,12 @@ IP: [describe-model-schema.md](../implementationPlans/describe-model-schema.md)
 
 ## Phase 1 — Descriptor + MCP
 
-- [ ] **Task 1.1**: `describeModel` / `describeModelForRouter`
+- [x] **Task 1.1**: `describeModel` / `describeModelForRouter`
   - Delivers: field graph + snapshot tests on a fixture schema
   - Files: `api/src/schemaMetadata.ts`, `api/src/schemaMetadata.test.ts`
   - Blocked by: none
   - Acceptance: snapshots for enum, ref, array, subdocument, system fields
-- [ ] **Task 1.2**: MCP Zod from descriptor
+- [x] **Task 1.2**: MCP Zod from descriptor
   - Delivers: `schemaGenerator.ts` maps `FieldDescription`; no SchemaType switch for kinds already in the descriptor
   - Files: `api/src/mcp/schemaGenerator.ts`, `api/src/mcp/schemaGenerator.test.ts`
   - Blocked by: 1.1
@@ -17,7 +17,7 @@ IP: [describe-model-schema.md](../implementationPlans/describe-model-schema.md)
 
 ## Phase 2 — Admin
 
-- [ ] **Task 2.1**: `extractFieldMeta` from descriptor
+- [x] **Task 2.1**: `extractFieldMeta` from descriptor
   - Delivers: admin config fields built from `describeModel`, not OpenAPI property walk
   - Files: `admin-backend/src/adminApp.ts`, admin-backend tests
   - Blocked by: 1.1
@@ -25,12 +25,12 @@ IP: [describe-model-schema.md](../implementationPlans/describe-model-schema.md)
 
 ## Phase 3 — OpenAPI + docs
 
-- [ ] **Task 3.1**: `getOpenApiSpecForModel` from descriptor
+- [x] **Task 3.1**: `getOpenApiSpecForModel` from descriptor
   - Delivers: OpenAPI properties derived from `ModelDescription`; populate still applied
   - Files: `api/src/populate.ts`, `api/src/openApi.test.ts` / example-backend openapi snapshot if required
   - Blocked by: 1.1
   - Acceptance: OpenAPI tests pass; any snapshot diff is reviewed in the PR
-- [ ] **Task 3.2**: Docs + export
+- [x] **Task 3.2**: Docs + export
   - Files: `docs/explanation/schema-metadata.md`, `docs/reference/api.md`, `docs/how-to/create-a-model.md`, admin reference, `api/src/index.ts`, changelog
   - Blocked by: 1.2, 2.1, 3.1
   - Skills: `update-docs`

package/dist/docs/versioned/next/tasks/migrate-cicd-to-circleci.md

@@ -103,19 +103,21 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 0.2, Task 1.3
   - Acceptance: preview deploy URL posted or visible; prod deploy on master path filter.
-  - Note: Path filters and preview jobs exist. Live Netlify still runs on GHA until `terreno-netlify` is filled; CircleCI skips. Cleanup on PR close is GHA `preview-cleanup.yml`.
+  - Note: CircleCI is the only Netlify deployer; jobs fail when `terreno-netlify` is empty. PR close triggers CircleCI `preview-cleanup` through `preview-cleanup.yml`.
 
 - [ ] **Task 4.2**: Preview cleanup port
   - Description: On PR close, clean Netlify/GCP preview resources from CircleCI (webhook or GitHub App → pipeline). Prefer OIDC over `GCP_SA_KEY`.
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 4.1
   - Acceptance: closing a PR removes preview resources; no orphaned Cloud Run `pr-N` services in a test PR.
+  - Note: Cutover code landed on branch `move-cd-to-circleci` (GHA deploy workflows disabled; CircleCI deploy jobs fail on empty contexts). Check off after contexts are filled and the acceptance is observed.
 
 - [ ] **Task 4.3**: Dual-run cutover for Netlify
   - Description: Delete GHA deploy workflows after CircleCI trusted.
   - Files: `.github/workflows/demo-deploy.yml`, `frontend-example-deploy.yml`, `docs-deploy.yml`, `preview-cleanup.yml`
   - Depends on: Task 4.1, Task 4.2
   - Acceptance: GHA deploy twins deleted.
+  - Note: Cutover code landed on branch `move-cd-to-circleci` (GHA deploy workflows disabled; CircleCI deploy jobs fail on empty contexts). Check off after contexts are filled and the acceptance is observed.
 
 ## Phase 5: EAS + fingerprint
 
@@ -150,13 +152,14 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Files: `.circleci/continue-config.yml`
   - Depends on: Task 6.1
   - Acceptance: terraform preview on PR; apply+deploy on master for a safe test path; GitHub Deployment records optional but documented.
-  - Note: Path filters exist. Live GCP still runs on GHA until `terreno-gcp` is filled; CircleCI skips apply.
+  - Note: CircleCI is the only GCP deployer; jobs fail when `terreno-gcp` is empty. `gcp-cd-prod` runs MCP `test:ci` before the MCP deploy.
 
 - [ ] **Task 6.3**: Dual-run cutover for CD
   - Description: Single deployer: disable GHA `cd.yml` when CircleCI CD is required; remove GitHub OIDC provider only after GHA CD is gone (or keep read-only if other repos need it — document).
   - Files: `.github/workflows/cd.yml`, terraform OIDC
   - Depends on: Task 6.2
   - Acceptance: only CircleCI performs terreno CD; no double apply.
+  - Note: Cutover code landed on branch `move-cd-to-circleci` (GHA deploy workflows disabled; CircleCI deploy jobs fail on empty contexts). Check off after contexts are filled and the acceptance is observed.
 
 ## Phase 7: npm publish
 
@@ -200,7 +203,7 @@ Research: [`docs/implementationPlans/migrate-cicd-to-circleci-research.md`](../i
   - Depends on: Task 0.2
   - Acceptance: Security tab still receives results **or** explicit maintainer sign-off on alternative.
 
-- [ ] **Task 9.2**: Replace Dependabot auto-merge + triage + roadmap-generate + docs-audit
+- [ ] **Task 9.2**: Replace Dependabot auto-merge + triage + docs-audit (roadmap workflows stay on GitHub Actions, decided 2026-09-26)
   - Description: Implement CircleCI (or Renovate) equivalents; wire issue/schedule triggers without leaving required logic on GHA.
   - Files: `.circleci/continue-config.yml`, corresponding GHA deletions
   - Depends on: Task 0.2

package/package.json

@@ -11,7 +11,7 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.6.1",
+    "@terreno/api": "57.8.0",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -104,5 +104,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.6.1"
+  "version": "57.8.0"
 }

package/src/docs/resources/ui.md

@@ -253,7 +253,7 @@ radiusSm, radiusMd, radiusLg, radiusXl, radius2xl, radius3xl
 ## Utilities
 
 ```typescript
-import { useStoredState, MediaQuery, isMobileDevice } from "@terreno/ui";
+import { useStoredState, MediaQuery, isNarrowViewport } from "@terreno/ui";
 
 // Persist state to storage
 const [value, setValue] = useStoredState("key", defaultValue);
@@ -263,9 +263,10 @@ const [value, setValue] = useStoredState("key", defaultValue);
   <DesktopLayout />
 </MediaQuery>
 
-// Device detection
-if (isMobileDevice()) {
-  // Mobile-specific code
+// Current window is below the desktop breakpoint.
+// isMobileDevice() is deprecated in favor of isNarrowViewport().
+if (isNarrowViewport()) {
+  // Narrow-viewport code
 }
 ```
 

package/src/docs/upgrades/57.7.0.md

@@ -0,0 +1,64 @@
+# Upgrading to 57.7.0
+
+**Action required:** No
+**Affected packages:** @terreno/ui
+
+## Summary
+
+Bump every `@terreno/*` package together to `57.7.0`. `@terreno/ui`'s `Filter` is now `DropdownPanel`. Existing `Filter` and `FilterProps` imports keep working until Terreno 58. Panels stay on screen, render through the `TerrenoProvider` portal on native, and accept styled or custom triggers. No Expo upgrade is required if you are already on `57.x`.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+### `Filter` and `FilterProps`
+
+**What changed**
+
+`Filter` is renamed to `DropdownPanel`. `Filter` and `FilterProps` stay exported as deprecated aliases and are removed in Terreno 58. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
+
+**Why**
+
+The control is a general compositional dropdown (trigger, anchored panel, optional Apply/Clear/Cancel footer), not a filter-only widget.
+
+**Migration**
+
+```tsx
+// Before
+import {Filter} from "@terreno/ui";
+
+<Filter label="Status">{children}</Filter>;
+
+// After
+import {DropdownPanel} from "@terreno/ui";
+
+<DropdownPanel label="Status">{children}</DropdownPanel>;
+```
+
+## Changed behavior
+
+### Panels stay on screen and escape clipping
+
+**What changed**
+
+`DropdownPanel` (including the `Filter` alias) right-aligns to its trigger when a left-aligned panel would cross the right viewport edge, clamps to an 8px screen margin, flips above the trigger when there is no usable room below, and scrolls its body with the footer pinned when the content is taller than the space available. On native it renders through the `TerrenoProvider` portal host, so the panel is no longer clipped inside scroll views or cards. Without a host it stays an inline overlay.
+
+**Why**
+
+Left-aligned panels ran off screen, and inline overlays were clipped by parent scroll views.
+
+**Migration**
+
+No call-site change is required. Pass `align` or `maxPanelHeight` to override the automatic layout. Apps that position their own panels can call `computeDropdownPanelLayout`.
+
+## New capabilities
+
+`DropdownPanel` triggers accept `triggerVariant` (any `Button` variant), `applyButtonVariant`, `triggerSize` on labeled triggers, `fullWidth`, and `renderTrigger` for a fully custom trigger.
+
+## Verification
+
+- `bun add` every `@terreno/*` dependency to `57.7.0`, then `bun run compile` at the app root
+- Open a screen that uses `Filter` or `DropdownPanel` and confirm the panel stays inside the viewport, including near the right edge and inside a scrolling parent
+- Replace `Filter` imports with `DropdownPanel` before upgrading to Terreno 58