@cavuno/board 2.0.5 → 3.0.0

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

@@ -1,108 +1,102 @@
 ---
 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).
+description: Grant-is-truth candidate paywall with @cavuno/board. Use for offers, gated job counts, embedded checkout handoff, access confirmation, or subscription portal links.
 ---
 
-# Candidate paywall: offers, checkout, grant
+# Grant-is-truth candidate paywall
 
-The candidate-facing money flow: anonymous pricing, gated job lists, and an embedded Stripe checkout that ends in an access grant.
+The candidate money flow is anonymous offers → authenticated embedded checkout → webhook-backed grant. The grant, rather than checkout completion, owns access.
 
-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.
+Board-password access is a separate `X-Board-Access` mechanism. Employer posting payments use `cavuno-board-post-a-job`.
 
-## When to use
+## Render offers and gating
 
-- 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).
+`board.paywall.offers()` is anonymous and returns an empty list when disabled. Internal Stripe price ids stay server-side.
 
 ```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.offerKey;
   offer.label;
   offer.billingLabel;
   offer.amountCents;
   offer.currency;
-  offer.offerType;    // 'recurring' | 'lifetime'
-  offer.isDefault;    // pre-select this tier
+  offer.offerType;
+  offer.isDefault;
 }
 ```
 
-## The gated browse: gatedCount
+`offerType` is `'recurring' | 'lifetime'`; post the selected `offerKey` to checkout.
 
-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:
+Gated catalog reads expose withheld inventory as `gatedCount`. The same jobs endpoint returns the entitled view when called with the candidate bearer token.
 
 ```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
+if ((page.gatedCount ?? 0) > 0) {
+  renderUpsell(page.gatedCount);
 }
 ```
 
-The same call with an entitled board-user bearer token returns the ungated view — one URL for both.
-
-## Checkout: mint the mount kit
+## Mint and mount checkout
 
-`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}`.
+`board.me.access.checkout` requires a signed-in candidate profile and returns a mount kit. `returnPath` is relative; the server makes the canonical absolute return URL and appends Stripe's session placeholder.
 
 ```ts snippet
-import { loadStripe } from '@stripe/stripe-js'; // host-app dependency
+import { loadStripe } from '@stripe/stripe-js';
 
 const kit = await board.me.access.checkout({
-  offerKey: 'monthly',           // the chosen PaywallOffer.offerKey
-  returnPath: '/account/access', // relative path Stripe returns to
+  offerKey: 'monthly',
+  returnPath: '/account/access',
   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.
+The kit contains `sessionId`, `clientSecret`, `stripeAccountId`, `publishableKey`, and `offerType`. The host owns Stripe.js, embedded-checkout mounting, and redirects. A repeated checkout POST safely creates another session that can expire unpaid.
 
-## Completion: poll the session, confirm the grant
+## Confirm access from 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):
+`retrieveCheckout` reports `open`, `complete`, or `expired`. Open sessions are remountable with their `clientSecret`; expired sessions require a new checkout. After completion, poll `grant()` within a bounded window because webhook delivery is asynchronous.
 
 ```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;
+const checkout = await board.me.access.retrieveCheckout(kit.sessionId);
+
+if (checkout.status === 'complete') {
+  let grant = await board.me.access.grant();
+  for (let poll = 0; !grant.hasAccess && poll < 10; poll++) {
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    grant = await board.me.access.grant();
+  }
+  if (grant.hasAccess) renderUnlockedJobs();
+  else renderPendingAccess();
+}
 ```
 
-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`.
+`grant()` always resolves: no access is `{ hasAccess: false }`. Its `status`, `offerType`, `currentPeriodEnd`, and `cancelAtPeriodEnd` drive the account UI. Gate failures use `paywall_disabled`, `paywall_no_candidate_profile`, `paywall_offer_not_found`, `paywall_already_active`, and `paywall_invalid_checkout_session`; handle them with `cavuno-board-errors`.
 
-## Manage subscription: portal
+## Open the 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:
+Only recurring grants have a portal. The host follows the returned Stripe-hosted URL.
 
 ```ts snippet
+const grant = await board.me.access.grant();
 if (grant.offerType === 'recurring') {
-  const { url } = await board.me.access.portal({ returnPath: '/account' });
-  location.href = url; // host-owned redirect to Stripe's portal
+  const { url } = await board.me.access.portal({
+    returnPath: '/account',
+  });
+  location.href = url;
 }
 ```
 
-## Verify
+A lifetime grant produces `paywall_no_recurring_subscription` for `portal`.
+
+## Completion gate
 
-- [ ] 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.
+- Anonymous offers render without authorization; disabled paywall renders no tiers.
+- Unentitled jobs show `gatedCount`; the active-grant request exposes the full list.
+- Test checkout reaches `complete`, then bounded grant polling reaches `hasAccess: true` after webhook delivery.
+- UI access decisions read `grant().hasAccess`.
+- Recurring grants open the portal; lifetime grants show a deliberate non-portal state.

package/skills/cavuno-board-post-a-job/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: cavuno-board-post-a-job
+description: Post a job publicly with @cavuno/board. Use for plan selection, logos, checkout handoff, or verified existing credit.
+---
+
+# Status-first job posting
+
+The public posting funnel is anonymous and rate-limited. Its invariant is status-first handling: `board.jobPosting.create` returns one of four success states, and the host follows that state. Rejected submissions throw `BoardApiError` instead.
+
+Employer dashboard job management belongs to `board.me.companies.jobs.*`. Candidate access payments belong to `cavuno-board-paywall`.
+
+## Select a plan
+
+```ts snippet
+const { data: plans } = await board.jobPosting.plans();
+for (const plan of plans) {
+  plan.id;
+  plan.prices;
+  plan.invoiceOnly;
+  plan.isRecommended;
+  plan.features;
+}
+```
+
+Pass the chosen `plan.id` as `submission.selectedPlan`. Invoice-only plans collect `invoiceBilling` rather than immediate payment.
+
+## Resolve a logo
+
+Both logo paths return a stored `publicUrl` for `create`. The SDK owns multipart encoding.
+
+```ts snippet
+const uploaded = await board.jobPosting.uploadLogo(file);
+const fetched = await board.jobPosting.fetchLogoByDomain('acme.com');
+```
+
+Uploads accept JPEG, PNG, WebP, or GIF up to 2 MB. A missing domain logo throws code `job_posting_logo_not_found`; continue without a logo.
+
+## Submit and exhaust the result
+
+```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: uploaded.publicUrl,
+});
+
+switch (result.status) {
+  case 'checkout':
+    location.href = result.checkoutUrl;
+    break;
+  case 'published':
+    linkToJob(result.jobSlug);
+    break;
+  case 'pending_approval':
+    showPending(result.jobId);
+    break;
+  case 'invoice_sent':
+    showInvoiceSent(result.jobId);
+    break;
+}
+```
+
+The mapping is:
+
+- paid Stripe plan → `checkout`;
+- free or credited posting → `published`, or `pending_approval` on moderated boards;
+- invoice plan → `invoice_sent`.
+
+The checkout value is a URL for a host-owned full-page redirect. Payment publication happens by webhook; the SDK exposes no Stripe integration or publish-confirm method.
+
+## Verified existing credit
+
+Email verification protects billing ownership. Send verification first, then exchange the token for options; a selected option becomes `selectedBilling`.
+
+```ts snippet
+await board.jobPosting.sendBillingVerification({ email });
+
+const { options } = await board.jobPosting.getBillingOptions({
+  verificationToken,
+});
+
+const option = options[0];
+if (option) {
+  option.jobsRemaining;
+  option.featuredRemaining;
+  option.renewsAt;
+
+  await board.jobPosting.create({
+    submission,
+    selectedBilling: {
+      type: option.type,
+      id: option.id,
+      planId: option.planId,
+    },
+  });
+}
+```
+
+Bare-email billing lookup is intentionally absent because it would expose whether an address holds credit.
+
+## Completion gate
+
+- Every `create` call handles all four statuses.
+- Paid checkout redirects through `checkoutUrl`; the job appears only after webhook completion.
+- Free unmoderated submission returns a resolving `jobSlug`.
+- Missing domain logos leave submission usable without `logoUrl`.
+- Existing credit is selectable only after token verification.

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

@@ -1,87 +1,110 @@
 ---
 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.
+description: Salary read models with @cavuno/board. Use for title, skill, or location salary indexes and detail, cross-axis pages, or the salary companies hub.
 ---
 
-# Salary pages
+# Salaries
 
-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.
+The salary namespaces return pre-aggregated read models. Render their figures
+directly in the response `currency`; server-side weighted averages, medians,
+percentile bands, and seniority splits are the source of truth.
 
-## When to use
+Single-company salary pages use `companies.salaries` and
+`companies.salaries.category`. A job's own range comes from its
+`salaryMin`/`salaryMax` fields.
 
-- `/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.
+## Build axis indexes
 
-## 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`.
+Titles, skills, and locations each expose `.list()`. Index items contain
+`avgSalaryMin`, `avgSalaryMax`, and sample-size `jobCount`; title and skill
+items also contain `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"
+for (const title of titles.data) {
+  title.slug;
+  title.name;
+  title.avgSalaryMin;
+  title.avgSalaryMax;
+  title.jobCount;
 }
 const skills = await board.salaries.skills.list();
-const companies = await board.salaries.companies.list(); // ranked by sample size
+const companies = await board.salaries.companies.list();
 ```
 
-`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.
+`salaries.companies.list()` ranks companies by sample size.
+`salaries.locations.list()` returns a flattened place tree: rebuild country,
+region, and city nesting from each `SalaryLocation.parentSlug`; top-level rows
+have `parentSlug: null`.
 
-## Detail pages and the slug contract
+## Retrieve detail and canonicalize slugs
 
-`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).
+Every axis `retrieve(slug)` accepts an inbound English or board-language slug.
+The result includes immutable English `sourceSlug` and board-language
+`canonicalSlug`. Pass `{ locale }` for board-language names and canonical
+slugs, then issue a 308 when the inbound slug differs from `canonicalSlug`.
+The API itself returns data rather than a redirect.
 
 ```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 title = await board.salaries.titles.retrieve('software-engineer', {
+  locale: 'de',
+});
+title.canonicalSlug;
+title.overallSalary;
+title.bySeniority;
+title.topCompanies;
+title.currency;
 
 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.
+`overallSalary` is nullable. Render an empty state when it is `null`.
+Title detail contains `{ avgMin, avgMax, p25Min, p75Max, jobCount }` there and
+exposes medians as top-level `boardMedianMin` and `boardMedianMax`. Skill and
+location details instead include `medianMin` and `medianMax` inside
+`overallSalary`. Title and skill `bySeniority` rows include board-comparison
+fields such as `boardAvgMin` and `diffPercent`.
 
-## Cross-axis pages
+## Build 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)`.
+Titles and skills expose `.locations(slug)` and
+`.location(slug, locationSlug)`. Locations expose `.titles(slug)` and
+`.skills(slug)`.
 
 ```ts snippet
-const idx = await board.salaries.titles.locations('software-engineer');
-idx.locations; // SalaryLocation[] — flattened parentSlug tree
+const index = await board.salaries.titles.locations('software-engineer');
+index.locations;
 
-const berlin = await board.salaries.titles.location('software-engineer', 'berlin');
-berlin.categoryCanonicalSlug; // 4 slugs: category/location × source/canonical
+const berlin = await board.salaries.titles.location(
+  'software-engineer',
+  'berlin');
+berlin.categoryCanonicalSlug;
 berlin.locationCanonicalSlug;
-berlin.overallSalary;         // p25Min/p75Max nullable here
+berlin.overallSalary;
 
-const inBerlin = await board.salaries.locations.titles('berlin');
+const titlesInBerlin = await board.salaries.locations.titles('berlin');
 const skillsInBerlin = await board.salaries.locations.skills('berlin');
 ```
 
-## Never recompute salary math
+A cross-axis detail carries four slug fields: source and canonical slugs for
+both category and location. Canonicalize both URL segments. Its
+`overallSalary.p25Min` and `p75Max` may be null.
+
+## Preserve aggregate semantics
+
+Display response fields as-is. Client arithmetic such as averaging min/max,
+deriving medians from percentiles, summing rails, or converting currencies
+changes the weighted meaning and diverges from the hosted board. Use
+`jobCount`, rather than `data.length`, for sample-size copy.
 
-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 is done server-side against the full sample. Client-side arithmetic will disagree with the hosted board and other consumers.
+## Completion gate
 
-## Verify
+Finish only after every applicable check passes:
 
-- [ ] 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`.
+- Stale axis and cross-axis slugs produce 308s to every returned canonical
+  segment.
+- A non-English board passes `{ locale }` and renders board-language names.
+- `overallSalary: null` renders an empty state rather than `0` or `NaN`.
+- Every salary, comparison, and sample size maps directly to a response field
+  and uses the response currency.

package/skills/cavuno-board-search-suggestions/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: cavuno-board-search-suggestions
+description: Build server-ranked search suggestions with @cavuno/board. Use for company-and-term typeahead, autocomplete dropdowns, or suggestion-controller wiring.
+---
+
+# Server-ranked search suggestions
+
+`board.search.suggest` returns one interleaved list of companies and taxonomy terms. Server rank is the contract: render its order unchanged. For UI, the headless controller adds debounce, abort, and stale-result dropping.
+
+Location autocomplete uses `board.taxonomy.places.list({ q })`; filter option lists use `board.taxonomy.categories.list`, `board.taxonomy.skills.list`, or `board.taxonomy.suggestions.list`; job results use `board.jobs.list` or `board.jobs.search`.
+
+## Read suggestions
+
+```ts snippet
+const { items, query } = await board.search.suggest({
+  q: 'acme',
+  limit: 10,
+});
+
+for (const item of items) {
+  if (item.type === 'company') {
+    item.slug;
+    item.name;
+    item.jobCount;
+  } else {
+    item.termType;
+    item.displayName;
+    item.canonicalSlug;
+    item.sourceSlug;
+  }
+}
+```
+
+Queries shorter than two characters return no items. `limit` accepts 1–25 and defaults to 25.
+
+Term suggestions have `termType: 'category' | 'skill'`; use `canonicalSlug` for links and `sourceSlug` for job filters.
+
+## Drive UI with the controller
+
+```ts snippet
+import { createSuggestController } from '@cavuno/board/suggest';
+
+const suggest = createSuggestController(board, { limit: 10 });
+const unsubscribe = suggest.subscribe(() => {
+  const state = suggest.getState();
+  renderSuggestions(state.items, state.status, state.query);
+});
+
+suggest.setQuery(inputValue);
+suggest.setExcludedCompanySlugs(appliedCompanySlugs);
+
+unsubscribe();
+suggest.dispose();
+```
+
+Defaults are a 250 ms debounce and two-character minimum. Previous items remain while status is `loading`. The store is compatible with `useSyncExternalStore`. `setExcludedCompanySlugs` is the view-level exception: it removes company items synchronously without requesting again. Preserve the remaining items and order.
+
+The SDK provides the data and controller, while the host owns dropdown markup, keyboard navigation, and framework bindings.
+
+## Apply a company suggestion
+
+Company slugs are public URL identity. Write the slug into listing filters and pass it as `companySlug`.
+
+```ts snippet
+import { parseListingFilters } from '@cavuno/board/filters';
+
+const filters = parseListingFilters(rawSearchParams);
+const page = await board.jobs.list({
+  limit: 20,
+  companySlug: filters.company,
+});
+```
+
+Unknown slugs are dropped server-side. If none resolve, the listing has `count: 0`. When `companySlug` and `companyId` are both present, the server uses their union.
+
+## Completion gate
+
+- A controller query below two characters renders no results and makes no request.
+- Rapid typing renders only the final response.
+- Excluded companies disappear without changing the relative order of other items.
+- Selecting a company writes its slug to the URL and sends `companySlug` directly.
+- Teardown unsubscribes listeners and calls `dispose`.

package/skills/cavuno-board-seo/BLOG.md

@@ -0,0 +1,40 @@
+# Blog structured data
+
+Read this reference for blog-post `Article` and author `ProfilePage` JSON-LD.
+
+```ts snippet
+import {
+  createAuthorProfileJsonLd,
+  createBlogArticleJsonLd,
+} from '@cavuno/board/seo';
+
+const { name } = await board.context();
+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`,
+});
+
+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,
+  totalPosts: authorPosts.length,
+});
+```
+
+The article `ogImageUrl` is the fallback when the post has no cover. Supply
+author posts newest-first; the profile builder keeps the first five as
+`hasPart`.
+
+This branch is complete when the post emits an `Article`, the author emits a
+`ProfilePage`, every URL is absolute and canonical, and a null builder result
+leaves no script tag.

package/skills/cavuno-board-seo/JOB_AND_BREADCRUMBS.md

@@ -0,0 +1,49 @@
+# Job detail and breadcrumbs
+
+Read this reference for Google for Jobs `JobPosting` or `BreadcrumbList`
+structured data.
+
+## Build JobPosting JSON-LD
+
+`PublicJob` carries the inputs, including derived remote permit codes.
+Worldwide-remote jobs automatically enumerate all 249 countries because
+Google requires a location signal alongside `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}`,
+});
+```
+
+Use the builder as the schema boundary. It encodes pruning, salary mirroring,
+remote-location behavior, and Google for Jobs shapes.
+
+## Build BreadcrumbList JSON-LD
+
+Labels are trimmed, blank crumbs are dropped, and fewer than two surviving
+crumbs return `null`. The current page omits `href`, which makes the builder
+omit its `item`. Supply absolute hrefs, or pass `origin` for path hrefs.
+
+```ts snippet
+import { createBreadcrumbJsonLd } from '@cavuno/board/seo';
+
+const trail = createBreadcrumbJsonLd(
+  [
+    { label: 'Home', href: '/' },
+    { label: 'Jobs', href: '/jobs' },
+    { label: job.title },
+  ],
+  { origin: 'https://jobs.example.com' });
+```
+
+This branch is complete when the JobPosting passes Google's Rich Results test,
+the worldwide-remote fixture contains 249 countries, and breadcrumb output is
+absent below two usable crumbs.

package/skills/cavuno-board-seo/LISTING.md

@@ -0,0 +1,36 @@
+# Listing metadata and JSON-LD
+
+Read this reference for a job-listing page's head descriptors and structural
+JSON-LD. These builders are locale-neutral pass-throughs; supply the page's
+resolved heading copy.
+
+```ts snippet
+import { listingHead, listingJsonLd } from '@cavuno/board/seo';
+
+const { name } = await board.context();
+const head = listingHead({
+  boardName: name,
+  origin: 'https://jobs.example.com',
+  path: '/jobs/robotics',
+  heading: 'Robotics jobs',
+  count: 42,
+});
+
+const objects = listingJsonLd({
+  origin: 'https://jobs.example.com',
+  breadcrumbs: [{ name: 'Home', path: '/' }, { name: 'Jobs' }],
+  jobs: cards.map((card) => ({
+    slug: card.slug,
+    company: card.company,
+  })),
+});
+```
+
+`head.meta` contains title, description, and Open Graph descriptors;
+`head.links` contains the canonical link. For the example, the count-aware
+title is `42 Robotics jobs | Acme Jobs`.
+
+This branch is complete when head descriptors reflect the resolved page
+heading and count, the canonical URL combines the intended origin and path,
+and `listingJsonLd` receives card slugs plus company objects from the listing
+response.