@cavuno/board 2.0.5 → 3.1.0

package/skills/cavuno-board-seo/LISTING.md

@@ -0,0 +1,36 @@
+# Listing metadata and JSON-LD
+
+Read this reference for a job-listing page's head descriptors and structural
+JSON-LD. These builders are locale-neutral pass-throughs; supply the page's
+resolved heading copy.
+
+```ts snippet
+import { listingHead, listingJsonLd } from '@cavuno/board/seo';
+
+const { name } = await board.context();
+const head = listingHead({
+  boardName: name,
+  origin: 'https://jobs.example.com',
+  path: '/jobs/robotics',
+  heading: 'Robotics jobs',
+  count: 42,
+});
+
+const objects = listingJsonLd({
+  origin: 'https://jobs.example.com',
+  breadcrumbs: [{ name: 'Home', path: '/' }, { name: 'Jobs' }],
+  jobs: cards.map((card) => ({
+    slug: card.slug,
+    company: card.company,
+  })),
+});
+```
+
+`head.meta` contains title, description, and Open Graph descriptors;
+`head.links` contains the canonical link. For the example, the count-aware
+title is `42 Robotics jobs | Acme Jobs`.
+
+This branch is complete when head descriptors reflect the resolved page
+heading and count, the canonical URL combines the intended origin and path,
+and `listingJsonLd` receives card slugs plus company objects from the listing
+response.

package/skills/cavuno-board-seo/SALARY.md

@@ -0,0 +1,61 @@
+# Salary rich results
+
+Read this reference for salary structured data, `ItemList`, FAQ, formatters, or
+seniority ordering.
+
+## Build a title page
+
+Display-producing helpers require the board language as their leading
+argument. The salary money formatters intentionally retain the hosted page's
+USD assumption; locale changes number formatting, not currency. The current
+FAQ uses templated English sentences until board-custom FAQ copy is exposed.
+
+```ts snippet
+import {
+  buildSalaryFaq,
+  faqJsonLd,
+  formatRange,
+  itemListJsonLd,
+  sortBySeniority,
+  titleSalaryJsonLd,
+} from '@cavuno/board/seo';
+
+const { language } = await board.context();
+const detail = await board.salaries.titles.retrieve('software-engineer');
+
+const occupation = titleSalaryJsonLd(language, detail);
+const faq = faqJsonLd(
+  buildSalaryFaq(language, detail.categoryName, detail.overallSalary));
+const range = detail.overallSalary
+  ? formatRange(
+      language,
+      detail.overallSalary.avgMin,
+      detail.overallSalary.avgMax)
+  : null;
+const ladder = sortBySeniority(detail.bySeniority);
+const index = itemListJsonLd([
+  {
+    name: detail.categoryName,
+    url: 'https://jobs.example.com/salaries/titles/software-engineer',
+  },
+]);
+```
+
+## Select other salary builders
+
+- `skillSalaryJsonLd(detail)` for a skill detail.
+- `locationSalaryJsonLd(detail)` for a city-level location detail.
+- `crossAxisSalaryJsonLd(locale, args)` for a title/skill and location pair.
+- `companySalaryJsonLd(locale, detail)` for a company overview.
+- `companyCategorySalaryJsonLd(locale, detail)` for a company-category page.
+- `formatUsd(locale, value)` for the hosted USD amount format.
+- `formatSeniority(locale, key)` and `SENIORITY_ORDER` for seniority display.
+
+The structured-data families are `Occupation`,
+`MonetaryAmountDistribution`, `ItemList`, and `FAQPage`. Feed them the SDK
+salary read model; preserve nullable aggregates and server-computed values.
+
+This branch is complete when every applicable schema object has the expected
+schema.org type, null aggregates produce no fabricated figure, the board
+language comes from context, and every displayed value traces to a response
+field.

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

@@ -1,178 +1,51 @@
 ---
 name: cavuno-board-seo
-description: Structured data + head builders for board frontends with @cavuno/board/seo — Google for Jobs JobPosting JSON-LD, breadcrumbs, blog Article/ProfilePage, salary-page Occupation/FAQ structured data, and listing <head> descriptors. Use when building a job-detail, listing, blog, or salary page and it needs JSON-LD or SEO meta tags, or whenever "structured data", "rich results", or "Google for Jobs" comes up.
+description: SEO builders with @cavuno/board/seo. Use for JobPosting or breadcrumb JSON-LD, blog schema, salary rich results, or job-listing head metadata.
 ---
 
-# SEO: structured data + head builders
+# SEO builders
 
-`@cavuno/board/seo` emits the exact structured data the hosted board emits —
-tested against the hosted builders, so a tenant frontend gets Google
-for Jobs, breadcrumb, blog, and salary rich results without reinventing (or
-drifting from) the platform's rules. Render every builder's output into a
-`<script type="application/ld+json">` tag; builders return `null` when there
-is nothing worth emitting — skip the tag then.
+`@cavuno/board/seo` returns the hosted board's structured data and
+framework-neutral listing-head descriptors.
 
-## When to use
+## Select the page branch
 
-- A job detail page needs Google for Jobs `JobPosting` JSON-LD.
-- Any page needs a `BreadcrumbList`.
-- Blog post / author pages need `Article` / `ProfilePage` JSON-LD.
-- Salary pages need `Occupation`/`MonetaryAmountDistribution`/`ItemList`/
-  `FAQPage` structured data or the templated salary FAQ.
-- A jobs-listing page needs its `<head>` (title with count, canonical, OG).
+Read the matching reference completely before implementing that page:
 
-## When not to use
+- Job detail or breadcrumbs: [`JOB_AND_BREADCRUMBS.md`](JOB_AND_BREADCRUMBS.md)
+- Blog post or author profile: [`BLOG.md`](BLOG.md)
+- Salary detail, index, comparison, or FAQ: [`SALARY.md`](SALARY.md)
+- Job-listing metadata or structural JSON-LD: [`LISTING.md`](LISTING.md)
 
-- Display text on the page itself — `cavuno-board-format`.
-- Sitemaps and robots.txt — the sitemap module/skill.
-- OG image generation and route maps — app-owned (see out of scope).
+For a page that combines branches, read every matching reference.
 
-## Job-posting JSON-LD (the detail page)
+Sitemaps and robots.txt use `cavuno-board-sitemap`. The host app owns OG-image
+generation and its route map. `listingHead` receives app-owned heading copy;
+the SDK does not reproduce the board's configured meta copy.
 
-`PublicJob` carries every field this needs — including the derived remote
-permit codes. Worldwide-remote jobs automatically enumerate all 249
-countries (Google requires a location signal next to TELECOMMUTE).
+## Apply the shared rendering contract
 
-```ts snippet
-import { createJobPostingJsonLd } from '@cavuno/board/seo';
+Builders with nullable return types use `null` when no useful object remains.
+Emit a `<script type="application/ld+json">` only for a non-null result.
+Helpers that produce display strings take `board.context().language` as their
+required leading argument; pass the context value as the locale.
 
-const { name, logoUrl } = await board.context();
-const job = await board.jobs.retrieve('senior-chef');
+## Completion gate
 
-const jsonLd = createJobPostingJsonLd({
-  job,
-  board: { name, logoUrl },
-  shareUrl: `https://jobs.example.com/companies/${job.company?.slug}/jobs/${job.slug}`,
-});
-// null when nothing renderable remains — omit the <script> tag then.
-```
+Finish only after every applicable branch check passes:
 
-## Breadcrumbs
+- Each emitted JSON-LD value is non-null and is serialized in an
+  `application/ld+json` script.
+- Job detail validates as `JobPosting` in Google's Rich Results test; a
+  worldwide-remote job contains all 249 country codes.
+- Breadcrumb schema appears only with at least two non-blank crumbs.
+- Blog post and author pages emit their matching `Article` and `ProfilePage`
+  objects with canonical absolute URLs.
+- Salary builders receive the board language wherever their signature
+  requires it, and rendered figures match the returned salary read model.
+- Listing head output supplies title, description, Open Graph descriptors,
+  and canonical link for the requested absolute origin and path.
 
-Hosted semantics: labels are trimmed, blank crumbs dropped, fewer than two
-crumbs → `null`, and the current page (no `href`) omits `item`. Pass
-absolute hrefs, or give `origin` and use paths:
+## Cavuno SDK reference
 
-```ts snippet
-import { createBreadcrumbJsonLd } from '@cavuno/board/seo';
-
-const trail = createBreadcrumbJsonLd(
-  [
-    { label: 'Home', href: '/' },
-    { label: 'Jobs', href: '/jobs' },
-    { label: job.title }, // current page — no href
-  ],
-  { origin: 'https://jobs.example.com' });
-```
-
-## Blog Article + author ProfilePage
-
-```ts snippet
-import {
-  createBlogArticleJsonLd,
-  createAuthorProfileJsonLd,
-} from '@cavuno/board/seo';
-
-const post = await board.blog.posts.retrieve('hello-world');
-const article = createBlogArticleJsonLd({
-  post,
-  boardName: name,
-  permalink: `https://jobs.example.com/blog/${post.slug}`,
-  ogImageUrl: `https://jobs.example.com/blog/${post.slug}/og`, // fallback when no cover
-});
-
-const author = await board.blog.authors.retrieve('jane');
-const { data: authorPosts } = await board.blog.posts.list({ authorSlug: 'jane' });
-const profile = createAuthorProfileJsonLd({
-  author,
-  canonical: `https://jobs.example.com/blog/author/${author.slug}`,
-  description: author.bio ?? `Posts by ${author.name}`,
-  origin: 'https://jobs.example.com',
-  posts: authorPosts, // newest first; the builder keeps 5 as hasPart
-  totalPosts: authorPosts.length,
-});
-```
-
-## Salary-page structured data + FAQ
-
-The board language is a REQUIRED leading parameter wherever display strings
-are produced (no `en` default). The money formatters are USD-hardcoded —
-the hosted salary-page quirk, kept deliberately; the locale drives number
-formatting only. The FAQ ships TEMPLATED English sentences (board-custom
-FAQ copy is a not currently available and will supersede it).
-
-```ts snippet
-import {
-  titleSalaryJsonLd,
-  buildSalaryFaq,
-  faqJsonLd,
-  itemListJsonLd,
-  formatRange,
-  sortBySeniority,
-} from '@cavuno/board/seo';
-
-const { language } = await board.context();
-const detail = await board.salaries.titles.retrieve('software-engineer');
-
-const occupation = titleSalaryJsonLd(language, detail);
-const faq = faqJsonLd(
-  buildSalaryFaq(language, detail.categoryName, detail.overallSalary));
-// Index pages: itemListJsonLd(items); on-page figures: formatRange(language, min, max)
-// and sortBySeniority(detail.bySeniority) for the ladder table.
-```
-
-Also available: `skillSalaryJsonLd(detail)`, `locationSalaryJsonLd(detail)`
-(city-level pages only), `crossAxisSalaryJsonLd(locale, args)`,
-`companySalaryJsonLd(locale, detail)`,
-`companyCategorySalaryJsonLd(locale, detail)`, `formatUsd(locale, value)`,
-`formatSeniority(locale, key)`, `SENIORITY_ORDER`.
-
-## Listing pages: head + structural JSON-LD
-
-Locale-neutral pass-through — you supply the heading copy:
-
-```ts snippet
-import { listingHead, listingJsonLd } from '@cavuno/board/seo';
-
-const head = listingHead({
-  boardName: name,
-  origin: 'https://jobs.example.com',
-  path: '/jobs/robotics',
-  heading: 'Robotics jobs',
-  count: 42, // → "42 Robotics jobs | Acme Jobs"
-});
-// head.meta → title/description/OG descriptors; head.links → canonical.
-
-const objects = listingJsonLd({
-  origin: 'https://jobs.example.com',
-  breadcrumbs: [{ name: 'Home', path: '/' }, { name: 'Jobs' }],
-  jobs: cards.map((c) => ({ slug: c.slug, company: c.company })),
-});
-```
-
-## Anti-patterns
-
-```ts no-check
-// NEVER hand-roll JobPosting JSON-LD — the pruning, salary mirroring, and
-// worldwide country enumeration are Google-spec rules the SDK encodes:
-const ld = { '@type': 'JobPosting', salary: job.salaryMin }; // wrong shape
-// NEVER default the locale on salary builders:
-titleSalaryJsonLd('en', detail); // hardcoded 'en' on a de board
-// NEVER emit a JSON-LD script for a null builder result.
-```
-
-## Out of scope — do not invent exports
-
-OG **image generation** (the `/og` card renderer), the legal/route **map**,
-and the meta title/description **copy** (board SEO config + localized copy
-is not replicated — `listingHead` takes your strings) are app-owned. No
-sitemap builders here — that is `@cavuno/board/sitemap`'s job.
-
-## Verify
-
-- [ ] The job detail page's JSON-LD validates in Google's Rich Results test
-      as a JobPosting, and a worldwide-remote job lists 249 countries.
-- [ ] Pages with a null builder result render NO empty ld+json script.
-- [ ] A de board passes `language` from `board.context()` — the salary
-      FAQ figures render de-formatted, and no call site hardcodes 'en'.
-- [ ] Breadcrumb JSON-LD only appears on pages with 2+ crumbs.
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).

package/skills/cavuno-board-server-sessions/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: cavuno-board-server-sessions
+description: Wire Cavuno server sessions and board-password access. Use when a server-rendered app needs httpOnly cookies, per-request bearer headers, single-flight refresh, grant cookies, or safe redirect-back handling.
+---
+
+# Wire server sessions
+
+`@cavuno/board/server` provides platform-neutral cookie strings and refresh coordination. The framework skills installed in the app provide request, middleware, and response APIs.
+
+The server contract has three invariants:
+
+1. One module-scoped board client uses server-default `nostore`.
+2. Each request reads an app-owned httpOnly cookie and passes credentials in that call's headers.
+3. One module-scoped `createSessionRefresher(board)` coordinates refreshes within the process or isolate.
+
+## 1. Persist the board-user session
+
+`BoardSession` contains `{ accessToken, refreshToken, expiresAt }`. The codec uses one `__Host-` cookie with `Path=/`, `HttpOnly`, `Secure`, `SameSite=Lax`, and a 30-day `Max-Age`. The framework owns header I/O and CSRF controls; wrap the codec when the app requires cookie encryption.
+
+```ts snippet
+import {
+  clearSessionCookie,
+  parseSessionCookie,
+  serializeSessionCookie,
+} from '@cavuno/board/server';
+
+const signedIn = await board.auth.login({ email, password });
+const setCookie = serializeSessionCookie({
+  accessToken: signedIn.accessToken,
+  refreshToken: signedIn.refreshToken,
+  expiresAt: signedIn.expiresAt,
+});
+
+const session = parseSessionCookie(request.headers.get('cookie'));
+const clearedCookie = clearSessionCookie();
+```
+
+`parseSessionCookie` returns `null` for absent, malformed, or wrong-shaped values. Treat that state as signed out. On logout, call `board.auth.logout({ refreshToken })`, then emit `clearSessionCookie()` after successful revocation.
+
+**Complete when:** login emits the serialized cookie, the next server request restores the same session, malformed input becomes signed out, and logout expires the cookie.
+
+## 2. Resolve one fresh session per request
+
+Refresh tokens rotate once. Create the refresher beside the shared client so concurrent requests using the same refresh token await one rotation. `isExpiringSoon` selects sessions within the proactive five-minute window.
+
+```ts snippet
+import {
+  clearSessionCookie,
+  createSessionRefresher,
+  isExpiringSoon,
+  parseSessionCookie,
+  serializeSessionCookie,
+} from '@cavuno/board/server';
+
+const refreshSession = createSessionRefresher(board);
+
+async function resolveSession(cookieHeader: string | null) {
+  const session = parseSessionCookie(cookieHeader);
+  if (!session) return { session: null, setCookie: null };
+  if (!isExpiringSoon(session, Date.now())) {
+    return { session, setCookie: null };
+  }
+
+  const rotated = await refreshSession(session);
+  return rotated
+    ? { session: rotated, setCookie: serializeSessionCookie(rotated) }
+    : { session: null, setCookie: clearSessionCookie() };
+}
+```
+
+A rotated session is written back before the response completes. A `null` result represents a 401 from a burned or revoked token: clear the cookie and continue signed out. Network, 5xx, and 429 failures rethrow to the app's error boundary. The helper deduplicates within one process or isolate; separate deployment instances can still race.
+
+**Complete when:** two simultaneous resolutions for one expiring session invoke one rotation in the process, both observe the same result, success writes the rotated pair, and `null` produces one clear-cookie response with no refresh retry.
+
+## 3. Authenticate each SDK call
+
+Pass the resolved access token in the call's trailing `FetchOptions`:
+
+```ts snippet
+const me = await board.me.retrieve(undefined, {
+  headers: { authorization: `Bearer ${session.accessToken}` },
+});
+```
+
+This keeps the shared client's storage empty across users.
+
+**Complete when:** concurrent requests can present different tokens without mutating the shared client.
+
+## 4. Persist board-password access
+
+The board-password grant has its own 24-hour `__Host-` cookie. It remains separate from the board-user session.
+
+```ts snippet
+import {
+  clearGrantCookie,
+  parseGrantCookie,
+  serializeGrantCookie,
+} from '@cavuno/board/server';
+
+const { token } = await board.password.verify(password);
+const setGrantCookie = serializeGrantCookie(token);
+
+const grant = parseGrantCookie(request.headers.get('cookie'));
+const jobs = await board.jobs.list(undefined, {
+  headers: grant ? { 'X-Board-Access': grant } : {},
+});
+
+const clearedGrantCookie = clearGrantCookie();
+```
+
+When a read returns `isBoardPasswordRequired`, clear the stale grant and route the visitor through the password challenge again.
+
+**Complete when:** verification writes the grant, a later request supplies `X-Board-Access`, and an expired or rotated grant is cleared before rechallenge.
+
+## 5. Guard redirect-back paths
+
+Every password challenge and post-login redirect consumes a same-origin absolute path through `safeRedirectPath`. `currentPathFromReferer` derives an already-guarded return path from a Referer header.
+
+```ts snippet
+import {
+  currentPathFromReferer,
+  safeRedirectPath,
+} from '@cavuno/board/server';
+
+const destination = safeRedirectPath(query.redirect);
+const returnTo = currentPathFromReferer(request.headers.get('referer'));
+```
+
+Values that could resolve off-origin collapse to `/` (or the explicit fallback passed as the second argument).
+
+**Complete when:** raw query values never reach the redirect API and tests cover a valid local path, a full URL, a protocol-relative URL, backslashes, and control-character normalization.
+
+## Multi-board origins
+
+When one origin serves multiple boards, pass the board identifier to every session and grant codec so cookies cannot collide:
+
+```ts snippet
+const scope = { board: 'pk_boardA' };
+const cookie = serializeSessionCookie(session, scope);
+const restored = parseSessionCookie(cookieHeader, scope);
+```
+
+Single-board origins omit the scope.
+
+## 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-setup/SKILL.md

@@ -1,57 +1,23 @@
 ---
 name: cavuno-board-setup
-description: End-to-end orchestrator for building a headless Cavuno job board with the @cavuno/board SDK. Start here after `npx @cavuno/board setup` copies the skills — detect the framework, wire the client, render board context, jobs browsing and detail, board-user auth and saved jobs, handle errors and access gating, then verify.
+description: Orchestrate a headless Cavuno board integration. Use when starting a frontend with @cavuno/board or adding Cavuno board surfaces to an existing app.
 ---
 
-# Setting up a Cavuno board
+# Set up a Cavuno board
 
-`@cavuno/board` is a thin, isomorphic, typed client for the Cavuno Board API (`/v1/boards/:identifier/*`). It brings the commerce of a job board — jobs, companies, blog, search, auth, saved jobs, alerts — to the framework you already use. You bring the framework and own the layout; the SDK brings the data contract.
+Build the board as a sequence of working slices. The framework owns rendering and routing; Cavuno skills own Board API behavior and data contracts.
 
-This skill is the orchestrator. Work top to bottom, delegating each surface to its focused skill.
+## 1. Map the host app
 
-## When to use
+Read `package.json`, the route tree, environment conventions, and existing data-fetching boundaries. Use the framework skills already installed in the project for framework APIs, including TanStack Start, Next.js, Remix, Nuxt, SvelteKit, Astro, and SolidStart.
 
-- Standing up a new headless board frontend against the Board API.
-- Adding board data (jobs/companies/blog/auth) to an existing app.
-- After `npx @cavuno/board setup` has installed the package and copied these skills.
+Choose where public reads run and identify the server boundary for bearer tokens. `@cavuno/board` runs in browsers, Node 20+, and Cloudflare Workers.
 
-## When not to use
+**Complete when:** the framework, route convention, rendering boundary, and server-only environment boundary are identified from the repository.
 
-- Authoring the hosted board inside the Cavuno admin (that's the operator Puck builder, not the SDK).
-- Building operator automation — use the public `cavuno` CLI or REST API;
-  `@cavuno/board` is for visitor-facing board experiences.
+## 2. Configure one client
 
-## Inspect the app
-
-Read `package.json` and the project layout before writing anything. Identify: the framework (see below), whether it renders on a server (SSR/RSC) or only in the browser, and where server-only secrets are read. Match the project's existing conventions — do not introduce a new data-fetching style.
-
-## Detect the framework
-
-`@cavuno/board` is framework-agnostic: it needs only `fetch` and runs in the browser, Node ≥ 20, and Cloudflare Workers. Detect the framework from dependencies and adapt:
-
-- `@tanstack/react-start` → the reference flavor. Read `cavuno-board-tanstack-start` for SSR-loader + cookie wiring.
-- `next` → use Server Components + per-call `FetchOptions` (`next: { revalidate, tags }`).
-- Anything else (Nuxt, SvelteKit, Astro, SolidStart, plain JS) → use the core skills directly; the SDK surface is identical.
-
-## Use the standard board environment name
-
-Read the board key from the environment; never hard-code it:
-
-- `PUBLIC_CAVUNO_BOARD` — the board identifier. Use the `pk_…` publishable key, not the slug (the slug is operator-mutable and breaks deployed frontends on rename).
-
-The `pk_…` key is public-safe by design. Use your framework's public-env convention for the variable name (`VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`). The SDK uses `https://api.cavuno.com` by default. Pass `baseUrl` only when Cavuno supplies a staging or development origin.
-
-## Keep credentials server-side
-
-The board identifier is public. A board-user **bearer JWT is not** — it must never reach the browser bundle. On a server framework, keep the session in an httpOnly cookie owned by your app and pass it per call; see `cavuno-board-auth`.
-
-## Use board route conventions
-
-The canonical public job-detail URL is `/companies/:companySlug/jobs/:jobSlug` — a job needs both slugs. `/jobs`, `/jobs/:keyword`, `/jobs/locations/:slug` are listing/search pages, never individual jobs. Mirror these paths so a board migrating hosted → headless keeps its indexed URLs.
-
-## Wire the client
-
-Create one client and reuse it. See `cavuno-board-client`.
+Read the board identifier from the host framework's public environment convention. Prefer the immutable, publishable `pk_…` key; it is safe to expose. The default API origin is `https://api.cavuno.com`; set `baseUrl` only for a Cavuno-supplied alternate origin.
 
 ```ts
 import { createBoardClient } from '@cavuno/board';
@@ -61,59 +27,60 @@ export const board = createBoardClient({
 });
 ```
 
-## Build the board shell from context
+Use `cavuno-board-api-client` for hooks, headers, caching, and SSR state boundaries.
+
+**Complete when:** one reused client resolves `board.context()` with the expected board name.
 
-`board.context()` (a root method on the client) returns identity, theme, analytics, and the board's capability `features` flags. Render branding from it and **gate every optional surface on its capability flag** — only build a route when its feature is enabled. (A dedicated context skill ships with a later slice; the return type is self-describing until then.)
+## 3. Build a vertical jobs slice
 
-## Build jobs browsing + detail
+Render the shell from `board.context()`, including board identity and branding. Treat its `features` as capabilities: expose each optional surface only when its capability is enabled.
 
-The core surface. `jobs.list` / `jobs.search` for listing pages, `jobs.retrieve` for the detail page, `jobs.similar` for the related rail. Honor catalog pagination and the candidate-paywall `gatedCount`; use `paginate()` for full-catalog walks (sitemaps, feeds). See `cavuno-board-jobs`.
+Then build the jobs list and detail routes with `cavuno-board-jobs`. Preserve the hosted board's indexed route contract:
 
-## Add board users + saved jobs
+- `/jobs`, `/jobs/:keyword`, and `/jobs/locations/:slug` are listings.
+- `/companies/:companySlug/jobs/:jobSlug` is a job detail.
 
-Register/login/refresh/logout, then `me.retrieve` and `me.savedJobs.*`. There is **no auto-refresh on 401** — handle it explicitly. See `cavuno-board-auth`.
+Use `cavuno-board-format`, `cavuno-board-filters`, and `cavuno-board-search-suggestions` for their respective display, URL-filter, and search-suggestion contracts.
 
-## Handle errors + gating
+**Complete when:** a real job card links to a working canonical detail page, and a fabricated slug renders the app's handled not-found state.
 
-Every method throws `BoardApiError` on a non-2xx; branch with the typed guards. Password-protected boards need a `password.verify()` grant. See `cavuno-board-errors`.
+## 4. Add identity and access
 
-## Style, format, and filter with the helper subpaths
+Use `cavuno-board-auth` for board-user registration, login, verification, recovery, and browser storage. In a server-rendered app, use `cavuno-board-server-sessions` as the authority for the httpOnly session cookie, per-call bearer header, and `createSessionRefresher`. Use `cavuno-board-errors` for typed failure branches and board-password grants.
 
-Three subpath modules carry the display layer — use them instead of
-hand-rolling (each has a skill):
+**Complete when:** an authenticated `board.me.retrieve()` succeeds, logout returns the app to a signed-out state, and concurrent server requests share the server skill's single-flight refresher.
 
-- Salary/date/label formatting in the board language → `cavuno-board-format`
-- Listing-filter vocabulary + URL param parsing → `cavuno-board-filters`
-- Optional hosted-board theme compatibility → `cavuno-board-theme`. By default, the consuming application owns tokens, fonts, and color mode.
+## 5. Add only the enabled surfaces
 
-## Build the remaining surfaces per feature flag
+Route each enabled capability to its focused skill:
 
-One focused skill per surface — delegate by name, and build a surface only
-when its `features` flag (from `board.context()`) is enabled:
+| Surface | Skill |
+| --- | --- |
+| Companies and markets | `cavuno-board-companies` |
+| Blog | `cavuno-board-blog` |
+| Salary pages | `cavuno-board-salaries` |
+| Job alerts | `cavuno-board-job-alerts` |
+| Candidate account | `cavuno-board-account` |
+| Saved jobs and applications | `cavuno-board-applications` |
+| Messaging | `cavuno-board-messaging` |
+| Candidate paywall | `cavuno-board-paywall` |
+| Public job posting | `cavuno-board-post-a-job` |
+| Localized chrome | `cavuno-board-i18n` |
+| Metadata and structured data | `cavuno-board-seo` |
+| Sitemap routes | `cavuno-board-sitemap` |
 
-- Companies directory, markets, per-company jobs → `cavuno-board-companies`
-- Blog (posts, tags, authors, search) → `cavuno-board-blog`
-- Programmatic salary pages → `cavuno-board-salaries`
-- Job alerts (anonymous double-opt-in + account CRUD) → `cavuno-board-job-alerts`
-- Candidate account self-service (profile, resume, avatar, prefs) → `cavuno-board-account`
-- Apply flow + my applications + saved jobs → `cavuno-board-applications`
-- Candidate↔employer messaging (polled REST) → `cavuno-board-messaging`
-- Candidate job-access paywall (offers, checkout, grant) → `cavuno-board-paywall`
-- Public job-posting funnel (plans, submit, billing) → `cavuno-board-job-posting`
+The app remains the source of page composition, chrome copy, and marketing or legal prose. Cavuno supplies data and helpers for the artifacts its focused skills cover.
 
-## App-owned concerns (out of scope)
+**Complete when:** every implemented optional route maps to an enabled board capability and the relevant focused skill's verification passes.
 
-The SDK serves data only. Your app owns: page layout and chrome copy, marketing/legal prose, and the authoring of SEO artifacts (sitemap, RSS, OG images) — built from API data, not served as documents. The Board API never returns layouts or page-builder JSON.
+## 6. Prove the integration
 
-## Verification
+Run `cavuno-board-smoke-test` with the real `pk_…` value. Its runtime probes and production build are the completion gate for setup.
 
-- `board.context()` resolves and returns your board's name.
-- A listing page renders cards from `board.jobs.list()`.
-- A detail page renders from `board.jobs.retrieve(slug)`.
-- An invalid slug surfaces a handled `isNotFound(err)` path, not a crash.
+Pause with a concrete blocker when the board identifier or a required test credential is unavailable, or the public API probe fails before it reaches app code.
 
-Then run the `cavuno-board-smoke-test` skill against your `pk_…` — type checks are not enough for board wiring.
+**Complete when:** doctor, direct API probes, implemented-surface checks, and the production-build probe all pass or each skipped credentialed check is reported.
 
-## Stop conditions
+## Cavuno SDK reference
 
-Stop and ask the human when: no `pk_…` board identifier is available; the framework is unrecognized and has no server boundary for credentials; or a surface you need (e.g. job alerts, applications) has no corresponding skill yet — the SDK only exposes endpoints that are live, so a missing skill means the endpoint isn't shipped.
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).