From 04adffc411aa127045d5a4335743f503b4922c90 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 30 May 2026 06:15:44 +0000
Subject: [PATCH 1/6] Initial plan


From 657a869c9d6e5afdb9147862c28a601022b6ed01 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 30 May 2026 06:27:53 +0000
Subject: [PATCH 2/6] feat(content-ui): add articles detail page, sitemap, and
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Create /articles/[slug].astro — SSR article detail page with breadcrumbs,
  author/date/reading-time meta, markdown rendering, inline conversion CTA,
  related articles section, Article + BreadcrumbList JSON-LD schemas
- Update sitemap.xml.ts: add /guides and /articles to static routes; fetch
  and include all published guides and articles with lastmod dates
- Create docs/content-ui.md: full developer reference covering routing,
  content hubs, detail page features, SEO, CMS API, editorial workflow,
  internal linking, accessibility, and testing commands

All 93 CMS service tests pass."

Co-authored-by: NickLetts2 <90337962+NickLetts2@users.noreply.github.com>
---
 .../src/pages/articles/[slug].astro           | 251 +++++++++++
 .../src/pages/articles/index.astro            | 286 +++++++++++++
 .../src/pages/guides/[slug].astro             | 254 ++++++++++++
 .../src/pages/guides/index.astro              | 291 +++++++++++++
 apps/marketing-site/src/pages/sitemap.xml.ts  |  43 +-
 docs/content-ui.md                            | 391 ++++++++++++++++++
 services/cms-service/app/models/schemas.py    |  27 +-
 services/cms-service/app/routers/content.py   | 309 +++++++++++++-
 services/cms-service/tests/test_content.py    | 191 +++++++++
 9 files changed, 2036 insertions(+), 7 deletions(-)
 create mode 100644 apps/marketing-site/src/pages/articles/[slug].astro
 create mode 100644 apps/marketing-site/src/pages/articles/index.astro
 create mode 100644 apps/marketing-site/src/pages/guides/[slug].astro
 create mode 100644 apps/marketing-site/src/pages/guides/index.astro
 create mode 100644 docs/content-ui.md

diff --git a/apps/marketing-site/src/pages/articles/[slug].astro b/apps/marketing-site/src/pages/articles/[slug].astro
new file mode 100644
index 00000000..4a8142ae
--- /dev/null
+++ b/apps/marketing-site/src/pages/articles/[slug].astro
@@ -0,0 +1,251 @@
+---
+// SSR — visibility rules enforced at request time
+import BaseLayout from '../../layouts/BaseLayout.astro';
+import CtaBanner from '../../components/sections/CtaBanner.astro';
+import { marked } from 'marked';
+import { sanitizeBlogHtml } from '../../lib/sanitize';
+import { appUrl, siteUrl } from '../../config';
+
+const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
+const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+
+const { slug } = Astro.params;
+
+interface ArticleDetail {
+  id: string;
+  content_type: string;
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  content_markdown: string;
+  author_name: string;
+  category: string | null;
+  seo_title: string | null;
+  seo_description: string | null;
+  canonical_url: string | null;
+  published_at: string | null;
+  created_at: string;
+  updated_at: string;
+  reading_time_minutes: number | null;
+  primary_topic: string | null;
+}
+
+interface RelatedItem {
+  id: string;
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  published_at: string | null;
+  created_at: string;
+  reading_time_minutes: number | null;
+}
+
+let article: ArticleDetail | null = null;
+let relatedItems: RelatedItem[] = [];
+
+try {
+  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+  const res = await fetch(`${cmsBase}/articles/${encodeURIComponent(slug!)}`, { headers });
+  if (res.ok) {
+    article = await res.json();
+  }
+} catch {
+  // Network error — fall through to 404
+}
+
+if (!article) {
+  return Astro.redirect('/404', 404);
+}
+
+// Related articles (best-effort)
+try {
+  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+  const relRes = await fetch(`${cmsBase}/content/articles/related/${encodeURIComponent(slug!)}?limit=3`, { headers });
+  if (relRes.ok) {
+    const relData = await relRes.json();
+    relatedItems = relData.items ?? [];
+  }
+} catch {
+  // Non-critical
+}
+
+const publishDate = article.published_at ?? article.created_at;
+const formattedDate = new Date(publishDate).toLocaleDateString('en-GB', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+});
+
+const publishMs = new Date(publishDate).getTime();
+const updatedMs = new Date(article.updated_at).getTime();
+const wasUpdated = updatedMs - publishMs > 86_400_000;
+const formattedUpdated = wasUpdated
+  ? new Date(article.updated_at).toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })
+  : null;
+
+const wordCount = article.content_markdown.trim().split(/\s+/).length;
+const readMins = article.reading_time_minutes ?? Math.max(1, Math.round(wordCount / 200));
+const readingTime = `${readMins} min read`;
+
+const pageTitle = `${article.seo_title ?? article.title} | Curvit Articles`;
+const pageDescription = article.seo_description ?? article.excerpt ?? `Read "${article.title}" — a Curvit career and CV article.`;
+const canonicalURL = article.canonical_url ?? `${siteUrl}/articles/${article.slug}/`;
+
+const contentHtml = sanitizeBlogHtml(marked.parse(article.content_markdown, { async: false }) as string);
+
+const articleSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'Article',
+  headline: article.title,
+  description: article.excerpt ?? undefined,
+  author: { '@type': 'Person', name: article.author_name },
+  datePublished: publishDate,
+  dateModified: article.updated_at,
+  url: canonicalURL,
+  publisher: {
+    '@type': 'Organization',
+    name: 'Curvit',
+    url: siteUrl,
+  },
+};
+
+const breadcrumbSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'BreadcrumbList',
+  itemListElement: [
+    { '@type': 'ListItem', position: 1, name: 'Home', item: siteUrl },
+    { '@type': 'ListItem', position: 2, name: 'Articles', item: `${siteUrl}/articles/` },
+    { '@type': 'ListItem', position: 3, name: article.title, item: canonicalURL },
+  ],
+};
+---
+
+<BaseLayout
+  title={pageTitle}
+  description={pageDescription}
+  canonicalURL={canonicalURL}
+  ogType="article"
+>
+  <script slot="head" type="application/ld+json" is:inline set:html={JSON.stringify(articleSchema)} />
+  <script slot="head" type="application/ld+json" is:inline set:html={JSON.stringify(breadcrumbSchema)} />
+
+  <div class="mx-auto max-w-4xl px-4 py-16 sm:px-6 sm:py-24">
+    <!-- Breadcrumb -->
+    <nav aria-label="Breadcrumb" class="mb-8">
+      <ol class="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-stone-500">
+        <li>
+          <a href="/" class="hover:text-teal-400 transition-colors">Home</a>
+        </li>
+        <li aria-hidden="true"><span class="text-stone-700">/</span></li>
+        <li>
+          <a href="/articles/" class="hover:text-teal-400 transition-colors">Articles</a>
+        </li>
+        <li aria-hidden="true"><span class="text-stone-700">/</span></li>
+        <li class="truncate text-stone-400" aria-current="page">{article.title}</li>
+      </ol>
+    </nav>
+
+    <!-- Article header -->
+    <header class="mb-10">
+      {article.category && (
+        <span class="mb-3 inline-block rounded-full bg-teal-900/50 px-3 py-1 text-xs font-semibold text-teal-300">
+          {article.category}
+        </span>
+      )}
+      <h1
+        class="mb-5 text-3xl font-bold tracking-tight text-stone-50 sm:text-4xl"
+        style="font-family: 'DM Serif Display', serif;"
+      >
+        {article.title}
+      </h1>
+
+      <div class="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-stone-500">
+        <span class="font-medium text-stone-400">{article.author_name}</span>
+        <span aria-hidden="true" class="text-stone-700">·</span>
+        <time datetime={publishDate}>{formattedDate}</time>
+        <span aria-hidden="true" class="text-stone-700">·</span>
+        <span>{readingTime}</span>
+      </div>
+
+      {formattedUpdated && (
+        <p class="mt-2 text-xs text-stone-400">
+          Updated <time datetime={article.updated_at}>{formattedUpdated}</time>
+        </p>
+      )}
+
+      {article.excerpt && (
+        <p class="mt-6 text-base leading-relaxed text-stone-300 border-l-2 border-teal-600 pl-4">
+          {article.excerpt}
+        </p>
+      )}
+
+      <hr class="mt-8 border-stone-800" />
+    </header>
+
+    <!-- Article content -->
+    <article
+      class="prose prose-invert prose-stone max-w-none prose-headings:font-bold prose-a:text-teal-400 prose-a:no-underline hover:prose-a:underline prose-img:rounded-xl"
+      set:html={contentHtml}
+    />
+
+    <!-- Inline educational CTA -->
+    <aside class="my-12 rounded-xl border border-teal-800/50 bg-teal-950/30 p-6">
+      <p class="text-sm font-semibold text-teal-200">How would your CV score against this role?</p>
+      <p class="mt-1 text-xs text-stone-400">Upload your CV and paste any job description — Curvit gives you an instant match score and actionable suggestions.</p>
+      <a
+        href={`${appUrl}/signup`}
+        class="mt-4 inline-flex items-center gap-2 rounded-lg bg-teal-600 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-teal-500"
+        data-analytics="article-inline-cta"
+      >
+        Score my CV free
+      </a>
+    </aside>
+
+    <!-- Related articles -->
+    {relatedItems.length > 0 && (
+      <aside class="mt-16 border-t border-stone-800 pt-10" aria-label="Related articles">
+        <h2 class="mb-6 text-lg font-bold text-stone-100" style="font-family: 'DM Serif Display', serif;">
+          Related articles
+        </h2>
+        <ul role="list" class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {relatedItems.map((item) => {
+            const itemDate = item.published_at ?? item.created_at;
+            return (
+              <li>
+                <a
+                  href={`/articles/${item.slug}/`}
+                  class="block rounded-xl border border-stone-800 bg-stone-900/70 p-5 transition-colors hover:border-stone-700"
+                >
+                  <p class="font-semibold text-sm text-stone-100 leading-snug">{item.title}</p>
+                  {item.excerpt && (
+                    <p class="mt-1.5 text-xs leading-relaxed text-stone-400 line-clamp-2">{item.excerpt}</p>
+                  )}
+                  <p class="mt-3 text-xs font-medium text-teal-400">Read article →</p>
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </aside>
+    )}
+
+    <!-- Footer: back link -->
+    <div class="mt-16 border-t border-stone-800 pt-8">
+      <a
+        href="/articles/"
+        class="inline-flex items-center gap-1.5 text-sm text-stone-500 hover:text-teal-400 transition-colors"
+      >
+        <svg viewBox="0 0 20 20" fill="currentColor" class="h-4 w-4" aria-hidden="true">
+          <path fill-rule="evenodd" d="M17 10a.75.75 0 01-.75.75H5.612l4.158 3.96a.75.75 0 11-1.04 1.08l-5.5-5.25a.75.75 0 010-1.08l5.5-5.25a.75.75 0 111.04 1.08L5.612 9.25H16.25A.75.75 0 0117 10z" clip-rule="evenodd" />
+        </svg>
+        Back to articles
+      </a>
+    </div>
+  </div>
+
+  <CtaBanner
+    heading="Put these insights to work"
+    body="Score your CV against a real job description — get your match score and targeted suggestions in seconds."
+    cta={{ label: 'Start free', href: `${appUrl}/signup` }}
+  />
+</BaseLayout>
diff --git a/apps/marketing-site/src/pages/articles/index.astro b/apps/marketing-site/src/pages/articles/index.astro
new file mode 100644
index 00000000..02ed4295
--- /dev/null
+++ b/apps/marketing-site/src/pages/articles/index.astro
@@ -0,0 +1,286 @@
+---
+// SSR — content changes dynamically; no prerender
+import BaseLayout from '../../layouts/BaseLayout.astro';
+import CtaBanner from '../../components/sections/CtaBanner.astro';
+import { appUrl, siteUrl } from '../../config';
+
+const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
+const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+
+const url = new URL(Astro.request.url);
+const searchQuery = url.searchParams.get('search') ?? '';
+const categoryFilter = url.searchParams.get('category') ?? '';
+const currentPage = Math.max(1, parseInt(url.searchParams.get('page') ?? '1', 10));
+const PAGE_SIZE = 12;
+
+interface ArticleSummary {
+  id: string;
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  author_name: string;
+  category: string | null;
+  published_at: string | null;
+  created_at: string;
+  reading_time_minutes: number | null;
+}
+
+interface ArticlesResponse {
+  items: ArticleSummary[];
+  total: number;
+  page: number;
+  page_size: number;
+}
+
+let articlesData: ArticlesResponse = { items: [], total: 0, page: 1, page_size: PAGE_SIZE };
+let fetchError = false;
+let categories: string[] = [];
+
+try {
+  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+  const params = new URLSearchParams({
+    page: String(currentPage),
+    page_size: String(PAGE_SIZE),
+  });
+  if (searchQuery) params.set('search', searchQuery);
+  if (categoryFilter) params.set('category', categoryFilter);
+
+  const res = await fetch(`${cmsBase}/articles?${params}`, { headers });
+  if (res.ok) {
+    articlesData = await res.json();
+    const allCategories = articlesData.items
+      .map((a) => a.category)
+      .filter((c): c is string => !!c);
+    categories = [...new Set(allCategories)].sort();
+  } else {
+    fetchError = true;
+  }
+} catch {
+  fetchError = true;
+}
+
+const totalPages = Math.ceil(articlesData.total / PAGE_SIZE);
+const canonicalURL = `${siteUrl}/articles/`;
+
+const pageSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'CollectionPage',
+  name: 'Career & CV Articles — Curvit',
+  url: canonicalURL,
+  description: 'Long-form articles on CV writing, career strategy, job search and the UK recruitment landscape.',
+};
+
+const breadcrumbSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'BreadcrumbList',
+  itemListElement: [
+    { '@type': 'ListItem', position: 1, name: 'Home', item: siteUrl },
+    { '@type': 'ListItem', position: 2, name: 'Articles', item: canonicalURL },
+  ],
+};
+---
+
+<BaseLayout
+  title="Career & CV Articles | Curvit"
+  description="Long-form articles on CV writing, career strategy, and the UK job market — written for UK jobseekers and professionals."
+  canonicalURL={canonicalURL}
+  ogType="website"
+>
+  <Fragment slot="head">
+    <script type="application/ld+json" is:inline set:html={JSON.stringify(pageSchema)} />
+    <script type="application/ld+json" is:inline set:html={JSON.stringify(breadcrumbSchema)} />
+  </Fragment>
+
+  <div class="mx-auto max-w-5xl px-4 py-16 sm:px-6 sm:py-24">
+    <!-- Hub header -->
+    <header class="mb-12 text-center">
+      <p class="mb-3 text-sm font-semibold uppercase tracking-[0.14em] text-teal-400">Articles · UK</p>
+      <h1
+        class="mb-4 text-4xl font-bold tracking-tight text-stone-50 sm:text-5xl"
+        style="font-family: 'DM Serif Display', serif;"
+      >
+        Career &amp; CV articles
+      </h1>
+      <p class="mx-auto max-w-2xl text-lg leading-relaxed text-stone-400">
+        Long-form, research-backed articles on CV writing, career development, and navigating the UK job market.
+      </p>
+    </header>
+
+    <!-- Search and filter bar -->
+    <form method="get" action="/articles/" class="mb-10 flex flex-col gap-4 sm:flex-row sm:items-end">
+      <div class="flex-1">
+        <label for="search" class="mb-1.5 block text-sm font-medium text-stone-400">Search articles</label>
+        <div class="relative">
+          <svg
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            class="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-stone-500"
+            aria-hidden="true"
+          >
+            <path fill-rule="evenodd" d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z" clip-rule="evenodd" />
+          </svg>
+          <input
+            id="search"
+            type="search"
+            name="search"
+            value={searchQuery}
+            placeholder="e.g. career change, remote working…"
+            class="w-full rounded-lg border border-stone-700 bg-stone-900 py-2.5 pl-9 pr-4 text-sm text-stone-100 placeholder:text-stone-500 focus:border-teal-600 focus:outline-none focus:ring-1 focus:ring-teal-600"
+          />
+        </div>
+      </div>
+
+      {categories.length > 0 && (
+        <div class="sm:w-48">
+          <label for="category" class="mb-1.5 block text-sm font-medium text-stone-400">Category</label>
+          <select
+            id="category"
+            name="category"
+            class="w-full rounded-lg border border-stone-700 bg-stone-900 py-2.5 px-3 text-sm text-stone-100 focus:border-teal-600 focus:outline-none focus:ring-1 focus:ring-teal-600"
+          >
+            <option value="">All categories</option>
+            {categories.map((cat) => (
+              <option value={cat} selected={cat === categoryFilter}>{cat}</option>
+            ))}
+          </select>
+        </div>
+      )}
+
+      <button
+        type="submit"
+        class="rounded-lg bg-teal-600 px-5 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-teal-500 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
+      >
+        Search
+      </button>
+
+      {(searchQuery || categoryFilter) && (
+        <a
+          href="/articles/"
+          class="rounded-lg border border-stone-700 px-4 py-2.5 text-sm text-stone-400 hover:text-stone-200 transition-colors"
+        >
+          Clear
+        </a>
+      )}
+    </form>
+
+    {(searchQuery || categoryFilter) && (
+      <p class="mb-6 text-sm text-stone-500">
+        {articlesData.total === 0 ? 'No articles found' : `${articlesData.total} article${articlesData.total === 1 ? '' : 's'} found`}
+        {searchQuery && <span> for &ldquo;<span class="text-stone-300">{searchQuery}</span>&rdquo;</span>}
+        {categoryFilter && <span> in <span class="text-stone-300">{categoryFilter}</span></span>}
+      </p>
+    )}
+
+    {fetchError && (
+      <p class="text-center text-sm text-stone-500">Unable to load articles right now. Please try again later.</p>
+    )}
+
+    {!fetchError && articlesData.items.length === 0 && (
+      <p class="text-center text-sm text-stone-500">No articles published yet.</p>
+    )}
+
+    <!-- Article cards -->
+    {articlesData.items.length > 0 && (
+      <ul role="list" class="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+        {articlesData.items.map((article) => {
+          const dateStr = article.published_at ?? article.created_at;
+          const formattedDate = new Date(dateStr).toLocaleDateString('en-GB', {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+          });
+          return (
+            <li>
+              <article class="flex h-full flex-col gap-3 rounded-xl border border-stone-800 bg-stone-900 p-6 transition-colors hover:border-stone-700">
+                {article.category && (
+                  <span class="inline-block w-fit rounded-full bg-teal-900/50 px-2.5 py-0.5 text-xs font-medium text-teal-300">
+                    {article.category}
+                  </span>
+                )}
+                <div class="flex items-center gap-2 text-xs text-stone-500">
+                  <span>{article.author_name}</span>
+                  <span aria-hidden="true">·</span>
+                  <time datetime={dateStr}>{formattedDate}</time>
+                  {article.reading_time_minutes && (
+                    <>
+                      <span aria-hidden="true">·</span>
+                      <span>{article.reading_time_minutes} min read</span>
+                    </>
+                  )}
+                </div>
+                <h2 class="text-base font-semibold leading-snug text-stone-100">
+                  <a href={`/articles/${article.slug}/`} class="hover:text-teal-400 transition-colors">
+                    {article.title}
+                  </a>
+                </h2>
+                {article.excerpt && (
+                  <p class="text-sm leading-relaxed text-stone-400 line-clamp-2">{article.excerpt}</p>
+                )}
+                <a
+                  href={`/articles/${article.slug}/`}
+                  class="mt-auto inline-flex items-center gap-1 text-sm font-medium text-teal-400 hover:text-teal-300 transition-colors"
+                  aria-label={`Read article: ${article.title}`}
+                >
+                  Read article
+                  <svg viewBox="0 0 20 20" fill="currentColor" class="h-4 w-4" aria-hidden="true">
+                    <path fill-rule="evenodd" d="M3 10a.75.75 0 01.75-.75h10.638L10.23 5.29a.75.75 0 111.04-1.08l5.5 5.25a.75.75 0 010 1.08l-5.5 5.25a.75.75 0 11-1.04-1.08l4.158-3.96H3.75A.75.75 0 013 10z" clip-rule="evenodd" />
+                  </svg>
+                </a>
+              </article>
+            </li>
+          );
+        })}
+      </ul>
+    )}
+
+    <!-- Pagination -->
+    {totalPages > 1 && (
+      <nav aria-label="Pagination" class="mt-12 flex items-center justify-center gap-2">
+        {currentPage > 1 && (
+          <a
+            href={`/articles/?page=${currentPage - 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
+            aria-label="Previous page"
+          >
+            ← Previous
+          </a>
+        )}
+        <span class="text-sm text-stone-500">
+          Page {currentPage} of {totalPages}
+        </span>
+        {currentPage < totalPages && (
+          <a
+            href={`/articles/?page=${currentPage + 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
+            aria-label="Next page"
+          >
+            Next →
+          </a>
+        )}
+      </nav>
+    )}
+
+    <!-- Benchmark CTA -->
+    <div class="mt-16 rounded-2xl border border-stone-800 bg-stone-900/70 p-6 text-center">
+      <h2 class="text-xl font-bold text-stone-100" style="font-family: 'DM Serif Display', serif;">
+        How would your CV score against this role?
+      </h2>
+      <p class="mt-2 text-sm text-stone-400">
+        Paste any job description and upload your CV — Curvit benchmarks your match and shows you the exact gaps to close.
+      </p>
+      <a
+        href={`${appUrl}/signup`}
+        class="mt-4 inline-flex items-center gap-2 rounded-lg bg-teal-600 px-5 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-teal-500 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
+        data-analytics="articles-hub-cta"
+      >
+        Score my CV free
+      </a>
+    </div>
+  </div>
+
+  <CtaBanner
+    heading="Put these insights to work"
+    body="Score your CV against real job descriptions and get targeted feedback — free to start."
+    cta={{ label: 'Start free', href: `${appUrl}/signup` }}
+  />
+</BaseLayout>
diff --git a/apps/marketing-site/src/pages/guides/[slug].astro b/apps/marketing-site/src/pages/guides/[slug].astro
new file mode 100644
index 00000000..ab1f33d9
--- /dev/null
+++ b/apps/marketing-site/src/pages/guides/[slug].astro
@@ -0,0 +1,254 @@
+---
+// SSR — visibility rules enforced at request time
+import BaseLayout from '../../layouts/BaseLayout.astro';
+import CtaBanner from '../../components/sections/CtaBanner.astro';
+import { marked } from 'marked';
+import { sanitizeBlogHtml } from '../../lib/sanitize';
+import { appUrl, siteUrl } from '../../config';
+
+const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
+const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+
+const { slug } = Astro.params;
+
+interface GuideDetail {
+  id: string;
+  content_type: string;
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  content_markdown: string;
+  author_name: string;
+  category: string | null;
+  seo_title: string | null;
+  seo_description: string | null;
+  canonical_url: string | null;
+  published_at: string | null;
+  created_at: string;
+  updated_at: string;
+  reading_time_minutes: number | null;
+  primary_topic: string | null;
+}
+
+interface RelatedItem {
+  id: string;
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  published_at: string | null;
+  created_at: string;
+  reading_time_minutes: number | null;
+}
+
+let guide: GuideDetail | null = null;
+let relatedItems: RelatedItem[] = [];
+
+try {
+  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+
+  const res = await fetch(`${cmsBase}/guides/${encodeURIComponent(slug!)}`, { headers });
+  if (res.ok) {
+    guide = await res.json();
+  } else if (res.status !== 404) {
+    // Non-404 errors: fall through and show 404 page
+  }
+} catch {
+  // Network error — fall through to 404
+}
+
+if (!guide) {
+  return Astro.redirect('/404', 404);
+}
+
+// Fetch related guides in parallel (best-effort)
+try {
+  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+  const relRes = await fetch(`${cmsBase}/content/guides/related/${encodeURIComponent(slug!)}?limit=3`, { headers });
+  if (relRes.ok) {
+    const relData = await relRes.json();
+    relatedItems = relData.items ?? [];
+  }
+} catch {
+  // Related content is non-critical — ignore errors
+}
+
+const publishDate = guide.published_at ?? guide.created_at;
+const formattedDate = new Date(publishDate).toLocaleDateString('en-GB', {
+  year: 'numeric',
+  month: 'long',
+  day: 'numeric',
+});
+
+const publishMs = new Date(publishDate).getTime();
+const updatedMs = new Date(guide.updated_at).getTime();
+const wasUpdated = updatedMs - publishMs > 86_400_000;
+const formattedUpdated = wasUpdated
+  ? new Date(guide.updated_at).toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })
+  : null;
+
+const wordCount = guide.content_markdown.trim().split(/\s+/).length;
+const readMins = guide.reading_time_minutes ?? Math.max(1, Math.round(wordCount / 200));
+const readingTime = `${readMins} min read`;
+
+const pageTitle = `${guide.seo_title ?? guide.title} | Curvit Guides`;
+const pageDescription = guide.seo_description ?? guide.excerpt ?? `Read "${guide.title}" — a Curvit career and CV guide.`;
+const canonicalURL = guide.canonical_url ?? `${siteUrl}/guides/${guide.slug}/`;
+
+const contentHtml = sanitizeBlogHtml(marked.parse(guide.content_markdown, { async: false }) as string);
+
+const articleSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'Article',
+  headline: guide.title,
+  description: guide.excerpt ?? undefined,
+  author: { '@type': 'Person', name: guide.author_name },
+  datePublished: publishDate,
+  dateModified: guide.updated_at,
+  url: canonicalURL,
+  publisher: {
+    '@type': 'Organization',
+    name: 'Curvit',
+    url: siteUrl,
+  },
+};
+
+const breadcrumbSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'BreadcrumbList',
+  itemListElement: [
+    { '@type': 'ListItem', position: 1, name: 'Home', item: siteUrl },
+    { '@type': 'ListItem', position: 2, name: 'Guides', item: `${siteUrl}/guides/` },
+    { '@type': 'ListItem', position: 3, name: guide.title, item: canonicalURL },
+  ],
+};
+---
+
+<BaseLayout
+  title={pageTitle}
+  description={pageDescription}
+  canonicalURL={canonicalURL}
+  ogType="article"
+>
+  <script slot="head" type="application/ld+json" is:inline set:html={JSON.stringify(articleSchema)} />
+  <script slot="head" type="application/ld+json" is:inline set:html={JSON.stringify(breadcrumbSchema)} />
+
+  <div class="mx-auto max-w-4xl px-4 py-16 sm:px-6 sm:py-24">
+    <!-- Breadcrumb -->
+    <nav aria-label="Breadcrumb" class="mb-8">
+      <ol class="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-stone-500">
+        <li>
+          <a href="/" class="hover:text-teal-400 transition-colors">Home</a>
+        </li>
+        <li aria-hidden="true"><span class="text-stone-700">/</span></li>
+        <li>
+          <a href="/guides/" class="hover:text-teal-400 transition-colors">Guides</a>
+        </li>
+        <li aria-hidden="true"><span class="text-stone-700">/</span></li>
+        <li class="truncate text-stone-400" aria-current="page">{guide.title}</li>
+      </ol>
+    </nav>
+
+    <!-- Article header -->
+    <header class="mb-10">
+      {guide.category && (
+        <span class="mb-3 inline-block rounded-full bg-teal-900/50 px-3 py-1 text-xs font-semibold text-teal-300">
+          {guide.category}
+        </span>
+      )}
+      <h1
+        class="mb-5 text-3xl font-bold tracking-tight text-stone-50 sm:text-4xl"
+        style="font-family: 'DM Serif Display', serif;"
+      >
+        {guide.title}
+      </h1>
+
+      <div class="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-stone-500">
+        <span class="font-medium text-stone-400">{guide.author_name}</span>
+        <span aria-hidden="true" class="text-stone-700">·</span>
+        <time datetime={publishDate}>{formattedDate}</time>
+        <span aria-hidden="true" class="text-stone-700">·</span>
+        <span>{readingTime}</span>
+      </div>
+
+      {formattedUpdated && (
+        <p class="mt-2 text-xs text-stone-400">
+          Updated <time datetime={guide.updated_at}>{formattedUpdated}</time>
+        </p>
+      )}
+
+      {guide.excerpt && (
+        <p class="mt-6 text-base leading-relaxed text-stone-300 border-l-2 border-teal-600 pl-4">
+          {guide.excerpt}
+        </p>
+      )}
+
+      <hr class="mt-8 border-stone-800" />
+    </header>
+
+    <!-- Article content -->
+    <article
+      class="prose prose-invert prose-stone max-w-none prose-headings:font-bold prose-a:text-teal-400 prose-a:no-underline hover:prose-a:underline prose-img:rounded-xl"
+      set:html={contentHtml}
+    />
+
+    <!-- Inline conversion CTA -->
+    <aside class="my-12 rounded-xl border border-teal-800/50 bg-teal-950/30 p-6">
+      <p class="text-sm font-semibold text-teal-200">Check whether these issues exist in your CV.</p>
+      <p class="mt-1 text-xs text-stone-400">Upload your CV and paste a job description — Curvit scores your match and highlights what to improve.</p>
+      <a
+        href={`${appUrl}/signup`}
+        class="mt-4 inline-flex items-center gap-2 rounded-lg bg-teal-600 px-4 py-2 text-sm font-semibold text-white transition-colors hover:bg-teal-500"
+        data-analytics="guide-inline-cta"
+      >
+        Score my CV free
+      </a>
+    </aside>
+
+    <!-- Related guides -->
+    {relatedItems.length > 0 && (
+      <aside class="mt-16 border-t border-stone-800 pt-10" aria-label="Related guides">
+        <h2 class="mb-6 text-lg font-bold text-stone-100" style="font-family: 'DM Serif Display', serif;">
+          Related guides
+        </h2>
+        <ul role="list" class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+          {relatedItems.map((item) => {
+            const itemDate = item.published_at ?? item.created_at;
+            return (
+              <li>
+                <a
+                  href={`/guides/${item.slug}/`}
+                  class="block rounded-xl border border-stone-800 bg-stone-900/70 p-5 transition-colors hover:border-stone-700"
+                >
+                  <p class="font-semibold text-sm text-stone-100 leading-snug">{item.title}</p>
+                  {item.excerpt && (
+                    <p class="mt-1.5 text-xs leading-relaxed text-stone-400 line-clamp-2">{item.excerpt}</p>
+                  )}
+                  <p class="mt-3 text-xs font-medium text-teal-400">Read guide →</p>
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      </aside>
+    )}
+
+    <!-- Footer: back link -->
+    <div class="mt-16 border-t border-stone-800 pt-8">
+      <a
+        href="/guides/"
+        class="inline-flex items-center gap-1.5 text-sm text-stone-500 hover:text-teal-400 transition-colors"
+      >
+        <svg viewBox="0 0 20 20" fill="currentColor" class="h-4 w-4" aria-hidden="true">
+          <path fill-rule="evenodd" d="M17 10a.75.75 0 01-.75.75H5.612l4.158 3.96a.75.75 0 11-1.04 1.08l-5.5-5.25a.75.75 0 010-1.08l5.5-5.25a.75.75 0 111.04 1.08L5.612 9.25H16.25A.75.75 0 0117 10z" clip-rule="evenodd" />
+        </svg>
+        Back to guides
+      </a>
+    </div>
+  </div>
+
+  <CtaBanner
+    heading="Ready to put this guide into practice?"
+    body="Score your CV against a real job description and get tailored suggestions — in seconds."
+    cta={{ label: 'Start free', href: `${appUrl}/signup` }}
+  />
+</BaseLayout>
diff --git a/apps/marketing-site/src/pages/guides/index.astro b/apps/marketing-site/src/pages/guides/index.astro
new file mode 100644
index 00000000..20e2a90c
--- /dev/null
+++ b/apps/marketing-site/src/pages/guides/index.astro
@@ -0,0 +1,291 @@
+---
+// SSR — content changes dynamically; no prerender
+import BaseLayout from '../../layouts/BaseLayout.astro';
+import CtaBanner from '../../components/sections/CtaBanner.astro';
+import { appUrl, siteUrl } from '../../config';
+
+const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
+const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+
+// Read search / category / page from query string
+const url = new URL(Astro.request.url);
+const searchQuery = url.searchParams.get('search') ?? '';
+const categoryFilter = url.searchParams.get('category') ?? '';
+const currentPage = Math.max(1, parseInt(url.searchParams.get('page') ?? '1', 10));
+const PAGE_SIZE = 12;
+
+interface GuideSummary {
+  id: string;
+  title: string;
+  slug: string;
+  excerpt: string | null;
+  author_name: string;
+  category: string | null;
+  published_at: string | null;
+  created_at: string;
+  reading_time_minutes: number | null;
+}
+
+interface GuidesResponse {
+  items: GuideSummary[];
+  total: number;
+  page: number;
+  page_size: number;
+}
+
+let guidesData: GuidesResponse = { items: [], total: 0, page: 1, page_size: PAGE_SIZE };
+let fetchError = false;
+let categories: string[] = [];
+
+try {
+  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+  const params = new URLSearchParams({
+    page: String(currentPage),
+    page_size: String(PAGE_SIZE),
+  });
+  if (searchQuery) params.set('search', searchQuery);
+  if (categoryFilter) params.set('category', categoryFilter);
+
+  const res = await fetch(`${cmsBase}/guides?${params}`, { headers });
+  if (res.ok) {
+    guidesData = await res.json();
+    // Build unique category list for filtering UI
+    const allCategories = guidesData.items
+      .map((g) => g.category)
+      .filter((c): c is string => !!c);
+    categories = [...new Set(allCategories)].sort();
+  } else {
+    fetchError = true;
+  }
+} catch {
+  fetchError = true;
+}
+
+const totalPages = Math.ceil(guidesData.total / PAGE_SIZE);
+const canonicalURL = `${siteUrl}/guides/`;
+
+const pageSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'CollectionPage',
+  name: 'CV & Career Guides — Curvit',
+  url: canonicalURL,
+  description: 'Practical, in-depth guides on CV writing, ATS optimisation, interview preparation and job search strategy for UK jobseekers.',
+};
+
+const breadcrumbSchema = {
+  '@context': 'https://schema.org',
+  '@type': 'BreadcrumbList',
+  itemListElement: [
+    { '@type': 'ListItem', position: 1, name: 'Home', item: siteUrl },
+    { '@type': 'ListItem', position: 2, name: 'Guides', item: canonicalURL },
+  ],
+};
+---
+
+<BaseLayout
+  title="CV & Career Guides | Curvit"
+  description="Practical, in-depth guides on CV writing, ATS optimisation, and job search strategy — written for UK jobseekers."
+  canonicalURL={canonicalURL}
+  ogType="website"
+>
+  <Fragment slot="head">
+    <script type="application/ld+json" is:inline set:html={JSON.stringify(pageSchema)} />
+    <script type="application/ld+json" is:inline set:html={JSON.stringify(breadcrumbSchema)} />
+  </Fragment>
+
+  <div class="mx-auto max-w-5xl px-4 py-16 sm:px-6 sm:py-24">
+    <!-- Hub header -->
+    <header class="mb-12 text-center">
+      <p class="mb-3 text-sm font-semibold uppercase tracking-[0.14em] text-teal-400">Guides · UK</p>
+      <h1
+        class="mb-4 text-4xl font-bold tracking-tight text-stone-50 sm:text-5xl"
+        style="font-family: 'DM Serif Display', serif;"
+      >
+        Career &amp; CV guides
+      </h1>
+      <p class="mx-auto max-w-2xl text-lg leading-relaxed text-stone-400">
+        Practical, in-depth guides on writing a strong CV, passing ATS screening, preparing for interviews and navigating the UK job market.
+      </p>
+    </header>
+
+    <!-- Search and filter bar -->
+    <form method="get" action="/guides/" class="mb-10 flex flex-col gap-4 sm:flex-row sm:items-end">
+      <div class="flex-1">
+        <label for="search" class="mb-1.5 block text-sm font-medium text-stone-400">Search guides</label>
+        <div class="relative">
+          <svg
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            class="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-stone-500"
+            aria-hidden="true"
+          >
+            <path fill-rule="evenodd" d="M9 3.5a5.5 5.5 0 100 11 5.5 5.5 0 000-11zM2 9a7 7 0 1112.452 4.391l3.328 3.329a.75.75 0 11-1.06 1.06l-3.329-3.328A7 7 0 012 9z" clip-rule="evenodd" />
+          </svg>
+          <input
+            id="search"
+            type="search"
+            name="search"
+            value={searchQuery}
+            placeholder="e.g. ATS, cover letter, interview…"
+            class="w-full rounded-lg border border-stone-700 bg-stone-900 py-2.5 pl-9 pr-4 text-sm text-stone-100 placeholder:text-stone-500 focus:border-teal-600 focus:outline-none focus:ring-1 focus:ring-teal-600"
+          />
+        </div>
+      </div>
+
+      {categories.length > 0 && (
+        <div class="sm:w-48">
+          <label for="category" class="mb-1.5 block text-sm font-medium text-stone-400">Category</label>
+          <select
+            id="category"
+            name="category"
+            class="w-full rounded-lg border border-stone-700 bg-stone-900 py-2.5 px-3 text-sm text-stone-100 focus:border-teal-600 focus:outline-none focus:ring-1 focus:ring-teal-600"
+          >
+            <option value="">All categories</option>
+            {categories.map((cat) => (
+              <option value={cat} selected={cat === categoryFilter}>{cat}</option>
+            ))}
+          </select>
+        </div>
+      )}
+
+      <button
+        type="submit"
+        class="rounded-lg bg-teal-600 px-5 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-teal-500 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
+      >
+        Search
+      </button>
+
+      {(searchQuery || categoryFilter) && (
+        <a
+          href="/guides/"
+          class="rounded-lg border border-stone-700 px-4 py-2.5 text-sm text-stone-400 hover:text-stone-200 transition-colors"
+        >
+          Clear
+        </a>
+      )}
+    </form>
+
+    <!-- Active filter indicators -->
+    {(searchQuery || categoryFilter) && (
+      <p class="mb-6 text-sm text-stone-500">
+        {guidesData.total === 0 ? 'No guides found' : `${guidesData.total} guide${guidesData.total === 1 ? '' : 's'} found`}
+        {searchQuery && <span> for &ldquo;<span class="text-stone-300">{searchQuery}</span>&rdquo;</span>}
+        {categoryFilter && <span> in <span class="text-stone-300">{categoryFilter}</span></span>}
+      </p>
+    )}
+
+    <!-- Error state -->
+    {fetchError && (
+      <p class="text-center text-sm text-stone-500">Unable to load guides right now. Please try again later.</p>
+    )}
+
+    <!-- Empty state -->
+    {!fetchError && guidesData.items.length === 0 && (
+      <p class="text-center text-sm text-stone-500">No guides published yet.</p>
+    )}
+
+    <!-- Guide cards -->
+    {guidesData.items.length > 0 && (
+      <ul role="list" class="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+        {guidesData.items.map((guide) => {
+          const dateStr = guide.published_at ?? guide.created_at;
+          const formattedDate = new Date(dateStr).toLocaleDateString('en-GB', {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+          });
+          return (
+            <li>
+              <article class="flex h-full flex-col gap-3 rounded-xl border border-stone-800 bg-stone-900 p-6 transition-colors hover:border-stone-700">
+                {guide.category && (
+                  <span class="inline-block w-fit rounded-full bg-teal-900/50 px-2.5 py-0.5 text-xs font-medium text-teal-300">
+                    {guide.category}
+                  </span>
+                )}
+                <div class="flex items-center gap-2 text-xs text-stone-500">
+                  <span>{guide.author_name}</span>
+                  <span aria-hidden="true">·</span>
+                  <time datetime={dateStr}>{formattedDate}</time>
+                  {guide.reading_time_minutes && (
+                    <>
+                      <span aria-hidden="true">·</span>
+                      <span>{guide.reading_time_minutes} min read</span>
+                    </>
+                  )}
+                </div>
+                <h2 class="text-base font-semibold leading-snug text-stone-100">
+                  <a href={`/guides/${guide.slug}/`} class="hover:text-teal-400 transition-colors">
+                    {guide.title}
+                  </a>
+                </h2>
+                {guide.excerpt && (
+                  <p class="text-sm leading-relaxed text-stone-400 line-clamp-2">{guide.excerpt}</p>
+                )}
+                <a
+                  href={`/guides/${guide.slug}/`}
+                  class="mt-auto inline-flex items-center gap-1 text-sm font-medium text-teal-400 hover:text-teal-300 transition-colors"
+                  aria-label={`Read guide: ${guide.title}`}
+                >
+                  Read guide
+                  <svg viewBox="0 0 20 20" fill="currentColor" class="h-4 w-4" aria-hidden="true">
+                    <path fill-rule="evenodd" d="M3 10a.75.75 0 01.75-.75h10.638L10.23 5.29a.75.75 0 111.04-1.08l5.5 5.25a.75.75 0 010 1.08l-5.5 5.25a.75.75 0 11-1.04-1.08l4.158-3.96H3.75A.75.75 0 013 10z" clip-rule="evenodd" />
+                  </svg>
+                </a>
+              </article>
+            </li>
+          );
+        })}
+      </ul>
+    )}
+
+    <!-- Pagination -->
+    {totalPages > 1 && (
+      <nav aria-label="Pagination" class="mt-12 flex items-center justify-center gap-2">
+        {currentPage > 1 && (
+          <a
+            href={`/guides/?page=${currentPage - 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
+            aria-label="Previous page"
+          >
+            ← Previous
+          </a>
+        )}
+        <span class="text-sm text-stone-500">
+          Page {currentPage} of {totalPages}
+        </span>
+        {currentPage < totalPages && (
+          <a
+            href={`/guides/?page=${currentPage + 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
+            aria-label="Next page"
+          >
+            Next →
+          </a>
+        )}
+      </nav>
+    )}
+
+    <!-- Diagnostic CTA -->
+    <div class="mt-16 rounded-2xl border border-stone-800 bg-stone-900/70 p-6 text-center">
+      <h2 class="text-xl font-bold text-stone-100" style="font-family: 'DM Serif Display', serif;">
+        How does your CV compare to the role?
+      </h2>
+      <p class="mt-2 text-sm text-stone-400">
+        Upload your CV and paste a job description — Curvit scores your match and shows you exactly what to improve.
+      </p>
+      <a
+        href={`${appUrl}/signup`}
+        class="mt-4 inline-flex items-center gap-2 rounded-lg bg-teal-600 px-5 py-2.5 text-sm font-semibold text-white transition-colors hover:bg-teal-500 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
+        data-analytics="guides-hub-cta"
+      >
+        Score my CV free
+      </a>
+    </div>
+  </div>
+
+  <CtaBanner
+    heading="Apply the advice from these guides"
+    body="Score your CV against real job descriptions, identify gaps, and get tailored improvement suggestions — all in one place."
+    cta={{ label: 'Start free', href: `${appUrl}/signup` }}
+  />
+</BaseLayout>
diff --git a/apps/marketing-site/src/pages/sitemap.xml.ts b/apps/marketing-site/src/pages/sitemap.xml.ts
index 71bc8ce1..82dddbad 100644
--- a/apps/marketing-site/src/pages/sitemap.xml.ts
+++ b/apps/marketing-site/src/pages/sitemap.xml.ts
@@ -1,12 +1,16 @@
 import type { APIRoute } from 'astro';
 import { cvForRoles } from '../lib/content/cv-for-roles';
 
-interface BlogPost {
+interface ContentItemSummary {
   slug: string;
-  start_date?: string;
+  published_at?: string;
   created_at?: string;
 }
 
+interface ContentListResponse {
+  items: ContentItemSummary[];
+}
+
 // Static public routes only - NO user-specific or authenticated content
 const staticRoutes = [
   '/',
@@ -18,6 +22,8 @@ const staticRoutes = [
   '/privacy',
   '/terms',
   '/blog',
+  '/guides',
+  '/articles',
   '/cv-for',
   '/ats-cv-checker',
   '/cv-tailoring-tool',
@@ -63,7 +69,7 @@ export const GET: APIRoute = async ({ site }) => {
     const res = await fetch(cmsUrl, { headers });
 
     if (res.ok) {
-      const posts: BlogPost[] = await res.json();
+      const posts: { slug: string; start_date?: string; created_at?: string }[] = await res.json();
       const now = new Date();
       let includedCount = 0;
 
@@ -93,6 +99,37 @@ export const GET: APIRoute = async ({ site }) => {
     console.warn(`Sitemap: Failed to fetch blog posts: ${error instanceof Error ? error.message : String(error)}`);
   }
 
+  // Fetch and include published guides and articles
+  const contentTypes: { type: string; path: string }[] = [
+    { type: 'guides', path: 'guides' },
+    { type: 'articles', path: 'articles' },
+  ];
+
+  for (const { type, path } of contentTypes) {
+    try {
+      const cmsBase = process.env.CMS_SERVICE_URL || 'http://cms-service:8000';
+      const internalApiKey = process.env.INTERNAL_API_KEY || '';
+      const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+
+      const res = await fetch(`${cmsBase}/${type}?page_size=100`, { headers });
+      if (res.ok) {
+        const data: ContentListResponse = await res.json();
+        data.items.forEach((item) => {
+          const dateStr = item.published_at ?? item.created_at;
+          const lastmod = dateStr ? new Date(dateStr).toISOString().split('T')[0] : undefined;
+          urls.push(`  <url>
+    <loc>${new URL(`/${path}/${item.slug}`, site).href}</loc>
+    ${lastmod ? `<lastmod>${lastmod}</lastmod>\n    ` : ''}<changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>`);
+        });
+        console.log(`Sitemap: Included ${data.items.length} published ${type}`);
+      }
+    } catch (error) {
+      console.warn(`Sitemap: Failed to fetch ${type}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
   const urlsXml = urls.join('\n');
 
   const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
diff --git a/docs/content-ui.md b/docs/content-ui.md
new file mode 100644
index 00000000..08e954fc
--- /dev/null
+++ b/docs/content-ui.md
@@ -0,0 +1,391 @@
+# Content UI — Developer Reference
+
+> **Issue:** #330 Content UI Refactor  
+> **Depends on:** #329 (Unified Content Platform)  
+> **Blocks:** #331 (AI Content Creator)
+
+---
+
+## Overview
+
+This document describes the public-facing content experience and the CMS administration layer that power Curvit's editorial platform.
+
+The platform supports four content types:
+
+| Content type | URL prefix | CMS slug |
+|---|---|---|
+| Blog | `/blog/:slug` | `blog` |
+| Guide | `/guides/:slug` | `guides` |
+| Article | `/articles/:slug` | `articles` |
+| CV For | `/cv-for/:slug` | `cv-for` |
+
+All four types are modelled as a unified `ContentItem` in the CMS service database and share a common administration interface.
+
+---
+
+## Routing structure
+
+### Public content hubs
+
+| Route | Description |
+|---|---|
+| `/blog` | Blog index — legacy `BlogPost` model (existing) |
+| `/blog/:slug` | Individual blog post |
+| `/guides` | Guides hub — SSR, paginated, searchable |
+| `/guides/:slug` | Individual guide detail page |
+| `/articles` | Articles hub — SSR, paginated, searchable |
+| `/articles/:slug` | Individual article detail page |
+| `/cv-for` | CV For landing page (static) |
+| `/cv-for/:slug` | Individual CV For role page (static) |
+
+### Administration
+
+| Route | Description |
+|---|---|
+| `/admin/content` | Content list / management dashboard |
+| `/admin/content/new` | Create new content item |
+| `/admin/content/:id/edit` | Edit existing content item |
+| `/admin/content/calendar` | Editorial calendar (month/week view) |
+| `/admin/content/assets` | Content asset library |
+
+---
+
+## Content hubs
+
+### Hub page features
+
+Each hub page (`/guides`, `/articles`) supports:
+
+- **Search** — `?q=` query parameter, title-and-excerpt full-text search via CMS API
+- **Category filter** — `?category=` parameter, single-category filtering
+- **Pagination** — `?page=` parameter (default page size: 12 items)
+- **SEO metadata** — canonical URL, `og:*` tags, `twitter:*` tags
+- **Structured data** — `CollectionPage` + `BreadcrumbList` JSON-LD schemas
+- **Diagnostic CTA** — soft conversion CTA encouraging users to score their CV
+
+### Hub page query parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `q` | string | — | Full-text search (title / excerpt) |
+| `category` | string | — | Filter by category slug |
+| `page` | number | `1` | Pagination page number |
+
+### Example requests
+
+```
+GET /guides?q=ats&page=1
+GET /articles?category=career-advice&page=2
+```
+
+---
+
+## Content detail pages
+
+### Common capabilities
+
+Every content detail page provides:
+
+| Feature | Description |
+|---|---|
+| **Hero / header** | Title, author, published date, reading time, category badge |
+| **Breadcrumbs** | Home → Hub → Article title (visible + schema) |
+| **Markdown rendering** | Server-side via `marked`; sanitised by `sanitizeBlogHtml` |
+| **Updated date** | Shown when `updated_at` is more than 24 hours after `published_at` |
+| **Reading time** | Derived from `reading_time_minutes` field or calculated at ~200 wpm |
+| **Inline CTA** | Educational/curiosity CTA ("How would your CV score against this role?") |
+| **Related content** | Up to 3 related items of the same content type |
+| **Canonical URL** | From `canonical_url` field, or constructed from `siteUrl + /type/slug/` |
+| **Structured data** | `Article` + `BreadcrumbList` JSON-LD schemas |
+| **Open Graph** | `og:title`, `og:description`, `og:type=article` |
+
+### CTA patterns used
+
+Per the conversion UX requirements, only soft educational CTAs are used:
+
+- **Curiosity CTA** (inline): _"How would your CV score against this role?"_
+- **Educational CTA** (page footer banner): _"Score your CV against a real job description"_
+
+No aggressive sales messaging is used.
+
+---
+
+## CV For pages
+
+CV For pages use a separate static implementation based on `cv-for-roles.ts`:
+
+- Pre-rendered at build time (`prerender = true`)
+- Data source: `apps/marketing-site/src/lib/content/cv-for-roles.ts`
+- Template: `apps/marketing-site/src/pages/cv-for/[slug].astro`
+- Content includes: recruiter expectations, ATS tips, common mistakes, example sections
+
+CV For pages are not yet migrated to the unified `ContentItem` model. Migration is deferred to preserve existing content parity.
+
+---
+
+## SEO features
+
+### Metadata
+
+All content pages set:
+
+- `<title>` — `{seo_title ?? title} | Curvit {ContentType}`
+- `<meta name="description">` — `seo_description ?? excerpt ?? fallback`
+- `<link rel="canonical">` — from `canonical_url` field or constructed
+- `<meta property="og:*">` — title, description, type
+- `<meta name="twitter:*">` — card type, title, description
+
+### Structured data
+
+Hub pages emit:
+
+```json
+{ "@type": "CollectionPage" }
+{ "@type": "BreadcrumbList" }
+```
+
+Detail pages emit:
+
+```json
+{ "@type": "Article" }
+{ "@type": "BreadcrumbList" }
+```
+
+The `Article` schema includes `headline`, `description`, `author`, `datePublished`, `dateModified`, `url`, and `publisher`.
+
+### Sitemap
+
+`/sitemap.xml` is dynamically generated and includes:
+
+- All static routes
+- All published blog posts (with `lastmod`)
+- All published guides (with `lastmod`)
+- All published articles (with `lastmod`)
+- All CV For role pages
+
+---
+
+## CMS service API
+
+### Public endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/guides` | List published guides |
+| `GET` | `/guides/:slug` | Get a single published guide |
+| `GET` | `/articles` | List published articles |
+| `GET` | `/articles/:slug` | Get a single published article |
+| `GET` | `/content/{type}/related/{slug}` | Get related items for a content page |
+
+#### List endpoint query parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `category` | string | — | Filter by category |
+| `search` | string | — | Full-text search (title) |
+| `page` | int | `1` | Page number |
+| `page_size` | int | `20` | Items per page (max 100) |
+
+#### Related content endpoint
+
+```
+GET /content/{type_slug}/related/{slug}?limit=3
+```
+
+Returns up to `limit` published items of the same type, preferring items in the same category as the current item, excluding the current item itself.
+
+### Admin endpoints
+
+All admin endpoints require the `X-Internal-Api-Key` header.
+
+#### Content CRUD
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/admin/content` | List all content items |
+| `POST` | `/admin/content` | Create new content item |
+| `GET` | `/admin/content/:id` | Get content item by ID |
+| `PUT` | `/admin/content/:id` | Update content item |
+
+#### Workflow actions
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/admin/content/:id/submit-review` | Submit draft for review |
+| `POST` | `/admin/content/:id/approve` | Approve reviewed content |
+| `POST` | `/admin/content/:id/request-changes` | Request changes (with reason) |
+| `POST` | `/admin/content/:id/schedule` | Schedule for publication |
+| `POST` | `/admin/content/:id/publish` | Publish immediately |
+| `POST` | `/admin/content/:id/unpublish` | Return to draft |
+| `POST` | `/admin/content/:id/archive` | Archive content |
+| `POST` | `/admin/content/:id/clone` | Clone content as new draft |
+| `DELETE` | `/admin/content/:id` | Delete content (Draft or Archived only) |
+
+---
+
+## Editorial workflow
+
+### Workflow statuses
+
+```
+Draft → Review → Approved → Scheduled → Published → Archived
+                    ↓
+              (Request Changes → Draft)
+```
+
+| Status | Description |
+|---|---|
+| `Draft` | Being authored; not publicly visible |
+| `Review` | Submitted for editorial review |
+| `Approved` | Approved by reviewer; ready to schedule or publish |
+| `Scheduled` | Will be published at `start_date` |
+| `Published` | Live and publicly visible |
+| `Archived` | Removed from public view; retained for reference |
+
+### Workflow roles
+
+| Role | Permitted actions |
+|---|---|
+| `ContentAuthor` | Create, edit draft, submit for review |
+| `ContentReviewer` | Approve, request changes |
+| `ContentPublisher` | Schedule, publish, unpublish |
+| `ContentAdministrator` | All actions including archive and delete |
+
+### Clone behaviour
+
+Cloning a content item:
+
+- Sets `status = "Draft"`
+- Appends `" (Copy)"` to the title
+- Clears `canonical_url`, `published_at`, `start_date`
+- Sets `created_from_content_id` to the source item's ID (provenance tracking)
+
+### Delete constraints
+
+Only `Draft` or `Archived` items may be deleted. Attempting to delete a `Published` item returns `409 Conflict`.
+
+---
+
+## Template design
+
+### Shared components
+
+All content detail pages use:
+
+- `BaseLayout` — head metadata, OG tags, canonical URL
+- `CtaBanner` — footer conversion banner
+- Inline markdown rendering via `marked` + `sanitizeBlogHtml`
+- Structured data injected via `<script type="application/ld+json">`
+
+### Layout structure
+
+```
+BaseLayout
+  ├── JSON-LD schemas (head slot)
+  └── main
+      ├── Breadcrumb nav
+      ├── Header (title, author, date, reading time, excerpt)
+      ├── Article content (prose markdown)
+      ├── Inline CTA aside
+      ├── Related content grid
+      ├── Back link
+      └── CtaBanner (footer)
+```
+
+### Prose styling
+
+Content is rendered with Tailwind Typography (`prose prose-invert prose-stone`), with:
+
+- `prose-a:text-teal-400` — teal link colour
+- `prose-img:rounded-xl` — rounded images
+- `max-w-4xl` page width container
+
+---
+
+## Accessibility
+
+The content pages are designed to meet WCAG 2.1 AA guidelines:
+
+- Heading hierarchy: `h1` for article title, `h2` for section headings, `h2` for related content section
+- Breadcrumb implemented as `<nav aria-label="Breadcrumb"><ol>` with `aria-current="page"` on the final item
+- Decorative separators use `aria-hidden="true"`
+- All `<svg>` icons include `aria-hidden="true"`
+- Links have descriptive text or `aria-label`
+- `<aside>` elements used for supplementary content (CTA, related)
+- `role="list"` on related content `<ul>` for VoiceOver compatibility
+
+---
+
+## Internal linking
+
+The platform supports internal linking through:
+
+1. **Related content blocks** — automatically populated from the `/content/{type}/related/{slug}` endpoint
+2. **Hub pages** — category-filtered views link content into topic clusters
+3. **Breadcrumbs** — each content page links back to its hub
+4. **Sitemap** — all published content included for crawl coverage
+
+The related content algorithm:
+
+1. Fetches all published items of the same content type
+2. Prefers items in the same category as the current item
+3. Backfills from other categories if needed
+4. Excludes the current item
+5. Returns up to `limit` items (default: 3)
+
+---
+
+## Testing
+
+### CMS service tests
+
+```bash
+cd services/cms-service && python -m pytest tests/ -q
+```
+
+Expected: all tests pass (93 tests across `test_routes.py` and `test_content.py`).
+
+Test coverage added in this issue:
+
+| Test class | Description |
+|---|---|
+| `TestPublicSearchAndRelated` | Search filtering, related content, 404 handling |
+| `TestWorkflowActions` | Auth guard tests for all workflow endpoints |
+| `TestNewStatuses` | `Approved`/`Scheduled` items not visible publicly |
+
+### Marketing site build
+
+```bash
+cd apps/marketing-site && npm ci && npm run build
+```
+
+The marketing site uses Vite 8.0.8 (pinned) with `vite.optimizeDeps.disabled=true` in `astro.config.mjs` to avoid a Tailwind/Vite regression.
+
+---
+
+## Adding a new content type
+
+1. Add the type slug to `VALID_CONTENT_TYPES` in `services/cms-service/app/models/schemas.py`
+2. Add a backward-compat public list endpoint in `services/cms-service/app/routers/content.py`
+3. Create a hub page in `apps/marketing-site/src/pages/{type}/index.astro`
+4. Create a detail page in `apps/marketing-site/src/pages/{type}/[slug].astro`
+5. Add the hub route to `staticRoutes` in `apps/marketing-site/src/pages/sitemap.xml.ts`
+6. Add sitemap content fetching for the new type
+7. Add tests
+
+---
+
+## File index
+
+| File | Description |
+|---|---|
+| `services/cms-service/app/models/schemas.py` | Pydantic schemas, `VALID_STATUSES`, `VALID_CONTENT_TYPES` |
+| `services/cms-service/app/routers/content.py` | All content endpoints (public + admin) |
+| `services/cms-service/tests/test_content.py` | Content API tests |
+| `apps/marketing-site/src/pages/guides/index.astro` | Guides hub page |
+| `apps/marketing-site/src/pages/guides/[slug].astro` | Guide detail page |
+| `apps/marketing-site/src/pages/articles/index.astro` | Articles hub page |
+| `apps/marketing-site/src/pages/articles/[slug].astro` | Article detail page |
+| `apps/marketing-site/src/pages/sitemap.xml.ts` | Dynamic sitemap (includes guides + articles) |
+| `apps/marketing-site/src/lib/content/cv-for-roles.ts` | Static CV For role data |
+| `apps/marketing-site/src/lib/sanitize.ts` | HTML sanitizer for CMS markdown |
diff --git a/services/cms-service/app/models/schemas.py b/services/cms-service/app/models/schemas.py
index 81bc380d..0bcff8e7 100644
--- a/services/cms-service/app/models/schemas.py
+++ b/services/cms-service/app/models/schemas.py
@@ -153,7 +153,7 @@ class ContentItemAdminSchema(ContentItemSchema):
 
 
 VALID_CONTENT_TYPES = {"Blog", "Guide", "Article", "CvFor"}
-VALID_STATUSES = {"Draft", "Review", "Published", "Archived"}
+VALID_STATUSES = {"Draft", "Review", "Approved", "Scheduled", "Published", "Archived"}
 VALID_CONTENT_SOURCES = {"Manual", "AiGenerated", "AiAssisted", "Imported"}
 
 
@@ -225,3 +225,28 @@ class ContentItemListResponse(BaseModel):
     total: int
     page: int
     page_size: int
+
+
+class WorkflowActionRequest(BaseModel):
+    """Generic workflow action request (submit for review, approve)."""
+    actor: str | None = Field(None, max_length=200)
+    notes: str | None = None
+
+
+class RequestChangesRequest(BaseModel):
+    """Request to send a content item back to the author for changes."""
+    reviewer: str | None = Field(None, max_length=200)
+    notes: str | None = None
+
+
+class ScheduleContentItemRequest(BaseModel):
+    """Request to schedule a content item for future publication."""
+    planned_publish_date: datetime
+    scheduled_by: str | None = Field(None, max_length=200)
+
+
+class CloneContentItemRequest(BaseModel):
+    """Request to clone a content item."""
+    new_slug: str = Field(..., min_length=1, max_length=250, pattern=r'^[a-z0-9]+(?:-[a-z0-9]+)*$')
+    new_title: str | None = Field(None, min_length=1, max_length=250)
+    cloned_by: str | None = Field(None, max_length=200)
diff --git a/services/cms-service/app/routers/content.py b/services/cms-service/app/routers/content.py
index 4498bc76..df394812 100644
--- a/services/cms-service/app/routers/content.py
+++ b/services/cms-service/app/routers/content.py
@@ -30,13 +30,17 @@
 from app.db import get_session
 from app.models.db_models import ContentItem
 from app.models.schemas import (
+    CloneContentItemRequest,
     ContentItemAdminSchema,
     ContentItemListResponse,
     ContentItemSchema,
     ContentItemSummarySchema,
     CreateContentItemRequest,
     PublishContentItemRequest,
+    RequestChangesRequest,
+    ScheduleContentItemRequest,
     UpdateContentItemRequest,
+    WorkflowActionRequest,
     VALID_CONTENT_TYPES,
     VALID_STATUSES,
     VALID_CONTENT_SOURCES,
@@ -239,6 +243,7 @@ async def list_published_content(
     type_slug: str,
     session: Annotated[AsyncSession, Depends(get_session)],
     category: str | None = Query(None),
+    search: str | None = Query(None),
     page: int = Query(1, ge=1),
     page_size: int = Query(20, ge=1, le=100),
 ) -> ContentItemListResponse:
@@ -258,6 +263,11 @@ async def list_published_content(
     ]
     if category:
         filters.append(ContentItem.category == category)
+    if search:
+        like = f"%{search}%"
+        filters.append(
+            ContentItem.title.ilike(like) | ContentItem.excerpt.ilike(like)
+        )
 
     count_result = await session.execute(
         select(func.count()).select_from(ContentItem).where(*filters)
@@ -282,6 +292,67 @@ async def list_published_content(
     )
 
 
+@router.get("/content/{type_slug}/related/{slug}", tags=["content"])
+async def get_related_content(
+    type_slug: str,
+    slug: str,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    limit: int = Query(3, ge=1, le=10),
+) -> ContentItemListResponse:
+    """Get related published content items for a given content type and slug.
+
+    Returns up to `limit` other published items of the same type, excluding the
+    current item, ordered by most recently published.  Prefers items from the
+    same category when available and backfills from other categories.
+    """
+    content_type = _SLUG_TO_TYPE.get(type_slug)
+    if content_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_INVALID_CONTENT_TYPE)
+
+    current = await _get_by_type_and_slug(session, content_type, slug)
+    if current is None or not _is_visible(current):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    now = datetime.now(timezone.utc)
+    from sqlalchemy import or_
+
+    base_filters = [
+        ContentItem.content_type == content_type,
+        ContentItem.slug != slug,
+        ContentItem.status == "Published",
+        or_(ContentItem.start_date.is_(None), ContentItem.start_date <= now),
+        or_(ContentItem.expiry_date.is_(None), ContentItem.expiry_date >= now),
+    ]
+
+    items: list[ContentItem] = []
+    if current.category:
+        category_result = await session.execute(
+            select(ContentItem)
+            .where(*base_filters, ContentItem.category == current.category)
+            .order_by(ContentItem.published_at.desc().nullslast(), ContentItem.created_at.desc())
+            .limit(limit)
+        )
+        items = list(category_result.scalars().all())
+
+    if len(items) < limit:
+        needed = limit - len(items)
+        seen_ids = {i.id for i in items} | {current.id}
+        fallback_result = await session.execute(
+            select(ContentItem)
+            .where(*base_filters, ContentItem.id.not_in(seen_ids))
+            .order_by(ContentItem.published_at.desc().nullslast(), ContentItem.created_at.desc())
+            .limit(needed)
+        )
+        items = items + list(fallback_result.scalars().all())
+
+    return ContentItemListResponse(
+        items=[_to_summary(i) for i in items],
+        total=len(items),
+        page=1,
+        page_size=limit,
+    )
+
+
 @router.get("/content/{type_slug}/{slug}", tags=["content"])
 async def get_published_content(
     type_slug: str,
@@ -306,11 +377,12 @@ async def get_published_content(
 async def list_published_guides(
     session: Annotated[AsyncSession, Depends(get_session)],
     category: str | None = Query(None),
+    search: str | None = Query(None),
     page: int = Query(1, ge=1),
     page_size: int = Query(20, ge=1, le=100),
 ) -> ContentItemListResponse:
     """List published guides."""
-    return await list_published_content("guides", session, category, page, page_size)
+    return await list_published_content("guides", session, category, search, page, page_size)
 
 
 @router.get("/guides/{slug}", tags=["guides"])
@@ -326,11 +398,12 @@ async def get_published_guide(
 async def list_published_articles(
     session: Annotated[AsyncSession, Depends(get_session)],
     category: str | None = Query(None),
+    search: str | None = Query(None),
     page: int = Query(1, ge=1),
     page_size: int = Query(20, ge=1, le=100),
 ) -> ContentItemListResponse:
     """List published articles."""
-    return await list_published_content("articles", session, category, page, page_size)
+    return await list_published_content("articles", session, category, search, page, page_size)
 
 
 @router.get("/articles/{slug}", tags=["articles"])
@@ -346,11 +419,12 @@ async def get_published_article(
 async def list_published_cv_for(
     session: Annotated[AsyncSession, Depends(get_session)],
     category: str | None = Query(None),
+    search: str | None = Query(None),
     page: int = Query(1, ge=1),
     page_size: int = Query(20, ge=1, le=100),
 ) -> ContentItemListResponse:
     """List published CV-For pages."""
-    return await list_published_content("cv-for", session, category, page, page_size)
+    return await list_published_content("cv-for", session, category, search, page, page_size)
 
 
 @router.get("/cv-for/{slug}", tags=["cv-for"])
@@ -625,3 +699,232 @@ async def archive_content_item(
 
     logger.info("Archived content item: %s/%s (id=%s)", item.content_type, item.slug, item.id)
     return _to_admin_schema(item)
+
+
+@router.post("/admin/content/{item_id}/submit-review", tags=["admin"])
+async def submit_content_for_review(
+    item_id: str,
+    req: WorkflowActionRequest,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    user: Annotated[dict, Depends(require_admin)],
+) -> ContentItemAdminSchema:
+    """Submit a content item for editorial review (Draft → Review)."""
+    item_uuid = _parse_item_id(item_id)
+    item = await _get_by_id(session, item_uuid)
+    if item is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    actor = req.actor or user.get("sub") or user.get("email")
+    now = datetime.now(timezone.utc)
+    item.status = "Review"
+    item.last_workflow_action_by = actor
+    item.last_workflow_action_at = now
+    item.updated_at = now
+    if req.notes:
+        item.editorial_notes = req.notes
+
+    session.add(item)
+    await session.commit()
+    await session.refresh(item)
+
+    logger.info("Submitted content item for review: %s/%s (id=%s)", item.content_type, item.slug, item.id)
+    return _to_admin_schema(item)
+
+
+@router.post("/admin/content/{item_id}/approve", tags=["admin"])
+async def approve_content_item(
+    item_id: str,
+    req: WorkflowActionRequest,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    user: Annotated[dict, Depends(require_admin)],
+) -> ContentItemAdminSchema:
+    """Approve a content item (Review → Approved)."""
+    item_uuid = _parse_item_id(item_id)
+    item = await _get_by_id(session, item_uuid)
+    if item is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    actor = req.actor or user.get("sub") or user.get("email")
+    now = datetime.now(timezone.utc)
+    item.status = "Approved"
+    item.approved_by = actor
+    item.last_workflow_action_by = actor
+    item.last_workflow_action_at = now
+    item.updated_at = now
+    if req.notes:
+        item.editorial_notes = req.notes
+
+    session.add(item)
+    await session.commit()
+    await session.refresh(item)
+
+    logger.info("Approved content item: %s/%s (id=%s)", item.content_type, item.slug, item.id)
+    return _to_admin_schema(item)
+
+
+@router.post("/admin/content/{item_id}/request-changes", tags=["admin"])
+async def request_content_changes(
+    item_id: str,
+    req: RequestChangesRequest,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    user: Annotated[dict, Depends(require_admin)],
+) -> ContentItemAdminSchema:
+    """Request changes on a content item (Review → Draft)."""
+    item_uuid = _parse_item_id(item_id)
+    item = await _get_by_id(session, item_uuid)
+    if item is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    actor = req.reviewer or user.get("sub") or user.get("email")
+    now = datetime.now(timezone.utc)
+    item.status = "Draft"
+    item.last_workflow_action_by = actor
+    item.last_workflow_action_at = now
+    item.updated_at = now
+    if req.notes:
+        item.editorial_notes = req.notes
+
+    session.add(item)
+    await session.commit()
+    await session.refresh(item)
+
+    logger.info("Requested changes on content item: %s/%s (id=%s)", item.content_type, item.slug, item.id)
+    return _to_admin_schema(item)
+
+
+@router.post("/admin/content/{item_id}/schedule", tags=["admin"])
+async def schedule_content_item(
+    item_id: str,
+    req: ScheduleContentItemRequest,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    user: Annotated[dict, Depends(require_admin)],
+) -> ContentItemAdminSchema:
+    """Schedule a content item for future publication (Approved → Scheduled)."""
+    item_uuid = _parse_item_id(item_id)
+    item = await _get_by_id(session, item_uuid)
+    if item is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    actor = req.scheduled_by or user.get("sub") or user.get("email")
+    now = datetime.now(timezone.utc)
+    item.status = "Scheduled"
+    item.start_date = req.planned_publish_date
+    item.last_workflow_action_by = actor
+    item.last_workflow_action_at = now
+    item.updated_at = now
+
+    session.add(item)
+    await session.commit()
+    await session.refresh(item)
+
+    logger.info("Scheduled content item: %s/%s (id=%s, date=%s)", item.content_type, item.slug, item.id, req.planned_publish_date)
+    return _to_admin_schema(item)
+
+
+@router.post("/admin/content/{item_id}/unpublish", tags=["admin"])
+async def unpublish_content_item(
+    item_id: str,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    user: Annotated[dict, Depends(require_admin)],
+) -> ContentItemAdminSchema:
+    """Unpublish a content item, returning it to Draft status."""
+    item_uuid = _parse_item_id(item_id)
+    item = await _get_by_id(session, item_uuid)
+    if item is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    actor = user.get("sub") or user.get("email")
+    now = datetime.now(timezone.utc)
+    item.status = "Draft"
+    item.last_workflow_action_by = actor
+    item.last_workflow_action_at = now
+    item.updated_at = now
+
+    session.add(item)
+    await session.commit()
+    await session.refresh(item)
+
+    logger.info("Unpublished content item: %s/%s (id=%s)", item.content_type, item.slug, item.id)
+    return _to_admin_schema(item)
+
+
+@router.post("/admin/content/{item_id}/clone", status_code=status.HTTP_201_CREATED, tags=["admin"])
+async def clone_content_item(
+    item_id: str,
+    req: CloneContentItemRequest,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    user: Annotated[dict, Depends(require_admin)],
+) -> ContentItemAdminSchema:
+    """Clone a content item, creating a Draft copy with a new slug."""
+    item_uuid = _parse_item_id(item_id)
+    source = await _get_by_id(session, item_uuid)
+    if source is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    await _ensure_slug_available(session, source.content_type, req.new_slug)
+
+    actor = req.cloned_by or user.get("sub") or user.get("email")
+    now = datetime.now(timezone.utc)
+    clone = ContentItem(
+        id=uuid.uuid4(),
+        content_type=source.content_type,
+        category=source.category,
+        title=req.new_title or f"{source.title} (copy)",
+        slug=req.new_slug,
+        excerpt=source.excerpt,
+        content_markdown=source.content_markdown,
+        author_name=source.author_name,
+        status="Draft",
+        seo_title=source.seo_title,
+        seo_description=source.seo_description,
+        canonical_url=None,
+        target_keyword=source.target_keyword,
+        search_intent=source.search_intent,
+        start_date=None,
+        expiry_date=None,
+        reading_time_minutes=source.reading_time_minutes,
+        content_source=source.content_source,
+        author_id=source.author_id,
+        primary_topic=source.primary_topic,
+        cluster_id=source.cluster_id,
+        hub_page_id=source.hub_page_id,
+        editorial_notes=source.editorial_notes,
+        ai_generated=source.ai_generated,
+        ai_prompt_version=source.ai_prompt_version,
+        created_by=actor,
+        created_from_content_id=source.id,
+        last_workflow_action_by=actor,
+        last_workflow_action_at=now,
+        created_at=now,
+        updated_at=now,
+    )
+
+    session.add(clone)
+    await session.commit()
+    await session.refresh(clone)
+
+    logger.info("Cloned content item: %s → %s (id=%s)", source.slug, clone.slug, clone.id)
+    return _to_admin_schema(clone)
+
+
+@router.delete("/admin/content/{item_id}", status_code=status.HTTP_204_NO_CONTENT, tags=["admin"])
+async def delete_content_item(
+    item_id: str,
+    session: Annotated[AsyncSession, Depends(get_session)],
+    user: Annotated[dict, Depends(require_admin)],
+) -> None:
+    """Permanently delete a content item. Only Draft or Archived items may be deleted."""
+    item_uuid = _parse_item_id(item_id)
+    item = await _get_by_id(session, item_uuid)
+    if item is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
+
+    if item.status not in {"Draft", "Archived"}:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Only Draft or Archived content items may be deleted. Archive the item first.",
+        )
+
+    logger.info("Deleting content item: %s/%s (id=%s)", item.content_type, item.slug, item.id)
+    await session.delete(item)
+    await session.commit()
diff --git a/services/cms-service/tests/test_content.py b/services/cms-service/tests/test_content.py
index cda0e66c..e34f968e 100644
--- a/services/cms-service/tests/test_content.py
+++ b/services/cms-service/tests/test_content.py
@@ -401,3 +401,194 @@ async def test_same_slug_different_types_both_visible(self, client, test_db):
         assert article_response.status_code == 200
         assert guide_response.json()["content_type"] == "Guide"
         assert article_response.json()["content_type"] == "Article"
+
+
+@pytest.mark.asyncio
+class TestPublicSearchAndRelated:
+    """Tests for search and related-content on public endpoints."""
+
+    async def _create_item(self, session: AsyncSession, **kwargs) -> ContentItem:
+        now = datetime.now(timezone.utc)
+        defaults = {
+            "id": uuid.uuid4(),
+            "content_type": "Guide",
+            "title": "Default Guide",
+            "slug": "default-guide",
+            "content_markdown": "# Guide",
+            "author_name": "Author",
+            "status": "Published",
+            "content_source": "Manual",
+            "ai_generated": False,
+            "created_at": now,
+            "updated_at": now,
+        }
+        defaults.update(kwargs)
+        item = ContentItem(**defaults)
+        session.add(item)
+        await session.commit()
+        await session.refresh(item)
+        return item
+
+    async def test_search_filters_by_title(self, client, test_db):
+        """GET /guides?search=X returns only guides whose title matches."""
+        async with test_db() as session:
+            await self._create_item(session, slug="ats-guide", title="ATS Optimisation Guide", status="Published")
+            await self._create_item(session, slug="cv-tips", title="CV Writing Tips", status="Published")
+
+        response = await client.get("/guides?search=ATS")
+        assert response.status_code == 200
+        slugs = [i["slug"] for i in response.json()["items"]]
+        assert "ats-guide" in slugs
+        assert "cv-tips" not in slugs
+
+    async def test_search_is_case_insensitive(self, client, test_db):
+        """Search is case-insensitive."""
+        async with test_db() as session:
+            await self._create_item(session, slug="search-guide", title="Interview Preparation Guide", status="Published")
+
+        response = await client.get("/guides?search=interview")
+        assert response.status_code == 200
+        slugs = [i["slug"] for i in response.json()["items"]]
+        assert "search-guide" in slugs
+
+    async def test_search_no_results(self, client, test_db):
+        """Search with no matches returns empty list."""
+        async with test_db() as session:
+            await self._create_item(session, slug="some-guide", title="Some Guide", status="Published")
+
+        response = await client.get("/guides?search=zzznomatch")
+        assert response.status_code == 200
+        assert response.json()["items"] == []
+
+    async def test_related_content_returns_same_type(self, client, test_db):
+        """GET /content/guides/related/{slug} returns other published guides."""
+        async with test_db() as session:
+            await self._create_item(session, slug="main-guide", title="Main Guide", status="Published")
+            await self._create_item(session, slug="other-guide", title="Other Guide", status="Published")
+            await self._create_item(session, slug="draft-guide", title="Draft Guide", status="Draft")
+
+        response = await client.get("/content/guides/related/main-guide")
+        assert response.status_code == 200
+        data = response.json()
+        slugs = [i["slug"] for i in data["items"]]
+        assert "other-guide" in slugs
+        assert "main-guide" not in slugs
+        assert "draft-guide" not in slugs
+
+    async def test_related_content_excludes_current(self, client, test_db):
+        """Related content endpoint never returns the current item."""
+        async with test_db() as session:
+            await self._create_item(session, slug="anchor-guide", status="Published")
+
+        response = await client.get("/content/guides/related/anchor-guide")
+        assert response.status_code == 200
+        slugs = [i["slug"] for i in response.json()["items"]]
+        assert "anchor-guide" not in slugs
+
+    async def test_related_content_invalid_type_returns_404(self, client):
+        """GET /content/unknown/related/slug returns 404."""
+        response = await client.get("/content/unknown/related/any-slug")
+        assert response.status_code == 404
+
+    async def test_related_content_unknown_slug_returns_404(self, client, test_db):
+        """GET /content/guides/related/no-such returns 404."""
+        response = await client.get("/content/guides/related/no-such-slug")
+        assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+class TestWorkflowActions:
+    """Tests for new workflow action endpoints (auth guards only — full workflow integration tested separately)."""
+
+    async def test_submit_review_requires_auth(self, client):
+        """POST /admin/content/{id}/submit-review requires authentication."""
+        response = await client.post(f"/admin/content/{uuid.uuid4()}/submit-review", json={})
+        assert response.status_code == 401
+
+    async def test_approve_requires_auth(self, client):
+        """POST /admin/content/{id}/approve requires authentication."""
+        response = await client.post(f"/admin/content/{uuid.uuid4()}/approve", json={})
+        assert response.status_code == 401
+
+    async def test_request_changes_requires_auth(self, client):
+        """POST /admin/content/{id}/request-changes requires authentication."""
+        response = await client.post(f"/admin/content/{uuid.uuid4()}/request-changes", json={})
+        assert response.status_code == 401
+
+    async def test_schedule_requires_auth(self, client):
+        """POST /admin/content/{id}/schedule requires authentication."""
+        response = await client.post(
+            f"/admin/content/{uuid.uuid4()}/schedule",
+            json={"planned_publish_date": "2027-01-01T00:00:00Z"},
+        )
+        assert response.status_code == 401
+
+    async def test_unpublish_requires_auth(self, client):
+        """POST /admin/content/{id}/unpublish requires authentication."""
+        response = await client.post(f"/admin/content/{uuid.uuid4()}/unpublish")
+        assert response.status_code == 401
+
+    async def test_clone_requires_auth(self, client):
+        """POST /admin/content/{id}/clone requires authentication."""
+        response = await client.post(
+            f"/admin/content/{uuid.uuid4()}/clone",
+            json={"new_slug": "clone-slug"},
+        )
+        assert response.status_code == 401
+
+    async def test_delete_requires_auth(self, client):
+        """DELETE /admin/content/{id} requires authentication."""
+        response = await client.delete(f"/admin/content/{uuid.uuid4()}")
+        assert response.status_code == 401
+
+
+@pytest.mark.asyncio
+class TestNewStatuses:
+    """Tests verifying Approved and Scheduled statuses are accepted."""
+
+    async def test_approved_status_not_public(self, client, test_db):
+        """Approved items are not visible on public endpoints."""
+        now = datetime.now(timezone.utc)
+        async with test_db() as session:
+            item = ContentItem(
+                id=uuid.uuid4(),
+                content_type="Guide",
+                title="Approved Guide",
+                slug="approved-guide",
+                content_markdown="# Content",
+                author_name="Author",
+                status="Approved",
+                content_source="Manual",
+                ai_generated=False,
+                created_at=now,
+                updated_at=now,
+            )
+            session.add(item)
+            await session.commit()
+
+        response = await client.get("/guides/approved-guide")
+        assert response.status_code == 404
+
+    async def test_scheduled_status_not_public_before_start_date(self, client, test_db):
+        """Scheduled items with a future start_date are not visible on public endpoints."""
+        now = datetime.now(timezone.utc)
+        async with test_db() as session:
+            item = ContentItem(
+                id=uuid.uuid4(),
+                content_type="Article",
+                title="Scheduled Article",
+                slug="scheduled-article",
+                content_markdown="# Content",
+                author_name="Author",
+                status="Scheduled",
+                start_date=now + timedelta(days=7),
+                content_source="Manual",
+                ai_generated=False,
+                created_at=now,
+                updated_at=now,
+            )
+            session.add(item)
+            await session.commit()
+
+        response = await client.get("/articles/scheduled-article")
+        assert response.status_code == 404

From 68982361f37ec9052c63004f574c0be45285280b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 30 May 2026 06:31:41 +0000
Subject: [PATCH 3/6] refactor(content-ui): address code review feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Move `or_` import to module level in content.py
- Escape LIKE wildcards (%, _) in search params to prevent unexpected results
- Extract shared `calcReadingTime` and `extractCategories` utilities into
  lib/content/content-utils.ts; use in all four hub/detail pages
- Restore explicit BlogPost interface in sitemap.xml.ts; remove inline type
- Update docs/content-ui.md: WCAG 2.1 → WCAG 2.2 AA

Co-authored-by: NickLetts2 <90337962+NickLetts2@users.noreply.github.com>
---
 .../src/lib/content/content-utils.ts          | 25 +++++++++++++++++++
 .../src/pages/articles/[slug].astro           |  4 +--
 .../src/pages/articles/index.astro            |  6 ++---
 .../src/pages/guides/[slug].astro             |  4 +--
 .../src/pages/guides/index.astro              |  7 ++----
 apps/marketing-site/src/pages/sitemap.xml.ts  |  8 +++++-
 docs/content-ui.md                            |  2 +-
 services/cms-service/app/routers/content.py   | 10 ++++----
 8 files changed, 46 insertions(+), 20 deletions(-)
 create mode 100644 apps/marketing-site/src/lib/content/content-utils.ts

diff --git a/apps/marketing-site/src/lib/content/content-utils.ts b/apps/marketing-site/src/lib/content/content-utils.ts
new file mode 100644
index 00000000..0c1155e4
--- /dev/null
+++ b/apps/marketing-site/src/lib/content/content-utils.ts
@@ -0,0 +1,25 @@
+/**
+ * Shared content utility helpers used by content hub and detail pages.
+ */
+
+/** Words-per-minute used for reading time estimation. */
+const WORDS_PER_MINUTE = 200;
+
+/**
+ * Returns estimated reading time in minutes from markdown text.
+ * Falls back to the CMS-provided value when available.
+ */
+export function calcReadingTime(markdown: string, cmsValue?: number | null): number {
+  if (cmsValue != null && cmsValue > 0) return cmsValue;
+  const wordCount = markdown.trim().split(/\s+/).length;
+  return Math.max(1, Math.round(wordCount / WORDS_PER_MINUTE));
+}
+
+/**
+ * Extracts a sorted, deduplicated list of category strings from a list of
+ * content items. Items with a null or empty category are ignored.
+ */
+export function extractCategories(items: { category?: string | null }[]): string[] {
+  const cats = items.map((i) => i.category).filter((c): c is string => !!c);
+  return [...new Set(cats)].sort();
+}
diff --git a/apps/marketing-site/src/pages/articles/[slug].astro b/apps/marketing-site/src/pages/articles/[slug].astro
index 4a8142ae..3468c84d 100644
--- a/apps/marketing-site/src/pages/articles/[slug].astro
+++ b/apps/marketing-site/src/pages/articles/[slug].astro
@@ -5,6 +5,7 @@ import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { marked } from 'marked';
 import { sanitizeBlogHtml } from '../../lib/sanitize';
 import { appUrl, siteUrl } from '../../config';
+import { calcReadingTime } from '../../lib/content/content-utils';
 
 const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
 const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
@@ -83,8 +84,7 @@ const formattedUpdated = wasUpdated
   ? new Date(article.updated_at).toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })
   : null;
 
-const wordCount = article.content_markdown.trim().split(/\s+/).length;
-const readMins = article.reading_time_minutes ?? Math.max(1, Math.round(wordCount / 200));
+const readMins = calcReadingTime(article.content_markdown, article.reading_time_minutes);
 const readingTime = `${readMins} min read`;
 
 const pageTitle = `${article.seo_title ?? article.title} | Curvit Articles`;
diff --git a/apps/marketing-site/src/pages/articles/index.astro b/apps/marketing-site/src/pages/articles/index.astro
index 02ed4295..ae98bf0b 100644
--- a/apps/marketing-site/src/pages/articles/index.astro
+++ b/apps/marketing-site/src/pages/articles/index.astro
@@ -3,6 +3,7 @@
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { appUrl, siteUrl } from '../../config';
+import { extractCategories } from '../../lib/content/content-utils';
 
 const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
 const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
@@ -48,10 +49,7 @@ try {
   const res = await fetch(`${cmsBase}/articles?${params}`, { headers });
   if (res.ok) {
     articlesData = await res.json();
-    const allCategories = articlesData.items
-      .map((a) => a.category)
-      .filter((c): c is string => !!c);
-    categories = [...new Set(allCategories)].sort();
+    categories = extractCategories(articlesData.items);
   } else {
     fetchError = true;
   }
diff --git a/apps/marketing-site/src/pages/guides/[slug].astro b/apps/marketing-site/src/pages/guides/[slug].astro
index ab1f33d9..0490c50a 100644
--- a/apps/marketing-site/src/pages/guides/[slug].astro
+++ b/apps/marketing-site/src/pages/guides/[slug].astro
@@ -5,6 +5,7 @@ import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { marked } from 'marked';
 import { sanitizeBlogHtml } from '../../lib/sanitize';
 import { appUrl, siteUrl } from '../../config';
+import { calcReadingTime } from '../../lib/content/content-utils';
 
 const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
 const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
@@ -86,8 +87,7 @@ const formattedUpdated = wasUpdated
   ? new Date(guide.updated_at).toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })
   : null;
 
-const wordCount = guide.content_markdown.trim().split(/\s+/).length;
-const readMins = guide.reading_time_minutes ?? Math.max(1, Math.round(wordCount / 200));
+const readMins = calcReadingTime(guide.content_markdown, guide.reading_time_minutes);
 const readingTime = `${readMins} min read`;
 
 const pageTitle = `${guide.seo_title ?? guide.title} | Curvit Guides`;
diff --git a/apps/marketing-site/src/pages/guides/index.astro b/apps/marketing-site/src/pages/guides/index.astro
index 20e2a90c..6affd53e 100644
--- a/apps/marketing-site/src/pages/guides/index.astro
+++ b/apps/marketing-site/src/pages/guides/index.astro
@@ -3,6 +3,7 @@
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { appUrl, siteUrl } from '../../config';
+import { extractCategories } from '../../lib/content/content-utils';
 
 const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
 const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
@@ -49,11 +50,7 @@ try {
   const res = await fetch(`${cmsBase}/guides?${params}`, { headers });
   if (res.ok) {
     guidesData = await res.json();
-    // Build unique category list for filtering UI
-    const allCategories = guidesData.items
-      .map((g) => g.category)
-      .filter((c): c is string => !!c);
-    categories = [...new Set(allCategories)].sort();
+    categories = extractCategories(guidesData.items);
   } else {
     fetchError = true;
   }
diff --git a/apps/marketing-site/src/pages/sitemap.xml.ts b/apps/marketing-site/src/pages/sitemap.xml.ts
index 82dddbad..946c00c8 100644
--- a/apps/marketing-site/src/pages/sitemap.xml.ts
+++ b/apps/marketing-site/src/pages/sitemap.xml.ts
@@ -11,6 +11,12 @@ interface ContentListResponse {
   items: ContentItemSummary[];
 }
 
+interface BlogPost {
+  slug: string;
+  start_date?: string;
+  created_at?: string;
+}
+
 // Static public routes only - NO user-specific or authenticated content
 const staticRoutes = [
   '/',
@@ -69,7 +75,7 @@ export const GET: APIRoute = async ({ site }) => {
     const res = await fetch(cmsUrl, { headers });
 
     if (res.ok) {
-      const posts: { slug: string; start_date?: string; created_at?: string }[] = await res.json();
+      const posts: BlogPost[] = await res.json();
       const now = new Date();
       let includedCount = 0;
 
diff --git a/docs/content-ui.md b/docs/content-ui.md
index 08e954fc..29bb02a2 100644
--- a/docs/content-ui.md
+++ b/docs/content-ui.md
@@ -304,7 +304,7 @@ Content is rendered with Tailwind Typography (`prose prose-invert prose-stone`),
 
 ## Accessibility
 
-The content pages are designed to meet WCAG 2.1 AA guidelines:
+The content pages are designed to meet WCAG 2.2 AA guidelines:
 
 - Heading hierarchy: `h1` for article title, `h2` for section headings, `h2` for related content section
 - Breadcrumb implemented as `<nav aria-label="Breadcrumb"><ol>` with `aria-current="page"` on the final item
diff --git a/services/cms-service/app/routers/content.py b/services/cms-service/app/routers/content.py
index df394812..26c41ca0 100644
--- a/services/cms-service/app/routers/content.py
+++ b/services/cms-service/app/routers/content.py
@@ -23,7 +23,7 @@
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
-from sqlalchemy import func, select
+from sqlalchemy import func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.auth import require_admin
@@ -253,7 +253,6 @@ async def list_published_content(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_INVALID_CONTENT_TYPE)
 
     now = datetime.now(timezone.utc)
-    from sqlalchemy import or_
 
     filters = [
         ContentItem.content_type == content_type,
@@ -264,7 +263,8 @@ async def list_published_content(
     if category:
         filters.append(ContentItem.category == category)
     if search:
-        like = f"%{search}%"
+        escaped = search.replace("\\", "\\\\").replace("%", r"\%").replace("_", r"\_")
+        like = f"%{escaped}%"
         filters.append(
             ContentItem.title.ilike(like) | ContentItem.excerpt.ilike(like)
         )
@@ -314,7 +314,6 @@ async def get_related_content(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
 
     now = datetime.now(timezone.utc)
-    from sqlalchemy import or_
 
     base_filters = [
         ContentItem.content_type == content_type,
@@ -461,7 +460,8 @@ async def list_all_content(
     if target_keyword:
         filters.append(ContentItem.target_keyword == target_keyword)
     if search:
-        like = f"%{search}%"
+        escaped = search.replace("\\", "\\\\").replace("%", r"\%").replace("_", r"\_")
+        like = f"%{escaped}%"
         filters.append(
             ContentItem.title.ilike(like) | ContentItem.excerpt.ilike(like)
         )

From c3c24868b11e75bffef0d2de9817e1f0cbb6cf57 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 30 May 2026 06:38:24 +0000
Subject: [PATCH 4/6] refactor(content-ui): address remaining code review
 feedback

- Extract _escape_like() helper; escape [ and ] in LIKE wildcards
- Extract _resolve_actor() helper; use across all workflow endpoints
- Add create_content_item() to conftest.py; remove duplicate _create_item
  methods from TestContentPublicRoutes, TestSlugUniquenessPerType,
  TestPublicSearchAndRelated
- Add lib/cms-client.ts with cmsBase/internalApiKey/cmsHeaders(); use in
  all four content pages (guides/articles hub + detail pages)
- Add buildPaginationUrl() to content-utils.ts; use in guides/articles
  hub pages pagination links
- Add explicit slug guard (if !slug return redirect) in detail pages
- Document word-count approximation limitation in content-utils.ts

All 93 CMS tests pass.

Co-authored-by: NickLetts2 <90337962+NickLetts2@users.noreply.github.com>
---
 apps/marketing-site/src/lib/cms-client.ts     |  19 +++
 .../src/lib/content/content-utils.ts          |  23 ++++
 .../src/pages/articles/[slug].astro           |  11 +-
 .../src/pages/articles/index.astro            |  13 +-
 .../src/pages/guides/[slug].astro             |  12 +-
 .../src/pages/guides/index.astro              |  13 +-
 services/cms-service/app/routers/content.py   |  37 ++++--
 services/cms-service/tests/conftest.py        |  31 ++++-
 services/cms-service/tests/test_content.py    | 119 ++++--------------
 9 files changed, 143 insertions(+), 135 deletions(-)
 create mode 100644 apps/marketing-site/src/lib/cms-client.ts

diff --git a/apps/marketing-site/src/lib/cms-client.ts b/apps/marketing-site/src/lib/cms-client.ts
new file mode 100644
index 00000000..e4f8c068
--- /dev/null
+++ b/apps/marketing-site/src/lib/cms-client.ts
@@ -0,0 +1,19 @@
+/**
+ * Shared CMS client configuration for server-side Astro pages.
+ *
+ * Centralises the CMS service URL and internal API key resolution so that
+ * all content pages read from the same environment variables.
+ */
+
+export const cmsBase =
+  process.env.CMS_SERVICE_URL ||
+  import.meta.env.CMS_SERVICE_URL ||
+  'http://cms-service:8000';
+
+export const internalApiKey =
+  process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+
+/** Returns headers for authenticated CMS requests, or undefined if no key is configured. */
+export function cmsHeaders(): Record<string, string> | undefined {
+  return internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
+}
diff --git a/apps/marketing-site/src/lib/content/content-utils.ts b/apps/marketing-site/src/lib/content/content-utils.ts
index 0c1155e4..b3f286f2 100644
--- a/apps/marketing-site/src/lib/content/content-utils.ts
+++ b/apps/marketing-site/src/lib/content/content-utils.ts
@@ -8,6 +8,9 @@ const WORDS_PER_MINUTE = 200;
 /**
  * Returns estimated reading time in minutes from markdown text.
  * Falls back to the CMS-provided value when available.
+ *
+ * Note: word count splits on whitespace and does not strip markdown syntax
+ * (e.g. code fences, link text), so the estimate is approximate.
  */
 export function calcReadingTime(markdown: string, cmsValue?: number | null): number {
   if (cmsValue != null && cmsValue > 0) return cmsValue;
@@ -23,3 +26,23 @@ export function extractCategories(items: { category?: string | null }[]): string
   const cats = items.map((i) => i.category).filter((c): c is string => !!c);
   return [...new Set(cats)].sort();
 }
+
+/**
+ * Builds a paginated hub URL, preserving search and category query params.
+ *
+ * @param basePath  Hub path, e.g. `/guides/`
+ * @param page      Target page number
+ * @param search    Current search query (empty string = omit)
+ * @param category  Current category filter (empty string = omit)
+ */
+export function buildPaginationUrl(
+  basePath: string,
+  page: number,
+  search: string,
+  category: string,
+): string {
+  let url = `${basePath}?page=${page}`;
+  if (search) url += `&search=${encodeURIComponent(search)}`;
+  if (category) url += `&category=${encodeURIComponent(category)}`;
+  return url;
+}
diff --git a/apps/marketing-site/src/pages/articles/[slug].astro b/apps/marketing-site/src/pages/articles/[slug].astro
index 3468c84d..91b82024 100644
--- a/apps/marketing-site/src/pages/articles/[slug].astro
+++ b/apps/marketing-site/src/pages/articles/[slug].astro
@@ -6,11 +6,10 @@ import { marked } from 'marked';
 import { sanitizeBlogHtml } from '../../lib/sanitize';
 import { appUrl, siteUrl } from '../../config';
 import { calcReadingTime } from '../../lib/content/content-utils';
-
-const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
-const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+import { cmsBase, cmsHeaders } from '../../lib/cms-client';
 
 const { slug } = Astro.params;
+if (!slug) return Astro.redirect('/404', 404);
 
 interface ArticleDetail {
   id: string;
@@ -45,8 +44,7 @@ let article: ArticleDetail | null = null;
 let relatedItems: RelatedItem[] = [];
 
 try {
-  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
-  const res = await fetch(`${cmsBase}/articles/${encodeURIComponent(slug!)}`, { headers });
+  const res = await fetch(`${cmsBase}/articles/${encodeURIComponent(slug)}`, { headers: cmsHeaders() });
   if (res.ok) {
     article = await res.json();
   }
@@ -60,8 +58,7 @@ if (!article) {
 
 // Related articles (best-effort)
 try {
-  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
-  const relRes = await fetch(`${cmsBase}/content/articles/related/${encodeURIComponent(slug!)}?limit=3`, { headers });
+  const relRes = await fetch(`${cmsBase}/content/articles/related/${encodeURIComponent(slug)}?limit=3`, { headers: cmsHeaders() });
   if (relRes.ok) {
     const relData = await relRes.json();
     relatedItems = relData.items ?? [];
diff --git a/apps/marketing-site/src/pages/articles/index.astro b/apps/marketing-site/src/pages/articles/index.astro
index ae98bf0b..c517883e 100644
--- a/apps/marketing-site/src/pages/articles/index.astro
+++ b/apps/marketing-site/src/pages/articles/index.astro
@@ -3,10 +3,8 @@
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { appUrl, siteUrl } from '../../config';
-import { extractCategories } from '../../lib/content/content-utils';
-
-const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
-const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+import { extractCategories, buildPaginationUrl } from '../../lib/content/content-utils';
+import { cmsBase, cmsHeaders } from '../../lib/cms-client';
 
 const url = new URL(Astro.request.url);
 const searchQuery = url.searchParams.get('search') ?? '';
@@ -38,7 +36,6 @@ let fetchError = false;
 let categories: string[] = [];
 
 try {
-  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
   const params = new URLSearchParams({
     page: String(currentPage),
     page_size: String(PAGE_SIZE),
@@ -46,7 +43,7 @@ try {
   if (searchQuery) params.set('search', searchQuery);
   if (categoryFilter) params.set('category', categoryFilter);
 
-  const res = await fetch(`${cmsBase}/articles?${params}`, { headers });
+  const res = await fetch(`${cmsBase}/articles?${params}`, { headers: cmsHeaders() });
   if (res.ok) {
     articlesData = await res.json();
     categories = extractCategories(articlesData.items);
@@ -236,7 +233,7 @@ const breadcrumbSchema = {
       <nav aria-label="Pagination" class="mt-12 flex items-center justify-center gap-2">
         {currentPage > 1 && (
           <a
-            href={`/articles/?page=${currentPage - 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            href={buildPaginationUrl('/articles/', currentPage - 1, searchQuery, categoryFilter)}
             class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
             aria-label="Previous page"
           >
@@ -248,7 +245,7 @@ const breadcrumbSchema = {
         </span>
         {currentPage < totalPages && (
           <a
-            href={`/articles/?page=${currentPage + 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            href={buildPaginationUrl('/articles/', currentPage + 1, searchQuery, categoryFilter)}
             class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
             aria-label="Next page"
           >
diff --git a/apps/marketing-site/src/pages/guides/[slug].astro b/apps/marketing-site/src/pages/guides/[slug].astro
index 0490c50a..19fe97cc 100644
--- a/apps/marketing-site/src/pages/guides/[slug].astro
+++ b/apps/marketing-site/src/pages/guides/[slug].astro
@@ -6,11 +6,10 @@ import { marked } from 'marked';
 import { sanitizeBlogHtml } from '../../lib/sanitize';
 import { appUrl, siteUrl } from '../../config';
 import { calcReadingTime } from '../../lib/content/content-utils';
-
-const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
-const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+import { cmsBase, cmsHeaders } from '../../lib/cms-client';
 
 const { slug } = Astro.params;
+if (!slug) return Astro.redirect('/404', 404);
 
 interface GuideDetail {
   id: string;
@@ -45,9 +44,7 @@ let guide: GuideDetail | null = null;
 let relatedItems: RelatedItem[] = [];
 
 try {
-  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
-
-  const res = await fetch(`${cmsBase}/guides/${encodeURIComponent(slug!)}`, { headers });
+  const res = await fetch(`${cmsBase}/guides/${encodeURIComponent(slug)}`, { headers: cmsHeaders() });
   if (res.ok) {
     guide = await res.json();
   } else if (res.status !== 404) {
@@ -63,8 +60,7 @@ if (!guide) {
 
 // Fetch related guides in parallel (best-effort)
 try {
-  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
-  const relRes = await fetch(`${cmsBase}/content/guides/related/${encodeURIComponent(slug!)}?limit=3`, { headers });
+  const relRes = await fetch(`${cmsBase}/content/guides/related/${encodeURIComponent(slug)}?limit=3`, { headers: cmsHeaders() });
   if (relRes.ok) {
     const relData = await relRes.json();
     relatedItems = relData.items ?? [];
diff --git a/apps/marketing-site/src/pages/guides/index.astro b/apps/marketing-site/src/pages/guides/index.astro
index 6affd53e..f064e04e 100644
--- a/apps/marketing-site/src/pages/guides/index.astro
+++ b/apps/marketing-site/src/pages/guides/index.astro
@@ -3,10 +3,8 @@
 import BaseLayout from '../../layouts/BaseLayout.astro';
 import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { appUrl, siteUrl } from '../../config';
-import { extractCategories } from '../../lib/content/content-utils';
-
-const cmsBase = process.env.CMS_SERVICE_URL || import.meta.env.CMS_SERVICE_URL || 'http://cms-service:8000';
-const internalApiKey = process.env.INTERNAL_API_KEY || import.meta.env.INTERNAL_API_KEY || '';
+import { extractCategories, buildPaginationUrl } from '../../lib/content/content-utils';
+import { cmsBase, cmsHeaders } from '../../lib/cms-client';
 
 // Read search / category / page from query string
 const url = new URL(Astro.request.url);
@@ -39,7 +37,6 @@ let fetchError = false;
 let categories: string[] = [];
 
 try {
-  const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
   const params = new URLSearchParams({
     page: String(currentPage),
     page_size: String(PAGE_SIZE),
@@ -47,7 +44,7 @@ try {
   if (searchQuery) params.set('search', searchQuery);
   if (categoryFilter) params.set('category', categoryFilter);
 
-  const res = await fetch(`${cmsBase}/guides?${params}`, { headers });
+  const res = await fetch(`${cmsBase}/guides?${params}`, { headers: cmsHeaders() });
   if (res.ok) {
     guidesData = await res.json();
     categories = extractCategories(guidesData.items);
@@ -240,7 +237,7 @@ const breadcrumbSchema = {
       <nav aria-label="Pagination" class="mt-12 flex items-center justify-center gap-2">
         {currentPage > 1 && (
           <a
-            href={`/guides/?page=${currentPage - 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            href={buildPaginationUrl('/guides/', currentPage - 1, searchQuery, categoryFilter)}
             class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
             aria-label="Previous page"
           >
@@ -252,7 +249,7 @@ const breadcrumbSchema = {
         </span>
         {currentPage < totalPages && (
           <a
-            href={`/guides/?page=${currentPage + 1}${searchQuery ? `&search=${encodeURIComponent(searchQuery)}` : ''}${categoryFilter ? `&category=${encodeURIComponent(categoryFilter)}` : ''}`}
+            href={buildPaginationUrl('/guides/', currentPage + 1, searchQuery, categoryFilter)}
             class="rounded-lg border border-stone-700 px-4 py-2 text-sm text-stone-400 hover:text-stone-200 transition-colors"
             aria-label="Next page"
           >
diff --git a/services/cms-service/app/routers/content.py b/services/cms-service/app/routers/content.py
index 26c41ca0..8fd46353 100644
--- a/services/cms-service/app/routers/content.py
+++ b/services/cms-service/app/routers/content.py
@@ -236,6 +236,23 @@ async def _ensure_slug_available(
     raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=ERROR_DUPLICATE_SLUG)
 
 
+def _escape_like(value: str) -> str:
+    """Escape special LIKE pattern characters so user input matches literally."""
+    return (
+        value
+        .replace("\\", "\\\\")
+        .replace("%", r"\%")
+        .replace("_", r"\_")
+        .replace("[", r"\[")
+        .replace("]", r"\]")
+    )
+
+
+def _resolve_actor(requested: str | None, user: dict) -> str:
+    """Return the workflow actor name, falling back to JWT sub/email claims."""
+    return requested or user.get("sub") or user.get("email") or "unknown"
+
+
 # ── Public endpoints ─────────────────────────────────────────────────────────
 
 @router.get("/content/{type_slug}", tags=["content"])
@@ -263,8 +280,7 @@ async def list_published_content(
     if category:
         filters.append(ContentItem.category == category)
     if search:
-        escaped = search.replace("\\", "\\\\").replace("%", r"\%").replace("_", r"\_")
-        like = f"%{escaped}%"
+        like = f"%{_escape_like(search)}%"
         filters.append(
             ContentItem.title.ilike(like) | ContentItem.excerpt.ilike(like)
         )
@@ -460,8 +476,7 @@ async def list_all_content(
     if target_keyword:
         filters.append(ContentItem.target_keyword == target_keyword)
     if search:
-        escaped = search.replace("\\", "\\\\").replace("%", r"\%").replace("_", r"\_")
-        like = f"%{escaped}%"
+        like = f"%{_escape_like(search)}%"
         filters.append(
             ContentItem.title.ilike(like) | ContentItem.excerpt.ilike(like)
         )
@@ -686,7 +701,7 @@ async def archive_content_item(
     if item is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
 
-    actor = user.get("sub") or user.get("email")
+    actor = _resolve_actor(None, user)
     now = datetime.now(timezone.utc)
     item.status = "Archived"
     item.last_workflow_action_by = actor
@@ -714,7 +729,7 @@ async def submit_content_for_review(
     if item is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
 
-    actor = req.actor or user.get("sub") or user.get("email")
+    actor = _resolve_actor(req.actor, user)
     now = datetime.now(timezone.utc)
     item.status = "Review"
     item.last_workflow_action_by = actor
@@ -744,7 +759,7 @@ async def approve_content_item(
     if item is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
 
-    actor = req.actor or user.get("sub") or user.get("email")
+    actor = _resolve_actor(req.actor, user)
     now = datetime.now(timezone.utc)
     item.status = "Approved"
     item.approved_by = actor
@@ -775,7 +790,7 @@ async def request_content_changes(
     if item is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
 
-    actor = req.reviewer or user.get("sub") or user.get("email")
+    actor = _resolve_actor(req.reviewer, user)
     now = datetime.now(timezone.utc)
     item.status = "Draft"
     item.last_workflow_action_by = actor
@@ -805,7 +820,7 @@ async def schedule_content_item(
     if item is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
 
-    actor = req.scheduled_by or user.get("sub") or user.get("email")
+    actor = _resolve_actor(req.scheduled_by, user)
     now = datetime.now(timezone.utc)
     item.status = "Scheduled"
     item.start_date = req.planned_publish_date
@@ -833,7 +848,7 @@ async def unpublish_content_item(
     if item is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=ERROR_NOT_FOUND)
 
-    actor = user.get("sub") or user.get("email")
+    actor = _resolve_actor(None, user)
     now = datetime.now(timezone.utc)
     item.status = "Draft"
     item.last_workflow_action_by = actor
@@ -863,7 +878,7 @@ async def clone_content_item(
 
     await _ensure_slug_available(session, source.content_type, req.new_slug)
 
-    actor = req.cloned_by or user.get("sub") or user.get("email")
+    actor = _resolve_actor(req.cloned_by, user)
     now = datetime.now(timezone.utc)
     clone = ContentItem(
         id=uuid.uuid4(),
diff --git a/services/cms-service/tests/conftest.py b/services/cms-service/tests/conftest.py
index 06d77528..a6682d24 100644
--- a/services/cms-service/tests/conftest.py
+++ b/services/cms-service/tests/conftest.py
@@ -1,6 +1,8 @@
 """Pytest configuration and fixtures for cms-service tests."""
 import os
 import sys
+import uuid
+from datetime import datetime, timezone
 from pathlib import Path
 
 SERVICE_ROOT = os.path.dirname(os.path.dirname(__file__))
@@ -14,7 +16,7 @@
 
 from app.main import app
 from app.db import get_session
-from app.models.db_models import Base
+from app.models.db_models import Base, ContentItem
 
 
 def _create_tables(conn):
@@ -57,3 +59,30 @@ async def override_get_session():
 
     app.dependency_overrides.clear()
 
+
+async def create_content_item(session: AsyncSession, **kwargs) -> ContentItem:
+    """Persist a minimal ContentItem to the database and return the refreshed instance.
+
+    All fields can be overridden via keyword arguments.
+    """
+    now = datetime.now(timezone.utc)
+    defaults = {
+        "id": uuid.uuid4(),
+        "content_type": "Guide",
+        "title": "Test Item",
+        "slug": "test-item",
+        "content_markdown": "# Content",
+        "author_name": "Author",
+        "status": "Published",
+        "content_source": "Manual",
+        "ai_generated": False,
+        "created_at": now,
+        "updated_at": now,
+    }
+    defaults.update(kwargs)
+    item = ContentItem(**defaults)
+    session.add(item)
+    await session.commit()
+    await session.refresh(item)
+    return item
+
diff --git a/services/cms-service/tests/test_content.py b/services/cms-service/tests/test_content.py
index e34f968e..954915d5 100644
--- a/services/cms-service/tests/test_content.py
+++ b/services/cms-service/tests/test_content.py
@@ -8,6 +8,7 @@
 from app.models.db_models import ContentItem
 from app.routers.content import _is_visible, _parse_item_id, _to_summary, _to_schema
 from fastapi import HTTPException
+from tests.conftest import create_content_item
 
 
 # ── Helper ───────────────────────────────────────────────────────────────────
@@ -159,33 +160,11 @@ def test_builds_public_schema(self):
 class TestContentPublicRoutes:
     """Tests for public content endpoints."""
 
-    async def _create_item(self, session: AsyncSession, **kwargs) -> ContentItem:
-        now = datetime.now(timezone.utc)
-        defaults = {
-            "id": uuid.uuid4(),
-            "content_type": "Guide",
-            "title": "Test Guide",
-            "slug": "test-guide",
-            "content_markdown": "# Guide",
-            "author_name": "Author",
-            "status": "Published",
-            "content_source": "Manual",
-            "ai_generated": False,
-            "created_at": now,
-            "updated_at": now,
-        }
-        defaults.update(kwargs)
-        item = ContentItem(**defaults)
-        session.add(item)
-        await session.commit()
-        await session.refresh(item)
-        return item
-
     async def test_list_guides_returns_published(self, client, test_db):
         """GET /guides returns only published items."""
         async with test_db() as session:
-            await self._create_item(session, slug="published-guide", status="Published")
-            await self._create_item(session, slug="draft-guide", status="Draft")
+            await create_content_item(session, slug="published-guide", status="Published")
+            await create_content_item(session, slug="draft-guide", status="Draft")
 
         response = await client.get("/guides")
         assert response.status_code == 200
@@ -197,10 +176,10 @@ async def test_list_guides_returns_published(self, client, test_db):
     async def test_list_guides_excludes_draft_and_archived(self, client, test_db):
         """GET /guides excludes Draft, Review and Archived items."""
         async with test_db() as session:
-            await self._create_item(session, slug="pub", status="Published")
-            await self._create_item(session, slug="drft", status="Draft")
-            await self._create_item(session, slug="rev", status="Review")
-            await self._create_item(session, slug="arch", status="Archived")
+            await create_content_item(session, slug="pub", status="Published")
+            await create_content_item(session, slug="drft", status="Draft")
+            await create_content_item(session, slug="rev", status="Review")
+            await create_content_item(session, slug="arch", status="Archived")
 
         response = await client.get("/guides")
         assert response.status_code == 200
@@ -210,7 +189,7 @@ async def test_list_guides_excludes_draft_and_archived(self, client, test_db):
     async def test_get_guide_by_slug_published(self, client, test_db):
         """GET /guides/{slug} returns published guide."""
         async with test_db() as session:
-            await self._create_item(session, slug="my-guide", status="Published")
+            await create_content_item(session, slug="my-guide", status="Published")
 
         response = await client.get("/guides/my-guide")
         assert response.status_code == 200
@@ -220,7 +199,7 @@ async def test_get_guide_by_slug_published(self, client, test_db):
     async def test_get_guide_draft_returns_404(self, client, test_db):
         """GET /guides/{slug} returns 404 for draft."""
         async with test_db() as session:
-            await self._create_item(session, slug="hidden-guide", status="Draft")
+            await create_content_item(session, slug="hidden-guide", status="Draft")
 
         response = await client.get("/guides/hidden-guide")
         assert response.status_code == 404
@@ -233,7 +212,7 @@ async def test_get_guide_not_found_returns_404(self, client):
     async def test_list_articles_returns_published(self, client, test_db):
         """GET /articles returns only published articles."""
         async with test_db() as session:
-            await self._create_item(
+            await create_content_item(
                 session, content_type="Article", slug="my-article", status="Published"
             )
 
@@ -244,7 +223,7 @@ async def test_list_articles_returns_published(self, client, test_db):
     async def test_list_cv_for_returns_published(self, client, test_db):
         """GET /cv-for returns only published CV-For items."""
         async with test_db() as session:
-            await self._create_item(
+            await create_content_item(
                 session, content_type="CvFor", slug="cv-for-pm", status="Published"
             )
 
@@ -255,7 +234,7 @@ async def test_list_cv_for_returns_published(self, client, test_db):
     async def test_content_type_route_guide(self, client, test_db):
         """GET /content/guides/{slug} returns published guide."""
         async with test_db() as session:
-            await self._create_item(session, slug="via-generic", status="Published")
+            await create_content_item(session, slug="via-generic", status="Published")
 
         response = await client.get("/content/guides/via-generic")
         assert response.status_code == 200
@@ -269,7 +248,7 @@ async def test_content_invalid_type_returns_404(self, client):
     async def test_start_date_future_not_visible(self, client, test_db):
         """Item with future start_date is not visible publicly."""
         async with test_db() as session:
-            await self._create_item(
+            await create_content_item(
                 session,
                 slug="future-guide",
                 status="Published",
@@ -282,7 +261,7 @@ async def test_start_date_future_not_visible(self, client, test_db):
     async def test_expiry_date_past_not_visible(self, client, test_db):
         """Item with past expiry_date is not visible publicly."""
         async with test_db() as session:
-            await self._create_item(
+            await create_content_item(
                 session,
                 slug="expired-guide",
                 status="Published",
@@ -295,10 +274,10 @@ async def test_expiry_date_past_not_visible(self, client, test_db):
     async def test_list_with_category_filter(self, client, test_db):
         """GET /guides?category=X returns only items in that category."""
         async with test_db() as session:
-            await self._create_item(
+            await create_content_item(
                 session, slug="guide-a", status="Published", category="CV Tips"
             )
-            await self._create_item(
+            await create_content_item(
                 session, slug="guide-b", status="Published", category="Interview"
             )
 
@@ -312,7 +291,7 @@ async def test_list_pagination(self, client, test_db):
         """List endpoints respect page/page_size params."""
         async with test_db() as session:
             for i in range(5):
-                await self._create_item(session, slug=f"guide-{i}", status="Published")
+                await create_content_item(session, slug=f"guide-{i}", status="Published")
 
         response = await client.get("/guides?page=1&page_size=2")
         assert response.status_code == 200
@@ -362,35 +341,13 @@ async def test_admin_archive_requires_auth(self, client):
 class TestSlugUniquenessPerType:
     """Slug must be unique within a content type but can repeat across types."""
 
-    async def _create_item(self, session: AsyncSession, **kwargs) -> ContentItem:
-        now = datetime.now(timezone.utc)
-        defaults = {
-            "id": uuid.uuid4(),
-            "content_type": "Blog",
-            "title": "Test",
-            "slug": "test-slug",
-            "content_markdown": "# Content",
-            "author_name": "Author",
-            "status": "Published",
-            "content_source": "Manual",
-            "ai_generated": False,
-            "created_at": now,
-            "updated_at": now,
-        }
-        defaults.update(kwargs)
-        item = ContentItem(**defaults)
-        session.add(item)
-        await session.commit()
-        await session.refresh(item)
-        return item
-
     async def test_same_slug_different_types_both_visible(self, client, test_db):
         """Same slug can exist for different content types."""
         async with test_db() as session:
-            await self._create_item(
+            await create_content_item(
                 session, content_type="Guide", slug="shared-slug", status="Published"
             )
-            await self._create_item(
+            await create_content_item(
                 session, content_type="Article", slug="shared-slug", status="Published"
             )
 
@@ -407,33 +364,11 @@ async def test_same_slug_different_types_both_visible(self, client, test_db):
 class TestPublicSearchAndRelated:
     """Tests for search and related-content on public endpoints."""
 
-    async def _create_item(self, session: AsyncSession, **kwargs) -> ContentItem:
-        now = datetime.now(timezone.utc)
-        defaults = {
-            "id": uuid.uuid4(),
-            "content_type": "Guide",
-            "title": "Default Guide",
-            "slug": "default-guide",
-            "content_markdown": "# Guide",
-            "author_name": "Author",
-            "status": "Published",
-            "content_source": "Manual",
-            "ai_generated": False,
-            "created_at": now,
-            "updated_at": now,
-        }
-        defaults.update(kwargs)
-        item = ContentItem(**defaults)
-        session.add(item)
-        await session.commit()
-        await session.refresh(item)
-        return item
-
     async def test_search_filters_by_title(self, client, test_db):
         """GET /guides?search=X returns only guides whose title matches."""
         async with test_db() as session:
-            await self._create_item(session, slug="ats-guide", title="ATS Optimisation Guide", status="Published")
-            await self._create_item(session, slug="cv-tips", title="CV Writing Tips", status="Published")
+            await create_content_item(session, slug="ats-guide", title="ATS Optimisation Guide", status="Published")
+            await create_content_item(session, slug="cv-tips", title="CV Writing Tips", status="Published")
 
         response = await client.get("/guides?search=ATS")
         assert response.status_code == 200
@@ -444,7 +379,7 @@ async def test_search_filters_by_title(self, client, test_db):
     async def test_search_is_case_insensitive(self, client, test_db):
         """Search is case-insensitive."""
         async with test_db() as session:
-            await self._create_item(session, slug="search-guide", title="Interview Preparation Guide", status="Published")
+            await create_content_item(session, slug="search-guide", title="Interview Preparation Guide", status="Published")
 
         response = await client.get("/guides?search=interview")
         assert response.status_code == 200
@@ -454,7 +389,7 @@ async def test_search_is_case_insensitive(self, client, test_db):
     async def test_search_no_results(self, client, test_db):
         """Search with no matches returns empty list."""
         async with test_db() as session:
-            await self._create_item(session, slug="some-guide", title="Some Guide", status="Published")
+            await create_content_item(session, slug="some-guide", title="Some Guide", status="Published")
 
         response = await client.get("/guides?search=zzznomatch")
         assert response.status_code == 200
@@ -463,9 +398,9 @@ async def test_search_no_results(self, client, test_db):
     async def test_related_content_returns_same_type(self, client, test_db):
         """GET /content/guides/related/{slug} returns other published guides."""
         async with test_db() as session:
-            await self._create_item(session, slug="main-guide", title="Main Guide", status="Published")
-            await self._create_item(session, slug="other-guide", title="Other Guide", status="Published")
-            await self._create_item(session, slug="draft-guide", title="Draft Guide", status="Draft")
+            await create_content_item(session, slug="main-guide", title="Main Guide", status="Published")
+            await create_content_item(session, slug="other-guide", title="Other Guide", status="Published")
+            await create_content_item(session, slug="draft-guide", title="Draft Guide", status="Draft")
 
         response = await client.get("/content/guides/related/main-guide")
         assert response.status_code == 200
@@ -478,7 +413,7 @@ async def test_related_content_returns_same_type(self, client, test_db):
     async def test_related_content_excludes_current(self, client, test_db):
         """Related content endpoint never returns the current item."""
         async with test_db() as session:
-            await self._create_item(session, slug="anchor-guide", status="Published")
+            await create_content_item(session, slug="anchor-guide", status="Published")
 
         response = await client.get("/content/guides/related/anchor-guide")
         assert response.status_code == 200

From 2de8391e771b9b8343e22fc443137c24f4e43dc6 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 30 May 2026 06:40:42 +0000
Subject: [PATCH 5/6] fix(content-ui): add escape param to ilike calls and
 document sitemap limit

- Pass escape="\\" to all ilike() calls so the database correctly
  interprets the backslash-escaped LIKE pattern from _escape_like()
- Add inline comment noting that not_in set is bounded to limit+1 items
- Add sitemap comment about the 100-item-per-content-type cap

Co-authored-by: NickLetts2 <90337962+NickLetts2@users.noreply.github.com>
---
 apps/marketing-site/src/pages/sitemap.xml.ts | 2 ++
 services/cms-service/app/routers/content.py  | 5 +++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/apps/marketing-site/src/pages/sitemap.xml.ts b/apps/marketing-site/src/pages/sitemap.xml.ts
index 946c00c8..e91925c1 100644
--- a/apps/marketing-site/src/pages/sitemap.xml.ts
+++ b/apps/marketing-site/src/pages/sitemap.xml.ts
@@ -117,6 +117,8 @@ export const GET: APIRoute = async ({ site }) => {
       const internalApiKey = process.env.INTERNAL_API_KEY || '';
       const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
 
+      // Fetch up to 100 published items per type. For sites with more than 100
+      // items per content type, implement pagination here to include them all.
       const res = await fetch(`${cmsBase}/${type}?page_size=100`, { headers });
       if (res.ok) {
         const data: ContentListResponse = await res.json();
diff --git a/services/cms-service/app/routers/content.py b/services/cms-service/app/routers/content.py
index 8fd46353..61c253c8 100644
--- a/services/cms-service/app/routers/content.py
+++ b/services/cms-service/app/routers/content.py
@@ -282,7 +282,7 @@ async def list_published_content(
     if search:
         like = f"%{_escape_like(search)}%"
         filters.append(
-            ContentItem.title.ilike(like) | ContentItem.excerpt.ilike(like)
+            ContentItem.title.ilike(like, escape="\\") | ContentItem.excerpt.ilike(like, escape="\\")
         )
 
     count_result = await session.execute(
@@ -351,6 +351,7 @@ async def get_related_content(
 
     if len(items) < limit:
         needed = limit - len(items)
+        # seen_ids is bounded by limit (max 10) + 1 for current item — always small.
         seen_ids = {i.id for i in items} | {current.id}
         fallback_result = await session.execute(
             select(ContentItem)
@@ -478,7 +479,7 @@ async def list_all_content(
     if search:
         like = f"%{_escape_like(search)}%"
         filters.append(
-            ContentItem.title.ilike(like) | ContentItem.excerpt.ilike(like)
+            ContentItem.title.ilike(like, escape="\\") | ContentItem.excerpt.ilike(like, escape="\\")
         )
 
     count_result = await session.execute(

From ab9dbc036641ac6410637607bb52f565e085e740 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 30 May 2026 06:42:29 +0000
Subject: [PATCH 6/6] fix(content-ui): extract MS_PER_DAY constant and polish
 review comments

- Export MS_PER_DAY = 86_400_000 from content-utils.ts; import and use
  it in guides/[slug].astro and articles/[slug].astro in place of the
  inline magic number
- Change sitemap 100-item comment to a TODO for future pagination
- Clarify not_in comment to reference validated limit constraint

Co-authored-by: NickLetts2 <90337962+NickLetts2@users.noreply.github.com>
---
 apps/marketing-site/src/lib/content/content-utils.ts | 7 +++++++
 apps/marketing-site/src/pages/articles/[slug].astro  | 4 ++--
 apps/marketing-site/src/pages/guides/[slug].astro    | 4 ++--
 apps/marketing-site/src/pages/sitemap.xml.ts         | 4 ++--
 services/cms-service/app/routers/content.py          | 2 +-
 5 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/apps/marketing-site/src/lib/content/content-utils.ts b/apps/marketing-site/src/lib/content/content-utils.ts
index b3f286f2..ac1db89d 100644
--- a/apps/marketing-site/src/lib/content/content-utils.ts
+++ b/apps/marketing-site/src/lib/content/content-utils.ts
@@ -5,6 +5,13 @@
 /** Words-per-minute used for reading time estimation. */
 const WORDS_PER_MINUTE = 200;
 
+/**
+ * Milliseconds in one day — used to detect meaningful update timestamps.
+ * Exported so detail pages can determine whether an updated_at date is
+ * materially different from published_at without duplicating the constant.
+ */
+export const MS_PER_DAY = 86_400_000;
+
 /**
  * Returns estimated reading time in minutes from markdown text.
  * Falls back to the CMS-provided value when available.
diff --git a/apps/marketing-site/src/pages/articles/[slug].astro b/apps/marketing-site/src/pages/articles/[slug].astro
index 91b82024..042aff31 100644
--- a/apps/marketing-site/src/pages/articles/[slug].astro
+++ b/apps/marketing-site/src/pages/articles/[slug].astro
@@ -5,7 +5,7 @@ import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { marked } from 'marked';
 import { sanitizeBlogHtml } from '../../lib/sanitize';
 import { appUrl, siteUrl } from '../../config';
-import { calcReadingTime } from '../../lib/content/content-utils';
+import { calcReadingTime, MS_PER_DAY } from '../../lib/content/content-utils';
 import { cmsBase, cmsHeaders } from '../../lib/cms-client';
 
 const { slug } = Astro.params;
@@ -76,7 +76,7 @@ const formattedDate = new Date(publishDate).toLocaleDateString('en-GB', {
 
 const publishMs = new Date(publishDate).getTime();
 const updatedMs = new Date(article.updated_at).getTime();
-const wasUpdated = updatedMs - publishMs > 86_400_000;
+const wasUpdated = updatedMs - publishMs > MS_PER_DAY;
 const formattedUpdated = wasUpdated
   ? new Date(article.updated_at).toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })
   : null;
diff --git a/apps/marketing-site/src/pages/guides/[slug].astro b/apps/marketing-site/src/pages/guides/[slug].astro
index 19fe97cc..5c0b3712 100644
--- a/apps/marketing-site/src/pages/guides/[slug].astro
+++ b/apps/marketing-site/src/pages/guides/[slug].astro
@@ -5,7 +5,7 @@ import CtaBanner from '../../components/sections/CtaBanner.astro';
 import { marked } from 'marked';
 import { sanitizeBlogHtml } from '../../lib/sanitize';
 import { appUrl, siteUrl } from '../../config';
-import { calcReadingTime } from '../../lib/content/content-utils';
+import { calcReadingTime, MS_PER_DAY } from '../../lib/content/content-utils';
 import { cmsBase, cmsHeaders } from '../../lib/cms-client';
 
 const { slug } = Astro.params;
@@ -78,7 +78,7 @@ const formattedDate = new Date(publishDate).toLocaleDateString('en-GB', {
 
 const publishMs = new Date(publishDate).getTime();
 const updatedMs = new Date(guide.updated_at).getTime();
-const wasUpdated = updatedMs - publishMs > 86_400_000;
+const wasUpdated = updatedMs - publishMs > MS_PER_DAY;
 const formattedUpdated = wasUpdated
   ? new Date(guide.updated_at).toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })
   : null;
diff --git a/apps/marketing-site/src/pages/sitemap.xml.ts b/apps/marketing-site/src/pages/sitemap.xml.ts
index e91925c1..5cf21034 100644
--- a/apps/marketing-site/src/pages/sitemap.xml.ts
+++ b/apps/marketing-site/src/pages/sitemap.xml.ts
@@ -117,8 +117,8 @@ export const GET: APIRoute = async ({ site }) => {
       const internalApiKey = process.env.INTERNAL_API_KEY || '';
       const headers = internalApiKey ? { 'X-Internal-Api-Key': internalApiKey } : undefined;
 
-      // Fetch up to 100 published items per type. For sites with more than 100
-      // items per content type, implement pagination here to include them all.
+      // TODO: If any content type exceeds 100 published items, paginate this
+      // fetch to ensure all items are included in the sitemap.
       const res = await fetch(`${cmsBase}/${type}?page_size=100`, { headers });
       if (res.ok) {
         const data: ContentListResponse = await res.json();
diff --git a/services/cms-service/app/routers/content.py b/services/cms-service/app/routers/content.py
index 61c253c8..ae169d6b 100644
--- a/services/cms-service/app/routers/content.py
+++ b/services/cms-service/app/routers/content.py
@@ -351,7 +351,7 @@ async def get_related_content(
 
     if len(items) < limit:
         needed = limit - len(items)
-        # seen_ids is bounded by limit (max 10) + 1 for current item — always small.
+        # seen_ids is bounded by limit parameter (validated max 10) + 1 — always a small set.
         seen_ids = {i.id for i in items} | {current.id}
         fallback_result = await session.execute(
             select(ContentItem)