@cavuno/board 1.34.0 → 1.35.0

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

@@ -32,14 +32,13 @@ Read `package.json` and the project layout before writing anything. Identify: th
 - `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
+## Use the standard board environment name
 
-Read these two values from the environment; never hard-code them:
+Read the board key from the environment; never hard-code it:
 
-- `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.
+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
 
@@ -57,7 +56,6 @@ Create one client and reuse it. See `cavuno-board-client`.
 import { createBoardClient } from '@cavuno/board';
 
 export const board = createBoardClient({
-  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
   board: process.env.PUBLIC_CAVUNO_BOARD!,
 });
 ```
@@ -68,7 +66,7 @@ export const board = createBoardClient({
 
 ## 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`; use `paginate()` for full-catalog walks (sitemaps, feeds). See `cavuno-board-jobs`.
+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`.
 
 ## Add board users + saved jobs
 
@@ -85,7 +83,7 @@ hand-rolling (each has a skill):
 
 - Salary/date/label formatting in the board language → `cavuno-board-format`
 - Listing-filter vocabulary + URL param parsing → `cavuno-board-filters`
-- Board theme → shadcn CSS variables + fonts → `cavuno-board-theme`
+- Optional hosted-board theme compatibility → `cavuno-board-theme`. By default, the consuming application owns tokens, fonts, and color mode.
 
 ## Build the remaining surfaces per feature flag
 
@@ -117,4 +115,4 @@ Then run the `cavuno-board-smoke-test` skill against your `pk_…` — type chec
 
 ## 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.
+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.

package/skills/cavuno-board-smoke-test/SKILL.md

@@ -18,7 +18,7 @@ auth, and SEO surfaces behave. Verify at runtime, in this order.
 ## 0 — Run `doctor` first (deterministic pass)
 
 ```bash
-PUBLIC_CAVUNO_API_URL=... PUBLIC_CAVUNO_BOARD=pk_... \
+PUBLIC_CAVUNO_BOARD=pk_... \
   npx @cavuno/board doctor --frontend http://localhost:3000
 ```
 
@@ -45,21 +45,22 @@ board; wait a few minutes.
 
 ## 1 — Probe the API directly (before blaming app code)
 
-Use the real env values the app reads (`PUBLIC_CAVUNO_API_URL`,
-`PUBLIC_CAVUNO_BOARD`). Expected outputs are exact.
+Use the real `PUBLIC_CAVUNO_BOARD` value the app reads. The SDK and doctor use `https://api.cavuno.com` by default; set `PUBLIC_CAVUNO_API_URL` only for a Cavuno-supplied non-production override. Expected outputs are exact.
 
 ```bash
+CAVUNO_API_URL="${PUBLIC_CAVUNO_API_URL:-https://api.cavuno.com}"
+
 # Board context: MUST return JSON with "object": "public_board" and your
 # board's name — not an HTML error page, not {"error":{"code":"boards_not_found"}}.
-curl -s "$PUBLIC_CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD" | head -c 300
+curl -s "$CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD" | head -c 300
 
 # Jobs list: MUST return {"object":"list", ... "data":[...]}. An empty data
 # array on a board you know has jobs means the wrong board identifier.
-curl -s "$PUBLIC_CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD/jobs?limit=2" | head -c 300
+curl -s "$CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD/jobs?limit=2" | head -c 300
 
 # Error envelope: a bogus job slug MUST return the v1 error shape with
 # "code":"jobs_not_found" — anything else means a proxy is rewriting responses.
-curl -s "$PUBLIC_CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD/jobs/definitely-not-a-job"
+curl -s "$CAVUNO_API_URL/v1/boards/$PUBLIC_CAVUNO_BOARD/jobs/definitely-not-a-job"
 ```
 
 On a password-protected board, every content read above returns 401 with

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

@@ -1,69 +1,57 @@
 ---
 name: cavuno-board-theme
-description: Board branding with @cavuno/board/theme — map the board's stored theme (16 semantic colors × light/dark + typography from board.context().theme) onto shadcn CSS variables, resolve the color-scheme mode, and build the Google Fonts request. Use when wiring the app shell, dark mode, or brand styling for a tenant frontend.
+description: Optional hosted-board theme compatibility with @cavuno/board/theme. Use only when a custom frontend deliberately mirrors or migrates an existing Cavuno hosted theme; the consuming application normally owns tokens, fonts, and color mode.
 ---
 
-# Theme: board branding → shadcn tokens
+# Optional hosted-board theme compatibility
 
-`@cavuno/board/theme` maps the board's stored theme onto the canonical
-shadcn token vocabulary as CSS-variable overrides. One contract, two
-consumers: the dashboard edits the board theme; agents restyle through the
-standard shadcn theme file — both end up in the same tokens.
+The custom frontend owns its visual system by default: semantic design tokens, component styles, font loading, and light/dark-mode state belong in the application. Do not make remote `board.context().theme` the default source of truth for a new SDK frontend.
+
+`@cavuno/board/theme` exists for a narrower job: mirroring an existing hosted board or providing a starting point during a hosted-to-custom migration.
 
 ## When to use
 
-- The app shell/root layout of any tenant frontend, once.
-- Wiring dark mode or brand fonts.
+- The human explicitly wants the custom frontend to mirror the current hosted board.
+- A migration needs a temporary compatibility layer while tokens move into the application.
+- One application intentionally renders many Cavuno boards with different operator-owned themes.
 
 ## When not to use
 
-- Component-level styling — write normal Tailwind/shadcn classes; they pick
-  the overridden tokens up automatically.
+- A normal custom frontend whose design system already defines tokens and fonts.
+- Component-level styling.
+- As a replacement for the framework's theme provider or font system.
 
-## Wire it once at the shell
+## Read compatibility values
 
 ```ts snippet
-import { boardThemeToCss, themeMode, googleFontsUrl } from '@cavuno/board/theme';
+import {
+  boardThemeToCss,
+  googleFontsUrl,
+  themeMode,
+} from '@cavuno/board/theme';
 
 const context = await board.context();
-const css = boardThemeToCss(context.theme);   // ':root {…}' + '.dark {…}'
-const mode = themeMode(context.theme);        // 'light' | 'dark' | 'system'
-const fontsHref = googleFontsUrl(context.theme); // one <link>, or null
+const hostedTheme = {
+  css: boardThemeToCss(context.theme),
+  fontUrl: googleFontsUrl(context.theme),
+  mode: themeMode(context.theme),
+};
 ```
 
-Inject `css` in a `<style>` AFTER the static theme stylesheet so the
-overrides win; render nothing when it's empty (a null theme means the app's
-default theme applies untouched). Apply `mode` by toggling the `.dark`
-class (`system` = follow `prefers-color-scheme`).
-
-## The mapping is the contract
-
-All 16 board color keys are consumed — a coverage golden in-monorepo
-asserts neither the hosted board nor this module drops one. Standard
-shadcn tokens carry the core (background/foreground, card, popover,
-primary, secondary, muted, accent, destructive, border, input, ring);
-the four keys shadcn has no standard token for ship as
-`--contrast-background`, `--contrast-foreground`, `--foreground-subtle`,
-`--foreground-disabled`, plus `--foreground-error`.
+`boardThemeToCss` validates the stored colors before emitting CSS. A null theme returns no CSS, so the application default remains intact.
 
-## Anti-patterns
-
-```ts no-check
-// NEVER hardcode brand colors in components — they bypass the board theme:
-<button style={{ background: '#7c3aed' }} />
-// NEVER re-map theme keys ad hoc per page; the shell mapping is the single source.
-// NEVER fetch fonts per-family — googleFontsUrl builds ONE deduped request.
-```
+## Migration guidance
 
-## Out of scope — do not invent exports
+1. Compare the returned colors, fonts, and mode with the consuming design system.
+2. Move the chosen values into the application's own semantic tokens and font loader.
+3. Remove the runtime theme injection when the application becomes authoritative.
 
-No color math (hover/pressed derivation, contrast checking — the hosted
-dashboard owns palette design), no per-component theme props, no CSS-in-JS
-runtime. The module emits strings; the app owns injection.
+If permanent multi-board mirroring is an explicit requirement, inject the validated CSS after the static theme and make the framework's theme provider apply the returned mode. Do not interpolate raw stored colors or build font URLs yourself.
 
 ## Verify
 
-- [ ] A board with a custom theme renders its brand color on primary
-      buttons and focus rings; a board without one renders the app default.
-- [ ] Dark palette applies under `.dark` and `mode` drives the class.
-- [ ] The Google Fonts request appears once, covering sans + heading.
+- [ ] The application renders correctly when `context.theme` is null.
+- [ ] New custom frontends do not fetch theme data merely to establish basic styling.
+- [ ] Compatibility CSS never contains unsafe stored color syntax.
+- [ ] Font loading and color-mode ownership are explicit and tested.
+- [ ] A migration has a documented point where the application becomes authoritative.

package/skills/flavors/tanstack-start/SKILL.md

@@ -19,7 +19,6 @@ import { createBoardClient } from '@cavuno/board';
 
 // Module-scoped, no auth.storage → safe across concurrent Workers requests.
 export const board = createBoardClient({
-  baseUrl: process.env.PUBLIC_CAVUNO_API_URL!,
   board: process.env.PUBLIC_CAVUNO_BOARD!,
 });
 ```

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.34.0",
+  "version": "1.35.0",
   "skills": [
     {
       "name": "cavuno-board-account",
@@ -31,7 +31,7 @@
     },
     {
       "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.",
+      "description": "Create and configure the @cavuno/board client — the pk_ board identifier, optional API-origin override, global headers, hooks, per-call FetchOptions, and the rule that keeps one shared instance safe under SSR.",
       "path": "skills/cavuno-board-client/SKILL.md",
       "framework": null,
       "category": "core"
@@ -87,7 +87,7 @@
     },
     {
       "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.",
+      "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, catalog pagination (count/limit/offset + opaque cursor), filters, and the candidate-paywall gatedCount.",
       "path": "skills/cavuno-board-jobs/SKILL.md",
       "framework": null,
       "category": "core"
@@ -157,7 +157,7 @@
     },
     {
       "name": "cavuno-board-theme",
-      "description": "Board branding with @cavuno/board/theme — map the board's stored theme (16 semantic colors × light/dark + typography from board.context().theme) onto shadcn CSS variables, resolve the color-scheme mode, and build the Google Fonts request. Use when wiring the app shell, dark mode, or brand styling for a tenant frontend.",
+      "description": "Optional hosted-board theme compatibility with @cavuno/board/theme. Use only when a custom frontend deliberately mirrors or migrates an existing Cavuno hosted theme; the consuming application normally owns tokens, fonts, and color mode.",
       "path": "skills/cavuno-board-theme/SKILL.md",
       "framework": null,
       "category": "core"