@yojahny/wp-design-library 0.2.0 → 0.3.0

package/README.md

@@ -244,11 +244,19 @@ node bin/library.mjs index         # rebuild the index from entries/
 node bin/library.mjs check         # validate every entry, 1 line per problem
 ```
 
-Over MCP, six tools: `search` (keyword + facet filters, aliases resolved),
-`get_entry`, `similar`, `add`, `refresh`, `save_entry`. `search` and `similar` carry
+Over MCP, seven tools: `search` (keyword + facet filters, aliases resolved),
+`get_entry` (pass `detail: "summary"` for just the body's first paragraph, instead of
+the default `"full"`), `similar`, `recommend` (turns a brief into a per-role reference
+set in one call), `add`, `refresh`, `save_entry`. `search` and `similar` carry
 `arms` (which retrieval arms ran; `["fts"]` in Phase 1); any tool may instead respond
 with `refused` and the reason.
 
+The server also ships MCP `instructions`, read once at session start. They claim what
+this library is authoritative about — role/composition fit and which motion device
+carries a section — and fence what it is not: colour is not this library's to give, the
+client's own material and existing site own the palette. Where the project's own
+conventions and this library disagree, the project wins.
+
 ## Vector search
 
 `index` also builds a `vec` arm — two `sqlite-vec` tables (`vec_text` 384-d,
@@ -370,8 +378,8 @@ root only to `chown` an existing (possibly root-owned) `/data` volume, then drop
 ## Releasing
 
 1. Bump `version` in `package.json`.
-2. Tag the release: `git tag v0.2.0` (the workflow triggers on any `v*` tag).
-3. Push the tag: `git push origin v0.2.0`.
+2. Tag the release: `git tag vX.Y.Z` (the workflow triggers on any `v*` tag).
+3. Push the tag: `git push origin vX.Y.Z`.
 4. `.github/workflows/publish.yml` runs on that push: checks out, installs with
    `npm ci`, runs `npm test`, then `npm publish`. Trusted publishing means no npm
    token lives in this repo — the registry trusts the GitHub Actions run itself via
@@ -413,6 +421,16 @@ without breaking this workflow, since it never uses a token.
   (models and entries) so an old root-owned volume keeps working with no operator
   step; start latency grows with the corpus. Replace it with an ownership probe if it
   ever shows up in the health-check window.
+- **Instructions are advice, not enforcement.** A client is free to ignore every word,
+  including the line saying colour is not this library's to give. What the text buys is
+  that an agent which has never read `claude-wp-builder`'s command prose now has something
+  correct to go on instead of nothing at all.
+- **`recommend` fans out one search per role, server-side.** It saves round-trips and
+  transcript, not database work. At the current corpus size that is irrelevant; it is worth
+  revisiting if twelve queries per call ever becomes measurable.
+- **`detail: "summary"` skips leading headings and takes the first prose paragraph.** An
+  entry whose opening paragraph says nothing useful summarises badly. The fix is a better
+  entry, not a cleverer splitter.
 
 ## Layout
 

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Design reference corpus and MCP server for claude-wp-builder",
-  "repository": { "type": "git", "url": "git+https://github.com/yojahny55/wp-design-library.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yojahny55/wp-design-library.git"
+  },
   "homepage": "https://github.com/yojahny55/wp-design-library#readme",
-  "bugs": { "url": "https://github.com/yojahny55/wp-design-library/issues" },
+  "bugs": {
+    "url": "https://github.com/yojahny55/wp-design-library/issues"
+  },
   "type": "module",
-  "bin": { "library": "bin/library.mjs" },
-  "engines": { "node": ">=22" },
+  "bin": {
+    "library": "bin/library.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "test": "bash tests/run.sh",
     "check": "node bin/library.mjs check",
@@ -27,8 +36,12 @@
     "playwright-core": "1.63.0"
   },
   "peerDependenciesMeta": {
-    "@huggingface/transformers": { "optional": true },
-    "playwright-core": { "optional": true }
+    "@huggingface/transformers": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
   },
   "license": "MIT",
   "private": false,

package/src/mcp/instructions.mjs

@@ -0,0 +1,17 @@
+// Reaches every session in a project where this server is registered, not only the
+// command that wants it — so it is kept under 1500 characters and says only what a
+// client cannot infer from the tool descriptions. tests/checks/instructions.sh pins
+// the size and the three claims that keep a client from misusing the library.
+export const INSTRUCTIONS = `A corpus of design references for building WordPress page sections. Each entry carries roles (hero, proof, feature, offer, testimonial, faq, closing...), feel tags, the data-motion device names it uses, and a scroll strip.
+
+AUTHORITATIVE ABOUT: which composition suits a role, and which motion device carries it. NOT about colour — the client's own material and their existing site own the palette. An entry's colours are context for how that reference reads, never tokens to adopt.
+
+CALL IT WHEN: building or redesigning a page section; choosing a motion device; needing a worked example of a role.
+
+DO NOT CALL IT WHEN: the project already has a design system or tokens — follow those; the work is copy, logic, tests or infrastructure; the design is already specified.
+
+Where the project's own conventions and this library disagree, the project wins.
+
+BUDGET: a tool result is re-read on every later turn, so a study costs the transcript, not the call. One recommend, or one search per role you actually need, then get_entry on the three to five you keep, is a complete study. A further search costs more than it finds. Use get_entry with detail:"summary" to decide, detail:"full" only to build.
+
+READING A HIT: ranks.fts null means it matched by semantic distance alone, with no keyword in common. A role whose hits are all weak has no reference — report that rather than filling it with a weak one.`;

package/src/mcp/prompts.mjs

@@ -85,9 +85,10 @@ and \`public-site\` are inspiration only and \`save_entry\` refuses \`tier: port
 - Never run git in the current project.`;
 }
 
-// brief-from-library turns a client brief into a search plan: one `search` call per
-// role the page needs, feel filters from the brief's own vibe words, then a
-// `## References` block the session fills in with the slugs it actually used.
+// brief-from-library turns a client brief into a reference set: one `recommend` call,
+// then `get_entry` on what survives, then a `## References` block the session fills in
+// with the slugs it actually used. The per-role `search` fan-out is kept as a fallback
+// for a client whose server predates `recommend`.
 
 export function briefFromLibraryPrompt(ctx, { brief }) {
   const v = ctx.vocab.facets;
@@ -101,9 +102,14 @@ ${brief}
 
 ## What to do
 
-For each of the ${v.role.size} roles below, call the \`search\` tool once with \`filters.role\`
-set to that role, \`limit: 3\`, and \`filters.feel\` set to whichever feel terms from
-the vocabulary (${feels}) match the brief's own vibe words. Roles: ${roles}.
+Call the \`recommend\` tool once with this brief. It runs one search per role and
+returns a compact per-role digest. Read the digest, then call \`get_entry\` with
+\`detail: "summary"\` on the candidates worth considering and \`detail: "full"\` on the
+ones you will actually build from.
+
+If \`recommend\` is unavailable, fall back to calling \`search\` once per role
+(${roles}) with \`limit: 3\` and \`filters.feel\` set to whichever feel terms
+(${feels}) match the brief's own vibe words.
 
 Read the results, pick the entries that best fit the brief for each role, and use
 \`get_entry\` on any slug whose body you need to see in full before deciding.
@@ -123,7 +129,7 @@ export function registerPrompts(server, ctx) {
   server.registerPrompt(
     'brief-from-library',
     {
-      description: "Turn a client brief into a search plan against this library: one search per role, feel filters from the brief's vibe words, and a References block of the slugs used.",
+      description: "Turn a client brief into a per-role reference set against this library: one recommend call, then a References block of the slugs actually used.",
       argsSchema: { brief: z.string().describe('the client brief or page description to search the library against') },
     },
     async (a) => ({ messages: [{ role: 'user', content: { type: 'text', text: briefFromLibraryPrompt(ctx, a) } }] }),

package/src/mcp/server.mjs

@@ -6,6 +6,7 @@ import { getEmbedder, absentReason } from '../index/embed.mjs';
 import { registerPrompts } from './prompts.mjs';
 import { registerResources } from './resources.mjs';
 import { makeTools, registerTools } from './tools.mjs';
+import { INSTRUCTIONS } from './instructions.mjs';
 
 export async function buildServer(opts = {}) {
   const transport = opts.transport ?? 'stdio';
@@ -15,7 +16,7 @@ export async function buildServer(opts = {}) {
   ctx.embedder = 'embedder' in opts ? opts.embedder : await getEmbedder({ models: ctx.models });
   // Names why, when it's null: off / package not installed / models absent are distinct.
   ctx.embedderReason = ctx.embedder ? null : absentReason(ctx.models);
-  const server = new McpServer({ name: 'wp-design-library', version: p.version });
+  const server = new McpServer({ name: 'wp-design-library', version: p.version }, { instructions: INSTRUCTIONS });
   registerTools(server, makeTools(ctx));
   registerPrompts(server, ctx);
   registerResources(server, ctx);

package/src/mcp/tools.mjs

@@ -76,11 +76,28 @@ export function makeTools(ctx) {
     },
     {
       name: 'get_entry',
-      description: 'Return one entry: frontmatter, prose body, and the path to its strip.png.',
-      schema: z.object({ slug: z.string() }),
-      handler: withDb((db, { slug }) => {
+      description: "Return one entry: frontmatter, prose body, and the path to its strip.png. detail:'summary' returns the body's first paragraph instead of the whole body — enough to decide whether to fetch the rest.",
+      schema: z.object({
+        slug: z.string(),
+        detail: z.enum(['summary', 'full']).default('full'),
+      }),
+      handler: withDb((db, { slug, detail }) => {
         const e = getEntry(db, slug);
-        return e ? { ...e, strip: `${e.dir}/strip.png` } : { refused: `no entry with slug ${slug}` };
+        if (!e) return { refused: `no entry with slug ${slug}` };
+        const out = { ...e, strip: `${e.dir}/strip.png` };
+        if (detail !== 'summary') return out;
+        // The first PROSE paragraph. Bodies conventionally open with `## What it does`,
+        // so splitting on the first blank line alone would return a bare heading, which
+        // tells a caller nothing. Skip leading heading lines, then take one paragraph.
+        // An entry whose first paragraph says nothing useful summarises badly — that is
+        // an entry to rewrite, not a splitter to make cleverer.
+        // This relies on the authoring convention that a heading is followed by a blank
+        // line: a body with no blank line after its heading is one unsplit paragraph
+        // that still starts with `#`, so it's skipped and the fallback returns that same
+        // unsplit blob — summary equals full for that entry. Also an entry to rewrite.
+        const paras = String(out.body ?? '').trim().split(/\n\s*\n/);
+        const first = paras.find((x) => !/^\s*#/.test(x)) ?? paras[0] ?? '';
+        return { ...out, body: first.trim(), detail: 'summary' };
       }),
     },
     {
@@ -100,6 +117,48 @@ export function makeTools(ctx) {
         return similar(db, { ...a, embedder: ctx.embedder, embedderReason: ctx.embedderReason });
       }),
     },
+    {
+      name: 'recommend',
+      description: "Turn a brief into a per-role reference set in one call. Runs one search per vocabulary role with feel filters drawn from the brief's own words, and returns a compact digest — no prose bodies. Use get_entry on the three to five you keep. A hit marked weak matched by semantic distance alone, with no keyword in common; a role whose hits are all weak has no reference.",
+      schema: z.object({
+        brief: z.string().trim().min(1),
+        limit: z.number().int().min(1).max(10).default(3),
+      }),
+      handler: withDb(async (db, { brief, limit }) => {
+        // Feel terms are whichever vocabulary feels the brief actually names. Matching
+        // on the brief's own words keeps the filter honest: a brief that says nothing
+        // about feel gets no feel filter rather than a guessed one.
+        const words = brief.toLowerCase();
+        const feel = [...ctx.vocab.facets.feel].filter((f) => words.includes(f));
+        let arms = null;
+        let skipped;
+        const roles = [];
+        for (const role of ctx.vocab.facets.role) {
+          const r = await search(db, {
+            query: brief,
+            filters: { role: [role], ...(feel.length ? { feel } : {}) },
+            limit,
+            embedder: ctx.embedder,
+            embedderReason: ctx.embedderReason,
+          });
+          arms ??= r.arms;
+          skipped ??= r.skipped;
+          roles.push({
+            role,
+            hits: (r.hits ?? []).map((h) => ({
+              slug: h.slug,
+              title: h.title,
+              tier: h.tier,
+              score: h.score,
+              // ranks is absent when only one arm ran; a hit is weak only when the
+              // fused result says it had no keyword match.
+              weak: Boolean(h.ranks) && h.ranks.fts === null,
+            })),
+          });
+        }
+        return { arms: arms ?? ['fts'], ...(skipped ? { skipped } : {}), feel, roles };
+      }),
+    },
     {
       name: 'add',
       description: 'Ingest a video/animated image, or measure a live https:// URL with the system Chrome: sample frames or measure into strip.png/measure.json and write a draft entry. Returns the blank fields the caller must fill before save_entry.',

package/tests/README.md

@@ -19,3 +19,15 @@ no port; it exercises `add`/`export`/`index`/`check`/`save` directly or drives `
 (no `--http`) over stdio.
 
 A new serve-based check takes the next free port below 4191.
+
+## Checks with no port
+
+`instructions.sh`, `entry-detail.sh` and `recommend.sh` drive the server over stdio
+(`serve`, no `--http`) and start no server on a fixed port, so the table above is
+unchanged by them.
+
+| Check | Asserts |
+|---|---|
+| instructions.sh | the `initialize` response's `instructions`: present, under the 1500-char budget, and carrying the colour fence, the project-wins line, the call budget, and the `ranks.fts` explanation |
+| entry-detail.sh | `get_entry`'s `detail: "summary"` returns a strictly shorter body than `detail: "full"` for the same slug, with matching frontmatter and strip path |
+| recommend.sh | `recommend` returns one group per vocabulary role, weak hits marked, no prose bodies, and the same named-reason degradation `search` already gives when the vector arm is absent |

package/tests/checks/entry-detail.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# summary returns a strictly shorter body than full for the same slug, and both
+# carry the same frontmatter and strip path — a summary that dropped either would
+# be a different tool, not a cheaper one.
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+LIBRARY_DATA="$tmp" node bin/library.mjs index >/dev/null 2>&1
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_entry","arguments":{"slug":"entry-ok"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_entry","arguments":{"slug":"entry-ok","detail":"summary"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" timeout 20 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
+
+node --input-type=module -e '
+import fs from "node:fs";
+const byId = {};
+for (const line of fs.readFileSync(process.argv[1], "utf8").split("\n")) {
+  if (!line.startsWith("{")) continue;
+  const d = JSON.parse(line);
+  if (d.id) byId[d.id] = d;
+}
+const fail = (m) => { console.error("FAIL: " + m); process.exit(1); };
+const full = byId[2]?.result?.structuredContent;
+const sum  = byId[3]?.result?.structuredContent;
+if (!full) fail("no full result");
+if (!sum) fail("no summary result");
+if (typeof sum.body !== "string") fail("summary has no body");
+if (!(sum.body.length < full.body.length)) fail(`summary body (${sum.body.length}) is not shorter than full (${full.body.length})`);
+if (/^\s*#/.test(sum.body)) fail(`summary is a bare heading, not prose: ${JSON.stringify(sum.body)}`);
+if (/\n\s*\n/.test(sum.body)) fail(`summary spans a paragraph break, so it is a truncation not a paragraph: ${JSON.stringify(sum.body)}`);
+if (/^\s*#/m.test(sum.body)) fail(`summary contains a heading line: ${JSON.stringify(sum.body)}`);
+if (sum.body.trim().length < 20) fail(`summary is too short to decide from: ${JSON.stringify(sum.body)}`);
+if (sum.detail !== "summary") fail("summary result is not labelled detail:summary");
+if (sum.strip !== full.strip) fail("summary lost the strip path");
+if (JSON.stringify(sum.fm) !== JSON.stringify(full.fm)) fail("summary changed the frontmatter");
+// A splitter that FILTERS every prose paragraph and joins them (instead of taking
+// just the first) can still pass every assertion above: joined with a space instead
+// of a blank line, it dodges the paragraph-break check, and it is still shorter than
+// full because only headings were dropped. Pin the actual promise: summary is a
+// PREFIX of full body, and a later prose paragraph never appears in it.
+if (!full.body.includes(sum.body)) fail(`summary is not a substring of full body: ${JSON.stringify(sum.body)}`);
+const fullProse = full.body.trim().split(/\n\s*\n/).filter((x) => !/^\s*#/.test(x));
+if (fullProse.length < 2) fail("fixture needs more than one prose paragraph to exercise this assertion");
+const later = fullProse[fullProse.length - 1];
+if (sum.body.includes(later)) fail(`summary includes a later prose paragraph, so it did not stop at the first: ${JSON.stringify(later)}`);
+console.log(`full ${full.body.length} chars, summary ${sum.body.length}`);
+' "$tmp/out" || { cat "$tmp/err"; exit 1; }
+echo PASS

package/tests/checks/instructions.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# The server's instructions reach every session in a project where it is registered,
+# so they are asserted for presence, for size, and for the three claims that keep a
+# client from misusing the library: colour is not ours, the project wins, and a study
+# has a budget.
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" timeout 20 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
+
+ins=$(node --input-type=module -e '
+import fs from "node:fs";
+for (const line of fs.readFileSync(process.argv[1], "utf8").split("\n")) {
+  if (!line.startsWith("{")) continue;
+  const d = JSON.parse(line);
+  if (d.id === 1) { process.stdout.write(d.result.instructions ?? ""); break; }
+}' "$tmp/out")
+
+[ -n "$ins" ] || { echo "FAIL: no instructions on initialize"; cat "$tmp/err"; exit 1; }
+n=${#ins}
+[ "$n" -lt 1500 ] || { echo "FAIL: instructions are $n chars, budget is 1500"; exit 1; }
+printf '%s' "$ins" | grep -q 'NOT about colour' || { echo "FAIL: instructions do not fence colour"; exit 1; }
+printf '%s' "$ins" | grep -q 'the project wins' || { echo "FAIL: instructions do not defer to the project"; exit 1; }
+printf '%s' "$ins" | grep -q 'costs more than it finds' || { echo "FAIL: instructions carry no call budget"; exit 1; }
+printf '%s' "$ins" | grep -q 'ranks.fts' || { echo "FAIL: instructions do not explain a weak hit"; exit 1; }
+echo "instructions: $n chars"
+echo PASS

package/tests/checks/recommend.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# recommend replaces a twelve-call client fan-out with one call: one group per
+# vocabulary role, no prose bodies, weak hits marked, and the same named-reason
+# degradation search already gives when the vector arm is absent.
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); export LIBRARY_SEED="$tmp/noseed"; trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+# entries_fts is a trigram index (schema.sql), and search() ANDs one quoted phrase
+# per query word (query.mjs's fts5Quote): a 1-character phrase like "a" can never
+# match under a trigram tokenizer, no matter what any entry contains. A brief built
+# from ordinary English ("a ... and a ...") is therefore guaranteed zero hits on
+# every role, which would let the weak-marking assertion below pass vacuously
+# (empty hits arrays, never actually checked) even if `weak` were dropped entirely.
+# So: drop the two 1-char words from the brief, and seed a second fixture entry
+# whose title carries every remaining query word verbatim, so role "hero" gets a
+# real hit and the weak-key assertion is actually exercised.
+mkdir -p "$tmp/entries/entry-hit"; cp tests/fixtures/entry-ok/strip.png "$tmp/entries/entry-hit/strip.png"
+cat > "$tmp/entries/entry-hit/entry.md" <<'EOF'
+---
+slug: entry-hit
+title: dark premium hero and pricing table
+tier: inspiration
+source:
+  kind: open
+  url: https://example.com
+  license: MIT
+captured:
+  method: frames
+  at: 2026-09-14
+  tool: wp-design-library@0.1.0
+roles: [hero]
+feel: [dark, premium]
+palette:
+  canvas: "#0b0f14"
+  ink: "#f4f6f8"
+  accent: "#6ea8ff"
+type:
+  display: geometric sans, light
+  body: same family
+motion:
+  devices: [reveal]
+  notes: fades in gently
+ported_from: null
+---
+
+## What it does
+
+A second fixture entry seeded so recommend has a real hit to mark weak or not.
+
+## Section roster
+
+hero
+EOF
+LIBRARY_DATA="$tmp" node bin/library.mjs index >/dev/null 2>&1
+{
+  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}'
+  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"recommend","arguments":{"brief":"dark premium hero and pricing table"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" LIBRARY_EMBED= timeout 30 node bin/library.mjs serve >"$tmp/out" 2>"$tmp/err" || true
+
+node --input-type=module -e '
+import fs from "node:fs";
+import yaml from "js-yaml";
+const fail = (m) => { console.error("FAIL: " + m); process.exit(1); };
+const tmpDir = process.argv[2];
+function rolesOf(slug) {
+  const raw = fs.readFileSync(`${tmpDir}/entries/${slug}/entry.md`, "utf8");
+  const m = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) fail(`entry ${slug} has no frontmatter`);
+  return yaml.load(m[1]).roles ?? [];
+}
+let res = null;
+for (const line of fs.readFileSync(process.argv[1], "utf8").split("\n")) {
+  if (!line.startsWith("{")) continue;
+  const d = JSON.parse(line);
+  if (d.id === 2) res = d.result?.structuredContent;
+}
+if (!res) fail("no recommend result");
+const vocabRoles = yaml.load(fs.readFileSync("vocab.yaml", "utf8")).role;
+if (!Array.isArray(res.roles)) fail("no roles array");
+if (res.roles.length !== vocabRoles.length) fail(`${res.roles.length} role groups for ${vocabRoles.length} vocabulary roles`);
+let totalHits = 0;
+for (const g of res.roles) {
+  if (!vocabRoles.includes(g.role)) fail("unknown role group " + g.role);
+  for (const h of g.hits ?? []) {
+    totalHits++;
+    if ("body" in h) fail("recommend returned a prose body");
+    if (!("weak" in h)) fail("hit is not marked weak or not");
+    // The whole promise of recommend is that a group only carries hits filed under
+    // its own role — assert that against the entry'"'"'s own frontmatter, not just
+    // against the shape of the response.
+    const entryRoles = rolesOf(h.slug);
+    if (!entryRoles.includes(g.role)) fail(`hit ${h.slug} in role group ${g.role} does not carry that role (entry roles: ${JSON.stringify(entryRoles)})`);
+  }
+}
+// A pass with zero hits everywhere would let the weak-key and role-membership
+// assertions above pass vacuously (nothing to iterate). The seeded second fixture
+// exists so this never happens silently.
+if (totalHits === 0) fail("no hits at all — weak-marking and role membership were never exercised");
+if (!Array.isArray(res.arms)) fail("no arms");
+if (!res.arms.includes("fts")) fail("fts arm did not run");
+if (!res.skipped || !res.skipped[0]?.reason) fail("vector arm skipped without a named reason");
+console.log(`roles ${res.roles.length}, arms ${res.arms.join(",")}, skipped ${res.skipped[0].reason}`);
+' "$tmp/out" "$tmp" || { cat "$tmp/err"; exit 1; }
+echo PASS

package/tests/checks/resources.sh

@@ -31,11 +31,14 @@ bad=$(grep '"id":9' "$tmp/out")
 echo "$bad" | grep -q '"error"' || { echo "FAIL: bad slug did not error"; exit 1; }
 echo "$bad" | grep -qF 'no entry bad.slug' || { echo "FAIL: bad slug error lacks 'no entry bad.slug'"; exit 1; }
 grep '"id":7' "$tmp/out" | grep -q '"name":"brief-from-library"' || { echo "FAIL: prompts/list lacks brief-from-library"; exit 1; }
+grep '"id":7' "$tmp/out" | grep -qF 'per-role reference set' || { echo "FAIL: prompt description does not match its recommend-first body"; exit 1; }
 get=$(grep '"id":8' "$tmp/out")
 echo "$get" | grep -qF 'limit: 3' || { echo "FAIL: prompt text lacks: limit: 3"; exit 1; }
 echo "$get" | grep -qF '## References' || { echo "FAIL: prompt text lacks: ## References"; exit 1; }
 echo "$get" | grep -qF 'ranks.fts' || { echo "FAIL: prompt text lacks the weak-vector-match rule (ranks.fts)"; exit 1; }
 echo "$get" | grep -qF 'having no reference rather than filling it' || { echo "FAIL: prompt text lacks the weak-match-only role guidance"; exit 1; }
+echo "$get" | grep -qF 'Call the `recommend` tool once' || { echo "FAIL: prompt does not reach for recommend"; exit 1; }
+echo "$get" | grep -qF 'fall back to calling' || { echo "FAIL: prompt lost its search fallback"; exit 1; }
 echo "$get" | grep -qi 'hero' || { echo "FAIL: prompt text lacks the word hero"; exit 1; }
 # vocabulary is rendered from vocab.yaml, so every feel term appears
 for t in $(node --input-type=module -e 'import { loadVocab } from "./src/vocab.mjs"; console.log([...loadVocab().facets.feel].join(" "))'); do