terp-cli 0.30.0__tar.gz → 0.32.0__tar.gz

{terp_cli-0.30.0 → terp_cli-0.32.0}/PKG-INFO

@@ -1,19 +1,19 @@
 Metadata-Version: 2.5
 Name: terp-cli
-Version: 0.30.0
+Version: 0.32.0
 Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
 Project-URL: Repository, https://github.com/AITT-NL/terp-framework
 Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
 License-Expression: Apache-2.0
 Requires-Python: >=3.13
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: terp-arch==0.30.0
-Requires-Dist: terp-core==0.30.0
-Requires-Dist: terp-migrations==0.30.0
+Requires-Dist: terp-arch==0.32.0
+Requires-Dist: terp-core==0.32.0
+Requires-Dist: terp-migrations==0.32.0
 Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.30.0; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.30.0; extra == 'jobs'
+Requires-Dist: terp-cap-outbox==0.32.0; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.32.0; extra == 'jobs'
 Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.30.0; extra == 'scheduler'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.32.0; extra == 'scheduler'
 Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.30.0; extra == 'worker'
+Requires-Dist: terp-cap-outbox==0.32.0; extra == 'worker'

{terp_cli-0.30.0 → terp_cli-0.32.0}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.30.0"
+version = "0.32.0"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.30.0",
+    "terp-core==0.32.0",
     # `terp migrate` delegates to terp-migrations (lazily imported), keeping Alembic
     # off the path for `terp inspect` / `terp guide` while making migrations work.
-    "terp-migrations==0.30.0",
+    "terp-migrations==0.32.0",
     # `terp guide rules` projects the live rule registry; terp-arch is imported lazily
     # (only when that topic is rendered), so it stays off the common `terp guide` path.
-    "terp-arch==0.30.0",
+    "terp-arch==0.32.0",
     # `terp verify --only env-seams` and `terp smoke` read the compose profiles as data
     # (anchors and `<<:` merge keys resolved), so both answer without a Docker daemon or
     # even the `docker` binary. Declared explicitly rather than leant on: every app
@@ -29,11 +29,11 @@ dependencies = [
 # or a scheduler engine into apps that only use inspect/check/migrate. Deployments can select
 # one process role, while `jobs` is the convenient complete jobs-process bundle.
 [project.optional-dependencies]
-worker = ["terp-cap-outbox==0.30.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.30.0"]
+worker = ["terp-cap-outbox==0.32.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.32.0"]
 jobs = [
-    "terp-cap-outbox==0.30.0",
-    "terp-cap-scheduler-apscheduler==0.30.0",
+    "terp-cap-outbox==0.32.0",
+    "terp-cap-scheduler-apscheduler==0.32.0",
 ]
 
 [project.scripts]

{terp_cli-0.30.0 → terp_cli-0.32.0}/src/terp/cli/__init__.py

@@ -1797,8 +1797,9 @@ Frontend module screens (@terpjs/react-core)
   insertAdjacentHTML/document.write) are refused — render text, or Markdown from
   @terpjs/react-core for rich text; eval() / new Function() are refused; javascript:
   URLs in href/src are refused; a static target="_blank" link needs rel="noopener".
-- Every routed view renders a page archetype (Page / OverviewPage / DetailPage / HubPage);
-  buildAppRouter refuses an unframed view at runtime, fail closed. An app can ratchet
+- Every routed view renders a page archetype (Page / OverviewPage / DetailPage / HubPage /
+  DashboardPage / FormPage / SettingsPage / SplitPage); buildAppRouter refuses an unframed
+  view at runtime, fail closed. An app can ratchet
   further with an opt-in slot-typed layout contract (terp guide layouts).
 - Route paths and params are CHECKED, from generated types (ADR 0092). The router is built
   at runtime from the manifests, so nothing type-checks a path or a param name until you
@@ -1940,11 +1941,16 @@ Theming and branding (design tokens, palettes, the brand mark)
   refuses `style={}`, `className` and module stylesheets: a module that painted itself
   would not follow the palette. Modules never need theme-specific code.
 - THE SHIPPED PALETTES, plus "system":
-      light  dark  midnight  twilight  contrast
-  `contrast` is a high-contrast light set. The active one is `data-theme` on <html>;
-  the shell header's theme toggle offers all five plus "system" (follow the viewer's
-  own platform preference) and persists the choice. `system` resolves to the dark set
-  when the platform asks for dark.
+      midday  twilight  evening  night  contrast
+  Named for the time of day they suit: midday is the light set, twilight a dimmed dark,
+  evening the slate dark, night the near-black dark. `contrast` is a high-contrast light
+  set. The active one is `data-theme` on <html>; the shell header's theme toggle offers all
+  five plus "system" (follow the viewer's own platform preference) and persists the choice.
+  `system` resolves to `night` when the platform asks for dark.
+  `light`, `dark` and `midnight` are the EARLIER names of midday, evening and night. They
+  are still accepted wherever a theme is named (defaultTheme, a stored choice, data-theme)
+  and resolve to the new name -- but the theme toggle now writes the new names, so a
+  selector in your own theme.css must use them: `[data-theme="dark"]` no longer matches.
 - TO CHANGE HOW YOUR APP LOOKS, redefine tokens in `frontend/src/theme.css`. It is
   imported last and therefore wins the cascade. Declare only what you are changing;
   everything else falls back to the framework's value.
@@ -1954,17 +1960,38 @@ Theming and branding (design tokens, palettes, the brand mark)
   depart from a house style, declare the token in theme.css; nothing takes that back.
 
       :root { --color-brand-primary: #2563eb; }
-      [data-theme="dark"] { --color-brand-primary: #60a5fa; }
+      [data-theme="evening"] { --color-brand-primary: #60a5fa; }
 
   Per palette, use that palette's selector. A token with no palette selector is
   declared in `:root` and governs every palette at once — which is what you want for
   spacing, corners and typography, and usually not what you want for a colour.
-- TO SHIP ON A PALETTE OTHER THAN light, name it in the layout declaration — never by
+- THE PAGE'S BACKGROUNDS MOVE AS A SET (ADR 0169). `--color-bg-canvas` is the page,
+  `--color-bg-subtle` the containers and chrome on it — boxed cards, hub tiles, the page
+  band — and `--color-bg-surface` where data is read: tables, and charts and figures as
+  they land. Every shipped palette declares all three, with subtle the midpoint of the
+  other two. A token in theme.css does not recompute another, so a theme that moves canvas
+  or surface redeclares subtle as well, usually as their midpoint; otherwise its containers
+  keep the shipped tone, between two rungs the app no longer has.
+
+      :root {
+        --color-bg-canvas: #e8eef8;
+        --color-bg-subtle: #f4f7fc;
+        --color-bg-surface: #ffffff;
+      }
+
+  The page's summary band — the figures under its title — sits on its own token,
+  `--color-bg-summary`, which every palette ships at its brand soft tint (night's a step
+  darker, so subtle text clears AA on it). It is a value of its own, not a reference: a theme
+  that moves `--color-brand-primary-soft` for a new brand moves `--color-bg-summary` with it,
+  or the band keeps the shipped blue; a theme that wants a calmer band moves this one token
+  and the tint the hub tiles share stays where it is.
+
+- TO SHIP ON A PALETTE OTHER THAN midday, name it in the layout declaration — never by
   restyling one palette to imitate another:
 
-      frontend/layout-contract.json -> { "defaultTheme": "midnight" }
+      frontend/layout-contract.json -> { "defaultTheme": "night" }
 
-  Legal values are the five above plus "system". Passing `defaultTheme` as a bootstrap
+  Legal values are the palettes named above, plus "system". Passing `defaultTheme` as a bootstrap
   option as well is refused (terp guide layouts). Your organisation's styling tool may
   seed this key; changing it here makes it yours and later rollouts leave it alone.
 
@@ -1975,7 +2002,7 @@ Theming and branding (design tokens, palettes, the brand mark)
   so declare it on the document as well and the app opens in its own palette with no
   flash either:
 
-      frontend/index.html -> <html lang="en" data-theme="midnight">
+      frontend/index.html -> <html lang="en" data-theme="night">
 
   Both halves are the same fact, in the two places that can each answer at a different
   moment: the attribute is there before anything runs, and the script overrides it only
@@ -1997,9 +2024,18 @@ Theming and branding (design tokens, palettes, the brand mark)
   a palette may vary it). Spacing, corners, typography, motion and z-index are
   theme-INVARIANT by design — declare them once in `:root`. An app whose spacing
   changed when someone switched palette is not what anyone means by a theme.
-- CONTRAST is measurable, so measure it: @terpjs/contract carries a WCAG contrast suite
-  over the shipped palettes. If you override a foreground or a background, check the
-  pairing rather than trusting the eye.
+- CONTRAST is measurable, so measure it. @terpjs/contract holds every pairing the shipped
+  palettes paint to two models (ADR 0170): the WCAG ratio, and APCA lightness contrast at
+  the level the text's reading asks for -- Lc 90 for body text, 75 for secondary text a
+  reader still has to take in (a label, a hint, a link, a badge), 60 for a count or a
+  position. The manifest publishes both: each of `textPairs` names its `reading`, and
+  `apca.minimumLc` the floors. If you override a foreground or a background, check its
+  pairings against both rather than trusting the eye: WCAG's ratio alone passes light text
+  on a dark ground that reads poorly. In module code the same split is `Text`'s tone:
+  `muted` for anything read, `subtle` only for what orients.
+- A CONTROL'S OUTLINE is `--color-border-strong`, held at 3:1 against the surfaces controls
+  sit on. Move that token to retune the edge of every input, select and secondary button;
+  `--color-neutral-300` is the scrollbar and disabled ink, not a border.
 """,
     "layouts": """\
 Layout contracts (slot-typed layouts, ADR 0079)
@@ -2049,15 +2085,65 @@ Layout contracts (slot-typed layouts, ADR 0079)
       DetailPage   -> DetailList / DetailListGroup / Stack / Grid / Tabs / ModuleNav /
                       DataView / Card / Divider / Text + the same framework states and
                       ConfirmDialog
-  Grid is a DETAIL-body component and not an overview one, deliberately: an overview
-  body is a data collection, and a grid of summary cards is a hub — which has its own
-  archetype. Heading is admitted nowhere: a heading in a governed body must OWN its
+      FormPage     -> Stack / Grid / Card / Divider / Text + the same states and
+                      ConfirmDialog: a form body is a container (Stack as="form"), never
+                      a loose run of Fields
+      SettingsPage -> Card / Stack / Divider / Text + the same states and ConfirmDialog:
+                      Card sections, no collection
+      SplitPage    -> SplitPane only: a list beside the record it selects
+      DashboardPage -> Grid / Stack / Card / DataView / Stat / StatGroup / TrendChart /
+                      BarChart / ProportionBar / StatusHistory / Timeline / Divider / Text +
+                      the same states and ConfirmDialog: "how is the whole doing", its
+                      figures in the summary band
+  Grid is not an overview-body component, deliberately: an overview body is a data
+  collection, a grid of cards into each area is a hub, and sections of figures and charts
+  are a dashboard — each has its own archetype. Heading is admitted nowhere: a heading in a governed body must OWN its
   section, and Card (boxed, or variant="plain" for no chrome) is how a section is
   owned; a bare heading with siblings after it is a grouping the check cannot see.
-  The plain Page stays unconstrained — it is the sanctioned home for a bespoke screen.
-  Only the slot's DIRECT children are governed: an allowed container's own subtree
+  The plain Page's BODY stays unconstrained — it is the sanctioned home for a bespoke
+  screen. Only the slot's DIRECT children are governed: an allowed container's own subtree
   (a Card's body, a Stack's rows) is yours to compose — nesting content inside an
   allowed component is sanctioned composition, not an escape.
+- Two rules belong to the page FRAME rather than to a body, so they hold on every page,
+  the plain Page included (ADR 0169 §4):
+      summary   -> Stat / StatGroup / StatusHistory / Badge / Text only: the band under
+                   the title holds the page's own figures, nothing else
+      headline  -> at most ONE figure per page is the headline (the brand-filled one);
+                   the lint counts a page element's static JSX, the runtime the rendered
+                   page, and both say the fix
+- Compose a page from the shape of its data (ADR 0169). Decide what each block IS and use
+  the component made for it — there are no style variants to pick, and the framework owns
+  how each one looks:
+      the figures the page is about   -> a StatGroup in the page's `summary`
+      one figure, with its context    -> Stat: `delta` (the sentiment is yours to declare —
+                                         more rejections is up and bad), `trend` (a
+                                         sparkline), `target` (a range, drawn as a Meter)
+      the figure that matters most    -> Stat `headline`, once per page
+      facts about one record          -> DetailList
+      values over time                -> TrendChart: mark "line", "area" or "columns",
+                                         `comparison` for the period before
+      categories compared             -> BarChart, ranked before it is passed
+      a whole and its parts           -> ProportionBar, each part a word with its share
+      how recent runs ended           -> StatusHistory, or `history` on a DataView column
+      events in order                 -> Timeline: a record's history, newest first
+      a collection                    -> DataView (the brightest object on the page)
+      a section beside another        -> Grid template="2:1" ("1:2", "3:1", or the equal
+                                         "1:1" / "1:1:1" / "1:1:1:1"), which collapses on a
+                                         phone where columns={4} would clip
+  Contrast is that ranking — the figures in their band, containers stepped back onto
+  --color-bg-subtle, the data forward on the surface — so a block that should stand out
+  is a different shape of data, not a custom colour.
+- Pick the archetype by the question the page answers: a landing that only leads into the
+  app's areas is a HubPage; one area's collection (how each one is doing) an OverviewPage;
+  how the whole is doing a DashboardPage -- a landing that also carries the app's figures is
+  one, as the hub preset scaffolds it; one record a DetailPage; entering a record a
+  FormPage; settings a SettingsPage; a list beside the record it selects a SplitPage.
+- Alternate framed and unframed blocks. The frame belongs to the data a reader works with:
+  a collection, a chart and a lone figure sit on the surface, the collection brightest. A
+  boxed Card steps back onto --color-bg-subtle, for a group of controls or one section of
+  a record. Much of a page needs no frame at all: a StatGroup's figures, a DetailList, a
+  Timeline, a line of Text, a titled section as Card variant="plain". A page that boxes
+  every block in a Card reads as one object repeated, however good each block is.
 - Enforcement (never lint-only):
       build time  -> the terp/layout-contract ESLint rule checks the static JSX
                      children of each governed archetype (npm --prefix frontend run lint)

{terp_cli-0.30.0 → terp_cli-0.32.0}/src/terp/cli/docker.py

@@ -29,6 +29,8 @@ import subprocess
 from collections.abc import Callable, Sequence
 
 from terp.cli import ports
+from terp.cli._output import emit
+from terp.cli.docker_masks import clear_stale_masks
 
 _DEFAULT_COMPOSE = "docker-compose.yml"
 
@@ -229,6 +231,18 @@ def run_docker_dev_command(
     _, note = ports.ensure_assigned(path.parent)
     if note:
         print(note)
+    # Before `watch` creates anything: a workbench from before 0.30.0 holds its
+    # node_modules mask as a volume, which Compose would reattach over the tmpfs the
+    # compose file now declares and keep serving old packages from
+    # (terp.cli.docker_masks). No docker on PATH is `watch`'s to report, in its own
+    # words, not this check's.
+    try:
+        cleared = clear_stale_masks(path, project_name=project_name, capture=capture or _capture)
+    except OSError:
+        cleared = ""
+    if cleared:
+        # Through the CLI's one output seam, and flushed: `watch` holds the terminal next.
+        emit(cleared)
     status = (runner or _run)(docker_dev_argv(path, project_name=project_name))
     message = f"docker compose watch exited with status {status}"
     if status == 0:

terp_cli-0.32.0/src/terp/cli/docker_masks.py

@@ -0,0 +1,167 @@
+"""A mask the compose file declares as ``tmpfs`` that a running workbench still holds as a volume.
+
+0.30.0 turned the frontend's ``node_modules`` mask from an anonymous volume into a
+``tmpfs``, so that a dependency bump reaches the running dev server. A workbench that
+was already up before the upgrade does not get it. When Compose recreates a container
+it reattaches the old container's anonymous volumes by target path, and that wins over
+the ``tmpfs`` now declared at the same path. The dev server then keeps serving the
+first boot's packages from that volume, with every container healthy and the page
+answering 200. An upgraded-on-paper workbench and an upgraded one look identical.
+
+Compose owns that reattachment, so the place to undo it is before ``watch`` creates
+anything. For every service whose mount at a ``tmpfs`` path is still a volume, the
+container is removed, and so is that volume and only that one. Compose then creates
+both fresh, with the ``tmpfs``. The volume held nothing but a copy of the image's
+packages: the mask exists to hide the checkout's ``node_modules``, never to keep one.
+A named volume is never touched, and neither is any other volume of the container.
+
+Best effort, like the failure diagnosis next door: a daemon that is not up, a compose
+file Compose cannot read, or a ``ps`` with no containers yet means there is nothing to
+undo, and ``watch`` speaks for itself.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from collections.abc import Callable, Sequence
+
+#: Runs argv, returning ``(exit status, combined output)``.
+Capture = Callable[[Sequence[str]], tuple[int, str]]
+
+
+def _compose(compose_file: pathlib.Path, project_name: str | None) -> list[str]:
+    argv = ["docker", "compose", "-f", str(compose_file)]
+    if project_name:
+        argv += ["-p", project_name]
+    return argv
+
+
+def _json_entries(output: str) -> list[dict]:
+    """A JSON array, one object, or newline-delimited objects, as Compose has printed each."""
+    stripped = output.strip()
+    if not stripped:
+        return []
+    try:
+        parsed = json.loads(stripped)
+    except json.JSONDecodeError:
+        entries = []
+        for line in stripped.splitlines():
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return [entry for entry in entries if isinstance(entry, dict)]
+    items = parsed if isinstance(parsed, list) else [parsed]
+    return [entry for entry in items if isinstance(entry, dict)]
+
+
+def tmpfs_targets(config_output: str) -> dict[str, frozenset[str]]:
+    """Per service, the paths ``docker compose config --format json`` declares as ``tmpfs``.
+
+    Both spellings count: a ``volumes`` entry of ``type: tmpfs``, and the service-level
+    ``tmpfs:`` list (whose entries may carry ``:options`` after the path).
+    """
+    try:
+        config = json.loads(config_output)
+    except json.JSONDecodeError:
+        return {}
+    services = config.get("services") if isinstance(config, dict) else None
+    if not isinstance(services, dict):
+        return {}
+    found: dict[str, frozenset[str]] = {}
+    for name, service in services.items():
+        if not isinstance(service, dict):
+            continue
+        targets = {
+            volume["target"]
+            for volume in service.get("volumes") or ()
+            if isinstance(volume, dict)
+            and volume.get("type") == "tmpfs"
+            and isinstance(volume.get("target"), str)
+        }
+        listed = service.get("tmpfs") or ()
+        for entry in [listed] if isinstance(listed, str) else listed:
+            if isinstance(entry, str) and entry:
+                targets.add(entry.split(":", 1)[0])
+        if targets:
+            found[name] = frozenset(targets)
+    return found
+
+
+def containers(ps_output: str) -> dict[str, str]:
+    """Service name to container id, from ``docker compose ps --all --format json``."""
+    found: dict[str, str] = {}
+    for entry in _json_entries(ps_output):
+        service, container = entry.get("Service"), entry.get("ID")
+        if isinstance(service, str) and isinstance(container, str) and container:
+            found.setdefault(service, container)
+    return found
+
+
+def stale_volumes(inspect_output: str, targets: frozenset[str]) -> tuple[str, ...]:
+    """The volumes ``docker inspect`` shows mounted at a path that should be a ``tmpfs``.
+
+    Only a volume counts, never a bind: a bind at that path is somebody's deliberate
+    choice, and removing it is not this command's to decide.
+    """
+    names: list[str] = []
+    for container in _json_entries(inspect_output):
+        for mount in container.get("Mounts") or ():
+            if (
+                isinstance(mount, dict)
+                and mount.get("Type") == "volume"
+                and mount.get("Destination") in targets
+                and isinstance(mount.get("Name"), str)
+                and mount["Name"] not in names
+            ):
+                names.append(mount["Name"])
+    return tuple(names)
+
+
+def clear_stale_masks(
+    compose_file: pathlib.Path,
+    *,
+    project_name: str | None = None,
+    capture: Capture,
+) -> str:
+    """Undo a pre-0.30.0 ``node_modules`` volume before ``watch``; what was done, or ``""``."""
+    compose = _compose(compose_file, project_name)
+    status, config = capture([*compose, "config", "--format", "json"])
+    targets = tmpfs_targets(config) if status == 0 else {}
+    if not targets:
+        return ""
+    status, ps_output = capture([*compose, "ps", "--all", "--format", "json"])
+    running = containers(ps_output) if status == 0 else {}
+    stale: dict[str, tuple[str, ...]] = {}
+    for service, paths in sorted(targets.items()):
+        container = running.get(service)
+        if container is None:
+            continue
+        status, inspected = capture(["docker", "inspect", container])
+        volumes = stale_volumes(inspected, paths) if status == 0 else ()
+        if volumes:
+            stale[service] = volumes
+    if not stale:
+        return ""
+    services = sorted(stale)
+    volumes = [volume for service in services for volume in stale[service]]
+    listing = ", ".join(repr(service) for service in services)
+    removed, _ = capture([*compose, "rm", "--stop", "--force", *services])
+    if removed == 0:
+        removed, _ = capture(["docker", "volume", "rm", *volumes])
+    if removed != 0:
+        renew = [*compose, "up", "-d", "--no-deps", "--force-recreate", "--renew-anon-volumes"]
+        return (
+            f"terp docker dev: {listing} still mount(s) a volume where the compose file "
+            "declares a tmpfs (a workbench from before 0.30.0), so the dev server would keep "
+            "serving its old packages. Removing it failed; once, by hand:\n"
+            f"  {' '.join([*renew, *services])}\n"
+            f"  docker volume rm {' '.join(volumes)}"
+        )
+    return (
+        f"terp docker dev: {listing} still mounted a volume where the compose file declares "
+        "a tmpfs (a workbench from before 0.30.0), so the dev server kept serving the packages "
+        "it first booted with. Removed the container and that volume; this start creates both "
+        "fresh."
+    )

{terp_cli-0.30.0 → terp_cli-0.32.0}/src/terp/cli/verify.py

@@ -1043,6 +1043,24 @@ def _node_modules_problem(root: pathlib.Path, workspace: str) -> str | None:
     except (OSError, ValueError):
         return None
 
+    # A directory with none of the lockfile's platform-neutral packages in it is not
+    # a tree for another platform but no tree at all -- an install that never ran,
+    # or a fresh mount point. Calling it "a different platform" sends the reader
+    # looking for a second machine that does not exist. Neutral ones only: every
+    # platform installs those, so not one of them present means nothing was.
+    neutral = [
+        name
+        for name, entry in packages.items()
+        if name.startswith("node_modules/")
+        and isinstance(entry, dict)
+        and not (entry.get("os") or entry.get("cpu") or entry.get("libc"))
+    ]
+    if neutral and not any((directory / name).exists() for name in neutral):
+        return (
+            f"{label} is missing (the directory is there, but holds none of the "
+            f"lockfile's packages) — {subject} cannot run.\n  Fix: {fix}"
+        )
+
     system, arch = _node_platform()
     libc = _node_libc(system)
     missing = [

{terp_cli-0.30.0 → terp_cli-0.32.0}/src/terp/cli/version.py

@@ -236,6 +236,7 @@ _APP_OWNED_SCAFFOLD_FILES = (
     "control_plane/app_operations.py",
     "environment.schema.json",
     "escape-hatch-budget.json",
+    "frontend/escape-hatch-budget.json",
     "frontend/layout-contract.json",
     "frontend/src/house-style.css",
     "frontend/src/routes.gen.d.ts",
@@ -450,8 +451,11 @@ def _rerender_recipe(target: str, current: str, count: int) -> list[str]:
         "     and its own diff is much easier to review on its own.",
         "  3. copier update          (or the Studio's upgrade flow, which records the",
         "     answers file it needs). This rewrites EVERY file the template owns and",
-        "     writes the terp-* and @terpjs/* pins for you.",
-        "  4. Resolve what it reports. Two conflicts are structural rather than bad luck,",
+        "     writes the terp-* and @terpjs/* pins for you. Its --pretend lists none of",
+        "     that, so do not judge the update by a dry run: review what it did as its",
+        "     own diff (git status, git diff) — that is why step 2 cleans the tree.",
+        "  4. Resolve what it reports: conflict markers in the file, or a *.rej beside it",
+        "     when it ran with --conflict rej. Two conflicts are structural, not bad luck,",
         "     because the template owns the file and your app also writes to it:",
         "       pyproject.toml            keep your dependencies, take the terp-* pins.",
         "       control_plane/operations.py  the capability folding is the template's;",
@@ -468,7 +472,10 @@ def _rerender_recipe(target: str, current: str, count: int) -> list[str]:
         "  in while the source is bind-mounted, so correct new code reloads against old",
         "  libraries and dies on an import nowhere near its cause. `terp docker dev`",
         "  rebuilds on a pyproject.toml change; a plain `docker compose up` does not,",
-        "  and `terp verify` now refuses the skew either way.",
+        "  and `terp verify` now refuses the skew either way. Coming from 0.29 or older,",
+        "  a stack that is already up keeps its old node_modules volume where 0.30.0",
+        "  declares a tmpfs. `terp docker dev` removes it before it starts; with plain",
+        "  compose, run `up --force-recreate --renew-anon-volumes` once.",
         "",
         "A green gate proves the upgrade did not break this app. It cannot prove the",
         "release did not change something this app should adopt — step 1 is the only",