primitive-admin 1.0.53 → 1.0.54

package/dist/src/commands/sync.js

@@ -1,16 +1,21 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, rmdirSync, statSync } from "fs";
 import { join, basename } from "path";
 import { createHash } from "crypto";
-import * as TOML from "@iarna/toml";
 import { lookup as mimeLookup } from "mime-types";
 import { ApiClient, ApiError, ConflictError, SchemaRequiredError, OperationRefError, SchemaBreaksOpsError, SchemaHasUncheckableOpsError, TomlParseError, OpsExistError, } from "../lib/api-client.js";
 import { buildDatabaseTypeTomlData, detectExistingOperationForms, normalizeOperationFromToml, normalizeSubscriptionFromToml, SubscriptionAccessKeyConflictError, } from "../lib/toml-database-config.js";
+import { canEmitNative } from "../lib/toml-native-form.js";
+import { parseMetadataCategoryToml, validateMetadataCategoryConfig, serializeMetadataCategoryConfig, parseDeclaredAccessManifestToml, validateDeclaredAccessManifest, serializeDeclaredAccessManifest, } from "../lib/toml-metadata-config.js";
 import { validateOperations, formatIssue, } from "../lib/toml-params-validator.js";
 import { getServerUrl, resolveAppId } from "../lib/config.js";
 import { resolveSyncDir, resolveSnapshotsRoot, isAutoResolvedSyncDir, checkLegacySyncMigration, } from "../lib/sync-paths.js";
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
+import { parseConfigToml, stringifyConfigToml } from "../lib/config-toml.js";
+import { applyWorkflowBody } from "../lib/workflow-apply.js";
+import { buildWorkflowPayloadFromToml } from "../lib/workflow-payload.js";
+import { detectLayout, migrateLegacyToV2 } from "../lib/block-layout.js";
 import { success, error, printApiError, info, warn, keyValue, json, divider, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
@@ -132,30 +137,43 @@ export function shouldPushExpandedFile(parsed, storedHash) {
     return computeExpandedContentHash(parsed) !== storedHash;
 }
 /**
- * Model defaults for the *exact five* workflow-level fields that
- * `serializeWorkflow` emits unconditionally (`sync.ts` workflow serializer:
- * `perUserMaxRunning`, `perUserMaxQueued`, `dequeueOrder`,
- * `requiresClientApply`, `syncCallable`). These mirror `models.yaml`
- * (`WorkflowDefinition`): `perUserMaxRunning=4`, `perUserMaxQueued=100`,
- * `dequeueOrder="fifo"`, `requiresClientApply=true`, `syncCallable=false`.
+ * Model defaults for the workflow-level fields that `serializeWorkflow` emits
+ * with a concrete server default the *local* file may omit (`sync.ts` workflow
+ * serializer): `perUserMaxRunning`, `perUserMaxQueued`, `perAppMaxRunning`,
+ * `perAppMaxQueued`, `queueTtlSeconds`, `dequeueOrder`, `requiresClientApply`,
+ * `syncCallable`. These mirror `models.yaml` (`WorkflowDefinition`):
+ * `perUserMaxRunning=4`, `perUserMaxQueued=100`, `perAppMaxRunning=25`,
+ * `perAppMaxQueued=10000`, `queueTtlSeconds=43200`, `dequeueOrder="fifo"`,
+ * `requiresClientApply=true`, `syncCallable=false`.
+ *
+ * `perAppMax*` / `queueTtlSeconds` were added here for #1177: once the pull
+ * serializer began emitting them (they carry a non-null model default, so a GET
+ * always returns them), an unchanged workflow using the server defaults hashed
+ * unequal to a local TOML that omits them — a false `modified` diff that made
+ * `sync pull` rewrite the file just to inject defaults. Normalizing both sides
+ * to the model default here closes that gap the same way the per-user limits do.
  *
  * This is deliberately NOT a generic models.yaml default importer — the model
- * carries many defaults the serializer never writes (`perAppMax*`,
- * `queueTtlSeconds`, …). Only the serializer-emitted surface matters for a
- * content comparison, because the remote side is hashed via `serializeWorkflow`
- * and therefore only ever contains these five.
+ * carries defaults the serializer never writes. Only the serializer-emitted
+ * surface with a concrete default matters for a content comparison, because the
+ * remote side is hashed via `serializeWorkflow`. Emit-when-set fields whose GET
+ * value is null/empty when unset (`accessRule`, `runAs`, `capabilities`) are
+ * omitted on both sides and so need no normalization here.
  */
 const WORKFLOW_SERIALIZER_DEFAULTS = {
     perUserMaxRunning: 4,
     perUserMaxQueued: 100,
+    perAppMaxRunning: 25,
+    perAppMaxQueued: 10000,
+    queueTtlSeconds: 43200,
     dequeueOrder: "fifo",
     requiresClientApply: true,
     syncCallable: false,
 };
 /**
- * Normalize a parsed workflow TOML object so that any of the five
- * serializer-emitted fields the *local* file omits are filled in with the
- * model default. Used by `diff` so a hand-authored workflow that omits e.g.
+ * Normalize a parsed workflow TOML object so that any of the
+ * serializer-emitted default fields the *local* file omits are filled in with
+ * the model default. Used by `diff` so a hand-authored workflow that omits e.g.
  * `perUserMaxRunning` compares equal to a server that defaulted it to 4
  * (the #1175 false-positive guard) — while a server value that was
  * *explicitly set* to a non-default (e.g. 8) still shows as Modified.
@@ -173,6 +191,25 @@ export function normalizeWorkflowTomlDefaults(parsed) {
             workflow[field] = defaultValue;
         }
     }
+    // Schema-form canonicalization (issue #1446): a legacy file carries
+    // `inputSchema` / `outputSchema` as a JSON string, while the native form (and
+    // the remote serialization) carries a parsed object. Parse the string form to
+    // its object here so the two forms hash equal — `sync diff` stays
+    // form-independent and an unchanged schema never shows a false `modified`
+    // during the transition. This runs only on the diff-hash path
+    // (`hashWorkflowTomlForDiff`); the stored-state hash path is untouched, so
+    // there is no forced one-time re-push after upgrade.
+    for (const field of ["inputSchema", "outputSchema"]) {
+        if (typeof workflow[field] === "string") {
+            try {
+                workflow[field] = JSON.parse(workflow[field]);
+            }
+            catch {
+                // Not valid JSON — leave the raw string so a genuinely malformed value
+                // still compares by its literal content.
+            }
+        }
+    }
     return { ...parsed, workflow };
 }
 /**
@@ -191,14 +228,97 @@ export function hashWorkflowTomlForDiff(parsed) {
  * `getWorkflow` + active `getWorkflowConfig`), mirroring exactly what a fresh
  * `sync pull` would write to disk. Serializes via `serializeWorkflow`, parses
  * the resulting TOML (remote serialized TOML never carries `include`s, so a
- * plain `TOML.parse` is sufficient — no fragment path needed), then hashes
+ * plain `parseConfigToml` is sufficient — no fragment path needed), then hashes
  * through `hashWorkflowTomlForDiff` so it lines up with the local-file hash.
  */
 export function hashRemoteWorkflowForDiff(workflow, draft, configs) {
     const serialized = serializeWorkflow(workflow, draft, configs || []);
-    const parsed = TOML.parse(serialized);
+    // serializeWorkflow emits via smol-toml (issue #1450) and may contain a
+    // heterogeneous array, so re-parse through the TOML 1.0-compliant facade.
+    const parsed = parseConfigToml(serialized);
     return hashWorkflowTomlForDiff(parsed);
 }
+// Boolean [auth] keys in app.toml that map 1:1 to app-settings fields.
+const AUTH_BOOLEAN_KEYS = [
+    "googleOAuthEnabled",
+    "passkeyEnabled",
+    "magicLinkEnabled",
+    "appleSignInEnabled",
+    "otpEnabled",
+];
+// Every recognized [auth] key. Single source of truth shared by pull
+// serialization, push parsing, and the unrecognized-key warning so the three
+// never drift apart. `appleAudiences` is a string array and `passkeys` is the
+// passkey RP config object; the rest are booleans.
+const RECOGNIZED_AUTH_KEYS = new Set([
+    ...AUTH_BOOLEAN_KEYS,
+    "appleAudiences",
+    "passkeys",
+]);
+/**
+ * Build the [auth] block of app.toml from server settings (pull direction).
+ *
+ * Apple/OTP fields round-trip alongside the legacy google/passkey/magic-link
+ * keys. Two asymmetries are handled deliberately:
+ *  - `appleSignInEnabled` comes back as `boolean | null`; smol-toml throws on
+ *    null, so an unset value (null) is omitted rather than written.
+ *  - `appleAudiences` is omitted when empty. An empty array and an omitted key
+ *    both mean "no audiences" (the server normalizes [] -> null), so omitting
+ *    an empty list on pull is not lossy.
+ */
+export function serializeAuthBlock(settings) {
+    const auth = {
+        googleOAuthEnabled: settings.googleOAuthEnabled,
+        passkeyEnabled: settings.passkeyEnabled,
+        magicLinkEnabled: settings.magicLinkEnabled,
+    };
+    if (typeof settings.appleSignInEnabled === "boolean") {
+        auth.appleSignInEnabled = settings.appleSignInEnabled;
+    }
+    if (Array.isArray(settings.appleAudiences) &&
+        settings.appleAudiences.length > 0) {
+        auth.appleAudiences = settings.appleAudiences;
+    }
+    if (typeof settings.otpEnabled === "boolean") {
+        auth.otpEnabled = settings.otpEnabled;
+    }
+    if (settings.passkeyRpConfig) {
+        auth.passkeys = settings.passkeyRpConfig;
+    }
+    return auth;
+}
+/**
+ * Translate the [auth] block of app.toml into app-settings fields (push
+ * direction).
+ *
+ * Only keys actually present in the TOML are forwarded — an omitted key is left
+ * untouched so it never overwrites server state (e.g. flipping a previously-true
+ * flag to false). An explicit value, including `false`, is forwarded as-is.
+ * `appleAudiences = []` is forwarded too; the server normalizes [] -> null
+ * ("no audiences"). Keys outside RECOGNIZED_AUTH_KEYS produce a warning rather
+ * than a hard error, so a typo or a future key doesn't silently drop.
+ */
+export function parseAppAuthSettings(auth) {
+    const settings = {};
+    const warnings = [];
+    for (const key of AUTH_BOOLEAN_KEYS) {
+        if (key in auth)
+            settings[key] = auth[key];
+    }
+    if ("appleAudiences" in auth) {
+        settings.appleAudiences = auth.appleAudiences;
+    }
+    if ("passkeys" in auth) {
+        settings.passkeyRpConfig = auth.passkeys;
+    }
+    for (const key of Object.keys(auth)) {
+        if (!RECOGNIZED_AUTH_KEYS.has(key)) {
+            warnings.push(`Unrecognized [auth] key "${key}" in app.toml — ignored. ` +
+                `Recognized keys: ${[...RECOGNIZED_AUTH_KEYS].join(", ")}.`);
+        }
+    }
+    return { settings, warnings };
+}
 // TOML serialization helpers
 function serializeAppSettings(settings) {
     const data = {
@@ -208,15 +328,8 @@ function serializeAppSettings(settings) {
             waitlistEnabled: settings.waitlistEnabled,
             baseUrl: settings.baseUrl,
         },
-        auth: {
-            googleOAuthEnabled: settings.googleOAuthEnabled,
-            passkeyEnabled: settings.passkeyEnabled,
-            magicLinkEnabled: settings.magicLinkEnabled,
-        },
+        auth: serializeAuthBlock(settings),
     };
-    if (settings.passkeyRpConfig) {
-        data.auth.passkeys = settings.passkeyRpConfig;
-    }
     if (settings.corsMode === "custom") {
         data.cors = {
             mode: settings.corsMode,
@@ -226,7 +339,313 @@ function serializeAppSettings(settings) {
             maxAge: settings.corsMaxAge,
         };
     }
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
+}
+// --- Config vars (issue #1423) ---------------------------------------------
+// Per-environment non-secret scalars, round-tripped as a single flat
+// `vars.toml` at the sync-dir root (like app.toml). They bind as
+// `{{ vars.KEY }}` in workflow/integration config and `vars.*` in CEL rules.
+/** Key format shared with the vars service (`^[A-Z][A-Z0-9_]{0,63}$`). */
+const VARS_KEY_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** SHA-256 of a var's value — the per-key content hash tracked in sync state. */
+function hashVarValue(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/**
+ * Serialize the app config vars to a flat TOML table (keys sorted for a stable,
+ * diff-friendly file). Values are non-secret plaintext; a header comment says
+ * so loudly. An empty var set yields a comment-only file.
+ */
+function serializeVars(vars) {
+    const data = {};
+    for (const v of [...vars].sort((a, b) => a.key.localeCompare(b.key))) {
+        data[v.key] = String(v.value ?? "");
+    }
+    const header = "# Per-environment non-secret config vars (issue #1423).\n" +
+        "# Bind as {{ vars.KEY }} in workflow/integration config and vars.* in CEL\n" +
+        "# rules. Values are checked into the repo and NOT secret — never put a\n" +
+        "# credential here; use `primitive secrets` for that.\n\n";
+    return header + stringifyConfigToml(data);
+}
+/**
+ * Decide whether `sync pull` should (over)write `vars.toml`, given the outcome
+ * of fetching the app's config vars.
+ *
+ * The distinction that matters (issue #1423 review): a SUCCESSFUL fetch that
+ * returns zero vars is safe to write — the comment-only file is the intended
+ * empty state. A FAILED fetch (transient 401/500/network) must NOT write,
+ * because `serializeVars([])` would clobber a good local `vars.toml` with a
+ * comment-only file while the pull otherwise reports success. On failure we
+ * keep the prior manifest entries so the untouched file and the sync state stay
+ * consistent.
+ *
+ * Pure and side-effect-free (the caller owns the actual `writeFileSync`) so the
+ * clobber guard is unit-testable without a live server.
+ */
+export function planVarsPull(outcome, priorVars) {
+    const varEntities = {};
+    if (!outcome.ok) {
+        // Preserve the prior manifest entries for the (untouched) local file.
+        if (priorVars)
+            Object.assign(varEntities, priorVars);
+        return { write: false, content: null, varEntities };
+    }
+    for (const v of outcome.vars) {
+        varEntities[v.key] = {
+            // The vars API returns `updatedAt` (see toVarResponse); record it as the
+            // baseline server timestamp so `sync push` can detect a concurrent remote
+            // edit. Fall back to `modifiedAt`/now only for older/partial responses.
+            modifiedAt: v.updatedAt || v.modifiedAt || new Date().toISOString(),
+            contentHash: hashVarValue(String(v.value ?? "")),
+        };
+    }
+    return { write: true, content: serializeVars(outcome.vars), varEntities };
+}
+/**
+ * Maximum var value size, in bytes — mirrors the server's `MAX_VALUE_BYTES`
+ * (app-secrets-service.ts). Kept in sync manually because the CLI can't import
+ * the Worker service module.
+ */
+const MAX_VAR_VALUE_BYTES = 2048;
+/**
+ * Maximum number of vars per app — mirrors the server's `MAX_VARS_PER_APP`
+ * (app-config-vars-service.ts). Kept in sync manually because the CLI can't
+ * import the Worker service module.
+ */
+const MAX_VARS_PER_APP = 100;
+/**
+ * Validate a parsed `vars.toml` table against the same key/value constraints
+ * the server enforces (key format, string type, non-empty, size cap) plus the
+ * aggregate per-app var-count cap. Returns a list of human-readable errors
+ * (empty when valid).
+ *
+ * Run in `sync push`'s up-front preflight pass (issue #1423 review) so an
+ * invalid entry — or a file that would exceed the server's `MAX_VARS_PER_APP`
+ * cap — aborts BEFORE any mutation is applied. Validating only individual
+ * entries let a 101-entry file create/update many vars before the server
+ * rejected a later create at the cap, leaving a partial push (issue #1423
+ * review pass 3). Pure and side-effect-free so it's unit-testable without a
+ * live server.
+ */
+export function validateVarsFile(parsedVars) {
+    const errors = [];
+    const keyCount = Object.keys(parsedVars).length;
+    if (keyCount > MAX_VARS_PER_APP) {
+        errors.push(`vars.toml declares ${keyCount} vars, exceeding the maximum of ${MAX_VARS_PER_APP} vars per app. Remove ${keyCount - MAX_VARS_PER_APP} entr${keyCount - MAX_VARS_PER_APP === 1 ? "y" : "ies"}.`);
+    }
+    for (const [key, rawValue] of Object.entries(parsedVars)) {
+        if (!VARS_KEY_RE.test(key)) {
+            errors.push(`Invalid var key "${key}" in vars.toml: must match ^[A-Z][A-Z0-9_]{0,63}$ (uppercase letters, digits, underscores; start with a letter; max 64 chars)`);
+            continue;
+        }
+        if (typeof rawValue !== "string") {
+            errors.push(`Var "${key}" in vars.toml must be a string value (got ${typeof rawValue}) — quote the value.`);
+            continue;
+        }
+        const byteLength = new TextEncoder().encode(rawValue).length;
+        if (byteLength === 0) {
+            errors.push(`Var "${key}" in vars.toml must not be empty.`);
+        }
+        else if (byteLength > MAX_VAR_VALUE_BYTES) {
+            errors.push(`Var "${key}" in vars.toml exceeds the maximum value size of ${MAX_VAR_VALUE_BYTES} bytes (got ${byteLength}).`);
+        }
+    }
+    return errors;
+}
+/**
+ * Plan the config-var writes a `sync push` should make, detecting concurrent
+ * remote edits before overwriting them (issue #1423 review).
+ *
+ * This is the client-side half of a two-layer concurrency guard. The vars
+ * PUT/DELETE endpoints now honor an `expectedModifiedAt` precondition (issue
+ * #1423 review r-2 P1) and raise a `ConflictError` when the server row changed
+ * since the caller's snapshot — the atomic, server-side check every other
+ * synced entity relies on. This function is the fast fail-before-mutate layer:
+ * it compares the recorded baseline against the current remote snapshot and, for
+ * a var whose remote value has drifted from what we last synced, reports a
+ * conflict (fed into the same `conflicts[]` accumulator the other entities use)
+ * before any write is attempted. A var tracked at the baseline but absent from
+ * the remote snapshot (deleted remotely while edited locally) is remote drift
+ * too, and also reported as a conflict rather than silently recreated.
+ * Conversely, a var removed locally that is already absent remotely is NOT
+ * planned for deletion — its desired (absent) state is already met, so a DELETE
+ * would 404 and fail the push. The same drift check guards deletions: a var
+ * removed locally whose remote value no longer matches the baseline was edited
+ * remotely since the last sync, and deleting it would silently discard that
+ * edit — reported as a conflict instead. `force` skips the conflict guard,
+ * matching `sync push --force` for every other entity.
+ *
+ * Pure and side-effect-free (the caller owns the API calls and sync-state
+ * updates) so the guard is unit-testable without a live server. Assumes
+ * `parsedVars` has already passed `validateVarsFile` (values are strings). The
+ * caller normally fails the push closed when the remote snapshot can't be
+ * fetched, but under `--force` it falls back to an empty snapshot and sets
+ * `snapshotUnavailable` — which keeps removed-key deletions in the plan (they'd
+ * otherwise be mistaken for already-deleted and dropped) and leans on the apply
+ * loop's idempotent 404 handling (issue #1423 review r-2 P2).
+ */
+export function planVarsPush(parsedVars, baseline, remoteVars, options = {}) {
+    const remoteByKey = new Map(remoteVars.map((r) => [r.key, r]));
+    const upserts = [];
+    const conflicts = [];
+    const deletions = [];
+    let skippedCount = 0;
+    const localKeys = new Set();
+    for (const [key, value] of Object.entries(parsedVars)) {
+        localKeys.add(key);
+        const valueHash = hashVarValue(value);
+        const existing = baseline?.[key];
+        // Unchanged since last sync — skip (unless forced), mirroring the
+        // content-hash skip the other file-backed entities use.
+        if (!options.force && existing && existing.contentHash === valueHash) {
+            skippedCount++;
+            continue;
+        }
+        const action = existing ? "update" : "create";
+        // Concurrent-edit guard: if the remote value has drifted from the baseline
+        // we last synced (for an update) — or a var with this key was created
+        // remotely with a different value (for a create) — pushing would silently
+        // clobber that remote change. Report a conflict instead. `--force`
+        // overrides, exactly like the other entities.
+        if (!options.force) {
+            const remote = remoteByKey.get(key);
+            if (remote && typeof remote.value === "string") {
+                const remoteHash = hashVarValue(remote.value);
+                const remoteDrifted = existing?.contentHash
+                    ? remoteHash !== existing.contentHash
+                    : remoteHash !== valueHash;
+                if (remoteDrifted) {
+                    conflicts.push({
+                        key,
+                        serverModifiedAt: remote.updatedAt || "unknown",
+                        localModifiedAt: existing?.modifiedAt || "unknown",
+                    });
+                    continue;
+                }
+            }
+            else if (existing) {
+                // Tracked at the baseline but absent from the remote snapshot: the var
+                // was deleted remotely since our last sync while we edited it locally
+                // (we only reach here past the unchanged-skip above, so the local value
+                // differs from the baseline). Upserting would recreate the
+                // remotely-deleted var — that missing remote value is remote drift too,
+                // so report a conflict instead (issue #1423 review pass 3). `--force`
+                // overrides.
+                conflicts.push({
+                    key,
+                    serverModifiedAt: "deleted",
+                    localModifiedAt: existing.modifiedAt || "unknown",
+                });
+                continue;
+            }
+        }
+        upserts.push({ action, key, value, valueHash });
+    }
+    // Prune vars tracked in the baseline but removed from the local file
+    // (hard-delete; nested-entity precedent). Skip keys already absent from the
+    // remote snapshot: a var independently deleted remotely and also removed
+    // locally is already in its desired (absent) state, and a server DELETE would
+    // 404 and fail the whole push (issue #1423 review pass 3). `--force` does not
+    // resurrect these deletes — the desired state is met either way.
+    for (const [key, entry] of Object.entries(baseline ?? {})) {
+        if (localKeys.has(key))
+            continue;
+        const remote = remoteByKey.get(key);
+        if (!remote) {
+            // Normally an absent remote entry means the var is already gone, so its
+            // desired (deleted) state is met and a DELETE would 404 — skip it. But
+            // when the remote snapshot could NOT be fetched (the `--force` fallback
+            // after a failed `listAppConfigVars`, which passes an empty snapshot),
+            // "absent from the snapshot" means "unknown", not "gone". Suppressing the
+            // delete would silently keep a var the user removed from `vars.toml` while
+            // the push still reports success (issue #1423 review r-2 P2). Enqueue the
+            // removal and rely on the apply loop's idempotent 404 handling to absorb a
+            // key that really was already absent.
+            if (options.snapshotUnavailable)
+                deletions.push(key);
+            continue;
+        }
+        // Concurrent-edit guard, mirroring the upsert path (issue #1423 review
+        // pass 4): deleting a var whose remote value drifted from the last-synced
+        // baseline would silently discard that remote edit. When drift cannot be
+        // verified (no baseline hash, or no remote value in the snapshot), fail
+        // closed and report the conflict. `--force` deletes unconditionally.
+        if (!options.force) {
+            const remoteDrifted = typeof remote.value !== "string" ||
+                !entry.contentHash ||
+                hashVarValue(remote.value) !== entry.contentHash;
+            if (remoteDrifted) {
+                conflicts.push({
+                    key,
+                    serverModifiedAt: remote.updatedAt || "unknown",
+                    localModifiedAt: entry.modifiedAt || "unknown",
+                });
+                continue;
+            }
+        }
+        deletions.push(key);
+    }
+    return { upserts, deletions, conflicts, skippedCount };
+}
+/**
+ * Compute the number of config vars the server would hold after a push plan
+ * is applied (issue #1423 review pass 5). Validating only the local file's
+ * entry count misses remote-only vars: 95 local entries plus 10 vars that
+ * exist only on the server passes a local-count check, and the creates then
+ * exceed the server's cap mid-push, after earlier writes were already
+ * applied. Counted from the fetched remote snapshot: planned deletions remove
+ * keys that exist remotely (the plan already omits deletes for absent keys),
+ * and only upserts whose key is NOT already on the server add to the total.
+ * Conflicted keys are not mutated, so they contribute nothing beyond their
+ * current remote presence. Pure and side-effect-free so it's unit-testable
+ * without a live server.
+ */
+export function countVarsAfterPush(remoteVars, plan) {
+    const remoteKeys = new Set(remoteVars.map((r) => r.key));
+    let count = remoteKeys.size;
+    for (const key of plan.deletions) {
+        if (remoteKeys.has(key))
+            count--;
+    }
+    for (const upsert of plan.upserts) {
+        if (!remoteKeys.has(upsert.key))
+            count++;
+    }
+    return count;
+}
+/**
+ * Compute the `sync diff` rows for config vars (issue #1423 review). Before
+ * this, `sync diff` ignored vars entirely, so an add/remove/value-drift between
+ * the local `vars.toml` and the server read as no difference. Value-aware: a
+ * var present on both sides whose value differs is reported as `modified`
+ * (framed like the other content-aware entities — `sync pull` would rewrite the
+ * local value). Pure and side-effect-free so it's unit-testable without a live
+ * server.
+ */
+export function diffVars(localVars, remoteVars) {
+    const rows = [];
+    for (const [key, localValue] of localVars) {
+        if (!remoteVars.has(key)) {
+            rows.push({ type: "var", key, status: "local only" });
+        }
+        else if (remoteVars.get(key) !== localValue) {
+            rows.push({
+                type: "var",
+                key,
+                status: "modified",
+                hint: "run `sync pull` to rewrite vars.toml to match the server value",
+            });
+        }
+        else {
+            rows.push({ type: "var", key, status: "exists" });
+        }
+    }
+    for (const key of remoteVars.keys()) {
+        if (!localVars.has(key)) {
+            rows.push({ type: "var", key, status: "remote only" });
+        }
+    }
+    return rows;
 }
 function serializeIntegration(integration) {
     const data = {
@@ -239,9 +658,9 @@ function serializeIntegration(integration) {
         },
         requestConfig: integration.requestConfig || {},
     };
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
-function serializeWebhook(webhook) {
+export function serializeWebhook(webhook) {
     const data = {
         webhook: {
             key: webhook.webhookKey,
@@ -256,6 +675,17 @@ function serializeWebhook(webhook) {
             secretGracePeriodMs: webhook.secretGracePeriodMs,
         },
     };
+    // Re-emit a `{{secrets.KEY}}` reference so a pull→push round-trip is lossless
+    // (#1235). The server only returns `signingSecret` when it is such a
+    // reference (a real secret is returned masked, never in plaintext); guard on
+    // the template shape here too so a masked or raw value can never be written
+    // to TOML.
+    if (typeof webhook.signingSecret === "string" &&
+        // Whitespace-tolerant (#1468) to match the server's shared resolver, so a
+        // hand-authored spaced reference `{{ secrets.KEY }}` round-trips pull→push.
+        /\{\{\s*secrets\.[A-Z][A-Z0-9_]{0,63}\s*\}\}/.test(webhook.signingSecret)) {
+        data.webhook.signingSecret = webhook.signingSecret;
+    }
     // Parse JSON fields if they're strings
     if (webhook.allowedIpCidrs) {
         try {
@@ -284,7 +714,7 @@ function serializeWebhook(webhook) {
         if (data.webhook[k] === undefined)
             delete data.webhook[k];
     });
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 function serializeCronTrigger(trigger) {
     const data = {
@@ -320,7 +750,7 @@ function serializeCronTrigger(trigger) {
         if (data.cronTrigger[k] === undefined)
             delete data.cronTrigger[k];
     });
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 function serializeBlobBucket(bucket) {
     const data = {
@@ -346,7 +776,32 @@ function serializeBlobBucket(bucket) {
         if (data.bucket[k] === undefined)
             delete data.bucket[k];
     });
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
+}
+/**
+ * Build the PATCH payload for a blob-bucket update from local TOML.
+ *
+ * EXACT extraction of the inline builder shared by the existing-update and
+ * 409-adopt branches — do NOT "clean up" the truthiness checks. The server
+ * treats `preset` and `accessPolicy` as mutually exclusive, only clears
+ * `ruleSetId` when a preset/accessPolicy is also present, and nulls
+ * `description` only when the key is explicitly present with a falsy value.
+ * `bucketKey` and `ttlTier` are immutable and never sent. Both call sites
+ * must go through this helper so their field sets never drift.
+ */
+function buildBlobBucketUpdatePayload(bucket) {
+    const updatePayload = {};
+    if (bucket.preset)
+        updatePayload.preset = bucket.preset;
+    else if (bucket.accessPolicy)
+        updatePayload.accessPolicy = bucket.accessPolicy;
+    if (bucket.ruleSetId)
+        updatePayload.ruleSetId = bucket.ruleSetId;
+    if (bucket.name)
+        updatePayload.name = bucket.name;
+    if (bucket.description !== undefined)
+        updatePayload.description = bucket.description || null;
+    return updatePayload;
 }
 function serializePrompt(prompt) {
     const data = {
@@ -369,9 +824,102 @@ function serializePrompt(prompt) {
             userPromptTemplate: config.userPromptTemplate,
         })),
     };
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
+}
+/**
+ * Emit a workflow schema field (`inputSchema` / `outputSchema`) for the TOML
+ * `[workflow]` table.
+ *
+ * Issue #1446: pull used to `JSON.stringify` both schema fields into a single
+ * escaped-JSON line — unreadable and undiffable. We now emit the parsed JSON
+ * Schema as a native `[workflow.inputSchema]` / `[workflow.outputSchema]`
+ * table whenever it round-trips faithfully (`canEmitNative === null`), falling
+ * back to the JSON string only for the values TOML silently drops (`null` /
+ * `undefined` anywhere in the schema). The empty-object schema `{}` is a real,
+ * distinct value ("accepts anything") and emits as an empty table.
+ *
+ * Returns `undefined` for an absent schema (the key is then omitted). The
+ * sponsor-approved decision is to always move to native aggressively — no
+ * form preservation — so this does not consult the existing file's form.
+ */
+function serializeWorkflowSchemaField(value, fieldName, workflowKey, log) {
+    if (value === undefined || value === null)
+        return undefined;
+    // Schemas arrive from the server GET as parsed objects; defensively accept a
+    // JSON string too (e.g. an inline-authored file re-serialized here).
+    let obj = value;
+    if (typeof value === "string") {
+        try {
+            obj = JSON.parse(value);
+        }
+        catch {
+            // Not valid JSON — keep the original string as the emitted value.
+            return value;
+        }
+    }
+    if (obj && typeof obj === "object") {
+        const reason = canEmitNative(obj);
+        if (reason) {
+            log(`Workflow '${workflowKey}': cannot emit \`${fieldName}\` as native TOML (${reason}); using JSON string.`);
+            return JSON.stringify(obj);
+        }
+        return obj;
+    }
+    // A non-object schema (unexpected) — preserve it as a JSON string.
+    return JSON.stringify(obj);
 }
-function serializeWorkflow(workflow, draft, configs) {
+/**
+ * Rewrite a workflow TOML file's string-form `inputSchema` / `outputSchema` to
+ * native object form for `sync migrate-toml` (issue #1446).
+ *
+ * Purely local, no server fetch. Parses the raw source WITHOUT expanding
+ * fragment `include`s (so those directives survive the rewrite), swaps a
+ * JSON-string schema for its parsed object when it round-trips faithfully
+ * (`canEmitNative === null`), and re-serializes via `stringifyConfigToml`.
+ *
+ * Only rewrites when a field is actually converted: a file whose schemas are
+ * already native, absent, or un-representable (a `null` default) is returned
+ * with `changed: false` and its original bytes untouched — so migrate is
+ * idempotent and never reports a spurious migration or reformats a file it
+ * didn't need to touch.
+ */
+export function rewriteWorkflowSchemasToNative(rawToml, workflowKey = "", log = () => { }) {
+    const parsed = parseConfigToml(rawToml);
+    if (!parsed || typeof parsed !== "object" || !parsed.workflow) {
+        return { content: rawToml, changed: false };
+    }
+    const workflow = parsed.workflow;
+    let converted = false;
+    for (const field of ["inputSchema", "outputSchema"]) {
+        const value = workflow[field];
+        // Only a JSON-string schema is a migration candidate; an object is already
+        // native and an absent key needs nothing.
+        if (typeof value !== "string")
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(value);
+        }
+        catch {
+            // Not JSON — leave the literal string in place.
+            continue;
+        }
+        if (!obj || typeof obj !== "object")
+            continue;
+        const reason = canEmitNative(obj);
+        if (reason) {
+            log(`Workflow '${workflowKey}': cannot migrate \`${field}\` to native TOML (${reason}); leaving as JSON string.`);
+            continue;
+        }
+        workflow[field] = obj;
+        converted = true;
+    }
+    if (!converted)
+        return { content: rawToml, changed: false };
+    return { content: stringifyConfigToml(parsed), changed: true };
+}
+export function serializeWorkflow(workflow, draft, configs, logger) {
+    const log = logger ?? (() => { });
     // Find the active config or use the first one
     const activeConfigId = workflow.activeConfigId;
     const activeConfig = configs?.find((c) => c.configId === activeConfigId) || configs?.[0];
@@ -391,8 +939,24 @@ function serializeWorkflow(workflow, draft, configs) {
             // #1081 — workflow principal mode. Emit only when set so a fresh
             // pull → push round-trips it without writing a noisy `runAs = ""`.
             runAs: workflow.runAs || undefined,
+            // #1233 — opt-in sensitive capability grants. The GET response always
+            // returns an array (empty when unset); emit only when non-empty so a
+            // fresh pull → push round-trips a real value without writing a noisy
+            // `capabilities = []`. This is the load-bearing fix: before this, pull
+            // dropped capabilities entirely and a pull → push cycle silently cleared
+            // them on the server.
+            capabilities: Array.isArray(workflow.capabilities) && workflow.capabilities.length > 0
+                ? workflow.capabilities
+                : undefined,
             perUserMaxRunning: workflow.perUserMaxRunning,
             perUserMaxQueued: workflow.perUserMaxQueued,
+            // #1177 — app-level queue limits + queue TTL. Emit only when set so a
+            // fresh pull → push round-trips them without writing noisy zero/empty
+            // keys. The shared payload builder forwards these on create AND update,
+            // so the pull serializer must surface them for the round-trip to close.
+            perAppMaxRunning: workflow.perAppMaxRunning ?? undefined,
+            perAppMaxQueued: workflow.perAppMaxQueued ?? undefined,
+            queueTtlSeconds: workflow.queueTtlSeconds ?? undefined,
             dequeueOrder: workflow.dequeueOrder,
             // Sync-callable flags (#807): always emit both so a fresh pull → push
             // cycle round-trips them. The GET response normalizes these to booleans
@@ -400,9 +964,11 @@ function serializeWorkflow(workflow, draft, configs) {
             // they're safe to coerce here.
             requiresClientApply: workflow.requiresClientApply !== false,
             syncCallable: workflow.syncCallable === true,
-            // Schemas are at workflow level
-            inputSchema: workflow.inputSchema ? JSON.stringify(workflow.inputSchema) : undefined,
-            outputSchema: workflow.outputSchema ? JSON.stringify(workflow.outputSchema) : undefined,
+            // Schemas are at workflow level. Emit native `[workflow.inputSchema]` /
+            // `[workflow.outputSchema]` tables when representable, JSON string only
+            // as a data-loss fallback (issue #1446).
+            inputSchema: serializeWorkflowSchemaField(workflow.inputSchema, "inputSchema", workflow.workflowKey, log),
+            outputSchema: serializeWorkflowSchemaField(workflow.outputSchema, "outputSchema", workflow.workflowKey, log),
         },
         // Use active config steps, fall back to draft
         steps,
@@ -413,8 +979,12 @@ function serializeWorkflow(workflow, draft, configs) {
             status: config.status,
             isActive: config.configId === activeConfigId,
         })) || [],
+        // #1304 (P-C): the declared-access manifest — top-level `[metadata]` /
+        // `secrets`, merged the same way the collection/database type configs do so
+        // a workflow's `md`/`secrets` declarations round-trip through pull → push.
+        ...serializeDeclaredAccessManifest(workflow.metadataManifest),
     };
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 // Database config serialization helpers
 //
@@ -423,15 +993,17 @@ function serializeWorkflow(workflow, draft, configs) {
 // rows over JSON-strings stuffed into a single field. The form is sticky
 // per file — if the existing file uses the legacy JSON-string form, we
 // preserve it so we don't generate surprise diffs. New files default to
-// native. Un-TOMLable shapes (null, mixed-type arrays) fall back to JSON
-// string per field with a log message.
+// native. The round-trip serializes with `smol-toml` (TOML 1.0), so
+// heterogeneous arrays emit natively (issue #1450); only shapes that TOML
+// genuinely can't represent without data loss (null / undefined / an array
+// containing null) fall back to a JSON string per field with a log message.
 //
 // Issue #666: when the type has a stored `schema` (raw TOML of `[models.*]`
 // blocks), `buildDatabaseTypeTomlData` parses + merges it into the same TOML
 // object so the result round-trips as `[models.<Name>.fields.<field>]`.
 function serializeDatabaseType(typeConfig, operations, ruleSetIdToName, options = {}) {
     const data = buildDatabaseTypeTomlData(typeConfig, operations, ruleSetIdToName, options);
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 function serializeEmailTemplate(template) {
     // The API returns { emailType, hasOverride, override: { subject, htmlBody, textBody }, default: { ... } }
@@ -449,7 +1021,7 @@ function serializeEmailTemplate(template) {
     if (override.textBody) {
         data.template.textBody = override.textBody;
     }
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 function serializeRuleSet(ruleSet) {
     const data = {
@@ -466,9 +1038,9 @@ function serializeRuleSet(ruleSet) {
     if (Object.keys(rules).length > 0) {
         data.rules = rules;
     }
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
-function serializeGroupTypeConfig(config, ruleSetIdToName) {
+export function serializeGroupTypeConfig(config, ruleSetIdToName) {
     const ruleSetName = config.ruleSetId ? (ruleSetIdToName.get(config.ruleSetId) || "") : "";
     const data = {
         groupTypeConfig: {
@@ -476,8 +1048,12 @@ function serializeGroupTypeConfig(config, ruleSetIdToName) {
             ruleSetName: ruleSetName,
             autoAddCreator: config.autoAddCreator ?? true,
         },
+        // Declared-access manifest (issue #1350, extending #1304 P-C): merge the
+        // top-level `[metadata]` + `secrets` fragments so a pull→push→pull cycle
+        // round-trips, exactly like the collection/database/workflow type configs.
+        ...serializeDeclaredAccessManifest(config.metadataManifest),
     };
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 function serializeCollectionTypeConfig(config, ruleSetIdToName) {
     const ruleSetName = config.ruleSetId ? (ruleSetIdToName.get(config.ruleSetId) || "") : "";
@@ -486,8 +1062,11 @@ function serializeCollectionTypeConfig(config, ruleSetIdToName) {
             collectionType: config.collectionType,
             ruleSetName: ruleSetName,
         },
+        // Declared-access manifest (issue #1304, P-C): merge the top-level
+        // `[metadata]` + `secrets` fragments so a pull→push→pull cycle round-trips.
+        ...serializeDeclaredAccessManifest(config.metadataManifest),
     };
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 export function parseDatabaseTypeToml(tomlData) {
     const typeSection = tomlData.type || {};
@@ -530,6 +1109,17 @@ export function parseDatabaseTypeToml(tomlData) {
     if (tomlData.triggers) {
         typeConfig.triggers = tomlData.triggers;
     }
+    // Declared-access manifest (issue #1304, P-C): the top-level `[metadata]` +
+    // `secrets` blocks. Validated locally before push; the server re-validates
+    // (graph/schema) at persist time.
+    const manifest = parseDeclaredAccessManifestToml(tomlData);
+    if (manifest) {
+        const manifestError = validateDeclaredAccessManifest(manifest);
+        if (manifestError) {
+            throw new Error(`Invalid metadata manifest in database type "${typeSection.databaseType || ""}": ${manifestError}`);
+        }
+        typeConfig.metadataManifest = manifest;
+    }
     // Issue #666: extract the `[models.*]` subtree (if present) and re-serialize
     // it to a TOML string for the server's `schema` field.
     //
@@ -542,7 +1132,7 @@ export function parseDatabaseTypeToml(tomlData) {
     let schemaSerialized = null;
     if (tomlData.models && typeof tomlData.models === "object") {
         try {
-            schemaSerialized = TOML.stringify({ models: tomlData.models });
+            schemaSerialized = stringifyConfigToml({ models: tomlData.models });
         }
         catch {
             // Fall through — server-side parser will fail with a clear
@@ -584,6 +1174,17 @@ export function parseGroupTypeConfigToml(tomlData) {
     else if (section.ruleSetId && section.ruleSetId !== "") {
         result.ruleSetId = section.ruleSetId;
     }
+    // Declared-access manifest (issue #1350, extending #1304 P-C): the top-level
+    // `[metadata]` + `secrets` blocks. Validated locally before push; the server
+    // re-validates (graph/schema) at persist time.
+    const manifest = parseDeclaredAccessManifestToml(tomlData);
+    if (manifest) {
+        const manifestError = validateDeclaredAccessManifest(manifest);
+        if (manifestError) {
+            throw new Error(`Invalid metadata manifest in group type config "${section.groupType || ""}": ${manifestError}`);
+        }
+        result.metadataManifest = manifest;
+    }
     return result;
 }
 export function parseCollectionTypeConfigToml(tomlData) {
@@ -598,6 +1199,17 @@ export function parseCollectionTypeConfigToml(tomlData) {
     else if (section.ruleSetId && section.ruleSetId !== "") {
         result.ruleSetId = section.ruleSetId;
     }
+    // Declared-access manifest (issue #1304, P-C): the top-level `[metadata]` +
+    // `secrets` blocks. Validated locally before push; the server re-validates
+    // (graph/schema) at persist time.
+    const manifest = parseDeclaredAccessManifestToml(tomlData);
+    if (manifest) {
+        const manifestError = validateDeclaredAccessManifest(manifest);
+        if (manifestError) {
+            throw new Error(`Invalid metadata manifest in collection type config "${section.collectionType || ""}": ${manifestError}`);
+        }
+        result.metadataManifest = manifest;
+    }
     return result;
 }
 // Parsing helpers
@@ -609,7 +1221,7 @@ export function parseCollectionTypeConfigToml(tomlData) {
 // the original object untouched.
 function parseTomlFile(filePath) {
     const content = readFileSync(filePath, "utf-8");
-    const parsed = TOML.parse(content);
+    const parsed = parseConfigToml(content);
     return expandWorkflowTomlData(parsed, filePath);
 }
 /**
@@ -629,17 +1241,6 @@ export async function fetchAll(listFn, pageSize = 100, maxPages = 100) {
     } while (cursor);
     return all;
 }
-/**
- * Safely parse a JSON field that may be a string or already an object.
- * TOML can parse inline tables as objects, so we need to handle both.
- */
-export function safeJsonParse(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value === "string")
-        return JSON.parse(value);
-    return value; // Already an object (TOML parsed it as a table)
-}
 /**
  * Resolve a key-based rule set name reference to an ID.
  * Throws if the name cannot be resolved and throwOnMissing is true.
@@ -681,7 +1282,14 @@ export function resolveSlugCollisions(slug, usedSlugs) {
     return resolved;
 }
 function getTestsDir(configDir, blockType, blockKey) {
-    const typeDir = blockType === "prompt" ? "prompts" : "workflows";
+    // Scripts (blockType "script") live under `transforms/` on disk (their
+    // bodies are `transforms/<name>.rhai`), so their test cases sit alongside at
+    // `transforms/<name>.tests/`. Prompts and workflows keep their own dirs.
+    const typeDir = blockType === "prompt"
+        ? "prompts"
+        : blockType === "script"
+            ? "transforms"
+            : "workflows";
     return join(configDir, typeDir, `${blockKey}.tests`);
 }
 export function serializeTestCase(testCase, lookupMaps) {
@@ -705,7 +1313,7 @@ export function serializeTestCase(testCase, lookupMaps) {
             expectedJsonSubset: testCase.expectedJsonSubset || "{}",
         },
     };
-    return TOML.stringify(data);
+    return stringifyConfigToml(data);
 }
 export function parseTestCaseToml(tomlData) {
     const test = tomlData.test || {};
@@ -963,8 +1571,10 @@ async function pushTestCasesForBlock(client, appId, blockType, blockId, blockKey
                 const configMapKey = `${blockKey}#${testPayload._configName}`;
                 const configMap = blockType === "prompt"
                     ? resolutionMaps.promptConfigNameToId
-                    : resolutionMaps.workflowConfigNameToId;
-                const resolvedId = configMap.get(configMapKey);
+                    : blockType === "script"
+                        ? resolutionMaps.scriptConfigNameToId
+                        : resolutionMaps.workflowConfigNameToId;
+                const resolvedId = configMap?.get(configMapKey);
                 if (resolvedId) {
                     testPayload.configId = resolvedId;
                 }
@@ -1166,6 +1776,7 @@ Directory Structure:
     rule-sets/*.toml                # Access rule sets
     group-type-configs/*.toml       # Group type configs
     collection-type-configs/*.toml  # Collection type configs
+    metadata-category-configs/*.toml # Resource-metadata category configs
     email-templates/*.toml          # Email template overrides
 `);
     // Init
@@ -1196,6 +1807,7 @@ Directory Structure:
         ensureDir(join(configDir, "rule-sets"));
         ensureDir(join(configDir, "group-type-configs"));
         ensureDir(join(configDir, "collection-type-configs"));
+        ensureDir(join(configDir, "metadata-category-configs"));
         ensureDir(join(configDir, "email-templates"));
         const state = {
             appId: resolvedAppId,
@@ -1267,11 +1879,12 @@ Directory Structure:
                 return;
             }
             // Fetch database config resources
-            const [databaseTypeConfigsResult, ruleSetsResult, groupTypeConfigsResult, collectionTypeConfigsResult,] = await Promise.all([
+            const [databaseTypeConfigsResult, ruleSetsResult, groupTypeConfigsResult, collectionTypeConfigsResult, metadataCategoryConfigsResult,] = await Promise.all([
                 client.listDatabaseTypeConfigs(resolvedAppId).catch(() => []),
                 client.listRuleSets(resolvedAppId).catch(() => []),
                 client.listGroupTypeConfigs(resolvedAppId).catch(() => []),
                 client.listCollectionTypeConfigs(resolvedAppId).catch(() => []),
+                client.listMetadataCategoryConfigs(resolvedAppId).catch(() => []),
             ]);
             // Fetch operations + subscriptions for each database type. Issue #803:
             // subscriptions are pulled symmetrically with operations so a
@@ -1330,6 +1943,7 @@ Directory Structure:
             ensureDir(join(configDir, "rule-sets"));
             ensureDir(join(configDir, "group-type-configs"));
             ensureDir(join(configDir, "collection-type-configs"));
+            ensureDir(join(configDir, "metadata-category-configs"));
             ensureDir(join(configDir, "email-templates"));
             // Write app settings
             if (settings) {
@@ -1337,6 +1951,38 @@ Directory Structure:
                 writeFileSync(appTomlPath, serializeAppSettings(settings));
                 info("  Wrote app.toml");
             }
+            // Write config vars (issue #1423). A single flat vars.toml at the
+            // sync-dir root (like app.toml), holding the per-environment non-secret
+            // scalars. Written (comment-only when empty) so the managed file exists
+            // and a later push knows the vars surface is under sync control.
+            //
+            // Distinguish "app genuinely has zero vars" (a successful empty
+            // response — safe to write the comment-only file) from "fetch failed"
+            // (a transient 401/500/network error). Previously a `.catch(() => [])`
+            // conflated the two, so a transient error silently clobbered a good
+            // local vars.toml with a comment-only file while reporting success. On a
+            // fetch error we now leave the existing vars.toml untouched and preserve
+            // the prior manifest entry so state stays consistent with the file.
+            const varsTomlPathPull = join(configDir, "vars.toml");
+            let varsOutcome;
+            try {
+                varsOutcome = { ok: true, vars: await client.listAppConfigVars(resolvedAppId) };
+            }
+            catch (varErr) {
+                varsOutcome = { ok: false, error: varErr };
+            }
+            const varsPlan = planVarsPull(varsOutcome, varsOutcome.ok ? undefined : loadSyncState(configDir)?.entities?.vars);
+            const varEntities = varsPlan.varEntities;
+            if (varsPlan.write && varsPlan.content !== null) {
+                writeFileSync(varsTomlPathPull, varsPlan.content);
+                const count = varsOutcome.vars.length;
+                info(`  Wrote vars.toml (${count} var${count === 1 ? "" : "s"})`);
+            }
+            else {
+                const err = varsOutcome.error;
+                error(`  Skipped vars.toml — failed to fetch config vars: ${err?.message ?? err}. ` +
+                    "Left the existing vars.toml untouched.");
+            }
             // Write integrations
             const integrationEntities = {};
             for (const integration of integrations) {
@@ -1425,7 +2071,7 @@ Directory Structure:
             for (const { workflow, draft, configs } of workflows) {
                 const filename = `${workflow.workflowKey}.toml`;
                 const filePath = join(configDir, "workflows", filename);
-                writeFileSync(filePath, serializeWorkflow(workflow, draft, configs || []));
+                writeFileSync(filePath, serializeWorkflow(workflow, draft, configs || [], (msg) => info(`  ${msg}`)));
                 // Hash the expanded (post-fragment-splice) form so subsequent pushes
                 // can detect fragment-only edits. See `computeExpandedContentHash`.
                 // Pulled workflows never carry `include`, so the expander is a
@@ -1468,6 +2114,23 @@ Directory Structure:
                     }
                 }
             }
+            // Include script config names so a pinned script test case
+            // round-trips its `configName` reference (the same way prompt/workflow
+            // configs above do). One extra `configs` fetch per pulled script.
+            for (const [name, entity] of Object.entries(scriptEntities)) {
+                try {
+                    const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, entity.id);
+                    for (const config of scriptConfigs) {
+                        configIdToName.set(config.configId, config.configName);
+                    }
+                }
+                catch {
+                    // Non-fatal: a script test case pinned to a config just serializes
+                    // without a resolvable name (falls back to active on push). The
+                    // header/body still pulled fine — `name` retained for clarity.
+                    void name;
+                }
+            }
             const testCaseLookupMaps = { configIdToName, promptIdToKey };
             // Write email templates (use detailed emailTemplates, not summaries)
             const emailTemplateEntities = {};
@@ -1510,6 +2173,15 @@ Directory Structure:
                 }
                 totalTestCases += count;
             }
+            // Pull test cases for scripts (transforms). Script blocks use
+            // blockType "script"; their tests land under transforms/<name>.tests/.
+            for (const [name, entity] of Object.entries(scriptEntities)) {
+                const count = await pullTestCasesForBlock(client, resolvedAppId, "script", entity.id, name, configDir, testCaseEntities, testCaseLookupMaps);
+                if (count > 0) {
+                    info(`  Wrote ${count} test case(s) for script: ${name}`);
+                }
+                totalTestCases += count;
+            }
             // Build ruleSetId → name map for database types and group type configs
             const ruleSets = Array.isArray(ruleSetsResult) ? ruleSetsResult : [];
             const ruleSetIdToName = new Map();
@@ -1605,6 +2277,23 @@ Directory Structure:
                 };
                 info(`  Wrote collection-type-configs/${filename}`);
             }
+            // Write metadata category configs (issue #1304, P-B). One file per
+            // `{resourceType, category}`; the entity key is the `resourceType#category`
+            // pair so push can match it back.
+            const metadataCategoryConfigEntities = {};
+            const metadataCategoryConfigs = Array.isArray(metadataCategoryConfigsResult)
+                ? metadataCategoryConfigsResult
+                : [];
+            for (const config of metadataCategoryConfigs) {
+                const filename = `${config.resourceType}.${config.category}.toml`;
+                const filePath = join(configDir, "metadata-category-configs", filename);
+                writeFileSync(filePath, serializeMetadataCategoryConfig(config));
+                metadataCategoryConfigEntities[`${config.resourceType}#${config.category}`] = {
+                    modifiedAt: config.modifiedAt || new Date().toISOString(),
+                    contentHash: computeFileHash(filePath),
+                };
+                info(`  Wrote metadata-category-configs/${filename}`);
+            }
             // Save sync state
             const state = {
                 appId: resolvedAppId,
@@ -1623,15 +2312,20 @@ Directory Structure:
                     testCases: Object.keys(testCaseEntities).length > 0 ? testCaseEntities : undefined,
                     databaseTypes: Object.keys(databaseTypeEntities).length > 0 ? databaseTypeEntities : undefined,
                     ruleSets: Object.keys(ruleSetEntities).length > 0 ? ruleSetEntities : undefined,
+                    vars: Object.keys(varEntities).length > 0 ? varEntities : undefined,
                     groupTypeConfigs: Object.keys(groupTypeConfigEntities).length > 0 ? groupTypeConfigEntities : undefined,
                     collectionTypeConfigs: Object.keys(collectionTypeConfigEntities).length > 0
                         ? collectionTypeConfigEntities
                         : undefined,
+                    metadataCategoryConfigs: Object.keys(metadataCategoryConfigEntities).length > 0
+                        ? metadataCategoryConfigEntities
+                        : undefined,
                 },
             };
             saveSyncState(configDir, state);
             divider();
             success(`Pulled configuration to ${configDir}`);
+            keyValue("Config Vars", Object.keys(varEntities).length);
             keyValue("Integrations", integrations.length);
             keyValue("Webhooks", webhooks.length);
             keyValue("Cron Triggers", cronTriggerItems.length);
@@ -1645,6 +2339,7 @@ Directory Structure:
             keyValue("Rule Sets", ruleSets.length);
             keyValue("Group Type Configs", groupTypeConfigs.length);
             keyValue("Collection Type Configs", collectionTypeConfigs.length);
+            keyValue("Metadata Category Configs", metadataCategoryConfigs.length);
         }
         catch (err) {
             error(err.message);
@@ -1896,10 +2591,91 @@ Directory Structure:
                     }
                 }
             }
+            // Validate config vars up-front (issue #1423 review). Parse vars.toml
+            // and check the same key/value constraints the server enforces here, in
+            // the preflight pass, so an invalid entry aborts BEFORE any mutation
+            // (app settings or a var upsert) is applied. Previously validation ran
+            // mid-push, after app settings could already have been updated.
+            const preflightVarsTomlPath = join(configDir, "vars.toml");
+            let preflightParsedVars = null;
+            if (existsSync(preflightVarsTomlPath)) {
+                try {
+                    const parsed = parseTomlFile(preflightVarsTomlPath);
+                    for (const e of validateVarsFile(parsed)) {
+                        preflightValidationErrors.push(`  ${e}`);
+                    }
+                    preflightParsedVars = parsed;
+                }
+                catch (err) {
+                    preflightValidationErrors.push(`  vars.toml: ${err?.message || String(err)}`);
+                }
+            }
             if (preflightValidationErrors.length > 0) {
                 throw new Error(`Aborting push: ${preflightValidationErrors.length} TOML validation error(s) — no changes were applied.\n` +
                     preflightValidationErrors.join("\n"));
             }
+            // Fetch the current remote config vars up-front — before ANY mutation
+            // (issue #1423 review pass 3). `planVarsPush` needs this snapshot both
+            // to detect concurrent remote edits and to decide which already-absent
+            // deletes to skip. A failed fetch must FAIL CLOSED: proceeding with an
+            // empty snapshot would silently disable the concurrency guard and let a
+            // changed local value clobber a remote edit. Abort unless `--force`.
+            // Fetching here (not mid-push) keeps the abort fail-before-mutate.
+            let remoteVarsSnapshot = [];
+            // Whether the snapshot above is authoritative. A failed fetch under
+            // `--force` leaves it empty but UNKNOWN (not "the server has no vars") —
+            // `planVarsPush` needs this so it doesn't mistake "absent from the empty
+            // snapshot" for "already deleted remotely" and silently drop deletions
+            // the user asked for (issue #1423 review r-2 P2).
+            let varSnapshotUnavailable = false;
+            if (existsSync(preflightVarsTomlPath)) {
+                try {
+                    remoteVarsSnapshot = await client.listAppConfigVars(resolvedAppId);
+                }
+                catch (err) {
+                    if (!options.force) {
+                        throw new Error(`Aborting push: could not fetch remote config vars to check for ` +
+                            `concurrent edits (${err?.message || String(err)}) — no changes ` +
+                            `were applied. Re-run with --force to push without the ` +
+                            `concurrency guard.`);
+                    }
+                    // --force: proceed without a snapshot; the guard is intentionally
+                    // bypassed and every local var is upserted as authoritative. The
+                    // snapshot is unknown, so deletions of removed keys are still
+                    // enqueued (idempotent 404 handling absorbs already-absent keys).
+                    remoteVarsSnapshot = [];
+                    varSnapshotUnavailable = true;
+                }
+            }
+            // Plan the var writes up-front and validate the FINAL server var
+            // count against the cap BEFORE any mutation (issue #1423 review pass
+            // 5). `validateVarsFile` above caps the local file's entry count, but
+            // remote-only vars (on the server, not in vars.toml) still count
+            // toward the server's limit: 95 local entries plus 10 remote-only
+            // vars passes the local check, then a later create is rejected at the
+            // cap after earlier writes were already applied. Computed from the
+            // remote snapshot plus planned creates minus planned deletions. The
+            // check applies even with `--force`: the cap is a server hard limit,
+            // not a conflict guard, so a push that would exceed it cannot succeed
+            // and forcing it would only leave a partial push. (Under `--force`
+            // with a failed snapshot fetch the remote count is unknown; the check
+            // then degrades to the local file count, like the concurrency guard.)
+            let varPlan = null;
+            if (preflightParsedVars) {
+                varPlan = planVarsPush(preflightParsedVars, syncState?.entities?.vars, remoteVarsSnapshot, { force: options.force, snapshotUnavailable: varSnapshotUnavailable });
+                const finalVarCount = countVarsAfterPush(remoteVarsSnapshot, varPlan);
+                if (finalVarCount > MAX_VARS_PER_APP) {
+                    const localKeys = new Set(Object.keys(preflightParsedVars));
+                    const plannedDeletes = new Set(varPlan.deletions);
+                    const remoteOnlyCount = remoteVarsSnapshot.filter((r) => !localKeys.has(r.key) && !plannedDeletes.has(r.key)).length;
+                    throw new Error(`Aborting push: it would leave ${finalVarCount} config vars on the server, ` +
+                        `exceeding the maximum of ${MAX_VARS_PER_APP} vars per app ` +
+                        `(server has ${remoteVarsSnapshot.length} vars, ${remoteOnlyCount} of ` +
+                        `which are not in vars.toml) — no changes were applied. Run ` +
+                        `\`sync pull\` to bring the remote-only vars into vars.toml, or ` +
+                        `delete unneeded vars, then push again.`);
+                }
+            }
             // Process app settings
             const appTomlPath = join(configDir, "app.toml");
             if (existsSync(appTomlPath)) {
@@ -1920,11 +2696,10 @@ Directory Structure:
                         }
                     }
                     if (tomlData.auth) {
-                        settings.googleOAuthEnabled = tomlData.auth.googleOAuthEnabled;
-                        settings.passkeyEnabled = tomlData.auth.passkeyEnabled;
-                        settings.magicLinkEnabled = tomlData.auth.magicLinkEnabled;
-                        if (tomlData.auth.passkeys) {
-                            settings.passkeyRpConfig = tomlData.auth.passkeys;
+                        const { settings: authSettings, warnings: authWarnings } = parseAppAuthSettings(tomlData.auth);
+                        Object.assign(settings, authSettings);
+                        for (const w of authWarnings) {
+                            warn(`  ${w}`);
                         }
                     }
                     if (tomlData.cors) {
@@ -1948,6 +2723,135 @@ Directory Structure:
                     }
                 }
             }
+            // Process config vars (issue #1423). Read the flat vars.toml, upsert
+            // each key (PUT by key is idempotent — one call covers create+update),
+            // and hard-delete keys removed from the file (nested-entity precedent:
+            // database operations/subscriptions). Pruning runs ONLY when the file
+            // is present, so an absent vars.toml never mass-deletes server vars.
+            //
+            // Key/value validation now runs up-front in the preflight pass above,
+            // so by the time we get here the file is known-valid (values are
+            // strings). The remote-vars snapshot was also fetched up-front (fail
+            // closed) so `planVarsPush` can detect a concurrent remote edit and
+            // report it as a conflict instead of silently overwriting it (review
+            // r-2 P1), and the plan itself was computed up-front so the final
+            // server var count could be validated against the cap before any
+            // mutation (review pass 5).
+            if (varPlan) {
+                skippedCount += varPlan.skippedCount;
+                // Feed var conflicts into the shared accumulator — same convention as
+                // every other entity, so the end-of-run report renders them as
+                // `CONFLICT var: KEY` and the push exits non-zero.
+                for (const c of varPlan.conflicts) {
+                    conflicts.push({
+                        type: "var",
+                        key: c.key,
+                        serverModifiedAt: c.serverModifiedAt,
+                        localModifiedAt: c.localModifiedAt,
+                    });
+                }
+                // Delete removed keys BEFORE upserting new ones (issue #1423 review
+                // pass 3). At the server's 100-var cap, a replacement (remove one key,
+                // add another) is a valid final state, but upserting the new key first
+                // would transiently exceed the cap and the create would be rejected.
+                // Freeing the removed slots first lets the replacement synchronize.
+                // Each removal prints an "Unsetting var X" line so the destructive
+                // action is visible.
+                for (const key of varPlan.deletions) {
+                    changes.push({ type: "var", action: "delete", key });
+                    if (!options.dryRun) {
+                        // Server-side concurrency guard (issue #1423 review r-2 P1): send
+                        // the `updatedAt` we last synced so the server rejects the delete
+                        // (409 CONFLICT) if the var was edited remotely since — closing the
+                        // race between the client snapshot and this DELETE that the
+                        // client-side `planVarsPush` guard alone can't. `--force` omits it
+                        // and deletes unconditionally.
+                        const expectedModifiedAt = options.force
+                            ? undefined
+                            : syncState?.entities?.vars?.[key]?.modifiedAt;
+                        try {
+                            await client.deleteAppConfigVar(resolvedAppId, key, expectedModifiedAt);
+                            info(`  Unsetting var ${key}`);
+                            if (syncState?.entities?.vars)
+                                delete syncState.entities.vars[key];
+                        }
+                        catch (err) {
+                            // A remote edit landed since our snapshot — report a conflict
+                            // instead of discarding it (feeds the shared accumulator →
+                            // `CONFLICT var: KEY`, non-zero exit).
+                            if (err instanceof ConflictError) {
+                                conflicts.push({
+                                    type: "var",
+                                    key,
+                                    serverModifiedAt: err.serverModifiedAt,
+                                    localModifiedAt: expectedModifiedAt || "unknown",
+                                });
+                            }
+                            else if (err instanceof ApiError && err.statusCode === 404) {
+                                // A 404 means the var is already absent — the desired
+                                // (deleted) state is met, so treat it as an idempotent success
+                                // rather than failing the whole push (issue #1423 review pass
+                                // 3). The plan omits deletes for keys absent from a fetched
+                                // snapshot; this also absorbs the forced no-snapshot fallback
+                                // (r-2 P2), where removed keys are enqueued unconditionally.
+                                info(`  Var ${key} already absent (nothing to unset)`);
+                                if (syncState?.entities?.vars)
+                                    delete syncState.entities.vars[key];
+                            }
+                            else {
+                                throw wrapEntityError(err, "delete", "var", key);
+                            }
+                        }
+                    }
+                }
+                for (const item of varPlan.upserts) {
+                    changes.push({ type: "var", action: item.action, key: item.key });
+                    if (!options.dryRun) {
+                        // Server-side concurrency guard (issue #1423 review r-2 P1): for an
+                        // update, send the `updatedAt` we last synced so the server rejects
+                        // the write (409 CONFLICT) if the var changed remotely since — this
+                        // closes the snapshot→PUT race the client-side guard can't. A
+                        // create has no baseline, so instead it sends a create-only
+                        // precondition (`expectNotExists`, review r-3 P1a): the server 409s
+                        // if the key was created remotely since our snapshot rather than
+                        // silently overwriting that concurrent create. `--force` overrides
+                        // both.
+                        const isCreate = item.action === "create";
+                        const expectedModifiedAt = options.force || isCreate
+                            ? undefined
+                            : syncState?.entities?.vars?.[item.key]?.modifiedAt;
+                        try {
+                            const result = await client.upsertAppConfigVar(resolvedAppId, item.key, { value: item.value }, expectedModifiedAt, { expectNotExists: !options.force && isCreate });
+                            if (syncState) {
+                                if (!syncState.entities.vars)
+                                    syncState.entities.vars = {};
+                                syncState.entities.vars[item.key] = {
+                                    // Record the server's returned timestamp (updatedAt) so the
+                                    // next push's concurrent-edit guard has an accurate baseline.
+                                    modifiedAt: result?.updatedAt || result?.modifiedAt || new Date().toISOString(),
+                                    contentHash: item.valueHash,
+                                };
+                            }
+                        }
+                        catch (err) {
+                            // A remote edit landed since our snapshot — report a conflict
+                            // instead of clobbering it (feeds the shared accumulator →
+                            // `CONFLICT var: KEY`, non-zero exit).
+                            if (err instanceof ConflictError) {
+                                conflicts.push({
+                                    type: "var",
+                                    key: item.key,
+                                    serverModifiedAt: err.serverModifiedAt,
+                                    localModifiedAt: expectedModifiedAt || "unknown",
+                                });
+                            }
+                            else {
+                                throw wrapEntityError(err, item.action, "var", item.key);
+                            }
+                        }
+                    }
+                }
+            }
             // Process rule sets first (other entities may reference them by name)
             const ruleSetsDir = join(configDir, "rule-sets");
             if (existsSync(ruleSetsDir)) {
@@ -2142,6 +3046,14 @@ Directory Structure:
                         deduplicationWindowMs: webhook.deduplicationWindowMs,
                         secretGracePeriodMs: webhook.secretGracePeriodMs,
                     };
+                    // Forward the declared signing secret so a `{{secrets.KEY}}`
+                    // reference reaches the server intact (#1235). Without this the
+                    // value declared in TOML is silently dropped and the server
+                    // rejects a verified webhook with "signingSecret is required".
+                    // Mirrors how integrations forward requestConfig with refs intact.
+                    if (webhook.signingSecret !== undefined) {
+                        payload.signingSecret = webhook.signingSecret;
+                    }
                     // Handle JSON fields
                     if (tomlData.allowedIps?.cidrs) {
                         payload.allowedIpCidrs = JSON.stringify(tomlData.allowedIps.cidrs);
@@ -2346,30 +3258,27 @@ Directory Structure:
                     if (existingId) {
                         // #1020 (D8): idempotently apply preset/ruleSet/name/description
                         // changes via PATCH. bucketKey/ttlTier are immutable and not sent.
-                        const updatePayload = {};
-                        if (bucket.preset)
-                            updatePayload.preset = bucket.preset;
-                        else if (bucket.accessPolicy)
-                            updatePayload.accessPolicy = bucket.accessPolicy;
-                        if (bucket.ruleSetId)
-                            updatePayload.ruleSetId = bucket.ruleSetId;
-                        if (bucket.name)
-                            updatePayload.name = bucket.name;
-                        if (bucket.description !== undefined)
-                            updatePayload.description = bucket.description || null;
+                        const updatePayload = buildBlobBucketUpdatePayload(bucket);
                         changes.push({ type: "blob-bucket", action: "update", key });
                         if (!options.dryRun) {
                             try {
                                 await client.updateBlobBucket(resolvedAppId, existingId, updatePayload);
                                 info(`  Updated blob bucket: ${key}`);
+                                // #1459: stamp the content hash ONLY after a successful
+                                // update, and only when this is not a dry run. A failed
+                                // update (or a dry run) must leave the file pending rather
+                                // than mark it in-sync and suppress it on the next push.
+                                if (syncState?.entities?.blobBuckets?.[key]) {
+                                    syncState.entities.blobBuckets[key].contentHash =
+                                        computeFileHash(filePath);
+                                }
                             }
                             catch (err) {
+                                // Keep the warn-and-continue contract (sponsor decision):
+                                // do not abort the push, just don't stamp the hash.
                                 warn(`  Failed to update blob bucket ${key}: ${String(err?.message || err)}`);
                             }
                         }
-                        if (syncState?.entities?.blobBuckets?.[key]) {
-                            syncState.entities.blobBuckets[key].contentHash = computeFileHash(filePath);
-                        }
                     }
                     else {
                         const payload = {
@@ -2404,23 +3313,86 @@ Directory Structure:
                             catch (err) {
                                 const msg = String(err?.message || err);
                                 if (msg.includes("already exists") || err.statusCode === 409) {
-                                    info(`  Blob bucket already exists on server: ${key}`);
-                                    // Fetch the existing bucket to get its ID
+                                    // #1459: adopt-by-key on 409. A blob bucket can already
+                                    // exist on the server (an out-of-band create, or a prior
+                                    // push that aborted before recording it in sync state). The
+                                    // old handler stamped the LOCAL file's contentHash WITHOUT
+                                    // applying the local config, so a divergent bucket was
+                                    // silently marked in-sync and never reconciled. Mirror the
+                                    // cron/workflow adopt paths: look up the bucket by key,
+                                    // re-issue the local payload as an UPDATE, and stamp the
+                                    // hash ONLY after the update succeeds.
+                                    info(`  Blob bucket already exists on server, adopting by key: ${key}`);
+                                    let existing;
                                     try {
-                                        const existing = await client.getBlobBucket(resolvedAppId, key);
-                                        if (syncState && existing?.bucketId) {
-                                            if (!syncState.entities.blobBuckets) {
-                                                syncState.entities.blobBuckets = {};
-                                            }
-                                            syncState.entities.blobBuckets[key] = {
-                                                id: existing.bucketId,
-                                                modifiedAt: existing.modifiedAt || new Date().toISOString(),
-                                                contentHash: computeFileHash(filePath),
-                                            };
+                                        existing = await client.getBlobBucket(resolvedAppId, key);
+                                    }
+                                    catch (lookupErr) {
+                                        // A lookup failure after a 409 means we cannot adopt —
+                                        // surface it instead of swallowing it (the old silent
+                                        // `catch {}` left no sync-state entry, looping
+                                        // create→409 on every push).
+                                        throw wrapEntityError(new Error(`blob bucket "${key}" already exists but could not be adopted (lookup failed: ${String(lookupErr?.message || lookupErr)})`), "create", "blob bucket", key);
+                                    }
+                                    if (!existing?.bucketId) {
+                                        // 409 but no matching bucket found — surface the original
+                                        // create error rather than silently proceeding.
+                                        throw wrapEntityError(err, "create", "blob bucket", key);
+                                    }
+                                    // Verify the resolved bucket is actually the one we asked
+                                    // for. `getBlobBucket` resolves the identifier by primary id
+                                    // (appId, bucketId) BEFORE bucketKey, and a bucketKey may be
+                                    // a ULID-shaped string (the key regex permits it). If the
+                                    // local key collides with an unrelated bucket's bucketId,
+                                    // the lookup returns that unrelated bucket — patching and
+                                    // stamping it would overwrite the wrong resource. Require an
+                                    // exact key match, matching the cron/workflow adopt paths'
+                                    // exact-key equality (they list + filter by key for the same
+                                    // reason). Surface the mismatch via wrapEntityError; do NOT
+                                    // patch or stamp.
+                                    if (existing.bucketKey !== key) {
+                                        throw wrapEntityError(new Error(`blob bucket "${key}" already exists, but the server resolved a different bucket (bucketKey "${existing.bucketKey}", bucketId "${existing.bucketId}"); refusing to adopt. This happens when the local key collides with an unrelated bucket's id — rename the local bucket key so it does not match an existing bucket id.`), "create", "blob bucket", key);
+                                    }
+                                    // ttlTier is immutable and cannot be reconciled by an
+                                    // UPDATE. A local TOML whose retention tier diverges from
+                                    // the server must fail loudly (sponsor decision) rather
+                                    // than be silently blessed while the cosmetic fields
+                                    // converge.
+                                    if (bucket.ttlTier &&
+                                        existing.ttlTier &&
+                                        bucket.ttlTier !== existing.ttlTier) {
+                                        throw wrapEntityError(new Error(`blob bucket "${key}" ttlTier mismatch: local TOML has "${bucket.ttlTier}" but the server bucket has "${existing.ttlTier}". ttlTier is immutable; align the TOML with the server (or recreate the bucket) before pushing.`), "update", "blob bucket", key);
+                                    }
+                                    const updatePayload = buildBlobBucketUpdatePayload(bucket);
+                                    let updated;
+                                    if (Object.keys(updatePayload).length > 0) {
+                                        // Surface an update failure via wrapEntityError (no
+                                        // stamp) — matches the cron adopt path.
+                                        try {
+                                            updated = await client.updateBlobBucket(resolvedAppId, existing.bucketId, updatePayload);
                                         }
+                                        catch (updateErr) {
+                                            throw wrapEntityError(updateErr, "update", "blob bucket", key);
+                                        }
+                                        info(`  Adopted + updated blob bucket: ${key}`);
+                                    }
+                                    else {
+                                        // No mutable fields in the local TOML — the server
+                                        // rejects an empty update (400). Adopt the existing
+                                        // bucket without a PATCH.
+                                        info(`  Adopted blob bucket (no updatable fields): ${key}`);
                                     }
-                                    catch {
-                                        // Ignore fetch errors
+                                    if (syncState) {
+                                        if (!syncState.entities.blobBuckets) {
+                                            syncState.entities.blobBuckets = {};
+                                        }
+                                        syncState.entities.blobBuckets[key] = {
+                                            id: existing.bucketId,
+                                            modifiedAt: updated?.modifiedAt ||
+                                                existing.modifiedAt ||
+                                                new Date().toISOString(),
+                                            contentHash: computeFileHash(filePath),
+                                        };
                                     }
                                 }
                                 else {
@@ -2774,6 +3746,19 @@ Directory Structure:
                     const workflow = tomlData.workflow || {};
                     const key = workflow.key || basename(file, ".toml");
                     const steps = tomlData.steps || [];
+                    // #1304 (P-C): the declared-access manifest lives at top-level
+                    // `[metadata]` / `secrets` (same shape the database/collection type
+                    // configs use). Parse + surface-validate it, then carry it on the
+                    // `workflow` payload object so it flows through both the create call
+                    // and the shared `applyWorkflowBody` update. A null manifest (no
+                    // `[metadata]`) clears it on the server so pull → push round-trips a
+                    // drop; the deep graph check runs server-side at persist.
+                    const workflowManifest = parseDeclaredAccessManifestToml(tomlData);
+                    const workflowManifestError = validateDeclaredAccessManifest(workflowManifest);
+                    if (workflowManifestError) {
+                        throw new Error(`${filePath}: ${workflowManifestError}`);
+                    }
+                    workflow.metadataManifest = workflowManifest;
                     const existingId = syncState?.entities?.workflows?.[key]?.id;
                     const existingActiveConfigId = syncState?.entities?.workflows?.[key]?.activeConfigId;
                     // Skip if file hasn't changed since last sync. Use the expanded
@@ -2805,80 +3790,17 @@ Directory Structure:
                     // out-of-manifest workflow).
                     const applyWorkflowUpdate = async (workflowId, opts) => {
                         const { expectedModifiedAt, activeConfigId } = opts;
-                        // Update workflow metadata and schemas.
-                        //
-                        // Sync-callable ordering (#807, codex review): the metadata
-                        // PATCH must NOT carry `syncCallable: true` here. The server
-                        // re-validates `syncCallable: true` against the workflow's
-                        // CURRENTLY-active server steps (`loadCurrentActiveSteps`),
-                        // not the steps being pushed in the same sync. So when a
-                        // single TOML edit both enables `syncCallable` and replaces
-                        // sync-incompatible active steps with compatible ones, a
-                        // combined metadata-first PATCH would be rejected against the
-                        // stale steps. Defer `syncCallable` to a second PATCH issued
-                        // AFTER the config/step update lands, so it validates against
-                        // the new (compatible) active steps. `requiresClientApply`
-                        // has no step-dependent validation, so it stays in the first
-                        // PATCH unchanged.
-                        const updated = await client.updateWorkflow(resolvedAppId, workflowId, {
-                            name: workflow.name,
-                            description: workflow.description,
-                            status: workflow.status,
-                            accessRule: workflow.accessRule !== undefined ? (workflow.accessRule || null) : undefined,
-                            // #1081 — workflow principal mode. Absent key → undefined
-                            // (server leaves it untouched); explicit value/empty is
-                            // forwarded so it round-trips.
-                            runAs: workflow.runAs !== undefined ? (workflow.runAs || null) : undefined,
-                            perUserMaxRunning: workflow.perUserMaxRunning,
-                            perUserMaxQueued: workflow.perUserMaxQueued,
-                            dequeueOrder: workflow.dequeueOrder,
-                            // Sync-callable flags (#807): pass through as-is. An absent
-                            // TOML key is `undefined` (dropped by JSON.stringify, so the
-                            // server's hasOwnProperty guard leaves the value untouched);
-                            // an explicit `false` is preserved as a meaningful value.
-                            requiresClientApply: workflow.requiresClientApply,
-                            inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
-                            outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : null,
-                        }, expectedModifiedAt);
-                        // Track the latest workflow `modifiedAt` for the sync-state
-                        // write below. The first PATCH bumps it; the `syncCallable`
-                        // PATCH (if any) bumps it again. The config/step update does
-                        // NOT touch the workflow definition's `modifiedAt`.
-                        let latestModifiedAt = updated?.workflow?.modifiedAt;
-                        // Update active configuration steps (or draft for legacy).
-                        // Issue #687: name the slot we touched so the dev-loop
-                        // user can confirm before previewing.
-                        let updateSlotLabel = "active config";
-                        if (activeConfigId) {
-                            await client.updateWorkflowConfig(resolvedAppId, workflowId, activeConfigId, {
-                                steps,
-                            });
-                        }
-                        else {
-                            // Fallback to draft update for legacy workflows
-                            await client.updateWorkflowDraft(resolvedAppId, workflowId, {
-                                steps,
-                                inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
-                            });
-                            updateSlotLabel = "draft (legacy)";
-                        }
-                        // Second PATCH: apply `syncCallable` now that the new steps
-                        // are active (#807). Only sent when the TOML actually carries
-                        // the key — an absent key stays `undefined` and we skip the
-                        // call entirely, preserving the no-clobber discipline. Chain
-                        // `expectedModifiedAt` off the first PATCH's returned value so
-                        // optimistic concurrency stays intact (the step update above
-                        // doesn't change the workflow definition's `modifiedAt`).
-                        if (workflow.syncCallable !== undefined) {
-                            const syncCallableUpdated = await client.updateWorkflow(resolvedAppId, workflowId, { syncCallable: workflow.syncCallable }, 
-                            // Mirror the first PATCH's concurrency posture: `--force`
-                            // skips the check (undefined), otherwise reuse the fresh
-                            // `modifiedAt` from the first PATCH.
-                            options.force ? undefined : latestModifiedAt);
-                            if (syncCallableUpdated?.workflow?.modifiedAt) {
-                                latestModifiedAt = syncCallableUpdated.workflow.modifiedAt;
-                            }
-                        }
+                        // The ordering-sensitive core (metadata PATCH → config/draft
+                        // steps → deferred `syncCallable` PATCH, #807) lives in the
+                        // shared `applyWorkflowBody` helper so `workflows update
+                        // --from-file` runs it identically (#1249, Fork 4). The
+                        // sync-specific bookkeeping (the progress log, sync-state
+                        // `modifiedAt`/hash, and config name→ID map) stays here.
+                        const { latestModifiedAt, updateSlotLabel, fullWorkflow } = await applyWorkflowBody(client, resolvedAppId, workflowId, workflow, steps, {
+                            expectedModifiedAt,
+                            activeConfigId,
+                            force: options.force,
+                        });
                         info(`  Updated workflow: ${key} (${updateSlotLabel})`);
                         // Update sync state with new modifiedAt. Store the *expanded*
                         // content hash so future fragment-only edits are detected. The
@@ -2888,9 +3810,8 @@ Directory Structure:
                             syncState.entities.workflows[key].modifiedAt = latestModifiedAt;
                             syncState.entities.workflows[key].contentHash = computeExpandedContentHash(tomlData);
                         }
-                        // Fetch full workflow to get config name→ID mappings
-                        // (updateWorkflow response doesn't include configs)
-                        const fullWorkflow = await client.getWorkflow(resolvedAppId, workflowId);
+                        // `applyWorkflowBody` already fetched the full workflow; reuse it
+                        // for the config name→ID mappings (the PATCH response omits configs).
                         if (fullWorkflow?.configs) {
                             for (const config of fullWorkflow.configs) {
                                 workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
@@ -2930,25 +3851,22 @@ Directory Structure:
                         changes.push({ type: "workflow", action: "create", key });
                         if (!options.dryRun) {
                             try {
+                                // #1177: build the `[workflow]`-derived fields through the
+                                // shared builder so `sync push` create can't drift from
+                                // `create --from-file` / the update path (this branch used to
+                                // drop `status`, `capabilities`, `perAppMax*`, `queueTtlSeconds`).
+                                // Structural fields (`workflowKey`, `steps`, `metadataManifest`)
+                                // and the manifest-key `name` fallback are attached here; the
+                                // `name` override follows the spread so it wins over the
+                                // builder's bare `name`.
                                 const created = await client.createWorkflow(resolvedAppId, {
                                     workflowKey: key,
-                                    name: workflow.name || key,
-                                    description: workflow.description,
                                     steps,
-                                    inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : undefined,
-                                    outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : undefined,
-                                    accessRule: workflow.accessRule || undefined,
-                                    // #1081 — workflow principal mode (absent → server default).
-                                    runAs: workflow.runAs || undefined,
-                                    perUserMaxRunning: workflow.perUserMaxRunning,
-                                    perUserMaxQueued: workflow.perUserMaxQueued,
-                                    dequeueOrder: workflow.dequeueOrder,
-                                    // Sync-callable flags (#807): pass through as-is. An absent
-                                    // TOML key is `undefined` (dropped by JSON.stringify), so the
-                                    // server applies its defaults (requiresClientApply=true,
-                                    // syncCallable=false); an explicit value is honored.
-                                    requiresClientApply: workflow.requiresClientApply,
-                                    syncCallable: workflow.syncCallable,
+                                    ...buildWorkflowPayloadFromToml(workflow, { mode: "create" }),
+                                    name: workflow.name || key,
+                                    // #1304 (P-C): declared-access manifest (absent → undefined,
+                                    // server default null).
+                                    metadataManifest: workflow.metadataManifest ?? undefined,
                                 });
                                 info(`  Created workflow: ${key}`);
                                 // Add new entity to sync state (including activeConfigId)
@@ -3214,6 +4132,14 @@ Directory Structure:
                         if ("timestamps" in typeConfig) {
                             u.timestamps = typeConfig.timestamps || null;
                         }
+                        // Issue #1304 (P-C): declared-access manifest. `parseDatabaseTypeToml`
+                        // only sets `metadataManifest` when the TOML declares a `[metadata]`
+                        // / `secrets` block, so this forwards a set/update; clearing a
+                        // manifest by removing the block is a follow-on (mirrors the
+                        // schema-deletion tracking).
+                        if ("metadataManifest" in typeConfig) {
+                            u.metadataManifest = typeConfig.metadataManifest || null;
+                        }
                         const localHasSchema = typeof typeConfig.schema === "string" &&
                             typeConfig.schema.trim().length > 0;
                         if (localHasSchema) {
@@ -3583,7 +4509,8 @@ Directory Structure:
                                 "defaultAccess" in typeConfig ||
                                 "autoPopulatedFields" in typeConfig ||
                                 "timestamps" in typeConfig ||
-                                "schema" in typeConfig;
+                                "schema" in typeConfig ||
+                                "metadataManifest" in typeConfig;
                             if (wouldUpdate) {
                                 changes.push({ type: "database-type", action: "update", key: dbType });
                             }
@@ -3616,6 +4543,9 @@ Directory Structure:
                             // validating against the intended shape.
                             if (typeConfig.schema)
                                 createData.schema = typeConfig.schema;
+                            // Issue #1304 (P-C): declared-access manifest.
+                            if (typeConfig.metadataManifest)
+                                createData.metadataManifest = typeConfig.metadataManifest;
                             try {
                                 const created = await client.createDatabaseTypeConfig(resolvedAppId, createData);
                                 info(`  Created database type: ${dbType}`);
@@ -4072,6 +5002,10 @@ Directory Structure:
                                 const updated = await client.updateGroupTypeConfig(resolvedAppId, groupType, {
                                     ruleSetId: configData.ruleSetId,
                                     autoAddCreator: configData.autoAddCreator,
+                                    // Issue #1350: null clears the manifest server-side when
+                                    // the TOML drops the `[metadata]` block (matches the
+                                    // collection type config update semantics).
+                                    metadataManifest: configData.metadataManifest ?? null,
                                 }, expectedModifiedAt);
                                 info(`  Updated group type config: ${groupType}`);
                                 if (syncState?.entities?.groupTypeConfigs?.[groupType] && updated?.modifiedAt) {
@@ -4103,6 +5037,9 @@ Directory Structure:
                                     groupType,
                                     ruleSetId: configData.ruleSetId || undefined,
                                     autoAddCreator: configData.autoAddCreator,
+                                    ...(configData.metadataManifest
+                                        ? { metadataManifest: configData.metadataManifest }
+                                        : {}),
                                 });
                                 info(`  Created group type config: ${groupType}`);
                                 if (syncState) {
@@ -4149,6 +5086,7 @@ Directory Structure:
                             try {
                                 const updated = await client.updateCollectionTypeConfig(resolvedAppId, collectionType, {
                                     ruleSetId: configData.ruleSetId ?? null,
+                                    metadataManifest: configData.metadataManifest ?? null,
                                 }, expectedModifiedAt);
                                 info(`  Updated collection type config: ${collectionType}`);
                                 if (syncState?.entities?.collectionTypeConfigs?.[collectionType] && updated?.modifiedAt) {
@@ -4179,6 +5117,9 @@ Directory Structure:
                                 const created = await client.createCollectionTypeConfig(resolvedAppId, {
                                     collectionType,
                                     ruleSetId: configData.ruleSetId || undefined,
+                                    ...(configData.metadataManifest
+                                        ? { metadataManifest: configData.metadataManifest }
+                                        : {}),
                                 });
                                 info(`  Created collection type config: ${collectionType}`);
                                 if (syncState) {
@@ -4198,6 +5139,69 @@ Directory Structure:
                     }
                 }
             }
+            // Process metadata category configs (issue #1304, P-B). Idempotent
+            // upsert via the path-addressed PUT route — no create/update split.
+            const metadataCategoryConfigsDir = join(configDir, "metadata-category-configs");
+            if (existsSync(metadataCategoryConfigsDir)) {
+                const files = readdirSync(metadataCategoryConfigsDir).filter((f) => f.endsWith(".toml"));
+                for (const file of files) {
+                    const filePath = join(metadataCategoryConfigsDir, file);
+                    const tomlData = parseTomlFile(filePath);
+                    const configData = parseMetadataCategoryToml(tomlData);
+                    // Fall back to the filename (`resourceType.category.toml`) if the
+                    // section omits the identity fields.
+                    if (!configData.resourceType || !configData.category) {
+                        const base = basename(file, ".toml");
+                        const dot = base.indexOf(".");
+                        if (dot > 0) {
+                            configData.resourceType = configData.resourceType || base.slice(0, dot);
+                            configData.category = configData.category || base.slice(dot + 1);
+                        }
+                    }
+                    const validationError = validateMetadataCategoryConfig(configData);
+                    if (validationError) {
+                        throw new Error(`Invalid metadata category config in ${file}: ${validationError}`);
+                    }
+                    const entityKey = `${configData.resourceType}#${configData.category}`;
+                    const existingEntry = syncState?.entities?.metadataCategoryConfigs?.[entityKey];
+                    // Skip if the file hasn't changed since last sync.
+                    if (!options.force && existingEntry && !shouldPushFile(filePath, existingEntry.contentHash)) {
+                        skippedCount++;
+                        continue;
+                    }
+                    changes.push({
+                        type: "metadata-category-config",
+                        action: existingEntry ? "update" : "create",
+                        key: entityKey,
+                    });
+                    if (!options.dryRun) {
+                        try {
+                            const saved = await client.upsertMetadataCategoryConfig(resolvedAppId, configData.resourceType, configData.category, {
+                                schema: configData.schema,
+                                readRule: configData.readRule,
+                                writeRule: configData.writeRule,
+                                description: configData.description,
+                                // #1420 Phase 2: send the declared-access manifest so a
+                                // category's md.self/secrets access round-trips through sync.
+                                metadataManifest: configData.metadataManifest,
+                            });
+                            info(`  Upserted metadata category config: ${entityKey}`);
+                            if (syncState) {
+                                if (!syncState.entities.metadataCategoryConfigs) {
+                                    syncState.entities.metadataCategoryConfigs = {};
+                                }
+                                syncState.entities.metadataCategoryConfigs[entityKey] = {
+                                    modifiedAt: saved?.modifiedAt || new Date().toISOString(),
+                                    contentHash: computeFileHash(filePath),
+                                };
+                            }
+                        }
+                        catch (err) {
+                            throw wrapEntityError(err, existingEntry ? "update" : "create", "metadata category config", entityKey);
+                        }
+                    }
+                }
+            }
             // Process email templates
             const emailTemplatesDir = join(configDir, "email-templates");
             if (existsSync(emailTemplatesDir)) {
@@ -4234,11 +5238,13 @@ Directory Structure:
                     }
                 }
             }
-            // Push test cases for prompts and workflows
+            // Push test cases for prompts, workflows, and scripts
+            const scriptConfigNameToId = new Map(); // "scriptName#configName" → configId
             const pushMaps = {
                 promptKeyToId,
                 promptConfigNameToId,
                 workflowConfigNameToId,
+                scriptConfigNameToId,
             };
             const promptsDir2 = join(configDir, "prompts");
             if (existsSync(promptsDir2)) {
@@ -4262,6 +5268,33 @@ Directory Structure:
                     }
                 }
             }
+            // Push test cases for scripts (transforms). Each script's tests live at
+            // transforms/<name>.tests/; the scriptId was recorded in
+            // entities.scripts[name].id when the script body was pushed above.
+            const transformsDir2 = join(configDir, "transforms");
+            if (existsSync(transformsDir2)) {
+                for (const file of readdirSync(transformsDir2).filter((f) => f.endsWith(".rhai"))) {
+                    const scriptName = basename(file, ".rhai");
+                    const blockId = syncState?.entities?.scripts?.[scriptName]?.id;
+                    if (!blockId)
+                        continue;
+                    const scriptTestsDir = join(transformsDir2, `${scriptName}.tests`);
+                    if (!existsSync(scriptTestsDir))
+                        continue;
+                    // Populate scriptConfigNameToId for this script so a test case that
+                    // pins a config by name resolves to a live configId.
+                    try {
+                        const { items: scriptConfigs } = await client.listScriptConfigs(resolvedAppId, blockId);
+                        for (const config of scriptConfigs) {
+                            scriptConfigNameToId.set(`${scriptName}#${config.configName}`, config.configId);
+                        }
+                    }
+                    catch {
+                        // Non-fatal — unpinned (active-version) test cases still push.
+                    }
+                    skippedCount += await pushTestCasesForBlock(client, resolvedAppId, "script", blockId, scriptName, configDir, syncState, options.dryRun, changes, pushMaps, { force: options.force });
+                }
+            }
             divider();
             // Issue #813: a gate failure surfaced by the validate-first pass (which
             // also runs in dry-run mode via the server's dry-run gate endpoints).
@@ -4499,6 +5532,31 @@ Directory Structure:
                     localScripts.set(name, readFileSync(join(transformsDirPath, file), "utf-8"));
                 }
             }
+            // Config vars — issue #1423. Before this, `sync diff` ignored vars
+            // entirely, so an add/remove/value-drift between the local `vars.toml`
+            // and the server silently read as no difference right before a push
+            // would change or unset them. Fetch the remote vars (value included —
+            // vars are non-secret) and read the local `vars.toml` so the comparison
+            // below can report added/removed/modified vars.
+            let remoteVarItemsDiff = [];
+            try {
+                remoteVarItemsDiff = await client.listAppConfigVars(resolvedAppId);
+            }
+            catch {
+                // Older server without the vars route — treat as no remote vars.
+            }
+            const remoteVars = new Map(remoteVarItemsDiff
+                .filter((v) => typeof v?.key === "string")
+                .map((v) => [v.key, String(v.value ?? "")]));
+            const localVars = new Map();
+            const varsTomlPathDiff = join(configDir, "vars.toml");
+            if (existsSync(varsTomlPathDiff)) {
+                const parsed = parseTomlFile(varsTomlPathDiff);
+                for (const [key, rawValue] of Object.entries(parsed)) {
+                    if (typeof rawValue === "string")
+                        localVars.set(key, rawValue);
+                }
+            }
             // Compare
             const differences = [];
             // Integrations
@@ -4703,6 +5761,10 @@ Directory Structure:
                     differences.push({ type: "transform", key: name, status: "remote only" });
                 }
             }
+            // Config vars — issue #1423 (see `diffVars`).
+            for (const row of diffVars(localVars, remoteVars)) {
+                differences.push(row);
+            }
             // Compare test cases for synced prompts and workflows
             const testCaseDiffs = [];
             // Helper to compare test cases for a block
@@ -4823,11 +5885,15 @@ Directory Structure:
     // Migrate-toml (issue #752): bulk-rewrite database-type TOML files from
     // the legacy JSON-string form for `definition`/`params` to the native
     // nested-table form. Idempotent: ops already in native form are left as
-    // is; ops that are un-TOMLable (mixed-type arrays, null values) fall
-    // back to JSON-string per field with a log message.
+    // is; the round-trip serializes with smol-toml (TOML 1.0, issue #1450), so
+    // heterogeneous arrays now converge to native form too — only shapes that
+    // TOML can't represent without data loss (null / undefined / an array
+    // containing null) fall back to JSON-string per field with a log message.
     sync
         .command("migrate-toml")
-        .description("Rewrite database-type TOML files to native [operations.definition] / [[operations.params]] form")
+        .description("Rewrite database-type and workflow TOML files to native form " +
+        "([operations.definition] / [[operations.params]] for database types; " +
+        "[workflow.inputSchema] / [workflow.outputSchema] for workflows)")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
         .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
@@ -4846,83 +5912,122 @@ Directory Structure:
             process.exit(1);
         }
         const dbTypesDir = join(configDir, "database-types");
-        if (!existsSync(dbTypesDir)) {
-            info("No database-types/ directory found; nothing to migrate.");
+        const workflowsDir = join(configDir, "workflows");
+        const dbFiles = existsSync(dbTypesDir)
+            ? readdirSync(dbTypesDir).filter((f) => f.endsWith(".toml"))
+            : [];
+        const workflowFiles = existsSync(workflowsDir)
+            ? readdirSync(workflowsDir).filter((f) => f.endsWith(".toml"))
+            : [];
+        // Restructured early-return (issue #1446): don't bail just because
+        // `database-types/` is absent — a workflow-only project still has
+        // `inputSchema`/`outputSchema` to migrate.
+        if (dbFiles.length === 0 && workflowFiles.length === 0) {
+            info("No database-type or workflow TOML files found; nothing to migrate.");
             return;
         }
-        const files = readdirSync(dbTypesDir).filter((f) => f.endsWith(".toml"));
-        if (files.length === 0) {
-            info("No database-type TOML files found; nothing to migrate.");
-            return;
-        }
-        // Hydrate ruleSetIdToName from local sync state so files that
-        // reference a rule set via the legacy `ruleSetId = "01..."` form
-        // round-trip with the correct `ruleSetName`. Without this, any user
-        // who runs migrate-toml against a file with a rule-set assignment
-        // would silently lose that reference (review feedback r3246633010).
-        //
-        // Files that use the modern key-based `ruleSetName = "..."` form
-        // don't need the map at all — `parseDatabaseTypeToml` stores the
-        // value in `typeConfig._ruleSetName` and the serializer now prefers
-        // that. The map is only load-bearing for the legacy ID-based form.
-        const ruleSetIdToName = new Map();
-        const migrateSyncState = loadSyncState(configDir);
-        if (migrateSyncState?.entities?.ruleSets) {
-            for (const [fileKey, entry] of Object.entries(migrateSyncState.entities.ruleSets)) {
-                if (entry && typeof entry === "object" && "id" in entry && entry.id) {
-                    // fileKey is the sanitized rule-set name (see sync pull at
-                    // sync.ts:1385). It's the same shape the server returned and
-                    // matches what a TOML file's ruleSetName field would carry.
-                    ruleSetIdToName.set(entry.id, fileKey);
-                }
-            }
-        }
         let migratedCount = 0;
         let unchangedCount = 0;
-        for (const file of files) {
-            const filePath = join(dbTypesDir, file);
-            const rawBefore = readFileSync(filePath, "utf-8");
-            const tomlData = parseTomlFile(filePath);
-            // `accessRule`/`access` conflicts surface as a clear error here too,
-            // rather than silently dropping the field during a migrate rewrite.
-            let typeConfig;
-            let operations;
-            let subscriptions;
-            try {
-                ({ typeConfig, operations, subscriptions } =
-                    parseDatabaseTypeToml(tomlData));
+        // ---- database-types/ pass ----
+        if (dbFiles.length > 0) {
+            // Hydrate ruleSetIdToName from local sync state so files that
+            // reference a rule set via the legacy `ruleSetId = "01..."` form
+            // round-trip with the correct `ruleSetName`. Without this, any user
+            // who runs migrate-toml against a file with a rule-set assignment
+            // would silently lose that reference (review feedback r3246633010).
+            //
+            // Files that use the modern key-based `ruleSetName = "..."` form
+            // don't need the map at all — `parseDatabaseTypeToml` stores the
+            // value in `typeConfig._ruleSetName` and the serializer now prefers
+            // that. The map is only load-bearing for the legacy ID-based form.
+            const ruleSetIdToName = new Map();
+            const migrateSyncState = loadSyncState(configDir);
+            if (migrateSyncState?.entities?.ruleSets) {
+                for (const [fileKey, entry] of Object.entries(migrateSyncState.entities.ruleSets)) {
+                    if (entry && typeof entry === "object" && "id" in entry && entry.id) {
+                        // fileKey is the sanitized rule-set name (see sync pull at
+                        // sync.ts:1385). It's the same shape the server returned and
+                        // matches what a TOML file's ruleSetName field would carry.
+                        ruleSetIdToName.set(entry.id, fileKey);
+                    }
+                }
             }
-            catch (err) {
-                if (err instanceof SubscriptionAccessKeyConflictError) {
-                    error(`  ${file}: ${err.message}`);
-                    error(`Aborting migrate-toml: subscription \`access\`/\`accessRule\` conflict in ${file}.`);
-                    process.exit(1);
+            for (const file of dbFiles) {
+                const filePath = join(dbTypesDir, file);
+                const rawBefore = readFileSync(filePath, "utf-8");
+                const tomlData = parseTomlFile(filePath);
+                // `accessRule`/`access` conflicts surface as a clear error here too,
+                // rather than silently dropping the field during a migrate rewrite.
+                let typeConfig;
+                let operations;
+                let subscriptions;
+                try {
+                    ({ typeConfig, operations, subscriptions } =
+                        parseDatabaseTypeToml(tomlData));
                 }
-                throw err;
+                catch (err) {
+                    if (err instanceof SubscriptionAccessKeyConflictError) {
+                        error(`  ${file}: ${err.message}`);
+                        error(`Aborting migrate-toml: subscription \`access\`/\`accessRule\` conflict in ${file}.`);
+                        process.exit(1);
+                    }
+                    throw err;
+                }
+                // Force-native: ignore existing hints so every TOMLable field
+                // ends up in nested-table form. Subscriptions are preserved on the
+                // rewrite (issue #803) so migrate-toml never drops them.
+                const rewritten = serializeDatabaseType(typeConfig, operations, ruleSetIdToName, {
+                    defaultForm: "native",
+                    logger: (msg) => info(`  ${msg}`),
+                    subscriptions,
+                });
+                if (rewritten === rawBefore) {
+                    unchangedCount++;
+                    continue;
+                }
+                if (options.dryRun) {
+                    info(`Would migrate database-types/${file}`);
+                }
+                else {
+                    writeFileSync(filePath, rewritten);
+                    info(`Migrated database-types/${file}`);
+                    // Update content hash in sync state if we have an entry for it.
+                    const syncState = loadSyncState(configDir);
+                    const dbType = typeConfig.databaseType || basename(file, ".toml");
+                    if (syncState?.entities?.databaseTypes?.[dbType]) {
+                        syncState.entities.databaseTypes[dbType].contentHash = computeFileHash(filePath);
+                        saveSyncState(configDir, syncState);
+                    }
+                }
+                migratedCount++;
             }
-            // Force-native: ignore existing hints so every TOMLable field
-            // ends up in nested-table form. Subscriptions are preserved on the
-            // rewrite (issue #803) so migrate-toml never drops them.
-            const rewritten = serializeDatabaseType(typeConfig, operations, ruleSetIdToName, {
-                defaultForm: "native",
-                logger: (msg) => info(`  ${msg}`),
-                subscriptions,
-            });
-            if (rewritten === rawBefore) {
+        }
+        // ---- workflows/ pass (issue #1446) ----
+        // Convert string-form `inputSchema`/`outputSchema` to native tables.
+        // Purely local, mirroring the database-types pass. The stored workflow
+        // hash uses `computeExpandedContentHash` (parse then hash), NOT
+        // `computeFileHash`, matching the workflow convention on the pull/push
+        // paths — otherwise a push after migrate would spuriously re-push.
+        for (const file of workflowFiles) {
+            const filePath = join(workflowsDir, file);
+            const rawBefore = readFileSync(filePath, "utf-8");
+            const workflowKey = basename(file, ".toml");
+            const { content: rewritten, changed } = rewriteWorkflowSchemasToNative(rawBefore, workflowKey, (msg) => info(`  ${msg}`));
+            if (!changed) {
                 unchangedCount++;
                 continue;
             }
             if (options.dryRun) {
-                info(`Would migrate database-types/${file}`);
+                info(`Would migrate workflows/${file}`);
             }
             else {
                 writeFileSync(filePath, rewritten);
-                info(`Migrated database-types/${file}`);
-                // Update content hash in sync state if we have an entry for it.
+                info(`Migrated workflows/${file}`);
+                // Update the stored content hash so a subsequent push sees a no-op.
                 const syncState = loadSyncState(configDir);
-                const dbType = typeConfig.databaseType || basename(file, ".toml");
-                if (syncState?.entities?.databaseTypes?.[dbType]) {
-                    syncState.entities.databaseTypes[dbType].contentHash = computeFileHash(filePath);
+                if (syncState?.entities?.workflows?.[workflowKey]) {
+                    syncState.entities.workflows[workflowKey].contentHash =
+                        computeExpandedContentHash(parseTomlFile(filePath));
                     saveSyncState(configDir, syncState);
                 }
             }
@@ -4938,6 +6043,63 @@ Directory Structure:
             success(`Rewrote ${migratedCount} TOML file(s) to native form.`);
         }
     });
+    // migrate-v2 — convert a legacy sync directory into the unified block
+    // layout `blocks/<type>/<key>/block.toml` (issue #1183, Phase 3). Purely
+    // local: it reads already-pulled legacy files and writes the v2 tree. The
+    // legacy files are left in place (legacy stays the default until v2 is
+    // proven), so re-running push/pull is unaffected.
+    sync
+        .command("migrate-v2")
+        .description("Convert legacy per-type sync files (prompts/, integrations/, workflows/, transforms/) into the v2 blocks/<type>/<key>/block.toml layout")
+        .argument("[app-id]", "App ID (uses current app if not specified)")
+        .option("--app <app-id>", "App ID")
+        .option("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
+        .option("--dry-run", "Show what would change without writing files")
+        .option("--force", "Overwrite existing block.toml files instead of skipping them")
+        .action(async (appId, options) => {
+        // Resolve appId so we land in the per-env sync dir even when the user
+        // didn't pass `--dir`. The app ID itself isn't used for any API calls —
+        // migrate-v2 is a purely local rewrite (like migrate-toml).
+        const resolvedAppId = resolveAppId(appId, options);
+        const configDir = resolveSyncDir({ appId: resolvedAppId, userDir: options.dir });
+        if (isAutoResolvedSyncDir(options.dir)) {
+            info(`Using per-environment sync directory: ${configDir}`);
+        }
+        if (!existsSync(configDir)) {
+            error(`Config directory not found: ${configDir}`);
+            process.exit(1);
+        }
+        const before = detectLayout(configDir);
+        if (!before.legacy) {
+            info("No legacy block files found (prompts/, integrations/, workflows/, transforms/); nothing to migrate.");
+            return;
+        }
+        const result = migrateLegacyToV2(configDir, {
+            dryRun: options.dryRun,
+            force: options.force,
+        });
+        for (const b of result.blocks) {
+            const suffix = b.testsCopied > 0 ? ` (+${b.testsCopied} test case(s))` : "";
+            if (options.dryRun) {
+                info(`Would write blocks/${b.type === "script" ? "scripts" : b.type + "s"}/${b.key}/block.toml${suffix}`);
+            }
+            else {
+                info(`Wrote blocks/${b.type === "script" ? "scripts" : b.type + "s"}/${b.key}/block.toml${suffix}`);
+            }
+        }
+        for (const s of result.skipped) {
+            warn(`Skipped ${s.type}/${s.key}: ${s.reason}`);
+        }
+        divider();
+        keyValue("Migrated", result.blocks.length);
+        keyValue("Skipped", result.skipped.length);
+        if (options.dryRun) {
+            info("Dry-run only — no files were modified.");
+        }
+        else if (result.blocks.length > 0) {
+            success(`Converted ${result.blocks.length} block(s) to the v2 layout. Legacy files were left in place.`);
+        }
+    });
     // Revert — restore a pre-pull snapshot (issue #578, Phase 1).
     sync
         .command("revert")