1. Doctor Diagnostic Pipeline
Thedoctor command is the primary diagnostic and recovery tool for Palyra. It evaluates the health of the local installation, configuration validity, and connectivity to remote services.
Core Components
DoctorReport: A structured collection of diagnostic checks covering environment variables, file permissions, configuration syntax, and network reachability crates/palyra-cli/src/commands/doctor/recovery.rs#81-83.DoctorRepairStep: A discrete unit of remediation. Each step includes a title, description, impact analysis, and whether it requires a--forceflag to apply crates/palyra-cli/src/commands/doctor/recovery.rs#105-118.DoctorRecoveryManifest: When repairs are applied, the system generates a manifest tracking all changes (backups, SHA256 hashes, and file paths) to allow for safe rollbacks crates/palyra-cli/src/commands/doctor/recovery.rs#141-169.
Diagnostic Flow
The doctor pipeline operates in several modes:Diagnostics (read-only), RepairPreview, and RepairApply crates/palyra-cli/src/commands/doctor/recovery.rs#66-74. It checks for:
- Config Integrity: Validates
palyra.tomlversioning and schema crates/palyra-cli/src/commands/doctor/recovery.rs#182-191. - Auth Registries: Ensures
auth_profiles.tomlis not corrupted and root keys are normalized crates/palyra-cli/src/commands/doctor/recovery.rs#195-205. - Sandbox/Browser: Verifies encryption keys for
browserdand existence of state directories crates/palyra-cli/src/commands/doctor/recovery.rs#192-194.
Data Flow: Doctor Recovery
Title: Doctor Diagnostic and Repair Lifecycle Sources: crates/palyra-cli/src/commands/doctor.rs#8-10, crates/palyra-cli/src/commands/doctor/recovery.rs#76-83, crates/palyra-cli/src/commands/doctor/recovery.rs#105-118, crates/palyra-cli/src/commands/doctor/recovery.rs#141-1552. Setup and Onboarding Wizard
The Onboarding Wizard handles the initial bootstrap of a Palyra installation. It is invoked viapalyra setup --wizard or palyra onboarding wizard crates/palyra-cli/src/commands/operator_wizard.rs#240-247.
Wizard Engine (WizardBackend)
The system uses a generic WizardBackend trait to support different interaction modes:
InteractiveWizardBackend: Uses standard I/O to prompt the user for input, choices, and confirmations crates/palyra-cli/src/commands/operator_wizard.rs#10-13.NonInteractiveWizardBackend: Resolves steps automatically using command-line arguments and defaults, failing if a required value is missing crates/palyra-cli/src/commands/operator_wizard.rs#10-13.
Onboarding Flows
The wizard supports three primary flows defined inWizardFlowKind crates/palyra-cli/src/commands/operator_wizard.rs#65-69:
- Quickstart: Minimal prompts, optimized for local setup with OpenAI or Anthropic crates/palyra-cli/src/commands/operator_wizard.rs#74-74.
- Manual: Detailed configuration of ports, TLS paths, and specific bind profiles (e.g.,
public-tls) crates/palyra-cli/src/commands/operator_wizard.rs#75-75. - Remote: Configures the local CLI to communicate with an existing remote daemon crates/palyra-cli/src/commands/operator_wizard.rs#76-76.
Implementation: Wizard Steps
Title: Onboarding Wizard Logic Flow Sources: crates/palyra-cli/src/commands/wizard.rs#29-39, crates/palyra-cli/src/commands/wizard.rs#98-105, crates/palyra-cli/src/commands/operator_wizard.rs#169-195, crates/palyra-cli/src/commands/operator_wizard.rs#198-2163. Configuration and Migration
Theconfigure command allows users to modify an existing installation safely. It reuses the same underlying wizard engine as the onboarding flow but targets specific sections of the configuration crates/palyra-cli/src/commands/operator_wizard.rs#219-226.
Configuration Sections
Users can target specific sections for reconfiguration:workspace: Workspace root and default models.auth-model: Provider keys and model selection.gateway: Ports and binding profiles.channels: Integration settings for Discord/Slack.
Migration Safety
When the wizard orconfigure command modifies a file, it implements a backup rotation strategy. It maintains up to 5 backups (defined by CONFIGURE_BACKUPS) of palyra.toml before applying changes crates/palyra-cli/src/commands/operator_wizard.rs#17-17.
Summary and Health Check
At the end of a setup or configuration run, the system performs a post-flight health check and emits anOnboardingSummary (for setup) or ConfigureSummary (for configuration) crates/palyra-cli/src/commands/operator_wizard.rs#198-216, crates/palyra-cli/src/commands/operator_wizard.rs#229-238.
| Field | Description |
|---|---|
status | complete or failed |
config_path | Absolute path to the written palyra.toml |
health_status | Result of post-setup diagnostics (ConfigReady, RemoteVerified, etc.) |
risk_events | List of security risks acknowledged by the user (e.g., public binding) |
restart_required | Boolean indicating if the daemon needs a restart to apply changes |