@wtfalch/foundry 0.3.0 → 0.5.0

package/dist/plan/executor.js

@@ -1,5 +1,9 @@
 import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
+import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
+import { AGORA_CLIENT_ID_SCOPE_KEY, agoraHostnameFor, desiredAgoraEnv, } from './agora.js';
+import { MAS_IMAGE, SYNAPSE_IMAGE, SYNAPSE_TAG, callsMasConfigYaml, callsServerName, callsSynapseHomeserverYaml, mintCallsMatrixSecrets, parseCallsDbUrl, } from './calls-matrix.js';
+import { ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, } from './platform-diff.js';
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -32,14 +36,30 @@ function hostnameFor(org) {
 }
 /**
  * `cms.<domain>` -- the cms studio's own hostname (`cmsSite` below), apart
- * from the public site itself at `org.domain` (used directly there). Only
- * ever called from `cmsSite`, which only ever runs once `org.site.enabled`
- * is true, so `org.domain` is non-null by the same `validateSite` guarantee
+ * from the public site itself at `org.domain` (used directly there). Called
+ * from `cmsSite` and from `zitadelApp` for the fixed `cms` client (#139),
+ * both of which only run once `org.site.enabled` is true, so `org.domain`
+ * is non-null by the same `validateSite` guarantee
  * {@link tunnelIngressHostnames}'s own doc comment cites.
  */
 function cmsHostnameFor(org) {
     return `cms.${org.domain}`;
 }
+/**
+ * #145's "Decided" (2026-09-27): the calls service's own public hostname.
+ * `calls.usesDomain: false` (or no `domain`) is served flat, like
+ * `<slug>-stage.oikos.host` and `<slug>-pr-<n>.oikos.host` (`../slug.ts`) --
+ * the shared tunnel's wildcard `*.oikos.host` DNS record already reaches it,
+ * so nothing changes in `scripts/shared-ingress.mjs`. `calls.usesDomain: true`
+ * gets `calls.<domain>` instead, on its own per-org tunnel
+ * ({@link tunnelIngressHostnames}), the same subdomain-of-the-org's-own-domain
+ * shape {@link cmsHostnameFor} uses for `cms.<domain>`.
+ */
+function callsHostnameFor(org) {
+    return org.calls.usesDomain && org.domain
+        ? `calls.${org.domain}`
+        : `${org.slug}-calls.oikos.host`;
+}
 /**
  * The hostnames `cloudflareTunnel` routes to `COOLIFY_PROXY_ORIGIN`
  * (https://github.com/wtfalch/foundry/issues/115). A site-enabled org
@@ -51,11 +71,24 @@ function cmsHostnameFor(org) {
  * concretely a hosting org, whose one app hostname this served before #115
  * ever existed -- keeps exactly the prior single-hostname behavior
  * ({@link hostnameFor}), unchanged.
+ *
+ * #145: an own-domain calls service adds `calls.<domain>` on top of whichever
+ * of those a site/hosting org already gets, since calls can run alongside
+ * either (or neither).
  */
 function tunnelIngressHostnames(org) {
-    if (org.site.enabled && org.domain)
-        return [org.domain, `cms.${org.domain}`];
-    return [hostnameFor(org)];
+    const hostnames = org.site.enabled && org.domain ? [org.domain, `cms.${org.domain}`] : [hostnameFor(org)];
+    if (org.calls.enabled && org.calls.usesDomain && org.domain) {
+        hostnames.push(`calls.${org.domain}`);
+    }
+    // #164: Agora always moves onto `agora.<domain>` once `org.domain` is set
+    // -- no toggle to gate this on. A level-1 org (no domain) adds nothing
+    // here: `<slug>-agora.oikos.host` rides the shared `*.oikos.host` wildcard
+    // tunnel (`scripts/shared-ingress.mjs`), not a per-org tunnel.
+    if (org.domain) {
+        hostnames.push(agoraHostnameFor(org));
+    }
+    return hostnames;
 }
 /**
  * The health URLs an outside prober should call for this org (#43): one per
@@ -97,7 +130,7 @@ function mailOrgFor(org, usesDomain, mode) {
  */
 const COOLIFY_PROXY_ORIGIN = 'http://coolify-proxy:80';
 /** The one Access policy foundry puts on its own Access app (#84). */
-const ACCESS_POLICY_NAME = 'foundry: allowed emails';
+export const ACCESS_POLICY_NAME = 'foundry: allowed emails';
 /**
  * The sign-in broker's own route mount (`@wtfalch/auth`'s `NextAuth`,
  * `dist/next.d.ts`'s `handlers` doc comment: "`export const { GET, POST } =
@@ -141,8 +174,15 @@ const RATE_LIMIT_REQUESTS_PER_PERIOD = 10;
  * org declares none of its own — the repo may not exist yet at decision
  * time, and Coolify's own GitHub App create call is what will fail loudly
  * against it, the same as any other repo name that does not exist.
+ *
+ * Hestia moved into this repo's own `apps/hestia` (estate DECISIONS.md,
+ * 2026-09-28; the hestia repo archives once this move lands), so the
+ * standard app now builds from foundry's own repo, told apart from
+ * `packages/foundry` by `dockerfile_location` — the same one-repo,
+ * multiple-apps shape `cmsSite`/`CMS_APP_DOCKERFILE` already use below.
  */
-const DEFAULT_APP_REPO = 'wtfalch/hestia';
+const DEFAULT_APP_REPO = 'wtfalch/foundry';
+const DEFAULT_APP_DOCKERFILE = 'apps/hestia/Dockerfile';
 /**
  * The one repo `cmsSite` builds both of its apps from
  * (https://github.com/wtfalch/cms) -- the 2026-09-25 decision this campaign
@@ -156,6 +196,25 @@ const DEFAULT_APP_REPO = 'wtfalch/hestia';
 const CMS_REPO = 'wtfalch/cms';
 const CMS_APP_DOCKERFILE = 'Dockerfile';
 const CMS_SITE_APP_DOCKERFILE = 'apps/site/Dockerfile';
+/**
+ * #164: the repo `coolifyAgora` builds the org's Agora from
+ * (https://github.com/wtfalch/agora) -- the issue's own "How" names this
+ * exact Dockerfile, and it is the only build strategy any app this file
+ * provisions ever uses ({@link DEFAULT_APP_DOCKERFILE}/{@link CMS_APP_DOCKERFILE}/
+ * `CALLS_SERVICE_DOCKERFILE` below are all `dockerfile_location` into a
+ * `createGithubAppApplication` build-from-repo call, never a registry
+ * image): "Coolify builds each org's Agora from the agora repo" is not a
+ * fresh product choice here, it is this file's one established convention,
+ * followed rather than reopened (#164 "Decide" 1). The agora repo's own
+ * Dockerfile (`apps/agora/Dockerfile`) already `EXPOSE`s 8080 and serves
+ * from a build built at the repository root, the same one-repo shape
+ * `CMS_REPO`'s own two apps use -- no `ports_exposes`/`PORT` env is needed
+ * the way `CALLS_SERVICE_PORT` is for the calls service's own Node process,
+ * since Coolify's github-app build already reads the exposed port the same
+ * way it does for `cmsSite`'s two apps above.
+ */
+const AGORA_REPO = 'wtfalch/agora';
+const AGORA_APP_DOCKERFILE = 'apps/agora/Dockerfile';
 /**
  * Every app foundry deploys keeps its own logs across a redeploy, so a
  * database outage does not also erase the only other copy of the evidence
@@ -168,9 +227,13 @@ const CMS_SITE_APP_DOCKERFILE = 'apps/site/Dockerfile';
  */
 const LOG_DIR = '/app/logs';
 /**
- * The one shared Stalwart apex and MX host every org's mail lives on (#7
- * "Mail"), the same values `@wtfalch/email`'s own README examples use for
- * `applyOrgMail`/`parkOrgMail`'s `OrgMailOptions`.
+ * #177: the fallback Stalwart apex and mail host `coolifyMail` uses when its
+ * own step carries none (`diff.ts`'s `planMail` always supplies one once a
+ * platform is wired -- `platform-org.ts`'s `DEFAULT_ORG_PLATFORM_READINESS`
+ * is this exact pair, so a host that has not wired `FoundryPlanApplyOptions.
+ * platform` yet keeps running on the address every org's mail always ran on
+ * before the platform existed to ask, the same values `@wtfalch/email`'s own
+ * README examples use for `applyOrgMail`/`parkOrgMail`'s `OrgMailOptions`).
  */
 const MAIL_APEX = 'wtfalch.dev';
 const MAIL_HOST = 'mail.wtfalch.dev';
@@ -185,6 +248,16 @@ const MAIL_HOST = 'mail.wtfalch.dev';
  * report).
  */
 const APP_CLIENT_ID_SCOPE_KEY = 'zitadel_app_client_id';
+/**
+ * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
+ * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the
+ * org's own hosted app (`diff.ts`'s `planIssuerApps`), a different
+ * `zitadel:app` step from the fixed `cms` client `diff.ts`'s `planCmsClient`
+ * plans. `cmsSite` reads this key to push `AUTH_CLIENT_ID` onto the cms app,
+ * the same way `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` for the hosted
+ * app.
+ */
+const CMS_CLIENT_ID_SCOPE_KEY = 'cms_client_id';
 /**
  * `cmsSite` provisions two applications from one `cms:site` step, but
  * `execute`'s own return value auto-records only one `resourceId`, under
@@ -210,6 +283,123 @@ const SITE_APP_SCOPE_KEY = 'coolify_site_app';
  * never collide with that form.
  */
 const CMS_DATABASE_SCOPE_KEY = 'coolify_cms_database';
+/**
+ * #138/#140 (2026-09-28 lettermint-org-mail swap): the mail domain
+ * `coolifyMail` resolved with Stalwart -- `org.domain` when the org uses its
+ * own domain, else `<slug>.<apex>` for a domainless org (2026-09-28:
+ * domainless orgs get their own Lettermint domain too). Recorded so the app
+ * step can derive `MAIL_FROM` and drive its own Lettermint domain/project
+ * work (`ensureAppLettermintMail`) without recomputing `mailOrgFor`'s own
+ * domain choice, the same way {@link APP_CLIENT_ID_SCOPE_KEY} carries a
+ * public value out. All of that org's Lettermint work -- ensure domain,
+ * restrict, publish DNS, verify -- now happens inside the same step that
+ * reads this key (`ensureAppLettermintMail`), so unlike the Resend design
+ * this rework replaces, no separate domain-id scope key is recorded: the
+ * domain is looked up by name fresh each apply. Renamed from
+ * `resend_mail_domain`.
+ */
+const MAIL_DOMAIN_SCOPE_KEY = 'mail_domain';
+/**
+ * #162: the owner's own mailbox, created once inside `coolify:mail` after
+ * `applyOrgMail` succeeds, alongside {@link MAIL_DOMAIN_SCOPE_KEY} -- another
+ * flat scope id for the same reason, no `:`. Recorded with the address
+ * itself (not just a boolean) so a future step could read it back the same
+ * way {@link MAIL_DOMAIN_SCOPE_KEY} lets `ensureAppLettermintMail` read the
+ * domain back; `ensureOwnerMailbox` only ever checks that this key is set at
+ * all before deciding whether to call `MailPort.createMailbox` again.
+ * `plan/diff.ts` keeps its own copy of this literal (`MAIL_OWNER_MAILBOX_SCOPE_KEY`
+ * there) rather than importing it, the same restated-not-shared rule this
+ * file's own `LOG_DIR` doc comment names for `diff.ts`.
+ */
+const MAIL_OWNER_MAILBOX_SCOPE_KEY = 'mail_owner_mailbox';
+/**
+ * #80: the id of an ai key `aiKey` has minted but not yet delivered, a flat
+ * scope id (no `:`). `plan/diff.ts` keeps its own copy of this literal.
+ */
+const AI_KEY_UNDELIVERED_SCOPE_KEY = 'ai_key_undelivered';
+/** How many times `aiKey` tries `deliverSecret` before giving up. */
+const AI_KEY_DELIVERY_ATTEMPTS = 3;
+/**
+ * #173: the id of a jobs project `jobsRegistration` has registered but not
+ * yet delivered the credentials of, a flat scope id (no `:`). `serviceIds` is
+ * already per org, so the key needs no org in it. `plan/diff.ts` keeps its own
+ * copy of this literal.
+ */
+const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = 'jobs_registration_undelivered';
+/** How many times `jobsRegistration` tries each `deliverSecret` before giving up. */
+const JOBS_DELIVERY_ATTEMPTS = 3;
+/**
+ * The one mailbox this executor mints on its own (#162) -- a plain,
+ * discoverable local part rather than anything derived from the owner's own
+ * (possibly personal) `email`, so it never collides with a name and never
+ * repeats a stranger's inbox back at them. #162's own "Decide" section
+ * leaves open whether every *other* person in the org also gets a mailbox
+ * from foundry, or only from Boule -- unresolved, on purpose, until a human
+ * picks one; this constant and {@link ensureOwnerMailbox} only ever cover
+ * the owner, which every candidate answer to that question already includes.
+ */
+const MAIL_OWNER_LOCAL_PART = 'owner';
+/**
+ * `coolifyCalls` provisions four resources from one `coolify:calls` step
+ * (#128) — the same one-step, several-resource shape `cmsSite` already solves
+ * with flat scope ids (`CMS_APP_SCOPE_KEY`/`SITE_APP_SCOPE_KEY`/
+ * `CMS_DATABASE_SCOPE_KEY`, that constant's own doc comment). This step's own
+ * auto-recorded `resourceId` (under `coolify:calls:<orgId>`) is the MAS app's
+ * id, the one every secret this stack mints lives on
+ * ({@link CALLS_SECRET_ENV_KEYS}); the other three get their own flat scope
+ * id here for the same reason CMS's site app and database do.
+ */
+const CALLS_SYNAPSE_SCOPE_KEY = 'coolify_calls_synapse';
+const CALLS_MAS_SCOPE_KEY = 'coolify_calls_mas';
+const CALLS_SYNAPSE_DB_SCOPE_KEY = 'coolify_calls_synapse_database';
+const CALLS_MAS_DB_SCOPE_KEY = 'coolify_calls_mas_database';
+/**
+ * Synapse refuses to start against a database whose `LC_COLLATE`/`LC_CTYPE`
+ * is not `C` (https://element-hq.github.io/synapse/latest/postgres.html);
+ * Coolify's official postgres image otherwise creates one with `en_US.utf8`.
+ * `postgres_initdb_args` is the only point this can be set -- it cannot be
+ * migrated onto an existing database. MAS has no such requirement, so this
+ * is passed for the Synapse database only. Not using Synapse's own
+ * `allow_unsafe_locale` escape hatch: that trades a loud startup refusal for
+ * silent index corruption after a future glibc upgrade.
+ */
+const CALLS_SYNAPSE_DB_INITDB_ARGS = '--locale=C --encoding=UTF8';
+/**
+ * `CallsMatrixSecrets`' six fields, held nowhere else once minted
+ * (`calls-matrix.ts`'s own doc comment: no `ctx.outputs` state file exists
+ * here) — pushed onto the MAS app's own envs purely as memory for the next
+ * apply, never read by MAS itself (MAS reads only its `config.yaml` file
+ * storage). `multiline: true` on the two PEM keys, the same flag
+ * `CoolifyPort.bulkUpsertEnvs` already carries for exactly this shape of
+ * value.
+ */
+const CALLS_SECRET_ENV_KEYS = {
+    masSynapseSharedSecret: 'CALLS_MATRIX_MAS_SYNAPSE_SHARED_SECRET',
+    masClientId: 'CALLS_MATRIX_MAS_CLIENT_ID',
+    masClientSecret: 'CALLS_MATRIX_MAS_CLIENT_SECRET',
+    masEncryptionKey: 'CALLS_MATRIX_MAS_ENCRYPTION_KEY',
+    masRsaKeyPem: 'CALLS_MATRIX_MAS_RSA_KEY_PEM',
+    masEcKeyPem: 'CALLS_MATRIX_MAS_EC_KEY_PEM',
+};
+/** `FROM ${MAS_IMAGE}` plus the entry command its published image needs (chat's own `MAS_DOCKERFILE`, same reason: no arguments by default). */
+const CALLS_MAS_DOCKERFILE = [
+    `FROM ${MAS_IMAGE}`,
+    'CMD ["server", "--config", "/config/config.yaml"]',
+].join('\n');
+/**
+ * `coolifyCallsService`'s own database (#145) -- no `system:kind:key` slot
+ * of its own, the same reason {@link CALLS_SYNAPSE_SCOPE_KEY}'s doc comment
+ * gives for the Matrix stack's two: this step's one auto-recorded
+ * `resourceId` (under `coolify:calls-service:<orgId>`) is the calls service
+ * app itself, not its database.
+ */
+const CALLS_SERVICE_DB_SCOPE_KEY = 'coolify_calls_service_database';
+/** `wtfalch/calls`'s own repo -- `coolifyCallsService` deploys its `packages/service` (#145, part 2 of #128). */
+const CALLS_SERVICE_REPO = 'wtfalch/calls';
+/** `packages/service/Dockerfile`, built from the repo root (that Dockerfile's own top comment). */
+const CALLS_SERVICE_DOCKERFILE = 'packages/service/Dockerfile';
+/** The port `calls/packages/service/Dockerfile` documents (`EXPOSE 8080`) -- `config.mjs`'s own `PORT` has no default, so this must be pushed explicitly. */
+const CALLS_SERVICE_PORT = '8080';
 /**
  * Whether an application's own Coolify `status` (`` `running:healthy`,
  * `exited:unhealthy` `` -- `@wtfalch/providers`' own doc comment) means it is
@@ -221,7 +411,7 @@ const CMS_DATABASE_SCOPE_KEY = 'coolify_cms_database';
  * same "nothing says it's off" convention `planHostingToggle` (`diff.ts`)
  * uses for the org's own app.
  */
-function isRunningOrStarting(status) {
+export function isRunningOrStarting(status) {
     if (!status)
         return true;
     return !status.startsWith('exited') && !status.startsWith('stopped');
@@ -249,10 +439,14 @@ export class FoundryStepExecutor {
                 return this.coolifyApp(action, org, context);
             case 'coolify:database':
                 return this.coolifyDatabase(action, org, context);
+            case 'coolify:calls':
+                return this.coolifyCalls(action, org, context);
+            case 'coolify:calls-service':
+                return this.coolifyCallsService(action, org, context);
             case 'cloudflare:tunnel':
                 return this.cloudflareTunnel(action, org, context);
             case 'cloudflare:zone':
-                return this.cloudflareZone(action);
+                return this.cloudflareZone(action, org);
             case 'cloudflare:access':
                 return this.cloudflareAccess(org);
             case 'cloudflare:ratelimit':
@@ -265,12 +459,18 @@ export class FoundryStepExecutor {
                 return this.aiOrganisation(action, org);
             case 'ai:budget':
                 return this.aiBudget(action, org);
+            case 'ai:key':
+                return this.aiKey(action, org, context);
             case 'coolify:mail':
-                return this.coolifyMail(action, org);
+                return this.coolifyMail(action, org, context);
             case 'coolify:chat':
                 throw new NotBuiltError(`coolify:chat for ${org.slug}`, "chat's per-org Synapse+MAS has no admin API yet; tracked at https://github.com/wtfalch/chat/issues/40");
             case 'cms:site':
                 return this.cmsSite(action, org, context);
+            case 'coolify:agora':
+                return this.coolifyAgora(action, org, context);
+            case 'jobs:registration':
+                return this.jobsRegistration(action, org, context);
             default:
                 throw new Error(`FoundryStepExecutor has no dispatch for ${action.system}:${action.kind}`);
         }
@@ -427,10 +627,39 @@ export class FoundryStepExecutor {
         const projectId = await this.ensureZitadelProject(org, zitadelOrgId, context);
         // A kind change deletes the recorded app then recreates it (task
         // brief); the first-ever create for this key has nothing recorded, so
-        // this is a no-op then.
+        // this is a no-op then. A 404 here (already gone) is tolerated the same
+        // way `destroy` tolerates one -- a retry after the delete half already
+        // succeeded but the recreate half failed must find an already-deleted
+        // app a no-op, not a new error that wedges the apply forever.
         const priorAppId = recorded[`zitadel:app:${action.key}`];
         if (priorAppId) {
-            await this.ports.zitadel.deleteApp(zitadelOrgId, projectId, priorAppId);
+            try {
+                await this.ports.zitadel.deleteApp(zitadelOrgId, projectId, priorAppId);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+            // The recreate half is retried on its own failure (the delete above
+            // already tolerates the resulting 404), so a retry can also land here
+            // after an earlier attempt's create call actually succeeded against
+            // ZITADEL but whose response this executor never saw (a dropped
+            // connection, a killed process). That app is deleted, not reused: the
+            // lost response also lost its clientSecret and clientId, which
+            // `listApps` cannot return, so reusing it would leave the secret
+            // undelivered and the clientId unrecorded forever. The create below
+            // then runs every side effect. A first-ever create (no `priorAppId`)
+            // has nothing to find here and never pays this read.
+            const orphan = await this.findRecreatedApp(zitadelOrgId, projectId, action.key, appType);
+            if (orphan) {
+                try {
+                    await this.ports.zitadel.deleteApp(zitadelOrgId, projectId, orphan.id);
+                }
+                catch (error) {
+                    if (!isNotFoundError(error))
+                        throw error;
+                }
+            }
         }
         if (appType === 'api') {
             const created = await this.ports.zitadel.createApiApp(zitadelOrgId, projectId, {
@@ -442,26 +671,71 @@ export class FoundryStepExecutor {
             await this.ports.deliverSecret(`zitadel:app:${org.slug}:${action.key}`, created.clientSecret);
             return { resourceId: created.appId };
         }
-        const hostname = hostnameFor(org);
+        // #139: the fixed `cms` client (`diff.ts`'s `planCmsClient`) signs
+        // people into the cms studio at `cms.<domain>`, not the org's own app
+        // hostname -- `org.site.enabled` guarantees `org.domain` is set
+        // (`org.ts`'s `validateSite`), the same guarantee `cmsHostnameFor`'s own
+        // doc comment relies on. #164: the fixed `agora` client (`diff.ts`'s
+        // `planAgoraClient`) is the same shape, always -- there is no
+        // `org.site.enabled`-style guard to check, since Agora is always on.
+        const isCmsClient = action.key === 'cms' && org.site.enabled;
+        // The Agora client stays `appType: 'web'`: providers' `createOidcApp`
+        // makes every non-native app a public client (authorization code + PKCE,
+        // `OIDC_AUTH_METHOD_TYPE_NONE`, no secret), which is what Agora's browser
+        // SPA needs. Providers cannot create ZITADEL's `USER_AGENT` app kind.
+        const isAgoraClient = action.key === 'agora';
+        const hostname = isCmsClient
+            ? cmsHostnameFor(org)
+            : isAgoraClient
+                ? agoraHostnameFor(org)
+                : hostnameFor(org);
         // Native apps sign in via device code, with no redirect of their own
         // (auth/scripts/provision.mjs:475-497, prior art cited in the decisions
         // file) -- empty arrays rather than a web app's callback/logout URLs.
+        // #164: Agora's own callback path is `/callback`, not `/auth/callback`
+        // (agora/apps/agora/README.md, "Deploying an Agora": "The issuer's OAuth
+        // client needs `https://<agora address>/callback` as a redirect URI") --
+        // Agora is not built on `@wtfalch/auth`'s `NextAuth` mount the way every
+        // other web app this file provisions is.
+        const redirectUri = isAgoraClient
+            ? `https://${hostname}/callback`
+            : `https://${hostname}/auth/callback`;
         const created = await this.ports.zitadel.createOidcApp(zitadelOrgId, projectId, {
             name: action.key,
             appType,
-            redirectUris: appType === 'native' ? [] : [`https://${hostname}/auth/callback`],
+            redirectUris: appType === 'native' ? [] : [redirectUri],
             postLogoutRedirectUris: appType === 'native' ? [] : [`https://${hostname}/`],
         });
         if (appType === 'web') {
-            // `coolifyApp`'s own `pushAppEnv` reads this to push AUTH_CLIENT_ID
-            // (level-1 app-env campaign, gap P2) -- public, not a secret, so a
+            // `coolifyApp`'s own `pushAppEnv` reads `APP_CLIENT_ID_SCOPE_KEY` to
+            // push AUTH_CLIENT_ID (level-1 app-env campaign, gap P2); `cmsSite`
+            // reads `CMS_CLIENT_ID_SCOPE_KEY` for the same env on the cms app
+            // (#139), and `coolifyAgora` reads `AGORA_CLIENT_ID_SCOPE_KEY` for
+            // `AGORA_CONFIG`'s own `clientId` (#164) -- public, not a secret, so a
             // plain scope id, not `deliverSecret`. A native app signs in via
             // device code with no cookie session of its own, so its clientId is
-            // never something the app's env needs.
-            context.recordScopeId(APP_CLIENT_ID_SCOPE_KEY, created.clientId);
+            // never something an app's env needs.
+            context.recordScopeId(isCmsClient
+                ? CMS_CLIENT_ID_SCOPE_KEY
+                : isAgoraClient
+                    ? AGORA_CLIENT_ID_SCOPE_KEY
+                    : APP_CLIENT_ID_SCOPE_KEY, created.clientId);
         }
         return { resourceId: created.appId };
     }
+    /**
+     * The app an earlier attempt's recreate already made under the same
+     * name, whose response this executor never saw -- deleted before the
+     * create so no duplicate is left behind. Matches on name and the
+     * desired kind, and skips a removed app -- ZITADEL's
+     * search can return one that has since been deleted (`isNotFoundError`'s
+     * own doc comment covers why a delete can be retried into a 404), and
+     * that is not the survivor this is looking for.
+     */
+    async findRecreatedApp(zitadelOrgId, projectId, name, appType) {
+        const apps = await this.ports.zitadel.listApps(zitadelOrgId, projectId);
+        return apps.find((app) => app.name === name && app.appType === appType && app.state !== 'APP_STATE_REMOVED');
+    }
     async ensureZitadelProject(org, zitadelOrgId, context) {
         const recorded = context.recordedIds();
         const existing = recorded.zitadel_project;
@@ -537,6 +811,9 @@ export class FoundryStepExecutor {
                 build_pack: org.hosting.buildPack,
                 name: org.slug,
                 domains: hostnameFor(org),
+                // Only the shared standard app builds from this repo; a bespoke
+                // app's Dockerfile is at its own repo's root.
+                dockerfile_location: org.bespokeAppRepo ? undefined : DEFAULT_APP_DOCKERFILE,
             });
             appId = created.uuid;
         }
@@ -562,6 +839,12 @@ export class FoundryStepExecutor {
         // unlike the database push above: every app has a hostname, and an
         // upsert of the same value on a later apply is a no-op, not a change.
         await this.pushAppEnv(appId, org, context);
+        // #140 rework (2026-09-28 lettermint-org-mail swap): the hosted app's own
+        // Lettermint project, domain restriction and `MAIL_FROM` (only the app
+        // started by this same step, per the design's "only apps that send mail
+        // get it" -- cms and calls do not). A no-op until `coolify:mail` has
+        // actually resolved a mail domain for this org.
+        await this.ensureAppLettermintMail(appId, org, context, Boolean(existing));
         return { resourceId: appId };
     }
     /**
@@ -735,6 +1018,123 @@ export class FoundryStepExecutor {
             return null;
         return randomBytes(32).toString('base64');
     }
+    /**
+     * #140 rework (2026-09-28 lettermint-org-mail swap, "Core rule" +
+     * "Credential model"): all of the org's Lettermint work now lives here,
+     * in the app step, since the first project -- and so the first domain
+     * restriction -- can only exist once the token has a home (the app env). A
+     * no-op until `coolify:mail` has recorded {@link MAIL_DOMAIN_SCOPE_KEY} for
+     * this org; the next apply fills it in once `coolify:mail` runs first
+     * (`diff.ts`'s `computePlanDetail` order).
+     *
+     * Order, exactly as the swap's "Core rule" states it: ensure the
+     * `<slug>-app` project, ensure the mail domain, restrict that domain to the
+     * org's own projects, publish its DNS records, trigger verification, then
+     * delete every stale `<slug>-app` project. New projects are created and the
+     * domain restricted to them before any old project is deleted, so the
+     * restriction list never becomes empty.
+     *
+     * Mint rule ("Credential model"): the project is healthy when the app env
+     * holds `LETTERMINT_API_TOKEN` and Lettermint lists exactly one project
+     * named `<slug>-app` -- unlike Resend's key, a Lettermint project's name
+     * carries no domain id, since a domain switch is handled entirely by
+     * {@link LettermintPort.restrictDomainToProjects} below and never needs a
+     * fresh project. Otherwise a fresh project is created and its token
+     * written to the env first, and only then is every other `<slug>-app`
+     * project deleted -- a lost mint response and a duplicate both end the
+     * same way. An app that was already running is restarted before that
+     * delete, since a container reads its env only at start (`running`, the
+     * same reason {@link ensureLogVolume} restarts one).
+     *
+     * The domain's restriction is rebuilt from every project named `<slug>-app`
+     * or `<slug>-relay` (the relay project itself is #149, not built yet) --
+     * never patched, so it can never end up scoped only to a project about to
+     * be deleted.
+     *
+     * `MAIL_FROM` is upserted every time: it depends only on the mail domain
+     * `coolify:mail` resolved.
+     *
+     * The token goes straight to `bulkUpsertEnvs` and nowhere else: never
+     * returned, never recorded in `serviceIds` (`recordScopeId`'s own doc
+     * comment), never logged, never interpolated into a thrown error -- the
+     * same discipline `pushDatabaseUrl`'s doc comment states for a database's
+     * own connection string.
+     */
+    async ensureAppLettermintMail(appId, org, context, running) {
+        const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!mailDomain)
+            return;
+        const appName = `${org.slug}-app`;
+        const relayName = `${org.slug}-relay`;
+        const [projects, envs] = await Promise.all([
+            this.ports.lettermint.listProjects(),
+            this.ports.coolify.listEnvs(appId),
+        ]);
+        const envValue = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+        const ours = projects.filter((p) => p.name === appName);
+        const held = ours.length === 1 ? ours[0] : undefined;
+        const healthy = held !== undefined && Boolean(envValue('LETTERMINT_API_TOKEN'));
+        let allProjects = projects;
+        let keepProjectId;
+        const envUpdates = [];
+        if (healthy && held) {
+            keepProjectId = held.id;
+        }
+        else {
+            const created = await this.ports.lettermint.createProject(appName);
+            keepProjectId = created.project.id;
+            allProjects = [...projects, created.project];
+            envUpdates.push({ key: 'LETTERMINT_API_TOKEN', value: created.token });
+        }
+        envUpdates.push({ key: 'MAIL_FROM', value: `no-reply@${mailDomain}` });
+        await this.ports.coolify.bulkUpsertEnvs(appId, envUpdates);
+        // A running container read its env at start and still holds the old
+        // token, so a fresh one only reaches it through a restart -- before the
+        // old project is deleted below. A just-created app starts with the new env.
+        if (!healthy && running)
+            await this.ports.coolify.restart(appId);
+        const existing = await this.findExactLettermintDomain(mailDomain);
+        // A crash between here and `restrictDomainToProjects` below is safe even
+        // for a freshly created domain: DNS is only published, and verification
+        // only triggered, after the restriction -- so an unrestricted domain
+        // cannot verify and cannot send, whichever project owns it.
+        const domain = existing
+            ? await this.ports.lettermint.getDomain(existing.id)
+            : await this.ports.lettermint.createDomain(mailDomain);
+        const scopedProjectIds = allProjects
+            .filter((p) => p.name === appName || p.name === relayName)
+            .map((p) => p.id);
+        await this.ports.lettermint.restrictDomainToProjects(domain.id, scopedProjectIds);
+        const zone = await this.ports.cloudflare.findZoneByApex(mailDomain);
+        if (!zone) {
+            throw new Error(`coolify:app for ${org.slug}: no Cloudflare zone found for ${mailDomain}`);
+        }
+        await this.publishLettermintDnsRecords(zone.id, domain.dnsRecords);
+        await this.ports.lettermint.verifyDomain(domain.id);
+        for (const project of allProjects) {
+            if (project.name === appName && project.id !== keepProjectId) {
+                await this.ports.lettermint.deleteProject(project.id);
+            }
+        }
+    }
+    /**
+     * Review finding (post-#140 rework): {@link LettermintPort.findDomain}'s
+     * own match is partial and case-insensitive, so a raw result can be a
+     * lookalike (`notacme.com`, `mail.acme.com`) rather than `name` itself --
+     * and every caller here full-replaces the found domain's project
+     * restriction ({@link LettermintPort.restrictDomainToProjects}), so taking
+     * a lookalike as a match would let it be taken over. Every domain lookup
+     * in this class (`ensureAppLettermintMail`, `parkLettermintMail`,
+     * `deleteStaleLettermintDomain`) goes through this instead of the port
+     * directly, and treats anything but an exact, case-insensitive match as
+     * not found.
+     */
+    async findExactLettermintDomain(name) {
+        const found = await this.ports.lettermint.findDomain(name);
+        if (!found || found.domain.toLowerCase() !== name.toLowerCase())
+            return undefined;
+        return found;
+    }
     /**
      * `plan/diff.ts`'s `planSite` (#116, slicing #99's "provision the cms app,
      * database and site app per org"): the 2026-09-25 decision
@@ -832,11 +1232,32 @@ export class FoundryStepExecutor {
         // (see that section's own comment) instead of caught, so a database
         // failure must not also cost the app these two calls already have
         // everything they need for.
-        await this.ports.coolify.bulkUpsertEnvs(cms.appId, [
+        //
+        // #139: `@wtfalch/cms`'s `AUTH_*` contract
+        // (https://github.com/wtfalch/cms/blob/main/apps/host/.env.example),
+        // pushed in this same call. `AUTH_ORGANIZATION_ID` and `AUTH_CLIENT_ID`
+        // are pushed only once their own source step has recorded them --
+        // `zitadel:issuer` and this org's `cms` `zitadel:app` step
+        // (`diff.ts`'s `planCmsClient`), both ordered before `cms:site` for
+        // exactly this reason, the same rule `pushAppEnv` follows for the
+        // hosted app. `AUTH_COOKIE_SECRET` is generated once and never rotated
+        // (`ensureAuthCookieSecret`'s own doc comment).
+        const recorded = context.recordedIds();
+        const cmsEnvs = [
             { key: 'APP_URL', value: `https://${cmsHostnameFor(org)}` },
             { key: 'CMS_ORGANISATION_ID', value: org.id },
             { key: 'CMS_SITE_URL', value: `https://${domain}` },
-        ]);
+        ];
+        if (recorded.zitadel_org) {
+            cmsEnvs.push({ key: 'AUTH_ORGANIZATION_ID', value: recorded.zitadel_org });
+        }
+        const cmsClientId = recorded[CMS_CLIENT_ID_SCOPE_KEY];
+        if (cmsClientId)
+            cmsEnvs.push({ key: 'AUTH_CLIENT_ID', value: cmsClientId });
+        const cookieSecret = await this.ensureAuthCookieSecret(cms.appId);
+        if (cookieSecret)
+            cmsEnvs.push({ key: 'AUTH_COOKIE_SECRET', value: cookieSecret });
+        await this.ports.coolify.bulkUpsertEnvs(cms.appId, cmsEnvs);
         await this.ports.coolify.bulkUpsertEnvs(site.appId, [
             { key: 'CMS_URL', value: `https://${cmsHostnameFor(org)}` },
         ]);
@@ -1015,6 +1436,521 @@ export class FoundryStepExecutor {
         });
         return { appId: created.uuid, existed: false };
     }
+    // ---- calls (#128) ------------------------------------------------------
+    /**
+     * `plan/diff.ts`'s `planCalls`: the org's own calls Matrix stack, entirely
+     * separate from chat's (`calls-matrix.ts`'s own top doc comment) -- two
+     * Coolify-managed Postgres databases, a Synapse app and an MAS app, no
+     * public hostname of its own (neither app is reachable from outside
+     * Coolify's own Docker network) -- `coolifyCallsService` below (#145, part 2
+     * of #128) is the one that gets a public hostname, since it is the one a
+     * browser actually talks to. Park stops Synapse and MAS only, the same
+     * park-not-delete rule `coolifyApp`/`cmsSite` already follow (#7
+     * corrections 1) -- their databases are never touched from that branch, the
+     * same way `cmsSite`'s own database never is.
+     */
+    async coolifyCalls(action, org, context) {
+        if (action.desired.enabled === false) {
+            const recorded = context.recordedIds();
+            const synapseId = recorded[CALLS_SYNAPSE_SCOPE_KEY];
+            const masId = recorded[CALLS_MAS_SCOPE_KEY];
+            if (!synapseId && !masId) {
+                throw new Error(`coolify:calls for ${org.slug}: no live calls stack recorded, nothing to park`);
+            }
+            if (synapseId)
+                await this.ports.coolify.raw('POST', `/applications/${synapseId}/stop`);
+            if (masId)
+                await this.ports.coolify.raw('POST', `/applications/${masId}/stop`);
+            return { resourceId: masId ?? synapseId };
+        }
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const server = await this.resolveServer();
+        const names = {
+            synapse: `${org.slug}-calls-synapse`,
+            mas: `${org.slug}-calls-mas`,
+            synapseDb: `${org.slug}-calls-synapse-db`,
+            masDb: `${org.slug}-calls-mas-db`,
+        };
+        const synapseDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.synapseDb, 'synapse', CALLS_SYNAPSE_DB_SCOPE_KEY, CALLS_SYNAPSE_DB_INITDB_ARGS);
+        context.recordScopeId(CALLS_SYNAPSE_DB_SCOPE_KEY, synapseDbId);
+        const masDbId = await this.ensureCallsDatabase(context, projectUuid, environment, names.masDb, 'mas', CALLS_MAS_DB_SCOPE_KEY);
+        context.recordScopeId(CALLS_MAS_DB_SCOPE_KEY, masDbId);
+        const [synapseDbRow, masDbRow] = await Promise.all([
+            this.ports.coolify.getDatabase(synapseDbId),
+            this.ports.coolify.getDatabase(masDbId),
+        ]);
+        const synapseDb = synapseDbRow.internal_db_url
+            ? parseCallsDbUrl(synapseDbRow.internal_db_url)
+            : null;
+        const masDb = masDbRow.internal_db_url ? parseCallsDbUrl(masDbRow.internal_db_url) : null;
+        if (!synapseDb || !masDb) {
+            // Static config check before the two apps below are ever touched
+            // (issue #128's "static config checks run before the first Coolify
+            // call", carried from PR 344's review) -- Coolify can take a moment to
+            // report a freshly created database's `internal_db_url`; the next
+            // apply retries this from a clean, unstarted state rather than half
+            // deploying Synapse or MAS against a connection string it does not have
+            // yet.
+            throw new Error(`coolify:calls for ${org.slug}: a database has no internal_db_url yet -- retry this apply once Coolify reports one`);
+        }
+        const synapse = await this.findOrCreateCallsApp(names.synapse, environment.id, () => this.ports.coolify.createDockerImageApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            docker_registry_image_name: SYNAPSE_IMAGE,
+            docker_registry_image_tag: SYNAPSE_TAG,
+            ports_exposes: '8008',
+            name: names.synapse,
+            description: `Synapse for ${org.slug}'s calls stack (${SYNAPSE_IMAGE}:${SYNAPSE_TAG})`,
+            instant_deploy: false,
+        }));
+        if (!synapse.existed) {
+            await this.ports.coolify.updateApplication(synapse.appId, {
+                health_check_enabled: false,
+                custom_internal_name: names.synapse,
+            });
+        }
+        context.recordScopeId(CALLS_SYNAPSE_SCOPE_KEY, synapse.appId);
+        const mas = await this.findOrCreateCallsApp(names.mas, environment.id, () => this.ports.coolify.createDockerfileApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            dockerfile: CALLS_MAS_DOCKERFILE,
+            name: names.mas,
+            description: `matrix-authentication-service for ${org.slug}'s calls stack`,
+            instant_deploy: false,
+        }));
+        if (!mas.existed) {
+            await this.ports.coolify.updateApplication(mas.appId, {
+                health_check_enabled: false,
+                custom_internal_name: names.mas,
+            });
+        }
+        context.recordScopeId(CALLS_MAS_SCOPE_KEY, mas.appId);
+        // Synapse's own signing key, media store and pid file (#75's own
+        // durable-volume convention, reused here for a different reason: this
+        // volume is Synapse's own state, not a log).
+        const synapseStorages = await this.ports.coolify.listStorages(synapse.appId);
+        if (!(synapseStorages.persistent_storages ?? []).some((s) => s.mount_path === '/data')) {
+            await this.ports.coolify.createPersistentStorage(synapse.appId, {
+                name: `${names.synapse}-data`,
+                mount_path: '/data',
+            });
+        }
+        const secrets = await this.ensureCallsMatrixSecrets(mas.appId);
+        await this.ensureCallsFileStorage(synapse.appId, '/data/homeserver.yaml', callsSynapseHomeserverYaml({
+            orgSlug: org.slug,
+            db: synapseDb,
+            masHost: names.mas,
+            masSharedSecret: secrets.value.masSynapseSharedSecret,
+        }));
+        // Synapse's official image reads `/data/homeserver.yaml` by default, but
+        // it also needs write access to the mounted volume it does not own by
+        // default (`calls/proof/provider/scripts/guest-stack.mjs`'s own working
+        // config carries the same three envs).
+        await this.ports.coolify.bulkUpsertEnvs(synapse.appId, [
+            { key: 'SYNAPSE_CONFIG_PATH', value: '/data/homeserver.yaml' },
+            { key: 'UID', value: '0' },
+            { key: 'GID', value: '0' },
+        ]);
+        await this.ensureCallsFileStorage(mas.appId, '/config/config.yaml', callsMasConfigYaml({
+            orgSlug: org.slug,
+            db: masDb,
+            synapseHost: names.synapse,
+            sharedSecret: secrets.value.masSynapseSharedSecret,
+            clientId: secrets.value.masClientId,
+            clientSecret: secrets.value.masClientSecret,
+            encryptionKey: secrets.value.masEncryptionKey,
+            rsaKeyPem: secrets.value.masRsaKeyPem,
+            ecKeyPem: secrets.value.masEcKeyPem,
+        }));
+        // Issue #128's "a running app is redeployed when its config changed"
+        // (PR 344's review fix): a file-storage write alone never reaches a
+        // running container until its next deploy, but redeploying an unchanged,
+        // already-running app on every apply would mean this step never
+        // converges. A brand new app or a freshly minted secret set are the only
+        // two reasons the file just written could differ from what the container
+        // already has -- reusing existing secrets means byte-identical content.
+        if (!synapse.existed || secrets.changed)
+            await this.ports.coolify.deploy(synapse.appId);
+        if (!mas.existed || secrets.changed)
+            await this.ports.coolify.deploy(mas.appId);
+        return { resourceId: mas.appId };
+    }
+    /**
+     * `coolifyCalls`'s own find-or-create for Synapse/MAS, restarting a
+     * found-but-stopped app (#116 review round 3, Finding 1's same fix). Reused
+     * by `coolifyCallsService` (#145) for the calls service app itself -- the
+     * same find-by-name-then-start-or-create shape applies unchanged.
+     */
+    async findOrCreateCallsApp(name, environmentId, create) {
+        const existing = await this.ports.coolify.findApplicationByName(name, {
+            environmentIds: [environmentId],
+        });
+        if (existing) {
+            const live = await this.ports.coolify.getApplication(existing.uuid);
+            if (!isRunningOrStarting(live.status)) {
+                await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
+            }
+            return { appId: existing.uuid, existed: true };
+        }
+        const created = await create();
+        return { appId: created.uuid, existed: false };
+    }
+    /**
+     * `coolifyCalls`'s own database find-or-create, modeled on
+     * `ensureCmsDatabase`: `context.recordedIds()` is checked first since
+     * neither database has a `system:kind:key` slot of its own (this step's one
+     * auto-recorded `resourceId` is the MAS app, not either database --
+     * {@link CALLS_SYNAPSE_SCOPE_KEY}'s own doc comment), then `listDatabases`
+     * finds one already created by name before `createPostgresDatabase` makes
+     * one. Reused by `coolifyCallsService` (#145) for the calls service's own
+     * database, whose {@link CALLS_SERVICE_DB_SCOPE_KEY} has no
+     * `system:kind:key` slot of its own for the same reason.
+     */
+    async ensureCallsDatabase(context, projectUuid, environment, name, postgresDb, scopeKey, postgresInitdbArgs) {
+        const existing = context.recordedIds()[scopeKey];
+        if (existing)
+            return existing;
+        const found = (await this.ports.coolify.listDatabases()).find((d) => d.name === name && d.environment_id === environment.id);
+        if (found)
+            return found.uuid;
+        const server = await this.resolveServer();
+        const created = await this.ports.coolify.createPostgresDatabase({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name,
+            postgres_db: postgresDb,
+            postgres_user: postgresDb,
+            ...(postgresInitdbArgs ? { postgres_initdb_args: postgresInitdbArgs } : {}),
+        });
+        return created.uuid;
+    }
+    /**
+     * Reads back {@link CALLS_SECRET_ENV_KEYS} from the MAS app's own envs
+     * before minting fresh ones -- this stack's only memory across a re-run
+     * (`calls-matrix.ts`'s `CallsMatrixSecrets` doc comment). `changed: true`
+     * only when nothing usable was found: a partial set (a crash mid-mint) is
+     * still treated as "mint fresh", since MAS's shared secret and Synapse's
+     * copy of it must always agree.
+     */
+    async ensureCallsMatrixSecrets(masAppId) {
+        const envs = await this.ports.coolify.listEnvs(masAppId);
+        const read = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+        const fields = Object.entries(CALLS_SECRET_ENV_KEYS);
+        const existing = {};
+        for (const [field, envKey] of fields) {
+            const value = read(envKey);
+            if (value !== undefined)
+                existing[field] = value;
+        }
+        const hasAll = fields.every(([field]) => existing[field] !== undefined);
+        if (hasAll)
+            return { value: existing, changed: false };
+        const minted = mintCallsMatrixSecrets();
+        await this.ports.coolify.bulkUpsertEnvs(masAppId, fields.map(([field, envKey]) => ({
+            key: envKey,
+            value: minted[field],
+            multiline: field === 'masRsaKeyPem' || field === 'masEcKeyPem',
+        })));
+        return { value: minted, changed: true };
+    }
+    /**
+     * Upserts a file storage's content, creating it if the application has none
+     * at that mount path yet -- there is no way to read a file storage's
+     * current content back from Coolify to diff it, the same limit
+     * `archon/bootstrap/steps/chat-instance.ts`'s own `ensureFileStorage` notes,
+     * so an existing one is always re-written.
+     */
+    async ensureCallsFileStorage(applicationUuid, mountPath, content) {
+        const storages = await this.ports.coolify.listStorages(applicationUuid);
+        const found = storages.file_storages?.find((s) => s.mount_path === mountPath);
+        if (found) {
+            await this.ports.coolify.updateFileStorage(applicationUuid, found.uuid, content);
+        }
+        else {
+            await this.ports.coolify.createFileStorage(applicationUuid, {
+                mount_path: mountPath,
+                content,
+            });
+        }
+    }
+    // ---- calls service (#145, part 2 of #128) -------------------------------
+    /**
+     * `plan/diff.ts`'s `planCallsService`: the org's own calls service --
+     * `wtfalch/calls`'s `packages/service`, wired to the calls Matrix stack
+     * {@link coolifyCalls} provisions and the shared LiveKit SFU (#122/#127).
+     * Static config checks run first, before any Coolify call (#128's own
+     * carried-over PR 344 review fix, restated in #145's own issue body): the
+     * calls Matrix stack must already be recorded, its MAS app must already
+     * carry its client id/secret, and the shared SFU's LiveKit credentials must
+     * already be resolvable -- none of the three is minted or guessed here.
+     * Park stops the app only, the same park-not-delete rule
+     * {@link coolifyCalls}/{@link coolifyApp} already follow (#7 corrections
+     * 1); its own database is never touched from that branch.
+     */
+    async coolifyCallsService(action, org, context) {
+        if (action.desired.enabled === false) {
+            const appId = context.recordedIds()[`coolify:calls-service:${action.key}`];
+            if (!appId) {
+                throw new Error(`coolify:calls-service for ${org.slug}: no live app recorded, nothing to park`);
+            }
+            await this.ports.coolify.raw('POST', `/applications/${appId}/stop`);
+            return { resourceId: appId };
+        }
+        const recorded = context.recordedIds();
+        const synapseId = recorded[CALLS_SYNAPSE_SCOPE_KEY];
+        const masId = recorded[CALLS_MAS_SCOPE_KEY];
+        if (!synapseId || !masId) {
+            throw new Error(`coolify:calls-service for ${org.slug}: the calls Matrix stack has not been provisioned yet -- coolify:calls must run first`);
+        }
+        const masCredentials = await this.readCallsMasClientCredentials(masId);
+        if (!masCredentials) {
+            throw new Error(`coolify:calls-service for ${org.slug}: the calls Matrix stack's MAS client credentials are not on the MAS app yet -- retry this apply once coolify:calls has minted them`);
+        }
+        const sfu = await this.ports.callsSfu.resolveCredentials();
+        if (!sfu) {
+            throw new Error(`coolify:calls-service for ${org.slug}: the shared calls SFU has no LiveKit credentials configured yet -- see https://github.com/wtfalch/foundry/issues/122`);
+        }
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const name = `${org.slug}-calls`;
+        const synapseHost = `${org.slug}-calls-synapse`;
+        const masHost = `${org.slug}-calls-mas`;
+        const dbName = `${name}-db`;
+        const dbId = await this.ensureCallsDatabase(context, projectUuid, environment, dbName, dbName.replace(/-/g, '_'), CALLS_SERVICE_DB_SCOPE_KEY);
+        context.recordScopeId(CALLS_SERVICE_DB_SCOPE_KEY, dbId);
+        const db = await this.ports.coolify.getDatabase(dbId);
+        if (!db.internal_db_url) {
+            throw new Error(`coolify:calls-service for ${org.slug}: its database has no internal_db_url yet -- retry this apply once Coolify reports one`);
+        }
+        const server = await this.resolveServer();
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: CALLS_SERVICE_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name,
+            domains: callsHostnameFor(org),
+            dockerfile_location: CALLS_SERVICE_DOCKERFILE,
+        }));
+        // Every app foundry deploys keeps its own logs (#75), reused as-is here.
+        await this.ensureLogVolume(app.appId, org, app.existed);
+        const bindingSecret = await this.ensureCallsBindingSecret(app.appId);
+        const envs = [
+            { key: 'DATABASE_URL', value: db.internal_db_url },
+            { key: 'LIVEKIT_URL', value: CALLS_SFU_PRIVATE_URL },
+            { key: 'LIVEKIT_PUBLIC_URL', value: CALLS_SFU_PUBLIC_URL },
+            { key: 'LIVEKIT_API_KEY', value: sfu.apiKey },
+            { key: 'LIVEKIT_API_SECRET', value: sfu.apiSecret },
+            { key: 'MAS_URL', value: `http://${masHost}:8080/` },
+            { key: 'MAS_HOMESERVER', value: callsServerName(org.slug) },
+            { key: 'MAS_CLIENT_ID', value: masCredentials.clientId },
+            { key: 'MAS_CLIENT_SECRET', value: masCredentials.clientSecret },
+            { key: 'SYNAPSE_URL', value: `http://${synapseHost}:8008` },
+            { key: 'CALLS_ORIGIN', value: `https://${callsHostnameFor(org)}` },
+            { key: 'CALLS_HOST_ADAPTER', value: 'production' },
+            { key: 'CALLS_TRUSTED_IP_HEADER', value: 'cf-connecting-ip' },
+            { key: 'PORT', value: CALLS_SERVICE_PORT },
+        ];
+        if (bindingSecret)
+            envs.push({ key: 'CALLS_BINDING_SECRET', value: bindingSecret });
+        await this.ports.coolify.bulkUpsertEnvs(app.appId, envs);
+        return { resourceId: app.appId };
+    }
+    /**
+     * Reads back the calls Matrix stack's MAS client id/secret from the MAS
+     * app's own envs ({@link CALLS_SECRET_ENV_KEYS}) -- never mints: minting
+     * either is {@link ensureCallsMatrixSecrets}'s own job, and a missing value
+     * here means that stack has not finished provisioning yet, not something
+     * this step can fix on its own.
+     */
+    async readCallsMasClientCredentials(masAppId) {
+        const envs = await this.ports.coolify.listEnvs(masAppId);
+        const read = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+        const clientId = read(CALLS_SECRET_ENV_KEYS.masClientId);
+        const clientSecret = read(CALLS_SECRET_ENV_KEYS.masClientSecret);
+        if (!clientId || !clientSecret)
+            return null;
+        return { clientId, clientSecret };
+    }
+    /**
+     * `null` once the calls service app already has a `CALLS_BINDING_SECRET` --
+     * never rotated, the same rule {@link ensureAuthCookieSecret} follows for
+     * `AUTH_COOKIE_SECRET`: it wraps the provider-token ciphertext already
+     * stored under any binding minted so far
+     * (`calls/packages/service/src/config.mjs`'s own doc comment on
+     * `CALLS_BINDING_SECRET`), so overwriting it would strand every binding
+     * minted under the old value. 32 raw bytes, hex-encoded -- the exact shape
+     * `config.mjs`'s own regex requires.
+     */
+    async ensureCallsBindingSecret(appId) {
+        const envs = await this.ports.coolify.listEnvs(appId);
+        const already = envs.some((e) => e.key === 'CALLS_BINDING_SECRET' && !e.is_preview);
+        if (already)
+            return null;
+        return randomBytes(32).toString('hex');
+    }
+    // ---- agora (#164) --------------------------------------------------------
+    /**
+     * `plan/diff.ts`'s `planAgora`: provisions the org's own Agora
+     * (https://github.com/wtfalch/agora) as one more Coolify application, from
+     * that repo's `apps/agora/Dockerfile` ({@link AGORA_REPO}'s doc comment),
+     * and pushes its env. `findOrCreateCallsApp` is reused as-is for the
+     * find-by-name-then-start-or-create shape, like {@link coolifyCallsService}.
+     * There is no park branch: Agora is always on.
+     *
+     * The env comes from `plan/agora.ts`'s `desiredAgoraEnv`, the same function
+     * the plan compares the live app against, so a re-plan after this step is
+     * empty. The step never writes a partial config: when any input is missing
+     * (the org's ZITADEL org id or Agora client id, or an issuer or
+     * mail/messaging project id the host does not supply,
+     * `AgoraHostPort`, read by the plan) it throws naming each one, before
+     * it creates anything.
+     *
+     * `AGORA_CANONICAL_HOST` is always pushed. `AGORA_MAIL_UPSTREAM`/
+     * `AGORA_FILES_UPSTREAM` are pushed once the platform's own mail/files
+     * hosts are on and applied (#177's `platform-org.ts`'s
+     * `agoraHostValuesFromPlatform`, read by `plan-apply.ts` when no host
+     * `agora` port overrides it) -- absent otherwise. The chat upstreams are
+     * still never pushed: chat has no admin API yet
+     * (https://github.com/wtfalch/chat/issues/40). Agora answers 502 on those
+     * routes rather than serving anything wrong.
+     */
+    async coolifyAgora(action, org, context) {
+        // The host values the plan read, carried in the step: never read again
+        // here, so the env written is the env the plan showed.
+        const host = action.desired.host;
+        if (!host) {
+            throw new Error(`Agora for ${org.slug} cannot be configured: the step carries no host values`);
+        }
+        const { env, missing } = desiredAgoraEnv(org, context.recordedIds(), host);
+        if (missing.length > 0) {
+            throw new Error(`Agora for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
+        }
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const name = `${org.slug}-agora`;
+        const server = await this.resolveServer();
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: AGORA_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name,
+            domains: agoraHostnameFor(org),
+            dockerfile_location: AGORA_APP_DOCKERFILE,
+        }));
+        // Every app foundry deploys keeps its own logs (#75), reused as-is here.
+        await this.ensureLogVolume(app.appId, org, app.existed);
+        await this.ports.coolify.bulkUpsertEnvs(app.appId, Object.entries(env).map(([key, value]) => ({ key, value })));
+        return { resourceId: app.appId };
+    }
+    // ---- jobs (#173) ---------------------------------------------------------
+    /**
+     * `plan/diff.ts`'s `planJobsRegistration`: registers the org's own app with
+     * the platform's jobs scheduler (`JobsSchedulerPort.registerProject`, the
+     * scheduler's `POST /admin/projects`), then hands the freshly minted
+     * `secret` and `syncKey` to the host through `deliverSecret` -- but only
+     * when this call actually minted them. The admin API is itself idempotent
+     * by `(name, baseUrl)`: a repeat call for an already-registered project
+     * resolves with just the `id`, and this never re-delivers a secret or sync
+     * key it did not just mint, the same "registers an app once" rule
+     * `diff.ts`'s own plan-level gate (recordedIds, mirroring `planOwner`)
+     * already provides on a normal re-plan -- this check is what keeps that
+     * true even if this step somehow runs twice on the same apply.
+     *
+     * Never logs, returns or records either credential (this file's own top
+     * doc comment's "a secret is never a step's return value" rule) -- only the
+     * scheduler's own non-secret project id comes back as `resourceId`.
+     */
+    /** #177: the host's own port when it supplies one, else the platform's, built from its address and held key. */
+    async filesPort() {
+        const port = this.ports.filesOrganisation ?? (await this.ports.platformOrg?.files());
+        if (!port)
+            throw new Error('files: this executor was built without a files port (#177)');
+        return port;
+    }
+    async aiPort() {
+        const port = this.ports.aiOrganisation ?? (await this.ports.platformOrg?.ai());
+        if (!port)
+            throw new Error('ai: this executor was built without an ai port (#177)');
+        return port;
+    }
+    async jobsPort(org) {
+        const port = this.ports.jobsScheduler ?? (await this.ports.platformOrg?.jobs());
+        if (!port) {
+            throw new Error(`jobs:registration for ${org.slug}: this executor was built without a jobsScheduler port (#173)`);
+        }
+        return port;
+    }
+    async jobsRegistration(action, org, context) {
+        const scheduler = await this.jobsPort(org);
+        const name = action.desired.name;
+        const baseUrl = action.desired.baseUrl;
+        const registered = await scheduler.registerProject({ name, baseUrl });
+        // A repeat call for an already-registered project carries neither
+        // credential: nothing to deliver.
+        if (!registered.secret && !registered.syncKey)
+            return { resourceId: registered.id };
+        // The project now exists and its credentials are shown exactly once, so
+        // the id is recorded before anything else can fail: a step's return value
+        // is only recorded on success, and without this a failed delivery would
+        // leave the next run's `registerProject` answering with just `{ id }`,
+        // the step recording success, and the sync key lost for good.
+        // `planJobsRegistration` reports this id as blocked instead of planning
+        // the step again.
+        context.recordScopeId(JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, registered.id);
+        // Written now, so a crash during delivery cannot lose the id either.
+        await context.persistScopeIds();
+        if (!registered.secret || !registered.syncKey) {
+            // Only one half came back; the other can never be fetched again.
+            throw new Error(`jobs:registration for ${org.slug}: project ${registered.id} was registered but the scheduler returned only one of its secret and sync key; deregister it in the scheduler before registering again`);
+        }
+        const failed = [];
+        for (const [part, value] of [
+            ['secret', registered.secret],
+            ['syncKey', registered.syncKey],
+        ]) {
+            if (!(await this.deliverWithRetry(`jobs:registration:${org.slug}:${part}`, value))) {
+                failed.push(part);
+            }
+        }
+        if (failed.length > 0) {
+            // Names the project id only; the underlying errors are dropped in case
+            // one echoes a credential.
+            throw new Error(`jobs:registration for ${org.slug}: project ${registered.id} was registered but its ${failed.join(' and ')} could not be delivered after ${JOBS_DELIVERY_ATTEMPTS} attempts; deregister it in the scheduler before registering again`);
+        }
+        return { resourceId: registered.id };
+    }
+    /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
+    async deliverWithRetry(ref, value) {
+        for (let attempt = 1; attempt <= JOBS_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.deliverSecret(ref, value);
+                return true;
+            }
+            catch {
+                // Retried; the error is dropped in case it echoes the secret.
+            }
+        }
+        return false;
+    }
     // ---- cloudflare --------------------------------------------------------
     async cloudflareTunnel(action, org, context) {
         if (action.desired.enabled === false) {
@@ -1058,12 +1994,34 @@ export class FoundryStepExecutor {
         });
         return { resourceId: tunnel.id };
     }
-    async cloudflareZone(action) {
+    /**
+     * `plan/diff.ts`'s `planZone`: finds or creates the Cloudflare zone for the
+     * org's own domain. Refuses to adopt a zone the store already records
+     * under a *different* org's applied state (#131), the same
+     * do-not-adopt-a-foreign-resource rule `cloudflareAccess` above enforces --
+     * but where that method tells "foundry's own" from "foreign" by reading
+     * Cloudflare's own Access-app name live, a Cloudflare zone carries no
+     * org-identifying field of its own, so this asks the store instead. That
+     * matters because two different, DB-unique `domain` values (`org.ts`'s
+     * `validateDomain` plus its unique index) can still resolve to the same
+     * Cloudflare zone -- a zone is keyed by apex, and one org's domain can be a
+     * subdomain of another org's -- which is exactly the shared-zone,
+     * shared-hostname collision this ticket exists to refuse. An org re-running
+     * its own already-recorded zone is unaffected: the store then names this
+     * same org as the owner.
+     */
+    async cloudflareZone(action, org) {
         const domain = action.key;
-        const existing = await this.ports.cloudflare.findZoneByApex(domain);
-        if (existing)
+        const cf = this.ports.cloudflare;
+        const existing = await cf.findZoneByApex(domain);
+        if (existing) {
+            const owner = await this.ports.declaredOrgStore.findOrgIdForZone(existing.id);
+            if (owner !== null && owner !== org.id) {
+                throw new Error(`cloudflare:zone for ${org.slug}: zone ${existing.id} (${domain}) is already recorded under org ${owner}; foundry does not adopt it`);
+            }
             return { resourceId: existing.id };
-        const created = await this.ports.cloudflare.createZone(domain);
+        }
+        const created = await cf.createZone(domain);
         return { resourceId: created.id };
     }
     // ---- mail -----------------------------------------------------------
@@ -1071,20 +2029,95 @@ export class FoundryStepExecutor {
      * `plan/diff.ts`'s `planMail`: gives an org mail, moves it between modes,
      * or parks it on the one shared Stalwart instance (`this.ports.mail`,
      * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
-     * publishes whatever DNS records the call returns.
+     * publishes whatever Stalwart DNS records the call returns, and records the
+     * resolved mail domain as a scope id ({@link MAIL_DOMAIN_SCOPE_KEY}).
+     * 2026-09-28 lettermint-org-mail swap: this step no longer calls the mail
+     * relay provider at all -- registering the domain, restricting it and
+     * publishing its own DNS records all moved to the app step
+     * (`ensureAppLettermintMail`, "Core rule"), since the first project can
+     * only exist once the token has a home. Parking mail (mode `'off'`) does
+     * still reach Lettermint, the one exception: {@link parkLettermintMail}
+     * deletes the org's own projects and then its domain, so a domain never
+     * ends up restricted only to dead projects.
+     *
+     * Review finding: a mail domain switch (`org.domain` changes, or
+     * `usesDomain` flips) must also delete the *old* Lettermint domain here,
+     * before recording the new one -- otherwise it stays registered and
+     * restricted to the org's still-live `<slug>-app` project, which could
+     * then keep sending as it forever. {@link deleteStaleLettermintDomain}
+     * does this by comparing the previously recorded domain (case-insensitive)
+     * against the one this apply just resolved.
+     *
+     * #162: once `applyOrgMail` has given the org a domain, {@link ensureOwnerMailbox}
+     * gives its declared owner a mailbox on it, so Agora's Mail section is not
+     * empty for them after the org's first apply.
      */
-    async coolifyMail(action, org) {
+    async coolifyMail(action, org, context) {
         const mode = action.desired.mode;
         const usesDomain = action.desired.usesDomain;
-        const options = { apex: MAIL_APEX, mailHost: MAIL_HOST };
+        // #177: `diff.ts`'s `planMail` carries the platform's own apex/mail host
+        // in `desired` once it is wired -- "the executor writes exactly these
+        // host values, so what the plan showed is what gets applied" (`planAgora`'s
+        // own rule). `MAIL_APEX`/`MAIL_HOST` remain the fallback for a plan built
+        // without a platform (this file's own doc comment on those constants).
+        const options = {
+            apex: action.desired.apex ?? MAIL_APEX,
+            mailHost: action.desired.mailHost ?? MAIL_HOST,
+        };
         if (mode === 'off') {
             await this.ports.mail.parkOrgMail(mailOrgFor(org, usesDomain, 'hosted'), options);
+            await this.parkLettermintMail(org, context);
             return undefined;
         }
-        const result = await this.ports.mail.applyOrgMail(mailOrgFor(org, usesDomain, mode), options);
+        const mailOrg = mailOrgFor(org, usesDomain, mode);
+        const result = await this.ports.mail.applyOrgMail(mailOrg, options);
         await this.publishMailDnsRecords(org, result);
+        await this.deleteStaleLettermintDomain(context, result.domain);
+        context.recordScopeId(MAIL_DOMAIN_SCOPE_KEY, result.domain);
+        // #177: what this step wrote from the platform, so `planMail` can see a later change.
+        context.recordScopeId(ORG_MAIL_APPLIED_APEX_SCOPE_KEY, options.apex);
+        context.recordScopeId(ORG_MAIL_APPLIED_HOST_SCOPE_KEY, options.mailHost);
+        await this.ensureOwnerMailbox(org, mailOrg, result.domain, context);
         return { resourceId: result.domain };
     }
+    /**
+     * #162: gives the org's declared owner a mailbox on its just-resolved mail
+     * domain, the one address this executor mints on its own
+     * ({@link MAIL_OWNER_LOCAL_PART}'s own doc comment). A no-op when the org
+     * has no owner yet, or once {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already
+     * recorded -- checked first so a second apply never calls
+     * `MailPort.createMailbox` again, rather than relying on that port method's
+     * own duplicate refusal.
+     */
+    async ensureOwnerMailbox(org, mailOrg, domain, context) {
+        if (!org.owner)
+            return;
+        if (context.recordedIds()[MAIL_OWNER_MAILBOX_SCOPE_KEY])
+            return;
+        const address = `${MAIL_OWNER_LOCAL_PART}@${domain}`;
+        await this.ports.mail.createMailbox(mailOrg, {
+            address,
+            name: `${org.owner.givenName} ${org.owner.familyName}`,
+        });
+        context.recordScopeId(MAIL_OWNER_MAILBOX_SCOPE_KEY, address);
+    }
+    /**
+     * Deletes the org's previous Lettermint domain once the mail domain it was
+     * registered under has changed -- otherwise it stays registered and
+     * restricted to the org's still-live `<slug>-app` project after the switch
+     * (review finding, post-#140 rework). A no-op on first apply (no previous
+     * domain recorded) and on a same-domain re-apply (compared
+     * case-insensitively, the same rule {@link findExactLettermintDomain}
+     * applies to the lookup itself).
+     */
+    async deleteStaleLettermintDomain(context, newDomain) {
+        const previous = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!previous || previous.toLowerCase() === newDomain.toLowerCase())
+            return;
+        const stale = await this.findExactLettermintDomain(previous);
+        if (stale)
+            await this.ports.lettermint.deleteDomain(stale.id);
+    }
     /**
      * Upserts each DNS record `applyOrgMail` says foundry must publish, found
      * by an exact name+type match (`CloudflarePort.findDnsRecord`'s own doc
@@ -1109,6 +2142,72 @@ export class FoundryStepExecutor {
             }
         }
     }
+    /**
+     * Parking mail (2026-09-28 lettermint-org-mail swap, "Core rule": "Parking
+     * mail deletes the org's projects and then the domain itself, so no
+     * restriction points only at dead projects"). Deletes every Lettermint
+     * project named `<slug>-app` or `<slug>-relay`, then the org's own
+     * Lettermint domain, if one was found -- in that order, never the reverse.
+     * A no-op until a previous apply recorded {@link MAIL_DOMAIN_SCOPE_KEY}:
+     * nothing was ever provisioned for an org whose mail went straight from
+     * never-applied to off.
+     */
+    async parkLettermintMail(org, context) {
+        const mailDomain = context.recordedIds()[MAIL_DOMAIN_SCOPE_KEY];
+        if (!mailDomain)
+            return;
+        const names = new Set([`${org.slug}-app`, `${org.slug}-relay`]);
+        const projects = await this.ports.lettermint.listProjects();
+        for (const project of projects) {
+            if (names.has(project.name))
+                await this.ports.lettermint.deleteProject(project.id);
+        }
+        const domain = await this.findExactLettermintDomain(mailDomain);
+        if (domain)
+            await this.ports.lettermint.deleteDomain(domain.id);
+    }
+    /**
+     * Upserts each DNS record Lettermint's domain names, the same find-then-
+     * upsert `publishMailDnsRecords` above uses for Stalwart's own records --
+     * except an existing `_dmarc` record is never overwritten (a stricter
+     * policy an org already set, `p=quarantine`/`p=reject`, should not be
+     * relaxed back to Lettermint's own default). Resend's own domain also
+     * carried an apex `SPF` TXT record that had to be merged into whatever SPF
+     * record already existed there (RFC 7208: two `v=spf1` TXT records on one
+     * name is a permerror); Lettermint's own DNS records
+     * (`.plans/2026-09-28-lettermint-api.md` §3) have no such record -- its
+     * `purpose` enum is `return_path`/`dmarc`/`dkim_legacy`/`dkim_primary`/
+     * `dkim_secondary`, none of them SPF -- so that merge has no case left to
+     * handle here and is dropped rather than kept as dead code.
+     */
+    async publishLettermintDnsRecords(zoneId, records) {
+        const cf = this.ports.cloudflare;
+        for (const record of records) {
+            if (record.type === 'TXT' && record.value.toLowerCase().startsWith('v=dmarc1')) {
+                await this.ensureLettermintDmarcRecord(cf, zoneId, record);
+                continue;
+            }
+            const [existing] = await cf.findDnsRecord(zoneId, record.name, record.type);
+            const rec = { type: record.type, name: record.name, content: record.value };
+            if (existing) {
+                await cf.updateDnsRecord(zoneId, existing.id, rec);
+            }
+            else {
+                await cf.createDnsRecord(zoneId, rec);
+            }
+        }
+    }
+    /**
+     * Never overwrites an existing `_dmarc` record -- a stricter policy an org
+     * already set (`p=quarantine`/`p=reject`) should not be relaxed back to
+     * Lettermint's own `p=none` default.
+     */
+    async ensureLettermintDmarcRecord(cf, zoneId, record) {
+        const hasDmarc = (await cf.findDnsRecord(zoneId, record.name, 'TXT')).some((r) => r.content.toLowerCase().startsWith('v=dmarc1'));
+        if (hasDmarc)
+            return;
+        await cf.createDnsRecord(zoneId, { type: 'TXT', name: record.name, content: record.value });
+    }
     // ---- files / ai --------------------------------------------------------
     /**
      * #80: provisions the org's own organisation on Files, before
@@ -1118,7 +2217,8 @@ export class FoundryStepExecutor {
      * idempotent by find-or-create, not by checking `recordedIds` first.
      */
     async filesOrganisation(action, org) {
-        const provisioned = await this.ports.filesOrganisation.provisionOrganisation({
+        const files = await this.filesPort();
+        const provisioned = await files.provisionOrganisation({
             organisationId: org.id,
             ceilingBytes: action.desired.ceilingBytes ?? null,
             ceilingMicros: action.desired.ceilingMicros ?? null,
@@ -1126,9 +2226,9 @@ export class FoundryStepExecutor {
         return { resourceId: provisioned.organisationId };
     }
     async filesStorage(action, org) {
-        const limits = this.ports.filesLimitsFor(org.id);
-        await limits.setQuota(action.desired.limitBytes ?? null);
-        await limits.setBudget(action.desired.limitMicros ?? null);
+        const files = await this.filesPort();
+        await files.setQuota(org.id, action.desired.limitBytes ?? null);
+        await files.setBudget(org.id, action.desired.limitMicros ?? null);
         return { resourceId: org.id };
     }
     /**
@@ -1139,11 +2239,12 @@ export class FoundryStepExecutor {
      * every time regardless of whether they already ran.
      */
     async aiOrganisation(action, org) {
-        const provisioned = await this.ports.aiOrganisation.provisionOrganisation({
+        const ai = await this.aiPort();
+        const provisioned = await ai.provisionOrganisation({
             organisationId: org.id,
             limitMicros: action.desired.limitMicros ?? null,
         });
-        await this.ports.aiOrganisation.setOrganisationOffers(org.id, action.desired.offers ?? []);
+        await ai.setOrganisationOffers(org.id, action.desired.offers ?? []);
         return { resourceId: provisioned.organisationId };
     }
     async aiBudget(action, org) {
@@ -1154,10 +2255,48 @@ export class FoundryStepExecutor {
             // (Finding, this campaign's report).
             throw new Error(`ai:budget for ${org.slug}: AI's updateBudget has no uncapped representation (UpdateBudget.limitMicros is a required string); declare a numeric limit until AI's API adds one`);
         }
-        const limits = this.ports.aiLimitsFor(org.id);
-        await limits.updateBudget({ keyId: null, limitMicros });
+        const ai = await this.aiPort();
+        await ai.updateBudget(org.id, { keyId: null, limitMicros });
         return { resourceId: org.id };
     }
+    /**
+     * #80 step 3: mints the org's own ai key, once, and hands its one-time
+     * secret straight to {@link FoundryStepExecutorPorts.deliverSecret} --
+     * never returned, stored in `serviceIds` or logged, the same discipline
+     * `zitadelApp`'s own `created.clientSecret` follows. `diff.ts`'s
+     * `planAiKey` never plans this step again once its resource id
+     * (the key's id, not its secret) is recorded, since ai's own API offers no
+     * way to check for an already-minted key.
+     */
+    async aiKey(action, org, context) {
+        const ai = await this.aiPort();
+        const issued = await ai.issueOrganisationKey(org.id, {
+            name: action.desired.name,
+            expiresDays: action.desired.expiresDays,
+            permissions: action.desired.permissions ?? [],
+        });
+        // Recorded before the secret is delivered: a step's return value is only
+        // recorded on success, so a delivery that throws would otherwise lose
+        // the id and the retry would mint a second, orphaned key. `planAiKey`
+        // treats this id as undelivered until the returned resource id (which
+        // only a delivered key gets) is recorded too.
+        context.recordScopeId(AI_KEY_UNDELIVERED_SCOPE_KEY, issued.id);
+        // Written now, so a crash during delivery cannot lose the id either.
+        await context.persistScopeIds();
+        let lastError;
+        for (let attempt = 1; attempt <= AI_KEY_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.deliverSecret(`ai:key:${org.slug}`, issued.secret);
+                return { resourceId: issued.id };
+            }
+            catch (e) {
+                lastError = e;
+            }
+        }
+        // Names the key id only; the underlying error is dropped in case it
+        // echoes the secret.
+        throw new Error(`ai:key for ${org.slug}: key ${issued.id} was minted but its secret could not be delivered after ${AI_KEY_DELIVERY_ATTEMPTS} attempts (${lastError instanceof Error ? lastError.name : 'error'}); revoke it in ai before a new one is minted`);
+    }
     // ---- destroy -------------------------------------------------------------
     /**
      * {@link StepDestroyer.destroy}: deletes the one resource
@@ -1233,7 +2372,7 @@ export class FoundryStepExecutor {
  * status in: the first `→ `, after the client, method and path, and before
  * `:`. It never scans the path or the response body.
  */
-function isNotFoundError(error) {
+export function isNotFoundError(error) {
     const status = error?.status;
     if (typeof status === 'number')
         return status === 404;