# panto system agent tree

Contents of this directory are embedded into the `panto` binary at
build time and staged onto disk at bootstrap into
`$PANTO_HOME/agent/` (i.e. `$XDG_DATA_HOME/panto/agent/`, or
`~/.local/share/panto/agent/` if `XDG_DATA_HOME` is unset).

The staged tree is the "system" layer of panto's extension/tool
search path — sitting underneath the user layer
(`$XDG_CONFIG_HOME/panto/`) and the project layer
(`./.panto/`). Project shadows user shadows system.

Files are written with `writeIfDifferent` semantics: on each
bootstrap, embedded contents are compared against what's on disk and
only rewritten when they differ. This keeps mtimes stable across
reruns.

The staged tree is **panto's territory** — local edits will be
overwritten on the next bootstrap. To customize a system tool,
override it at the user or project layer (a file with the same
basename under `$XDG_CONFIG_HOME/panto/tools/` or `./.panto/tools/`
shadows the system copy).

## Layout

    agent/
      tools/            single-file tools, one per `.lua`
      extensions/       (future) multi-tool extensions