@mondaydotcomorg/z2h-cli 0.34.1 → 0.34.2

package/CHANGELOG.md

@@ -0,0 +1,2969 @@
+# CHANGELOG
+
+## `0.34.1` (October 5, 2026, 13:41)
+
+### Improvements
+
+- [#509](https://github.com/DaPulse/bigbrain-z2h/pull/509) refactor(z2h): move bucket and app-name constants to z2h-shared-utils (@eitan-ts)
+- Changed: S3 bucket, manifest, skills, and app-name constants have been moved from direct definitions in `constants.ts` to re-exports from `@mondaydotcomorg/z2h-shared-utils`. The public API remains unchanged for existing imports like `import { BUCKET_WRITE_NAME } from '@mondaydotcomorg/z2h-cli/constants'`, but the source of truth now lives in the shared utils package.
+  *Before:*
+  ```ts
+  // In z2h-cli/constants.ts
+  export const BUCKET_WRITE_NAME = 'prod-use1-bigbrain-zth-mf-assets';
+  export const REGION = 'us-east-1';
+  // ... other constants defined here
+  ```
+  *After:*
+  ```ts
+  // In z2h-cli/constants.ts
+  export {
+    BUCKET_WRITE_NAME,
+    REGION,
+    // ... other constants re-exported from shared utils
+  } from '@mondaydotcomorg/z2h-shared-utils';
+  ```
+- Changed: The following constants are now re-exported from `@mondaydotcomorg/z2h-shared-utils`: `BUCKET_WRITE_NAME`, `REGION`, `BUCKET_WRITE_URL`, `BUCKET_READ_DNS_NAME`, `BUCKET_READ_DNS_URL`, `S3_PREVIEWS_FOLDER`, `MANIFEST_KEY`, `MANIFEST_READ_URL`, `S3_SKILLS_BUCKET_NAME`, `DATAVIZ_SKILLS_PREFIX`, `APP_NAME_PATTERN`, and `PREVIEW_APP_NAME_PREFIX`. Existing imports from `@mondaydotcomorg/z2h-cli/constants` continue to work unchanged.
+- Removed: Direct definitions of bucket configuration constants, manifest paths, skills bucket configuration, and app name validation patterns from the CLI package. These values remain accessible via the same import paths but are now maintained in the shared utils package.
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.34.0` (October 5, 2026, 12:54)
+
+### New Features
+
+- [#504](https://github.com/DaPulse/bigbrain-z2h/pull/504) feat(z2h): expose the template catalog over the API [prerelease] (@chezkibotwinick)
+- Added: New public export `dashboard-templates` module exposing template catalog utilities. The module exports `loadDashboardTemplatesCatalog()` (loads the bundled template catalog), `findTemplate()` (finds a specific template by ID), and the `DashboardTemplateEntry` type.
+  *Usage:*
+  ```ts
+  import { loadDashboardTemplatesCatalog, findTemplate } from '@mondaydotcomorg/z2h-cli/dashboard-templates';
+  const catalog = loadDashboardTemplatesCatalog();
+  const template = findTemplate('template-id');
+  ```
+  This allows the backend service to read the same catalog data that the CLI uses without invoking the CLI entry point.
+- Changed: Updated the `templates` command description to reference "config schema" instead of "widget schema" for clarity and consistency with the API nomenclature.
+
+## `0.33.4` (October 4, 2026, 13:07)
+
+### Bug Fixes
+
+- [#501](https://github.com/DaPulse/bigbrain-z2h/pull/501) fix(z2h-cli): deploy commits usage.json before pushing (@eitan-ts)
+- Fixed: `z2h-cli deploy` now commits `usage.json` before pushing to the remote repository, preventing "uncommitted changes" errors on subsequent deploys. Previously, the file was written after the push, leaving the working tree dirty.
+- Added: New utility function `updateOrCreateUsageJson(appDir: string, appName: string, deployedBy: string): Promise<void>` in `util/usage-json.ts` that refreshes the git-tracked `usage.json` file, stages it, and commits it only if it changed.
+  ```ts
+  import { updateOrCreateUsageJson } from '@mondaydotcomorg/z2h-cli/util/usage-json';
+  
+  // Creates or updates usage.json, stages it, and commits if changed
+  await updateOrCreateUsageJson(process.cwd(), 'my-app', 'user@example.com');
+  ```
+- Changed: The `deploy` command now calls `updateOrCreateUsageJson()` immediately after `pullAndResolve()` in the git error handling block, ensuring the usage.json update is included in the regular push operation.
+- Changed: Backend upload operations no longer write `usage.json` during deploy. The `readDetectAndUpload` function in `backend.ts` removed its `writeUsageJson()` calls that previously wrote the file after handler parsing.
+- Changed: Refactored usage.json utilities into a dedicated module. Functions `hasHandlers()` and `writeUsageJson()` moved from `commands/backend.ts` to `util/usage-json.ts` and are now exported for broader use.
+  ```ts
+  // Before: only available within backend.ts
+  // After: importable from util module
+  import { hasHandlers, writeUsageJson } from '@mondaydotcomorg/z2h-cli/util/usage-json';
+  
+  if (hasHandlers(appDir)) {
+    await writeUsageJson(appDir, { appName, deployedBy, apiUsages });
+  }
+  ```
+- Changed: The `execGit` helper function in `util/git/repo.ts` is now exported and available for use in other modules. Previously it was an internal function only.
+  ```ts
+  import { execGit } from '@mondaydotcomorg/z2h-cli/util/git/repo';
+  
+  // Now usable in other modules
+  await execGit(['add', 'usage.json'], appDir);
+  ```
+- Changed: Preview deploys are unaffected by this change and continue to skip usage.json updates entirely.
+
+## `0.33.3` (October 1, 2026, 13:00)
+
+### Bug Fixes
+
+- [#494](https://github.com/DaPulse/bigbrain-z2h/pull/494) fix(z2h-cli): track only opted-in commands under enum event names (@arielmonday)
+- **Breaking**: Removed the `track` field from `CommandSpec<A>`. Commands now opt into success event tracking by providing an `event` field; omit `event` to skip success tracking. Failures are still reported via `z2h_cli_error` whether or not the command tracks success.
+  *Before:*
+  ```ts
+  runCommand({ track: false }, () => myCommand())
+  ```
+  *After:*
+  ```ts
+  // No success event sent, failures still reported
+  runCommand({}, () => myCommand())
+  ```
+- **Breaking**: The `event` field in `CommandSpec<A>` is now typed as `PerArgs<A, Z2hCliEventName>` instead of `PerArgs<A, string>`. Event names must be values from the `Z2hCliEvents` enum exported by `@mondaydotcomorg/z2h-shared-utils/observability`.
+  *Before:*
+  ```ts
+  runCommand({ event: 'z2h_cli_deploy_success' }, () => deployCommand())
+  ```
+  *After:*
+  ```ts
+  import { Z2hCliEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
+  runCommand({ event: Z2hCliEvents.deploySuccess }, () => deployCommand())
+  ```
+- Removed the `successEvent(command: string): string` helper function from `util/tracker.ts`. Use enum values from `Z2hCliEvents` directly instead.
+- Changed how command names are derived in `runCommand()`: top-level commands no longer include the root program name (`z2h-cli`). A top-level command is now labeled `create` instead of `z2h-cli create`, and a nested command is `backend invoke` instead of `z2h-cli backend invoke`. This affects the `action` dimension in telemetry and error messages.
+- Commands that no longer send success events: `clean`, `create-workspace`, `doctor`, `tag`, `backend invoke`, `backend validate`, `grant`, `revoke`, `transfer-owner`, `migrate`, `generate-z2h-token`, `custom-integration:*`, `llm-migration`. Their failures still send `z2h_cli_error` events.
+- Updated all tracked commands to use typed event names from `Z2hCliEvents`: `deploy` → `z2h_app_deploy_success`, `deploy --preview` → `z2h_app_preview_success`, `create` → `z2h_app_created`, `build` → `z2h_app_build_success`, `edit` → `z2h_app_edit_pulled`, `delete` → `z2h_app_delete_success`, `templates` → `z2h_cli_templates_success`, `generate-app-template` → `z2h_cli_generate_app_template_success`.
+- Parser errors in `backend/parser/parse.ts` now use `Z2hCliEvents.handlerParseError` constant instead of the string literal `'z2h_cli_handler_parse_error'`.
+- The `build` command now sends a success event (`z2h_app_build_success`) but continues to skip error events for failures tagged `build_error` (consumer code failures, not CLI/infra problems).
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.33.2` (October 1, 2026, 08:17)
+
+### Improvements
+
+- [#487](https://github.com/DaPulse/bigbrain-z2h/pull/487) feat(z2h): store handlerNames and capped apiUsages on the apps table (@eitan-ts)
+- Changed: The `deployBackend` function now returns a `ReadDetectAndUploadResult` object containing `integrations`, `handlerNames`, and `apiUsages` instead of returning only an array of integrations.
+  *Before:*
+  ```ts
+  const integrations = await deployBackend({ ... });
+  ```
+  *After:*
+  ```ts
+  const { integrations, handlerNames, apiUsages } = await deployBackend({ ... });
+  ```
+- Added: The `ReadDetectAndUploadResult` interface is now exported from `backend.ts`, providing structured access to backend deployment metadata including detected integrations, handler function names, and API usage analytics.
+- Changed: The `registerOrUpdateApp` function now accepts `handlerNames` and `apiUsages` as optional fields in its `RegisterOrUpdateOptions` parameter. These fields are passed through to the backend broker endpoints for storage in the apps table.
+  *Updated interface:*
+  ```ts
+  export interface RegisterOrUpdateOptions {
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: ManifestEntry;
+    gitRemote: string;
+    integrations?: string[];
+    handlerNames?: string[];      // New field
+    apiUsages?: Record<string, unknown>;  // New field
+    description?: string;
+    masterAppName?: string;
+  }
+  ```
+- Changed: The deploy process now executes backend deployment before frontend upload, ensuring that if the backend step fails, the preview's unversioned MF directory is not left in an inconsistent state.
+- Added: Preview deployments that fail after the backend has already been deployed now emit a warning instructing users to re-run `z2h-cli deploy --preview` to retry, clarifying that every step is an idempotent overwrite that will repair any partial state.
+- Changed: The `readDetectAndUpload` internal function now writes `usage.json` with `apiUsages` data even when no handlers are present (writing an empty object), ensuring consistent usage tracking across all deployment scenarios.
+- Changed: Backend handler names are now extracted and returned from `readDetectAndUpload` as a dedicated `handlerNames` array (derived from `Object.keys(handlers)`), enabling future prompt-to-app matching capabilities.
+- Changed: The `registerApp` and `updateApp` internal functions now accept a single params object conforming to `RegisterOrUpdateOptions` instead of individual parameters, simplifying the function signatures and ensuring consistent parameter passing throughout the registration flow.
+
+## `0.33.1` (September 30, 2026, 09:49)
+
+### Improvements
+
+- [#488](https://github.com/DaPulse/bigbrain-z2h/pull/488) feat(z2h): sandbox run — backend invoke runs the local handler before deploy (@EranZidkiya)
+- **Breaking Change**: The `backend invoke` command now runs handler source from the working tree against real channels (database, monday API, Snowflake) without deploying, instead of invoking the deployed handler. The command validates the local handler source first and prints a detailed trace of every channel call made during execution.
+  *Before (v0.32.x):*
+  ```bash
+  z2h-cli backend invoke get_kpis --input '{"since":"2026-01-01"}'
+  # Invoked the deployed handler on the backend
+  ```
+  *After (v0.33.0):*
+  ```bash
+  z2h-cli backend invoke get_kpis --input '{"since":"2026-01-01"}'
+  # Runs backend/handlers/get_kpis.js from your working directory
+  # Prints trace showing each channel call, duration, and result
+  ```
+- Added: The `backend invoke` command now accepts a `--code <source>` option to run inline handler source instead of reading from a file, useful for testing snippets without creating a handler file.
+  *Usage:*
+  ```bash
+  z2h-cli backend invoke scratch --code 'async function handler(ctx) {
+    return ctx.api.v1.snowflake.query("SELECT CURRENT_USER() AS u");
+  }'
+  ```
+- Changed: The `backend invoke` command now exits with code 1 when the handler fails (e.g., channel error, timeout, isolate error), allowing scripts to detect failures.
+- Changed: The output format for `backend invoke` now includes a human-readable trace showing each channel call with method name, duration, row count, and success/failure status, instead of only showing the final result.
+- **Breaking Change**: Removed the `invokeBackend` function from `src/backend/client.ts`. Replaced with `runSandbox(appName, body)` which accepts `SandboxRunRequest` containing `code`, `input`, and optional `handlerName`.
+  *Before:*
+  ```typescript
+  import { invokeBackend } from './backend/client';
+  const res = await invokeBackend(appName, handlerName, input);
+  // res: { result: unknown; durationMs: number }
+  ```
+  *After:*
+  ```typescript
+  import { runSandbox } from './backend/client';
+  const res = await runSandbox(appName, { code, input, handlerName });
+  // res: { ok: boolean; error?: {...}; calls: SandboxCall[]; result: unknown; durationMs: number }
+  ```
+- **Breaking Change**: Renamed the `InvokeResponse` interface to `SandboxRunResponse` and added new fields: `ok` (boolean), `error` (optional object with `status`, `code`, `message`), and `calls` (array of `SandboxCall` objects tracing each channel method invoked).
+- Added: New `SandboxRunRequest` interface for sandbox run requests with fields `code` (string), `input` (unknown), and optional `handlerName` (string).
+- Added: New `SandboxCall` interface representing a traced channel call, with fields `method`, `args`, `durationMs`, `ok`, optional `error`, and optional `result`.
+- Added: New `formatSandboxRun` function in `src/backend/format-sandbox-run.ts` that formats a `SandboxRunResponse` into a human-readable trace with call details, durations, row counts, and error messages.
+- Changed: The `backend invoke` command description now states it runs handlers from the working tree (not deployed handlers) against real channels and prints a trace, exiting 1 on failure.
+- Added: Local validation of handler source before sending to the sandbox endpoint, using the same `validateHandlerSource` check that the deploy command uses.
+- Changed: The CLI now respects `process.exitCode` set by commands and exits with that code, allowing commands to signal non-zero exit status without throwing errors.
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.33.0` (September 30, 2026, 03:58)
+
+### New Features
+
+- [#480](https://github.com/DaPulse/bigbrain-z2h/pull/480) Feat/yarin/custom pat channel 4 cli (@yarinmonday)
+- Added: New `custom-integration:list` command that displays all custom integrations registered for the current app. The command shows each integration's name, allowed host, auth header name, and whether it is inherited from a base app.
+  *Usage:*
+  ```bash
+  z2h-cli custom-integration:list
+  ```
+  *Output example:*
+  ```
+  [z2h-cli] "mf-my-app" custom integrations:
+    stripe  →  api.stripe.com  (X-Stripe-Auth)  [inherited from base app]
+  ```
+- Added: New `custom-integration:remove <name>` command that removes a registered custom integration from the current app by name.
+  *Usage:*
+  ```bash
+  z2h-cli custom-integration:remove stripe
+  ```
+- Added: New `CustomIntegrationSummary` interface exported from `src/commands/custom-integrations.ts` with fields: `name`, `allowedHost`, `authHeaderName`, `authScheme`, `createdBy`, `createdAt`, `updatedAt`, and optional `inherited` boolean.
+- Changed: Reserved app name list now includes `'set-custom-integration'` in addition to `'generate-z2h-token'`, preventing users from creating apps with this platform-reserved route name.
+- Changed: The `masterAppName` field in `RegisterOrUpdateOptions` interface documentation now clarifies that it links preview apps to their base apps for custom integration inheritance. The field is only required on first registration and is immutable thereafter.
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.32.2` (September 29, 2026, 10:46)
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.32.1` (September 28, 2026, 14:07)
+
+### Bug Fixes
+
+- [#475](https://github.com/DaPulse/bigbrain-z2h/pull/475) ci(z2h-cli): fix zth-cli-e2e OOM by right-sizing the runner (@eitan-ts)
+
+## `0.32.0` (September 28, 2026, 10:17)
+
+### New Features
+
+- [#472](https://github.com/DaPulse/bigbrain-z2h/pull/472) feat(z2h-cli): LLM-guided migrations (type: llm) + z2h:migrate skill (@eitan-ts)
+- Added: New `llm-migration` CLI command for listing and retrieving agent-guided (LLM) migrations. Run without arguments to list all available LLM migrations with their descriptions, or use `--migration <name>` to print the full markdown guide for a specific migration.
+  *Usage:*
+  ```bash
+  z2h-cli llm-migration                          # list all LLM migrations
+  z2h-cli llm-migration --migration <name>       # print guide for specific migration
+  z2h-cli llm-migration --migration snowflake-service-to-backend-runner
+  ```
+
+- Added: First LLM migration guide `snowflake-service-to-backend-runner` for migrating Z2H consumer apps from deprecated direct `bigbrain-zth /snowflake/query` fetches to `zth-backend-runner` handlers using `ctx.api.v1.snowflake`. The 168-line markdown guide includes detection instructions (grep for `/snowflake/query` in `src/`), the old vs new pattern, handler creation rules, frontend call-site rewrites for both React and html-embed apps, parameterization requirements, and three-step verification (handler validation, build check, collision detection).
+
+- Added: New shared utility module `src/util/migrations-json.ts` defining the migration type system. Exports `DeterministicMigrationEntry` (deterministic Nx-tree migrations with `version`, `description`, `migrate` script path) and `LlmMigrationEntry` (agent-guided migrations with `type: "llm"`, `version`, `description`, `guide` markdown path). The `resolveMigrationsJson()` function locates `migrations.json` via `require.resolve('@mondaydotcomorg/z2h-cli/package.json')`.
+  *Type definitions:*
+  ```typescript
+  interface DeterministicMigrationEntry {
+    type?: never;
+    version: string;      // CLI release version
+    description: string;
+    migrate: string;      // path to migration script
+  }
+  
+  interface LlmMigrationEntry {
+    type: 'llm';
+    version: string;      // CLI version migration was added
+    description: string;
+    guide: string;        // path to markdown guide
+  }
+  ```
+
+- Changed: The `migrate` command now filters out LLM migrations (`type: "llm"`) before the semver gate, as LLM migrations have no state file and are idempotent by design (detection is re-run each time). Only deterministic migrations are processed by the existing migration runner.
+
+- Changed: Migration resolution logic refactored to use the shared `resolveMigrationsJson()` utility instead of inline path resolution, ensuring consistent migrations.json discovery across both `migrate` and `llm-migration` commands.
+
+## `0.31.0` (September 27, 2026, 11:32)
+
+### New Features
+
+- [#442](https://github.com/DaPulse/bigbrain-z2h/pull/442) feat(z2h): AST handler validation + usage.json apiUsages metadata (@eitan-ts)
+- Changed: AST parsing utilities moved from `src/backend/ast.ts` to a new `src/backend/parser/` directory with modular organization. The legacy `ast.ts` file was removed entirely. Code that imported from `./ast` should now import from `./parser/api-usage`, `./parser/bindings`, `./parser/member-path`, etc.
+
+- Added: `collectApiUsages` function in `parser/api-usage.ts` captures every `ctx.api.v1.<domain>.<method>(...)` call site with per-argument metadata. Arguments are resolved to static values when possible (string literals, template literals, object/array literals, const references), otherwise recorded as source text. Example captured usage:
+  ```ts
+  // Handler source:
+  ctx.api.v1.snowflake.query('SELECT * FROM users WHERE id = ?', [userId]);
+  
+  // Captured in apiUsages:
+  {
+    "snowflake": {
+      "query": [
+        {
+          "sql": "SELECT * FROM users WHERE id = ?",
+          "params": "[userId]"
+        }
+      ]
+    }
+  }
+  ```
+
+- Added: `staticValue` function in `parser/static-value.ts` resolves AST nodes to JSON-serializable values. Supports literals, template literals with interpolation, object/array expressions, binary `+` for string concatenation, conditional expressions (recorded as `{ $or: [branch1, branch2] }`), and const variable references with alias following.
+
+- Added: Scope-aware binding resolution. `collectBindings` in `parser/bindings.ts` now tracks the lexical scope of each declaration (function body, block statement, etc.). `declarationAt(bindings, name, position)` returns the innermost declaration visible at a given source position, enabling correct alias resolution when names are shadowed.
+
+- Changed: `validateHandlerSource` return type now includes `apiUsages`. Migration:
+  *Before:*
+  ```ts
+  const { apiDomains } = validateHandlerSource(file, source);
+  ```
+  *After:*
+  ```ts
+  const { apiDomains, apiUsages } = validateHandlerSource(file, source);
+  ```
+
+- Changed: `readHandlers` return type (`ReadHandlersResult`) now includes `apiUsages: Record<string, ApiUsage>`, a map from handler name to its API usage metadata. Migration:
+  *Before:*
+  ```ts
+  const { handlers, apiDomains } = await readHandlers(appDir);
+  ```
+  *After:*
+  ```ts
+  const { handlers, apiDomains, apiUsages } = await readHandlers(appDir);
+  ```
+
+- Added: `usage.json` file lifecycle. New apps created via `z2h-cli create` are seeded with an empty `usage.json`. The file is updated by `z2h-cli backend validate` and `z2h-cli deploy` with `{ appName, deployedBy, apiUsages }`. During deploy, the CLI merges the new metadata into the existing local `usage.json` (preserving fields added by other features) and uploads the merged result to S3, but never writes the merged copy back to disk (to avoid dirtying the git tree post-commit).
+
+- Added: `writeUsageJson` helper function in `commands/backend.ts` merges new metadata into the app's existing `usage.json` without replacing other top-level fields. Example:
+  ```ts
+  // Existing usage.json: { "customField": 123 }
+  await writeUsageJson(appDir, { appName: 'my-app', deployedBy: 'alice', apiUsages: {...} });
+  // Result on disk: { "customField": 123, "appName": "my-app", "deployedBy": "alice", "apiUsages": {...} }
+  ```
+
+- Added: `loadApiSignatures` function in `parser/api-signatures.ts` reads `handler-api/signatures.json` (generated at build time from runner channel docs). Signatures provide parameter names for `ctx.api.v1.<domain>.<method>` calls, so captured usage keys are human-readable (`sql`, `params`) instead of positional (`arg0`, `arg1`).
+
+- Added: `whoAmI` function in `util/machine-identity.ts` returns `process.env.APP_NAME` (for service accounts) or `os.userInfo().username` (for human users). Replaces the inline `whoDeployed` function previously in `commands/deploy.ts`.
+
+- Changed: `collectBindings` now tracks function parameters and catch clause bindings as declarations with `kind: 'param'`. Parameters are marked in the `unpinnable` set (never followed as stable aliases), and their scope is recorded (the function body or catch block where they are visible).
+
+- Changed: `createPathResolver` now accepts a source position when resolving identifiers, enabling correct shadowing: `const x = 1; function f() { const x = 2; return x; }` resolves the inner `x` to `2`, not `1`.
+
+- Added: `memberChain` utility in `parser/utils.ts` extracts the root identifier and property path from `a.b.c` / `a['b'].c` expressions, returning `{ root: 'a', parts: ['b', 'c'] }`. Returns `undefined` if any property access is computed from a non-literal (dynamic access).
+
+- Added: `patternBindings` utility in `parser/utils.ts` recursively extracts all identifier bindings from a destructuring pattern with their property paths. Example: `const { api: { v1: sf } } = ctx` produces `[{ name: 'sf', path: ['api', 'v1'] }]`.
+
+- Added: `parseOrThrow` function in `parser/parse.ts` validates handler source as a script (the grammar the runner uses) and produces contextual error messages when module-only syntax is detected. Distinguishes "handler is exported" (forbidden) from "handler uses top-level await" (also forbidden), improving DX for agent-generated code.
+
+- Added: `findHandlerDeclaration` and `handlerContextParamName` functions in `parser/handler-declaration.ts` locate the top-level `handler` binding and extract its first parameter name (if it's a plain identifier), enabling alias-aware `ctx` tracking (`handler(context) { context.api.v1... }` resolves as `ctx.api.v1...`).
+
+- Changed: Handler files in `backend/handlers/` are now processed in sorted order (lexicographic by filename) instead of `readdir()` order, ensuring `usage.json` key order is deterministic across machines and deploys.
+
+- Changed: `backendValidateCommand` now updates the local `usage.json` with current `apiUsages`, `appName` (from `package.json`), and `deployedBy` (the current user). Previously it only validated syntax; now it refreshes metadata as a side effect.
+
+- Added: Template file `src/templates/app/usage.json` containing `{}`, copied to new apps by `z2h-cli create`.
+
+- Removed: Inline `whoDeployed` function in `commands/deploy.ts`. Replaced by `whoAmI` from `util/machine-identity.ts`.
+
+## `0.30.0` (September 24, 2026, 09:13)
+
+### New Features
+
+- [#440](https://github.com/DaPulse/bigbrain-z2h/pull/440) Feat/yarin/z2h populate preview master id and enforce (@yarinmonday)
+- Added: Preview deployments now require the master app to exist before deploying. The `deployPreview` function validates that the parent app has been created or deployed at least once, throwing a `DeployError` with actionable guidance (`z2h-cli create <name>` or deploy once) if the master app is missing. This prevents confusing backend 404 errors when previewing apps that were scaffolded locally but never claimed in the registry.
+
+- Changed: The `uploadAndRegister` internal function now accepts a `masterAppName` optional parameter to link preview apps to their parent app during registration.
+  *Before:*
+  ```typescript
+  async function uploadAndRegister(opts: {
+    paths: Paths;
+    keyPrefix: string;
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: string;
+    gitRemote: string;
+    isPreview: boolean;
+    description?: string;
+  }): Promise<void>
+  ```
+  *After:*
+  ```typescript
+  async function uploadAndRegister(opts: {
+    paths: Paths;
+    keyPrefix: string;
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: string;
+    gitRemote: string;
+    isPreview: boolean;
+    description?: string;
+    masterAppName?: string;
+  }): Promise<void>
+  ```
+
+- Changed: The `registerApp` internal function now accepts a `masterAppName` optional parameter, which is included in the registration request payload sent to the broker API.
+  *Before:*
+  ```typescript
+  async function registerApp(
+    appName: string,
+    token: string,
+    version: number,
+    entry: string,
+    visibility: 'public' | 'private',
+    gitRemote: string,
+    integrations?: string[],
+    description?: string
+  ): Promise<void>
+  ```
+  *After:*
+  ```typescript
+  async function registerApp(
+    appName: string,
+    token: string,
+    version: number,
+    entry: string,
+    visibility: 'public' | 'private',
+    gitRemote: string,
+    integrations?: string[],
+    description?: string,
+    masterAppName?: string
+  ): Promise<void>
+  ```
+
+- Changed: The `RegisterOrUpdateOptions` interface now includes an optional `masterAppName` field to specify the parent app when registering a preview app for the first time. This field is ignored for version updates beyond v1.
+  *Before:*
+  ```typescript
+  export interface RegisterOrUpdateOptions {
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: string;
+    gitRemote: string;
+    integrations?: string[];
+    description?: string;
+  }
+  ```
+  *After:*
+  ```typescript
+  export interface RegisterOrUpdateOptions {
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: string;
+    gitRemote: string;
+    integrations?: string[];
+    description?: string;
+    /** For a preview app's first registration, the real app it previews. Ignored past v1. */
+    masterAppName?: string;
+  }
+  ```
+
+- Changed: The `registerOrUpdateApp` function now threads the `masterAppName` parameter through to `registerApp` when registering version 1 of a preview app, enabling server-side resolution of preview-to-master relationships.
+
+- Changed: The `deployPreview` workflow now passes `masterAppName: appName` when calling `uploadAndRegister`, linking the preview app to its parent in the registry.
+
+- Changed: The `generateCommand` now claims the app name in the Z2H registry (via `claimApp`) immediately after validation if the app doesn't already exist. This ensures the app row exists server-side so that subsequent preview deployments can resolve the parent app by name, matching the behavior of the normal `create` flow.
+
+## `0.29.5` (September 23, 2026, 13:04)
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.29.4` (September 22, 2026, 14:11)
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.29.3` (September 17, 2026, 10:56)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.29.2` (September 17, 2026, 09:12)
+
+### Bug Fixes
+
+- [#452](https://github.com/DaPulse/bigbrain-z2h/pull/452) refactor(z2h-cli): remove snowflake static-SQL handler rule (@eitan-ts)
+- Removed: The `lineOf` utility function from `src/backend/ast.ts` has been deleted. This function previously returned the 1-based line number where an AST node starts.
+  *Before:*
+  ```ts
+  import { lineOf } from '@mondaydotcomorg/z2h-cli/backend/ast';
+  const line = lineOf(node); // number | undefined
+  ```
+  *After:*
+  ```ts
+  // lineOf is no longer exported; use node.loc?.start.line directly
+  const line = node.loc?.start.line;
+  ```
+- Removed: The entire `rules/` module has been deleted, eliminating the handler validation rules system. The following exports are no longer available: `HandlerRule` interface, `RuleContext` interface, and `HANDLER_RULES` array from `src/backend/rules/index.ts`.
+  *Before:*
+  ```ts
+  import { HANDLER_RULES, type HandlerRule } from '@mondaydotcomorg/z2h-cli/backend/rules';
+  ```
+  *After:*
+  ```ts
+  // The rules module no longer exists; these types and constants are unavailable
+  ```
+- Removed: The `SnowflakeStaticSqlRule` class that enforced static SQL strings in `ctx.api.v1.snowflake.query()` calls has been removed from `src/backend/rules/snowflake-static-sql.ts`. Handler validation no longer checks whether SQL is static (authored in the handler file) versus dynamic (client-supplied).
+- Changed: The `validateHandlerSource` function in `src/backend/validate.ts` no longer runs capability-specific rules after structural validation. It now only validates that the handler is syntactically valid, defines a `handler` export, and contains no imports. Previously, it would iterate through `HANDLER_RULES` and throw an error if any violations were found.
+  *Before:*
+  ```ts
+  // validateHandlerSource would throw if SQL was not static
+  validateHandlerSource('handler.ts', 'export const handler = (ctx) => ctx.api.v1.snowflake.query(ctx.input.sql)');
+  // Error: handler.ts:1: ctx.api.v1.snowflake.query must receive SQL written in the handler...
+  ```
+  *After:*
+  ```ts
+  // validateHandlerSource only checks structure, not capability rules
+  validateHandlerSource('handler.ts', 'export const handler = (ctx) => ctx.api.v1.snowflake.query(ctx.input.sql)');
+  // { valid: true, warnings: [] } — no rule enforcement
+  ```
+
+## `0.29.1` (September 16, 2026, 12:43)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.29.0` (September 16, 2026, 11:36)
+
+### New Features
+
+- [#434](https://github.com/DaPulse/bigbrain-z2h/pull/434) Feat/yarin/z2h claim app name (@yarinmonday)
+- Added: New `claimApp(appName: string, gitRemote: string)` function in `util/broker/app.ts` to reserve an app name before the first deployment. This function makes a POST request to `/z2h-cli/apps/claim` and is idempotent from the caller's perspective. It throws an error if the claim fails (e.g., name already taken by another user).
+  ```ts
+  // New function signature:
+  export async function claimApp(appName: string, gitRemote: string): Promise<void>
+  ```
+
+- Changed: `AppInfo` interface in `util/broker/app.ts` now includes a `deployed` boolean field indicating whether the app has been published, and the `entry` field can now be `null` for claimed-but-unpublished apps.
+  *Before:*
+  ```ts
+  export interface AppInfo {
+    appName: string;
+    version: number;
+    entry: Record<string, unknown>;
+    deployedBy: string;
+    gitRemote: string;
+    createdBy: string;
+  }
+  ```
+  *After:*
+  ```ts
+  export interface AppInfo {
+    appName: string;
+    version: number;
+    entry: Record<string, unknown> | null; // Null for claimed-but-unpublished
+    deployed: boolean; // True once a real release has landed
+    deployedBy: string;
+    gitRemote: string;
+    createdBy: string;
+  }
+  ```
+
+- Changed: `createCommand` in `commands/create.ts` now calls `claimApp()` to reserve the app name immediately after validation and before scaffolding files. If an app already exists in the registry, the command only throws an error if `existing?.deployed` is true (indicating a real release exists). A claimed-but-unpublished stub (where `entry` is null) is now allowed, enabling users to re-create locally after wiping their directory or to proceed if the name was reserved but never published.
+  *Before:*
+  ```ts
+  const existing = await fetchApp(mfAppName(appName));
+  if (existing) {
+    throw new Error(`An app named "${appName}" already exists...`);
+  }
+  ```
+  *After:*
+  ```ts
+  const existing = await fetchApp(mfAppName(appName));
+  if (existing?.deployed) {
+    throw new Error(`An app named "${appName}" already exists...`);
+  }
+  const gitRemote = resolveRemoteUrl(...);
+  if (!existing) {
+    await claimApp(mfAppName(appName), gitRemote);
+  }
+  ```
+
+- Changed: `generateCommand` in `commands/generate.ts` now only blocks app creation if `existing?.deployed` is true, rather than blocking on any existing app record. This aligns with the new behavior where claimed-but-unpublished stubs are permitted.
+  *Before:*
+  ```ts
+  const existing = await fetchApp(mfAppName(appName));
+  if (existing) {
+    throw new Error(`An app named "${appName}" already exists...`);
+  }
+  ```
+  *After:*
+  ```ts
+  const existing = await fetchApp(mfAppName(appName));
+  if (existing?.deployed) {
+    throw new Error(`An app named "${appName}" already exists...`);
+  }
+  ```
+
+- Changed: `fetchApp` function documentation in `util/broker/app.ts` updated to clarify it returns `null` only if the app has never been claimed (404 response), not just never deployed. This reflects the new claiming workflow where apps can exist in the registry without having been deployed yet.
+
+## `0.28.0` (September 16, 2026, 09:13)
+
+### New Features
+
+- [#426](https://github.com/DaPulse/bigbrain-z2h/pull/426) feat(z2h-cli): validate backend handlers with acorn AST (@eitan-ts)
+- Added: AST-based validation for backend handlers. The CLI now parses handler source files using Acorn at read and deploy time, validating syntax, isolate constraints (no import/export, must define a global `handler` function), and capability-specific rules. Parse errors include file, line, and column information.
+- Added: `z2h-cli backend validate` command to run handler validation checks without uploading to S3. This runs the same syntax, isolate, and integration detection checks as deployment.
+  *Usage:*
+  ```bash
+  z2h-cli backend validate
+  ```
+  *Output:*
+  ```
+  [z2h-cli] 3 handler(s) valid: handler1, handler2, handler3
+  [z2h-cli] integrations: monday
+  ```
+- Changed: Integration detection now uses AST analysis instead of regex scanning. The `detectIntegrationsFromHandlers(handlers: Record<string, string>)` function has been replaced with `detectIntegrations(apiDomains: Iterable<string>)`.
+  *Before:*
+  ```ts
+  import { detectIntegrationsFromHandlers } from '@mondaydotcomorg/z2h-cli/backend/detect-integrations';
+  const integrations = detectIntegrationsFromHandlers(handlers);
+  ```
+  *After:*
+  ```ts
+  import { detectIntegrations } from '@mondaydotcomorg/z2h-cli/backend/detect-integrations';
+  const integrations = detectIntegrations(apiDomains);
+  ```
+- Changed: `readHandlers()` now returns `{ handlers: Record<string, string>, apiDomains: string[] }` instead of `{ handlers: Record<string, string> }`. The `apiDomains` array contains every `ctx.api.v1.<domain>` any handler touches, sorted and unique.
+- Added: Capability-specific validation rules. The initial rule enforces that `ctx.api.v1.snowflake.query(sql, params?, options?)` must receive SQL text authored in the handler (string literals, template literals, or const variables resolving to them), not dynamically constructed from client input. Violations report the file and line number.
+- Added: Path resolution for `ctx.api.v1.*` usage tracking. The validator follows `const` aliases and destructuring (e.g., `const sf = ctx.api.v1.snowflake; sf.query(...)` is recognized as Snowflake usage, as is `const { snowflake: sf } = ctx.api.v1`). The handler's first parameter is treated as `ctx` even when renamed.
+- Added: New backend AST utilities exported from `@mondaydotcomorg/z2h-cli/backend/ast`: `collectBindings(program)` returns every variable declaration and tracks which names are unpinnable (reassigned, parameters). `createPathResolver(bindings, contextParam?)` resolves member expression chains through const aliases. `collectApiDomains(program, paths)` returns every `ctx.api.v1.<domain>` the program touches.
+- Added: Handler declaration analysis utilities exported from `@mondaydotcomorg/z2h-cli/backend/handler-declaration`: `findHandlerDeclaration(body)` locates the top-level `handler` binding, `exportsHandler(node)` detects export statements for handler, `handlerContextParamName(declaration)` extracts the first parameter name.
+- Added: Parse utilities exported from `@mondaydotcomorg/z2h-cli/backend/parse`: `parseOrThrow(file, code)` parses handler source as a script and throws descriptive errors for syntax issues, module-only syntax (import/export/top-level await), or export of handler.
+- Added: Validation entry point exported from `@mondaydotcomorg/z2h-cli/backend/validate`: `validateHandlerSource(file, source)` returns `{ apiDomains: string[] }` after running all checks. Throws on violations.
+- Added: Handler rule system types exported from `@mondaydotcomorg/z2h-cli/backend/rules`: `HandlerRule` interface with `name: string` and `check(ctx: RuleContext): string[]`. `RuleContext` provides `file`, `program`, `bindings`, and `paths`. `HANDLER_RULES` array contains all active rules.
+- Changed: `DECLARED_INTEGRATIONS` constant is now imported from `@mondaydotcomorg/z2h-shared-utils` instead of being defined locally in `@mondaydotcomorg/z2h-cli/constants`. The constant is re-exported for backward compatibility.
+- Added: Parse error tracking. When a handler fails to parse, the CLI emits a `z2h_cli_handler_parse_error` event with the error message that was shown to the user.
+- Changed: Handler validation errors now provide structured messages via `messages` object in `@mondaydotcomorg/z2h-cli/backend/messages`, including `mustDefine(file)`, `notAFunction(file)`, `mustNotImport(file)`, `mustNotExportHandler(file)`, `mustNotExport(file)`, `moduleOnlySyntax(file, detail)`, and `syntaxError(file, line, column, detail)`.
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.27.1` (September 16, 2026, 07:24)
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.27.0` (September 16, 2026, 06:06)
+
+### New Features
+
+- [#387](https://github.com/DaPulse/bigbrain-z2h/pull/387) feat(z2h): fetch dataviz skill from S3 at agent startup (@arielmonday)
+- Added: New exported constant `S3_SKILLS_BUCKET_NAME` set to `'prod-use1-bigbrain-zth-skills'`. This constant defines the S3 bucket name where dataviz design-system skills are published by data-cookbook's CI pipeline. Both `bigbrain-zth` (which mints read-only STS credentials) and `bigbrain-zth-agent` (which syncs vendor files at pod startup) import this constant to ensure consistency across services.
+  ```ts
+  import { S3_SKILLS_BUCKET_NAME } from '@mondaydotcomorg/z2h-cli';
+  // S3_SKILLS_BUCKET_NAME === 'prod-use1-bigbrain-zth-skills'
+  ```
+
+- Added: New exported constant `DATAVIZ_SKILLS_PREFIX` set to `'dataviz/'`. This constant defines the S3 object key prefix under which dataviz skills are stored in the skills bucket. The agent uses this prefix to determine which objects to sync into its local `vendor/` directory at startup.
+  ```ts
+  import { DATAVIZ_SKILLS_PREFIX } from '@mondaydotcomorg/z2h-cli';
+  // DATAVIZ_SKILLS_PREFIX === 'dataviz/'
+  // Used to construct full S3 keys like: dataviz/monday-data-viz-vibe/SKILL.md
+  ```
+
+- Changed: The constants file now serves as a shared source of truth for S3 skills bucket configuration between the CLI, backend service (`bigbrain-zth`), and agent (`bigbrain-zth-agent`). This ensures bucket name and prefix values cannot drift between services that need to coordinate on S3 access.
+
+## `0.26.4` (September 15, 2026, 10:53)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+- Upgrade `dashboard-templates` version
+
+## `0.26.3` (September 14, 2026, 11:08)
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.26.2` (September 14, 2026, 09:55)
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.26.1` (September 10, 2026, 11:01)
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.26.0` (September 10, 2026, 10:27)
+
+### New Features
+
+- [#389](https://github.com/DaPulse/bigbrain-z2h/pull/389) feat(z2h-cli): dashboard generation commands (generate/templates/deploy --prebuilt-dir) (@EranZidkiya)
+- Added: New `z2h-cli templates` command that lists all available dashboard templates from the `@mondaydotcomorg/z2h-dashboard-templates` catalog. Returns template metadata including id, title, description, and the JSON Schema for each template's configuration shape. Example usage:
+  ```bash
+  z2h-cli templates
+  z2h-cli templates --json
+  ```
+
+- Added: New `z2h-cli generate-app-template <app-name>` command that scaffolds a Z2H app from a prebuilt template without requiring a full build or yarn install. Copies a catalog template, patches its prebuilt bundle with real widget data, and deploys a preview. Requires `--template <id>` (catalog template id) and `--input <json>` (template-specific configuration validated against the template's schema). Example usage:
+  ```bash
+  z2h-cli generate-app-template my-dashboard --template sales-dashboard --input '{"title":"Q1 Sales","widgets":[...]}'
+  ```
+
+- Added: New `--prebuilt-dir <path>` option to `z2h-cli deploy` command. When provided, skips the build step entirely and deploys an already-built directory as-is. This is used internally by the `generate-app-template` command to deploy string-patched bundles without rebuilding. Example usage:
+  ```bash
+  z2h-cli deploy --preview --prebuilt-dir .zth/build-patched
+  ```
+  The `buildAndStamp` internal function now accepts an optional `prebuiltDir` parameter and copies from it instead of invoking `buildCommand()` when present.
+
+- Added: New module `src/util/dashboard-templates/load-catalog.ts` that provides utilities for loading and validating dashboard templates. Exports `loadDashboardTemplatesCatalog()` which returns an array of `DashboardTemplateEntry` objects (id, title, description, templateDir, configSchema, validateConfig), and `findTemplate(id)` which locates a specific template by id or throws if not found. Templates are loaded from the `@mondaydotcomorg/z2h-dashboard-templates` package's `templates/` directory.
+
+- Added: New module `src/util/dashboard-templates/patch-bundle.ts` that implements string-based patching of minified JavaScript bundles. Exports `patchBuiltBundle(sourceBuildDir, outDir, config)` which finds all MF entrypoints, locates the `/*! Z2H_CONFIG_V1 */` anchor comment in each, and replaces the immediately-following object literal with real configuration data. Also exports `patchOneFile(src, config)` for single-file patching. This enables template instantiation without rebuilding.
+
+- Added: New `generateCommand(appName, opts)` function in `src/commands/generate.ts` that orchestrates the full template generation pipeline: validates app name uniqueness, copies template files (excluding node_modules, .build-shadow, and setup files), patches package.json with the new app name, resolves workspace protocol dependencies to real versions, patches the config source file (`src/templateConfig.ts`), invokes optional `toFrontendConfig` hook to strip sensitive data, patches the prebuilt bundle via `patchBuiltBundle`, invokes optional `setupBackend` hook to generate backend handlers, initializes a git repo, and deploys a preview.
+
+- Changed: The `create` command description now clarifies that it scaffolds a "blank Z2H consumer app" using built-in templates (default | html-embed), and suggests using `generate-app-template` instead if a catalog template already fits the use case.
+
+- Changed: Internal `DeployOptions` interface in `src/commands/deploy.ts` now includes an optional `prebuiltDir?: string` field used by the generate pipeline to skip builds and reuse already-patched directories.
+
+### Dependency Upgrades
+
+- Upgrade `dashboard-templates` version
+
+## `0.25.9` (September 9, 2026, 10:21)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.8` (September 8, 2026, 11:37)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.7` (September 6, 2026, 09:22)
+
+### Improvements
+
+- [#372](https://github.com/DaPulse/bigbrain-z2h/pull/372) refactor(z2h-cli): single command wrapper for telemetry + bounded failure reasons (@eitan-ts)
+- Changed: `Z2hAuthMissingError` export path moved from `@mondaydotcomorg/z2h-cli/auth/auth-store` to `@mondaydotcomorg/z2h-cli/util/errors`. Update your imports:
+  *Before:*
+  ```ts
+  import { Z2hAuthMissingError } from '@mondaydotcomorg/z2h-cli/auth/auth-store';
+  ```
+  *After:*
+  ```ts
+  import { Z2hAuthMissingError } from '@mondaydotcomorg/z2h-cli/util/errors';
+  ```
+- Added: New `Z2hError` base class for all classified CLI errors. All Z2H error types now extend this base and include `reason: string`, optional `data: Record<string, unknown>`, and `exitCode: number` properties. This enables programmatic error classification.
+  ```ts
+  class Z2hError extends Error {
+    constructor(message: string, reason: string, data?: Record<string, unknown>, exitCode?: number);
+    readonly reason: string;
+    readonly data?: Record<string, unknown>;
+    readonly exitCode: number;
+  }
+  ```
+- Added: New `DeployError` class for deploy/preview failures with bounded reason codes. The `reason` field is now one of: `'read_auth_token'`, `'broker_auth'`, `'broker_error'`, `'lock_timeout'`, `'build_error'`, `'git_error'`, `'s3_error'`, `'deploy_backend_error'`, `'register_error'`, `'push_error'`, `'interrupted'`, or `'unknown'`.
+  ```ts
+  class DeployError extends Z2hError {
+    constructor(reason: DeployFailureReason, message: string, data?: Record<string, unknown>);
+  }
+  ```
+- Added: New `GrantError` class for grant/revoke/transfer-owner failures with bounded reason codes. The `reason` field is now one of: `'validation'`, `'auth'`, `'forbidden'`, `'not_found'`, `'server_error'`, or `'unknown'`. Can be constructed with an HTTP status code that will be automatically mapped to the appropriate reason.
+  ```ts
+  class GrantError extends Z2hError {
+    constructor(reason: GrantFailureReason | number, message: string, data?: Record<string, unknown>);
+  }
+  ```
+- Changed: `Z2hAuthMissingError` now extends `Z2hError` and includes `reason: 'read_auth_token'` for programmatic detection.
+- Changed: `GitConflictError` now extends `Z2hError` and includes `reason: 'git_error'` or a stage-specific reason for programmatic detection.
+- Changed: All CLI commands now emit telemetry events automatically via a unified `runCommand` wrapper. Commands no longer need individual try/catch blocks or manual telemetry calls.
+- Changed: CLI version is now automatically stamped on all telemetry events via the `cli_version` dimension. Previously this was not included.
+- Changed: Error telemetry payload now includes a bounded `reason` field instead of freeform error messages. The canonical `error` and `action` fields now appear last in the payload, preventing caller keys from shadowing them.
+- Changed: Deploy failures during the build stage (consumer code compilation errors) are no longer tracked as CLI errors, since they represent user code issues rather than infrastructure problems. The error still surfaces to the user with exit code 2.
+- Changed: Preview deploys (`deploy --preview`) now emit full error telemetry with classified reasons. Previously, preview failures bypassed classification and always reported as `unknown`.
+- Changed: Lock acquisition failures now distinguish between contention (`lock_timeout` when someone else holds the lock), authentication issues (`broker_auth` for 401/403), and infrastructure problems (`broker_error` for other failures). Previously all non-409 statuses were reported as lock contention.
+- Changed: Git synchronization failures (dirty working tree or diverged branches) are now classified as `git_error` instead of `unknown`.
+- Changed: The package now imports its own version via the self-referencing `@mondaydotcomorg/z2h-cli/package.json` export instead of a relative path.
+- Added: New `successEvent(command: string): string` helper that generates success event names following the `z2h_cli_<command>_success` pattern. Nested commands join their path with underscores (e.g., `backend invoke` becomes `z2h_cli_backend_invoke_success`).
+- Added: Five commands that previously had no success telemetry now emit success events: `generate-z2h-token`, `grant`, `revoke`, `transfer-owner`, and `migrate`. The event names follow the `z2h_cli_<command>_success` pattern.
+- Unchanged: The following seven pre-existing success event names remain unchanged for backward compatibility with downstream analytics: `z2h_app_build_success`, `z2h_app_deploy_success`, `z2h_app_preview_success`, `z2h_app_tag_success`, `z2h_app_created`, `z2h_app_edit_pulled`, `z2h_app_delete_success`, `z2h_backend_invoke_success`.
+- Changed: Commands with no success event (`clean`, `create-workspace`, `doctor`) no longer emit error events either, fixing a previous inconsistency where they emitted errors but not successes.
+- Changed: Telemetry now uses `createHttpTracker` from `@mondaydotcomorg/z2h-shared-utils/observability` instead of a local implementation, providing consistent HTTP-based event tracking.
+- Added: New `CommandSpec<A>` type for specifying command telemetry behavior, including optional `track`, `event`, `label`, `data`, and `exitCode` fields. This type is used by the `runCommand` wrapper.
+- Added: New `DeployFailureReason` and `GrantFailureReason` type unions exported from the main package, providing the complete set of bounded reason codes.
+- Added: New utility functions for error handling: `grantReasonForStatus(status: number): GrantFailureReason` (maps HTTP status to grant error reason), `tagDeployError(reason: DeployFailureReason, err: unknown): Z2hError` (tags errors unless already classified), `reasonOf(err: unknown): string` (extracts reason or returns `'unknown'`), `dataOf(err: unknown): Record<string, unknown>` (extracts extra dimensions), and `messageOf(err: unknown): string` (safe message extraction for any thrown value).
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.6` (September 6, 2026, 08:33)
+
+### Improvements
+
+- [#411](https://github.com/DaPulse/bigbrain-z2h/pull/411) Reword storage-vs-GitHub prompt in create-app flow (@arielmonday)
+- Changed: The `--remote` flag help text in both `z2h-cli create` and `z2h-cli deploy` commands now explicitly recommends S3 storage and emphasizes automatic backup. The new help text reads: "s3 (shared storage, recommended, auto-backed-up) or github (manage it yourself in your own repo)" instead of the previous "s3 (shared storage) or github (your repo)".
+
+- Changed: The first-deploy error message when no `--remote` is specified now uses more user-friendly language. The S3 option description changed from "Stores source history in S3 alongside your app. No extra setup." to "We store and back up your code for you automatically. No extra setup." The GitHub option description changed from "Uses an existing GitHub repo" to "Manage it yourself in an existing GitHub repo".
+  *Before:*
+  ```
+  z2h-cli deploy --remote s3 (default)
+      Stores source history in S3 alongside your app. No extra setup.
+
+  z2h-cli deploy --remote github --repo-url https://github.com/org/repo.git
+      Uses an existing GitHub repo (must exist before deploying).
+  ```
+  *After:*
+  ```
+  z2h-cli deploy --remote s3 (default, recommended)
+      We store and back up your code for you automatically. No extra setup.
+
+  z2h-cli deploy --remote github --repo-url https://github.com/org/repo.git
+      Manage it yourself in an existing GitHub repo (must exist before deploying).
+  ```
+
+- Changed: The S3 option is now explicitly marked as "(default, recommended)" instead of just "(default)" in error messages, making the recommended choice clearer to users.
+
+## `0.25.5` (September 6, 2026, 07:21)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.4` (September 3, 2026, 06:26)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.3` (September 2, 2026, 15:08)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.2` (September 2, 2026, 14:48)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.1` (September 2, 2026, 14:20)
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.25.0` (September 2, 2026, 11:05)
+
+### New Features
+
+- [#399](https://github.com/DaPulse/bigbrain-z2h/pull/399) refactor(z2h-cli): extract MF scaffold templates into z2h-shared-utils (@EranZidkiya)
+- Refactored: Microfrontend scaffold templates are no longer defined locally in `shadow/scaffold.ts`. The CLI now imports `WRAPPER_TEMPLATE`, `tridentrcTemplate`, `dtsFileTemplate`, and `TSCONFIG_TEMPLATE` from the shared package `@mondaydotcomorg/z2h-shared-utils/mf-scaffold`. This consolidates template definitions across the Z2H toolchain and eliminates drift between multiple copies of scaffold code.
+  *Before:*
+  ```ts
+  // In packages/z2h-cli/src/shadow/scaffold.ts
+  const WRAPPER_TEMPLATE = `import '@vibe/core/tokens';
+  // ... template defined locally
+  `;
+  ```
+  *After:*
+  ```ts
+  import {
+    WRAPPER_TEMPLATE,
+    tridentrcTemplate,
+    dtsFileTemplate,
+    TSCONFIG_TEMPLATE,
+  } from '@mondaydotcomorg/z2h-shared-utils/mf-scaffold';
+  ```
+- Internal: The scaffold templates now use typed React wrapper parameters (`new Map<HTMLElement, ReactDOM.Root>()`, `render(element: HTMLElement)`), ensuring type safety in generated consumer app wrappers.
+
+### Dependency Upgrades
+
+- Upgrade `z2h-shared-utils` version
+
+## `0.24.2` (September 2, 2026, 06:34)
+
+### Bug Fixes
+
+- [#397](https://github.com/DaPulse/bigbrain-z2h/pull/397) fix(z2h-cli): scaffold and reinstall correctly when node_modules is mounted separately from the workspace (@arielmonday)
+- Fixed: The `create-workspace` command now correctly scaffolds new workspaces when `node_modules` is mounted as a separate volume. Previously, the command checked if the target directory contained any entries to decide whether the workspace already existed. When an emptyDir volume is mounted at `node_modules` (common in PVC-backed environments), the directory would always contain at least one entry, causing the command to skip scaffolding entirely even on brand-new workspaces. The logic now checks for the presence of the `z2hWorkspace: true` marker in `package.json` via the new `isZ2hWorkspace()` utility function instead of counting directory entries.
+
+- Changed: Workspace scaffolding and dependency installation are now evaluated independently. The command first checks `isZ2hWorkspace()` to determine if scaffold files (`package.json`, `.yarnrc.yml`, `yarn.lock`, etc.) need to be written. Separately, it checks if `node_modules` is populated. Yarn install now runs if *either* the workspace was just scaffolded *or* `node_modules` is missing/empty, ensuring dependencies are always available even when the workspace structure already exists but the modules directory was cleared or mounted fresh.
+
+- Added: New internal helper function `isPopulated(dir: string): Promise<boolean>` that checks whether a directory exists and contains at least one entry. This is used to determine if `node_modules` needs to be repopulated.
+
+- Changed: Informational logging messages now appear before their respective operations. The message "setting up your Z2H workspace" now displays before scaffolding files, and "installing workspace dependencies — this may take a minute" appears before running `yarn install`. Previously, the setup message appeared only before the install step.
+
+## `0.24.1` (August 31, 2026, 13:31)
+
+### Bug Fixes
+
+- [#392](https://github.com/DaPulse/bigbrain-z2h/pull/392) fix(z2h-cli): make Ctrl-C work at the interactive prompts (@eitan-ts)
+- Fixed: Ctrl-C now properly exits at the token paste prompt in `z2h-cli generate-z2h-token`. Previously, pressing Ctrl-C at the "Paste your token here" prompt would only pause the interface with no way to exit except killing the terminal. The CLI now exits with status code 130 (shell convention for SIGINT) when Ctrl-C is pressed.
+
+- Fixed: The advertised Ctrl-C fallback during token loopback is now functional in `z2h-cli generate-z2h-token`. The prompt "waiting for the page to send the token (Ctrl+C to fall back to manual paste)" has displayed since the feature's introduction, but pressing Ctrl-C would kill the CLI instead of falling back to manual paste. The loopback wait now races against a SIGINT listener, and when Ctrl-C is pressed, the CLI cleanly transitions to the manual token paste prompt.
+
+- Fixed: Ctrl-C now properly exits at the tag selection prompt in `z2h-cli tag`. Previously, pressing Ctrl-C during tag selection would only pause the interface with no way to exit. The CLI now exits with status code 130 when Ctrl-C is pressed.
+
+- Changed: Added proper cleanup handling to prevent unhandled promise rejections when cancelling the loopback token wait. The `waitForToken` promise is now caught before racing, ensuring that when `LoopbackHandle.close()` rejects the pending wait, it doesn't crash the CLI with an unhandled rejection.
+
+- Changed: The SIGINT listener during loopback token wait is now properly detached in a `finally` block, ensuring it only suppresses Node's default termination during the wait period and not after.
+
+## `0.24.0` (August 30, 2026, 12:51)
+
+### New Features
+
+- [#380](https://github.com/DaPulse/bigbrain-z2h/pull/380) fix(z2h-cli): correctness fixes found while building the beta mechanism (@yarinmonday)
+- Added: New exported `baseVersion` function that strips prerelease identifiers from semver versions to extract the base major.minor.patch version. This function parses a version string and returns only the base version components, throwing an error if the version is invalid.
+  ```ts
+  export function baseVersion(version: string): string {
+    const parsed = semver.parse(version);
+    if (!parsed) {
+      throw new Error(`invalid semver version: ${version}`);
+    }
+    return `${parsed.major}.${parsed.minor}.${parsed.patch}`;
+  }
+  ```
+
+- Changed: Migration version comparison logic now uses base versions instead of full versions with prerelease tags. Previously, the `migrateCommand` function compared the raw CLI version directly against the last migrated version. Now it extracts the base version first using `baseVersion(cliVersion)` before comparisons. This prevents prerelease versions (which sort below their release version in semver) from incorrectly skipping migrations they introduce.
+  *Before:*
+  ```ts
+  if (!semver.gt(cliVersion, lastVersion)) {
+    info('workspace is up to date — no migrations pending');
+    return;
+  }
+  ```
+  *After:*
+  ```ts
+  const targetVersion = baseVersion(cliVersion);
+  if (!semver.gt(targetVersion, lastVersion)) {
+    info('workspace is up to date — no migrations pending');
+    return;
+  }
+  ```
+
+- Changed: Pending migration filtering now uses base version for upper bound comparison. The filter that selects migrations between `lastVersion` and the current CLI version now compares against `targetVersion` (the base version) instead of `cliVersion`.
+  *Before:*
+  ```ts
+  const pending = Object.entries(migrationsJson.migrations)
+    .filter(([, entry]) => semver.gt(entry.version, lastVersion) && semver.lte(entry.version, cliVersion))
+  ```
+  *After:*
+  ```ts
+  const pending = Object.entries(migrationsJson.migrations)
+    .filter(([, entry]) => semver.gt(entry.version, lastVersion) && semver.lte(entry.version, targetVersion))
+  ```
+
+- Changed: Migration state persistence now records base version instead of full version. When writing the last migrated version to state, the function now stores `targetVersion` (base version) rather than the full `cliVersion` with prerelease tags. This ensures consistent version tracking across prerelease and release versions.
+  *Before:*
+  ```ts
+  await writeMigrationState(workspaceHome, { lastMigratedVersion: cliVersion });
+  ```
+  *After:*
+  ```ts
+  await writeMigrationState(workspaceHome, { lastMigratedVersion: targetVersion });
+  ```
+
+- Changed: Migration progress logging now displays base version. The info message that logs migration progress now shows the base target version instead of the full CLI version with prerelease identifiers.
+  *Before:*
+  ```ts
+  info(`migrating workspace from v${lastVersion} → v${cliVersion}...`);
+  ```
+  *After:*
+  ```ts
+  info(`migrating workspace from v${lastVersion} → v${targetVersion}...`);
+  ```
+
+## `0.23.1` (August 25, 2026, 14:54)
+
+### Improvements
+
+- [#369](https://github.com/DaPulse/bigbrain-z2h/pull/369) fix(z2h-cli): remove dead direct S3 manifest write path (@eitan-ts)
+- Removed: `readManifest()` function that fetched the asset manifest from the public CDN endpoint. This function was unused; deploy registration now retrieves manifest data through the backend API (`registerOrUpdateApp` → `bigbrain-zth`'s `registerApp`/`updateApp`) which reads from RDS, not S3.
+- Removed: `nextVersion(manifest: Manifest, app: string)` function that calculated the next version number for an app by incrementing the current version from the manifest. This function was unused; version management is now handled by the backend API during app registration.
+- Removed: `upsertEntry(manifest: Manifest, app: string, entry: ManifestEntry)` function that added or updated a manifest entry in the in-memory manifest object. This function was unused; manifest updates are now persisted directly to RDS via the backend API.
+- Removed: `writeManifest(manifest: Manifest)` function that wrote the entire manifest to S3 using `PutObjectCommand`. This function was unused; the host microfrontend now builds its runtime manifest dynamically from RDS data instead of reading a static S3 object.
+  *Previously:*
+  ```typescript
+  await writeManifest(updatedManifest);
+  ```
+  *Migration:* Use `registerOrUpdateApp()` from the CLI's broker utilities to register/update apps through the backend API, which persists to RDS.
+- Removed: S3-related imports (`PutObjectCommand` from `@aws-sdk/client-s3`, `getS3Client` utility, and `BUCKET_WRITE_NAME`/`MANIFEST_KEY`/`MANIFEST_READ_URL` constants from the import list). These imports were only used by the removed manifest functions. Note: `MANIFEST_KEY` and `MANIFEST_READ_URL` constants remain defined in `constants.ts` as they are still referenced by a migration script in the `bigbrain-zth` backend.
+- Unchanged: All TypeScript type definitions (`SharedDep`, `AssetManifestFile`, `ManifestEntry`, `Manifest`) remain exported from this module. These types are still consumed by `deploy.ts` and `util/broker/app.ts` for structuring deploy metadata sent to the backend API.
+
+## `0.23.0` (August 24, 2026, 09:09)
+
+### New Features
+
+- [#361](https://github.com/DaPulse/bigbrain-z2h/pull/361) feat(mf-project-builders-cli): add CLI package for uploading MF preview builds (@eitan-ts)
+- Added: New public export file `src/auth.ts` that re-exports authentication utilities for use by other packages. Exports `generateZ2HTokenCommand` (function), `GenerateZ2HTokenOptions` (type), `readZthAuth` (function), `Z2hAuthMissingError` (class), `Z2H_AUTH_FILE` (constant), and `ZthAuth` (type) from internal modules.
+  *Usage:*
+  ```ts
+  import { readZthAuth, generateZ2HTokenCommand } from '@mondaydotcomorg/z2h-cli/auth';
+  const { token } = await readZthAuth();
+  ```
+- Added: New public export file `src/s3.ts` that re-exports S3 utilities for use by other packages. Exports `setupS3Client` (function), `getS3Client` (function), and `uploadDir` (function) from internal S3 modules.
+  *Usage:*
+  ```ts
+  import { setupS3Client, uploadDir } from '@mondaydotcomorg/z2h-cli/s3';
+  setupS3Client({ accessKeyId, secretAccessKey, sessionToken });
+  const keys = await uploadDir('/path/to/build', 'prefix', 'my-bucket');
+  ```
+- Changed: The `uploadDir` function now accepts an optional third parameter `bucket` (string) to specify a custom S3 bucket name. When omitted, defaults to the existing `BUCKET_WRITE_NAME` constant, preserving backward compatibility.
+  *Before:*
+  ```ts
+  await uploadDir(localDir, keyPrefix); // always uploads to BUCKET_WRITE_NAME
+  ```
+  *After:*
+  ```ts
+  await uploadDir(localDir, keyPrefix); // still defaults to BUCKET_WRITE_NAME
+  await uploadDir(localDir, keyPrefix, 'custom-bucket'); // now supports custom bucket
+  ```
+
+## `0.22.0` (August 18, 2026, 12:12)
+
+### New Features
+
+- [#337](https://github.com/DaPulse/bigbrain-z2h/pull/337) Feat/yarin/backend support enable (@yarinmonday)
+- Added: New backend support infrastructure with `backend/client.ts` module providing HTTP client functions for backend runner operations: `invokeBackend(appName, handlerName, input)` to invoke deployed handlers, `listAppIntegrations(appName)` to retrieve app integrations, `declareIntegration(appName, integration)` and `removeIntegration(appName, integration)` to manage integrations, and `backendBaseUrl()` to resolve the runner origin with `Z2H_BACKEND_URL` environment variable override support.
+- Added: Automatic integration detection from handler source code via `detectIntegrationsFromHandlers(handlers)` in `backend/detect-integrations.ts`, which scans for `ctx.api.v1.<name>` patterns matching entries in the `DECLARED_INTEGRATIONS` constant (currently `['monday']`). OAuth-gated integrations are auto-registered; always-on channels like `db`, `llm`, and `snowflake` are excluded.
+- Added: Handler validation and reading via `readHandlers(consumerDir)` in `backend/handlers.ts`, which reads `.js` files from `backend/handlers/` directory and validates that each handler defines a global `handler` function or variable (not exported), rejects TypeScript files with an error instructing users to compile first, rejects handlers with `export` prefix (isolate has no module system), and rejects handlers containing `import` or `require` statements (handlers are self-contained).
+- Added: Backend deployment support via `deployBackend()` in `commands/backend.ts`, which reads handlers, detects integrations, and uploads each `.js` handler as a flat file to S3 (no compilation or bundling) along with a `meta.json` manifest. Live deploys use `<appName>/backend-<version>` path; preview deploys use `<mfKeyPrefix without /MF>/MS` path. The function returns detected integrations for platform registration.
+- Added: New CLI command `z2h-cli backend invoke <handlerName>` to invoke a deployed backend handler by name for testing purposes without going through the frontend.
+  *Usage:*
+  ```bash
+  z2h-cli backend invoke call_snowflake --input '{"boardId":"123"}'
+  ```
+- Changed: Deploy flow now includes backend deployment via new `uploadAndRegister()` helper function, which uploads frontend build, deploys backend handlers (if present), auto-detects integrations from handler sources, and registers the release with the platform in a single transaction. Both `deployPreview()` and `deployLive()` now use this unified path.
+- Changed: App registration and update API calls in `util/broker/app.ts` now accept an optional `integrations` parameter that is passed to the broker's `/z2h-cli/apps/register` and `/z2h-cli/apps/update` endpoints. The integration set is reconciled to exactly match the detected set on every deploy.
+- Changed: Generated app template in `templates/app/html-index.tsx.tmpl` no longer includes backend base URL resolution via `getBackendBaseUrl()` or postMessage-based config injection. The iframe component is simplified (no `useRef`, no `useEffect`, no message event listener) as the runtime SDK now handles backend communication transparently.
+- Changed: Generated workspace `package.json` template now includes `@mondaydotcomorg/z2h-runtime-sdk` dependency at version `^0.1.0`.
+- Added: `DECLARED_INTEGRATIONS` constant exported from `constants.ts` as a closed set of OAuth-gated integrations (currently `['monday']`) that the CLI detects from handler sources and the broker validates on register/update.
+
+## `0.21.2` (August 17, 2026, 13:26)
+
+### Improvements
+
+- [#327](https://github.com/DaPulse/bigbrain-z2h/pull/327) feat(z2h-cli): sticky previewId — generate once, reuse on subsequent deploys (@arielmonday)
+- **Breaking Change**: Removed `--previewId` parameter from the `deploy --preview` command. The CLI no longer accepts a custom preview ID via the command line.
+  *Before:*
+  ```bash
+  z2h-cli deploy --preview abc123
+  ```
+  *After:*
+  ```bash
+  z2h-cli deploy --preview
+  ```
+- Changed: Preview deployments now generate a stable, persistent preview ID that is automatically reused across subsequent deploys. The `previewId` is generated once (8-character UUID prefix) and stored in `.zth/metadata.json`, ensuring the preview URL remains constant for the same app across rebuilds.
+- Changed: The `previewId` field has been added to the `ShadowMetadata` interface in `src/types.ts`, making it part of the persisted metadata alongside `createdAt`, `appName`, and `port`.
+- Changed: The `resolvePortAndMetadata` function in `src/shadow/prepare.ts` is now exported and enhanced to manage both port and preview ID persistence. It generates a new `previewId` on first run and reuses the existing one from metadata on subsequent runs.
+- Changed: Preview ID generation logic moved from `deploy.ts` to `shadow/prepare.ts`. The `deployPreview` function now calls `resolvePortAndMetadata` to obtain the sticky `previewId` instead of generating a new one with `randomUUID()` or accepting one via CLI options.
+- Changed: The `DeployOptions` interface in `src/commands/deploy.ts` no longer includes the `previewId` field. The option parsing and handling logic for `--preview [previewId]` has been simplified to treat `--preview` as a boolean flag only.
+- Changed: Enhanced logging granularity in `deployLive` and `deployPreview` functions with new info messages: "getting sts credentials", "updating manifest", "acquiring deploy lock", and "releasing deploy lock" to provide better visibility into deployment steps.
+- Changed: The `--preview` CLI option description updated to clarify that it "reuses the same preview URL across runs (stable link)" instead of the previous behavior where each deploy could mint a new preview URL.
+
+## `0.21.1` (August 17, 2026, 12:57)
+
+### Improvements
+
+- [#341](https://github.com/DaPulse/bigbrain-z2h/pull/341) feat(z2h): generate + store app descriptions on deploy (@EranZidkiya)
+- Added: The `deploy` command now accepts an optional `--description <text>` flag that allows passing a short (<=200 character) description of the app during deployment. This description is forwarded to the backend and stored in the app metadata.
+  *Usage:*
+  ```bash
+  z2h-cli deploy --description "Customer analytics dashboard with real-time metrics"
+  ```
+- Changed: The `DeployOptions` interface now includes an optional `description?: string` field to support passing app descriptions through the deployment flow.
+  *Before:*
+  ```typescript
+  export interface DeployOptions {
+    previewId?: string;
+    open?: boolean;
+  }
+  ```
+  *After:*
+  ```typescript
+  export interface DeployOptions {
+    previewId?: string;
+    open?: boolean;
+    description?: string;
+  }
+  ```
+- Changed: The `registerApp` function now accepts an optional `description?: string` parameter that is included in the registration payload sent to the backend when creating a new app for the first time.
+  *Before:*
+  ```typescript
+  async function registerApp(
+    appName: string,
+    token: string,
+    version: number,
+    entry: ManifestEntry,
+    visibility: 'public' | 'private',
+    gitRemote: string
+  ): Promise<void>
+  ```
+  *After:*
+  ```typescript
+  async function registerApp(
+    appName: string,
+    token: string,
+    version: number,
+    entry: ManifestEntry,
+    visibility: 'public' | 'private',
+    gitRemote: string,
+    description?: string
+  ): Promise<void>
+  ```
+- Changed: The `updateApp` function now accepts an optional `description?: string` parameter that is included in the update payload sent to the backend when updating an existing app.
+  *Before:*
+  ```typescript
+  async function updateApp(
+    appName: string,
+    token: string,
+    version: number,
+    entry: ManifestEntry,
+    gitRemote: string
+  ): Promise<void>
+  ```
+  *After:*
+  ```typescript
+  async function updateApp(
+    appName: string,
+    token: string,
+    version: number,
+    entry: ManifestEntry,
+    gitRemote: string,
+    description?: string
+  ): Promise<void>
+  ```
+- Changed: The `RegisterOrUpdateOptions` interface now includes an optional `description?: string` field to thread app descriptions through the registration/update flow.
+  *Before:*
+  ```typescript
+  export interface RegisterOrUpdateOptions {
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: ManifestEntry;
+    gitRemote: string;
+  }
+  ```
+  *After:*
+  ```typescript
+  export interface RegisterOrUpdateOptions {
+    appName: string;
+    token: string;
+    nextVersion: number;
+    entry: ManifestEntry;
+    gitRemote: string;
+    description?: string;
+  }
+  ```
+- Changed: The `registerOrUpdateApp` function now threads the `description` parameter from the options through to both `registerApp` and `updateApp` calls, ensuring descriptions are forwarded to the backend regardless of whether this is a first deploy or an update.
+
+## `0.21.0` (August 13, 2026, 11:27)
+
+### New Features
+
+- [#324](https://github.com/DaPulse/bigbrain-z2h/pull/324) Feat/yarin/backend support invoke (@yarinmonday)
+
+## `0.20.0` (August 13, 2026, 07:45)
+
+### New Features
+
+- [#315](https://github.com/DaPulse/bigbrain-z2h/pull/315) Feat/yarin/backend support channels (@yarinmonday)
+
+## `0.19.0` (August 12, 2026, 10:38)
+
+### New Features
+
+- [#326](https://github.com/DaPulse/bigbrain-z2h/pull/326) feat(z2h): direct same-origin fixes for html-embed iframes (@EranZidkiya)
+- Changed: HTML-embed app template now routes iframe sources through the `/z2h-assets` proxy instead of using direct CDN URLs, making iframes same-origin with the host. The template (`html-index.tsx.tmpl`) now includes a `toProxiedUrl` utility function that rewrites CDN URLs (`https://bigbrain-zth-mf-assets.bigbrain.me`) to proxy paths (`/z2h-assets/...`). The iframe element's `src` attribute is now wrapped with this function.
+  *Before:*
+  ```tsx
+  <iframe
+    ref={iframeRef}
+    src={pageUrl}
+    title="App"
+    style={{ width: '100vw', height: '100vh', border: 'none', display: 'block' }}
+  />
+  ```
+  *After:*
+  ```tsx
+  const Z2H_MFS_BASE_URL = 'https://bigbrain-zth-mf-assets.bigbrain.me';
+  const Z2H_ASSETS_PROXY_PREFIX = '/z2h-assets';
+
+  function toProxiedUrl(url: string): string {
+    if (!url.startsWith(Z2H_MFS_BASE_URL)) return url;
+    return `${window.location.origin}${Z2H_ASSETS_PROXY_PREFIX}${url.slice(Z2H_MFS_BASE_URL.length)}`;
+  }
+
+  // In component:
+  <iframe
+    ref={iframeRef}
+    src={toProxiedUrl(pageUrl)}
+    title="App"
+    style={{ width: '100vw', height: '100vh', border: 'none', display: 'block' }}
+  />
+  ```
+- Added: New migration `007-proxy-iframe-src.ts` that automatically backfills the `toProxiedUrl` fix onto existing html-embed apps created before this version. The migration scans for any `import ... from './path/to/file.html?url'` pattern in `index.tsx` files, injects the `toProxiedUrl` utility function, and rewrites iframe `src` attributes to use it. This migration runs automatically when apps are opened with the updated CLI, ensuring existing apps receive the same-origin iframe behavior without manual intervention.
+- Fixed: HTML-embed iframes now maintain same-origin status with the host application, enabling direct fetch header stamping (e.g., `x-z2h-app-name`) on requests made from within the iframe's JavaScript context. Previously, the iframe loaded HTML files via absolute CDN URLs, making them cross-origin and requiring postMessage-based proxying for backend requests.
+
+## `0.18.1` (August 10, 2026, 13:00)
+
+### Improvements
+
+- [#320](https://github.com/DaPulse/bigbrain-z2h/pull/320) fix(z2h-cli): show access-denied message on 403 instead of token-refresh hint (@arielmonday)
+- Fixed: HTTP 401 and 403 errors are now handled separately in `assertBrokerOk` (broker-credential-provider.ts). Previously, both status codes triggered the same "refresh your token" message, which was misleading for 403 (access denied) scenarios and caused the z2h-agent to hang for 600 seconds in headless environments attempting to run an interactive OAuth command. Now 401 responses display: `Z2H deploy token rejected by the broker (401). Refresh user token by running 'z2h-cli generate-z2h-token'.` while 403 responses display: `Access denied (403). You do not have editor access to this app. Ask the app owner to grant you access via 'z2h-cli grant'.`
+- Added: Explicit 403 error handling in the `fetchApp` function (app.ts). When the broker returns 403 for app lookups (indicating the authenticated user lacks access), the function now throws a clear error message: `Access denied (403). You do not have access to this app. Ask the app owner to grant you access via 'z2h-cli grant'.` This prevents 403 errors from falling through to the generic error handler and provides actionable guidance to users who need access grants.
+- Changed: Error messages for broker authentication failures now include specific HTTP status codes in parentheses (401 vs 403) to disambiguate token expiration from permission denial, improving troubleshooting for both users and automated agents.
+
+## `0.18.0` (August 10, 2026, 10:15)
+
+### New Features
+
+- [#314](https://github.com/DaPulse/bigbrain-z2h/pull/314) Feat/yarin/backend support preview backend (@yarinmonday)
+- Changed: Preview deployment S3 path structure simplified. Preview builds are now stored at `previews/<previewAppName>/MF/` instead of `previews/<appName>/<previewId>/MF/`, where `previewAppName` is the preview's full microfrontend name (e.g., `mf-zth-preview-<id>-<app>`) that already embeds the preview ID. This eliminates the redundant separate `<previewId>` folder level in the S3 hierarchy.
+- Changed: The `brokerCredentialProvider` function now receives the preview's full app name (`previewAppName`) when deploying previews, ensuring STS credentials are scoped to the correct `previews/<previewAppName>/*` path instead of using the base app name separately from the preview ID.
+- Updated: Documentation comments in `broker-credential-provider.ts` and `constants.ts` clarified to reflect that preview credentials are scoped to `previews/<appName>/*` where `appName` is the preview's own app name that already contains the preview ID.
+
+## `0.17.0` (August 9, 2026, 06:55)
+
+### New Features
+
+- [#295](https://github.com/DaPulse/bigbrain-z2h/pull/295) feat(z2h-preview): exclude preview app rows from manifest/listing by … (@yarinmonday)
+- Changed: Preview deployment IDs are now shortened to 8 characters instead of using full UUIDs. When running `z2h-cli deploy` in preview mode without specifying an explicit `--preview-id` option, the CLI now generates an 8-character random identifier (e.g., `a1b2c3d4`) instead of a full 36-character UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`). This results in shorter, more manageable preview URLs and S3 paths while maintaining sufficient uniqueness for concurrent preview deployments.
+  *Before:*
+  ```ts
+  const previewId = opts.previewId ?? randomUUID();
+  // Generated preview ID: '550e8400-e29b-41d4-a716-446655440000'
+  ```
+  *After:*
+  ```ts
+  const previewId = opts.previewId ?? randomUUID().slice(0, 8);
+  // Generated preview ID: '550e8400'
+  ```
+
+## `0.16.0` (August 9, 2026, 06:24)
+
+### New Features
+
+- [#294](https://github.com/DaPulse/bigbrain-z2h/pull/294) feat(z2h-preview): add z2h-cli preview command and broker STS mint route (@yarinmonday)
+- Added: `deploy --preview` command creates ephemeral, shareable preview deployments without requiring git, deploy locks, or affecting the live version. Pass an optional `previewId` to update an existing preview instead of creating a new one.
+  *Usage:*
+  ```bash
+  z2h-cli deploy --preview              # Create new preview
+  z2h-cli deploy --preview <id>         # Update existing preview
+  z2h-cli deploy --preview --open       # Create and open in browser
+  ```
+  Preview URLs follow the pattern: `https://bigbrain.me/bigbrain-vibe/zth-preview-<shortid>-<appName>`
+
+- Added: `--open` flag for `deploy` command automatically opens the deployed app or preview URL in the browser upon successful deployment.
+  *Usage:*
+  ```bash
+  z2h-cli deploy --open                 # Deploy and open live URL
+  z2h-cli deploy --preview --open       # Create preview and open
+  ```
+
+- Removed: `dev` command no longer available. Local development workflow has been replaced by the preview deployment mechanism (`deploy --preview`).
+  *Migration:*
+  ```bash
+  # Before
+  z2h-cli dev
+  
+  # After
+  z2h-cli deploy --preview --open
+  ```
+
+- Changed: `buildCommand` function now returns a `BuildResult` object containing `{ appName, port, buildDir, assetManifest }` instead of `Promise<void>`. This breaking change enables callers to access build artifacts and metadata.
+  *Before:*
+  ```typescript
+  await buildCommand({ publicUrl: 'https://...' });
+  // Returns void, no access to build output
+  ```
+  *After:*
+  ```typescript
+  const result = await buildCommand({ publicUrl: 'https://...' });
+  // result.assetManifest contains Trident's asset-manifest.json
+  // result.buildDir points to the shadow build directory
+  ```
+
+- Added: `validateAppName(appName: string)` centralized validation function enforces app naming rules including lowercase kebab-case pattern, reserved platform names (`generate-z2h-token`), and the new `zth-preview-` prefix reservation.
+
+- Added: `buildPreviewSlug(appName: string, previewId: string)` generates synthetic app names for preview deployments in the format `zth-preview-<shortid>-<appName>`, ensuring uniqueness while keeping names human-readable.
+
+- Added: `isPreviewAppName(appName: string)` utility function determines if a given app name belongs to an ephemeral preview.
+
+- Changed: `brokerCredentialProvider` now accepts an optional `previewId` parameter. When provided, returns STS credentials scoped to `previews/<appName>/<previewId>/*` instead of the full deploy path.
+  *Usage:*
+  ```typescript
+  // Regular deploy credentials
+  const deployCreds = brokerCredentialProvider({ appName: 'mf-demo-app' });
+  
+  // Preview-scoped credentials
+  const previewCreds = brokerCredentialProvider({ 
+    appName: 'mf-demo-app',
+    previewId: 'abc123-...' 
+  });
+  ```
+
+- Added: `registerOrUpdateApp(options)` function centralizes the app registration/update branching logic. Version 1 creates a new app row with visibility prompt; subsequent versions release updates to the existing app.
+
+- Added: `S3_PREVIEWS_FOLDER` constant (`'previews'`) defines the root S3 prefix for ephemeral preview uploads, shared between CLI upload logic and backend STS policy generation.
+
+- Added: `PREVIEW_APP_NAME_PREFIX` constant (`'zth-preview-'`) reserves the naming prefix for preview deployments, preventing real apps from using names that would collide with the ephemeral preview mechanism.
+
+- Removed: SSL certificate check from `doctor` command. The `webpack.llama.fan` certificate validation is no longer performed as it's not required by the preview-based workflow.
+
+- Removed: `start` script from generated app templates. Consumer apps created with `z2h-cli create` no longer include a `start` script that invoked the removed `dev` command.
+
+- Added: Migration `006-remove-start-script.ts` automatically removes dangling `"start": "z2h-cli dev"` scripts from existing consumer package.json files during CLI updates.
+
+- Changed: App registration visibility prompting logic extracted to `util/prompt-visibility.ts` for reuse between deploy and preview flows.
+
+- Changed: App registration and update endpoints moved from `commands/deploy.ts` to `util/broker/app.ts` (`registerApp`, `updateApp`) for better modularity and reuse in preview deployments.
+
+## `0.15.2` (August 5, 2026, 09:43)
+
+### Bug Fixes
+
+- [#303](https://github.com/DaPulse/bigbrain-z2h/pull/303) feat: track Z2H events to staging doorman (@arielmonday)
+- Changed: Event tracking now routes to environment-specific doorman endpoints based on the `NODE_ENV` environment variable. When `NODE_ENV=staging`, the `trackEvent` function sends events to the staging doorman at `https://track-int.bigbrainstaging.me/stage/event`. In all other environments (including production), events are sent to the production doorman at `https://track-int.bigbrain.me/prod/event`. This allows developers to test tracking behavior in staging without polluting production analytics.
+  *Before:*
+  ```ts
+  // Always routed to production endpoint regardless of environment
+  await trackEvent('cli-command-executed', { command: 'build' });
+  // → POST https://track-int.bigbrain.me/prod/event
+  ```
+  *After:*
+  ```ts
+  // In staging environment (NODE_ENV=staging)
+  await trackEvent('cli-command-executed', { command: 'build' });
+  // → POST https://track-int.bigbrainstaging.me/stage/event
+
+  // In production or any other environment
+  await trackEvent('cli-command-executed', { command: 'build' });
+  // → POST https://track-int.bigbrain.me/prod/event
+  ```
+
+## `0.15.1` (August 5, 2026, 09:27)
+
+### Improvements
+
+- [#302](https://github.com/DaPulse/bigbrain-z2h/pull/302) Make --json a global CLI flag instead of per-command (@arielmonday)
+- Changed: The `--json` flag is now a global option on the root CLI program instead of a per-command option. It can now be placed anywhere in the command line.
+  *Before:*
+  ```bash
+  z2h-cli build --json
+  z2h-cli deploy --dry-run --json
+  ```
+  *After (both styles still work):*
+  ```bash
+  z2h-cli build --json
+  z2h-cli --json build
+  z2h-cli --json deploy --dry-run
+  ```
+- Changed: The `BuildOptions` interface no longer includes the `json?: boolean` property. The `buildCommand()` function signature remains `async function buildCommand(opts: BuildOptions = {}): Promise<void>` but the options object no longer accepts `json`.
+- Changed: The `CleanOptions` interface has been removed entirely. The `cleanCommand()` function signature changed from `async function cleanCommand(opts: CleanOptions = {}): Promise<void>` to `async function cleanCommand(): Promise<void>`.
+- Changed: The `CreateWorkspaceOptions` interface has been removed. The `createWorkspaceCommand()` function signature changed from `async function createWorkspaceCommand(opts: CreateWorkspaceOptions = {}): Promise<void>` to `async function createWorkspaceCommand(): Promise<void>`.
+- Changed: The `CreateOptions` interface no longer includes the `json?: boolean` property. Other fields (`template`, `htmlFile`, `remote`, `repoUrl`) remain unchanged.
+- Changed: The `DeleteOptions` interface no longer includes the `json?: boolean` property. The `yes?: boolean` property remains. Internal implementation now uses `getOutputMode()` instead of checking a local `opts.json` flag.
+- Changed: The `DeployOptions` interface no longer includes the `json?: boolean` property. Other fields (`dryRun`, `remote`, `repoUrl`) remain unchanged. Internal calls to `buildCommand()` no longer pass a `json` option.
+- Changed: The `DevOptions` interface no longer includes the `json?: boolean` property. The `open?: boolean` property remains.
+- Changed: The `DoctorOptions` interface has been removed. The `doctorCommand()` function signature changed from `async function doctorCommand(opts: DoctorOptions = {}): Promise<void>` to `async function doctorCommand(): Promise<void>`. Internal implementation now uses `getOutputMode()` to determine output format.
+- Changed: The `EditOptions` interface has been removed. The `editCommand()` function signature changed from `async function editCommand(appName: string, opts: EditOptions = {}): Promise<void>` to `async function editCommand(appName: string): Promise<void>`.
+- Changed: The `GenerateZ2HTokenOptions` interface no longer includes the `json?: boolean` property. Other fields (`noBrowser`, `url`) remain unchanged.
+- Changed: The `GrantOptions` interface no longer includes the `json?: boolean` property. Other fields (`public`, `level`) remain unchanged. The `grantCommand()` and `revokeCommand()` function signatures are otherwise unchanged.
+- Changed: The `TransferOwnerOptions` interface has been removed. The `transferOwnerCommand()` function signature changed from `async function transferOwnerCommand(email: string | undefined, opts: TransferOwnerOptions): Promise<void>` to `async function transferOwnerCommand(email: string | undefined): Promise<void>`.
+- Changed: The `TagOptions` interface no longer includes the `json?: boolean` property. The `tag?: string[]` property remains. Internal implementation now uses `getOutputMode()` instead of checking `opts.json`.
+- Changed: The `MigrateOptions` interface no longer includes the `json?: boolean` property. The `dryRun?: boolean` property remains.
+- Changed: The migration engine previously in `src/migrations/auto-migrate.ts` (217 lines) has been consolidated into `src/commands/migrate.ts`. All migration logic including `readMigrationState()`, `writeMigrationState()`, and the core migration loop is now colocated with the `migrateCommand()` function. The file `src/migrations/auto-migrate.ts` has been deleted.
+- Added: New workspace utility functions exported from `src/util/workspace.ts`: `runYarnInstall(workspaceHome: string, context: string): Promise<boolean>`, `isNxAvailable(workspaceHome: string): boolean`, `ensureWorkspaceNx(workspaceHome: string): Promise<boolean>`, and internal helper `getLatestTrientMonorepoVersion(): Promise<string>`. These were previously private functions in the migration module.
+- Changed: Commander.js program setup now uses `.hook('preAction', ...)` to set the output mode globally before any command action runs, ensuring consistent `--json` behavior across all commands without per-command boilerplate.
+
+## `0.15.0` (August 2, 2026, 11:11)
+
+### New Features
+
+- [#277](https://github.com/DaPulse/bigbrain-z2h/pull/277) feat(zth-agent): M3 — connect the agent to z2h-cli (create/edit/build/deploy loop) (@arielmonday)
+- Changed: The `create-workspace` command now generates `.npmrc` and `.yarnrc.yml` configuration files dynamically from broker configuration instead of copying static template files. This enables environment-aware registry URLs that respect the `Z2H_BROKER_BASE_URL` environment variable.
+  *Before:*
+  ```ts
+  copy(path.join(wsTemplatesDir, 'yarnrc.yml'), path.join(home, '.yarnrc.yml')),
+  copy(path.join(wsTemplatesDir, 'npmrc'), path.join(home, '.npmrc')),
+  ```
+  *After:*
+  ```ts
+  writeFile(path.join(home, '.yarnrc.yml'), workspaceYarnrcContents()),
+  writeFile(path.join(home, '.npmrc'), workspaceNpmrcContents()),
+  ```
+- Removed: Static template files `packages/z2h-cli/src/templates/workspace/npmrc` and `packages/z2h-cli/src/templates/workspace/yarnrc.yml` have been deleted from the codebase. These previously contained hardcoded production broker URLs (`https://bigbrain-zth.bigbrain.me/z2h-cli/npm/`) that prevented correct operation in staging environments.
+- Added: New import in `create-workspace.ts` for dynamic configuration generation functions `workspaceNpmrcContents` and `workspaceYarnrcContents` from `../util/npm/broker-config`. These functions generate workspace registry configuration based on the current environment's broker URL.
+- Fixed: Workspace creation now correctly configures npm and yarn to use the staging broker when `Z2H_BROKER_BASE_URL` points to staging, resolving timeout issues during `yarn install` in non-production environments.
+
+## `0.14.0` (July 13, 2026, 09:15)
+
+### New Features
+
+- [#247](https://github.com/DaPulse/bigbrain-z2h/pull/247) feat(z2h-cli): add doctor command for setup health checks (@arielmonday)
+- Added: New `doctor` command that performs comprehensive health checks for Z2H setup. Run `z2h-cli doctor` to validate your entire development environment.
+  ```bash
+  z2h-cli doctor
+  # or for JSON output:
+  z2h-cli doctor --json
+  ```
+
+- Added: System tools validation including checks for `nvm`, `node`, `yarn`, `aws-cli`, and `git-remote-s3` with version detection and comparison.
+
+- Added: Node.js version verification against the `.nvmrc` requirement. The doctor command compares your installed Node version with the required version using semver `~` range matching and reports mismatches as failures.
+
+- Added: CLI version freshness check that queries the broker npm registry to detect outdated `z2h-cli` installations and warns when a newer version is available.
+
+- Added: Authentication token validation that checks for the presence and validity of `~/.z2h/auth.json` and verifies the token field exists.
+
+- Added: NPM token environment variable check that scans shell profiles (`dotfiles/.bash_profile`, `.zshrc`, `.bash_profile`) for `export Z2H_NPM_TOKEN` declarations.
+
+- Added: Workspace initialization check that validates the Z2H workspace directory structure and reports if `z2h-cli create-workspace` needs to be run.
+
+- Added: React version validation in workspace `package.json` that ensures React 18.x is installed as a dependency.
+
+- Added: SSL certificate check for `webpack.llama.fan` in `~/Library/Application Support/devcert/domains/webpack.llama.fan/certificate.crt`.
+
+- Added: Claude plugin validation with differentiated severity levels:
+  - Mandatory: `z2h@bigbrain-z2h` plugin (failure if missing)
+  - Optional: `cf-external-claude-plugin@client-foundations-ai-tools` and `pr-guardrails@agentic-builders-hub` (warning if missing)
+  The command verifies plugin registration in `~/.claude/plugins/installed_plugins.json` and checks that install paths exist.
+
+- Added: Three-tier status system for check results:
+  - `ok` (✅): Check passed
+  - `warn` (⚠️): Non-critical issue detected
+  - `fail` (❌): Critical issue requiring action
+
+- Added: Automatic fix command suggestions. When issues are detected, doctor outputs deduplicated fix commands in order of first appearance:
+  ```
+  In order to fix these issues, run the following commands:
+    bash ~/Development/bigbrain-z2h/z2h/setup/bootstrap.sh
+    z2h-cli generate-z2h-token
+  ```
+
+- Added: JSON output mode via `--json` flag that emits structured check results for programmatic consumption:
+  ```json
+  {
+    "ok": false,
+    "checks": [
+      {
+        "label": "nvm",
+        "status": "ok",
+        "detail": "0.39.1"
+      }
+    ]
+  }
+  ```
+
+- Added: Four categorized check sections in output: "System tools", "CLI & auth", "Workspace", and "Plugins" for organized diagnostics.
+
+- Added: Helper function `checkTool` that standardizes tool existence and version detection with configurable failure severity and version extraction logic.
+
+- Added: Timeout protection for network requests (5-second timeout on npm registry version check) to prevent hanging on network issues.
+
+- Added: Graceful degradation when optional data is unavailable (e.g., version check works without auth token or network access, showing current version only).
+
+## `0.13.2` (July 12, 2026, 09:42)
+
+### Improvements
+
+- [#250](https://github.com/DaPulse/bigbrain-z2h/pull/250) feat(z2h): add self-serve app delete (CLI, backend, SDK) (@EranZidkiya)
+- Added: New `z2h-cli delete` command for permanently deleting Z2H apps. The command must be run from within the consumer app directory and requires owner or admin access. By default, it prompts the user to type the app name for confirmation before deletion. The `--yes` flag skips the confirmation prompt (required when using `--json` or in non-interactive environments). The `--json` flag outputs structured JSON to stdout. When successful, the command removes the app from the backend (including grants and tags via cascading deletes) and takes it offline immediately.
+  *Usage:*
+  ```bash
+  # Interactive mode with confirmation prompt
+  z2h-cli delete
+  
+  # Non-interactive mode (e.g., for CI/CD)
+  z2h-cli delete --yes
+  
+  # JSON output for programmatic use
+  z2h-cli delete --yes --json
+  ```
+- Changed: The `pullAndResolve` git utility function now checks if the remote repository has a `master` branch before attempting to pull. If the remote has no `master` branch (e.g., brand-new remote or after app deletion wiped the S3 git prefix), the pull operation is skipped entirely. This prevents bogus merge conflicts during the first deploy or after an app is recreated following deletion.
+  *Impact:*
+  This change enables seamless re-deployment scenarios where an app's S3 git objects were removed (such as after deletion), allowing the subsequent push to create the `master` branch without encountering pull errors.
+
+## `0.13.1` (July 8, 2026, 11:26)
+
+### Improvements
+
+- [#222](https://github.com/DaPulse/bigbrain-z2h/pull/222) Feat/eran/tags addition (@EranZidkiya)
+- Added: New `tag` command that allows setting category tags (app type & team) for Z2H apps, supporting both interactive and non-interactive modes.
+  ```bash
+  z2h-cli tag [app-name]
+  z2h-cli tag my-app --tag "Dashboard" --tag "Analytics Team"
+  z2h-cli tag --json
+  ```
+- Added: New `--tag <tag>` repeatable option for the `tag` command that sets the full tag set non-interactively.
+- Added: New `--json` option for the `tag` command that prints the catalog and current tags as JSON without prompting (read-only mode for agents and non-TTY environments).
+- Added: New `promptForTags(appSlug: string, catalog: CatalogEntry[], current: AppTag[])` function that provides an interactive closed-list prompt for selecting tags across dimensions (app type, team). Users can enter a number or name to select, or press Enter to keep the current value or skip.
+- Added: New `resolveAppSlug(appArg?: string)` utility that resolves the target app name from an explicit argument or from the consumer package.json `name` field in the current directory, normalized to the `mf-` bundle name format.
+- Added: New `formatTags(tags: AppTag[])` utility that renders an app's tags in the format `name (Type), ...` or `(none)` if empty.
+- Added: New `util/tags.ts` module with tag-related types, constants, and API client functions:
+  - `TagType` type (`'app_type' | 'team'`)
+  - `TAG_TYPES` array defining prompt order
+  - `TAG_TYPE_LABELS` record for human-readable dimension labels
+  - `CatalogEntry` and `AppTag` interfaces
+  - `fetchTagCatalog()` function to retrieve the full tag catalog
+  - `fetchAppTags(appSlug: string)` function to get tags for a specific app
+  - `setAppTags(appSlug: string, tags: string[])` function to full-replace an app's tag set
+  - `tagFetch()` internal authenticated request handler for tag endpoints
+- Changed: The `deploy` command now automatically handles tags post-deployment via a new `handleDeployTags(appName: string)` function. In interactive TTY sessions, users are prompted to categorize their app on first deploy if no tags are set. In non-interactive or non-TTY sessions, a nudge message is shown.
+- Changed: Logger imports in `deploy.ts` now include `getOutputMode` to support conditional interactive behavior.
+- Changed: The `deploy` command now imports `promptForTags` from `./tag` and tag utilities from `../util/tags` to support post-deploy tag handling.
+- Changed: Tag failures during deployment never fail the deploy itself (tag handling is a post-deploy concern executed after successful S3 upload).
+- Added: New `collectTag(value: string, previous: string[])` utility in `index.ts` for commander to accumulate repeatable `--tag` option values.
+- Added: New `z2h_app_tag_success` telemetry tracking for the `tag` command execution duration.
+
+## `0.13.0` (July 7, 2026, 14:26)
+
+### New Features
+
+- [#239](https://github.com/DaPulse/bigbrain-z2h/pull/239) feat(z2h-cli): enhance snowflake query (@yarinmonday)
+- Enhanced the html-embed app template to support a new Snowflake data-fetching bridge pattern via `postMessage` communication between the React wrapper and the embedded HTML page.
+- Added a `getBackendBaseUrl()` helper function that constructs the bigbrain-zth microservice URL by retrieving the base URL from `getBigBrainAPI().contextService.bigbrainBaseUrl` and inserting the `bigbrain-zth` subdomain. This enables html-embed pages to fetch data from the backend without hardcoding URLs.
+- Introduced a `postMessage` event listener in the React wrapper component that listens for `z2h:getConfig` messages from the iframe and responds with a `z2h:config` message containing the computed `baseUrl`.
+  *Before:*
+  ```tsx
+  export default function MyApp() {
+    return <iframe src={pageUrl} title="App" style={{...}} />;
+  }
+  ```
+  *After:*
+  ```tsx
+  export default function MyApp() {
+    const iframeRef = useRef<HTMLIFrameElement>(null);
+    useEffect(() => {
+      const handleMessage = (event: MessageEvent) => {
+        if (event.data?.type !== 'z2h:getConfig') return;
+        const baseUrl = getBackendBaseUrl();
+        (event.source as Window).postMessage({ type: 'z2h:config', baseUrl }, event.origin);
+      };
+      window.addEventListener('message', handleMessage);
+      return () => window.removeEventListener('message', handleMessage);
+    }, []);
+    return <iframe ref={iframeRef} src={pageUrl} title="App" style={{...}} />;
+  }
+  ```
+- Added a `useRef` hook to the iframe element to enable message source validation, ensuring only messages from the embedded iframe trigger configuration responses.
+- Updated the iframe rendering to attach the ref (`ref={iframeRef}`) for secure message origin verification.
+- Changed imports in the html-embed template to include `useRef` and `useEffect` from React, and `getBigBrainAPI` from `@mondaydotcomorg/trident-runtime`.
+- Introduced a `BACKEND_SUBDOMAIN` constant set to `'bigbrain-zth'` for backend URL construction.
+
+## `0.12.1` (July 6, 2026, 09:42)
+
+### Bug Fixes
+
+- [#235](https://github.com/DaPulse/bigbrain-z2h/pull/235) Use global z2h-cli command instead of npx (@arielmonday)
+- Changed: CLI invocation pattern updated from `npx z2h-cli` to direct `z2h-cli` command across all documentation. The CLI now expects to be installed globally or available in PATH, removing reliance on npx which can cache stale versions. This affects all command examples in the app template's CLAUDE.md file.
+  *Before:*
+  ```bash
+  npx z2h-cli dev
+  npx z2h-cli deploy
+  npx z2h-cli clean
+  npx z2h-cli grant --public
+  npx z2h-cli revoke --public
+  ```
+  *After:*
+  ```bash
+  z2h-cli dev
+  z2h-cli deploy
+  z2h-cli clean
+  z2h-cli grant --public
+  z2h-cli revoke --public
+  ```
+- Changed: App template documentation (CLAUDE.md) now references the global `z2h-cli` command for all CLI operations including development server (`dev`), deployment (`deploy`), cleanup (`clean`), and permission management (`grant`/`revoke`).
+- Improved: Removed dependency on npx for CLI execution, eliminating potential issues with cached or outdated CLI versions during development and deployment workflows.
+
+## `0.12.0` (July 6, 2026, 07:41)
+
+### New Features
+
+- [#230](https://github.com/DaPulse/bigbrain-z2h/pull/230) feat(z2h-cli): add --open flag to auto-open browser when dev server is ready (@arielmonday)
+- Added: New `--open` flag to the `dev` command that automatically opens the browser when the Trident dev server is ready.
+  *Usage:*
+  ```bash
+  z2h-cli dev --open
+  ```
+  When this flag is provided, the browser will open automatically at the dev server URL once the server emits the "Server started at" signal. Without this flag, the browser will not open automatically (existing behavior preserved).
+
+- Added: New shared utility `openInBrowser` in `src/util/open-browser.ts` that handles cross-platform browser opening (macOS via `open`, Windows via `start`, Linux via `xdg-open`).
+  *API:*
+  ```ts
+  import { openInBrowser } from '../util/open-browser';
+  await openInBrowser(url);
+  ```
+  This function includes error handling that logs a message if the browser fails to open, instructing the user to open it manually.
+
+- Changed: The `DevOptions` interface now includes an optional `open` boolean property.
+  *Before:*
+  ```ts
+  export interface DevOptions {
+    json?: boolean;
+  }
+  ```
+  *After:*
+  ```ts
+  export interface DevOptions {
+    json?: boolean;
+    open?: boolean;
+  }
+  ```
+
+- Changed: The `devCommand` function now accepts the `open` option and calls `openInBrowser(url)` when the Trident ready pattern is detected and `opts.open` is truthy.
+  *Implementation:*
+  ```ts
+  if (opts.open) {
+    void openInBrowser(url);
+  }
+  ```
+
+- Refactored: Removed the duplicate `browserOpenCommand` and `openInBrowser` functions from `src/commands/generate-z2h-token.ts` and replaced them with an import of the shared `openInBrowser` utility.
+  *Before (in generate-z2h-token.ts):*
+  ```ts
+  function browserOpenCommand(): string { /* ... */ }
+  async function openInBrowser(url: string): Promise<void> {
+    await execa(browserOpenCommand(), [url], { stdio: 'ignore' });
+  }
+  ```
+  *After (in generate-z2h-token.ts):*
+  ```ts
+  import { openInBrowser } from '../util/open-browser';
+  ```
+
+- Changed: The CLI command definition for `dev` now accepts the `--open` option in addition to the existing `--json` option.
+  *Before:*
+  ```ts
+  .action(async (opts: { json?: boolean }) => {
+  ```
+  *After:*
+  ```ts
+  .option('--open', 'open the browser automatically when the dev server is ready')
+  .action(async (opts: { open?: boolean; json?: boolean }) => {
+  ```
+
+- Improved: The shared `openInBrowser` utility includes a `.catch()` handler that logs a user-friendly error message if the browser fails to open, preventing unhandled promise rejections.
+
+## `0.11.6` (July 5, 2026, 08:18)
+
+### Bug Fixes
+
+- [#229](https://github.com/DaPulse/bigbrain-z2h/pull/229) fix(z2h-cli): better error handling across CLI and setup (@arielmonday)
+- Changed: The `create-workspace` command now handles existing workspaces gracefully instead of throwing an error. When a workspace already exists at the target path with content, the command logs a skip message and returns successfully (`ok: true`) rather than throwing an error and exiting with a failure code.
+  *Before:*
+  ```ts
+  // Would throw: "Workspace already exists at ${home}. Remove it and try again."
+  throw new Error(`Workspace already exists at ${home}. Remove it and try again.`);
+  ```
+  *After:*
+  ```ts
+  // Now returns gracefully with success status
+  output(`[z2h-cli] workspace already exists at ${home} — skipping`, {
+    ok: true,
+    workspace: home,
+  });
+  return;
+  ```
+- Changed: CLI main error handler now provides a more helpful error message that suggests checking for the latest version when an unexpected failure occurs. The error message format has been updated to be more actionable.
+  *Before:*
+  ```ts
+  await fail(`main failed: ${(err as Error).message}`, { command: 'cli-main' });
+  ```
+  *After:*
+  ```ts
+  const errorMsg = err instanceof Error ? err.message : String(err);
+  await fail(`main failed, check you are on latest version.\nerror: ${errorMsg}`, {
+    command: 'cli-main',
+  });
+  ```
+- Changed: `GitConflictError` messages now include human-readable prefixes that describe whether the conflict occurred during a pull or push operation, making errors readable without JSON parsing. Previously, the error message consisted only of stringified JSON, requiring parsing to understand the context.
+  *Before (pull):*
+  ```ts
+  throw new GitConflictError(JSON.stringify(info));
+  // Message: "{\"conflictFiles\":[...],\"branch\":\"...\"}"
+  ```
+  *After (pull):*
+  ```ts
+  throw new GitConflictError(`Pull rejected: Git conflict detected: ${JSON.stringify(info)}`);
+  // Message: "Pull rejected: Git conflict detected: {\"conflictFiles\":[...],\"branch\":\"...\"}"
+  ```
+  *Before (push):*
+  ```ts
+  throw new GitConflictError(JSON.stringify(info));
+  // Message: "{\"conflictFiles\":[...],\"branch\":\"...\"}"
+  ```
+  *After (push):*
+  ```ts
+  throw new GitConflictError(`Push rejected: Git conflict detected: ${JSON.stringify(info)}`);
+  // Message: "Push rejected: Git conflict detected: {\"conflictFiles\":[...],\"branch\":\"...\"}"
+  ```
+
+## `0.11.5` (July 5, 2026, 07:11)
+
+### Bug Fixes
+
+- [#228](https://github.com/DaPulse/bigbrain-z2h/pull/228) fix(z2h-cli): pin shadow trident-toolkit to workspace root version (@encodedz)
+- Fixed: `z2h-cli create` now generates apps that build successfully without manual intervention. Previously, the shadow package declared `"@mondaydotcomorg/trident-toolkit": "*"` which caused Yarn to install toolkit 3.x alongside the workspace root's 2.x, resulting in duplicate React versions (19.x and 18.x) and a singleton-package violation that aborted builds.
+- Changed: `SHADOW_DEV_DEPS` in `constants.ts` now specifies a fallback version `^2.9.25` for `@mondaydotcomorg/trident-toolkit` instead of `"*"`.
+  *Before:*
+  ```ts
+  export const SHADOW_DEV_DEPS: Record<string, string> = {
+    '@mondaydotcomorg/trident-toolkit': '*',
+  };
+  ```
+  *After:*
+  ```ts
+  export const SHADOW_DEV_DEPS: Record<string, string> = {
+    '@mondaydotcomorg/trident-toolkit': '^2.9.25',
+  };
+  ```
+- Changed: `buildShadowPkg` function signature now accepts an optional second parameter `pinnedVersions` to override shadow devDependencies with workspace root pinned versions.
+  *Before:*
+  ```ts
+  export function buildShadowPkg(consumerPkg: ConsumerPkg): ShadowPkg
+  ```
+  *After:*
+  ```ts
+  export function buildShadowPkg(consumerPkg: ConsumerPkg, pinnedVersions: Record<string, string> = {}): ShadowPkg
+  ```
+- Added: `syncShadow` now reads the workspace root's `package.json` at runtime and passes pinned versions for packages listed in `SHADOW_DEV_DEPS` to `buildShadowPkg`, ensuring the shadow's devDependencies always mirror the workspace root's version ranges.
+- Added: New helper function `readWorkspacePinnedVersions` in `sync.ts` that reads version ranges from the workspace root package.json (one directory above the consumer app) for all packages in `SHADOW_DEV_DEPS`. Returns an empty object if the root package.json is missing or unreadable.
+- Added: New helper function `shadowDevDepsChanged` in `sync.ts` that compares the existing shadow package.json devDependencies against newly computed ones to detect changes. Returns `false` if the shadow package.json doesn't exist or is unreadable.
+- Changed: `syncShadow` now clears the `.deps-hash` file and forces a `yarn install` when shadow devDependencies differ from what's about to be written, ensuring Yarn resolves corrected version ranges.
+- Added: New migration `005-fix-shadow-toolkit-wildcard.ts` that sweeps all `*/.zth/package.json` files in the workspace, replaces any `"*"` entry for `@mondaydotcomorg/trident-toolkit` with the workspace root's pinned version (or `^2.9.25` as fallback), and triggers a workspace-level `yarn install`. This migration ships in version 0.11.5 and is invoked via `z2h-cli migrate`.
+  *Migration behavior:*
+  ```ts
+  // Reads workspace root package.json to find toolkit version
+  const pkg = JSON.parse(tree.read('package.json', 'utf-8')!);
+  const targetVersion = pkg.devDependencies?.['@mondaydotcomorg/trident-toolkit'] ?? '^2.9.25';
+  
+  // Rewrites each shadow package.json with '*' entry
+  if (pkg.devDependencies?.['@mondaydotcomorg/trident-toolkit'] === '*') {
+    pkg.devDependencies['@mondaydotcomorg/trident-toolkit'] = targetVersion;
+    tree.write(shadowPkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  }
+  ```
+
+## `0.11.4` (July 2, 2026, 13:52)
+
+### Bug Fixes
+
+- [#225](https://github.com/DaPulse/bigbrain-z2h/pull/225) feat(z2h-cli): migration 004 — remove z2h-cli from workspace deps (@encodedz)
+- Added: New migration `004-remove-z2h-cli-workspace-dep` that automatically removes `@mondaydotcomorg/z2h-cli` from workspace/consumer `package.json` files. This migration scans for the package in `dependencies` and `devDependencies` sections and removes it, cleaning up empty sections after removal. The z2h-cli is globally installed and must not be a local dependency to prevent version drift and installation conflicts.
+  *Usage (automatic via auto-migrate):*
+  ```ts
+  // Migration runs automatically on CLI commands
+  // Removes entries like:
+  // "dependencies": {
+  //   "@mondaydotcomorg/z2h-cli": "^0.11.0"
+  // }
+  ```
+- Changed: The migration logic iterates over both `dependencies` and `devDependencies` sections, deleting any occurrence of `@mondaydotcomorg/z2h-cli` and removing the entire section object if it becomes empty after deletion.
+- Changed: The migration uses `@nx/devkit` Tree API to safely read and write `package.json`, ensuring changes are properly tracked and applied during the migration process.
+- Changed: Migration only runs if `package.json` exists at the root of the tree, returning early otherwise to avoid errors on projects without a package manifest.
+
+## `0.11.3` (July 2, 2026, 13:12)
+
+### Bug Fixes
+
+- [#224](https://github.com/DaPulse/bigbrain-z2h/pull/224) feat(z2h-apps): add gitRemote parameter to updateApp and related inte… (@yarinmonday)
+- Added: The `updateApp` function now accepts a `gitRemote` parameter to track the Git remote repository URL when updating an app.
+  *Before:*
+  ```ts
+  await updateApp(appName, token, nextVersion, entry);
+  ```
+  *After:*
+  ```ts
+  await updateApp(appName, token, nextVersion, entry, gitRemote);
+  ```
+- Changed: The `deploy` command now passes the `gitRemote` parameter to the `updateApp` function call (line 155), ensuring the Git remote is sent to the backend when releasing app updates.
+- Changed: The HTTP request body in `updateApp` now includes the `gitRemote` field alongside `appName`, `version`, and `entry` when calling the `/z2h-cli/apps/update` API endpoint (line 224).
+
+## `0.11.2` (July 2, 2026, 09:33)
+
+### Bug Fixes
+
+- [#219](https://github.com/DaPulse/bigbrain-z2h/pull/219) fix(z2h-cli): strip AWS_CREDENTIAL_EXPIRATION from env (@encodedz)
+- Fixed: AWS credential handling during git operations to prevent authentication failures caused by stale `AWS_CREDENTIAL_EXPIRATION` environment variable. The CLI now strips `AWS_CREDENTIAL_EXPIRATION` from the environment before spawning git-remote-s3 processes, preventing boto3 from rejecting valid credentials due to expired timestamp metadata.
+  *Updated constant:*
+  ```ts
+  // Before
+  const CONFLICTING_ENV_VARS = ['AWS_PROFILE'];
+  
+  // After
+  const CONFLICTING_ENV_VARS = ['AWS_PROFILE', 'AWS_CREDENTIAL_EXPIRATION'];
+  ```
+  This prevents 401 errors during deploy operations when the user's shell environment contains a stale `AWS_CREDENTIAL_EXPIRATION` value that conflicts with freshly minted credentials from the broker.
+
+## `0.11.1` (July 2, 2026, 09:00)
+
+### Bug Fixes
+
+- [#218](https://github.com/DaPulse/bigbrain-z2h/pull/218) fix(z2h-cli): disable all local git hooks in Z2H repos (@encodedz)
+- Fixed: Git hooks are now completely disabled in Z2H repositories to prevent blocking non-interactive deploys. Previously, `overrideGlobalHooks` only bypassed hooks configured via `core.hooksPath`, but hooks injected by `init.templateDir` (which are copied directly into `.git/hooks/`) were still executed and could block automated pushes.
+- Changed: The `overrideGlobalHooks` function has been renamed to `disableLocalHooks` to better reflect its purpose. Z2H repositories are agent-driven and non-interactive, so all git hooks are now bypassed regardless of their source (global `core.hooksPath`, `init.templateDir`, or manually placed hooks).
+  *Before:*
+  ```ts
+  await overrideGlobalHooks(dir);
+  ```
+  *After:*
+  ```ts
+  await disableLocalHooks(dir);
+  ```
+- Changed: The `disableLocalHooks` function now unconditionally sets `core.hooksPath` to the empty `.zth/hooks/` directory, removing the previous conditional logic that only activated when a global hooks path was detected. This ensures all hook delivery mechanisms are bypassed.
+- Removed: The warning message that was previously shown when global git hooks were detected has been removed. The function no longer checks for a global `core.hooksPath` configuration before setting the local override.
+- Improved: The function now creates the `.zth/hooks/` directory and sets the local `core.hooksPath` configuration immediately if it doesn't already exist, simplifying the logic and ensuring consistent behavior across all hook sources.
+
+## `0.11.0` (July 2, 2026, 07:24)
+
+### New Features
+
+- [#209](https://github.com/DaPulse/bigbrain-z2h/pull/209) feat(z2h-git-flow): Phases 6 & 7 — edit command + deploy git sync (@arielmonday)
+- Added: New `z2h-cli edit <app-name>` command that clones an app on first use and pulls the latest version on subsequent opens. When the app has no git remote (never deployed with git tracking), the command gracefully skips and suggests running `z2h-cli deploy` to set up git tracking.
+  *Usage:*
+  ```bash
+  z2h-cli edit my-app
+  ```
+
+- Added: Three new access control commands for managing app visibility and permissions:
+  - `z2h-cli grant [email]` — grants access to the current app (individual user, `--public` flag for company-wide, or both)
+  - `z2h-cli revoke [email]` — revokes access from an individual user or removes public visibility
+  - `z2h-cli transfer-owner [email]` — transfers ownership of the current app to another user
+  *Example:*
+  ```bash
+  z2h-cli grant --public                    # Make app visible to all employees
+  z2h-cli grant user@monday.com --level editor  # Grant editor access to specific user
+  z2h-cli revoke --public                   # Remove public access
+  z2h-cli transfer-owner newowner@monday.com
+  ```
+
+- Changed: The `z2h-cli deploy` command now accepts `--remote` and `--repo-url` options on first deploy to initialize the git remote. These options are only valid for apps without an existing remote; passing them for apps that already have a remote will throw an error.
+  *First deploy with S3 remote:*
+  ```bash
+  z2h-cli deploy --remote s3
+  ```
+  *First deploy with GitHub remote:*
+  ```bash
+  z2h-cli deploy --remote github --repo-url https://github.com/org/repo.git
+  ```
+
+- Changed: The `deploy` command now performs git synchronization before building and uploading. It guards against uncommitted changes with `guardCleanTree`, pulls from the remote before starting, and pushes to the remote **before** uploading to S3. This ensures that a rejected push (divergence detected) halts the deploy before any artifacts go live.
+
+- Changed: First deploy now prompts for app visibility in interactive mode (TTY). Users are asked "Make <app> public to all monday.com employees? (y/N)". Non-interactive runs (`--json` or no TTY) default to private. The visibility choice is passed to the new `/z2h-cli/apps/register` endpoint.
+
+- Added: The `deploy` command now acquires an explicit per-app deploy lock via a new `/z2h-cli/lock/acquire` broker endpoint before uploading. A 409 response indicates another deploy is in progress and throws a user-friendly error. The lock is released after manifest write in a best-effort fashion (2-minute TTL backstop on the backend).
+
+- Changed: The deploy version is now fetched from a dedicated `/z2h-cli/apps/version` broker endpoint before requesting STS credentials. Version derivation has been moved out of the manifest-read logic and onto its own endpoint for cleaner separation.
+
+- Changed: The `registerApp` function now accepts additional parameters `visibility` ("public" or "private") and `gitRemote` (string) and sends them in the request body to `/z2h-cli/apps/register`.
+
+- Added: New `updateApp` function for releasing subsequent versions (v2+). The deploy flow now branches: v1 calls `registerApp` (creates the app row + owner grant), later versions call `updateApp` (releases onto existing app).
+
+- Added: Git conflict detection and structured error surfacing. When `pullAndResolve` or `pushToRemote` encounter a divergence (non-fast-forward pull or rejected push), they now throw `GitConflictError` with a JSON payload containing `localCommits`, `remoteCommits`, and `conflictingFiles` arrays. This enables LLM-based conflict resolution in the Z2H skill layer.
+  *Example error payload:*
+  ```json
+  {
+    "localCommits": ["a1b2c3d Fix button color"],
+    "remoteCommits": ["e4f5g6h Update header layout"],
+    "conflictingFiles": ["src/App.tsx"]
+  }
+  ```
+
+- Added: New `guardCleanTree` function that throws an error if the working tree has uncommitted changes. Called before git sync in deploy to ensure the tree is clean.
+
+- Added: New `pushToRemote` function that pushes the local master branch to origin. On a rejected (non-fast-forward) push, it gathers conflict info and throws `GitConflictError`. This stops the deploy before the bundle upload if someone deployed during the build.
+
+- Changed: `pullAndResolve` now accepts an optional `env` parameter (git environment variables) and gracefully handles first deploy scenarios where the remote exists but has no commits yet. On pull failure, it backs up dirty state and throws `GitConflictError` with conflict details.
+
+- Changed: `cloneRepo` now accepts an optional `env` parameter and automatically calls `overrideGlobalHooks` after cloning to prevent global git hooks from interfering with Z2H's non-interactive operations.
+
+- Added: New `overrideGlobalHooks` function that detects if the user has a global `core.hooksPath` configured and overrides it locally for the Z2H project (sets `core.hooksPath` to `.zth/hooks` in the local git config). This prevents global hooks like "prevent-push-to-master" from blocking automated pushes while leaving other repos protected.
+
+- Added: New utility module `util/git/git-env.ts` with `resolveGitEnv` function. For S3-backed remotes, it mints short-lived broker credentials and returns them as `AWS_*` environment variables for `git-remote-s3`. For GitHub remotes, it returns `undefined` (user's own git credentials are used).
+
+- Added: New utility module `util/git/remote-options.ts` with shared remote validation logic. Exports `REMOTE_TYPES` constant, `RemoteType` type, `validateRemoteOptions` function (validates `--remote` and `--repo-url` flags), and `resolveRemoteUrl` function (converts options to a git remote URL).
+
+- Added: New utility module `util/broker/app.ts` with `fetchApp` function. Fetches a single app's current state (including `gitRemote`) from the broker. Returns `null` for apps that have never been deployed (404 response).
+
+- Changed: The `create` command now uses the broker's `/z2h-cli/apps/<appName>` endpoint to check for name collisions instead of reading the S3 manifest directly. This shifts app registration logic to the backend.
+
+- Changed: The `create` command now validates remote options using the shared `validateRemoteOptions` function and resolves the remote URL with `resolveRemoteUrl`. The validation and remote URL logic has been extracted and reused.
+
+- Changed: The `create` command no longer performs a pre-build (`buildCommand`) after scaffolding. Instead, it runs best-effort `prepareShadow` to wire the workspace. The pre-build step was removed to speed up project creation; build happens on first `dev` or `deploy`.
+
+- Changed: `setupS3Client` now accepts an `AwsCredentialIdentity` object directly instead of an `{ appName }` options object. The caller is responsible for obtaining credentials (via `brokerCredentialProvider` or other means) before calling `setupS3Client`.
+  *Before:*
+  ```typescript
+  setupS3Client({ appName: 'my-app' });
+  ```
+  *After:*
+  ```typescript
+  const creds = await brokerCredentialProvider({ appName: 'my-app' })();
+  setupS3Client(creds);
+  ```
+
+- Added: New `fetchDeployVersion` function in `util/auth/broker-credential-provider.ts` that reserves the version this deploy will write to via a new `/z2h-cli/apps/version` endpoint. This separates version derivation from the STS credentials call.
+
+- Changed: The broker request logic has been extracted into a shared `postToBroker` helper function. Both `fetchDeployVersion` and `fetchStsOnce` (renamed from `fetchCredentialsOnce`) now use this helper, which injects the authorization token and routing headers.
+
+- Added: `postToBroker` and all broker HTTP calls now include `routingHeaders()` in request headers. This returns a `Baggage: routingKey=<value>` header when `Z2H_BROKER_BASE_URL` is set (for monday-mirror routing in development environments).
+
+- Added: New `routingHeaders` function in `constants.ts` that returns routing headers for monday-mirror when `Z2H_ROUTING_KEY` is set. Returns an empty object in production.
+
+- Added: New `getCwdAppName` utility function in `util/app-name.ts` that reads the package name from `package.json` in the current working directory. Returns `undefined` if the file doesn't exist or can't be parsed.
+
+- Changed: `prepareShadow` now accepts an optional `consumerDir` parameter (defaults to `process.cwd()`) to allow shadow preparation for a specific directory without changing the process working directory.
+
+- Changed: The CLI now strips conflicting environment variables (`AWS_PROFILE` and potentially others) at startup via `stripConflictingEnvVars` to prevent user AWS profiles from interfering with Z2H broker credentials.
+
+- Changed: The `create-workspace` command description now uses `getWorkspaceHome()` instead of hardcoding `~/zth-projects/` to reflect the actual workspace location.
+
+- Changed: Git operations have been refactored to use helper functions `execGit` and `execGitLines` that accept an optional `env` parameter for injecting AWS credentials or other environment variables.
+
+- Changed: The consumer app template `CLAUDE.md` now includes a new "App Visibility" section documenting that apps are private by default and explaining how to use `z2h-cli grant --public` and `z2h-cli revoke --public` to control visibility.
+
+- Removed: The manifest read/write logic (`readManifest`, `writeManifest`, `upsertEntry`, `nextVersion`) has been removed from the deploy flow. The broker backend now owns the manifest and app version state.
+
+## `0.10.1` (July 1, 2026, 05:42)
+
+### Bug Fixes
+
+- [#211](https://github.com/DaPulse/bigbrain-z2h/pull/211) feat(z2h): machine-user auth bypass for headless CLI operations (@encodedz)
+- Added: Machine-user authentication support via `Z2H_AUTH_TOKEN` environment variable. When set, the CLI will use this JWT token for authentication instead of the file-based token flow, enabling headless/automated deployments.
+  *Usage:*
+  ```bash
+  export Z2H_AUTH_TOKEN="eyJhbG...<your-jwt>..."
+  z2h-cli deploy
+  ```
+- Changed: `readZthAuth()` function now checks `Z2H_AUTH_TOKEN` environment variable first before reading from the file system. If the environment variable is present, it validates the JWT format (three dot-separated segments) and returns it directly, bypassing file I/O.
+  *Before:*
+  ```ts
+  // Always read from Z2H_AUTH_FILE
+  export async function readZthAuth(): Promise<ZthAuth> {
+    if (!(await pathExists(Z2H_AUTH_FILE))) {
+      throw new Z2hAuthMissingError(Z2H_AUTH_FILE);
+    }
+    const parsed = await readJson(Z2H_AUTH_FILE);
+    // ...
+  }
+  ```
+  *After:*
+  ```ts
+  export async function readZthAuth(): Promise<ZthAuth> {
+    // Check env var first
+    if (process.env.Z2H_AUTH_TOKEN) {
+      const token = process.env.Z2H_AUTH_TOKEN;
+      if (!/^[\w-]+\.[\w-]+\.[\w-]+$/.test(token)) {
+        throw new Error('Z2H_AUTH_TOKEN is not a valid JWT...');
+      }
+      return { token };
+    }
+    // Fall back to file
+    if (!(await pathExists(Z2H_AUTH_FILE))) {
+      throw new Z2hAuthMissingError(Z2H_AUTH_FILE);
+    }
+    // ...
+  }
+  ```
+- Changed: `tryReadAuthTokenSync()` function now checks `Z2H_AUTH_TOKEN` environment variable first before attempting synchronous file read, maintaining consistency with async version.
+  *After:*
+  ```ts
+  export function tryReadAuthTokenSync(): string | null {
+    if (process.env.Z2H_AUTH_TOKEN) {
+      return process.env.Z2H_AUTH_TOKEN;
+    }
+    // Fall back to file read
+    // ...
+  }
+  ```
+- Added: New utility function `getMachineAppName()` in `util/machine-identity.ts` that reads `APP_NAME` environment variable to identify machine/service deployers (returns `undefined` for human users).
+  *Implementation:*
+  ```ts
+  export function getMachineAppName(): string | undefined {
+    return process.env.APP_NAME || undefined;
+  }
+  ```
+- Changed: `deployCommand` now uses `getMachineAppName()` for the `deployedBy` audit field, falling back to `os.userInfo().username` for human users. This enables proper audit trails when deployments are triggered by automated services.
+  *Before:*
+  ```ts
+  const deployedBy = os.userInfo().username;
+  ```
+  *After:*
+  ```ts
+  const deployedBy = getMachineAppName() ?? os.userInfo().username;
+  ```
+
+## `0.10.0` (June 30, 2026, 13:46)
+
+### New Features
+
+- [#202](https://github.com/DaPulse/bigbrain-z2h/pull/202) feat(z2h-cli): Phase 5 — create with required remote choice (@arielmonday)
+- **Breaking Change**: The `create` command now requires the `--remote` flag with a value of either `s3` (shared storage) or `github` (GitHub repository). Attempting to run `create` without this flag will result in an error: "--remote is required. Use --remote=s3 (shared storage) or --remote=github (your GitHub repo)."
+  *Before:*
+  ```bash
+  z2h-cli create my-app
+  ```
+  *After:*
+  ```bash
+  z2h-cli create my-app --remote=s3
+  # or
+  z2h-cli create my-app --remote=github --repo-url=https://github.com/user/repo.git
+  ```
+- **Breaking Change**: When using `--remote=github`, the `--repo-url` parameter is now required and must specify the GitHub repository URL. Omitting `--repo-url` will result in an error: "--repo-url is required when using --remote=github."
+  *Usage:*
+  ```bash
+  z2h-cli create my-app --remote=github --repo-url=https://github.com/user/my-app.git
+  ```
+- Added: New `REMOTE_TYPES` constant exported from `src/commands/create.ts` as a readonly tuple `['s3', 'github']`, along with a derived `RemoteType` type. This ensures remote type validation is centralized.
+- Added: New `CreateOptions` interface properties: `remote?: RemoteType` and `repoUrl?: string` to support the remote selection at creation time.
+- Changed: The `create` command now initializes a local git repository and configures the specified remote during app creation, but **does not push** the initial commit. The first push is deferred to the first `deploy` command.
+- Added: New `initRepo` function in `src/util/git/repo.ts` that initializes a git repository, commits all files with "Initial commit", and adds the specified remote as `origin`. This function does not push to the remote.
+  *Signature:*
+  ```ts
+  export async function initRepo(dir: string, remote: string): Promise<void>
+  ```
+- Removed: The `initAndPush` function has been removed from `src/util/git/repo.ts`. Use `initRepo` for creation-time repository setup (no push) instead.
+- Changed: The `defaultS3Remote` function now applies `mfAppName` transformation to the app name before constructing the S3 remote URL.
+  *Before:*
+  ```ts
+  return `s3://${BUCKET_WRITE_NAME}/${app}/git`;
+  ```
+  *After:*
+  ```ts
+  return `s3://${BUCKET_WRITE_NAME}/${mfAppName(app)}/git`;
+  ```
+- Added: New `getRemoteUrl` function in `src/util/git/repo.ts` that retrieves the `origin` remote URL from a git repository, returning `undefined` if the remote is not configured or an error occurs.
+  *Signature:*
+  ```ts
+  export async function getRemoteUrl(dir: string): Promise<string | undefined>
+  ```
+- Changed: The `deploy` command now captures the git remote URL via `getRemoteUrl` and includes it in the `ManifestEntry` under the `gitRemote` property.
+- Changed: The `ManifestEntry` interface now includes an optional `gitRemote?: string` property, while the `AssetManifestFile` interface no longer has a required `gitRemote: string` field. This reflects that `gitRemote` is determined at deploy time, not build time.
+  *Before (`AssetManifestFile`):*
+  ```ts
+  export interface AssetManifestFile {
+    // ...
+    gitRemote: string;
+  }
+  ```
+  *After (`ManifestEntry`):*
+  ```ts
+  export interface ManifestEntry extends AssetManifestFile {
+    version: number;
+    url: string;
+    deployedBy: string;
+    gitRemote?: string;
+  }
+  ```
+- Changed: The `commitDetailedAndPush` function in `src/util/git/repo.ts` now verifies that the current branch is `master` before attempting to deploy. If the user is on a different branch, it throws an error: "expected branch \"master\" but you are on \"<branch>\" — switch back before deploying."
+- Changed: The `commitDetailedAndPush` function now checks if there are any staged changes before committing. If no files have changed since the last deploy, it throws an error: "Nothing new to deploy — no files have changed since the last deploy."
+- Changed: The `commitDetailedAndPush` function now uses `git push -u origin master` instead of `git push`, ensuring the upstream branch is set on both the first push and subsequent pushes.
+- Changed: The error handling in `commitDetailedAndPush` now checks for `[rejected]` or `non-fast-forward` patterns in the error message to throw a `GitConflictError` with the message "push rejected — remote has new commits". Other git errors are re-thrown as-is.
+- Changed: The `create` command action handler in `src/index.ts` now accepts `remote?: string` and `repoUrl?: string` options and casts them to `CreateOptions` when invoking `createCommand`.
+- Changed: The `z2h_app_created` tracking event now includes a `remote` property in its metadata, defaulting to `'unknown'` if not provided.
+- Changed: The `create` command now returns additional fields in its JSON output: `remote: opts.remote` and `gitRemote: string` (the resolved remote URL).
+
+## `0.9.1` (June 30, 2026, 13:08)
+
+### Improvements
+
+- [#212](https://github.com/DaPulse/bigbrain-z2h/pull/212) fix(z2h): init DB in apps migration + dual-write apps on deploy (@EranZidkiya)
+- Added: Automatic app registration to RDS database after successful deploy. The `deploy` command now calls a new `registerApp()` function that sends a POST request to `/z2h-cli/apps/register` with the app name, version, and manifest entry immediately after updating the S3 manifest.
+  *New behavior:*
+  ```ts
+  // After manifest write
+  info(`registering app "${appName}" → v${version}`);
+  await registerApp(appName, token, version, entry);
+  ```
+- Added: New internal `registerApp()` function that POSTs app metadata to the backend broker endpoint. The function sends app name, version, and manifest entry as JSON, and throws an error if registration fails.
+  *Usage:*
+  ```ts
+  async function registerApp(appName: string, token: string, version: number, entry: ManifestEntry): Promise<void> {
+    const res = await fetch(`${brokerBaseUrl()}/z2h-cli/apps/register`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ appName, version, entry }),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`App registration failed (${res.status}): ${text.slice(0, 1024)}`);
+    }
+  }
+  ```
+- Changed: Deploy workflow now performs dual-write operation. After uploading bundle to S3 and updating the manifest, the CLI also registers the app in the RDS database, ensuring both storage systems remain synchronized during the migration period before RDS becomes the sole source of truth.
+- Changed: Deploy command now includes error handling for app registration failures. If the backend registration endpoint returns a non-OK status, the deploy command will throw an error with the HTTP status code and response text (truncated to 1024 characters).
+
+## `0.9.0` (June 30, 2026, 10:14)
+
+### New Features
+
+- [#213](https://github.com/DaPulse/bigbrain-z2h/pull/213) fix: trigger CLI release (@arielmonday)
+- Changed: Import statement ordering in `auto-migrate.ts` to follow conventional import organization patterns. The `fs-extra` import is now placed before the `execa` import, aligning with alphabetical ordering conventions for external package imports. This is a non-functional code style improvement with no impact on runtime behavior or public APIs.
+
+## `0.8.0` (June 30, 2026, 09:49)
+
+### Improvements
+
+- [#196](https://github.com/DaPulse/bigbrain-z2h/pull/196) feat(z2h-cli): build app after create + improve setup README (@arielmonday)
+- Changed: The `createCommand` function now automatically builds the app after scaffolding and dependency installation, eliminating cold-start build delays on first `dev` run. If the pre-build fails, a warning is logged but the process continues.
+- Changed: All command functions (`buildCommand`, `cleanCommand`, `createWorkspaceCommand`, `createCommand`, `deployCommand`, `devCommand`, `migrateCommand`) now have optional options parameters with default values `{}` instead of required parameters.
+  *Before:*
+  ```ts
+  export async function buildCommand(opts: BuildOptions): Promise<void>
+  export async function createCommand(appName: string, opts: CreateOptions): Promise<void>
+  ```
+  *After:*
+  ```ts
+  export async function buildCommand(opts: BuildOptions = {}): Promise<void>
+  export async function createCommand(appName: string, opts: CreateOptions = {}): Promise<void>
+  ```
+- Added: All build/dev/deploy/clean commands now include documentation comments clarifying they must be run from the consumer app directory because they use `process.cwd()` to locate the app.
+- Changed: The `createCommand` function now changes the working directory to the app directory before calling `buildCommand`, then restores the previous working directory after the build completes or fails.
+- Changed: The `devCommand` function now sets `NPM_TOKEN=FAKE_TOKEN` in the environment when starting the Trident dev server, preventing startup failures when the environment variable is not set. This ensures deterministic behavior across all users regardless of their local NPM token configuration.
+  *Implementation:*
+  ```ts
+  const server = execa('yarn', ['start'], {
+    cwd: ctx.paths.shadowDir,
+    stdio: ['inherit', 'pipe', 'inherit'],
+    env: { ...process.env, NPM_TOKEN: 'FAKE_TOKEN' },
+  });
+  ```
+- Changed: The `releaseLockBestEffort` function in the deploy command now logs informational and warning messages for successful and failed lock releases respectively, improving observability during deployment.
+- Changed: Import statement ordering in `auto-migrate.ts` has been reorganized for consistency (external packages before Node.js built-ins).
+- Added: The `createCommand` function now imports and uses `buildCommand` from `./build` to enable the post-scaffold build step.
+
+### New Features
+
+- [#191](https://github.com/DaPulse/bigbrain-z2h/pull/191) feat(z2h-git-flow): Phase 4 — git plumbing library (@arielmonday)
+- Added: New `GitConflictError` class for handling git conflict scenarios during remote operations.
+  ```ts
+  throw new GitConflictError('push rejected — remote has new commits');
+  ```
+- Added: `defaultS3Remote(app: string)` function to construct S3-backed git remote URLs for Z2H applications.
+  ```ts
+  const remote = defaultS3Remote('my-app');
+  // Returns: 's3://prod-use1-bigbrain-zth-mf-assets/my-app/git'
+  ```
+- Added: `initAndPush(dir: string, remote: string)` function to initialize a new git repository with required `.gitignore` entries (`node_modules/`, `.zth/`, `build/`), create an initial commit on the `master` branch, configure the remote origin, and push to S3.
+  ```ts
+  await initAndPush('/path/to/app', 's3://bucket/app/git');
+  ```
+- Added: `cloneRepo(remote: string, dir: string)` function to clone a git repository from an S3 remote URL to a local directory.
+  ```ts
+  await cloneRepo('s3://bucket/app/git', '/path/to/local/dir');
+  ```
+- Added: `safeBackupIfDirty(dir: string)` function that creates a timestamped backup copy of a repository directory if it contains uncommitted changes (detected via `git status --porcelain`). The backup directory is created as `<appName>.backup-<sha>` in the parent directory.
+  ```ts
+  await safeBackupIfDirty('/path/to/app');
+  // Creates: /path/to/app.backup-abc123 (if dirty)
+  ```
+- Added: `pullAndResolve(dir: string)` function to perform a fast-forward-only `git pull` from the remote. Throws `GitConflictError` if the pull fails (e.g., divergent branches). Phase 7 TODO comment indicates future support for automatic conflict resolution via `resolveDivergence(dir)`.
+  ```ts
+  try {
+    await pullAndResolve('/path/to/app');
+  } catch (err) {
+    if (err instanceof GitConflictError) {
+      // Handle conflict: 'This app changed while you were working'
+    }
+  }
+  ```
+- Added: `remoteHead(dir: string)` function to fetch the current commit SHA of the `refs/heads/master` branch from the remote origin using `git ls-remote`.
+  ```ts
+  const sha = await remoteHead('/path/to/app');
+  // Returns: '1a2b3c4d5e6f...'
+  ```
+- Added: `localHead(dir: string)` function to retrieve the current local HEAD commit SHA using `git rev-parse HEAD`.
+  ```ts
+  const sha = await localHead('/path/to/app');
+  // Returns: '1a2b3c4d5e6f...'
+  ```
+- Added: `commitDetailedAndPush(dir: string, version: number)` function to stage all changes, create a commit with a version-prefixed message listing modified files (truncated to 5 files + count), and push to the remote. Throws `GitConflictError` if the push is rejected due to remote changes. Phase 7 TODO comment indicates future replacement of the commit message builder with an LLM-generated summary.
+  ```ts
+  await commitDetailedAndPush('/path/to/app', 42);
+  // Commit message example: 'v42: deploy — src/index.tsx, README.md (+3 more)'
+  ```
+- Added: Internal `buildCommitMessage(dir: string, version: number)` function that generates a commit message by running `git status --short`, extracting up to 5 changed file paths, and formatting them as `v<version>: deploy — <file1>, <file2>, ...`. Files beyond the first 5 are summarized as `(+N more)`.
+- Added: Internal `ensureGitignore(dir: string)` function that reads the existing `.gitignore` file (if present) and appends any missing required entries (`node_modules/`, `.zth/`, `build/`) to ensure Z2H projects always exclude build artifacts and dependencies from version control.
+- Changed: The `AssetManifestFile` interface in `packages/z2h-cli/src/util/manifest.ts` now includes a required `gitRemote: string` field to store the S3 remote URL for each Z2H application.
+  ```ts
+  interface AssetManifestFile {
+    // ... existing fields ...
+    gitRemote: string; // New required field
+  }
+  ```
+- Changed: The `ManifestEntry` interface (which extends `AssetManifestFile`) now inherits the new `gitRemote` field, making it available to all manifest entry consumers.
+- [#179](https://github.com/DaPulse/bigbrain-z2h/pull/179) feat(z2h-cli): Phase 3 — per-app deploy lock via Redis (@arielmonday)
+- Added: Import of `brokerBaseUrl` from `../constants` to support new deploy lock release endpoint communication.
+- Changed: The `deployCommand` function now reads and stores the authentication token from `readZthAuth()` at the beginning of the deployment process.
+  *Before:*
+  ```ts
+  await readZthAuth();
+  ```
+  *After:*
+  ```ts
+  const { token } = await readZthAuth();
+  ```
+- Added: Deploy lock release mechanism in a try-finally block wrapping the S3 upload and manifest update operations. The lock is automatically released after deployment completes (success or failure) via a call to `releaseLockBestEffort`.
+  *New structure:*
+  ```ts
+  try {
+    // Lock is acquired here — uploadDir triggers the STS credential provider on first S3 call
+    info(`uploading build → s3://${BUCKET_WRITE_NAME}/${keyPrefix}/`);
+    await uploadDir(paths.shadowBuild, keyPrefix);
+    info(`updating manifest entry "${appName}" → v${version}`);
+    await writeManifest(upsertEntry(manifest, appName, entry));
+  } finally {
+    await releaseLockBestEffort(appName, token);
+  }
+  ```
+- Added: New private function `releaseLockBestEffort(appName: string, token: string): Promise<void>` that makes a POST request to `/z2h-cli/lock/release` endpoint to release the per-app deploy lock acquired during credential minting. The function includes error suppression (empty catch block) since lock release is best-effort with a 5-minute TTL backstop on the server side.
+  *Usage:*
+  ```ts
+  async function releaseLockBestEffort(appName: string, token: string): Promise<void> {
+    try {
+      await fetch(`${brokerBaseUrl()}/z2h-cli/lock/release`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ appName }),
+      });
+    } catch {
+      // best-effort — the 5-min TTL backstop handles failures
+    }
+  }
+  ```
+- Changed: Deploy lock is now acquired automatically when `uploadDir` triggers the STS credential provider on the first S3 call, and released in the finally block regardless of deployment success or failure. This prevents concurrent deployments of the same app and ensures lock cleanup even if the deployment fails.
+
+### Bug Fixes
+
+- [#167](https://github.com/DaPulse/bigbrain-z2h/pull/167) fix(z2h-cli): prevent infinite self-update loop + skill and setup improvements (@arielmonday)
+- Fixed: Infinite self-update loop prevented by adding environment guard to `selfUpdate()` function. The function now sets `Z2H_UPDATE_RUNNING=1` on the spawned child process environment before detaching `update.sh`, which prevents `z2h-cli migrate` from triggering additional update chains. The guard is inherited by every `z2h-cli` invocation inside the update script, breaking the cycle without affecting the user's shell environment.
+  *Technical detail:* The `execa` call in `packages/z2h-cli/src/index.ts:24` now includes the environment variable in the spawned process, though the diff shown only reflects formatting changes to the `execa` options object structure.
+
+- Changed: App template `CLAUDE.md` now enforces stricter backend modification rules. The data-fetching hierarchy section explicitly states that backend changes to `bigbrain-zth` are "not in scope — no modifications, no suggestions, no workarounds" (previously only implied no modifications were in scope).
+  *Location:* `packages/z2h-cli/src/templates/app/CLAUDE.md:30`
+
+- Added: Query storage rule in app template `CLAUDE.md`. All SQL query strings must now be stored in `src/queries.ts` rather than inline in components or hooks, with imports required from that centralized location.
+  *New section added at:* `packages/z2h-cli/src/templates/app/CLAUDE.md:32`
+  *Usage example:*
+  ```ts
+  // src/queries.ts
+  export const GET_USERS = `SELECT * FROM users WHERE active = true`;
+  
+  // component file
+  import { GET_USERS } from './queries';
+  ```
+
+- Fixed: Claude Code session stop hook in app template now properly kills entire process group instead of just the parent process. The stop hook command in `claude-settings.json` now retrieves the process group ID and uses `kill -- -$PGID` to terminate all child processes spawned by the dev server.
+  *Before:*
+  ```bash
+  kill $(cat .zth/dev.pid) 2>/dev/null
+  ```
+  *After:*
+  ```bash
+  PGID=$(ps -o pgid= -p $(cat .zth/dev.pid) 2>/dev/null | tr -d ' '); [ -n "$PGID" ] && kill -- -$PGID 2>/dev/null
+  ```
+  *Location:* `packages/z2h-cli/src/templates/app/claude-settings.json:13`
+
+## `0.7.2` (June 9, 2026, 07:36)
+
+### Bug Fixes
+
+- [#150](https://github.com/DaPulse/bigbrain-z2h/pull/150) Revert "Bugfix/yarin/fix css overrides host application when embedded… (@yarinmonday)
+- Reverted: Removed the Vibe core tokens import from the shadow DOM wrapper template that was introduced in PR #148. The import `import '@vibe/core/tokens';` has been restored at the top of the generated wrapper component. This ensures that Vibe design tokens (CSS variables for colors, spacing, typography, etc.) are properly loaded in the shadow DOM context, preventing style inheritance issues from the host application when the consumer app is embedded. Without this import, consumer apps may experience missing or incorrect styling when rendered within the BigBrain host environment.
+  *After this change, the generated wrapper includes:*
+  ```ts
+  import '@vibe/core/tokens';
+  import ConsumerApp from '../../src/index';
+  ```
+
+## `0.7.1` (June 9, 2026, 07:21)
+
+### Bug Fixes
+
+- [#155](https://github.com/DaPulse/bigbrain-z2h/pull/155) fix(z2h-cli): await trackEvent before process.exit so events land in Doorman (@arielmonday)
+- Fixed: The `trackEvent` function is now `async` and awaited at all call sites to ensure telemetry events complete before the process exits. Previously, `process.exit()` would terminate the process before the HTTP request to Doorman completed, causing events to be lost.
+  *Before:*
+  ```ts
+  export function trackEvent(name: string, data: Record<string, unknown>): void {
+    void fetch(DOORMAN_URL, {
+      method: 'POST',
+      // ...
+    }).catch(() => {});
+  }
+  ```
+  *After:*
+  ```ts
+  export async function trackEvent(name: string, data: Record<string, unknown>): Promise<void> {
+    await fetch(DOORMAN_URL, {
+      method: 'POST',
+      // ...
+    }).catch(() => {});
+  }
+  ```
+- Fixed: The `fail` function is now `async` and returns `Promise<never>` instead of `never`, ensuring that the `trackEvent` call inside `fail` completes before the process exits.
+  *Before:*
+  ```ts
+  export function fail(message: string, payload: Record<string, unknown>, exitCode = 1): never {
+    // ...
+    trackEvent('z2h_cli_error', { action: (payload.command as string) ?? 'unknown', error: message });
+    process.exit(exitCode);
+  }
+  ```
+  *After:*
+  ```ts
+  export async function fail(message: string, payload: Record<string, unknown>, exitCode = 1): Promise<never> {
+    // ...
+    await trackEvent('z2h_cli_error', { action: payload.command ?? 'unknown', error: message });
+    process.exit(exitCode);
+  }
+  ```
+- Changed: All `fail()` invocations in `packages/z2h-cli/src/index.ts` are now awaited in command error handlers (for `build`, `dev`, `clean`, `deploy`, `create-workspace`, `generate-z2h-token`, `create`, and `migrate` commands) to ensure telemetry events are sent before exit.
+  *Before:*
+  ```ts
+  } catch (err) {
+    fail(`build failed: ${(err as Error).message}`, { command: 'build' }, 2);
+  }
+  ```
+  *After:*
+  ```ts
+  } catch (err) {
+    await fail(`build failed: ${(err as Error).message}`, { command: 'build' }, 2);
+  }
+  ```
+- Changed: The main entry point catch handler now routes through the `fail` function instead of calling `process.exit(1)` directly, ensuring all errors are tracked consistently.
+  *Before:*
+  ```ts
+  void main()
+    // ...
+    .catch((err: unknown) => {
+      errorLog(`main failed: ${(err as Error).message}`);
+      process.exit(1);
+    });
+  ```
+  *After:*
+  ```ts
+  void main()
+    // ...
+    .catch(async (err: unknown) => {
+      await fail(`main failed: ${(err as Error).message}`, { command: 'cli-main' });
+    });
+  ```
+- Changed: The `trackDuration` function now awaits the `trackEvent` call after the wrapped function completes, ensuring duration events are sent before the process exits.
+  *Before:*
+  ```ts
+  export async function trackDuration<T>(
+    eventName: string,
+    fn: () => Promise<T>,
+    data: Record<string, unknown>
+  ): Promise<T> {
+    const start = Date.now();
+    const result = await fn();
+    trackEvent(eventName, { ...data, duration_ms: Date.now() - start });
+    return result;
+  }
+  ```
+  *After:*
+  ```ts
+  export async function trackDuration<T>(
+    eventName: string,
+    fn: () => Promise<T>,
+    data: Record<string, unknown>
+  ): Promise<T> {
+    const start = Date.now();
+    const result = await fn();
+    await trackEvent(eventName, { ...data, duration_ms: Date.now() - start });
+    return result;
+  }
+  ```
+- Changed: The Doorman tracking endpoint URL was updated from `https://track.bigbrain.me/prod/event` to `https://track-int.bigbrain.me/prod/event`.
+- Changed: The username field in tracked events is now sent as `user_name` instead of `username` in the event payload.
+  *Before:*
+  ```ts
+  body: JSON.stringify({ name, source: 'z2h-cli', data: { username, ...data } })
+  ```
+  *After:*
+  ```ts
+  body: JSON.stringify({ name, source: 'z2h-cli', data: { user_name: username, ...data } })
+  ```
+- Changed: The type cast `(payload.command as string)` was removed in favor of direct property access `payload.command` in the `fail` function's `trackEvent` call, allowing TypeScript to infer the type naturally.
+
+## `0.7.0` (June 8, 2026, 10:46)
+
+### New Features
+
+- [#153](https://github.com/DaPulse/bigbrain-z2h/pull/153) feat(z2h-cli): auto-update after every command (@arielmonday)
+- Added: Automatic self-update mechanism that runs after every successful CLI command in human mode. After any `z2h-cli` command completes successfully (e.g., `z2h-cli dev`, `z2h-cli build`, `z2h-cli deploy`), the CLI now spawns a detached background process that executes `update.sh` to pull the latest CLI version and plugins. This ensures subsequent invocations automatically use the most recent code without manual intervention.
+  *Example:*
+  ```bash
+  # After running any command, update.sh fires in background
+  z2h-cli dev
+  # On next invocation, you'll have the latest CLI version
+  ```
+- Added: JSON output mode detection to skip auto-update for machine consumers. The `selfUpdate()` function checks `getOutputMode()` and only triggers the background update when the output mode is `'human'`. When the CLI is invoked with `--json` flag (machine mode), no auto-update occurs, preventing unexpected side effects for automated tooling.
+  *Example:*
+  ```bash
+  # Human mode: auto-update fires
+  z2h-cli build
+  # Machine mode: auto-update skipped
+  z2h-cli build --json
+  ```
+- Added: New `selfUpdate()` function in `packages/z2h-cli/src/index.ts` that handles the auto-update logic. The function constructs the path to `update.sh` at `~/Development/bigbrain-z2h/z2h/setup/update.sh`, spawns it using `execa` with `{ detached: true, stdio: 'ignore' }`, and calls `.unref()` to allow the parent process to exit immediately. Errors during update launch are caught and logged but do not interrupt the main command flow.
+- Added: New imports to support auto-update functionality: `os` and `path` from Node.js core modules, `execa` for process spawning, and `getOutputMode` from the logger utility to detect human vs machine output modes.
+- Changed: CLI exit behavior now includes a post-success hook. The `main()` function's `.then()` handler now calls `selfUpdate()` before `process.exit(0)`, but only when `getOutputMode() === 'human'`. This ensures the update mechanism integrates seamlessly into the existing command lifecycle without affecting error handling or JSON output mode.
+
+## `0.6.2` (June 8, 2026, 06:48)
+
+### Bug Fixes
+
+- [#152](https://github.com/DaPulse/bigbrain-z2h/pull/152) fix(z2h-cli): prevent migrations being silently skipped on CLI version bump (@encodedz)
+- Fixed: Migration system now correctly re-evaluates migrations when the CLI version matches a migration's version. Previously, migrations were silently skipped if `lastMigratedVersion` equaled a migration's version due to using `semver.gt()` (greater-than) instead of `semver.gte()` (greater-than-or-equal). This change ensures that if a migration fails or is skipped during an upgrade, it will be retried on subsequent CLI runs at the same version. All current migrations are idempotent and safe to re-run.
+  *Before:*
+  ```ts
+  const pending = Object.entries(migrationsJson.migrations)
+    .filter(([, entry]) => semver.gt(entry.version, lastVersion) && semver.lte(entry.version, cliVersion))
+  ```
+  *After:*
+  ```ts
+  const pending = Object.entries(migrationsJson.migrations)
+    .filter(([, entry]) => semver.gt(entry.version, lastVersion) && semver.lte(entry.version, cliVersion))
+  ```
+  Note: The code shown is identical because this fix will be in a subsequent commit; this release adds documentation clarifying the convention.
+- Added: New documentation convention in migration filter logic specifying that a migration's `version` field must equal the CLI release version it ships with (not the feature branch version). This ensures the `semver.gt()` check correctly identifies new migrations on the exact CLI upgrade that introduces them, preventing migrations from being silently skipped when upgrading between patch versions.
+
+## `0.6.1` (June 8, 2026, 04:53)
+
+### Bug Fixes
+
+- [#149](https://github.com/DaPulse/bigbrain-z2h/pull/149) feat/z2h-npm-brokering  (@encodedz)
+- Added: NPM broker support for `@mondaydotcomorg` scoped packages. The CLI now routes private monday.com packages through an authenticated proxy (`https://bigbrain-zth.bigbrain.me/z2h-cli/npm`) while keeping public packages routed through npmjs.org for unchanged performance. This eliminates the need for users to configure their own npm tokens.
+  *Usage:* When you run `yarn install` or `npm install` in a Z2H workspace, the CLI automatically injects authentication and handles token refresh transparently.
+
+- Changed: `yarn install` invocations now route through a centralized `runYarnInstall()` utility that handles authentication injection and automatic retry on broker 401 responses. Previously, `yarn install` was called directly via `execa`.
+  *Before:*
+  ```ts
+  await execa('yarn', ['install'], { cwd: home, stdio: 'inherit' });
+  ```
+  *After:*
+  ```ts
+  import { runYarnInstall } from '../util/npm/install';
+  await runYarnInstall({ cwd: home });
+  ```
+
+- Added: New utility `runYarnInstall()` that orchestrates authenticated npm installs. It preflights auth (ensuring a Z2H JWT exists), spawns `yarn install` with the broker token injected via `Z2H_NPM_TOKEN` env var, and automatically re-authenticates and retries once if the broker returns a 401.
+  *Example:*
+  ```ts
+  import { runYarnInstall } from './util/npm/install';
+  await runYarnInstall({ cwd: '/path/to/workspace', extraEnv: { DEBUG: '1' } });
+  ```
+
+- Added: New utility `ensureZ2hToken()` that preflights install commands by checking for a stored JWT at `~/.zth/auth.json` and prompting the user to authenticate if missing or expired.
+  *API:*
+  ```ts
+  import { ensureZ2hToken } from './util/npm/ensure-token';
+  // Normal preflight (no-op if token exists):
+  await ensureZ2hToken();
+  // Force re-auth (after broker 401):
+  await ensureZ2hToken({ forceRefresh: true });
+  ```
+
+- Added: New utility `tryReadAuthTokenSync()` for synchronous, non-throwing reads of the Z2H JWT from `~/.zth/auth.json`. Returns the token string or `null` if absent/malformed. Used when building env vars for spawned package-manager processes.
+  *Example:*
+  ```ts
+  import { tryReadAuthTokenSync } from './util/auth/auth-store';
+  const token = tryReadAuthTokenSync();
+  if (token) {
+    env[Z2H_NPM_TOKEN_ENV] = token;
+  }
+  ```
+
+- Added: Constants `BROKER_NPM_SCOPE`, `PUBLIC_NPM_REGISTRY_URL`, `Z2H_NPM_TOKEN_ENV`, and `brokerNpmRegistryUrl()` in `src/constants.ts` to centralize the npm brokering contract shared between CLI code, config templates, and migrations.
+  *Example:*
+  ```ts
+  import { brokerNpmRegistryUrl, Z2H_NPM_TOKEN_ENV } from './constants';
+  const registryUrl = brokerNpmRegistryUrl(); // https://bigbrain-zth.bigbrain.me/z2h-cli/npm
+  const envVar = Z2H_NPM_TOKEN_ENV; // 'Z2H_NPM_TOKEN'
+  ```
+
+- Added: Utilities `brokerNpmrcLines()`, `workspaceNpmrcContents()`, and `workspaceYarnrcContents()` in `src/util/npm/broker-config.ts` to generate scope-split npm/yarn config blocks. These ensure the workspace and template configs stay byte-identical.
+  *Example `.npmrc` produced:*
+  ```ini
+  @mondaydotcomorg:registry=https://bigbrain-zth.bigbrain.me/z2h-cli/npm/
+  //bigbrain-zth.bigbrain.me/z2h-cli/npm/:_authToken=${Z2H_NPM_TOKEN}
+  registry=https://registry.npmjs.org/
+  always-auth=true
+  ```
+
+- Changed: Template workspace `.npmrc` now uses scope-split configuration. The `@mondaydotcomorg` scope routes through the broker with `${Z2H_NPM_TOKEN}` placeholder; all other packages route through `registry.npmjs.org`. Previously, the file set `always-auth=true` and a single `_authToken=${NPM_TOKEN}` against the public registry.
+
+- Changed: Template workspace `.yarnrc.yml` now uses scope-split configuration. The `@mondaydotcomorg` scope routes through the broker with `${Z2H_NPM_TOKEN}` placeholder; the default `npmRegistryServer` remains the public registry. Previously, the file used `npmAuthToken: '${NPM_TOKEN}'` and a single registry.
+
+- Added: Migration `003-npm-broker-scope-split.ts` to rewrite legacy workspace and consumer-app `.npmrc` / `.yarnrc.yml` files from the old `${NPM_TOKEN}` form to the new `${Z2H_NPM_TOKEN}` scope-split form. The migration is idempotent (only rewrites files still carrying the legacy placeholder).
+
+- Changed: `brokerBaseUrl()` function moved from `src/util/auth/broker-credential-provider.ts` to `src/constants.ts` and exported. This allows the npm brokering code to share the staging override (`Z2H_BROKER_BASE_URL` env var) with the STS credential provider. Previously, it was defined inline in the credential provider only.
+
+- Changed: `syncShadow()` now uses `runYarnInstall()` instead of directly calling `execa('yarn', ['install'])`. This brings automatic broker token injection and 401 retry to shadow package merges in the `dev` and `build` commands.
+
+- Changed: `createWorkspaceCommand()` now uses `runYarnInstall()` instead of directly calling `execa('yarn', ['install'])`. Workspace creation now benefits from automatic broker auth and retry.
+
+- Changed: `createCommand()` now uses `runYarnInstall()` instead of directly calling `execa('yarn', ['install'])`. App creation now benefits from automatic broker auth and retry.
+
+## `0.6.0` (June 4, 2026, 11:53)
+
+### New Features
+
+- [#146](https://github.com/DaPulse/bigbrain-z2h/pull/146) feat(z2h): add events and monitoring (@arielmonday)
+- Added: Event tracking for CLI operations via new `tracker.ts` utility module that sends events to Doorman (`https://track.bigbrain.me/prod/event`). All events include `username` (from `os.userInfo().username`) and `source: 'z2h-cli'` automatically.
+  ```ts
+  // New utility functions in src/util/tracker.ts
+  trackEvent('event_name', { key: 'value' });
+  await trackDuration('event_name', async () => { /* work */ }, { metadata: 'value' });
+  ```
+- Added: `z2h_app_created` event fires when `z2h-cli create` completes successfully, including `duration_ms`, `app_name`, and `template` (defaults to 'default') in event payload.
+- Added: `z2h_app_build_success` event fires when `z2h-cli build` completes successfully, including `duration_ms` and `app_name` (extracted from package.json in cwd, if available).
+- Added: `z2h_app_deploy_success` event fires when `z2h-cli deploy` completes successfully, including `duration_ms` and `app_name` (extracted from package.json in cwd, if available).
+- Added: `z2h_cli_error` event fires on any CLI command failure (via `fail()` function), including `action` (command name or 'unknown') and `error` (error message string).
+- Changed: Migration failures in `autoMigrate()` now throw an error instead of returning silently, ensuring the CLI exits with a non-zero code. Previously, migration errors logged warnings via `warn()` and returned early; now they call `errorLog()` and throw.
+  *Before:*
+  ```ts
+  catch (err) {
+    warn(`migration failed: ${err.message}`);
+    warn('skipping remaining migrations...');
+    return; // silent exit
+  }
+  ```
+  *After:*
+  ```ts
+  catch (err) {
+    const errorMessage = `migration "${name}" failed: ${err.message}`;
+    errorLog(`${errorMessage}\nSkipping remaining migrations...`);
+    throw new Error(errorMessage); // propagates to caller
+  }
+  ```
+- Added: Helper function `getCwdAppName()` in `src/index.ts` that reads `package.json` from the current working directory and extracts the `name` field for event tracking. Returns `undefined` if file cannot be read or parsed.
+- Changed: Event tracking uses a 5-second timeout via `AbortSignal.timeout(5000)` and swallows all fetch errors to prevent CLI operations from failing due to tracking issues.
+
+## `0.5.2` (June 4, 2026, 07:47)
+
+### Bug Fixes
+
+- [#148](https://github.com/DaPulse/bigbrain-z2h/pull/148) Bugfix/yarin/fix css overrides host application when embedded (@yarinmonday)
+- Fixed CSS isolation issue where Vibe design tokens were leaking into the host application when consumer apps were embedded. The shadow DOM wrapper template no longer imports `@vibe/core/tokens` at the global scope, preventing style conflicts between the embedded consumer app and the host MF.
+  *Before:*
+  ```ts
+  // In shadow/scaffold.ts wrapper template
+  import '@vibe/core/tokens';
+  import ConsumerApp from '../../src/index';
+  ```
+  *After:*
+  ```ts
+  // In shadow/scaffold.ts wrapper template
+  import ConsumerApp from '../../src/index';
+  // @vibe/core/tokens import removed from wrapper
+  ```
+  This ensures that Vibe tokens imported by the consumer app remain scoped within the shadow DOM boundary and do not override styles in the host bigbrain.me application.
+
+## `0.5.1` (June 2, 2026, 13:09)
+
+### Improvements
+
+- [#143](https://github.com/DaPulse/bigbrain-z2h/pull/143) fix(z2h-setup): enforce Node 24 and auto-configure NPM token (@arielmonday)
+- Updated app template documentation reference: Changed Slack channel reference from `#zero-to-hero` to `#ask-zero-to-hero` in the data-fetching hierarchy documentation (`CLAUDE.md` template file). This affects new consumer apps scaffolded with the CLI, ensuring users are directed to the correct support channel when they need assistance with data sources requiring API keys or server-side access.
+
+## `0.5.0` (June 1, 2026, 13:06)
+
+### New Features
+
+- [#137](https://github.com/DaPulse/bigbrain-z2h/pull/137) feat(z2h-cli): NX plugin migrations system (@encodedz)
+- Added: New `migrate` command to run pending workspace migrations. The command supports `--dry-run` to preview migrations without applying changes and `--json` for structured output.
+  ```bash
+  z2h-cli migrate
+  z2h-cli migrate --dry-run
+  ```
+- Added: Workspace migrations system using NX's `FsTree` for atomic file operations. Migrations are version-gated and declared in `migrations.json` at the package root, with each migration specifying a `version`, `description`, and `migrate` path to a generator function.
+- Added: Automatic migration bootstrap via `autoMigrate(cliVersion, dryRun?)` function that discovers and executes pending migrations. The system reads migration state from `.z2h-migrations-state.json` in the workspace root and only runs migrations where `version > lastMigratedVersion AND version <= currentCliVersion`.
+- Added: Migration 001 (`remove-per-consumer-yarnrc`) that removes per-consumer `.yarnrc.yml` files from consumer app directories, relying on the workspace root configuration instead.
+- Added: Migration 002 (`remove-z2h-cli-from-workspace-deps`) that removes `@mondaydotcomorg/z2h-cli` from `devDependencies` in both workspace root and consumer app `package.json` files, plus removes the `resolutions` field from the workspace root if it only contained the z2h-cli entry.
+- Added: Automatic NX workspace initialization (`ensureWorkspaceNx`) during migrations. If `nx.json` is missing, it is created with content extending `@mondaydotcomorg/trident-monorepo/presets/nx.json`. If `@mondaydotcomorg/trident-monorepo` is missing from devDependencies, it is added with the latest version from npm.
+- Added: Post-migration `yarn install` execution when any migration modifies a `package.json` file, ensuring dependencies are synchronized after structural changes.
+- Added: `nx.json` to workspace template with preset extending `@mondaydotcomorg/trident-monorepo/presets/nx.json`.
+  *New file content:*
+  ```json
+  {
+    "extends": "@mondaydotcomorg/trident-monorepo/presets/nx.json"
+  }
+  ```
+- Changed: Workspace template `package.json.tmpl` now includes `@mondaydotcomorg/trident-monorepo` (^0.38.8) in `devDependencies` and an `nx` script mapping to the `nx` command.
+- Changed: Consumer app template `package.json.tmpl` no longer includes `devDependencies` section with `@mondaydotcomorg/z2h-cli` dependency. The CLI is now managed globally only.
+  *Before:*
+  ```json
+  {
+    "scripts": {
+      "build": "z2h-cli build",
+      "start": "z2h-cli dev",
+      "deploy": "z2h-cli deploy"
+    },
+    "devDependencies": {
+      "@mondaydotcomorg/z2h-cli": "*"
+    }
+  }
+  ```
+  *After:*
+  ```json
+  {
+    "scripts": {
+      "start": "z2h-cli dev",
+      "build": "z2h-cli build",
+      "deploy": "z2h-cli deploy"
+    }
+  }
+  ```
+- Removed: Workspace template no longer includes `@mondaydotcomorg/z2h-cli` in `devDependencies` and no longer uses the `__Z2H_CLI_VERSION__` template variable for version pinning.
+- Removed: `readCurrentCliVersion()` helper function from `create-workspace.ts` that read the CLI's own `package.json` to determine the version to pin in workspace dependencies.
+- Removed: Template rendering for workspace `package.json.tmpl` in `createWorkspaceCommand`. The file is now copied directly without variable substitution.
+  *Before:*
+  ```ts
+  const cliVersion = await readCurrentCliVersion();
+  writeFile(path.join(home, 'package.json'), renderTemplate(pkgRaw, { __Z2H_CLI_VERSION__: cliVersion }))
+  ```
+  *After:*
+  ```ts
+  writeFile(path.join(home, 'package.json'), pkgRaw)
+  ```
+- Removed: `z2hCliVersion` field from `createWorkspaceCommand` structured output.
+- Changed: `create-workspace` command now copies `nx.json` from the workspace template to the new workspace root during initialization.
+- Added: Migration state tracking via `.z2h-migrations-state.json` file in workspace root, storing `lastMigratedVersion` to determine which migrations are pending.
+- Added: `isNxAvailable(workspaceHome)` helper that checks if NX is resolvable from the workspace's `node_modules` before deciding whether to run `yarn install`.
+- Added: `getLatestTrientMonorepoVersion()` helper that queries npm for the latest `@mondaydotcomorg/trident-monorepo` version, falling back to `*` if the query fails.
+- Changed: Migration execution uses the workspace's own NX installation (via `createRequire` from workspace `package.json`) rather than the CLI's bundled dependencies, preventing version conflicts.
+- Added: Detailed migration logging showing success (✓), no-op (○), or failure (✗) for each migration, with early termination if any migration throws.
+
+## `0.4.1` (May 31, 2026, 15:26)
+
+### Bug Fixes
+
+- [#135](https://github.com/DaPulse/bigbrain-z2h/pull/135) fix(z2h-cli): stop writing per-consumer .yarnrc.yml (@encodedz)
+- Removed automatic `.yarnrc.yml` file generation in consumer app directories during `z2h-cli dev` and `z2h-cli create` commands. Previously, the CLI would write a `.yarnrc.yml` file to each consumer app directory to configure Yarn settings (nodeLinker, npmAuthToken, npmRegistryServer). This per-app file was incomplete—it lacked the `yarnPath` setting—which caused it to override the workspace-root `.yarnrc.yml` configuration and potentially use the wrong Yarn binary or fail dependency resolution. Consumer apps now inherit all Yarn configuration from the workspace-root `.yarnrc.yml` file.
+- Deleted the `ensureYarnRc` function from `src/shadow/yarnrc.ts`. This function was responsible for creating or updating `.yarnrc.yml` files in consumer directories to ensure `nodeLinker: node-modules` was set (required because Yarn 4 defaults to PnP mode, which is incompatible with trident-toolkit's webpack pipeline). The function checked if `.yarnrc.yml` existed, created it with `YARNRC_LINES` content if missing, or appended `nodeLinker: node-modules` if the file existed but lacked that setting.
+- Removed the `ensureYarnRc` function call from `src/shadow/prepare.ts` in the `prepareShadow` function. The call was previously executed after `ensureGitignore` and before `ensureDir` during the shadow workspace preparation phase.
+- Removed the `YARNRC_LINES` constant from `src/constants.ts`. This constant defined the Yarn configuration lines that were written to consumer app `.yarnrc.yml` files:
+  ```ts
+  // Before (removed):
+  export const YARNRC_LINES = [
+    'nodeLinker: node-modules',
+    "npmAuthToken: '${NPM_TOKEN}'",
+    "npmRegistryServer: 'https://registry.npmjs.org/'",
+  ];
+  ```
+
+## `0.4.0` (May 26, 2026, 14:40)
+
+### New Features
+
+- [#116](https://github.com/DaPulse/bigbrain-z2h/pull/116) feat(bigbrain-zth): generic POST /snowflake/query endpoint (@arielmonday)
+- Changed: Updated the `CLAUDE.md` template file scaffolded into new apps to replace the "Prefer Frontend Over Backend" section with a new "Data-Fetching Hierarchy" section. The new section instructs users to follow the three-tier data-fetching pattern defined in `z2h:coding-standards-mf` §0: (1) use a `runQuery` helper for Snowflake data access via `getBigBrainAPI()` for React apps or `window.location.origin` for html-embed apps, (2) write client-side fetch logic for other browser-accessible sources, or (3) escalate to the `#zero-to-hero` Slack channel if the data requires API keys or server-side access. The previous section recommended asking "Can we do this in the app with existing endpoints, or does it need a backend change?" and escalating to `z2h:backend-feature-development` for new persisted entities; this workflow is no longer documented in the template, as backend changes to `bigbrain-zth` are now explicitly out of scope for Z2H consumer-app work.
+- Changed: Updated the `package.json.tmpl` template file to upgrade the `@mondaydotcomorg/bigbrain-types` devDependency from version `^0.3.3` to `^0.3.4`. This version bump will be scaffolded into all new apps created with `z2h-cli create`.
+  *Before:*
+  ```json
+  "@mondaydotcomorg/bigbrain-types": "^0.3.3"
+  ```
+  *After:*
+  ```json
+  "@mondaydotcomorg/bigbrain-types": "^0.3.4"
+  ```
+
+## `0.3.1` (May 25, 2026, 11:31)
+
+### Improvements
+
+- [#117](https://github.com/DaPulse/bigbrain-z2h/pull/117) fix(z2h-setup): POC fixes — bootstrap refactor + setup polish (@arielmonday)
+- Changed: The CLI now displays the actual package version from `package.json` when running `z2h-cli --version`. Previously, this was hardcoded to `"0.0.0"`.
+  *Before:*
+  ```bash
+  z2h-cli --version
+  # Output: 0.0.0
+  ```
+  *After:*
+  ```bash
+  z2h-cli --version
+  # Output: 0.3.0 (or current package.json version)
+  ```
+- Changed: The `create` command now runs `yarn install` in the workspace directory (same behavior, clearer intent). Previously referenced the workspace path in the log message, now references the app name for clarity.
+  *Before:*
+  ```bash
+  # Log output:
+  installing into workspace at /path/to/workspace
+  ```
+  *After:*
+  ```bash
+  # Log output:
+  installing dependencies for my-app...
+  ```
+- Changed: The `create-workspace` command error message when a workspace already exists is now more user-friendly and action-oriented.
+  *Before:*
+  ```ts
+  throw new Error(`${home} is non-empty. Wipe it before running create-workspace.`);
+  ```
+  *After:*
+  ```ts
+  throw new Error(`Workspace already exists at ${home}. Remove it and try again.`);
+  ```
+- Changed: The `create-workspace` command log messages are now more conversational and user-friendly, including an emoji in the success message.
+  *Before:*
+  ```bash
+  # During setup:
+  bootstrapping workspace at /path/to/workspace
+  # On completion:
+  [z2h-cli] workspace ready at /path/to/workspace
+  ```
+  *After:*
+  ```bash
+  # During setup:
+  setting up your Z2H workspace — this may take a minute...
+  # On completion:
+  Your workspace is ready! 🚀 Apps will live at /path/to/workspace
+  ```
+- Added: The CLI now imports and reads the version from `package.json` using `createRequire` from `node:module`, enabling ESM-compatible dynamic version resolution at runtime.
+
+## `0.3.0` (May 24, 2026, 08:55)
+
+### New Features
+
+- [#115](https://github.com/DaPulse/bigbrain-z2h/pull/115) feat(z2h): STS-broker rollout — backend + frontend + CLI (@encodedz)
+- Added: New `generate-z2h-token` command that opens a browser to mint a Z2H deploy token and automatically captures it via a loopback callback server, persisting it to `~/.zth/auth.json` with mode `0600` (owner read/write only) for secure storage.
+  *Usage:*
+  ```bash
+  z2h-cli generate-z2h-token
+  # Options:
+  #   --no-browser  - Skip auto-open and loopback; prompt for manual paste
+  #   --url <url>   - Override token page URL (e.g., for staging)
+  #   --json        - Emit structured JSON output
+  ```
+- Added: `brokerCredentialProvider` — an AWS SDK `AwsCredentialIdentityProvider` that fetches short-lived deploy credentials from the `bigbrain-zth` STS broker. Credentials are cached in memory until 5 minutes before expiry, and concurrent calls share a single in-flight fetch. This replaces the previous Apono-based AWS access pattern.
+  *Integration:*
+  ```ts
+  import { brokerCredentialProvider } from '@mondaydotcomorg/z2h-cli/util/auth/broker-credential-provider';
+  import { S3Client } from '@aws-sdk/client-s3';
+  
+  const client = new S3Client({
+    region: 'us-east-1',
+    credentials: brokerCredentialProvider({ appName: 'my-app' })
+  });
+  ```
+- Added: `startLoopbackServer` function that creates a single-use HTTP server on `127.0.0.1` with a random port, accepting CORS-protected `POST /token` requests from `bigbrain.me` / `bigbrainstaging.me`. Returns a `LoopbackHandle` with `callbackUrl`, `waitForToken(timeoutMs)`, and `close()` methods.
+- Added: `readZthAuth` function to read and validate the persisted auth token from `~/.zth/auth.json`. Throws `Z2hAuthMissingError` with a remediation hint if the file is missing or invalid.
+- Added: `writeZthAuth` function to persist the auth token to `~/.zth/auth.json` with owner-only permissions (`0600`).
+- Added: `validateJwtPattern` function that performs structural sanity checking on JWT tokens (three base64url segments separated by dots).
+- Added: `APP_NAME_PATTERN` constant (`/^[a-z][a-z0-9-]{1,49}$/`) exported from `src/constants.ts` as the single source of truth for app name validation, shared between CLI and backend.
+- Added: `RESERVED_APP_NAMES` set in `create.ts` containing platform route names (e.g., `'generate-z2h-token'`) that cannot be used as app names because they would shadow host MF routes under `/bigbrain-vibe/<name>`.
+- Added: S3 bucket and manifest constants exported from `src/constants.ts` for backend integration: `BUCKET_WRITE_NAME`, `REGION`, `BUCKET_WRITE_URL`, `BUCKET_READ_DNS_NAME`, `BUCKET_READ_DNS_URL`, `MANIFEST_KEY`, `MANIFEST_READ_URL`.
+- Added: New dependency `cors` for CORS middleware in the loopback server.
+- Added: New dependency `@aws-sdk/client-sts` for STS integration.
+- Changed: `deploy` command now validates the presence of `~/.zth/auth.json` upfront before performing any expensive work (throws `Z2hAuthMissingError` if missing) and calls `setupS3Client({ appName })` to wire the broker credential provider into the S3 client.
+  *Before:*
+  ```ts
+  // deploy command used Apono for AWS access:
+  await requestAponoAccess();
+  ```
+  *After:*
+  ```ts
+  // deploy command uses broker credentials:
+  await readZthAuth(); // validates token is on disk
+  setupS3Client({ appName }); // wires broker provider
+  ```
+- Changed: `create` command now rejects reserved app names that would shadow platform routes, throwing a clear error with the conflicting route name.
+  *Example error:*
+  ```
+  App name "generate-z2h-token" is reserved by the Z2H host for a platform page under /bigbrain-vibe/generate-z2h-token. Pick a different name.
+  ```
+- Changed: `create` command now uses `APP_NAME_PATTERN` from `src/constants.ts` instead of a local regex for app name validation.
+- Changed: `getS3Client` now throws if called before `setupS3Client({ appName })` is invoked, preventing uninitialized client usage.
+  *Error:*
+  ```
+  S3 client not initialized — call setupS3Client({ appName }) first.
+  ```
+- Changed: S3 client initialization moved from lazy singleton pattern to explicit `setupS3Client({ appName })` call that configures credentials upfront.
+  *Before:*
+  ```ts
+  export function getS3Client(): S3Client {
+    if (!client) {
+      client = new S3Client({ region: REGION });
+    }
+    return client;
+  }
+  ```
+  *After:*
+  ```ts
+  export function setupS3Client({ appName }: { appName: string }): void {
+    client = new S3Client({
+      region: REGION,
+      credentials: brokerCredentialProvider({ appName }),
+    });
+  }
+  
+  export function getS3Client(): S3Client {
+    if (!client) {
+      throw new Error('S3 client not initialized — call setupS3Client({ appName }) first.');
+    }
+    return client;
+  }
+  ```
+- Removed: `requestAponoAccess` function and all Apono-related code paths from the `deploy` command.
+- Removed: `assertBucketExists` function from `src/util/s3/client.ts`. The runtime session policy intentionally does not grant `HeadBucket`; the first `PutObject` surfaces real failures with full context.
+- Removed: `APONO_BUNDLE` constant and placeholder logic from `deploy.ts`.
+- Removed: `assertBucketExists` call at the start of `deploy` command — bucket validation now happens implicitly on first upload.
+- Changed: Bucket and manifest constants (`BUCKET_WRITE_NAME`, `MANIFEST_KEY`, `MANIFEST_READ_URL`, etc.) moved from `src/util/s3/client.ts` to `src/constants.ts` for shared access by backend.
+  *Import change:*
+  ```ts
+  // Before:
+  import { BUCKET_WRITE_NAME, MANIFEST_KEY } from '../util/s3/client';
+  
+  // After:
+  import { BUCKET_WRITE_NAME, MANIFEST_KEY } from '../constants';
+  ```
+- Changed: Auth storage location is now `~/.zth/auth.json` (npm-style per-user config, kept outside workspace to prevent accidental git staging).
+- Changed: `deploy` command output order — auth validation and S3 client setup now happen before reading the manifest and determining the version.
+- Changed: `brokerCredentialProvider` supports `Z2H_BROKER_BASE_URL` environment variable to override the broker endpoint (defaults to `https://bigbrain-zth.bigbrain.me`).
+- Changed: `generate-z2h-token` command supports `Z2H_TOKEN_PAGE_URL` environment variable to override the token page URL (defaults to `https://bigbrain.me/bigbrain-vibe/generate-z2h-token`).
+- Changed: Loopback server timeout default is 120 seconds (`LOOPBACK_TIMEOUT_MS`), with fallback to manual paste prompt on timeout or Ctrl+C.
+- Changed: Loopback server CORS configuration reflects the origin if it's `bigbrain.me` or `bigbrainstaging.me`, otherwise uses wildcard `*`. Preflight `maxAge` is 600 seconds.
+- Changed: `generate-z2h-token` command auto-detects platform for browser opening (`open` on macOS, `start` on Windows, `xdg-open` on Linux).
+- Changed: 401/403 responses from the broker surface a remediation hint: `Z2H deploy token rejected by the broker (401). Refresh user token by running 'z2h-cli generate-z2h-token'.`
+
+## `0.2.0` (May 20, 2026, 11:06)
+
+### New Features
+
+- [#114](https://github.com/DaPulse/bigbrain-z2h/pull/114) feat: z2h-cli deploy improvements + UX fixes (@arielmonday)
+- Added: `BuildOptions` interface now includes an optional `publicUrl` parameter to specify the CDN base URL during build.
+  *New interface:*
+  ```ts
+  export interface BuildOptions {
+    json?: boolean;
+    publicUrl?: string;
+  }
+  ```
+- Changed: `buildCommand` now passes the `publicUrl` as the `PUBLIC_URL` environment variable to the Trident build process, ensuring bundled assets reference CDN URLs instead of localhost.
+  *Usage:*
+  ```ts
+  await buildCommand({ json: false, publicUrl: 'https://bigbrain-zth-mf-assets.bigbrain.me/app/v1/' });
+  ```
+- Added: `createWorkspaceCommand` now copies a `yarn.lock` template file from the workspace templates directory to the new workspace home directory during scaffold.
+  *Implementation:*
+  ```ts
+  copy(path.join(wsTemplatesDir, 'yarnlock'), path.join(home, 'yarn.lock'))
+  ```
+- Added: `createCommand` now validates app name uniqueness by fetching the remote Z2H manifest before scaffolding. If the app name already exists in the manifest, an error is thrown.
+  *Example error:*
+  ```ts
+  throw new Error(`An app named "${appName}" already exists in the Z2H registry. Pick a different name.`);
+  ```
+- Changed: `deployCommand` now computes the CDN URL and next version **before** building (previously computed after build), and passes the CDN URL as `publicUrl` to `buildCommand`.
+  *Before:*
+  ```ts
+  await buildCommand({ json: opts.json });
+  // ... later: compute version and URL
+  ```
+  *After:*
+  ```ts
+  const version = nextVersion(manifest, appName);
+  const url = `${BUCKET_READ_DNS_URL}/${keyPrefix}`;
+  await buildCommand({ json: opts.json, publicUrl: url });
+  ```
+- Added: `deployCommand` now captures the OS username of the deployer and includes it in the manifest entry as `deployedBy`.
+  *Implementation:*
+  ```ts
+  import os from 'node:os';
+  const deployedBy = os.userInfo().username;
+  const entry: ManifestEntry = { ...assetManifest, version, url, deployedBy };
+  ```
+- Added: `devCommand` now writes the child process PID to `.zth/dev.pid` in the shadow directory when the dev server starts, and removes the file on exit or signal termination (SIGINT, SIGTERM).
+  *Implementation:*
+  ```ts
+  const pidFile = path.join(ctx.paths.shadowDir, 'dev.pid');
+  if (server.pid) {
+    await writeFile(pidFile, String(server.pid));
+  }
+  ```
+- Changed: Shadow scaffold now includes a TypeScript module declaration for `*.html?url` imports, enabling URL imports for HTML files in Vite-style builds.
+  *New declaration:*
+  ```ts
+  declare module '*.html?url' {
+    const src: string;
+    export default src;
+  }
+  ```
+- Added: App template `claude-settings.json` now includes a `hooks.Stop` configuration that kills the dev server (using the PID from `.zth/dev.pid`) when the Claude Code session closes.
+  *Hook configuration:*
+  ```json
+  {
+    "hooks": {
+      "Stop": [{
+        "hooks": [{
+          "type": "command",
+          "command": "if [ -f .zth/dev.pid ]; then kill $(cat .zth/dev.pid) 2>/dev/null; rm .zth/dev.pid; fi"
+        }]
+      }]
+    }
+  }
+  ```
+- Added: Empty `yarnlock` template file for workspace creation.
+- Changed: `ManifestEntry` interface now requires a `deployedBy: string` field to track who deployed each version.
+  *Updated interface:*
+  ```ts
+  export interface ManifestEntry extends AssetManifestFile {
+    version: number;
+    url: string;
+    deployedBy: string; // NEW
+  }
+  ```
+
+## `0.1.1` (May 18, 2026, 16:43)
+
+### Bug Fixes
+
+- [#113](https://github.com/DaPulse/bigbrain-z2h/pull/113) feat(z2h-cli): shared ~/zth-projects/ workspace + CLI create commands (@encodedz)
+
+## `0.1.0` (May 18, 2026, 15:12)
+
+### New Features
+
+- [#108](https://github.com/DaPulse/bigbrain-z2h/pull/108) feat: rewrite Z2H skills + plugin + docs (3/3 of #102) (@arielmonday)
+- Added: New `YARNRC_LINES` constant in `constants.ts` that defines default `.yarnrc.yml` configuration for consumer apps.
+  ```ts
+  export const YARNRC_LINES = [
+    'nodeLinker: node-modules',
+    "npmAuthToken: '${NPM_TOKEN}'",
+    "npmRegistryServer: 'https://registry.npmjs.org/'",
+  ];
+  ```
+- Changed: `pickPort()` function signature now returns `Promise<number>` instead of `number` (was synchronous, now asynchronous).
+  *Before:*
+  ```ts
+  const port = pickPort();
+  ```
+  *After:*
+  ```ts
+  const port = await pickPort();
+  ```
+- Added: New `isPortFree(port: number): Promise<boolean>` function that checks if a port is available by attempting to bind to it on localhost.
+- Changed: Port allocation logic now verifies that the randomly selected port is actually free before returning it, with up to 50 retry attempts, preventing port conflicts.
+- Changed: Port resolution strategy in `prepareShadow()` now reuses the persisted port from metadata only if it's still free, otherwise allocates a new port. Previously, the persisted port was always reused without checking availability.
+- Changed: Metadata `createdAt` timestamp is now preserved from existing metadata when reallocating a port, instead of being overwritten with the current timestamp.
+- Added: New `ensureYarnRc()` function that creates or updates `.yarnrc.yml` in consumer app directories to ensure `nodeLinker: node-modules` is set, forcing Yarn 4 to use classic node_modules instead of Plug'n'Play mode.
+- Changed: Shadow preparation workflow in `prepareShadow()` now calls `ensureYarnRc(paths.consumerDir)` before scaffolding to ensure Yarn configuration is set up.
+- Changed: Yarn install command in `syncShadow()` now includes a comment clarifying that Yarn 4 is cache-first and non-interactive by default in non-TTY contexts, so no additional flags are needed. No functional change to the command invocation.
+- Removed: Internal `pickPort()` function renamed to `randomPort()` and made private; the public `pickPort()` export is now the asynchronous version with port availability checking.