@fullstackdatasolutions/articles 0.12.0 → 1.0.0

package/README.md

@@ -139,8 +139,10 @@ import {
   ArticleNavigation,
   ArticleSEO,
   ArticleSocialShare,
+  ArticleViewTracker,
   Breadcrumb,
   CommentsSection,
+  RelatedArticlesSection,
   ScrollToTop,
 } from '@fullstackdatasolutions/articles'
 import {
@@ -152,6 +154,7 @@ import {
   getAdjacentArticles,
   getArticleAuthors,
   getArticleMetadata,
+  getRelatedArticlesByCategory,
 } from '@fullstackdatasolutions/articles/server'
 import { siteConfig } from '@/config/articles'
 type ArticlePageProps = Readonly<{ params: Promise<{ slug: string[] }> }>
@@ -172,6 +175,7 @@ export default async function Page({ params }: ArticlePageProps) {
   const article = await getArticleMetadata(slug, siteConfig)
   if (!article) notFound()
   const { previous, next } = await getAdjacentArticles(slug)
+  const related = await getRelatedArticlesByCategory(slug, article.category, 3, siteConfig)
   const authors = getArticleAuthors(article, siteConfig)
   const breadcrumbItems = buildArticleBreadcrumbs(article, siteConfig)
   const siteUrl = siteConfig.siteUrl.replace(/\/$/, '')
@@ -183,6 +187,7 @@ export default async function Page({ params }: ArticlePageProps) {
         articleUrl={articleUrl}
         siteName={siteConfig.siteName}
         authors={authors}
+        config={siteConfig}
       />
       <Breadcrumb items={breadcrumbItems} />
       <ArticleDetailHero
@@ -190,12 +195,15 @@ export default async function Page({ params }: ArticlePageProps) {
         authors={authors}
         categoryBasePath="/articles/category"
       />
+      <ArticleViewTracker article={article} config={siteConfig} />
       {siteConfig.showToc !== false && article.toc && article.toc.length > 0 && (
         <ArticleTOC toc={article.toc} />
       )}
+      {/* See "Discovery & reader-journey layer" below for afterHero/afterIntro/midContent/afterContent slots */}
       <ArticleContent article={article} config={siteConfig} />
-      <ArticleSocialShare title={article.title} url={articleUrl} excerpt={article.excerpt} />
+      <ArticleSocialShare title={article.title} url={articleUrl} excerpt={article.excerpt} articleSlug={slug} config={siteConfig} />
       {siteConfig.comments && <CommentsSection articleSlug={slug} config={siteConfig.comments} />}
+      <RelatedArticlesSection articles={related} category={article.category} />
       <ArticleNavigation previous={previous} next={next} basePath="/articles" />
       <ScrollToTop />
     </>
@@ -471,6 +479,7 @@ Use this if you don't need a custom API base path. For custom paths, use `create
 | `linkTargetStrategy`   | `'external-new-tab' \| 'all-new-tab' \| 'same-tab'` | `'external-new-tab'` | Controls article body links. Internal links open in the same window by default; external `http`/`https` links open in a new window.                 |
 | `mdxComponents`        | `Record<string, ComponentType<never>>`              | -                    | Components exposed to article `.mdx` bodies by tag name. Merged with the built-in MDX image override.                                               |
 | `description`          | `string`                                            | —                    | Short description used as the RSS feed channel description. Falls back to `siteName` if omitted.                                                    |
+| `listingPagination`    | `'load-more' \| 'pages'`                            | `'load-more'`        | `'load-more'` keeps the client-only "Load more" button (no URL change). `'pages'` opts every listing surface into real, crawlable paginated routes - see the [Pagination](#pagination) section.  |
 
 **Default layout order:** `['hero', 'search', 'featured', 'latest', 'categories']`
 
@@ -617,6 +626,7 @@ import { ArticleDetailHero } from '@fullstackdatasolutions/articles'
 - The date field is hidden by default. Pass `showDate={true}` to display it.
 - All layout styles are inline so the component renders correctly regardless of whether `@source` is configured for the package.
 - Hero image / categories behave automatically once you use this component; apps do not need to reimplement the hero section for those features.
+- **Author authority statement (Phase 27E):** when `authors` has exactly one entry and that author's `AuthorProfile.promise` is set, `ArticleDetailHero` renders it as a one-sentence line under the byline. Omitted for zero or multiple authors, or when `promise` is unset - purely additive, no existing output changes.
 
 ---
 
@@ -667,6 +677,518 @@ const { previous, next } = await getAdjacentArticles(slug)
 
 ---
 
+## RelatedArticlesSection
+
+`RelatedArticlesSection` renders a grid of other articles in the same category as the current article, using `ArticleCard` for each one - real `<a href>` links, not a client-only "Load more" interaction. Use `getRelatedArticlesByCategory` from the server entry to fetch the data.
+
+```tsx
+import { RelatedArticlesSection } from '@fullstackdatasolutions/articles'
+import { getRelatedArticlesByCategory } from '@fullstackdatasolutions/articles/server'
+
+const related = await getRelatedArticlesByCategory(slug, article.category, 3, siteConfig)
+
+<RelatedArticlesSection articles={related} category={article.category} />
+```
+
+| Prop       | Type       | Required | Description                                          |
+| ---------- | ---------- | -------- | ----------------------------------------------------- |
+| `articles` | `Article[]` | yes     | Related articles to render, already excluding the current one |
+| `category` | `string`    | yes     | Category name shown in the section heading ("More in {category}") |
+
+`getRelatedArticlesByCategory(currentSlug, category, limit?, config?)` returns up to `limit` (default `3`) other articles sharing `category` with `currentSlug`, most recent first, built on the same category-slug matching `getArticlesByCategory` already uses. Returns `[]` (and the component renders nothing) when no other articles share the category.
+
+---
+
+## Pagination
+
+By default (`listingPagination` unset, or `'load-more'`), `/articles`, every category page, and every author page use a client-only "Load more" button - clicking it never changes the URL, so a crawler that doesn't execute client JS never sees article 7+ on a listing with more than one page of content.
+
+Set `listingPagination: 'pages'` in `ArticlesConfig` to opt into real, directly-navigable paginated routes instead: `/articles/page/2`, `/articles/category/[category]/page/2`, `/articles/authors/[author]/page/2`, each server-rendered with real `<a href>` prev/next links and its own canonical URL. This is a config choice, not a migration - `'load-more'` (the default) keeps working exactly as before, and each listing surface only switches to `'pages'` behavior when both `config.listingPagination === 'pages'` **and** the surface's `page`/`totalPages` props are passed in.
+
+The package does not ship the route *files* themselves (Next.js requires them to live in your app's `app/` directory) - it exports the primitives to build them: pagination math (`./server`), a prev/next nav component (`PaginationNav`, from the main entry), and per-page metadata generators (`./server`).
+
+### Pagination primitives (`./server`)
+
+| Export                                             | Description                                                                                                                          |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `getTotalPages(totalCount, pageSize)`                | Total page count, rounded up. Returns `1` for a zero/negative count or pageSize.                                                        |
+| `paginateArticles(articles, page, pageSize)`         | Slices `articles` to the requested page. Out-of-range page numbers are clamped into `[1, totalPages]`. Returns `{ articles, page, totalPages, hasPrevious, hasNext }`. |
+| `buildPageUrl(basePath, page)`                       | Page 1 returns `basePath` unchanged; page N>1 returns `${basePath}/page/${N}`.                                                          |
+| `buildPaginationLinks(basePath, page, totalPages)`   | Returns `{ canonicalUrl, prevUrl, nextUrl }` (`prevUrl`/`nextUrl` are `null` at the ends).                                              |
+| `generateListingPageStaticParams(totalPages)`        | Returns `{ page: string }[]` for pages `2..totalPages` (page 1 has no `/page/1` route - it's the base route itself).                    |
+| `parsePageParam(raw)`                                | Parses a route param string to a page number; defaults to `1` for missing/invalid input.                                               |
+| `isPageOutOfRange(page, totalPages)`                 | `true` when `page < 1` or `page > totalPages` - call `notFound()` when this is `true`.                                                  |
+
+### `PaginationNav` (main entry)
+
+Renders real Previous/Next `<a href>` links plus `<link rel="prev"/"next">` tags (React 19 hoists these into `<head>` automatically wherever they're rendered in the tree). Rendered automatically by `LatestArticles`/`ArticlesPage`/`CategoryArticlesPage`/`AuthorArticlesPage` when you pass pagination props - you generally won't render it directly.
+
+| Prop         | Type     | Required | Description                                             |
+| ------------ | -------- | -------- | --------------------------------------------------------- |
+| `basePath`   | `string` | yes      | Un-paginated route path, e.g. `/articles`.                |
+| `page`       | `number` | yes      | Current page number.                                     |
+| `totalPages` | `number` | yes      | Total page count. Renders nothing when `totalPages <= 1`. |
+
+**rel=next/prev and Google:** Google Search Central's pagination guidance no longer treats `rel="next"`/`rel="prev"` as an indexing or ranking signal (dropped in 2019) - what actually makes page 2+ indexable to Google is each page having its own self-referencing canonical (never pointing back to page 1) plus real crawlable links between pages, both of which are handled here (`generate*PageMetadata` below for the canonical, `PaginationNav`'s visible links for crawlability). `rel=next/prev` remains valid HTML and is still read by Bing and some third-party tools, so `PaginationNav` emits it anyway - it's just not the mechanism Google uses.
+
+### Per-page metadata (`./server`)
+
+`generateArticlesIndexPageMetadata`, `generateCategoryPageMetadata`, and `generateAuthorPageMetadata` wrap the existing `generate*Metadata` functions, adding a `" - Page N"` title suffix (page 1 is unchanged) and pointing `alternates.canonical`/`openGraph.url` at that page's own URL instead of page 1's. Paginated pages stay `index, follow` - the entire point is making them indexable, not excluding them.
+
+### Wiring the routes
+
+```tsx
+// app/articles/page/[page]/page.tsx
+import { notFound } from 'next/navigation'
+import { ArticlesPage } from '@fullstackdatasolutions/articles'
+import {
+  generateArticlesIndexPageMetadata,
+  generateListingPageStaticParams,
+  getAllArticles,
+  getAllCategories,
+  getTotalPages,
+  isPageOutOfRange,
+  paginateArticles,
+  parsePageParam,
+} from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '@/config/articles'
+
+type PageProps = Readonly<{ params: Promise<{ page: string }> }>
+
+export async function generateStaticParams() {
+  const totalPages = getTotalPages((await getAllArticles(siteConfig)).length, siteConfig.pageSize ?? 6)
+  return generateListingPageStaticParams(totalPages)
+}
+
+export async function generateMetadata({ params }: PageProps) {
+  const page = parsePageParam((await params).page)
+  const totalPages = getTotalPages((await getAllArticles(siteConfig)).length, siteConfig.pageSize ?? 6)
+  return generateArticlesIndexPageMetadata(page, totalPages, siteConfig)
+}
+
+export default async function Page({ params }: PageProps) {
+  const page = parsePageParam((await params).page)
+  const [allArticles, categories] = await Promise.all([
+    getAllArticles(siteConfig),
+    getAllCategories(),
+  ])
+  const { articles, totalPages } = paginateArticles(allArticles, page, siteConfig.pageSize ?? 6)
+  if (isPageOutOfRange(page, totalPages)) notFound()
+  return (
+    <ArticlesPage
+      config={siteConfig}
+      initialArticles={articles}
+      initialCategories={categories}
+      page={page}
+      totalPages={totalPages}
+      totalCount={allArticles.length}
+    />
+  )
+}
+
+// app/articles/category/[category]/page/[page]/page.tsx
+import { notFound } from 'next/navigation'
+import { CategoryArticlesPage } from '@fullstackdatasolutions/articles'
+import {
+  generateCategoryPageMetadata,
+  generateListingPageStaticParams,
+  getAllCategories,
+  getArticlesByCategory,
+  getTotalPages,
+  isPageOutOfRange,
+  paginateArticles,
+  parsePageParam,
+} from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '@/config/articles'
+
+type CategoryPageProps = Readonly<{ params: Promise<{ category: string; page: string }> }>
+
+export async function generateStaticParams() {
+  const categories = await getAllCategories()
+  const perCategory = await Promise.all(
+    categories.map(async (cat) => {
+      const totalPages = getTotalPages(
+        (await getArticlesByCategory(cat.slug, siteConfig)).length,
+        siteConfig.pageSize ?? 6
+      )
+      return generateListingPageStaticParams(totalPages).map((p) => ({
+        category: cat.slug,
+        page: p.page,
+      }))
+    })
+  )
+  return perCategory.flat()
+}
+
+export async function generateMetadata({ params }: CategoryPageProps) {
+  const { category, page: pageParam } = await params
+  const page = parsePageParam(pageParam)
+  const totalPages = getTotalPages(
+    (await getArticlesByCategory(category, siteConfig)).length,
+    siteConfig.pageSize ?? 6
+  )
+  return generateCategoryPageMetadata(category, page, totalPages, siteConfig)
+}
+
+export default async function Page({ params }: CategoryPageProps) {
+  const { category, page: pageParam } = await params
+  const page = parsePageParam(pageParam)
+  const allArticles = await getArticlesByCategory(category, siteConfig)
+  if (allArticles.length === 0) notFound()
+  const { articles, totalPages } = paginateArticles(allArticles, page, siteConfig.pageSize ?? 6)
+  if (isPageOutOfRange(page, totalPages)) notFound()
+  return (
+    <CategoryArticlesPage
+      category={category}
+      articles={articles}
+      config={siteConfig}
+      page={page}
+      totalPages={totalPages}
+      totalCount={allArticles.length}
+    />
+  )
+}
+
+// app/articles/authors/[author]/page/[page]/page.tsx
+import { notFound } from 'next/navigation'
+import { AuthorArticlesPage } from '@fullstackdatasolutions/articles'
+import {
+  generateAuthorPageMetadata,
+  generateListingPageStaticParams,
+  getArticlesByAuthor,
+  getAuthorBySlug,
+  getTotalPages,
+  isPageOutOfRange,
+  paginateArticles,
+  parsePageParam,
+} from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '@/config/articles'
+
+type AuthorPageProps = Readonly<{ params: Promise<{ author: string; page: string }> }>
+
+export async function generateMetadata({ params }: AuthorPageProps) {
+  const { author: authorSlug, page: pageParam } = await params
+  const page = parsePageParam(pageParam)
+  const totalPages = getTotalPages(
+    (await getArticlesByAuthor(authorSlug, siteConfig)).length,
+    siteConfig.pageSize ?? 6
+  )
+  return generateAuthorPageMetadata(authorSlug, page, totalPages, siteConfig)
+}
+
+export default async function Page({ params }: AuthorPageProps) {
+  const { author: authorSlug, page: pageParam } = await params
+  const author = getAuthorBySlug(authorSlug, siteConfig)
+  if (!author) notFound()
+  const page = parsePageParam(pageParam)
+  const allArticles = await getArticlesByAuthor(authorSlug, siteConfig)
+  const { articles, totalPages } = paginateArticles(allArticles, page, siteConfig.pageSize ?? 6)
+  if (isPageOutOfRange(page, totalPages)) notFound()
+  return (
+    <AuthorArticlesPage
+      author={author}
+      articles={articles}
+      config={siteConfig}
+      page={page}
+      totalPages={totalPages}
+      totalCount={allArticles.length}
+    />
+  )
+}
+```
+
+`ArticlesPage`, `CategoryArticlesPage`, and `AuthorArticlesPage` all accept the same three optional props - `page`, `totalPages`, `totalCount` - which are only read when `config.listingPagination === 'pages'`; passing them with any other (or unset) `listingPagination` value is a no-op, so the default behavior can never regress from adding this wiring. `totalCount` (the true total across every page, not just the current slice) feeds `CollectionPageSchema.articleCount`/`numberOfItems`; omit it and it falls back to the length of the `articles`/`initialArticles` array you pass, matching prior behavior.
+
+**Search stays unpaginated in both modes.** `ArticlesPage`'s search bar (`ArticleSearchBar`/`useArticles`) fetches from `/api/articles?q=...` and shows every match on one page regardless of `listingPagination` - search result URLs aren't meant to be indexed, so real pagination adds no SEO value there, and `LatestArticlesSection` explicitly drops the `pagination` prop while a search query is active.
+
+**Sitemap:** paginated listing URLs (`/articles/page/2`, etc.) are intentionally **not** added to `getArticleSitemapEntries`. Every individual article, category, and author URL is already listed directly in the sitemap output, so a paginated listing page adds no new discoverable URLs to it - the reason `'pages'` mode exists is internal link equity (real `<a href>` links between pages) and crawlers/AI agents that weight on-page links over sitemaps, not sitemap coverage.
+
+---
+
+## Discovery & reader-journey layer (Phase 27F)
+
+Search/social metadata overrides, series and curated paths, article-detail extension points, an app-owned primary action reference, reusable related-content selection, a vendor-neutral event contract, and a package validator. All additive - every legacy consumer with none of these fields/props set renders/behaves identically to before this phase.
+
+### Discovery metadata overrides
+
+Optional frontmatter fields let one article optimize its search-result snippet differently from its social-share card, without touching canonical URLs, JSON-LD, RSS, or `ArticleCard` (those always read `title`/`excerpt`/`featuredImage` directly):
+
+```yaml
+---
+title: The Real Article Title
+excerpt: The real, on-page excerpt.
+searchTitle: 'A Punchier, SEO-Optimized Title' # <title>/meta description ONLY
+searchDescription: 'A keyword-forward summary for search snippets.'
+socialTitle: 'A Scroll-Stopping Social Headline' # Open Graph/Twitter Card ONLY
+socialDescription: 'A more casual, share-friendly description.'
+socialImage: social-card.png # falls back to featuredImage when unset
+---
+```
+
+`generateArticleMetadata`'s `<title>`/meta description prefer `searchTitle`/`searchDescription`, falling back to `title`/`excerpt`. Its Open Graph/Twitter Card output prefers `socialTitle`/`socialDescription`/`socialImage`, falling back to `title`/`excerpt`/`featuredImage`. Both resolvers are also exported directly for custom metadata generation:
+
+```ts
+import { resolveSearchMetadata, resolveSocialMetadata } from '@fullstackdatasolutions/articles/server'
+
+const { title, description } = resolveSearchMetadata(article, config)
+const { title: ogTitle, description: ogDescription, imageUrl } = resolveSocialMetadata(article, config.siteUrl)
+```
+
+A blank string (`searchTitle: ""`) is treated as unset, same as omitting the key. Recommended length limits (checked by `validateArticles`, warnings only): `searchTitle` 60 chars, `searchDescription` 160 chars, `socialTitle` 95 chars, `socialDescription` 200 chars.
+
+### Series as a navigable reader journey
+
+`series` (a display label) keeps working exactly as before. Two new optional fields turn it into a real, orderable journey:
+
+```yaml
+---
+series: New GM Starter Path # label-only, unchanged
+seriesSlug: new-gm-path # machine-safe id
+seriesOrder: 2 # position within the series
+---
+```
+
+```ts
+import {
+  getArticlesBySeries,
+  getAdjacentArticlesInSeries,
+  generateSeriesStaticParams,
+  generateSeriesMetadata,
+} from '@fullstackdatasolutions/articles/server'
+import { SeriesArticlesPage } from '@fullstackdatasolutions/articles'
+
+// app/articles/series/[series]/page.tsx
+export async function generateStaticParams() {
+  return generateSeriesStaticParams(siteConfig)
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ series: string }> }) {
+  const { series } = await params
+  return generateSeriesMetadata(series, siteConfig)
+}
+
+export default async function SeriesPage({ params }: { params: Promise<{ series: string }> }) {
+  const { series } = await params
+  const articles = await getArticlesBySeries(series, siteConfig)
+  return <SeriesArticlesPage seriesSlug={series} articles={articles} config={siteConfig} />
+}
+```
+
+`getArticlesBySeries(seriesSlug, config?)` sorts by `seriesOrder` ascending, falling back to `getAllArticles`' date order (stable sort) for articles missing `seriesOrder`. `getAdjacentArticlesInSeries(currentSlug, seriesSlug, config?)` is a series-aware sibling of `getAdjacentArticles` - it walks `seriesOrder` within the series instead of global date order. It returns the same `{ previous, next }` shape, so the existing `ArticleNavigation` component works unchanged for series navigation:
+
+```tsx
+const { previous, next } = await getAdjacentArticlesInSeries(article.slug, article.seriesSlug!, siteConfig)
+<ArticleNavigation previous={previous} next={next} basePath="/articles" />
+```
+
+### `Path`: curated "start here" journeys
+
+A `Path` is a distinct primitive from `series` - a curated, ordered journey that can cross series and categories, configured (not frontmatter-driven) via `ArticlesConfig.paths`:
+
+```ts
+const siteConfig: ArticlesConfig = {
+  siteUrl: 'https://example.com',
+  siteName: 'Example',
+  paths: {
+    'new-gm': {
+      name: 'New GM Starter Path',
+      promise: 'Run your first session with confidence.',
+      articles: ['intro-to-gming', 'prepping-your-first-session', 'running-combat'],
+      nextAction: { label: 'Get the GM checklist', href: '/lead-magnets/gm-checklist' },
+    },
+  },
+}
+```
+
+```ts
+import { getPath, getPathArticles } from '@fullstackdatasolutions/articles/server'
+
+const path = getPath('new-gm', siteConfig) // PathDefinition | null
+const orderedArticles = await getPathArticles('new-gm', siteConfig) // resolved Article[], path order
+```
+
+Missing or unpublished (`draft: true`) article references are **not** silently dropped into a dead step - they're hard failures caught by `validateArticles` (see below). `getPathArticles` itself resolves what it can (skipping unresolvable slugs) so a broken reference degrades gracefully at runtime while still failing your CI/build check.
+
+### Article-detail extension points (slots)
+
+Four typed, optional slots on `ArticleContent` place consumer-rendered content **around** the article body (a different problem from `config.mdxComponents`, which places content *inside* MDX bodies):
+
+```tsx
+import { ArticleContent } from '@fullstackdatasolutions/articles/server'
+
+<ArticleContent
+  article={article}
+  config={siteConfig}
+  afterHero={<NewsletterBanner />}
+  afterIntro={(ctx) => <InlineCta actionId={ctx.primaryActionId} />}
+  midContent={<LeadMagnetCallout />}
+  afterContent={<ArticleSocialShare title={article.title} url={articleUrl} articleSlug={article.slug} config={siteConfig} />}
+/>
+```
+
+Each slot accepts either a plain `ReactNode` or a function receiving a sanitized `ArticleSlotContext` (`slug`, `title`, `category`, `tags`, `readTime`, `wordCount`, `authorSlug`, `seriesSlug`, `primaryActionId` - no raw body content, no author PII). `afterHero`/`afterContent` always work. `afterIntro`/`midContent` need a detectable paragraph structure in the raw markdown/MDX source - resolved deterministically from the parsed AST (`getContentSlotBoundaries`, also exported from `./server`), never by splitting rendered HTML strings. When the source has no detectable paragraphs (e.g., very JSX-heavy MDX), `afterIntro`/`midContent` are silently omitted for that article - `afterHero`/`afterContent` still render. Omitting all four slot props reproduces `ArticleContent`'s exact pre-27F output.
+
+### Primary action reference
+
+`Article.primaryAction?: { actionId: string }` (frontmatter: `primaryAction: download-starter-kit` or `primaryAction: { actionId: download-starter-kit }`) references an app-owned CTA/offer by opaque ID. The package never interprets `actionId` - no coupling to a specific form, email provider, or analytics vendor. Look it up in your own registry inside a slot, and render nothing when there's no match:
+
+```tsx
+const CTA_REGISTRY: Record<string, ReactNode> = {
+  'download-starter-kit': <LeadMagnetCTA offer="gm-starter-kit" />,
+}
+
+afterContent={(ctx) => (ctx.primaryActionId ? (CTA_REGISTRY[ctx.primaryActionId] ?? null) : null)}
+```
+
+### Reusable related-content selection
+
+`getRelatedContent(article, config, limit?)` prefers a configured `Path` containing the article first, then its `seriesSlug`, falling back to 27B's `getRelatedArticlesByCategory` (imported, not reimplemented) when neither applies:
+
+```ts
+import { getRelatedContent } from '@fullstackdatasolutions/articles/server'
+import { RelatedArticlesSection } from '@fullstackdatasolutions/articles'
+
+const related = await getRelatedContent(article, siteConfig)
+
+<RelatedArticlesSection
+  articles={related.articles}
+  category={article.category}
+  heading={related.heading}
+  source={related.source}
+  fromSlug={article.slug}
+  config={siteConfig}
+/>
+```
+
+`RelatedArticlesSection` gained an optional `heading` override (defaults to `"More in {category}"` when omitted, unchanged) and, with `config`/`fromSlug` set, fires a `related_article_clicked` event on card click.
+
+### Event callbacks
+
+`ArticlesConfig.onEvent?: (event: ArticleEvent) => void` receives a typed, vendor-neutral event for eight reader-journey moments - `article_viewed`, `meaningful_read`, `author_clicked`, `cta_viewed`, `cta_clicked`, `shared`, `related_article_clicked`, `path_step_advanced`. Payloads only ever contain slugs/IDs/enums - no PII (no emails, no names-as-identifiers). The package has no PostHog/Plunk dependency; translate events to your own analytics stack inside `onEvent`:
+
+```ts
+const siteConfig: ArticlesConfig = {
+  siteUrl: 'https://example.com',
+  siteName: 'Example',
+  onEvent: (event) => {
+    posthog.capture(event.name, event)
+  },
+}
+```
+
+Components that fire events (all safely no-op when `config`/`config.onEvent` is omitted):
+
+| Component/hook           | Event(s)                  | Requires                          |
+| ------------------------- | -------------------------- | ---------------------------------- |
+| `ArticleViewTracker`      | `article_viewed`, `meaningful_read` | mount on the article detail page   |
+| `ArticleCard`              | `author_clicked`           | `config` prop                      |
+| `RelatedArticlesSection`   | `related_article_clicked`  | `config` + `fromSlug` props        |
+| `ArticleNavigation`        | `path_step_advanced`       | `config` + `pathKey` + `fromSlug` props |
+| `ArticleSocialShare`       | `shared`                   | `config` + `articleSlug` props     |
+| `AuthorArticlesPage` (`'cta'` section) | `cta_viewed`, `cta_clicked` | `config` prop               |
+| `CtaViewTracker`           | `cta_viewed`                | wrap any CTA block                 |
+
+`ArticleViewTracker` (client component, renders nothing) fires `article_viewed` on mount and `meaningful_read` once, after roughly half the article's estimated read time (`article.wordCount`-based, 15s default when unset) - a deterministic timing approximation, not scroll-depth tracking:
+
+```tsx
+import { ArticleViewTracker } from '@fullstackdatasolutions/articles'
+
+<ArticleViewTracker article={article} config={siteConfig} />
+<ArticleContent article={article} config={siteConfig} />
+```
+
+`CtaViewTracker` wraps any CTA block and fires `cta_viewed` once, the first time at least half of it scrolls into view (falls back to firing immediately when `IntersectionObserver` is unavailable):
+
+```tsx
+import { CtaViewTracker } from '@fullstackdatasolutions/articles'
+
+<CtaViewTracker ctaId="download-starter-kit" articleSlug={article.slug} config={siteConfig}>
+  {CTA_REGISTRY[actionId]}
+</CtaViewTracker>
+```
+
+### Package validator
+
+`validateArticles(articles, config)` (pure, no `fs`) and `validateAllArticles(config)` (loads via `getAllArticles` first) check required frontmatter, unique canonical URLs, valid author references, series order/slug collisions, `Path` article references (missing or draft), unsafe URL schemes (`javascript:`/`data:`/`vbscript:` in `Path.nextAction.href`/`AuthorProfile.primaryCta.href`), and discovery field length limits - returning `{ ok, errors, warnings }`. Errors are broken-reader-journey issues (fail your build/CI on them); warnings are optional-field gaps (missing excerpt/date, over-length search/social fields, category slug collisions).
+
+```ts
+// scripts/validate-articles.ts (your app)
+import { validateAllArticles } from '@fullstackdatasolutions/articles/server'
+import { siteConfig } from '../lib/articles-config'
+
+const result = await validateAllArticles(siteConfig)
+for (const warning of result.warnings) console.warn(warning.code, warning.message, warning.articleSlug)
+for (const error of result.errors) console.error(error.code, error.message, error.articleSlug ?? error.pathKey)
+if (!result.ok) process.exit(1)
+```
+
+There's no standalone CLI binary shipped in this package - `validateAllArticles` needs your app's real `ArticlesConfig` (author registry, paths, site URL), which lives in app code the package can't import. The thin script above is the intended integration point; wire it into CI or a pre-build step.
+
+---
+
+## Rich author profiles & composable `AuthorArticlesPage` sections
+
+`AuthorProfile` has optional, additive fields beyond the original `name`/`slug`/`bio`/`avatar`/`url`/`social` (Phase 27E). All are optional - a profile that doesn't set them renders exactly as before, everywhere `AuthorProfile` is used.
+
+| Field         | Type                                | Description                                                                                   |
+| ------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `promise`     | `string`                             | Short one-line audience promise, e.g. `"Helping new GMs run confident first sessions."`         |
+| `originStory` | `RichText` (`RichTextSection[]`)     | Structured long-form story: `{ heading?: string; paragraphs: string[] }[]` - not a single HTML blob. |
+| `servesWho`   | `string[]`                           | Who the author's work is for, e.g. `["New game masters", "Streaming DMs"]`.                     |
+| `principles`  | `string[]`                           | Core beliefs/approach statements.                                                               |
+| `credentials` | `string[]`                           | Experience/credential claims. Never included in Person JSON-LD (see below).                     |
+| `proof`       | `ProofItem[]`                        | `{ claim: string; source?: string; url?: string }[]` - concrete, sourceable proof points.        |
+| `primaryCta`  | `{ label: string; href: string }`    | Primary call-to-action for the author's page.                                                   |
+
+### Composable `AuthorArticlesPage` sections
+
+`AuthorArticlesPage` accepts an optional `sections` prop - an ordered array of section keys - plus a `customSection` slot:
+
+```ts
+type AuthorPageSection =
+  | 'hero'
+  | 'promise'
+  | 'servesWho'
+  | 'originStory'
+  | 'principles'
+  | 'proof'
+  | 'cta'
+  | 'articles'
+  | 'custom'
+```
+
+```tsx
+<AuthorArticlesPage
+  author={author}
+  articles={articles}
+  config={siteConfig}
+  sections={['hero', 'promise', 'servesWho', 'originStory', 'principles', 'proof', 'cta', 'custom', 'articles']}
+  customSection={<NewsletterSignup />}
+/>
+```
+
+- **Omitting `sections` keeps current behavior**: `AuthorArticlesPage` renders only the Person/CollectionPage JSON-LD plus the article list - no hero, no rich-profile sections - identical to pre-27E output. This is true even if `author` has every new field populated; nothing renders until you opt in via `sections`.
+- Each section (other than `'hero'`, `'articles'`, and `'custom'`) renders nothing when its backing field is unset, so you can safely list a key for a profile that doesn't have that data yet.
+- `'hero'` renders `AuthorDetailHero` (the same component you'd otherwise compose manually next to `AuthorArticlesPage`) - if you include it in `sections`, stop also rendering `<AuthorDetailHero>` separately in your page to avoid a duplicate.
+- `'custom'` renders whatever `ReactNode` you pass as `customSection`; omitted (renders nothing) if `'custom'` isn't in `sections`, or if `customSection` isn't passed.
+- Every new section uses a semantic `<section aria-label="...">` landmark with a visible heading, matching this package's existing accessibility convention (e.g. `RelatedArticlesSection`'s `aria-label="Related articles"`, `ArticleNavigation`'s `aria-label="Article navigation"`).
+
+```tsx
+// app/articles/authors/[author]/page.tsx
+<AuthorArticlesPage
+  author={author}
+  articles={articles}
+  config={siteConfig}
+  sections={['hero', 'promise', 'originStory', 'articles']}
+/>
+```
+
+### Person JSON-LD
+
+`getPersonSchema` (`AuthorArticlesPage`) and `getPersonSchemas` (`ArticleSchemas.tsx`, used by `ArticleSEO`) intentionally do **not** include `promise`, `servesWho`, `principles`, `credentials`, or `proof` - `promise`/`principles` are audience-facing marketing copy, `servesWho` is an audience segment rather than a `knowsAbout` topic, and `credentials`/`proof` are self-reported/unverifiable claims. None meet the bar for schema.org structured data. `description`, `image`, `sameAs`, and `knowsAbout` are sourced exactly as they were before this phase (`bio`, resolved avatar, approved social links, `config.siteName`).
+
+---
+
 ## ArticleTOC
 
 `ArticleTOC` renders the article's table of contents as an inline nav block above article content. Server component (no `'use client'`). Returns `null` when the `toc` array is empty, so it is safe to render unconditionally.
@@ -941,7 +1463,11 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
 
 Returns article entries (priority 0.8, changeFrequency 'weekly') and category entries (priority 0.7, changeFrequency 'weekly'). Alternative: pass a plain URL string instead of `siteConfig`: `getArticleSitemapEntries('https://yoursite.com')`.
 
-JSON-LD structured data (`ArticleSchema`, `Breadcrumb`, `BreadcrumbSchema`, `CollectionPageSchema`) is rendered automatically inside the library components. Use `Breadcrumb` for visible navigation plus schema, or `BreadcrumbSchema` when you only need visually hidden breadcrumb schema output.
+JSON-LD structured data (`ArticleSEO`, `Breadcrumb`, `BreadcrumbSchema`, `CollectionPageSchema`) is rendered automatically inside the library components. Use `Breadcrumb` for visible navigation plus schema, or `BreadcrumbSchema` when you only need visually hidden breadcrumb schema output.
+
+`ArticleSEO` accepts an optional `config?: ArticlesConfig` prop - pass it (as shown in the canonical `app/articles/[...slug]/page.tsx` example above) to populate each author's `image` in the `Person` schema via `getAuthorAvatar`. Without `config`, author schemas omit `image` unless the author's `avatar` is already an absolute URL. The `Article` schema also always includes `articleSection` (from `article.category`), `keywords` (from `article.tags`, comma-joined, omitted if empty), and `wordCount` (from `article.wordCount`, omitted if unset - computed automatically from the article body, no extra parsing cost).
+
+`CollectionPageSchema` accepts an optional `items?: { position: number; url: string; name: string }[]` prop - when provided (non-empty), it adds a `mainEntity: { '@type': 'ItemList', itemListElement: [...] }` alongside the existing `numberOfItems`. `ArticlesPage`, `CategoryArticlesPage`, and `AuthorArticlesPage` all pass this automatically, built from the articles actually present in the page's initial HTML (the first `pageSize`, matching what a crawler sees before "Load more" is clicked) - `CategoryArticlesPage` previously emitted no JSON-LD at all; `AuthorArticlesPage` now emits both its existing `Person` schema and a `CollectionPage`/`ItemList`.
 
 ---
 
@@ -962,8 +1488,16 @@ JSON-LD structured data (`ArticleSchema`, `Breadcrumb`, `BreadcrumbSchema`, `Col
 | `howTo`         | `{ name: string; text: string }[]`       | no       | How-to steps used by the article structured data. Invalid entries are ignored.                                                                                                                                                                                                           |
 | `canonicalUrl`  | `string`                                 | no       | Canonical URL override for article metadata.                                                                                                                                                                                                                                             |
 | `articleType`   | `string`                                 | no       | Optional article type value included in article metadata/structured data.                                                                                                                                                                                                                |
-| `series`        | `string`                                 | no       | Optional series label for grouping related articles.                                                                                                                                                                                                                                     |
+| `series`        | `string`                                 | no       | Optional series label for grouping related articles (display only).                                                                                                                                                                                                                     |
+| `seriesSlug`    | `string`                                 | no       | Machine-safe series id. Enables `getArticlesBySeries`/`getAdjacentArticlesInSeries`. See [Discovery & reader-journey layer](#discovery--reader-journey-layer-phase-27f).                                                                                                                |
+| `seriesOrder`   | `number`                                 | no       | Position within `seriesSlug`, ascending. Omitted articles fall back to date order.                                                                                                                                                                                                        |
 | `aiCrawl`       | `boolean`                                | no       | Set to `true` to publish the article's markdown twin and add a `text/markdown` alternate link. Omitted or `false` keeps markdown private and opts the HTML page out of AI indexing via helper headers.                                                                                   |
+| `searchTitle`   | `string`                                 | no       | Overrides `<title>`/meta description ONLY. Falls back to `title`.                                                                                                                                                                                                                         |
+| `searchDescription` | `string`                              | no       | Overrides meta description ONLY. Falls back to `excerpt`.                                                                                                                                                                                                                                 |
+| `socialTitle`   | `string`                                 | no       | Overrides Open Graph/Twitter Card title ONLY. Falls back to `title`.                                                                                                                                                                                                                      |
+| `socialDescription` | `string`                              | no       | Overrides Open Graph/Twitter Card description ONLY. Falls back to `excerpt`.                                                                                                                                                                                                              |
+| `socialImage`   | `string`                                 | no       | Overrides Open Graph/Twitter Card image ONLY. Falls back to `featuredImage`.                                                                                                                                                                                                              |
+| `primaryAction` | `string \| { actionId: string }`         | no       | References an app-owned CTA/offer by opaque ID. See [Discovery & reader-journey layer](#discovery--reader-journey-layer-phase-27f).                                                                                                                                                      |
 
 Articles can be authored as either `article.md` or `article.mdx` inside `public/articles/{slug}/`. The `{slug}` may be a path-like slug such as `game-system/article-name`. Markdown files are converted to HTML; MDX files are returned as `mdxSource` for the consuming app to render. Reading time and the table of contents are generated from the article body automatically.
 
@@ -993,23 +1527,36 @@ import {
   getAllCategories,
   getAvailableArticleSlugs,
   getAdjacentArticles,
+  getAdjacentArticlesInSeries,
+  getArticlesBySeries,
+  getRelatedArticlesByCategory,
+  getRelatedContent,
+  getPath,
+  getPathArticles,
   searchArticles,
   categoryToSlug,
   sanitizeImagePath,
   markdownToHtml,
   extractToc,
+  getContentSlotBoundaries,
   generateArticleStaticParams,
   generateCategoryStaticParams,
+  generateSeriesStaticParams,
   generateAuthorStaticParams,
   getArticleSitemapEntries,
   generateRssFeed,
   generateArticlesIndexMetadata,
   generateArticleMetadata,
   generateCategoryMetadata,
+  generateSeriesMetadata,
   generateAuthorMetadata,
+  resolveSearchMetadata,
+  resolveSocialMetadata,
   buildArticleBreadcrumbs,
   buildCategoryBreadcrumbs,
   buildAuthorBreadcrumbs,
+  validateArticles,
+  validateAllArticles,
 } from '@fullstackdatasolutions/articles/server'
 ```