Reference

A version 1 JSON manifest contains named collections. Each collection selects a relative anchor glob with items, chooses file or directory as its kind, and lists named requirements under require. A minimum of one selected item is assumed unless min_items explicitly says otherwise. Manifest keys use lowercase ASCII spelling. Unknown fields, duplicate keys, unsupported globs and invalid regexes are rejected.

Each requirement gives an expected path relative to the scan root. The variables are {item}, the full relative anchor path; {name}, its basename; {stem}, the basename with its last extension removed; and {dir}, its parent directory. For articles/cafe.md those values are articles/cafe.md, cafe.md, cafe and articles. Required paths are literal after expansion, without wildcard searching.

A requirement defaults to kind file. It may set min_bytes to reject empty or undersized files and contains to check a nonempty Go regular expression. Directory requirements can test the presence of a directory, but cannot use file size or content rules. A check reports the first failed condition, rather than listing several consequences of the same missing file.

Anchor globs use forward slashes and match one path segment at a time. Recursive double-star patterns, parent traversal, drive names and noncanonical dot segments or separators are rejected. The scanner does not follow symlinks. A direct or possible ancestor symlink affecting anchor selection is an operational error, as is a symlink anywhere in a required path. Unrelated symlinks that cannot affect selection are ignored.

A missing companion, wrong type, minimum-size failure or content mismatch is a declared gap. An unreadable path or a content check beyond its read allowance is an operational error. The default content limit is 1048576 bytes per file, adjustable with --max-content-bytes. Oversized files are never matched against a silently truncated prefix. Presence-only and size-only rules check metadata; they do not establish content readability.

Reports use complete, incomplete or error as the top-level status, corresponding to exit 0, 1 or 2. Operational errors take priority over gaps. JSON and HTML keep every selected item and check; text emphasizes problems and totals. Collection ordering follows the manifest, item paths are sorted, and requirement ordering follows the declaration. The report includes the exact manifest’s SHA-256 digest.

Keep the collection still while scanning. Enumeration and reads are not an atomic filesystem snapshot, and this is not a sandbox against another process replacing paths concurrently. A suitably narrow root also avoids walking unrelated build folders. The manual, report reference and examples give the full schema and operational limits.