# Instructions agent guide
This module loads startup guidance and discovers local guides for touched paths.
## Where to look
- `mod.rs`: instruction source kinds, startup order, configured Markdown, and aggregate budget.
- `subdir.rs`: nearest-first discovery, canonical identity, and nonfatal diagnostics.
- Both files contain focused discovery tests.
## Local contracts
- Startup order is user `AGENTS.md`, explicit project-root `AGENTS.md`, then configured Markdown paths in listed order. Do not scan arbitrary ancestors or automatically load `CLAUDE.md`.
- Configured Markdown entries must be absolute `.md` paths. Preserve the indexed setting name in errors so users can identify the bad entry.
- Startup files are capped at 256 KiB each and 1 MiB combined. Missing optional guides are ignored; other startup read failures propagate.
- Touched-path discovery walks nearest-first, excluding the root guide and already-loaded canonical paths.
- Canonicalize root, touched path, and candidate guides. An in-root link may load only if its canonical target remains inside the root; do not impose the stricter skill/profile symlink policy here.
- Local guides have a 256 KiB per-file cap. Return discovery/read diagnostics alongside successfully loaded guides rather than failing the whole local walk.
- Preserve source kind, path, and order for the caller. Discovery loads text only; it does not execute instructions or write memory files.
`AGENTS_CUSTOM.MD` is a repository maintenance convention, not another automatically discovered instruction filename.