guides.shared

The guide catalogue, and the way a path resolves against it. Every tool in this toolbox reads it, so "which guides are there" has one answer whether it was asked from the shell, from Luau, or through MCP.

What counts as a guide

A .guide asset wherever it lives — built into the engine, shipped inside a package, or authored in this world — and an asset TYPE, whose README documents it and which answers under types/<name>. Both are documentation, and the documentation search ranks over both, so both belong in the same catalogue.

One guide, one entry

A guide reachable under two spellings is one asset, and the catalogue lists it once. The spelling that names a LOCATION wins the listing (controlsKit.package/my-guide, topics/physics) and every other spelling becomes an alias: the asset identity the engine states for it (controlsKit.my-guide, @builtin::docs.topics.physics), the form every other asset in a package is addressed by, and the spelling that names a PACKAGE. All of them keep resolving, so a path written against any of them still opens the guide, and pathOf is the one derivation of the listed path, which the documentation search hands back as a hit's path too.

How a path widens

resolve takes the spelling a caller typed and widens only while the answer stays unique: the exact spelling (a listed path, an alias, the guide's guid, or the VFS path of its folder or its guide.md), then the same ignoring case, then any identity ending in /<wanted>, then a bare last segment, then a run of name segments, read the way segments reads them (split at /, . and :, with @lib:: and ~ dropped), so controlsKit/my-guide reaches controlsKit.package/my-guide. The moment a widening matches more than one guide it stops and reports those spellings, because which one was meant is not knowable from what was typed — and answering with one of them would be a guess the caller could not see.