@elevasis/sdk 1.15.0 → 1.16.0

package/reference/scaffold/recipes/extend-lead-gen.md

@@ -30,29 +30,31 @@ Lead gen is a layered platform surface, not one component:
 
 ## Decision Table
 
-| User wants                                                                        | Start here                                                                                                        | Notes                                                                                                           |
-| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| Change lead-gen feature availability, labels, quick access, or pipeline semantics | `core/config/organization-model.ts` plus `core/config/organization-model.examples.ts`                             | Treat this as Organization OS work. Use the project's configure ceremony if available.                          |
-| Add lead-gen sidebar nav or a lead-gen route                                      | `@elevasis/ui/features/lead-gen` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`          | Prefer manifest/sidebar composition. Do not fork shared source first.                                           |
-| Wrap a shared lead-gen page with project chrome                                   | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage` | Keep route files thin and put project-specific behavior in local feature modules.                               |
-| Build a custom campaign/list workspace                                            | `useLists`, `useList`, `useListMembers`, `useArtifacts`, `useTransitionListMember` from `@elevasis/ui/hooks`      | Use hooks for platform data and compose your own UI.                                                            |
-| Render artifacts or list-member detail                                            | `LeadGenListDetailPage`, `useArtifacts`, `useCreateArtifact`, `useListMember`                                     | Artifacts are a substrate primitive. Keep vertical-specific rendering local until there are repeated use cases. |
-| Read or mutate lead-gen data inside a workflow                                    | `acqDb` or `list` from `@elevasis/sdk/worker`                                                                     | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.         |
-| Add a new persisted lead-gen field, artifact kind, or transition API              | Platform/API migration work, not just scaffold work                                                               | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.              |
+| User wants                                                                        | Start here                                                                                                                                      | Notes                                                                                                           |
+| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Change lead-gen feature availability, labels, quick access, or pipeline semantics | `core/config/organization-model.ts` plus `core/config/organization-model.examples.ts`                                                           | Treat this as Organization OS work. Use the project's configure ceremony if available.                          |
+| Add lead-gen sidebar nav or a lead-gen route                                      | `@elevasis/ui/features/lead-gen` and `node_modules/@elevasis/sdk/reference/scaffold/ui/customization.md`                                        | Prefer manifest/sidebar composition. Do not fork shared source first.                                           |
+| Wrap a shared lead-gen page with project chrome                                   | `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`            | Keep route files thin and put project-specific behavior in local feature modules.                               |
+| Build a custom campaign/list workspace                                            | `ListBuilderPage`, `useLists`, `useList`, `useListProgress`, `useListExecutions`, `useWorkflowExecution`, `useExecutionSSE` from `@elevasis/ui` | Use the shared builder when possible; otherwise compose hooks for platform data and workflow execution.         |
+| Render artifacts or list-member detail                                            | `LeadGenListDetailPage`, `useArtifacts`, `useCreateArtifact`, `useListMember`                                                                   | Artifacts are a substrate primitive. Keep vertical-specific rendering local until there are repeated use cases. |
+| Read or mutate lead-gen data inside a workflow                                    | `acqDb` or `list` from `@elevasis/sdk/worker`                                                                                                   | `organizationId` is injected server-side by the platform dispatcher. Do not pass it from workflow code.         |
+| Add a new persisted lead-gen field, artifact kind, or transition API              | Platform/API migration work, not just scaffold work                                                                                             | Update DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts together.              |
 
 ## Published Lead-Gen Surfaces
 
-| Surface                                                                                                                                                      | Import from                      | Use for                                                              |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | -------------------------------------------------------------------- |
-| `leadGenManifest`, `LEAD_GEN_ITEMS`, `LeadGenSidebar`, `LeadGenSidebarTop`, `LeadGenSidebarMiddle`                                                           | `@elevasis/ui/features/lead-gen` | Feature registration and sidebar composition                         |
-| `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                                            | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                       |
-| `LeadGenRouteShell`, `CompanyDetailModal`, `ContactDetailModal`, `LIST_TEMPLATE_OPTIONS`, `buildListConfig`                                                  | `@elevasis/ui/features/lead-gen` | Route shell helpers, detail modals, and list creation config helpers |
-| `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks`             | Headless list and telemetry data access                              |
-| `useCompanies`, `useCompany`, `useContacts`, `useContact`                                                                                                    | `@elevasis/ui/hooks`             | Acquisition company/contact data access                              |
-| `useArtifacts`, `useCreateArtifact`, `useListMembers`, `useListMember`                                                                                       | `@elevasis/ui/hooks`             | Lead-gen substrate data access                                       |
-| `useTransitionList`, `useTransitionListMember`, `useTransitionListCompany`, `useDeriveActions`                                                               | `@elevasis/ui/hooks`             | Stateful transition mutations and contextual action derivation       |
-| `ElevasisUIProvider`, `ElevasisCoreProvider`, `useElevasisServices`                                                                                          | `@elevasis/ui/provider`          | Provider setup, API access, and organization context                 |
-| `acqDb`, `list`                                                                                                                                              | `@elevasis/sdk/worker`           | Workflow-side acquisition and list-scoped platform adapters          |
+| Surface                                                                                                                                                      | Import from                      | Use for                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `leadGenManifest`, `LEAD_GEN_ITEMS`, `LeadGenSidebar`, `LeadGenSidebarTop`, `LeadGenSidebarMiddle`                                                           | `@elevasis/ui/features/lead-gen` | Feature registration and sidebar composition                                                |
+| `LeadGenOverviewPage`, `LeadGenListsPage`, `LeadGenListDetailPage`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                         | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                                              |
+| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, `LeadGenCapabilityKey`                                                | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, slot-based field contracts, and project-owned action wiring |
+| `LeadGenRouteShell`, `CompanyDetailModal`, `ContactDetailModal`, `LIST_TEMPLATE_OPTIONS`, `buildListConfig`                                                  | `@elevasis/ui/features/lead-gen` | Route shell helpers, detail modals, and list creation config helpers                        |
+| `useLists`, `useList`, `useListsTelemetry`, `useListProgress`, `useListExecutions`, `useCreateList`, `useUpdateList`, `useUpdateListConfig`, `useDeleteList` | `@elevasis/ui/hooks`             | Headless list and telemetry data access                                                     |
+| `useWorkflowExecution`, `useExecutionSSE`, `useAddCompaniesToList`, `useRemoveCompaniesFromList`, `useAddContactsToList`                                     | `@elevasis/ui/hooks`             | List Builder workflow triggering, live execution tailing, and list membership mutations     |
+| `useCompanies`, `useCompany`, `useContacts`, `useContact`                                                                                                    | `@elevasis/ui/hooks`             | Acquisition company/contact data access                                                     |
+| `useArtifacts`, `useCreateArtifact`, `useListMembers`, `useListMember`                                                                                       | `@elevasis/ui/hooks`             | Lead-gen substrate data access                                                              |
+| `useTransitionList`, `useTransitionListMember`, `useTransitionListCompany`, `useDeriveActions`                                                               | `@elevasis/ui/hooks`             | Stateful transition mutations and contextual action derivation                              |
+| `ElevasisUIProvider`, `ElevasisCoreProvider`, `useElevasisServices`                                                                                          | `@elevasis/ui/provider`          | Provider setup, API access, organization context, and `listActions` registry injection      |
+| `acqDb`, `list`                                                                                                                                              | `@elevasis/sdk/worker`           | Workflow-side acquisition and list-scoped platform adapters                                 |
 
 Read the generated contracts before changing typed boundaries:
 
@@ -135,6 +137,113 @@ function ListDetailRoute() {
 
 Use the same wrapping pattern for `LeadGenOverviewPage`, `LeadGenCompaniesPage`, and `LeadGenContactsPage`.
 
+For the real-time List Builder workspace, add a thin route that passes the route param into `ListBuilderPage`:
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { ListBuilderPage } from '@elevasis/ui/features/lead-gen'
+
+export const Route = createFileRoute('/lead-gen/list-builder/$listId')({
+  component: ListBuilderRoute
+})
+
+function ListBuilderRoute() {
+  const { listId } = Route.useParams()
+  return <ListBuilderPage listId={listId} />
+}
+```
+
+Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids, capability keys, default inputs, and field components.
+
+Each registry entry declares a Zod `schema` and a `layout` of declarative field hints (`StepConfigLayout<Input>`). The shared `StepConfigForm` renders the layout, validates against the schema, and wires `value`/`onChange` for you — no per-action React components. The List Builder right column renders the form as `Configuration | Advanced | Runs` tabs with a sticky action footer; `RunWorkflowModal` renders the same form inline. Omit the `advanced:` section when a step has none.
+
+Available field component variants: `textinput`, `textarea`, `numberinput`, `switch`, `segmented`, `select`, `multiselect`, `tags`, `json`. Field hints support `label`, `description`, `placeholder`, `min`/`max`/`step` (numbers), `options` (selects), and `when: (values) => boolean` for conditional visibility.
+
+```tsx
+import * as z from 'zod'
+import { type ListBuilderRegistry } from '@elevasis/ui/features/lead-gen'
+import type { StepConfigLayout } from '@elevasis/ui/components/forms'
+import { ElevasisUIProvider } from '@elevasis/ui/provider'
+
+const companyCleanupInputSchema = z.object({
+  listId: z.string().uuid(),
+  targetDescription: z.string(),
+  dryRun: z.boolean().default(true),
+  batchSize: z.number().int().min(1).default(20),
+  mode: z.enum(['mock', 'live']).default('live')
+})
+
+type CompanyCleanupInput = z.infer<typeof companyCleanupInputSchema>
+
+const companyCleanupLayout: StepConfigLayout<CompanyCleanupInput> = {
+  sections: [
+    {
+      id: 'configuration',
+      fields: [
+        {
+          path: 'targetDescription',
+          component: 'textarea',
+          label: 'Target description',
+          placeholder: 'independent veterinary clinics in Orange County'
+        },
+        { path: 'dryRun', component: 'switch', label: 'Dry run' }
+      ]
+    }
+  ],
+  advanced: {
+    id: 'advanced',
+    fields: [
+      { path: 'batchSize', component: 'numberinput', label: 'Batch size', min: 1 },
+      {
+        path: 'mode',
+        component: 'segmented',
+        options: [
+          { value: 'mock', label: 'Mock' },
+          { value: 'live', label: 'Live' }
+        ],
+        when: () => import.meta.env.DEV
+      }
+    ]
+  }
+}
+
+const listActions: ListBuilderRegistry = [
+  {
+    resourceId: 'lgn-company-cleanup-workflow',
+    workflowId: 'lgn-company-cleanup-workflow',
+    capabilityKey: 'lead-gen.company.cleanup',
+    label: 'Company Cleanup',
+    description: 'Normalize and clean company records for the list.',
+    category: 'utility',
+    stagesAffected: ['populated'],
+    schema: companyCleanupInputSchema,
+    layout: companyCleanupLayout,
+    defaultInput: (list) => ({
+      listId: list.id,
+      targetDescription: '',
+      dryRun: true,
+      batchSize: 20
+    })
+  }
+]
+
+export function App() {
+  return (
+    <ElevasisUIProvider listActions={listActions} {...providerProps}>
+      {children}
+    </ElevasisUIProvider>
+  )
+}
+```
+
+Author the `schema` in a browser-safe sibling file (no Node-only imports) so it can be reused by the workflow runtime AND the UI form. See `apollo-import-schema.ts` in the platform for the canonical split pattern.
+
+Per-section split rule (operator-grade vs power-user):
+
+- **Configuration:** target/limit, dry-run toggle, mode (preview/finalize), and any field an operator changes between runs.
+- **Advanced:** concurrency, batch size, timeouts, credential names, workflow chaining, dev-only mode toggles. Omit the `advanced:` key entirely when a step has none.
+- **`defaultInput`:** seeds the form before the user touches anything; must include `listId: list.id`.
+
 ## 3. Build a Custom Campaign Workspace
 
 When the project needs custom layout or vertical-specific rendering, use the hooks directly:

package/reference/scaffold/recipes/gate-by-feature-or-admin.md

@@ -29,7 +29,7 @@ features: [
     label: 'Analytics',
     enabled: false,
     path: '/analytics',
-    icon: 'chart',
+    icon: 'custom.analytics',
     uiPosition: 'sidebar-primary'
   }
 ]

package/reference/scaffold/recipes/index.md

@@ -34,6 +34,12 @@ You want to build on the shared lead-gen system without forking it: add lead-gen
 **[Customize CRM Actions](customize-crm-actions.md)**
 You want to add, hide, or replace CRM deal action buttons, configure the shared `crmActions` provider path, or call a project-owned workflow from custom UI when server-side action dispatch constraints require it. Covers `ActionDef`, `DEFAULT_CRM_ACTIONS`, provider wiring, and the current v1 boundary for custom action dispatch.
 
+**[Customize Knowledge Browser](customize-knowledge-browser.md)**
+You want to mount, extend, or replace the default Knowledge Browser. Covers the three customization tiers (default manifest mount, sidebar composition via `KnowledgeSidebarMiddle` + `KNOWLEDGE_ITEMS`, and direct query access via `@elevasis/core/knowledge`), the one-line `vite.config.ts` plugin add (`knowledgePlugin()` from `@elevasis/ui/vite-plugin-knowledge`), and the CSS import requirement.
+
+**[Query the Knowledge Graph](query-the-knowledge-graph.md)**
+You want to browse, inspect, or traverse the OrganizationModel knowledge graph from the command line. Covers the three verbs (`knowledge:ls`, `knowledge:cat`, `knowledge:graph`), all five mount axes (`/by-feature/`, `/by-kind/`, `/by-owner/`, `/graph/.../governs/`, `/graph/.../governed-by/`), dual-CLI invocation patterns (`elevasis-sdk` for external projects, `elevasis` for the monorepo), and the Windows/MSYS PowerShell gotcha.
+
 ---
 
 ## Reference docs these recipes link into