@cavuno/board 1.25.0 → 1.26.0

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

@@ -0,0 +1,110 @@
+---
+name: cavuno-board-applications
+description: The native apply flow with the @cavuno/board SDK — jobs.apply (signed-in or guest), attaching a resume via jobs.uploadApplicationResume, the jobs.myApplication "have I applied?" check, managing submitted applications (me.applications list/retrieve/updateFacts/withdraw), and saved jobs (me.savedJobs). Use when building an apply form, an application-tracker page, or a save-job button.
+---
+
+# Apply flow and application tracking
+
+Apply lives on the job (`board.jobs.apply` — optional-auth); everything after submission lives under `board.me.applications` (bearer token required, see `cavuno-board-auth`). Saved jobs follow the same authenticated pattern.
+
+## When to use
+
+- The apply form on a job page (native apply, signed-in or guest).
+- Attaching a resume to an application.
+- "My applications" tracker: list, detail, edit facts, withdraw.
+- Save/unsave-job buttons and the saved-jobs page.
+
+## When not to use
+
+- Jobs whose `applicationUrl` points off-board (external apply) — just link out.
+- The employer's pipeline view of the same data (`me.companies.applicants.*`).
+- Candidate profile/resume self-service — `cavuno-board-account`.
+
+Out of scope — do not invent exports: the SDK provides no apply-form components, file-picker UI, or auth cookie plumbing — the host app owns those. There is also **no guest-claim method** on the SDK: after a guest signs up, their applications are associated via a server-driven magic-link email flow, not an SDK call.
+
+## Submit an application
+
+`jobs.apply` is optional-auth on one URL. Signed in, name/email derive from the candidate profile — send at most a `coverNote`. A guest supplies `name` + `email` (allowed only when the board permits applying without sign-up; otherwise the call fails). Idempotent — a repeat apply returns the existing application.
+
+```ts snippet
+// Signed-in candidate:
+const application = await board.jobs.apply('senior-chef', {
+  coverNote: 'Excited to cook here.',
+});
+
+// Guest (board must allow applications without sign-up):
+const guestApp = await board.jobs.apply('senior-chef', {
+  name: 'Ada Lovelace',
+  email: 'ada@example.com',
+});
+```
+
+## Attach a resume
+
+A separate multipart call — pass a `Blob`/`File`; the SDK builds the `FormData`. A signed-in candidate targets their own application for the job; a guest passes the `applicationId` returned by `apply`. Returns the updated application (`resumeFilename` set).
+
+```ts snippet
+// Signed-in:
+await board.jobs.uploadApplicationResume('senior-chef', file);
+// Guest:
+await board.jobs.uploadApplicationResume('senior-chef', file, {
+  applicationId: guestApp.id,
+});
+```
+
+## "Have I applied?" — the apply-button state
+
+`jobs.myApplication` returns the authenticated candidate's application for the job, and **throws a 404 `BoardApiError` when there is none** — branch with `isNotFound`:
+
+```ts snippet
+import { isNotFound } from '@cavuno/board';
+
+try {
+  const mine = await board.jobs.myApplication('senior-chef');
+  // already applied — show status instead of the apply button
+} catch (err) {
+  if (!isNotFound(err)) throw err;
+  // not applied yet — show the apply form
+}
+```
+
+## Application status — polled, not realtime
+
+`Application.status` is a coarse candidate-facing state **derived from the employer's pipeline stage**: `'applied' | 'interviewing' | 'negotiation' | 'hired' | 'archived'`. It changes server-side as the employer moves the applicant — the surface is plain REST, so re-fetch to observe updates; nothing pushes to the client. `job` on the application is nullable (the job may have been removed).
+
+## Manage my applications
+
+```ts snippet
+const { data, nextCursor } = await board.me.applications.list({ limit: 20 }); // newest first
+const app = await board.me.applications.retrieve(applicationId);
+
+// Merge-patch the candidate-facing facts — only while still editable:
+await board.me.applications.updateFacts(applicationId, {
+  coverNote: 'Updated after our call.',
+});
+
+await board.me.applications.withdraw(applicationId); // 204 — permanently deletes
+```
+
+`updateFacts` accepts `candidateName`, `candidateEmail`, `candidateHeadline`, `candidateLocation`, `coverNote` (all optional). Withdraw is permanent deletion, not a status flip — confirm before calling.
+
+## Saved jobs — the adjacent pattern
+
+Same authenticated `me.*` shape. Each saved row embeds the full `PublicJob`, so the saved-jobs page renders without extra fetches.
+
+```ts snippet
+const saved = await board.me.savedJobs.list({ limit: 20 });
+saved.data[0]?.job.title; // full PublicJob embedded
+
+await board.me.savedJobs.save({ jobId: job.id }); // converges — re-saving returns the same row
+await board.me.savedJobs.unsave(job.id); // idempotent — unknown ids still 204
+```
+
+## Verify
+
+- [ ] Signed-in apply sends no name/email; guest apply sends both.
+- [ ] A second apply to the same job returns the same application id (no duplicate).
+- [ ] After `uploadApplicationResume`, the application's `resumeFilename` is set.
+- [ ] The apply button flips state via `myApplication` + `isNotFound`, not a local flag.
+- [ ] Withdraw removes the row from `me.applications.list` on re-fetch.
+- [ ] Unsave leaves the saved-jobs list consistent even when clicked twice.

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

@@ -0,0 +1,99 @@
+---
+name: cavuno-board-blog
+description: Build the blog with the @cavuno/board SDK — post archives (blog.posts.list with tagSlug/authorSlug/featured), the post page (blog.posts.retrieve + adjacent + similar), blog.tags and blog.authors, and free-text blog.search. Covers the summary-vs-detail split (html on the single read only), cursor pagination, slug-change redirects (redirected/newSlug), and the SEO fields the API actually returns.
+---
+
+# Blog: posts, tags, authors, search
+
+Every list and search returns `PublicBlogPostSummary`; only `posts.retrieve` returns the full `PublicBlogPost` with the `html` body.
+
+## When to use
+
+- The blog index, tag archives, author archives, and featured rails.
+- The post page: body, prev/next nav, related-posts rail.
+- Blog search boxes.
+
+## When not to use
+
+- Writing posts/tags/authors — that is the admin API; this SDK is the public read surface.
+- Deciding whether the board has a blog at all — read `features.blog` from the board context.
+
+Out of scope — do not invent exports: no RSS feed, sitemap, or OG-image generation — the host app builds those routes from the data here (`publishedAt`, `canonicalUrl`, `ogImageUrl` are all returned).
+
+## List posts and archives
+
+`blog.posts.list` returns a `ListEnvelope<PublicBlogPostSummary>`. `BlogPostsListQuery` supports `limit` (1–100), `cursor`, `tagSlug`, `authorSlug`, and `featured: 'true'` (opt-in only — the string literal, not a boolean). Blog lists page by cursor only; there is no `offset` and no total `count`.
+
+```ts snippet
+const page = await board.blog.posts.list({ tagSlug: 'news', limit: 12 });
+for (const post of page.data) {
+  post.title;
+  post.customExcerpt;   // null unless the author wrote one
+  post.coverUrl;        // null when no cover image
+  post.readingTimeMin;
+  post.authors;         // embedded: id, name, slug, bio, avatarUrl, social URLs
+  post.tags;            // embedded: id, name, slug, description
+}
+const next = page.nextCursor
+  ? await board.blog.posts.list({ tagSlug: 'news', limit: 12, cursor: page.nextCursor })
+  : null; // nextCursor is null when hasMore is false
+```
+
+## Render a post
+
+`posts.retrieve` adds the detail-only fields: `html` (the rendered rich-text body, nullable), `ogImageUrl`, `featureImageCaption`, `seoTitle`, `seoDescription`, `redirected`, `newSlug`.
+
+```ts snippet
+const post = await board.blog.posts.retrieve('hello-world');
+if (post.redirected && post.newSlug) {
+  // the slug changed — redirect to the post at newSlug instead of rendering here
+}
+post.html;                          // inject as the article body
+post.seoTitle ?? post.title;        // <title>
+post.seoDescription ?? post.customExcerpt; // meta description
+post.canonicalUrl;                  // author-set canonical override, or null
+post.ogImageUrl ?? post.coverUrl;   // social card image
+```
+
+Anti-pattern: don't render a post at a stale URL. When `redirected` is true, issue a redirect to `newSlug` — old slugs keep resolving, but the canonical location moved.
+
+Anti-pattern: don't look for `html` on list items. Summaries never carry it; fetch `retrieve` for the post page only.
+
+## Prev/next and related
+
+```ts snippet
+const { previous, next } = await board.blog.posts.adjacent('hello-world');
+// previous = older post, next = newer; each a summary or null
+
+const rail = await board.blog.posts.similar('hello-world', { limit: 6 }); // 1–20, default 6
+```
+
+## Tags and authors
+
+Both are list + retrieve-by-slug. `PublicBlogTag`: `id`, `name`, `slug`, `description`. `PublicBlogAuthor`: `id`, `name`, `slug`, `bio`, `avatarUrl`, `websiteUrl`, `twitterUrl`, `linkedinUrl`, `githubUrl`.
+
+```ts snippet
+const { data: tags } = await board.blog.tags.list();
+const tag = await board.blog.tags.retrieve('news');
+const { data: authors } = await board.blog.authors.list();
+const author = await board.blog.authors.retrieve('jane');
+```
+
+Archive pages combine the two: `tags.retrieve` for the header, `posts.list({ tagSlug })` for the posts.
+
+## Search
+
+`blog.search` posts a `BlogSearchBody` (`query` up to 200 chars, optional `cursor`, `limit` 1–50 — note the lower cap than lists) and returns a `SearchEnvelope<PublicBlogPostSummary>`:
+
+```ts snippet
+const results = await board.blog.search({ query: 'launch', limit: 10 });
+results.data[0]?.slug;
+```
+
+## Verify
+
+- A list item has no `html` key; `posts.retrieve` of the same slug returns it (string or null).
+- Retrieving a post by an old slug returns `redirected: true` with `newSlug` set, and your route redirects there.
+- `posts.list({ featured: 'true' })` returns only posts with `featured: true`.
+- Cursor paging terminates: `nextCursor` is `null` on the last page.
+- `adjacent` on the newest post returns `next: null`; on the oldest, `previous: null`.

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

@@ -0,0 +1,99 @@
+---
+name: cavuno-board-companies
+description: Build company surfaces with the @cavuno/board SDK — the companies index (companies.list / companies.search with the market filter), the company profile (companies.retrieve, listJobs, similar), the markets sub-surface (companies.markets + markets.resolve with its 308 redirectTo), and company salary pages (companies.salaries + salaries.category). Covers PublicCompany vs PublicCompanyDetail and envelope pagination.
+---
+
+# Companies: index, profile, markets, salaries
+
+Lists and search return `PublicCompany`; only `retrieve` returns `PublicCompanyDetail` (which adds `markets`). Company salary pages are their own sub-surface under `companies.salaries`.
+
+## When to use
+
+- The companies index page and its market (sector) filter.
+- The company profile page: detail, open-jobs list, similar-companies rail.
+- Per-company salary pages (`/companies/:slug/salaries[/:category]`).
+
+## When not to use
+
+- Board-wide job browse/search — `jobs.*` (see cavuno-board-jobs).
+- Board-wide salary hubs (titles/skills/locations) — `board.salaries.*`.
+- Employer self-service (claiming/managing a company) — the authed `board.me.companies.*` surface.
+
+Out of scope — do not invent exports: no company create/update/logo upload (that is the admin API, not this SDK), and no sitemap or OG-image generation — the host app owns those routes.
+
+## List, search, market filter
+
+`companies.list` returns a `CompanyListEnvelope`: `ListEnvelope<PublicCompany>` plus optional `relatedSearches` (market suggestions). `CompaniesListQuery` supports `limit` (1–100), `cursor`, `offset` (takes precedence over `cursor`; pair with the response `count` to page in parallel), and `marketSlug` — unknown market slugs 404.
+
+```ts snippet
+const page = await board.companies.list({ limit: 20, marketSlug: 'cybersecurity' });
+page.hasMore;
+page.nextCursor; // null when hasMore is false
+for (const company of page.data) {
+  company.name;
+  company.publishedJobCount;
+  company.links.public; // canonical URL, or null when the company lacks a slug
+}
+```
+
+`companies.search` posts a `CompaniesSearchBody` (`query` free text matched against the company name, up to 200 chars; optional `marketSlug`, `cursor`, `limit` 1–100) and returns a `SearchEnvelope<PublicCompany>`:
+
+```ts snippet
+const results = await board.companies.search({ query: 'acme', limit: 20 });
+```
+
+## Markets (sectors)
+
+`companies.markets` is callable AND carries `.resolve`. The call lists the board's markets ranked by company count (`CompanyMarket`: `slug`, `name`, `companyCount`; `limit` 1–200, default 100 — a top-N preview; optional `search`). `.resolve(slug)` returns a `TaxonomyResolution` — `sourceSlug`, `canonicalSlug`, `displayName`, and `redirectTo` (the canonical slug to 308 to when the inbound slug differs; `null` otherwise).
+
+```ts snippet
+const { data: markets } = await board.companies.markets({ search: 'robotics' });
+const market = await board.companies.markets.resolve('cybersecurity');
+if (market.redirectTo) {
+  // 308 the market-scoped browse to the canonical slug
+}
+```
+
+Resolve first, then pass the resolved slug as `marketSlug` — don't guess slugs (unknown ones 404).
+
+## Profile: retrieve, jobs, similar
+
+`PublicCompany` (lists/search) carries: `id`, `name`, `slug`, `website`, `logoUrl`, `description`, `jobCount`, `publishedJobCount`, `links.public`. `PublicCompanyDetail` (retrieve only) adds `markets: CompanyMarketRef[]` (`name` + source `slug`; empty when none).
+
+```ts snippet
+const company = await board.companies.retrieve('acme'); // PublicCompanyDetail
+company.markets;                                        // detail-only
+
+const jobs = await board.companies.listJobs('acme', { limit: 10 });
+// JobCardListEnvelope — same PublicJobCard shape as jobs.list; cursor + limit only
+
+const rail = await board.companies.similar('acme', { limit: 6 }); // 1–20, default 6
+```
+
+`similar` uses the hosted ranking (most open roles first) and excludes the company itself.
+
+Anti-pattern: don't render `markets` from a list row — it only exists on the detail. Fetch `retrieve` for the profile page.
+
+## Company salaries
+
+`companies.salaries` is callable AND carries `.category`. The call is the company salary overview (`CompanySalary`): `overallSalary` (nullable), `bySeniority` rows vs the board baseline (`diffPercent`), `competitors`, `topLocations`, `byCategory`, board-wide baselines, and `currency`. `.category(companySlug, categorySlug, { locale })` is one job category at the company (`CompanyCategorySalary`).
+
+```ts snippet
+const overview = await board.companies.salaries('acme');
+overview.bySeniority[0]?.diffPercent; // vs the board baseline, or null
+
+const cat = await board.companies.salaries.category('acme', 'software-engineer', {
+  locale: 'de',
+});
+cat.categorySourceSlug;    // immutable English slug
+cat.categoryCanonicalSlug; // board-language slug — 308 to it when the inbound differs
+```
+
+Pass `{ locale }` for board-language category names; the company slug/name are never localized. The response returns BOTH `categorySourceSlug` and `categoryCanonicalSlug` — the consumer issues the 308 itself.
+
+## Verify
+
+- `companies.retrieve('<known-slug>')` returns `object: 'public_company'` with a `markets` array; the same company in `companies.list` has no `markets` key.
+- A slug from `companies.markets()` works as `marketSlug`; a made-up slug returns 404 (`isNotFound`).
+- Paginating with `nextCursor` terminates: `nextCursor` is `null` on the last page.
+- `companies.salaries.category(...)` with a non-canonical category slug returns a differing `categoryCanonicalSlug`, and your route 308s to it.

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

@@ -0,0 +1,89 @@
+---
+name: cavuno-board-filters
+description: The canonical listing-filter vocabulary and URL search-param parsing with @cavuno/board/filters — remote/employment/seniority/sort sets, localized seniority labels, and parseListingFilters for jobs-listing routes. Use when building listing pages, filter sidebars, sort dropdowns, or validating listing URL params.
+---
+
+# Filters: vocabulary + URL parsing
+
+`@cavuno/board/filters` is the one filter vocabulary every tenant frontend
+shares — the seniority set is golden-tested against the platform source, and
+URL parsing follows the hosted semantics (hand-typed URLs are messy; parsing
+never throws).
+
+## When to use
+
+- The jobs index and every programmatic listing page (category / skill /
+  location) — they all layer the same cross-cutting filters on any seed.
+- `validateSearch`-style route param validation (server-safe, SSR-ready).
+
+## When not to use
+
+- Turning values into card display text — `cavuno-board-format`.
+- Search QUERIES (`jobs.search` bodies) — this module is about the listing
+  URL contract, not the search POST body.
+
+## Parse listing URLs
+
+```ts snippet
+import { parseListingFilters, DEFAULT_SORT } from '@cavuno/board/filters';
+
+const filters = parseListingFilters(rawSearchParams);
+// { q?, remoteOption?, employmentType?, seniority?: Seniority[], sort? }
+
+const page = await board.jobs.list({
+  limit: 20,
+  seniority: filters.seniority,
+  remoteOption: filters.remoteOption ? [filters.remoteOption] : undefined,
+  employmentType: filters.employmentType ? [filters.employmentType] : undefined,
+});
+```
+
+Unknown values are dropped silently (public URLs, never throw). Seniority
+accepts repeated params or a comma-string and normalizes with the hosted
+rules: trim, lowercase, dedupe, keep order.
+
+## Render the filter UI from the vocabulary
+
+```ts snippet
+import {
+  REMOTE_OPTIONS,
+  EMPLOYMENT_TYPES,
+  SENIORITIES,
+  JOB_SORTS,
+  seniorityLabels,
+  sortLabels,
+} from '@cavuno/board/filters';
+
+const { language } = await board.context();
+const labels = seniorityLabels(language); // de: executive → "Führungskraft"
+const sorts = sortLabels(language);       // English defaults on every locale
+```
+
+Seniority renders as a MULTI-select (hosted parity). `EMPLOYMENT_TYPES`
+deliberately offers 5 of the 7 wire values (`volunteer`/`other` exist on
+jobs but are not filter options). `JOB_SORTS` deliberately excludes
+`oldest` (ADR-0048); `relevance` is the featured-ranked default.
+
+## Anti-patterns
+
+```ts no-check
+// NEVER hand-roll the vocab per page — one page offering 'oldest' or a
+// 6th employment type diverges from every other board frontend:
+const sorts = ['relevance', 'newest', 'oldest'];
+// NEVER trust raw search params into the SDK query:
+board.jobs.list({ seniority: rawSearch.seniority });
+```
+
+## Out of scope — do not invent exports
+
+No URL BUILDER (routes are app-owned — serialize with your router), no
+category/skill/location taxonomy lists (those come from the API:
+`board.taxonomy.*`, `jobs.list` filters), no saved-filter persistence.
+
+## Verify
+
+- [ ] `/jobs?seniority=Senior,%20lead&sort=oldest` renders the senior+lead
+      selection and the default sort — no crash, no leaked invalid value.
+- [ ] The seniority multi-select shows all 8 levels, labeled in the board
+      language.
+- [ ] The sort dropdown offers exactly relevance / newest / salary_high.

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

@@ -0,0 +1,104 @@
+---
+name: cavuno-board-format
+description: Display formatting for board frontends with @cavuno/board/format — salary ranges, seniority/employment/remote labels, location labels, dates, and the board-language salary lexicon. Use when rendering job cards, detail pages, or salary figures, and whenever a value like salaryMin/salaryTimeframe/seniority needs to become display text.
+---
+
+# Format: board-language display text
+
+`@cavuno/board/format` turns wire values into the exact display text the
+hosted board renders — golden-tested against the hosted formatters, so a
+tenant frontend cannot drift from the platform's rendering rules.
+
+## When to use
+
+- Rendering salary ranges, dates, locations, or enum labels anywhere.
+- Building salary-page metadata sentences (the lexicon frames).
+
+## When not to use
+
+- Filter vocabulary and URL parsing — `cavuno-board-filters`.
+- Money math. Never compute or convert amounts client-side; format what the
+  wire provides.
+
+## The board language is a required first argument
+
+Every label-producing helper takes the board language — read it once from
+context. There is no `en` default: a German-native board must never
+silently render English.
+
+```ts snippet
+import {
+  formatSalaryRange,
+  formatPublishedRelativeDate,
+  formatDate,
+  fieldLabel,
+} from '@cavuno/board/format';
+
+const { language } = await board.context();
+
+formatSalaryRange(language, job.salaryMin, job.salaryMax, job.salaryTimeframe, job.salaryCurrency);
+// en: "$90K – $120K Yearly" · de: "90.000 € – 120.000 € pro Jahr"
+formatPublishedRelativeDate(language, job.publishedAt); // "5d ago" — what job CARDS render
+formatDate(language, job.publishedAt); // "Jun 24, 2026" — blog metadata / detail facts (UTC-pinned)
+fieldLabel(language, job.seniority);   // de: 'executive' → "Führungskraft"
+```
+
+Job cards and the job-detail header show the RELATIVE form; the absolute
+medium date is for blog metadata and detail fact rows — matching hosted.
+
+Localization matches hosted exactly: seniority + timeframe words are
+localized (en+de lexicon, other locales fall back to English words with
+locale-correct number formatting); employment/remote labels are English on
+every board because hosted ships no other vocabulary yet.
+
+## Location labels
+
+Cards carry server-computed labels — use them via `cardLocationLabel`. Only
+the full `PublicJob` needs client-side derivation:
+
+```ts snippet
+import { cardLocationLabel, locationLabel, fullJobToCard } from '@cavuno/board/format';
+
+cardLocationLabel(language, card);   // "Remote · Europe" | "Berlin, Germany"
+locationLabel(language, job);        // full PublicJob (detail page)
+const card = fullJobToCard(language, job); // embed a saved job in a card list
+```
+
+## Salary lexicon (metadata sentences)
+
+`getSalaryLexicon(language)` exposes the words and the `<title>`/meta
+sentence frames the hosted salary pages use:
+
+```ts snippet
+import { getSalaryLexicon } from '@cavuno/board/format';
+
+const lexicon = getSalaryLexicon(language);
+lexicon.frames.entitySalariesTitle({ entity: 'JavaScript', range: '$70K – $90K' });
+// "JavaScript Salaries ($70K – $90K/yr)"
+lexicon.seniority.senior; // "Senior"
+```
+
+## Anti-patterns
+
+```ts no-check
+// NEVER hand-format money — symbol placement and words are locale rules:
+`$${(job.salaryMin / 1000).toFixed(0)}k`;          // wrong on de boards
+// NEVER default the locale:
+formatSalaryRange('en', ...);                      // hardcoded 'en' on a de board
+// NEVER rebuild card location labels from scratch — the wire pre-computes them.
+```
+
+## Out of scope — do not invent exports
+
+No currency conversion, no relative-time ("3 days ago") helper, no
+number-only formatter — the SDK formats exactly what the hosted board
+formats. Sort-dropdown copy lives in `cavuno-board-filters`.
+
+## Verify
+
+- [ ] A de board renders "pro Jahr"/"ab"/"Führungskraft" where an en board
+      renders "Yearly"/"From"/"Executive" — same code path, different
+      `language`.
+- [ ] An en board's salary strings are byte-identical to the hosted board's
+      for the same job.
+- [ ] No call site passes a hardcoded locale string.

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

@@ -0,0 +1,115 @@
+---
+name: cavuno-board-job-alerts
+description: Build job-alert flows with the @cavuno/board SDK — the anonymous double-opt-in surface (jobAlerts.subscribe/confirm/resendConfirmation + HMAC-token manage/unsubscribe/resubscribe/updatePreference/deletePreference) and the authenticated board.me.alerts CRUD. Covers which surface to use when, how the manage token rides, which filters actually scope delivery, and the full-replace update trap.
+---
+
+# Job alerts: two surfaces
+
+Two distinct surfaces. **Anonymous** (`board.jobAlerts.*`): email capture with double opt-in; later edits authenticate with an HMAC manage token from the digest email. **Authenticated** (`board.me.alerts.*`): CRUD for a signed-in board user (bearer token), active immediately — the authenticated action is the consent. Both are gated on `board.context()` → `features.jobAlerts`.
+
+## When to use
+
+- Anonymous: the "email me new jobs" capture form for visitors, the confirm landing page, and the manage/unsubscribe page linked from digest emails.
+- Authenticated: an alerts section in the signed-in account area (up to 10 alerts per user).
+
+## When not to use
+
+- Board-user sign-in itself — see `cavuno-board-auth`.
+
+## Out of scope — do not invent exports
+
+Only the methods and fields shown here exist. There is no pause/suspend: deactivation is `unsubscribe` (anonymous) or `remove` (authenticated).
+
+## Anonymous: subscribe → confirm
+
+`subscribe` requires `consent: true` (server-enforced) and sends a confirmation email. `confirm` always returns HTTP 200 — branch on `status`.
+
+```ts snippet
+const sub = await board.jobAlerts.subscribe({
+  email: 'ada@example.com',
+  consent: true,
+  frequency: 'weekly', // 'daily' | 'weekly'
+  filters: { jobFunctions: ['engineering'], remoteOptions: ['remote'], placeSlugs: ['berlin'] },
+});
+sub.status;               // 'created' | 'duplicate'
+sub.requiresConfirmation; // true when the opt-in email was sent
+
+// Confirm page — token from the email link:
+const res = await board.jobAlerts.confirm({ token });
+res.status; // 'confirmed' | 'already_confirmed' | 'expired' | 'not_found'
+if (res.status === 'expired') {
+  await board.jobAlerts.resendConfirmation({ email }); // status: 'sent' | 'throttled' | ...
+}
+```
+
+Filter caveat: only `jobFunctions`, `placeSlugs`, and `remoteOptions` scope the digest server-side; `seniorityLevels`/`salaryMin`/`salaryMax`/`salaryCurrency` are stored but do not filter delivery.
+
+## Anonymous: the HMAC manage token
+
+Digest emails carry a per-subscription HMAC token. **`manage` is a GET — the token rides as query params `{ subscription, token }`. All writes are POST/DELETE — the token rides in the JSON body as `{ subscriptionId, token }`** (note the different key: `subscription` on the query, `subscriptionId` in bodies). Each preference in the manage state also carries its own `manageToken`.
+
+```ts snippet
+// Manage page, from the email link's query string:
+const state = await board.jobAlerts.manage({ subscription: subscriptionId, token });
+state.email; state.confirmed; state.unsubscribed;
+state.preferences; // [{ id, label, frequency, isActive, filters, manageToken }]
+
+await board.jobAlerts.unsubscribe({ subscriptionId, token });
+await board.jobAlerts.resubscribe({ subscriptionId, token });
+await board.jobAlerts.deletePreference({ subscriptionId, preferenceId, token });
+```
+
+`unsubscribe`/`resubscribe` also accept an optional `preferenceId` to scope to one preference. `updatePreference` is a **full replace** — `frequency` is required every time; restate the filters you aren't editing or they reset:
+
+```ts snippet
+const pref = state.preferences[0];
+await board.jobAlerts.updatePreference({
+  subscriptionId,
+  preferenceId: pref.id,
+  token,
+  frequency: 'daily',    // required — restate even if unchanged
+  filters: pref.filters, // round-trip stored filters you aren't editing
+});
+```
+
+## Authenticated: board.me.alerts
+
+Bearer-authenticated CRUD. Alerts are active on create (no opt-in email). The `AlertBody` uses `placeIds` (not `placeSlugs`), and `frequency` is required.
+
+```ts snippet
+const { data: alerts } = await board.me.alerts.list();
+alerts[0].isActive; alerts[0].lastSentAt; alerts[0].filters;
+
+const alert = await board.me.alerts.create({
+  frequency: 'weekly',
+  jobFunctions: ['engineering'],
+  remoteOptions: ['remote'],
+});
+
+await board.me.alerts.remove(alert.id); // 204 → void; the only way to stop an alert
+```
+
+`update` is a PUT with **full-replace semantics** — the body is the same `AlertBody` as create, so round-trip every field you aren't changing:
+
+```ts snippet
+const current = await board.me.alerts.retrieve(alertId);
+await board.me.alerts.update(alertId, {
+  frequency: 'daily', // the one edit
+  jobFunctions: current.filters.jobFunctions,
+  seniorityLevels: current.filters.seniorityLevels,
+  remoteOptions: current.filters.remoteOptions,
+  placeIds: current.filters.placeIds,
+  salaryMin: current.filters.salaryMin,
+  salaryMax: current.filters.salaryMax,
+  salaryCurrency: current.filters.salaryCurrency,
+});
+```
+
+## Verify
+
+- [ ] Subscribe form sends `consent: true` and handles `status: 'duplicate'` without erroring.
+- [ ] Confirm page branches on all four statuses (including `expired` → resend).
+- [ ] Manage page reads `subscription` + `token` from the email link's query string; writes send `subscriptionId` in the body.
+- [ ] Editing one preference field leaves the others intact (full-replace round-trip, both surfaces).
+- [ ] Alert UI only promises filtering on job function / place / remote option.
+- [ ] Alert surfaces are hidden when `features.jobAlerts` is false.