guides.read

One guide, by path.

topics/physics, types/material and controlsKit.package/my-guide are paths, the way guides.list lists them and a search hit hands them back. A guide also opens by its asset identity (controlsKit.my-guide, @builtin::docs.topics.physics), by its guid, by the VFS path of its folder (/zero/source/controlsKit.package/my-guide.guide, or through /source) or of its guide.md (the vfsPath a read hands back), and by shorter spellings that still name exactly one guide: a path resolves by exact spelling, then ignoring case, then by what the identity ends with, then by its last segment, then by a run of its name segments (controlsKit/my-guide), widening only while the answer stays unique. A trailing .md or .guide, and surrounding slashes, come off first, so a path copied out of a search result or a file tree resolves as typed.

When a path does not name one guide

Both outcomes are answers rather than errors to parse.

A path matching several guides comes back with candidates: the spellings it tied between, so the caller can say which they meant. Nothing is chosen for them, because the choice is not derivable from what they typed.

A path matching none comes back with suggestions: the paths it was nearest to, ranked so a spelling that contains the whole query outranks one that only shares a segment, a dotted identity matched part by part the way a slashed path is. Its error names the forms a guide opens by and the nearest path. A typo is answered with the guide it was reaching for.