@cavuno/board 4.26.0 → 4.28.0

package/dist/server.d.mts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.mjs';
-import './_spec-EgN7VmAI.mjs';
-import './search-DKS7OIn2.mjs';
-import './board-q0svBKW3.mjs';
-import './jobs-CfrxlDMU.mjs';
-import './seo-CI3wLKUW.mjs';
-import './blog-T7gQ0ciz.mjs';
+import './_spec-DQvmsp5o.mjs';
+import './search-C0LiPXVb.mjs';
+import './board-D6xOidUX.mjs';
+import './jobs-DjMcghv6.mjs';
+import './seo-DCQp8V1c.mjs';
+import './blog-CvuObn9O.mjs';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/server.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-DQvmsp5o.js';
+import './search-D-EjtZH3.js';
+import './board-CCG1pO6r.js';
+import './jobs-CEIuahbz.js';
+import './seo-CjNGqZZH.js';
+import './blog-CUkvhn3c.js';
 
 /**
  * Session cookie codec — pure (no framework imports, no node imports) so it

package/dist/server.mjs

@@ -4,7 +4,7 @@ import {
 } from "./chunk-Z4ALWIGS.mjs";
 import {
   isUnauthorized
-} from "./chunk-DP2ZZZEO.mjs";
+} from "./chunk-EHSB2VAJ.mjs";
 
 // src/server/cookie.ts
 var COOKIE_ATTRIBUTES = "Path=/; HttpOnly; Secure; SameSite=Lax";

package/dist/sitemap.d.mts

@@ -1,10 +1,10 @@
 import { BoardSdk } from './index.mjs';
-import './_spec-EgN7VmAI.mjs';
-import './search-DKS7OIn2.mjs';
-import './board-q0svBKW3.mjs';
-import './jobs-CfrxlDMU.mjs';
-import './seo-CI3wLKUW.mjs';
-import './blog-T7gQ0ciz.mjs';
+import './_spec-DQvmsp5o.mjs';
+import './search-C0LiPXVb.mjs';
+import './board-D6xOidUX.mjs';
+import './jobs-DjMcghv6.mjs';
+import './seo-DCQp8V1c.mjs';
+import './blog-CvuObn9O.mjs';
 
 /**
  * Sitemap primitives — the pure XML + bucket-filename logic behind a board

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-DQvmsp5o.js';
+import './search-D-EjtZH3.js';
+import './board-CCG1pO6r.js';
+import './jobs-CEIuahbz.js';
+import './seo-CjNGqZZH.js';
+import './blog-CUkvhn3c.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-EHSB2VAJ.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-C0LiPXVb.mjs';
+import './_spec-DQvmsp5o.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-D-EjtZH3.js';
+import './_spec-DQvmsp5o.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.28.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
@@ -11,6 +11,31 @@ Anonymous methods here are token-based email unsubscribe and email-change confir
 
 The host application owns forms, file pickers, and cookie plumbing; this SDK surface supplies data operations.
 
+## Candidate screens are candidate-only
+
+A board user is either a candidate or an employer (`me.role`). Only candidates have a candidate profile. Render candidate screens and fields (the profile form, profile completeness, resume upload, experience, education, skills, and languages) only when `me.role === 'candidate'`. On the account page, give an employer account the employer profile view instead: avatar, `displayName` (the one profile field every account can update), and a link to the employer screens (`board.me.companies.*`). Never show them the empty candidate form.
+
+The API is the backstop: a profile write from an account with no candidate profile returns 403 `candidate_profile_required` before anything is saved. `displayName` alone is the one profile field every account can update. Surface this error as a message; never swallow it and report "Saved".
+
+```ts snippet
+import { isBoardApiError } from '@cavuno/board';
+
+const me = await board.me.retrieve();
+if (me.role !== 'candidate') {
+  return renderEmployerProfile(me); // avatar, displayName, link to employer screens
+}
+
+try {
+  await board.me.profile.update({ headline: 'Staff Engineer' });
+  showSaved();
+} catch (error) {
+  if (isBoardApiError(error) && error.code === 'candidate_profile_required') {
+    return showError('Only candidate accounts have a candidate profile.');
+  }
+  throw error;
+}
+```
+
 ## Account and profile
 
 Account deletion is a synchronous, irreversible cascade over the profile, collections, saved jobs, alerts, avatar, and resume. Obtain explicit confirmation before calling it.
@@ -41,6 +66,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 +277,12 @@ await board.me.notificationPreferences.unsubscribeWithToken({
 
 ## Completion gate
 
+- Candidate screens render only for `me.role === 'candidate'`; an employer account gets the employer profile view (avatar, `displayName`, link to employer screens).
+- A `candidate_profile_required` 403 shows an error and never a "Saved" state.
+- 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-errors/SKILL.md

@@ -44,7 +44,7 @@ try {
 }
 ```
 
-The remaining status guards are `isForbidden` for 403 and `isConflict` for 409. Record `code` and `requestId` in support diagnostics. Because v1 may add error codes, unmatched `BoardApiError` instances still need a safe generic state.
+The remaining status guards are `isForbidden` for 403 and `isConflict` for 409. A 403 `candidate_profile_required` means an account that is not a candidate (for example an employer) tried to write candidate profile data: gate candidate screens on `me.role === 'candidate'` and show the error rather than a success state. Record `code` and `requestId` in support diagnostics. Because v1 may add error codes, unmatched `BoardApiError` instances still need a safe generic state.
 
 **Complete when:** every expected failure has one typed branch, an invalid resource renders not-found, and unmatched failures retain their original error.