Onboarding Guidelines

Onboarding is designed after the product promise and release model, but before core functionality. It defines how a person or system moves from zero knowledge and zero configuration to the first successful product outcome.

Onboarding is part of the product, not an installation appendix.

Terminology boundary

Onboarding is the first-use product journey that explains the product promise and operating model, learns the intended outcome, and leads the user to one observable successful product result.

The following remain separate operations even when a journey invokes them:

• authentication establishes a user or workload identity;
• installation places a supported release on a target system;
• setup configures an environment, product, or integration;
• provisioning creates infrastructure or external resources;
• credential lifecycle creates, verifies, rotates, revokes, or removes a credential;
• activation is the first meaningful product action;
• first success is the first observed result that fulfills the product promise;
• checkout completes a commercial transaction;
• entitlement is the authoritative observed right to use a paid capability.

Onboarding may invoke authentication, installation, setup, provisioning, or a credential operation just in time. Those operations do not become onboarding merely because they happen during first use. Product copy, code, analytics, and documentation must preserve these boundaries.

The onboarding owner owns explanation, routing, and observation of first success. The invoked component continues to own its state transitions, permissions, recovery, idempotency, and failure behavior.

The canonical classification of repositories and product surfaces is maintained in Onboarding Product Inventory.

Required outcome

A new intended user must be able to:

• understand what they need before starting;
• install an exact supported release;
• configure the minimum viable environment;
• start the required product components;
• complete one representative workflow;
• recognize the expected successful result;
• diagnose common failures without private assistance;
• remove or reset the local setup safely;
• understand the free and paid boundary before activating a paid capability;
• encounter a truthful paywall and either complete, restore, or deliberately decline the commercial step;
• resume the journey at the correct state after interruption.

Start from a true zero state

Design onboarding against a clean environment:

• no existing configuration;
• no cached credentials;
• no pre-created state directory;
• no implicit environment variables;
• no running background services;
• no repository-specific shell setup;
• no knowledge of internal terminology.

Do not validate onboarding only on a maintainer's configured workstation.

First screen or first command

Launching the product without arguments or configuration must produce safe, actionable guidance. It should explain:

• the product's one-sentence purpose;
• the minimum configuration categories;
• the safest supported starting mode;
• the next command or action;
• how to access full help.

The zero-state path must not create mutable state, contact external services, request broad credentials, or start billable resources merely to display guidance.

Prerequisites

List prerequisites before installation. Separate them into:

• required for every installation;
• required only for a specific operating mode;
• required only for an optional integration;
• supplied automatically by the installer.

Prerequisites may include operating system support, architecture, runtime, drivers, network access, local permissions, cloud accounts, identity, storage, or external services.

State how each prerequisite can be checked.

Installation

Installation instructions must:

• select an exact release channel and version;
• obtain artifacts from the canonical release source;
• verify integrity and provenance;
• explain the installation location;
• avoid requiring a source checkout for normal users;
• state whether elevated privileges are required;
• explain how to uninstall or revert.

Installation and configuration must be separate concepts. Installing a binary must not silently create production configuration.

Minimum configuration

Explain the smallest configuration that produces a useful result. Group configuration by user decision rather than by internal module.

Typical categories are:

• state or data storage;
• execution or compute provider;
• worker or service location;
• identity and credentials;
• network exposure;
• cost and safety limits.

Provide safe defaults for local or sandbox use. Clearly identify values that users must replace and values generated automatically.

Configuration generation must be idempotent or must refuse to overwrite existing configuration. Generated files must contain no real secrets.

Credentials and permissions

Request credentials only when the selected workflow needs them. Explain:

• the identity being used;
• the permissions required;
• why each permission is needed;
• where the credential is stored;
• how it is rotated or revoked;
• which operations remain unavailable without it.

Prefer workload identity, managed identity, or scoped grants over copied long-lived secrets. Never tell users to paste credentials into commands, screenshots, logs, or committed files.

First successful workflow

Choose one workflow that represents the core product promise and can complete quickly with minimal risk.

The walkthrough must include:

1. the exact starting state;
2. copyable commands or actions;
3. the expected output after each meaningful step;
4. the final artifact, status, or visible result;
5. cleanup or shutdown instructions.

A command completing with exit code zero is not enough. The user must be able to observe the promised outcome.

Progressive disclosure

The initial path should teach only what is required for first success. Advanced providers, production topology, automation, integrations, scaling, and policy belong in follow-up paths.

After first success, offer clear next steps such as:

• use real workload data;
• connect a shared backend;
• add another worker;
• enable a cloud provider;
• configure secrets;
• enable automation or integrations;
• move from local to production deployment.

Dynamic progression

Human onboarding must be dynamic. It must derive the current step, available actions, explanations, and completion state from live product evidence rather than a fixed page index or a static checklist.

The journey must:

• skip requirements that are already satisfied;
• reveal a requirement only when the selected workflow needs it;
• update immediately when identity, entitlement, permissions, services, integrations, or local capabilities change;
• preserve completed work and resume at the first unresolved user decision after relaunch;
• distinguish loading, unavailable, stale, failed, blocked, and complete states;
• provide a safe retry or alternate route when a dependency is unavailable;
• keep back navigation and cancellation safe, without repeating completed side effects;
• explain why the next action changed when new evidence changes the route.

Dynamic behavior must be modeled as explicit states and transitions. Unknown or contradictory evidence must fail safe and show a corrective action; it must not silently reset the journey, guess success, or expose the full internal state machine to the user.

Automated multi-screen journey

Human onboarding must be a sequence of multiple focused screens orchestrated automatically. A single dense setup, diagnostics, or status screen is not an onboarding journey. The sequence is a versioned journey graph, not a fixed product tour: each user sees only the screens earned by their goals, answers, product state, entitlement, experiment assignment, and observed progress.

Each screen must:

• advance one user decision, understanding, or observable product outcome;
• have one dominant purpose and primary action;
• expose only the explanation and controls required at that point;
• provide Back, Skip, Not now, or Exit when the step is not mandatory;
• identify mandatory steps and explain why they cannot be skipped;
• define its entry conditions, completion evidence, failure state, analytics exposure, and allowed next screens;
• preserve answers and completed side effects when the user moves backward or resumes later.

A typical journey may include separate screens for the desired outcome, role and context, use-case priorities, environment detection, personalized product proof, just-in-time permissions, plan selection and paywall, first product action, first successful result, and next steps. This is a menu of possible nodes, not a requirement to show every node to every user.

The sequence engine must choose the next screen automatically from explicit rules and live evidence. Every decision must record a versioned journey_id, journey_version, current screen_id, selected next_screen_id, and a machine-readable reason code. Rules must be deterministic for the same declared inputs. If an adaptive model is used, its eligible inputs, bounded outputs, fallback route, version, and decision record must be reviewable; model failure must fall back to a safe deterministic sequence.

Automation may personalize explanation, ordering, examples, and optional offers. It must not silently widen permissions, change legal consent, manufacture entitlement, conceal price, or use protected or sensitive attributes to exploit a user.

Machine-readable journey contract

Every human onboarding publishes an immutable, versioned journey definition. The central service may distribute a reviewed definition, but the product must bundle a deterministic canonical definition that remains usable when the service, transport, or network is unavailable.

The definition contains at least:

Field	Contract
schema_version	Supported wire-contract version
product_id	Stable product identifier
journey_id	Stable product-scoped journey identifier
journey_version	Immutable version pinned for one attempt
entry_screen_id	Deterministic initial graph node
first_success_fact	Observable fact that fulfills the product promise
published_at	Publication timestamp
source_revision	Full source revision that owns product semantics
screens	Closed graph of reviewed product screens
analytics_contract	Versioned exposure, action, completion, and outcome events
experiment_contract	Control, variants, assignment, reward, guardrails, owner, and kill switch

Each screen declares screen_id, screen_kind, presentation keys, required state, entry conditions, completion evidence, allowed actions, transitions, and a safe fallback. A remote definition may select only a screen_kind registered in the product release. It must never name an arbitrary component class or contain executable code.

The condition language is closed to all, any, not, present, absent, eq, not_eq, contains, gt, gte, lt, and lte. Products must reject unknown operators, unknown fields, duplicate screen identifiers, missing targets, unsupported screen kinds, oversized definitions, and definitions whose identity differs from the requested product and journey.

For every transition, persist product_id, journey_id, journey_version, attempt_id, current_screen_id, selected_next_screen_id, reason_code, evidence_revision, decision time, and experiment and variant identifiers when present. The same definition, evidence revision, answers, entitlement, and assignment must yield the same route.

Assignment is not exposure. Record exposure only after the assigned presentation is rendered. Pin assignment and journey version for the entire attempt. Analytics failure must not block routing or the first product result.

Central authoring, analytics, and optimization do not own product semantics. The product repository owns the renderer registry, supported actions, live evidence adapter, canonical fallback, and definition of first success.

Reference platform responsibilities

The shared onboarding platform has one explicit control path:

1. Echo stores the product registry, immutable journey versions, proof assets, attempt progress, canonical events, deterministic routing decisions, and experiment assignments. Onboarding Studio is the authoring and publication surface; the funnel view is the operational analytics surface.
2. Stado exposes only the product-scoped bundle.read, experiments.assign, events.collect, and state.read operations granted to a named client. It does not own journey content or product credentials.
3. Shared runtimes validate the closed graph and content hash, pin one journey version and assignment to an attempt, persist progress, route from declared evidence, queue canonical events offline, and use the bundled canonical definition when central delivery is unavailable.
4. Product repositories render registered screen kinds, execute owned actions, adapt live product evidence, and emit first success only after the promised result is observed.
5. Probierz executes release-bound zero-state journeys and publishes redacted, signed evidence bundles. A journey is not release-ready merely because its definition was published.

The publication sequence is draft definition, reviewed immutable version, product-owned evidence capture, verified proof artifact, and release eligibility. Adaptive optimization may promote only an eligible published variant with sufficient evidence and passing guardrails. It must retain a control, honor the kill switch, and never override entitlement, consent, permissions, or the product's first-success condition.

Questions and declared intent

The journey must ask the user focused questions when the answers can change the sequence, product configuration, proof shown, or commercial offer. Ask directly rather than pretending to infer intent the product has not observed.

Useful question categories include:

• the outcome the user wants first;
• which capability or result they are most excited to achieve;
• role, use case, experience level, and team or organization context;
• current tools, supported environment, and relevant existing configuration;
• urgency, expected usage frequency, and the user's definition of first success;
• individual versus organization ownership and relevant purchasing context.

Each question must have a documented decision it informs. Optional personalization questions must be skippable. Explain why an answer is requested, allow the user to revise it, provide an inclusive answer set plus a neutral free-form or “not sure” route where appropriate, and never make sensitive disclosure a condition of ordinary product access.

Store answers under stable question and answer identifiers with schema version, source screen, timestamp, and journey version. Do not place credentials, secrets, unrestricted free text, or sensitive personal data in ordinary analytics events. Define retention, deletion, account-switching, and organization-switching behavior before collection.

Interest, excitement, and engagement signals

Track what appears to interest or excite the user through a combination of explicit self-report and observable behavior. Explicit answers such as “Which outcome are you most excited to achieve?” are the primary evidence of subjective preference. Clicks, active dwell time, demo interaction, repetition, skipping, backtracking, help requests, and conversion are behavioral proxies; never label them as the user's emotion or intention without direct confirmation.

At minimum, instrument:

• journey, experiment, variant, and screen exposure;
• answers selected, changed, skipped, or abandoned;
• primary and secondary actions;
• active time on screen, excluding background or inactive-window time;
• proof, example, demo, feature, and plan interactions;
• backward navigation, repeated screens, help, retry, and exit;
• paywall view, checkout start, checkout completion, entitlement observation, decline, and restore;
• first product action, first successful result, and the defined activation event.

Every event must use a documented schema containing pseudonymous subject scope, journey and screen versions, experiment and variant identifiers, sequence position, event name, timestamp, and relevant reason code. Event production must be idempotent where retries are possible. Analytics failure must not block the journey.

Personalized sequencing and conversion loop

The sequence engine must combine declared answers, live product state, prior completed steps, entitlement, experiment assignment, and permitted engagement signals to select the next useful screen. It must not optimize only for clicks or payment. The optimization contract must balance first product success, truthful paid conversion, time to value, completion, support burden, cancellation, refund, accessibility, safety, and user-reported usefulness.

Define separate funnel stages for:

1. onboarding started;
2. intent or desired outcome declared;
3. personalized proof or relevant capability engaged;
4. account and required environment ready;
5. paywall exposed;
6. checkout started;
7. checkout completed;
8. authoritative entitlement observed;
9. first product action completed;
10. first successful product outcome observed;
11. the product-specific retained-use milestone.

Product activation and revenue conversion are distinct outcomes and must not be collapsed into one metric. For every screen and sequence variant, report exposure, continuation, skip, abandonment, time to next stage, product activation, paywall conversion, entitlement conversion, first success, and declared guardrails. Use this evidence to revise questions, routing rules, screen content, and experiment variants through reviewed versions rather than silently mutating a live journey.

Paywall and commercial boundary

Every human onboarding must include a paywall. The paywall is a product and entitlement boundary, not a decorative pricing card or an unexpected terminal error.

Show it after the user understands the product outcome and before the first paid capability is activated. If payment is required before any useful result can be produced, the first screen must say so plainly.

The paywall must state:

• the selected plan or purchasable entitlement;
• price, billing period, currency, applicable trial, renewal behavior, and material tax handling;
• the concrete capabilities included and the meaningful limits or exclusions;
• whether the purchase belongs to a person, organization, workspace, device, or seat;
• when charging starts and what confirmation action creates the commitment;
• how to restore an existing entitlement, manage billing, cancel, and obtain the applicable refund or support policy;
• what remains usable when the user declines or closes the paywall.

Paywall state must be derived from the authoritative billing and entitlement source. A successful checkout is not sufficient until the resulting entitlement is observed. Relaunching, switching accounts or organizations, restoring a purchase, webhook delay, checkout cancellation, and billing-service failure must each have an explicit state and recovery route.

Do not use fake urgency, preselected paid consent, disguised close controls, misleading trials, obstructive cancellation, invented savings, or a different price at checkout. Never request payment details outside the approved payment provider or unlock a paid capability from a client-side flag alone.

A/B testing

Every human onboarding must support controlled A/B testing. Each onboarding experiment must ship with an explicit control, at least one approved variant, stable assignment, exposure recording, outcome attribution, guardrail metrics, and a kill switch.

Before implementation, record:

• the hypothesis and single primary decision the experiment is intended to inform;
• the eligible population, exclusion rules, assignment unit, traffic allocation, and experiment duration or stopping rule;
• the exact differences between control and each variant;
• the primary outcome, funnel events, time horizon, and guardrail metrics;
• the experiment and variant identifiers written to durable analytics;
• the minimum evidence required to promote, revise, or reject a variant;
• the owner authorized to stop the experiment and select the permanent experience.

Assignment must remain stable across relaunches and across every screen in the same journey. Exposure is recorded only after the assigned experience is actually rendered. Conversion must be attributed to the exposed variant rather than inferred from assignment alone. Analytics failure must not block onboarding or alter entitlement.

Variants may change sequencing, explanation, presentation, or an approved commercial offer. They must not weaken accessibility, safety, security claims, permission meaning, credential handling, legal consent, data retention, or recovery. Price and trial experiments require an approved commercial definition, must preserve the exact offer shown through checkout, and must never cause two users in the same organization or purchase context to receive contradictory binding terms.

Experiment results must be segmented for material differences such as platform, release, acquisition source, new versus returning user, and individual versus organization purchase where sample size permits. Stop or roll back a variant immediately when a guardrail regresses beyond its declared limit.

Failure guidance

For each onboarding step, document common failures and recovery:

• missing prerequisite;
• invalid configuration;
• insufficient permission;
• unavailable dependency;
• port or path conflict;
• unsupported platform;
• worker not running;
• state backend unreachable;
• external service or cloud outage.

Errors must state what failed, whether retrying can help, and the next corrective action. Avoid messages that expose internal stack traces without user guidance.

Safety rules

The onboarding path must:

• default to local, sandbox, dry-run, or report-only behavior where practical;
• avoid creating billable cloud resources without explicit confirmation;
• avoid destructive cleanup;
• avoid binding unauthenticated services to public interfaces;
• avoid collecting secrets before they are needed;
• avoid silently modifying shell profiles or system services;
• preserve existing user configuration.

Human and machine onboarding

If the product supports automation, define a separate machine onboarding contract. It must specify stable schemas, authentication, idempotency, error codes, and noninteractive configuration.

Do not force automation to parse decorative human output.

Prohibited patterns

Do not:

• assume the user has read the source code;
• require undocumented environment variables;
• make cloud credentials mandatory for a supported local path;
• present the full production configuration as the first task;
• hide required background services;
• claim success before the first product result exists;
• use a destructive command as a setup shortcut;
• depend on a maintainer-owned account, bucket, project, or secret;
• treat a full help listing as onboarding;
• force every user through a static linear sequence that ignores already satisfied requirements;
• hide the paid boundary until after the user has supplied payment details or attempted a paid action;
• treat checkout completion as entitlement proof;
• change experiment assignment during one journey or count assignment as exposure;
• ship an onboarding experiment without a hypothesis, guardrails, attribution, stop conditions, and an accountable owner;
• present one overloaded setup, diagnostics, or status screen as the entire human onboarding journey;
• show every possible screen to every user instead of routing from declared intent and live evidence;
• ask a question that does not change routing, configuration, proof, measurement, or an approved commercial decision;
• describe clicks, dwell time, or conversion as proof of emotion without explicit self-report;
• optimize sequencing only for engagement or payment while ignoring first success, cancellation, refund, safety, accessibility, or user-reported usefulness;
• personalize from protected or sensitive attributes, unrestricted free text, credentials, or secrets;
• choose a next screen without recording the journey version, decision, and reason;
• collapse product activation, checkout completion, entitlement observation, and retained use into one ambiguous conversion metric.

Completion gate

The onboarding stage is complete only when:

• the zero-state experience is intentionally defined;
• prerequisites and minimum configuration are explicit;
• installation resolves an immutable supported release;
• the first workflow reaches an observable product outcome;
• common failures have actionable recovery guidance;
• local or sandbox defaults are safe;
• cleanup and uninstall paths exist;
• dynamic states, transitions, resumption, cancellation, and contradictory-evidence handling are explicitly defined;
• the paywall, checkout, entitlement observation, restore, decline, cancellation, and billing-failure routes are complete;
• the A/B control, variants, stable assignment, exposure, attribution, primary outcome, guardrails, kill switch, and decision owner are defined;
• a versioned multi-screen journey graph defines each screen, entry condition, completion evidence, actions, failures, and allowed transitions;
• automated routing has deterministic rules, decision reason codes, a safe fallback, and auditable adaptive-model boundaries where applicable;
• every onboarding question has a documented routing, configuration, proof, measurement, or commercial purpose and a defined data lifecycle;
• explicit interest answers, behavioral proxy events, screen exposures, and analytics schemas are defined without claiming unobserved emotion;
• product activation, paywall exposure, checkout, entitlement, first success, and retained use are measured as distinct attributable funnel stages;
• core functionality can be implemented against a complete first-user journey rather than assumptions.