feat(api): let a package carry guidance about whether to choose it

A blurb says what a package does. It has no room for the other thing a reader
needs, which is whether to pick it at all — and @imqueue/sequelize is the case
that forces the question: it is locked to Sequelize v6 because upstream has sat
in v7-alpha for years and is asking for maintainers, so it is maintained and
still evolving for services already on Sequelize, while new development should
start with @imqueue/pg-prisma.

Optional `note` field, rendered under the blurb on /api/ as a rule-marked aside
and carried into llms.txt. The llms.txt half matters more than it looks: an agent
reading that file to recommend a package sees only the blurb otherwise, and would
recommend the wrong one with complete confidence.

The two ORM packages already both carry the exclusive `ORM` tag, so the page said
"pick at most one of these" without saying which. Now it says which.

Verified end to end by temporarily attaching a note to a shipped package —
sequelize is still `planned`, so its own note appears when Wave 6 ships — and
checked in both themes.

Author: Mikhus

scripts/lib/api-packages.js

@@ -30,6 +30,13 @@
 //               are hand-written and the owner decided that block stays as it is.
 //   blurb       One line on /api/. Seeded from the package's own npm description
 //               so it starts out true; revise it when the package's wave ships.
+//   note        Optional. Guidance about CHOOSING the package rather than about what
+//               it does — "locked to an upstream that has stalled, prefer X for new
+//               work" is the case it exists for. Rendered under the blurb on /api/
+//               and carried into llms.txt, because an agent recommending a package
+//               needs it more than a human browsing does. Keep it to one or two
+//               sentences and keep it about the choice: anything describing behaviour
+//               belongs in the blurb or in the package's own documentation.
 //   cliId       Matching id in the CLI's package catalog, or null when the package
 //               has no catalog entry. `catalog.json` ships with the CLI and is
 //               mirrored in the templates repo — it does NOT live in this repo, so
@@ -154,7 +161,12 @@ const PACKAGES = [
     tier: 2,
     group: 'Data & events',
     tags: ['ORM'],
-    blurb: 'Turns GraphQL input — filters, paging, ordering and the selected field set — into efficient Sequelize queries, with database views as models.',
+    blurb: 'Turns a query described as data — filters, paging, ordering and the '
+      + 'requested fields — into one efficient Sequelize statement, with database '
+      + 'views as models.',
+    note: 'Locked to Sequelize v6, which upstream has left in v7-alpha for years. '
+      + 'Maintained and still evolving for services already on it; new development '
+      + 'should start with @imqueue/pg-prisma.',
     cliId: 'sequelize',
     latestOnly: true,
     status: 'planned',

src/_data/apiPackages.js

@@ -24,7 +24,7 @@ const idOf = (group) =>
   group.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
 
 module.exports = () => ({
-  // [{ group, id, packages: [{ name, scoped, url, repo, blurb, tags: [{ label, exclusive }] }] }]
+  // [{ group, id, packages: [{ name, scoped, url, repo, blurb, note, tags: [{ label, exclusive }] }] }]
   groups: shippedGroups().map(({ group, packages }) => ({
     group,
     id: idOf(group),
@@ -34,6 +34,9 @@ module.exports = () => ({
       url: `/api/${p.name}/latest/`,
       repo: repoOf(p.name),
       blurb: p.blurb,
+      // Absent on almost every package, so `|| null` rather than undefined —
+      // Liquid treats both as falsy, but null survives a JSON dump readably.
+      note: p.note || null,
       tags: p.tags.map(label => ({ label, exclusive: TAGS[label].exclusive })),
     })),
   })),

src/_shared/css/prose.css

@@ -149,6 +149,11 @@
    no "Older versions" list to sit beside it. */
 .prose .api-pkg-ver { margin-left: auto; }
 .prose .api-pkg-blurb { flex: 1 1 100%; font-size: 15px; color: var(--muted); line-height: 1.6; }
+/* Choosing guidance, not behaviour — "prefer this other package for new work". Set
+   apart by a rule rather than by colour so it still reads as an aside when the card
+   is the accent-tinted hover state, and kept smaller than the blurb because it is
+   about the decision rather than about what the package does. */
+.prose .api-pkg-note { flex: 1 1 100%; font-size: 14px; color: var(--muted); line-height: 1.55; padding-left: 10px; border-left: 2px solid var(--line); }
 @media (max-width: 620px) { .prose .api-ref-cards { grid-template-columns: 1fr; } }
 
 /* FAQ accordion */

src/llms.liquid

@@ -84,7 +84,7 @@ generate. A group with nothing shipped yet emits no heading.
 
 ### Reference — {{ group.group }}
 {%- for pkg in group.packages %}
-- [{{ pkg.scoped }} API reference]({{ siteUrl }}{{ pkg.url }}): Every exported symbol of {{ pkg.scoped }}, generated from {{ apiVersions[pkg.name].latest }} — this URL always serves the current major. {{ pkg.blurb }}{% if pkg.tags.size > 0 %} Tagged {% for tag in pkg.tags %}`{{ tag.label }}`{% unless forloop.last %}, {% endunless %}{% endfor %}{% for tag in pkg.tags %}{% if tag.exclusive %} (pick at most one package with this tag){% endif %}{% endfor %}.{% endif %} — [markdown]({{ siteUrl }}{{ pkg.url }}index.md)
+- [{{ pkg.scoped }} API reference]({{ siteUrl }}{{ pkg.url }}): Every exported symbol of {{ pkg.scoped }}, generated from {{ apiVersions[pkg.name].latest }} — this URL always serves the current major. {{ pkg.blurb }}{% if pkg.note %} {{ pkg.note }}{% endif %}{% if pkg.tags.size > 0 %} Tagged {% for tag in pkg.tags %}`{{ tag.label }}`{% unless forloop.last %}, {% endunless %}{% endfor %}{% for tag in pkg.tags %}{% if tag.exclusive %} (pick at most one package with this tag){% endif %}{% endfor %}.{% endif %} — [markdown]({{ siteUrl }}{{ pkg.url }}index.md)
 {%- endfor %}
 {%- endfor %}
 

src/org/api/index.md

@@ -136,7 +136,7 @@ Browse the complete generated reference for the latest release — every class,
 
 <ul class="api-pkg-list">
 {%- for pkg in group.packages %}
-<li class="api-pkg"><a class="api-pkg-link" href="{{ pkg.url }}"><span class="api-pkg-name">{{ pkg.scoped | escape }}</span>{% if pkg.tags.size > 0 %} <span class="api-pkg-tags">{% for tag in pkg.tags %}<span class="topic-chip topic-chip--flat"{% if tag.exclusive %} title="Exclusive — pick at most one package carrying this tag"{% endif %}>{{ tag.label | escape }}</span>{% endfor %}</span>{% endif %}{% if apiVersions[pkg.name].latest %}<span class="api-ref-ver api-pkg-ver">v{{ apiVersions[pkg.name].latest }}</span>{% endif %}<span class="api-pkg-blurb">{{ pkg.blurb | escape }}</span></a></li>
+<li class="api-pkg"><a class="api-pkg-link" href="{{ pkg.url }}"><span class="api-pkg-name">{{ pkg.scoped | escape }}</span>{% if pkg.tags.size > 0 %} <span class="api-pkg-tags">{% for tag in pkg.tags %}<span class="topic-chip topic-chip--flat"{% if tag.exclusive %} title="Exclusive — pick at most one package carrying this tag"{% endif %}>{{ tag.label | escape }}</span>{% endfor %}</span>{% endif %}{% if apiVersions[pkg.name].latest %}<span class="api-ref-ver api-pkg-ver">v{{ apiVersions[pkg.name].latest }}</span>{% endif %}<span class="api-pkg-blurb">{{ pkg.blurb | escape }}</span>{% if pkg.note %}<span class="api-pkg-note">{{ pkg.note | escape }}</span>{% endif %}</a></li>
 {%- endfor %}
 </ul>