@synap-core/workspace-templates 0.9.2 → 0.9.4

package/src/index.ts

@@ -11,7 +11,7 @@
  *   const template = getWorkspaceTemplate('brand-library');
  *   // template.workspace.name === 'Brand Library'
  *   // template.app.kind === 'native'
- *   // template.layout.defaultApp === 'brandLibrary'
+ *   // template.app.appId === 'brandLibrary'
  *
  * YAML source files live in src/*.yaml — AI-friendly, commentable, mergeable.
  * Run `pnpm build` to regenerate src/templates.ts from YAML.
@@ -22,6 +22,10 @@ export type {
   TemplateMeta,
   TemplateAppRef,
   TemplateAppKind,
+  WorkspaceJsonValue,
+  WorkspacePrimarySurface,
+  WorkspacePrimarySurfaceViewReference,
+  TemplatePrimarySurface,
   TemplateProfile,
   TemplateProperty,
   TemplateView,
@@ -86,8 +90,7 @@ export type {
 } from "./catalog.js";
 
 export {
-  layerTemplateGraph,
-  bundledEdgesOf,
+  layerTemplateGraph, bundledEdgesOf
 } from "./composition-graph.js";
 export type {
   CompositionInstalledEntry,
@@ -138,10 +141,30 @@ export type {
   TemplateConverters,
 } from "./validate.js";
 
+// The pure, DB-free automation-flow node-contract validator. `validateTemplate`
+// runs it over every `automations[].flow` so broken flows (unknown node type,
+// dangling edge, cycle, typo'd channelType, verb-less capability node) fail at
+// author time instead of silently never firing on a live pod. Exported so the
+// pod's persist doors + the (post-publish) backend re-export share this SSOT.
+
+export {
+  validateFlowDefinition,
+  flowValidationErrorMessage,
+  FLOW_NODE_TYPES,
+  FLOW_OUTPUT_TYPES,
+  CHANNEL_MESSAGE_CHANNEL_TYPES,
+} from "./validate-flow.js";
+export type {
+  FlowValidationError,
+  FlowValidationResult,
+  FlowValidationResolvers,
+} from "./validate-flow.js";
+
 export {
   toWorkspaceDefinition,
   toPackageDefinition,
   splitBentoBlocks,
+  normalizeTemplateLayout,
 } from "./define.js";
 export type {
   WorkspaceDefinitionInput,

package/src/marketing.yaml

@@ -92,6 +92,25 @@ profiles:
         label: Notes
         valueType: string
         inputType: textarea
+      # `campaign-type` is the campaign's NATURE/phase, orthogonal to
+      # `campaign-channel` (the delivery medium). scoping/outreach/live have no
+      # channel equivalent, so folding them into `campaign-channel` would lose
+      # them — they get their own def. Kept verbatim across the three campaign
+      # declarations (business-developer / content-os / here) so there is no drift.
+      - slug: campaign-type
+        label: Type
+        valueType: string
+        inputType: select
+        enumValues:
+          [scoping, outreach, live, partnership, event, other]
+        constraints: { defaultValue: outreach }
+      # `campaign-color` backs the per-campaign colour the CRM surfaces render.
+      # Stored as a palette NAME (see apps/crm/lib/campaignColors.ts), not a hex.
+      - slug: campaign-color
+        label: Color
+        valueType: string
+        inputType: select
+        enumValues: [indigo, violet, amber, cyan, pink, teal]
 
   - slug: contact
     displayName: Contact

package/src/templates.ts

@@ -6833,14 +6833,13 @@ const DATA = {
             "valueType": "string",
             "inputType": "select",
             "enumValues": [
-              "manual",
-              "referral",
+              "cold-outreach",
               "linkedin",
-              "email",
+              "twitter",
+              "landing-page",
+              "inbound-call",
+              "referral",
               "event",
-              "inbound",
-              "partner",
-              "import",
               "other"
             ]
           },
@@ -7210,6 +7209,37 @@ const DATA = {
             "label": "Notes",
             "valueType": "string",
             "inputType": "textarea"
+          },
+          {
+            "slug": "campaign-type",
+            "label": "Type",
+            "valueType": "string",
+            "inputType": "select",
+            "enumValues": [
+              "scoping",
+              "outreach",
+              "live",
+              "partnership",
+              "event",
+              "other"
+            ],
+            "constraints": {
+              "defaultValue": "outreach"
+            }
+          },
+          {
+            "slug": "campaign-color",
+            "label": "Color",
+            "valueType": "string",
+            "inputType": "select",
+            "enumValues": [
+              "indigo",
+              "violet",
+              "amber",
+              "cyan",
+              "pink",
+              "teal"
+            ]
           }
         ]
       }
@@ -8909,6 +8939,37 @@ const DATA = {
             "label": "Notes",
             "valueType": "string",
             "inputType": "textarea"
+          },
+          {
+            "slug": "campaign-type",
+            "label": "Type",
+            "valueType": "string",
+            "inputType": "select",
+            "enumValues": [
+              "scoping",
+              "outreach",
+              "live",
+              "partnership",
+              "event",
+              "other"
+            ],
+            "constraints": {
+              "defaultValue": "outreach"
+            }
+          },
+          {
+            "slug": "campaign-color",
+            "label": "Color",
+            "valueType": "string",
+            "inputType": "select",
+            "enumValues": [
+              "indigo",
+              "violet",
+              "amber",
+              "cyan",
+              "pink",
+              "teal"
+            ]
           }
         ]
       },
@@ -10009,6 +10070,12 @@ const DATA = {
       ],
       "isPublic": true
     },
+    "app": {
+      "kind": "url",
+      "appId": "crm",
+      "url": "https://crm.synap.live",
+      "title": "CRM"
+    },
     "dependencies": [
       {
         "slug": "foundation",
@@ -10079,7 +10146,17 @@ const DATA = {
             "slug": "source",
             "label": "Source",
             "valueType": "string",
-            "inputType": "text"
+            "inputType": "select",
+            "enumValues": [
+              "cold-outreach",
+              "linkedin",
+              "twitter",
+              "landing-page",
+              "inbound-call",
+              "referral",
+              "event",
+              "other"
+            ]
           },
           {
             "slug": "icpScore",
@@ -10168,7 +10245,17 @@ const DATA = {
             "slug": "source",
             "label": "Source",
             "valueType": "string",
-            "inputType": "text"
+            "inputType": "select",
+            "enumValues": [
+              "cold-outreach",
+              "linkedin",
+              "twitter",
+              "landing-page",
+              "inbound-call",
+              "referral",
+              "event",
+              "other"
+            ]
           },
           {
             "slug": "icpScore",
@@ -10556,6 +10643,66 @@ const DATA = {
         "type": "linked_to_deal"
       }
     ],
+    "onboarding": {
+      "goal": "Turn the user's real commercial motion into a usable pipeline — the right companies and people, their active opportunities, and an explicit next step for every deal — so CRM becomes the place sales work moves forward.\n",
+      "framing": "THE REVENUE OPERATOR: Act as a pragmatic sales lead setting up a CRM people will actually maintain. Start from the user's existing motion, vocabulary, and active conversations. Resolve before creating so imported or Pod-wide people are reused rather than duplicated. Push for a concrete next step and date; never invent revenue, probability, or contact details.\n",
+      "expertise": {
+        "starters": [
+          "A useful first pipeline is deliberately small. Start with the few stages that change how the team acts — contacted, qualifying, proposal, negotiating, won, and lost — and keep the template's default stages unless the user's real process needs a different view.\n",
+          "Populate the workspace with live work, not a perfect historical archive: propose the three to five opportunities the user is actively trying to move, then add the companies and people needed to understand those deals.\n",
+          "Every active deal needs one observable next step with a date. If the next step is \"follow up\" or \"keep warm\", help turn it into a specific action such as \"send the revised proposal Thursday\" before capturing it.\n"
+        ],
+        "blindSpots": [
+          "A deal without a real person is usually an account-shaped hope. If an opportunity has no stakeholder, surface the gap instead of fabricating a placeholder contact.\n",
+          "Pipelines become fiction when stages describe confidence rather than an event the buyer completed. Ask what evidence moves a deal into its current stage, especially around proposal and negotiation.\n",
+          "More fields do not create better sales hygiene. Prioritize stage, value when known, expected close date, and next step; leave unverifiable fields empty and offer enrichment separately.\n"
+        ],
+        "bar": "A sales lead can open the pipeline and immediately see the few live opportunities, the real company and stakeholder behind each one, its evidence-based stage, and the dated next action — with no duplicate people and no invented commercial data.\n"
+      },
+      "collect": [
+        {
+          "profileSlug": "company",
+          "what": "The real prospect organisations behind current conversations.",
+          "cardinality": "few",
+          "keyFields": [
+            "website",
+            "industry",
+            "companySize",
+            "source",
+            "nextStep"
+          ]
+        },
+        {
+          "profileSlug": "person",
+          "what": "The known stakeholders for those organisations and opportunities.",
+          "cardinality": "few",
+          "keyFields": [
+            "email",
+            "jobTitle",
+            "company",
+            "source",
+            "nextFollowUpDate"
+          ]
+        },
+        {
+          "profileSlug": "deal",
+          "what": "The live opportunities worth actively moving through the pipeline.",
+          "cardinality": "few",
+          "keyFields": [
+            "dealStage",
+            "value",
+            "closeDate",
+            "nextStep"
+          ]
+        }
+      ],
+      "openingQuestions": [
+        "Which three to five opportunities are you actively trying to move right now?",
+        "For the most important one, which company and real stakeholder are involved?",
+        "What has the buyer actually done so far, and what is the next dated action?"
+      ],
+      "doneWhen": "At least one real opportunity is linked to its company or stakeholder and has an evidence-based stage plus a concrete next step; the user can see how to add or import the rest without duplicating existing people.\n"
+    },
     "playbooks": [
       {
         "name": "Enrich Lead/Company",
@@ -22004,6 +22151,37 @@ const DATA = {
             "label": "Notes",
             "valueType": "string",
             "inputType": "textarea"
+          },
+          {
+            "slug": "campaign-type",
+            "label": "Type",
+            "valueType": "string",
+            "inputType": "select",
+            "enumValues": [
+              "scoping",
+              "outreach",
+              "live",
+              "partnership",
+              "event",
+              "other"
+            ],
+            "constraints": {
+              "defaultValue": "outreach"
+            }
+          },
+          {
+            "slug": "campaign-color",
+            "label": "Color",
+            "valueType": "string",
+            "inputType": "select",
+            "enumValues": [
+              "indigo",
+              "violet",
+              "amber",
+              "cyan",
+              "pink",
+              "teal"
+            ]
           }
         ]
       },

package/src/types.ts

@@ -10,24 +10,97 @@
 // App Reference — what opens as first screen when entering this workspace
 // ============================================================================
 
-export type TemplateAppKind = 'native' | 'stored' | 'url';
+export type TemplateAppKind = "native" | "stored" | "url";
 
 export interface TemplateAppRef {
   kind: TemplateAppKind;
   /** For kind='native': the appId registered in the browser manifest */
   appId?: string;
   /** For kind='native': how the platform renders the app */
-  rendererType?: 'native' | 'external' | 'iframe-srcdoc';
+  rendererType?: "native" | "external" | "iframe-srcdoc";
   /** For kind='stored': the cell key registered in the cell registry */
   cellKey?: string;
   /** For kind='stored': default props passed to the cell */
-  props?: Record<string, unknown>;
+  props?: Record<string, WorkspaceJsonValue>;
   /** For kind='url': external URL to open */
   url?: string;
   /** Human label */
   title?: string;
 }
 
+// ============================================================================
+// Workspace primary surface — JSON-safe persisted subset of SurfaceDescriptor
+// ============================================================================
+
+export type WorkspaceJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | WorkspaceJsonValue[]
+  | { [key: string]: WorkspaceJsonValue };
+
+export type WorkspacePrimarySurface =
+  | {
+      kind: "app";
+      appId: string;
+      rendererType: "native";
+      title?: string;
+      props?: Record<string, WorkspaceJsonValue>;
+    }
+  | {
+      kind: "app";
+      appId: string;
+      rendererType: "external";
+      url: string;
+      title?: string;
+      props?: Record<string, WorkspaceJsonValue>;
+    }
+  | {
+      kind: "cell";
+      cellKey: string;
+      title?: string;
+      props?: Record<string, WorkspaceJsonValue>;
+    }
+  | {
+      /**
+       * Ordinary website. Unlike an external `app`, this has no trusted app
+       * identity and is always opened through the Browser's unprivileged URL
+       * surface.
+       */
+      kind: "url";
+      url: string;
+      title?: string;
+    }
+  | {
+      kind: "view";
+      viewId: string;
+      title?: string;
+    };
+
+/**
+ * Authoring-time view reference. View IDs do not exist until provisioning, so
+ * templates and packages address a view by its stable authored name and/or
+ * slug. The pod resolves this to `WorkspacePrimarySurface` before persistence.
+ */
+export type WorkspacePrimarySurfaceViewReference =
+  | {
+      kind: "view";
+      viewName: string;
+      viewSlug?: string;
+      title?: string;
+    }
+  | {
+      kind: "view";
+      viewName?: string;
+      viewSlug: string;
+      title?: string;
+    };
+
+export type TemplatePrimarySurface =
+  | WorkspacePrimarySurface
+  | WorkspacePrimarySurfaceViewReference;
+
 // ============================================================================
 // Property / Profile / View (mirrors WorkspaceProposal from onboarding)
 // ============================================================================
@@ -53,8 +126,7 @@ export interface TemplateProfile {
    * Visibility of the profile DEFINITION — who can USE this vocabulary.
    * `system` = pod-wide; `shared` = ONE row reachable from other workspaces via
    * a `profile_workspace_access` grant; omit or `workspace` = this workspace
-   * only. Orthogonal to `entityScope` below — do not conflate the two axes.
-   */
+   * only. Orthogonal to `entityScope` below — do not conflate the two axes. */
   scope?: string;
   /**
    * Placement of the profile's ENTITY ROWS — where the data LANDS.
@@ -72,7 +144,7 @@ export interface TemplateProfile {
    * `entity_scope` of an existing profile (a divergence is reported as an
    * advisory `scopeConflict` and the live row is left alone).
    */
-  entityScope?: 'pod' | 'workspace';
+  entityScope?: "pod" | "workspace";
   /** Semantic slug for system profiles. */
   semanticSlug?: string;
   /** Kind vs role profile. Omit for default ('kind'). */
@@ -139,22 +211,22 @@ export interface TemplateDisplayTemplate {
 // ============================================================================
 
 export interface TemplateSidebarSurface {
-  kind: 'cell' | 'view' | 'entity' | 'document' | 'channel' | 'app' | 'url';
+  kind: "cell" | "view" | "entity" | "document" | "channel" | "app" | "url";
   cellKey?: string;
   viewId?: string;
   viewName?: string;
   appId?: string;
   url?: string;
-  rendererType?: 'native' | 'external' | 'iframe-srcdoc';
-  placement?: 'main' | 'side' | 'floating' | 'modal' | 'popover' | 'embed';
-  displayMode?: 'compact' | 'medium' | 'full';
+  rendererType?: "native" | "external" | "iframe-srcdoc";
+  placement?: "main" | "side" | "floating" | "modal" | "popover" | "embed";
+  displayMode?: "compact" | "medium" | "full";
   props?: Record<string, unknown>;
   title?: string;
   meta?: Record<string, unknown>;
 }
 
 export interface TemplateSidebarItem {
-  kind: 'app' | 'view' | 'profile' | 'external' | 'cell';
+  kind: "app" | "view" | "profile" | "external" | "cell";
   appId?: string;
   viewName?: string;
   viewId?: string;
@@ -173,7 +245,14 @@ export interface TemplateSidebarItem {
 export interface TemplateLayoutConfig {
   pinnedApps?: string[];
   defaultView?: string;
-  /** The first-screen app — auto-opened on workspace switch */
+  /**
+   * Canonical first screen for this workspace.
+   *
+   * `undefined` means the template has no opinion during reconciliation,
+   * `null` explicitly returns the workspace to its home surface, and a
+   * descriptor replaces the current primary surface. */
+  primarySurface?: TemplatePrimarySurface | null;
+  /** Compatibility input only. New templates should use `app:` or `primarySurface`. */
   defaultApp?: string | null;
   theme?: string;
   sidebarItems?: TemplateSidebarItem[];
@@ -184,7 +263,7 @@ export interface TemplateLayoutConfig {
 // ============================================================================
 
 export interface TemplateBentoBlock {
-  kind: 'view' | 'widget';
+  kind: "view" | "widget";
   viewName?: string;
   widgetType?: string;
   pos: { x: number; y: number; w: number; h: number };
@@ -203,7 +282,7 @@ export interface TemplateProfileEntityBentoTemplates {
 // ============================================================================
 
 /** Mirrors `WorkspaceSourceRole` in synap-backend `schema/workspaces.ts`. */
-export type TemplateSourceRole = 'provider' | 'consumer' | 'provider-consumer';
+export type TemplateSourceRole = "provider" | "consumer" | "provider-consumer";
 
 /** Mirrors `WorkspaceDefaultSource` in synap-backend `schema/workspaces.ts`. */
 export interface TemplateDefaultSource {
@@ -233,7 +312,7 @@ export interface TemplateOnboardingCollectTarget {
   /** Human description of what to capture for this target. */
   what: string;
   /** Roughly how many to expect — guides interview depth. */
-  cardinality?: 'one' | 'few' | 'several';
+  cardinality?: "one" | "few" | "several";
   /** Key fields the agent should make sure to fill. */
   keyFields?: string[];
 }
@@ -288,7 +367,7 @@ export interface TemplateOnboarding {
 
 export interface TemplatePlaybookParam {
   name: string;
-  type: 'text' | 'number' | 'entity' | 'choice' | 'boolean';
+  type: "text" | "number" | "entity" | "choice" | "boolean";
   label?: string;
   required?: boolean;
   defaultValue?: unknown;
@@ -299,12 +378,12 @@ export interface TemplatePlaybook {
   description?: string;
   goalTemplate: string;
   params?: TemplatePlaybookParam[];
-  executor?: 'is-agent' | 'external-agent' | 'hybrid';
-  inputStrategy?: 'none' | 'static' | 'rotating' | 'query';
+  executor?: "is-agent" | "external-agent" | "hybrid";
+  inputStrategy?: "none" | "static" | "rotating" | "query";
   channelSpec?: {
-    type: 'GROUP' | 'AGENT_COLLAB' | 'THREAD';
+    type: "GROUP" | "AGENT_COLLAB" | "THREAD";
     members?: string[];
-    aiReactionMode?: 'on_mention' | 'always' | 'never';
+    aiReactionMode?: "on_mention" | "always" | "never";
   };
   /**
    * A cron schedule that maintains ONE backing cron automation (a single
@@ -330,7 +409,7 @@ export interface TemplatePlaybook {
    * captured entity of this kind can auto-launch the playbook as a session.
    */
   subjectProfile?: { profileSlug: string; filter?: Record<string, unknown> };
-  status?: 'draft' | 'active' | 'paused';
+  status?: "draft" | "active" | "paused";
 }
 
 // ============================================================================
@@ -360,10 +439,10 @@ export interface TemplateAutomation {
   key?: string;
   name: string;
   description?: string;
-  triggerType: 'event' | 'cron' | 'webhook' | 'manual';
+  triggerType: "event" | "cron" | "webhook" | "manual";
   triggerConfig?: Record<string, unknown>;
   flow: { nodes: unknown[]; edges: unknown[]; precondition?: string };
-  status?: 'draft' | 'active' | 'paused';
+  status?: "draft" | "active" | "paused";
 }
 
 // ============================================================================
@@ -395,9 +474,9 @@ export interface TemplateActionPlacement {
   /** Entity kind whose detail surface this action appears on. */
   profileSlug: string;
   /** Where the action renders. Only "entity-detail" is consumed today. */
-  surface: 'entity-detail' | string;
+  surface: "entity-detail" | string;
   /** What the action does when clicked. */
-  kind: 'capability' | 'playbook' | 'automation';
+  kind: "capability" | "playbook" | "automation";
   /**
    * Reference to the thing to run: a capability verb key, or a playbook /
    * automation NAME (resolved to a row id at apply time).
@@ -440,7 +519,7 @@ export interface TemplateIntegration {
   /** Override default params with {{var}} interpolation. */
   params?: Record<string, string>;
   /** "apply" (create+update) or "install" (create only). */
-  mode?: 'apply' | 'install';
+  mode?: "apply" | "install";
 }
 
 // ============================================================================
@@ -514,10 +593,10 @@ export interface TemplateExtendsRef {
  *   3. Once no payload carries `'automation'`, drop it from the wire enums and this tuple.
  */
 export const PACKAGE_DEPENDENCY_KINDS = [
-  'workspace',
-  'capability',
+  "workspace",
+  "capability",
   /** @deprecated Retired by CP 0049 in favour of `workflow`. See note above. */
-  'automation',
+  "automation",
 ] as const;
 
 /** What a `TemplateDependency` points at. Derived — never re-declare the list. */
@@ -541,7 +620,7 @@ export interface TemplateDependency {
    * - `'require'` (default): the dependency must be present on the pod as its
    *   own artifact, but this template does not merge into it.
    */
-  relation?: 'compose' | 'require';
+  relation?: "compose" | "require";
   /**
    * Short human reason shown in the install-time "this also installs…" prompt.
    */
@@ -585,7 +664,7 @@ export interface WorkspaceYaml {
      * Workspace classifier — consumed by createFromDefinition (settings.workspaceType,
      * creator-role + agent-workspace behavior). Mirrors the backend union.
      */
-    workspaceType?: 'personal' | 'agent' | 'project' | 'operational';
+    workspaceType?: "personal" | "agent" | "project" | "operational";
     visibility?: string;
     /** Capabilities this workspace provides (e.g. "brand.library", "content.pipeline") */
     capabilities?: string[];
@@ -682,7 +761,7 @@ export interface WorkspaceYaml {
 
 export interface ResolvedWorkspaceTemplate {
   meta: TemplateMeta;
-  definition: WorkspaceYaml['workspace'] & {
+  definition: WorkspaceYaml["workspace"] & {
     profiles: TemplateProfile[];
     views: TemplateView[];
     entityLinks: TemplateEntityLink[];