@cavuno/board 3.2.0 → 4.0.0

package/skills/cavuno-board-format/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: cavuno-board-format
-description: Board-language display formatting with @cavuno/board/format. Use for salary ranges, dates, job labels, location labels, card conversion, or salary metadata copy.
+description: Board-language display formatting with @cavuno/board/format. Use for salary ranges, dates, custom-field display, or salary-stat numbers.
 ---
 
 # Display formatting
 
-`@cavuno/board/format` matches the hosted board's display rules. Read the
-board language once and pass it as the required first argument to every
-label-producing helper.
+`@cavuno/board/format` matches the hosted board's display rules for
+**contract and data-shaping** helpers. Chrome words (enum→label, uiCopy,
+salary lexicon) are application-owned and are not exported here.
+
+Read the board language once and pass it as the required first argument to
+every label-producing helper.
 
 Filter controls use `cavuno-board-filters`. Salary values remain in their wire
 currency and retain their server-computed amounts.
@@ -16,87 +19,96 @@ currency and retain their server-computed amounts.
 
 ```ts snippet
 import {
-  fieldLabel,
   formatDate,
   formatPublishedRelativeDate,
   formatSalaryRange,
+  formatSalaryStat,
+  formatSalaryStatRange,
+  resolveCustomFieldDisplay,
 } from '@cavuno/board/format';
 
 const { language } = await board.context();
 
-formatSalaryRange(
+const salary = formatSalaryRange(
   language,
   job.salaryMin,
   job.salaryMax,
   job.salaryTimeframe,
   job.salaryCurrency);
+// salary: { text, timeframe, bound: 'range' | 'from' | 'upTo' } | null
+// Pieces — application composes order (do not paste a join template):
+// text       = Intl amount/range (e.g. "$90–120K", "90.000–120.000 €")
+// timeframe  = the WIRE ENUM ("per_year" … "per_hour") or null —
+// never a word. Map it through your own catalog.
+// bound      = which open-range chrome word to attach, if any
+// When joining text + timeframe (or any mixed-direction operands), isolate
+// each side: U+2066 FSI … U+2069 PDI, or HTML <bdi> / dir="auto".
+// Small rates default to standard by magnitude (|value| < 1000) so
+// cents survive: formatSalaryRange(lang, 22.5, null, 'per_hour', 'USD')
+// → { text: "$22.50", timeframe: "per_hour", bound: "from" }
+// Pass notation 'compact' only when you want forced compact glue.
 formatPublishedRelativeDate(language, job.publishedAt);
 formatDate(language, job.publishedAt);
-fieldLabel(language, job.seniority);
+
+// Salary-page stats (currency required — not USD-hardcoded).
+// notation matches formatSalaryRange: omit for magnitude default
+// (|value| ≥ 1000 → compact; smaller → standard). Pass 'standard' for
+// full figures ($90,000) or 'compact' to force short form.
+formatSalaryStat(language, 90000, detail.currency);
+formatSalaryStatRange(language, 90000, 120000, detail.currency);
+formatSalaryStatRange(language, 90000, 120000, detail.currency, 'standard');
+
+// Custom fields — language first. number → kind: 'number' (raw);
+// multi_select → kind: 'multi_select' with values: string[] (labels).
+// Do not String(n). Do not join multi-select in the SDK — app owns list
+// style (conjunction / short / chips):
+// new Intl.ListFormat(language, { style: 'long', type: 'conjunction' })
+// .format(entry.values)
+const fields = resolveCustomFieldDisplay(
+  language,
+  context.customFields.job,
+  job.customFieldValues);
 ```
 
-`formatPublishedRelativeDate` produces the compact relative value used on job
-cards and the job-detail header, such as `5d ago`. `formatDate` produces the
-UTC-pinned medium date used in blog metadata and detail facts, such as
-`Jun 24, 2026`. This format surface limits relative time to the compact
-job-publication label.
+`formatPublishedRelativeDate` produces the short relative value used on job
+cards and the job-detail header (locale-owned RTF `style: 'short'`). `formatDate`
+and `formatMonthYear` produce UTC-pinned absolute forms for blog metadata
+and detail facts.
 
-Salary timeframe and seniority copy is localized for English and German;
-other locales use English words with locale-correct number formatting.
-Employment and remote labels remain English across board languages because
-the hosted board currently has no translated vocabulary for them.
+The salary timeframe ships as the wire enum on `timeframe` alone —
+not glued to `text` with a space or `/`. Open-range chrome is also
+application-owned via `bound`. Compose amount, unit, and chrome in
+board-language order (prefix, postfix, particles, no-space gluing for ja/zh),
+with bidi isolation when directions may differ.
 
-## Render locations and saved-job cards
+Missing/`null` currency is not treated as USD: helpers return `null`. Pass the
+job's real `salaryCurrency`. Invalid or unsupported locales return `null`
+rather than English or host-default fallbacks; underscore tags like `ja_JP`
+are normalized to BCP-47 and checked with `Intl.NumberFormat.supportedLocalesOf`.
 
-Cards already contain server-computed location labels. Full `PublicJob`
-detail requires the full-job formatter. Convert a full saved job before
-placing it in a card collection.
+## Saved-job cards
 
-```ts snippet
-import {
-  cardLocationLabel,
-  fullJobToCard,
-  locationLabel,
-} from '@cavuno/board/format';
-
-cardLocationLabel(language, card);
-locationLabel(language, job);
-const savedCard = fullJobToCard(language, job);
-```
-
-## Build salary metadata copy
-
-`getSalaryLexicon` exposes hosted salary terminology and sentence frames.
+`me/saved-jobs` embeds the same slim `job_card` as the jobs list. Map it with
+the same card view-model as listings — do not convert a full job client-side.
 
 ```ts snippet
-import { getSalaryLexicon } from '@cavuno/board/format';
-
-const lexicon = getSalaryLexicon(language);
-lexicon.frames.entitySalariesTitle({
-  entity: 'JavaScript',
-  range: '$70K – $90K',
-});
-lexicon.seniority.senior;
+// saved.job is already PublicJobCard
+const card = toJobCardVM(saved.job, { language, /* … */ });
 ```
 
-Use the helpers as the formatting boundary: pass the board language, wire
-amounts, wire currency, and server location data in; render the returned text.
-This keeps symbol placement, timeframe copy, number rules, and hosted labels
-aligned. Sort-dropdown copy remains in `cavuno-board-filters`.
-
 ## Completion gate
 
 Finish only after every applicable check passes:
 
 - Every label-producing call receives `board.context().language`; no call site
-  substitutes a hardcoded locale.
-- A German board renders `pro Jahr`, `ab`, and `Führungskraft` where the same
-  path renders `Yearly`, `From`, and `Executive` in English.
-- English salary strings are byte-identical to the hosted board for the same
-  wire job.
-- Cards use `cardLocationLabel`; full jobs use `locationLabel`; saved full jobs
-  are converted with `fullJobToCard` before card rendering.
-- Formatting changes neither salary amounts nor currency.
+  substitutes a hardcoded locale or relies on a silent `en` default.
+- Amount and timeframe stay separate until the application joins them; the SDK
+  does not emit a pre-joined `"$90K / year"`.
+- Open ranges return `bound: 'from' | 'upTo'`; the application adds open-range
+  chrome and composes order itself.
+- Saved jobs arrive as cards; no `fullJobToCard` conversion.
+- Salary-stat formatters receive the detail's `currency` (never invent USD).
+- Formatting changes neither salary amounts nor invents chrome words.
 
 ## Cavuno SDK reference
 

package/skills/cavuno-board-i18n/SKILL.md

@@ -1,55 +1,136 @@
 ---
 name: cavuno-board-i18n
-description: One-seam board localization with @cavuno/board. Use when localizing UI chrome, adding locale routing, merging operator labels, or preserving board-language content.
+description: One-seam board localization with @cavuno/board. Use when localizing UI chrome, adding locale routing, or preserving board-language content.
 ---
 
 # One-seam board localization
 
 A Cavuno board has one content language: `board.context().language`. Jobs, companies, and blog content remain in that API-served language. Multi-locale frontends localize chrome—labels, headings, filters, and FAQ scaffolding—plus entity data the API already translates, such as taxonomy, places, and salary names.
 
-## Build the copy seam
-
-All UI strings resolve through one application module. Layer copy in this order:
+## Own the chrome catalog
 
-1. `uiCopy(language)` provides the versioned `en`, `de`, and `fr` catalog, including functions for pluralized keys.
-2. `board.context().labels` overlays operator-specific labels.
-3. Generated application copy overlays both when the builder ejects native code.
+Applications own chrome words. The SDK does not export a chrome-copy runtime
+or seed `messages/`. Keep a typed copy seam in application code
+(the starter already commits `messages/*.json` for en/de/fr).
 
 ```ts snippet
-import {
-  uiCopy,
-  type BoardLabelOverrides,
-} from '@cavuno/board/format';
-
-export function boardCopy(
-  language: string | undefined,
-  labels?: BoardLabelOverrides) {
-  return uiCopy(language, labels);
-}
+// Application-owned: load messages/ for the active locale and expose a
+// seam components import. Shape is a fixed set of string groups (jobCard,
+// jobSearch, jobDetail, apply, alerts, …).
+export type BoardCopy = {
+  jobCard: { featuredLabel: string; /* … */ };
+  // …
+};
 ```
 
-Components import this seam rather than the catalog. That keeps the catalog-to-generated-code transition to one module.
+## Build the copy seam
+
+All UI strings resolve through one application module. Prefer compile-time messages (Paraglide / inlang) fed by application-owned `messages/` files:
+
+1. Keep `messages/` in the application (or starter).
+2. Compile messages with your framework's i18n tool.
+3. Expose one seam modules components import (`src/copy.ts` or equivalent).
+
+Components import this seam rather than reading JSON ad hoc. That keeps the catalog-to-generated-code transition to one module.
 
 ## Add locales
 
 Use the installed framework and i18n guidance for routing, SSR locale detection, link rewriting, and compiled messages. Keep the board language unprefixed at `/` and prefix additional locales such as `/de/` or `/fr/`. Preserve these Cavuno invariants while doing so:
 
-1. Generate locale messages from `uiCopy(locale)` so reviewed SDK copy remains the translation source. This step is complete when every supported locale's chrome keys are generated from the catalog.
-2. Point the seam at the URL locale and merge the current board's label overrides. This step is complete when switching locale changes chrome while retaining operator labels.
+1. Start from your application message catalogs so chrome wording is under version control with the app.
+2. Point the seam at the URL locale. This step is complete when switching locale changes chrome.
 3. Keep API content in `board.context().language`. This step is complete when locale switching leaves job, company, and blog fields unchanged.
 4. Emit locale-aware `<html lang>`, canonical URLs, `hreflang`, and sitemap entries. This step is complete when each public locale route declares itself and all alternates consistently.
 
 A compile-time i18n system can replace the seam's backing source. Keep the seam provider-free unless the chosen framework integration itself requires a provider.
 
+## Own the five  obligations
+
+The SDK formats amounts, units, and relative dates with `Intl` and returns
+structure. It does **not** ship plural selection, gender agreement, bidi
+isolation, grapheme-safe truncation, or locale-aware case mapping. Those
+five are application-owned. Satisfying the chrome / routing
+gates alone is not enough — a board that ships without plural rules or
+bidi isolation still fails this skill.
+
+### Plural selection
+
+Never branch on `count === 1`. Use `Intl.PluralRules` for the active locale
+and pick the catalog form for the returned category:
+
+```ts snippet
+const pr = new Intl.PluralRules(locale);
+// categories: zero | one | two | few | many | other (locale-dependent)
+const form = messages.jobCount[pr.select(count)];
+// en: { one: "{n} job", other: "{n} jobs" }
+// ar: { zero, one, two, few, many, other } — all six can be required
+const label = form.replace('{n}', new Intl.NumberFormat(locale).format(count));
+```
+
+Use this for every count-bearing chrome string (search results, FAQ sample
+sizes, alert copy). Do not hardcode English `-s`.
+
+### Gender agreement
+
+When a catalog string agrees with a person or role (adjectives, participles
+in fr/de/ru/…), store gendered variants in the catalog and select by the
+entity's gender metadata — do not invent agreement in code from English
+stems.
+
+### Bidi isolation
+
+When composing SDK display strings with chrome or with mixed-direction
+data (Latin company name inside an RTL sentence is the standard case),
+isolate each operand whose direction may differ:
+
+```ts snippet
+const FSI = '\u2066'; // FIRST STRONG ISOLATE
+const PDI = '\u2069'; // POP DIRECTIONAL ISOLATE
+// Prefer HTML <bdi> / dir="auto" in markup; FSI/PDI in plain-text joins.
+// `salary.timeframe` is the wire enum (`per_year`) — resolve it through
+// your catalog first, then isolate both operands before joining.
+const unit = salary.timeframe ? m[`salary_${salary.timeframe}`]() : '';
+const line = `${FSI}${salary.text}${PDI} ${FSI}${unit}${PDI}`;
+```
+
+Never paste a bare `` `${amount} ${label}` `` into RTL chrome without
+isolation. The SDK returns bare `string` values on purpose — isolation is
+app-owned at the join site.
+
+### Grapheme-safe truncation
+
+Do not slice with `string.length` / `substring` on user-visible text.
+Count grapheme clusters (`Intl.Segmenter` with `granularity: 'grapheme'`,
+or a well-tested grapheme library) so emoji ZWJ sequences and combining
+marks are not split.
+
+### Locale-aware case mapping
+
+Use `toLocaleLowerCase(locale)` / `toLocaleUpperCase(locale)` for display
+case (Turkish `i`/`İ`, Greek final sigma). Keep identifier folding
+(`toLowerCase` without locale) only for URL slugs and Set keys — the SDK
+does that on purpose.
+
+### Native digits
+
+When formatting numbers the app owns (custom-field `kind: 'number'`,
+counts, pagination), use `Intl.NumberFormat(locale)` so native-digit
+locales (`ar`, `bn`, `hi-u-nu-deva`, …) render correctly. Never
+`String(n)` for display.
+
 ## Completion gate
 
 - Every authored chrome string enters components through the copy seam.
-- `uiCopy` plus `board.context().labels` resolves the expected operator override.
+- Chrome comes from application messages, not from `board.context()` (the API no longer serves a labels bag).
 - Each supported locale renders translated chrome at its public URL.
 - Switching locale preserves API-served job, company, and blog content.
 - Server HTML uses the active locale in `<html lang>` with no hydration mismatch.
 - Canonical, `hreflang`, and sitemap URLs agree for every locale route.
 - Missing translation keys fail generation or tests rather than appearing as raw keys.
+- Count-bearing chrome uses `Intl.PluralRules` (no `count === 1` English branches).
+- Composed display strings that mix directions isolate operands (FSI/PDI or `<bdi>`).
+- Visible truncation is grapheme-safe; display case mapping uses the locale.
+- App-owned numbers format via `Intl.NumberFormat`, not `String(n)`.
 
 ## Cavuno SDK reference
 

package/skills/cavuno-board-search-suggestions/SKILL.md

@@ -5,9 +5,9 @@ description: Build server-ranked search suggestions with @cavuno/board. Use for
 
 # Server-ranked search suggestions
 
-`board.search.suggest` returns one interleaved list of companies and taxonomy terms. Server rank is the contract: render its order unchanged. For UI, the headless controller adds debounce, abort, and stale-result dropping.
+`board.search.suggest` returns one interleaved list of companies, markets, taxonomy terms, blog posts, and tags. Pass `types` to restrict kinds; `limit` applies after that filter. Server rank is the contract: render its order unchanged. For UI, the headless controller adds debounce, abort, and stale-result dropping.
 
-Location autocomplete uses `board.taxonomy.places.list({ q })`; filter option lists use `board.taxonomy.categories.list`, `board.taxonomy.skills.list`, or `board.taxonomy.suggestions.list`; job results use `board.jobs.list` or `board.jobs.search`.
+Location autocomplete uses `board.taxonomy.places.list({ q })`; filter option lists use `board.taxonomy.categories.list` or `board.taxonomy.skills.list`; job results use `board.jobs.list` or `board.jobs.search`. Route a selected suggestion with `suggestionPath` from `@cavuno/board/paths`.
 
 ## Read suggestions
 
@@ -15,6 +15,7 @@ Location autocomplete uses `board.taxonomy.places.list({ q })`; filter option li
 const { items, query } = await board.search.suggest({
   q: 'acme',
   limit: 10,
+  types: ['company', 'skill', 'category'],
 });
 
 for (const item of items) {
@@ -22,6 +23,10 @@ for (const item of items) {
     item.slug;
     item.name;
     item.jobCount;
+  } else if (item.type === 'market') {
+    item.slug;
+    item.name;
+    item.companyCount;
   } else {
     item.termType;
     item.displayName;
@@ -31,7 +36,7 @@ for (const item of items) {
 }
 ```
 
-Queries shorter than two characters return no items. `limit` accepts 1–25 and defaults to 25.
+Queries shorter than two characters return no items. `limit` accepts 1–25 and defaults to 25. `{ types: ['skill'], limit: 10 }` returns up to ten skills.
 
 Term suggestions have `termType: 'category' | 'skill'`; use `canonicalSlug` for links and `sourceSlug` for job filters.
 

package/skills/cavuno-board-seo/BLOG.md

@@ -21,10 +21,13 @@ const author = await board.blog.authors.retrieve('jane');
 const { data: authorPosts } = await board.blog.posts.list({
   authorSlug: 'jane',
 });
+// Profile description is application-owned. Prefer author.bio; otherwise
+// compose from the board catalog (shape only — not an English sentence).
 const profile = createAuthorProfileJsonLd({
   author,
   canonical: `https://jobs.example.com/blog/author/${author.slug}`,
-  description: author.bio ?? `Posts by ${author.name}`,
+  description:
+    author.bio ?? messages.authorProfileDescription({ name: author.name }),
   origin: 'https://jobs.example.com',
   posts: authorPosts,
   totalPosts: authorPosts.length,

package/skills/cavuno-board-seo/JOB_AND_BREADCRUMBS.md

@@ -32,13 +32,16 @@ Labels are trimmed, blank crumbs are dropped, and fewer than two surviving
 crumbs return `null`. The current page omits `href`, which makes the builder
 omit its `item`. Supply absolute hrefs, or pass `origin` for path hrefs.
 
+Breadcrumb labels are application-owned — pull them from the board's message
+catalog. The snippet shows structure only, not English copy.
+
 ```ts snippet
 import { createBreadcrumbJsonLd } from '@cavuno/board/seo';
 
 const trail = createBreadcrumbJsonLd(
   [
-    { label: 'Home', href: '/' },
-    { label: 'Jobs', href: '/jobs' },
+    { label: messages.breadcrumb('home'), href: '/' },
+    { label: messages.breadcrumb('jobs'), href: '/jobs' },
     { label: job.title },
   ],
   { origin: 'https://jobs.example.com' });

package/skills/cavuno-board-seo/LISTING.md

@@ -1,24 +1,45 @@
 # Listing metadata and JSON-LD
 
 Read this reference for a job-listing page's head descriptors and structural
-JSON-LD. These builders are locale-neutral pass-throughs; supply the page's
-resolved heading copy.
+JSON-LD. These builders assemble structure only; supply the page's resolved
+title and meta description from the board's copy source.
 
 ```ts snippet
 import { listingHead, listingJsonLd } from '@cavuno/board/seo';
 
-const { name } = await board.context();
-const head = listingHead({
+const { name, language } = await board.context();
+const count = 42;
+const heading = /* resolved page heading from your catalog */ '…';
+// Application owns every display join — count, counter/particle, heading,
+// separator, board name. Pieces (not a pasteable template):
+// countLabel  = Intl.NumberFormat(language).format(count)
+// heading     = catalog heading for this page
+// boardName   = name
+// Compose title and description in the board language (ja counters, RTL order,
+// …). Do not hardcode number-then-noun or " | " order in shared helpers.
+const countLabel = new Intl.NumberFormat(language).format(count);
+const title = messages.listingTitle({ count, countLabel, heading, boardName: name });
+const description = messages.listingDescription({
+  count,
+  countLabel,
+  heading,
   boardName: name,
+});
+
+const head = listingHead({
+  title,
   origin: 'https://jobs.example.com',
   path: '/jobs/robotics',
-  heading: 'Robotics jobs',
-  count: 42,
+  description,
 });
 
+// Breadcrumb labels are application-owned (catalog), not English literals.
 const objects = listingJsonLd({
   origin: 'https://jobs.example.com',
-  breadcrumbs: [{ name: 'Home', path: '/' }, { name: 'Jobs' }],
+  breadcrumbs: [
+    { name: messages.breadcrumb('home'), path: '/' },
+    { name: messages.breadcrumb('jobs') },
+  ],
   jobs: cards.map((card) => ({
     slug: card.slug,
     company: card.company,
@@ -27,10 +48,12 @@ const objects = listingJsonLd({
 ```
 
 `head.meta` contains title, description, and Open Graph descriptors;
-`head.links` contains the canonical link. For the example, the count-aware
-title is `42 Robotics jobs | Acme Jobs`.
+`head.links` contains the canonical link. Title and description are whatever
+you passed — the SDK does not join count, heading, or board name. Use a
+locale-aware lowercasing API (not `.toLowerCase()`) when your copy needs case
+folding.
 
 This branch is complete when head descriptors reflect the resolved page
-heading and count, the canonical URL combines the intended origin and path,
-and `listingJsonLd` receives card slugs plus company objects from the listing
-response.
+title and description, the canonical URL combines the intended origin and
+path, and `listingJsonLd` receives card slugs plus company objects from the
+listing response.

package/skills/cavuno-board-seo/SALARY.md

@@ -6,15 +6,17 @@ seniority ordering.
 ## Build a title page
 
 Display-producing helpers require the board language as their leading
-argument. The salary money formatters intentionally retain the hosted page's
-USD assumption; locale changes number formatting, not currency. The current
-FAQ uses templated English sentences until board-custom FAQ copy is exposed.
+argument. Salary money formatters take the detail's `currency` as well —
+locale drives digits/grouping; currency is never USD-hardcoded. FAQ helpers
+return entry kinds and values; compose question/answer prose from the board's
+message catalog (with proper plural rules via `Intl.PluralRules` — never a
+two-way `one`/else branch).
 
 ```ts snippet
 import {
   buildSalaryFaq,
   faqJsonLd,
-  formatRange,
+  formatSalaryStatRange,
   itemListJsonLd,
   sortBySeniority,
   titleSalaryJsonLd,
@@ -23,14 +25,57 @@ import {
 const { language } = await board.context();
 const detail = await board.salaries.titles.retrieve('software-engineer');
 
-const occupation = titleSalaryJsonLd(language, detail);
+// Application owns the finished distribution name (label + word order).
+// French: `${entity} ${catalog.seniority[seniority]}`; English often
+// `${catalog.seniority[seniority]} ${entity}`; Japanese may omit the space.
+const occupation = titleSalaryJsonLd(detail, {
+  seniorityName: ({ seniority, entity }) =>
+    copy.seniorityName({ seniority, entity }),
+});
+
+// Structure only — map kinds to localized FAQ sentences in the app.
+// The application owns every word; the snippet shows shape, not copy.
+// average carries avgMin/avgMax/currency (raw) + range (compact convenience).
+// Prefer the raw figures when FAQ prose wants full notation ($100,000).
+const entries = buildSalaryFaq(
+  language,
+  detail.categoryName,
+  detail.overallSalary,
+  detail.currency);
 const faq = faqJsonLd(
-  buildSalaryFaq(language, detail.categoryName, detail.overallSalary));
+  entries.map((entry) => {
+    if (entry.kind === 'average') {
+      const range =
+        formatSalaryStatRange(
+          language,
+          entry.avgMin,
+          entry.avgMax,
+          entry.currency,
+          'standard') ?? entry.range;
+      return {
+        // Application catalog — use Intl.PluralRules for jobCount, never a
+        // one/else English plural.
+        q: copy.faqQuestion({ kind: 'average', label: entry.label }),
+        a: copy.faqAnswer({
+          kind: 'average',
+          label: entry.label,
+          range,
+          jobCount: entry.jobCount,
+        }),
+      };
+    }
+    return {
+      q: copy.faqQuestion({ kind: 'methodology', label: entry.label }),
+      a: copy.faqAnswer({ kind: 'methodology', label: entry.label }),
+    };
+  }));
+
 const range = detail.overallSalary
-  ? formatRange(
+  ? formatSalaryStatRange(
       language,
       detail.overallSalary.avgMin,
-      detail.overallSalary.avgMax)
+      detail.overallSalary.avgMax,
+      detail.currency)
   : null;
 const ladder = sortBySeniority(detail.bySeniority);
 const index = itemListJsonLd([
@@ -44,18 +89,38 @@ const index = itemListJsonLd([
 ## Select other salary builders
 
 - `skillSalaryJsonLd(detail)` for a skill detail.
-- `locationSalaryJsonLd(detail)` for a city-level location detail.
-- `crossAxisSalaryJsonLd(locale, args)` for a title/skill and location pair.
-- `companySalaryJsonLd(locale, detail)` for a company overview.
-- `companyCategorySalaryJsonLd(locale, detail)` for a company-category page.
-- `formatUsd(locale, value)` for the hosted USD amount format.
-- `formatSeniority(locale, key)` and `SENIORITY_ORDER` for seniority display.
+- `locationSalaryJsonLd(detail, { occupationUrl })` for a city-level location
+  detail — emits an `ItemList` of top categories (not an `Occupation` named
+  after the city). Supply absolute URLs to each title salary page.
+- `crossAxisSalaryJsonLd(args, { seniorityName? })` for a title/skill and
+  location pair.
+- `companySalaryJsonLd(detail, { occupationUrl })` for a company overview —
+  `ItemList` of categories at that employer (not an occupation named after
+  the company).
+- `companyCategorySalaryJsonLd(detail, { seniorityName? })` for a
+  company-category page (keeps `Occupation`).
+- `formatSalaryStat(locale, value, currency, notation?)` /
+  `formatSalaryStatRange(locale, min, max, currency, notation?)` for
+  salary-page amounts (currency from the detail, not hardcoded USD;
+  `formatRange` owns the join). `notation` matches `formatSalaryRange`
+  (magnitude default when omitted; pass `'standard'` for full figures).
+  Returns `null` when currency is empty or `Intl` rejects inputs.
+- `SENIORITY_ORDER` / `sortBySeniority` for seniority ladder ordering
+  (display names are application-owned via `seniorityName`).
+
+JSON-LD `name` fields are data labels (entity and category names).
+Per-seniority distribution names come only from `seniorityName`; when that
+callback is omitted, those distributions ship without a `name`. Do not expect
+English framing such as "salary (all levels)" or "Average Salary in …" from
+the SDK — put those words in the app if a board still wants them.
 
-The structured-data families are `Occupation`,
-`MonetaryAmountDistribution`, `ItemList`, and `FAQPage`. Feed them the SDK
-salary read model; preserve nullable aggregates and server-computed values.
+The structured-data families are `Occupation` (title, skill, cross-axis,
+company-category), `ItemList` (location overview, company overview, indexes),
+`MonetaryAmountDistribution`, and `FAQPage`. Feed them the SDK salary read
+model; preserve nullable aggregates and server-computed values.
 
 This branch is complete when every applicable schema object has the expected
 schema.org type, null aggregates produce no fabricated figure, the board
-language comes from context, and every displayed value traces to a response
+language comes from context, FAQ prose comes from the application catalog
+with proper plural rules, and every displayed value traces to a response
 field.

package/skills/cavuno-board-seo/SKILL.md

@@ -20,8 +20,9 @@ Read the matching reference completely before implementing that page:
 For a page that combines branches, read every matching reference.
 
 Sitemaps and robots.txt use `cavuno-board-sitemap`. The host app owns OG-image
-generation and its route map. `listingHead` receives app-owned heading copy;
-the SDK does not reproduce the board's configured meta copy.
+generation and its route map. `listingHead` receives app-owned title and
+meta description copy; the SDK never composes those sentences or joins
+count/heading/board name.
 
 ## Apply the shared rendering contract
 

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.2.0",
+  "version": "4.0.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -59,14 +59,14 @@
     },
     {
       "name": "cavuno-board-format",
-      "description": "Board-language display formatting with @cavuno/board/format. Use for salary ranges, dates, job labels, location labels, card conversion, or salary metadata copy.",
+      "description": "Board-language display formatting with @cavuno/board/format. Use for salary ranges, dates, custom-field display, or salary-stat numbers.",
       "path": "skills/cavuno-board-format/SKILL.md",
       "framework": null,
       "category": "core"
     },
     {
       "name": "cavuno-board-i18n",
-      "description": "One-seam board localization with @cavuno/board. Use when localizing UI chrome, adding locale routing, merging operator labels, or preserving board-language content.",
+      "description": "One-seam board localization with @cavuno/board. Use when localizing UI chrome, adding locale routing, or preserving board-language content.",
       "path": "skills/cavuno-board-i18n/SKILL.md",
       "framework": null,
       "category": "core"