DESKTOP_SHELL

Desktop shell

AncestryLLM 0.5.0 is a bounded, offline Electron control shell. It does not move the genealogy-capable CLI or console into the desktop application and it does not introduce a second command or domain layer.

Supported surface

The supported desktop destinations are deliberately small:

• Home identifies the application, its offline posture, and sanitized startup and capability state. The capability summary reports only whether the bundled local runtime is ready; it does not expose accounts, providers, credentials, genealogy data, or cloud consent.
• Diagnostics shows stable, sanitized lifecycle state and offers bounded retry or restart recovery.
• Settings stores local visual preferences only: color scheme and reduced motion. The internal onboarding flag is not a user-facing setting.

These destinations must remain usable with keyboard navigation and assistive technology, and in loading, empty, degraded, failure, narrow-window, and zoomed layouts.

The 0.5.0 shell has no genealogy, file or folder, GEDCOM or RootsMagic, job, chat, provider or credential, cloud or account, domain-dispatch, updater, or background-channel surface. Those exclusions apply to navigation and hidden controls as well as visible content.

Offline and process boundary

Electron starts the packaged sidecar on a private, ephemeral loopback endpoint with provider none; the Electron main process is the sole authenticated client. The preload bridge exposes exactly these six methods:

• getAppInfo
• getStartupDiagnostics
• getCapabilities
• retrySidecar
• getPreferences
• updatePreferences

The renderer receives no Node.js, Electron, network, filesystem, keyring, provider, database, shell, or arbitrary-path access. It must never receive the sidecar port, bearer token, endpoint, executable path, preference-file path, stderr, raw sidecar or bridge errors, or stack traces. See the packaged sidecar contract and desktop ADR for the underlying process and architecture controls.

Installation and updates

The supported 0.5.0 targets are macOS 15 and 26 on arm64 and x64, Windows 11 on x64, and Ubuntu 24.04 on x64. A supported release is a manually installed, signed installer that has passed the target-specific release and packaged assurance gates in the release runbook.

Unsigned CI artifacts and unpacked development builds are verification inputs, not supported releases or evidence of successful signing, notarization, or installation. Version 0.5.0 has no updater, update feed, background update channel, or staged rollout. Updating and rolling back mean manually installing the appropriate complete, signed installer.

Sanitized diagnostics and recovery

When the bundled runtime is unavailable, keep recovery bounded and generic:

1. Open Diagnostics and request one bounded retry.
2. If the failure remains, close and reopen the application.
3. Reinstall the same supported, target-matched signed build when local files may be incomplete.
4. When reporting a problem, include only the application version, operating-system target, and stable diagnostic code shown by the shell. Do not include local paths, environment values, process details, genealogy data, or raw error output.

Generic recovery text is part of the security boundary: the capability summary and diagnostics must not turn private runtime state into renderer-visible details.