Advice: situations, the shortlist, and the package cache

/just-say-so:advise runs node src/cli/advise.js, which prints the advice inputs, and the model writes one recommendation per situation from them: the project and tag, the counts, and a ready-to-paste change, which is a .vale.ini line, a rules.extra bullet in the shape /draft produces, or a Packages line with vale sync and the BasedOnStyles addition for the reply section. The model names only rules and packages the inputs printed.

The inputs, per project in the report: the situations; for each rule a situation’s bullet names, whether it is installed and on for the reply target and at what level, read with the same rule-state resolution the reminder uses; a shortlist of candidate rules per tag; the project’s Packages entries and the reply section’s BasedOnStyles; and the registry packages the project does not have, with their descriptions. The shortlist scores every candidate rule by word overlap between the tag and its typed reasons on one side and the rule’s id and message on the other, ids split on capitals and dots, plurals folded, and prints the top ten at or above a floor with the score and the matched words. The pool is the rules installed under the project’s styles path, read from disk, plus the rules in the package cache for packages the project has not installed; an installed rule is listed once, from disk. An empty shortlist means this search found nothing, which the text says, not that no rule exists.

The package cache. The Vale registry, library.json in vale-cli/packages, is the list Vale resolves a bare Packages name from: 27 entries in October 2026, each with a name, a one-line description, a release URL, and a tags list, where style marks writing rules and config marks markup support with no rules. Advise fetches it live with a 3 second timeout and falls back to the copy shipped at rules/vale-library.json; JUST_SAY_SO_REGISTRY=shipped skips the fetch. Descriptions alone sort a tag into a category, not onto a rule, so /just-say-so:packages --refresh downloads every style package’s archive (about 3 MB from the packages’ GitHub release pages), reads each rule’s id, level, what it extends, message, link, and a sample of its tokens, and writes one JSON file per package under packages/ in the state directory. Nothing else downloads an archive: advise reads the cache and says when it is empty or older than 30 days. An archive is read in memory, only its .yml entries are looked at, and nothing from it is written out or run. A failed download keeps the package’s previous file, and a message the single-line parser could not read is counted and reported. /just-say-so:packages with no arguments reports the cache against the registry; --prune removes packages the registry dropped. The doctor prints the cache size in one line. Packages outside the registry are under the GitHub topic vale-linter-style, which the advice names as a place to look.