@cavuno/board 1.26.0 → 1.27.0

package/dist/sitemap.mjs

@@ -0,0 +1,330 @@
+// src/sitemap/xml.ts
+var SITEMAP_BUCKETS = [
+  "marketing",
+  "jobs-categories",
+  "jobs-skills",
+  "jobs-locations",
+  "jobs-details",
+  "companies",
+  "salaries",
+  "blog"
+];
+var SITEMAP_CHUNK_SIZE = 45e3;
+function xmlEscape(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function bucketFilename(bucket, chunkIndex = 0) {
+  const suffix = chunkIndex > 0 ? `-${chunkIndex + 1}` : "";
+  return `${bucket}${suffix}.xml`;
+}
+function parseBucketFilename(filename) {
+  if (!filename.endsWith(".xml")) return null;
+  const stem = filename.slice(0, -".xml".length);
+  const chunkMatch = stem.match(/^(.+?)-(\d+)$/);
+  if (chunkMatch) {
+    const candidate = chunkMatch[1];
+    const chunkNumber = Number.parseInt(chunkMatch[2] ?? "", 10);
+    if (SITEMAP_BUCKETS.includes(candidate) && Number.isFinite(chunkNumber) && chunkNumber >= 2) {
+      return { bucket: candidate, chunkIndex: chunkNumber - 1 };
+    }
+  }
+  if (SITEMAP_BUCKETS.includes(stem)) {
+    return { bucket: stem, chunkIndex: 0 };
+  }
+  return null;
+}
+function chunk(items, size) {
+  if (items.length === 0) return [];
+  if (items.length <= size) return [[...items]];
+  const out = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}
+var XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8"?>\n';
+var SITEMAP_NS = "http://www.sitemaps.org/schemas/sitemap/0.9";
+var IMAGE_NS = "http://www.google.com/schemas/sitemap-image/1.1";
+function lastmod(value) {
+  const serialized = value instanceof Date ? value.toISOString() : value;
+  return `<lastmod>${xmlEscape(serialized)}</lastmod>
+`;
+}
+function renderUrlset(entries) {
+  const normalized = entries.map(
+    (entry) => typeof entry === "string" ? { url: entry } : entry
+  );
+  const hasImages = normalized.some((entry) => (entry.images?.length ?? 0) > 0);
+  const namespaces = [`xmlns="${SITEMAP_NS}"`];
+  if (hasImages) {
+    namespaces.push(`xmlns:image="${IMAGE_NS}"`);
+  }
+  let xml = XML_DECLARATION + `<urlset ${namespaces.join(" ")}>
+`;
+  for (const entry of normalized) {
+    xml += "<url>\n";
+    xml += `<loc>${xmlEscape(entry.url)}</loc>
+`;
+    if (entry.images?.length) {
+      for (const image of entry.images) {
+        xml += `<image:image>
+<image:loc>${xmlEscape(image)}</image:loc>
+</image:image>
+`;
+      }
+    }
+    if (entry.lastModified) {
+      xml += lastmod(entry.lastModified);
+    }
+    xml += "</url>\n";
+  }
+  xml += "</urlset>\n";
+  return xml;
+}
+function renderSitemapIndex(entries) {
+  let xml = XML_DECLARATION + `<sitemapindex xmlns="${SITEMAP_NS}">
+`;
+  for (const raw of entries) {
+    const entry = typeof raw === "string" ? { url: raw } : raw;
+    xml += "<sitemap>\n";
+    xml += `<loc>${xmlEscape(entry.url)}</loc>
+`;
+    if (entry.lastModified) {
+      xml += lastmod(entry.lastModified);
+    }
+    xml += "</sitemap>\n";
+  }
+  xml += "</sitemapindex>\n";
+  return xml;
+}
+
+// src/pagination.ts
+function paginate(listFn, query, options) {
+  async function* pages() {
+    let current = query;
+    for (; ; ) {
+      const page = await listFn(current, options);
+      yield page;
+      if (!page.hasMore || page.nextCursor === null) return;
+      const { offset: _offset, ...rest } = current ?? {};
+      current = { ...rest, cursor: page.nextCursor };
+    }
+  }
+  return {
+    pages,
+    async *[Symbol.asyncIterator]() {
+      for await (const page of pages()) {
+        yield* page.data;
+      }
+    },
+    async toArray({ limit }) {
+      const items = [];
+      for await (const page of pages()) {
+        items.push(...page.data);
+        if (items.length >= limit) break;
+      }
+      return items.slice(0, limit);
+    }
+  };
+}
+
+// src/sitemap/walker.ts
+var MIN_JOBS_PER_INDEXED_PAGE = 5;
+var MAX_PAGES = 200;
+async function drainPages(pages) {
+  const acc = [];
+  let pageCount = 0;
+  for await (const page of pages) {
+    acc.push(...page.data);
+    pageCount += 1;
+    if (pageCount >= MAX_PAGES) {
+      if (page.hasMore) {
+        console.warn(
+          `[sitemap] hit the ${MAX_PAGES}-page pagination cap \u2014 output may be truncated`
+        );
+      }
+      break;
+    }
+  }
+  return acc;
+}
+var PAGE = 100;
+var OFFSET_CONCURRENCY = 8;
+var OFFSET_CEILING = 1e4;
+async function enumerateByOffset(fetchAt, fallback) {
+  const first = await fetchAt(0);
+  if (first.count === void 0) return fallback();
+  const all = [...first.data];
+  const ceiling = Math.min(first.count, OFFSET_CEILING);
+  const offsets = [];
+  for (let o = PAGE; o < ceiling; o += PAGE) offsets.push(o);
+  for (let i = 0; i < offsets.length; i += OFFSET_CONCURRENCY) {
+    const pages = await Promise.all(
+      offsets.slice(i, i + OFFSET_CONCURRENCY).map(fetchAt)
+    );
+    for (const page of pages) all.push(...page.data);
+  }
+  if (first.count > OFFSET_CEILING) {
+    console.warn(
+      `[sitemap] count ${first.count} exceeds the ${OFFSET_CEILING} offset ceiling \u2014 tail not enumerated (needs cursor/bulk support).`
+    );
+  }
+  return all;
+}
+function enumerateJobs(board) {
+  return enumerateByOffset(
+    (offset) => board.jobs.list({ limit: PAGE, offset }),
+    () => drainPages(paginate(board.jobs.list, { limit: PAGE }).pages())
+  );
+}
+function enumerateCompanies(board) {
+  return enumerateByOffset(
+    (offset) => board.companies.list({ limit: PAGE, offset }),
+    () => drainPages(paginate(board.companies.list, { limit: PAGE }).pages())
+  );
+}
+async function listedBuckets(board) {
+  const { features } = await board.context();
+  return SITEMAP_BUCKETS.filter((b) => b !== "blog" || features.blog);
+}
+async function buildBucketUrls(board, origin, bucket) {
+  switch (bucket) {
+    case "marketing":
+      return marketing(board, origin);
+    case "jobs-categories":
+      return jobsTaxonomy(board, origin, "categories");
+    case "jobs-skills":
+      return jobsTaxonomy(board, origin, "skills");
+    case "jobs-locations":
+      return jobsLocations(board, origin);
+    case "jobs-details":
+      return jobDetails(board, origin);
+    case "companies":
+      return companies(board, origin);
+    case "salaries":
+      return salaries(board, origin);
+    case "blog":
+      return blog(board, origin);
+  }
+}
+async function marketing(board, origin) {
+  const { features } = await board.context();
+  const urls = [
+    `${origin}/`,
+    `${origin}/jobs`,
+    `${origin}/about`,
+    `${origin}/privacy-policy`,
+    `${origin}/terms-of-service`,
+    `${origin}/cookie-policy`
+  ];
+  if (features.impressum) urls.push(`${origin}/impressum`);
+  if (features.talentDirectory) urls.push(`${origin}/talent`);
+  if (features.employers) urls.push(`${origin}/employers`);
+  return urls;
+}
+async function jobsTaxonomy(board, origin, kind) {
+  const jobs = await enumerateJobs(board);
+  const counts = /* @__PURE__ */ new Map();
+  for (const job of jobs) {
+    const slugs = new Set(
+      (kind === "categories" ? job.categories : job.skills).map((t) => t.slug)
+    );
+    for (const slug of slugs) counts.set(slug, (counts.get(slug) ?? 0) + 1);
+  }
+  const prefix = kind === "categories" ? `${origin}/jobs` : `${origin}/jobs/skills`;
+  return [...counts.entries()].filter(([, n]) => n >= MIN_JOBS_PER_INDEXED_PAGE).map(([slug]) => slug).sort().map((slug) => `${prefix}/${slug}`);
+}
+async function jobsLocations(board, origin) {
+  const { language } = await board.context();
+  const { data } = await board.salaries.locations.list({ locale: language });
+  return data.filter((l) => l.jobCount >= MIN_JOBS_PER_INDEXED_PAGE).map((l) => l.placeSlug).sort().map((slug) => `${origin}/jobs/locations/${slug}`);
+}
+async function jobDetails(board, origin) {
+  const jobs = await enumerateJobs(board);
+  const seen = /* @__PURE__ */ new Set();
+  for (const job of jobs) {
+    if (!job.company?.slug || !job.slug) continue;
+    seen.add(`${origin}/companies/${job.company.slug}/jobs/${job.slug}`);
+  }
+  return [...seen].sort();
+}
+async function companies(board, origin) {
+  const [list, markets] = await Promise.all([
+    enumerateCompanies(board),
+    board.companies.markets()
+  ]);
+  const urls = [`${origin}/companies`];
+  for (const company of list) urls.push(`${origin}/companies/${company.slug}`);
+  for (const market of markets.data) {
+    urls.push(`${origin}/companies/markets/${market.slug}`);
+  }
+  return urls;
+}
+async function salaries(board, origin) {
+  const { language } = await board.context();
+  const [salaryCompanies, titles, skills, locations] = await Promise.all([
+    board.salaries.companies.list(),
+    board.salaries.titles.list({ locale: language }),
+    board.salaries.skills.list({ locale: language }),
+    board.salaries.locations.list({ locale: language })
+  ]);
+  if (!salaryCompanies.data.length && !titles.data.length && !skills.data.length && !locations.data.length) {
+    return [];
+  }
+  const urls = [`${origin}/salaries`];
+  if (salaryCompanies.data.length) {
+    urls.push(`${origin}/salaries/companies`);
+    for (const c of salaryCompanies.data) {
+      urls.push(`${origin}/companies/${c.companySlug}/salaries`);
+    }
+  }
+  if (titles.data.length) {
+    urls.push(`${origin}/salaries/titles`);
+    for (const t of titles.data)
+      urls.push(`${origin}/salaries/titles/${t.slug}`);
+  }
+  if (skills.data.length) {
+    urls.push(`${origin}/salaries/skills`);
+    for (const s of skills.data)
+      urls.push(`${origin}/salaries/skills/${s.slug}`);
+  }
+  if (locations.data.length) {
+    urls.push(`${origin}/salaries/locations`);
+    for (const l of locations.data) {
+      urls.push(`${origin}/salaries/locations/${l.placeSlug}`);
+    }
+  }
+  return urls;
+}
+async function blog(board, origin) {
+  const posts = await drainPages(
+    paginate(board.blog.posts.list, { limit: 100 }).pages()
+  );
+  const urls = [`${origin}/blog`];
+  const tagSlugs = /* @__PURE__ */ new Set();
+  const authorSlugs = /* @__PURE__ */ new Set();
+  for (const post of posts) {
+    urls.push(`${origin}/blog/${post.slug}`);
+    for (const tag of post.tags) tagSlugs.add(tag.slug);
+    for (const author of post.authors) authorSlugs.add(author.slug);
+  }
+  for (const slug of [...tagSlugs].sort())
+    urls.push(`${origin}/blog/tag/${slug}`);
+  for (const slug of [...authorSlugs].sort()) {
+    urls.push(`${origin}/blog/author/${slug}`);
+  }
+  return urls;
+}
+export {
+  MIN_JOBS_PER_INDEXED_PAGE,
+  SITEMAP_BUCKETS,
+  SITEMAP_CHUNK_SIZE,
+  bucketFilename,
+  buildBucketUrls,
+  chunk,
+  listedBuckets,
+  parseBucketFilename,
+  renderSitemapIndex,
+  renderUrlset,
+  xmlEscape
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavuno/board",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "Typed isomorphic client for the Cavuno Board API",
   "license": "MIT",
   "type": "commonjs",
@@ -60,6 +60,26 @@
         "default": "./dist/theme.js"
       }
     },
+    "./seo": {
+      "import": {
+        "types": "./dist/seo.d.mts",
+        "default": "./dist/seo.mjs"
+      },
+      "require": {
+        "types": "./dist/seo.d.ts",
+        "default": "./dist/seo.js"
+      }
+    },
+    "./sitemap": {
+      "import": {
+        "types": "./dist/sitemap.d.mts",
+        "default": "./dist/sitemap.mjs"
+      },
+      "require": {
+        "types": "./dist/sitemap.d.ts",
+        "default": "./dist/sitemap.js"
+      }
+    },
     "./skills": {
       "import": {
         "types": "./dist/skills.d.mts",

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

@@ -0,0 +1,180 @@
+---
+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.
+---
+
+# SEO: structured data + head builders
+
+`@cavuno/board/seo` emits the exact structured data the hosted board emits —
+golden-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.
+
+## When to use
+
+- 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).
+
+## When not to use
+
+- 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).
+
+## Job-posting JSON-LD (the detail page)
+
+`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).
+
+```ts snippet
+import { createJobPostingJsonLd } from '@cavuno/board/seo';
+
+const { name, logoUrl } = await board.context();
+const job = await board.jobs.retrieve('senior-chef');
+
+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.
+```
+
+## Breadcrumbs
+
+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:
+
+```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 tracked API gap 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.

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

@@ -0,0 +1,147 @@
+---
+name: cavuno-board-sitemap
+description: Build the board's sitemap with @cavuno/board/sitemap — the hosted 8-bucket model (marketing, jobs taxonomies, job details, companies, salaries, blog), 45k chunking, XML rendering, and the buildBucketUrls walker that enumerates a board's content through the BoardSdk with the hosted SEO rules built in (feature gating, ≥5-job thin-content floor, pagination backstops). Use when adding /sitemap.xml and /sitemap/:file routes to a custom board frontend.
+---
+
+# Sitemap: the 8-bucket model
+
+`@cavuno/board/sitemap` ships the hosted board's sitemap architecture: a
+sitemap INDEX at `/sitemap.xml` pointing at one file per content bucket,
+each an ordinary `<urlset>`. The XML byte layout and the bucket rules are
+golden-tested against the hosted implementation, so a custom frontend's
+sitemap corpus lines up bucket-for-bucket with what cavuno.com would emit.
+
+Two tiers, use both:
+
+- **XML primitives** (pure, no I/O): `SITEMAP_BUCKETS`,
+  `SITEMAP_CHUNK_SIZE` (45,000), `chunk`, `bucketFilename` /
+  `parseBucketFilename`, `renderUrlset`, `renderSitemapIndex`.
+- **The walker** (opinionated, injected I/O): `listedBuckets(board)` and
+  `buildBucketUrls(board, origin, bucket)` take your `BoardSdk` instance
+  and return plain URL strings with the hosted rules applied — you never
+  re-derive the SEO policy.
+
+## When to use
+
+- Adding `/sitemap.xml` + `/sitemap/:file` routes to a board frontend.
+- Deciding which listing pages deserve indexing (the walker already does).
+
+## When not to use
+
+- Structured data / meta tags — `cavuno-board-seo`.
+- Feeds (RSS/Atom) — app-owned.
+
+## The two routes
+
+The index lists one entry per bucket; each bucket route parses its filename
+back to a bucket + chunk and renders a urlset. Empty buckets render a valid
+empty urlset — only `blog` is dropped from the index when the feature is
+off (`listedBuckets` handles that).
+
+```ts snippet
+import {
+  SITEMAP_CHUNK_SIZE,
+  buildBucketUrls,
+  bucketFilename,
+  chunk,
+  listedBuckets,
+  parseBucketFilename,
+  renderSitemapIndex,
+  renderUrlset,
+} from '@cavuno/board/sitemap';
+
+// GET /sitemap.xml — one <sitemap> per listed bucket (plus -2, -3… chunks).
+const origin = 'https://jobs.example.com';
+const buckets = await listedBuckets(board);
+const locs: string[] = [];
+for (const bucket of buckets) {
+  const urls = await buildBucketUrls(board, origin, bucket);
+  const chunks = chunk(urls, SITEMAP_CHUNK_SIZE);
+  for (let i = 0; i < Math.max(chunks.length, 1); i += 1) {
+    locs.push(`${origin}/sitemap/${bucketFilename(bucket, i)}`);
+  }
+}
+return xmlResponse(renderSitemapIndex(locs));
+```
+
+```ts snippet
+// GET /sitemap/:file — parse, enumerate, slice, render. Unknown file → 404.
+const parsed = parseBucketFilename(params.file);
+if (!parsed) return notFound();
+const urls = await buildBucketUrls(board, origin, parsed.bucket);
+const page = chunk(urls, SITEMAP_CHUNK_SIZE)[parsed.chunkIndex] ?? [];
+return xmlResponse(renderUrlset(page));
+```
+
+`renderUrlset` also accepts `{ url, lastModified?, images? }` entries when
+you have per-URL dates (a `Date` serializes to ISO 8601). `changefreq` and
+`priority` are deliberately unsupported — the hosted board never emits them.
+
+## robots.txt
+
+Point crawlers at the index — one line, at the site root:
+
+```txt
+Sitemap: https://jobs.example.com/sitemap.xml
+```
+
+## The rules the walker enforces (don't re-implement)
+
+- **Thin-content floor**: a category/skill/location listing page is emitted
+  only with ≥5 distinct jobs (`MIN_JOBS_PER_INDEXED_PAGE`) — below that,
+  the page is thin content that wastes crawl budget.
+- **Feature gating**: `/impressum`, `/talent`, `/employers` appear in the
+  marketing bucket only when `context().features` enables them; the blog
+  bucket exists only when `features.blog` is on.
+- **Board language**: salary-index reads pass `context().language`, so a
+  non-English board emits board-language canonical salary slugs (jobs,
+  companies, and blog slugs arrive canonical on the wire already). No
+  locale parameter to thread.
+- **Pagination backstops**: offset enumeration runs in parallel when the
+  envelope carries `count` (capped at the API's 10,000-offset window);
+  cursor walks cap at 200 pages. Both warn on truncation instead of
+  hanging a build.
+
+## Stable order caveat (cursor walks)
+
+Cursor and offset enumeration order can shift between requests on a large,
+churning board — two chunk requests may see slightly different orderings.
+That is harmless for a sitemap (URLs dedupe and the ≥5 counts are a
+heuristic), but do NOT reuse the walker as a general "export all jobs in
+order" tool; for stable ordering, pass an explicit sort/query to
+`board.jobs.list` yourself.
+
+## Named exclusions (v1 API gap — not bugs)
+
+Two URL families the HOSTED sitemap emits are deliberately absent, because
+v1 exposes them only per-slug and a bulk-pairs endpoint doesn't exist yet
+(per-slug N+1 is ~1k+ calls per build):
+
+- Cross-axis salary pages (title×location, skill×location,
+  company×category, and the per-entity `/locations` · `/titles` ·
+  `/skills` salary index pages).
+- Jobs place×category / place×skill combination listings.
+
+Both stay reachable through internal links. When the bulk endpoint lands,
+the walker picks them up additively — don't hand-enumerate them.
+
+## Anti-patterns
+
+```ts snippet
+// NEVER emit every taxonomy page unconditionally — the ≥5-job floor exists
+// to keep thin pages out of the index:
+for (const c of allCategories) urls.push(`${origin}/jobs/${c.slug}`); // wrong
+// NEVER hand-build the XML with a template string per route — use
+// renderUrlset/renderSitemapIndex (escaping + byte-parity with hosted).
+// NEVER fetch every salary detail page to discover cross-axis pairs (N+1).
+```
+
+## Verify
+
+- [ ] `/sitemap.xml` lists one file per bucket (no `blog` entry when the
+      feature is off) and every listed file returns valid XML.
+- [ ] A category with 4 jobs is absent from `jobs-categories.xml`; one with
+      5 is present.
+- [ ] `jobs-details-2.xml` style chunk names round-trip through
+      `parseBucketFilename` and unknown filenames 404.
+- [ ] robots.txt points at `/sitemap.xml`.