native-packages 0.6.0 → 0.7.0

data/docs/_reference/commands.md

@@ -0,0 +1,206 @@
+---
+title: Command reference
+description: Look up native-packages commands, options, and examples for building, publishing, and managing recipes.
+nav_order: 2
+---
+
+# Command reference
+
+Run commands from your application's directory. To select another configuration:
+
+```sh
+native-packages --config packaging/native-packages.yaml COMMAND
+```
+
+Use `native-packages --help` for a summary and `native-packages --version` for
+the installed tool version. The examples below use app version `1.2.3`.
+
+## init
+
+Create `native-packages.yaml`:
+
+```sh
+native-packages init
+native-packages init --interactive
+native-packages init --name hello --input dist/hello.tar.gz --formats deb,rpm
+```
+
+The default is a Linux amd64 template. Setup uses available Cargo and Git
+metadata. Review the inputs, library type, dependencies, and metadata before
+building. Existing configuration is never overwritten. Interactive setup
+requires a terminal and is unavailable in CI.
+
+## validate
+
+```sh
+native-packages validate
+```
+
+Validate the configuration and render templates with placeholder values to
+catch unknown tokens. This does not require actual build inputs or run hooks.
+
+## doctor
+
+```sh
+native-packages doctor
+native-packages doctor --target linux-amd64 --format deb
+native-packages doctor --target macos-arm64 --defer-recipes
+native-packages doctor --release v1.2.3
+```
+
+Check configuration and required tools for selected targets. Repeat `--target`
+and `--format` for several selections. `--defer-recipes` omits recipe tools;
+`--release` also checks for the download tool. Actual input and package checks
+happen during `build`.
+
+## build
+
+```sh
+native-packages build --version 1.2.3
+native-packages build --release v1.2.3
+```
+
+| Option | Effect |
+| --- | --- |
+| `--version VERSION` | Set app version and use local inputs, unless `--release` is also present. |
+| `--release TAG` | Download checked release inputs and use the tag's version. |
+| `--target ID` | Select a target; repeat for several. |
+| `--format FORMAT` | Select an output format; repeat for several. |
+| `--output DIRECTORY` | Choose a new output directory. Default: `dist/packages/<version>`. |
+| `--dry-run` | Print the plan without downloading, building, or executing hooks. |
+| `--defer-recipes` | Build packages without acquiring global recipe assets or rendering templates. |
+
+With neither version option, an exact supported release tag must exist at
+`HEAD`. Supplying both requires matching versions. See
+[Building packages](../_guides/building-packages.md).
+
+## aggregate
+
+Combine build directories into a new output:
+
+```sh
+native-packages aggregate dist/linux dist/macos dist/windows --output dist/complete
+```
+
+`--output` is required. All inputs must have matching configuration, version,
+and timestamp. The result must include every configured target and format.
+
+For inputs made with `build --defer-recipes`, add `--finalize-recipes` to
+render recipes using completed package hashes and remaining local assets.
+See [Building across platforms](../_guides/multi-platform.md).
+
+## publish a build
+
+```sh
+native-packages publish --from dist/packages/1.2.3 --to github
+native-packages publish --from dist/linux --to github --target linux-amd64
+```
+
+`--from` selects the build directory; `--to` lists destinations separated by
+commas. `github` uploads release assets. Other names select entries or groups
+in `repositories`.
+
+The build must be complete and its recorded files unmodified. Repeated
+`--target` options require exactly those targets, with all their formats.
+Without target selection, all configured targets are required. There is no
+publication `--format` or `--dry-run` option.
+
+See [Publishing a release](../_guides/publishing.md) for release setup and
+upload behavior.
+
+## Manage downstream recipes
+
+| Command | Effect |
+| --- | --- |
+| `repositories` | List configured downstream destinations. |
+| `stage TARGET DIRECTORY` | Stage generated recipes in the destination's local checkout. |
+| `diff TARGET` | Show the staged changes. |
+| `publish TARGET` | Commit and publish the staged update. |
+| `status [TARGET]` | Query downstream versions and open requests; defaults to all. |
+
+Here, `TARGET` means a repository destination or group, such as `aur`. It is
+different from a build target such as `linux-amd64`.
+
+For example:
+
+```sh
+native-packages stage aur dist/packages/1.2.3/recipes
+native-packages diff aur
+native-packages publish aur
+native-packages status aur --offline --json
+```
+
+`status --offline` reads cached information; `--json` prints structured output.
+Status exits unsuccessfully when a remote or request check fails.
+
+For GitHub PR or GitLab MR destinations, `publish` requires `--body-file FILE`
+with the reviewed submission description. It can also be used with
+`publish --from ... --to DESTINATION`. Publish submission destinations
+individually. See [Distribution recipes](../_guides/distribution-recipes.md).
+
+## notarize-macos
+
+```sh
+native-packages notarize-macos portable-input --output signed/hello
+```
+
+Copy a prepared macOS directory and, when Apple credentials are configured,
+sign and notarize the copy. `--output` is required, must be new, and must be
+outside the input. This command needs no project configuration. See
+[Apple signing and notarization](../_guides/apple-notarization.md).
+
+## Release checksums and signatures
+
+```sh
+native-packages release-checksums dist/release --output dist/release/checksums.txt
+native-packages sign-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex
+native-packages verify-checksums dist/release/checksums.txt --public-key assets/update-public-key.hex
+```
+
+These commands need no project configuration. Generation requires a nonempty,
+flat directory of regular files and a new output file in that directory.
+Signing checks every listed artifact before writing a new `checksums.txt.sig`.
+Verification requires both a valid signature and matching artifact hashes.
+
+The signing key comes from `NATIVE_PACKAGES_SIGNING_KEY`, or the environment
+variable named by `--key-env VARIABLE`. Pass only the variable's name on the
+command line, never its secret value. The public-key file contains 64 hex digits.
+See [Release signatures and attestations](../_guides/release-signing.md).
+
+## migrate
+
+```sh
+native-packages migrate --dry-run
+native-packages migrate
+```
+
+Preview or create a single configuration from the legacy `packaging/project.yml`
+setup. Existing packaging files are preserved.
+
+## check-version
+
+```sh
+native-packages check-version v1.2.3
+```
+
+Validate a stable tag and, when `version_file` is configured, compare it with
+the application's Cargo manifest version. Set `version_section` for workspace
+manifests.
+
+## Select an installed tool version
+
+If several gem versions are installed, RubyGems lets you select the one required
+by the configuration:
+
+```sh
+native-packages _0.7.0_ build --version 1.2.3
+```
+
+Bundler also works if you prefer to manage the gem in a Gemfile.
+
+## Legacy commands
+
+`prepare`, `check`, `artifacts`, `publish-release`, and `publish-aur` remain
+available for older projects. Their original workflow is documented in the
+[legacy guide](https://github.com/crmne/native-packages/blob/main/docs/legacy.md).
+Use `build` and `publish --from` for new configurations.

data/docs/_reference/configuration.md

@@ -0,0 +1,323 @@
+---
+title: Configuration reference
+description: All native-packages configuration fields, target options, hooks, tokens, and downstream repository settings.
+nav_order: 1
+---
+
+# Configuration reference
+
+For a first configuration, follow [Getting started](../_guides/getting-started.md).
+This page is for looking up individual settings.
+
+## File location
+
+Use `native-packages.yaml` or `native-packages.yml` in your working directory.
+To choose another file:
+
+```sh
+native-packages --config packaging/native-packages.yaml build --version 1.2.3
+```
+
+Configuration paths and hooks resolve from that file's directory. Keep only
+one of the auto-discovered filenames, or use `--config` to select one.
+The configuration is YAML data; it does not evaluate Ruby or general template
+expressions. Use the replacement values listed below.
+
+## Top-level fields
+
+| Field | Purpose |
+| --- | --- |
+| `schema` | Required. Set to `1`. |
+| `tool.version` | Required. Exact native-packages version, such as `'0.7.0'`. |
+| `tool.nfpm` | Required. Set to `'2.47.0'`, including in native-only configurations. |
+| `nfpm` | Shared package metadata and installed-file mappings, or a relative YAML filename. Requires `name`. |
+| `targets` | Required. Named build targets; use `{}` for recipe-only projects. |
+| `release` | GitHub repository, checksum filename, and prerelease opt-in. |
+| `assets` | Additional files used by recipe templates. Defaults to `{}`. |
+| `templates` | Generated recipe paths mapped to source template paths. Defaults to `{}`. |
+| `repositories` | Downstream publication destinations. Defaults to `{}`. |
+| `libraries` | Additional shared-library dependency mappings for DEB/RPM. |
+| `revisions` | Package revision numbers by app version and recipe path. |
+| `version_file` | Cargo manifest checked by `check-version`. |
+| `version_section` | Cargo section to check; defaults to `package`. |
+
+Quote tool versions so they remain strings. A version mismatch reports the
+command needed to install and select the configured gem.
+
+## Package metadata
+
+`nfpm` is named after the helper that writes Linux packages and MSIX files.
+It holds the package's metadata, files, dependencies, and package-manager
+settings. Native DMG and Inno targets also read the shared metadata.
+
+Every target needs nonempty `maintainer`, `description`, and `license` values.
+Non-native targets need a `contents` list. The shared package name may contain
+letters, digits, dots, underscores, and hyphens, starting with a letter or digit.
+
+```yaml
+nfpm:
+  name: hello
+  description: A small greeting application
+  maintainer: Your Name <you@example.com>
+  license: MIT
+  contents:
+    - src: '@PAYLOAD@/hello'
+      dst: /usr/bin/hello
+      file_info:
+        mode: 0755
+```
+
+You can move that mapping to a file and use `nfpm: packaging/package.yml`.
+A target can supply an `nfpm` mapping or filename to override shared values.
+Maps merge recursively; lists replace in full.
+
+The package name, version, platform, and architecture come from the shared
+name, build version, and target. Avoid conflicting declarations under `nfpm`.
+Format-specific architecture names belong under sections such as `deb.arch`.
+For additional metadata, scripts, and format overrides, see the
+[nFPM configuration reference](https://nfpm.goreleaser.com/docs/configuration/).
+
+## Targets
+
+Each key under `targets` is an ID such as `linux-amd64`. IDs use lowercase
+letters, digits, and hyphens, starting with a letter or digit.
+
+| Target field | Purpose |
+| --- | --- |
+| `platform` | Required: `linux`, `macos`, or `windows`. |
+| `arch` | Required. Architecture, commonly `amd64` or `arm64`. macOS also supports `universal`. |
+| `formats` | Required nonempty list of output formats, without duplicates. |
+| `kind` | `binary` (default), `data`, or `source`. |
+| `libc` | Required for Linux binary targets: `glibc`, `musl`, or `static`. |
+| `abi` | Required for IPK: a label identifying the device/distribution baseline. |
+| `input` | Required. Local file, directory, or release asset to package. |
+| `nfpm` | Package metadata overrides for this target. |
+| `compiler_target` | Optional value for `@TARGET@`; otherwise it is the target ID. |
+| `before_build` | Command arguments run before copying a local input. |
+| `after_package` | Command arguments run on each package before its hash is recorded. |
+| `native` | Required for DMG/Inno. Contains `command` and `output`. |
+
+Formats are `deb`, `rpm`, `archlinux`, `apk`, `ipk`, `srpm`, `msix`, `dmg`,
+and `inno`. See [Supported platforms](platforms.md) for their requirements.
+
+Windows targets select only `[msix]` or `[inno]`; macOS targets select `[dmg]`.
+DMG and Inno each require a separate binary target. SRPM requires a separate
+`kind: source` target with only `[srpm]`.
+
+### Inputs
+
+| Input field | Purpose |
+| --- | --- |
+| `local` | Path used by local builds. |
+| `release_asset` | Filename used by `build --release`. |
+| `url` | Optional download URL overriding the default GitHub release URL. |
+| `kind` | `archive` (default), `directory`, or `file`. |
+
+Declare at least `local` or `release_asset`, and supply the field needed for
+your chosen build mode. Native targets require `kind: directory` and `local`.
+Binary release inputs always need a matching published checksum.
+
+Regular package inputs reject symbolic links. Use explicit installed symlink
+entries in `contents`. Native inputs preserve safe internal relative links.
+
+### Native commands
+
+```yaml
+native:
+  command: [ruby, packaging/dmg.rb, '@PAYLOAD@', '@PACKAGE@', '@VERSION@']
+  output: 'hello-@TAG@-macos-arm64.dmg'
+```
+
+The command must be a nonempty argument list containing `@PACKAGE@`, and must
+create only that output file. `output` is a filename ending in `.dmg` or `.exe`.
+See [macOS and Windows installers](../_guides/native-recipes.md) for the script
+contract and a complete DMG example.
+
+## Hooks
+
+`before_build` runs once per selected target before copying local input.
+It is skipped in release mode. `after_package` runs once per generated package
+in either mode, before checksums are recorded.
+
+```yaml
+before_build: [./scripts/build-linux.sh, '@ARCH@']
+after_package: [pwsh, -File, packaging/sign.ps1, '@PACKAGE@']
+```
+
+Hooks run in the configuration directory with `NATIVE_PACKAGES_TARGET` and
+`NATIVE_PACKAGES_VERSION`. They are argument lists, so use a script for shell
+pipelines. `validate`, `doctor`, and dry runs never execute build hooks.
+The output hook must preserve the package's filename and file set.
+
+For DMGs, automatic Apple input signing finishes before the native command.
+DMG signing and notarization run after `after_package`, before the final hash.
+See [Apple signing and notarization](../_guides/apple-notarization.md).
+
+## Replacement values
+
+Strings can contain `@KEY@` values. Unknown or unavailable values cause an error.
+
+| Value | Meaning |
+| --- | --- |
+| `@NAME@` | Shared package name. |
+| `@VERSION@` | App version without the leading `v`. |
+| `@TAG@` | Version with the leading `v`. |
+| `@DATE@` | Build timestamp in UTC ISO 8601 format. |
+| `@SOURCE_DATE_EPOCH@` | Build timestamp as Unix seconds. |
+| `@ROOT@` | Absolute configuration directory. |
+| `@UPSTREAM@` | GitHub URL of `release.repository`. |
+| `@GIT_VERSION@` | Git revision value such as `r42.abc1234`; `r0.unknown` without Git metadata. |
+| `@ARCH@`, `@PLATFORM@` | Target architecture and platform. |
+| `@TARGET_ID@` | Target ID. |
+| `@TARGET@` | `compiler_target`, or the target ID if omitted. |
+| `@PAYLOAD@` | Copied or extracted input directory, available during packaging. |
+| `@PACKAGE@`, `@FORMAT@` | Output path and format, available to native commands and `after_package`. |
+| `@PKGREL@` | Recipe revision; defaults to `1`. |
+| `@KEY_FILE@`, `@KEY_URL@`, `@KEY_SHA256@` | Filename, URL, and hash for asset `KEY`. |
+
+Target values are available within target definitions and package metadata,
+not global recipe templates. `before_build` runs before the payload exists;
+use it to produce `input.local`.
+
+## Release
+
+```yaml
+release:
+  repository: your-name/hello
+  checksums: checksums.txt
+  prereleases: false
+```
+
+`repository` is the GitHub `owner/repository` for downloads and package uploads.
+`checksums` is a filename, defaulting to `checksums.txt`.
+`prereleases: true` opts into the formats and version rules described in
+[Prereleases](../_guides/prereleases.md).
+
+### Version and timestamp
+
+`build --version 1.2.3` uses local inputs. `build --release v1.2.3` supplies the
+version and uses release inputs. If both options are given, their versions
+must agree. Omitting both requires an exact supported release tag at `HEAD`.
+
+Versions are stable `MAJOR.MINOR.PATCH` unless prereleases are enabled. A leading
+`v` is accepted. Build timestamps use `SOURCE_DATE_EPOCH`, then the relevant
+Git commit's timestamp, then the current time if Git metadata is unavailable.
+Set an explicit epoch for repeatable builds outside Git and for builds split
+across hosts.
+
+## Assets and templates
+
+```yaml
+assets:
+  AMD64:
+    file: hello_@VERSION@_linux_amd64.tar.gz
+    local: dist/hello_@VERSION@_linux_amd64.tar.gz
+templates:
+  arch/hello-bin/PKGBUILD: packaging/arch/hello-bin/PKGBUILD.in
+```
+
+Asset keys use uppercase letters, digits, and underscores, starting with a
+letter. Each asset needs `file`; local builds also need `local`. An optional
+`url` overrides its release download location. Downloads are checked against
+release checksums by default. For a source archive omitted from the published
+checksum list, explicitly set `checksummed: false`; its computed SHA-256 still
+appears in the rendered recipe.
+
+`templates` maps output paths under `recipes/` to source paths relative to the
+configuration. See [Distribution recipes](../_guides/distribution-recipes.md)
+for a complete example.
+
+### Deferred recipe generation
+
+`build --defer-recipes` skips global assets and templates. Use
+`aggregate --finalize-recipes` once all package builds and remaining local
+assets are available. No additional configuration fields are needed. See
+[Building across platforms](../_guides/multi-platform.md) for prerequisites,
+asset matching, and publication rules.
+
+## Repositories
+
+Each entry under `repositories` names a destination. These settings apply to
+`stage`, `diff`, `publish`, and `status`:
+
+| Field | Purpose |
+| --- | --- |
+| `publish` | Required: `push`, `github-pr`, `gitlab-mr`, or `manual`. |
+| `url` | Required. Upstream clone URL. |
+| `push_url` | Push URL; defaults to `url`. Set to your fork for submissions. |
+| `fork_url` | Fork clone URL for submissions. |
+| `group` | Optional name for selecting several destinations together. |
+| `branch` | Upstream branch to start from. Required for managed Git destinations. |
+| `package_path` | Package directory to check out; `.` for the whole repository. |
+| `files` | Generated recipe paths mapped to downstream repository paths. |
+| `version_file` | Downstream file containing the package version. |
+| `version_files` | Alternative directory whose filenames contain versions, such as ebuilds. |
+| `version_pattern` | Regular expression capturing the version from that file or those filenames. |
+| `proposal_branch` | Branch pushed for a PR/MR; can contain `@VERSION@`. |
+| `title` | Commit/request title template; defaults to the package name and version. |
+| `status_branch` | Optional branch to inspect for upstream status. |
+| `sign_commit`, `sign_push` | Enable Git commit or push signing. |
+| `signoff` | Add a sign-off to the commit. |
+| `notes` | Instructions for a manual destination. |
+
+GitHub PR entries also need `repository` (upstream `owner/repo`) and
+`fork_owner`. GitLab MR entries need `repository`, `fork_repository`, `host`,
+and `token_env` (the environment variable holding the GitLab token).
+Submission destinations need a fork, a `proposal_branch`, and a reviewed
+`--body-file` when publishing. GitHub requests use authenticated `gh`; direct
+Git pushes use your configured Git credentials.
+
+## Libraries
+
+Add a mapping from a shared library's filename to its distribution package:
+
+```yaml
+libraries:
+  libexample.so.1:
+    deb: libexample1
+    rpm: libexample
+```
+
+Mappings extend the built-in DEB/RPM table. A mapping for an existing library
+replaces that library's mapping, so include both formats if needed. Verify
+package names against your supported distribution versions.
+
+## Revisions and version checks
+
+To regenerate a recipe with a new package revision for the same app version:
+
+```yaml
+revisions:
+  '1.2.3':
+    arch/hello-bin/PKGBUILD: 2
+```
+
+That template receives `@PKGREL@` as `2`; other versions and templates default
+to `1`. This setting controls recipe revisions, not the `nfpm.release` field.
+
+For Cargo version checks:
+
+```yaml
+version_file: Cargo.toml
+version_section: package
+```
+
+Run `native-packages check-version v1.2.3` to compare the manifest version with
+the tag. Use `version_section: workspace.package` for a workspace version.
+
+## Output and publication
+
+A build writes to a fresh `dist/packages/<version>/` by default. Packages live
+under `packages/<target>/<format>/`. `build.json` records configuration identity,
+targets, input/output hashes, and validation results.
+
+Publication verifies the files against the manifest. It requires every format
+for all configured targets unless exact complete targets are selected with
+`publish --target`. See [Publishing a release](../_guides/publishing.md).
+
+### One configuration across native hosts
+
+Build each native target on its host, then combine results with `aggregate`.
+Use the same configuration, version, and timestamp. The Linux reusable workflow
+can select Linux targets through its `targets` input. See
+[Building across platforms](../_guides/multi-platform.md).

data/docs/_reference/platforms.md

@@ -0,0 +1,104 @@
+---
+title: Supported platforms
+description: Package formats, required build inputs and tools, architecture checks, and distribution recipe support.
+nav_order: 3
+---
+
+# Supported platforms
+
+Choose formats for the systems your app already supports. Each target needs
+binaries built for the correct operating system, CPU architecture, and runtime
+libraries.
+
+## Package formats
+
+| Format | Target | What you supply | Packaging tools |
+| --- | --- | --- | --- |
+| `deb` | Linux | Compatible Linux files and package metadata. | nFPM, `readelf` for binaries. |
+| `rpm` | Linux | Compatible Linux files and RPM-specific dependencies. | nFPM, `readelf` for binaries. |
+| `archlinux` | Linux | Arch-compatible files and explicit dependencies. | nFPM, `readelf` for binaries. |
+| `apk` | Linux | Suitable Alpine files, usually musl or static binaries, and dependencies. | nFPM, `readelf` for binaries. |
+| `ipk` | Linux | Files for the device/distribution baseline, dependencies, and an `abi` label. | nFPM, `readelf` for binaries. |
+| `srpm` | Linux source target | RPM spec and source files. | nFPM; native RPM tooling for rebuild tests. |
+| `msix` | Windows | Windows binaries, identity, application assets, and capabilities. | nFPM; Windows tools for signing and installation tests. |
+| `dmg` | macOS | Complete app and a DMG script. | macOS, `lipo`, and your script's tools, such as `hdiutil`. |
+| `inno` | Windows | Complete app and an Inno Setup recipe/wrapper. | Windows and your installed Inno compiler. |
+
+The supported nFPM version is **2.47.0**. It writes package files from your
+prepared contents. Native DMG and Inno targets call your scripts instead.
+Archive inputs also require `bsdtar`; release downloads require `curl`.
+
+## Linux compatibility
+
+Linux binary targets declare `libc: glibc`, `musl`, or `static`. The tool checks
+ELF architecture, linked libraries, and the declared C library without executing
+the binaries. DEB/RPM dependency detection can be extended with
+[configuration mappings](configuration.md#libraries).
+
+Supported inspection architectures are `386`, `amd64`, `arm64`, `arm5`, `arm6`,
+`arm7`, `mips`, `mipsle`, `mips64`, `mips64le`, `ppc64`, `ppc64le`, `s390x`,
+`riscv64`, and `loong64`. Unknown architectures fail explicitly.
+
+Use explicit dependencies for Arch, Alpine, and IPK. Test against the oldest
+distribution version you intend to support, including any libraries your app
+loads at runtime. Changing a glibc target's format to APK does not turn its
+binary into a musl build.
+
+For IPK, check which format your device's distribution release actually uses.
+The repository's IPK fixture targets OpenWrt 24.10.8; its coverage should not
+be treated as a claim about every OpenWrt version.
+
+## MSIX
+
+MSIX targets use `platform: windows`, `formats: [msix]`, and PE binaries with
+`arch: 386`, `amd64`, or `arm64`. Supply `nfpm.msix.publisher`, at least one
+application under `nfpm.msix.applications`, and the required assets and
+capabilities for your app.
+
+The [all-formats example](https://github.com/crmne/native-packages/blob/main/examples/native-packages-all-formats.yaml)
+includes an MSIX configuration. The reusable Linux workflow can construct an
+MSIX from already-built Windows inputs. Perform signing and installation
+checks on Windows.
+
+Use Windows SDK SignTool through an `after_package` hook for signing, as the
+project's Windows acceptance tests do. Those tests found that Windows rejected
+nFPM 2.47.0's built-in signature with `0x80096010`. An MSIX file built
+successfully is not yet evidence that Windows will accept and install it.
+
+## DMG and Inno Setup
+
+These formats run on their native host and each require a separate binary
+target with a local directory input. macOS inspection supports `amd64`,
+`arm64`, and `universal`; Windows inspection supports `386`, `amd64`, and
+`arm64`. Your script and compiler must also support the chosen architecture.
+
+Follow [macOS and Windows installers](../_guides/native-recipes.md) for setup.
+DMG targets can automatically [sign and notarize](../_guides/apple-notarization.md)
+when complete Apple credentials are available.
+
+## Distribution recipes
+
+[Templates and downstream repository settings](../_guides/distribution-recipes.md)
+support AUR, Homebrew taps, Nixpkgs, Gentoo, Void, and other native recipe
+repositories. You supply each distribution's recipe and its validation steps.
+The tool renders release values and stages or submits the update.
+
+An Arch package file and an AUR recipe are separate outputs: the former can
+be installed directly; the latter tells Arch tooling how to obtain and package
+your app.
+
+There is no Flatpak build/publication adapter, no NSIS/WiX adapter, and no
+hosted APT/DNF index service. Keep those workflows in your app's release
+process if you need them.
+
+## What validation establishes
+
+Builds check inputs, architecture, applicable library requirements, package
+contents or native containers, and recorded hashes. A `build.json` reports
+installation as `not-tested`.
+
+This repository's CI separately builds fixtures in every supported format and
+runs Linux install/upgrade/remove checks, an SRPM rebuild, Windows MSIX and
+Inno checks, and macOS DMG checks. Your app still needs its own installation
+and runtime tests, including services, GUI integrations, entitlements, or
+hardware access where applicable.