@cavuno/board 1.2.1 → 1.4.0

package/dist/skills.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Skill-corpus loader. Node-only (reads the shipped `skills/` directory from
+ * the installed package) — kept out of the isomorphic core and exposed via the
+ * `@cavuno/board/skills` subpath export. Both `npx @cavuno/board setup` and the
+ * in-admin sidekick (ADR-0033) read the corpus through here, so the two doors
+ * stay fed from one source.
+ */
+interface SkillManifestEntry {
+    name: string;
+    description: string;
+    /** Path to the SKILL.md, relative to the package root. */
+    path: string;
+    /** Framework slug for flavor skills; `null` for framework-agnostic core skills. */
+    framework: string | null;
+    category: 'core' | 'flavor';
+}
+interface SkillManifest {
+    version: string;
+    skills: SkillManifestEntry[];
+}
+interface LoadedSkill extends SkillManifestEntry {
+    content: string;
+}
+interface SkillCorpus {
+    version: string;
+    skills: LoadedSkill[];
+}
+/** Resolve a package-root-relative path (e.g. a manifest `path`) to an absolute path. */
+declare function resolveFromPackageRoot(relativePath: string): string;
+declare function loadSkillManifest(): SkillManifest;
+/**
+ * Load the full skill corpus — manifest metadata plus each skill's markdown
+ * `content`. The sidekick injects `content` into its agent context; an external
+ * Claude Code instead receives the files copied by the setup command.
+ */
+declare function loadSkillCorpus(): SkillCorpus;
+
+export { type LoadedSkill, type SkillCorpus, type SkillManifest, type SkillManifestEntry, loadSkillCorpus, loadSkillManifest, resolveFromPackageRoot };

package/dist/skills.js

@@ -0,0 +1,62 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/skills.ts
+var skills_exports = {};
+__export(skills_exports, {
+  loadSkillCorpus: () => loadSkillCorpus,
+  loadSkillManifest: () => loadSkillManifest,
+  resolveFromPackageRoot: () => resolveFromPackageRoot
+});
+module.exports = __toCommonJS(skills_exports);
+
+// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.7.0_postcss@8.5.14_tsx@4.21.0_typescript@5.9.3_yaml@2.8.4/node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/skills.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_url = require("url");
+function packageRoot() {
+  return (0, import_node_path.resolve)((0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(importMetaUrl)), "..");
+}
+function resolveFromPackageRoot(relativePath) {
+  return (0, import_node_path.resolve)(packageRoot(), relativePath);
+}
+function loadSkillManifest() {
+  const manifestPath = resolveFromPackageRoot("skills/manifest.json");
+  return JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+}
+function loadSkillCorpus() {
+  const manifest = loadSkillManifest();
+  return {
+    version: manifest.version,
+    skills: manifest.skills.map((skill) => ({
+      ...skill,
+      content: (0, import_node_fs.readFileSync)(resolveFromPackageRoot(skill.path), "utf8")
+    }))
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loadSkillCorpus,
+  loadSkillManifest,
+  resolveFromPackageRoot
+});

package/dist/skills.mjs

@@ -0,0 +1,29 @@
+// src/skills.ts
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function resolveFromPackageRoot(relativePath) {
+  return resolve(packageRoot(), relativePath);
+}
+function loadSkillManifest() {
+  const manifestPath = resolveFromPackageRoot("skills/manifest.json");
+  return JSON.parse(readFileSync(manifestPath, "utf8"));
+}
+function loadSkillCorpus() {
+  const manifest = loadSkillManifest();
+  return {
+    version: manifest.version,
+    skills: manifest.skills.map((skill) => ({
+      ...skill,
+      content: readFileSync(resolveFromPackageRoot(skill.path), "utf8")
+    }))
+  };
+}
+export {
+  loadSkillCorpus,
+  loadSkillManifest,
+  resolveFromPackageRoot
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,9 @@
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "cavuno-board": "./dist/bin.mjs"
+  },
   "exports": {
     ".": {
       "import": {
@@ -25,10 +28,22 @@
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
       }
-    }
+    },
+    "./skills": {
+      "import": {
+        "types": "./dist/skills.d.mts",
+        "default": "./dist/skills.mjs"
+      },
+      "require": {
+        "types": "./dist/skills.d.ts",
+        "default": "./dist/skills.js"
+      }
+    },
+    "./skills/*": "./skills/*"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
@@ -36,15 +51,17 @@
   "scripts": {
     "build": "tsup",
     "clean": "git clean -xdf .turbo dist node_modules",
-    "typecheck": "tsgo --noEmit",
+    "typecheck": "tsgo --noEmit && tsgo --noEmit -p tsconfig.node.json",
     "test": "vitest run",
+    "gen:skills-manifest": "tsx scripts/generate-skills-manifest.ts",
     "assert-publish-target": "node -e \"const p=require('./package.json'); if(p.name!=='@cavuno/board'){throw new Error('Refusing to publish: package.json name is '+p.name+', expected @cavuno/board')}; if(p.private){throw new Error('Refusing to publish: package.json has private:true')}\"",
-    "prepublishOnly": "pnpm run assert-publish-target && pnpm run build"
+    "prepublishOnly": "pnpm run assert-publish-target && pnpm run gen:skills-manifest && pnpm run build"
   },
   "devDependencies": {
     "@kit/tsconfig": "workspace:*",
     "@types/node": "catalog:",
     "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
     "vitest": "^2.1.9"
   }
 }

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

@@ -0,0 +1,113 @@
+---
+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.
+---
+
+# Board-user authentication
+
+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).
+
+## When to use
+
+- Sign-up / sign-in / sign-out for board users.
+- Email verification and password reset flows.
+- Wiring authenticated calls (`me`, saved jobs, applications).
+
+## When not to use
+
+- Anonymous reads (jobs/companies/blog) — no auth needed.
+- Board-password gating — that's a separate grant; see `cavuno-board-errors`.
+
+## Register and login
+
+```ts snippet
+await board.auth.register({
+  role: 'candidate',
+  method: 'emailpass',
+  email: 'ada@example.com',
+  password: 'a-strong-password',
+  displayName: 'Ada',
+});
+
+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'` | a `CustomStorage`. Defaults: **`memory` in the browser, `nostore` on the server**. Browser login works out of the box; shared SSR instances stay stateless.
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+// Browser/SPA: token held in memory on the instance.
+const board = createBoardClient({
+  baseUrl: 'https://api.cavuno.com',
+  board: 'pk_a8f3...',
+  auth: { storage: 'memory' },
+});
+```
+
+A `CustomStorage` implements async `getItem`/`setItem`/`removeItem` — back it with `localStorage`, IndexedDB, Redis, or your own store.
+
+## No auto-refresh on 401 — handle it 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.
+
+```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;
+}
+```
+
+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`).
+
+## refresh / logout token sourcing
+
+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:
+
+```ts snippet
+await board.auth.refresh({ refreshToken });   // server: explicit
+await board.auth.logout({ refreshToken });    // revokes server-side, clears storage
+```
+
+## Server-side pattern (keep tokens out of the browser)
+
+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:
+
+```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}` },
+});
+```
+
+## Email verification & password reset
+
+```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
+```
+
+## Checklist
+
+- [ ] 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`.

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

@@ -0,0 +1,93 @@
+---
+name: cavuno-board-client
+description: Create and configure the @cavuno/board client — baseUrl and the pk_ board identifier, global headers, request/response hooks, per-call FetchOptions caching passthrough, the client.fetch escape hatch, and the rule that keeps one shared instance safe under SSR.
+---
+
+# The Board API client
+
+`createBoardClient` returns a typed client whose namespaces (`jobs`, `companies`, `blog`, `auth`, `me`, …) all route through one request pipeline: board-identifier base path, default headers, bearer token from storage, and your hooks.
+
+## When to use
+
+- Creating the client instance your whole app shares.
+- Adding global headers, logging, request/response hooks, or framework caching.
+- Calling an endpoint the SDK doesn't expose yet (`client.fetch`).
+
+## When not to use
+
+- Per-surface usage (listing jobs, auth) — see the surface skills; they assume the client exists.
+
+## Create the client
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+const board = createBoardClient({
+  baseUrl: 'https://api.cavuno.com',
+  board: 'pk_a8f3...', // pk_ key (preferred) | boards_ id | slug
+});
+```
+
+Use the `pk_…` publishable key for `board`, not the slug: the slug is operator-mutable and renames break deployed frontends. The `pk_…` key is immutable and client-safe.
+
+## Configuration
+
+```ts no-check
+const board = createBoardClient({
+  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+  globalHeaders: { 'Accept-Language': 'en' },
+  onRequest: async (req) => req,          // mutate/replace the request (locale, URL rewrite)
+  onResponse: async (res, req) => {},     // side effects only (logging, analytics)
+  logger: console,
+  auth: { storage: 'memory' },            // see cavuno-board-auth
+});
+```
+
+The `onRequest`/`onResponse` hooks are first-class — do not monkey-patch the client. `onResponse` receives a **clone** of the response, so reading its body never disturbs the SDK's own parsing.
+
+## Per-call FetchOptions ride straight to fetch
+
+Every method takes a trailing `options?` of type `FetchOptions` (`Omit<RequestInit,'body'>` plus `query`). Anything besides `body`/`query` passes through to `fetch` untouched, so framework caching works with zero SDK knowledge:
+
+```ts snippet
+// Next.js ISR
+await board.jobs.list({ limit: 20 }, { next: { revalidate: 60, tags: ['jobs'] } });
+// Cloudflare Workers
+await board.jobs.list({ limit: 20 }, { cf: { cacheTtl: 60 } } as never);
+// Standard fetch + abort
+const ac = new AbortController();
+await board.jobs.list({ limit: 20 }, { cache: 'force-cache', signal: ac.signal });
+```
+
+## One shared instance is SSR-safe — if state stays per-call
+
+A single Workers isolate serves many users at once. A module-scoped client is safe **only** while per-user state is passed per call (`options.headers`), not stored on the instance. For browser/SPA usage, the instance may hold the session (`auth.storage`); for SSR, keep the session in an httpOnly cookie and pass `{ headers: { authorization } }` per call (see `cavuno-board-auth`).
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+// Safe: shared, stateless. Per-user token rides per call.
+export const board = createBoardClient({
+  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+});
+```
+
+## Escape hatch: client.fetch
+
+`board.client.fetch<T>(path, init)` is public and first-class — it runs the full pipeline (base path, headers, token, hooks), not a raw `fetch`. Use it to call an endpoint before the SDK ships a typed method for it:
+
+```ts snippet
+const data = await board.client.fetch<{ object: 'list'; data: unknown[] }>(
+  '/some-new-endpoint',
+  { query: { limit: 5 } },
+);
+```
+
+## Checklist
+
+- [ ] One client created from env values, reused everywhere.
+- [ ] `board` is the `pk_…` key, not the slug.
+- [ ] No per-user state on a shared SSR instance.
+- [ ] Caching done via per-call `FetchOptions`, not a wrapper.

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

@@ -0,0 +1,86 @@
+---
+name: cavuno-board-errors
+description: Handle errors and access gating with the @cavuno/board SDK — the BoardApiError shape, the typed guards (isNotFound, isUnauthorized, isValidationError, isRateLimited, isForbidden, isConflict), and the board-password flow (isBoardPasswordRequired → password.verify → X-Board-Access grant).
+---
+
+# Errors and access gating
+
+Every SDK method throws on a non-2xx response. The error keeps the server's full typed envelope — never string-match messages.
+
+## When to use
+
+- Branching on failures (not found, unauthorized, validation, rate limit).
+- Unlocking a password-protected board.
+
+## The BoardApiError shape
+
+```ts no-check
+class BoardApiError extends Error {
+  status: number;
+  code: string;        // `<domain>_<snake_reason>`
+  details?: unknown;    // structured, per-code
+  requestId?: string;
+  raw: unknown;         // parsed body, untouched
+}
+```
+
+## Branch with the typed guards
+
+```ts snippet
+import {
+  isBoardApiError,
+  isNotFound,
+  isUnauthorized,
+  isValidationError,
+  isRateLimited,
+  isForbidden,
+  isConflict,
+} from '@cavuno/board';
+
+try {
+  return await board.jobs.retrieve('senior-chef');
+} catch (err) {
+  if (isNotFound(err)) return null;          // 404 → render not-found
+  if (isUnauthorized(err)) {                  // 401 → refresh or sign in
+    /* see cavuno-board-auth */
+  }
+  if (isValidationError(err)) {               // 400 validation_bad_request → field errors in err.details
+  }
+  if (isRateLimited(err)) {                    // 429 → back off
+  }
+  if (isBoardApiError(err)) {
+    console.error(err.code, err.requestId);    // log code + requestId for support
+  }
+  throw err;
+}
+```
+
+`isForbidden` (403) and `isConflict` (409) round out the set. Use `err.requestId` in support reports.
+
+## Password-protected boards
+
+A gated board answers reads with `isBoardPasswordRequired` until the visitor presents a grant. Exchange the password once with `password.verify()`; the SDK stores the grant and attaches it as `X-Board-Access` on every subsequent read automatically.
+
+```ts snippet
+import { isBoardPasswordRequired } from '@cavuno/board';
+
+try {
+  await board.jobs.list({ limit: 20 });
+} catch (err) {
+  if (isBoardPasswordRequired(err)) {
+    await board.password.verify(userEnteredPassword); // stores the grant
+    await board.jobs.list({ limit: 20 });             // now passes the wall
+  } else {
+    throw err;
+  }
+}
+```
+
+The grant is identical for every visitor of the board and is not a user session. On SSR (`nostore`), pass it per call as `{ headers: { 'x-board-access': grant } }` instead of relying on stored state.
+
+## Checklist
+
+- [ ] Failures branched via guards, never message string-matching.
+- [ ] `404` → handled not-found path (not a crash).
+- [ ] `err.requestId` logged for support.
+- [ ] Password-gated boards call `password.verify()` on `isBoardPasswordRequired`.

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

@@ -0,0 +1,93 @@
+---
+name: cavuno-board-jobs
+description: Browse, search, and render jobs with the @cavuno/board SDK — jobs.list, jobs.search, jobs.retrieve, jobs.similar. Covers the slim card vs full job shapes, storefront pagination (count/limit/offset + opaque cursor), filters, and the candidate-paywall gatedCount.
+---
+
+# Jobs: browse, search, detail
+
+The highest-traffic surface. Listing and search return slim `PublicJobCard`s; the detail endpoint returns the full `PublicJob`.
+
+## When to use
+
+- Listing/search/keyword/location pages.
+- The job-detail page and its "similar jobs" rail.
+
+## When not to use
+
+- Company-scoped listings — use `companies.listJobs` (same card shape).
+- The ungated embeddable widget — use `embed.jobs`.
+
+## List and render cards
+
+`jobs.list` returns a `JobCardListEnvelope`: storefront pagination fields plus `data: PublicJobCard[]` and optional `relatedSearches`.
+
+```ts snippet
+const page = await board.jobs.list({ limit: 20, seniority: ['senior', 'lead'] });
+page.count;        // total matches ("X jobs")
+page.hasMore;      // more pages exist
+page.nextCursor;   // opaque forward token, or null
+for (const card of page.data) {
+  card.title;
+  card.company?.name;
+  card.links.public; // canonical /companies/:companySlug/jobs/:jobSlug
+}
+```
+
+### Filters and pagination
+
+`JobsListQuery` supports `limit` (1–100), `offset` (takes precedence over `cursor`), `cursor`, and filters: `companyId`, `remoteOption`, `employmentType`, `seniority` (single or repeated → OR-matched), `location` + `radius` (km), `category`, `skill`. Paginate by passing back `nextCursor`, or use numbered pages with `offset`:
+
+```ts snippet
+const p1 = await board.jobs.list({ limit: 20 });
+const p2 = p1.nextCursor
+  ? await board.jobs.list({ limit: 20, cursor: p1.nextCursor })
+  : null;
+// or numbered pages:
+const page3 = await board.jobs.list({ limit: 20, offset: 40 });
+```
+
+## Search
+
+`jobs.search` posts a `JobsSearchBody` (free-text `query` + structured `filters`) and returns a `JobCardSearchEnvelope`:
+
+```ts snippet
+const results = await board.jobs.search({
+  query: 'chef',
+  filters: {
+    seniority: ['senior'],
+    remoteOption: ['remote'],
+    publishedAt: { gte: '2026-01-01T00:00:00Z' },
+  },
+  limit: 20,
+});
+```
+
+## Detail and similar
+
+```ts snippet
+const job = await board.jobs.retrieve('senior-chef'); // full PublicJob
+job.description;       // HTML
+job.officeLocations;
+job.company?.slug;
+const rail = await board.jobs.similar('senior-chef', { limit: 5 });
+```
+
+## The candidate paywall: gatedCount
+
+On gated boards, some results are hidden from anonymous/unentitled viewers. `gatedCount` is how many were withheld for the current viewer (absent/0 when entitled). Surface it as an upsell rather than pretending the list is complete:
+
+```ts snippet
+const page = await board.jobs.list({ limit: 20 });
+if (page.gatedCount && page.gatedCount > 0) {
+  // e.g. "Sign in to see N more roles"
+}
+```
+
+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.
+
+## Checklist
+
+- [ ] Listing/search use `PublicJobCard`; detail uses `PublicJob`.
+- [ ] Job links use `links.public` (canonical `/companies/:companySlug/jobs/:jobSlug`).
+- [ ] Pagination via `nextCursor` or `offset`, not client-side slicing.
+- [ ] `gatedCount` surfaced as an upsell, not hidden.

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

@@ -0,0 +1,96 @@
+---
+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.
+---
+
+# Setting 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.
+
+This skill is the orchestrator. Work top to bottom, delegating each surface to its focused skill.
+
+## When to use
+
+- 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.
+
+## When not to use
+
+- Authoring the hosted board inside the Cavuno admin (that's the operator Puck builder, not the SDK).
+- Building the operator/admin REST API client — that's `@kit/api-client`, not `@cavuno/board`.
+
+## 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 standard environment names
+
+Read these two values from the environment; never hard-code them:
+
+- `PUBLIC_CAVUNO_API_URL` — the API base, e.g. `https://api.cavuno.com`.
+- `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).
+
+Both are public-safe (the `pk_…` key is client-safe by design). Use your framework's public-env convention for the variable name (`VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`); the values are the same.
+
+## 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`.
+
+```ts
+import { createBoardClient } from '@cavuno/board';
+
+export const board = createBoardClient({
+  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
+  board: process.env.PUBLIC_CAVUNO_BOARD!,
+});
+```
+
+## Build the board shell from context
+
+`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.)
+
+## Build jobs browsing + detail
+
+The core surface. `jobs.list` / `jobs.search` for listing pages, `jobs.retrieve` for the detail page, `jobs.similar` for the related rail. Honor storefront pagination and the candidate-paywall `gatedCount`. See `cavuno-board-jobs`.
+
+## Add board users + saved jobs
+
+Register/login/refresh/logout, then `me.retrieve` and `me.savedJobs.*`. There is **no auto-refresh on 401** — handle it explicitly. See `cavuno-board-auth`.
+
+## Handle errors + gating
+
+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`.
+
+## App-owned concerns (out of scope)
+
+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.
+
+## Verification
+
+- `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.
+
+When the `cavuno-board-smoke-test` skill is present, run it against your `pk_…` to verify end to end.
+
+## Stop conditions
+
+Stop and ask the human when: no `pk_…` board identifier or API URL is available; the framework is unrecognized and has no server boundary for secrets; 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.