@elevasis/sdk 1.15.1 → 1.16.0

package/reference/scaffold/recipes/customize-organization-model.md

@@ -36,14 +36,14 @@ const override = defineOrganizationModel({
       label: 'Dashboard',
       enabled: true,
       path: '/',
-      icon: 'dashboard',
+      icon: 'feature.dashboard',
       uiPosition: 'sidebar-primary'
     },
     {
       id: 'sales',
       label: 'Sales',
       enabled: true,
-      icon: 'briefcase',
+      icon: 'feature.sales',
       uiPosition: 'sidebar-primary'
     },
     {
@@ -71,7 +71,7 @@ Feature field reference:
 - `description` -- optional settings/help text.
 - `enabled` -- organization default.
 - `path` -- route path for leaf nodes. Containers omit it.
-- `icon` and `color` -- optional display metadata.
+- `icon` and `color` -- optional display metadata. Use semantic icon tokens such as `feature.dashboard`, `feature.sales`, or project-owned `custom.*` tokens; UI icon libraries are implementation details.
 - `uiPosition` -- `sidebar-primary` or `sidebar-bottom`; descendants inherit it.
 - `requiresAdmin` -- hides the node for non-admin members; descendants inherit it.
 - `devOnly` -- hides the node outside development contexts; descendants inherit it.

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

@@ -30,31 +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`, `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.              |
+| 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`, `ListBuilderPage`, `LeadGenCompaniesPage`, `LeadGenContactsPage`                          | `@elevasis/ui/features/lead-gen` | Shared lead-gen pages you can route to or wrap                       |
-| `ListActionsProvider`, `useListActions`, `ListBuilderWorkflow`, `ListBuilderRegistry`, MVP workflow form components                                           | `@elevasis/ui/features/lead-gen` | List Builder workflow registry, run modal inputs, 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          |
+| 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:
 
@@ -153,50 +153,77 @@ function ListBuilderRoute() {
 }
 ```
 
-Register project workflow actions at the provider boundary. The shared UI owns the contract; each project owns workflow ids and form choices:
+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 {
-  CompanyCleanupForm,
-  EmailDiscoveryForm,
-  EmailVerificationForm,
-  WebsiteExtractForm,
-  type ListBuilderRegistry
-} from '@elevasis/ui/features/lead-gen'
+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-04-email-discovery-workflow',
-    label: 'Email Discovery',
-    description: 'Discover contact email addresses for companies in the list.',
-    category: 'enrich',
-    stagesAffected: ['discovered'],
-    inputForm: EmailDiscoveryForm
-  },
-  {
-    resourceId: 'lgn-05-email-verification-workflow',
-    label: 'Email Verification',
-    description: 'Verify deliverability for contact emails in the list.',
-    category: 'enrich',
-    stagesAffected: ['verified'],
-    inputForm: EmailVerificationForm
-  },
-  {
-    resourceId: 'lgn-02-website-extract-workflow',
-    label: 'Website Extract',
-    description: 'Extract website intelligence for companies in the list.',
-    category: 'scrape',
-    stagesAffected: ['extracted'],
-    inputForm: WebsiteExtractForm
-  },
   {
     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'],
-    inputForm: CompanyCleanupForm
+    schema: companyCleanupInputSchema,
+    layout: companyCleanupLayout,
+    defaultInput: (list) => ({
+      listId: list.id,
+      targetDescription: '',
+      dryRun: true,
+      batchSize: 20
+    })
   }
 ]
 
@@ -209,6 +236,14 @@ export function App() {
 }
 ```
 
+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