glia-overlay

Closing glia's blind spots with the overlay

glia builds its graph from source, so it misses links the source does not spell out: a URL built at runtime, a project's own request / publish / collection helper, an entry point that the OS or a scheduler calls. <repo>/.glia/overlay.toml declares them. glia never calls a model: you write candidate stanzas from the code, and glia measures them. Three commands run the loop:

• glia overlay propose lists the gaps a stanza could close. Each gap has a stable id (gap:<16 hex>) and the source lines around it. It writes nothing.
• glia overlay try builds the repo with and without your candidate stanzas and gives each stanza a verdict. It writes only the parse cache.
• glia overlay accept is the only writer of .glia/overlay.toml. It adds the stanzas you pick and removes rotted rules by gap id.

The same loop carries architecture rules ([[constraint]] stanzas that glia check enforces): you write the rule, try judges it by the violations glia check finds on the code as it is, and accept writes it.

The schema of every section is in docs/overlay.md (https://github.com/James-Chahwan/glia/blob/main/docs/overlay.md). For queries (where is X, what does X affect), use the glia skill.

From Python. The wheel runs the same three steps in-process, with the same reports as the --json output: glia_py.overlay_propose(repo_paths, categories=None, top_k=20, snippet_lines=3), glia_py.overlay_try(repo_paths, candidate, leave_one_out=True) and glia_py.overlay_accept(repo_path, candidate=None, only=None, remove=None, dry_run=False). repo_paths is a list: the first is the primary repo, whose .glia/overlay.toml the loop reads, and the rest are what --with adds. candidate is the candidate's TOML text, not a path. only and remove are lists of stanza handles and gap ids. A refused candidate, or an accept that would not validate, raises ValueError with the loader's reasons, and nothing is written. overlay_accept is still the only writer of .glia/overlay.toml.