1. Onboarding & Setup Wizard
The onboarding system is designed to transition a fresh installation into a fully configured environment. It supports multiple deployment modes (Local vs. Remote) and interaction styles (Interactive TUI vs. Headless CLI).1.1 Wizard Engine Architecture
The wizard is built on a generic backend-agnostic session manager. This allows the same logic to drive both the terminal-based interactive experience and automated CI/CD flows.WizardBackend: A trait defining how steps are executed and how validation errors are handled crates/palyra-cli/src/commands/wizard.rs#147-153.InteractiveWizardBackend: Implements the TUI prompts usinginquirefor selection, confirmation, and text input crates/palyra-cli/src/commands/operator_wizard.rs#11-13.NonInteractiveWizardBackend: Consumes pre-provided arguments and fails if a required input is missing crates/palyra-cli/src/commands/operator_wizard.rs#11-13.WizardStep: Defines the metadata for a single UI interaction, including its type (Select, Text, Confirm), default values, and sensitivity crates/palyra-cli/src/commands/wizard.rs#29-39.
1.2 Flow Logic and Configuration
Therun_setup_wizard function orchestrates the sequence of steps based on the OnboardingFlowArg crates/palyra-cli/src/commands/operator_wizard.rs#240-246.
| Flow | Description | Code Entity |
|---|---|---|
| Quickstart | Minimal prompts, uses defaults for models and ports. | WizardFlowKind::Quickstart crates/palyra-cli/src/commands/operator_wizard.rs#66-66 |
| Manual | Full control over model providers, ports, and storage paths. | WizardFlowKind::Manual crates/palyra-cli/src/commands/operator_wizard.rs#67-67 |
| Remote | Configures a local client to connect to a remote palyrad instance. | WizardFlowKind::Remote crates/palyra-cli/src/commands/operator_wizard.rs#68-68 |
1.3 Natural Language to Code Mapping: Setup
The following diagram maps setup concepts to the implementation structures inpalyra-cli.
Setup Entity Mapping
Sources: crates/palyra-cli/src/commands/operator_wizard.rs#23-30, crates/palyra-cli/src/commands/operator_wizard.rs#151-157, crates/palyra-cli/src/commands/operator_wizard.rs#169-195, crates/palyra-cli/src/commands/wizard.rs#155-157
2. The Doctor Diagnostic Pipeline
Thedoctor command family provides diagnostics, repair capabilities, and support bundle generation. It is the primary tool for troubleshooting node failures, corrupted configurations, or connectivity issues.
2.1 Diagnostic Checks & Repairs
The system performs a series of checks and can optionally apply “Repair Steps” crates/palyra-cli/src/commands/doctor/recovery.rs#105-118.DoctorReport: The result of a diagnostic run, containing identified issues and their severity crates/palyra-cli/src/commands/doctor/recovery.rs#77-83.DoctorRepairStep: A specific remediation action (e.g.,InitializeMissingConfig,NormalizeAuthRegistry,BackfillAccessRegistry) crates/palyra-cli/src/commands/doctor/recovery.rs#179-236.- Rollback Mechanism: Every repair operation that modifies the filesystem creates a backup. Users can revert these changes using the
--rollback-run <ID>flag crates/palyra-cli/src/commands/doctor/recovery.rs#56-56.
2.2 Support Bundles
For remote troubleshooting, thedoctor can generate a “Support Bundle”. This is a redacted snapshot of the system state, including:
- CLI and Auth profiles (redacted).
- Routine definitions and run metadata.
- Node runtime state and access registries.
- Browser daemon (
palyra-browserd) profile metadata.
build_doctor_support_bundle_value crates/palyra-cli/src/commands/doctor/recovery.rs#5-5.
2.3 Data Flow: Diagnostic to Repair
The diagnostic pipeline follows a strict Plan-then-Apply pattern to prevent accidental data loss. Doctor Execution Pipeline Sources: crates/palyra-cli/src/commands/doctor/recovery.rs#48-57, crates/palyra-cli/src/commands/doctor/recovery.rs#60-64, crates/palyra-cli/src/commands/doctor/recovery.rs#141-155, crates/palyra-cli/src/commands/doctor/recovery.rs#172-1753. Configuration Management
Thepalyra configure command allows for safe, incremental updates to an existing installation. It reuses the onboarding wizard logic but limits the scope to specific “sections”.
3.1 Configuration Sections
Users can target specific subsystems for reconfiguration crates/palyra-cli/tests/help_snapshots/configure-help.txt#8-9:workspace: Root paths and directory structures.auth-model: API keys and model provider settings.gateway: Ports, binding profiles, and TLS settings.channels: Connector settings for Discord, Slack, etc.skills: Skill trust stores and installation directories.
3.2 Change Detection
Whenpalyra configure is run, the system generates a ConfigureSummary crates/palyra-cli/src/commands/operator_wizard.rs#229-238. This summary tracks:
changed_sections: Which parts of the config were modified.restart_required: Whether thepalyraddaemon needs a restart to apply the changes.section_changes: A detailed diff of values before and after the operation crates/palyra-cli/src/commands/operator_wizard.rs#219-226.
4. Skills Management & Inventory
While part of theskills command family, the setup and diagnostic tools frequently interact with the skills inventory to ensure the node is ready for agent execution.
4.1 Inventory Snapshots
TheOnboardingSummary includes a SkillsInventorySnapshot crates/palyra-cli/src/commands/operator_wizard.rs#215-216. This ensures that after a setup or configuration change, the operator knows exactly which skills are available and their trust status.
4.2 Diagnostic Integration
Thedoctor checks for:
- Missing skill artifacts in the managed directory.
- Mismatched trust store integrity hashes.
- Expired or invalid skill signatures.
SkillCheckResult structures during the diagnostic phase crates/palyra-cli/src/output/skills.rs#85-89.
Sources: crates/palyra-cli/src/commands/skills.rs#1-4, crates/palyra-cli/src/output/skills.rs#25-29, crates/palyra-cli/src/output/skills.rs#101-113