services.describe

Describe your assets: finds the descriptions (READMEs) they are missing and writes them, many at a call. A description is the text an asset's type asks it to carry: for the built-in types that ask, its README, or the intent, function and usage texts of a type's about.yaml. Each call costs 1 credit and covers many assets. What it writes is an ordinary file in the asset, there for you to edit.

tools.use("services", "describe", { mode = "find" })   -- what is missing, how many calls, what they cost
tools.use("services", "describe", { mode = "all" })    -- fill what that listing names
tools.use("services", "describe", { assets = { "Spinner", "Door" } })

Modes

• find (the default) lists the assets that lack the description their type asks for, the file and keys each needs, the number of calls filling them makes and the total price. It writes nothing.
• all fills every asset find lists.
• assets fills the assets you name.

By default the assets are the ones that block the current push. scope = "world" takes every asset your world holds that a type asks to describe.

What it does

The assets are packed whole into as few calls as fit, in the order of their names, and the calls run several at once. Each asset comes back written, failed (with the reason) or skipped (with the reason). An answer that is missing or unusable for one asset fails that asset and no other. The text is written into the description file or keys the type declares. Text you wrote is never replaced: it fills only what is missing or still starts with [[describe]]. Library and installed assets, /tmp and /local are never touched, and a sub-asset is left to its enclosing asset unless that asset's type makes its sub-assets discoverable.

Add instructions to say more to the model, and examples to name assets whose descriptions show the shape you want. The model also reads the type's own guidance and example descriptions, and each asset's files, whole.

Price

A call costs 1 credit, whatever it carries, and a call covers many assets. find reports the number of calls the fill would make, which is also the total in credits, before anything is spent. The credits for the whole fill are checked before the first call, and a fill you cannot cover starts nothing. An asset whose files alone are more than one call carries is answered failed, since the files are never cut down.