Support and Diagnostics

Audience: preview users and support
Status: Preview

Use diagnostics output rather than screenshots when possible. The support path is designed to identify install, runtime, license, cache, and workflow failures from structured data.

SDK diagnostics

Run:

ophiolite doctor

Include the full JSON output in support requests. Each check includes:

• name
• status
• category
• code
• message
• details
• remediation when available

Treat fail checks as install blockers. Treat warn checks as usable preview states unless the warning blocks the workflow you are trying to run.

When OPHIOLITE_COMMERCIAL_SERVICE_URL or OPHIOLITE_COMMERCIAL_SERVICE_URI is configured, doctor also includes an account_service check. That check reports whether the configured account service can be reached and whether it exposes an active ophiolite-sdk-developer entitlement. Without a configured service URL, doctor omits this check and only reports local certificate state.

License diagnostics

Run:

ophiolite auth status

The preview build supports local certificate inspection/import and verifies preview-2026-05 certificates with a built-in public key. In Workbench, use the license status dialog’s Install license… action to choose a signed license.json; in the SDK/CLI, use ophiolite auth import <license_json_path>. It can also smoke the account-service contract with:

$env:OPHIOLITE_COMMERCIAL_SERVICE_URL = "http://127.0.0.1:8787"
$env:OPHIOLITE_COMMERCIAL_SERVICE_SCENARIO = "paid-sdk-developer"
ophiolite auth login

The mock-service login path does not cache the mock certificate, so a missing local license is expected until a signed preview certificate or production commercial activation is available.

For imported certificates, include the verification_status, verification_key_source, and key_id fields from ophiolite auth status.

Workbench diagnostics

In Ophiolite Workbench, use Help -> Export Diagnostics… or the Diagnostics action in the status bar.

After export, Workbench shows the bundle path and the status bar offers a Reveal action for opening the exported zip in the system file browser.

License status surface

The status bar shows a compact license indicator next to the diagnostics action. Click it (or run License: Show status from the command palette) to open a details dialog with account, plan, license ID, expiry date, offline-use date, and verification source when available. The dialog also offers Install license… for signed preview certificates, Read activation policy, which opens the activation policy in the system browser, and Export diagnostics. The dialog only reports state and routes to existing actions; it does not gate workflow execution.

The indicator labels map to commercial state as follows:

Label	Meaning
Licensed preview	Local certificate or configured account entitlement is verified for preview use
Free preview	No local certificate or paid Workbench entitlement is active
Activation issue	A certificate or account entitlement exists but needs attention, is invalid, or has expired
Preview build	Local development build with no certificate; paid gates are not enforced

If the desktop UI cannot launch, advanced users can create the same structured support zip from the desktop binary:

ophiolite-workbench-desktop diagnostics export --headless --output workbench-diagnostics.zip

The exported bundle contains:

• app name, identifier, version, and Tauri version
• OS version, architecture, executable path state, log directory state, temporary directory state, and available parallelism
• runtime, IPC, workflow script, workflow recipe, and workflow report version metadata
• diagnostics session id and start time
• verbose diagnostics setting
• preview commercial activation state
• session events
• session log when available

By default, sensitive paths are redacted from structured metadata. Workbench keeps third-party runtime logging quiet by default, but the session log can still contain operational context and file names from the active workflow, so review it before sharing outside your organization.

Support request checklist

Include:

• SDK or Workbench version
• OS and architecture
• exact command or UI action that failed
• ophiolite doctor JSON for SDK issues
• Workbench diagnostics bundle for desktop issues
• whether the issue happens on the bundled sample path
• whether a license certificate is configured
• any local workaround already tried

Do not include proprietary data files unless support explicitly asks for a minimized reproduction.

Next: Troubleshooting and Known Issues