Appointment wizard

The appointment wizard is the principal’s onboarding flow for a new AR or IAR. It renders at /demo/principal/register/new and walks the principal-admin through a four-stage path: Identity → Enrichment → Scope and due diligence → Notify the FCA. A sticky Draft contract preview rail builds on the right as the principal-admin works, so the SUP 12.5 written contract assembles itself in real time.

Live: lending-agent-oversight.vercel.app/demo/principal/register/new.

Why a wizard

Onboarding an AR is structurally a sequence of distinct, gated steps in the regulatory framework: SUP 12.4 due diligence comes before SUP 12.5 contract terms come before SUP 12.7 notification of intent comes before the actual appointment. A single long form would let the principal-admin fill in the wrong order or skip steps. A wizard with four stages and a live contract preview makes the gating obvious and demonstrates the connector layer doing real work between stages 1 and 2.

Stages

01 — Identity

The first stage captures the absolute minimum the platform needs to start an enrichment lookup.

Appointment type. Two radio cards: AR (full Appointed Representative — the AR carries on the principal’s regulated activities within scope) and IAR (Introducer Appointed Representative — limited to introductions per SUP 12.2). The cards carry a one-line scope reminder so the principal-admin doesn’t pick the wrong one.
Trading name. Free text, 2-character minimum.
Legal name. Free text, 2-character minimum.
Companies House number. Auto-uppercased, max 10 characters. A Lookup on next badge sits inside the input on the right to telegraph what stage 2 will do.

The Run enrichment → button activates when all four fields are filled. Clicking it advances to stage 2.

02 — Enrichment

This is the moment the connector work pays off. On stage entry, three connector cards appear in succession, each with a “Looking up…” amber badge and three skeleton placeholders. After ~1.8s, each card flips to “Synced” emerald and renders its enriched fields with motion-staggered row reveals.

Companies House

Fields populated: Registered office, SIC codes, Directors, Persons with significant control, Outstanding charges, Confirmation statement due. Source: https://developer.company-information.service.gov.uk/.

CreditSafe

Fields populated: Rating, Score (0-100), CCJs in last 24 months. Source: https://www.creditsafe.com/gb/en/business/api.html.

FCA Register

Fields populated: Status (Not yet authorised / Authorised / Cancelled), Permissions on Register. Source: https://register.fca.org.uk/Services/V0.1/Help/Index.

The principal-admin can ← Back or, once the enrichment completes, Configure scope →.

In production, errors on individual connectors don’t block the wizard — the affected card surfaces an error state and the principal-admin can proceed with the remaining data, with a [verify-on-onboarding] flag captured against the missing fields.

03 — Scope and due diligence

The SUP 12.5 contract scope and the SUP 12.4 pre-appointment checklist.

Permitted activities

A multi-select grid keyed to the principal’s rubric:

MCOB principals see four mortgage-broking permissions (advise, arrange, make-arrangements, agree-to-carry-on).
ICOBS principals see four insurance-distribution permissions (advise, arrange, assist, deal-as-agent).
CONC principals see three credit-broking permissions (credit broking, debt counselling, agree-to-carry-on).

If arType === "IAR", the grid collapses to a single fixed permission: IAR.INTRODUCE — Effecting introductions to the principal. An amber-tinted callout reminds the principal-admin that “IARs are limited to introductions only. Permission scope is fixed by SUP 12.2 and cannot be extended via the appointment contract.”

PS22/11 and SYSC 15A flags

Two amber-bordered toggle cards:

Self-employed AR cohort. When enabled: “PS22/11 enhanced oversight applies. Risk model up-weights this AR.”
Important Business Service. When enabled: “SYSC 15A. AR’s resilience posture rolls up to the principal’s resilience register.”

Contract reference

A SUP 12.5 written contract reference field defaulting to CONTRACT-2026-V1. Captures the executed contract version held on file. The annual review packet renders the contract in force at each cycle.

SUP 12.4 due-diligence checklist

Five items with explanatory subtext:

Check	Subtext
Fitness and propriety of the AR firm and its individuals	References, regulatory history, criminal-record self-declarations.
Solvency and financial standing	CreditSafe rating reviewed. Latest filed accounts on file.
Suitability of the proposed regulated activities	Permission scope matches the firm’s resourcing and competence.
Controllers and PSC verified	Companies House PSC register cross-checked for prohibited persons.
Resources adequate for the appointed activities	Headcount, professional indemnity insurance, T&C arrangements.

A counter N/5 next to the section label tracks completion. All five must be ticked to advance.

04 — Notify the FCA

PS22/11 / SUP 12.7: the principal must notify the FCA at least 30 calendar days before the appointment takes effect.

AR senior contact (name). The named individual at the AR firm.
Contact email. Validated against \S+@\S+\.\S+.
Notification of intent — PS22/11 (amber-bordered panel):
- Date FCA will be notified (date input, defaults to today).
- Earliest appointment date — read-only, computed as notification date + 30 days.
- Footnote: “The thirty-day window gives the FCA time to object. The platform opens the AR record on the register with status pending-appointment. The status flips to active on the appointment date provided no objection is raised.”

The Submit notification of intent button activates when the contact name and a valid email are present. Clicking it:

Generates an FRN for the new AR (random in the demo; production: assigned by FCA after the notification window).
Builds the AppointedRep record with status: "pending-appointment", the selected permissions, the IBS/self-employed flags, and the post-30-day appointment date.
Calls appendDraftAppointment(ar) on the demo store — the new AR appears at the top of the AR register with the brand-coloured row rail.
Flips the wizard to its success view.

Sticky live contract preview

A right-rail Card with a black header strip carrying Draft contract and the contract reference. The body grows as the principal-admin works through the stages:

Principal block (always visible) — principal firm name and FRN.
Appointed Representative block — trading name, legal name, CRN, and a Full AR / IAR (introducer only) badge. Italicised placeholders sit in for fields not yet filled.
Permitted activities (SUP 12.5) — bullet list of selected permission codes (italic placeholder until stage 3).
Controllers (Companies House) — appears once stage 2 completes; lists directors.
Flag chips — Self-employed cohort and Important Business Service amber chips when set.
Dates block — Notify FCA / Earliest appointment, both font-mono tabular-nums.
Contract assembly bar — N/10 fields counter and a 1px progress fill that animates each time a field is added.

The contract is the artefact, the wizard is just the assembly. By stage 4 the contract preview is recognisably a SUP 12.5 contract draft, ready for export.

Submitted view

A celebratory full-card surface replacing the wizard:

A 20-unit emerald-tinted card-rounded box with a PartyPopper icon, scale-in over 600ms.
Headline: Notification submitted. in Fraunces 3xl.
Body: [Trading name] is on the register with status pending-appointment. The earliest appointment date is [long date]. We've drafted the SUP 12.5 contract, attached the SUP 12.4 evidence pack, and started the audit chain.
Two CTAs: Back to register (outline, returns to the AR register where the new draft is at the top) and Appoint another (primary, restarts the wizard with cleared fields).

States

Stage gating. Each stage’s Continue → button is disabled until the stage’s valid predicate returns true. Disabled buttons use the standard shadcn disabled styling (50% opacity, no pointer events).
Enriching. Stage 2’s three cards each render skeleton placeholders for ~1.8s before flipping to populated rows. Reduced motion: skip the animation, render fields immediately.
Validation failure. Field-level Zod validation in production; the demo uses HTML constraints and a single submit-disabled predicate per stage.
Connector failure (production-only). Per-card error state with a Retry button. Wizard advance is blocked until either retry succeeds or the principal-admin clicks Proceed without [connector] (logs [verify-on-onboarding]).

Responsive behaviour

Mobile (< 1024px). Two-column layout collapses; the contract preview moves below the active stage. Stage progress dots hide on < 768px to save header room.
Desktop (≥ 1024px). Two-column grid-cols-[minmax(0,1fr)_360px] with the contract preview sticky at top-32.

Components

app/demo/principal/register/new/page.tsx (page shell)
components/principal/appoint-ar.tsx (top-level wizard with four Stage components, the ContractPreview, and the SubmittedView)

The wizard is intentionally one file — the four stages share enough state and motion to make a flat structure clearer than a wrapper-and-children pattern.

How this connects to the rest of the demo

Entry: from the AR register header CTA + Appoint a new AR or IAR, or via the network-empty state’s primary action.
On submission the new AR appears on the register at the top with status pending-appointment and the brand-coloured row rail. Clicking the row opens the AR detail, which renders the new draft just like any other AR.
The AR lifecycle state machine documents the pending-appointment → active transition that runs automatically on the cron job 30 days after submission, and the SUP 12.6A regulatory page covers the underlying notification regime.
The connector enrichment in stage 2 references the Connectors and enrichment architecture page for the production design.