@cavuno/board 2.0.5 → 3.1.0

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

@@ -1,44 +1,25 @@
 ---
 name: cavuno-board-account
-description: Candidate account self-service with the @cavuno/board SDK — me.retrieve/delete, the candidate profile (merge-patch update, handle availability), experience/education CRUD, skills/languages full-replace, avatar upload, resume upload with async parse polling, and notification preferences plus the anonymous token unsubscribe. Use when building account, profile-edit, onboarding, or notification-settings pages for a signed-in board user.
+description: Candidate self-service boundary with @cavuno/board. Use for account, profile, resume onboarding, avatar, experience, education, skills, languages, or notification preferences.
 ---
 
-# Candidate account self-service
+# Candidate self-service boundary
 
-Everything the signed-in candidate manages about themselves lives under `board.me`. Every call here requires a board-user bearer token — in the browser the SDK reads it from `auth.storage` after login; on the server pass it per call via `options.headers` (see `cavuno-board-auth` for the httpOnly-cookie pattern). The one exception is the anonymous token unsubscribe at the end.
+Signed-in candidate data lives under `board.me`. Browser calls use the bearer token in `auth.storage`; server calls pass it per request in `options.headers`. See `cavuno-board-auth` for cookie-based server sessions.
 
-## When to use
+The only anonymous method here is token-based email unsubscribe. Applications, employer companies, messaging, and alerts have their own skills.
 
-- Account page: show the signed-in user, delete the account.
-- Profile editor: bio/headline/handle, experience, education, skills, languages, avatar.
-- Resume-driven onboarding (upload → parse → auto-populated profile).
-- Email notification settings + the unsubscribe link in emails.
+The host application owns forms, file pickers, and cookie plumbing; this SDK surface supplies data operations.
 
-## When not to use
+## Account and profile
 
-- Login/registration/tokens — `cavuno-board-auth`.
-- Applications and saved jobs — `cavuno-board-applications`.
-- The employer facet (`me.companies.*`), messaging (`me.conversations.*`), job alerts (`me.alerts.*`).
-
-Out of scope — do not invent exports: the SDK ships no form components, file-picker UI, or upload widgets; the host app owns all UI and cookie plumbing.
-
-## Account: retrieve and delete
+Account deletion is a synchronous, irreversible cascade over the profile, collections, saved jobs, alerts, avatar, and resume. Obtain explicit confirmation before calling it.
 
 ```ts snippet
-const me = await board.me.retrieve(); // the authenticated BoardUser
-await board.me.delete(); // 204 — synchronous, irreversible cascade
-```
-
-`delete` removes the account and all dependent data (profile, collections, saved jobs, alerts, avatar/resume files). Gate it behind an explicit confirmation.
-
-## Profile: retrieve, update, handle availability
+const me = await board.me.retrieve();
+await board.me.delete();
 
-The profile is a singleton. `update` is a merge-patch — omitted fields stay unchanged.
-
-```ts snippet
 const profile = await board.me.profile.retrieve();
-profile.handle; profile.headline; profile.jobSearchStatus;
-
 await board.me.profile.update({
   headline: 'Staff Engineer',
   jobSearchStatus: 'open_to_offers',
@@ -48,33 +29,40 @@ await board.me.profile.update({
 const { available } = await board.me.profile.handleAvailable('jane');
 ```
 
-`handleAvailable` is advisory (my current handle counts as available); `update` re-checks on write.
+Profile updates are merge-patches. Handle availability is advisory—your current handle counts as available—and the write re-checks uniqueness.
 
-## Experience and education: per-entry CRUD
+## Experience and education
 
-Both collections are id-keyed CRUD; updates are merge-patch. `createExperience` requires `title`, `companyName`, `startDate`; `createEducation` requires `institutionName`.
+Both collections are id-keyed CRUD with merge-patch updates. Experience creation requires `title`, `companyName`, and `startDate`; education creation requires `institutionName`.
 
 ```ts snippet
-const { data: entries } = await board.me.profile.listExperience();
-const entry = await board.me.profile.createExperience({
+const page = await board.me.profile.listExperience();
+const experience = await board.me.profile.createExperience({
   title: 'Staff Engineer',
   companyName: 'Acme',
   startDate: '2022-01',
 });
-await board.me.profile.updateExperience(entry.id, { endDate: '2025-06' });
-await board.me.profile.deleteExperience(entry.id);
-// Education mirrors this: listEducation / createEducation /
-// updateEducation(id, body) / deleteEducation(id).
+await board.me.profile.updateExperience(experience.id, {
+  endDate: '2025-06',
+});
+await board.me.profile.deleteExperience(experience.id);
+
+const education = await board.me.profile.createEducation({
+  institutionName: 'Example University',
+});
+await board.me.profile.listEducation();
+await board.me.profile.updateEducation(education.id, {});
+await board.me.profile.deleteEducation(education.id);
 ```
 
-## Skills and languages: PUT full-replace
+## Full-set fields
 
-`updateSkills` / `updateLanguages` replace the **whole set** — there is no add/remove-one endpoint. Sending only the new item wipes the rest. Round-trip the current list:
+`updateSkills` and `updateLanguages` replace the whole ordered set. Read-modify-write any value the user intends to retain.
 
 ```ts snippet
 const current = await board.me.profile.listSkills();
 await board.me.profile.updateSkills({
-  skills: [...current.data.map((s) => s.name), 'TypeScript'], // ordered names
+  skills: [...current.data.map((skill) => skill.name), 'TypeScript'],
 });
 
 await board.me.profile.updateLanguages({
@@ -82,53 +70,53 @@ await board.me.profile.updateLanguages({
 });
 ```
 
-Both return the full updated list envelope, so you can render straight from the response.
+Both updates return the complete updated list.
 
-## Avatar upload
+## Files
 
-Pass a `Blob`/`File` — the SDK builds the multipart `FormData` (field `file`). JPEG/PNG/WebP, ≤ 5 MB.
+The SDK builds multipart `FormData` with field `file` from a `Blob` or `File`. Avatar uploads accept JPEG, PNG, or WebP up to 5 MB.
 
 ```ts snippet
 const { avatarUrl } = await board.me.profile.uploadAvatar(file);
 ```
 
-## Resume: upload, then poll the parse
-
-`upload` starts an **async parse** that auto-populates the profile. It returns the resume with `parseStatus: 'parsing'` — poll `retrieve()` until `parsed` or `failed`, then re-read `profile.*` for the populated fields. Options: `keepResumeOnFile`, `importMode: 'append_only' | 'replace_all'`, `confirmReplaceAll`.
+Resume upload starts an asynchronous parse that may populate the profile. Poll within a fixed budget, surface failure, and keep manual editing available if parsing runs long.
 
 ```ts snippet
-let resume = await board.me.resume.upload(file, { keepResumeOnFile: true });
-// Bounded poll — a stuck parse job must not hang the UI forever.
-const MAX_POLLS = 30; // ~60s at 2s cadence
-for (let i = 0; resume.parseStatus === 'parsing' && i < MAX_POLLS; i++) {
-  await new Promise((r) => setTimeout(r, 2000));
+let resume = await board.me.resume.upload(file, {
+  keepResumeOnFile: true,
+});
+
+const maxPolls = 30;
+for (let poll = 0; resume.parseStatus === 'parsing' && poll < maxPolls; poll++) {
+  await new Promise((resolve) => setTimeout(resolve, 2000));
   resume = await board.me.resume.retrieve();
 }
+
 if (resume.parseStatus === 'parsed') {
-  const profile = await board.me.profile.retrieve(); // auto-populated
+  await board.me.profile.retrieve();
 } else if (resume.parseStatus === 'failed') {
-  resume.parseFailureReason; // surface it
+  showParseFailure(resume.parseFailureReason);
 } else {
-  // still 'parsing' after the window: show "taking longer than usual",
-  // keep the manual profile editor usable — never block on the parse.
+  showDelayedParseState();
 }
 ```
 
-`resume.file` holds the stored file (`url` is a short-lived signed download URL). `parseStatus` is `null` when no parse has run. `board.me.resume.delete()` removes the stored file and withdraws keep-on-file consent — parsed profile fields stay.
+Upload options also include `importMode: 'append_only' | 'replace_all'` and `confirmReplaceAll`. `resume.file.url` is a short-lived signed URL. `parseStatus` is null before any parse. `board.me.resume.delete()` removes the stored file and keep-on-file consent while retaining imported profile fields.
 
-## Notification preferences + anonymous unsubscribe
+## Notification preferences
 
-Two channels today: `messageEmails` and `applicationEmails`. `update` toggles one and returns the full updated set.
+Authenticated settings expose `messageEmails` and `applicationEmails`. Updating one channel returns the full set.
 
 ```ts snippet
-const { data: prefs } = await board.me.notificationPreferences.retrieve();
+const preferences = await board.me.notificationPreferences.retrieve();
 await board.me.notificationPreferences.update({
   channel: 'messageEmails',
   subscribed: false,
 });
 ```
 
-The one-click unsubscribe link in emails is **anonymous** — no session; the HMAC token is the authorization. All three fields come from the link's query string; resolves void (204):
+Email links use an anonymous HMAC token as authorization. Read all three inputs from the link query:
 
 ```ts snippet
 await board.me.notificationPreferences.unsubscribeWithToken({
@@ -138,10 +126,14 @@ await board.me.notificationPreferences.unsubscribeWithToken({
 });
 ```
 
-## Verify
+## Completion gate
+
+- Profile update is visible after retrieval.
+- 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.
+- Anonymous unsubscribe works in a logged-out browser.
+
+## Cavuno SDK reference
 
-- [ ] A profile `update` followed by `retrieve` shows the new field values.
-- [ ] Adding a skill preserves the existing ones (the full-replace round-trip is in place).
-- [ ] After `uploadAvatar`, the returned `avatarUrl` renders.
-- [ ] Resume upload reaches `parsed` (or surfaces `failed` + `parseFailureReason`), and the profile shows parsed data.
-- [ ] The email unsubscribe link works in a logged-out browser.
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).

package/skills/cavuno-board-api-client/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: cavuno-board-api-client
+description: Configure the @cavuno/board API client. Use when creating the shared client, adding global hooks or headers, passing framework fetch options, or calling an endpoint through the typed escape hatch.
+---
+
+# Configure the Board API client
+
+Create one client and keep its shared state board-scoped, not user-scoped.
+
+## Create the shared client
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+export const board = createBoardClient({
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+});
+```
+
+The `board` option accepts a `pk_…` key, `boards_…` ID, or slug. Prefer the immutable, publishable `pk_…` key for deployed frontends. The client defaults to `https://api.cavuno.com`; use `baseUrl` only for a Cavuno-supplied alternate origin.
+
+**Complete when:** the app imports one reused client and `board.context()` identifies the expected board.
+
+## Configure the request pipeline
+
+Every namespace uses the same pipeline: board base path, global headers, stored browser credentials, request/response hooks, and per-call options.
+
+```ts no-check
+const board = createBoardClient({
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+  globalHeaders: { 'Accept-Language': 'en' },
+  onRequest: async (request) => request,
+  onResponse: async (response, request) => {
+    console.info(request.url, response.status);
+  },
+  logger: console,
+});
+```
+
+Use `onRequest` to replace or adjust the request. Use `onResponse` for observation; it receives a response clone, so reading it leaves SDK parsing intact.
+
+**Complete when:** cross-cutting behavior is expressed once in client configuration and a request proves the hook or header is active.
+
+## Pass runtime state per call
+
+Every method accepts a trailing `FetchOptions`: `RequestInit` without `body`, plus `query`. Fetch-native and framework-specific fields pass through unchanged.
+
+```ts snippet
+await board.jobs.list(
+  { limit: 20 },
+  { next: { revalidate: 60, tags: ['jobs'] } });
+
+const controller = new AbortController();
+await board.jobs.list(
+  { limit: 20 },
+  { cache: 'force-cache', signal: controller.signal });
+```
+
+A module-scoped client is safe for concurrent SSR requests when it uses the server default `nostore` and each request supplies its own bearer or grant headers. `cavuno-board-server-sessions` is the authority for that session pattern. Browser persistence belongs to `cavuno-board-auth`.
+
+**Complete when:** a shared server client contains no per-user state and each authenticated request supplies its own headers.
+
+## Use the escape hatch for an untyped endpoint
+
+`board.client.fetch<T>(path, options)` keeps the full request pipeline while providing a response type locally.
+
+```ts snippet
+const data = await board.client.fetch<{
+  object: 'list';
+  data: unknown[];
+}>('/some-new-endpoint', { query: { limit: 5 } });
+```
+
+**Complete when:** the call uses a board-relative path, supplies an honest response type, and no parallel raw-fetch client was introduced.
+
+## 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-applications/SKILL.md

@@ -1,110 +1,100 @@
 ---
 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.
+description: Candidate application handoff with @cavuno/board. Use for native or guest apply, application tracking, resume attachment, withdrawal, and saved jobs.
 ---
 
-# Apply flow and application tracking
+# Candidate application handoff
 
-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.
+Treat applying as a handoff: submission belongs to `board.jobs`; the resulting candidate record belongs to `board.me`. The `me.*` side requires a board-user bearer token. See `cavuno-board-auth` for authentication.
 
-## When to use
+External jobs expose `applicationUrl`; link to it instead of creating a native application. Employer pipeline work belongs to `board.me.companies.applicants.*`.
 
-- 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.
+The host application owns apply forms and file-pickers; the SDK owns submission data operations.
 
-## When not to use
+## Submit
 
-- 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.
+`jobs.apply` is optional-auth and idempotent. A signed-in candidate supplies at most `coverNote`; a guest supplies `name` and `email`, when the board permits guest applications.
 
 ```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', {
+const guestApplication = await board.jobs.apply('senior-chef', {
   name: 'Ada Lovelace',
   email: 'ada@example.com',
 });
 ```
 
+Guest applications are claimed through the server-driven magic-link flow; the SDK has no guest-claim method.
+
 ## 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).
+Pass the `Blob` or `File`; the SDK builds multipart `FormData`. A signed-in candidate targets their own application. A guest must pass the id returned by `apply`.
 
 ```ts snippet
-// Signed-in:
 await board.jobs.uploadApplicationResume('senior-chef', file);
-// Guest:
 await board.jobs.uploadApplicationResume('senior-chef', file, {
-  applicationId: guestApp.id,
+  applicationId: guestApplication.id,
 });
 ```
 
-## "Have I applied?" — the apply-button state
+This step is complete when the returned application has `resumeFilename` set.
 
-`jobs.myApplication` returns the authenticated candidate's application for the job, and **throws a 404 `BoardApiError` when there is none** — branch with `isNotFound`:
+## Derive the apply-button state
+
+`jobs.myApplication` returns the signed-in candidate's application and throws a 404 when none exists. Derive the UI from that result rather than a local submitted flag.
 
 ```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
+  renderApplicationStatus(mine.status);
+} catch (error) {
+  if (!isNotFound(error)) throw error;
+  renderApplyForm();
 }
 ```
 
-## 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).
+`Application.status` is a polled candidate-facing projection of the employer stage: `'applied' | 'interviewing' | 'negotiation' | 'hired' | 'archived'`. Its `job` may be null after job removal.
 
-## Manage my applications
+## Track and manage applications
 
 ```ts snippet
-const { data, nextCursor } = await board.me.applications.list({ limit: 20 }); // newest first
-const app = await board.me.applications.retrieve(applicationId);
+const page = await board.me.applications.list({ limit: 20 }); // newest first
+const application = 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
+await board.me.applications.withdraw(applicationId);
 ```
 
-`updateFacts` accepts `candidateName`, `candidateEmail`, `candidateHeadline`, `candidateLocation`, `coverNote` (all optional). Withdraw is permanent deletion, not a status flip — confirm before calling.
+`updateFacts` merge-patches `candidateName`, `candidateEmail`, `candidateHeadline`, `candidateLocation`, and `coverNote`. `withdraw` permanently deletes the application, so obtain explicit confirmation first.
 
-## Saved jobs — the adjacent pattern
+## Save jobs
 
-Same authenticated `me.*` shape. Each saved row embeds the full `PublicJob`, so the saved-jobs page renders without extra fetches.
+Saved rows embed the full `PublicJob`. `save` converges on the existing row and `unsave` is idempotent.
 
 ```ts snippet
 const saved = await board.me.savedJobs.list({ limit: 20 });
-saved.data[0]?.job.title; // full PublicJob embedded
+saved.data[0]?.job.title;
 
-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
+await board.me.savedJobs.save({ jobId: job.id });
+await board.me.savedJobs.unsave(job.id);
 ```
 
-## Verify
+## Completion gate
+
+- Signed-in submission omits name and email; guest submission includes both.
+- Repeating `apply` returns the same application id.
+- Resume upload returns an application with `resumeFilename`.
+- `myApplication` plus `isNotFound` drives the apply-button state.
+- Re-fetching after withdrawal removes the application.
+- Repeating `unsave` leaves the saved list consistent.
+
+## Cavuno SDK reference
 
-- [ ] 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.
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).

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

@@ -1,24 +1,25 @@
 ---
 name: cavuno-board-auth
-description: Authenticate board users with the @cavuno/board SDK — register, login, refresh, logout, email verification and password reset. Covers bearer-JWT storage modes, the deliberate no-auto-refresh-on-401 rule (and single-flight handling), and the server-side httpOnly-cookie pattern that keeps tokens out of the browser.
+description: Authenticate Cavuno board users. Use for registration, login, logout, token refresh, email verification, password recovery, magic links, OAuth, or authenticated board-user calls.
 ---
 
-# Board-user authentication
+# Authenticate board users
 
-Board users (candidates, employers) authenticate with a short-lived bearer access token plus a refresh token. The SDK manages the pair via pluggable async storage. There is exactly one auth mode — bearer JWT (no cookie/session mode).
+Board users authenticate with a short-lived bearer access token and a single-use refresh token. The SDK persists returned token pairs through its configured async storage and leaves navigation to the app.
 
-## When to use
+## 1. Choose the storage boundary
 
-- Sign-up / sign-in / sign-out for board users.
-- Email verification and password reset flows.
-- Wiring authenticated calls (`me`, saved jobs, applications).
+`auth.storage` accepts `'memory'`, `'local'`, `'session'`, `'nostore'`, or a `CustomStorage` with async `getItem`, `setItem`, and `removeItem` methods.
 
-## When not to use
+- Browsers default to `'memory'`; choose `'local'` for persistence across tabs and reloads or `'session'` for tab-scoped persistence.
+- Servers default to `'nostore'`. Keep tokens in the app's httpOnly cookie and follow `cavuno-board-server-sessions` for every SSR session and refresh rule.
+- A custom store is appropriate when the app already owns a user-scoped persistence boundary.
 
-- Anonymous reads (jobs/companies/blog) — no auth needed.
-- Board-password gating — that's a separate grant; see `cavuno-board-errors`.
+`'local'` and `'session'` are browser runtimes; constructing them off-browser fails immediately.
 
-## Register and login
+**Complete when:** the selected store matches the runtime and a shared server client remains `nostore`.
+
+## 2. Establish the session
 
 ```ts snippet
 await board.auth.register({
@@ -33,81 +34,59 @@ const session = await board.auth.login({
   email: 'ada@example.com',
   password: 'a-strong-password',
 });
-session.boardUser.email; // the signed-in user
-session.accessToken;     // bearer; never expose to the browser bundle on SSR
 ```
 
-`register`/`login`/`refresh` persist the returned token pair to storage; `logout` clears it. The SDK never navigates — your app owns redirects and verification UX.
-
-## Storage modes
-
-`auth.storage` is `'memory'` | `'nostore'` | `'local'` | `'session'` | a `CustomStorage`. Defaults: **`memory` in the browser, `nostore` on the server**. Browser login works out of the box; shared SSR instances stay stateless.
+`register`, `login`, `consumeMagicLink`, `exchangeOAuth`, and `refresh` persist the returned session. Use the returned `boardUser` for identity and verification state.
 
-```ts
-import { createBoardClient } from '@cavuno/board';
-
-// Browser/SPA: 'local' persists the pair across tabs + reloads via
-// localStorage; 'session' scopes it to the tab; 'memory' drops it on reload.
-const board = createBoardClient({
-  board: 'pk_a8f3...',
-  auth: { storage: 'local' },
-});
-```
+For alternate entry points, use `requestMagicLink` / `consumeMagicLink` or the OAuth authorization and exchange methods exposed under `board.auth`.
 
-`'local'`/`'session'` are **browser-only** — off-browser they throw loudly at client creation (`storage mode 'local' is browser-only — use 'nostore' + per-call headers on the server`). A `CustomStorage` implements async `getItem`/`setItem`/`removeItem` — back it with IndexedDB, Redis, or your own store.
+**Complete when:** the chosen entry flow returns a session and `board.me.retrieve()` resolves as that board user.
 
-## No auto-refresh on 401 — handle it explicitly
+## 3. Handle expiry explicitly
 
-An expired access token surfaces as a `BoardApiError` you detect with `isUnauthorized`. The SDK does **not** silently refresh — refresh tokens are single-use with atomic rotation, so safe refresh under concurrency needs a single-flight guard you own.
+The SDK surfaces an expired access token as `BoardApiError`; it does not refresh and replay a failed request automatically. In a browser app, classify the failure with `isUnauthorized`, serialize refresh through one in-flight promise, then retry the original operation once with the rotated session.
 
 ```ts snippet
 import { isUnauthorized } from '@cavuno/board';
 
 try {
   return await board.me.retrieve();
-} catch (err) {
-  if (isUnauthorized(err)) {
-    await board.auth.refresh(); // reads the stored refresh token, rotates the pair
-    return await board.me.retrieve();
-  }
-  throw err;
+} catch (error) {
+  if (!isUnauthorized(error)) throw error;
+  await refreshOnce();
+  return board.me.retrieve();
 }
 ```
 
-Under concurrency, wrap `auth.refresh()` in a single-flight promise so parallel 401s trigger exactly one rotation (the reference flavor encodes this once — see `cavuno-board-tanstack-start`).
+On SSR, use the module-scoped `createSessionRefresher` pattern in `cavuno-board-server-sessions`; it is the single source of truth for concurrency, cookies, retry limits, and per-call authorization headers.
 
-## refresh / logout token sourcing
+**Complete when:** concurrent expiry paths share one rotation and the original operation is attempted at most once after a successful refresh.
 
-Both accept an optional body `{ refreshToken }`. When omitted, the SDK reads the token from storage and throws if neither exists — so `nostore` (server) callers must pass it explicitly:
+## 4. Refresh and logout from the right source
+
+`refresh()` and `logout()` read the refresh token from configured storage when their body is omitted. A `nostore` caller passes it explicitly:
 
 ```ts snippet
-await board.auth.refresh({ refreshToken });   // server: explicit
-await board.auth.logout({ refreshToken });    // revokes server-side, clears storage
+await board.auth.refresh({ refreshToken });
+await board.auth.logout({ refreshToken });
 ```
 
-## Server-side pattern (keep tokens out of the browser)
+Successful logout revokes the refresh token and clears SDK storage. A failed logout request retains stored tokens so the app can retry revocation or deliberately choose a local-only sign-out.
+
+**Complete when:** logout revokes the server session, clears the app-owned cookie or browser store, and an authenticated read is handled as signed out.
 
-On SSR, do not hold the session on a shared instance. Keep the token pair in an httpOnly cookie owned by your app and pass it per call. `@cavuno/board/server` ships the cookie codec + the single-flight refresh helper for exactly this (see `cavuno-board-server`):
+## Verification and recovery
 
 ```ts snippet
-// `accessToken` comes from your httpOnly cookie, read in server code.
-// Per-call options are the 2nd argument; the 1st is `query` (pass undefined).
-const me = await board.me.retrieve(undefined, {
-  headers: { authorization: `Bearer ${accessToken}` },
-});
+await board.auth.verifyEmail({ token });
+await board.auth.forgotPassword({ email: 'ada@example.com' });
+await board.auth.resetPassword({ token, password: 'a-new-password' });
 ```
 
-## Email verification & password reset
+The signed-in OTP verification, resend, magic-link, and OAuth branches use their corresponding `board.auth` methods. Password-reset requests preserve account privacy; a successful single-use reset invalidates existing sessions.
 
-```ts snippet
-await board.auth.verifyEmail({ token });             // token from the email link
-await board.auth.forgotPassword({ email });          // sends the reset email
-await board.auth.resetPassword({ token, password }); // token from the email link
-```
+**Complete when:** each implemented auth route exercises its success state and typed failure state, with bearer tokens absent from server-rendered browser payloads.
 
-## Checklist
+## Cavuno SDK reference
 
-- [ ] Bearer tokens never reach the browser bundle on SSR (httpOnly cookie + per-call header).
-- [ ] 401s handled explicitly with `isUnauthorized` + `auth.refresh()`.
-- [ ] Concurrent refresh guarded by single-flight.
-- [ ] `nostore` callers pass `{ refreshToken }` to `refresh`/`logout`.
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).