@yojahny/wp-design-library 0.1.0 → 0.3.0

package/Dockerfile

@@ -14,6 +14,10 @@ RUN if [ "$WITH_CHROME" = "1" ] && [ "$(dpkg --print-architecture)" = "amd64" ];
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --omit=dev
+# The vector arm and URL measurement are optional peers (npm ci skips an optional
+# peer by design); the hosted image wants both, so install them explicitly at the
+# pins package.json declares.
+RUN npm install --no-save --no-audit --no-fund @huggingface/transformers@4.2.0 playwright-core@1.63.0
 COPY . .
 # Vector-search models are not baked into the image: they land on the /data volume
 # under models/ and are fetched at container start when LIBRARY_FETCH_MODELS=1.

package/README.md

@@ -24,9 +24,28 @@ only for `own` or `open` sources; the licence gate refuses anything else.
 ```bash
 git clone git@github.com:yojahny55/wp-design-library.git
 cd wp-design-library && npm install
-npm test          # 24 checks, all should PASS (measure.sh SKIPs without a system Chrome)
+npm test          # 25 checks, all should PASS (measure.sh SKIPs without a system Chrome)
 ```
 
+## Install: core vs full
+
+A plain `npm install` (or the plugin's `npx @yojahny/wp-design-library serve`) gives you
+keyword search, ingest from recordings, the gallery, and every MCP tool — everything except
+the vector arm of `search`/`similar` and live-URL measurement (`add https://…`, `refresh`).
+Those two features sit behind `@huggingface/transformers` and `playwright-core`, listed as
+optional `peerDependencies` rather than regular dependencies precisely so the `npx` path (what
+the plugin actually runs) stays a core-only install. Measured on a fresh npm cache, a cold
+install is 57 MB and takes 6 s, against 736 MB and 48 s when both are regular dependencies;
+513 MB of the difference is `onnxruntime-node`, which transformers pulls in.
+Add them yourself when you want both arms:
+
+```bash
+npm install @huggingface/transformers@4.2.0 playwright-core@1.63.0
+```
+
+Without them, `search` degrades to the `fts` arm alone (`skipped` names the missing package),
+and `add`/`refresh` refuse a URL input with a named reason instead of crashing.
+
 ## Adding an entry
 
 Adding is two steps by design: the tool does the mechanical part, a Claude
@@ -225,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,
@@ -348,6 +375,36 @@ The container runs as `node` (uid 1000), not root: `docker/entrypoint.sh` starts
 root only to `chown` an existing (possibly root-owned) `/data` volume, then drops to
 `node` via `setpriv` before exec'ing the server.
 
+## Releasing
+
+1. Bump `version` in `package.json`.
+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
+   OIDC (`id-token: write`).
+
+One-time setup on npmjs.com, before the first tagged release:
+
+1. Open the package's settings page on npmjs.com.
+2. Under **Trusted Publisher**, add a publisher.
+3. Choose **GitHub Actions** as the provider.
+4. Organisation: `yojahny55`.
+5. Repository: `wp-design-library`.
+6. Workflow filename: `publish.yml` (the filename only, not the path under
+   `.github/workflows/`).
+7. Environment: leave empty (the workflow does not define one).
+
+Trusted publisher configurations created now default to **staged** publishing rather
+than a direct `npm publish`. Either flip the allowed-actions toggle on the trusted
+publisher to permit direct publishing (matches the workflow above as written), or
+change the workflow's last step to `npm stage publish` and approve each release by
+hand in the npm UI. Provenance is not generated for this release, because this repo
+is private — provenance requires a public repository. After the first successful
+publish, publishing access can be tightened to require 2FA and disallow tokens
+without breaking this workflow, since it never uses a token.
+
 ## Known ceilings
 
 - **Chrome runs without its own sandbox inside the container.** Docker's default
@@ -364,6 +421,16 @@ root only to `chown` an existing (possibly root-owned) `/data` volume, then drop
   (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,10 +1,22 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "0.1.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"
+  },
+  "homepage": "https://github.com/yojahny55/wp-design-library#readme",
+  "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",
@@ -12,15 +24,39 @@
     "serve": "node bin/library.mjs serve"
   },
   "dependencies": {
-    "@huggingface/transformers": "4.2.0",
     "@modelcontextprotocol/sdk": "^1.20.0",
     "better-sqlite3": "^12.2.0",
     "js-yaml": "^4.1.0",
-    "playwright-core": "1.63.0",
     "sharp": "^0.34.3",
     "sqlite-vec": "0.1.9",
     "zod": "^3.25.0"
   },
+  "peerDependencies": {
+    "@huggingface/transformers": "4.2.0",
+    "playwright-core": "1.63.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
+  },
   "license": "MIT",
-  "private": false
+  "private": false,
+  "files": [
+    ".dockerignore",
+    ".env.example",
+    "Dockerfile",
+    "LICENSE",
+    "README.md",
+    "bin/",
+    "docker-compose.yml",
+    "docker/",
+    "entries/",
+    "src/",
+    "tests/",
+    "vocab.yaml"
+  ]
 }

package/src/cli/check.mjs

@@ -7,7 +7,8 @@ import { fetchModels, modelDirs } from '../index/embed.mjs';
 export async function run(args = []) {
   const p = paths();
   if (args.includes('--fetch-models')) {
-    await fetchModels(p.models);
+    const r = await fetchModels(p.models);
+    if (r?.refused) { process.stdout.write(JSON.stringify(r) + '\n'); return 1; }
     const d = modelDirs(p.models);
     process.stdout.write(`model: ${d.text}\nmodel: ${d.image}\n`);
     return 0;

package/src/index/embed.mjs

@@ -19,6 +19,12 @@ export function modelDirs(models) {
   return { text: path.join(models, TEXT_MODEL), image: path.join(models, IMAGE_MODEL) };
 }
 
+// Resolvable without importing/executing the module, so it works as a cheap, sync
+// "is it installed" probe for the optional peer.
+function packageAvailable(specifier) {
+  try { import.meta.resolve(specifier); return true; } catch { return false; }
+}
+
 export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } = {}) {
   if (mode === 'off') return null;
   if (mode === 'stub') {
@@ -34,7 +40,9 @@ export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } =
   }
   const d = modelDirs(models);
   if (!fs.existsSync(d.text) || !fs.existsSync(d.image)) return null; // caller reads absentReason()
-  const tf = await import('@huggingface/transformers');
+  let tf;
+  try { tf = await import('@huggingface/transformers'); }
+  catch { return null; } // package not installed; caller reads absentReason()
   tf.env.cacheDir = models; tf.env.allowRemoteModels = process.env.LIBRARY_FETCH_MODELS === '1';
   const textPipe = await tf.pipeline('feature-extraction', TEXT_MODEL);
   const proc = await tf.AutoProcessor.from_pretrained(IMAGE_MODEL);
@@ -55,13 +63,19 @@ export function absentReason(models, mode = process.env.LIBRARY_EMBED) {
   // An explicit opt-out is the reason on its own; do not let a stale/present
   // model dir on disk relabel it, and do not touch the filesystem to find out.
   if (mode === 'off') return 'LIBRARY_EMBED=off';
+  // The package is a smaller, more fundamental blocker than an unfetched model
+  // directory, and it's checked first so a host missing the peer gets told that,
+  // not a misleading "models absent" (a fresh host has neither).
+  if (!packageAvailable('@huggingface/transformers')) return '@huggingface/transformers is not installed';
   const d = modelDirs(models);
   const missing = Object.entries(d).filter(([, p]) => !fs.existsSync(p)).map(([k]) => k);
   return missing.length ? `models absent: ${missing.join(', ')} under ${models}` : null;
 }
 
 export async function fetchModels(models) {
-  const tf = await import('@huggingface/transformers');
+  let tf;
+  try { tf = await import('@huggingface/transformers'); }
+  catch { return { refused: '@huggingface/transformers is not installed' }; }
   tf.env.cacheDir = models; tf.env.allowRemoteModels = true;
   await tf.pipeline('feature-extraction', TEXT_MODEL);
   await tf.AutoProcessor.from_pretrained(IMAGE_MODEL);

package/src/index/query.mjs

@@ -20,7 +20,7 @@ function filterSql(filters = {}, col = 'slug') {
 
 const RRF_K = 60;
 
-export async function search(db, { query = '', filters = {}, limit = 10, embedder = null }) {
+export async function search(db, { query = '', filters = {}, limit = 10, embedder = null, embedderReason = null }) {
   const { where, params } = filterSql(filters, 'e.slug');
   if (!query.trim()) {
     const { where, params } = filterSql(filters);
@@ -39,7 +39,7 @@ export async function search(db, { query = '', filters = {}, limit = 10, embedde
     return { arms: ['fts'], skipped: [{ arm: 'vec', reason }], hits: rows };
   };
   if (!(db.vec && embedder)) {
-    return ftsOnly(db.vec ? 'no embedder' : 'sqlite-vec not loaded');
+    return ftsOnly(db.vec ? (embedderReason ?? 'no embedder') : 'sqlite-vec not loaded');
   }
   let vec;
   try {
@@ -65,9 +65,9 @@ export async function search(db, { query = '', filters = {}, limit = 10, embedde
   };
 }
 
-export async function similar(db, { slug, image, limit = 10, embedder = null }) {
+export async function similar(db, { slug, image, limit = 10, embedder = null, embedderReason = null }) {
   if (!(db.vec && embedder)) {
-    return { refused: `similar needs the image arm: ${db.vec ? 'no embedder' : 'sqlite-vec not loaded'}` };
+    return { refused: `similar needs the image arm: ${db.vec ? (embedderReason ?? 'no embedder') : 'sqlite-vec not loaded'}` };
   }
   let vec;
   if (slug) {

package/src/ingest/measure.mjs

@@ -1,6 +1,5 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { chromium } from 'playwright-core';
 
 const VIEWPORT_WIDE = { width: 1440, height: 900 };
 const VIEWPORT_NARROW = { width: 390, height: 844 };
@@ -87,6 +86,12 @@ function collect() {
 // comes back as { ok: false, error }, with whatever partial output (frames,
 // screenshots) had already been captured still attached.
 export async function measure(url, outDir, { chrome = process.env.CHROME_PATH, record = false, stops = 12 } = {}) {
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright-core'));
+  } catch {
+    return { ok: false, error: 'playwright-core is not installed; install it for URL measurement' };
+  }
   if (!chrome || !fs.existsSync(chrome)) {
     return { ok: false, error: 'chrome not available: CHROME_PATH not set or not found' };
   }

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

@@ -2,10 +2,11 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { paths } from '../paths.mjs';
 import { loadVocab } from '../vocab.mjs';
-import { getEmbedder } from '../index/embed.mjs';
+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';
@@ -13,7 +14,9 @@ export async function buildServer(opts = {}) {
   const ctx = { paths: p, vocab: loadVocab(p.vocab), transport, models: p.models };
   // http passes its own cached embedder in (one per process, not one per request); stdio resolves its own.
   ctx.embedder = 'embedder' in opts ? opts.embedder : await getEmbedder({ models: ctx.models });
-  const server = new McpServer({ name: 'wp-design-library', version: p.version });
+  // 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 }, { instructions: INSTRUCTIONS });
   registerTools(server, makeTools(ctx));
   registerPrompts(server, ctx);
   registerResources(server, ctx);

package/src/mcp/tools.mjs

@@ -70,17 +70,34 @@ export function makeTools(ctx) {
       }),
       handler: withDb(async (db, a) => {
         const { filters, unknown } = resolveFilters(ctx.vocab, a.filters ?? {});
-        const result = await search(db, { ...a, filters, embedder: ctx.embedder });
+        const result = await search(db, { ...a, filters, embedder: ctx.embedder, embedderReason: ctx.embedderReason });
         return unknown.length ? { ...result, unknown } : result;
       }),
     },
     {
       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' };
       }),
     },
     {
@@ -97,7 +114,49 @@ export function makeTools(ctx) {
           const refusal = confineToInbox(ctx, a.image);
           if (refusal) return { refused: refusal };
         }
-        return similar(db, { ...a, embedder: ctx.embedder });
+        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 };
       }),
     },
     {

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/frames-dense.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -eu
 cd "$(dirname "$0")/../.."
+command -v ffmpeg >/dev/null || { echo "SKIP: ffmpeg not installed"; exit 0; }
 tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 mkdir -p "$tmp/f" "$tmp/data/entries"
 node --input-type=module -e 'import sharp from "sharp"; for (let i = 0; i < 60; i++) await sharp({create:{width:40,height:20,channels:3,background:{r:i*4,g:0,b:0}}}).png().toFile(process.argv[1] + "/" + i + ".png")' "$tmp/f"

package/tests/checks/index-degrade.sh

@@ -6,7 +6,7 @@ mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
 # models absent → fts only, skip reported, exit 0
 out=$(LIBRARY_DATA="$tmp" LIBRARY_EMBED= node bin/library.mjs index 2>&1)
 echo "$out" | grep -qE "arms: fts([^,]|$)" || { echo "FAIL: arms without models; got: $out"; exit 1; }
-echo "$out" | grep -q "embeddings: skipped (models absent" || { echo "FAIL: skip line; got: $out"; exit 1; }
+echo "$out" | grep -qE "embeddings: skipped \((models absent|@huggingface/transformers is not installed)" || { echo "FAIL: skip line; got: $out"; exit 1; }
 # stub → both arms, vectors stored with the right dims
 out=$(LIBRARY_DATA="$tmp" LIBRARY_EMBED=stub node bin/library.mjs index 2>&1)
 echo "$out" | grep -q "arms: fts,vec" || { echo "FAIL: arms with stub; got: $out"; exit 1; }

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/measure.sh

@@ -3,6 +3,8 @@ set -eu
 cd "$(dirname "$0")/../.."
 [ -n "${CHROME_PATH:-}" ] || CHROME_PATH=$(command -v google-chrome || command -v chromium || true)
 [ -n "$CHROME_PATH" ] || { echo "SKIP: no chrome/chromium found"; exit 0; }
+node --input-type=module -e 'await import("playwright-core")' 2>/dev/null \
+  || { echo "SKIP: playwright-core not installed"; exit 0; }
 export CHROME_PATH
 tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 mkdir -p "$tmp/entries"
@@ -51,7 +53,9 @@ if (strip.height < single.height * 2) { console.error('FAIL: strip height ' + st
 # refresh re-measures and rewrites captured.at
 out=$(LIBRARY_DATA="$tmp" node bin/library.mjs refresh fx)
 echo "$out" | grep -q '"ok":true' || { echo "FAIL: refresh did not succeed"; echo "$out"; exit 1; }
-today=$(date +%Y-%m-%d)
+# UTC, because measure.mjs writes `new Date().toISOString()`. Using local `date`
+# here fails every evening west of Greenwich, on a correct entry.
+today=$(date -u +%Y-%m-%d)
 grep -Eq "^  at: '?$today'?\$" "$tmp/entries/fx/entry.md" || { echo "FAIL: captured.at not rewritten to today"; cat "$tmp/entries/fx/entry.md"; exit 1; }
 
 # add without --record: strip is just the 1440 screenshot, method is measured (not both)

package/tests/checks/optional-deps.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -eu
+cd "$(dirname "$0")/../.."
+tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/entries"; cp -r tests/fixtures/entry-ok "$tmp/entries/entry-ok"
+
+# A sandbox that genuinely lacks the two optional peers: copy the code, then symlink
+# every real node_modules entry except @huggingface/transformers and playwright-core.
+# Scoped packages are symlinked individually under @scope/, not the scope directory
+# itself — symlinking the scope dir would drag the excluded package back in.
+sandbox="$tmp/sandbox"
+mkdir -p "$sandbox/node_modules"
+cp -r bin src package.json vocab.yaml "$sandbox/"
+for entry in node_modules/*; do
+  name=$(basename "$entry")
+  case "$name" in
+    @*|playwright-core) continue ;;
+  esac
+  ln -s "$PWD/$entry" "$sandbox/node_modules/$name"
+done
+for scope in node_modules/@*; do
+  sname=$(basename "$scope")
+  mkdir -p "$sandbox/node_modules/$sname"
+  for pkg in "$scope"/*; do
+    pname=$(basename "$pkg")
+    [ "$sname/$pname" = "@huggingface/transformers" ] && continue
+    ln -s "$PWD/$pkg" "$sandbox/node_modules/$sname/$pname"
+  done
+done
+[ ! -e "$sandbox/node_modules/playwright-core" ] || { echo "FAIL: sandbox still has playwright-core"; exit 1; }
+[ ! -e "$sandbox/node_modules/@huggingface/transformers" ] || { echo "FAIL: sandbox still has @huggingface/transformers"; exit 1; }
+
+# search over stdio: fts only, skip names the transformers package
+{
+  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":"search","arguments":{"query":"parallax"}}}'
+  sleep 1
+} | LIBRARY_DATA="$tmp" LIBRARY_SEED="$tmp/noseed" timeout 10 node "$sandbox/bin/library.mjs" serve >"$tmp/out" 2>"$tmp/err" || true
+grep -q '"arms":\["fts"\]' "$tmp/out" || { echo "FAIL: arms not fts-only; got:"; cat "$tmp/out"; exit 1; }
+grep -q '"skipped":\[{"arm":"vec","reason":"@huggingface/transformers is not installed"}\]' "$tmp/out" \
+  || { echo "FAIL: skipped reason did not name the transformers package; got:"; cat "$tmp/out"; exit 1; }
+
+# add <https url>: refused, naming playwright-core
+out=$(LIBRARY_DATA="$tmp" node "$sandbox/bin/library.mjs" add https://example.com --slug px-url --title "Px Url" --source own --license x) || true
+echo "$out" | grep -q '"refused"' || { echo "FAIL: https add did not refuse; got: $out"; exit 1; }
+echo "$out" | grep -q "playwright-core is not installed" || { echo "FAIL: refusal did not name playwright-core; got: $out"; exit 1; }
+
+# add <local recording>: still works — the regression a static playwright-core import
+# in measure.mjs would cause, since add.mjs imports measure.mjs unconditionally
+out=$(LIBRARY_DATA="$tmp" node "$sandbox/bin/library.mjs" add "$PWD/tests/fixtures/three-frame.webp" --slug px-local --title "Px Local" --source own --license x)
+echo "$out" | grep -q '"blanks"' || { echo "FAIL: local-file add did not draft; got: $out"; exit 1; }
+[ -f "$tmp/entries/px-local/strip.png" ] || { echo "FAIL: strip.png missing for local-file add"; exit 1; }
+
+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

package/tests/run.sh

@@ -1,10 +1,16 @@
 #!/usr/bin/env bash
 set -u
 cd "$(dirname "$0")/.."
-pass=0; fail=0
+pass=0; fail=0; skip=0
+# A check that cannot run its subject exits 0 after printing SKIP. Counting those as
+# PASS would let a runner missing every tool report a clean suite, which is how three
+# absent-dependency failures reached the publish workflow unnoticed.
 for f in tests/checks/*.sh; do
-  if out=$(bash "$f" 2>&1); then pass=$((pass+1)); echo "PASS $f"
+  if out=$(bash "$f" 2>&1); then
+    if printf '%s' "$out" | grep -q '^SKIP'; then
+      skip=$((skip+1)); echo "SKIP $f  ($(printf '%s' "$out" | grep -m1 '^SKIP' | cut -c7-))"
+    else pass=$((pass+1)); echo "PASS $f"; fi
   else fail=$((fail+1)); echo "FAIL $f"; echo "$out" | tail -20; fi
 done
-echo "PASS=$pass FAIL=$fail"
+echo "PASS=$pass SKIP=$skip FAIL=$fail"
 [ "$fail" -eq 0 ]