@pmeweb/plugin-chat 1.2.1 → 1.3.0

package/INSTALL.md

@@ -90,28 +90,61 @@ package's, approved once.
    `design.colors`. `opener` is `t.chat.openers[path]`, else
    the default filled with the page's title; `logo` only for `avatar: "logo"` (an `?url` import of
    the site's logo). The panel links to `privacyHref`.
-8. **The context file**, `src/pages/plugins/chat/context.json.ts`:
+8. **The context file** (since 1.3.0: what the assistant knows). Three sources, nothing else:
+
+   - **`src/chat/context.<lang>.md`**, one per language of the site (manifest `context`), WRITTEN
+     BY CLAUDE CODE AT INSTALL for the assistant, from the site's pages and dictionary (« The
+     context file » below). Installing the chat is writing this file.
+   - **The pricing source** (`public/pricing.md`, or what the site's `pricing.md` route renders):
+     prices live there only, never in the `.md`.
+   - **The collections listed in `pmeweb.json` `plugins.chat.contextCollections`**
+     (`"portfolio"`, `"realisations,services"`: names separated by commas, no space): one line per
+     published entry, its title and a summary (its `summary`, else `resume`/`description`/`about`...,
+     else the start of its body, cut at 200 characters). Never `blog` or `authors` (the package and
+     the gate refuse them). The portal publishes these entries without Claude Code, so they stay
+     current by themselves. List a collection only when it answers a visitor's question (« avez-vous
+     fait un site pour un couvreur? »).
+
+   The route, `src/pages/plugins/chat/context.json.ts`:
 
    ```ts
-   import { chatContext } from '@pmeweb/plugin-chat/build';
-   import { fr } from '../../../i18n/fr';
-   import { en } from '../../../i18n/en';
-   import { llmsText } from '../../../lib/llms';       // what src/pages/llms.txt.ts renders
-   import { pricingText } from '../../../lib/pricing'; // the source of public/pricing.md
+   import { getCollection } from 'astro:content';
+   import { chatContext, contextCollections } from '@pmeweb/plugin-chat/build';
+   import site from '../../../../pmeweb.json';
+   import pricing from '../../../../public/pricing.md?raw';
+   import contextFr from '../../../chat/context.fr.md?raw';
+   import contextEn from '../../../chat/context.en.md?raw';
    export const prerender = true;
-   export const GET = async () => new Response(chatContext({
-     langs: {
-       fr: { business: 'Nom', llms: await llmsText('fr'), pricing: pricingText('fr'), dictionary: fr },
-       en: { business: 'Name', llms: await llmsText('en'), pricing: pricingText('en'), dictionary: en },
-     },
-     collections: [/* published entries: { collection, lang?, title, data, body } */],
-   }));
+   export const GET = async () => {
+     const entries = [];
+     for (const name of contextCollections(site.plugins?.chat?.contextCollections)) {
+       for (const e of getPublished(await getCollection(name))) {   // the site's own filter
+         entries.push({ collection: name, label: 'Réalisations', lang: e.data.lang, title: e.data.titre, data: e.data, body: e.body });
+       }
+     }
+     return new Response(chatContext({
+       langs: { fr: { business: 'Nom', context: contextFr, pricing }, en: { business: 'Name', context: contextEn, pricing } },
+       collections: entries,
+     }));
+   };
    ```
 
-   The `lib/` names differ per site: read its `src/pages/llms.txt.ts` and pricing module and import
-   what they export (extract a function if the page inlines it). Never read `dist/` from a route.
-   Collections through `getPublished` only. A French-only site passes `fr` alone. Above 200 KB the
-   build fails.
+   `title` is the collection's `titleField`; `summary` may be composed by the site when no single
+   field says it (pmeweb: the portfolio's industry, then its « about »). A French-only site passes
+   `fr` alone. Never read `dist/` from a route. The build fails on a missing or empty `.md`, a `.md`
+   over 16 000 characters, a blog collection, or a file over 200 KB.
+
+   **The gate.** `a11y-tools/check-plugins.mjs` (pre-push and the builder's « Publier » preflight)
+   FAILS when a language's file is missing, over 16 000 characters, contains a price, names a blog
+   collection in `contextCollections`, or when its first line's fingerprint
+   (`<!-- chat-context sources:<16 hex> -->`) is not the hash of the site's current sources: its
+   dictionaries `src/i18n/*.ts`, its pricing source (`public/pricing.md`,
+   `src/{lib,data}/{prices,pricing}.*`) and its page files under `src/pages` (the blog routes,
+   `plugins/` and `og-card/` excluded). After writing or reviewing the files, from the site:
+   `node ../../a11y-tools/chat-context.mjs --stamp`. Renewing the stamp is a deliberate act after a
+   review, never a reflex to make the gate pass: read what changed, put in the file what is new
+   information for a visitor (a section, a service, a process, a policy), then stamp.
+
 9. **Privacy**: nothing to paste. `<PluginPrivacy>` renders the package's section (and the voip.ms
    and photos paragraphs when those keys are set), only while `enabled` is true: it needs
    `@pmeweb/consent` 1.1.0 or later (manifest `activeWhen`; 1.0.0 would print it switched off, and
@@ -127,3 +160,42 @@ package's, approved once.
 13. Deploy (still off: nothing on the site, health `disabled`). Once the client or the operator
     switches it on and publishes, from a real host: the bubble shows, a question gets an answer, the signed health
     route answers `chat.ok`.
+
+## The context file
+
+Written for the assistant, not for a visitor; it is never published. Read every page of the site
+(`src/pages`, the components they render, the dictionary of the language) and the legal pages,
+then write, in the site's language and wording, answer-shaped plain facts under `## ` headings
+(each heading becomes a section the model reads):
+
+- the business: what it does, for whom, where, its languages; the legal name and city when a page
+  already says them;
+- the offer: each service or product and what it includes, in the site's own words;
+- the process and the timelines;
+- the frequent questions the site answers (its FAQ blocks, its terms: payment, cancellation,
+  ownership), each as a fact;
+- what the business does not do, only where the site says so (never deduced from silence);
+- how to reach it: form address, email, phone, hours, response time.
+
+Rules: nothing that is not already public on the site (workspace rule: never newly publish client
+information); **no price** (the gate refuses `$` with a digit; write « voir Tarifs »); no blog
+post; no marketing adjectives, no em-dash, OQLF typography in French (`docs/AVOIDING_AI_TELLS.md`);
+16 000 characters at most per language (pmeweb.ca: about 10 000). Then stamp it.
+
+**Every later site change that adds or changes information** (a section, a service, a process, a
+policy) updates the file in the same change; the gate says when the sources moved. Blog posts
+never go in.
+
+## Updating from 1.2.1
+
+1.3.0 changes what the context is built from (1.2.1 sent llms.txt, the whole dictionary and every
+entry's full text: about 26 000 tokens per reply on pmeweb.ca, mostly interface labels).
+`context.json` keeps format 1; pmeweb-chat needs no change.
+
+1. Write `src/chat/context.<lang>.md` for each language (« The context file »), then
+   `node ../../a11y-tools/chat-context.mjs --stamp`.
+2. Rewrite `src/pages/plugins/chat/context.json.ts` as in step 8: `chatContext` no longer accepts
+   `llms` or `dictionary` (the build throws naming this section). Drop the blog posts.
+3. If a collection helps answer visitors, list it: `"contextCollections": "portfolio"` in
+   `pmeweb.json` `plugins.chat`.
+4. `npm run build && node ../../a11y-tools/check-plugins.mjs .` until PASS.

package/README.md

@@ -17,6 +17,22 @@ Three pieces:
 
 Install it with the `install-plugin` skill (`INSTALL.md`).
 
+## What the assistant knows (1.3.0)
+
+`plugins/chat/context.json` (format 1, unchanged) is built from three sources only:
+`src/chat/context.<lang>.md`, a file Claude Code writes for the assistant from the site (the
+business, the offer and what it includes, the process, the frequent questions, what the business
+does not do, how to reach it; no price, nothing not already public), the site's pricing source,
+and the collections listed in `pmeweb.json` `plugins.chat.contextCollections` as one line per
+entry (title and a 200-character summary). Never the blog, the dictionary or llms.txt. On
+pmeweb.ca that is about 4 500 input tokens per reply instead of 22 300 (measured 2026-11-13, 38 replies each).
+
+The `.md` carries a fingerprint of the site's sources on its first line;
+`a11y-tools/check-plugins.mjs` fails a push (and the builder's preflight) when the site changed
+since the last review, until someone rereads the change, updates the file and runs
+`node ../../a11y-tools/chat-context.mjs --stamp`. Details: `INSTALL.md`, step 8 and « The context
+file ».
+
 ## Behaviour worth knowing
 
 - **A demo in the preview** (manifest `preview: "test"`). Off the site's real hosts
@@ -153,6 +169,9 @@ site changes with `a11y-tools/contrast.mjs`.
   says `settings: false`.
 - The context file absent from `dist/` or not served signed: the bot falls back to the contact form
   on every message.
+- A fact the site states but `src/chat/context.<lang>.md` does not: the bot says it does not know.
+  The fingerprint catches changes to the dictionaries, the pricing source and `src/pages`, not to a
+  component that hardcodes text (a site's copy belongs in its dictionary).
 
 ## Avatars
 

package/manifest.json

@@ -15,7 +15,8 @@
     "sms": { "pattern": "^voipms$", "optional": true },
     "photos": { "type": "boolean", "optional": true },
     "avatar": { "pattern": "^(?:photos-[1-5]|illustration-[1-5]|sans-visage-[1-5]|logo)$" },
-    "avatarBg": { "pattern": "^#[0-9a-f]{6}$", "optional": true }
+    "avatarBg": { "pattern": "^#[0-9a-f]{6}$", "optional": true },
+    "contextCollections": { "pattern": "^[a-z][a-z0-9-]*(?:,[a-z][a-z0-9-]*)*$", "optional": true }
   },
   "bindings": [
     { "kind": "service", "binding": "CHAT", "service": "pmeweb-chat", "entrypoint": "ChatApi" },
@@ -33,6 +34,7 @@
   },
   "markup": { "pages": "all", "required": ["#pmw-chat", "[data-pmw-chat-opener]"] },
   "build": ["plugins/chat/context.json"],
+  "context": { "file": "src/chat/context.{lang}.md", "maxChars": 16000 },
   "portal": {
   "screens": [
     { "key": "appearance",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmeweb/plugin-chat",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "PmeWeb chat plugin: the bubble, the lazy chat panel, the site Worker's /api/chat routes and the build-time context file. The conversations, the model and the alerts live in the pmeweb-chat service.",
   "type": "module",
   "license": "MIT",

package/src/build.d.ts

@@ -1,30 +1,45 @@
 export declare const CONTEXT_FORMAT: 1
 export declare const MAX_CONTEXT_BYTES: number
+/** The curated file's budget per language, stamp line excluded. */
+export declare const MAX_CONTEXT_CHARS: number
+export declare const SUMMARY_CHARS: number
+export declare const SUMMARY_FIELDS: readonly string[]
+/** blog and authors: never in the context. */
+export declare const NEVER_COLLECTIONS: readonly string[]
+
+type Localized = string | Partial<Record<'fr' | 'en', string>>
 
 export interface ChatContextLang {
   /** The business's name in this language (the bot says it; pmeweb-chat falls back to the host). */
   business?: string
-  /** What src/pages/llms.txt.ts renders for this language. */
-  llms?: string
-  /** The pricing text (the source of public/pricing.md). */
+  /** The text of src/chat/context.<lang>.md (the stamp line is removed here). Required. */
+  context: string
+  /** The pricing text (the site's pricing source, public/pricing.md on most sites). */
   pricing?: string
-  /** src/i18n/<lang>.ts: flattened to `key: value` lines, strings only. */
-  dictionary?: object
 }
 
 export interface ChatContextEntry {
+  /** A collection listed in plugins.chat.contextCollections; never blog or authors. */
   collection: string
+  /** The section's title (default: the collection's name). */
+  label?: Localized
   /** Absent: the entry belongs to every language. */
   lang?: 'fr' | 'en'
   title: string
+  /** The entry's one line; absent: its summary-like field (SUMMARY_FIELDS), else its body. Cut at 200 characters. */
+  summary?: Localized
   data?: Record<string, unknown>
   body?: string
 }
 
-/** The JSON text of plugins/chat/context.json. Deterministic; throws above 200 KB or on an empty language. */
+/** The JSON text of plugins/chat/context.json. Deterministic; throws on a missing or oversized curated file. */
 export declare function chatContext(sources: {
   langs: Partial<Record<'fr' | 'en', ChatContextLang>>
   collections?: ChatContextEntry[]
 }): string
 
-export declare function flattenDictionary(dict: object, prefix?: string): string
+/** `plugins.chat.contextCollections` as a list of collection names; throws on blog or authors. */
+export declare function contextCollections(value: unknown): string[]
+export declare function entrySummary(entry: ChatContextEntry, lang: 'fr' | 'en'): string
+export declare function stripStamp(md: string): string
+export declare function contextSections(md: string, fallbackTitle: string): { title: string; text: string }[]

package/src/build.js

@@ -1,58 +1,125 @@
 // @pmeweb/plugin-chat/build: the site's context file for pmeweb-chat (manifest `build`:
 // plugins/chat/context.json, one file for every language). The site renders it from a prerendered
-// route with sources it already has (llms.txt, its pricing text, its dictionaries, its published
-// collection entries); pmeweb-chat reads `langs[lang]` (src/context.ts there):
+// route; pmeweb-chat reads `langs[lang]` (src/context.ts there):
 //
 //   { "format": 1, "langs": { "fr": { "business": "...", "sections": [{ "title", "text" }] } } }
 //
+// Since 1.3.0 the sources are three, and only three (operator decision 2026-11-13):
+//   1. the site's curated file, src/chat/context.<lang>.md (manifest `context`), written by Claude
+//      Code for the assistant and held current by check-plugins' fingerprint. Its `## ` headings
+//      become the sections; the first-line stamp comment is not sent.
+//   2. the pricing text (the site's pricing source, public/pricing.md on most sites): prices are
+//      never copied into the curated file.
+//   3. the entries of the collections the site lists in `plugins.chat.contextCollections`, one line
+//      each (title and a short summary, never the body). Blog posts never go in.
+// The dictionary and llms.txt are no longer read (1.2.0 sent them whole: ~26 000 tokens on pmeweb.ca,
+// mostly interface labels).
+//
 // DETERMINISTIC: same sources, same bytes. No date, no random id, no network, no model call (the
 // builder holds no secret, and a rebuild must not spend money). Not public: the site's worker serves
 // it only to a signed request (plugin-kit's pluginArtifacts), never to a visitor.
 
 export const CONTEXT_FORMAT = 1
-/** About 50k tokens at most: past this the prompt would cost too much per message. */
+/** A last guard on the whole file; the curated file has its own, smaller budget (MAX_CONTEXT_CHARS). */
 export const MAX_CONTEXT_BYTES = 200 * 1024
+/** The curated file's budget per language, stamp line excluded (equal to the manifest's `context.maxChars`). */
+export const MAX_CONTEXT_CHARS = 16000
+/** An entry's summary is cut here, at a word. */
+export const SUMMARY_CHARS = 200
+/** The fields an entry's summary is taken from, in this order, before its body. */
+export const SUMMARY_FIELDS = ['summary', 'resume', 'résumé', 'description', 'excerpt', 'extrait', 'about', 'apropos', 'intro']
+/** Collections that never go in the context, whatever the config says. */
+export const NEVER_COLLECTIONS = ['blog', 'authors']
 
 const LANGS = ['fr', 'en']
 const TITLES = {
-  fr: { llms: 'llms.txt', pricing: 'Tarifs', dictionary: 'Textes du site', colon: ' : ' },
-  en: { llms: 'llms.txt', pricing: 'Pricing', dictionary: 'Site text', colon: ': ' },
+  fr: { pricing: 'Tarifs', colon: ' : ' },
+  en: { pricing: 'Pricing', colon: ': ' },
 }
 
 const text = (v) => (typeof v === 'string' ? v.trim() : '')
 const oneLine = (v) => v.replace(/\s*\n\s*/g, ' ').trim()
 
-/** A dictionary as `path.to.key: value` lines, strings only, in the dictionary's own order. */
-export function flattenDictionary(dict, prefix = '') {
+/** The curated file's text, its leading HTML comments (the stamp) removed. */
+export function stripStamp(md) {
+  return text(md).replace(/^(?:<!--[\s\S]*?-->\s*)+/, '').trim()
+}
+
+/**
+ * The curated file as sections: one per `## ` heading; what comes before the first one is a
+ * section titled by the `# ` heading (else `fallbackTitle`).
+ */
+export function contextSections(md, fallbackTitle) {
   const out = []
-  const walk = (v, path) => {
-    if (typeof v === 'string') {
-      if (v.trim() !== '') out.push(`${path}: ${oneLine(v)}`)
-    } else if (Array.isArray(v)) {
-      v.forEach((x, i) => walk(x, path ? `${path}.${i}` : String(i)))
-    } else if (v && typeof v === 'object') {
-      for (const [k, x] of Object.entries(v)) walk(x, path ? `${path}.${k}` : k)
-    }
+  let title = fallbackTitle
+  let lines = []
+  const flush = () => {
+    const t = lines.join('\n').trim()
+    if (t) out.push({ title, text: t })
+    lines = []
+  }
+  for (const line of stripStamp(md).split(/\r?\n/)) {
+    const h1 = /^#\s+(.+?)\s*$/.exec(line)
+    const h2 = /^##\s+(.+?)\s*$/.exec(line)
+    if (h1 && out.length === 0 && lines.every((l) => l.trim() === '')) { title = h1[1]; continue }
+    if (h2) { flush(); title = h2[1]; continue }
+    lines.push(line)
   }
-  walk(dict, prefix)
-  return out.join('\n')
+  flush()
+  return out
+}
+
+/** `plugins.chat.contextCollections` ("portfolio,services") as a list; refuses the blog and its authors. */
+export function contextCollections(value) {
+  if (value === undefined || value === null || value === '') return []
+  if (typeof value !== 'string') throw new Error('chat : contextCollections est une chaîne, des noms de collections séparés par des virgules')
+  const names = value.split(',').map((s) => s.trim()).filter(Boolean)
+  const never = names.filter((n) => NEVER_COLLECTIONS.includes(n))
+  if (never.length) throw new Error(`chat : ${never.join(', ')} n'entre jamais dans le contexte (les articles et leurs auteurs restent sur le site)`)
+  return names
 }
 
-/** One collection entry: its string fields as `key: value` lines (the title itself left out), then its body. */
-function entryText(e) {
-  const lines = []
-  for (const [k, v] of Object.entries(e.data ?? {})) {
-    if (typeof v !== 'string' || v.trim() === '' || v === e.title) continue
-    lines.push(`${k}: ${oneLine(v)}`)
+/** Markdown reduced to plain words: links to their text, images, emphasis and heading marks gone. */
+function plain(md) {
+  return md
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/^#{1,6}\s+/gm, '')
+    .replace(/[*_`>]+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/** Cut at a word, at most `max` characters plus the ellipsis. */
+function cut(s, max) {
+  if (s.length <= max) return s
+  const head = s.slice(0, max)
+  const at = head.lastIndexOf(' ')
+  return `${(at > max * 0.6 ? head.slice(0, at) : head).replace(/[\s,;:.]+$/, '')}…`
+}
+
+/** A field's value in `lang`: a string, or a `{ fr, en }` object. */
+function inLang(v, lang) {
+  if (typeof v === 'string') return v
+  if (v && typeof v === 'object' && typeof v[lang] === 'string') return v[lang]
+  return ''
+}
+
+/** An entry's one-line summary: `summary`, else its first summary-like field, else its body; 200 characters at most. */
+export function entrySummary(e, lang) {
+  let s = inLang(e.summary, lang)
+  for (const k of SUMMARY_FIELDS) {
+    if (text(s)) break
+    s = inLang(e.data?.[k], lang)
   }
-  const body = text(e.body)
-  return [lines.join('\n'), body].filter(Boolean).join('\n\n')
+  if (!text(s)) s = text(e.body)
+  return cut(plain(oneLine(s)), SUMMARY_CHARS)
 }
 
 /**
  * @param {{
- *   langs: Partial<Record<'fr' | 'en', { business?: string, llms?: string, pricing?: string, dictionary?: object }>>,
- *   collections?: { collection: string, lang?: 'fr' | 'en', title: string, data?: Record<string, unknown>, body?: string }[],
+ *   langs: Partial<Record<'fr' | 'en', { business?: string, context?: string, pricing?: string }>>,
+ *   collections?: { collection: string, label?: string | Record<string, string>, lang?: 'fr' | 'en', title: string, summary?: string | Record<string, string>, data?: Record<string, unknown>, body?: string }[],
  * }} sources an entry with no `lang` belongs to every language
  * @returns {string} the JSON text of plugins/chat/context.json
  */
@@ -61,22 +128,38 @@ export function chatContext({ langs = {}, collections = [] } = {}) {
   if (keys.length === 0 || keys.some((l) => !LANGS.includes(l))) {
     throw new Error(`chat : une langue fr ou en au moins, et aucune autre (reçu ${keys.join(', ') || 'rien'})`)
   }
+  for (const l of keys) {
+    const old = ['llms', 'dictionary'].filter((k) => langs[l]?.[k] !== undefined)
+    if (old.length) throw new Error(`chat : ${old.join(' et ')} ne sont plus lus depuis 1.3.0 ; passer context (src/chat/context.${l}.md), voir INSTALL.md « Updating from 1.2.1 »`)
+  }
+  for (const e of collections) {
+    if (NEVER_COLLECTIONS.includes(e.collection)) throw new Error(`chat : la collection ${e.collection} n'entre jamais dans le contexte`)
+  }
   const out = { format: CONTEXT_FORMAT, langs: {} }
   for (const lang of LANGS.filter((l) => keys.includes(l))) {
     const src = langs[lang] ?? {}
     const t = TITLES[lang]
-    const sections = []
-    const add = (title, body) => { if (body) sections.push({ title, text: body }) }
-    add(t.llms, text(src.llms))
-    add(t.pricing, text(src.pricing))
-    add(t.dictionary, src.dictionary ? flattenDictionary(src.dictionary) : '')
+    const business = text(src.business)
+    const curated = stripStamp(src.context ?? '')
+    if (!curated) throw new Error(`chat : src/chat/context.${lang}.md absent ou vide (le contexte de l'assistant)`)
+    if (curated.length > MAX_CONTEXT_CHARS) throw new Error(`chat : src/chat/context.${lang}.md fait ${curated.length} caractères, au-delà de ${MAX_CONTEXT_CHARS}`)
+    const sections = contextSections(curated, business || (lang === 'fr' ? 'Entreprise' : 'Business'))
+    const pricing = text(src.pricing)
+    if (pricing) sections.push({ title: t.pricing, text: pricing })
+    // One section per collection, one line per entry, in the order the site gives them.
+    const groups = new Map()
     for (const e of collections) {
       if (e.lang !== undefined && e.lang !== lang) continue
-      add(`${e.collection}${t.colon}${text(e.title)}`, entryText(e))
+      const title = oneLine(text(e.title))
+      if (!title) continue
+      const label = inLang(e.label, lang) || e.collection
+      if (!groups.has(label)) groups.set(label, [])
+      const summary = entrySummary(e, lang)
+      groups.get(label).push(summary ? `- ${title}${t.colon}${summary}` : `- ${title}`)
     }
-    if (sections.length === 0) throw new Error(`chat : contexte ${lang} vide`)
+    for (const [label, lines] of groups) sections.push({ title: label, text: lines.join('\n') })
     const part = {}
-    if (text(src.business)) part.business = text(src.business)
+    if (business) part.business = business
     part.sections = sections
     out.langs[lang] = part
   }

package/src/worker.js

@@ -32,7 +32,7 @@ import { verifyTurnstile } from '@pmeweb/turnstile/worker'
 import { RPC_HEADER, RPC_VERSION } from './protocol.js'
 
 /** This package's version, reported by the health route (a test holds it equal to package.json). */
-export const VERSION = '1.2.1'
+export const VERSION = '1.3.0'
 export { RPC_VERSION }
 
 const SERVICE = 'https://pmeweb-chat.internal'