@cavuno/board 2.0.3 → 3.0.0

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

@@ -1,100 +1,89 @@
 ---
 name: cavuno-board-filters
-description: The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/company/sort sets, localized seniority labels, and parseListingFilters for jobs-listing routes. Use when building listing pages, filter sidebars, sort dropdowns, or validating listing URL params.
+description: Listing-filter contracts with @cavuno/board. Use for job filter controls, sort controls, listing URL validation, or taxonomy-backed filter options.
 ---
 
-# Filters: vocabulary + URL parsing
+# Listing filters
 
-`@cavuno/board/filters` is the one filter vocabulary every tenant frontend
-shares — the seniority set is tested against the platform source, and
-URL parsing follows the hosted semantics (hand-typed URLs are messy; parsing
-never throws).
+`@cavuno/board/filters` is the shared vocabulary and parser for every job
+listing route, including category, skill, and location pages. Display labels
+live in `@cavuno/board/format`; search POST bodies use `jobs.search`; typeahead
+UI behavior lives in `cavuno-board-search-suggestions`.
 
-## When to use
+## Parse public URL input
 
-- The jobs index and every programmatic listing page (category / skill /
-  location) — they all layer the same cross-cutting filters on any seed.
-- `validateSearch`-style route param validation (server-safe, SSR-ready).
-
-## When not to use
-
-- Turning values into card display text — `cavuno-board-format`.
-- Search QUERIES (`jobs.search` bodies) — this module is about the listing
-  URL contract, not the search POST body.
-- Search-dropdown typeahead — `cavuno-board-suggest`.
-
-## Parse listing URLs
+Run every listing URL through `parseListingFilters`. Public input is
+permissive: unknown values are dropped and parsing does not throw. Seniority
+and company accept repeated parameters or comma-separated strings, then trim,
+lowercase, deduplicate, and preserve order. Company is an open set of public
+slugs capped at the first 10 values.
 
 ```ts snippet
-import { parseListingFilters, DEFAULT_SORT } from '@cavuno/board/filters';
+import {
+  DEFAULT_SORT,
+  parseListingFilters,
+} from '@cavuno/board/filters';
 
 const filters = parseListingFilters(rawSearchParams);
-// { q?, remoteOption?, employmentType?, seniority?: Seniority[], company?: string[], sort? }
+const selectedSort = filters.sort ?? DEFAULT_SORT;
 
 const page = await board.jobs.list({
   limit: 20,
   seniority: filters.seniority,
   companySlug: filters.company,
   remoteOption: filters.remoteOption ? [filters.remoteOption] : undefined,
-  employmentType: filters.employmentType ? [filters.employmentType] : undefined,
+  employmentType: filters.employmentType
+    ? [filters.employmentType]
+    : undefined,
 });
 ```
 
-Unknown values are dropped silently (public URLs, never throw). Seniority
-and `company` accept repeated params or a comma-string and normalize with
-the hosted rules: trim, lowercase, dedupe, keep order. `company` is an open
-value set (public slugs) capped at 10 (wire max; first 10 kept).
+Company slugs are the URL identity. Map `filters.company` directly to
+`companySlug` in `jobs.list` queries or `jobs.search` filters.
 
-**Slugs are the URL identity.** Map `filters.company` to the wire as
-`companySlug` (`jobs.list` query / `jobs.search` filters). The API accepts
-slugs directly — never resolve slug→id client-side.
-
-## Render the filter UI from the vocabulary
+## Render controls from the vocabulary
 
 ```ts snippet
 import {
-  REMOTE_OPTIONS,
   EMPLOYMENT_TYPES,
-  SENIORITIES,
   JOB_SORTS,
+  REMOTE_OPTIONS,
+  SENIORITIES,
   seniorityLabels,
   sortLabels,
 } from '@cavuno/board/filters';
 
 const { language } = await board.context();
-const labels = seniorityLabels(language); // de: executive → "Führungskraft"
-const sorts = sortLabels(language);       // English defaults on every locale
+const seniorityCopy = seniorityLabels(language);
+const sortCopy = sortLabels(language);
 ```
 
-Seniority renders as a MULTI-select (hosted parity). `EMPLOYMENT_TYPES`
-deliberately offers 5 of the 7 wire values (`volunteer`/`other` exist on
-jobs but are not filter options). `JOB_SORTS` deliberately excludes
-`oldest`; `relevance` is the featured-ranked default.
+Render seniority as a multi-select with all eight `SENIORITIES`.
+`EMPLOYMENT_TYPES` contains five listing options; `volunteer` and `other`
+remain valid job wire values but are absent from the filter control.
+`JOB_SORTS` contains exactly `relevance`, `newest`, and `salary_high`;
+`relevance` is the featured-ranked default. Sort labels follow the board copy
+catalog and operator overrides supplied to `sortLabels`.
 
-## Load category, skill, and keyword options
+## Load taxonomy options
 
-Use the Board API taxonomy collections for filter/autocomplete options. Items
-are backed by published jobs on this board and already carry the board-language
-display name and canonical URL slug. Keep `sourceSlug` for job filtering and
-`canonicalSlug` for links.
+Category and skill collections contain terms backed by published jobs. Each
+term already carries a board-language `displayName`, immutable English
+`sourceSlug` for filtering, and board-language `canonicalSlug` for links.
 
 ```ts snippet
 const categories = await board.taxonomy.categories.list({ limit: 50 });
 const skills = await board.taxonomy.skills.list({ limit: 50 });
-const suggestions = await board.taxonomy.suggestions.list({
-  q: searchText,
-  limit: 10,
-});
 
 const categoryOptions = categories.data.map((term) => ({
-    label: term.displayName,
-    filterValue: term.sourceSlug,
-    href: `/jobs/${term.canonicalSlug}`,
+  label: term.displayName,
+  filterValue: term.sourceSlug,
+  href: `/jobs/${term.canonicalSlug}`,
 }));
 ```
 
-Category and skill lists accept `q`, `limit` (1–100), and the opaque
-`cursor` request field. Pass the previous response's `nextCursor` into it:
+Category and skill lists accept `q`, `limit` (1–100), and opaque `cursor`.
+Pass `nextCursor` unchanged to the next request.
 
 ```ts snippet
 const first = await board.taxonomy.categories.list({ limit: 50 });
@@ -106,31 +95,31 @@ const second = first.nextCursor
   : null;
 ```
 
-Suggestions accept `q` and `limit`;
-a present query under two characters returns no suggestions. Suggestions contain
-categories and skills only. A category and skill may legitimately share a slug,
-so use `type + canonicalSlug` as the option identity.
-
-## Anti-patterns
+Keyword suggestions accept `q` and `limit`. A present query shorter than two
+characters returns no results. Suggestions contain categories and skills only;
+because both types may share a slug, key each option by
+`type + canonicalSlug`.
 
-```ts no-check
-// NEVER hand-roll the vocab per page — one page offering 'oldest' or a
-// 6th employment type diverges from every other board frontend:
-const sorts = ['relevance', 'newest', 'oldest'];
-// NEVER trust raw search params into the SDK query:
-board.jobs.list({ seniority: rawSearch.seniority });
+```ts snippet
+const suggestions = await board.taxonomy.suggestions.list({
+  q: searchText,
+  limit: 10,
+});
 ```
 
-## Out of scope — do not invent exports
+The host router owns URL serialization and saved-filter persistence.
+Locations come from `board.taxonomy.places` rather than a static filter export.
 
-No URL BUILDER (routes are app-owned — serialize with your router), no location
-taxonomy vocabulary (locations come from `board.taxonomy.places`), no
-saved-filter persistence.
+## Completion gate
 
-## Verify
+Finish only after every applicable check passes:
 
-- [ ] `/jobs?seniority=Senior,%20lead&sort=oldest` renders the senior+lead
-      selection and the default sort — no crash, no leaked invalid value.
-- [ ] The seniority multi-select shows all 8 levels, labeled in the board
-      language.
-- [ ] The sort dropdown offers exactly relevance / newest / salary_high.
+- `/jobs?seniority=Senior,%20lead&sort=oldest` selects senior and lead, falls
+  back to `DEFAULT_SORT`, and passes no invalid value to the SDK.
+- The seniority control has all eight localized levels and supports multiple
+  selections.
+- The employment control has five options; the sort control has exactly
+  relevance, newest, and salary high.
+- Category and skill filtering sends `sourceSlug`, while links use
+  `canonicalSlug`.
+- Every paged taxonomy request forwards the previous opaque `nextCursor`.

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

@@ -1,104 +1,99 @@
 ---
 name: cavuno-board-format
-description: Display formatting for board frontends with @cavuno/board/format — salary ranges, seniority/employment/remote labels, location labels, dates, and the board-language salary lexicon. Use when rendering job cards, detail pages, or salary figures, and whenever a value like salaryMin/salaryTimeframe/seniority needs to become display text.
+description: Board-language display formatting with @cavuno/board/format. Use for salary ranges, dates, job labels, location labels, card conversion, or salary metadata copy.
 ---
 
-# Format: board-language display text
+# Display formatting
 
-`@cavuno/board/format` turns wire values into the exact display text the
-hosted board renders — tested against the hosted formatters, so a
-tenant frontend cannot drift from the platform's rendering rules.
+`@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.
 
-## When to use
+Filter controls use `cavuno-board-filters`. Salary values remain in their wire
+currency and retain their server-computed amounts.
 
-- Rendering salary ranges, dates, locations, or enum labels anywhere.
-- Building salary-page metadata sentences (the lexicon frames).
-
-## When not to use
-
-- Filter vocabulary and URL parsing — `cavuno-board-filters`.
-- Money math. Never compute or convert amounts client-side; format what the
-  wire provides.
-
-## The board language is a required first argument
-
-Every label-producing helper takes the board language — read it once from
-context. There is no `en` default: a German-native board must never
-silently render English.
+## Format job and blog fields
 
 ```ts snippet
 import {
-  formatSalaryRange,
-  formatPublishedRelativeDate,
-  formatDate,
   fieldLabel,
+  formatDate,
+  formatPublishedRelativeDate,
+  formatSalaryRange,
 } from '@cavuno/board/format';
 
 const { language } = await board.context();
 
-formatSalaryRange(language, job.salaryMin, job.salaryMax, job.salaryTimeframe, job.salaryCurrency);
-// en: "$90K – $120K Yearly" · de: "90.000 € – 120.000 € pro Jahr"
-formatPublishedRelativeDate(language, job.publishedAt); // "5d ago" — what job CARDS render
-formatDate(language, job.publishedAt); // "Jun 24, 2026" — blog metadata / detail facts (UTC-pinned)
-fieldLabel(language, job.seniority);   // de: 'executive' → "Führungskraft"
+formatSalaryRange(
+  language,
+  job.salaryMin,
+  job.salaryMax,
+  job.salaryTimeframe,
+  job.salaryCurrency);
+formatPublishedRelativeDate(language, job.publishedAt);
+formatDate(language, job.publishedAt);
+fieldLabel(language, job.seniority);
 ```
 
-Job cards and the job-detail header show the RELATIVE form; the absolute
-medium date is for blog metadata and detail fact rows — matching hosted.
+`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.
 
-Localization matches hosted exactly: seniority + timeframe words are
-localized (en+de lexicon, other locales fall back to English words with
-locale-correct number formatting); employment/remote labels are English on
-every board because hosted ships no other vocabulary yet.
+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.
 
-## Location labels
+## Render locations and saved-job cards
 
-Cards carry server-computed labels — use them via `cardLocationLabel`. Only
-the full `PublicJob` needs client-side derivation:
+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.
 
 ```ts snippet
-import { cardLocationLabel, locationLabel, fullJobToCard } from '@cavuno/board/format';
+import {
+  cardLocationLabel,
+  fullJobToCard,
+  locationLabel,
+} from '@cavuno/board/format';
 
-cardLocationLabel(language, card);   // "Remote · Europe" | "Berlin, Germany"
-locationLabel(language, job);        // full PublicJob (detail page)
-const card = fullJobToCard(language, job); // embed a saved job in a card list
+cardLocationLabel(language, card);
+locationLabel(language, job);
+const savedCard = fullJobToCard(language, job);
 ```
 
-## Salary lexicon (metadata sentences)
+## Build salary metadata copy
 
-`getSalaryLexicon(language)` exposes the words and the `<title>`/meta
-sentence frames the hosted salary pages use:
+`getSalaryLexicon` exposes hosted salary terminology and sentence frames.
 
 ```ts snippet
 import { getSalaryLexicon } from '@cavuno/board/format';
 
 const lexicon = getSalaryLexicon(language);
-lexicon.frames.entitySalariesTitle({ entity: 'JavaScript', range: '$70K – $90K' });
-// "JavaScript Salaries ($70K – $90K/yr)"
-lexicon.seniority.senior; // "Senior"
-```
-
-## Anti-patterns
-
-```ts no-check
-// NEVER hand-format money — symbol placement and words are locale rules:
-`$${(job.salaryMin / 1000).toFixed(0)}k`;          // wrong on de boards
-// NEVER default the locale:
-formatSalaryRange('en', ...);                      // hardcoded 'en' on a de board
-// NEVER rebuild card location labels from scratch — the wire pre-computes them.
+lexicon.frames.entitySalariesTitle({
+  entity: 'JavaScript',
+  range: '$70K – $90K',
+});
+lexicon.seniority.senior;
 ```
 
-## Out of scope — do not invent exports
+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`.
 
-No currency conversion, no relative-time ("3 days ago") helper, no
-number-only formatter — the SDK formats exactly what the hosted board
-formats. Sort-dropdown copy lives in `cavuno-board-filters`.
+## Completion gate
 
-## Verify
+Finish only after every applicable check passes:
 
-- [ ] A de board renders "pro Jahr"/"ab"/"Führungskraft" where an en board
-      renders "Yearly"/"From"/"Executive" — same code path, different
-      `language`.
-- [ ] An en board's salary strings are byte-identical to the hosted board's
-      for the same job.
-- [ ] No call site passes a hardcoded locale string.
+- 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.

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

@@ -1,81 +1,52 @@
 ---
 name: cavuno-board-i18n
-description: Multi-language chrome for a board frontend — the single-language board model, the uiCopy catalog ⊕ operator labels ⊕ generated copy layering, the one copy seam, and how to add path-prefixed locales (/de/, /fr/) with Paraglide JS on TanStack Start. Use when localizing a starter's chrome, adding a language, or wiring locale routing. Do NOT use to translate job content — that stays the board's language.
+description: One-seam board localization with @cavuno/board. Use when localizing UI chrome, adding locale routing, merging operator labels, or preserving board-language content.
 ---
 
-# Board i18n: localize the chrome, never the content
+# One-seam board localization
 
-A Cavuno board has **one content language** (`board.context().language`).
-Job titles, descriptions, and company text are that single language and
-never translated by the frontend. What you localize is the **chrome** —
-labels, headings, FAQ scaffolding, filter vocabulary — plus the entity
-data the API already translates (taxonomy, places, salary names).
+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.
 
-So there are two separate things:
-- **Content** (jobs, companies, blog): board-language, API-served, single.
-- **Chrome** (your authored UI strings): can be multi-locale, path-routed.
+## Build the copy seam
 
-## The copy layers (resolve in order)
+All UI strings resolve through one application module. Layer copy in this order:
 
-1. **`uiCopy(language)`** — the versioned SDK catalog (`@cavuno/board/format`,
-   `en`/`de`/`fr`, functions-per-key for plurals; no runtime, no provider).
-   The floor.
-2. **`⊕ board.context().labels`** — the operator's per-board overrides,
-   API-served (e.g. `featuredLabel` → "Top Job").
-3. **`⊕ generated code`** — per-board copy the AI builder ejects to native
-   code. Supersedes the catalog for that board.
-
-Every surface resolves copy through **one seam module** (`src/copy.ts`),
-never by calling the catalog inline:
+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.
 
 ```ts snippet
-import { uiCopy, type BoardLabelOverrides } from '@cavuno/board/format'
-export function boardCopy(language: string | undefined, labels?: BoardLabelOverrides) {
-  return uiCopy(language, labels)
+import {
+  uiCopy,
+  type BoardLabelOverrides,
+} from '@cavuno/board/format';
+
+export function boardCopy(
+  language: string | undefined,
+  labels?: BoardLabelOverrides) {
+  return uiCopy(language, labels);
 }
 ```
 
-The seam is the **single swap point** for the whole copy lifecycle: catalog
-today → Paraglide messages (below) → builder-generated code later. Components
-never change; only the seam's backing source does.
+Components import this seam rather than the catalog. That keeps the catalog-to-generated-code transition to one module.
 
-## Add path-prefixed locales with Paraglide JS (TanStack Start)
+## Add locales
 
-The starters are TanStack Start, and the TanStack-recommended i18n is
-**Paraglide JS** — compile-time (messages become tree-shakeable functions),
-**no runtime provider** (matches the catalog's no-provider stance), with
-built-in locale routing. The board's language is served unprefixed at `/`;
-extra locales are prefixed (`/de/`, `/fr/`).
+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. **Init.** `npx @inlang/paraglide-js@latest init` — creates the inlang
-   project, `messages/{en,de,fr}.json`, the `paraglide/` output, and the Vite
-   plugin. Add the plugin to `vite.config.ts`.
-2. **Generate messages FROM `uiCopy` — never hand-translate.** The catalog is
-   the source of truth. Emit `messages/{locale}.json` from
-   `uiCopy(locale)` so `de`/`fr` come from the reviewed SDK catalog, not a
-   second copy. (This generator is the `uiCopy → Paraglide` adapter.)
-3. **Route.** Wire the router's `rewrite` with Paraglide's `deLocalizeUrl` /
-   `localizeUrl` so `/de/jobs` routes internally as `/jobs` and every `Link`
-   auto-prefixes the active locale. Default-locale-no-prefix: the board
-   language stays at `/`.
-4. **SSR.** Add `paraglideMiddleware` in the server entry; set `<html lang>`
-   from `getLocale()` (it replaces the static `board.language` in the root).
-5. **Seam.** Point `boardCopy` at the URL locale (`getLocale()`) instead of
-   only `board.language`, so `/de/` renders German chrome even on an English
-   board. This is the opt-in over the single-language model.
-6. **SEO slice.** Per-locale `hreflang`, canonical, and sitemap entries are
-   part of completing multi-language — do them when you add real locales, not
-   in the foundation.
+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.
+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.
 
-## Do not
+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.
 
-- **Do not translate job content** (titles/descriptions). Fully multi-language
-  listings is a data-model change, out of scope.
-- **Do not hand-author translations** in the starter — generate messages from
-  `uiCopy` so there is one reviewed source.
-- **Do not add a runtime i18n provider** (e.g. use-intl's context). Paraglide
-  is compile-time; keep the no-provider property.
-- **Do not scatter catalog calls** through markup — everything imports the one
-  seam, so the catalog→code migration is a single-file change.
+## Completion gate
 
-Wiring flavor: `cavuno-board-tanstack-start`.
+- Every authored chrome string enters components through the copy seam.
+- `uiCopy` plus `board.context().labels` resolves the expected operator override.
+- 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.