> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Release Process and Packaging

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * crates/palyra-cli/examples/run\_workflow\_regression.rs
  * crates/palyra-cli/src/commands/docs.rs
  * crates/palyra-cli/src/workflow\_regression.rs
  * crates/palyra-cli/tests/help\_snapshots/docs-help.txt
  * crates/palyra-cli/tests/workflow\_regression\_contract.rs
  * crates/palyra-common/src/runtime\_preview\.rs
  * infra/release/compat-hardening-readiness.json
  * infra/release/workflow-regression-matrix.json
  * scripts/release/common.ps1
  * scripts/release/install-desktop-package.ps1
  * scripts/release/install-headless-package.ps1
  * scripts/release/package-portable.ps1
  * scripts/release/uninstall-package.ps1
  * scripts/release/validate-portable-archive.ps1
  * scripts/test/check-release-cli-exposure-escaping.ps1
  * scripts/test/install-clean-desktop.ps1
  * scripts/test/run-release-smoke.ps1
  * scripts/test/uninstall-clean-desktop.ps1
</details>

The Palyra release process is a multi-stage pipeline designed to ensure artifact coherence, cross-platform compatibility, and runtime safety. It encompasses the generation of portable archives, desktop-specific installation logic, and a rigorous "smoke test" suite that validates the system's behavior in clean environments. The process is governed by a regression matrix that enforces consistency between the code, documentation, and release readiness criteria.

## Packaging Architecture

Palyra utilizes PowerShell and Bash scripts to orchestrate the packaging of binaries and assets into distribution-ready archives. The primary packaging logic resides in `scripts/release/package-portable.ps1`, which supports two main artifact kinds: `desktop` and `headless` [scripts/release/package-portable.ps1#1-16](http://scripts/release/package-portable.ps1#1-16).

### Portable Archive Structure

Archives are generated as ZIP files containing a specific "payload" layout required for the application to function in a portable or installed state.

| Component                       | Description                                       | Source                                   |
| :------------------------------ | :------------------------------------------------ | :--------------------------------------- |
| `palyra`                        | The primary CLI entry point.                      | `palyra-cli`                             |
| `palyrad`                       | The core gateway daemon.                          | `palyra-daemon`                          |
| `palyra-browserd`               | The browser automation service.                   | `palyra-browserd`                        |
| `palyra-desktop-control-center` | (Desktop only) The Tauri-based GUI supervisor.    | `apps/desktop`                           |
| `web/`                          | Bundled React dashboard assets.                   | `apps/web/dist`                          |
| `docs/help_snapshots/`          | Offline CLI help documentation.                   | `crates/palyra-cli/tests/help_snapshots` |
| `deployment/`                   | Generated deployment recipes (e.g., `single-vm`). | Generated via `palyra deployment recipe` |

The `package-portable.ps1` script validates the existence of all required binaries and assets before staging them [scripts/release/package-portable.ps1#40-59](http://scripts/release/package-portable.ps1#40-59). It also calculates SHA-256 hashes for all binary entries to ensure integrity [scripts/release/package-portable.ps1#74-79](http://scripts/release/package-portable.ps1#74-79).

### Data Flow: Packaging to Metadata

The following diagram illustrates how raw build artifacts are transformed into a versioned release bundle with associated metadata.

**Release Packaging Data Flow**

```mermaid theme={null}
graph TD
    subgraph "Build Phase"
        B1["cargo build --release"] --> Binaries["palyra, palyrad, browserd"]
        B2["vite build"] --> WebAssets["web/dist/"]
    end

    subgraph "Scripts Space (package-portable.ps1)"
        P1["Get-WorkspaceVersion"] --> V["Version String"]
        P2["Get-PlatformSlug"] --> S["Platform Slug"]
        Binaries --> CP["Copy-BinaryIntoPayload"]
        WebAssets --> CP
        V --> CP
        S --> CP

        CP --> Meta["install-metadata.json"]
        CP --> Zip["ZIP Archive"]
    end

    Meta --> Dist["target/release-artifacts/"]
    Zip --> Dist
```

Sources: [scripts/release/package-portable.ps1#24-37](http://scripts/release/package-portable.ps1#24-37), [scripts/release/package-portable.ps1#63-80](http://scripts/release/package-portable.ps1#63-80), [scripts/release/package-portable.ps1#116-126](http://scripts/release/package-portable.ps1#116-126)

## Installation and CLI Exposure

Palyra provides specialized installation scripts for different environments. These scripts manage binary placement, environment variables, and "CLI exposure"—the process of making the `palyra` command available in the user's shell.

### Desktop Installation

`scripts/release/install-desktop-package.ps1` handles the setup of the desktop bundle. It:

1. Extracts the archive to the specified `InstallRoot` [scripts/release/install-desktop-package.ps1#24-25](http://scripts/release/install-desktop-package.ps1#24-25).
2. Sets executable permissions on all binaries [scripts/release/install-desktop-package.ps1#30-32](http://scripts/release/install-desktop-package.ps1#30-32).
3. Configures "CLI Exposure" using `Install-PalyraCliExposure`, which may involve creating shims or updating the system `PATH` [scripts/release/install-desktop-package.ps1#42-47](http://scripts/release/install-desktop-package.ps1#42-47).
4. Performs an initial `setup` in `local` mode to initialize the configuration [scripts/release/install-desktop-package.ps1#58-65](http://scripts/release/install-desktop-package.ps1#58-65).

### Headless Installation

`scripts/release/install-headless-package.ps1` is tailored for server environments. In addition to standard binary setup, it can generate a `systemd` unit file for `palyrad` on Linux systems, ensuring the daemon persists across reboots [scripts/release/install-headless-package.ps1#90-114](http://scripts/release/install-headless-package.ps1#90-114).

### Uninstallation and Cleanup

The `scripts/release/uninstall-package.ps1` and `scripts/test/uninstall-clean-desktop.ps1` scripts provide a clean teardown. This includes stopping running processes, removing binary shims, and optionally deleting the `StateRoot` where runtime data (journals, memory) is stored [scripts/test/uninstall-clean-desktop.ps1#20-40](http://scripts/test/uninstall-clean-desktop.ps1#20-40), [scripts/test/uninstall-clean-desktop.ps1#168-185](http://scripts/test/uninstall-clean-desktop.ps1#168-185).

Sources: [scripts/release/install-desktop-package.ps1#1-127](http://scripts/release/install-desktop-package.ps1#1-127), [scripts/release/install-headless-package.ps1#1-141](http://scripts/release/install-headless-package.ps1#1-141), [scripts/test/uninstall-clean-desktop.ps1#1-190](http://scripts/test/uninstall-clean-desktop.ps1#1-190)

## Release Readiness and Smoke Tests

Before a release is finalized, it must pass a series of automated gates defined in the `infra/release/` directory.

### Release Smoke Test

The `scripts/test/run-release-smoke.ps1` script executes a battery of tests against a freshly installed package. It validates:

* **Command Resolution**: Ensures the `palyra` command resolves from the expected installation directory [scripts/test/run-release-smoke.ps1#53](http://scripts/test/run-release-smoke.ps1#53).
* **Help Consistency**: Iterates through all major CLI command groups to ensure they render help text without errors [scripts/test/run-release-smoke.ps1#55-74](http://scripts/test/run-release-smoke.ps1#55-74).
* **Deployment Workflows**: Exercises `preflight`, `recipe` generation, and `promotion-check` logic to ensure infrastructure-as-code features are functional [scripts/test/run-release-smoke.ps1#99-105](http://scripts/test/run-release-smoke.ps1#99-105).
* **Dry-run Operations**: Validates that `update` and `uninstall` dry-runs report correctly [scripts/test/run-release-smoke.ps1#107-120](http://scripts/test/run-release-smoke.ps1#107-120).

### Workflow Regression Matrix

The `infra/release/workflow-regression-matrix.json` defines the canonical "acceptance scenarios" that must pass for a release to be considered stable. It supports two profiles:

* **Fast**: A per-push baseline focusing on deterministic contract checks [infra/release/workflow-regression-matrix.json#6-27](http://infra/release/workflow-regression-matrix.json#6-27).
* **Full**: A nightly/pre-release profile that includes deeper runtime diagnostics and "chaos" scenarios [infra/release/workflow-regression-matrix.json#28-50](http://infra/release/workflow-regression-matrix.json#28-50).

### Code-to-Manifest Consistency

The `crates/palyra-cli/tests/workflow_regression_contract.rs` test ensures that the actual code implementation of runtime capabilities matches the definitions in the regression matrix [crates/palyra-cli/tests/workflow\_regression\_contract.rs#1-46](http://crates/palyra-cli/tests/workflow_regression_contract.rs#1-46). It validates that every `RuntimePreviewCapability` defined in `palyra-common` is represented in the release readiness checklist [crates/palyra-cli/tests/workflow\_regression\_contract.rs#87-104](http://crates/palyra-cli/tests/workflow_regression_contract.rs#87-104).

**Workflow Regression Entity Map**

```mermaid theme={null}
graph LR
    subgraph "Code Entities (palyra-common)"
        RPC["RuntimePreviewCapability"]
        RPM["RuntimePreviewMode"]
    end

    subgraph "Manifest Space (infra/release/)"
        Matrix["workflow-regression-matrix.json"]
        Hardening["compat-hardening-readiness.json"]
    end

    subgraph "Test Logic (palyra-cli/tests/)"
        Contract["workflow_regression_contract.rs"]
    end

    RPC --> Contract
    Matrix --> Contract
    Hardening --> Contract
    Contract -- "Asserts Consistency" --> Matrix
```

Sources: [crates/palyra-common/src/runtime\_preview.rs#73-83](http://crates/palyra-common/src/runtime_preview.rs#73-83), [infra/release/workflow-regression-matrix.json#1-121](http://infra/release/workflow-regression-matrix.json#1-121), [crates/palyra-cli/tests/workflow\_regression\_contract.rs#46-52](http://crates/palyra-cli/tests/workflow_regression_contract.rs#46-52)

## Deployment Promotion and Rollout Gates

Palyra uses "Compatibility Hardening Readiness" checks to gate the rollout of new features, particularly those in "Runtime Preview."

### Rollout Controls

The `infra/release/compat-hardening-readiness.json` file tracks the state of specific subsystems (e.g., `retrieval_dual_path`, `networked_worker_preview_rollout`). These controls ensure that features remain "fail-closed" or disabled by default until they meet the required evidence criteria [infra/release/compat-hardening-readiness.json#6-37](http://infra/release/compat-hardening-readiness.json#6-37).

### Evidence Requirements

Promotion to a stable release requires evidence from multiple sources:

1. **Workflow Regression (Fast/Full)**: Must pass specific scenarios like `queued_input_lifecycle_contract` or `dual_path_retrieval_runtime_diagnostics` [infra/release/compat-hardening-readiness.json#75-165](http://infra/release/compat-hardening-readiness.json#75-165).
2. **Migration Tracks**: Validates that runtime contracts and config schemas have been properly adopted before widening the rollout [infra/release/compat-hardening-readiness.json#38-57](http://infra/release/compat-hardening-readiness.json#38-57).

### Known Limitations

The readiness checklist explicitly documents limitations, such as the `networked_worker_execution_remains_preview_only` state, which prevents accidental promotion of unfinished distributed execution features [infra/release/compat-hardening-readiness.json#58-74](http://infra/release/compat-hardening-readiness.json#58-74).

Sources: [infra/release/compat-hardening-readiness.json#1-165](http://infra/release/compat-hardening-readiness.json#1-165), [crates/palyra-cli/src/workflow\_regression.rs#1-100](http://crates/palyra-cli/src/workflow_regression.rs#1-100)