bsmnt 0.12.0 → 0.13.0

package/src/agent-skills/ashby-pagebuilder-block/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: ashby-pagebuilder-block
+description: >-
+  Register an Ashby job board as a selectable `ashbyJobBoardBlock` in a basement
+  Sanity page builder. Use when the user asks to "integrate/add Ashby to the page
+  builder", "add a job board / open positions block", "make the job list
+  selectable in the page builder / Studio", "register the Ashby block in Sanity",
+  or "wire up open positions so editors can drop them on a page". Also covers
+  rendering the Ashby job list directly (no CMS) when asked how to show open
+  positions.
+---
+
+# Wire the Ashby job-board block into the page builder
+
+The Ashby integration ships an agnostic core plus an optional Sanity adapter
+(`lib/integrations/ashby/sanity/`). The adapter is **not** auto-registered into
+the page builder (that wiring couples to each project's schema), so do it here by
+editing the project's real files. Read each file first and adapt to its actual
+shape — do not blindly pattern-match. If an anchor below is missing, stop and
+report it rather than guessing.
+
+## 0. Preconditions
+
+- `lib/integrations/ashby/` exists (the integration was added).
+- `lib/integrations/ashby/sanity/job-board-block.ts` exists (Sanity adapter —
+  only copied when Sanity is present). If it's missing, the project isn't a
+  Sanity project; skip to **Direct rendering** below.
+- The project has a page builder: `lib/integrations/sanity/page-builder-config.ts`
+  exists. If not, it's the standard Sanity integration (no page builder) — skip to
+  **Direct rendering**.
+- Read the `page-builder-block` skill first. Blocks in this template are defined
+  with `defineBlock` and drawn through a registry, and both halves are enforced
+  by a typecheck; the steps below are the Ashby-specific version of that recipe.
+- `ASHBY_JOB_BOARD_NAME` is set (the slug in the board's `jobs.ashbyhq.com` URL),
+  or the editor will set a per-block `boardName`. No token is needed — Ashby's
+  job-board endpoint is public. `isAshbyConfigured()` from
+  `@/lib/integrations/check-integration` reports whether the env var resolves.
+
+## 1. Re-wrap it with `defineBlock`, then register the schema
+
+The shipped adapter uses plain `defineType` so it also works in the standard
+Sanity integration, which has no page builder. In this template every block must
+go through `defineBlock`
+(`lib/integrations/sanity/schemas/shared/block.ts`) — it implies
+`type: "document"` and appends **Anchor ID** and **Presentation Mode**, the two
+fields the renderer reads for the anchor and the spacing. A block without them
+fails `page-builder-config`'s conventions test.
+
+Create `lib/integrations/sanity/schemas/components/reusable/ashby-job-board.ts`
+that re-declares the adapter through the factory. Keep the adapter as the source
+of the fields, so an integration update still flows through:
+
+```ts
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block"
+import { ashbyJobBoardBlock as base } from "@/lib/integrations/ashby/sanity/job-board-block"
+import { jobBoardIcon } from "@/lib/integrations/sanity/icons"
+
+export const ashbyJobBoardBlock = defineBlock({
+  name: base.name,
+  title: base.title,
+  icon: jobBoardIcon,
+  description: base.description,
+  fields: base.fields,
+  preview: base.preview,
+})
+```
+
+`heading` is one of the fields `resolveAnchorId` walks, so the block gets a
+generated anchor from the editor's heading with no extra work.
+
+Export it from `lib/integrations/sanity/schemas/components/index.ts` and add it
+to the `schema.types` array in `lib/integrations/sanity/schemas/index.ts`,
+alongside the other component documents (near `hero` / `description`):
+
+```ts
+import { ashbyJobBoardBlock } from "./components"
+// ...
+export const schema: { types: SchemaTypeDefinition[] } = {
+  types: [
+    // ...existing component types...
+    ashbyJobBoardBlock,
+  ],
+}
+```
+
+## 2. Add it to the page-builder config — `lib/integrations/sanity/page-builder-config.ts`
+
+Extend the `PageBuilderDocumentType` union and add a reusable reference member.
+Match the member shape the file actually uses — in the current basement page
+builder that's `pageTypes` (which page documents may host it) plus `category`
+(which insert-menu group it lands in):
+
+```ts
+export type PageBuilderDocumentType =
+  | "hero"
+  | "description"
+  | "ashbyJobBoardBlock"
+  // ...rest...
+
+// inside reusablePageBuilderReferenceMembers:
+{
+  documentType: "ashbyJobBoardBlock",
+  name: "ashbyJobBoardBlockReference",
+  title: "Job Board",
+  pageTypes: ["generic"],
+  category: "list",
+},
+```
+
+## 3. List it in the Studio — `lib/integrations/sanity/structure.ts`
+
+Under the "Reusable Components" list, add (the schema's own case icon is used
+automatically, so `.icon()` is optional):
+
+```ts
+S.documentTypeListItem("ashbyJobBoardBlock").title("Job Boards"),
+```
+
+## 4. Icon — `lib/integrations/sanity/icons.ts`
+
+The adapter defaults to `@sanity/icons`' `CaseIcon`. This project uses phosphor
+duotone throughout, so add one and pass it in step 1:
+
+```ts
+import { BriefcaseIcon } from "@phosphor-icons/react/dist/ssr"
+export const jobBoardIcon = asDuotoneIcon(BriefcaseIcon)
+```
+
+## 5. Render it — a component plus a registry entry
+
+Create `components/page-builder/components/ashby-job-board.tsx`. It must be an
+**async Server Component** — `getCareerJobs` is server-only. Style it with the
+project's own conventions (CSS modules vs Tailwind, `Link` primitive); the markup
+below is a starting point, not a spec.
+
+**No outer `<section>` and no vertical padding.** The renderer wraps every block
+in `<Section>`, which owns the `<section>` element, the anchor `id` and the
+padding the editor picked in Presentation Mode. A `py-*` here would fight it:
+
+```tsx
+import type { ReactNode } from "react"
+import { stegaClean } from "next-sanity"
+import { Link } from "@/components/ui/link"
+import type { CareerJob } from "@/lib/integrations/ashby"
+import { getCareerJobs } from "@/lib/integrations/ashby"
+import { isAshbyConfigured } from "@/lib/integrations/check-integration"
+import type { PageBuilderBlock } from "../types"
+
+type AshbyJobBoardProps = {
+  block: Extract<PageBuilderBlock, { _type: "ashbyJobBoardBlock" }>
+}
+
+export async function AshbyJobBoard({ block }: AshbyJobBoardProps) {
+  // stegaClean strips visual-editing metadata so the board name resolves.
+  const boardName = stegaClean(block.boardName)
+  if (!(boardName || isAshbyConfigured())) return null
+
+  let jobs: CareerJob[] = []
+  let hasError = false
+
+  try {
+    jobs = await getCareerJobs(boardName)
+  } catch (error) {
+    console.error("Failed to load Ashby jobs", error)
+    hasError = true
+  }
+
+  let body: ReactNode = null
+
+  if (hasError) {
+    body = (
+      <p className="text-base text-current/60">
+        Our job board is temporarily unavailable. Please try again shortly.
+      </p>
+    )
+  } else if (jobs.length === 0) {
+    body = (
+      <p className="text-base text-current/60">No open positions right now.</p>
+    )
+  } else {
+    body = (
+      <ul className="divide-y divide-current/10 border-current/10 border-t">
+        {jobs.map((job) => (
+          <li key={job.id}>
+            <Link
+              href={job.href}
+              className="flex flex-col gap-1 py-4 transition-opacity hover:opacity-70 md:flex-row md:items-center md:justify-between"
+            >
+              <span className="font-medium text-base">{job.title}</span>
+              <span className="text-current/60 text-sm">
+                {[job.department, job.location].filter(Boolean).join(" · ")}
+              </span>
+            </Link>
+          </li>
+        ))}
+      </ul>
+    )
+  }
+
+  return (
+    <div>
+      {block.heading ? (
+        <h2 className="mb-6 font-semibold text-2xl tracking-tight md:text-3xl">
+          {block.heading}
+        </h2>
+      ) : null}
+      {body}
+    </div>
+  )
+}
+```
+
+Then add one entry to `components/page-builder/registry.tsx`, keyed by schema
+type. There is no switch to extend, and the map's key set is typed as exactly
+`PageBuilderDocumentType` — miss this and `bun typecheck` fails:
+
+```tsx
+import { AshbyJobBoard } from "./components/ashby-job-board"
+// ...inside blockRegistry:
+ashbyJobBoardBlock: {
+  render: (block) => <AshbyJobBoard block={block} />,
+},
+```
+
+Don't add an `isEmpty` here: whether the board has open roles is only known after
+the fetch, and `isEmpty` runs before the block renders. The component's own
+"No open positions right now" copy covers the empty case.
+
+The renderer is synchronous and returns this async component as a child, which
+React resolves — no change to `Renderer` itself is needed. If the project runs
+with **Cache Components** (`cacheComponents: true`), the live Ashby read is
+uncached, so wrap the block in a `<Suspense>` boundary (or wrap `getCareerJobs`
+in your own `"use cache"` function with `cacheLife`) to keep the route's static
+shell prerenderable.
+
+## 6. Regenerate types + verify
+
+```bash
+bun run sanity:typegen   # regenerates sanity.types.ts so PageBuilderBlock includes the block
+bun typecheck
+bun lint
+```
+
+`bun typecheck` must pass. The page query already spreads dereferenced block
+fields (`...@->{ ... }`), so `heading`, `boardName`, `anchorId` and
+`presentation` flow through with no query change.
+
+Then check it in the Studio: the block's form ends with **Anchor ID** and
+**Presentation Mode**, and dropping it on a page with the heading "Open roles"
+renders `<section id="open-roles">` with the padding from the scale.
+
+## Direct rendering (no page builder)
+
+For any project, render the board without a CMS from a Server Component:
+
+```tsx
+import { getCareerJobs } from "@/lib/integrations/ashby"
+
+export default async function Careers() {
+  const jobs = await getCareerJobs()
+
+  return (
+    <ul>
+      {jobs.map((job) => (
+        <li key={job.id}>
+          <a href={job.href}>{job.title}</a>
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+`getCareerJobs()` reads `ASHBY_JOB_BOARD_NAME`; pass a board name to override it
+(`getCareerJobs("other-board")`). It throws when the board name is missing or
+Ashby returns a non-2xx status, so catch it if a job-board outage shouldn't fail
+the page. See `lib/integrations/ashby/README.md` for the full `CareerJob` shape.

package/src/agent-skills/hubspot-pagebuilder-block/SKILL.md

@@ -27,14 +27,45 @@ report it rather than guessing.
 - The project has a page builder: `lib/integrations/sanity/page-builder-config.ts`
   exists. If not, it's the standard Sanity integration (no page builder) — skip to
   **Direct rendering**.
+- Read the `page-builder-block` skill first. Blocks in this template are defined
+  with `defineBlock` and drawn through a registry, and both halves are enforced
+  by a typecheck; the steps below are the HubSpot-specific version of that recipe.
 
-## 1. Register the schema — `lib/integrations/sanity/schemas/index.ts`
+## 1. Re-wrap it with `defineBlock`, then register the schema
 
-Add the import and include the block in the `schema.types` array (alongside the
-other component documents, e.g. near `hero` / `description`):
+The shipped adapter uses plain `defineType` so it also works in the standard
+Sanity integration, which has no page builder. In this template every block must
+go through `defineBlock`
+(`lib/integrations/sanity/schemas/shared/block.ts`) — it implies
+`type: "document"` and appends **Anchor ID** and **Presentation Mode**, the two
+fields the renderer reads for the anchor and the spacing. A block without them
+fails `page-builder-config`'s conventions test.
+
+Create `lib/integrations/sanity/schemas/components/reusable/hubspot-form.ts`
+that re-declares the adapter through the factory. Keep the adapter as the source
+of the fields, so an integration update still flows through:
+
+```ts
+import { defineBlock } from "@/lib/integrations/sanity/schemas/shared/block"
+import { hubspotFormBlock as base } from "@/lib/integrations/hubspot/sanity/form-block"
+import { hubspotFormIcon } from "@/lib/integrations/sanity/icons"
+
+export const hubspotFormBlock = defineBlock({
+  name: base.name,
+  title: base.title,
+  icon: hubspotFormIcon,
+  description: base.description,
+  fields: base.fields,
+  preview: base.preview,
+})
+```
+
+Export it from `lib/integrations/sanity/schemas/components/index.ts` and add it
+to the `schema.types` array in `lib/integrations/sanity/schemas/index.ts`,
+alongside the other component documents (near `hero` / `description`):
 
 ```ts
-import { hubspotFormBlock } from "@/lib/integrations/hubspot/sanity/form-block"
+import { hubspotFormBlock } from "./components"
 // ...
 export const schema: { types: SchemaTypeDefinition[] } = {
   types: [
@@ -73,30 +104,23 @@ automatically, so `.icon()` is optional):
 S.documentTypeListItem("hubspotFormBlock").title("HubSpot Forms"),
 ```
 
-## 4. (Optional) Envelope icon — `lib/integrations/sanity/icons.ts`
+## 4. Envelope icon — `lib/integrations/sanity/icons.ts`
 
-The block already defaults to `@sanity/icons`' `EnvelopeIcon`. To match this
-project's phosphor duotone icons, add and apply one:
+The adapter defaults to `@sanity/icons`' `EnvelopeIcon`. This project uses
+phosphor duotone throughout, so add one and pass it in step 1:
 
 ```ts
 import { EnvelopeIcon } from "@phosphor-icons/react/dist/ssr"
 export const hubspotFormIcon = asDuotoneIcon(EnvelopeIcon)
 ```
 
-Then override the icon where the block is registered in `schemas/index.ts`:
+## 5. Render it — a component plus a registry entry
 
-```ts
-import { hubspotFormBlock as hubspotFormBlockBase } from "@/lib/integrations/hubspot/sanity/form-block"
-import { hubspotFormIcon } from "../icons"
-const hubspotFormBlock: SchemaTypeDefinition = {
-  ...hubspotFormBlockBase,
-  icon: hubspotFormIcon,
-}
-```
-
-## 5. Render it — `components/page-builder/renderer.tsx` + a new component
+Create `components/page-builder/components/hubspot-form.tsx`.
 
-Create `components/page-builder/components/hubspot-form.tsx`:
+**No outer `<section>` and no vertical padding.** The renderer wraps every block
+in `<Section>`, which owns the `<section>` element, the anchor `id` and the
+padding the editor picked in Presentation Mode. A `py-*` here would fight it:
 
 ```tsx
 import { stegaClean } from "next-sanity"
@@ -114,32 +138,41 @@ export function HubSpotFormBlock({ block }: HubSpotFormBlockProps) {
   if (!selection) return null
 
   return (
-    <section className="px-4 py-8 md:py-12">
+    <div className="px-4">
       <HubSpotForm
         className="mx-auto max-w-[590px]"
         formId={selection.formId}
         portalId={selection.portalId}
         region={selection.region}
       />
-    </section>
+    </div>
   )
 }
 ```
 
-Then add the case to the renderer's `switch (block._type)`:
+Then add one entry to `components/page-builder/registry.tsx`, keyed by schema
+type. There is no switch to extend, and the map's key set is typed as exactly
+`PageBuilderDocumentType` — miss this and `bun typecheck` fails:
 
 ```tsx
 import { HubSpotFormBlock } from "./components/hubspot-form"
-// ...
-case "hubspotFormBlock":
-  return <HubSpotFormBlock block={block} />
+// ...inside blockRegistry:
+hubspotFormBlock: {
+  render: (block) => <HubSpotFormBlock block={block} />,
+  isEmpty: (block) => !block.form,
+},
 ```
 
+`isEmpty` is what makes an unconfigured block leave no padded gap behind, and
+keeps it from claiming an anchor id — prefer it over the early `return null`
+above, which the renderer cannot see before it wraps the block.
+
 ## 6. Regenerate types + verify
 
 ```bash
 bun run sanity:typegen   # regenerates sanity.types.ts so PageBuilderBlock includes the block
 bun typecheck
+bun lint
 ```
 
 `bun typecheck` must pass. The page query already spreads dereferenced block

package/src/agent-skills/ketch-consent-check/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: ketch-consent-check
+description: >-
+  Gate a tracking or third-party script behind Ketch consent, using the
+  project's single consent helper. Use when the user asks to "add
+  GTM/PostHog/Claydar/Segment/Hotjar/Clarity", "wire up analytics", "add the
+  tracking script", "fire this only with consent", "check consent before
+  loading", "make tracking respect consent", "gate this behind cookie consent",
+  "stop tracking when someone opts out", or "revoking consent doesn't stop
+  tracking". Installing Ketch itself is the `ketch-consent-setup` skill.
+---
+
+# Check consent before firing anything
+
+There is exactly one way to ask whether tracking is allowed. Never read
+`window.ketch`, `window.semaphore`, cookies or `localStorage` anywhere else —
+that is how a codebase ends up with five slightly different, silently wrong
+checks and no way to audit them.
+
+Read each file first and adapt to its actual shape — do not blindly
+pattern-match. If an anchor below is missing, stop and report it rather than
+guessing.
+
+## 0. Preconditions
+
+- `lib/integrations/ketch/` exists. If it doesn't, the consent gate isn't
+  installed — stop and run the `ketch-consent-setup` skill first.
+- `lib/integrations/ketch/use-consent.ts` exports `useConsent`. If the helper
+  has a different shape than below, follow the real file, not this doc.
+
+## 1. Map the tracker to a category
+
+Categories are `essential`, `analytics` and `marketing`. Add the tracker to
+`TRACKER_CONSENT_CATEGORY` in `lib/integrations/ketch/categories.ts` so the
+mapping lives in one place and is reviewable:
+
+```ts
+export const TRACKER_CONSENT_CATEGORY = {
+  gtm: "analytics",
+  posthog: "analytics",
+  claydar: "marketing",
+} as const satisfies Record<string, ConsentCategory>
+```
+
+How to choose:
+
+| The tracker… | Category |
+| --- | --- |
+| measures traffic or behaviour (analytics, session replay, heatmaps) | `analytics` |
+| builds advertising profiles, retargets, or links identity across sites | `marketing` |
+| is required for the site to function (session, security, CSRF) | `essential` |
+
+`essential` is exempt from consent. Do not use it to sneak a tracker through —
+if it sends data to a vendor for measurement or advertising, it is not
+essential.
+
+When a tool does both (GTM firing ad tags, PostHog with ads integrations
+enabled), gate on the **stricter** category, or split it into two loaders.
+
+## 2. Write the loader
+
+```tsx
+"use client"
+
+import { useEffect } from "react"
+import { useConsent } from "@/lib/integrations/ketch/use-consent"
+
+export const PostHogLoader = () => {
+  const { hasConsent } = useConsent()
+
+  useEffect(() => {
+    if (!hasConsent("analytics")) return
+
+    const posthog = startPostHog()
+    return () => posthog.shutdown()
+  }, [hasConsent])
+
+  return null
+}
+```
+
+Mount it in the same layout as `KetchConsentScript` — the one that renders the
+site chrome, typically `app/(content)/layout.tsx`, not the root layout. A
+tracker mounted above the CMP would run on admin routes where Ketch never
+loads, and `hasConsent` would sit at `false` forever.
+
+Three things make this correct, and all three are load-bearing:
+
+- **`hasConsent` returns `false` until Ketch resolves.** A tracker written this
+  way cannot fire before consent. Do not add an "optimistic" path, a timeout
+  fallback, or a "load it disabled and enable later" variant.
+- **The cleanup function is what makes revocation work.** When the visitor turns
+  a category off, `hasConsent` changes, the effect re-runs, and the cleanup
+  tears the tracker down — no reload. Without a real cleanup, revoking consent
+  silently keeps collecting, which is the actual compliance failure.
+- **The dependency is `hasConsent`, not `granted`.** `hasConsent` is stable
+  between consent changes, so the effect doesn't thrash.
+
+`useConsent()` also returns `granted`, `isResolved`, `jurisdiction` and
+`openPreferences()`.
+
+### If the SDK has no teardown
+
+Some tags can't be unloaded. Then do not load it inside the effect body at all:
+
+```tsx
+useEffect(() => {
+  if (!hasConsent("analytics")) return
+
+  let cancelled = false
+  const load = async () => {
+    const mod = await import("some-sdk")
+    if (cancelled) return
+    mod.init()
+    return mod
+  }
+  const pending = load()
+
+  return () => {
+    cancelled = true
+    pending.then((mod) => mod?.optOut())
+  }
+}, [hasConsent])
+```
+
+If there is no `optOut`, no `shutdown`, and no way to stop it, say so
+explicitly rather than shipping a gate that only works one way — the vendor may
+need to be swapped or fronted by a server-side proxy.
+
+## 3. Scripts outside React
+
+Subscribe to the same store — same default-deny semantics, same live updates:
+
+```ts
+import { consentStore } from "@/lib/integrations/ketch/consent-store"
+
+const unsubscribe = consentStore.subscribe(() => {
+  if (consentStore.hasConsent("marketing")) startClaydar()
+  else stopClaydar()
+})
+```
+
+`consentStore.hasConsent(category)` reads the current snapshot;
+`consentStore.subscribe(fn)` fires on every change and returns an unsubscribe.
+
+## 4. Do not
+
+- **Do not inject the tag unconditionally and "configure consent mode" inside
+  it.** The tag must not load at all without consent. A tag that loads and
+  self-restricts still opens a connection and often still sets cookies.
+- **Do not gate on `isResolved` alone.** That only says Ketch answered, not that
+  the visitor said yes.
+- **Do not add a second source of truth** (own cookie, a context seeded on the
+  server, a `useState` copy). Ketch already persists across navigation and
+  reloads; two sources drift and the bug is invisible.
+- **Do not read the Ketch purpose code directly** (`"targeted_advertising"`).
+  Go through the category names so a purpose rename is a one-line change.
+- **Do not gate with `dynamic()` / `next/script` alone.** Deferring a script is
+  not consent — it still loads.
+
+## 5. Verify
+
+```bash
+bun run typecheck && bun run lint && bun run build
+```
+
+Then in the browser, on a page that renders the footer (in a Sanity
+page-builder project `/` often 404s and the 404 has no footer — use a real
+slug):
+
+1. **Nothing fires before consent.** Fresh profile or cleared storage, open the
+   Network tab, filter by the vendor's domain, load the page → zero requests.
+   This is the acceptance criterion; check it per tracker, not once.
+2. **Accepting starts it.** Accept in the banner → the vendor's request appears
+   without a reload.
+3. **Revoking stops it.** Open preferences from the footer, turn the category
+   off → no further requests, still without a reload. This is what proves the
+   cleanup is wired; it is the step most likely to be silently broken.
+4. **It survives a reload.** Reload and confirm the choice held, and that the
+   tracker's state matches it.
+
+If step 3 passes only after a reload, the effect cleanup is missing or the
+tracker was loaded outside the effect. Fix that, don't document it as a
+limitation.
+
+## Region note
+
+The helper defaults to denied until Ketch confirms, so trackers stay off even
+in opt-out jurisdictions until the consent record arrives. That is stricter
+than the law requires and intentional — do not "optimise" it away. The
+region-by-region table lives with the project's Ketch documentation.
+
+Steps 2 and 3 of Verify need an explicit Accept/Reject to test, which only
+opt-in jurisdictions (EEA/UK, California, Quebec) show. From a default
+(notice-only) or opt-out region, consent is auto-granted with no banner
+interaction — append `?ketch_jurisdiction=gdpr` to the URL to test the real
+gated behaviour instead of assuming it's broken.