@cavuno/board 1.25.0 → 1.27.0

package/dist/theme.mjs

@@ -0,0 +1,128 @@
+// src/theme/index.ts
+var BOARD_COLOR_KEYS = [
+  "brandColor",
+  "buttonPrimary",
+  "buttonPrimaryText",
+  "buttonDanger",
+  "background",
+  "surfaceBackground",
+  "mutedBackground",
+  "highlightBackground",
+  "text",
+  "textSubtle",
+  "textMuted",
+  "textDisabled",
+  "textError",
+  "border",
+  "contrastBackground",
+  "contrastText"
+];
+function color(colors, key) {
+  const value = colors[key];
+  return typeof value === "string" && value ? value : void 0;
+}
+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"));
+  return lines;
+}
+function boardThemeToCss(theme) {
+  if (!theme) return "";
+  const light = tokenLines(theme.colors.light ?? {});
+  const dark = tokenLines(theme.colors.dark ?? {});
+  const fontSans = theme.typography?.fontSans;
+  if (fontSans) {
+    light.push(
+      `  --font-sans: '${themeFontFamily(fontSans)}', ui-sans-serif, system-ui, sans-serif;`
+    );
+  }
+  const blocks = [];
+  if (light.length > 0) blocks.push(`:root {
+${light.join("\n")}
+}`);
+  if (dark.length > 0) blocks.push(`.dark {
+${dark.join("\n")}
+}`);
+  return blocks.join("\n\n");
+}
+function themeMode(theme) {
+  if (!theme) return "system";
+  return theme.mode === "light" || theme.mode === "dark" ? theme.mode : "system";
+}
+var THEME_FONT_GOOGLE_FAMILIES = {
+  "be-vietnam-pro": "Be+Vietnam+Pro",
+  inter: "Inter",
+  "plus-jakarta-sans": "Plus+Jakarta+Sans",
+  "dm-sans": "DM+Sans",
+  "public-sans": "Public+Sans",
+  figtree: "Figtree",
+  "work-sans": "Work+Sans",
+  "open-sans": "Open+Sans",
+  poppins: "Poppins",
+  hind: "Hind",
+  lexend: "Lexend",
+  "fira-sans": "Fira+Sans",
+  manrope: "Manrope",
+  "source-sans-pro": "Source+Sans+3",
+  outfit: "Outfit",
+  "space-grotesk": "Space+Grotesk",
+  geist: "Geist",
+  "source-serif-4": "Source+Serif+4",
+  lora: "Lora",
+  "crimson-pro": "Crimson+Pro"
+};
+function googleFamily(fontKey) {
+  return THEME_FONT_GOOGLE_FAMILIES[fontKey] ?? encodeURIComponent(fontKey).replaceAll("%20", "+");
+}
+function themeFontFamily(fontKey) {
+  return googleFamily(fontKey).replaceAll("+", " ");
+}
+function googleFontsUrl(theme) {
+  if (!theme) return null;
+  const families = /* @__PURE__ */ new Set();
+  if (theme.typography?.fontSans) {
+    families.add(googleFamily(theme.typography.fontSans));
+  }
+  if (theme.typography?.fontHeading) {
+    families.add(googleFamily(theme.typography.fontHeading));
+  }
+  if (families.size === 0) return null;
+  const params = [...families].map((f) => `family=${f}:wght@400;500;600;700`).join("&");
+  return `https://fonts.googleapis.com/css2?${params}&display=swap`;
+}
+export {
+  BOARD_COLOR_KEYS,
+  THEME_FONT_GOOGLE_FAMILIES,
+  boardThemeToCss,
+  googleFontsUrl,
+  themeFontFamily,
+  themeMode
+};

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@cavuno/board",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
+  "type": "commonjs",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wollemiahq/cavuno.git",
@@ -29,6 +30,56 @@
         "default": "./dist/index.js"
       }
     },
+    "./format": {
+      "import": {
+        "types": "./dist/format.d.mts",
+        "default": "./dist/format.mjs"
+      },
+      "require": {
+        "types": "./dist/format.d.ts",
+        "default": "./dist/format.js"
+      }
+    },
+    "./filters": {
+      "import": {
+        "types": "./dist/filters.d.mts",
+        "default": "./dist/filters.mjs"
+      },
+      "require": {
+        "types": "./dist/filters.d.ts",
+        "default": "./dist/filters.js"
+      }
+    },
+    "./theme": {
+      "import": {
+        "types": "./dist/theme.d.mts",
+        "default": "./dist/theme.mjs"
+      },
+      "require": {
+        "types": "./dist/theme.d.ts",
+        "default": "./dist/theme.js"
+      }
+    },
+    "./seo": {
+      "import": {
+        "types": "./dist/seo.d.mts",
+        "default": "./dist/seo.mjs"
+      },
+      "require": {
+        "types": "./dist/seo.d.ts",
+        "default": "./dist/seo.js"
+      }
+    },
+    "./sitemap": {
+      "import": {
+        "types": "./dist/sitemap.d.mts",
+        "default": "./dist/sitemap.mjs"
+      },
+      "require": {
+        "types": "./dist/sitemap.d.ts",
+        "default": "./dist/sitemap.js"
+      }
+    },
     "./skills": {
       "import": {
         "types": "./dist/skills.d.mts",
@@ -49,19 +100,23 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "rm -rf dist && tsup",
     "clean": "git clean -xdf .turbo dist node_modules src/generated",
     "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.node.json",
     "test": "vitest run",
+    "check:publish": "publint --strict && attw --pack . --profile node16",
     "gen:types": "tsx scripts/gen-types.ts",
+    "check:types": "OPENAPI_URL=spec/openapi.snapshot.json tsx scripts/gen-types.ts && git diff --exit-code -- src/generated/openapi-types.ts",
     "gen:skills-manifest": "tsx scripts/generate-skills-manifest.ts",
     "assert-publish-target": "node -e \"const p=require('./package.json'); if(p.name!=='@cavuno/board'){throw new Error('Refusing to publish: package.json name is '+p.name+', expected @cavuno/board')}; if(p.private){throw new Error('Refusing to publish: package.json has private:true')}\"",
     "prepublishOnly": "pnpm run assert-publish-target && pnpm run gen:skills-manifest && pnpm run build"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
     "@kit/tsconfig": "workspace:*",
     "@types/node": "catalog:",
     "openapi-typescript": "^7.6.0",
+    "publint": "^0.3.12",
     "tsup": "^8.4.0",
     "tsx": "^4.19.2",
     "vitest": "^2.1.9"

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

@@ -0,0 +1,147 @@
+---
+name: cavuno-board-account
+description: Candidate account self-service with the @cavuno/board SDK — me.retrieve/delete, the candidate profile (merge-patch update, handle availability), experience/education CRUD, skills/languages full-replace, avatar upload, resume upload with async parse polling, and notification preferences plus the anonymous token unsubscribe. Use when building account, profile-edit, onboarding, or notification-settings pages for a signed-in board user.
+---
+
+# Candidate account self-service
+
+Everything the signed-in candidate manages about themselves lives under `board.me`. Every call here requires a board-user bearer token — in the browser the SDK reads it from `auth.storage` after login; on the server pass it per call via `options.headers` (see `cavuno-board-auth` for the httpOnly-cookie pattern). The one exception is the anonymous token unsubscribe at the end.
+
+## When to use
+
+- Account page: show the signed-in user, delete the account.
+- Profile editor: bio/headline/handle, experience, education, skills, languages, avatar.
+- Resume-driven onboarding (upload → parse → auto-populated profile).
+- Email notification settings + the unsubscribe link in emails.
+
+## When not to use
+
+- Login/registration/tokens — `cavuno-board-auth`.
+- Applications and saved jobs — `cavuno-board-applications`.
+- The employer facet (`me.companies.*`), messaging (`me.conversations.*`), job alerts (`me.alerts.*`).
+
+Out of scope — do not invent exports: the SDK ships no form components, file-picker UI, or upload widgets; the host app owns all UI and cookie plumbing.
+
+## Account: retrieve and delete
+
+```ts snippet
+const me = await board.me.retrieve(); // the authenticated BoardUser
+await board.me.delete(); // 204 — synchronous, irreversible cascade
+```
+
+`delete` removes the account and all dependent data (profile, collections, saved jobs, alerts, avatar/resume files). Gate it behind an explicit confirmation.
+
+## Profile: retrieve, update, handle availability
+
+The profile is a singleton. `update` is a merge-patch — omitted fields stay unchanged.
+
+```ts snippet
+const profile = await board.me.profile.retrieve();
+profile.handle; profile.headline; profile.jobSearchStatus;
+
+await board.me.profile.update({
+  headline: 'Staff Engineer',
+  jobSearchStatus: 'open_to_offers',
+  profileVisibility: 'public',
+});
+
+const { available } = await board.me.profile.handleAvailable('jane');
+```
+
+`handleAvailable` is advisory (my current handle counts as available); `update` re-checks on write.
+
+## Experience and education: per-entry CRUD
+
+Both collections are id-keyed CRUD; updates are merge-patch. `createExperience` requires `title`, `companyName`, `startDate`; `createEducation` requires `institutionName`.
+
+```ts snippet
+const { data: entries } = await board.me.profile.listExperience();
+const entry = await board.me.profile.createExperience({
+  title: 'Staff Engineer',
+  companyName: 'Acme',
+  startDate: '2022-01',
+});
+await board.me.profile.updateExperience(entry.id, { endDate: '2025-06' });
+await board.me.profile.deleteExperience(entry.id);
+// Education mirrors this: listEducation / createEducation /
+// updateEducation(id, body) / deleteEducation(id).
+```
+
+## Skills and languages: PUT full-replace
+
+`updateSkills` / `updateLanguages` replace the **whole set** — there is no add/remove-one endpoint. Sending only the new item wipes the rest. Round-trip the current list:
+
+```ts snippet
+const current = await board.me.profile.listSkills();
+await board.me.profile.updateSkills({
+  skills: [...current.data.map((s) => s.name), 'TypeScript'], // ordered names
+});
+
+await board.me.profile.updateLanguages({
+  languages: [{ name: 'English', proficiency: 'native' }],
+});
+```
+
+Both return the full updated list envelope, so you can render straight from the response.
+
+## Avatar upload
+
+Pass a `Blob`/`File` — the SDK builds the multipart `FormData` (field `file`). JPEG/PNG/WebP, ≤ 5 MB.
+
+```ts snippet
+const { avatarUrl } = await board.me.profile.uploadAvatar(file);
+```
+
+## Resume: upload, then poll the parse
+
+`upload` starts an **async parse** that auto-populates the profile. It returns the resume with `parseStatus: 'parsing'` — poll `retrieve()` until `parsed` or `failed`, then re-read `profile.*` for the populated fields. Options: `keepResumeOnFile`, `importMode: 'append_only' | 'replace_all'`, `confirmReplaceAll`.
+
+```ts snippet
+let resume = await board.me.resume.upload(file, { keepResumeOnFile: true });
+// Bounded poll — a stuck parse job must not hang the UI forever.
+const MAX_POLLS = 30; // ~60s at 2s cadence
+for (let i = 0; resume.parseStatus === 'parsing' && i < MAX_POLLS; i++) {
+  await new Promise((r) => setTimeout(r, 2000));
+  resume = await board.me.resume.retrieve();
+}
+if (resume.parseStatus === 'parsed') {
+  const profile = await board.me.profile.retrieve(); // auto-populated
+} else if (resume.parseStatus === 'failed') {
+  resume.parseFailureReason; // surface it
+} else {
+  // still 'parsing' after the window: show "taking longer than usual",
+  // keep the manual profile editor usable — never block on the parse.
+}
+```
+
+`resume.file` holds the stored file (`url` is a short-lived signed download URL). `parseStatus` is `null` when no parse has run. `board.me.resume.delete()` removes the stored file and withdraws keep-on-file consent — parsed profile fields stay.
+
+## Notification preferences + anonymous unsubscribe
+
+Two channels today: `messageEmails` and `applicationEmails`. `update` toggles one and returns the full updated set.
+
+```ts snippet
+const { data: prefs } = await board.me.notificationPreferences.retrieve();
+await board.me.notificationPreferences.update({
+  channel: 'messageEmails',
+  subscribed: false,
+});
+```
+
+The one-click unsubscribe link in emails is **anonymous** — no session; the HMAC token is the authorization. All three fields come from the link's query string; resolves void (204):
+
+```ts snippet
+await board.me.notificationPreferences.unsubscribeWithToken({
+  boardUserId,
+  channel: 'applicationEmails',
+  token,
+});
+```
+
+## Verify
+
+- [ ] A profile `update` followed by `retrieve` shows the new field values.
+- [ ] Adding a skill preserves the existing ones (the full-replace round-trip is in place).
+- [ ] After `uploadAvatar`, the returned `avatarUrl` renders.
+- [ ] Resume upload reaches `parsed` (or surfaces `failed` + `parseFailureReason`), and the profile shows parsed data.
+- [ ] The email unsubscribe link works in a logged-out browser.

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

@@ -0,0 +1,110 @@
+---
+name: cavuno-board-applications
+description: The native apply flow with the @cavuno/board SDK — jobs.apply (signed-in or guest), attaching a resume via jobs.uploadApplicationResume, the jobs.myApplication "have I applied?" check, managing submitted applications (me.applications list/retrieve/updateFacts/withdraw), and saved jobs (me.savedJobs). Use when building an apply form, an application-tracker page, or a save-job button.
+---
+
+# Apply flow and application tracking
+
+Apply lives on the job (`board.jobs.apply` — optional-auth); everything after submission lives under `board.me.applications` (bearer token required, see `cavuno-board-auth`). Saved jobs follow the same authenticated pattern.
+
+## When to use
+
+- The apply form on a job page (native apply, signed-in or guest).
+- Attaching a resume to an application.
+- "My applications" tracker: list, detail, edit facts, withdraw.
+- Save/unsave-job buttons and the saved-jobs page.
+
+## When not to use
+
+- Jobs whose `applicationUrl` points off-board (external apply) — just link out.
+- The employer's pipeline view of the same data (`me.companies.applicants.*`).
+- Candidate profile/resume self-service — `cavuno-board-account`.
+
+Out of scope — do not invent exports: the SDK provides no apply-form components, file-picker UI, or auth cookie plumbing — the host app owns those. There is also **no guest-claim method** on the SDK: after a guest signs up, their applications are associated via a server-driven magic-link email flow, not an SDK call.
+
+## Submit an application
+
+`jobs.apply` is optional-auth on one URL. Signed in, name/email derive from the candidate profile — send at most a `coverNote`. A guest supplies `name` + `email` (allowed only when the board permits applying without sign-up; otherwise the call fails). Idempotent — a repeat apply returns the existing application.
+
+```ts snippet
+// Signed-in candidate:
+const application = await board.jobs.apply('senior-chef', {
+  coverNote: 'Excited to cook here.',
+});
+
+// Guest (board must allow applications without sign-up):
+const guestApp = await board.jobs.apply('senior-chef', {
+  name: 'Ada Lovelace',
+  email: 'ada@example.com',
+});
+```
+
+## Attach a resume
+
+A separate multipart call — pass a `Blob`/`File`; the SDK builds the `FormData`. A signed-in candidate targets their own application for the job; a guest passes the `applicationId` returned by `apply`. Returns the updated application (`resumeFilename` set).
+
+```ts snippet
+// Signed-in:
+await board.jobs.uploadApplicationResume('senior-chef', file);
+// Guest:
+await board.jobs.uploadApplicationResume('senior-chef', file, {
+  applicationId: guestApp.id,
+});
+```
+
+## "Have I applied?" — the apply-button state
+
+`jobs.myApplication` returns the authenticated candidate's application for the job, and **throws a 404 `BoardApiError` when there is none** — branch with `isNotFound`:
+
+```ts snippet
+import { isNotFound } from '@cavuno/board';
+
+try {
+  const mine = await board.jobs.myApplication('senior-chef');
+  // already applied — show status instead of the apply button
+} catch (err) {
+  if (!isNotFound(err)) throw err;
+  // not applied yet — show the apply form
+}
+```
+
+## Application status — polled, not realtime
+
+`Application.status` is a coarse candidate-facing state **derived from the employer's pipeline stage**: `'applied' | 'interviewing' | 'negotiation' | 'hired' | 'archived'`. It changes server-side as the employer moves the applicant — the surface is plain REST, so re-fetch to observe updates; nothing pushes to the client. `job` on the application is nullable (the job may have been removed).
+
+## Manage my applications
+
+```ts snippet
+const { data, nextCursor } = await board.me.applications.list({ limit: 20 }); // newest first
+const app = await board.me.applications.retrieve(applicationId);
+
+// Merge-patch the candidate-facing facts — only while still editable:
+await board.me.applications.updateFacts(applicationId, {
+  coverNote: 'Updated after our call.',
+});
+
+await board.me.applications.withdraw(applicationId); // 204 — permanently deletes
+```
+
+`updateFacts` accepts `candidateName`, `candidateEmail`, `candidateHeadline`, `candidateLocation`, `coverNote` (all optional). Withdraw is permanent deletion, not a status flip — confirm before calling.
+
+## Saved jobs — the adjacent pattern
+
+Same authenticated `me.*` shape. Each saved row embeds the full `PublicJob`, so the saved-jobs page renders without extra fetches.
+
+```ts snippet
+const saved = await board.me.savedJobs.list({ limit: 20 });
+saved.data[0]?.job.title; // full PublicJob embedded
+
+await board.me.savedJobs.save({ jobId: job.id }); // converges — re-saving returns the same row
+await board.me.savedJobs.unsave(job.id); // idempotent — unknown ids still 204
+```
+
+## Verify
+
+- [ ] Signed-in apply sends no name/email; guest apply sends both.
+- [ ] A second apply to the same job returns the same application id (no duplicate).
+- [ ] After `uploadApplicationResume`, the application's `resumeFilename` is set.
+- [ ] The apply button flips state via `myApplication` + `isNotFound`, not a local flag.
+- [ ] Withdraw removes the row from `me.applications.list` on re-fetch.
+- [ ] Unsave leaves the saved-jobs list consistent even when clicked twice.

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

@@ -0,0 +1,99 @@
+---
+name: cavuno-board-blog
+description: Build the blog with the @cavuno/board SDK — post archives (blog.posts.list with tagSlug/authorSlug/featured), the post page (blog.posts.retrieve + adjacent + similar), blog.tags and blog.authors, and free-text blog.search. Covers the summary-vs-detail split (html on the single read only), cursor pagination, slug-change redirects (redirected/newSlug), and the SEO fields the API actually returns.
+---
+
+# Blog: posts, tags, authors, search
+
+Every list and search returns `PublicBlogPostSummary`; only `posts.retrieve` returns the full `PublicBlogPost` with the `html` body.
+
+## When to use
+
+- The blog index, tag archives, author archives, and featured rails.
+- The post page: body, prev/next nav, related-posts rail.
+- Blog search boxes.
+
+## When not to use
+
+- Writing posts/tags/authors — that is the admin API; this SDK is the public read surface.
+- Deciding whether the board has a blog at all — read `features.blog` from the board context.
+
+Out of scope — do not invent exports: no RSS feed, sitemap, or OG-image generation — the host app builds those routes from the data here (`publishedAt`, `canonicalUrl`, `ogImageUrl` are all returned).
+
+## List posts and archives
+
+`blog.posts.list` returns a `ListEnvelope<PublicBlogPostSummary>`. `BlogPostsListQuery` supports `limit` (1–100), `cursor`, `tagSlug`, `authorSlug`, and `featured: 'true'` (opt-in only — the string literal, not a boolean). Blog lists page by cursor only; there is no `offset` and no total `count`.
+
+```ts snippet
+const page = await board.blog.posts.list({ tagSlug: 'news', limit: 12 });
+for (const post of page.data) {
+  post.title;
+  post.customExcerpt;   // null unless the author wrote one
+  post.coverUrl;        // null when no cover image
+  post.readingTimeMin;
+  post.authors;         // embedded: id, name, slug, bio, avatarUrl, social URLs
+  post.tags;            // embedded: id, name, slug, description
+}
+const next = page.nextCursor
+  ? await board.blog.posts.list({ tagSlug: 'news', limit: 12, cursor: page.nextCursor })
+  : null; // nextCursor is null when hasMore is false
+```
+
+## Render a post
+
+`posts.retrieve` adds the detail-only fields: `html` (the rendered rich-text body, nullable), `ogImageUrl`, `featureImageCaption`, `seoTitle`, `seoDescription`, `redirected`, `newSlug`.
+
+```ts snippet
+const post = await board.blog.posts.retrieve('hello-world');
+if (post.redirected && post.newSlug) {
+  // the slug changed — redirect to the post at newSlug instead of rendering here
+}
+post.html;                          // inject as the article body
+post.seoTitle ?? post.title;        // <title>
+post.seoDescription ?? post.customExcerpt; // meta description
+post.canonicalUrl;                  // author-set canonical override, or null
+post.ogImageUrl ?? post.coverUrl;   // social card image
+```
+
+Anti-pattern: don't render a post at a stale URL. When `redirected` is true, issue a redirect to `newSlug` — old slugs keep resolving, but the canonical location moved.
+
+Anti-pattern: don't look for `html` on list items. Summaries never carry it; fetch `retrieve` for the post page only.
+
+## Prev/next and related
+
+```ts snippet
+const { previous, next } = await board.blog.posts.adjacent('hello-world');
+// previous = older post, next = newer; each a summary or null
+
+const rail = await board.blog.posts.similar('hello-world', { limit: 6 }); // 1–20, default 6
+```
+
+## Tags and authors
+
+Both are list + retrieve-by-slug. `PublicBlogTag`: `id`, `name`, `slug`, `description`. `PublicBlogAuthor`: `id`, `name`, `slug`, `bio`, `avatarUrl`, `websiteUrl`, `twitterUrl`, `linkedinUrl`, `githubUrl`.
+
+```ts snippet
+const { data: tags } = await board.blog.tags.list();
+const tag = await board.blog.tags.retrieve('news');
+const { data: authors } = await board.blog.authors.list();
+const author = await board.blog.authors.retrieve('jane');
+```
+
+Archive pages combine the two: `tags.retrieve` for the header, `posts.list({ tagSlug })` for the posts.
+
+## Search
+
+`blog.search` posts a `BlogSearchBody` (`query` up to 200 chars, optional `cursor`, `limit` 1–50 — note the lower cap than lists) and returns a `SearchEnvelope<PublicBlogPostSummary>`:
+
+```ts snippet
+const results = await board.blog.search({ query: 'launch', limit: 10 });
+results.data[0]?.slug;
+```
+
+## Verify
+
+- A list item has no `html` key; `posts.retrieve` of the same slug returns it (string or null).
+- Retrieving a post by an old slug returns `redirected: true` with `newSlug` set, and your route redirects there.
+- `posts.list({ featured: 'true' })` returns only posts with `featured: true`.
+- Cursor paging terminates: `nextCursor` is `null` on the last page.
+- `adjacent` on the newest post returns `next: null`; on the oldest, `previous: null`.

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

@@ -0,0 +1,99 @@
+---
+name: cavuno-board-companies
+description: Build company surfaces with the @cavuno/board SDK — the companies index (companies.list / companies.search with the market filter), the company profile (companies.retrieve, listJobs, similar), the markets sub-surface (companies.markets + markets.resolve with its 308 redirectTo), and company salary pages (companies.salaries + salaries.category). Covers PublicCompany vs PublicCompanyDetail and envelope pagination.
+---
+
+# Companies: index, profile, markets, salaries
+
+Lists and search return `PublicCompany`; only `retrieve` returns `PublicCompanyDetail` (which adds `markets`). Company salary pages are their own sub-surface under `companies.salaries`.
+
+## When to use
+
+- The companies index page and its market (sector) filter.
+- The company profile page: detail, open-jobs list, similar-companies rail.
+- Per-company salary pages (`/companies/:slug/salaries[/:category]`).
+
+## When not to use
+
+- Board-wide job browse/search — `jobs.*` (see cavuno-board-jobs).
+- Board-wide salary hubs (titles/skills/locations) — `board.salaries.*`.
+- Employer self-service (claiming/managing a company) — the authed `board.me.companies.*` surface.
+
+Out of scope — do not invent exports: no company create/update/logo upload (that is the admin API, not this SDK), and no sitemap or OG-image generation — the host app owns those routes.
+
+## List, search, market filter
+
+`companies.list` returns a `CompanyListEnvelope`: `ListEnvelope<PublicCompany>` plus optional `relatedSearches` (market suggestions). `CompaniesListQuery` supports `limit` (1–100), `cursor`, `offset` (takes precedence over `cursor`; pair with the response `count` to page in parallel), and `marketSlug` — unknown market slugs 404.
+
+```ts snippet
+const page = await board.companies.list({ limit: 20, marketSlug: 'cybersecurity' });
+page.hasMore;
+page.nextCursor; // null when hasMore is false
+for (const company of page.data) {
+  company.name;
+  company.publishedJobCount;
+  company.links.public; // canonical URL, or null when the company lacks a slug
+}
+```
+
+`companies.search` posts a `CompaniesSearchBody` (`query` free text matched against the company name, up to 200 chars; optional `marketSlug`, `cursor`, `limit` 1–100) and returns a `SearchEnvelope<PublicCompany>`:
+
+```ts snippet
+const results = await board.companies.search({ query: 'acme', limit: 20 });
+```
+
+## Markets (sectors)
+
+`companies.markets` is callable AND carries `.resolve`. The call lists the board's markets ranked by company count (`CompanyMarket`: `slug`, `name`, `companyCount`; `limit` 1–200, default 100 — a top-N preview; optional `search`). `.resolve(slug)` returns a `TaxonomyResolution` — `sourceSlug`, `canonicalSlug`, `displayName`, and `redirectTo` (the canonical slug to 308 to when the inbound slug differs; `null` otherwise).
+
+```ts snippet
+const { data: markets } = await board.companies.markets({ search: 'robotics' });
+const market = await board.companies.markets.resolve('cybersecurity');
+if (market.redirectTo) {
+  // 308 the market-scoped browse to the canonical slug
+}
+```
+
+Resolve first, then pass the resolved slug as `marketSlug` — don't guess slugs (unknown ones 404).
+
+## Profile: retrieve, jobs, similar
+
+`PublicCompany` (lists/search) carries: `id`, `name`, `slug`, `website`, `logoUrl`, `description`, `jobCount`, `publishedJobCount`, `links.public`. `PublicCompanyDetail` (retrieve only) adds `markets: CompanyMarketRef[]` (`name` + source `slug`; empty when none).
+
+```ts snippet
+const company = await board.companies.retrieve('acme'); // PublicCompanyDetail
+company.markets;                                        // detail-only
+
+const jobs = await board.companies.listJobs('acme', { limit: 10 });
+// JobCardListEnvelope — same PublicJobCard shape as jobs.list; cursor + limit only
+
+const rail = await board.companies.similar('acme', { limit: 6 }); // 1–20, default 6
+```
+
+`similar` uses the hosted ranking (most open roles first) and excludes the company itself.
+
+Anti-pattern: don't render `markets` from a list row — it only exists on the detail. Fetch `retrieve` for the profile page.
+
+## Company salaries
+
+`companies.salaries` is callable AND carries `.category`. The call is the company salary overview (`CompanySalary`): `overallSalary` (nullable), `bySeniority` rows vs the board baseline (`diffPercent`), `competitors`, `topLocations`, `byCategory`, board-wide baselines, and `currency`. `.category(companySlug, categorySlug, { locale })` is one job category at the company (`CompanyCategorySalary`).
+
+```ts snippet
+const overview = await board.companies.salaries('acme');
+overview.bySeniority[0]?.diffPercent; // vs the board baseline, or null
+
+const cat = await board.companies.salaries.category('acme', 'software-engineer', {
+  locale: 'de',
+});
+cat.categorySourceSlug;    // immutable English slug
+cat.categoryCanonicalSlug; // board-language slug — 308 to it when the inbound differs
+```
+
+Pass `{ locale }` for board-language category names; the company slug/name are never localized. The response returns BOTH `categorySourceSlug` and `categoryCanonicalSlug` — the consumer issues the 308 itself.
+
+## Verify
+
+- `companies.retrieve('<known-slug>')` returns `object: 'public_company'` with a `markets` array; the same company in `companies.list` has no `markets` key.
+- A slug from `companies.markets()` works as `marketSlug`; a made-up slug returns 404 (`isNotFound`).
+- Paginating with `nextCursor` terminates: `nextCursor` is `null` on the last page.
+- `companies.salaries.category(...)` with a non-canonical category slug returns a differing `categoryCanonicalSlug`, and your route 308s to it.