feat: SEO backend output (2/4)

docs/api/articles.md

@@ -36,12 +36,14 @@ Visibility is unchanged: anonymous and unverified callers only see online articl
 | `q` | up to 200 characters, matched anywhere in the title, ignoring case and accents | none |
 | `status` | `online` or `draft` | none |
 | `site` | the `key` of a site; an unknown key gives an empty page, an empty value is `400` | none |
+| `seo` | `ready`, `suggestions` or `hidden`; any other value, an empty one included, is `400` | none |
 | `sort` | `title`, `status`, `created_at` or `updated_at`, then `:asc` or `:desc` (lowercase, for example `title:asc`) | `updated_at:desc` |
 
 - `items` is `[]` when empty, never `null`. Each item is the article object below.
 - Items follow `sort` (default `updated_at:desc`) across the whole list before paging. `title` ignores case, `status` orders on online state (`status:asc` puts drafts first), and every ordering ends with `id` descending so pages never overlap.
 - `total` is the number of visible articles matching `q` and `status`, before paging. `page` and `size` echo the values applied.
 - `counts` ignores `q` and `status`, so tab counts do not move while searching. For anonymous and unverified callers `all` equals `online` and `draft` is `0`, and `status=draft` answers `items: []` and `total: 0`.
+- Each item also carries `seo_status` and `seo_suggestions` (see [SEO status and suggestions](#seo-status-and-suggestions)). `seo` filters on the status before paging, so `total` follows it while `counts` do not.
 - A page beyond the last answers `200` with `items: []` and the real `total`.
 - An invalid `page`, `size`, `status`, `sort` or an over-long `q` answers `400` with the plain-text message `The request cannot be processed due to a mismatch in the format of the body.` An invalid `format` is reported first.
 
@@ -117,6 +119,45 @@ Editing a slug that another article of the target site already uses (the new sit
 
 Publishing, unpublishing and `noindex` never change a slug. A deleted article frees its slug.
 
+## Resolved SEO object
+
+`GET /v1/article/{id}/seo` answers the data a frontend renders in its `<head>`. Online articles are public; a draft needs a verified session or API key and is otherwise `404 Article not found`. The query is ignored (no `format`). Keys:
+
+`title`, `description`, `canonical_url`, `robots`, `og` (`type`, `title`, `description`, `image`, `image_alt`, `url`, `site_name`, `locale`), `twitter` (`card`, `title`, `description`, `image`, `image_alt`), `image` (`url`, `alt`, `source`), `authors` (`name`, `url`, `same_as`), `published_at`, `modified_at`, `fallbacks` and `json_ld` (a ready schema.org `Article`).
+
+The fallback chain, first non-empty wins:
+
+| Output | Chain | `fallbacks` value |
+| --- | --- | --- |
+| `title` | `seo_title`, then the article title, then the site `title_template` (`%title%`, `%site%` replaced by `site_name`, result trimmed) | `seo_title`, `title` |
+| `description` | `seo_description`, `excerpt`, the first sentence of the body (tags removed), the site `default_description` | `seo_description`, `excerpt`, `body`, `site`, `none` |
+| `image` | `social_image_id`, `cover_image_id` (with `cover_image_alt`), the site `default_social_image_id`; `url` is the site `base_url` plus the image path, `""` and `none` when there is none | `social`, `cover`, `site`, `none` |
+| `canonical_url` | `canonical_url`, then site `base_url` + `/` + `slug` | `canonical_url`, `site` |
+| `robots` | `noindex, nofollow` when `noindex` is true, otherwise from the site `default_robots` (`index, follow` or `noindex, nofollow`) | none |
+| `og` and `twitter` title and description | `social_title` and `social_description`, then the resolved values | none |
+
+`og.type` is `article`, `og.locale` is the site locale (`""` when none), `twitter.card` is `summary_large_image` with an image and `summary` without. `published_at` is the creation time of an online article and `null` for a draft; `modified_at` is `updated_at`. `authors[].url` is the author website (`""` when none) and `same_as` lists the social link URLs only. `json_ld.headline` is the meta title without the site template, and `author`, `image` and `datePublished` are left out when empty.
+
+## SEO status and suggestions
+
+`POST /v1/article/{id}/seo/check` and the list use one rule set. Soft ranges never block saving or publishing; lengths are counted in characters.
+
+| Code | Field | Fires when | `params` |
+| --- | --- | --- | --- |
+| `title_long` | `seo_title` | the meta title (`seo_title`, else the title) is over 60 characters | `length`, `max` |
+| `title_empty` | `seo_title` | the meta title is empty after trimming | none |
+| `desc_short` | `seo_description` | the resolved description is under 70 characters | `length`, `min` |
+| `desc_long` | `seo_description` | the resolved description is over 160 characters | `length`, `max` |
+| `cover_alt` | `cover_image_alt` | there is a cover and its alt text is empty | none |
+| `cover_none` | `cover_image_id` | there is no cover | none |
+| `slug_long` | `slug` | the slug is over 75 characters | `length`, `max` |
+| `no_au` | `author_ids` | no author is credited | none |
+| `no_h` | `body` | the text has at least 1000 characters and no `h2` to `h6` | none |
+| `body_alt` | `body` | an image of the body has no alt text | `count` |
+| `short` | `body` | the text has fewer than 300 characters | `length`, `min` |
+
+Suggestions come in that order. Codes in `seo_dismissed` are never reported or counted. The status is `hidden` when `noindex` is true, else `suggestions` when at least one suggestion remains, else `ready`. The list items carry `seo_status` and `seo_suggestions` (the count, also for a hidden article).
+
 ## Markdown output
 
 Headings, bold, italic, links, bullet and ordered lists, blockquotes, fenced code blocks, rules, images and inline code are converted. Anything else is reduced to its text. `script` and `style` content is removed, and the source HTML is never passed through; the only HTML in the output is the alignment wrapper described below. List indentation attributes are dropped. Links with a scheme other than http, https, mailto or tel are reduced to their text. Characters that markdown would read as formatting (`*`, `_`, `` ` ``, `[`, `]`, `<`, `\`) and line starts that would read as a heading, list, quote or rule (`#`, `-`, `+`, `>`, `1.`) are backslash-escaped, so plain text stays plain text. A line break becomes a backslash followed by a newline.