@topy-ai/maggie 0.1.0

package/references/seo-technical-contract.md

@@ -0,0 +1,75 @@
+# Maggie SEO Technical Contract
+
+This contract fixes the SEO output that agents should generate. Layout and
+visual design remain flexible; these page-level signals are not optional.
+
+## Required post metadata
+
+Every published post response should contain exactly one of each where
+applicable:
+
+```text
+<title>{title} | {site name}</title>
+<meta name="description" content="{excerpt}">
+<link rel="canonical" href="{absolute canonical URL}">
+<meta property="og:type" content="article">
+<meta property="og:title" content="{title}">
+<meta property="og:description" content="{excerpt}">
+<meta property="og:url" content="{absolute canonical URL}">
+<meta property="og:image" content="{absolute image URL}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="{title}">
+<meta name="twitter:description" content="{excerpt}">
+```
+
+Rules:
+
+- Escape all values for HTML attributes and JSON-LD.
+- Use the configured site origin; never derive canonical URLs from an
+  untrusted `Host` header.
+- Do not index preview, query-string, draft, login, or error URLs.
+- Do not emit empty descriptions, relative canonical URLs, or placeholder image
+  URLs.
+- A post page has one visible `h1`; headings in body content start at `h2`.
+
+## Article JSON-LD
+
+Emit one `Article` or `BlogPosting` object that agrees with visible content:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Post title",
+  "description": "Post excerpt",
+  "mainEntityOfPage": { "@type": "WebPage", "@id": "https://example.com/posts/post-title" },
+  "url": "https://example.com/posts/post-title",
+  "datePublished": "2026-08-28T00:00:00Z",
+  "dateModified": "2026-08-28T00:00:00Z",
+  "author": { "@type": "Person", "name": "Author" },
+  "publisher": { "@type": "Organization", "name": "Site name" },
+  "image": ["https://example.com/images/post-title.jpg"]
+}
+```
+
+Never invent an author, date, publisher, review, rating, or image. Omit an
+optional property when the source does not provide it. JSON-LD must not claim
+facts that are absent from the rendered page.
+
+## Crawl surfaces
+
+`robots.txt` must be a successful plain-text response and reference the
+absolute sitemap URL. The sitemap must:
+
+- contain only canonical, published post URLs;
+- use valid XML and an absolute `<loc>`;
+- include `<lastmod>` only when it is a trustworthy ISO date;
+- exclude drafts, redirects, duplicates, unmatched records, and query URLs;
+- use a sitemap index when the output exceeds the chosen URL limit.
+
+## Acceptance checks
+
+The adapter or CLI should fail the build or preview check when a published
+post has a missing title, slug, canonical URL, publication date, metadata,
+JSON-LD, or sitemap eligibility decision. Also test a draft, an unpublished
+post, a missing slug, a changed slug with redirect, and a failed content sync.