@cavuno/board 1.25.0 → 1.26.0

package/skills/cavuno-board-job-posting/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: cavuno-board-job-posting
+description: Build the anonymous "Post a job" funnel with the @cavuno/board SDK — jobPosting.plans, create and its status-discriminated JobPostingResult (checkout / published / pending_approval / invoice_sent), logo upload + fetchLogoByDomain, and the email-verified billing helpers (checkBilling, sendBillingVerification, getBillingOptions, checkSubscriptionEntitlements).
+---
+
+# Job posting: the anonymous submission funnel
+
+The no-account "Post a job" wizard (ADR-0042): pick a plan, upload a logo, submit — then branch on the status-discriminated result. Anonymous by design (no board-user token) and rate-limited server-side.
+
+Out of scope — do not invent exports: the `checkout` branch returns a Stripe Checkout **URL** — the full-page redirect is host-app-owned, and the webhook publishes the job after payment. The SDK ships no Stripe code and no publish/confirm method for the paid path.
+
+## When to use
+
+- The public `/post` wizard: plan picker, logo step, submission, and the post-submit screen.
+- Letting an existing plan/bundle holder submit against remaining capacity via email verification.
+
+## When not to use
+
+- Authenticated employer job management (drafts, edit, republish, ATS) — that is `board.me.companies.jobs.*`.
+- The candidate-access paywall — see `cavuno-board-paywall`.
+
+## Plans
+
+The chosen plan's `id` goes in `submission.selectedPlan`:
+
+```ts snippet
+const { data: plans } = await board.jobPosting.plans();
+for (const plan of plans) {
+  plan.id;            // → submission.selectedPlan
+  plan.prices;        // [{ currency, amountCents, isActive }]
+  plan.invoiceOnly;   // collect invoiceBilling instead of paying now
+  plan.isRecommended; // highlight in the picker
+  plan.features;      // [{ key, value }] rows for the plan card
+}
+```
+
+## Logo
+
+Upload a file, or fetch by company domain (Brandfetch). Both return a stored `publicUrl` you pass back as `logoUrl` on `create(...)`:
+
+```ts snippet
+const logo = await board.jobPosting.uploadLogo(file); // JPEG/PNG/WebP/GIF, ≤2 MB
+// or:
+const fetched = await board.jobPosting.fetchLogoByDomain('acme.com');
+// a BoardApiError code 'job_posting_logo_not_found' = no usable logo — continue without one
+```
+
+## Submit and branch on the result
+
+`create` returns a `JobPostingResult` — a discriminated union on `.status` with exactly four variants. The host app **must** branch on it; a rejected submission throws a `BoardApiError` instead.
+
+```ts snippet
+const result = await board.jobPosting.create({
+  submission: {
+    companyName: 'Acme',
+    contactName: 'Ada',
+    contactEmail: 'ada@acme.com',
+    title: 'Staff Engineer',
+    description: '<p>…</p>',
+    employmentType: 'full_time',
+    remoteOption: 'remote',
+    officeLocations: [],
+    applicationUrl: 'https://acme.com/apply',
+    salaryRangeEnabled: false,
+    selectedPlan: plan.id,
+  },
+  logoUrl: logo.publicUrl,
+});
+
+switch (result.status) {
+  case 'checkout':         // paid plan → send the poster to Stripe
+    location.href = result.checkoutUrl; // webhook publishes on payment
+    break;
+  case 'published':        // live now
+    result.jobSlug;        // link straight to the job
+    break;
+  case 'pending_approval': // moderated board — live after review
+    result.jobId;
+    break;
+  case 'invoice_sent':     // invoice plan — a Stripe invoice was emailed
+    result.jobId;
+    break;
+}
+```
+
+The five billing paths map onto those four statuses: paid-Stripe → `checkout`; free and existing bundle/subscription credit publish without payment (`published`, or `pending_approval` on moderated boards); invoice plans → `invoice_sent`.
+
+## Existing credit: the verified-email branch
+
+A submitter whose email already holds a plan/bundle can post against remaining capacity — no new charge. Verify the email first; an option's fields become `selectedBilling`:
+
+```ts snippet
+const { hasActiveBilling } = await board.jobPosting.checkBilling({ email });
+if (hasActiveBilling) {
+  await board.jobPosting.sendBillingVerification({ email }); // emails a token
+  // …the poster pastes/clicks the token…
+  const { options } = await board.jobPosting.getBillingOptions({
+    verificationToken,
+  });
+  const option = options[0]!;
+  option.jobsRemaining;     // capacity left
+  option.featuredRemaining; // featured slots left
+  option.renewsAt;
+
+  await board.jobPosting.create({
+    submission, // as above — selectedPlan not needed on this path
+    selectedBilling: { type: option.type, id: option.id, planId: option.planId },
+  });
+}
+```
+
+For subscription holders, gate the "featured" toggle on entitlements:
+
+```ts snippet
+const ent = await board.jobPosting.checkSubscriptionEntitlements({
+  email,
+  planId: plan.id,
+});
+ent.hasSubscription;
+ent.canFeature;             // may the wizard offer isFeatured?
+ent.featuredSlotsRemaining; // and how many
+ent.maxActiveRemaining;
+```
+
+## Verify
+
+- [ ] Every `create` call site handles all four `result.status` variants — no fallthrough that assumes `published`.
+- [ ] A paid-plan submission lands on Stripe via `result.checkoutUrl`, and the job appears on the board only after payment (webhook), not on redirect.
+- [ ] A free-plan submission on an unmoderated board returns `published` with a `jobSlug` that resolves.
+- [ ] `fetchLogoByDomain` on a bogus domain surfaces the not-found error path, and the wizard still submits without a logo.

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

@@ -85,6 +85,21 @@ if (page.gatedCount && page.gatedCount > 0) {
 
 A board-user bearer token on the same call returns the entitled (ungated) view — the endpoint is optional-auth, one URL for both anonymous and personalized reads.
 
+## Full-catalog walks: paginate()
+
+For sitemaps, feeds, or exports, never hand-roll the cursor loop — `paginate()` iterates items (or raw pages via `.pages()`) until `hasMore` is false, and drops `offset` after the first page (offset would win over the cursor and re-serve the same page forever):
+
+```ts snippet
+import { paginate } from '@cavuno/board';
+
+for await (const card of paginate(board.jobs.list, { limit: 100 })) {
+  urls.push(card.links.public);
+}
+const first500 = await paginate(board.jobs.list).toArray({ limit: 500 });
+```
+
+Iteration order is stable only under an explicit sort/search — a churning board reorders default browse results between pages.
+
 ## Checklist
 
 - [ ] Listing/search use `PublicJobCard`; detail uses `PublicJob`.

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

@@ -0,0 +1,121 @@
+---
+name: cavuno-board-messaging
+description: Build the board-user messaging inbox with the @cavuno/board SDK — me.conversations (list, unreadCount, retrieve, listMessages, start, reply, markRead, archive), me.messages (edit, unsend, report), me.blocks. Covers the polled-REST contract (no realtime transport in v1), visibility-aware polling, the unread badge, and read receipts.
+---
+
+# Messaging: the polled inbox
+
+Employer↔candidate direct messaging for signed-in board users. The v1 transport is **polled REST by design (ADR-0053)** — there is no realtime primitive; near-live UX comes from re-fetching on an interval (3–5s is the reference cadence).
+
+Out of scope — do not invent exports: no websockets, no SSE, no `subscribe`/`onMessage` — polling `list` / `listMessages` / `unreadCount` IS the contract.
+
+## When to use
+
+- The inbox page, unread badge, thread view, and composer.
+- Edit/unsend, report-a-message, and block flows.
+
+## When not to use
+
+- Anonymous visitors — every method here requires a signed-in board user (see `cavuno-board-auth`).
+- Job applications themselves — messaging an applicant *starts from* an application, but the application surface is `board.me.applications.*`.
+
+## Poll while visible
+
+Poll only while the tab is visible — stop on hide, resume (with an immediate refresh) on show:
+
+```ts snippet
+const POLL_MS = 4000; // 3–5s reference cadence
+
+async function refresh() {
+  const [{ count }, inbox] = await Promise.all([
+    board.me.conversations.unreadCount(), // distinct unread threads → badge
+    board.me.conversations.list({ limit: 20 }),
+  ]);
+  render(count, inbox.data);
+}
+
+let timer: ReturnType<typeof setInterval> | undefined;
+function start() {
+  void refresh();
+  timer ??= setInterval(refresh, POLL_MS);
+}
+function stop() {
+  clearInterval(timer);
+  timer = undefined;
+}
+document.addEventListener('visibilitychange', () => {
+  document.visibilityState === 'visible' ? start() : stop();
+});
+start();
+```
+
+Each inbox row is a `Conversation`: `lastMessageAt`, `lastMessageSnippet`, `hasUnread`, and a live-resolved `counterparty` (`displayName`, `avatarUrl`, `companyName`, `handle`). `list({ archived: true })` is the archived view; `archive`/`unarchive` move a thread per-side and are idempotent.
+
+## The thread: header, messages, read receipts
+
+The header and the messages are separate calls. Messages come oldest-first; unsent messages are tombstones (empty `body`, `deletedAt` set) — render a placeholder, don't filter them out.
+
+```ts snippet
+const convo = await board.me.conversations.retrieve(conversationId);
+convo.viewerRole;              // 'employer' | 'candidate'
+convo.viewerLastReadMessageId; // my last-read pointer (null = never)
+
+const { data: messages } = await board.me.conversations.listMessages(
+  conversationId,
+  { limit: 50 },
+);
+for (const m of messages) {
+  m.body;     // '' when unsent (tombstone)
+  m.readAt;   // read receipt — when the recipient read it, or null
+  m.editedAt; // non-null after an edit
+}
+
+await board.me.conversations.markRead(conversationId); // idempotent
+```
+
+Call `markRead` when the viewer opens the thread — it clears `hasUnread` and drives the counterparty's `readAt` receipts.
+
+## Sending
+
+`start` cold-initiates a candidate (employer-only) and converges on the existing thread; `startAboutApplication` messages an applicant in application context; `reply` continues a thread. Each returns the created `Message`.
+
+```ts snippet
+// Route to an existing thread instead of opening a composer:
+const { conversationId } = await board.me.conversations.findExisting({
+  candidateBoardUserId,
+});
+
+const first = await board.me.conversations.start({
+  candidateBoardUserId,
+  body: 'Hi — your profile looks like a great fit.',
+});
+await board.me.conversations.reply(first.conversationId, {
+  body: 'Following up!',
+});
+```
+
+Sends are gated server-side (messaging enabled, cold-message rule, per-pair daily limits, blocks) — failures arrive as `messaging_*` `BoardApiError` codes; branch with the guards from `cavuno-board-errors`.
+
+## Edit, unsend, report, block
+
+Your own messages can be edited or unsent within a 15-minute window. Reporting a message addressed to you auto-blocks its author.
+
+```ts snippet
+await board.me.messages.edit(messageId, { body: 'fixed typo' });
+await board.me.messages.unsend(messageId); // tombstones; idempotent
+
+const { blocked } = await board.me.messages.report(messageId, {
+  reason: 'spam', // 'spam' | 'harassment' | 'misrepresentation' | 'other'
+});
+
+await board.me.blocks.create({ boardUserId }); // silent; idempotent
+```
+
+`board.me.blocks.list()` / `.remove(boardUserId)` / `.status(boardUserId)` round out blocking.
+
+## Verify
+
+- [ ] Kill the network tab timer: polling stops when the tab is hidden, resumes on focus with a fresh read.
+- [ ] Send from a second account: the badge (`unreadCount().count`) and `hasUnread` flip within one poll interval.
+- [ ] Open the thread: `markRead` fires once and the sender sees `readAt` populate on their next poll.
+- [ ] Unsend a message: it renders as a tombstone (empty `body`), not a gap.

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

@@ -0,0 +1,108 @@
+---
+name: cavuno-board-paywall
+description: Build the candidate job-access paywall with the @cavuno/board SDK — anonymous offer reads (paywall.offers), the gated browse experience (gatedCount on job lists), the embedded Stripe checkout mount kit (me.access.checkout → retrieveCheckout → grant), and the billing portal (me.access.portal for recurring grants).
+---
+
+# Candidate paywall: offers, checkout, grant
+
+The candidate-facing money flow (doc 36 / ADR-0056): anonymous pricing, gated job lists, and an embedded Stripe checkout that ends in an access grant.
+
+Out of scope — do not invent exports: the SDK is Stripe-agnostic. It returns a *mount kit*; loading Stripe.js (`loadStripe`, `initEmbeddedCheckout`) and every redirect is host-app-owned. There is no SDK helper that mounts, redirects, or handles webhooks.
+
+## When to use
+
+- The pricing/upsell page, the gated jobs view, the checkout page, and the "manage subscription" button.
+
+## When not to use
+
+- Board-password gating (`X-Board-Access`) — unrelated; see `cavuno-board-errors`.
+- Employer job-posting payments — see `cavuno-board-job-posting`.
+
+## Offers (anonymous)
+
+`board.paywall.offers()` lists the enabled offer tiers — public, no auth. Returns `[]` when the paywall is disabled (the internal Stripe price id is never exposed).
+
+```ts snippet
+const { data: offers } = await board.paywall.offers();
+for (const offer of offers) {
+  offer.offerKey;     // e.g. 'monthly' — what you post to checkout
+  offer.label;
+  offer.billingLabel;
+  offer.amountCents;
+  offer.currency;
+  offer.offerType;    // 'recurring' | 'lifetime'
+  offer.isDefault;    // pre-select this tier
+}
+```
+
+## The gated browse: gatedCount
+
+On gated boards the jobs catalog reads (browse / search / company-jobs) withhold results from unentitled viewers and report how many via `gatedCount` on the envelope. Surface it as the upsell:
+
+```ts snippet
+const page = await board.jobs.list({ limit: 20 });
+if (page.gatedCount && page.gatedCount > 0) {
+  // "Unlock N more roles" → link to the offers page
+}
+```
+
+The same call with an entitled board-user bearer token returns the ungated view — one URL for both.
+
+## Checkout: mint the mount kit
+
+`board.me.access.checkout` (signed-in, candidate profile required) starts an embedded checkout and returns a connected-account mount kit — `{ sessionId, clientSecret, stripeAccountId, publishableKey, offerType }`. `returnPath` is relative-only; the server resolves it against the board's canonical host and appends `?session_id={CHECKOUT_SESSION_ID}`.
+
+```ts snippet
+import { loadStripe } from '@stripe/stripe-js'; // host-app dependency
+
+const kit = await board.me.access.checkout({
+  offerKey: 'monthly',           // the chosen PaywallOffer.offerKey
+  returnPath: '/account/access', // relative path Stripe returns to
+  colorMode: 'light',
+});
+
+// Host-owned mounting — stripeAccount is required for connected-account embeds:
+const stripe = await loadStripe(kit.publishableKey, {
+  stripeAccount: kit.stripeAccountId,
+});
+```
+
+Duplicate POSTs are benign (a second session simply expires unpaid) — no idempotency machinery needed.
+
+## Completion: poll the session, confirm the grant
+
+`retrieveCheckout(sessionId)` reports `open` (re-mountable — `clientSecret` set), `complete`, or `expired`. On completion, the entitlement lands via webhook within seconds — `grant()` is the source of truth, and it always resolves (no access is `hasAccess: false`, not an error):
+
+```ts snippet
+const state = await board.me.access.retrieveCheckout(kit.sessionId);
+// 'open'     → remount with state.clientSecret
+// 'expired'  → mint a fresh session
+// 'complete' → poll the grant until the webhook lands:
+
+const grant = await board.me.access.grant();
+grant.hasAccess;         // gate the ungated jobs view on this
+grant.status;            // 'active' | 'past_due' | … | null
+grant.offerType;         // 'recurring' | 'lifetime' | null
+grant.currentPeriodEnd;
+grant.cancelAtPeriodEnd;
+```
+
+Gate failures throw `paywall_*` codes (`paywall_disabled`, `paywall_no_candidate_profile`, `paywall_offer_not_found`, `paywall_already_active`, `paywall_invalid_checkout_session`) — branch with the guards from `cavuno-board-errors`.
+
+## Manage subscription: portal
+
+Only `recurring` grants get a portal (`paywall_no_recurring_subscription` otherwise). Unlike checkout, the portal IS a redirect flow — the host app navigates to the Stripe-hosted URL:
+
+```ts snippet
+if (grant.offerType === 'recurring') {
+  const { url } = await board.me.access.portal({ returnPath: '/account' });
+  location.href = url; // host-owned redirect to Stripe's portal
+}
+```
+
+## Verify
+
+- [ ] Anonymous fetch of `paywall.offers()` renders tiers with no auth header; a paywall-disabled board renders none (`data: []`).
+- [ ] As an unentitled viewer, `board.jobs.list` carries `gatedCount > 0` and the upsell shows; with an active grant the same call returns `gatedCount` absent/0 and the full list.
+- [ ] Complete a test payment: `retrieveCheckout` flips to `complete` and `grant().hasAccess` turns true within seconds (webhook latency), not instantly.
+- [ ] `portal()` succeeds for a recurring grant and throws for a lifetime one.

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

@@ -0,0 +1,87 @@
+---
+name: cavuno-board-salaries
+description: Build salary pages with the @cavuno/board SDK — salaries.titles/skills/locations (list + retrieve + cross-axis .locations/.location/.titles/.skills), salaries.companies.list. Covers the sourceSlug/canonicalSlug 308 contract, the { locale } overlay, aggregate field shapes (avg/median/percentile bands + jobCount), and why salary math must never be recomputed client-side.
+---
+
+# Salary pages
+
+Pre-aggregated salary read-models, one nested resource per axis (titles, skills, locations) plus a companies hub. Every number is server-computed; the SDK returns render-ready aggregates.
+
+## When to use
+
+- `/salaries` index pages (by title, skill, or location) and their detail pages.
+- Cross-axis pages: "Software Engineer salary in Berlin", "Python salary by location".
+- The `/salaries/companies` hub.
+
+## When not to use
+
+- A single company's salary pages — use `companies.salaries(slug)` / `companies.salaries.category(slug, categorySlug)` (see the companies namespace).
+- Per-job salary display — the job itself carries `salaryMin`/`salaryMax` (see `cavuno-board-jobs`).
+
+## Out of scope — do not invent exports
+
+Only the methods and fields shown here exist. If a field is not in these snippets or the exported types, do not reference it.
+
+## Index pages
+
+Each axis has `list` returning a `ListEnvelope` of index items. Index items carry `avgSalaryMin`/`avgSalaryMax` and `jobCount` (sample size); title/skill items add `p25SalaryMin`/`p75SalaryMax` and `currency`.
+
+```ts snippet
+const titles = await board.salaries.titles.list();
+for (const t of titles.data) {
+  t.slug; t.name;
+  t.avgSalaryMin; t.avgSalaryMax; // render as-is, in t.currency
+  t.jobCount;                     // "based on N jobs"
+}
+const skills = await board.salaries.skills.list();
+const companies = await board.salaries.companies.list(); // ranked by sample size
+```
+
+`salaries.locations.list()` returns a flattened place tree — each `SalaryLocation` has `parentSlug` (`null` at the top level); rebuild the country → region → city browse from those edges.
+
+## Detail pages and the slug contract
+
+`retrieve(slug)` accepts the inbound slug (board-language or English) and returns both `sourceSlug` (immutable English stats key) and `canonicalSlug` (board-language URL). **The API never redirects — your app 308s to `canonicalSlug` when the inbound slug differs.** Pass `{ locale }` for board-language names + canonical slugs (`en` is the identity fast-path).
+
+```ts snippet
+const title = await board.salaries.titles.retrieve('software-engineer', { locale: 'de' });
+title.canonicalSlug;   // 308 target if it differs from the requested slug
+title.overallSalary;   // { avgMin, avgMax, p25Min, p75Max, jobCount } | null
+title.bySeniority;     // rows with avgSalaryMin/avgSalaryMax/jobCount + board comparison
+title.topCompanies;    // rails: { avgSalaryMin, avgSalaryMax, jobCount, ... }
+title.currency;        // the single currency all numbers are quoted in
+
+const skill = await board.salaries.skills.retrieve('python');
+const place = await board.salaries.locations.retrieve('berlin');
+```
+
+`overallSalary` is `null` when the axis has no sample — render an empty state, don't fabricate a band. Skill and location details also carry `medianMin`/`medianMax` inside `overallSalary`; the title detail exposes medians as top-level `boardMedianMin`/`boardMedianMax` instead. `bySeniority` rows on title/skill details include board-wide comparison fields (`boardAvgMin`, `diffPercent`, …) for "X% above board average" copy.
+
+## Cross-axis pages
+
+Titles and skills each expose `.locations(slug)` (index of places with data) and `.location(slug, locationSlug)` (one place); locations expose the suffix reads `.titles(slug)` and `.skills(slug)`.
+
+```ts snippet
+const idx = await board.salaries.titles.locations('software-engineer');
+idx.locations; // SalaryLocation[] — flattened parentSlug tree
+
+const berlin = await board.salaries.titles.location('software-engineer', 'berlin');
+berlin.categoryCanonicalSlug; // 4 slugs: category/location × source/canonical
+berlin.locationCanonicalSlug;
+berlin.overallSalary;         // p25Min/p75Max nullable here
+
+const inBerlin = await board.salaries.locations.titles('berlin');
+const skillsInBerlin = await board.salaries.locations.skills('berlin');
+```
+
+## Never recompute salary math
+
+Render the returned aggregates **as-is**. Do not average mins and maxes, derive medians from percentiles, sum across rails, or convert currency client-side — every response quotes one board `currency` and the weighted math (averages, medians, p25/p75 bands, per-seniority splits) is done server-side against the full sample. Client-side arithmetic will disagree with the hosted board and other consumers.
+
+## Verify
+
+- [ ] Requesting a title/skill/location by a stale slug renders a 308 to `canonicalSlug`.
+- [ ] A non-`en` board passes `{ locale }` and shows board-language names.
+- [ ] An axis with `overallSalary: null` shows an empty state, not `NaN`/`0`.
+- [ ] All displayed figures match the raw response fields (no client math), formatted in the response `currency`.
+- [ ] Sample sizes come from `jobCount`, not `data.length`.

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

@@ -68,7 +68,7 @@ export const board = createBoardClient({
 
 ## Build jobs browsing + detail
 
-The core surface. `jobs.list` / `jobs.search` for listing pages, `jobs.retrieve` for the detail page, `jobs.similar` for the related rail. Honor storefront pagination and the candidate-paywall `gatedCount`. See `cavuno-board-jobs`.
+The core surface. `jobs.list` / `jobs.search` for listing pages, `jobs.retrieve` for the detail page, `jobs.similar` for the related rail. Honor storefront pagination and the candidate-paywall `gatedCount`; use `paginate()` for full-catalog walks (sitemaps, feeds). See `cavuno-board-jobs`.
 
 ## Add board users + saved jobs
 
@@ -78,6 +78,30 @@ Register/login/refresh/logout, then `me.retrieve` and `me.savedJobs.*`. There is
 
 Every method throws `BoardApiError` on a non-2xx; branch with the typed guards. Password-protected boards need a `password.verify()` grant. See `cavuno-board-errors`.
 
+## Style, format, and filter with the helper subpaths
+
+Three subpath modules carry the display layer — use them instead of
+hand-rolling (each has a skill):
+
+- Salary/date/label formatting in the board language → `cavuno-board-format`
+- Listing-filter vocabulary + URL param parsing → `cavuno-board-filters`
+- Board theme → shadcn CSS variables + fonts → `cavuno-board-theme`
+
+## Build the remaining surfaces per feature flag
+
+One focused skill per surface — delegate by name, and build a surface only
+when its `features` flag (from `board.context()`) is enabled:
+
+- Companies directory, markets, per-company jobs → `cavuno-board-companies`
+- Blog (posts, tags, authors, search) → `cavuno-board-blog`
+- Programmatic salary pages → `cavuno-board-salaries`
+- Job alerts (anonymous double-opt-in + account CRUD) → `cavuno-board-job-alerts`
+- Candidate account self-service (profile, resume, avatar, prefs) → `cavuno-board-account`
+- Apply flow + my applications + saved jobs → `cavuno-board-applications`
+- Candidate↔employer messaging (polled REST) → `cavuno-board-messaging`
+- Candidate job-access paywall (offers, checkout, grant) → `cavuno-board-paywall`
+- Public job-posting funnel (plans, submit, billing) → `cavuno-board-job-posting`
+
 ## App-owned concerns (out of scope)
 
 The SDK serves data only. Your app owns: page layout and chrome copy, marketing/legal prose, and the authoring of SEO artifacts (sitemap, RSS, OG images) — built from API data, not served as documents. The Board API never returns layouts or page-builder JSON.
@@ -89,7 +113,7 @@ The SDK serves data only. Your app owns: page layout and chrome copy, marketing/
 - A detail page renders from `board.jobs.retrieve(slug)`.
 - An invalid slug surfaces a handled `isNotFound(err)` path, not a crash.
 
-When the `cavuno-board-smoke-test` skill is present, run it against your `pk_…` to verify end to end.
+Then run the `cavuno-board-smoke-test` skill against your `pk_…` — type checks are not enough for board wiring.
 
 ## Stop conditions
 

package/skills/cavuno-board-smoke-test/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: cavuno-board-smoke-test
+description: Runtime verification for a wired Cavuno board frontend — literal curl probes against the Board API plus per-surface behavioral checks and a mandatory production-build pass. Run after cavuno-board-setup finishes, after upgrading @cavuno/board, or whenever board wiring is suspect. Type checks are not enough for board wiring.
+---
+
+# Smoke-testing a Cavuno board frontend
+
+Type checks prove the code compiles against the SDK; they do not prove the
+app reaches the right board with the right credentials, or that gating,
+auth, and SEO surfaces behave. Verify at runtime, in this order.
+
+## When to use
+
+- Right after `cavuno-board-setup` completes.
+- After upgrading `@cavuno/board` or rotating the `pk_…` key.
+- When any surface renders empty and you don't know which layer is wrong.
+
+## 1 — Probe the API directly (before blaming app code)
+
+Use the real env values the app reads (`PUBLIC_CAVUNO_API_URL`,
+`PUBLIC_CAVUNO_BOARD`). Expected outputs are exact.
+
+```bash
+# Board context: MUST return JSON with "object": "public_board" and your
+# board's name — not an HTML error page, not {"error":{"code":"boards_not_found"}}.
+curl -s "$PUBLIC_CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD" | head -c 300
+
+# Jobs list: MUST return {"object":"list", ... "data":[...]}. An empty data
+# array on a board you know has jobs means the wrong board identifier.
+curl -s "$PUBLIC_CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD/jobs?limit=2" | head -c 300
+
+# Error envelope: a bogus job slug MUST return the v1 error shape with
+# "code":"jobs_not_found" — anything else means a proxy is rewriting responses.
+curl -s "$PUBLIC_CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD/jobs/definitely-not-a-job"
+```
+
+On a password-protected board, every content read above returns 401 with
+`"code":"board_password_required"` — that is correct behavior, not a
+failure; verify the grant flow in step 3 instead.
+
+## 2 — Verify the app serves board data
+
+Start the app (dev is fine for this step) and probe its own routes:
+
+- The home/shell renders the board name and logo from `board.context()`.
+- A listing page shows real job cards; a card links to
+  `/companies/:companySlug/jobs/:jobSlug` (never `/jobs/:slug`).
+- A fabricated job URL renders the app's not-found state — a handled
+  `isNotFound` branch, not a crash or blank page.
+
+## 3 — Per-surface behavioral checks (only for surfaces you built)
+
+- **Auth**: register → the verification gate appears; login → an authed
+  read (`me.retrieve`) succeeds; after `auth.logout()` the same read fails
+  with a 401 that the app handles by signing out, not looping.
+- **Password gate**: with protection enabled, an anonymous content read
+  redirects to the password page; `password.verify()` + retry renders
+  content; a wrong password shows `board_password_invalid` messaging.
+- **Saved jobs / apply**: save → reload → still saved (server state, not
+  local); a second apply to the same job returns the same application
+  (idempotent), not a duplicate.
+- **Paywall** (gated boards): anonymous list shows the `gatedCount` upsell;
+  an entitled login makes the same URL return the ungated view.
+- **Alerts**: subscribe → `status: "created"`; repeat → `"duplicate"`.
+
+## 4 — Production build (mandatory)
+
+Dev servers mask wiring bugs (looser env loading, dev-only middleware, no
+tree-shake). Run the app's real build, boot the production output, and
+repeat step 2 against it. `import 'server-only'`-style boundaries and env
+prefixes (`VITE_`, `NEXT_PUBLIC_`) frequently pass dev and fail prod.
+
+## Out of scope — do not invent checks
+
+No load testing, no Lighthouse/SEO scoring, no visual regression — those
+are app-owned. This skill verifies board wiring only.
+
+## Stop conditions
+
+Stop and report to the human when: step 1 fails (the problem is
+credentials/network, not code — do not "fix" app code to compensate); the
+API returns codes the app has no branch for; or a check needs a credential
+you don't have (board password, test account). Never commit real
+credentials while fixing findings.

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

@@ -0,0 +1,69 @@
+---
+name: cavuno-board-theme
+description: Board branding with @cavuno/board/theme — map the board's stored theme (16 semantic colors × light/dark + typography from board.context().theme) onto shadcn CSS variables, resolve the color-scheme mode, and build the Google Fonts request. Use when wiring the app shell, dark mode, or brand styling for a tenant frontend.
+---
+
+# Theme: board branding → shadcn tokens
+
+`@cavuno/board/theme` maps the board's stored theme onto the canonical
+shadcn token vocabulary as CSS-variable overrides. One contract, two
+consumers: the dashboard edits the board theme; agents restyle through the
+standard shadcn theme file — both end up in the same tokens.
+
+## When to use
+
+- The app shell/root layout of any tenant frontend, once.
+- Wiring dark mode or brand fonts.
+
+## When not to use
+
+- Component-level styling — write normal Tailwind/shadcn classes; they pick
+  the overridden tokens up automatically.
+
+## Wire it once at the shell
+
+```ts snippet
+import { boardThemeToCss, themeMode, googleFontsUrl } from '@cavuno/board/theme';
+
+const context = await board.context();
+const css = boardThemeToCss(context.theme);   // ':root {…}' + '.dark {…}'
+const mode = themeMode(context.theme);        // 'light' | 'dark' | 'system'
+const fontsHref = googleFontsUrl(context.theme); // one <link>, or null
+```
+
+Inject `css` in a `<style>` AFTER the static theme stylesheet so the
+overrides win; render nothing when it's empty (a null theme means the app's
+default theme applies untouched). Apply `mode` by toggling the `.dark`
+class (`system` = follow `prefers-color-scheme`).
+
+## The mapping is the contract
+
+All 16 board color keys are consumed — a coverage golden in-monorepo
+asserts neither the hosted board nor this module drops one. Standard
+shadcn tokens carry the core (background/foreground, card, popover,
+primary, secondary, muted, accent, destructive, border, input, ring);
+the four keys shadcn has no standard token for ship as
+`--contrast-background`, `--contrast-foreground`, `--foreground-subtle`,
+`--foreground-disabled`, plus `--foreground-error`.
+
+## Anti-patterns
+
+```ts no-check
+// NEVER hardcode brand colors in components — they bypass the board theme:
+<button style={{ background: '#7c3aed' }} />
+// NEVER re-map theme keys ad hoc per page; the shell mapping is the single source.
+// NEVER fetch fonts per-family — googleFontsUrl builds ONE deduped request.
+```
+
+## Out of scope — do not invent exports
+
+No color math (hover/pressed derivation, contrast checking — the hosted
+dashboard owns palette design), no per-component theme props, no CSS-in-JS
+runtime. The module emits strings; the app owns injection.
+
+## Verify
+
+- [ ] A board with a custom theme renders its brand color on primary
+      buttons and focus rings; a board without one renders the app default.
+- [ ] Dark palette applies under `.dark` and `mode` drives the class.
+- [ ] The Google Fonts request appears once, covering sans + heading.