@topy-ai/maggie 0.1.0

package/references/ai-native-blog-contract.md

@@ -0,0 +1,310 @@
+# Maggie AI-Native Blog Application Contract
+
+This contract describes the complete application surface for a Maggie-powered
+blog. It fixes the content, operations, and SEO semantics while leaving visual
+design and component composition to the implementing agent.
+
+## Public information architecture
+
+The default route map is:
+
+```text
+/blog                         published post index
+/blog/[slug]                  post detail
+/topics                       topic index
+/topics/[topic-slug]          topic landing page and post grid
+/authors/[author-slug]        authorship page when author pages are enabled
+/about                        optional organisation/EEAT page
+/sitemap.xml                  sitemap index or single sitemap
+/sitemap-posts-[part].xml     post sitemap parts when required
+/robots.txt                   crawl rules and sitemap reference
+```
+
+### Blog index
+
+The blog index should contain, in an accessible and crawlable order:
+
+1. page title and concise description;
+2. optional featured or latest post block;
+3. hot-topic navigation using real topic URLs;
+4. blog grid/list with title, excerpt, date, author, image alt text, and
+   normal anchor links;
+5. stable pagination with self-canonical pages and no indexable duplicate
+   query URLs;
+6. useful FAQ section only when questions and answers are maintained in the
+   content model;
+7. a configured CTA with explicit attribution.
+
+### Post detail
+
+Each published post must render:
+
+- title, excerpt, canonical URL, language, and visible publication date;
+- author name, author profile link, credentials or organisation context when
+  available, and source attribution;
+- modified date only when it represents a real content revision;
+- readable content with one `h1`, logical `h2`/`h3` headings, table of contents
+  when useful, internal links, related topics, and related posts;
+- cover image with dimensions and meaningful alt text;
+- Article/BlogPosting JSON-LD matching the visible page;
+- FAQ section only when the FAQ items are visible and maintained;
+- CTA selected by policy, with UTM attribution generated from known values only;
+- no draft, queue, internal note, or private project context.
+
+### Topic landing page
+
+Each indexable topic page must have:
+
+- unique topic title and useful topic description;
+- a stable topic slug and canonical URL;
+- a crawlable post grid filtered by `published` status;
+- pagination when the list exceeds the configured page size;
+- optional topic FAQ with visible answers and FAQ schema only when eligible;
+- related topics and one configured CTA where relevant;
+- no thin page created solely because a tag exists.
+
+Do not create indexable topic pages until the topic has a description and a
+minimum configured number of published posts, unless the user explicitly
+approves an exception.
+
+## Stable domain model
+
+```ts
+type PublishStatus = "draft" | "review" | "approved" | "published" | "archived";
+
+type Author = {
+  id: string;
+  slug: string;
+  name: string;
+  jobTitle?: string;
+  organisation?: string;
+  bio?: string;
+  profileUrl?: string;
+  sameAs?: string[];
+  avatarUrl?: string;
+  credentials?: string[];
+};
+
+type Topic = {
+  id: string;
+  slug: string;
+  title: string;
+  description: string;
+  status: "draft" | "published" | "archived";
+  seoTitle?: string;
+  seoDescription?: string;
+  faqIds: string[];
+  minimumPublishedPosts: number;
+};
+
+type FaqItem = {
+  id: string;
+  question: string;
+  answerMarkdown: string;
+  sortOrder: number;
+  status: "draft" | "published";
+};
+
+type Cta = {
+  id: string;
+  label: string;
+  url: string;
+  placement: "blog_index" | "post" | "topic" | "footer";
+  status: "draft" | "active" | "archived";
+  trackingKey?: string;
+};
+
+type SeoSnapshot = {
+  title: string;
+  description: string;
+  canonicalUrl: string;
+  robots: "index,follow" | "noindex,follow" | "noindex,nofollow";
+  ogType: "website" | "article";
+  ogImageUrl?: string;
+  twitterCard: "summary" | "summary_large_image";
+  jsonLdType: "Article" | "BlogPosting" | "CollectionPage" | "FAQPage";
+};
+
+type BlogReport = {
+  id: string;
+  runType: "technical_seo" | "content_quality" | "visibility" | "analytics";
+  status: "queued" | "running" | "completed" | "failed";
+  startedAt?: string;
+  completedAt?: string;
+  summary: Record<string, unknown>;
+  findings: Array<{
+    severity: "error" | "warning" | "info";
+    code: string;
+    url?: string;
+    message: string;
+  }>;
+};
+```
+
+Extend the [canonical post model](blog-data-contract.md) with `authorIds`,
+`topicIds`, `faqIds`, `ctaId`, `seo`, and `contentQuality` rather than putting
+these fields into an untyped metadata blob.
+
+## Maggie Ops dashboard
+
+The operations dashboard is private, authenticated, and never included in the
+public sitemap or robots allowlist:
+
+```text
+/ops                         health summary and pending actions
+/ops/posts                   filterable post inventory
+/ops/posts/new               create draft
+/ops/posts/[id]/edit         edit metadata/content with validation
+/ops/posts/[id]/preview      preview draft without indexing
+/ops/topics                  topic and FAQ management
+/ops/sitemap                 sitemap source, matching history, and eligibility
+/ops/reports                 technical SEO, content, visibility, analytics reports
+/ops/settings/site           origin, locale, timezone, author defaults, CTA defaults
+/ops/settings/integrations   AI CMO key status, API Pull, GSC, and GA4 settings
+```
+
+Dashboard actions must be explicit and auditable:
+
+| Action | Required state | External write |
+|---|---|---:|
+| Save draft | authenticated editor | no |
+| Approve post | review-ready post and editor approval | no |
+| Publish post | approved post and publishing permission | yes/public |
+| Match sitemap | completed bootstrap and configured source | AI CMO API |
+| Queue rewrite | matched asset and rewrite policy | AI CMO API |
+| Sync API Pull | server key and source mapping | AI CMO API |
+| Run report | configured target/property | provider/API varies |
+| Change integration | owner/admin permission | yes |
+
+Every mutation records actor, timestamp, previous state, new state, reason,
+and correlation/idempotency key. The dashboard should show a dry-run preview
+before queueing, publishing, changing sitemap sources, or changing integration
+settings.
+
+### Ops API boundary
+
+Keep the browser UI thin. All reads and mutations go through authenticated
+server-side routes with typed request/response objects:
+
+```text
+GET    /api/ops/summary
+GET    /api/ops/posts?status=&topic=&page=
+POST   /api/ops/posts
+GET    /api/ops/posts/[id]
+PATCH  /api/ops/posts/[id]
+POST   /api/ops/posts/[id]/preview
+POST   /api/ops/posts/[id]/approve
+POST   /api/ops/posts/[id]/publish
+GET    /api/ops/topics
+POST   /api/ops/topics
+PATCH  /api/ops/topics/[id]
+GET    /api/ops/sitemap/runs
+POST   /api/ops/sitemap/match
+POST   /api/ops/sitemap/auto-detect
+GET    /api/ops/reports?type=&status=
+POST   /api/ops/reports
+GET    /api/ops/settings
+PATCH  /api/ops/settings/site
+PATCH  /api/ops/settings/integrations
+```
+
+Every route must perform session authentication, role authorization, input
+schema validation, and state-transition validation. Do not expose raw database
+queries or the AI CMO key to the browser. Return a correlation ID with errors
+so an Ops user can reconcile a failed action without seeing secret values.
+
+The post editor must validate title, slug, excerpt, language, author, topics,
+publication status, canonical URL, cover image/alt text, and SEO fields before
+save. A preview uses `noindex` and the same renderer as the public post; it is
+not a second content implementation.
+
+### Ops dashboard summary
+
+`GET /api/ops/summary` should expose only bounded operational facts:
+
+```ts
+type OpsSummary = {
+  bootstrap: "complete" | "incomplete";
+  content: { published: number; drafts: number; review: number; failedSyncs: number };
+  sitemap: { lastRunAt?: string; matched: number; eligible: number; unmatched: number };
+  reports: { openErrors: number; lastTechnicalSeoRunAt?: string };
+  integrations: { aiCmo: "disabled" | "configured" | "verified" | "error"; gsc: string; ga4: string };
+};
+```
+
+Counts must be calculated from the same repositories used by the public
+routes. Do not use stale client counters to decide whether a post is eligible
+for publication or rewrite.
+
+## Configuration boundary
+
+Keep non-secret configuration typed and reviewable:
+
+```ts
+type BlogConfig = {
+  site: {
+    name: string;
+    baseUrl: string;
+    locale: string;
+    timezone: string;
+    blogPath: string;
+    postsPerPage: number;
+    topicMinimumPosts: number;
+  };
+  defaults: {
+    authorId?: string;
+    ctaId?: string;
+    language: string;
+    robotsPolicy: "index,follow" | "noindex,follow";
+  };
+  integrations: {
+    aiCmo: { enabled: boolean; baseUrl: string; apiKeyEnv: string; syncMode: "manual" | "scheduled" };
+    gsc: { enabled: boolean; verificationMode?: "html" | "dns" };
+    ga4: { enabled: boolean; measurementIdEnv?: string; consentRequired: boolean };
+  };
+  publishing: {
+    requireApproval: boolean;
+    allowScheduledPublish: boolean;
+    allowAutoRewritePublish: boolean;
+  };
+};
+```
+
+Secret values stay in runtime environment variables. The dashboard may show
+configured/missing/verified status, but never the key or token value.
+
+## Backend and SEO invariants
+
+- Public reads select `status = published` and valid `publishedAt` in one
+  repository function; templates must not implement their own filtering.
+- Post, topic, FAQ, author, CTA, and report IDs are stable and never derived
+  from mutable display text after publication.
+- Every public URL has one canonical owner. Slug changes create redirects and
+  never silently create a second page.
+- Preview, draft, review, archived, ops, and report URLs are `noindex` and
+  excluded from sitemap output.
+- The sitemap is generated from the same publication query used by the public
+  list, not from a separate hand-maintained URL array.
+- Metadata and JSON-LD are generated from validated domain objects, not from
+  free-form agent prose.
+- Build and report failures preserve the last known-good public output.
+- API Pull, GSC, and GA4 integrations are optional; missing credentials must
+  produce a visible disabled/unverified state, not a broken build.
+
+## Implementation order
+
+Generate and verify the application in this order:
+
+1. typed config and environment validation;
+2. database migrations and repository functions;
+3. post/topic/author/FAQ/CTA schemas and seed fixtures;
+4. public rendering and metadata helpers;
+5. sitemap/robots generation from the publication query;
+6. authenticated Ops API and dashboard screens;
+7. API Pull adapter, sitemap matching, and state reporting;
+8. reports, GSC/GA4 readback, and scheduled jobs;
+9. integration, route, metadata, and migration tests.
+
+Do not build the dashboard against mock objects after step 2. Fixtures are for
+tests and empty-state UI only; production reads must use the validated
+repository boundary.

package/references/blog-data-contract.md

@@ -0,0 +1,146 @@
+# Maggie Blog Data Contract
+
+This contract is the stable backend boundary for every Maggie framework
+template. UI components may differ, but adapters should normalize all content
+to this model before rendering.
+
+## Canonical post model
+
+```ts
+type PostStatus = "draft" | "review" | "approved" | "scheduled" | "published" | "archived";
+
+type BlogPost = {
+  id: string;                    // local stable id
+  source: "local" | "api-pull" | "cms" | "manual";
+  sourceId?: string;             // remote content_id or provider id
+  slug: string;                  // unique public identity
+  title: string;
+  excerpt: string;
+  contentMarkdown?: string;
+  contentHtml?: string;
+  canonicalUrl: string;
+  coverImageUrl?: string;
+  coverImageAlt?: string;
+  authorName?: string;
+  authorUrl?: string;
+  language: string;
+  tags: string[];
+  status: PostStatus;
+  publishedAt?: string;          // ISO-8601 UTC
+  updatedAt?: string;            // ISO-8601 UTC
+  createdAt: string;             // ISO-8601 UTC
+  contentHash?: string;
+};
+```
+
+Required invariants:
+
+- `slug` is unique and does not change after publication without a redirect.
+- `status = published` and a valid `publishedAt` are both required for a
+  public route, list item, sitemap entry, or Article JSON-LD record.
+- `canonicalUrl` is absolute, uses the configured site origin, and has no
+  tracking query parameters.
+- Store Markdown and/or sanitized HTML, never unsanitized remote HTML.
+- Keep remote `sourceId` separate from local `id`; neither may be inferred from
+  a mutable title.
+- Dates are serialized as ISO-8601 UTC and displayed using the chosen locale.
+
+## SQLite reference schema
+
+The Astro starter additionally includes migration tables for external CMS
+imports: `wp_migrations`, `wp_import_items`, `wp_terms`, `media_assets`,
+`post_media`, and `redirects`. A WordPress source identity is stored as
+`source = 'cms'` and `source_id = 'wordpress:<id>'` so it remains compatible
+with the canonical post source enum while remaining unique and rerunnable.
+
+This is the default for a new, small single-instance project. Use the same
+logical fields with Postgres or another engine when the deployment requires it.
+
+```sql
+CREATE TABLE posts (
+  id TEXT PRIMARY KEY,
+  source TEXT NOT NULL CHECK (source IN ('local', 'api-pull', 'cms', 'manual')),
+  source_id TEXT,
+  slug TEXT NOT NULL UNIQUE,
+  title TEXT NOT NULL,
+  excerpt TEXT NOT NULL DEFAULT '',
+  content_markdown TEXT,
+  content_html TEXT,
+  canonical_url TEXT NOT NULL UNIQUE,
+  cover_image_url TEXT,
+  cover_image_alt TEXT,
+  author_name TEXT,
+  author_url TEXT,
+  language TEXT NOT NULL DEFAULT 'en',
+  status TEXT NOT NULL DEFAULT 'draft'
+    CHECK (status IN ('draft', 'review', 'approved', 'scheduled', 'published', 'archived')),
+  published_at TEXT,
+  updated_at TEXT,
+  created_at TEXT NOT NULL,
+  content_hash TEXT,
+  CHECK (status <> 'published' OR published_at IS NOT NULL)
+);
+
+CREATE UNIQUE INDEX posts_source_identity
+  ON posts (source, source_id)
+  WHERE source_id IS NOT NULL;
+CREATE INDEX posts_public_order
+  ON posts (status, published_at DESC, updated_at DESC);
+
+CREATE TABLE post_tags (
+  post_id TEXT NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  tag TEXT NOT NULL,
+  PRIMARY KEY (post_id, tag)
+);
+
+CREATE TABLE content_sync_state (
+  source TEXT PRIMARY KEY,
+  cursor TEXT,
+  etag TEXT,
+  last_success_at TEXT,
+  last_error TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE content_delivery_state (
+  post_id TEXT PRIMARY KEY REFERENCES posts(id) ON DELETE CASCADE,
+  remote_content_id TEXT,
+  remote_version TEXT,
+  delivery_status TEXT NOT NULL DEFAULT 'not_delivered'
+    CHECK (delivery_status IN ('not_delivered', 'received', 'stored', 'published', 'failed')),
+  last_reported_url TEXT,
+  last_reported_hash TEXT,
+  last_error TEXT,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE post_redirects (
+  old_slug TEXT PRIMARY KEY,
+  post_id TEXT NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL
+);
+```
+
+For a multi-instance or serverless production deployment, confirm the hosted
+database and migration strategy before using SQLite. Never silently create a
+second database beside an existing ORM or CMS database.
+
+## API Pull normalization
+
+Map the remote response at one adapter boundary:
+
+```text
+remote content_id       -> posts.source_id and content_delivery_state.remote_content_id
+remote id                -> posts.source_id when content_id is unavailable
+remote title             -> posts.title
+remote excerpt           -> posts.excerpt
+remote content_markdown  -> posts.content_markdown
+remote content_html      -> sanitize, then posts.content_html
+remote canonical_url     -> posts.canonical_url
+remote slug              -> posts.slug, never overwrite a published local slug
+remote generated_at      -> posts.updated_at
+```
+
+The adapter must validate required fields, preserve the original response for
+debugging outside public output, upsert by source identity, and only mark a
+delivery successful after local storage succeeds.

package/references/blog-implementation.md

@@ -0,0 +1,46 @@
+# Framework-Neutral Blog Implementation Contract
+
+This is the minimum complete blog surface. Framework templates may map these
+routes differently, but must preserve their behaviour.
+
+## Public surface
+
+| Surface | Requirement |
+|---|---|
+| Posts index | Crawlable links, title, excerpt, published date, pagination or bounded feed |
+| Post detail | Stable slug, 404 for missing/unpublished content, canonical URL |
+| Robots | Allow public posts and reference the sitemap |
+| Sitemap | Published posts only, absolute canonical URLs, `lastmod` when known |
+| Metadata | Title, description, canonical, OG, Twitter, Article JSON-LD |
+| Analytics | GA4 only when configured and consent policy permits |
+| GSC | Verification path or documented DNS verification |
+
+## Data rules
+
+- `slug` is unique and immutable after publication unless a redirect is created.
+- `publishedAt` controls sitemap/index inclusion.
+- `updatedAt` is not a substitute for publication state.
+- `canonicalUrl` wins over inferred request host when configured.
+- Untrusted HTML is sanitized before rendering.
+
+## Technical SEO acceptance
+
+- one canonical per post;
+- no indexable duplicate query URLs;
+- server output contains the post title and primary content;
+- one `h1` per post;
+- images have dimensions or stable layout reservation and alt text;
+- internal links use normal anchors;
+- sitemap and robots return 200 with the correct content type.
+
+## GEO/AI discoverability acceptance
+
+The implementation should make the same facts available to humans and crawlers:
+
+- clear author, organisation, date, and source attribution;
+- concise answer-first opening paragraphs;
+- descriptive headings and stable URLs;
+- Article JSON-LD matching visible content;
+- no robots rule that accidentally blocks major search crawlers;
+- no claim that crawler access guarantees AI citations or rankings.
+

package/references/blog-operations-contract.md

@@ -0,0 +1,68 @@
+# Maggie Blog Operations Contract
+
+The starter keeps blog reading, content operations, migration, and agency
+administration on explicit server-side contracts. Agents may customize UI/UX,
+but must preserve these invariants:
+
+## Content operations
+
+- Every scheduled publication is stored in `content_calendar` and is promoted
+  only from an approved/review state by `POST /api/ops/calendar/publish-due`.
+- Every revision is a complete immutable post snapshot in `post_revisions`.
+- Every bulk mutation starts as `bulk-preview`; apply operations are limited to
+  an allowlist of fields and produce an `audit_events` record.
+- Redirects are unique by source path and accept only 301/308.
+- Media is a first-class `media_assets` record with usage counts, metadata and
+  optional folders; remote media is never silently assumed to be local.
+
+## Migration
+
+`POST /api/ops/migrations/import` accepts JSON, CSV, WXR, sitemap, or
+`media-archive` input in preview/apply mode. Imported content uses
+`source + source_id` as its identity and a SHA-256 checksum for incremental
+reruns. `syncMode` supports `all`, `new`, and `modified`; `detectDeleted` archives
+source records absent from a full snapshot, and `conflict` supports
+`source-wins`, `target-wins`, or `manual`. Redirect mappings support both JSON
+and CSV import/export. Persisted migrations can resume with
+`POST /api/ops/migrations/:id/resume`; source identity and checksums keep the
+resumed import idempotent. WordPress REST remains the richer adapter for terms,
+authors, featured media and old-path redirects.
+
+## Agency
+
+`workspaces`, `clients`, `sites`, and `workspace_members` isolate client data
+and credentials. Workspace-scoped reads and writes use `/api/ops/agency` and
+reject cross-workspace client/site/project relations. Roles are fixed to the
+eight supported agency roles; secrets remain in server
+environment/configuration and are never returned by browser APIs.
+`approval_links` provides expiring, branded-review-compatible handoff tokens
+without storing raw tokens.
+
+Entity profiles and `entity_relations` form a small explicit entity graph;
+insights also return refresh recommendations derived from persisted content
+quality signals rather than silently mutating published content.
+
+## Vibe-coding safety
+
+Bootstrap confirmation writes the project, decisions, schema, routes,
+integrations, and migration manifests under `.maggie/`. `maggie doctor` and
+`npm run schema:check` are required gates before generated code is considered
+ready. Fixtures are deterministic and must be used for local provider tests.
+
+## API Pull lifecycle
+
+The adapter exposes project context, post/update pulls, sitemap matching
+history, rewrite queue/history, and publication-state reporting as separate
+server-only operations. A local write and approval decision must complete
+before `report-state` is called. Batch reporting is bounded to 500 records per
+request, and API credentials are read from server configuration only.
+
+## External providers
+
+Email and media are provider-neutral contracts. Resend is the default email
+adapter and Cloudinary is the default media storage/delivery adapter; local or
+webhook adapters can be selected without changing post, report, or media
+records. Provider adapters must expose configuration health, normalize errors,
+and never return credentials through Ops APIs. A new provider should implement
+the relevant interface and register its ID rather than adding provider fields
+to content templates.

package/references/browser-inspection.md

@@ -0,0 +1,39 @@
+# Maggie Clone Browser Inspection Contract
+
+`maggie-clone` requires an available browser automation capability. The skill
+is intentionally provider-neutral: use the configured Chrome, browser,
+Playwright, Puppeteer, or equivalent MCP tools rather than adding a fake local
+MCP server to the host project.
+
+The browser capability must support:
+
+- navigation to a target URL and reading the final URL after redirects;
+- desktop, tablet, and mobile viewport sizes;
+- full-page and viewport screenshots saved to the planned artifact directory;
+- DOM/text/attribute queries and JavaScript evaluation;
+- slow scrolling, click, hover, keyboard focus, and back/forward navigation;
+- reading computed CSS, media sources, links, and visible accessibility labels.
+
+The minimum extraction result for a target is:
+
+```text
+final URL and redirect chain
+viewport screenshots: 1440, 768, 390
+page sections and destination route
+visible copy and links
+computed design tokens
+asset URLs and media metadata
+interaction states and triggers
+responsive differences
+```
+
+If a target requires login, a bot challenge, a consent interaction, or a
+private browser profile, stop at that boundary and ask the user to provide
+authorized access. Do not bypass access controls or record cookies in project
+artifacts.
+
+Use browser evaluation to measure values; do not infer a Tailwind class from
+appearance. For every stateful component capture state A and state B and
+record the trigger and transition. Keep screenshots and extracted data under
+the target's namespaced research root so multiple URLs cannot overwrite one
+another.

package/references/provider-adapter-contract.md

@@ -0,0 +1,68 @@
+# Maggie Provider Adapter Contract
+
+Third-party services are implementation details behind stable interfaces. Blog
+routes, content records, reports, and Ops screens must depend on capabilities,
+not on a vendor SDK or vendor-specific fields.
+
+## Defaults
+
+| Capability | Default | Local/development alternative |
+|---|---|---|
+| Email delivery | `resend` | `webhook` or `disabled` |
+| Media storage and delivery | `cloudinary` | `local` |
+
+The default can be changed through environment configuration. Missing
+credentials fail closed: email is queued or reports a provider error, and
+media upload is marked failed. A typo or unknown provider never silently falls
+back to a different external service.
+
+## Email interface
+
+An email adapter implements `EmailProvider`:
+
+```ts
+type EmailProvider = {
+  id: string;
+  send(message: EmailMessage): Promise<EmailResult>;
+  health(): { configured: boolean; capabilities: string[]; reason?: string };
+};
+```
+
+`EmailMessage` contains only normalized `from`, `to`, `subject`, `html`,
+optional `text`, and optional `replyTo`. The Resend adapter uses the server-only
+`RESEND_API_KEY` and `EMAIL_FROM`; it never accepts credentials from a request.
+The webhook adapter preserves compatibility with existing mail gateways.
+
+## Media interface
+
+An image/video/file adapter implements `MediaStorageProvider`:
+
+```ts
+type MediaStorageProvider = {
+  id: string;
+  upload(input: MediaUpload): Promise<MediaUploadResult>;
+  health(): { configured: boolean; capabilities: string[]; reason?: string };
+};
+```
+
+The normalized result stores provider ID, storage key, delivery URL, byte
+count, and MIME type. Local adapters may additionally return a filesystem path;
+public delivery URL and local path must not be conflated. Cloudinary uploads
+are signed server-side and expose only the resulting delivery URL to public
+rendering.
+
+## Adding a provider
+
+1. Implement the relevant interface in `src/lib/providers/`.
+2. Normalize provider errors into `sent`, `queued`, `failed`, or upload failure
+   states; include a bounded, non-secret error message.
+3. Implement `health()` with capabilities and required configuration names.
+4. Register the adapter with `registerEmailProvider()` or
+   `registerMediaStorageProvider()`.
+5. Add env names to `.env.example`, but never add values or credentials to
+   generated files, logs, database settings, or browser bundles.
+6. Add a fixture/mock and a contract test for missing credentials, success,
+   retryable failure, and idempotent repeated calls.
+
+Provider-specific options belong in provider configuration, not in the
+canonical post or report schema.