@cavuno/board 1.25.0 → 1.27.0

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.

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

@@ -0,0 +1,130 @@
+---
+name: cavuno-board-job-posting
+description: Build the anonymous "Post a job" funnel with the @cavuno/board SDK — jobPosting.plans, create and its status-discriminated JobPostingResult (checkout / published / pending_approval / invoice_sent), logo upload + fetchLogoByDomain, and the email-verified billing helpers (checkBilling, sendBillingVerification, getBillingOptions, checkSubscriptionEntitlements).
+---
+
+# Job posting: the anonymous submission funnel
+
+The no-account "Post a job" wizard (ADR-0042): pick a plan, upload a logo, submit — then branch on the status-discriminated result. Anonymous by design (no board-user token) and rate-limited server-side.
+
+Out of scope — do not invent exports: the `checkout` branch returns a Stripe Checkout **URL** — the full-page redirect is host-app-owned, and the webhook publishes the job after payment. The SDK ships no Stripe code and no publish/confirm method for the paid path.
+
+## When to use
+
+- The public `/post` wizard: plan picker, logo step, submission, and the post-submit screen.
+- Letting an existing plan/bundle holder submit against remaining capacity via email verification.
+
+## When not to use
+
+- Authenticated employer job management (drafts, edit, republish, ATS) — that is `board.me.companies.jobs.*`.
+- The candidate-access paywall — see `cavuno-board-paywall`.
+
+## Plans
+
+The chosen plan's `id` goes in `submission.selectedPlan`:
+
+```ts snippet
+const { data: plans } = await board.jobPosting.plans();
+for (const plan of plans) {
+  plan.id;            // → submission.selectedPlan
+  plan.prices;        // [{ currency, amountCents, isActive }]
+  plan.invoiceOnly;   // collect invoiceBilling instead of paying now
+  plan.isRecommended; // highlight in the picker
+  plan.features;      // [{ key, value }] rows for the plan card
+}
+```
+
+## Logo
+
+Upload a file, or fetch by company domain (Brandfetch). Both return a stored `publicUrl` you pass back as `logoUrl` on `create(...)`:
+
+```ts snippet
+const logo = await board.jobPosting.uploadLogo(file); // JPEG/PNG/WebP/GIF, ≤2 MB
+// or:
+const fetched = await board.jobPosting.fetchLogoByDomain('acme.com');
+// a BoardApiError code 'job_posting_logo_not_found' = no usable logo — continue without one
+```
+
+## Submit and branch on the result
+
+`create` returns a `JobPostingResult` — a discriminated union on `.status` with exactly four variants. The host app **must** branch on it; a rejected submission throws a `BoardApiError` instead.
+
+```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: logo.publicUrl,
+});
+
+switch (result.status) {
+  case 'checkout':         // paid plan → send the poster to Stripe
+    location.href = result.checkoutUrl; // webhook publishes on payment
+    break;
+  case 'published':        // live now
+    result.jobSlug;        // link straight to the job
+    break;
+  case 'pending_approval': // moderated board — live after review
+    result.jobId;
+    break;
+  case 'invoice_sent':     // invoice plan — a Stripe invoice was emailed
+    result.jobId;
+    break;
+}
+```
+
+The five billing paths map onto those four statuses: paid-Stripe → `checkout`; free and existing bundle/subscription credit publish without payment (`published`, or `pending_approval` on moderated boards); invoice plans → `invoice_sent`.
+
+## Existing credit: the verified-email branch
+
+A submitter whose email already holds a plan/bundle can post against remaining capacity — no new charge. Verify the email first; an option's fields become `selectedBilling`:
+
+```ts snippet
+const { hasActiveBilling } = await board.jobPosting.checkBilling({ email });
+if (hasActiveBilling) {
+  await board.jobPosting.sendBillingVerification({ email }); // emails a token
+  // …the poster pastes/clicks the token…
+  const { options } = await board.jobPosting.getBillingOptions({
+    verificationToken,
+  });
+  const option = options[0]!;
+  option.jobsRemaining;     // capacity left
+  option.featuredRemaining; // featured slots left
+  option.renewsAt;
+
+  await board.jobPosting.create({
+    submission, // as above — selectedPlan not needed on this path
+    selectedBilling: { type: option.type, id: option.id, planId: option.planId },
+  });
+}
+```
+
+For subscription holders, gate the "featured" toggle on entitlements:
+
+```ts snippet
+const ent = await board.jobPosting.checkSubscriptionEntitlements({
+  email,
+  planId: plan.id,
+});
+ent.hasSubscription;
+ent.canFeature;             // may the wizard offer isFeatured?
+ent.featuredSlotsRemaining; // and how many
+ent.maxActiveRemaining;
+```
+
+## Verify
+
+- [ ] Every `create` call site handles all four `result.status` variants — no fallthrough that assumes `published`.
+- [ ] A paid-plan submission lands on Stripe via `result.checkoutUrl`, and the job appears on the board only after payment (webhook), not on redirect.
+- [ ] A free-plan submission on an unmoderated board returns `published` with a `jobSlug` that resolves.
+- [ ] `fetchLogoByDomain` on a bogus domain surfaces the not-found error path, and the wizard still submits without a logo.

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

@@ -85,6 +85,21 @@ if (page.gatedCount && page.gatedCount > 0) {
 
 A board-user bearer token on the same call returns the entitled (ungated) view — the endpoint is optional-auth, one URL for both anonymous and personalized reads.
 
+## Full-catalog walks: paginate()
+
+For sitemaps, feeds, or exports, never hand-roll the cursor loop — `paginate()` iterates items (or raw pages via `.pages()`) until `hasMore` is false, and drops `offset` after the first page (offset would win over the cursor and re-serve the same page forever):
+
+```ts snippet
+import { paginate } from '@cavuno/board';
+
+for await (const card of paginate(board.jobs.list, { limit: 100 })) {
+  urls.push(card.links.public);
+}
+const first500 = await paginate(board.jobs.list).toArray({ limit: 500 });
+```
+
+Iteration order is stable only under an explicit sort/search — a churning board reorders default browse results between pages.
+
 ## Checklist
 
 - [ ] Listing/search use `PublicJobCard`; detail uses `PublicJob`.

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

@@ -0,0 +1,121 @@
+---
+name: cavuno-board-messaging
+description: Build the board-user messaging inbox with the @cavuno/board SDK — me.conversations (list, unreadCount, retrieve, listMessages, start, reply, markRead, archive), me.messages (edit, unsend, report), me.blocks. Covers the polled-REST contract (no realtime transport in v1), visibility-aware polling, the unread badge, and read receipts.
+---
+
+# Messaging: the polled inbox
+
+Employer↔candidate direct messaging for signed-in board users. The v1 transport is **polled REST by design (ADR-0053)** — there is no realtime primitive; near-live UX comes from re-fetching on an interval (3–5s is the reference cadence).
+
+Out of scope — do not invent exports: no websockets, no SSE, no `subscribe`/`onMessage` — polling `list` / `listMessages` / `unreadCount` IS the contract.
+
+## When to use
+
+- The inbox page, unread badge, thread view, and composer.
+- Edit/unsend, report-a-message, and block flows.
+
+## When not to use
+
+- Anonymous visitors — every method here requires a signed-in board user (see `cavuno-board-auth`).
+- Job applications themselves — messaging an applicant *starts from* an application, but the application surface is `board.me.applications.*`.
+
+## Poll while visible
+
+Poll only while the tab is visible — stop on hide, resume (with an immediate refresh) on show:
+
+```ts snippet
+const POLL_MS = 4000; // 3–5s reference cadence
+
+async function refresh() {
+  const [{ count }, inbox] = await Promise.all([
+    board.me.conversations.unreadCount(), // distinct unread threads → badge
+    board.me.conversations.list({ limit: 20 }),
+  ]);
+  render(count, inbox.data);
+}
+
+let timer: ReturnType<typeof setInterval> | undefined;
+function start() {
+  void refresh();
+  timer ??= setInterval(refresh, POLL_MS);
+}
+function stop() {
+  clearInterval(timer);
+  timer = undefined;
+}
+document.addEventListener('visibilitychange', () => {
+  document.visibilityState === 'visible' ? start() : stop();
+});
+start();
+```
+
+Each inbox row is a `Conversation`: `lastMessageAt`, `lastMessageSnippet`, `hasUnread`, and a live-resolved `counterparty` (`displayName`, `avatarUrl`, `companyName`, `handle`). `list({ archived: true })` is the archived view; `archive`/`unarchive` move a thread per-side and are idempotent.
+
+## The thread: header, messages, read receipts
+
+The header and the messages are separate calls. Messages come oldest-first; unsent messages are tombstones (empty `body`, `deletedAt` set) — render a placeholder, don't filter them out.
+
+```ts snippet
+const convo = await board.me.conversations.retrieve(conversationId);
+convo.viewerRole;              // 'employer' | 'candidate'
+convo.viewerLastReadMessageId; // my last-read pointer (null = never)
+
+const { data: messages } = await board.me.conversations.listMessages(
+  conversationId,
+  { limit: 50 },
+);
+for (const m of messages) {
+  m.body;     // '' when unsent (tombstone)
+  m.readAt;   // read receipt — when the recipient read it, or null
+  m.editedAt; // non-null after an edit
+}
+
+await board.me.conversations.markRead(conversationId); // idempotent
+```
+
+Call `markRead` when the viewer opens the thread — it clears `hasUnread` and drives the counterparty's `readAt` receipts.
+
+## Sending
+
+`start` cold-initiates a candidate (employer-only) and converges on the existing thread; `startAboutApplication` messages an applicant in application context; `reply` continues a thread. Each returns the created `Message`.
+
+```ts snippet
+// Route to an existing thread instead of opening a composer:
+const { conversationId } = await board.me.conversations.findExisting({
+  candidateBoardUserId,
+});
+
+const first = await board.me.conversations.start({
+  candidateBoardUserId,
+  body: 'Hi — your profile looks like a great fit.',
+});
+await board.me.conversations.reply(first.conversationId, {
+  body: 'Following up!',
+});
+```
+
+Sends are gated server-side (messaging enabled, cold-message rule, per-pair daily limits, blocks) — failures arrive as `messaging_*` `BoardApiError` codes; branch with the guards from `cavuno-board-errors`.
+
+## Edit, unsend, report, block
+
+Your own messages can be edited or unsent within a 15-minute window. Reporting a message addressed to you auto-blocks its author.
+
+```ts snippet
+await board.me.messages.edit(messageId, { body: 'fixed typo' });
+await board.me.messages.unsend(messageId); // tombstones; idempotent
+
+const { blocked } = await board.me.messages.report(messageId, {
+  reason: 'spam', // 'spam' | 'harassment' | 'misrepresentation' | 'other'
+});
+
+await board.me.blocks.create({ boardUserId }); // silent; idempotent
+```
+
+`board.me.blocks.list()` / `.remove(boardUserId)` / `.status(boardUserId)` round out blocking.
+
+## Verify
+
+- [ ] Kill the network tab timer: polling stops when the tab is hidden, resumes on focus with a fresh read.
+- [ ] Send from a second account: the badge (`unreadCount().count`) and `hasUnread` flip within one poll interval.
+- [ ] Open the thread: `markRead` fires once and the sender sees `readAt` populate on their next poll.
+- [ ] Unsend a message: it renders as a tombstone (empty `body`), not a gap.