@cavuno/board 1.25.0 → 1.27.0

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-seo/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: cavuno-board-seo
+description: Structured data + head builders for board frontends with @cavuno/board/seo — Google for Jobs JobPosting JSON-LD, breadcrumbs, blog Article/ProfilePage, salary-page Occupation/FAQ structured data, and listing <head> descriptors. Use when building a job-detail, listing, blog, or salary page and it needs JSON-LD or SEO meta tags, or whenever "structured data", "rich results", or "Google for Jobs" comes up.
+---
+
+# SEO: structured data + head builders
+
+`@cavuno/board/seo` emits the exact structured data the hosted board emits —
+golden-tested against the hosted builders, so a tenant frontend gets Google
+for Jobs, breadcrumb, blog, and salary rich results without reinventing (or
+drifting from) the platform's rules. Render every builder's output into a
+`<script type="application/ld+json">` tag; builders return `null` when there
+is nothing worth emitting — skip the tag then.
+
+## When to use
+
+- A job detail page needs Google for Jobs `JobPosting` JSON-LD.
+- Any page needs a `BreadcrumbList`.
+- Blog post / author pages need `Article` / `ProfilePage` JSON-LD.
+- Salary pages need `Occupation`/`MonetaryAmountDistribution`/`ItemList`/
+  `FAQPage` structured data or the templated salary FAQ.
+- A jobs-listing page needs its `<head>` (title with count, canonical, OG).
+
+## When not to use
+
+- Display text on the page itself — `cavuno-board-format`.
+- Sitemaps and robots.txt — the sitemap module/skill.
+- OG image generation and route maps — app-owned (see out of scope).
+
+## Job-posting JSON-LD (the detail page)
+
+`PublicJob` carries every field this needs — including the derived remote
+permit codes. Worldwide-remote jobs automatically enumerate all 249
+countries (Google requires a location signal next to TELECOMMUTE).
+
+```ts snippet
+import { createJobPostingJsonLd } from '@cavuno/board/seo';
+
+const { name, logoUrl } = await board.context();
+const job = await board.jobs.retrieve('senior-chef');
+
+const jsonLd = createJobPostingJsonLd({
+  job,
+  board: { name, logoUrl },
+  shareUrl: `https://jobs.example.com/companies/${job.company?.slug}/jobs/${job.slug}`,
+});
+// null when nothing renderable remains — omit the <script> tag then.
+```
+
+## Breadcrumbs
+
+Hosted semantics: labels are trimmed, blank crumbs dropped, fewer than two
+crumbs → `null`, and the current page (no `href`) omits `item`. Pass
+absolute hrefs, or give `origin` and use paths:
+
+```ts snippet
+import { createBreadcrumbJsonLd } from '@cavuno/board/seo';
+
+const trail = createBreadcrumbJsonLd(
+  [
+    { label: 'Home', href: '/' },
+    { label: 'Jobs', href: '/jobs' },
+    { label: job.title }, // current page — no href
+  ],
+  { origin: 'https://jobs.example.com' },
+);
+```
+
+## Blog Article + author ProfilePage
+
+```ts snippet
+import {
+  createBlogArticleJsonLd,
+  createAuthorProfileJsonLd,
+} from '@cavuno/board/seo';
+
+const post = await board.blog.posts.retrieve('hello-world');
+const article = createBlogArticleJsonLd({
+  post,
+  boardName: name,
+  permalink: `https://jobs.example.com/blog/${post.slug}`,
+  ogImageUrl: `https://jobs.example.com/blog/${post.slug}/og`, // fallback when no cover
+});
+
+const author = await board.blog.authors.retrieve('jane');
+const { data: authorPosts } = await board.blog.posts.list({ authorSlug: 'jane' });
+const profile = createAuthorProfileJsonLd({
+  author,
+  canonical: `https://jobs.example.com/blog/author/${author.slug}`,
+  description: author.bio ?? `Posts by ${author.name}`,
+  origin: 'https://jobs.example.com',
+  posts: authorPosts, // newest first; the builder keeps 5 as hasPart
+  totalPosts: authorPosts.length,
+});
+```
+
+## Salary-page structured data + FAQ
+
+The board language is a REQUIRED leading parameter wherever display strings
+are produced (no `en` default). The money formatters are USD-hardcoded —
+the hosted salary-page quirk, kept deliberately; the locale drives number
+formatting only. The FAQ ships TEMPLATED English sentences (board-custom
+FAQ copy is a tracked API gap and will supersede it).
+
+```ts snippet
+import {
+  titleSalaryJsonLd,
+  buildSalaryFaq,
+  faqJsonLd,
+  itemListJsonLd,
+  formatRange,
+  sortBySeniority,
+} from '@cavuno/board/seo';
+
+const { language } = await board.context();
+const detail = await board.salaries.titles.retrieve('software-engineer');
+
+const occupation = titleSalaryJsonLd(language, detail);
+const faq = faqJsonLd(
+  buildSalaryFaq(language, detail.categoryName, detail.overallSalary),
+);
+// Index pages: itemListJsonLd(items); on-page figures: formatRange(language, min, max)
+// and sortBySeniority(detail.bySeniority) for the ladder table.
+```
+
+Also available: `skillSalaryJsonLd(detail)`, `locationSalaryJsonLd(detail)`
+(city-level pages only), `crossAxisSalaryJsonLd(locale, args)`,
+`companySalaryJsonLd(locale, detail)`,
+`companyCategorySalaryJsonLd(locale, detail)`, `formatUsd(locale, value)`,
+`formatSeniority(locale, key)`, `SENIORITY_ORDER`.
+
+## Listing pages: head + structural JSON-LD
+
+Locale-neutral pass-through — you supply the heading copy:
+
+```ts snippet
+import { listingHead, listingJsonLd } from '@cavuno/board/seo';
+
+const head = listingHead({
+  boardName: name,
+  origin: 'https://jobs.example.com',
+  path: '/jobs/robotics',
+  heading: 'Robotics jobs',
+  count: 42, // → "42 Robotics jobs | Acme Jobs"
+});
+// head.meta → title/description/OG descriptors; head.links → canonical.
+
+const objects = listingJsonLd({
+  origin: 'https://jobs.example.com',
+  breadcrumbs: [{ name: 'Home', path: '/' }, { name: 'Jobs' }],
+  jobs: cards.map((c) => ({ slug: c.slug, company: c.company })),
+});
+```
+
+## Anti-patterns
+
+```ts no-check
+// NEVER hand-roll JobPosting JSON-LD — the pruning, salary mirroring, and
+// worldwide country enumeration are Google-spec rules the SDK encodes:
+const ld = { '@type': 'JobPosting', salary: job.salaryMin }; // wrong shape
+// NEVER default the locale on salary builders:
+titleSalaryJsonLd('en', detail); // hardcoded 'en' on a de board
+// NEVER emit a JSON-LD script for a null builder result.
+```
+
+## Out of scope — do not invent exports
+
+OG **image generation** (the `/og` card renderer), the legal/route **map**,
+and the meta title/description **copy** (board SEO config + localized copy
+is not replicated — `listingHead` takes your strings) are app-owned. No
+sitemap builders here — that is `@cavuno/board/sitemap`'s job.
+
+## Verify
+
+- [ ] The job detail page's JSON-LD validates in Google's Rich Results test
+      as a JobPosting, and a worldwide-remote job lists 249 countries.
+- [ ] Pages with a null builder result render NO empty ld+json script.
+- [ ] A de board passes `language` from `board.context()` — the salary
+      FAQ figures render de-formatted, and no call site hardcodes 'en'.
+- [ ] Breadcrumb JSON-LD only appears on pages with 2+ crumbs.

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-sitemap/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: cavuno-board-sitemap
+description: Build the board's sitemap with @cavuno/board/sitemap — the hosted 8-bucket model (marketing, jobs taxonomies, job details, companies, salaries, blog), 45k chunking, XML rendering, and the buildBucketUrls walker that enumerates a board's content through the BoardSdk with the hosted SEO rules built in (feature gating, ≥5-job thin-content floor, pagination backstops). Use when adding /sitemap.xml and /sitemap/:file routes to a custom board frontend.
+---
+
+# Sitemap: the 8-bucket model
+
+`@cavuno/board/sitemap` ships the hosted board's sitemap architecture: a
+sitemap INDEX at `/sitemap.xml` pointing at one file per content bucket,
+each an ordinary `<urlset>`. The XML byte layout and the bucket rules are
+golden-tested against the hosted implementation, so a custom frontend's
+sitemap corpus lines up bucket-for-bucket with what cavuno.com would emit.
+
+Two tiers, use both:
+
+- **XML primitives** (pure, no I/O): `SITEMAP_BUCKETS`,
+  `SITEMAP_CHUNK_SIZE` (45,000), `chunk`, `bucketFilename` /
+  `parseBucketFilename`, `renderUrlset`, `renderSitemapIndex`.
+- **The walker** (opinionated, injected I/O): `listedBuckets(board)` and
+  `buildBucketUrls(board, origin, bucket)` take your `BoardSdk` instance
+  and return plain URL strings with the hosted rules applied — you never
+  re-derive the SEO policy.
+
+## When to use
+
+- Adding `/sitemap.xml` + `/sitemap/:file` routes to a board frontend.
+- Deciding which listing pages deserve indexing (the walker already does).
+
+## When not to use
+
+- Structured data / meta tags — `cavuno-board-seo`.
+- Feeds (RSS/Atom) — app-owned.
+
+## The two routes
+
+The index lists one entry per bucket; each bucket route parses its filename
+back to a bucket + chunk and renders a urlset. Empty buckets render a valid
+empty urlset — only `blog` is dropped from the index when the feature is
+off (`listedBuckets` handles that).
+
+```ts snippet
+import {
+  SITEMAP_CHUNK_SIZE,
+  buildBucketUrls,
+  bucketFilename,
+  chunk,
+  listedBuckets,
+  parseBucketFilename,
+  renderSitemapIndex,
+  renderUrlset,
+} from '@cavuno/board/sitemap';
+
+// GET /sitemap.xml — one <sitemap> per listed bucket (plus -2, -3… chunks).
+const origin = 'https://jobs.example.com';
+const buckets = await listedBuckets(board);
+const locs: string[] = [];
+for (const bucket of buckets) {
+  const urls = await buildBucketUrls(board, origin, bucket);
+  const chunks = chunk(urls, SITEMAP_CHUNK_SIZE);
+  for (let i = 0; i < Math.max(chunks.length, 1); i += 1) {
+    locs.push(`${origin}/sitemap/${bucketFilename(bucket, i)}`);
+  }
+}
+return xmlResponse(renderSitemapIndex(locs));
+```
+
+```ts snippet
+// GET /sitemap/:file — parse, enumerate, slice, render. Unknown file → 404.
+const parsed = parseBucketFilename(params.file);
+if (!parsed) return notFound();
+const urls = await buildBucketUrls(board, origin, parsed.bucket);
+const page = chunk(urls, SITEMAP_CHUNK_SIZE)[parsed.chunkIndex] ?? [];
+return xmlResponse(renderUrlset(page));
+```
+
+`renderUrlset` also accepts `{ url, lastModified?, images? }` entries when
+you have per-URL dates (a `Date` serializes to ISO 8601). `changefreq` and
+`priority` are deliberately unsupported — the hosted board never emits them.
+
+## robots.txt
+
+Point crawlers at the index — one line, at the site root:
+
+```txt
+Sitemap: https://jobs.example.com/sitemap.xml
+```
+
+## The rules the walker enforces (don't re-implement)
+
+- **Thin-content floor**: a category/skill/location listing page is emitted
+  only with ≥5 distinct jobs (`MIN_JOBS_PER_INDEXED_PAGE`) — below that,
+  the page is thin content that wastes crawl budget.
+- **Feature gating**: `/impressum`, `/talent`, `/employers` appear in the
+  marketing bucket only when `context().features` enables them; the blog
+  bucket exists only when `features.blog` is on.
+- **Board language**: salary-index reads pass `context().language`, so a
+  non-English board emits board-language canonical salary slugs (jobs,
+  companies, and blog slugs arrive canonical on the wire already). No
+  locale parameter to thread.
+- **Pagination backstops**: offset enumeration runs in parallel when the
+  envelope carries `count` (capped at the API's 10,000-offset window);
+  cursor walks cap at 200 pages. Both warn on truncation instead of
+  hanging a build.
+
+## Stable order caveat (cursor walks)
+
+Cursor and offset enumeration order can shift between requests on a large,
+churning board — two chunk requests may see slightly different orderings.
+That is harmless for a sitemap (URLs dedupe and the ≥5 counts are a
+heuristic), but do NOT reuse the walker as a general "export all jobs in
+order" tool; for stable ordering, pass an explicit sort/query to
+`board.jobs.list` yourself.
+
+## Named exclusions (v1 API gap — not bugs)
+
+Two URL families the HOSTED sitemap emits are deliberately absent, because
+v1 exposes them only per-slug and a bulk-pairs endpoint doesn't exist yet
+(per-slug N+1 is ~1k+ calls per build):
+
+- Cross-axis salary pages (title×location, skill×location,
+  company×category, and the per-entity `/locations` · `/titles` ·
+  `/skills` salary index pages).
+- Jobs place×category / place×skill combination listings.
+
+Both stay reachable through internal links. When the bulk endpoint lands,
+the walker picks them up additively — don't hand-enumerate them.
+
+## Anti-patterns
+
+```ts snippet
+// NEVER emit every taxonomy page unconditionally — the ≥5-job floor exists
+// to keep thin pages out of the index:
+for (const c of allCategories) urls.push(`${origin}/jobs/${c.slug}`); // wrong
+// NEVER hand-build the XML with a template string per route — use
+// renderUrlset/renderSitemapIndex (escaping + byte-parity with hosted).
+// NEVER fetch every salary detail page to discover cross-axis pairs (N+1).
+```
+
+## Verify
+
+- [ ] `/sitemap.xml` lists one file per bucket (no `blog` entry when the
+      feature is off) and every listed file returns valid XML.
+- [ ] A category with 4 jobs is absent from `jobs-categories.xml`; one with
+      5 is present.
+- [ ] `jobs-details-2.xml` style chunk names round-trip through
+      `parseBucketFilename` and unknown filenames 404.
+- [ ] robots.txt points at `/sitemap.xml`.

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.