Project-Kiln/docs/phase-2/native-manifests.md

Native game manifests

Native discovery is opt-in. Place one schema-versioned TOML file per game under ${XDG_CONFIG_HOME:-$HOME/.config}/kiln/native/. Discovery is authoritative and read-only; it does not scan arbitrary system applications.

Direct executable

schema_version = 1
id = "openmw"
name = "OpenMW"
install_path = "/games/openmw"
executable = "/games/openmw/openmw"
arguments = ["--replace"]

id becomes native:<id>. install_path and executable must be absolute, normalized UTF-8 paths. Arguments are passed directly and are never evaluated by a shell.

Approved Desktop Entry

schema_version = 1
id = "supertuxkart"
name = "SuperTuxKart"
install_path = "/usr/bin"
desktop_entry = "/usr/share/applications/supertuxkart.desktop"

The explicit path is the approval boundary. The adapter accepts Application entries, parses Exec= without a shell, expands %%, %c, %i, and %k, and omits file/URL codes because no files or URLs are supplied. Unknown field codes, malformed quoting, symlinks, invalid UTF-8, files over 64 KiB, and mixed executable/Desktop Entry sources fail closed.

Commands and state

kiln list [--json]
kiln search <query> [--json]
kiln info <id-or-name> [--json]
kiln scan [--provider native] [--no-cache] [--json]
kiln launch <id-or-name> --dry-run [--json]
kiln launch <id-or-name> [--json]

Installation identity remains in the Phase 1 XDG state registry. Native stdout and stderr append to ${XDG_STATE_HOME:-$HOME/.local/state}/kiln/logs/native.log with mode 0600. A non-zero child exit returns a structured launch-failed error.