System overrides¶

Amri adds a small set of built-in commands to every profile you load. These are the "Amri, ..." commands, spoken with the reserved wake-word amri. Because they are always present, a profile that defines its own command with the same name would clash with them, and Amri handles that clash explicitly.

The built-in system commands¶

Amri ships a small set of engine-level commands and merges them into whatever profile you load, so they are available everywhere. They are keyed on the reserved word amri, for example a command to drop a manual profile override and return to the auto-selected default. You do not install them; they come with Amri.

When a profile clashes with them¶

If a profile defines a command with the same name as one of these built-in commands, Amri refuses to load that profile and reports an overlay conflict that points you at the allowlist below. This is the default, so a profile you downloaded cannot quietly replace a built-in command.

To allow the override, you add the profile's name to your own engine.toml. The permission lives in the file you control, never inside the profile, so a profile cannot grant itself the right to replace a built-in command:

# engine.toml, the file you control
[security]
permit_system_overrides_for = ["my_personal_overlay"]

The list holds profile names. Naming a profile here grants it permission to override the built-in commands as a whole; the permission is per profile, not per command. When a permitted profile does override a built-in command, Amri records a warning at startup naming each command it replaced.

Example¶

Amri's built-in commands include one that returns to the auto-selected profile:

# Amri's built-in system command (installed with Amri; you do not edit this)
[[command]]
name = "amri_release_profile"
lua = "amri.profile.release()"
[command.trigger]
pattern = "Amri release profile"

If your own profile also defines a command named amri_release_profile, the load fails with an overlay conflict until you list your profile in permit_system_overrides_for.

The reserved wake-word

The amri word at the start of these patterns is reserved for the built-in commands. To add your own "Amri, ..." command that reuses one of their names, allow the override as above. See Trust for how Amri decides what a profile may do.