@mondaydotcomorg/z2h-cli 0.12.1 → 0.13.1

package/dist/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAItG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJ3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/commands/deploy.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuJ3E"}

package/dist/commands/deploy.js

@@ -6,6 +6,7 @@ const node_readline = require('node:readline');
 const fs = require('fs-extra');
 const util_logger = require('../util/logger.js');
 const shadow_paths = require('../shadow/paths.js');
+const util_tags = require('../util/tags.js');
 const util_s3_upload = require('../util/s3/upload.js');
 const constants = require('../constants.js');
 const util_auth_brokerCredentialProvider = require('../util/auth/broker-credential-provider.js');
@@ -16,6 +17,7 @@ const util_git_repo = require('../util/git/repo.js');
 const util_git_gitEnv = require('../util/git/git-env.js');
 const util_git_remoteOptions = require('../util/git/remote-options.js');
 const util_s3_client = require('../util/s3/client.js');
+const commands_tag = require('./tag.js');
 const commands_build = require('./build.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
@@ -138,6 +140,9 @@ async function deployCommand(opts = {}) {
     finally {
         await releaseLockBestEffort(appName, token);
     }
+    // Tags are a post-deploy concern: the S3 upload has already succeeded, so a
+    // tag failure never fails the deploy (handled inside).
+    await handleDeployTags(appName);
     // The host MF parses the app name from the URL and prepends `mf-` itself
     // before looking it up in the manifest. So the user-facing URL must use
     // the consumer's de-scoped package name (no `mf-` prefix, no `@scope/`).
@@ -164,6 +169,27 @@ async function registerApp(appName, token, version, entry, visibility, gitRemote
         throw new Error(`App registration failed (${res.status}): ${text.slice(0, 1024)}`);
     }
 }
+const TAG_NUDGE = "run 'z2h-cli tag' to categorize this app (app type & team)";
+async function handleDeployTags(appSlug) {
+    try {
+        const interactive = util_logger.getOutputMode() === 'human' && Boolean(process.stdin.isTTY);
+        if (!interactive) {
+            util_logger.info(TAG_NUDGE);
+            return;
+        }
+        const current = await util_tags.fetchAppTags(appSlug);
+        if (current.length > 0) {
+            return; // already tagged — don't prompt on every redeploy
+        }
+        const catalog = await util_tags.fetchTagCatalog();
+        const selected = await commands_tag.promptForTags(appSlug, catalog, current);
+        const tags = await util_tags.setAppTags(appSlug, selected);
+        util_logger.info(tags.length > 0 ? `tags set: ${tags.map(t => t.name).join(', ')}` : TAG_NUDGE);
+    }
+    catch (err) {
+        util_logger.warn(`could not update tags: ${err.message}`);
+    }
+}
 // Acquire the per-app deploy lock. Throws a friendly error on 409 (someone else is deploying)
 // so the deploy stops and the caller can retry; the backend TTL backstops a crashed holder.
 async function acquireDeployLock(appName, token) {

package/dist/commands/tag.d.ts

@@ -0,0 +1,14 @@
+import { type AppTag, type CatalogEntry } from '../util/tags';
+export interface TagOptions {
+    /** Repeatable `--tag` — sets the full tag set non-interactively. */
+    tag?: string[];
+    json?: boolean;
+}
+/**
+ * Closed-list prompt: one numbered pick per dimension (app type, team). Enter
+ * keeps the current value for that dimension (or skips it if unset). Returns
+ * the full replacement set of tag names.
+ */
+export declare function promptForTags(appSlug: string, catalog: CatalogEntry[], current: AppTag[]): Promise<string[]>;
+export declare function tagCommand(appArg: string | undefined, opts: TagOptions): Promise<void>;
+//# sourceMappingURL=tag.d.ts.map

package/dist/commands/tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../src/commands/tag.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,MAAM,EACX,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAgCD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0ClH;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC5F"}

package/dist/commands/tag.js

@@ -0,0 +1,114 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const readline = require('node:readline/promises');
+const node_process = require('node:process');
+const fs = require('fs-extra');
+const shadow_paths = require('../shadow/paths.js');
+const util_appName = require('../util/app-name.js');
+const util_logger = require('../util/logger.js');
+const util_tags = require('../util/tags.js');
+
+const _interopDefault = e => e && e.__esModule ? e : { default: e };
+
+const readline__default = /*#__PURE__*/_interopDefault(readline);
+
+/** Render an app's tags as `name (Type), ...` — or `(none)`. */
+function formatTags(tags) {
+    return tags.map(t => `${t.name} (${util_tags.TAG_TYPE_LABELS[t.type]})`).join(', ') || '(none)';
+}
+/**
+ * Resolve the target app name: an explicit arg wins, else the consumer
+ * package.json `name` in the cwd. Normalized to the `mf-` bundle name the
+ * broker stores (via `mfAppName`), so the server finds the app.
+ */
+async function resolveAppSlug(appArg) {
+    if (appArg) {
+        return util_appName.mfAppName(appArg);
+    }
+    const paths = shadow_paths.resolveConsumerPaths(process.cwd());
+    let pkg;
+    try {
+        pkg = (await fs.readJson(paths.consumerPkg));
+    }
+    catch {
+        throw new Error('Could not read a consumer package.json in the current directory. ' +
+            'Either cd into your app folder or pass an app name: z2h-cli tag <app-name>.');
+    }
+    if (!pkg.name) {
+        throw new Error('Consumer package.json must have a "name" field (or pass an app name argument).');
+    }
+    return util_appName.mfAppName(pkg.name);
+}
+/**
+ * Closed-list prompt: one numbered pick per dimension (app type, team). Enter
+ * keeps the current value for that dimension (or skips it if unset). Returns
+ * the full replacement set of tag names.
+ */
+async function promptForTags(appSlug, catalog, current) {
+    const rl = readline__default.default.createInterface({ input: node_process.stdin, output: node_process.stdout });
+    const selected = [];
+    try {
+        util_logger.info(`Tagging "${appSlug}".`);
+        for (const type of util_tags.TAG_TYPES) {
+            const options = catalog.filter(t => t.type === type);
+            if (options.length === 0) {
+                continue;
+            }
+            const currentName = current.find(c => c.type === type)?.name;
+            const label = util_tags.TAG_TYPE_LABELS[type];
+            util_logger.info(`\n${label}${currentName ? ` (current: ${currentName})` : ''}:`);
+            options.forEach((o, i) => util_logger.info(`  ${i + 1}) ${o.name}`));
+            const raw = await rl.question(`Pick a ${label} (number or name; Enter to ${currentName ? 'keep current' : 'skip'}):\n> `);
+            const trimmed = raw.trim();
+            if (!trimmed) {
+                if (currentName) {
+                    selected.push(currentName);
+                }
+                continue;
+            }
+            // Accept either the 1-based number or the tag name (case-insensitive).
+            const idx = Number(trimmed) - 1;
+            const byNumber = Number.isInteger(idx) && idx >= 0 && idx < options.length ? options[idx] : undefined;
+            const chosen = byNumber ?? options.find(o => o.name.toLowerCase() === trimmed.toLowerCase());
+            if (chosen) {
+                selected.push(chosen.name);
+            }
+            else {
+                util_logger.info(`Invalid choice "${trimmed}" — ${currentName ? 'keeping current' : 'skipping'} ${label}.`);
+                if (currentName) {
+                    selected.push(currentName);
+                }
+            }
+        }
+        return selected;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function tagCommand(appArg, opts) {
+    if (opts.json) {
+        util_logger.setOutputMode('json');
+    }
+    const appSlug = await resolveAppSlug(appArg);
+    // Non-interactive write: `--tag` flags set the full set directly.
+    if (opts.tag && opts.tag.length > 0) {
+        const tags = await util_tags.setAppTags(appSlug, opts.tag);
+        util_logger.output(`[z2h-cli] tags for "${appSlug}": ${formatTags(tags)}`, { ok: true, appName: appSlug, tags });
+        return;
+    }
+    const [catalog, current] = await Promise.all([util_tags.fetchTagCatalog(), util_tags.fetchAppTags(appSlug)]);
+    // Read-only listing: agents (`--json`) and any non-TTY caller get the catalog
+    // + current tags without a prompt — then they set tags via `--tag`. This also
+    // avoids hanging on `readline` when no human is attached to stdin.
+    if (opts.json || !process.stdin.isTTY) {
+        util_logger.output(`[z2h-cli] "${appSlug}"\n  catalog: ${catalog.map(t => `${t.name} (${util_tags.TAG_TYPE_LABELS[t.type]})`).join(', ') || '(none)'}\n  current: ${formatTags(current)}`, { ok: true, appName: appSlug, catalog, current });
+        return;
+    }
+    const selected = await promptForTags(appSlug, catalog, current);
+    const tags = await util_tags.setAppTags(appSlug, selected);
+    util_logger.output(`[z2h-cli] tags for "${appSlug}": ${formatTags(tags)}`, { ok: true, appName: appSlug, tags });
+}
+
+exports.promptForTags = promptForTags;
+exports.tagCommand = tagCommand;

package/dist/esm/commands/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAItG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJ3E"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../../src/commands/deploy.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,UAAU,EAA2C,MAAM,4BAA4B,CAAC;AAKtG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,wBAAsB,aAAa,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuJ3E"}

package/dist/esm/commands/deploy.mjs

@@ -2,8 +2,9 @@ import path from 'node:path';
 import os from 'node:os';
 import { createInterface } from 'node:readline';
 import { readJson, pathExists } from 'fs-extra';
-import { setOutputMode, info, output, warn } from '../util/logger.mjs';
+import { setOutputMode, info, output, getOutputMode, warn } from '../util/logger.mjs';
 import { resolveConsumerPaths } from '../shadow/paths.mjs';
+import { fetchAppTags, fetchTagCatalog, setAppTags } from '../util/tags.mjs';
 import { uploadDir } from '../util/s3/upload.mjs';
 import { BUCKET_WRITE_NAME, brokerBaseUrl, routingHeaders, BUCKET_READ_DNS_URL } from '../constants.mjs';
 import { fetchDeployVersion, brokerCredentialProvider } from '../util/auth/broker-credential-provider.mjs';
@@ -14,6 +15,7 @@ import { getRemoteUrl, initRepo, guardCleanTree, pullAndResolve, pushToRemote }
 import { resolveGitEnv } from '../util/git/git-env.mjs';
 import { validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options.mjs';
 import { setupS3Client } from '../util/s3/client.mjs';
+import { promptForTags } from './tag.mjs';
 import { buildCommand } from './build.mjs';
 
 // Should be run from the consumer app directory — uses process.cwd() to locate it.
@@ -131,6 +133,9 @@ async function deployCommand(opts = {}) {
     finally {
         await releaseLockBestEffort(appName, token);
     }
+    // Tags are a post-deploy concern: the S3 upload has already succeeded, so a
+    // tag failure never fails the deploy (handled inside).
+    await handleDeployTags(appName);
     // The host MF parses the app name from the URL and prepends `mf-` itself
     // before looking it up in the manifest. So the user-facing URL must use
     // the consumer's de-scoped package name (no `mf-` prefix, no `@scope/`).
@@ -157,6 +162,27 @@ async function registerApp(appName, token, version, entry, visibility, gitRemote
         throw new Error(`App registration failed (${res.status}): ${text.slice(0, 1024)}`);
     }
 }
+const TAG_NUDGE = "run 'z2h-cli tag' to categorize this app (app type & team)";
+async function handleDeployTags(appSlug) {
+    try {
+        const interactive = getOutputMode() === 'human' && Boolean(process.stdin.isTTY);
+        if (!interactive) {
+            info(TAG_NUDGE);
+            return;
+        }
+        const current = await fetchAppTags(appSlug);
+        if (current.length > 0) {
+            return; // already tagged — don't prompt on every redeploy
+        }
+        const catalog = await fetchTagCatalog();
+        const selected = await promptForTags(appSlug, catalog, current);
+        const tags = await setAppTags(appSlug, selected);
+        info(tags.length > 0 ? `tags set: ${tags.map(t => t.name).join(', ')}` : TAG_NUDGE);
+    }
+    catch (err) {
+        warn(`could not update tags: ${err.message}`);
+    }
+}
 // Acquire the per-app deploy lock. Throws a friendly error on 409 (someone else is deploying)
 // so the deploy stops and the caller can retry; the backend TTL backstops a crashed holder.
 async function acquireDeployLock(appName, token) {

package/dist/esm/commands/tag.d.ts

@@ -0,0 +1,14 @@
+import { type AppTag, type CatalogEntry } from '../util/tags';
+export interface TagOptions {
+    /** Repeatable `--tag` — sets the full tag set non-interactively. */
+    tag?: string[];
+    json?: boolean;
+}
+/**
+ * Closed-list prompt: one numbered pick per dimension (app type, team). Enter
+ * keeps the current value for that dimension (or skips it if unset). Returns
+ * the full replacement set of tag names.
+ */
+export declare function promptForTags(appSlug: string, catalog: CatalogEntry[], current: AppTag[]): Promise<string[]>;
+export declare function tagCommand(appArg: string | undefined, opts: TagOptions): Promise<void>;
+//# sourceMappingURL=tag.d.ts.map

package/dist/esm/commands/tag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.d.ts","sourceRoot":"","sources":["../../../src/commands/tag.ts"],"names":[],"mappings":"AAMA,OAAO,EAML,KAAK,MAAM,EACX,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAgCD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0ClH;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC5F"}

package/dist/esm/commands/tag.mjs

@@ -0,0 +1,107 @@
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { readJson } from 'fs-extra';
+import { resolveConsumerPaths } from '../shadow/paths.mjs';
+import { mfAppName } from '../util/app-name.mjs';
+import { info, setOutputMode, output } from '../util/logger.mjs';
+import { TAG_TYPES, TAG_TYPE_LABELS, setAppTags, fetchTagCatalog, fetchAppTags } from '../util/tags.mjs';
+
+/** Render an app's tags as `name (Type), ...` — or `(none)`. */
+function formatTags(tags) {
+    return tags.map(t => `${t.name} (${TAG_TYPE_LABELS[t.type]})`).join(', ') || '(none)';
+}
+/**
+ * Resolve the target app name: an explicit arg wins, else the consumer
+ * package.json `name` in the cwd. Normalized to the `mf-` bundle name the
+ * broker stores (via `mfAppName`), so the server finds the app.
+ */
+async function resolveAppSlug(appArg) {
+    if (appArg) {
+        return mfAppName(appArg);
+    }
+    const paths = resolveConsumerPaths(process.cwd());
+    let pkg;
+    try {
+        pkg = (await readJson(paths.consumerPkg));
+    }
+    catch {
+        throw new Error('Could not read a consumer package.json in the current directory. ' +
+            'Either cd into your app folder or pass an app name: z2h-cli tag <app-name>.');
+    }
+    if (!pkg.name) {
+        throw new Error('Consumer package.json must have a "name" field (or pass an app name argument).');
+    }
+    return mfAppName(pkg.name);
+}
+/**
+ * Closed-list prompt: one numbered pick per dimension (app type, team). Enter
+ * keeps the current value for that dimension (or skips it if unset). Returns
+ * the full replacement set of tag names.
+ */
+async function promptForTags(appSlug, catalog, current) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    const selected = [];
+    try {
+        info(`Tagging "${appSlug}".`);
+        for (const type of TAG_TYPES) {
+            const options = catalog.filter(t => t.type === type);
+            if (options.length === 0) {
+                continue;
+            }
+            const currentName = current.find(c => c.type === type)?.name;
+            const label = TAG_TYPE_LABELS[type];
+            info(`\n${label}${currentName ? ` (current: ${currentName})` : ''}:`);
+            options.forEach((o, i) => info(`  ${i + 1}) ${o.name}`));
+            const raw = await rl.question(`Pick a ${label} (number or name; Enter to ${currentName ? 'keep current' : 'skip'}):\n> `);
+            const trimmed = raw.trim();
+            if (!trimmed) {
+                if (currentName) {
+                    selected.push(currentName);
+                }
+                continue;
+            }
+            // Accept either the 1-based number or the tag name (case-insensitive).
+            const idx = Number(trimmed) - 1;
+            const byNumber = Number.isInteger(idx) && idx >= 0 && idx < options.length ? options[idx] : undefined;
+            const chosen = byNumber ?? options.find(o => o.name.toLowerCase() === trimmed.toLowerCase());
+            if (chosen) {
+                selected.push(chosen.name);
+            }
+            else {
+                info(`Invalid choice "${trimmed}" — ${currentName ? 'keeping current' : 'skipping'} ${label}.`);
+                if (currentName) {
+                    selected.push(currentName);
+                }
+            }
+        }
+        return selected;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function tagCommand(appArg, opts) {
+    if (opts.json) {
+        setOutputMode('json');
+    }
+    const appSlug = await resolveAppSlug(appArg);
+    // Non-interactive write: `--tag` flags set the full set directly.
+    if (opts.tag && opts.tag.length > 0) {
+        const tags = await setAppTags(appSlug, opts.tag);
+        output(`[z2h-cli] tags for "${appSlug}": ${formatTags(tags)}`, { ok: true, appName: appSlug, tags });
+        return;
+    }
+    const [catalog, current] = await Promise.all([fetchTagCatalog(), fetchAppTags(appSlug)]);
+    // Read-only listing: agents (`--json`) and any non-TTY caller get the catalog
+    // + current tags without a prompt — then they set tags via `--tag`. This also
+    // avoids hanging on `readline` when no human is attached to stdin.
+    if (opts.json || !process.stdin.isTTY) {
+        output(`[z2h-cli] "${appSlug}"\n  catalog: ${catalog.map(t => `${t.name} (${TAG_TYPE_LABELS[t.type]})`).join(', ') || '(none)'}\n  current: ${formatTags(current)}`, { ok: true, appName: appSlug, catalog, current });
+        return;
+    }
+    const selected = await promptForTags(appSlug, catalog, current);
+    const tags = await setAppTags(appSlug, selected);
+    output(`[z2h-cli] tags for "${appSlug}": ${formatTags(tags)}`, { ok: true, appName: appSlug, tags });
+}
+
+export { promptForTags, tagCommand };

package/dist/esm/index.mjs

@@ -13,6 +13,7 @@ import { createWorkspaceCommand } from './commands/create-workspace.mjs';
 import { createCommand } from './commands/create.mjs';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
 import { migrateCommand } from './commands/migrate.mjs';
+import { tagCommand } from './commands/tag.mjs';
 import { editCommand } from './commands/edit.mjs';
 import { fail, errorLog, getOutputMode } from './util/logger.mjs';
 import { trackDuration } from './util/tracker.mjs';
@@ -37,6 +38,10 @@ function stripConflictingEnvVars() {
         delete process.env[name];
     }
 }
+/** commander collector for a repeatable `--tag` option. */
+function collectTag(value, previous) {
+    return previous.concat(value);
+}
 async function main() {
     stripConflictingEnvVars();
     const program = new Command();
@@ -109,6 +114,21 @@ async function main() {
             await fail(`deploy failed: ${err.message}`, { command: 'deploy' }, 2);
         }
     });
+    program
+        .command('tag [app-name]')
+        .description("Set an app's category tags — app type & team (interactive unless --tag or --json is given)")
+        .option('--tag <tag>', 'set a tag (repeatable); full-replaces the tag set non-interactively', collectTag, [])
+        .option('--json', "read-only: print the popular catalog + the app's current tags as JSON (no prompt)")
+        .action(async (appName, opts) => {
+        try {
+            await trackDuration('z2h_app_tag_success', () => tagCommand(appName, opts), {
+                app_name: appName ?? getCwdAppName(),
+            });
+        }
+        catch (err) {
+            await fail(`tag failed: ${err.message}`, { command: 'tag' }, 1);
+        }
+    });
     program
         .command('create-workspace')
         .description(`Bootstrap the ${getWorkspaceHome()}/ yarn workspace (one-time setup)`)

package/dist/esm/util/tags.d.ts

@@ -0,0 +1,24 @@
+/** The dimension a tag categorizes an app by. */
+export type TagType = 'app_type' | 'team';
+/** The tag dimensions, in prompt order. */
+export declare const TAG_TYPES: TagType[];
+/** Human labels for each dimension (CLI prompts / output). */
+export declare const TAG_TYPE_LABELS: Record<TagType, string>;
+/** A catalog entry: one selectable tag with its dimension + global usage count. */
+export interface CatalogEntry {
+    name: string;
+    type: TagType;
+    count: number;
+}
+/** A tag assigned to an app — name + dimension. */
+export interface AppTag {
+    name: string;
+    type: TagType;
+}
+/** The full closed tag catalog (app types + teams), with usage counts. */
+export declare function fetchTagCatalog(): Promise<CatalogEntry[]>;
+/** Tags currently assigned to an app (bare slug). */
+export declare function fetchAppTags(appSlug: string): Promise<AppTag[]>;
+/** Full-replace an app's tag set; returns the resulting tags. */
+export declare function setAppTags(appSlug: string, tags: string[]): Promise<AppTag[]>;
+//# sourceMappingURL=tags.d.ts.map

package/dist/esm/util/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../../src/util/tags.ts"],"names":[],"mappings":"AAGA,iDAAiD;AACjD,MAAM,MAAM,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;AAE1C,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,OAAO,EAAyB,CAAC;AAEzD,8DAA8D;AAC9D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAGnD,CAAC;AAEF,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAgDD,0EAA0E;AAC1E,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAI/D;AAED,qDAAqD;AACrD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIrE;AAED,iEAAiE;AACjE,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAInF"}

package/dist/esm/util/tags.mjs

@@ -0,0 +1,63 @@
+import { brokerBaseUrl, routingHeaders } from '../constants.mjs';
+import { readZthAuth } from './auth/auth-store.mjs';
+
+/** The tag dimensions, in prompt order. */
+const TAG_TYPES = ['app_type', 'team'];
+/** Human labels for each dimension (CLI prompts / output). */
+const TAG_TYPE_LABELS = {
+    app_type: 'App type',
+    team: 'Team',
+};
+/**
+ * Authenticated request to the bigbrain-zth tag endpoints. Mirrors the Bearer
+ * pattern used by the STS broker / lock-release calls, with network-error
+ * wrapping, auth-failure guidance, and response-body inclusion on failure.
+ */
+async function tagFetch(method, path, body) {
+    const { token } = await readZthAuth();
+    let res;
+    try {
+        res = await fetch(`${brokerBaseUrl()}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...routingHeaders(),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Z2H tag request failed: ${message}`);
+    }
+    if (res.status === 401 || res.status === 403) {
+        throw new Error(`Z2H tag request rejected by the broker (${res.status}). Refresh your token by running 'z2h-cli generate-z2h-token'.`);
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Z2H tag request returned ${res.status}: ${text.slice(0, 1024)}`);
+    }
+    return res;
+}
+/** The full closed tag catalog (app types + teams), with usage counts. */
+async function fetchTagCatalog() {
+    const res = await tagFetch('GET', '/z2h-cli/tags');
+    const data = (await res.json());
+    return data.tags ?? [];
+}
+/** Tags currently assigned to an app (bare slug). */
+async function fetchAppTags(appSlug) {
+    const res = await tagFetch('GET', `/z2h-cli/tags/${encodeURIComponent(appSlug)}`);
+    const data = (await res.json());
+    return data.tags ?? [];
+}
+/** Full-replace an app's tag set; returns the resulting tags. */
+async function setAppTags(appSlug, tags) {
+    const res = await tagFetch('PUT', `/z2h-cli/tags/${encodeURIComponent(appSlug)}`, { tags });
+    const data = (await res.json());
+    return data.tags ?? [];
+}
+
+export { TAG_TYPES, TAG_TYPE_LABELS, fetchAppTags, fetchTagCatalog, setAppTags };

package/dist/index.js

@@ -13,6 +13,7 @@ const commands_createWorkspace = require('./commands/create-workspace.js');
 const commands_create = require('./commands/create.js');
 const commands_generateZ2hToken = require('./commands/generate-z2h-token.js');
 const commands_migrate = require('./commands/migrate.js');
+const commands_tag = require('./commands/tag.js');
 const commands_edit = require('./commands/edit.js');
 const util_logger = require('./util/logger.js');
 const util_tracker = require('./util/tracker.js');
@@ -43,6 +44,10 @@ function stripConflictingEnvVars() {
         delete process.env[name];
     }
 }
+/** commander collector for a repeatable `--tag` option. */
+function collectTag(value, previous) {
+    return previous.concat(value);
+}
 async function main() {
     stripConflictingEnvVars();
     const program = new commander.Command();
@@ -115,6 +120,21 @@ async function main() {
             await util_logger.fail(`deploy failed: ${err.message}`, { command: 'deploy' }, 2);
         }
     });
+    program
+        .command('tag [app-name]')
+        .description("Set an app's category tags — app type & team (interactive unless --tag or --json is given)")
+        .option('--tag <tag>', 'set a tag (repeatable); full-replaces the tag set non-interactively', collectTag, [])
+        .option('--json', "read-only: print the popular catalog + the app's current tags as JSON (no prompt)")
+        .action(async (appName, opts) => {
+        try {
+            await util_tracker.trackDuration('z2h_app_tag_success', () => commands_tag.tagCommand(appName, opts), {
+                app_name: appName ?? util_appName.getCwdAppName(),
+            });
+        }
+        catch (err) {
+            await util_logger.fail(`tag failed: ${err.message}`, { command: 'tag' }, 1);
+        }
+    });
     program
         .command('create-workspace')
         .description(`Bootstrap the ${util_workspace.getWorkspaceHome()}/ yarn workspace (one-time setup)`)

package/dist/util/tags.d.ts

@@ -0,0 +1,24 @@
+/** The dimension a tag categorizes an app by. */
+export type TagType = 'app_type' | 'team';
+/** The tag dimensions, in prompt order. */
+export declare const TAG_TYPES: TagType[];
+/** Human labels for each dimension (CLI prompts / output). */
+export declare const TAG_TYPE_LABELS: Record<TagType, string>;
+/** A catalog entry: one selectable tag with its dimension + global usage count. */
+export interface CatalogEntry {
+    name: string;
+    type: TagType;
+    count: number;
+}
+/** A tag assigned to an app — name + dimension. */
+export interface AppTag {
+    name: string;
+    type: TagType;
+}
+/** The full closed tag catalog (app types + teams), with usage counts. */
+export declare function fetchTagCatalog(): Promise<CatalogEntry[]>;
+/** Tags currently assigned to an app (bare slug). */
+export declare function fetchAppTags(appSlug: string): Promise<AppTag[]>;
+/** Full-replace an app's tag set; returns the resulting tags. */
+export declare function setAppTags(appSlug: string, tags: string[]): Promise<AppTag[]>;
+//# sourceMappingURL=tags.d.ts.map

package/dist/util/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../src/util/tags.ts"],"names":[],"mappings":"AAGA,iDAAiD;AACjD,MAAM,MAAM,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;AAE1C,2CAA2C;AAC3C,eAAO,MAAM,SAAS,EAAE,OAAO,EAAyB,CAAC;AAEzD,8DAA8D;AAC9D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAGnD,CAAC;AAEF,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACf;AAgDD,0EAA0E;AAC1E,wBAAsB,eAAe,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAI/D;AAED,qDAAqD;AACrD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAIrE;AAED,iEAAiE;AACjE,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAInF"}

package/dist/util/tags.js

@@ -0,0 +1,69 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const constants = require('../constants.js');
+const util_auth_authStore = require('./auth/auth-store.js');
+
+/** The tag dimensions, in prompt order. */
+const TAG_TYPES = ['app_type', 'team'];
+/** Human labels for each dimension (CLI prompts / output). */
+const TAG_TYPE_LABELS = {
+    app_type: 'App type',
+    team: 'Team',
+};
+/**
+ * Authenticated request to the bigbrain-zth tag endpoints. Mirrors the Bearer
+ * pattern used by the STS broker / lock-release calls, with network-error
+ * wrapping, auth-failure guidance, and response-body inclusion on failure.
+ */
+async function tagFetch(method, path, body) {
+    const { token } = await util_auth_authStore.readZthAuth();
+    let res;
+    try {
+        res = await fetch(`${constants.brokerBaseUrl()}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+                ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...constants.routingHeaders(),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Z2H tag request failed: ${message}`);
+    }
+    if (res.status === 401 || res.status === 403) {
+        throw new Error(`Z2H tag request rejected by the broker (${res.status}). Refresh your token by running 'z2h-cli generate-z2h-token'.`);
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Z2H tag request returned ${res.status}: ${text.slice(0, 1024)}`);
+    }
+    return res;
+}
+/** The full closed tag catalog (app types + teams), with usage counts. */
+async function fetchTagCatalog() {
+    const res = await tagFetch('GET', '/z2h-cli/tags');
+    const data = (await res.json());
+    return data.tags ?? [];
+}
+/** Tags currently assigned to an app (bare slug). */
+async function fetchAppTags(appSlug) {
+    const res = await tagFetch('GET', `/z2h-cli/tags/${encodeURIComponent(appSlug)}`);
+    const data = (await res.json());
+    return data.tags ?? [];
+}
+/** Full-replace an app's tag set; returns the resulting tags. */
+async function setAppTags(appSlug, tags) {
+    const res = await tagFetch('PUT', `/z2h-cli/tags/${encodeURIComponent(appSlug)}`, { tags });
+    const data = (await res.json());
+    return data.tags ?? [];
+}
+
+exports.TAG_TYPES = TAG_TYPES;
+exports.TAG_TYPE_LABELS = TAG_TYPE_LABELS;
+exports.fetchAppTags = fetchAppTags;
+exports.fetchTagCatalog = fetchTagCatalog;
+exports.setAppTags = setAppTags;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/commands/deploy.ts

@@ -2,8 +2,9 @@ import path from 'node:path';
 import os from 'node:os';
 import { createInterface } from 'node:readline';
 import { pathExists, readJson } from 'fs-extra';
-import { info, output, setOutputMode, warn } from '../util/logger';
+import { info, warn, output, setOutputMode, getOutputMode } from '../util/logger';
 import { resolveConsumerPaths } from '../shadow/paths';
+import { fetchAppTags, fetchTagCatalog, setAppTags } from '../util/tags';
 import { type AssetManifestFile, type ManifestEntry } from '../util/manifest';
 import { uploadDir } from '../util/s3/upload';
 import { BUCKET_WRITE_NAME, BUCKET_READ_DNS_URL, brokerBaseUrl, routingHeaders } from '../constants';
@@ -15,6 +16,7 @@ import { getRemoteUrl, guardCleanTree, pullAndResolve, pushToRemote, initRepo }
 import { resolveGitEnv } from '../util/git/git-env';
 import { type RemoteType, validateRemoteOptions, resolveRemoteUrl } from '../util/git/remote-options';
 import { setupS3Client } from '../util/s3/client';
+import { promptForTags } from './tag';
 import { buildCommand } from './build';
 
 export interface DeployOptions {
@@ -158,6 +160,10 @@ export async function deployCommand(opts: DeployOptions = {}): Promise<void> {
     await releaseLockBestEffort(appName, token);
   }
 
+  // Tags are a post-deploy concern: the S3 upload has already succeeded, so a
+  // tag failure never fails the deploy (handled inside).
+  await handleDeployTags(appName);
+
   // The host MF parses the app name from the URL and prepends `mf-` itself
   // before looking it up in the manifest. So the user-facing URL must use
   // the consumer's de-scoped package name (no `mf-` prefix, no `@scope/`).
@@ -193,6 +199,30 @@ async function registerApp(
   }
 }
 
+const TAG_NUDGE = "run 'z2h-cli tag' to categorize this app (app type & team)";
+
+async function handleDeployTags(appSlug: string): Promise<void> {
+  try {
+    const interactive = getOutputMode() === 'human' && Boolean(process.stdin.isTTY);
+    if (!interactive) {
+      info(TAG_NUDGE);
+      return;
+    }
+
+    const current = await fetchAppTags(appSlug);
+    if (current.length > 0) {
+      return; // already tagged — don't prompt on every redeploy
+    }
+
+    const catalog = await fetchTagCatalog();
+    const selected = await promptForTags(appSlug, catalog, current);
+    const tags = await setAppTags(appSlug, selected);
+    info(tags.length > 0 ? `tags set: ${tags.map(t => t.name).join(', ')}` : TAG_NUDGE);
+  } catch (err) {
+    warn(`could not update tags: ${(err as Error).message}`);
+  }
+}
+
 // Acquire the per-app deploy lock. Throws a friendly error on 409 (someone else is deploying)
 // so the deploy stops and the caller can retry; the backend TTL backstops a crashed holder.
 async function acquireDeployLock(appName: string, token: string): Promise<void> {

package/src/commands/tag.ts

@@ -0,0 +1,134 @@
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { readJson } from 'fs-extra';
+import { resolveConsumerPaths } from '../shadow/paths';
+import { mfAppName } from '../util/app-name';
+import { info, output, setOutputMode } from '../util/logger';
+import {
+  fetchAppTags,
+  fetchTagCatalog,
+  setAppTags,
+  TAG_TYPES,
+  TAG_TYPE_LABELS,
+  type AppTag,
+  type CatalogEntry,
+} from '../util/tags';
+
+export interface TagOptions {
+  /** Repeatable `--tag` — sets the full tag set non-interactively. */
+  tag?: string[];
+  json?: boolean;
+}
+
+/** Render an app's tags as `name (Type), ...` — or `(none)`. */
+function formatTags(tags: AppTag[]): string {
+  return tags.map(t => `${t.name} (${TAG_TYPE_LABELS[t.type]})`).join(', ') || '(none)';
+}
+
+/**
+ * Resolve the target app name: an explicit arg wins, else the consumer
+ * package.json `name` in the cwd. Normalized to the `mf-` bundle name the
+ * broker stores (via `mfAppName`), so the server finds the app.
+ */
+async function resolveAppSlug(appArg?: string): Promise<string> {
+  if (appArg) {
+    return mfAppName(appArg);
+  }
+  const paths = resolveConsumerPaths(process.cwd());
+  let pkg: { name?: string };
+  try {
+    pkg = (await readJson(paths.consumerPkg)) as { name?: string };
+  } catch {
+    throw new Error(
+      'Could not read a consumer package.json in the current directory. ' +
+        'Either cd into your app folder or pass an app name: z2h-cli tag <app-name>.'
+    );
+  }
+  if (!pkg.name) {
+    throw new Error('Consumer package.json must have a "name" field (or pass an app name argument).');
+  }
+  return mfAppName(pkg.name);
+}
+
+/**
+ * Closed-list prompt: one numbered pick per dimension (app type, team). Enter
+ * keeps the current value for that dimension (or skips it if unset). Returns
+ * the full replacement set of tag names.
+ */
+export async function promptForTags(appSlug: string, catalog: CatalogEntry[], current: AppTag[]): Promise<string[]> {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  const selected: string[] = [];
+  try {
+    info(`Tagging "${appSlug}".`);
+    for (const type of TAG_TYPES) {
+      const options = catalog.filter(t => t.type === type);
+      if (options.length === 0) {
+        continue;
+      }
+      const currentName = current.find(c => c.type === type)?.name;
+      const label = TAG_TYPE_LABELS[type];
+      info(`\n${label}${currentName ? ` (current: ${currentName})` : ''}:`);
+      options.forEach((o, i) => info(`  ${i + 1}) ${o.name}`));
+
+      const raw = await rl.question(
+        `Pick a ${label} (number or name; Enter to ${currentName ? 'keep current' : 'skip'}):\n> `
+      );
+      const trimmed = raw.trim();
+      if (!trimmed) {
+        if (currentName) {
+          selected.push(currentName);
+        }
+        continue;
+      }
+      // Accept either the 1-based number or the tag name (case-insensitive).
+      const idx = Number(trimmed) - 1;
+      const byNumber = Number.isInteger(idx) && idx >= 0 && idx < options.length ? options[idx] : undefined;
+      const chosen = byNumber ?? options.find(o => o.name.toLowerCase() === trimmed.toLowerCase());
+      if (chosen) {
+        selected.push(chosen.name);
+      } else {
+        info(`Invalid choice "${trimmed}" — ${currentName ? 'keeping current' : 'skipping'} ${label}.`);
+        if (currentName) {
+          selected.push(currentName);
+        }
+      }
+    }
+    return selected;
+  } finally {
+    rl.close();
+  }
+}
+
+export async function tagCommand(appArg: string | undefined, opts: TagOptions): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  const appSlug = await resolveAppSlug(appArg);
+
+  // Non-interactive write: `--tag` flags set the full set directly.
+  if (opts.tag && opts.tag.length > 0) {
+    const tags = await setAppTags(appSlug, opts.tag);
+    output(`[z2h-cli] tags for "${appSlug}": ${formatTags(tags)}`, { ok: true, appName: appSlug, tags });
+    return;
+  }
+
+  const [catalog, current] = await Promise.all([fetchTagCatalog(), fetchAppTags(appSlug)]);
+
+  // Read-only listing: agents (`--json`) and any non-TTY caller get the catalog
+  // + current tags without a prompt — then they set tags via `--tag`. This also
+  // avoids hanging on `readline` when no human is attached to stdin.
+  if (opts.json || !process.stdin.isTTY) {
+    output(
+      `[z2h-cli] "${appSlug}"\n  catalog: ${
+        catalog.map(t => `${t.name} (${TAG_TYPE_LABELS[t.type]})`).join(', ') || '(none)'
+      }\n  current: ${formatTags(current)}`,
+      { ok: true, appName: appSlug, catalog, current }
+    );
+    return;
+  }
+
+  const selected = await promptForTags(appSlug, catalog, current);
+  const tags = await setAppTags(appSlug, selected);
+  output(`[z2h-cli] tags for "${appSlug}": ${formatTags(tags)}`, { ok: true, appName: appSlug, tags });
+}

package/src/index.ts

@@ -13,6 +13,7 @@ import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand, CreateOptions } from './commands/create';
 import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
+import { tagCommand } from './commands/tag';
 import { editCommand } from './commands/edit';
 import { errorLog, fail, getOutputMode } from './util/logger';
 import { trackDuration } from './util/tracker';
@@ -41,6 +42,11 @@ function stripConflictingEnvVars(): void {
   }
 }
 
+/** commander collector for a repeatable `--tag` option. */
+function collectTag(value: string, previous: string[]): string[] {
+  return previous.concat(value);
+}
+
 async function main(): Promise<void> {
   stripConflictingEnvVars();
 
@@ -127,6 +133,21 @@ async function main(): Promise<void> {
       }
     });
 
+  program
+    .command('tag [app-name]')
+    .description("Set an app's category tags — app type & team (interactive unless --tag or --json is given)")
+    .option('--tag <tag>', 'set a tag (repeatable); full-replaces the tag set non-interactively', collectTag, [])
+    .option('--json', "read-only: print the popular catalog + the app's current tags as JSON (no prompt)")
+    .action(async (appName: string | undefined, opts: { tag?: string[]; json?: boolean }) => {
+      try {
+        await trackDuration('z2h_app_tag_success', () => tagCommand(appName, opts), {
+          app_name: appName ?? getCwdAppName(),
+        });
+      } catch (err) {
+        await fail(`tag failed: ${(err as Error).message}`, { command: 'tag' }, 1);
+      }
+    });
+
   program
     .command('create-workspace')
     .description(`Bootstrap the ${getWorkspaceHome()}/ yarn workspace (one-time setup)`)

package/src/templates/app/html-index.tsx.tmpl

@@ -1,18 +1,30 @@
-// HTML-embed entrypoint. Renders src/page.html in an iframe, with the file
-// imported via Vite's `?url` suffix so Vite's dev server hosts it at
-// /src/page.html (and copies it to /assets/ at build time). Same-origin
-// (the URL lives under whatever host is rendering the app), so the page's
-// fetch() calls carry bigbrain.me auth cookies normally.
-//
-// The iframe gives the page its own document — scripts execute natively,
-// CSS/JS is fully isolated from the host React app, no script reinjection
-// logic needed.
-import React from 'react';
+import React, { useRef, useEffect } from 'react';
+import { getBigBrainAPI } from '@mondaydotcomorg/trident-runtime';
 import pageUrl from './page.html?url';
 
+const BACKEND_SUBDOMAIN = 'bigbrain-zth';
+
+function getBackendBaseUrl(): string | null {
+  const base = getBigBrainAPI()?.contextService?.bigbrainBaseUrl;
+  return base ? base.replace('//', `//${BACKEND_SUBDOMAIN}.`) : null;
+}
+
 export default function __APP_COMPONENT__() {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  useEffect(() => {
+    const handleMessage = (event: MessageEvent) => {
+      if (!iframeRef.current || event.source !== iframeRef.current.contentWindow) return;
+      if (event.data?.type !== 'z2h:getConfig') return;
+      const baseUrl = getBackendBaseUrl();
+      if (!baseUrl) return;
+      (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={{ width: '100vw', height: '100vh', border: 'none', display: 'block' }}

package/src/util/tags.ts

@@ -0,0 +1,94 @@
+import { brokerBaseUrl, routingHeaders } from '../constants';
+import { readZthAuth } from './auth/auth-store';
+
+/** The dimension a tag categorizes an app by. */
+export type TagType = 'app_type' | 'team';
+
+/** The tag dimensions, in prompt order. */
+export const TAG_TYPES: TagType[] = ['app_type', 'team'];
+
+/** Human labels for each dimension (CLI prompts / output). */
+export const TAG_TYPE_LABELS: Record<TagType, string> = {
+  app_type: 'App type',
+  team: 'Team',
+};
+
+/** A catalog entry: one selectable tag with its dimension + global usage count. */
+export interface CatalogEntry {
+  name: string;
+  type: TagType;
+  count: number;
+}
+
+/** A tag assigned to an app — name + dimension. */
+export interface AppTag {
+  name: string;
+  type: TagType;
+}
+
+interface CatalogResponse {
+  tags?: CatalogEntry[];
+}
+
+interface AppTagsResponse {
+  tags?: AppTag[];
+}
+
+/**
+ * Authenticated request to the bigbrain-zth tag endpoints. Mirrors the Bearer
+ * pattern used by the STS broker / lock-release calls, with network-error
+ * wrapping, auth-failure guidance, and response-body inclusion on failure.
+ */
+async function tagFetch(method: 'GET' | 'PUT', path: string, body?: unknown): Promise<Response> {
+  const { token } = await readZthAuth();
+
+  let res: Response;
+  try {
+    res = await fetch(`${brokerBaseUrl()}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        ...routingHeaders(),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Z2H tag request failed: ${message}`);
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    throw new Error(
+      `Z2H tag request rejected by the broker (${res.status}). Refresh your token by running 'z2h-cli generate-z2h-token'.`
+    );
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Z2H tag request returned ${res.status}: ${text.slice(0, 1024)}`);
+  }
+
+  return res;
+}
+
+/** The full closed tag catalog (app types + teams), with usage counts. */
+export async function fetchTagCatalog(): Promise<CatalogEntry[]> {
+  const res = await tagFetch('GET', '/z2h-cli/tags');
+  const data = (await res.json()) as CatalogResponse;
+  return data.tags ?? [];
+}
+
+/** Tags currently assigned to an app (bare slug). */
+export async function fetchAppTags(appSlug: string): Promise<AppTag[]> {
+  const res = await tagFetch('GET', `/z2h-cli/tags/${encodeURIComponent(appSlug)}`);
+  const data = (await res.json()) as AppTagsResponse;
+  return data.tags ?? [];
+}
+
+/** Full-replace an app's tag set; returns the resulting tags. */
+export async function setAppTags(appSlug: string, tags: string[]): Promise<AppTag[]> {
+  const res = await tagFetch('PUT', `/z2h-cli/tags/${encodeURIComponent(appSlug)}`, { tags });
+  const data = (await res.json()) as AppTagsResponse;
+  return data.tags ?? [];
+}