A %include directive stands where a member stands, letting one file draw on another.

{
  %include "base.fson",              // merge base's members as defaults
  %include "secrets.fson" as vault,  // bind secrets' root under "vault"
  timeout: 60                        // host value
}

Two forms

Form	Effect
%include "path"	Merge. The target's root-object members are added to the including object as defaults.
%include "path" as name	Alias. The target's whole root value is bound under the key name (the target root need not be an object).

The rules

• Host wins. A key already present in the including object is not overwritten by a merged default; an alias key already present is left untouched.
• Shallow merge. Only top-level keys are compared. A host logging object wholly shadows base's logging — nested objects are not deep-merged.
• Relative paths resolve against the directory of the file that contains the directive, not the process working directory — a file tree stays relocatable.
• Transitive. A target's own %include directives resolve before its members are merged in, so defaults chain through.
• Cycles (a includes b includes a) are reported as an error and broken; the document still loads with the non-cyclic content intact.
• Disabled directive. --%include "…" is preserved structurally but not resolved — its defaults are not applied — mirroring -- members.

Structural on write-back

Directives are structural. On write-back in the FSON dialect the %include line is reproduced verbatim, and the values it merged in are not written into the host file (they live in the included file). Programmatic overrides via the query API are written only to the host file.

The provenance API — isLocal / provenanceOf / provenanceMap — reports which file each resolved value actually came from, and LoadResult::dependencySet (or Fson::dependenciesOf) gives the full file list for a reload watch.

Why %?

@ is reserved for the FFS mechanism, and # is left unused (FSON needs no third comment syntax). % collides with nothing in the grammar and carries a template/directive connotation.