# 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

```toml
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

```toml
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

```text
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.