@cavuno/board 4.26.0 → 4.27.0

package/dist/sitemap.d.ts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.js';
-import './_spec-EgN7VmAI.js';
-import './search-Dx1TiAZk.js';
-import './board-CsEAgsKh.js';
-import './jobs-ub3gywNQ.js';
-import './seo-BbG2Ujyo.js';
-import './blog-BIjFcNcm.js';
+import './_spec-B_pBNVUd.js';
+import './search-BK_zHHNQ.js';
+import './board-fVAXZ8T5.js';
+import './jobs-BRysn2m0.js';
+import './seo-C7gMl6Y7.js';
+import './blog-DzGRUsj5.js';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

package/dist/sitemap.mjs

@@ -3,7 +3,7 @@ import {
 } from "./chunk-DLSO6XXY.mjs";
 import {
   isNotFound
-} from "./chunk-DP2ZZZEO.mjs";
+} from "./chunk-DUTQOLOF.mjs";
 import {
   BOARD_PATHS,
   blogAuthorPath,

package/dist/suggest.d.mts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-DKS7OIn2.mjs';
-import './_spec-EgN7VmAI.mjs';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-BlB690ma.mjs';
+import './_spec-B_pBNVUd.mjs';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/dist/suggest.d.ts

@@ -1,5 +1,5 @@
-import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-Dx1TiAZk.js';
-import './_spec-EgN7VmAI.js';
+import { h as SuggestionItem, b as SearchSuggestQuery, F as FetchOptions, g as SuggestResult } from './search-BK_zHHNQ.js';
+import './_spec-B_pBNVUd.js';
 
 /**
  * `@cavuno/board/suggest` — framework-agnostic headless search-suggest

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "4.26.0",
+  "version": "4.27.0",
   "description": "Build custom job boards and careers pages with Cavuno’s TypeScript SDK.",
   "keywords": [
     "api-client",
@@ -236,6 +236,7 @@
     "@playwright/test": "^1.59.1",
     "@types/node": "24.9.1",
     "esbuild": "^0.27.7",
+    "parse5": "7.3.0",
     "publint": "^0.3.12",
     "tsup": "^8.4.0",
     "tsx": "^4.19.2",

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

@@ -1,6 +1,6 @@
 ---
 name: cavuno-board-account
-description: Candidate self-service boundary with @cavuno/board. Use for account, profile, resume onboarding, recommended jobs, avatar, experience, education, skills, languages, or notification preferences.
+description: Candidate self-service boundary with @cavuno/board. Use for account, profile, custom profile fields, collection selections, resume onboarding, recommended jobs, avatar, experience, education, skills, languages, or notification preferences.
 ---
 
 # Candidate self-service boundary
@@ -41,6 +41,97 @@ const { available } = await board.me.profile.handleAvailable('jane');
 
 Profile updates are merge-patches. Handle availability is advisory—your current handle counts as available—and the write re-checks uniqueness.
 
+## Render the profile form from the operator's layout
+
+`board.context().forms.talent` is the candidate profile form as one ordered list, set by the operator. Render it in order and skip entries with `visible: false`. Each entry has `required`; validate it in the form before saving.
+
+```ts snippet
+const { forms } = await board.context();
+
+for (const field of forms.talent) {
+  if (!field.visible) continue;
+  if (field.kind === 'builtin') {
+    renderProfileBuiltin(field.key, { required: field.required });
+  } else if (field.definition.editableByOwner) {
+    renderProfileField(field, { required: field.required });
+  }
+}
+```
+
+Built-in keys map to the methods below: `name` → `displayName` and `headline`, `location`, `jobSearchStatus`, `bio` → `profile.update`; `email` → `requestEmailChange`; `avatar` → `uploadAvatar`; `experience` and `education` → their CRUD methods; `skills` and `languages` → `updateSkills` / `updateLanguages`. `name` and `email` are locked (always shown and required). Skip a built-in key you do not recognise.
+
+`custom` entries are scalar profile fields (`updateCustomFields`) and `collection` entries are collection fields (`updateObjectReferences`); both carry their public `definition` inline. Render only definitions with `editableByOwner: true` as inputs. The layout lists public fields only; private owner-editable fields come from `retrieveCustomFields` and `retrieveObjectReferences` below. A collection definition with `required: true` needs at least one selection while shown.
+
+## Custom fields and collection selections
+
+Scalar custom-field updates are additive. Render controls from the returned definitions, preserve their value types, and send only owner-editable keys. Omitted keys remain unchanged.
+
+Collection-selection updates replace the complete editable set. Read before writing when the user means to retain existing selections. Each resolved selection includes its display title, optional description and logo, shared attributes, and profile-specific details. Use `listObjectReferenceChoices` to search the active choices for one editable field; do not guess record IDs from names.
+
+```ts snippet
+const customFields = await board.me.profile.retrieveCustomFields();
+await board.me.profile.updateCustomFields({
+  values: { membership_number: 'A-1234' },
+});
+
+const references = await board.me.profile.retrieveObjectReferences();
+const choices = await board.me.profile.listObjectReferenceChoices(
+  'certifications',
+  { search: 'professional', limit: 20 });
+await board.me.profile.updateObjectReferences({
+  selections: [
+    ...references.selections
+      .filter((selection) => selection.fieldKey !== 'certifications')
+      .map(({ fieldKey, recordId, values, entries }) => ({
+        fieldKey,
+        recordId,
+        values,
+        entries,
+      })),
+    {
+      fieldKey: 'certifications',
+      recordId: choices.data[0]!.id,
+    },
+  ],
+});
+```
+
+Approved company members use the parallel company methods. The company slug comes before the body or field key.
+
+```ts snippet
+const companyFields = await board.me.companies.retrieveCustomFields('acme');
+await board.me.companies.updateCustomFields('acme', {
+  values: { founded_year: 2018 },
+});
+
+const companyReferences =
+  await board.me.companies.retrieveObjectReferences('acme');
+const technologies =
+  await board.me.companies.listObjectReferenceChoices(
+    'acme',
+    'technologies',
+    { search: 'typescript', limit: 20 });
+await board.me.companies.updateObjectReferences('acme', {
+  selections: [
+    ...companyReferences.selections
+      .filter((selection) => selection.fieldKey !== 'technologies')
+      .map(({ fieldKey, recordId, values, entries }) => ({
+        fieldKey,
+        recordId,
+        values,
+        entries,
+      })),
+    {
+      fieldKey: 'technologies',
+      recordId: technologies.data[0]!.id,
+      values: { years: 4 },
+    },
+  ],
+});
+```
+
+Collection creation, collection entry mutation, and bulk imports are operator API operations. Keep that API key on the server; the Board SDK intentionally exposes only public discovery and signed-in owner reads and writes.
+
 ## Experience and education
 
 Both collections are id-keyed CRUD with merge-patch updates. Experience creation requires `title`, `companyName`, and `startDate`; education creation requires `institutionName`.
@@ -161,7 +252,10 @@ await board.me.notificationPreferences.unsubscribeWithToken({
 
 ## Completion gate
 
+- The profile form follows `forms.talent`: order matches, hidden fields are absent, and required fields block save while empty.
 - Profile update is visible after retrieval.
+- Scalar field updates preserve omitted values; collection selection updates preserve every selection the user meant to keep.
+- Choice searches use the returned record `id`, and an optional returned `logoUrl` renders without a separate logo map.
 - Adding a skill preserves every existing skill.
 - Uploaded `avatarUrl` renders.
 - Resume parsing reaches `parsed`, reports `parseFailureReason`, or reaches the explicit delayed state without blocking editing.

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

@@ -0,0 +1,148 @@
+---
+name: cavuno-board-collections
+description: Custom profile fields and collection references with @cavuno/board. Use for rendering company, talent or job custom fields, collection entries, benefits/technologies/certification sections, or collection-backed filters.
+---
+
+# Custom fields and collections
+
+An operator defines two kinds of extra data. A **custom field** stores one typed value directly on a company, talent profile, or job. A **collection reference** points that record at reusable entries — benefits, technologies, certifications, learning resources — that the operator maintains once and every record shares.
+
+Hosted Cavuno boards do not render either one. The API resolves them and your frontend decides the layout, so this surface is read-heavy: definitions tell you what to draw, resolved selections tell you what to draw it with.
+
+## The read model
+
+Scalar values arrive opaque and keyed by field key; the labels, types, and select options live in a separate definition list. Never hard-code a label.
+
+- Job definitions: `board.context()` → `customFields.job` (scalar) and `customFields.jobCollections` (collection fields).
+- Company and talent definitions: `board.profileFields.retrieve('company' | 'candidate')` → `definitions` (scalar) and `referenceDefinitions` (collection fields).
+
+To build an input form rather than a display, read `board.context().forms` (`job`, `company`, `talent`): the operator's field order with each custom and collection definition inlined, plus which fields are shown and required. `cavuno-board-post-a-job`, `cavuno-board-account`, and `cavuno-board-companies` show how to render each form.
+
+A collection field definition carries `multiple`, and a multiple one may carry `maxSelections` — an operator-defined maximum, up to 100. Cap a picker at that number when it is present, at 100 when it is absent, and at one when `multiple` is false.
+
+A job collection definition may also carry `allowOverrides` — each job can replace a selected entry's title and description — and `descriptionFieldKey`, the entry field whose value is the default description. Both are absent when the operator has not set them.
+
+Resolved data rides on the detail responses:
+
+```ts snippet
+const context = await board.context();
+const definitions = context.customFields.job;
+
+const job = await board.jobs.retrieve('senior-chef');
+job.customFieldValues.clearance;
+job.resolvedCollectionFields;
+
+const company = await board.companies.retrieve('acme');
+company.customFieldValues.member_tier;
+company.objectReferences;
+
+const profile = await board.talent.retrieve('jane-doe');
+profile.customFieldValues.available_for_mentoring;
+profile.objectReferences;
+```
+
+A company or talent selection (`objectReferences[]`) carries `fieldKey`, `fieldLabel`, `recordId`, the entry's `slug` when it has one, a resolved `title` and optional `description`, optional `logoUrl`, the entry's own `fields` and `attributes`, and the record-specific `valueDefinitions` / `values` plus `entryDefinitions` / `entries`. `titleOverride` and `descriptionOverride` are present only when the profile replaced the shared wording — `title` and `description` are already resolved, so render those.
+
+```ts snippet
+const company = await board.companies.retrieve('acme');
+
+for (const selection of company.objectReferences) {
+  if (selection.fieldKey !== 'benefits') continue;
+  renderBenefit({
+    heading: selection.title,
+    body: selection.description,
+    logoUrl: selection.logoUrl,
+    daysPerYear: selection.values.days_per_year,
+  });
+}
+```
+
+`values` holds one set of typed details for the selection. `entries` holds repeatable rows, each `{ key, values }` — several awards of one certification, for example. Both are `{}` / `[]` when the field defines no details.
+
+Jobs use a different shape: `resolvedCollectionFields` is an array of `{ key, label, entries }`, and each entry is `{ id, name, slug?, logoUrl?, title, description, titleOverride, descriptionOverride, fields, values, references? }`. `title` and `description` are the entry's wording on this job, already resolved: the job's own wording when it set one, otherwise the entry `name` and the value of the definition's `descriptionFieldKey` field (`description` is `null` when neither exists). `titleOverride` and `descriptionOverride` hold the job's own wording, or `null` when the job uses the defaults. A job's wording is plain text; when the default description field is rich text, `description` is sanitised HTML with that wording escaped into paragraphs, so insert `description` as HTML only in that case. Jobs have no per-selection details or repeatable rows.
+
+```ts snippet
+const job = await board.jobs.retrieve('senior-chef');
+
+for (const field of job.resolvedCollectionFields) {
+  for (const entry of field.entries) {
+    renderChip({
+      label: entry.title,
+      description: entry.description,
+      logoUrl: entry.logoUrl,
+      group: field.label,
+    });
+  }
+}
+```
+
+Visibility is enforced server-side. Public reads return only public scalar fields, public collection fields, and active entries; private definitions and archived entries are omitted entirely, not nulled. Do not render a placeholder for a key that is absent — the operator meant it to be invisible. An owner read returns the private owner-editable fields too, so the same component can receive either payload; branch on what is present.
+
+## Owner writes
+
+Collection creation, entry mutation, and imports are operator API operations and are not on this SDK. A signed-in candidate or approved company member edits their own selections through `board.me`, where a selection update replaces the whole editable set and a scalar update is additive. Those read-modify-write rules, the choice search, and the repeatable-entry `key` contract live in `cavuno-board-account` — follow that skill for any write.
+
+An approved company member sets a job's own wording with `collectionOverrides` on `board.me.companies.jobs.create` / `update`: one `{ fieldKey, recordId, title?, description? }` per selected entry, only on a field whose definition has `allowOverrides`. `cavuno-board-post-a-job` shows the form.
+
+## Rendering
+
+- Take every label from the definition list (`referenceDefinitions[].label`, `definitions[].label`, `fieldLabel`, `field.label`), never from the key.
+- Render in the order the API returns. Definitions are in operator display order and selections follow the record's order; do not re-sort.
+- Resolve a select value through the definition's `options[].key` → `label`. A stored value is an option key, or an array of them for multi-select.
+- Media attributes are already metadata objects: `{ id, name, contentType, sizeBytes, url }`. An `image` or `file` attribute is one object, an `image_gallery` attribute is an array. Load by the returned `url`; never build a URL yourself.
+- `logoUrl` is optional on a selection, a job collection entry, and a choice row. The operator gives a collection a logo by adding an `image` field and marking it as the logo; `logoUrl` is that image's URL for the entry (older entries may instead carry a logo URL saved before logos were image fields). When present it is the entry's own logo — render it directly, loading it like any other media `url`, rather than keeping a second name-to-logo map, and fall back to initials or nothing when it is absent. The logo image may also appear among the entry's `attributes`; do not render it twice.
+- A `rich_text` value is sanitised HTML from the server. Insert it as HTML; do not re-escape it into visible tags and do not run a second markdown pass over it.
+- `references` on an entry is keyed by the reference field's key and always holds an array, even for a single reference.
+- Build an entry URL from its `slug`, never from `name` or `id`. A slug is URL-safe and unique within one collection only, so keep the collection or field in the path (`/benefits/annual-leave`). Renaming an entry keeps its slug; when the operator changes a slug, the previous one stays reserved for that entry. `slug` is on selections, job collection entries, nested `references`, and choice rows, and can be absent on entries saved before slugs existed — fall back to a non-linked render then.
+- Number, boolean, and date values keep their JSON types. `0` and `false` are real values — test for `undefined`, not falsiness.
+
+## Filters
+
+Public collection entries are filter values. Company and talent search accept `objectReferences: [{ key, recordIds }]`; job, company, and talent search accept `customFields: [{ key, values }]`. Load the options first and submit the returned record `id`.
+
+```ts snippet
+const choices = await board.profileFields.choices('company', 'technologies', {
+  search: 'typescript',
+  limit: 20,
+});
+
+const companies = await board.companies.search({
+  objectReferences: [
+    { key: 'technologies', recordIds: [choices.data[0]!.id] },
+  ],
+});
+
+const talent = await board.talent.list({
+  objectReferences: [
+    { key: 'certifications', recordIds: [choices.data[0]!.id] },
+  ],
+});
+
+const jobChoices = await board.jobs.collectionChoices('tech_stack', {
+  limit: 20,
+});
+
+void companies.data;
+void talent.data;
+void jobChoices.data;
+```
+
+Clause and cursor rules, the `invalid_filter` cases, and the listing-URL contract belong to `cavuno-board-filters`.
+
+## Completion gate
+
+Finish only after every applicable check passes:
+
+- Every rendered label comes from a definition or a resolved `fieldLabel`, and no key is displayed raw.
+- Select values render as their option label, and `0` / `false` survive to the screen.
+- A selection or job collection entry renders its resolved `title` and `description`, so an overridden entry shows the record's wording and a non-overridden one shows the collection default.
+- Media renders from the returned `url`, an `image_gallery` renders every image, and a missing `logoUrl` degrades without a broken image.
+- Rich text renders as formatted HTML, not escaped tags.
+- A private field and an archived entry are absent from the public render, with no empty placeholder left behind.
+- Job pages read `resolvedCollectionFields`, and company or talent pages read `objectReferences` — neither shape is assumed for the other.
+- Filter requests carry record IDs from a choices call, and the filter control's options come from the public definition list.
+- A multi-select picker stops at the definition's `maxSelections`, or at 100 when the definition omits it.
+
+## Cavuno SDK reference
+
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).

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

@@ -1,6 +1,6 @@
 ---
 name: cavuno-board-companies
-description: Company catalog reads with @cavuno/board. Use for company indexes, market archives, profiles, company job rails, similar companies, or company salary pages.
+description: Company catalog reads with @cavuno/board. Use for company indexes, market archives, profiles, company job rails, similar companies, company salary pages, or employer job drafts.
 ---
 
 # Companies
@@ -39,6 +39,47 @@ await board.me.companies.revokeInvite('acme', invites[0].id);
 const { companySlug } = await board.me.acceptInvite({ token });
 ```
 
+An approved member drafts jobs with `board.me.companies.jobs.create`. The body
+must carry `remoteOption` (`on_site`, `hybrid`, or `remote`): `on_site` and
+`hybrid` also need `officeLocations`, and `remote` needs `remotePermits`. A
+salary is optional, but a `salaryMin` or `salaryMax` needs both
+`salaryCurrency` and `salaryTimeframe`. `update` cannot clear `remoteOption`,
+and an update that sends salary fields is checked against the stored salary.
+Each violation is a 400 `validation_bad_request` naming the field.
+
+```ts snippet
+const draft = await board.me.companies.jobs.create('acme', {
+  title: 'Staff Engineer',
+  description: 'Build the platform.',
+  remoteOption: 'remote',
+  remotePermits: [{ type: 'worldwide', value: 'worldwide' }],
+  salaryMin: 150000,
+  salaryMax: 190000,
+  salaryCurrency: 'USD',
+  salaryTimeframe: 'per_year',
+});
+await board.me.companies.jobs.update('acme', draft.id, { salaryMax: 200000 });
+```
+
+## Render the company profile form
+
+`board.context().forms.company` is the company profile form as one ordered list, set by the operator. Use it for `board.me.companies.create` and `update`: render in order, skip entries with `visible: false`, and validate `required` in the form before saving.
+
+```ts snippet
+const { forms } = await board.context();
+
+for (const field of forms.company) {
+  if (!field.visible) continue;
+  if (field.kind === 'builtin') {
+    renderCompanyBuiltin(field.key, { required: field.required });
+  } else if (field.definition.editableByOwner) {
+    renderCompanyField(field, { required: field.required });
+  }
+}
+```
+
+Built-in keys `name`, `website`, `summary`, `xUrl`, `linkedinUrl`, `facebookUrl`, and `description` are the same-named body fields of `create` / `update`; `logo` is `board.me.companies.uploadLogo`. `name` is locked (always shown and required). Skip a built-in key you do not recognise. `custom` entries write through `updateCustomFields` and `collection` entries through `updateObjectReferences`; both carry their public `definition` inline, and only `editableByOwner` definitions are inputs. See `cavuno-board-account` for those write rules.
+
 ## List and search
 
 `companies.list` returns `CompanyListEnvelope`: `ListEnvelope<PublicCompany>`
@@ -146,6 +187,7 @@ one. Gate a Salaries tab with `company.salarySampleCount > 0` from
 
 Finish only after every applicable check passes:
 
+- The company form follows `forms.company`: order matches, hidden fields are absent, and required fields block save while empty.
 - A known company is a `public_company`; only its retrieve response has a
   `markets` array.
 - A listed market slug works as `marketSlug`, while an invented one produces a

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

@@ -1,6 +1,6 @@
 ---
 name: cavuno-board-filters
-description: Listing-filter contracts with @cavuno/board. Use for job filter controls, sort controls, listing URL validation, or taxonomy-backed filter options.
+description: Listing-filter contracts with @cavuno/board. Use for job filter controls, profile-field filters, collection choices, sort controls, listing URL validation, or taxonomy-backed filter options.
 ---
 
 # Listing filters
@@ -41,6 +41,33 @@ const page = await board.jobs.list({
 Company slugs are the URL identity. Map `filters.company` directly to
 `companySlug` in `jobs.list` queries or `jobs.search` filters.
 
+## Filter by category in search
+
+An "All filters" panel can carry a category facet next to seniority, company,
+workplace and employment type. `parseListingFilters` reads `category` the same
+way as company (repeated or comma-separated slugs, first 10 kept). Send it as
+`filters.categories` in a `jobs.search` body; a job matches when it has any of
+the given categories, and the other filters still apply.
+
+```ts snippet
+const results = await board.jobs.search({
+  query: filters.q,
+  sort: filters.sort,
+  filters: {
+    categories: filters.category,
+    seniority: filters.seniority,
+    companySlug: filters.company,
+    remoteOption: filters.remoteOption ? [filters.remoteOption] : undefined,
+  },
+  limit: 20,
+});
+```
+
+`categories` accepts a term's `sourceSlug` or its board-language
+`canonicalSlug`; an unknown slug matches no jobs. `jobs.list` takes a single
+`category` instead, which seeds a category landing page rather than filtering
+a search. Use `jobs.search` whenever the category is one facet among several.
+
 ## Render controls from the vocabulary
 
 ```ts snippet
@@ -123,6 +150,45 @@ const { items } = await board.search.suggest({
 The host router owns URL serialization and saved-filter persistence.
 Locations come from `board.taxonomy.places` rather than a static filter export.
 
+## Build filters from public profile fields
+
+`board.profileFields.retrieve('company')` and `retrieve('candidate')` return only public scalar and collection-reference definitions. Use each stored field key for filtering. For a collection reference, page or search its active public choices and submit the returned record `id`; the optional `logoUrl` is display metadata.
+
+```ts snippet
+const companyFields = await board.profileFields.retrieve('company');
+const technologyChoices = await board.profileFields.choices(
+  'company',
+  'technologies',
+  { search: 'typescript', limit: 20 });
+
+const companies = await board.companies.search({
+  query: 'engineering',
+  customFields: [{ key: 'member_tier', values: ['gold'] }],
+  objectReferences: [
+    { key: 'technologies', recordIds: [technologyChoices.data[0]!.id] },
+  ],
+});
+
+const candidateFields = await board.profileFields.retrieve('candidate');
+const certifications = await board.profileFields.choices(
+  'candidate',
+  'certifications',
+  { limit: 20 });
+const talent = await board.talent.list({
+  customFields: [{ key: 'available_for_mentoring', values: [true] }],
+  objectReferences: [
+    { key: 'certifications', recordIds: [certifications.data[0]!.id] },
+  ],
+});
+
+void companyFields.definitions;
+void candidateFields.referenceDefinitions;
+void companies.data;
+void talent.data;
+```
+
+Clauses are AND-matched. Values or record IDs inside one clause are alternatives. Unknown, private, invalid, or archived choices return `invalid_filter`; each array accepts at most 10 clauses and each clause at most 10 choices. Job search supports scalar `customFields` under `filters`, but job collection references are outside this surface.
+
 ## Completion gate
 
 Finish only after every applicable check passes:
@@ -135,7 +201,11 @@ Finish only after every applicable check passes:
   relevance, newest, and salary high.
 - Category and skill filtering sends `sourceSlug`, while links use
   `canonicalSlug`.
+- `/jobs?category=engineering,design` sends
+  `filters.categories: ['engineering', 'design']` to `jobs.search`.
 - Every paged taxonomy request forwards the previous opaque `nextCursor`.
+- Company and talent custom controls come from `board.profileFields`; private definitions and archived choices never become filter options.
+- Profile-filter requests use stored scalar values and returned collection entry IDs, not display labels.
 
 ## Cavuno SDK reference
 

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

@@ -26,7 +26,7 @@ for (const offer of offers) {
 }
 ```
 
-`offerType` is `'recurring' | 'lifetime'`; post the selected `offerKey` to checkout.
+`offerType` is `'recurring' | 'lifetime'`; post the selected `offerKey` to checkout unchanged. Treat it as opaque: newer offers use plan IDs, while older offers may use tier keys. Never derive it from the billing interval.
 
 Gated catalog reads expose withheld inventory as `gatedCount`. The same jobs endpoint returns the entitled view when called with the candidate bearer token.
 
@@ -44,8 +44,11 @@ if ((page.gatedCount ?? 0) > 0) {
 ```ts snippet
 import { loadStripe } from '@stripe/stripe-js';
 
+const { data: checkoutOffers } = await board.paywall.offers();
+const selectedOffer = checkoutOffers[0]; // Or the offer selected in your UI.
+if (!selectedOffer) throw new Error('No access offers available');
 const kit = await board.me.access.checkout({
-  offerKey: 'monthly',
+  offerKey: selectedOffer.offerKey,
   returnPath: '/account/access',
   colorMode: 'light',
 });

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

@@ -24,6 +24,69 @@ for (const plan of plans) {
 
 Pass the chosen `plan.id` as `submission.selectedPlan`. Invoice-only plans collect `invoiceBilling` rather than immediate payment.
 
+## Render the form from the operator's layout
+
+The operator orders the job form and chooses which fields show and which are required. `board.context().forms.job` is that form as one ordered list; render it top to bottom and never hard-code the order. Skip entries with `visible: false`: a hidden field is not collected and is never required.
+
+```ts snippet
+const { forms, jobForm } = await board.context();
+
+for (const field of forms.job) {
+  if (!field.visible) continue;
+  switch (field.kind) {
+    case 'builtin':
+      renderBuiltin(field.key, { required: field.required, locked: field.locked });
+      break;
+    case 'custom':
+      renderCustomField(field.definition, { required: field.required });
+      break;
+    case 'collection':
+      renderCollectionPicker(field.definition, { required: field.required });
+      break;
+  }
+}
+```
+
+A `builtin` entry is drawn by your own control for its `key`. A `locked` built-in is always shown and required; `lockReason` says why (for example `google_required` for the title and description Google for Jobs needs). Skip a built-in key you do not recognise. The keys map to submission fields:
+
+| `key` | Submission fields |
+| --- | --- |
+| `employmentType` | `employmentType`, from `jobForm.employmentType.allowedOptions` |
+| `seniority` | `seniority`, from `jobForm.seniority.allowedOptions` |
+| `title` | `title` |
+| `workArrangement` | `remoteOption`, from `jobForm.workArrangement.allowedOptions` |
+| `location` | `officeLocations`, `inOfficePeriod`, `inOfficeFrequency` |
+| `remoteEligibility` | `remoteWorkingPermits`, `remoteTimezones`, and `remoteSponsorship` when `jobForm.sponsorship.visible` |
+| `description` | `description` |
+| `salary` | `salaryRangeEnabled`, `salaryMin`, `salaryMax`, `salaryTimeframe`, `salaryCurrency` |
+| `applyMethod` | `applicationUrl` |
+| `company` | `companyName`, `companyWebsite`, and the resolved logo |
+
+`contactName`, `contactEmail`, and the plan are not layout fields; always collect them. `jobForm` still carries each built-in's allowed options and salary bounds.
+
+A `custom` entry renders from `definition` (`label`, `type`, `options`, `helpText`) and submits under `submission.customFieldValues[field.key]`; store option keys, never labels. A `collection` entry renders a picker capped by `definition.maxSelections` (one when `multiple` is false) with choices from `board.jobs.collectionChoices(field.key)`. The anonymous funnel takes no collection values, so collection fields belong on the signed-in employer job form (`board.me.companies.jobs.create`, `collectionValues`). Custom and collection rendering rules live in `cavuno-board-collections`.
+
+When a collection definition has `allowOverrides`, the employer job form can give each selected entry its own wording for this job — "Unlimited PTO" in place of the shared "Annual leave", for example. Offer an edit action per selected entry with a title (up to 160 characters) and a plain-text description (up to 2,000 characters), and send them as `collectionOverrides`, one item per entry that has wording:
+
+```ts snippet
+const created = await board.me.companies.jobs.create('acme', {
+  title: 'Head chef',
+  description: 'Run the kitchen.',
+  collectionValues: { benefits: [annualLeaveId] },
+  collectionOverrides: [
+    { fieldKey: 'benefits', recordId: annualLeaveId, title: 'Unlimited PTO' },
+  ],
+});
+
+await board.me.companies.jobs.update('acme', created.id, {
+  collectionOverrides: [],
+});
+```
+
+The list replaces the job's wording: omit it on `update` to keep what is stored, and send `[]` to restore every default. Wording for an entry the job does not select, or on a field without `allowOverrides`, is rejected with `jobs_constraint_violation`; `details.violations[].params.fieldKey` names the field, so show the message under it. Deselecting an entry drops its wording. The job's collection entries then return the resolved `title` and `description` to render.
+
+Validate `required` client-side from these entries before submitting, so the poster sees a missing field before the request.
+
 ## Resolve a logo
 
 Both logo paths return a stored `publicUrl` for `create`. The SDK owns multipart encoding.
@@ -111,6 +174,7 @@ Bare-email billing lookup is intentionally absent because it would expose whethe
 
 ## Completion gate
 
+- The form renders `forms.job` in order: hidden entries are absent, required and locked entries block submit while empty, and an unknown built-in key is skipped.
 - 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`.

package/skills/manifest.json

@@ -1,9 +1,9 @@
 {
-  "version": "4.26.0",
+  "version": "4.27.0",
   "skills": [
     {
       "name": "cavuno-board-account",
-      "description": "Candidate self-service boundary with @cavuno/board. Use for account, profile, resume onboarding, recommended jobs, avatar, experience, education, skills, languages, or notification preferences.",
+      "description": "Candidate self-service boundary with @cavuno/board. Use for account, profile, custom profile fields, collection selections, resume onboarding, recommended jobs, avatar, experience, education, skills, languages, or notification preferences.",
       "path": "skills/cavuno-board-account/SKILL.md",
       "framework": null,
       "category": "core"
@@ -36,9 +36,16 @@
       "framework": null,
       "category": "core"
     },
+    {
+      "name": "cavuno-board-collections",
+      "description": "Custom profile fields and collection references with @cavuno/board. Use for rendering company, talent or job custom fields, collection entries, benefits/technologies/certification sections, or collection-backed filters.",
+      "path": "skills/cavuno-board-collections/SKILL.md",
+      "framework": null,
+      "category": "core"
+    },
     {
       "name": "cavuno-board-companies",
-      "description": "Company catalog reads with @cavuno/board. Use for company indexes, market archives, profiles, company job rails, similar companies, or company salary pages.",
+      "description": "Company catalog reads with @cavuno/board. Use for company indexes, market archives, profiles, company job rails, similar companies, company salary pages, or employer job drafts.",
       "path": "skills/cavuno-board-companies/SKILL.md",
       "framework": null,
       "category": "core"
@@ -52,7 +59,7 @@
     },
     {
       "name": "cavuno-board-filters",
-      "description": "Listing-filter contracts with @cavuno/board. Use for job filter controls, sort controls, listing URL validation, or taxonomy-backed filter options.",
+      "description": "Listing-filter contracts with @cavuno/board. Use for job filter controls, profile-field filters, collection choices, sort controls, listing URL validation, or taxonomy-backed filter options.",
       "path": "skills/cavuno-board-filters/SKILL.md",
       "framework": null,
       "category": "core"