// SPDX-License-Identifier: CC-BY-SA-4.0
= Launcher Standard (Machine-Readable)
:toc:

This directory holds the canonical machine-readable companion to the prose
specification at `docs/UX-standards/launcher-standard.adoc`.

== Files

`launcher-standard.a2ml`::
  The authoritative A2ML form of the launcher standard. All tooling that
  provisions, audits, or validates launchers MUST consume this file rather
  than re-parsing the prose spec or carrying its own vendored copy.

== Consumer: launch-scaffolder

`launch-scaffolder` is the minter / provisioner / configurator for
launchers across the estate. Its workspace lives in the per-host
standards-monorepo checkout (e.g. `/var/mnt/eclipse/repos/launch-scaffolder/`,
`$HOME/developer/repos/launch-scaffolder/`, etc.; see the resolution ladder
below). It consumes this standard by reference, in this resolution order:

. `--standard <path>` — explicit CLI argument
. `$LAUNCH_SCAFFOLDER_STANDARD` — environment-variable override
. The `[resolution].standard-search` ladder declared in
  `launcher-standard.a2ml`, consulted in order, first existing path wins:
+
.. `$HP_ESTATE_ROOT/standards/launcher/launcher-standard.a2ml`
.. `$XDG_DATA_HOME/hyperpolymath/standards/launcher/launcher-standard.a2ml`
.. `/var/mnt/eclipse/repos/standards/launcher/launcher-standard.a2ml`
.. `$HOME/developer/repos/standards/launcher/launcher-standard.a2ml`
.. `$HOME/dev/repos/standards/launcher/launcher-standard.a2ml`

The ladder replaces the previous single hard-coded
`/var/mnt/eclipse/repos/...` literal, which broke the standard on any host
that didn't happen to use the eclipse-mount layout. A bash reference
implementation lives at `launcher/resolve-desktop-tools.sh`
(`hp_resolve_standard` function); `launch-scaffolder` re-implements the
same ladder in Rust.

A follow-up change in `launch-scaffolder` will drop its vendored copy
under `launch-scaffolder/standards/` and point its loader at the ladder
above.

== Sync requirement

This file MUST stay in lock-step with `docs/UX-standards/launcher-standard.adoc`.
Any edit to one REQUIRES a matching edit to the other in the same commit.
Drift between prose and machine-readable forms is a standards-compliance bug.
