@cavuno/board 1.38.0 → 1.40.0

package/dist/theme.d.mts

@@ -40,6 +40,54 @@ interface ThemeInput {
  * lives in exactly one place.
  */
 declare function isSafeThemeColorValue(value: string): boolean;
+/**
+ * Email-safe snapshot keys (platform brand snapshot / MIG-04).
+ * Light-only subset consumed by Convex email branding.
+ */
+type EmailSafeSnapshotColorKey = 'buttonPrimary' | 'buttonPrimaryText' | 'background' | 'mutedBackground' | 'border' | 'text' | 'textMuted' | 'brandColor';
+/**
+ * Inverse of the email-safe subset of `tokenLines`: for each snapshot
+ * color key, the ordered list of CSS custom property names (no `--`)
+ * that may supply it. First PRESENT property wins when DIFFERENT CSS
+ * names map to one snapshot key (e.g. muted > secondary for
+ * mutedBackground). Within one CSS property name, multi-`:root` cascade
+ * is last-wins and is resolved before this table is consulted.
+ *
+ * Additive export for the platform brand-snapshot deriver (MIG-04) —
+ * keeps the CSS ↔ board contract next to its forward twin.
+ */
+declare const EMAIL_SAFE_SNAPSHOT_FROM_CSS: {
+    readonly [K in EmailSafeSnapshotColorKey]: readonly string[];
+};
+/**
+ * Board key → CSS custom property name(s) (no `--` prefix).
+ *
+ * The forward write contract for the builder theme tab (MIG-05) and the
+ * emission table for `boardThemeToCss` / `tokenLines` — one table, so a
+ * tab edit and a render path cannot drift. When a board key fans out to
+ * several CSS names (e.g. `text` → foreground + card-foreground + …),
+ * a single tab edit writes every name with the same hex value.
+ *
+ * Fallbacks that only apply at *emit* time when a preferred key is
+ * absent (`destructive` ← buttonDanger ?? textError; `ring` ← brandColor
+ * ?? buttonPrimary) stay in `tokenLines` — they are not owned write
+ * targets of the fallback key.
+ */
+declare const BOARD_COLOR_TO_CSS_TOKENS: {
+    readonly [K in BoardColorKey]: readonly string[];
+};
+/**
+ * CSS custom property names (no `--`) that fan out from *optional*
+ * ColorTokensSchema keys (`textSubtle`, `textDisabled`). Production
+ * starter `tokens.css` may omit these declarations; the builder theme
+ * batch lane SKIPS missing optional declarations rather than escalating
+ * the whole preset to the model (MIG-05). Required declarations still
+ * escalate on absence — never invent (L5-B).
+ */
+declare const OPTIONAL_THEME_DECLARATIONS: readonly ["foreground-subtle", "foreground-disabled"];
+type OptionalThemeDeclaration = (typeof OPTIONAL_THEME_DECLARATIONS)[number];
+/** True when a CSS custom property name (with or without `--`) is optional. */
+declare function isOptionalThemeDeclaration(token: string): boolean;
 /**
  * Render the board theme as `:root` (+ `.dark`) CSS-variable overrides.
  * Inject once at the app shell, after the static theme stylesheet.
@@ -67,4 +115,4 @@ declare function themeFontFamily(fontKey: string): string;
 /** One Google Fonts request covering the sans + heading families. */
 declare function googleFontsUrl(theme: ThemeInput | null): string | null;
 
-export { BOARD_COLOR_KEYS, type BoardColorKey, THEME_FONT_GOOGLE_FAMILIES, type ThemeInput, boardThemeToCss, googleFontsUrl, isSafeThemeColorValue, themeFontFamily, themeMode };
+export { BOARD_COLOR_KEYS, BOARD_COLOR_TO_CSS_TOKENS, type BoardColorKey, EMAIL_SAFE_SNAPSHOT_FROM_CSS, type EmailSafeSnapshotColorKey, OPTIONAL_THEME_DECLARATIONS, type OptionalThemeDeclaration, THEME_FONT_GOOGLE_FAMILIES, type ThemeInput, boardThemeToCss, googleFontsUrl, isOptionalThemeDeclaration, isSafeThemeColorValue, themeFontFamily, themeMode };

package/dist/theme.d.ts

@@ -40,6 +40,54 @@ interface ThemeInput {
  * lives in exactly one place.
  */
 declare function isSafeThemeColorValue(value: string): boolean;
+/**
+ * Email-safe snapshot keys (platform brand snapshot / MIG-04).
+ * Light-only subset consumed by Convex email branding.
+ */
+type EmailSafeSnapshotColorKey = 'buttonPrimary' | 'buttonPrimaryText' | 'background' | 'mutedBackground' | 'border' | 'text' | 'textMuted' | 'brandColor';
+/**
+ * Inverse of the email-safe subset of `tokenLines`: for each snapshot
+ * color key, the ordered list of CSS custom property names (no `--`)
+ * that may supply it. First PRESENT property wins when DIFFERENT CSS
+ * names map to one snapshot key (e.g. muted > secondary for
+ * mutedBackground). Within one CSS property name, multi-`:root` cascade
+ * is last-wins and is resolved before this table is consulted.
+ *
+ * Additive export for the platform brand-snapshot deriver (MIG-04) —
+ * keeps the CSS ↔ board contract next to its forward twin.
+ */
+declare const EMAIL_SAFE_SNAPSHOT_FROM_CSS: {
+    readonly [K in EmailSafeSnapshotColorKey]: readonly string[];
+};
+/**
+ * Board key → CSS custom property name(s) (no `--` prefix).
+ *
+ * The forward write contract for the builder theme tab (MIG-05) and the
+ * emission table for `boardThemeToCss` / `tokenLines` — one table, so a
+ * tab edit and a render path cannot drift. When a board key fans out to
+ * several CSS names (e.g. `text` → foreground + card-foreground + …),
+ * a single tab edit writes every name with the same hex value.
+ *
+ * Fallbacks that only apply at *emit* time when a preferred key is
+ * absent (`destructive` ← buttonDanger ?? textError; `ring` ← brandColor
+ * ?? buttonPrimary) stay in `tokenLines` — they are not owned write
+ * targets of the fallback key.
+ */
+declare const BOARD_COLOR_TO_CSS_TOKENS: {
+    readonly [K in BoardColorKey]: readonly string[];
+};
+/**
+ * CSS custom property names (no `--`) that fan out from *optional*
+ * ColorTokensSchema keys (`textSubtle`, `textDisabled`). Production
+ * starter `tokens.css` may omit these declarations; the builder theme
+ * batch lane SKIPS missing optional declarations rather than escalating
+ * the whole preset to the model (MIG-05). Required declarations still
+ * escalate on absence — never invent (L5-B).
+ */
+declare const OPTIONAL_THEME_DECLARATIONS: readonly ["foreground-subtle", "foreground-disabled"];
+type OptionalThemeDeclaration = (typeof OPTIONAL_THEME_DECLARATIONS)[number];
+/** True when a CSS custom property name (with or without `--`) is optional. */
+declare function isOptionalThemeDeclaration(token: string): boolean;
 /**
  * Render the board theme as `:root` (+ `.dark`) CSS-variable overrides.
  * Inject once at the app shell, after the static theme stylesheet.
@@ -67,4 +115,4 @@ declare function themeFontFamily(fontKey: string): string;
 /** One Google Fonts request covering the sans + heading families. */
 declare function googleFontsUrl(theme: ThemeInput | null): string | null;
 
-export { BOARD_COLOR_KEYS, type BoardColorKey, THEME_FONT_GOOGLE_FAMILIES, type ThemeInput, boardThemeToCss, googleFontsUrl, isSafeThemeColorValue, themeFontFamily, themeMode };
+export { BOARD_COLOR_KEYS, BOARD_COLOR_TO_CSS_TOKENS, type BoardColorKey, EMAIL_SAFE_SNAPSHOT_FROM_CSS, type EmailSafeSnapshotColorKey, OPTIONAL_THEME_DECLARATIONS, type OptionalThemeDeclaration, THEME_FONT_GOOGLE_FAMILIES, type ThemeInput, boardThemeToCss, googleFontsUrl, isOptionalThemeDeclaration, isSafeThemeColorValue, themeFontFamily, themeMode };

package/dist/theme.js

@@ -21,9 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var theme_exports = {};
 __export(theme_exports, {
   BOARD_COLOR_KEYS: () => BOARD_COLOR_KEYS,
+  BOARD_COLOR_TO_CSS_TOKENS: () => BOARD_COLOR_TO_CSS_TOKENS,
+  EMAIL_SAFE_SNAPSHOT_FROM_CSS: () => EMAIL_SAFE_SNAPSHOT_FROM_CSS,
+  OPTIONAL_THEME_DECLARATIONS: () => OPTIONAL_THEME_DECLARATIONS,
   THEME_FONT_GOOGLE_FAMILIES: () => THEME_FONT_GOOGLE_FAMILIES,
   boardThemeToCss: () => boardThemeToCss,
   googleFontsUrl: () => googleFontsUrl,
+  isOptionalThemeDeclaration: () => isOptionalThemeDeclaration,
   isSafeThemeColorValue: () => isSafeThemeColorValue,
   themeFontFamily: () => themeFontFamily,
   themeMode: () => themeMode
@@ -56,37 +60,67 @@ function color(colors, key) {
   if (typeof value !== "string" || !value) return void 0;
   return isSafeThemeColorValue(value) ? value : void 0;
 }
+var EMAIL_SAFE_SNAPSHOT_FROM_CSS = {
+  buttonPrimary: ["primary"],
+  buttonPrimaryText: ["primary-foreground"],
+  background: ["background"],
+  // muted wins; secondary fills only when --muted is absent (A3).
+  mutedBackground: ["muted", "secondary"],
+  border: ["border"],
+  text: ["foreground"],
+  textMuted: ["muted-foreground"],
+  brandColor: ["ring"]
+};
+var BOARD_COLOR_TO_CSS_TOKENS = {
+  background: ["background"],
+  text: [
+    "foreground",
+    "card-foreground",
+    "popover-foreground",
+    "secondary-foreground",
+    "accent-foreground"
+  ],
+  surfaceBackground: ["card", "popover"],
+  mutedBackground: ["secondary", "muted"],
+  highlightBackground: ["accent"],
+  buttonPrimary: ["primary"],
+  buttonPrimaryText: ["primary-foreground"],
+  buttonDanger: ["destructive"],
+  textMuted: ["muted-foreground"],
+  border: ["border", "input"],
+  brandColor: ["ring"],
+  contrastBackground: ["contrast-background"],
+  contrastText: ["contrast-foreground"],
+  textSubtle: ["foreground-subtle"],
+  textDisabled: ["foreground-disabled"],
+  textError: ["foreground-error"]
+};
+var OPTIONAL_THEME_DECLARATIONS = [
+  "foreground-subtle",
+  "foreground-disabled"
+];
+function isOptionalThemeDeclaration(token) {
+  const name = token.startsWith("--") ? token.slice(2) : token;
+  return OPTIONAL_THEME_DECLARATIONS.includes(name);
+}
 function tokenLines(colors) {
   const lines = [];
   const set = (token, value) => {
     if (value) lines.push(`  --${token}: ${value};`);
   };
-  set("background", color(colors, "background"));
-  set("foreground", color(colors, "text"));
-  set("card", color(colors, "surfaceBackground"));
-  set("card-foreground", color(colors, "text"));
-  set("popover", color(colors, "surfaceBackground"));
-  set("popover-foreground", color(colors, "text"));
-  set("primary", color(colors, "buttonPrimary"));
-  set("primary-foreground", color(colors, "buttonPrimaryText"));
-  set("secondary", color(colors, "mutedBackground"));
-  set("secondary-foreground", color(colors, "text"));
-  set("muted", color(colors, "mutedBackground"));
-  set("muted-foreground", color(colors, "textMuted"));
-  set("accent", color(colors, "highlightBackground"));
-  set("accent-foreground", color(colors, "text"));
-  set(
-    "destructive",
-    color(colors, "buttonDanger") ?? color(colors, "textError")
-  );
-  set("border", color(colors, "border"));
-  set("input", color(colors, "border"));
-  set("ring", color(colors, "brandColor") ?? color(colors, "buttonPrimary"));
-  set("contrast-background", color(colors, "contrastBackground"));
-  set("contrast-foreground", color(colors, "contrastText"));
-  set("foreground-subtle", color(colors, "textSubtle"));
-  set("foreground-disabled", color(colors, "textDisabled"));
-  set("foreground-error", color(colors, "textError"));
+  for (const boardKey of BOARD_COLOR_KEYS) {
+    const value = color(colors, boardKey);
+    if (!value) continue;
+    for (const cssToken of BOARD_COLOR_TO_CSS_TOKENS[boardKey]) {
+      set(cssToken, value);
+    }
+  }
+  if (!color(colors, "buttonDanger") && color(colors, "textError")) {
+    set("destructive", color(colors, "textError"));
+  }
+  if (!color(colors, "brandColor") && color(colors, "buttonPrimary")) {
+    set("ring", color(colors, "buttonPrimary"));
+  }
   return lines;
 }
 function boardThemeToCss(theme) {

package/dist/theme.mjs

@@ -26,37 +26,67 @@ function color(colors, key) {
   if (typeof value !== "string" || !value) return void 0;
   return isSafeThemeColorValue(value) ? value : void 0;
 }
+var EMAIL_SAFE_SNAPSHOT_FROM_CSS = {
+  buttonPrimary: ["primary"],
+  buttonPrimaryText: ["primary-foreground"],
+  background: ["background"],
+  // muted wins; secondary fills only when --muted is absent (A3).
+  mutedBackground: ["muted", "secondary"],
+  border: ["border"],
+  text: ["foreground"],
+  textMuted: ["muted-foreground"],
+  brandColor: ["ring"]
+};
+var BOARD_COLOR_TO_CSS_TOKENS = {
+  background: ["background"],
+  text: [
+    "foreground",
+    "card-foreground",
+    "popover-foreground",
+    "secondary-foreground",
+    "accent-foreground"
+  ],
+  surfaceBackground: ["card", "popover"],
+  mutedBackground: ["secondary", "muted"],
+  highlightBackground: ["accent"],
+  buttonPrimary: ["primary"],
+  buttonPrimaryText: ["primary-foreground"],
+  buttonDanger: ["destructive"],
+  textMuted: ["muted-foreground"],
+  border: ["border", "input"],
+  brandColor: ["ring"],
+  contrastBackground: ["contrast-background"],
+  contrastText: ["contrast-foreground"],
+  textSubtle: ["foreground-subtle"],
+  textDisabled: ["foreground-disabled"],
+  textError: ["foreground-error"]
+};
+var OPTIONAL_THEME_DECLARATIONS = [
+  "foreground-subtle",
+  "foreground-disabled"
+];
+function isOptionalThemeDeclaration(token) {
+  const name = token.startsWith("--") ? token.slice(2) : token;
+  return OPTIONAL_THEME_DECLARATIONS.includes(name);
+}
 function tokenLines(colors) {
   const lines = [];
   const set = (token, value) => {
     if (value) lines.push(`  --${token}: ${value};`);
   };
-  set("background", color(colors, "background"));
-  set("foreground", color(colors, "text"));
-  set("card", color(colors, "surfaceBackground"));
-  set("card-foreground", color(colors, "text"));
-  set("popover", color(colors, "surfaceBackground"));
-  set("popover-foreground", color(colors, "text"));
-  set("primary", color(colors, "buttonPrimary"));
-  set("primary-foreground", color(colors, "buttonPrimaryText"));
-  set("secondary", color(colors, "mutedBackground"));
-  set("secondary-foreground", color(colors, "text"));
-  set("muted", color(colors, "mutedBackground"));
-  set("muted-foreground", color(colors, "textMuted"));
-  set("accent", color(colors, "highlightBackground"));
-  set("accent-foreground", color(colors, "text"));
-  set(
-    "destructive",
-    color(colors, "buttonDanger") ?? color(colors, "textError")
-  );
-  set("border", color(colors, "border"));
-  set("input", color(colors, "border"));
-  set("ring", color(colors, "brandColor") ?? color(colors, "buttonPrimary"));
-  set("contrast-background", color(colors, "contrastBackground"));
-  set("contrast-foreground", color(colors, "contrastText"));
-  set("foreground-subtle", color(colors, "textSubtle"));
-  set("foreground-disabled", color(colors, "textDisabled"));
-  set("foreground-error", color(colors, "textError"));
+  for (const boardKey of BOARD_COLOR_KEYS) {
+    const value = color(colors, boardKey);
+    if (!value) continue;
+    for (const cssToken of BOARD_COLOR_TO_CSS_TOKENS[boardKey]) {
+      set(cssToken, value);
+    }
+  }
+  if (!color(colors, "buttonDanger") && color(colors, "textError")) {
+    set("destructive", color(colors, "textError"));
+  }
+  if (!color(colors, "brandColor") && color(colors, "buttonPrimary")) {
+    set("ring", color(colors, "buttonPrimary"));
+  }
   return lines;
 }
 function boardThemeToCss(theme) {
@@ -131,9 +161,13 @@ function googleFontsUrl(theme) {
 }
 export {
   BOARD_COLOR_KEYS,
+  BOARD_COLOR_TO_CSS_TOKENS,
+  EMAIL_SAFE_SNAPSHOT_FROM_CSS,
+  OPTIONAL_THEME_DECLARATIONS,
   THEME_FONT_GOOGLE_FAMILIES,
   boardThemeToCss,
   googleFontsUrl,
+  isOptionalThemeDeclaration,
   isSafeThemeColorValue,
   themeFontFamily,
   themeMode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
   "type": "commonjs",
@@ -50,6 +50,16 @@
         "default": "./dist/filters.js"
       }
     },
+    "./suggest": {
+      "import": {
+        "types": "./dist/suggest.d.mts",
+        "default": "./dist/suggest.mjs"
+      },
+      "require": {
+        "types": "./dist/suggest.d.ts",
+        "default": "./dist/suggest.js"
+      }
+    },
     "./theme": {
       "import": {
         "types": "./dist/theme.d.mts",

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

@@ -1,6 +1,6 @@
 ---
 name: cavuno-board-filters
-description: The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/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: 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.
 ---
 
 # Filters: vocabulary + URL parsing
@@ -21,6 +21,7 @@ never throws).
 - 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
 
@@ -28,19 +29,25 @@ never throws).
 import { parseListingFilters, DEFAULT_SORT } from '@cavuno/board/filters';
 
 const filters = parseListingFilters(rawSearchParams);
-// { q?, remoteOption?, employmentType?, seniority?: Seniority[], sort? }
+// { q?, remoteOption?, employmentType?, seniority?: Seniority[], company?: string[], 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,
 });
 ```
 
 Unknown values are dropped silently (public URLs, never throw). Seniority
-accepts repeated params or a comma-string and normalizes with the hosted
-rules: trim, lowercase, dedupe, keep order.
+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).
+
+**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
 

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

@@ -35,7 +35,7 @@ for (const card of page.data) {
 
 ### Filters and pagination
 
-`JobsListQuery` supports `limit` (1–100), `offset` (takes precedence over `cursor`), `cursor`, and filters: `companyId`, `remoteOption`, `employmentType`, `seniority` (single or repeated → OR-matched), `location` + `radius` (km), `category`, `skill`. Paginate by passing back `nextCursor`, or use numbered pages with `offset`:
+`JobsListQuery` supports `limit` (1–100), `offset` (takes precedence over `cursor`), `cursor`, and filters: `companyId`, `companySlug`, `remoteOption`, `employmentType`, `seniority` (single or repeated → OR-matched), `location` + `radius` (km), `category`, `skill`. Paginate by passing back `nextCursor`, or use numbered pages with `offset`:
 
 ```ts snippet
 const p1 = await board.jobs.list({ limit: 20 });
@@ -46,9 +46,24 @@ const p2 = p1.nextCursor
 const page3 = await board.jobs.list({ limit: 20, offset: 40 });
 ```
 
+### Company filter via public slug
+
+`companySlug` is the public URL identity (what listing URLs carry). Prefer it
+over `companyId` in frontends — the API resolves slugs server-side. Unknown
+slugs are **ignored** (they contribute no matches, not an error); an entirely
+unknown set yields an empty result list with `count: 0`. Combined with
+`companyId` as a union when both are set. Cap is 10 values.
+
+```ts snippet
+const page = await board.jobs.list({
+  limit: 20,
+  companySlug: ['acme', 'globex'],
+});
+```
+
 ## Search
 
-`jobs.search` posts a `JobsSearchBody` (free-text `query` + structured `filters`) and returns a `JobCardSearchEnvelope`:
+`jobs.search` posts a `JobsSearchBody` (free-text `query` + structured `filters`) and returns a `JobCardSearchEnvelope`. The same `companySlug` rule applies under `filters`:
 
 ```ts snippet
 const results = await board.jobs.search({
@@ -56,6 +71,7 @@ const results = await board.jobs.search({
   filters: {
     seniority: ['senior'],
     remoteOption: ['remote'],
+    companySlug: ['acme'],
     publishedAt: { gte: '2026-01-01T00:00:00Z' },
   },
   limit: 20,

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

@@ -0,0 +1,119 @@
+---
+name: cavuno-board-suggest
+description: Federated keyword search suggestions with the @cavuno/board SDK — board.search.suggest for companies + taxonomy terms in one server-ranked list, and the headless createSuggestController under @cavuno/board/suggest (debounce, abort, stale-drop). Use when building a search dropdown, typeahead, or autocomplete that mirrors the hosted board.
+---
+
+# Search suggest: dropdown typeahead
+
+`board.search.suggest` returns ONE interleaved, server-ordered list of
+company and taxonomy-term suggestions for a keyword — the hosted search
+dropdown contract. `@cavuno/board/suggest` wraps that call in a headless
+controller so debounce / abort / stale-drop ship with the SDK and patch via
+npm update.
+
+## When to use
+
+- The global search input's suggestion dropdown.
+- Any typeahead that should offer companies and category/skill terms
+  together, ranked the way the hosted board ranks them.
+
+## When not to use
+
+- Location autocomplete — `board.taxonomy.places.list({ q })`.
+- Taxonomy-only option lists for filter sidebars —
+  `board.taxonomy.categories/skills/suggestions.list`.
+- Job results themselves — `board.jobs.list` / `board.jobs.search`.
+
+## Call the endpoint directly
+
+```ts snippet
+const { items, query } = await board.search.suggest({ q: 'acme', limit: 10 });
+// items is server-ranked — do NOT re-sort.
+for (const item of items) {
+  if (item.type === 'company') {
+    item.slug; // public company URL slug
+    item.name;
+    item.jobCount;
+  } else {
+    // item.type === 'term'
+    item.termType; // 'category' | 'skill'
+    item.displayName;
+    item.canonicalSlug; // for links
+    item.sourceSlug; // for job filters
+  }
+}
+```
+
+Queries under two characters return an empty `items` array. `limit` is
+1–25 (default 25). Order is the contract.
+
+## Prefer the headless controller for UI
+
+The controller owns debounce (default 250ms), min-chars (default 2),
+in-flight abort, and stale-drop. Compatible with `useSyncExternalStore`.
+
+```ts snippet
+import { createSuggestController } from '@cavuno/board/suggest';
+
+const suggest = createSuggestController(board, { limit: 10 });
+const unsub = suggest.subscribe(() => {
+  const { items, status, query } = suggest.getState();
+  // render dropdown; previous items are retained while status === 'loading'
+});
+suggest.setQuery(inputValue);
+// Hide the currently-applied company filter from the list:
+suggest.setExcludedCompanySlugs(appliedCompanySlugs);
+// teardown:
+unsub();
+suggest.dispose();
+```
+
+`setExcludedCompanySlugs` is the ONE permitted view-level filter (company
+items only, re-filters current items synchronously — no new request). Never
+reshape or re-sort the rest of the response.
+
+## Wire a company pick into the listing
+
+Company slugs are the URL identity. Map them onto the jobs surface as
+`companySlug` — never resolve slug→id client-side:
+
+```ts snippet
+import { parseListingFilters } from '@cavuno/board/filters';
+
+const filters = parseListingFilters(rawSearchParams);
+// filters.company is string[] of public slugs
+
+const page = await board.jobs.list({
+  limit: 20,
+  companySlug: filters.company,
+});
+```
+
+Unknown slugs are dropped server-side (not an error). If the entire company
+filter resolves to no known companies, the listing is empty (`count: 0`).
+Combined with `companyId` as a union when both are set.
+
+## Anti-patterns
+
+```ts no-check
+// NEVER re-sort server-ranked items:
+items.sort((a, b) => a.name.localeCompare(b.name));
+// NEVER resolve company slug → id on the client:
+const id = await lookupCompanyId(item.slug);
+board.jobs.list({ companyId: [id] });
+// NEVER hand-roll debounce/abort — use the controller so patches ship via npm.
+```
+
+## Out of scope — do not invent exports
+
+No React components, no dropdown UI, no keyboard navigation — this package
+is the data + controller layer. Location suggest stays on `taxonomy.places`.
+
+## Verify
+
+- [ ] Typing under 2 characters shows no suggestions and no network call
+      from the controller.
+- [ ] Fast typing cancels the previous request; only the final query's
+      results render.
+- [ ] Selecting a company writes its public slug into the URL and the
+      listing request uses `companySlug`, not a client-resolved id.

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.38.0",
+  "version": "1.40.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -52,7 +52,7 @@
     },
     {
       "name": "cavuno-board-filters",
-      "description": "The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/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": "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.",
       "path": "skills/cavuno-board-filters/SKILL.md",
       "framework": null,
       "category": "core"
@@ -148,6 +148,13 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-suggest",
+      "description": "Federated keyword search suggestions with the @cavuno/board SDK — board.search.suggest for companies + taxonomy terms in one server-ranked list, and the headless createSuggestController under @cavuno/board/suggest (debounce, abort, stale-drop). Use when building a search dropdown, typeahead, or autocomplete that mirrors the hosted board.",
+      "path": "skills/cavuno-board-suggest/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-tanstack-start",
       "description": "TanStack-Start-on-Cloudflare-Workers reference wiring for a headless Cavuno board — SSR loaders calling @cavuno/board server-side, the session held in an __Host- httpOnly cookie owned by the app, a single-flight refresh helper, and FetchOptions cache passthrough on Workers.",