# onboarding-01 (`onboarding-01`) - SignalOS page block

> Four-step onboarding wizard - custom model, connectors, pipelines, then department - with per-step loading and submitting states. Embeds the custom-model and add-connection dialogs.

- **Version:** 0.3.4
- **Kind:** block (group: onboarding) · **Category:** pages
- **Install:** `npx shadcn@latest add @signalos/onboarding-01`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/button, @signalos/card, @signalos/text-field, @signalos/dropdown-menu, @signalos/tooltip, @signalos/addconnector-01, @signalos/pipelinewizard-01, @signalos/addmodels-01, @signalos/badge, @signalos/input, @signalos/select, @signalos/form-dialog, @signalos/onboarding-wizard, @signalos/add-card, @signalos/confirm-dialog, @signalos/icon-button, @signalos/status-badge
- **npm dependencies:** lucide-react@^1.7.0
- **Files installed:** `src/components/blocks/onboarding-01/Onboarding01.types.ts`, `src/components/blocks/onboarding-01/Onboarding01.tsx`, `src/components/blocks/onboarding-01/Onboarding01.constants.ts`, `src/components/blocks/onboarding-01/components/ConnectorGrid.tsx`, `src/components/blocks/onboarding-01/components/PipelineListStep.tsx`, `src/components/blocks/onboarding-01/components/ConnectorGrid.types.ts`, `src/components/blocks/onboarding-01/components/CustomModelsStep.tsx`, `src/components/blocks/onboarding-01/components/CustomModelsStep.types.ts`, `src/components/blocks/onboarding-01/components/DepartmentSetup.tsx`, `src/components/blocks/onboarding-01/components/DepartmentSetup.types.ts`, `src/components/blocks/onboarding-01/components/departmentsetup/RolesSection.tsx`, `src/components/blocks/onboarding-01/components/departmentsetup/MemberForm.tsx`, `src/components/blocks/onboarding-01/components/departmentsetup/MemberList.tsx`, `src/components/blocks/onboarding-01/components/EditPipelineDialog.tsx`, `src/components/blocks/onboarding-01/components/EditPipelineDialog.types.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
// after: npx shadcn@latest add @signalos/onboarding-01
// mount the pulled page in a route, e.g. src/app/onboarding/page.tsx
import Onboarding01 from "@/components/blocks/onboarding-01/Onboarding01"

export default function Page() {
  return <Onboarding01 />
}
```

## Props

### `CustomModelDialogPassthroughProps`

```ts
export type CustomModelDialogPassthroughProps = Omit<
  CustomModelDialogProps,
  "data-testid"
>
```

### `AddConnectionModalPassthroughProps`

```ts
export type AddConnectionModalPassthroughProps = Pick<
  AddConnectionModalProps,
  | "open"
  | "onOpenChange"
  | "step"
  | "connectorUrl"
  | "connectionName"
  | "purposeDetails"
  | "availableConnectors"
  | "currentSpec"
  | "configValues"
  | "testResult"
  | "localError"
  | "isLoadingAvailable"
  | "isLoadingSpec"
  | "isTesting"
  | "isCreating"
  | "isLaunching"
  | "skipPipelineLaunch"
  | "getConnectorIcon"
  | "onSelectConnector"
  | "onManualConnect"
  | "onBack"
  | "onTestConnection"
  | "onSaveConnection"
  | "onConfigChange"
  | "onConnectionNameChange"
  | "onConnectorUrlChange"
  | "onPurposeChange"
>
```

### `CreatePipelineWizardPassthroughProps`

```ts
export type CreatePipelineWizardPassthroughProps = Pick<
  CreatePipelineWizardProps,
  | "open"
  | "onOpenChange"
  | "step"
  | "onStepChange"
  | "name"
  | "onNameChange"
  | "description"
  | "onDescriptionChange"
  | "selectedConnectionIds"
  | "onSelectedConnectionIdsChange"
  | "fieldErrors"
  | "onFieldErrorsChange"
  | "reasoningModel"
  | "onReasoningModelChange"
  | "supportingModel"
  | "onSupportingModelChange"
  | "embeddingModel"
  | "onEmbeddingModelChange"
  | "connections"
  | "llmModels"
  | "embeddingModels"
  | "isLoadingModels"
  | "isLoadingQuestions"
  | "isLoadingConnectors"
  | "isSubmitting"
  | "contextQuestions"
  | "contextAnswers"
  | "onContextAnswerChange"
  | "onOpen"
  | "onSubmit"
  | "onCreateCustomModel"
>
```

### `SemanticsPipelineType`

```ts
export type SemanticsPipelineType = "single" | "multi_source"
```

### `SemanticsPipelineStatus`

```ts
export type SemanticsPipelineStatus =
  "pending" | "running" | "awaiting_review" | "completed" | "failed"
```

### `SemanticsStageName`

```ts
export type SemanticsStageName =
  | "discover"
  | "content_profile"
  | "questionnaire"
  | "glossary"
  | "internal_relationships"
  | "cross_source_enrichment"
  | "functions"
  | "signal_rules"
  | "equilibria"
```

### `PipelineLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `pipeline_id` | `string` | yes | - |  |
| `name` | `string` | yes | - |  |
| `description` | `string \| undefined` | no | - |  |
| `status` | `SemanticsPipelineStatus` | yes | - |  |
| `pipeline_type` | `SemanticsPipelineType \| undefined` | no | - |  |
| `connector_count` | `number` | yes | - |  |
| `created_at` | `string` | yes | - |  |
| `current_stage` | `SemanticsStageName` | yes | - |  |

### `Onboarding01Props`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `open` | `boolean` | yes | - | Whether the onboarding wizard dialog is open. |
| `onOpenChange` | `(open: boolean) => void` | yes | - | Called when the dialog requests to open or close. |
| `currentStep` | `number \| undefined` | no | `0` | Zero-indexed current step. Steps are ordered: 0 = Custom Model, 1 = Connectors, 2 = Pipelines, 3 = Department |
| `onNext` | `(() => void) \| undefined` | no | - | Called when the user advances to the next step. |
| `onBack` | `(() => void) \| undefined` | no | - | Called when the user navigates back to the previous step. |
| `onFinish` | `(() => void) \| undefined` | no | - | Called when the user completes the final step and submits the wizard. The parent is responsible for any submission side-effects and for closing the dialog via `onOpenChange(false)`. |
| `isSubmitting` | `boolean \| undefined` | no | `false` | Whether a submission is in flight. Disables the Finish button and shows a spinner on the last step. |
| `canProceed` | `boolean \| undefined` | no | `true` | Whether the current step's primary action is permitted. When `false` the Next / Finish button is disabled. |
| `error` | `ReactNode` | no | - | An error message rendered above the footer actions. Omit to show nothing. |
| `eyebrow` | `ReactNode` | no | - | Optional eyebrow text rendered above the wizard title in the header. |
| `title` | `ReactNode` | no | `"Set up your workspace"` | Wizard title rendered in the header. |
| `subtitle` | `ReactNode` | no | `"Follow the steps below to configure SignalOS for your team."` | Subtitle rendered below the title in the header. |
| `className` | `string \| undefined` | no | - |  |
| `pipelines` | `PipelineLike[] \| undefined` | no | `[]` | Pipelines to display on the Pipelines step. |
| `isPipelinesLoading` | `boolean \| undefined` | no | `false` | Whether pipelines are currently loading. |
| `onCreatePipeline` | `(() => void) \| undefined` | no | - | Called when the user requests to create a new pipeline. |
| `onEditPipeline` | `((pipeline: PipelineLike) => void) \| undefined` | no | - | Called when the user requests to edit an existing pipeline. |
| `onDeletePipeline` | `((pipeline: PipelineLike) => void) \| undefined` | no | - | Called when the user requests to delete an existing pipeline. |
| `data-testid` | `string \| undefined` | no | - | Test identifier rendered as `data-testid` on the root element. |
| `connectors` | `ConnectorLike[] \| undefined` | no | `[]` | Platform connections to display in the connector grid. |
| `isConnectorsLoading` | `boolean \| undefined` | no | `false` | Whether connectors are still loading. |
| `onAddConnector` | `() => void` | yes | - | Called when the user requests to add a connector. |
| `customModels` | `CustomModelLike[] \| undefined` | no | `[]` | Custom models already saved by the user. |
| `isLoadingCustomModels` | `boolean \| undefined` | no | `false` | Whether the custom models list is loading. |
| `isTestingModel` | `boolean \| undefined` | no | `false` | Whether a connection test is in flight. |
| `testingModelId` | `string \| null \| undefined` | no | - | ID of the model whose test connection call is in-flight. |
| `onOpenCreateModel` | `(() => void) \| undefined` | no | - | Called when the user opens the "create custom model" dialog. |
| `onOpenEditModel` | `((model: CustomModelLike) => void) \| undefined` | no | - | Called when the user opens the "edit custom model" dialog. |
| `onDeleteModel` | `((model: CustomModelLike) => void) \| undefined` | no | - | Called when the user deletes a custom model. |
| `onTestModel` | `((model: CustomModelLike) => void) \| undefined` | no | - | Called when the user tests a custom model connection. |
| `serverRoles` | `ServerRoleLike[] \| undefined` | no | `[]` | Roles already persisted server-side (read-only). |
| `isServerRolesLoading` | `boolean \| undefined` | no | `false` | Whether server roles are still loading. |
| `localRoles` | `LocalRoleLike[] \| undefined` | no | `[]` | Locally-created roles not yet saved. |
| `allUsers` | `UserLike[] \| undefined` | no | `[]` | Existing platform users for the escalation-manager picker. |
| `members` | `MemberLike[] \| undefined` | no | `[]` | Members added locally during this onboarding session. |
| `onAddRole` | `((role: { name: string; description: string; }) => void) \| undefined` | no | - |  |
| `onUpdateRole` | `((tempId: string, role: { name: string; description: string; }) => void) \| undefined` | no | - |  |
| `onDeleteRole` | `((tempId: string) => void) \| undefined` | no | - |  |
| `onAddMember` | `((member: Omit<MemberLike, "id">) => void) \| undefined` | no | - |  |
| `onUpdateMember` | `((id: string, member: MemberLike) => void) \| undefined` | no | - |  |
| `onDeleteMember` | `((id?: string \| undefined) => void) \| undefined` | no | - |  |
| `editingPipeline` | `SemanticsPipelineListItemLike \| null \| undefined` | no | - | The pipeline currently being edited (opens the edit dialog when set). |
| `isEditingPipelineSubmitting` | `boolean \| undefined` | no | `false` | Whether the edit-pipeline save is in flight. |
| `onEditingPipelineOpenChange` | `((open: boolean) => void) \| undefined` | no | - | Called when the edit-pipeline dialog requests open/close. |
| `onSavePipelineEdit` | `((payload: { name?: string \| undefined; description?: string \| undefined; }) => void) \| undefined` | no | - | Called when the user saves pipeline edits. |
| `customModelDialog` | `CustomModelDialogPassthroughProps \| undefined` | no | - | All props forwarded verbatim to the embedded CustomModelDialog. When omitted the dialog is not rendered. |
| `addConnectionModal` | `AddConnectionModalPassthroughProps \| undefined` | no | - | All props forwarded verbatim to the embedded AddConnectionModal. When omitted the modal is not rendered. |
| `createPipelineWizard` | `CreatePipelineWizardPassthroughProps \| undefined` | no | - | All props forwarded verbatim to the embedded CreatePipelineWizard. When omitted the wizard is not rendered. |
| `deletePipelineConfirm` | `Pick<ConfirmDialogProps, "open" \| "onOpenChange" \| "description" \| "title" \| "onConfirm" \| "isConfirming" \| "confirmLabel" \| "cancelLabel" \| "dialogTestId" \| "confirmTestId" \| "cancelTestId"> \| undefined` | no | - | Props forwarded to the delete-pipeline ConfirmDialog. When omitted the dialog is not rendered. |

### `ConnectorLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes | - |  |
| `name` | `string` | yes | - |  |
| `connector_name` | `string \| undefined` | no | - |  |

### `CustomModelLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes | - |  |
| `name` | `string` | yes | - |  |
| `provider_kind` | `string` | yes | - |  |
| `model_id` | `string \| null \| undefined` | no | - |  |
| `endpoint_url` | `string \| null \| undefined` | no | - |  |
| `api_version` | `string \| null \| undefined` | no | - |  |
| `config` | `Record<string, unknown> \| null \| undefined` | no | - |  |
| `has_api_key` | `boolean` | yes | - |  |
| `status` | `"error" \| "active" \| "inactive"` | yes | - |  |
| `error_message` | `string \| null \| undefined` | no | - |  |
| `created_at` | `string` | yes | - |  |
| `last_checked_at` | `string \| null \| undefined` | no | - |  |

### `ServerRoleLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string \| undefined` | no | - |  |
| `name` | `string` | yes | - |  |
| `description` | `string` | yes | - |  |

### `LocalRoleLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tempId` | `string` | yes | - |  |
| `name` | `string` | yes | - |  |
| `description` | `string` | yes | - |  |

### `UserLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | yes | - |  |
| `full_name` | `string` | yes | - |  |
| `email` | `string` | yes | - |  |

### `MemberLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `string \| undefined` | no | - |  |
| `full_name` | `string` | yes | - |  |
| `role_id` | `string` | yes | - |  |
| `email` | `string` | yes | - |  |
| `password` | `string` | yes | - |  |
| `manager_id` | `string \| undefined` | no | - |  |

### `SemanticsPipelineListItemLike`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `pipeline_id` | `string` | yes | - |  |
| `name` | `string \| undefined` | no | - |  |
| `description` | `string \| undefined` | no | - |  |
| `status` | `string` | yes | - |  |
| `current_stage` | `string` | yes | - |  |
| `connector_count` | `number` | yes | - |  |
| `created_at` | `string` | yes | - |  |
| `pipeline_type` | `string \| undefined` | no | - |  |

## Changelog

## 0.3.4

- Replace the copied placeholder description with one that actually describes this block; the registry description is what the agent skill shows as "pick it when".

## 0.3.3

- Decompose `DepartmentSetup` into `MemberForm`, `MemberList`, and `RolesSection` subcomponents under `components/departmentsetup/`.
- Wire `AddConnectionModal`, `CustomModelDialog`, and `CreatePipelineWizard` block imports into the onboarding flow.

## 0.3.2

- Fix cross-item imports to use canonical @/components paths; add missing signalos.category to manifests.

# onboarding-01
## 0.3.1
- format the code

## 0.3.0

- Declare `@signalos/addconnector-01` as a `registryDependency` so consumers pulling `onboarding-01` automatically receive `addconnector-01`.

## 0.2.2

- Wire `CreatePipelineWizard` and `AddConnectionModal` into `Onboarding01`: both
  are now rendered outside the wizard dialog (so they layer correctly) and driven
  by new optional prop groups `createPipelineWizard` and `addConnectionModal`.
  Pass either prop object to enable the respective modal; omit it to suppress the
  render entirely.
- Add `AddConnectionModalPassthroughProps` and `CreatePipelineWizardPassthroughProps`
  type aliases in `Onboarding01.types.ts` so callers get a single import for the
  full prop shapes required by each embedded modal.

## 0.2.1

- Replace all raw color-scale utilities (`error-500`, `success-700`, `warning-600`, `info-500`, etc.) with semantic tokens (`text-destructive`, `text-text-success`, `bg-bg-warning`, `border-border-error`, etc.) across `CustomModelsStep`, `PipelineListStep`, and `DepartmentSetup` so client theme overrides apply correctly.

## 0.2.0

- Full rewrite of `Onboarding01.tsx`: the block now orchestrates the four-step
  onboarding flow (Custom Model → Connectors → Pipelines → Department) inside
  an `OnboardingWizard` dialog. All navigation state is owned by the caller via
  props (`open`, `currentStep`, `onNext`, `onBack`, `onFinish`).
- Add `Onboarding01Props` in `Onboarding01.types.tsx` with a fully documented
  prop contract including `canProceed`, `isSubmitting`, `error`, `title`,
  `subtitle`, `eyebrow`, and pipeline-step props.
- Introduce `PipelineLike` structural interface in `Onboarding01.types.tsx` so
  the block remains free of app domain types.
- Add `Onboarding01.constant.tsx` with `ONBOARDING_STEPS`, default title,
  subtitle, and test-id constants.
- `PipelineListStep` is now a named export and uses `PipelineLike` instead of
  the app type `SemanticsPipelineListItem`.
- Add `Onboarding01.test.tsx` covering: closed/open render, default and custom
  title, step routing, Next/Back/Finish callbacks, `canProceed` disabled state,
  error message, and `isSubmitting` state.
- Update `Onboarding01.preview.tsx` with seven catalog scenarios covering every
  step, the loading state, the error state, and the submitting state.

## 0.1.0

- Initial scaffold: thin wrapper around `OnboardingWizard`.