@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/frontend-definitions/settings-destination-ref.definitions.js

@@ -57,6 +57,15 @@ export var EngineSettingsDestinationRef;
     EngineSettingsDestinationRef["ORGANIZATION_GENERAL"] = "organization-general";
     /** Organization membership list, including INVITED rows. Org owner/admin only. */
     EngineSettingsDestinationRef["MEMBERS"] = "members";
+    /**
+     * The organization's internal structure — teams, departments, the hierarchy under the tenant.
+     *
+     * Its own rail entry rather than a tab inside {@link ORGANIZATION_GENERAL}. The general pane is a
+     * record — a column of decisions about the tenant itself — and a unit hierarchy is a population
+     * you navigate, which is a different kind of surface and a different task. Nesting it there also
+     * put it behind a pane a reader had no other reason to open.
+     */
+    EngineSettingsDestinationRef["ORGANIZATION_UNITS"] = "organization-units";
     /** Billing home — subscription, plans, usage, invoices. Gated on the `billingEnabled` capability. */
     EngineSettingsDestinationRef["BILLING"] = "billing";
     /** Organization API keys. Org owner/admin only. */
@@ -91,7 +100,115 @@ export var EngineSettingsDestinationRef;
     EngineSettingsDestinationRef["WEBHOOKS"] = "webhooks";
     /** The organization's audit log. Org owner/admin only. */
     EngineSettingsDestinationRef["AUDIT_LOGS"] = "audit-logs";
+    /**
+     * What THIS organization is currently entitled to — its features, its numeric limits, and the
+     * application-administrator exceptions laid over them.
+     *
+     * Readable by any organization member (`organizationFeatures` READ is `ORG_MEMBER`), which is why
+     * it carries no `requiredRoles`: a member who is told a surface needs an upgrade should be able to
+     * see what their organization actually has. The operations that CHANGE it — enable, disable, reset
+     * — are `APP_ADMIN_SUPER_ADMIN` on the resource itself, so the same screen is a read-only summary
+     * for a member and the grant/withdraw console for a platform administrator.
+     *
+     * Until this existed there was no way to reach the entitlement state from anywhere in the product:
+     * the resource had a table, an admin UI behaviour and three custom operations, and no door.
+     */
+    EngineSettingsDestinationRef["ORGANIZATION_ENTITLEMENTS"] = "organization-entitlements";
+    /** Referral codes and their redemptions. Organization-scoped despite living in the billing domain. */
+    EngineSettingsDestinationRef["ORGANIZATION_REFERRALS"] = "organization-referrals";
+    // ── Application administration ──────────────────────────────────────────────
+    //
+    // Everything below is `ResourcePrimaryScope.APPLICATION`: it configures the APPLICATION ITSELF
+    // rather than one tenant inside it, and it is the operator's surface, not a customer's. The
+    // category an application places these in is what supplies that scope, and
+    // `useVisibleSettingsHubConfig` resolves the application id from `appIdentity` — the access
+    // token does not carry one, so a category scoped this way was unreachable until 2026-09-17.
+    //
+    // Each mirrors an organization-scope sibling above, and the pairs are NOT redundant: an
+    // application-wide SSO connection authenticates everybody who is not covered by a tenant's own,
+    // and an application-wide SIEM export carries the operator's own security events rather than a
+    // customer's. Same mechanism, different principal, different consequence.
+    /** The application's own descriptive record — name, description, the operator's identity. */
+    EngineSettingsDestinationRef["APPLICATION_GENERAL"] = "application-general";
+    /** Released versions of the application. */
+    EngineSettingsDestinationRef["APPLICATION_VERSIONS"] = "application-versions";
+    /**
+     * OAuth clients registered against the APPLICATION — the credential a machine presents for a
+     * client-credentials or authorization-code exchange.
+     *
+     * The sibling of {@link APPLICATION_API_KEYS} rather than a duplicate of it: under
+     * client-credentials both authenticate the same `APPLICATION_MACHINE` principal, so they are two
+     * credential TYPES for one identity and belong side by side.
+     */
+    EngineSettingsDestinationRef["APPLICATION_OAUTH_CLIENTS"] = "application-oauth-clients";
+    /**
+     * The two-person rule, made reviewable — requested, signed, time-bound elevations over the
+     * application-wide reads.
+     *
+     * Placed because a control of this kind is justified by VISIBILITY rather than by prevention:
+     * it does not stop an operator reading across tenants, it makes a second administrator sign for
+     * it and leaves a record. An elevation nobody can read makes nothing visible, so the mechanism
+     * ran without its own justification until this had a door.
+     */
+    EngineSettingsDestinationRef["APPLICATION_ACCESS_GRANTS"] = "application-access-grants";
+    /**
+     * The application-wide audit trail — every tenant's events plus the ones belonging to no tenant.
+     *
+     * Distinct from the organization {@link AUDIT_LOGS} by the question it answers, not by scope
+     * alone: the tenant door answers "what happened in my organization", this one answers "what
+     * happened at all", and only the second can support a deployment-level attestation. Every read
+     * through it is a declared crossing and emits one event into each tenant it reached.
+     */
+    EngineSettingsDestinationRef["APPLICATION_AUDIT_LOGS"] = "application-audit-logs";
+    /** The application-scope feature and limit state, with administrator exceptions. */
+    EngineSettingsDestinationRef["APPLICATION_ENTITLEMENTS"] = "application-entitlements";
+    /** API keys that authenticate a machine to the APPLICATION rather than to one organization. */
+    EngineSettingsDestinationRef["APPLICATION_API_KEYS"] = "application-api-keys";
+    /** Application-wide single sign-on: the configuration, and the connections it admits. */
+    EngineSettingsDestinationRef["APPLICATION_SSO"] = "application-sso";
+    /**
+     * Application-wide SCIM directory provisioning.
+     *
+     * One target rather than the organization sibling's two tabs, and that asymmetry is real rather
+     * than an omission: there is no `APPLICATION_SCIM_TOKENS` resource — only
+     * `ORGANIZATION_SCIM_TOKENS` exists — so the application scope has a provisioning configuration
+     * and nothing to tab to.
+     */
+    EngineSettingsDestinationRef["APPLICATION_SCIM"] = "application-scim";
+    /** Application-wide audit-event streaming, and the deliveries that failed. */
+    EngineSettingsDestinationRef["APPLICATION_SIEM"] = "application-siem";
+    /** Application-wide outbound webhooks, and their delivery log. */
+    EngineSettingsDestinationRef["APPLICATION_WEBHOOKS"] = "application-webhooks";
+    /**
+     * The billing CATALOGUE the application sells — products, their prices, and promotions.
+     *
+     * Distinct from the organization `BILLING` destination, which is one tenant's subscription and
+     * invoices. This is the operator editing what is on sale; that is a customer reading what they
+     * bought.
+     */
+    EngineSettingsDestinationRef["BILLING_CATALOG"] = "billing-catalog";
 })(EngineSettingsDestinationRef || (EngineSettingsDestinationRef = {}));
+/**
+ * ## Two administration surfaces that are DELIBERATELY absent, so neither is re-proposed
+ *
+ * **A tenant directory.** `organizations` LIST looks like one and is not: it is confined by
+ * `assignScopeRootCollectionConfinementToFilter` to the tenants the caller holds an
+ * organization-wide role entry for, so a platform super-administrator sees THEIR OWN organizations
+ * and not every tenant. That confinement is deliberate — the resource's own banner says so, and
+ * says explicitly that an operator who "cannot find the tenant id" should stop rather than widen
+ * the operation, because widening it hands the full customer list to every platform administrator
+ * as a standing privilege. A destination named "Organizations" under Administration would promise
+ * the directory and deliver the memberships, which is worse than having no entry: the reader
+ * cannot tell the difference, and the number looks authoritative.
+ *
+ * **A user directory.** Same shape one level down. The application-wide user read is gated on a
+ * two-person `applicationAccessGrants` window precisely so that it is not a standing privilege, so
+ * a permanently-placed rail entry would either sit there refusing or quietly bypass the control it
+ * is supposed to pass through.
+ *
+ * Both become placeable when a governed cross-tenant read exists — an operation that requires the
+ * grant and says so. Neither becomes placeable by widening the operation that is already there.
+ */
 /** @wildo_source:part:end saas.frontend.settings-hub.engine-destinations */
 /**
  * Every destination ref the engine ships — the set an authored placement is validated against.

package/dist/esm/frontend-definitions/settings-destination-ref.definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings-destination-ref.definitions.js","sourceRoot":"","sources":["../../../src/frontend-definitions/settings-destination-ref.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oJAAoJ;AACpJ;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,4BAiDX;AAjDD,WAAY,4BAA4B;IACtC,+CAA+C;IAC/C,mDAAmB,CAAA;IACnB,wDAAwD;IACxD,qDAAqB,CAAA;IACrB,iEAAiE;IACjE,yDAAyB,CAAA;IACzB,kDAAkD;IAClD,2DAA2B,CAAA;IAC3B,8FAA8F;IAC9F,iEAAiC,CAAA;IACjC,mEAAmE;IACnE,6EAA6C,CAAA;IAC7C,kFAAkF;IAClF,mDAAmB,CAAA;IACnB,qGAAqG;IACrG,mDAAmB,CAAA;IACnB,mDAAmD;IACnD,qDAAqB,CAAA;IACrB;;;;;;OAMG;IACH,6EAA6C,CAAA;IAC7C;;;;;;;;;;OAUG;IACH,mFAAmD,CAAA;IACnD,oDAAoD;IACpD,2CAAW,CAAA;IACX,4DAA4D;IAC5D,6CAAa,CAAA;IACb,qEAAqE;IACrE,6CAAa,CAAA;IACb,mDAAmD;IACnD,qDAAqB,CAAA;IACrB,0DAA0D;IAC1D,yDAAyB,CAAA;AAC3B,CAAC,EAjDW,4BAA4B,KAA5B,4BAA4B,QAiDvC;AACD,4EAA4E;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAwB,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,4BAA4B,CAAC,CAAC,CAAC","sourcesContent":["/**\n * The IDENTITY half of the engine's settings-hub catalogue — the refs, and nothing else.\n *\n * ## Why the identity lives here and the catalogue does not\n *\n * A settings destination has two halves, and only one of them is a rendering concern:\n *\n * - **What a destination IS** — its `target` (a resource operation, a bespoke engine panel, a set\n *   of sub-tabs), its role gating, its runtime-capability gating. That half names components and\n *   panel refs, so it belongs to `@wildo-ai/saas-frontend-lib`, where `ENGINE_SETTINGS_DESTINATIONS`\n *   declares it.\n * - **WHICH destinations exist** — a closed set of ids. That half names nothing renderable. It is\n *   the vocabulary an application's `SettingsHubConfig` addresses by string, the vocabulary the\n *   app-creation placement plan names in a `PlacementSubject`, and the vocabulary engine code\n *   addresses by enum member. It is declared here.\n *\n * The split was made 2026-09-09 because the second half had a consumer the first half's package\n * could never serve. `validatePlacementPlan`'s `UNKNOWN_SUBJECT` finding is a HARD FLOOR — it\n * refuses a landing — and it can only fire when a caller supplies the universe of subjects that\n * exist. Its one production caller is the app-creation semantic authority, a backend-side package\n * that must not depend on `saas-frontend-lib`. So a declared refusal had no holder, for no reason\n * other than where a list of sixteen strings was written down.\n *\n * Nothing is re-exported across the boundary: `saas-frontend-lib` imports the enum from here and\n * declares only the catalogue.\n */\n\n/** @wildo_source:part:start saas.frontend.settings-hub.engine-destinations facet:layer:frontend facet:family:config facet:audience:app-developer */\n/**\n * Every settings destination the engine ships, as a named vocabulary.\n *\n * Imported from `@wildo-ai/saas-models`. Exists because these refs are a CLOSED\n * vocabulary that engine code addresses by name — the billing command-menu entry\n * opens `/settings/billing`, and any future engine launcher will do the same.\n * Before this enum, `'billing'` was a bare literal in `billing-launcher.ts` with\n * nothing tying it to the catalog entry it names: rename the destination and the\n * command silently resolves to the hub's DEFAULT section instead of failing, so a\n * menu item labelled \"Billing\" would open Profile.\n *\n * **Engine code must address a destination through this enum. Application\n * config addresses one by string**, deliberately: a placement is authored data,\n * an application should not import an engine enum to write its own rail, and a\n * typo there is caught at DEV startup by `verifySettingsHubContent`.\n */\nexport enum EngineSettingsDestinationRef {\n  /** The signed-in user's own profile record. */\n  PROFILE = 'profile',\n  /** Password, MFA, sessions — a bespoke engine panel. */\n  SECURITY = 'security',\n  /** Theme and appearance preferences — a bespoke engine panel. */\n  APPEARANCE = 'appearance',\n  /** The signed-in user's own preference record. */\n  PREFERENCES = 'preferences',\n  /** Invitations addressed TO the signed-in user, across organizations they have not joined. */\n  MY_INVITATIONS = 'my-invitations',\n  /** The current organization's own record. Org owner/admin only. */\n  ORGANIZATION_GENERAL = 'organization-general',\n  /** Organization membership list, including INVITED rows. Org owner/admin only. */\n  MEMBERS = 'members',\n  /** Billing home — subscription, plans, usage, invoices. Gated on the `billingEnabled` capability. */\n  BILLING = 'billing',\n  /** Organization API keys. Org owner/admin only. */\n  API_KEYS = 'api-keys',\n  /**\n   * The tenant's OWN credentials toward third parties — its Slack workspace token, its CRM key.\n   *\n   * The mirror image of {@link API_KEYS} and easy to confuse with it: an API key is a credential\n   * somebody uses to reach THIS application, and one of these is a credential this application uses\n   * to reach somebody else ON THIS TENANT'S BEHALF. Same administrator, opposite direction.\n   */\n  PROVIDER_CREDENTIALS = 'provider-credentials',\n  /**\n   * The signed-in person's OWN credentials toward third parties — their personal API key, the\n   * account they connected themselves.\n   *\n   * Distinct from {@link PROVIDER_CREDENTIALS} by OWNER, not by feature, and the two must never be\n   * merged into one screen. A tenant's credential is a shared integration an administrator\n   * configures for everyone; this one is an individual's own account, which nobody else may see,\n   * spend or remove. Putting them on one page would put a colleague's personal vendor token in an\n   * administrator's view — and the resource's authorization refuses that, so the screen would show\n   * an empty list nobody could explain.\n   */\n  MY_PROVIDER_CREDENTIALS = 'my-provider-credentials',\n  /** Single sign-on configuration and connections. */\n  SSO = 'sso',\n  /** SCIM directory provisioning configuration and tokens. */\n  SCIM = 'scim',\n  /** Audit-event streaming configuration and failed-delivery queue. */\n  SIEM = 'siem',\n  /** Outbound webhook endpoints and delivery log. */\n  WEBHOOKS = 'webhooks',\n  /** The organization's audit log. Org owner/admin only. */\n  AUDIT_LOGS = 'audit-logs',\n}\n/** @wildo_source:part:end saas.frontend.settings-hub.engine-destinations */\n\n/**\n * Every destination ref the engine ships — the set an authored placement is validated against.\n *\n * **Derived from the enum, not from the catalogue, and that is the point.** It used to be\n * `ENGINE_SETTINGS_DESTINATIONS.map(d => d.ref)`, which made the set a statement about how many\n * catalogue entries had been written rather than about what the vocabulary contains: a member added\n * to the enum and not yet given a catalogue entry would have been silently absent from the universe\n * a hard floor is measured against, so a placement naming it would have been refused as UNKNOWN.\n * Deriving from the enum is TOTAL over the vocabulary — a member added tomorrow is in this set the\n * same day — and the reverse obligation (every ref has a catalogue entry) is pinned in\n * `saas-frontend-lib`, where the catalogue lives and where an omission is a rendering defect.\n *\n * Values are bare ids, the shape `placementSubjectLocalKey` publishes for\n * `ENGINE_SETTINGS_DESTINATION` subjects, so this set can be handed to `validatePlacementPlan`\n * without being re-spelled.\n */\nexport const ENGINE_SETTINGS_DESTINATION_REFS: ReadonlySet<string> = new Set<string>(Object.values(EngineSettingsDestinationRef));\n"]}
+{"version":3,"file":"settings-destination-ref.definitions.js","sourceRoot":"","sources":["../../../../src/frontend-definitions/settings-destination-ref.definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oJAAoJ;AACpJ;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAN,IAAY,4BAmJX;AAnJD,WAAY,4BAA4B;IACtC,+CAA+C;IAC/C,mDAAmB,CAAA;IACnB,wDAAwD;IACxD,qDAAqB,CAAA;IACrB,iEAAiE;IACjE,yDAAyB,CAAA;IACzB,kDAAkD;IAClD,2DAA2B,CAAA;IAC3B,8FAA8F;IAC9F,iEAAiC,CAAA;IACjC,mEAAmE;IACnE,6EAA6C,CAAA;IAC7C,kFAAkF;IAClF,mDAAmB,CAAA;IACnB;;;;;;;OAOG;IACH,yEAAyC,CAAA;IACzC,qGAAqG;IACrG,mDAAmB,CAAA;IACnB,mDAAmD;IACnD,qDAAqB,CAAA;IACrB;;;;;;OAMG;IACH,6EAA6C,CAAA;IAC7C;;;;;;;;;;OAUG;IACH,mFAAmD,CAAA;IACnD,oDAAoD;IACpD,2CAAW,CAAA;IACX,4DAA4D;IAC5D,6CAAa,CAAA;IACb,qEAAqE;IACrE,6CAAa,CAAA;IACb,mDAAmD;IACnD,qDAAqB,CAAA;IACrB,0DAA0D;IAC1D,yDAAyB,CAAA;IACzB;;;;;;;;;;;;OAYG;IACH,uFAAuD,CAAA;IACvD,sGAAsG;IACtG,iFAAiD,CAAA;IAEjD,+EAA+E;IAC/E,EAAE;IACF,+FAA+F;IAC/F,4FAA4F;IAC5F,2EAA2E;IAC3E,4FAA4F;IAC5F,4FAA4F;IAC5F,EAAE;IACF,wFAAwF;IACxF,gGAAgG;IAChG,+FAA+F;IAC/F,0EAA0E;IAE1E,6FAA6F;IAC7F,2EAA2C,CAAA;IAC3C,4CAA4C;IAC5C,6EAA6C,CAAA;IAC7C;;;;;;;OAOG;IACH,uFAAuD,CAAA;IACvD;;;;;;;;OAQG;IACH,uFAAuD,CAAA;IACvD;;;;;;;OAOG;IACH,iFAAiD,CAAA;IACjD,oFAAoF;IACpF,qFAAqD,CAAA;IACrD,+FAA+F;IAC/F,6EAA6C,CAAA;IAC7C,yFAAyF;IACzF,mEAAmC,CAAA;IACnC;;;;;;;OAOG;IACH,qEAAqC,CAAA;IACrC,8EAA8E;IAC9E,qEAAqC,CAAA;IACrC,kEAAkE;IAClE,6EAA6C,CAAA;IAC7C;;;;;;OAMG;IACH,mEAAmC,CAAA;AACrC,CAAC,EAnJW,4BAA4B,KAA5B,4BAA4B,QAmJvC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4EAA4E;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAwB,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,4BAA4B,CAAC,CAAC,CAAC","sourcesContent":["/**\n * The IDENTITY half of the engine's settings-hub catalogue — the refs, and nothing else.\n *\n * ## Why the identity lives here and the catalogue does not\n *\n * A settings destination has two halves, and only one of them is a rendering concern:\n *\n * - **What a destination IS** — its `target` (a resource operation, a bespoke engine panel, a set\n *   of sub-tabs), its role gating, its runtime-capability gating. That half names components and\n *   panel refs, so it belongs to `@wildo-ai/saas-frontend-lib`, where `ENGINE_SETTINGS_DESTINATIONS`\n *   declares it.\n * - **WHICH destinations exist** — a closed set of ids. That half names nothing renderable. It is\n *   the vocabulary an application's `SettingsHubConfig` addresses by string, the vocabulary the\n *   app-creation placement plan names in a `PlacementSubject`, and the vocabulary engine code\n *   addresses by enum member. It is declared here.\n *\n * The split was made 2026-09-09 because the second half had a consumer the first half's package\n * could never serve. `validatePlacementPlan`'s `UNKNOWN_SUBJECT` finding is a HARD FLOOR — it\n * refuses a landing — and it can only fire when a caller supplies the universe of subjects that\n * exist. Its one production caller is the app-creation semantic authority, a backend-side package\n * that must not depend on `saas-frontend-lib`. So a declared refusal had no holder, for no reason\n * other than where a list of sixteen strings was written down.\n *\n * Nothing is re-exported across the boundary: `saas-frontend-lib` imports the enum from here and\n * declares only the catalogue.\n */\n\n/** @wildo_source:part:start saas.frontend.settings-hub.engine-destinations facet:layer:frontend facet:family:config facet:audience:app-developer */\n/**\n * Every settings destination the engine ships, as a named vocabulary.\n *\n * Imported from `@wildo-ai/saas-models`. Exists because these refs are a CLOSED\n * vocabulary that engine code addresses by name — the billing command-menu entry\n * opens `/settings/billing`, and any future engine launcher will do the same.\n * Before this enum, `'billing'` was a bare literal in `billing-launcher.ts` with\n * nothing tying it to the catalog entry it names: rename the destination and the\n * command silently resolves to the hub's DEFAULT section instead of failing, so a\n * menu item labelled \"Billing\" would open Profile.\n *\n * **Engine code must address a destination through this enum. Application\n * config addresses one by string**, deliberately: a placement is authored data,\n * an application should not import an engine enum to write its own rail, and a\n * typo there is caught at DEV startup by `verifySettingsHubContent`.\n */\nexport enum EngineSettingsDestinationRef {\n  /** The signed-in user's own profile record. */\n  PROFILE = 'profile',\n  /** Password, MFA, sessions — a bespoke engine panel. */\n  SECURITY = 'security',\n  /** Theme and appearance preferences — a bespoke engine panel. */\n  APPEARANCE = 'appearance',\n  /** The signed-in user's own preference record. */\n  PREFERENCES = 'preferences',\n  /** Invitations addressed TO the signed-in user, across organizations they have not joined. */\n  MY_INVITATIONS = 'my-invitations',\n  /** The current organization's own record. Org owner/admin only. */\n  ORGANIZATION_GENERAL = 'organization-general',\n  /** Organization membership list, including INVITED rows. Org owner/admin only. */\n  MEMBERS = 'members',\n  /**\n   * The organization's internal structure — teams, departments, the hierarchy under the tenant.\n   *\n   * Its own rail entry rather than a tab inside {@link ORGANIZATION_GENERAL}. The general pane is a\n   * record — a column of decisions about the tenant itself — and a unit hierarchy is a population\n   * you navigate, which is a different kind of surface and a different task. Nesting it there also\n   * put it behind a pane a reader had no other reason to open.\n   */\n  ORGANIZATION_UNITS = 'organization-units',\n  /** Billing home — subscription, plans, usage, invoices. Gated on the `billingEnabled` capability. */\n  BILLING = 'billing',\n  /** Organization API keys. Org owner/admin only. */\n  API_KEYS = 'api-keys',\n  /**\n   * The tenant's OWN credentials toward third parties — its Slack workspace token, its CRM key.\n   *\n   * The mirror image of {@link API_KEYS} and easy to confuse with it: an API key is a credential\n   * somebody uses to reach THIS application, and one of these is a credential this application uses\n   * to reach somebody else ON THIS TENANT'S BEHALF. Same administrator, opposite direction.\n   */\n  PROVIDER_CREDENTIALS = 'provider-credentials',\n  /**\n   * The signed-in person's OWN credentials toward third parties — their personal API key, the\n   * account they connected themselves.\n   *\n   * Distinct from {@link PROVIDER_CREDENTIALS} by OWNER, not by feature, and the two must never be\n   * merged into one screen. A tenant's credential is a shared integration an administrator\n   * configures for everyone; this one is an individual's own account, which nobody else may see,\n   * spend or remove. Putting them on one page would put a colleague's personal vendor token in an\n   * administrator's view — and the resource's authorization refuses that, so the screen would show\n   * an empty list nobody could explain.\n   */\n  MY_PROVIDER_CREDENTIALS = 'my-provider-credentials',\n  /** Single sign-on configuration and connections. */\n  SSO = 'sso',\n  /** SCIM directory provisioning configuration and tokens. */\n  SCIM = 'scim',\n  /** Audit-event streaming configuration and failed-delivery queue. */\n  SIEM = 'siem',\n  /** Outbound webhook endpoints and delivery log. */\n  WEBHOOKS = 'webhooks',\n  /** The organization's audit log. Org owner/admin only. */\n  AUDIT_LOGS = 'audit-logs',\n  /**\n   * What THIS organization is currently entitled to — its features, its numeric limits, and the\n   * application-administrator exceptions laid over them.\n   *\n   * Readable by any organization member (`organizationFeatures` READ is `ORG_MEMBER`), which is why\n   * it carries no `requiredRoles`: a member who is told a surface needs an upgrade should be able to\n   * see what their organization actually has. The operations that CHANGE it — enable, disable, reset\n   * — are `APP_ADMIN_SUPER_ADMIN` on the resource itself, so the same screen is a read-only summary\n   * for a member and the grant/withdraw console for a platform administrator.\n   *\n   * Until this existed there was no way to reach the entitlement state from anywhere in the product:\n   * the resource had a table, an admin UI behaviour and three custom operations, and no door.\n   */\n  ORGANIZATION_ENTITLEMENTS = 'organization-entitlements',\n  /** Referral codes and their redemptions. Organization-scoped despite living in the billing domain. */\n  ORGANIZATION_REFERRALS = 'organization-referrals',\n\n  // ── Application administration ──────────────────────────────────────────────\n  //\n  // Everything below is `ResourcePrimaryScope.APPLICATION`: it configures the APPLICATION ITSELF\n  // rather than one tenant inside it, and it is the operator's surface, not a customer's. The\n  // category an application places these in is what supplies that scope, and\n  // `useVisibleSettingsHubConfig` resolves the application id from `appIdentity` — the access\n  // token does not carry one, so a category scoped this way was unreachable until 2026-09-17.\n  //\n  // Each mirrors an organization-scope sibling above, and the pairs are NOT redundant: an\n  // application-wide SSO connection authenticates everybody who is not covered by a tenant's own,\n  // and an application-wide SIEM export carries the operator's own security events rather than a\n  // customer's. Same mechanism, different principal, different consequence.\n\n  /** The application's own descriptive record — name, description, the operator's identity. */\n  APPLICATION_GENERAL = 'application-general',\n  /** Released versions of the application. */\n  APPLICATION_VERSIONS = 'application-versions',\n  /**\n   * OAuth clients registered against the APPLICATION — the credential a machine presents for a\n   * client-credentials or authorization-code exchange.\n   *\n   * The sibling of {@link APPLICATION_API_KEYS} rather than a duplicate of it: under\n   * client-credentials both authenticate the same `APPLICATION_MACHINE` principal, so they are two\n   * credential TYPES for one identity and belong side by side.\n   */\n  APPLICATION_OAUTH_CLIENTS = 'application-oauth-clients',\n  /**\n   * The two-person rule, made reviewable — requested, signed, time-bound elevations over the\n   * application-wide reads.\n   *\n   * Placed because a control of this kind is justified by VISIBILITY rather than by prevention:\n   * it does not stop an operator reading across tenants, it makes a second administrator sign for\n   * it and leaves a record. An elevation nobody can read makes nothing visible, so the mechanism\n   * ran without its own justification until this had a door.\n   */\n  APPLICATION_ACCESS_GRANTS = 'application-access-grants',\n  /**\n   * The application-wide audit trail — every tenant's events plus the ones belonging to no tenant.\n   *\n   * Distinct from the organization {@link AUDIT_LOGS} by the question it answers, not by scope\n   * alone: the tenant door answers \"what happened in my organization\", this one answers \"what\n   * happened at all\", and only the second can support a deployment-level attestation. Every read\n   * through it is a declared crossing and emits one event into each tenant it reached.\n   */\n  APPLICATION_AUDIT_LOGS = 'application-audit-logs',\n  /** The application-scope feature and limit state, with administrator exceptions. */\n  APPLICATION_ENTITLEMENTS = 'application-entitlements',\n  /** API keys that authenticate a machine to the APPLICATION rather than to one organization. */\n  APPLICATION_API_KEYS = 'application-api-keys',\n  /** Application-wide single sign-on: the configuration, and the connections it admits. */\n  APPLICATION_SSO = 'application-sso',\n  /**\n   * Application-wide SCIM directory provisioning.\n   *\n   * One target rather than the organization sibling's two tabs, and that asymmetry is real rather\n   * than an omission: there is no `APPLICATION_SCIM_TOKENS` resource — only\n   * `ORGANIZATION_SCIM_TOKENS` exists — so the application scope has a provisioning configuration\n   * and nothing to tab to.\n   */\n  APPLICATION_SCIM = 'application-scim',\n  /** Application-wide audit-event streaming, and the deliveries that failed. */\n  APPLICATION_SIEM = 'application-siem',\n  /** Application-wide outbound webhooks, and their delivery log. */\n  APPLICATION_WEBHOOKS = 'application-webhooks',\n  /**\n   * The billing CATALOGUE the application sells — products, their prices, and promotions.\n   *\n   * Distinct from the organization `BILLING` destination, which is one tenant's subscription and\n   * invoices. This is the operator editing what is on sale; that is a customer reading what they\n   * bought.\n   */\n  BILLING_CATALOG = 'billing-catalog',\n}\n\n/**\n * ## Two administration surfaces that are DELIBERATELY absent, so neither is re-proposed\n *\n * **A tenant directory.** `organizations` LIST looks like one and is not: it is confined by\n * `assignScopeRootCollectionConfinementToFilter` to the tenants the caller holds an\n * organization-wide role entry for, so a platform super-administrator sees THEIR OWN organizations\n * and not every tenant. That confinement is deliberate — the resource's own banner says so, and\n * says explicitly that an operator who \"cannot find the tenant id\" should stop rather than widen\n * the operation, because widening it hands the full customer list to every platform administrator\n * as a standing privilege. A destination named \"Organizations\" under Administration would promise\n * the directory and deliver the memberships, which is worse than having no entry: the reader\n * cannot tell the difference, and the number looks authoritative.\n *\n * **A user directory.** Same shape one level down. The application-wide user read is gated on a\n * two-person `applicationAccessGrants` window precisely so that it is not a standing privilege, so\n * a permanently-placed rail entry would either sit there refusing or quietly bypass the control it\n * is supposed to pass through.\n *\n * Both become placeable when a governed cross-tenant read exists — an operation that requires the\n * grant and says so. Neither becomes placeable by widening the operation that is already there.\n */\n/** @wildo_source:part:end saas.frontend.settings-hub.engine-destinations */\n\n/**\n * Every destination ref the engine ships — the set an authored placement is validated against.\n *\n * **Derived from the enum, not from the catalogue, and that is the point.** It used to be\n * `ENGINE_SETTINGS_DESTINATIONS.map(d => d.ref)`, which made the set a statement about how many\n * catalogue entries had been written rather than about what the vocabulary contains: a member added\n * to the enum and not yet given a catalogue entry would have been silently absent from the universe\n * a hard floor is measured against, so a placement naming it would have been refused as UNKNOWN.\n * Deriving from the enum is TOTAL over the vocabulary — a member added tomorrow is in this set the\n * same day — and the reverse obligation (every ref has a catalogue entry) is pinned in\n * `saas-frontend-lib`, where the catalogue lives and where an omission is a rendering defect.\n *\n * Values are bare ids, the shape `placementSubjectLocalKey` publishes for\n * `ENGINE_SETTINGS_DESTINATION` subjects, so this set can be handed to `validatePlacementPlan`\n * without being re-spelled.\n */\nexport const ENGINE_SETTINGS_DESTINATION_REFS: ReadonlySet<string> = new Set<string>(Object.values(EngineSettingsDestinationRef));\n"]}

package/dist/esm/guidance/guidance-flow.shared.schemas.d.ts

@@ -1,9 +1,25 @@
 import { z } from 'zod';
 import { OnboardingElementType } from '../config/frontend/onboarding.shared.schemas';
+import type { OnboardingElement } from '../config/frontend/onboarding.shared.schemas';
+import { LifecycleScope, LifecycleStage } from './lifecycle-state.shared.schemas';
+import { ProgressionScope } from './milestone-definition.shared.schemas';
 import { CoreResourceType } from '../resources/resources.shared.core.definitions';
 /** ──────────────────────────────────────────────────────────────
  * Guidance Flow — Render Modes
  * ────────────────────────────────────────────────────────────── */
+/**
+ * @wildo_source:part:start saas.models.guidance-flow facet:layer:shared facet:family:guidance facet:audience:app-developer
+ *
+ * A guidance flow is triggered chrome — a banner, a modal, a tour, a survey — that appears over
+ * whatever the person is looking at when an event fires, remembers whether they finished with it,
+ * and does not come back. Declare flows as `GuidanceFlowDefinition[]` on a frontend module's
+ * `guidanceFlows`. Import from `@wildo-ai/saas-models`.
+ *
+ * Only ONE `OVERLAY` flow is shown at a time: of the active ones, the lowest `priority` number is
+ * shown. The others WAIT — each appears once the one in front of it is completed, skipped or
+ * dismissed in the same session. A flow that never got shown is not saved as started, so a page
+ * reload drops it until its trigger fires again.
+ */
 export declare enum GuidanceRenderMode {
     /** Modal, banner, announcement — rendered on top of the current view */
     OVERLAY = "overlay",
@@ -25,7 +41,31 @@ export declare enum GuidanceFlowScope {
 /** ──────────────────────────────────────────────────────────────
  * Guidance Flow — Audience
  * ────────────────────────────────────────────────────────────── */
-/** Audience targeting — who sees this flow */
+/**
+ * Audience targeting — who sees this flow.
+ *
+ * ## What it may read, and why that boundary is where it is
+ *
+ * Everything here is answered from state the GUIDANCE CONTEXT ALREADY HOLDS: the subject's roles,
+ * their resolved features, the flow states it loaded, and the progression and
+ * lifecycle documents it loads beside them. No criterion reads an arbitrary resource row, and that
+ * is the deliberate line: eligibility is computed on the frontend, synchronously, every time the
+ * eligible set is recomputed. A criterion needing a row nobody has loaded would turn that into a
+ * fetch, and an eligibility question that can be SLOW or FAIL is a different mechanism.
+ *
+ * ## Scope
+ *
+ * The progression and lifecycle criteria read the scope the FLOW declares — a USER flow asks about
+ * the user's own milestones and stage, an ORGANIZATION flow about the organization's. Anything else
+ * would make an org-wide flow gate on whichever member happened to load it.
+ *
+ * ## ANY vs ALL, stated per field because the two readings are both defensible
+ *
+ * A field answering "who are you" is ANY-of (`roles`, the two lifecycle fields): one match is
+ * enough. A field answering "what must already be true" is ALL-of (`requireIfCompleted`,
+ * `requiredMilestones`, `requiredSurveyAnswers`): a prerequisite list with one unmet entry is unmet.
+ * `excludeIfCompleted` is ANY-of because it is a veto — one reason to suppress is enough.
+ */
 export declare const GuidanceAudienceSchema: z.ZodObject<{
     roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
     requiredFeatures: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{
@@ -48,6 +88,16 @@ export declare const GuidanceAudienceSchema: z.ZodObject<{
         }, z.core.$strip>>>;
     }, z.core.$strip>]>>;
     excludeIfCompleted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requireIfCompleted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requiredMilestones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    currentLifecycleStages: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof LifecycleStage>>>;
+    lifecycleStagesReached: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof LifecycleStage>>>;
+    requiredSurveyAnswers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flowRef: z.ZodString;
+        elementRef: z.ZodString;
+        questionId: z.ZodString;
+        equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, z.core.$strip>>>;
     createdAfter: z.ZodOptional<z.ZodCoercedDate<unknown>>;
 }, z.core.$strip>;
 export type GuidanceAudience = z.infer<typeof GuidanceAudienceSchema>;
@@ -70,11 +120,6 @@ export declare const GuidanceFlowDefinitionSchema: z.ZodObject<{
         routePattern: z.ZodOptional<z.ZodString>;
         eventName: z.ZodOptional<z.ZodString>;
         delayMs: z.ZodOptional<z.ZodNumber>;
-        conditions: z.ZodOptional<z.ZodObject<{
-            newUsersOnly: z.ZodDefault<z.ZodBoolean>;
-            triggerOnce: z.ZodDefault<z.ZodBoolean>;
-            requiredRoles: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>;
     }, z.core.$strip>;
     audience: z.ZodOptional<z.ZodObject<{
         roles: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -98,6 +143,16 @@ export declare const GuidanceFlowDefinitionSchema: z.ZodObject<{
             }, z.core.$strip>>>;
         }, z.core.$strip>]>>;
         excludeIfCompleted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        requireIfCompleted: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        requiredMilestones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        currentLifecycleStages: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof LifecycleStage>>>;
+        lifecycleStagesReached: z.ZodOptional<z.ZodArray<z.ZodEnum<typeof LifecycleStage>>>;
+        requiredSurveyAnswers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            flowRef: z.ZodString;
+            elementRef: z.ZodString;
+            questionId: z.ZodString;
+            equals: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        }, z.core.$strip>>>;
         createdAfter: z.ZodOptional<z.ZodCoercedDate<unknown>>;
     }, z.core.$strip>>;
     priority: z.ZodDefault<z.ZodNumber>;
@@ -208,36 +263,36 @@ export declare const GuidanceFlowDefinitionSchema: z.ZodObject<{
                 ref: z.ZodString;
             }, z.core.$strip>>>;
             required: z.ZodDefault<z.ZodBoolean>;
+            bindToField: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         allowSkip: z.ZodDefault<z.ZodBoolean>;
+        bindTo: z.ZodOptional<z.ZodObject<{
+            resourceType: z.ZodString;
+        }, z.core.$strip>>;
         type: z.ZodLiteral<OnboardingElementType.SURVEY>;
     }, z.core.$strip>], "type">>;
-    options: z.ZodOptional<z.ZodObject<{
-        showProgress: z.ZodDefault<z.ZodBoolean>;
-        allowDismiss: z.ZodDefault<z.ZodBoolean>;
-        persistState: z.ZodDefault<z.ZodBoolean>;
-        autoStart: z.ZodDefault<z.ZodBoolean>;
-        allowSkip: z.ZodDefault<z.ZodBoolean>;
-        className: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
     labels: z.ZodOptional<z.ZodObject<{
         description: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type GuidanceFlowDefinition = z.infer<typeof GuidanceFlowDefinitionSchema>;
-/** ──────────────────────────────────────────────────────────────
- * Guidance Flow — Reference
- * ────────────────────────────────────────────────────────────── */
-/** Lightweight reference for toggling/prioritizing flows without repeating the full definition */
-export declare const GuidanceFlowReferenceSchema: z.ZodObject<{
-    ref: z.ZodString;
-    priority: z.ZodOptional<z.ZodNumber>;
-    enabled: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-export type GuidanceFlowReference = z.infer<typeof GuidanceFlowReferenceSchema>;
+/** @wildo_source:part:end saas.models.guidance-flow */
 /** ──────────────────────────────────────────────────────────────
  * Guidance — Scope to Resource Mapping
  * ────────────────────────────────────────────────────────────── */
+/**
+ * The progression scope a flow of this scope asks about (#1373).
+ *
+ * Written as an explicit total map rather than a cast, even though the three scope enums currently
+ * share their wire values. They are DISTINCT vocabularies — a guidance flow's storage scope, a
+ * milestone's accrual scope and a subject's lifecycle scope — and collapsing them because the
+ * strings line up today is what this repository's "never merge semantically distinct concepts
+ * merely because their wire values overlap" rule exists to stop. Being total, a member added to
+ * `GuidanceFlowScope` is a compile error here rather than a silent `undefined` lookup.
+ */
+export declare const GUIDANCE_SCOPE_TO_PROGRESSION_SCOPE: Record<GuidanceFlowScope, ProgressionScope>;
+/** The lifecycle scope a flow of this scope asks about. Total, for the reason above. */
+export declare const GUIDANCE_SCOPE_TO_LIFECYCLE_SCOPE: Record<GuidanceFlowScope, LifecycleScope>;
 /** Maps GuidanceFlowScope to the CoreResourceType that stores its state */
 export declare const GUIDANCE_SCOPE_TO_RESOURCE: Record<GuidanceFlowScope, CoreResourceType>;
 /** ──────────────────────────────────────────────────────────────
@@ -246,4 +301,31 @@ export declare const GUIDANCE_SCOPE_TO_RESOURCE: Record<GuidanceFlowScope, CoreR
 /** Controls which i18n keys are generated per element type.
  *  Follows the ERROR_GUIDANCE_REFS pattern — avoids wasteful cartesian product generation. */
 export declare const GUIDANCE_ELEMENT_FIELDS: Record<OnboardingElementType, string[]>;
+/**
+ * The label fields an element CANNOT be presented without — the subset of
+ * {@link GUIDANCE_ELEMENT_FIELDS} whose absence means the element's copy does not
+ * exist yet, rather than that its author chose to omit an optional slot.
+ *
+ * - **`title`, for every element type.** The labelling pipeline generates EVERY
+ *   field `GUIDANCE_ELEMENT_FIELDS` lists, so a missing title is never an
+ *   authoring choice: it means copy has not been generated for this element at all.
+ * - **`actionLabel`, only when the element declares an ACTION** (`actionRef`, or a
+ *   modal's `ctaAction`) and its type lists the field. A banner offering
+ *   navigation with no label renders no button, so the action the flow exists to
+ *   offer silently disappears (#539).
+ *
+ * `description` and `content` stay optional: an element with no body is legitimate.
+ *
+ * Two consumers act on the answer, and neither may re-derive it:
+ * - the element translator renders the raw KEY for a required field, so a missing
+ *   label LOOKS missing (`.claude/rules/display-text-comes-from-i18n.md`) instead of
+ *   collapsing to an invisible card;
+ * - the guidance renderer records a flow as PRESENTED — which is what spends its
+ *   once-per-user occasion — only when every required label of every element
+ *   resolves.
+ *
+ * Derived from the element's own type and declared action rather than listed per
+ * type, so a new element type is covered the day it joins `GUIDANCE_ELEMENT_FIELDS`.
+ */
+export declare function resolveGuidanceElementRequiredLabelFields(element: OnboardingElement): string[];
 //# sourceMappingURL=guidance-flow.shared.schemas.d.ts.map

package/dist/esm/guidance/guidance-flow.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guidance-flow.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/guidance/guidance-flow.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoD,qBAAqB,EAAE,MAAM,8CAA8C,CAAC;AAGvI,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAElF;;oEAEoE;AAEpE,oBAAY,kBAAkB;IAC5B,wEAAwE;IACxE,OAAO,YAAY;IACnB,wEAAwE;IACxE,MAAM,WAAW;IACjB,2DAA2D;IAC3D,SAAS,cAAc;CACxB;AAED;;oEAEoE;AAEpE,oDAAoD;AACpD,oBAAY,iBAAiB;IAC3B,qEAAqE;IACrE,IAAI,SAAS;IACb,sGAAsG;IACtG,YAAY,iBAAiB;CAC9B;AAED;;oEAEoE;AAEpE,8CAA8C;AAC9C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;iBASjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;oEAEoE;AAEpE,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuBvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;oEAEoE;AAEpE,kGAAkG;AAClG,eAAO,MAAM,2BAA2B;;;;iBAItC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;oEAEoE;AAEpE,2EAA2E;AAC3E,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,CAGlF,CAAC;AAEF;;oEAEoE;AAEpE;8FAC8F;AAC9F,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,EAAE,CAW3E,CAAC"}
+{"version":3,"file":"guidance-flow.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/guidance-flow.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAoD,qBAAqB,EAAE,MAAM,8CAA8C,CAAC;AACvI,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAElF;;oEAEoE;AAEpE;;;;;;;;;;;;GAYG;AAEH,oBAAY,kBAAkB;IAC5B,wEAAwE;IACxE,OAAO,YAAY;IACnB,wEAAwE;IACxE,MAAM,WAAW;IACjB,2DAA2D;IAC3D,SAAS,cAAc;CACxB;AAED;;oEAEoE;AAEpE,oDAAoD;AACpD,oBAAY,iBAAiB;IAC3B,qEAAqE;IACrE,IAAI,SAAS;IACb,sGAAsG;IACtG,YAAY,iBAAiB;CAC9B;AAED;;oEAEoE;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkDjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;oEAEoE;AAEpE,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,uDAAuD;AAYvD;;oEAEoE;AAEpE;;;;;;;;;GASG;AACH,eAAO,MAAM,mCAAmC,EAAE,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,CAG3F,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,iBAAiB,EAAE,cAAc,CAGvF,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,CAGlF,CAAC;AAEF;;oEAEoE;AAEpE;8FAC8F;AAC9F,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,EAAE,CAW3E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yCAAyC,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAU9F"}

package/dist/esm/guidance/guidance-flow.shared.schemas.js

@@ -1,11 +1,25 @@
 import { z } from 'zod';
 import { OnboardingTriggerSchema, OnboardingElementSchema, OnboardingElementType } from '../config/frontend/onboarding.shared.schemas.js';
-import { OnboardingViewOptionsSchema } from '../config/frontend/onboarding.shared.schemas.js';
+import { LifecycleScope, LifecycleStage } from './lifecycle-state.shared.schemas.js';
+import { ProgressionScope } from './milestone-definition.shared.schemas.js';
 import { RequiredFeaturesConfigSchema } from '../features/feature-definition.shared.schemas.js';
 import { CoreResourceType } from '../resources/resources.shared.core.definitions.js';
 /** ──────────────────────────────────────────────────────────────
  * Guidance Flow — Render Modes
  * ────────────────────────────────────────────────────────────── */
+/**
+ * @wildo_source:part:start saas.models.guidance-flow facet:layer:shared facet:family:guidance facet:audience:app-developer
+ *
+ * A guidance flow is triggered chrome — a banner, a modal, a tour, a survey — that appears over
+ * whatever the person is looking at when an event fires, remembers whether they finished with it,
+ * and does not come back. Declare flows as `GuidanceFlowDefinition[]` on a frontend module's
+ * `guidanceFlows`. Import from `@wildo-ai/saas-models`.
+ *
+ * Only ONE `OVERLAY` flow is shown at a time: of the active ones, the lowest `priority` number is
+ * shown. The others WAIT — each appears once the one in front of it is completed, skipped or
+ * dismissed in the same session. A flow that never got shown is not saved as started, so a page
+ * reload drops it until its trigger fires again.
+ */
 export var GuidanceRenderMode;
 (function (GuidanceRenderMode) {
     /** Modal, banner, announcement — rendered on top of the current view */
@@ -29,14 +43,79 @@ export var GuidanceFlowScope;
 /** ──────────────────────────────────────────────────────────────
  * Guidance Flow — Audience
  * ────────────────────────────────────────────────────────────── */
-/** Audience targeting — who sees this flow */
+/**
+ * Audience targeting — who sees this flow.
+ *
+ * ## What it may read, and why that boundary is where it is
+ *
+ * Everything here is answered from state the GUIDANCE CONTEXT ALREADY HOLDS: the subject's roles,
+ * their resolved features, the flow states it loaded, and the progression and
+ * lifecycle documents it loads beside them. No criterion reads an arbitrary resource row, and that
+ * is the deliberate line: eligibility is computed on the frontend, synchronously, every time the
+ * eligible set is recomputed. A criterion needing a row nobody has loaded would turn that into a
+ * fetch, and an eligibility question that can be SLOW or FAIL is a different mechanism.
+ *
+ * ## Scope
+ *
+ * The progression and lifecycle criteria read the scope the FLOW declares — a USER flow asks about
+ * the user's own milestones and stage, an ORGANIZATION flow about the organization's. Anything else
+ * would make an org-wide flow gate on whichever member happened to load it.
+ *
+ * ## ANY vs ALL, stated per field because the two readings are both defensible
+ *
+ * A field answering "who are you" is ANY-of (`roles`, the two lifecycle fields): one match is
+ * enough. A field answering "what must already be true" is ALL-of (`requireIfCompleted`,
+ * `requiredMilestones`, `requiredSurveyAnswers`): a prerequisite list with one unmet entry is unmet.
+ * `excludeIfCompleted` is ANY-of because it is a veto — one reason to suppress is enough.
+ */
 export const GuidanceAudienceSchema = z.object({
     /** Required user roles (any match = eligible). Empty/omitted = all roles. */
     roles: z.array(z.string()).optional(),
     /** Required features using the shared `RequiredFeaturesConfig` semantics. */
     requiredFeatures: RequiredFeaturesConfigSchema.optional(),
-    /** Exclude users who have completed these flows */
+    /** Exclude users who have completed these flows (ANY match suppresses). */
     excludeIfCompleted: z.array(z.string()).optional(),
+    /**
+     * Show only once ALL of these flows have been COMPLETED — the positive counterpart of
+     * `excludeIfCompleted`, and how a second flow follows a first.
+     *
+     * COMPLETED only. A flow that was dismissed or skipped has not met a prerequisite — the person
+     * declined it — and treating those as satisfaction would show a follow-up to exactly the people
+     * who opted out of its lead-in.
+     */
+    requireIfCompleted: z.array(z.string()).optional(),
+    /** Show only once ALL of these milestones are achieved, in the flow's own progression scope. */
+    requiredMilestones: z.array(z.string()).optional(),
+    /**
+     * Show only while the subject's CURRENT lifecycle stage is one of these.
+     *
+     * Distinct from `lifecycleStagesReached` on purpose, because the two answer opposite questions and
+     * confusing them is the likeliest authoring mistake here. This one is "who are you NOW" — it stops
+     * matching the moment the subject moves on, which is what a dormancy nudge wants and what an
+     * "already activated" tip does not.
+     */
+    currentLifecycleStages: z.array(z.enum(LifecycleStage)).optional(),
+    /**
+     * Show once the subject has EVER been in one of these stages.
+     *
+     * Reads `stagesVisited`, which exists precisely so this question survives the stage-history cap.
+     * This is what an onboarding tip usually wants: "once they have activated" stays true after they
+     * go on to ENGAGED, where `currentLifecycleStages: [ACTIVATED]` would silently stop matching.
+     */
+    lifecycleStagesReached: z.array(z.enum(LifecycleStage)).optional(),
+    /**
+     * Show only when ALL of these recorded survey answers match.
+     *
+     * The answer is read from the guidance state the context already holds, so it addresses a
+     * question by the flow, element and question that asked it. Equality only, against the scalar
+     * kinds an answer can be — the point is branching on what somebody said, not a query language.
+     */
+    requiredSurveyAnswers: z.array(z.object({
+        flowRef: z.string().min(1),
+        elementRef: z.string().min(1),
+        questionId: z.string().min(1),
+        equals: z.union([z.string(), z.number(), z.boolean()]),
+    })).optional(),
     /** Only show to users created after this date (for new-user flows) */
     createdAfter: z.coerce.date().optional(),
 });
@@ -61,25 +140,48 @@ export const GuidanceFlowDefinitionSchema = z.object({
     priority: z.number().int().default(100),
     /** Elements in this flow — reuses existing OnboardingElement discriminated union */
     elements: z.array(OnboardingElementSchema),
-    /** Flow-level options */
-    options: OnboardingViewOptionsSchema.optional(),
+    /*
+     * There is no flow-level options block: dismissing, skipping and progress display are set on each
+     * ELEMENT (`dismissible` on banner / modal / announcement / card, `allowSkip` on tour and survey,
+     * `showProgress` on checklist), where the element's renderer reads them.
+     */
     /** i18n: label configuration */
     labels: z.object({
         description: z.boolean().default(false),
     }).optional(),
 });
-/** ──────────────────────────────────────────────────────────────
- * Guidance Flow — Reference
- * ────────────────────────────────────────────────────────────── */
-/** Lightweight reference for toggling/prioritizing flows without repeating the full definition */
-export const GuidanceFlowReferenceSchema = z.object({
-    ref: z.string().min(1),
-    priority: z.number().int().optional(),
-    enabled: z.boolean().default(true),
-});
+/** @wildo_source:part:end saas.models.guidance-flow */
+/*
+ * Maintainer note — kept OUTSIDE the anchor above because it is history, not guidance an application
+ * needs. A flow-level `options` block (`OnboardingViewOptionsSchema`) was REMOVED rather than wired
+ * (#1368): the guidance renderer read none of it. Three of its six members were a second spelling of
+ * a per-element control already enforced where it is read (`dismissible`, `allowSkip`,
+ * `showProgress`), so wiring them would have created two places to say one thing plus a precedence
+ * rule; `persistState: false` named a mode that does not exist; `className` is the theme's; and
+ * `autoStart` is read at neither level. Do not reintroduce it without a renderer that reads it.
+ */
 /** ──────────────────────────────────────────────────────────────
  * Guidance — Scope to Resource Mapping
  * ────────────────────────────────────────────────────────────── */
+/**
+ * The progression scope a flow of this scope asks about (#1373).
+ *
+ * Written as an explicit total map rather than a cast, even though the three scope enums currently
+ * share their wire values. They are DISTINCT vocabularies — a guidance flow's storage scope, a
+ * milestone's accrual scope and a subject's lifecycle scope — and collapsing them because the
+ * strings line up today is what this repository's "never merge semantically distinct concepts
+ * merely because their wire values overlap" rule exists to stop. Being total, a member added to
+ * `GuidanceFlowScope` is a compile error here rather than a silent `undefined` lookup.
+ */
+export const GUIDANCE_SCOPE_TO_PROGRESSION_SCOPE = {
+    [GuidanceFlowScope.USER]: ProgressionScope.USER,
+    [GuidanceFlowScope.ORGANIZATION]: ProgressionScope.ORGANIZATION,
+};
+/** The lifecycle scope a flow of this scope asks about. Total, for the reason above. */
+export const GUIDANCE_SCOPE_TO_LIFECYCLE_SCOPE = {
+    [GuidanceFlowScope.USER]: LifecycleScope.USER,
+    [GuidanceFlowScope.ORGANIZATION]: LifecycleScope.ORGANIZATION,
+};
 /** Maps GuidanceFlowScope to the CoreResourceType that stores its state */
 export const GUIDANCE_SCOPE_TO_RESOURCE = {
     [GuidanceFlowScope.USER]: CoreResourceType.USER_GUIDANCE_STATE,
@@ -102,4 +204,40 @@ export const GUIDANCE_ELEMENT_FIELDS = {
     [OnboardingElementType.CARD]: ['title', 'description', 'content', 'actionLabel'],
     [OnboardingElementType.SURVEY]: ['title', 'description'],
 };
+/**
+ * The label fields an element CANNOT be presented without — the subset of
+ * {@link GUIDANCE_ELEMENT_FIELDS} whose absence means the element's copy does not
+ * exist yet, rather than that its author chose to omit an optional slot.
+ *
+ * - **`title`, for every element type.** The labelling pipeline generates EVERY
+ *   field `GUIDANCE_ELEMENT_FIELDS` lists, so a missing title is never an
+ *   authoring choice: it means copy has not been generated for this element at all.
+ * - **`actionLabel`, only when the element declares an ACTION** (`actionRef`, or a
+ *   modal's `ctaAction`) and its type lists the field. A banner offering
+ *   navigation with no label renders no button, so the action the flow exists to
+ *   offer silently disappears (#539).
+ *
+ * `description` and `content` stay optional: an element with no body is legitimate.
+ *
+ * Two consumers act on the answer, and neither may re-derive it:
+ * - the element translator renders the raw KEY for a required field, so a missing
+ *   label LOOKS missing (`.claude/rules/display-text-comes-from-i18n.md`) instead of
+ *   collapsing to an invisible card;
+ * - the guidance renderer records a flow as PRESENTED — which is what spends its
+ *   once-per-user occasion — only when every required label of every element
+ *   resolves.
+ *
+ * Derived from the element's own type and declared action rather than listed per
+ * type, so a new element type is covered the day it joins `GUIDANCE_ELEMENT_FIELDS`.
+ */
+export function resolveGuidanceElementRequiredLabelFields(element) {
+    const declaredFields = GUIDANCE_ELEMENT_FIELDS[element.type] ?? [];
+    const required = declaredFields.includes('title') ? ['title'] : [];
+    const declaresAction = ('actionRef' in element && typeof element.actionRef === 'string' && element.actionRef.length > 0)
+        || ('ctaAction' in element && typeof element.ctaAction === 'string' && element.ctaAction.length > 0);
+    if (declaresAction && declaredFields.includes('actionLabel')) {
+        required.push('actionLabel');
+    }
+    return required;
+}
 //# sourceMappingURL=guidance-flow.shared.schemas.js.map