From 0a720e6cd76b104462495589bed636c4a81c6ea5 Mon Sep 17 00:00:00 2001
From: Andrei Ivascu <7030530+aivascu@users.noreply.github.com>
Date: Tue, 8 Sep 2026 11:27:48 +0300
Subject: [PATCH] Add article updated dates, sitemap lastmod, and Atom feed.

---
 .gitignore                                   |   1 +
 site/app/composables/usePageSeo.ts           |  47 +++--
 site/app/pages/docs/[...slug].vue            |  15 +-
 site/app/utils/formatDocsUpdatedDate.ts      |  69 +++++++
 site/content.config.ts                       |   5 +
 site/content/docs/5.integrations/10.tunit.md |   1 +
 site/nuxt.config.ts                          |   7 +
 site/public/llms.txt                         |   3 +-
 site/readme.md                               |  24 ++-
 site/scripts/prepare-agent-assets.mjs        | 207 +++++++++++++++----
 site/tests/formatDocsUpdatedDate.test.ts     |  38 ++++
 11 files changed, 355 insertions(+), 62 deletions(-)
 create mode 100644 site/app/utils/formatDocsUpdatedDate.ts
 create mode 100644 site/tests/formatDocsUpdatedDate.test.ts

diff --git a/.gitignore b/.gitignore
index 7102b4e..ff4813e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,7 @@ site/public/api-meta/
 site/public/api-catalog.json
 site/public/docs-markdown/
 site/public/sitemap.xml
+site/public/feed.xml
 
 ###############
 # OS / IDE
diff --git a/site/app/composables/usePageSeo.ts b/site/app/composables/usePageSeo.ts
index e1ed9bf..d818244 100644
--- a/site/app/composables/usePageSeo.ts
+++ b/site/app/composables/usePageSeo.ts
@@ -12,6 +12,8 @@ type PageSeoOptions = {
   title?: MaybeRefOrGetter<string | undefined>
   description?: MaybeRefOrGetter<string | undefined>
   image?: MaybeRefOrGetter<string | undefined>
+  /** Article last-updated day as YYYY-MM-DD (adds Open Graph modified_time). */
+  modifiedTime?: MaybeRefOrGetter<string | undefined>
 }
 
 export function usePageSeo(options: PageSeoOptions = {}) {
@@ -22,23 +24,38 @@ export function usePageSeo(options: PageSeoOptions = {}) {
   const description = computed(() => toValue(options.description) ?? DEFAULT_DESCRIPTION)
   const image = computed(() => `${siteUrl}${toValue(options.image) ?? DEFAULT_OG_IMAGE}`)
   const url = computed(() => `${siteUrl}${route.path}`)
+  const modifiedTime = computed(() => {
+    const day = toValue(options.modifiedTime)
+    return day ? `${day}T00:00:00.000Z` : undefined
+  })
 
   useHead({
     title,
-    meta: computed(() => [
-      { name: 'description', content: description.value, tagPriority: seoTagPriority },
-      { property: 'og:site_name', content: 'AutoFixture', tagPriority: seoTagPriority },
-      { property: 'og:type', content: 'website', tagPriority: seoTagPriority },
-      { property: 'og:title', content: title.value, tagPriority: seoTagPriority },
-      { property: 'og:description', content: description.value, tagPriority: seoTagPriority },
-      { property: 'og:image', content: image.value, tagPriority: seoTagPriority },
-      { property: 'og:image:width', content: OG_IMAGE_WIDTH, tagPriority: seoTagPriority },
-      { property: 'og:image:height', content: OG_IMAGE_HEIGHT, tagPriority: seoTagPriority },
-      { property: 'og:url', content: url.value, tagPriority: seoTagPriority },
-      { name: 'twitter:card', content: 'summary_large_image', tagPriority: seoTagPriority },
-      { name: 'twitter:title', content: title.value, tagPriority: seoTagPriority },
-      { name: 'twitter:description', content: description.value, tagPriority: seoTagPriority },
-      { name: 'twitter:image', content: image.value, tagPriority: seoTagPriority },
-    ]),
+    meta: computed(() => {
+      const tags = [
+        { name: 'description', content: description.value, tagPriority: seoTagPriority },
+        { property: 'og:site_name', content: 'AutoFixture', tagPriority: seoTagPriority },
+        { property: 'og:type', content: 'website', tagPriority: seoTagPriority },
+        { property: 'og:title', content: title.value, tagPriority: seoTagPriority },
+        { property: 'og:description', content: description.value, tagPriority: seoTagPriority },
+        { property: 'og:image', content: image.value, tagPriority: seoTagPriority },
+        { property: 'og:image:width', content: OG_IMAGE_WIDTH, tagPriority: seoTagPriority },
+        { property: 'og:image:height', content: OG_IMAGE_HEIGHT, tagPriority: seoTagPriority },
+        { property: 'og:url', content: url.value, tagPriority: seoTagPriority },
+        { name: 'twitter:card', content: 'summary_large_image', tagPriority: seoTagPriority },
+        { name: 'twitter:title', content: title.value, tagPriority: seoTagPriority },
+        { name: 'twitter:description', content: description.value, tagPriority: seoTagPriority },
+        { name: 'twitter:image', content: image.value, tagPriority: seoTagPriority },
+      ]
+
+      if (modifiedTime.value) {
+        tags.push(
+          { property: 'article:modified_time', content: modifiedTime.value, tagPriority: seoTagPriority },
+          { property: 'og:updated_time', content: modifiedTime.value, tagPriority: seoTagPriority },
+        )
+      }
+
+      return tags
+    }),
   })
 }
diff --git a/site/app/pages/docs/[...slug].vue b/site/app/pages/docs/[...slug].vue
index 51b34ea..5f74f7a 100644
--- a/site/app/pages/docs/[...slug].vue
+++ b/site/app/pages/docs/[...slug].vue
@@ -1,4 +1,6 @@
 <script setup lang="ts">
+import { formatDocsUpdatedDate } from '~/utils/formatDocsUpdatedDate'
+
 definePageMeta({
   layout: 'docs',
 })
@@ -20,9 +22,12 @@ const { data: surround } = await useAsyncData(
   () => queryCollectionItemSurroundings('docs', docsPath.value),
 )
 
+const updated = computed(() => formatDocsUpdatedDate(page.value?.updated))
+
 usePageSeo({
   title: () => page.value?.title,
   description: () => page.value?.description,
+  modifiedTime: () => updated.value?.iso,
 })
 
 const tocLinks = computed(() => page.value?.body?.toc?.links ?? [])
@@ -33,7 +38,15 @@ const tocLinks = computed(() => page.value?.body?.toc?.links ?? [])
     <UPageHeader
       :title="page.title"
       :description="page.description"
-    />
+    >
+      <p
+        v-if="updated"
+        class="mt-3 text-sm text-muted"
+      >
+        Updated
+        <time :datetime="updated.iso">{{ updated.label }}</time>
+      </p>
+    </UPageHeader>
 
     <UPageBody>
       <ContentRenderer
diff --git a/site/app/utils/formatDocsUpdatedDate.ts b/site/app/utils/formatDocsUpdatedDate.ts
new file mode 100644
index 0000000..fdf5dbc
--- /dev/null
+++ b/site/app/utils/formatDocsUpdatedDate.ts
@@ -0,0 +1,69 @@
+/**
+ * Normalize and format docs frontmatter `updated` (YYYY-MM-DD or Date).
+ */
+
+export type DocsUpdatedDate = {
+  /** Calendar date as YYYY-MM-DD (UTC). */
+  iso: string
+  /** Human-readable label, e.g. "March 15, 2026". */
+  label: string
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, '0')
+}
+
+/** Return YYYY-MM-DD for a valid calendar date, or undefined. */
+export function toDocsUpdatedIso(value: unknown): string | undefined {
+  if (value === undefined || value === null || value === '') {
+    return undefined
+  }
+
+  if (value instanceof Date && !Number.isNaN(value.getTime())) {
+    return `${value.getUTCFullYear()}-${pad2(value.getUTCMonth() + 1)}-${pad2(value.getUTCDate())}`
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed)
+    if (!match) {
+      return undefined
+    }
+    const year = Number(match[1])
+    const month = Number(match[2])
+    const day = Number(match[3])
+    const probe = new Date(Date.UTC(year, month - 1, day))
+    if (
+      probe.getUTCFullYear() !== year
+      || probe.getUTCMonth() !== month - 1
+      || probe.getUTCDate() !== day
+    ) {
+      return undefined
+    }
+    return trimmed
+  }
+
+  return undefined
+}
+
+/**
+ * Format an `updated` value for display and `<time datetime>`.
+ * Uses the en-US long date style (month day, year).
+ */
+export function formatDocsUpdatedDate(value: unknown): DocsUpdatedDate | undefined {
+  const iso = toDocsUpdatedIso(value)
+  if (!iso) {
+    return undefined
+  }
+
+  const [year, month, day] = iso.split('-').map(Number)
+  const date = new Date(Date.UTC(year!, month! - 1, day!))
+  const label = new Intl.DateTimeFormat('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    timeZone: 'UTC',
+  }).format(date)
+
+  return { iso, label }
+}
diff --git a/site/content.config.ts b/site/content.config.ts
index bc331b4..0844f2a 100644
--- a/site/content.config.ts
+++ b/site/content.config.ts
@@ -17,6 +17,11 @@ export default defineContentConfig({
       },
       schema: z.object({
         description: z.string().optional(),
+        /**
+         * Last meaningful content update (calendar day).
+         * Prefer `YYYY-MM-DD` in frontmatter; YAML dates are also accepted.
+         */
+        updated: z.union([z.string(), z.date()]).optional(),
         /** Sidebar badge — string shortcut (`New`, `Updated`, `Preview`) or Nuxt UI BadgeProps. */
         badge: z.union([z.string(), z.number(), badgeObjectSchema]).optional(),
       }),
diff --git a/site/content/docs/5.integrations/10.tunit.md b/site/content/docs/5.integrations/10.tunit.md
index f87709a..f9ca0f6 100644
--- a/site/content/docs/5.integrations/10.tunit.md
+++ b/site/content/docs/5.integrations/10.tunit.md
@@ -1,6 +1,7 @@
 ---
 title: TUnit
 description: Use AutoDataSource, AutoArguments, and parameter attributes with TUnit test projects.
+updated: 2026-09-08
 badge:
   label: Preview
   color: warning
diff --git a/site/nuxt.config.ts b/site/nuxt.config.ts
index 9bcfa8c..a5112df 100644
--- a/site/nuxt.config.ts
+++ b/site/nuxt.config.ts
@@ -77,6 +77,13 @@ export default defineNuxtConfig({
           type: 'image/svg+xml',
           href: '/favicon.svg?v=2',
         },
+        {
+          key: 'docs-atom-feed',
+          rel: 'alternate',
+          type: 'application/atom+xml',
+          title: 'AutoFixture documentation',
+          href: '/feed.xml',
+        },
       ],
     },
   },
diff --git a/site/public/llms.txt b/site/public/llms.txt
index 31b25fa..52f271b 100644
--- a/site/public/llms.txt
+++ b/site/public/llms.txt
@@ -64,7 +64,8 @@ Slugs and version segments are lowercase. Package ids match the catalog (autofix
 - https://autofixture.com/api-meta/routes.json — all API HTML routes
 - https://autofixture.com/api-meta/{packageId}/{versionSegment}/toc.json — package TOC
 - https://autofixture.com/api-meta/{packageId}/{versionSegment}/search.json — searchable API snippets
-- https://autofixture.com/sitemap.xml — HTML and markdown URLs
+- https://autofixture.com/sitemap.xml — HTML and markdown URLs (`lastmod` when guides set `updated`)
+- https://autofixture.com/feed.xml — Atom feed of recently updated guides
 
 ## Optional
 
diff --git a/site/readme.md b/site/readme.md
index db5c9fb..8984c14 100644
--- a/site/readme.md
+++ b/site/readme.md
@@ -28,7 +28,8 @@ just site-generate   # runs prepare-agent-assets, then nuxt generate
 | `/api-markdown/**` | Raw API markdown (generated; not committed) |
 | `/llms.txt` | Agent discovery index |
 | `/robots.txt` | Crawler rules + sitemap pointer |
-| `/sitemap.xml` | Generated URL list (guides, docs-markdown, API) |
+| `/sitemap.xml` | Generated URL list (guides, docs-markdown, API); includes `lastmod` when set |
+| `/feed.xml` | Atom feed of guides that declare `updated` |
 
 API markdown is generated into `public/api-markdown` (not Nuxt Content). On API pages, the header shows the package and version from the API catalog.
 
@@ -37,13 +38,30 @@ API markdown is generated into `public/api-markdown` (not Nuxt Content). On API
 `scripts/prepare-agent-assets.mjs` (also `npm run prepare-agent-assets` / `pregenerate`):
 
 1. Mirrors `content/docs/**/*.md` → `public/docs-markdown/` with Nuxt-style paths (numeric prefixes stripped).
-2. Writes `public/sitemap.xml` from those guides plus `public/api-meta/routes.json` when present.
+2. Writes `public/sitemap.xml` from those guides plus `public/api-meta/routes.json` when present (`lastmod` from frontmatter `updated`).
+3. Writes `public/feed.xml` (Atom) for guides that set `updated`.
 
 Committed: `public/llms.txt`, `public/robots.txt`.
-Generated (gitignored): `public/docs-markdown/`, `public/sitemap.xml`.
+Generated (gitignored): `public/docs-markdown/`, `public/sitemap.xml`, `public/feed.xml`.
 
 Keep `llms.txt` in sync when you add major guide sections.
 
+## Article freshness (`updated`)
+
+Set `updated` in page frontmatter to a calendar day (`YYYY-MM-DD`). The docs page shows an "Updated …" line under the header, Open Graph gets `article:modified_time`, the sitemap gets `lastmod`, and the Atom feed includes the article.
+
+```yaml
+---
+title: Build DSL
+description: Use Build, With, Without, and OmitAutoProperties…
+updated: 2026-09-08
+---
+```
+
+Bump `updated` when you make a meaningful content change. Omit it when the day is unknown — the UI simply hides the line.
+
+Sidebar `badge: Updated` stays optional and explicit; it is not derived from `updated`.
+
 ## Sidebar badges
 
 Set an optional `badge` in page frontmatter to show a label next to the article in the docs sidebar (desktop and mobile). Badges are explicit — nothing is inferred from dates or git.
diff --git a/site/scripts/prepare-agent-assets.mjs b/site/scripts/prepare-agent-assets.mjs
index dc60865..f4fbb86 100644
--- a/site/scripts/prepare-agent-assets.mjs
+++ b/site/scripts/prepare-agent-assets.mjs
@@ -2,6 +2,7 @@
  * Prepare agent-facing static assets before `nuxt generate`:
  * - Mirror guide markdown to public/docs-markdown/ (URL-aligned paths)
  * - Write public/sitemap.xml (guides, docs-markdown, API routes when present)
+ * - Write public/feed.xml (Atom) from guides that declare `updated`
  *
  * Run from site/: node scripts/prepare-agent-assets.mjs
  * Or via npm pregenerate / just site-generate.
@@ -16,9 +17,12 @@ const contentDocs = path.join(siteRoot, 'content', 'docs')
 const publicDir = path.join(siteRoot, 'public')
 const docsMarkdownDir = path.join(publicDir, 'docs-markdown')
 const sitemapPath = path.join(publicDir, 'sitemap.xml')
+const feedPath = path.join(publicDir, 'feed.xml')
 const routesJsonPath = path.join(publicDir, 'api-meta', 'routes.json')
 
 const SITE_ORIGIN = 'https://autofixture.com'
+const FEED_TITLE = 'AutoFixture documentation'
+const FEED_ID = `${SITE_ORIGIN}/`
 
 /** Strip Nuxt Content-style numeric prefixes: "1.get-started" → "get-started" */
 function stripNumericPrefix(segment) {
@@ -69,33 +73,97 @@ function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true })
 }
 
+function escapeXml(value) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+/**
+ * @param {string} raw
+ * @returns {Record<string, string>}
+ */
+function parseSimpleFrontmatter(raw) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw)
+  if (!match) return {}
+
+  /** @type {Record<string, string>} */
+  const fields = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('-')) continue
+    // Skip nested object lines (badge:, indented keys)
+    if (/^\s/.test(line) || trimmed.endsWith(':')) continue
+    const sep = trimmed.indexOf(':')
+    if (sep <= 0) continue
+    const key = trimmed.slice(0, sep).trim()
+    let value = trimmed.slice(sep + 1).trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    fields[key] = value
+  }
+  return fields
+}
+
+/** @param {string} value */
+function toUpdatedIso(value) {
+  if (!value) return undefined
+  const trimmed = value.trim()
+  // YAML may emit 2026-09-08 or 2026-09-08T00:00:00.000Z
+  const day = trimmed.slice(0, 10)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(day)) return undefined
+  return day
+}
+
+/**
+ * @typedef {{
+ *   htmlPath: string
+ *   markdownPath: string
+ *   title?: string
+ *   description?: string
+ *   updated?: string
+ * }} GuideAsset
+ */
+
 /**
- * @returns {{ htmlPaths: string[], markdownPaths: string[] }}
+ * @returns {GuideAsset[]}
  */
 function mirrorDocsMarkdown() {
   removeIfExists(docsMarkdownDir)
   ensureDir(docsMarkdownDir)
 
-  /** @type {string[]} */
-  const htmlPaths = []
-  /** @type {string[]} */
-  const markdownPaths = []
+  /** @type {GuideAsset[]} */
+  const guides = []
 
   const files = walkMarkdownFiles(contentDocs)
   for (const rel of files) {
+    const sourcePath = path.join(contentDocs, rel)
+    const raw = fs.readFileSync(sourcePath, 'utf8')
+    const frontmatter = parseSimpleFrontmatter(raw)
     const publicRel = toPublicDocsRel(rel)
     const dest = path.join(docsMarkdownDir, publicRel)
     ensureDir(path.dirname(dest))
-    fs.copyFileSync(path.join(contentDocs, rel), dest)
+    fs.copyFileSync(sourcePath, dest)
 
-    const withoutExt = publicRel.replace(/\.md$/i, '')
-    htmlPaths.push(`/docs/${withoutExt}`)
-    markdownPaths.push(`/docs-markdown/${publicRel.replace(/\\/g, '/')}`)
+    const withoutExt = publicRel.replace(/\.md$/i, '').replace(/\\/g, '/')
+    guides.push({
+      htmlPath: `/docs/${withoutExt}`,
+      markdownPath: `/docs-markdown/${publicRel.replace(/\\/g, '/')}`,
+      title: frontmatter.title,
+      description: frontmatter.description,
+      updated: toUpdatedIso(frontmatter.updated),
+    })
   }
 
-  htmlPaths.sort()
-  markdownPaths.sort()
-  return { htmlPaths, markdownPaths }
+  guides.sort((a, b) => a.htmlPath.localeCompare(b.htmlPath))
+  return guides
 }
 
 function readApiRoutes() {
@@ -109,27 +177,28 @@ function readApiRoutes() {
   }
 }
 
-function escapeXml(value) {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-}
-
 /**
- * @param {string[]} locs
+ * @param {{ loc: string, lastmod?: string }[]} entries
  */
-function writeSitemap(locs) {
-  const unique = [...new Set(locs)]
-  unique.sort()
+function writeSitemap(entries) {
+  const byLoc = new Map()
+  for (const entry of entries) {
+    const existing = byLoc.get(entry.loc)
+    if (!existing || (entry.lastmod && (!existing.lastmod || entry.lastmod > existing.lastmod))) {
+      byLoc.set(entry.loc, entry)
+    }
+  }
+
+  const unique = [...byLoc.values()].sort((a, b) => a.loc.localeCompare(b.loc))
 
   const body = unique
-    .map(
-      (loc) => `  <url>
-    <loc>${escapeXml(`${SITE_ORIGIN}${loc}`)}</loc>
-  </url>`,
-    )
+    .map((entry) => {
+      const lines = [`    <loc>${escapeXml(`${SITE_ORIGIN}${entry.loc}`)}</loc>`]
+      if (entry.lastmod) {
+        lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`)
+      }
+      return `  <url>\n${lines.join('\n')}\n  </url>`
+    })
     .join('\n')
 
   const xml = `<?xml version="1.0" encoding="UTF-8"?>
@@ -142,35 +211,89 @@ ${body}
   return unique.length
 }
 
+/**
+ * @param {GuideAsset[]} guides
+ */
+function writeAtomFeed(guides) {
+  const withDates = guides
+    .filter((g) => g.updated && g.title)
+    .sort((a, b) => {
+      const byDate = b.updated.localeCompare(a.updated)
+      if (byDate !== 0) return byDate
+      return a.htmlPath.localeCompare(b.htmlPath)
+    })
+
+  const feedUpdated = withDates[0]?.updated
+    ?? new Date().toISOString().slice(0, 10)
+
+  const entries = withDates
+    .map((guide) => {
+      const link = `${SITE_ORIGIN}${guide.htmlPath}`
+      const summary = guide.description
+        ? `\n    <summary>${escapeXml(guide.description)}</summary>`
+        : ''
+      return `  <entry>
+    <title>${escapeXml(guide.title)}</title>
+    <link href="${escapeXml(link)}" rel="alternate" type="text/html"/>
+    <id>${escapeXml(link)}</id>
+    <updated>${escapeXml(guide.updated)}T00:00:00Z</updated>${summary}
+  </entry>`
+    })
+    .join('\n')
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <title>${escapeXml(FEED_TITLE)}</title>
+  <link href="${escapeXml(SITE_ORIGIN)}/" rel="alternate" type="text/html"/>
+  <link href="${escapeXml(`${SITE_ORIGIN}/feed.xml`)}" rel="self" type="application/atom+xml"/>
+  <id>${escapeXml(FEED_ID)}</id>
+  <updated>${escapeXml(feedUpdated)}T00:00:00Z</updated>
+${entries}
+</feed>
+`
+
+  fs.writeFileSync(feedPath, xml, 'utf8')
+  return withDates.length
+}
+
 function main() {
   if (!fs.existsSync(contentDocs)) {
     console.error(`Missing content docs at ${contentDocs}`)
     process.exit(1)
   }
 
-  const { htmlPaths, markdownPaths } = mirrorDocsMarkdown()
+  const guides = mirrorDocsMarkdown()
   const apiRoutes = readApiRoutes()
 
-  const locs = [
-    '/',
-    '/llms.txt',
-    '/robots.txt',
-    '/api-catalog.json',
-    ...htmlPaths,
-    ...markdownPaths,
-    ...apiRoutes,
+  /** @type {{ loc: string, lastmod?: string }[]} */
+  const sitemapEntries = [
+    { loc: '/' },
+    { loc: '/llms.txt' },
+    { loc: '/robots.txt' },
+    { loc: '/feed.xml' },
+    { loc: '/api-catalog.json' },
   ]
 
+  for (const guide of guides) {
+    sitemapEntries.push({ loc: guide.htmlPath, lastmod: guide.updated })
+    sitemapEntries.push({ loc: guide.markdownPath, lastmod: guide.updated })
+  }
+
+  for (const route of apiRoutes) {
+    sitemapEntries.push({ loc: route })
+  }
+
   // Prefer catalog when prepare-api has run; omit if missing (local docs-only).
   if (!fs.existsSync(path.join(publicDir, 'api-catalog.json'))) {
-    const i = locs.indexOf('/api-catalog.json')
-    if (i >= 0) locs.splice(i, 1)
+    const i = sitemapEntries.findIndex((e) => e.loc === '/api-catalog.json')
+    if (i >= 0) sitemapEntries.splice(i, 1)
   }
 
-  const count = writeSitemap(locs)
+  const sitemapCount = writeSitemap(sitemapEntries)
+  const feedCount = writeAtomFeed(guides)
 
   console.log(
-    `prepare-agent-assets: mirrored ${htmlPaths.length} guides → docs-markdown/; sitemap ${count} URLs` +
+    `prepare-agent-assets: mirrored ${guides.length} guides → docs-markdown/; sitemap ${sitemapCount} URLs; atom ${feedCount} entries` +
       (apiRoutes.length ? ` (incl. ${apiRoutes.length} API routes)` : ' (no api-meta/routes.json yet)'),
   )
 }
diff --git a/site/tests/formatDocsUpdatedDate.test.ts b/site/tests/formatDocsUpdatedDate.test.ts
new file mode 100644
index 0000000..5f1ddba
--- /dev/null
+++ b/site/tests/formatDocsUpdatedDate.test.ts
@@ -0,0 +1,38 @@
+import assert from 'node:assert/strict'
+import { describe, it } from 'node:test'
+import { formatDocsUpdatedDate, toDocsUpdatedIso } from '../app/utils/formatDocsUpdatedDate.ts'
+
+describe('toDocsUpdatedIso', () => {
+  it('toDocsUpdatedIso_WhenMissing_ReturnsUndefined', () => {
+    assert.equal(toDocsUpdatedIso(undefined), undefined)
+    assert.equal(toDocsUpdatedIso(null), undefined)
+    assert.equal(toDocsUpdatedIso(''), undefined)
+  })
+
+  it('toDocsUpdatedIso_WhenIsoString_ReturnsSame', () => {
+    assert.equal(toDocsUpdatedIso('2026-09-08'), '2026-09-08')
+  })
+
+  it('toDocsUpdatedIso_WhenInvalidString_ReturnsUndefined', () => {
+    assert.equal(toDocsUpdatedIso('09/08/2026'), undefined)
+    assert.equal(toDocsUpdatedIso('2026-13-01'), undefined)
+    assert.equal(toDocsUpdatedIso('not-a-date'), undefined)
+  })
+
+  it('toDocsUpdatedIso_WhenDate_ReturnsUtcCalendarDay', () => {
+    assert.equal(toDocsUpdatedIso(new Date(Date.UTC(2026, 8, 8))), '2026-09-08')
+  })
+})
+
+describe('formatDocsUpdatedDate', () => {
+  it('formatDocsUpdatedDate_WhenIso_ReturnsLabelAndIso', () => {
+    assert.deepEqual(formatDocsUpdatedDate('2026-09-08'), {
+      iso: '2026-09-08',
+      label: 'September 8, 2026',
+    })
+  })
+
+  it('formatDocsUpdatedDate_WhenInvalid_ReturnsUndefined', () => {
+    assert.equal(formatDocsUpdatedDate('nope'), undefined)
+  })
+})