How to Sync Onboarding and Config Across Your Apps

I have spent too much time trying to keep configuration logic consistent across different platforms. It is a headache when the CLI behaves differently than the desktop app or the web dashboard. Usually, you end up rewriting the same validation and UI logic multiple times, which leads to bugs and a disjointed experience for users.

I prefer using a shared protocol to handle this. By using a single wizard engine and a central config schema, you can ensure that every interface—whether it is a terminal or a browser—stays perfectly aligned.

What You’ll Need

To get started with this protocol, you will work with these core components:

• Wizard Engine: This manages the shared session, prompts, and onboarding state.
• Gateway RPC: The interface that exposes wizard and config schema endpoints.
• UI Hints: Metadata used to render forms correctly in the Web UI.
• JSON Schema: The underlying structure for your configuration.

Quick Start

I recommend using the Gateway RPC to manage your onboarding flow. Here is the 5-minute path to getting a session running and moving through steps.

1. Start the Wizard

First, call wizard.start to initialize your session. You can define the mode and workspace.

// wizard.start params
{
  "mode": "local",
  "workspace": "my-project-path"
}

2. Progress through Steps

Use the sessionId from the start response to send answers. This moves the user to the next part of the flow.

// wizard.next params
{
  "sessionId": "session-id-from-start",
  "answer": {
    "stepId": "database-selection",
    "value": "postgresql"
  }
}

3. Check Status or Cancel

If you need to verify where the user is or stop the process, use these calls:

// wizard.status params
{
  "sessionId": "session-id-abc"
}

// wizard.cancel params
{
  "sessionId": "session-id-abc"
}

4. Fetch the Config Schema

To render your configuration forms, pull the schema and UI hints.

// config.schema params
{}

The response gives you the full schema and uiHints needed to build your UI.

Troubleshooting

If you run into issues while implementing the protocol, check these two common scenarios mentioned in the documentation:

• UI Rendering Issues: If you encounter unsupported schema nodes, the system is designed to fall back to a raw JSON editor.
• Sensitive Data Exposure: Sensitive fields are rendered as password inputs. Note that there is no redaction layer, so handle these fields carefully.

If the wizard stops responding, check the error field in the Wizard response object: { sessionId, done, step, status, error }.

AI Setup Assistant

What’s Next

• Check the Gateway RPC protocol refactors.
• Review the UI Hints metadata for advanced field grouping.