Console welcome flow and tour

A user who has not finished onboarding lands on /welcome after signing in. The welcome flow issues their first API key in the personal workspace’s default project and shows a ready-to-run request. Finishing or skipping it records onboarding_completed_at on the user, so it is shown once. Afterwards the user menu offers Welcome guide, which reopens /welcome without issuing a new key, and Take the console tour, which replays the coach-mark tour of the console.

Settings

Variable	Default	Purpose
NEXUS_GATEWAY_PUBLIC_URL	https://$NEXUS_HOSTNAME/v1, else http://127.0.0.1:14450/v1	Base URL shown in the snippets. Must be reachable by users.
NEXUS_WELCOME_MODEL	Newest GPT chat model enabled in the registry, else nexus/auto	Model the snippets call.
NEXUS_WELCOME_GREETING	Welcome to Nexus, {first_name}	Welcome heading template (see placeholders below).
NEXUS_WELCOME_NAME_FORMAT	auto	How to split display_name into first/last (see below).
NEXUS_ONBOARDING_CONFIG	Everything on	JSON object that customizes the welcome flow and tour.

The Helm charts derive NEXUS_GATEWAY_PUBLIC_URL from the API host and scheme (ingress.tls in deploy/helm/nexus, application.publicScheme in nexus-iac); set console.gatewayPublicUrl in deploy/helm/nexus to override it.

Without NEXUS_WELCOME_MODEL, the console reads the model registry and picks the highest-versioned enabled gpt-* model, preferring the plain model over named variants and those over -mini and -nano. It skips variants the snippet cannot call on chat completions (-pro, -codex, audio, realtime, search, image, dated snapshots) and quarantined endpoints.

NEXUS_ONBOARDING_CONFIG

Every key is optional:

{
    "welcome": {
        "enabled": true,
        "steps": ["key", "request"],
        "model": "gpt-5.5",
        "greeting": "Welcome to Nexus, {first_name}",
        "nameFormat": "auto"
    },
    "tour": {
        "enabled": true,
        "exclude": ["workspace-billing"],
        "overrides": {
            "help": { "title": "Runbooks", "description": "Internal guides for this deployment." }
        }
    }
}

• welcome.enabled: false turns the welcome flow off: users go straight to the console and the user menu hides Welcome guide.
• welcome.steps lists the welcome steps to show. key (the API key) is always shown; drop request to finish right after the key.
• welcome.model sets the snippet model; NEXUS_WELCOME_MODEL takes precedence.
• welcome.greeting sets the welcome heading. Placeholders: {first_name}, {last_name}, {display_name}, {given_name}, {family_name}. NEXUS_WELCOME_GREETING takes precedence. First/last are derived by splitting the stored display name; see welcome.nameFormat.
• welcome.nameFormat controls that split: auto (comma ⇒ family-given-comma, else given-family), given-family (Ada Lovelace), family-given (Lovelace Ada), or family-given-comma (Lovelace, Ada). NEXUS_WELCOME_NAME_FORMAT takes precedence. Pair this with the OIDC connection’s *_DISPLAY_NAME_TEMPLATE so the stored display name matches the format you parse.
• tour.enabled: false turns the tour off: the welcome flow’s Take a quick tour button and the user menu’s tour item are hidden.
• tour.exclude drops tour steps by id. Excluding every step turns the tour off.
• tour.overrides replaces a step’s title, description, or both.

A value that is not a JSON object is logged and ignored, so the defaults apply.

Tour step ids

Steps run in this order. A step whose console element is not shown to the user (for example Billing for a non-manager, or Help without NEXUS_DOCS_URL) is skipped automatically.

Id	Highlights
workspace-switcher	Workspace switcher
workspace-usage	Workspace usage
workspace-billing	Billing
workspace-members	Members
workspace-organizations	Organizations
scope-org	Selected organization’s section
scope-project	Selected project’s section
scope-search	Organization and project search
model-registry	Model registry
help	Help link
user-menu	User menu

Model access for new users

The welcome flow does not ask users for a provider key. A first request succeeds only when the project can reach a provider: Nexus-managed access (NEXUS_GATEWAY_PTB=1, enabled for the workspace, a platform provider key, and wallet funds), or a provider key an administrator connected to the project. When neither holds, the request step warns that requests will be rejected until a workspace manager enables model access.

Deployment examples

Compose

NEXUS_GATEWAY_PUBLIC_URL=https://api.example.com/v1
NEXUS_WELCOME_MODEL=gpt-5.5
NEXUS_WELCOME_GREETING=Welcome to Nexus, {last_name}, {first_name}
NEXUS_WELCOME_NAME_FORMAT=family-given-comma
NEXUS_ONBOARDING_CONFIG={"tour":{"exclude":["workspace-billing"]}}

Inspect what an IdP actually returns (raw + normalized claims):

nexus auth oidc list
nexus auth oidc probe --connection pingfederate --port 9876
# Register http://127.0.0.1:9876/callback at the IdP first.
# Or normalize pasted UserInfo / ID-token payload JSON offline:
nexus auth oidc normalize --connection pingfederate --json claims.json

Helm

console:
    welcomeModel: gpt-5.5
    welcomeGreeting: "Welcome to Nexus, {last_name}, {first_name}"
    onboarding:
        welcome:
            nameFormat: family-given-comma
        tour:
            exclude: [workspace-billing]

In nexus-iac, the same keys live under application.console.

Verification

1. Sign in as a new user and confirm /welcome shows a key named default and, on the request step, the expected base URL and model.
2. Run the curl snippet from a user’s network and confirm the request step reports First request received.
3. Open the user menu and confirm Welcome guide and Take the console tour match the configuration, and that excluded tour steps do not appear.