@cavuno/board 2.0.5 → 3.1.0

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

@@ -1,76 +1,80 @@
 ---
 name: cavuno-board-blog
-description: Build the blog with the @cavuno/board SDK — post archives (blog.posts.list with tagSlug/authorSlug/featured), the post page (blog.posts.retrieve + adjacent + similar), blog.tags and blog.authors, and free-text blog.search. Covers the summary-vs-detail split (html on the single read only), cursor pagination, slug-change redirects (redirected/newSlug), and the SEO fields the API actually returns.
+description: Public blog reads with @cavuno/board. Use for post archives, post detail, adjacent or similar posts, tag and author pages, or blog search.
 ---
 
-# Blog: posts, tags, authors, search
+# Blog
 
-Every list and search returns `PublicBlogPostSummary`; only `posts.retrieve` returns the full `PublicBlogPost` with the `html` body.
+Collections return `PublicBlogPostSummary`; only `blog.posts.retrieve`
+returns `PublicBlogPost` with the rendered `html` body. Read
+`board.context().features.blog` when deciding whether the board exposes a blog.
+The host app owns authoring, feeds, sitemaps, and OG-image routes.
 
-## When to use
+## Build archives
 
-- The blog index, tag archives, author archives, and featured rails.
-- The post page: body, prev/next nav, related-posts rail.
-- Blog search boxes.
-
-## When not to use
-
-- Writing posts/tags/authors — that is the admin API; this SDK is the public read surface.
-- Deciding whether the board has a blog at all — read `features.blog` from the board context.
-
-Out of scope — do not invent exports: no RSS feed, sitemap, or OG-image generation — the host app builds those routes from the data here (`publishedAt`, `canonicalUrl`, `ogImageUrl` are all returned).
-
-## List posts and archives
-
-`blog.posts.list` returns a `ListEnvelope<PublicBlogPostSummary>`. `BlogPostsListQuery` supports `limit` (1–100), `cursor`, `tagSlug`, `authorSlug`, and `featured: 'true'` (opt-in only — the string literal, not a boolean). Blog lists page by cursor only; there is no `offset` and no total `count`.
+`blog.posts.list` returns `ListEnvelope<PublicBlogPostSummary>`. Its query
+accepts `limit` (1–100), `cursor`, `tagSlug`, `authorSlug`, and
+`featured: 'true'`. `featured` is the string literal. Blog lists use cursor
+pagination and expose neither `offset` nor total `count`.
 
 ```ts snippet
 const page = await board.blog.posts.list({ tagSlug: 'news', limit: 12 });
 for (const post of page.data) {
   post.title;
-  post.customExcerpt;   // null unless the author wrote one
-  post.coverUrl;        // null when no cover image
+  post.customExcerpt;
+  post.coverUrl;
   post.readingTimeMin;
-  post.authors;         // embedded: id, name, slug, bio, avatarUrl, social URLs
-  post.tags;            // embedded: id, name, slug, description
+  post.authors;
+  post.tags;
 }
 const next = page.nextCursor
-  ? await board.blog.posts.list({ tagSlug: 'news', limit: 12, cursor: page.nextCursor })
-  : null; // nextCursor is null when hasMore is false
+  ? await board.blog.posts.list({
+      tagSlug: 'news',
+      limit: 12,
+      cursor: page.nextCursor,
+    })
+  : null;
 ```
 
-## Render a post
+Embedded author rows carry `id`, `name`, `slug`, `bio`, `avatarUrl`, and
+social URLs. Embedded tag rows carry `id`, `name`, `slug`, and `description`.
+
+## Render a post and canonicalize its slug
 
-`posts.retrieve` adds the detail-only fields: `html` (the rendered rich-text body, nullable), `ogImageUrl`, `featureImageCaption`, `seoTitle`, `seoDescription`, `redirected`, `newSlug`.
+`posts.retrieve` adds `html`, `ogImageUrl`, `featureImageCaption`, `seoTitle`,
+`seoDescription`, `redirected`, and `newSlug`. Old slugs still resolve: when
+`redirected` and `newSlug` are set, redirect to `newSlug` before rendering.
 
 ```ts snippet
 const post = await board.blog.posts.retrieve('hello-world');
 if (post.redirected && post.newSlug) {
-  // the slug changed — redirect to the post at newSlug instead of rendering here
+  // Redirect to the post route at post.newSlug.
 }
-post.html;                          // inject as the article body
-post.seoTitle ?? post.title;        // <title>
-post.seoDescription ?? post.customExcerpt; // meta description
-post.canonicalUrl;                  // author-set canonical override, or null
-post.ogImageUrl ?? post.coverUrl;   // social card image
+post.html;
+post.seoTitle ?? post.title;
+post.seoDescription ?? post.customExcerpt;
+post.canonicalUrl;
+post.ogImageUrl ?? post.coverUrl;
 ```
 
-Anti-pattern: don't render a post at a stale URL. When `redirected` is true, issue a redirect to `newSlug` — old slugs keep resolving, but the canonical location moved.
+Fetch detail for the post page; summaries have no `html` field.
 
-Anti-pattern: don't look for `html` on list items. Summaries never carry it; fetch `retrieve` for the post page only.
-
-## Prev/next and related
+## Add post navigation
 
 ```ts snippet
 const { previous, next } = await board.blog.posts.adjacent('hello-world');
-// previous = older post, next = newer; each a summary or null
+// previous is older; next is newer; either can be null.
 
-const rail = await board.blog.posts.similar('hello-world', { limit: 6 }); // 1–20, default 6
+const rail = await board.blog.posts.similar('hello-world', { limit: 6 });
 ```
 
-## Tags and authors
+`similar` accepts `limit` 1–20 and defaults to 6.
+
+## Build tag and author pages
 
-Both are list + retrieve-by-slug. `PublicBlogTag`: `id`, `name`, `slug`, `description`. `PublicBlogAuthor`: `id`, `name`, `slug`, `bio`, `avatarUrl`, `websiteUrl`, `twitterUrl`, `linkedinUrl`, `githubUrl`.
+Tags and authors each provide list plus retrieve-by-slug. Combine a retrieved
+entity with `posts.list({ tagSlug })` or `posts.list({ authorSlug })` for its
+archive.
 
 ```ts snippet
 const { data: tags } = await board.blog.tags.list();
@@ -79,21 +83,32 @@ const { data: authors } = await board.blog.authors.list();
 const author = await board.blog.authors.retrieve('jane');
 ```
 
-Archive pages combine the two: `tags.retrieve` for the header, `posts.list({ tagSlug })` for the posts.
+`PublicBlogTag` carries `id`, `name`, `slug`, and `description`.
+`PublicBlogAuthor` carries `id`, `name`, `slug`, `bio`, `avatarUrl`,
+`websiteUrl`, `twitterUrl`, `linkedinUrl`, and `githubUrl`.
 
-## Search
+## Search posts
 
-`blog.search` posts a `BlogSearchBody` (`query` up to 200 chars, optional `cursor`, `limit` 1–50 — note the lower cap than lists) and returns a `SearchEnvelope<PublicBlogPostSummary>`:
+`blog.search` posts `BlogSearchBody`: `query` up to 200 characters, optional
+`cursor`, and `limit` 1–50. It returns
+`SearchEnvelope<PublicBlogPostSummary>`.
 
 ```ts snippet
 const results = await board.blog.search({ query: 'launch', limit: 10 });
 results.data[0]?.slug;
 ```
 
-## Verify
+## Completion gate
+
+Finish only after every applicable check passes:
+
+- Archive and search rows render summaries; the post page fetches detail for
+  `html`.
+- A retrieved old slug redirects to `newSlug` before rendering.
+- Featured archives send the exact string `featured: 'true'`.
+- Cursor paging reaches `nextCursor: null` without relying on count or offset.
+- Newest and oldest posts handle the null side of `adjacent`.
+
+## Cavuno SDK reference
 
-- A list item has no `html` key; `posts.retrieve` of the same slug returns it (string or null).
-- Retrieving a post by an old slug returns `redirected: true` with `newSlug` set, and your route redirects there.
-- `posts.list({ featured: 'true' })` returns only posts with `featured: true`.
-- Cursor paging terminates: `nextCursor` is `null` on the last page.
-- `adjacent` on the newest post returns `next: null`; on the oldest, `previous: null`.
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).

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

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

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

@@ -1,86 +1,73 @@
 ---
 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).
+description: Classify Board API failures and board-password challenges. Use when mapping SDK errors to UI states, retries, support diagnostics, or password-gated access.
 ---
 
-# Errors and access gating
+# Handle errors and access gates
 
-Every SDK method throws on a non-2xx response. The error keeps the server's full typed envelope — never string-match messages.
+Every non-2xx SDK response throws `BoardApiError`. Branch on its typed guards and codes; messages remain presentation text rather than control flow.
 
-## When to use
-
-- Branching on failures (not found, unauthorized, validation, rate limit).
-- Unlocking a password-protected board.
-
-## The BoardApiError shape
+## Error contract
 
 ```ts no-check
 class BoardApiError extends Error {
   status: number;
-  code: string;        // `<domain>_<snake_reason>`
-  details?: unknown;    // structured, per-code
+  code: string;
+  details?: unknown;
   requestId?: string;
-  raw: unknown;         // parsed body, untouched
+  raw: unknown;
 }
 ```
 
-## Branch with the typed guards
+Use the narrowest matching guard, render its domain state, and rethrow unmatched failures:
 
 ```ts snippet
 import {
   isBoardApiError,
   isNotFound,
+  isRateLimited,
   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
+} catch (error) {
+  if (isNotFound(error)) return null;
+  if (isUnauthorized(error)) return showSignIn();
+  if (isValidationError(error)) return showFieldErrors(error.details);
+  if (isRateLimited(error)) return scheduleRetry();
+  if (isBoardApiError(error)) {
+    console.error(error.code, error.requestId);
   }
-  if (isRateLimited(err)) {                    // 429 → back off
-  }
-  if (isBoardApiError(err)) {
-    console.error(err.code, err.requestId);    // log code + requestId for support
-  }
-  throw err;
+  throw error;
 }
 ```
 
-`isForbidden` (403) and `isConflict` (409) round out the set. Use `err.requestId` in support reports.
+The remaining status guards are `isForbidden` for 403 and `isConflict` for 409. Record `code` and `requestId` in support diagnostics. Because v1 may add error codes, unmatched `BoardApiError` instances still need a safe generic state.
+
+**Complete when:** every expected failure has one typed branch, an invalid resource renders not-found, and unmatched failures retain their original error.
 
-## Password-protected boards
+## Board-password challenge
 
-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.
+`isBoardPasswordRequired` distinguishes the `board_password_required` 401 from an expired board-user session. Exchange the visitor's password once; browser storage then attaches the returned grant as `X-Board-Access` on later reads.
 
 ```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;
-  }
+  return await board.jobs.list({ limit: 20 });
+} catch (error) {
+  if (!isBoardPasswordRequired(error)) throw error;
+  await board.password.verify(userEnteredPassword);
+  return board.jobs.list({ limit: 20 });
 }
 ```
 
-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.
+The grant is board access, not a user session. Server-rendered apps keep it in the app-owned grant cookie and pass it per request; `cavuno-board-server-sessions` defines that cookie and redirect contract. A fresh `board_password_required` response means the grant expired or the password rotated, so return to the challenge flow.
+
+**Complete when:** a valid password unlocks one retry, an invalid password renders its typed error, and a stale server grant is cleared before rechallenge.
 
-## Checklist
+## Cavuno SDK reference
 
-- [ ] 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`.
+For setup and API details beyond this workflow, use the [Cavuno Board SDK documentation](https://cavuno.com/docs/sdk).