@mesh-tech/mesh-cli 0.39.0 → 0.40.0

package/dist/src/utils/dev-sessions-root.js

@@ -0,0 +1,45 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+let migrated = false;
+export function devSessionsRoot(env = process.env) {
+    const configured = env.MESH_DEV_SESSIONS_DIR?.trim();
+    const root = configured ||
+        path.join(env.XDG_CONFIG_HOME?.trim() || path.join(os.homedir(), '.config'), 'mesh', 'dev-sessions');
+    fs.mkdirSync(root, { recursive: true });
+    if (!configured && !migrated) {
+        migrated = true;
+        migrateLegacySessionsDir(path.join(env.TMPDIR?.trim() || os.tmpdir(), 'mesh-dev-sessions'), root);
+    }
+    return root;
+}
+export function migrateLegacySessionsDir(legacy, root) {
+    try {
+        if (path.resolve(legacy) === path.resolve(root))
+            return;
+        let stat;
+        try {
+            stat = fs.lstatSync(legacy);
+        }
+        catch {
+            stat = undefined;
+        }
+        if (stat?.isSymbolicLink())
+            return;
+        if (stat?.isDirectory()) {
+            for (const entry of fs.readdirSync(legacy)) {
+                const to = path.join(root, entry);
+                if (!fs.existsSync(to))
+                    fs.cpSync(path.join(legacy, entry), to, { recursive: true, preserveTimestamps: true });
+            }
+            fs.renameSync(legacy, `${legacy}.migrated-${Date.now()}`);
+        }
+        fs.mkdirSync(path.dirname(legacy), { recursive: true });
+        fs.symlinkSync(root, legacy, 'dir');
+    }
+    catch {
+    }
+}
+export function resetDevSessionsRootForTests() {
+    migrated = false;
+}

package/dist/src/utils/kubeconfig.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
+import { devSessionsRoot } from './dev-sessions-root.js';
 export function buildKubeconfig(cluster, region) {
     return `apiVersion: v1
 kind: Config
@@ -31,7 +31,7 @@ users:
 `;
 }
 export function sessionKubeconfigPath(sessionName) {
-    return path.join(os.tmpdir(), 'mesh-dev-sessions', `${sessionName}.kubeconfig`);
+    return path.join(devSessionsRoot(), `${sessionName}.kubeconfig`);
 }
 export function resolveHubPlatformName(platform) {
     return platform?.name ?? 'mesh';

package/dist/src/utils/tailscale.js

@@ -434,8 +434,14 @@ export async function ensureForwarders(state) {
 }
 export function rewriteTunnelsForTargets(devOutput, targets) {
     const tunnels = { ...devOutput.tunnels };
+    for (const [name, tunnel] of Object.entries(devOutput.tunnels)) {
+        const target = targets.find((t) => t.name === name) ??
+            targets.find((t) => t.targetHost === tunnel.host && t.remotePort === tunnel.port);
+        if (target)
+            tunnels[name] = { host: "localhost", port: target.localPort };
+    }
     for (const t of targets) {
-        tunnels[t.name] = { host: "localhost", port: t.localPort };
+        tunnels[t.name] ??= { host: "localhost", port: t.localPort };
     }
     return { ...devOutput, tunnels };
 }

package/dist/src/utils/temporal-auth.js

@@ -74,7 +74,8 @@ export async function resolveTemporalAuth(tenant, env, platformName = tenant) {
                 if (/\.kube[/\\]config|error loading config file/i.test(`${detail} ${stderr}`)) {
                     logWarn("kubectl could not read a kubeconfig and fell back to ~/.kube/config " +
                         "(macOS blocks it for shells without Full Disk Access). Run inside the " +
-                        "mesh dev tmux session, or export KUBECONFIG=$TMPDIR/mesh-dev-sessions/<session>.kubeconfig.");
+                        "mesh dev tmux session, or export KUBECONFIG=~/.config/mesh/dev-sessions/<session>.kubeconfig " +
+                        "($MESH_DEV_SESSIONS_DIR/<session>.kubeconfig when that is set).");
                 }
             }
         }

package/dist/src/utils/workflow-fingerprint.js

@@ -7,6 +7,7 @@ export const WORKFLOW_PACKAGE_DIRS = [
     "packages/agent-contracts/src",
 ];
 const EXCLUDE = /(^|\/)(node_modules|dist|__tests__)(\/|$)|\.(test|spec)\.[cm]?tsx?$/;
+const EXCLUDED_DIR_NAMES = new Set(["node_modules", "dist", "__tests__"]);
 export function findRepoRoot(startDir) {
     let dir = startDir;
     for (;;) {
@@ -33,22 +34,32 @@ export function resolveWorkerSourceDirs(repoRoot, services = {}) {
     }
     return dirs;
 }
-export function computeWorkflowFingerprint(dirs, relativeTo) {
-    const files = [];
-    for (const dir of dirs) {
-        let rels;
-        try {
-            rels = readdirSync(dir, { recursive: true });
-        }
-        catch {
+function listDir(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function collectSourceFiles(dir, files) {
+    for (const entry of listDir(dir)) {
+        if (entry.isSymbolicLink())
             continue;
+        if (entry.isDirectory()) {
+            if (!EXCLUDED_DIR_NAMES.has(entry.name))
+                collectSourceFiles(join(dir, entry.name), files);
         }
-        for (const rel of rels) {
-            const p = String(rel);
-            if (/\.(ts|tsx)$/.test(p) && !EXCLUDE.test(p))
-                files.push(join(dir, p));
+        else if (entry.isFile() && /\.(ts|tsx)$/.test(entry.name) && !EXCLUDE.test(entry.name)) {
+            files.push(join(dir, entry.name));
         }
     }
+}
+export function computeWorkflowFingerprint(dirs, relativeTo) {
+    const files = [];
+    for (const dir of dirs) {
+        collectSourceFiles(dir, files);
+    }
     files.sort();
     if (files.length === 0)
         return "";

package/fragments/base/index.ts.hbs

@@ -76,6 +76,8 @@ const env = new mesh.apps.AppEnvironment("env", {
     codecServer: {
       ingressSubdomain: "codec-{{name}}",
     },
+    // Opt in to hold payloads over 20 KiB in the namespace's own bucket, by hash, outside Event History.
+    // claimCheck: true,
   },
 {{/if}}
 {{/if}}
@@ -249,6 +251,7 @@ new mesh.auth.AppAuthzPointer("authz", {
 });
 
 {{/if}}
+// `register()` comes after every component; one created after the entry point awaits throws at preview.
 export const app = env.register({
   // The line under this app's name on the Hub's Apps list, read by the
   // client's own operators more often than by anyone on the team. One

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mesh-tech/mesh-cli",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "CLI for Mesh platform development utilities",
   "type": "module",
   "license": "UNLICENSED",
@@ -41,13 +41,14 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@mesh-tech/agent-contracts": "0.2.0",
-    "@mesh-tech/tsconfig": "2.41.0",
+    "@mesh-tech/agent-contracts": "0.3.0",
+    "@mesh-tech/tsconfig": "2.43.0",
     "@mesh-tech/workflow-viz": "0.3.1",
     "@tanstack/intent": "^0.3.6",
     "@types/node": "^20.0.0",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
+    "eventsource": "^3.0.7",
     "tailwindcss": "^4.2.2"
   },
   "dependencies": {
@@ -60,6 +61,7 @@
     "@inquirer/input": "^4.2.1",
     "@inquirer/password": "^4.0.17",
     "@inquirer/select": "^4.3.1",
+    "@modelcontextprotocol/client": "^2.0.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "handlebars": "^4.7.8",
@@ -82,8 +84,8 @@
   },
   "optionalDependencies": {
     "@aws-sdk/client-s3": "^3.864.0",
-    "@temporalio/client": "^1.17.0",
-    "@temporalio/common": "^1.17.0"
+    "@temporalio/client": "^1.24.0",
+    "@temporalio/common": "^1.24.0"
   },
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts"

package/skills/mesh/SKILL.md

@@ -186,7 +186,8 @@ Top-level commands (each `register*` is wired in `src/program.ts`, which `bin/me
 | `mesh stack` | `init`, `status`, `rm <name>` | `init` in an **app** creates a personal app stack `dev-{github-user}`, copying base-stack config, setting `mesh:deploy: false`, inheriting KMS secrets provider; `--worktree` appends the git-worktree token (`dev-{user}-{token}`) so concurrent worktrees deploy to **distinct** stacks (SSM paths, Temporal namespace, Nexus endpoint all derive from the stack name → one discriminator isolates all three; no-op on the primary checkout). `init --platform` in a platform repo's **`platform/`** creates a **personal platform** `{tenant}-{github-user}-dev` — its own Zitadel, Hub, Temporal and tenant envs on the base stack's core (`mesh:coreEnv`, `mesh:clusterOwner false`, registry/VPN singletons off, deploy on); `--parent-zone` gives it its own DNS zone. `status` is the read-only drift check: for each platform this directory deploys (or an app deploys to), pinned vs deployed (the `core` and `platform` SSM registrations) vs latest `@mesh-tech/infra-components` / `@mesh-tech/hub`, plus this CLI vs the latest `@mesh-tech/mesh-cli`, with the upgrade steps when anything is behind. `rm <name>` removes a personal stack (backend state + local config), credentialed. `init`/`rm` assume the deployer role — no raw `pulumi` / manual creds needed. | `init`: `--from <stack>`, `--name <stack>`, `--worktree`, `--adopt`, `--platform`, `--parent-zone <zone>`; `status`: `--stack`, `--profile`, `--region`, `--json`, `--check` (exit 1 when behind); `rm`: `--yes` |
 | `mesh tenant` | `add <name>`, `list` | Register/inspect app tenants on a platform stack. Run from the **platform layer** of a tenant platform repo (e.g. `mesh-sandbox/platform`). `add` inserts the tenant under `mesh:tenants` in `Pulumi.<stack>.yaml` via a comment-preserving YAML round-trip (untouched lines don't reformat), refuses a tenant that is already declared (an existing entry may carry fields a re-add would drop), derives the `{name}-{env}` subdomain from the stack name (echoed in the success line), and guards against running on the core layer or an app dir; it then prints the deploy + verify sequence — `mesh deploy up` is what makes the registration live. `list` prints what the stack config declares, so "is it registered?" is answerable without opening YAML (warns when the project doesn't look like a platform layer, so an empty result isn't mistaken for "no tenants"). | `add`: `--display-name <name>`, `--subdomain <sub>`, `--zitadel-org-id <id>`, `--stack <stack>`, `--json`; `list`: `--stack <stack>`, `--json` |
 | `mesh tunnel [group]` | `external <name>` | SSM port-forward to platform services. Groups: `dev` (temporal+db), `temporal`. **`external <name>`** tunnels to a *registered* `ExternalService`: host/port are read from its credential secret (`mesh/{app-tenant}/{app-stage}/external/{name}`) — the same values deployed apps resolve at runtime — so anything the bastion can reach is tunnelable with no per-service CLI entry and no bastion services-map change. `-t/-e` are **optional inside an app directory** — they fall back to the same Pulumi/SST context detection `mesh dev` uses, which fails closed elsewhere, so pass `-t` outside an app dir (`-t` alone is enough; `-e` alone is not). `-e` names a platform env, not a stack, so it no longer doubles as the stage hint: the credential axis `external` keys on stays the app's real stack name. And `AWS_REGION`/`AWS_PROFILE` default from the nearest Pulumi config + the `{tenant}-{env}` profile convention (region falls back to the effective profile's own `region` — the `[default]` profile when none was resolved — before the platform default us-east-2). | root: `-t/--tenant`, `-e/--env`, `-l/--list`, `-s/--services <csv\|group>`, `--db-port`, `--temporal-ui-port`, `--temporal-frontend-port`; `external`: `-p/--port` (default: the remote port), `-k/--key <key>` (multi-instance `credentials.keyedBy` externals), `--app-tenant`/`--app-stage` (credential axis; default to `-t`/`-e`) |
-| `mesh secrets` | `exec <command...>`, `set [service]`, `reindex [service]`, `migrate-config` | Manage external-service creds in Secrets Manager. `exec` injects secrets as env; `set` reads field schema from SSM and prompts (or `--json`) — with `--key` it also records the instance in the service's instance index (`{prefix}/.index`, what `listInstances()` reads). `reindex` rebuilds that index from the per-key secrets actually in Secrets Manager (operator-credential `ListSecrets`) — the repair for an index that drifted (out-of-band secret create/delete, concurrent writers, malformed value) and the populate step when rolling the index out to an estate: **deploy the declaring stack first** (creates the managed, empty index), then `reindex`. All three resolve tenant + platform env from the cwd stack file and the app's `config.ts`; `-t/--tenant` overrides the tenant for one invocation, and with several `Pulumi.<stack>.yaml` files present pass `--stack` rather than relying on the base-stack pick. | `set`: `--key <id>` (multi-instance), `--all`, `--json <str>`, `-t/--tenant`, `--stack`, `--region`; `reindex`: `--dry-run`, `-t/--tenant`, `--stack`, `--region`; `migrate-config`: `--force`, `--dry-run`, `-t/--tenant`, `--stack`, `--region` |
+| `mesh secrets` | `exec <command...>`, `set [service]`, `reindex [service]`, `migrate-config` | Manage external-service creds in Secrets Manager. `exec` injects secrets as env; `set` reads field schema from SSM and prompts (or `--json`) — with `--key` it also records the instance in the service's instance index (`{prefix}/.index`, what `listInstances()` reads). `reindex` rebuilds that index from the per-key secrets actually in Secrets Manager (operator-credential `ListSecrets`) — the repair for an index that drifted (out-of-band secret create/delete, concurrent writers, malformed value) and the populate step when rolling the index out to an estate: **deploy the declaring stack first** (creates the managed, empty index), then `reindex`. All three resolve tenant + platform env from the cwd stack file and the app's `config.ts`; `-t/--tenant` overrides the tenant for one invocation, and with several `Pulumi.<stack>.yaml` files present pass `--stack` rather than relying on the base-stack pick. `set`, `reindex` and `mesh mcp review` share one lookup (`discoverStackExternalServices`): the stack's `mesh:platform` env, and only that stack's registration, never a sibling stack's on the same env. | `set`: `--key <id>` (multi-instance), `--all`, `--json <str>`, `-t/--tenant`, `--stack`, `--region`; `reindex`: `--dry-run`, `-t/--tenant`, `--stack`, `--region`; `migrate-config`: `--force`, `--dry-run`, `-t/--tenant`, `--stack`, `--region` |
+| `mesh mcp` | `review <manifest>`, `generate <manifest>` | Manifest-driven MCP Integrations (`mesh.apps.McpIntegration`). `review` fetches the server's `tools/list` with the Integration's own credential (stack resolved like `mesh secrets set`), diffs it against the reviewed snapshot with each tool's access class (a vendor `readOnlyHint` is shown as a suggestion, never a `read`), writes on confirmation and regenerates the worker package; it never enables a new upstream tool. `generate` writes the worker package the component deploys (`<manifest dir>/.mesh-mcp/<name>`: `package.json`, `main.ts`, `openapi.json`), keeping committed versions, and appends `<manifest dir>/.mesh-mcp/*` to `pnpm-workspace.yaml` when no glob covers the package (`pnpm install` records only workspace members; the apps-repo template's `apps/*`, `apps/*/*` do not cover it) or prints the glob when it cannot edit the file; run `pnpm install` and commit it with the lockfile. | `review`: `--yes`, `--dry-run`, `--stack`, `-t/--tenant`, `--secret <id>`, `--region`; `generate`: `--out <dir>`, `--refresh-versions` |
 | `mesh artifacts` | `get <ref>` | Download workflow artifact files from an AI-agent conversation. Ref `<conversationId>:<artifactId>` (artifactId defaults to `workflow-artifact`). | `-o/--output <dir>`, `--target <name>`, `--api-url <url>`, `--context <ctx>` (default `mesh.dev`) |
 | `mesh conversations` (alias `conv`) | `list`, `show <id>`, `artifacts <id>` | Read a deployed Mesh agent's conversations: list the caller's conversations, render a transcript, or list a conversation's artifacts. Resolves against the same `agent-targets` registry the MCP `agent_*` tools use. | all three: `--target <name>`, `--api-url <url>` (overrides `--target`), `--context <ctx>` (used with `--api-url`, default `mesh.dev`), `--json` (default when stdout isn't a TTY) |
 | `mesh vpn` | `connect <context>`, `disconnect`, `status`, `tunnel <up\|down\|status>`, `api-key`, `pre-auth-key`, `users` | Headscale VPN mgmt via Tailscale + kubectl. **`connect` now defaults to the userspace `tailscaled`** (brew formula, NOT the GUI Tailscale.app) — the same daemon `mesh dev --transport tailscale` / `mesh vpn tunnel` use, so it **runs headless / under the sandbox** and exposes a local SOCKS5 proxy (route a tool via `ALL_PROXY=socks5://127.0.0.1:<port>`). It relays a one-time browser-register URL for Zitadel auth. `--system` opts into the whole-machine GUI Tailscale.app (system TUN) — needs the app installed and **cannot run headless/sandboxed** (Sparkle.framework abort). For auto-forwarded VPC services (Temporal/RDS) prefer **`mesh vpn tunnel up`** or `mesh dev`. `tunnel status` reports runner **ownership** (`Runner: owned (verified)` vs `NOT OWNED (<reason>)` — a port answering a dial is not proof it's mesh's); `--json` adds `owned` (bool) + `ownership` (reason string). Admin subcommands `exec` into the `headscale-0` pod. | root: `-t/--tenant` (default `mesh`), `-e/--env` (default `dev`), `-n/--namespace`; `connect`/`disconnect`: `--system`; `tunnel up`: `--context <ctx>`; `tunnel down`: `--stop` (stop daemon, keep login), `--logout`; `tunnel status`: `--json`; `pre-auth-key`: `-u/--user` (**required**), `--expiration <24h>`, `--reusable`, `--ephemeral` |
@@ -436,13 +437,16 @@ code. If the **workflow** source (`agent-sdk` / `workflow-interpreter` /
 against the new code — a replay-incompatible change **strands** them. `mesh dev` now
 fingerprints that source at launch and **warns + refuses (use `--force`)** when it
 changed on a relaunch/worker-restart. The fix is not `--force`: keep the change
-replay-compatible — gate it with `wf.patched()` and regenerate the replay goldens
-(see the `temporal-workflow-safety` skill + the CI replay gate). Restarting unchanged
+replay-compatible — gate it with `wf.patched()` and commit a frozen taken/not-taken fixture
+pair for the gate (the `temporal-replay` skill's patch rule); never regenerate an existing
+golden (see the CI replay gate). Restarting unchanged
 code, or a non-worker service (ui/api), never warns.
 
 For **config/deploy** changes (not code): `mesh dev restart <svc> --refresh-env`
-re-reads stack/SSM output; if the *topology* changed, run `mesh deploy up` first
-(`mesh dev doctor` flags config staleness).
+re-reads stack/SSM output; if the *topology* changed, run `mesh deploy up` first.
+`mesh dev` itself warns, at launch and at `--refresh-env`, when the stack's stored
+outputs are older than the program or stack config ("Stack outputs are older than
+the program (…); run `mesh deploy up --stack <s>` to refresh the dev env.").
 
 ## Config / environment requirements
 
@@ -469,7 +473,7 @@ re-reads stack/SSM output; if the *topology* changed, run `mesh deploy up` first
 | `AssumeRoleWithWebIdentity … web identity token could not be validated` (`mesh deploy`, `mesh dev --stack`) | the cached session is from a different platform's Zitadel than the one the stack's deployer role trusts — e.g. a `mesh.dev` session (the package-registry front door) against a stack on the `mesh`/`dev` platform, which signs in as `mesh-platform.dev` | run the `mesh login <context> --device` the preflight prints (it is derived from the stack: `mesh:loginContext`, else `mesh:platform`); for a personal platform, set `mesh:loginContext` to its domain. Never fall back to exported AWS keys |
 | `login` config not found | context not discoverable | a known first-party short context (`mesh.dev`) resolves anonymously — no AWS needed. Otherwise use the platform's full domain (`mesh login dev.<tenant>.meshtech.io`). Only if neither works: ensure AWS SSO is active + the platform is deployed (SSM `cliClientId`), or add config to `~/.config/mesh/config.json` |
 | `vpn`/`temporal --show-payloads` fail | kubeconfig not set / expired creds | refresh the tenant cluster kubeconfig (`mesh vpn connect <ctx>` wires it; kubeconfig absorption into `mesh deploy` is planned) then retry | <!-- skill-lint-disable-next-line — next row's backticked `kubectl …` is a quoted ERROR SYMPTOM, not an operator command; the row's fix column already routes through mesh dev -->|
-| `kubectl could not read a kubeconfig … macOS blocks it` (from `mesh kubectl`/`logs`/`exec`/`temporal` in a bare shell) | macOS Full-Disk-Access blocks reading `~/.kube` from a shell outside the `mesh dev` session | run the command **inside** the `mesh dev` tmux window, or `export KUBECONFIG=$TMPDIR/mesh-dev-sessions/<session>.kubeconfig` first |
+| `kubectl could not read a kubeconfig … macOS blocks it` (from `mesh kubectl`/`logs`/`exec`/`temporal` in a bare shell) | macOS Full-Disk-Access blocks reading `~/.kube` from a shell outside the `mesh dev` session | run the command **inside** the `mesh dev` tmux window, or `export KUBECONFIG=~/.config/mesh/dev-sessions/<session>.kubeconfig` first (the sessions root is `$MESH_DEV_SESSIONS_DIR` when set) |
 | `mesh temporal …` won't authenticate against a **deployed** Temporal | passing `--address` (or `TEMPORAL_ADDRESS`) skips the app/stack resolution that mints a Zitadel **Bearer** — auth falls back to ambient env | omit `--address` and run from the app dir so `mesh temporal` resolves the authenticated frontend over the tunnel; use `--address` only for a local/unauthenticated Temporal |
 | `mesh dev` chose "VPN direct" then api/worker spin on `ECONNREFUSED …:27233` | tailnet-blind VPN *presence* check picked direct routing the mesh VPC doesn't actually serve | **no manual fallback needed** — current `mesh dev` TCP-probes the frontend and auto-falls back to SSM tunnels; if still stuck, force `--transport ssm` (or `--no-vpn`) |
 | `mesh dev` / `mesh vpn tunnel up` → `Tunnel port(s) for tenant '<t>' are bound by a process mesh does not own` | a foreign or orphaned listener holds a forwarder port; mesh refuses to adopt it rather than route traffic to the wrong upstream | `mesh vpn -t <t> tunnel down --stop` to reap mesh-owned runners; if the port is still held, `lsof -nP -iTCP:<port> -sTCP:LISTEN` and stop that process (if it names another mesh runner, it belongs to a different tenant — tear that one down). `mesh vpn -t <t> tunnel status` shows `Runner: owned (verified)` when healthy |

package/templates/api-auth/index.ts.hbs

@@ -124,6 +124,7 @@ new mesh.auth.AppAuthzPointer("authz", { env, mode: "policy-engine", opsHubMetad
 
 // --- Outputs ---
 
+// `register()` comes after every component; one created after the entry point awaits throws at preview.
 export const app = env.register({
   displayName: "{{titleCase name}}",
   // What a client operator reads on the Apps list. One sentence, their words.

package/templates/api-role-gating/index.ts.hbs

@@ -109,6 +109,7 @@ new mesh.auth.AppAuthzPointer("authz", {
   opsHubMetadata: compileOpsHubMetadata(schemaDef),
 });
 
+// `register()` comes after every component; one created after the entry point awaits throws at preview.
 export const app = env.register({
   displayName: "{{titleCase name}}",
   // What a client operator reads on the Apps list. One sentence, their words.

package/templates/external-service/index.ts.hbs

@@ -85,6 +85,7 @@ const api = new mesh.apps.Service("api", {
 
 // --- Outputs ---
 
+// `register()` comes after every component; one created after the entry point awaits throws at preview.
 export const app = env.register({
   description: "{{titleCase name}} — external-service (vendor credentials) pattern",
 });

package/templates/workflow/index.ts.hbs

@@ -27,6 +27,7 @@ const env = new mesh.apps.AppEnvironment("env", {
   appName: "{{name}}",
   namespace: true,
   rootDir: __dirname,
+  // `temporal: { claimCheck: true }` holds payloads over 20 KiB in the namespace's own bucket, by hash, outside Event History.
   temporal: true,
 });
 
@@ -66,6 +67,7 @@ const worker = new mesh.apps.TemporalWorker("worker", {
 
 // --- Outputs ---
 
+// `register()` comes after every component; one created after the entry point awaits throws at preview.
 export const app = env.register({
   displayName: "{{titleCase name}}",
   // What a client operator reads on the Apps list. One sentence, their words.