@terreno/mcp 57.6.1 → 57.8.0

package/src/docs/upgrades/57.8.0.md

@@ -0,0 +1,61 @@
+# Upgrading to 57.8.0
+
+**Action required:** No
+**Affected packages:** @terreno/ui, @terreno/announcements
+
+## Summary
+
+Bump every lockstep `@terreno/*` package together to `57.8.0`. `@terreno/ui` adds opt-in `SplitPage` web layouts and `IconButton` `backgroundOpacity`, and deprecates `isMobileDevice` in favor of `isNarrowViewport` (the old function still returns the same result). `@terreno/announcements` can import a Markdown release pack through `POST /announcements/import-release`. `DropdownPanel` anchors to its trigger, and `/gpt/prompt` emits each generated image once. No Expo upgrade is required if you are already on `57.x`.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+### `isMobileDevice`
+
+**What changed**
+
+`isMobileDevice` is deprecated. `isNarrowViewport` is the supported name. Both stay exported and return the same boolean: true when the window is below the supported desktop floor (web width under 1024, native width under 1024).
+
+**Why**
+
+`isMobileDevice` described a window-width check. The new name matches that behavior.
+
+**Migration**
+
+```typescript
+// Before
+import {isMobileDevice} from "@terreno/ui";
+
+if (isMobileDevice()) {
+  // narrow layout
+}
+
+// After
+import {isNarrowViewport} from "@terreno/ui";
+
+if (isNarrowViewport()) {
+  // narrow layout
+}
+```
+
+## New capabilities
+
+`SplitPage` web props are opt-in. Existing callers keep the previous layout.
+
+- `desktopChildrenMinWidth` keeps one or two desktop children at least that many pixels wide and scrolls the row when it is tighter. More than two children keeps the segmented control.
+- `narrowViewportChildLabels`, `narrowViewportSelectionActive`, `narrowViewportSelectionKey`, and `narrowViewportListButtonLabel` replace the dotted narrow swiper with a labeled pager.
+- `narrowBelowWidth` uses the narrow layout when the window width is less than or equal to that pixel value. Omit it to follow `isNarrowViewport()`.
+- Native `SplitPage` ignores these props.
+- `IconButton` `backgroundOpacity` tints only that button's background.
+
+`@terreno/announcements` accepts a `terreno.announcement-pack/v1` directory (`pack.yaml` plus one Markdown file per announcement) at `POST /announcements/import-release`. Imports are idempotent by product, release version, channel, and slug, default to drafts, and publish immediately when `publish: true`. Admin auth or bearer `ANNOUNCEMENTS_UPLOAD_TOKEN` can call the route. The token is optional.
+
+## Verification
+
+- `bun add` every lockstep `@terreno/*` dependency to `57.8.0`, then `bun run compile` at the app root
+- Replace `isMobileDevice` imports with `isNarrowViewport` before a future major removes the alias
+- Open a `DropdownPanel` whose trigger is not at the start of its row and confirm the panel opens on the trigger
+- Import a draft announcement pack with `POST /announcements/import-release` and confirm a second import updates the same slug instead of inserting a duplicate

package/src/docs/upgrades/58.0.0.md

@@ -2,6 +2,10 @@
 
 This file is a placeholder until Terreno 58 is cut. When that release ships, expand this page into a full upgrade note.
 
+## `Filter` and `FilterProps` are removed
+
+`@terreno/ui` removes the `Filter` and `FilterProps` aliases added as deprecations in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps`. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names. See [57.7.0](57.7.0.md).
+
 ## HTTP rate limiting defaults on
 
 `TerrenoApp` will enable HTTP rate limiting by default (memory store unless you pass `store`). Apps that must stay unlimited must pass an explicit off once 58 defines that API.

package/src/docs/versioned/next/explanation/example-coverage.md

@@ -20,6 +20,7 @@ that file (and its imports) to a working example. Gaps stay explicit.
 | Feature flags + live updates | yes — `FeatureFlagsApp` in `example-backend/src/server.ts`, seed `example-backend/src/scripts/seed-feature-flags.ts` | yes — `useTerrenoFeatureFlags` in `example-frontend/app/_layout.tsx` | Socket-backed live updates share the realtime connection. |
 | Websockets / realtime | yes — `RealtimeApp` in `example-backend/src/server.ts`, `example-backend/src/websockets.ts` | yes — `useSocketConnection` in `example-frontend/app/_layout.tsx` | Sync deltas also use the socket (`SyncApp` + `@terreno/syncdb`). |
 | Consent forms | yes — `example-backend/src/consentDefinitions.ts`, seed scripts | yes — `example-frontend/app/(tabs)/consents.tsx`, admin `example-frontend/app/admin/consent-forms/` | First-login flow is covered by e2e (`example-frontend/e2e/consents.spec.ts`). |
+| Product announcements | yes — `AnnouncementsApp` in `example-backend/src/server.ts`, release upload token via `ANNOUNCEMENTS_UPLOAD_TOKEN`, seed `example-backend/src/scripts/seed-announcements.ts`, sample release pack `example-backend/announcements/releases/1.14.0/` with `bun run announcements:pack` | yes — `AnnouncementNavigator` in `example-frontend/app/_layout.tsx` and admin announcement routes | Release packs support multiple Markdown surfaces and idempotent draft or explicit live API import. |
 | File upload / GCS | yes — `example-backend/src/api/settings.ts`, AI file routes in `example-backend/src/api/ai.ts` | yes — `example-frontend/app/(tabs)/files.tsx`, `example-frontend/app/gcs-settings.tsx` | |
 | Better Auth | yes — `example-backend/src/utils/betterAuthConfig.ts`, `BetterAuthApp` in `example-backend/src/server.ts` | yes — `example-frontend/app/login.tsx`, `example-frontend/lib/betterAuth.ts` | Default `AUTH_PROVIDER` is `better-auth`. |
 | syncdb local-first | yes — `SyncApp` in `example-backend/src/server.ts` | yes — `example-frontend/store/syncdb.ts`, `example-frontend/app/(tabs)/index.tsx` | PR #869 closed without merge; `@terreno/syncdb` shipped on the launch line and is the example todos path. |

package/src/docs/versioned/next/explanation/loop-engineering.md

@@ -49,7 +49,7 @@ the inner loop until the approved task list is done. Roast never invokes Pick. B
 Taste additionally wait while async review bots are running, preferring provider CLI
 watch hooks or harness event subscriptions over timer polling. Taste also waits in a
 loop for product CI with `gh` or `circleci` until jobs are terminal or the wait times
-out. Before any push it always pulls latest `master`, then records last-run failed tests
+out. Before any push it fetches latest `master` (merging it only when needed), then records last-run failed tests
 and re-verifies them locally, then runs the repository's root
 `prepush` package script in a no-context subagent when present (falling back to affected
 package lint, typecheck, and tests), then pushes and watches CI.
@@ -82,8 +82,8 @@ acceptance criteria. Taste is one reactive iteration, not an unbounded fix-until
 daemon. It waits until async review bots (Bugbot, CodeQL, and similar) on the current
 head have reported, 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 it always pulls latest
-`master`, records last-run failed tests and re-verifies them locally, then runs root
+jobs are terminal or the wait times out. Before any push it fetches latest
+`master` (merging it only when needed), records last-run failed tests and re-verifies them locally, then runs root
 `prepush` when present in a fresh subagent with no parent
 conversation. If absent, it proves affected-package lint, typecheck, and tests instead.
 It then pushes and watches CI, emits `PASS`, `FAIL`, `BLOCKED`, or `PENDING`, and exits.
@@ -139,6 +139,35 @@ or transports it and Brew excludes it from commits unless repository policy says
 otherwise. Stage results follow the plugin's JSON-schema-backed YAML contract and never
 contain chain-of-thought or transcripts.
 
+## Commits and pushes
+
+Every pushed commit starts a full CI run. Harnesses such as Cursor cloud agents push
+every commit automatically, so commit count turns directly into CI runs. Before these
+rules, one 30-commit dashboard PR had ten "mark slice roasted" commits and ten "harden"
+follow-ups, and `ui-ci` stayed red on every commit after the first.
+
+- One behavior-scoped commit per task, after Roast `PASS`: code, tests, docs, and the
+  task-file mark together. Roast-driven fixes fold into that commit.
+- Progress lives in execution state, not in standalone task-file commits.
+- Pick and Roast never push. Brew pushes once. Taste pushes at most once per reaction.
+- Pick does not continue on a head whose product CI shows a branch-caused failure.
+- Pick lists a behavior's edge cases before coding, so Roast proves them instead of
+  discovering them.
+- Roast runs the gate CI will run (root `prepush`, which mirrors the triggered CI jobs),
+  not only the task's test file.
+- Taste fetches `master` before every push but merges it only when the PR conflicts, a
+  failure traces to base drift, or the branch is otherwise merge-ready.
+
+## Direct invocation
+
+Outer loops (`terreno-planning-loop`, `terreno-taste-sweep`) consume Taste `PENDING`
+and invoke Taste again. When a human invokes Taste directly, no loop is waiting, so a
+`PENDING` would only tell them to come back later. In that case Taste uses
+**standalone entry**: it waits in-process with native watches and reacts again. It
+stops on `PASS`, `BLOCKED`, or `FAIL`, or after 3 fix pushes or 3 hours of waiting,
+which ends as `BLOCKED` with one concrete human action. A directly invoked Brew
+starts Taste as its next stage instead of exiting.
+
 ## Retry and stop rules
 
 - Pick implements one task, Roast proves it, then Pick takes the next unblocked task.

package/src/docs/versioned/next/explanation/model-router-actions.md

@@ -101,7 +101,7 @@ HTTP method and scope map to a CRUD permission check:
 **403** — denied after the instance document is loaded (e.g. `IsOwner` with a document that fails the check).  
 **401** — unauthenticated when a permission requires auth (from existing auth middleware).
 
-`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD.
+`authenticateMiddleware` honors the router’s `allowAnonymous` option, same as CRUD. An action may set `allowAnonymous: true` to accept unauthenticated requests without making the router's CRUD routes or other actions anonymous. Keep a non-empty permission such as `Permissions.IsAny` and authenticate any service token in the handler.
 
 ## Validation
 

package/src/docs/versioned/next/explanation/repository-settings.md

@@ -51,11 +51,18 @@ as GitHub App checks; they are not CircleCI jobs.
 
 **Path:** Settings → Environments
 
-Same-repo PR jobs in `cd.yml` (`Terraform preview`, `Tasks deploy (preview)`,
-`Backend deploy (preview)`) skip when `head.repo.full_name != github.repository`.
-Also restrict the `gcp-cd-preview` environment (create it on first deploy if missing) with a
-**deployment branch policy** or **required reviewers** so a fork that edits
-`cd.yml` cannot mint a prod WIF token.
+`cd.yml` is disabled; CircleCI `gcp-cd-preview` performs GCP previews and
+halts on fork PRs. While the GitHub WIF provider still exists, keep the
+`gcp-cd-preview` environment restricted with a **deployment branch policy** or
+**required reviewers** so a fork that re-enables `cd.yml` cannot mint a prod
+WIF token.
+
+### Actions secrets for CircleCI hooks
+
+`preview-cleanup.yml` (PR close) and `publish-on-tag.yml` (manual publish demo
+redeploy) start CircleCI pipelines. Set the secret `CIRCLECI_TOKEN` and the
+variable `CIRCLECI_PIPELINE_DEFINITION_ID` under Settings → Secrets and
+variables → Actions.
 
 ## Merge settings
 

package/src/docs/versioned/next/explanation/roadmap-process.md

@@ -88,11 +88,10 @@ half applies:
 | 1 | Announcements | Announcement | Maintainers only | Official release notes, breaking changes, deprecations, and launch updates from the Terreno team. |
 | 2 | Q&A | Question / Answer | Anyone | Ask how to use Terreno. Search existing threads first; accepted answers may become how-to guides in `docs/how-to/`. |
 | 3 | Ideas | Open-ended | Anyone | Feature ideas and improvements before they are shaped. This is the intake funnel — do not open a tracking issue until a maintainer promotes your idea. |
-| 4 | Hacktoberfest | Open-ended | Anyone | Pitch something to build during Hacktoberfest and upvote the ideas you want. Popular, well-scoped ideas become `hacktoberfest` issues anyone can pick up. |
-| 5 | Agents & AI | Open-ended | Anyone | MCP setup, Cursor/Claude skills, agent workflows, and prompt patterns for building with Terreno. |
-| 6 | RFCs | Open-ended | Anyone | Substantial proposals that change public API or add packages. Use the RFC discussion template; accepted RFCs become IPs. |
-| 7 | Show and tell | Open-ended | Anyone | Apps and experiments built with Terreno. Share what you shipped and what friction you hit. |
-| 8 | Docs feedback | Open-ended | Anyone | Report missing or confusing documentation. Link the page URL; recurring feedback becomes docs PRs. |
+| 4 | Agents & AI | Open-ended | Anyone | MCP setup, Cursor/Claude skills, agent workflows, and prompt patterns for building with Terreno. |
+| 5 | RFCs | Open-ended | Anyone | Substantial proposals that change public API or add packages. Use the RFC discussion template; accepted RFCs become IPs. |
+| 6 | Show and tell | Open-ended | Anyone | Apps and experiments built with Terreno. Share what you shipped and what friction you hit. |
+| 7 | Docs feedback | Open-ended | Anyone | Report missing or confusing documentation. Link the page URL; recurring feedback becomes docs PRs. |
 
 ### Pinned posts
 
@@ -127,24 +126,29 @@ When an answer repeats, maintainers turn it into a how-to doc via PR.
 - Do **not** open a feature issue directly — maintainers promote accepted ideas to tracked issues on the [Terreno Roadmap](https://github.com/TerrenoLabs/terreno/projects) board.
 - For API/package-level design, use the **RFCs** category instead.
 - Bugs → [Bug report](https://github.com/TerrenoLabs/terreno/issues/new?template=bug_report.yml).
+- **Hacktoberfest pitches live here too.** Tick the Hacktoberfest box on the form; maintainers apply the [`hacktoberfest`](https://github.com/TerrenoLabs/terreno/discussions?discussions_q=label%3Ahacktoberfest) label. 👍 the pitches you want built.
 ```
 
-#### Hacktoberfest
+#### Hacktoberfest (inside Ideas)
 
-```markdown
-**Pitch Hacktoberfest ideas here, and 👍 the ones you want built.**
-
-1. [Start a Hacktoberfest discussion](https://github.com/TerrenoLabs/terreno/discussions/new?category=hacktoberfest) — the form asks for the idea, area, rough size, and what "done" looks like.
-2. Upvote and comment on other pitches. Upvotes are how maintainers rank them.
-3. Maintainers turn popular, well-scoped ideas into issues labeled [`hacktoberfest`](https://github.com/TerrenoLabs/terreno/issues?q=is%3Aissue+is%3Aopen+label%3Ahacktoberfest) and link them back here. Pick one up by commenting on the issue.
+Hacktoberfest does not get its own category. Pitches are Ideas discussions carrying the
+`hacktoberfest` label, so upvotes, promotion, and search all use the same path as any other
+idea.
 
-Longer-term feature ideas → **Ideas**. Bugs → [Bug report](https://github.com/TerrenoLabs/terreno/issues/new?template=bug_report.yml).
-```
+1. [Start an Ideas discussion](https://github.com/TerrenoLabs/terreno/discussions/new?category=ideas)
+   and tick **This is a Hacktoberfest pitch**. Give the area, rough size, and what "done" looks
+   like.
+2. A maintainer applies the [`hacktoberfest`](https://github.com/TerrenoLabs/terreno/discussions?discussions_q=label%3Ahacktoberfest)
+   label and the matching `area:*` label. Upvotes are how maintainers rank pitches.
+3. Popular, well-scoped pitches become issues labeled
+   [`hacktoberfest`](https://github.com/TerrenoLabs/terreno/issues?q=is%3Aissue+is%3Aopen+label%3Ahacktoberfest),
+   linked back to the discussion. Pick one up by commenting on the issue.
 
-Promotion follows the Ideas path, with one change: a Hacktoberfest idea small enough to finish
+Promotion follows the Ideas path, with one change: a Hacktoberfest pitch small enough to finish
 in a weekend becomes a `hacktoberfest` + `good first issue` work item directly (see
 [GitHub issue lifecycle](../how-to/github-issue-lifecycle.md)) instead of a `Shaping` roadmap
-item. Larger ones go through `roadmap-promote` like any other idea.
+item. Larger ones get `hacktoberfest` + `help wanted` and go through `roadmap-promote` like any
+other idea.
 
 #### Agents & AI
 
@@ -397,10 +401,10 @@ do not claim completion until done.
 
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
-| [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present |
+| [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present; `area:*` / `type:*` labels the issue was opened with win, so `roadmap:sync` issues are not asked for an area |
 | [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when it changes |
 | [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
-| [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, push to the board, regenerate `ROADMAP.md` |
+| [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, add an entry for every new IP, open its tracking issue, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving
 them produces confusing partial states. After the group lock is acquired, each job refreshes
 to the latest branch HEAD so a queued `roadmap-sync` cannot overwrite statuses that
@@ -413,7 +417,7 @@ The full loop, each arrow with exactly one writer:
 
 ```
 docs/implementationPlans/*.md ──roadmap:reconcile──▶ roadmap-seed-issues.md
-docs/tasks/*.md                    (Status only)              │
+docs/tasks/*.md              (Status + new entries)           │
                                                          roadmap:sync
                                                               ▼
                                                         Project board
@@ -439,6 +443,24 @@ reported by `--check` and is never overwritten. Cards that are not in
 [`roadmap-seed-issues.md`](roadmap-seed-issues.md) are also `--check` failures; apply does
 not delete them. Maintainers own the board's *state* and `Community interest`.
 
+**New IPs reach the roadmap on merge.** When a merged plan has no entry,
+`roadmap:reconcile --fix` scaffolds one: the title from the IP's H1, the summary from the first
+paragraph of `## Goal`, and links to the IP and its task list (when `docs/tasks/<slug>.md`
+exists). Area, Target, and Impact come from an optional IP header:
+
+```markdown
+**Roadmap:** Area=`api`, Target=`Next`, Impact=`Feature`
+```
+
+Without that header they are inferred: Area from the packages named in the header block
+(default `dx`); Target `Released` for shipped work, `Future` for drafts, `58` when a
+`**Target:**` line names 58, otherwise `Next`; Impact `Breaking` when the `**Target:**` line
+says so, otherwise `Feature`. Edit the scaffolded section afterward if a guess is wrong. The
+workflow then runs `roadmap:sync --create-missing-ip-issues`, which opens a tracking issue
+only for entries backed by an IP. Drafts land as `Shaping`. Moving an entry to `Shipped` also
+moves its Target to `Released`. `ROADMAP.md` links each entry's IP and, when one exists, its
+task list.
+
 **Status automation is monotonic.** `roadmap:reconcile --fix` advances status and applies
 supersessions, but never walks a status backwards and never revives declined work. IP headers
 go stale far more often than boards do — several plans still read `Draft` for work that