@elevasis/sdk 1.8.3 → 1.9.0

package/reference/examples/organization-model.ts

@@ -0,0 +1,689 @@
+// Pure reference file -- NOT imported anywhere.
+// Copy individual examples into organization-model.ts as needed.
+// Each const is a valid `defineOrganizationModel()` override shape. All examples
+// are written against the current @elevasis/core schema (reality-domain expansion)
+// and will type-check once @elevasis/core is updated to the version that includes
+// the new domains (identity, customers, offerings, roles, goals, statuses, operations).
+//
+// Examples are organized by domain. Each section shows the minimal shape a developer
+// would write when answering /configure prompts for that domain.
+import {
+  SALES_PIPELINE_SURFACE_ID,
+  defineOrganizationModel,
+  type OrganizationModelResourceMapping
+} from '@elevasis/core/organization-model'
+
+const SALES_FEATURE_ID = 'crm' as const
+const PROSPECTING_FEATURE_ID = 'lead-gen' as const
+
+// ---------------------------------------------------------------------------
+// 1. Branding override -- shortest useful case
+// ---------------------------------------------------------------------------
+export const brandingOverrideExample = defineOrganizationModel({
+  branding: {
+    organizationName: 'Acme Corp',
+    productName: 'Acme Command Center',
+    shortName: 'Acme'
+  }
+})
+
+// ---------------------------------------------------------------------------
+// 2. CRM customization -- replace default pipeline stages
+// ---------------------------------------------------------------------------
+export const crmCustomizationExample = defineOrganizationModel({
+  sales: {
+    entityId: 'crm.deal',
+    defaultPipelineId: 'sales',
+    pipelines: [
+      {
+        id: 'sales',
+        label: 'Sales Pipeline',
+        entityId: 'crm.deal',
+        stages: [
+          {
+            id: 'qualified',
+            label: 'Qualified',
+            color: 'blue',
+            order: 1,
+            semanticClass: 'open',
+            surfaceIds: [SALES_PIPELINE_SURFACE_ID],
+            resourceIds: []
+          },
+          {
+            id: 'negotiating',
+            label: 'Negotiating',
+            color: 'yellow',
+            order: 2,
+            semanticClass: 'active',
+            surfaceIds: [SALES_PIPELINE_SURFACE_ID],
+            resourceIds: []
+          },
+          {
+            id: 'won',
+            label: 'Won',
+            color: 'green',
+            order: 3,
+            semanticClass: 'closed_won',
+            surfaceIds: [SALES_PIPELINE_SURFACE_ID],
+            resourceIds: []
+          }
+        ]
+      }
+    ]
+  }
+})
+
+// ---------------------------------------------------------------------------
+// 3. Lead-gen customization -- replace company lifecycle stages
+// ---------------------------------------------------------------------------
+export const leadGenCustomizationExample = defineOrganizationModel({
+  prospecting: {
+    listEntityId: 'leadgen.list',
+    companyEntityId: 'leadgen.company',
+    contactEntityId: 'leadgen.contact',
+    companyStages: [
+      { id: 'scraped', label: 'Scraped', order: 1 },
+      { id: 'enriched', label: 'Enriched', order: 2 },
+      { id: 'approved', label: 'Approved', order: 3 }
+    ],
+    contactStages: [
+      { id: 'found', label: 'Found', order: 1 },
+      { id: 'verified', label: 'Verified', order: 2 },
+      { id: 'ready', label: 'Ready', order: 3 }
+    ]
+  }
+})
+
+// ---------------------------------------------------------------------------
+// 4. Resource mappings -- associate platform resources with surfaces
+// ---------------------------------------------------------------------------
+const resourceMappingEntries: OrganizationModelResourceMapping[] = [
+  {
+    id: 'lead-gen-enrichment',
+    label: 'Lead Enrichment',
+    resourceId: 'my-org/lead-enrichment-workflow',
+    resourceType: 'workflow',
+    featureIds: [PROSPECTING_FEATURE_ID],
+    entityIds: ['leadgen.company'],
+    surfaceIds: ['lead-gen.lists'],
+    capabilityIds: []
+  },
+  {
+    id: 'crm-follow-up',
+    label: 'CRM Follow-Up Agent',
+    resourceId: 'my-org/crm-follow-up-agent',
+    resourceType: 'agent',
+    featureIds: [SALES_FEATURE_ID],
+    entityIds: ['crm.deal'],
+    surfaceIds: [SALES_PIPELINE_SURFACE_ID],
+    capabilityIds: ['crm.pipeline.manage']
+  }
+]
+
+export const resourceMappingExample = defineOrganizationModel({
+  resourceMappings: resourceMappingEntries
+})
+
+// ---------------------------------------------------------------------------
+// 5. Custom feature -- add a project-specific feature
+//
+// NOTE: the `features` field REPLACES the default array on merge (arrays are
+// not deep-merged). To keep the built-in features (CRM, Lead Gen, etc.) while
+// adding a custom one, spread them explicitly:
+//
+//   features: [...DEFAULT_ORGANIZATION_MODEL.features, myCustomFeature]
+//
+// The example below shows a standalone override with only the custom feature
+// to illustrate the shape. Import DEFAULT_ORGANIZATION_MODEL from
+// @elevasis/core/organization-model if you need the full set.
+// ---------------------------------------------------------------------------
+export const customFeatureExample = defineOrganizationModel({
+  features: [
+    {
+      id: 'my-custom',
+      label: 'My Custom Feature',
+      description: 'A project-specific feature outside the standard suite',
+      enabled: true,
+      color: 'teal',
+      entityIds: [],
+      surfaceIds: ['my-custom.dashboard'],
+      resourceIds: [],
+      capabilityIds: []
+    }
+  ]
+})
+
+// ---------------------------------------------------------------------------
+// 6. Identity domain -- legal entity, mission/vision, industry/geo anchors
+//
+// Decision #3: identity is distinct from branding. `branding` = display
+// identity (logos, product names). `identity` = legal identity (entity,
+// jurisdiction, mission/vision). Conflating risks branding edits touching
+// compliance fields.
+//
+// Fields: mission, vision, legalName, entityType, jurisdiction,
+//         industryCategory, geographicFocus, timeZone, businessHours.
+//
+// businessHours uses HH:MM 24-hour format per day of week.
+// timeZone is an IANA timezone identifier (e.g. "America/Los_Angeles").
+// ---------------------------------------------------------------------------
+export const identityExample = {
+  identity: {
+    mission: 'Automate the operational work that slows SMBs down so they can focus on what matters.',
+    vision: 'A world where every small business has the same operational leverage as a Fortune 500.',
+    legalName: 'Acme Automation, LLC',
+    entityType: 'LLC',
+    jurisdiction: 'United States \u2013 Delaware',
+    industryCategory: 'Software / SaaS',
+    geographicFocus: 'North America',
+    timeZone: 'America/New_York',
+    clientBrief:
+      'Acme Automation serves SMBs in the US that are growing past founder-led operations. Primary buyers are ops leads and founders at 10\u201350 person companies. Warm via referral, short sales cycle (~2 weeks), monthly SaaS. The team has no dedicated engineering staff -- we own the full stack from automation design through deployment.',
+    businessHours: {
+      monday: { open: '09:00', close: '18:00' },
+      tuesday: { open: '09:00', close: '18:00' },
+      wednesday: { open: '09:00', close: '18:00' },
+      thursday: { open: '09:00', close: '18:00' },
+      friday: { open: '09:00', close: '17:00' }
+    }
+  }
+}
+
+// Minimal identity -- only mission + timezone filled in; all other fields empty
+export const identityMinimalExample = {
+  identity: {
+    mission: 'Deliver premium digital marketing results for growth-stage brands.',
+    timeZone: 'America/Chicago'
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 7. Customers domain -- buyer archetypes with JTBD, pains, gains, firmographics
+//
+// Decision #4 (BMC/VPC shape): each segment declares jobs-to-be-done, pains,
+// gains, firmographics (industry, companySize, region), and a value proposition.
+// Agents use segments for outreach targeting, scoring, and proposal personalization.
+//
+// targetSegmentIds on offerings cross-reference segment ids declared here.
+// Bidirectional validation is enforced via OrganizationModelSchema.superRefine().
+// ---------------------------------------------------------------------------
+export const customersExample = {
+  customers: {
+    segments: [
+      {
+        id: 'segment-smb-agencies',
+        name: 'SMB Marketing Agencies',
+        description:
+          'Growth-oriented digital agencies with 5\u201350 staff who run client campaigns and need to eliminate manual operations.',
+        jobsToBeDone:
+          'Run more client campaigns without growing headcount. Deliver consistent results faster with fewer errors and no dropped balls.',
+        pains: [
+          'Manual data entry across disconnected tools (Instantly, HubSpot, Notion)',
+          'Slow lead qualification that takes hours per batch',
+          'Inconsistent follow-up causing deal leakage at the qualification stage'
+        ],
+        gains: [
+          'Automated pipelines that run overnight without oversight',
+          'Structured HITL handoffs that keep humans in the loop for high-stakes decisions',
+          'A unified view of every active client project and deal in one surface'
+        ],
+        firmographics: {
+          industry: 'Marketing / Digital Agency',
+          companySize: '5\u201350',
+          region: 'North America'
+        },
+        valueProp:
+          'Elevasis automates the repetitive parts of agency operations so the team focuses on strategy and client relationships \u2014 not spreadsheets.'
+      },
+      {
+        id: 'segment-ecom-operators',
+        name: 'E-Commerce Operators',
+        description:
+          'Bootstrapped or VC-backed e-commerce brands running on Shopify or WooCommerce with 10\u2013100 SKUs.',
+        jobsToBeDone: 'Scale order operations and supplier communication without hiring a large ops team.',
+        pains: ['Supplier follow-up is manual and inconsistent', 'Returns processing is slow and error-prone'],
+        gains: ['Automated supplier status updates', 'Faster returns processing with fewer manual steps'],
+        firmographics: {
+          industry: 'E-Commerce / Retail',
+          companySize: '1\u201320',
+          region: 'Global'
+        },
+        valueProp:
+          'Elevasis turns supplier and returns operations into structured workflows that run without daily oversight.'
+      }
+    ]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 8. Offerings domain -- products/services with pricing model and segment targeting
+//
+// Decision #5 (BMC Value Propositions shape): pricingModel enum values are
+// 'one-time' | 'subscription' | 'usage-based' | 'custom'.
+// targetSegmentIds must resolve to declared customers.segments[].id.
+// deliveryFeatureId (optional) must resolve to a declared features[].id.
+//
+// Arrays are NOT deep-merged: if you declare offerings here, include ALL products
+// you want. Do not rely on default products being preserved.
+// ---------------------------------------------------------------------------
+export const offeringsExample = {
+  offerings: {
+    products: [
+      {
+        id: 'product-starter',
+        name: 'Starter Automation Pack',
+        description: 'Pre-built workflow bundle for lead enrichment, CRM follow-up, and project delivery automation.',
+        pricingModel: 'subscription' as const,
+        price: 299,
+        currency: 'USD',
+        targetSegmentIds: ['segment-smb-agencies']
+      },
+      {
+        id: 'product-growth',
+        name: 'Growth Plan',
+        description:
+          'Full platform access including custom workflow builds, unlimited executions, and dedicated onboarding.',
+        pricingModel: 'subscription' as const,
+        price: 999,
+        currency: 'USD',
+        targetSegmentIds: ['segment-smb-agencies', 'segment-ecom-operators']
+      },
+      {
+        id: 'product-custom-build',
+        name: 'Custom Build',
+        description:
+          'Bespoke AI workflow design and deployment for organizations with unique operational requirements.',
+        pricingModel: 'custom' as const,
+        price: 0,
+        currency: 'USD',
+        targetSegmentIds: ['segment-smb-agencies']
+      }
+    ]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 9. Roles domain -- accountability chart with plain-language field names
+//
+// Decision #6 (EOS-inspired shape, plain language):
+// Schema fields: id, title, responsibilities[], reportsToId?, heldBy?
+// No EOS jargon: "title" not "seatTitle", "responsibilities" not "accountabilities".
+// reportsToId cross-references another roles[].id; cycle detection is not enforced.
+// heldBy is a free-form string (name or email) -- not validated against any user registry.
+// Absence of reportsToId indicates a top-level role.
+//
+// Agents use roles for HITL routing, escalation, and approval-rights reasoning.
+// "/configure roles" prompts the user to fill in this domain.
+// ---------------------------------------------------------------------------
+export const rolesExample = {
+  roles: {
+    roles: [
+      {
+        id: 'role-ceo',
+        title: 'CEO',
+        responsibilities: [
+          'Set company direction and approve strategic initiatives',
+          'Own enterprise-tier client relationships',
+          'Final approver for all platform deployments and budget over $5K'
+        ],
+        heldBy: 'Alex Johnson'
+      },
+      {
+        id: 'role-head-of-ops',
+        title: 'Head of Operations',
+        responsibilities: [
+          'Manage day-to-day workflow deployments and execution health',
+          'Review and approve items in the HITL queue',
+          'Escalate platform failures to CEO within 2 hours'
+        ],
+        reportsToId: 'role-ceo',
+        heldBy: 'Jordan Lee'
+      },
+      {
+        id: 'role-sales-lead',
+        title: 'Sales Lead',
+        responsibilities: [
+          'Qualify inbound leads and manage the CRM pipeline',
+          'Send proposals and follow up with prospects',
+          'Coordinate with ops on client onboarding timelines'
+        ],
+        reportsToId: 'role-ceo',
+        heldBy: 'sam@acme.io'
+      }
+    ]
+  }
+}
+
+// Minimal roles -- solo founder, no reports-to
+export const rolesSoloFounderExample = {
+  roles: {
+    roles: [
+      {
+        id: 'role-founder',
+        title: 'Founder',
+        responsibilities: ['Own all decisions', 'Review all HITL queue items', 'Approve all client deliverables'],
+        heldBy: 'founder@mycompany.io'
+      }
+    ]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 10. Goals domain -- quarterly objectives with plain-language measurable outcomes
+//
+// Decision #7 (OKR-shaped, plain-language rendering):
+// Schema fields: objectives[].{ id, description, periodStart, periodEnd, keyResults[] }
+// keyResults[].{ id, description, targetMetric, currentValue, targetValue? }
+// periodStart / periodEnd are ISO 8601 date strings (YYYY-MM-DD).
+// periodEnd must be strictly after periodStart (enforced by superRefine).
+//
+// IMPORTANT naming convention: the schema uses "objectives" and "keyResults"
+// internally for OKR-tooling compatibility. All user-facing labels and
+// /configure prompts say "goals" and "measurable outcomes" -- never "OKR",
+// "objective", or "key result".
+// ---------------------------------------------------------------------------
+export const goalsExample = {
+  goals: {
+    objectives: [
+      {
+        id: 'goal-grow-arr-q2-2026',
+        description: 'Grow monthly recurring revenue to hit our first ARR milestone by end of Q2 2026.',
+        periodStart: '2026-04-01',
+        periodEnd: '2026-06-30',
+        keyResults: [
+          {
+            id: 'kr-mrr-10k',
+            description: 'Reach $10K MRR',
+            targetMetric: 'Monthly recurring revenue (USD)',
+            currentValue: 2800,
+            targetValue: 10000
+          },
+          {
+            id: 'kr-customers-15',
+            description: 'Acquire 15 paying customers',
+            targetMetric: 'Paying customer count',
+            currentValue: 4,
+            targetValue: 15
+          }
+        ]
+      },
+      {
+        id: 'goal-launch-growth-tier-q2-2026',
+        description: 'Launch Growth Plan tier and land 3 customers on it by end of Q2 2026.',
+        periodStart: '2026-05-01',
+        periodEnd: '2026-06-30',
+        keyResults: [
+          {
+            id: 'kr-growth-launched',
+            description: 'Growth Plan live and purchasable',
+            targetMetric: 'Launch milestone (binary)',
+            currentValue: 0,
+            targetValue: 1
+          },
+          {
+            id: 'kr-growth-customers',
+            description: '3 customers on Growth tier',
+            targetMetric: 'Growth-tier customer count',
+            currentValue: 0,
+            targetValue: 3
+          }
+        ]
+      }
+    ]
+  }
+}
+
+// Directional goal -- no hard targetValue
+export const goalsDirectionalExample = {
+  goals: {
+    objectives: [
+      {
+        id: 'goal-reduce-churn-q3-2026',
+        description: 'Reduce monthly churn through better onboarding and proactive success check-ins.',
+        periodStart: '2026-07-01',
+        periodEnd: '2026-09-30',
+        keyResults: [
+          {
+            id: 'kr-onboarding-nps',
+            description: 'Improve onboarding satisfaction',
+            targetMetric: 'Onboarding NPS score',
+            currentValue: 32
+            // targetValue omitted -- directional goal, no hard number yet
+          }
+        ]
+      }
+    ]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 11. ResourceMappings with techStack extension
+//
+// Decision #4 (org-reality): techStack EXTENDS the resourceMappings subsection.
+// `techStack` is an optional field on each ResourceMapping entry. Fields:
+//   platform       -- external SaaS name (e.g. "HubSpot", "Stripe", "Notion")
+//   purpose        -- free-form description of what the integration does
+//   credentialStatus -- 'configured' | 'pending' | 'expired' | 'missing'
+//   isSystemOfRecord -- boolean; true if this is the primary SoR for its domain
+//
+// ResourceMapping entries with no `techStack` parse cleanly (backward-compat).
+// ---------------------------------------------------------------------------
+export const resourceMappingsWithTechStackExample = {
+  resourceMappings: [
+    {
+      id: 'integration-attio',
+      label: 'Attio CRM',
+      resourceId: 'my-org/attio-sync',
+      resourceType: 'integration' as const,
+      featureIds: [],
+      entityIds: [],
+      surfaceIds: [],
+      capabilityIds: [],
+      techStack: {
+        platform: 'Attio',
+        purpose: 'System of record for contacts and deals; synced from the CRM pipeline on stage change',
+        credentialStatus: 'configured' as const,
+        isSystemOfRecord: true
+      }
+    },
+    {
+      id: 'integration-stripe',
+      label: 'Stripe',
+      resourceId: 'my-org/stripe-billing',
+      resourceType: 'integration' as const,
+      featureIds: [],
+      entityIds: [],
+      surfaceIds: [],
+      capabilityIds: [],
+      techStack: {
+        platform: 'Stripe',
+        purpose: 'Subscription billing and invoice generation for all products',
+        credentialStatus: 'configured' as const,
+        isSystemOfRecord: true
+      }
+    },
+    {
+      id: 'integration-instantly',
+      label: 'Instantly.ai',
+      resourceId: 'my-org/instantly-campaigns',
+      resourceType: 'integration' as const,
+      featureIds: [],
+      entityIds: [],
+      surfaceIds: [],
+      capabilityIds: [],
+      techStack: {
+        platform: 'Instantly.ai',
+        purpose: 'Cold email outreach and campaign management for lead-gen sequences',
+        credentialStatus: 'pending' as const,
+        isSystemOfRecord: false
+      }
+    },
+    {
+      id: 'workflow-lead-enrichment',
+      label: 'Lead Enrichment Workflow',
+      resourceId: 'my-org/lead-enrichment-workflow',
+      resourceType: 'workflow' as const,
+      featureIds: [PROSPECTING_FEATURE_ID],
+      entityIds: ['leadgen.company'],
+      surfaceIds: ['lead-gen.lists'],
+      capabilityIds: []
+      // No techStack -- this is a platform workflow, not an external SaaS
+    }
+  ]
+}
+
+// ---------------------------------------------------------------------------
+// 12. Statuses domain -- per-org label customization of the platform status registry
+//
+// Decision #9 (vibe): statuses shape is { id, label, semanticClass, category? }.
+// semanticClass enum: 'delivery.task' | 'delivery.project' | 'delivery.milestone'
+//                   | 'queue' | 'execution' | 'schedule' | 'schedule.run' | 'request'
+//
+// The `entries` array REPLACES the default status registry (arrays are not deep-merged).
+// To keep all platform defaults and only relabel a subset, include the full registry.
+// See DEFAULT_ORGANIZATION_MODEL_STATUSES in @elevasis/core/organization-model.
+//
+// Pattern A -- minimal, override only a few labels (spread defaults + your changes):
+// ---------------------------------------------------------------------------
+export const statusesMinimalOverrideExample = {
+  // This shape shows only the entries you'd customise; in practice you must include
+  // the full DEFAULT_ORGANIZATION_MODEL_STATUSES.entries spread for all other statuses.
+  statuses: {
+    entries: [
+      // Relabeled to match agency vocabulary
+      { id: 'delivery.task.planned', label: 'Queued', semanticClass: 'delivery.task' as const, category: 'delivery' },
+      {
+        id: 'delivery.task.in_progress',
+        label: 'In Progress',
+        semanticClass: 'delivery.task' as const,
+        category: 'delivery'
+      },
+      {
+        id: 'delivery.task.revision_requested',
+        label: 'Needs Rework',
+        semanticClass: 'delivery.task' as const,
+        category: 'delivery'
+      },
+      {
+        id: 'delivery.task.completed',
+        label: 'Done',
+        semanticClass: 'delivery.task' as const,
+        category: 'delivery'
+      },
+      // Queue relabeled with client-facing language
+      { id: 'queue.pending', label: 'Awaiting Review', semanticClass: 'queue' as const, category: 'queue' },
+      { id: 'queue.completed', label: 'Resolved', semanticClass: 'queue' as const, category: 'queue' }
+    ]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 13. Operations domain -- runtime entity catalog
+//
+// Decision #10 (vibe): operations catalogs HITL queue, sessions, executions,
+// notifications, schedules as first-class model citizens.
+// semanticClass enum: 'queue' | 'executions' | 'sessions' | 'notifications' | 'schedules'
+// supportedStatusSemanticClass links back to the statuses domain for vibe rendering.
+//
+// Each entry represents one stateful runtime entity the org works with.
+// Agents use this to answer Query intents ("what's pending?", "what's running?")
+// without hardcoding service lookups. The `featureId` field routes the entity
+// to the correct feature surface.
+// ---------------------------------------------------------------------------
+export const operationsExample = {
+  operations: {
+    entries: [
+      {
+        id: 'operations.queue',
+        label: 'Review Queue',
+        semanticClass: 'queue' as const,
+        featureId: 'operations',
+        supportedStatusSemanticClass: ['queue']
+      },
+      {
+        id: 'operations.executions',
+        label: 'Workflow Runs',
+        semanticClass: 'executions' as const,
+        featureId: 'operations',
+        supportedStatusSemanticClass: ['execution']
+      },
+      {
+        id: 'operations.sessions',
+        label: 'Agent Sessions',
+        semanticClass: 'sessions' as const,
+        featureId: 'operations'
+      },
+      {
+        id: 'operations.notifications',
+        label: 'Platform Alerts',
+        semanticClass: 'notifications' as const,
+        featureId: 'monitoring'
+      },
+      {
+        id: 'operations.schedules',
+        label: 'Scheduled Tasks',
+        semanticClass: 'schedules' as const,
+        featureId: 'operations',
+        supportedStatusSemanticClass: ['schedule', 'schedule.run']
+      }
+    ]
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 14. Open placement extension -- navigation group with a custom placement ID
+//
+// Decision #12 (vibe): `surfaceType` and `resourceType` are closed enums
+// (UI/runtime invariants). `placement` is open via extension pattern.
+//
+// Core defines three canonical placement values: 'primary', 'secondary', 'bottom'.
+// NavigationGroupSchema uses z.string() for `placement`, so any string is valid
+// at the schema level -- no changes to @elevasis/core required.
+//
+// To introduce a new placement ID:
+//   1. Add a navigation group with the new placement string (shown below).
+//   2. Add matching rendering logic in the UI feature shell.
+//   3. Document the new placement in this file so the vibe agent can narrate it.
+//
+// The UI feature shell renders groups in document order within each placement bucket.
+// A custom placement that the UI doesn't recognize will be silently omitted from
+// the sidebar unless matching render logic is added.
+// ---------------------------------------------------------------------------
+export const openPlacementExample = {
+  navigation: {
+    // Extend existing groups by spreading DEFAULT_ORGANIZATION_MODEL.navigation.groups
+    // and appending the custom group. Example (not runnable here since it needs the import):
+    //
+    //   groups: [
+    //     ...DEFAULT_ORGANIZATION_MODEL.navigation.groups,
+    //     {
+    //       id: 'spotlight-pinned',
+    //       label: 'Pinned',
+    //       placement: 'spotlight',      // <-- custom placement, open string
+    //       surfaceIds: ['crm.pipeline']
+    //     }
+    //   ]
+    //
+    // Standalone shape for illustration (single group, no spread):
+    groups: [
+      {
+        id: 'spotlight-pinned',
+        label: 'Pinned',
+        placement: 'spotlight', // custom placement ID -- valid per schema (z.string())
+        surfaceIds: ['crm.pipeline']
+      },
+      {
+        id: 'contextual-tools',
+        label: 'Tools',
+        placement: 'contextual', // another custom placement
+        surfaceIds: ['operations.command-queue', 'operations.task-scheduler']
+      }
+    ]
+  }
+}
+
+// NOTE on the open-placement example: because this overrides `groups` without
+// spreading DEFAULT_ORGANIZATION_MODEL.navigation.groups, navigation groups from
+// the default model (primary-workspace, primary-operations, etc.) would be lost
+// at runtime. In practice, always spread the defaults unless you are intentionally
+// replacing the entire group list. This example isolates the shape only.