@wildo-ai/saas-models 1.1.4 → 1.1.6

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

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

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

package/dist/esm/guidance/guidance-state.shared.resources-config.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guidance-state.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/guidance/guidance-state.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAA8B,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAWzG,KAAK,+BAA+B,GAChC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAE5B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,WAAW,CAAC;AAEtC,eAAO,MAAM,4DAA4D,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;iCAyKzH,CAAC;AAIH,KAAK,uCAAuC,GACxC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,oEAAoE,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;iCAiGjI,CAAC"}
+{"version":3,"file":"guidance-state.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AACvF,OAAO,EAA8B,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAWzG,KAAK,+BAA+B,GAChC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAE5B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,WAAW,CAAC;AAEtC,eAAO,MAAM,4DAA4D,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;iCAyKzH,CAAC;AAIH,KAAK,uCAAuC,GACxC,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,oEAAoE,GAAI,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;iCAiGjI,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"guidance-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAIhF;;oEAEoE;AAEpE,mCAAmC;AACnC,eAAO,MAAM,0BAA0B;;;;;iBASrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;oEAEoE;AAEpE,qBAAqB;AACrB,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAa9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;iBAElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;iBAE1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,yBAAyB,CAAC"}
+{"version":3,"file":"guidance-state.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAIhF;;oEAEoE;AAEpE,mCAAmC;AACnC,eAAO,MAAM,0BAA0B;;;;;iBAUrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;oEAEoE;AAEpE,qBAAqB;AACrB,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;oEAEoE;AAEpE;;wDAEwD;AACxD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;iBAa9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;iBAElC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;iBAE1C,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,yBAAyB,CAAC"}

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

@@ -8,28 +8,29 @@ import { addImpersonalizeWith } from '@wildo-ai/zod-decorators';
  * ────────────────────────────────────────────────────────────── */
 /** Per-element completion state */
 export const GuidanceElementStateSchema = z.object({
-    status: z.enum(OnboardingStatus),
+    status: z.enum(OnboardingStatus).describe('Where this element stands. The guidance engine records an element when it is completed.'),
     /** Timestamp when this element was completed.
      *  Uses z.coerce.date() to handle string → Date coercion on parse (stored as ISO strings in DB). */
-    completedAt: z.coerce.date().optional(),
+    completedAt: z.coerce.date().optional().describe('When this element was completed.'),
     /** For surveys: submitted answers */
-    surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional(),
+    surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()
+        .describe('For a survey element, the submitted answers, keyed by question id. Absent for other element types.'),
     /** For tours: last completed step index */
-    lastStepIndex: z.number().int().optional(),
+    lastStepIndex: z.number().int().optional().describe('For a tour element, the zero-based index of the step on which the tour was finished. Absent for other element types.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Guidance State — Per-Flow State
  * ────────────────────────────────────────────────────────────── */
 /** Per-flow state */
 export const GuidanceFlowStateSchema = z.object({
-    status: z.enum(OnboardingStatus),
-    startedAt: z.coerce.date().optional(),
-    completedAt: z.coerce.date().optional(),
-    dismissedAt: z.coerce.date().optional(),
+    status: z.enum(OnboardingStatus).describe('Where this flow stands. `completed`, `skipped` and `dismissed` are final: a flow in one of them is not shown again.'),
+    startedAt: z.coerce.date().optional().describe('When the flow was first shown.'),
+    completedAt: z.coerce.date().optional().describe('When the flow was completed.'),
+    dismissedAt: z.coerce.date().optional().describe('When the flow was dismissed. Absent unless it was.'),
     /** Element-level state keyed by element ref */
-    elements: z.record(z.string(), GuidanceElementStateSchema).default({}),
+    elements: z.record(z.string(), GuidanceElementStateSchema).default({}).describe('Progress on the flow\'s individual elements, keyed by element reference. Elements not yet completed are absent.'),
     /** How many times this flow has been triggered */
-    triggerCount: z.number().int().default(0),
+    triggerCount: z.number().int().default(0).describe('How many times the flow has been shown. A first-visit flow is shown only while this is 0.'),
 });
 /** ──────────────────────────────────────────────────────────────
  * Guidance State — Top-Level Document

package/dist/esm/guidance/guidance-state.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"guidance-state.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { OnboardingStatus } from '../config/frontend/onboarding.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Element State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-element completion state */\nexport const GuidanceElementStateSchema = z.object({\n  status: z.enum(OnboardingStatus),\n  /** Timestamp when this element was completed.\n   *  Uses z.coerce.date() to handle string → Date coercion on parse (stored as ISO strings in DB). */\n  completedAt: z.coerce.date().optional(),\n  /** For surveys: submitted answers */\n  surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional(),\n  /** For tours: last completed step index */\n  lastStepIndex: z.number().int().optional(),\n});\nexport type GuidanceElementState = z.infer<typeof GuidanceElementStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Flow State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-flow state */\nexport const GuidanceFlowStateSchema = z.object({\n  status: z.enum(OnboardingStatus),\n  startedAt: z.coerce.date().optional(),\n  completedAt: z.coerce.date().optional(),\n  dismissedAt: z.coerce.date().optional(),\n  /** Element-level state keyed by element ref */\n  elements: z.record(z.string(), GuidanceElementStateSchema).default({}),\n  /** How many times this flow has been triggered */\n  triggerCount: z.number().int().default(0),\n});\nexport type GuidanceFlowState = z.infer<typeof GuidanceFlowStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Top-Level Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Shared guidance state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const GuidanceStateSchema = z.object({\n  /** Map of flowRef → flow state */\n  // USAGE — which guidance flows this person has seen and how far through. A record of what they\n  // did in the product, held per user, so a notice must enumerate it.\n  // RESET on erasure — returns this field to its schema default. It holds the per-flow progress map — which guidance flows this person saw and how far through each,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  flows: addImpersonalizeWith(\n  z.record(z.string(), GuidanceFlowStateSchema).default({}).isSummaryField()\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n});\nexport type GuidanceState = z.infer<typeof GuidanceStateSchema>;\n\nexport const UserGuidanceStateSchema = GuidanceStateSchema.extend({\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserGuidanceState = z.infer<typeof UserGuidanceStateSchema>;\n\nexport const OrganizationGuidanceStateSchema = GuidanceStateSchema.extend({\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationGuidanceState = z.infer<typeof OrganizationGuidanceStateSchema>;\n\nexport type PersistedGuidanceState = UserGuidanceState | OrganizationGuidanceState;\n"]}
+{"version":3,"file":"guidance-state.shared.schemas.js","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;oEAEoE;AAEpE,mCAAmC;AACnC,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,yFAAyF,CAAC;IACpI;wGACoG;IACpG,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IACpF,qCAAqC;IACrC,aAAa,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;SAChH,QAAQ,CAAC,oGAAoG,CAAC;IACjH,2CAA2C;IAC3C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sHAAsH,CAAC;CAC5K,CAAC,CAAC;AAGH;;oEAEoE;AAEpE,qBAAqB;AACrB,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,qHAAqH,CAAC;IAChK,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IAChF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IAChF,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;IACtG,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,0BAA0B,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,iHAAiH,CAAC;IAClM,kDAAkD;IAClD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2FAA2F,CAAC;CAChJ,CAAC,CAAC;AAGH;;oEAEoE;AAEpE;;wDAEwD;AACxD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,kCAAkC;IAClC,+FAA+F;IAC/F,oEAAoE;IACpE,mKAAmK;IACnK,iGAAiG;IACjG,iGAAiG;IACjG,wFAAwF;IACxF,KAAK,EAAE,oBAAoB,CAC3B,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,uBAAuB,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,cAAc,EAAE;SACrE,cAAc,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAC7C,aAAa,CAAC,KAAK,CACpB;CACF,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAAmB,CAAC,MAAM,CAAC;IAChE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;CAC5F,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,+BAA+B,GAAG,mBAAmB,CAAC,MAAM,CAAC;IACxE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;CACpG,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { OnboardingStatus } from '../config/frontend/onboarding.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Element State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-element completion state */\nexport const GuidanceElementStateSchema = z.object({\n  status: z.enum(OnboardingStatus).describe('Where this element stands. The guidance engine records an element when it is completed.'),\n  /** Timestamp when this element was completed.\n   *  Uses z.coerce.date() to handle string → Date coercion on parse (stored as ISO strings in DB). */\n  completedAt: z.coerce.date().optional().describe('When this element was completed.'),\n  /** For surveys: submitted answers */\n  surveyAnswers: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()\n    .describe('For a survey element, the submitted answers, keyed by question id. Absent for other element types.'),\n  /** For tours: last completed step index */\n  lastStepIndex: z.number().int().optional().describe('For a tour element, the zero-based index of the step on which the tour was finished. Absent for other element types.'),\n});\nexport type GuidanceElementState = z.infer<typeof GuidanceElementStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Per-Flow State\n * ────────────────────────────────────────────────────────────── */\n\n/** Per-flow state */\nexport const GuidanceFlowStateSchema = z.object({\n  status: z.enum(OnboardingStatus).describe('Where this flow stands. `completed`, `skipped` and `dismissed` are final: a flow in one of them is not shown again.'),\n  startedAt: z.coerce.date().optional().describe('When the flow was first shown.'),\n  completedAt: z.coerce.date().optional().describe('When the flow was completed.'),\n  dismissedAt: z.coerce.date().optional().describe('When the flow was dismissed. Absent unless it was.'),\n  /** Element-level state keyed by element ref */\n  elements: z.record(z.string(), GuidanceElementStateSchema).default({}).describe('Progress on the flow\\'s individual elements, keyed by element reference. Elements not yet completed are absent.'),\n  /** How many times this flow has been triggered */\n  triggerCount: z.number().int().default(0).describe('How many times the flow has been shown. A first-visit flow is shown only while this is 0.'),\n});\nexport type GuidanceFlowState = z.infer<typeof GuidanceFlowStateSchema>;\n\n/** ──────────────────────────────────────────────────────────────\n * Guidance State — Top-Level Document\n * ────────────────────────────────────────────────────────────── */\n\n/** Shared guidance state payload body.\n *  Scope-specific state resources extend this schema with their owning FK\n *  (`userId` / `organizationId`) before persistence. */\nexport const GuidanceStateSchema = z.object({\n  /** Map of flowRef → flow state */\n  // USAGE — which guidance flows this person has seen and how far through. A record of what they\n  // did in the product, held per user, so a notice must enumerate it.\n  // RESET on erasure — returns this field to its schema default. It holds the per-flow progress map — which guidance flows this person saw and how far through each,\n  // which the category above correctly declares as personal data. RESET rather than REMOVE or MASK\n  // because the field is non-nullable WITH a `.default()`: REMOVE needs a clearable field and MASK\n  // needs a string. The value comes from the schema, so there is no second copy to drift.\n  flows: addImpersonalizeWith(\n  z.record(z.string(), GuidanceFlowStateSchema).default({}).isSummaryField()\n      .dataCategories(PersonalDataCategory.USAGE),\n    RedactionType.RESET,\n  ),\n});\nexport type GuidanceState = z.infer<typeof GuidanceStateSchema>;\n\nexport const UserGuidanceStateSchema = GuidanceStateSchema.extend({\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type UserGuidanceState = z.infer<typeof UserGuidanceStateSchema>;\n\nexport const OrganizationGuidanceStateSchema = GuidanceStateSchema.extend({\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n});\nexport type OrganizationGuidanceState = z.infer<typeof OrganizationGuidanceStateSchema>;\n\nexport type PersistedGuidanceState = UserGuidanceState | OrganizationGuidanceState;\n"]}

package/dist/esm/guidance/guidance-state.shared.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guidance-state.shared.utils.d.ts","sourceRoot":"","sources":["../../../src/guidance/guidance-state.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC7B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAE5C,qBAAa,kBAAkB;IAC7B,OAAO;WAEO,0BAA0B,IAAI,aAAa;WAM3C,yBAAyB,CACrC,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,GAC1D,sBAAsB;WAgBX,6BAA6B,IAAI,gBAAgB;WAUjD,4BAA4B,CACxC,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,GAC1D,yBAAyB;WAgBd,2BAA2B,CAAC,GAAG,GAAE,IAAiB,GAAG,cAAc;WAgBnE,iCAAiC,CAC7C,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,EAC3D,GAAG,GAAE,IAAiB,GACrB,uBAAuB;CAe3B"}
+{"version":3,"file":"guidance-state.shared.utils.d.ts","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC7B,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAE5C,qBAAa,kBAAkB;IAC7B,OAAO;WAEO,0BAA0B,IAAI,aAAa;WAM3C,yBAAyB,CACrC,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,GAC1D,sBAAsB;WAgBX,6BAA6B,IAAI,gBAAgB;WAUjD,4BAA4B,CACxC,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,GAC1D,yBAAyB;WAgBd,2BAA2B,CAAC,GAAG,GAAE,IAAiB,GAAG,cAAc;WAgBnE,iCAAiC,CAC7C,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,EAC3D,GAAG,GAAE,IAAiB,GACrB,uBAAuB;CAe3B"}

package/dist/esm/guidance/guidance-state.shared.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"guidance-state.shared.utils.js","sourceRoot":"","sources":["../../../src/guidance/guidance-state.shared.utils.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC;AAM1C,MAAM,OAAO,kBAAkB;IAC7B,gBAAuB,CAAC;IAEjB,MAAM,CAAC,0BAA0B;QACtC,OAAO;YACL,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,yBAAyB,CACrC,UAA2D;QAE3D,MAAM,YAAY,GAAG,kBAAkB,CAAC,0BAA0B,EAAE,CAAC;QAErE,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;YAC3B,OAAO;gBACL,GAAG,YAAY;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;QACJ,CAAC;QAED,OAAO;YACL,GAAG,YAAY;YACf,cAAc,EAAE,UAAU,CAAC,cAAc;SAC1C,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,6BAA6B;QACzC,OAAO;YACL,kBAAkB,EAAE,EAAE;YACtB,eAAe,EAAE,EAAE;YACnB,WAAW,EAAE,CAAC;YACd,oBAAoB,EAAE,EAAE;YACxB,kBAAkB,EAAE,EAAE;SACvB,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,4BAA4B,CACxC,UAA2D;QAE3D,MAAM,YAAY,GAAG,kBAAkB,CAAC,6BAA6B,EAAE,CAAC;QAExE,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;YAC3B,OAAO;gBACL,GAAG,YAAY;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;QACJ,CAAC;QAED,OAAO;YACL,GAAG,YAAY;YACf,cAAc,EAAE,UAAU,CAAC,cAAc;SAC1C,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,2BAA2B,CAAC,MAAY,IAAI,IAAI,EAAE;QAC9D,OAAO;YACL,YAAY,EAAE,cAAc,CAAC,SAAS;YACtC,cAAc,EAAE,GAAG;YACnB,YAAY,EAAE,CAAC;oBACb,KAAK,EAAE,cAAc,CAAC,SAAS;oBAC/B,SAAS,EAAE,GAAG;oBACd,OAAO,EAAE,aAAa;iBACvB,CAAC;YACF,aAAa,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;YACzC,YAAY,EAAE,GAAG;YACjB,qBAAqB,EAAE,EAAE;YACzB,UAAU,EAAE,EAAE,yBAAyB,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE;SAC9D,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,iCAAiC,CAC7C,UAA2D,EAC3D,MAAY,IAAI,IAAI,EAAE;QAEtB,MAAM,YAAY,GAAG,kBAAkB,CAAC,2BAA2B,CAAC,GAAG,CAAC,CAAC;QAEzE,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;YAC3B,OAAO;gBACL,GAAG,YAAY;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;QACJ,CAAC;QAED,OAAO;YACL,GAAG,YAAY;YACf,cAAc,EAAE,UAAU,CAAC,cAAc;SAC1C,CAAC;IACJ,CAAC;CACF","sourcesContent":["import type {\n  GuidanceState,\n  PersistedGuidanceState,\n} from './guidance-state.shared.schemas';\nimport {\n  LifecycleStage,\n  type LifecycleState,\n  type PersistedLifecycleState,\n} from './lifecycle-state.shared.schemas';\nimport type {\n  PersistedProgressionState,\n  ProgressionState,\n} from './progression-state.shared.schemas';\n\nexport class GuidanceStateUtils {\n  private constructor() {}\n\n  public static createInitialGuidanceState(): GuidanceState {\n    return {\n      flows: {},\n    };\n  }\n\n  public static createScopedGuidanceState(\n    scopeOwner: { userId: string } | { organizationId: string },\n  ): PersistedGuidanceState {\n    const initialState = GuidanceStateUtils.createInitialGuidanceState();\n\n    if ('userId' in scopeOwner) {\n      return {\n        ...initialState,\n        userId: scopeOwner.userId,\n      };\n    }\n\n    return {\n      ...initialState,\n      organizationId: scopeOwner.organizationId,\n    };\n  }\n\n  public static createInitialProgressionState(): ProgressionState {\n    return {\n      milestonesAchieved: {},\n      operationCounts: {},\n      totalPoints: 0,\n      valueMomentsAchieved: {},\n      categoriesProgress: {},\n    };\n  }\n\n  public static createScopedProgressionState(\n    scopeOwner: { userId: string } | { organizationId: string },\n  ): PersistedProgressionState {\n    const initialState = GuidanceStateUtils.createInitialProgressionState();\n\n    if ('userId' in scopeOwner) {\n      return {\n        ...initialState,\n        userId: scopeOwner.userId,\n      };\n    }\n\n    return {\n      ...initialState,\n      organizationId: scopeOwner.organizationId,\n    };\n  }\n\n  public static createInitialLifecycleState(now: Date = new Date()): LifecycleState {\n    return {\n      currentStage: LifecycleStage.SIGNED_UP,\n      stageEnteredAt: now,\n      stageHistory: [{\n        stage: LifecycleStage.SIGNED_UP,\n        enteredAt: now,\n        trigger: 'auto_create',\n      }],\n      stagesVisited: [LifecycleStage.SIGNED_UP],\n      lastActiveAt: now,\n      activationCriteriaMet: {},\n      engagement: { operationsSinceActivation: 0, activeDates: [] },\n    };\n  }\n\n  public static createInitialScopedLifecycleState(\n    scopeOwner: { userId: string } | { organizationId: string },\n    now: Date = new Date(),\n  ): PersistedLifecycleState {\n    const initialState = GuidanceStateUtils.createInitialLifecycleState(now);\n\n    if ('userId' in scopeOwner) {\n      return {\n        ...initialState,\n        userId: scopeOwner.userId,\n      };\n    }\n\n    return {\n      ...initialState,\n      organizationId: scopeOwner.organizationId,\n    };\n  }\n}\n"]}
+{"version":3,"file":"guidance-state.shared.utils.js","sourceRoot":"","sources":["../../../../src/guidance/guidance-state.shared.utils.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,cAAc,GAGf,MAAM,kCAAkC,CAAC;AAM1C,MAAM,OAAO,kBAAkB;IAC7B,gBAAuB,CAAC;IAEjB,MAAM,CAAC,0BAA0B;QACtC,OAAO;YACL,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,yBAAyB,CACrC,UAA2D;QAE3D,MAAM,YAAY,GAAG,kBAAkB,CAAC,0BAA0B,EAAE,CAAC;QAErE,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;YAC3B,OAAO;gBACL,GAAG,YAAY;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;QACJ,CAAC;QAED,OAAO;YACL,GAAG,YAAY;YACf,cAAc,EAAE,UAAU,CAAC,cAAc;SAC1C,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,6BAA6B;QACzC,OAAO;YACL,kBAAkB,EAAE,EAAE;YACtB,eAAe,EAAE,EAAE;YACnB,WAAW,EAAE,CAAC;YACd,oBAAoB,EAAE,EAAE;YACxB,kBAAkB,EAAE,EAAE;SACvB,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,4BAA4B,CACxC,UAA2D;QAE3D,MAAM,YAAY,GAAG,kBAAkB,CAAC,6BAA6B,EAAE,CAAC;QAExE,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;YAC3B,OAAO;gBACL,GAAG,YAAY;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;QACJ,CAAC;QAED,OAAO;YACL,GAAG,YAAY;YACf,cAAc,EAAE,UAAU,CAAC,cAAc;SAC1C,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,2BAA2B,CAAC,MAAY,IAAI,IAAI,EAAE;QAC9D,OAAO;YACL,YAAY,EAAE,cAAc,CAAC,SAAS;YACtC,cAAc,EAAE,GAAG;YACnB,YAAY,EAAE,CAAC;oBACb,KAAK,EAAE,cAAc,CAAC,SAAS;oBAC/B,SAAS,EAAE,GAAG;oBACd,OAAO,EAAE,aAAa;iBACvB,CAAC;YACF,aAAa,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;YACzC,YAAY,EAAE,GAAG;YACjB,qBAAqB,EAAE,EAAE;YACzB,UAAU,EAAE,EAAE,yBAAyB,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE;SAC9D,CAAC;IACJ,CAAC;IAEM,MAAM,CAAC,iCAAiC,CAC7C,UAA2D,EAC3D,MAAY,IAAI,IAAI,EAAE;QAEtB,MAAM,YAAY,GAAG,kBAAkB,CAAC,2BAA2B,CAAC,GAAG,CAAC,CAAC;QAEzE,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;YAC3B,OAAO;gBACL,GAAG,YAAY;gBACf,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;QACJ,CAAC;QAED,OAAO;YACL,GAAG,YAAY;YACf,cAAc,EAAE,UAAU,CAAC,cAAc;SAC1C,CAAC;IACJ,CAAC;CACF","sourcesContent":["import type {\n  GuidanceState,\n  PersistedGuidanceState,\n} from './guidance-state.shared.schemas';\nimport {\n  LifecycleStage,\n  type LifecycleState,\n  type PersistedLifecycleState,\n} from './lifecycle-state.shared.schemas';\nimport type {\n  PersistedProgressionState,\n  ProgressionState,\n} from './progression-state.shared.schemas';\n\nexport class GuidanceStateUtils {\n  private constructor() {}\n\n  public static createInitialGuidanceState(): GuidanceState {\n    return {\n      flows: {},\n    };\n  }\n\n  public static createScopedGuidanceState(\n    scopeOwner: { userId: string } | { organizationId: string },\n  ): PersistedGuidanceState {\n    const initialState = GuidanceStateUtils.createInitialGuidanceState();\n\n    if ('userId' in scopeOwner) {\n      return {\n        ...initialState,\n        userId: scopeOwner.userId,\n      };\n    }\n\n    return {\n      ...initialState,\n      organizationId: scopeOwner.organizationId,\n    };\n  }\n\n  public static createInitialProgressionState(): ProgressionState {\n    return {\n      milestonesAchieved: {},\n      operationCounts: {},\n      totalPoints: 0,\n      valueMomentsAchieved: {},\n      categoriesProgress: {},\n    };\n  }\n\n  public static createScopedProgressionState(\n    scopeOwner: { userId: string } | { organizationId: string },\n  ): PersistedProgressionState {\n    const initialState = GuidanceStateUtils.createInitialProgressionState();\n\n    if ('userId' in scopeOwner) {\n      return {\n        ...initialState,\n        userId: scopeOwner.userId,\n      };\n    }\n\n    return {\n      ...initialState,\n      organizationId: scopeOwner.organizationId,\n    };\n  }\n\n  public static createInitialLifecycleState(now: Date = new Date()): LifecycleState {\n    return {\n      currentStage: LifecycleStage.SIGNED_UP,\n      stageEnteredAt: now,\n      stageHistory: [{\n        stage: LifecycleStage.SIGNED_UP,\n        enteredAt: now,\n        trigger: 'auto_create',\n      }],\n      stagesVisited: [LifecycleStage.SIGNED_UP],\n      lastActiveAt: now,\n      activationCriteriaMet: {},\n      engagement: { operationsSinceActivation: 0, activeDates: [] },\n    };\n  }\n\n  public static createInitialScopedLifecycleState(\n    scopeOwner: { userId: string } | { organizationId: string },\n    now: Date = new Date(),\n  ): PersistedLifecycleState {\n    const initialState = GuidanceStateUtils.createInitialLifecycleState(now);\n\n    if ('userId' in scopeOwner) {\n      return {\n        ...initialState,\n        userId: scopeOwner.userId,\n      };\n    }\n\n    return {\n      ...initialState,\n      organizationId: scopeOwner.organizationId,\n    };\n  }\n}\n"]}