backend-manager 5.2.16 → 5.2.17

package/CHANGELOG.md

@@ -14,6 +14,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.2.17] - 2026-05-29
+
+### Added
+
+- **Newsletter-driven blog articles (`marketing.beehiiv.content.article`).** When enabled, the newsletter generator expands its **lead section** (`structure.sections[0]`) into a full blog article via the Ghostii engine, publishes it to the website repo through the `admin/post` route, and injects a "Read the full article" CTA (`section.cta = { label, url }`) onto that section so the newsletter links to the long-form post. The article build runs **concurrently** with SVG image generation (both are slow AI calls) and is **failure-isolated** — if it throws, no CTA is injected and the newsletter ships normally. The published URL (`{brand.url}/blog/{slug}`) is surfaced on the generator return as `assets.articleUrl` and `meta.article`. New config block: `content.article = { enabled, author }` (`enabled` default `false`). See `docs/marketing-campaigns.md`.
+- **`section.cta` rendering.** Both the MJML template (`sectionCard`, already supported) and the markdown renderer (`lib/markdown-renderer.js`, new) now render `section.cta = { label, url }` when present. `getBodySections` passes `cta` through for both classic and field-report shapes. CTAs are still never authored by the AI — they're injected by code post-publish with a real, verified URL.
+- **Generate/publish split on the linked article (`opts.publishArticle`).** When `config.article.enabled` is on, the article is always **generated** (Ghostii writes it + the public URL is computed from the title slug + the CTA is injected), but it's only **committed** to the website repo via `admin/post` when `opts.publishArticle` is true. The production cron passes `publishArticle: true`. The newsletter iteration test (`test/marketing/newsletter-generate.js`) leaves it false by default — so a full `TEST_EXTENDED_MODE=1` run exercises the Ghostii write + CTA path without committing a real post — and opts in with `NEWSLETTER_CREATE_ARTICLE=1`. The CTA URL is valid either way (derived from the same slugify `admin/post` uses). `meta.article.published` records whether the post was actually committed.
+
+### Changed
+
+- **Extracted the Ghostii article engine into `src/manager/libraries/content/ghostii.js`** (`writeArticle` + `publishArticle`) as the SSOT for the Ghostii API request shape and the `admin/post` publish payload. Both the standalone `ghostii-auto-publisher.js` daily cron and the new newsletter linked-article flow import it (DRY). No behavior change to the standalone cron.
+- **Standalone Ghostii is now disabled by default** (`ghostii[0].articles: 0` in `templates/backend-manager-config.json`). The daily `ghostii-auto-publisher.js` cron remains fully functional — set `articles >= 1` to opt back into independent article publishing. For newsletter-linked articles, use `content.article.enabled` instead.
+
 # [5.2.16] - 2026-05-28
 
 ### Removed

package/CLAUDE.md

@@ -34,7 +34,7 @@ All `npx mgr <cmd>` aliases work: `npx bm <cmd>`, `npx bem <cmd>`, `npx backend-
 1. `npm install` — install BEM's own deps
 2. `npm run prepare` — build once: copies `src/` → `dist/` via prepare-package
 3. `npm run prepare:watch` — watch mode
-4. Test in a consumer project: from inside the consumer's `functions/` dir, run `npx mgr install local` (swaps BEM to the local repo via the `install` CLI). Reverse with `npx mgr install prod`.
+4. Test in a consumer project: from inside the consumer, run `npx mgr install dev` to swap BEM to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/backend-manager`). Reverse with `npx mgr install prod`. If `npx mgr` then errors with "could not determine executable to run", the local install skipped bin-linking — re-run `npm install` to relink, or call `node node_modules/backend-manager/bin/backend-manager <cmd>` directly.
 
 ## Architecture
 
@@ -119,9 +119,9 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 
 ### Built-in Routes
 
-- [docs/admin-post-route.md](docs/admin-post-route.md) — `POST/PUT /admin/post` blog creation via GitHub (image extraction + resize at ingest + `@post/` rewriting)
+- [docs/admin-post-route.md](docs/admin-post-route.md) — `POST/PUT /admin/post` blog creation via GitHub (image extraction + resize at ingest + `@post/` rewriting). Also the publish target for the Ghostii article engine (`libraries/content/ghostii.js`).
 - [docs/payment-system.md](docs/payment-system.md) — full payment pipeline: Intent → Webhook → On-Write → Transition; subscription model, statuses, `resolveSubscription()`, transition handlers, processor interface, product config, test processor
-- [docs/marketing-campaigns.md](docs/marketing-campaigns.md) — campaign CRUD routes, recurring campaigns, generator pipeline (newsletter), template-owned schemas, asset hosting, seed campaigns
+- [docs/marketing-campaigns.md](docs/marketing-campaigns.md) — campaign CRUD routes, recurring campaigns, generator pipeline (newsletter), newsletter-driven blog article (`content.article.enabled`), template-owned schemas, asset hosting, seed campaigns
 - [docs/consent.md](docs/consent.md) — marketing consent capture: canonical `consent.{legal,marketing}` user-doc shape, signup-form capture, account-page toggle, HMAC unsub link, SendGrid+Beehiiv webhook receivers, parent forwarder (`/marketing/webhook/forward`), migration script template
 - [docs/mcp.md](docs/mcp.md) — Model Context Protocol server: 19 tools, stdio + HTTP transports, OAuth, Claude Chat/Code configuration
 

package/README.md

@@ -412,6 +412,7 @@ Built-in marketing system with multi-provider support (SendGrid + Beehiiv + FCM
 - **Campaign CRUD** — `POST/GET/PUT/DELETE /marketing/campaign` with calendar-backed scheduling
 - **Recurring campaigns** — seasonal sales, newsletters with automatic sendAt advancement
 - **Newsletter generator** — AI-assembled newsletters from parent server content sources
+- **Newsletter-driven blog articles** — `content.article.enabled` expands the newsletter's lead section into a full blog post (via Ghostii → `admin/post`) and links to it with a "Read the full article" CTA
 - **Segment SSOT** — 22 segment definitions resolved to provider IDs at runtime
 - **UTM auto-tagging** — brand domain links tagged automatically in marketing + transactional emails
 - **Contact pruning** — monthly 2-stage re-engagement + deletion of inactive contacts

package/docs/admin-post-route.md

@@ -2,6 +2,8 @@
 
 The `POST /admin/post` route creates blog posts via GitHub's API. It handles image extraction, resize, upload, and body rewriting.
 
+**Consumers.** Besides direct admin/blogger HTTP calls, this route is the publish target for the **Ghostii article engine** (`src/manager/libraries/content/ghostii.js` → `publishArticle()`), which is used by two paths: the standalone daily `ghostii-auto-publisher.js` cron (off by default), and the newsletter generator's linked-article flow (`marketing.beehiiv.content.article.enabled`). Both POST `title`/`url`/`description`/`headerImageURL`/`body`/`author`/`categories`/`tags`/`postPath`/`githubUser`/`githubRepo` with a `backendManagerKey`. Note: `headerImageURL` MUST resolve to a `.jpg` (the downloader rejects non-`.jpg` headers); Ghostii's `unsplash` hero satisfies this. See [docs/marketing-campaigns.md](marketing-campaigns.md).
+
 ## Image Processing Flow
 
 1. Receives markdown body with external image URLs (e.g., `![alt](https://images.unsplash.com/...)`)

package/docs/ai-library.md

@@ -14,6 +14,23 @@ Return shape (same for all providers): `{ content, output, tokens, raw }`.
 
 API keys: `BACKEND_MANAGER_OPENAI_API_KEY`, `BACKEND_MANAGER_ANTHROPIC_API_KEY` (process.env or config).
 
+## Tools / web search (OpenAI)
+
+`options.tools` (and optional `options.toolChoice`) are passed through to the OpenAI Responses API verbatim. Opt-in — when omitted, no tools are sent and behavior is identical to a plain request. Use this to enable OpenAI's built-in **web search** so the model finds and cites real, currently-live URLs instead of hallucinating them:
+
+```js
+const r = await ai.request({
+  model: 'gpt-5.4',
+  response: 'json',
+  reasoning: { effort: 'medium' },
+  tools: [{ type: 'web_search' }],
+  prompt: { path: '.../research/system.md', settings },
+  message: { path: '.../research/user.md', settings },
+});
+```
+
+When tools are active, the response `output` array may contain tool-call items (e.g. `web_search_call`) alongside the `message`; the message-text extractor ignores non-message items, so `r.content` is unaffected. URL citations live in the returned `output` (message content) as `annotations` of type `url_citation`.
+
 ## `claude-code` provider — subscription billing
 
 The `claude-code` provider hits the same Claude Messages API as `anthropic`, but authenticates with a **Claude Code OAuth token** (`Authorization: Bearer ...` + `anthropic-beta: oauth-2025-04-20`) so usage bills the Claude Pro/Max subscription tied to the token rather than API credits.

package/docs/marketing-campaigns.md

@@ -100,6 +100,22 @@ Pipeline:
 4. **mjml-template.js** — Resolves the template by name from `templates/index.js`, calls `template.build({structure, imagePaths, theme, ...})` for the MJML, compiles to email-safe HTML via the `mjml` package. Brand-domain links get UTM-tagged via the existing `tagLinks()` utility.
 5. Mark used: `PUT {parentUrl}/newsletter/sources` per source
 
+> **Step 3 runs concurrently with the linked-article build** (see below) when `article.enabled` is on — both are slow AI calls, so they share one `Promise.all`. The article URL is stamped onto the lead section before steps 4/5 render.
+
+## Newsletter-driven blog article (`article.enabled`)
+
+When `marketing.beehiiv.content.article.enabled: true`, the newsletter generator expands its **lead section** (`structure.sections[0]`) into a full blog article and links to it from the newsletter.
+
+Flow (runs in parallel with SVG generation, between structure and render):
+1. `buildLinkedArticle()` builds a brief from the lead section's title + body, folded with the shared `tone` + `instructions`.
+2. **Ghostii** (`libraries/content/ghostii.js` → `writeArticle()`) expands it into a full article + hero image.
+3. `publishArticle()` POSTs to the `admin/post` route (commits markdown + images to the website repo). Public URL = `{brand.url}/blog/{slug}`.
+4. The URL is injected as `structure.sections[0].cta = { label: 'Read the full article', url }`. The MJML `sectionCard` and the markdown renderer both render `section.cta` automatically.
+
+**Failure is isolated** — if the article build throws, it resolves to `null`, no CTA is injected, and the newsletter ships normally. The newsletter never depends on the article succeeding.
+
+The published URL is surfaced on the return as `assets.articleUrl` and `meta.article`. Config block: `marketing.beehiiv.content.article = { enabled, author }` (`enabled` default `false`; `author` is the post author slug). Standalone article publishing (independent of the newsletter) still lives in the daily `ghostii-auto-publisher.js` cron, which now shares the same `libraries/content/ghostii.js` engine — see [docs/admin-post-route.md](admin-post-route.md). Standalone Ghostii is **disabled by default** (`ghostii[0].articles: 0`).
+
 ## Template-owned schemas
 
 Each template under `lib/templates/` owns its own content shape. Templates export:
@@ -199,7 +215,7 @@ marketing-campaigns/{newId}: {
 
 Templates add their own fields on top (e.g. classic adds `intro` + `sections`; field-report adds `tldr` + `dateline` + `dispatches`).
 
-**No CTAs in generated content.** The schema intentionally does NOT include section-level CTAs / outbound links. The AI cannot author URLs reliably — it has no browse access to your site and no real source URLs to reference, so any URL it produces is invented. Newsletters are self-contained reads; outbound links come from sponsorship blocks rendered by the template shell (driven by `marketing.beehiiv.content.sponsorships[]`), not from generated section bodies.
+**No AI-authored CTAs in generated content.** The schema intentionally does NOT include section-level CTAs / outbound links. The AI cannot author URLs reliably — it has no browse access to your site and no real source URLs to reference, so any URL it produces is invented. Newsletters are self-contained reads; outbound links come from sponsorship blocks rendered by the template shell (driven by `marketing.beehiiv.content.sponsorships[]`), not from generated section bodies. The **one exception** is the linked-article CTA: when `article.enabled` is on, `section.cta = { label, url }` is injected onto the lead section by code *after* the article is published (a real, verified URL) — never authored by the AI. Both `sectionCard` (MJML) and the markdown renderer render `section.cta` when present.
 
 **Beehiiv failure → fallback alert email.** When Beehiiv draft creation fails (e.g. `SEND_API_NOT_ENTERPRISE_PLAN` on the free plan), the generator sends an internal alert email via `sender: 'internal'` (resolves to `alerts@{brandDomain}`) to `brand.contact.email` with:
 - The failure reason
@@ -249,6 +265,10 @@ marketing: {
       instructions: '',                     // free-form AI instructions
       tone: 'professional',
       template: 'clean',                    // clean | editorial | field-report
+      article: {                            // expand the lead section into a linked blog post (Ghostii → admin/post)
+        enabled: false,
+        author: 'alex-raeburn',             // author slug for the linked article
+      },
       theme: { primaryColor, secondaryColor, accentColor, font },
       sponsorships: [ ... ],
     },
@@ -270,6 +290,8 @@ marketing: {
 | Newsletter MJML → HTML | `src/manager/libraries/email/generators/lib/mjml-template.js` |
 | Newsletter asset host (GitHub upload — PNGs + newsletter.html + newsletter.md + summary.md) | `src/manager/libraries/email/generators/lib/image-host.js` |
 | Newsletter markdown renderer (programmatic, no AI) | `src/manager/libraries/email/generators/lib/markdown-renderer.js` |
+| Ghostii article engine (writeArticle + publishArticle) | `src/manager/libraries/content/ghostii.js` |
+| Standalone Ghostii article cron (off by default) | `src/manager/events/cron/daily/ghostii-auto-publisher.js` |
 | Unified AI library | `src/manager/libraries/ai/index.js` (OpenAI + Anthropic via `Manager.AI(assistant).request({ provider, ... })`) |
 | Notification library | `src/manager/libraries/notification.js` |
 | SendGrid provider | `src/manager/libraries/email/providers/sendgrid.js` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.2.16",
+  "version": "5.2.17",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/base-command.js

@@ -130,6 +130,14 @@ class BaseCommand {
       }
     }
 
+    // Non-interactive environments (CI, agents, piped stdin) have no TTY, so inquirer
+    // can't read a keypress — prompting would error or hang. Skip the prompt entirely
+    // and auto-confirm the kill so unattended `mgr test` / `mgr emulator` runs proceed.
+    if (!process.stdin.isTTY) {
+      this.log(chalk.gray('  Non-interactive shell — auto-confirming port cleanup (Y).'));
+      return this.killBlockingProcesses(blockedPorts);
+    }
+
     // Auto-confirm (Y) after a few seconds of no input so unattended test/dev loops don't
     // hang. When the timeout fires the prompt is aborted via AbortSignal and we fall back to
     // the default (true). inquirer owns the cursor and can't live-update its own message, so
@@ -142,11 +150,20 @@ class BaseCommand {
         { signal: AbortSignal.timeout(AUTO_CONFIRM_SECONDS * 1000) },
       );
     } catch (error) {
-      // AbortPromptError (timeout reached) → take the default (true). Re-throw anything else.
-      if (error?.name !== 'AbortPromptError') {
-        throw error;
+      // Any prompt failure → fall back to the safe default (auto-confirm Y) instead of
+      // crashing. This covers:
+      //   - AbortPromptError: the 5s timeout fired (no input).
+      //   - ExitPromptError / force-close: stdin is present but closed/EOF'd (the
+      //     case under `mgr test`, agents, and other wrappers that pipe a non-readable
+      //     stdin). inquirer throws "User force closed the prompt with 0 null" here.
+      // Anything unexpected is logged but still defaults to Y so unattended runs proceed.
+      const name = error?.name || '';
+      const known = name === 'AbortPromptError' || name === 'ExitPromptError';
+      if (!known) {
+        this.log(chalk.gray(`  Prompt unavailable (${name || 'unknown'}) — auto-confirming (Y).`));
+      } else {
+        this.log(chalk.gray('  No input — auto-confirming (Y).'));
       }
-      this.log(chalk.gray('  No input — auto-confirming (Y).'));
       shouldKill = true;
     }
 
@@ -155,6 +172,15 @@ class BaseCommand {
       return false;
     }
 
+    return this.killBlockingProcesses(blockedPorts);
+  }
+
+  /**
+   * Kill every process on the given blocked ports, then wait for release.
+   * @param {object[]} blockedPorts - [{ name, port, processes: [{ pid }] }]
+   * @returns {Promise<boolean>} - true if all killed (or already dead), false on failure
+   */
+  async killBlockingProcesses(blockedPorts) {
     // Kill ALL processes on each blocked port
     for (const { name, port, processes } of blockedPorts) {
       for (const { pid } of processes) {

package/src/defaults/CLAUDE.md

@@ -23,10 +23,14 @@ npx mgr deploy            # deploy to Firebase
 npx mgr logs:read         # read Cloud Functions logs (also: logs:tail to stream)
 npx mgr firestore:get     # read a doc from Firestore (also: firestore:set / :query / :delete)
 npx mgr auth:get          # read an Auth user (also: auth:list / :delete / :set-claims)
+npx mgr install dev       # use LOCAL backend-manager source (to test framework edits)
+npx mgr install prod      # restore the published backend-manager from npm
 ```
 
 All `npx mgr <cmd>` aliases — `npx bm <cmd>`, `npx bem <cmd>`, `npx backend-manager <cmd>` work too.
 
+> Editing the BEM framework source while working here? Run `npx mgr install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/backend-manager`). Run `npx mgr install prod` to switch back.
+
 ## Where things live
 
 - `functions/index.js` — entry point. Must call `Manager.init(exports, { ... })` to register all built-in + custom endpoints.

package/src/manager/events/cron/daily/ghostii-auto-publisher.js

@@ -3,6 +3,8 @@ const powertools = require('node-powertools');
 const moment = require('moment');
 const JSON5 = require('json5');
 
+const { writeArticle, publishArticle } = require('../../../libraries/content/ghostii.js');
+
 const PROMPT = `
   Company: {brand.brand.name}: {brand.brand.description}
   Date: {date}
@@ -151,7 +153,11 @@ async function harvest(assistant, settings) {
     assistant.log('harvest(): Get final content', final);
 
     // Request to Ghostii
-    const article = await requestGhostii(settings, final).catch((e) => e);
+    const article = await writeArticle({
+      brand: settings.brand,
+      description: final,
+      links: settings.links,
+    }).catch((e) => e);
     if (article instanceof Error) {
       assistant.error('harvest(): Error requesting Ghostii', article);
       break;
@@ -161,7 +167,13 @@ async function harvest(assistant, settings) {
     assistant.log('harvest(): Article', article);
 
     // Upload post to blog
-    const uploadedPost = await uploadPost(assistant, settings, article).catch((e) => e);
+    const uploadedPost = await publishArticle(assistant, {
+      brand: settings.brand,
+      article,
+      id: postId++,
+      author: settings.author,
+      postPath: 'ghostii',
+    }).catch((e) => e);
     if (uploadedPost instanceof Error) {
       assistant.error('harvest(): Error uploading post to blog', uploadedPost);
       break;
@@ -197,51 +209,6 @@ function isURL(url) {
   }
 }
 
-function requestGhostii(settings, content) {
-  return fetch('https://api.ghostii.ai/write/article', {
-    method: 'post',
-    timeout: 90000,
-    tries: 1,
-    response: 'json',
-    body: {
-      backendManagerKey: process.env.BACKEND_MANAGER_KEY,
-      keywords: [''],
-      description: content,
-      insertLinks: true,
-      headerImageUrl: 'unsplash',
-      url: settings.brand.brand.url,
-      sectionQuantity: powertools.random(3, 6, { mode: 'gaussian' }),
-      feedUrl: `${settings.brand.brand.url}/feeds/posts.json`,
-      links: settings.links,
-    },
-  });
-}
-
-function uploadPost(assistant, settings, article) {
-  const apiUrl = `https://api.${(settings.brand.brand.url || '').replace(/^https?:\/\//, '')}`;
-  return fetch(`${apiUrl}/backend-manager/admin/post`, {
-    method: 'POST',
-    timeout: 90000,
-    tries: 1,
-    response: 'json',
-    body: {
-      backendManagerKey: process.env.BACKEND_MANAGER_KEY,
-      title: article.title,
-      url: article.title, // This is formatted on the bm_api endpoint
-      description: article.description,
-      headerImageURL: article.headerImageUrl,
-      body: article.body,
-      id: postId++,
-      author: settings.author,
-      categories: article.categories,
-      tags: article.keywords,
-      postPath: 'ghostii',
-      githubUser: settings.brand.github.user,
-      githubRepo: settings.brand.github.repo,
-    },
-  });
-}
-
 function extractBodyContent(text, contentType, url) {
   const parsed = tryParse(text);
 

package/src/manager/events/cron/daily/marketing-newsletter-generate.js

@@ -80,10 +80,12 @@ module.exports = async ({ Manager, assistant, libraries }) => {
     // Run the generator with imageHost forced to 'github' (production cron
     // path always uploads — that's what "production" means here) and the
     // campaignId pinned so all assets land in marketing-campaigns/{newId}/'s
-    // matching folder.
+    // matching folder. publishArticle: true so the linked blog post (when
+    // config.article.enabled is on) is actually committed to the website repo.
     const generated = await generators[generator].generate(Manager, assistant, settings, {
       campaignId: newId,
       imageHost: 'github',
+      publishArticle: true,
     });
 
     if (!generated) {

package/src/manager/libraries/ai/providers/openai.js

@@ -395,6 +395,11 @@ OpenAI.prototype.request = function (options) {
     // Reasons
     options.reasoning = options.reasoning || undefined;
 
+    // Tools (e.g. built-in web_search). Opt-in — when omitted, no tools are sent
+    // and behavior is identical to a plain request.
+    options.tools = options.tools || undefined;
+    options.toolChoice = options.toolChoice || undefined;
+
     // Format prompt
     //
     // Accepts two forms:
@@ -977,6 +982,18 @@ function makeRequest(mode, options, self, promptSegments, message, user, _log) {
       if (reasoning) {
         request.body.reasoning = reasoning;
       }
+
+      // Only include tools (e.g. web_search) if provided. When present, the
+      // response output may contain tool-call items (e.g. web_search_call)
+      // alongside the message — the message extractor below already ignores
+      // non-message items, so this is purely additive.
+      if (Array.isArray(options.tools) && options.tools.length) {
+        request.body.tools = options.tools;
+
+        if (options.toolChoice) {
+          request.body.tool_choice = options.toolChoice;
+        }
+      }
     }
 
     // Request

package/src/manager/libraries/content/ghostii.js

@@ -0,0 +1,100 @@
+/**
+ * Ghostii article engine — shared helpers for AI article generation + publishing.
+ *
+ * Ghostii (api.ghostii.ai) writes a full blog article (title, body, header image,
+ * categories, keywords) from a free-form description. We then publish it to the
+ * brand's website repo via the internal `admin/post` route (commits markdown +
+ * images to GitHub).
+ *
+ * Two consumers:
+ *   - events/cron/daily/ghostii-auto-publisher.js — standalone daily article job
+ *   - libraries/email/generators/newsletter.js    — newsletter-driven linked article
+ *
+ * Both call writeArticle() then publishArticle(). Kept here as the single source
+ * of truth for the Ghostii request shape and the admin/post payload.
+ */
+const fetch = require('wonderful-fetch');
+const powertools = require('node-powertools');
+
+/**
+ * Generate an article via the Ghostii API.
+ *
+ * @param {object} args
+ * @param {object} args.brand - Public brand config ({ brand: { url, ... }, github: { ... } })
+ * @param {string} args.description - The article brief / prompt content
+ * @param {string[]} [args.links] - Optional links to inject into the article body
+ * @returns {Promise<object>} { title, description, body, headerImageUrl, categories, keywords }
+ */
+function writeArticle({ brand, description, links }) {
+  return fetch('https://api.ghostii.ai/write/article', {
+    method: 'post',
+    timeout: 90000,
+    tries: 1,
+    response: 'json',
+    body: {
+      backendManagerKey: process.env.BACKEND_MANAGER_KEY,
+      keywords: [''],
+      description: description,
+      insertLinks: true,
+      headerImageUrl: 'unsplash',
+      url: brand.brand.url,
+      sectionQuantity: powertools.random(3, 6, { mode: 'gaussian' }),
+      feedUrl: `${brand.brand.url}/feeds/posts.json`,
+      links: links || [],
+    },
+  });
+}
+
+/**
+ * Publish a Ghostii article to the brand's website repo via the admin/post route.
+ *
+ * @param {object} assistant - BEM assistant instance
+ * @param {object} args
+ * @param {object} args.brand - Public brand config ({ brand: { url, ... }, github: { user, repo } })
+ * @param {object} args.article - The article from writeArticle()
+ * @param {number} args.id - Post ID (unix timestamp)
+ * @param {string} [args.author] - Author slug (admin/post picks a default if unset)
+ * @param {string} [args.postPath='ghostii'] - Sub-folder under _posts/{year}/
+ * @returns {Promise<object>} { post, url, slug, path } — `url` is the public blog URL
+ */
+async function publishArticle(assistant, { brand, article, id, author, postPath }) {
+  const baseUrl = (brand.brand.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+  const apiUrl = `https://api.${baseUrl}`;
+
+  const post = await fetch(`${apiUrl}/backend-manager/admin/post`, {
+    method: 'POST',
+    timeout: 90000,
+    tries: 1,
+    response: 'json',
+    body: {
+      backendManagerKey: process.env.BACKEND_MANAGER_KEY,
+      title: article.title,
+      url: article.title, // Slugified on the admin/post endpoint
+      description: article.description,
+      headerImageURL: article.headerImageUrl,
+      body: article.body,
+      id: id,
+      author: author,
+      categories: article.categories,
+      tags: article.keywords,
+      postPath: postPath || 'ghostii',
+      githubUser: brand.github.user,
+      githubRepo: brand.github.repo,
+    },
+  });
+
+  // admin/post returns the resolved `settings` (incl. the slugified `url` and repo `path`).
+  // The post template sets no permalink, so the public URL follows the Jekyll/UJM
+  // blog convention: {brand.url}/blog/{slug}.
+  const slug = post?.url || '';
+  const publicUrl = `${(brand.brand.url || '').replace(/\/$/, '')}/blog/${slug}`;
+
+  return {
+    post,
+    url: slug ? publicUrl : null,
+    slug,
+    path: post?.path || null,
+  };
+}
+
+module.exports = { writeArticle, publishArticle };

package/src/manager/libraries/email/generators/lib/markdown-renderer.js

@@ -165,6 +165,7 @@ function getBodySections(structure, template) {
       body: d.dispatch,
       dataPoints: d.dataPoints,
       image_prompt: d.image_prompt,
+      cta: d.cta,  // injected post-generation (e.g. linked-article "Read more")
     }));
   }
 
@@ -175,6 +176,7 @@ function getBodySections(structure, template) {
       title: s.title,
       body: s.body,
       image_prompt: s.image_prompt,
+      cta: s.cta,  // injected post-generation (e.g. linked-article "Read more")
     }));
   }
 
@@ -236,6 +238,13 @@ function renderSection(section, idx, imagePaths, template) {
     lines.push(section.body);
   }
 
+  // CTA (e.g. "Read the full article →") — injected by code post-generation,
+  // never authored by the AI. The MJML template renders section.cta via
+  // sectionCard; this is the markdown equivalent for the Beehiiv-paste view.
+  if (section.cta?.url && section.cta?.label) {
+    lines.push(`[${section.cta.label} →](${section.cta.url})`);
+  }
+
   return lines.join('\n\n');
 }
 

package/src/manager/libraries/email/generators/newsletter.js

@@ -26,6 +26,8 @@ const { generateSectionImage } = require('./lib/svg-illustrator.js');
 const { renderNewsletter } = require('./lib/mjml-template.js');
 const { renderMarkdown } = require('./lib/markdown-renderer.js');
 const { uploadAssets, RAW_BASE } = require('./lib/image-host.js');
+const { buildPublicConfig } = require('../../../routes/brand/get.js');
+const { writeArticle, publishArticle } = require('../../../libraries/content/ghostii.js');
 
 /**
  * Generate newsletter content from parent server sources.
@@ -45,6 +47,11 @@ const { uploadAssets, RAW_BASE } = require('./lib/image-host.js');
  * @param {object[]} [opts.sources] - Pre-fetched sources (bypasses parent server claim)
  * @param {boolean} [opts.skipClaim] - Don't call PUT to mark sources as used
  * @param {boolean} [opts.skipImages] - Skip SVG/PNG generation (use placeholders)
+ * @param {boolean} [opts.publishArticle] - When the linked-article build runs (config.article.enabled),
+ *                                          actually COMMIT the post to the website repo via admin/post.
+ *                                          When false (default), the article is still generated and its
+ *                                          URL computed + injected as the CTA, but nothing is committed.
+ *                                          Production cron passes true; the iteration test leaves it false.
  * @returns {object|null} Updated settings with content filled in, or null if unavailable
  */
 async function generate(Manager, assistant, settings, opts = {}) {
@@ -147,11 +154,17 @@ async function generate(Manager, assistant, settings, opts = {}) {
     || (sources.length === 1 ? sources[0].id : null)
     || generatePushId();
 
-  // 2. SVG illustrations (parallel) + upload PNGs first so we have URLs
-  //    available to embed in the HTML render below.
+  // 2. SVG illustrations + (optional) linked blog article — run CONCURRENTLY.
+  //    Both are slow AI calls. The image build produces the section image URLs;
+  //    the article build expands the lead section into a full blog post and
+  //    returns its public URL, which we inject as a "Read more" CTA before render.
   let imagePaths = [];
 
-  if (!opts.skipImages) {
+  const buildImages = async () => {
+    if (opts.skipImages) {
+      return;
+    }
+
     const images = await Promise.all(
       structure.sections.map((s) => generateSectionImage({
         imagePrompt: s.image_prompt,
@@ -191,6 +204,54 @@ async function generate(Manager, assistant, settings, opts = {}) {
 
     // Stash images on the return for callers that want to access raw buffers
     opts._lastImages = images;
+  };
+
+  // The linked-article build is gated by config.article.enabled and needs a lead
+  // section to expand. Wrapped so a failure here NEVER blocks the newsletter —
+  // it resolves to null and the CTA simply isn't injected.
+  //
+  // Two phases, independently controllable:
+  //   - GENERATE: always runs when article.enabled is on. Calls Ghostii to write
+  //     the article + hero image and computes the public URL it WOULD live at.
+  //   - PUBLISH:  commits the post to the website repo via admin/post. Only when
+  //     opts.publishArticle is true. The production cron passes true; the
+  //     iteration test leaves it false (so it exercises generation without
+  //     committing a real post) unless NEWSLETTER_CREATE_ARTICLE=1 is set.
+  //
+  // The CTA URL is derived from the article title (same slugify admin/post uses),
+  // so the newsletter links correctly even in generate-only mode.
+  const wantArticle = !!config.article?.enabled
+    && Array.isArray(structure.sections)
+    && structure.sections.length > 0;
+
+  const buildArticle = async () => {
+    if (!wantArticle) {
+      return null;
+    }
+
+    return buildLinkedArticle({
+      Manager,
+      assistant,
+      brand,
+      config,
+      structure,
+      publish: !!opts.publishArticle,
+    }).catch((e) => {
+      assistant.error(`Newsletter generator: linked article failed — ${e.message}`);
+      return null;
+    });
+  };
+
+  const [, articleResult] = await Promise.all([buildImages(), buildArticle()]);
+
+  // Inject the "Read the full article" CTA onto the lead section BEFORE render.
+  // sectionCard (MJML) renders section.cta = { label, url } automatically; the
+  // markdown renderer emits it too. The URL is the post's public blog URL —
+  // present whether the article was actually published or only generated
+  // (derived from the title slug), so the newsletter links correctly either way.
+  if (articleResult?.url) {
+    structure.sections[0].cta = { label: 'Read the full article', url: articleResult.url };
+    assistant.log(`Newsletter generator: linked article ${articleResult.published ? 'published' : 'generated (not published)'} — ${articleResult.url}`);
   }
 
   // 3. MJML → HTML
@@ -342,6 +403,11 @@ async function generate(Manager, assistant, settings, opts = {}) {
       })),
     },
     totals: aggregateTotals(filterMeta, structure._meta, opts._lastImages),
+    // Linked blog article (when config.article.enabled is on). null if disabled or failed.
+    // `published` is false when the article was generated but not committed (e.g. test mode).
+    article: articleResult
+      ? { url: articleResult.url, slug: articleResult.slug, path: articleResult.path, published: !!articleResult.published }
+      : null,
   };
 
   // Public asset URLs — stamped onto the generated campaign doc by the cron
@@ -358,6 +424,7 @@ async function generate(Manager, assistant, settings, opts = {}) {
     summaryUrl,
     imageUrls: imagePaths,
     beehiivPostId,
+    articleUrl: articleResult?.url || null,  // linked blog post (config.article.enabled), null otherwise
     tags: Array.isArray(structure.tags) ? structure.tags : [],
   } : null;
 
@@ -375,9 +442,87 @@ async function generate(Manager, assistant, settings, opts = {}) {
     images: opts._lastImages || [],  // image buffers for the iteration test to persist locally
     assets,               // GitHub asset URLs (folder, html, md, summary, images) — null in local mode
     meta,                 // per-step provider/model/cost/timing telemetry
+    article: articleResult || null,  // full linked-article result { url, slug, path, published, article: {title, body, headerImageUrl, ...} } — null when disabled/failed
   };
 }
 
+/**
+ * Expand the newsletter's lead section into a full blog article via Ghostii and
+ * (optionally) publish it to the brand's website repo. Returns the post's public
+ * URL so the newsletter can link to it via a "Read the full article" CTA.
+ *
+ * The lead section (structure.sections[0]) is the same topic the newsletter
+ * leads with, so the resulting article is the long-form version.
+ *
+ * Two phases:
+ *   - GENERATE (always): Ghostii writes the article + hero image. We then compute
+ *     the public URL the post WOULD live at, using the same title→slug rule
+ *     admin/post applies. This URL is valid for the CTA whether or not we publish.
+ *   - PUBLISH (only when `publish`): commit the post to the website repo via
+ *     admin/post (GitHub). When `publish` is false, nothing is committed.
+ *
+ * Gated upstream by config.article.enabled. Any failure is caught by the caller
+ * and the CTA is simply omitted — the newsletter never depends on this.
+ *
+ * @param {object} args
+ * @param {object} args.Manager
+ * @param {object} args.assistant
+ * @param {object} args.brand - { id, name, url, ... }
+ * @param {object} args.config - marketing.beehiiv.content (tone, instructions, article.author)
+ * @param {object} args.structure - newsletter structure (sections[0] is the lead)
+ * @param {boolean} [args.publish] - Commit the post to GitHub via admin/post. Default false.
+ * @returns {Promise<{url, slug, path, published}|null>}
+ */
+async function buildLinkedArticle({ Manager, assistant, brand, config, structure, publish }) {
+  const lead = structure.sections[0] || {};
+  const publicConfig = buildPublicConfig(Manager.config);
+
+  // Build the article brief from the lead section, folded with the shared
+  // editorial steer (tone + instructions) so the blog post matches the
+  // newsletter's voice. Ghostii expands this into a full article + hero image.
+  const briefLines = [
+    `Company: ${brand?.name || ''}: ${brand?.description || ''}`,
+    config?.tone ? `Tone: ${config.tone}` : '',
+    config?.instructions ? `Instructions: ${config.instructions}` : '',
+    '',
+    `Write a full blog article expanding on this topic:`,
+    `Title: ${lead.title || ''}`,
+    `Summary: ${lead.body || ''}`,
+  ].filter(Boolean).join('\n');
+
+  assistant.log(`Newsletter generator: building linked article for "${lead.title}"`);
+
+  // Phase 1 — GENERATE (always)
+  const article = await writeArticle({
+    brand: publicConfig,
+    description: briefLines,
+  });
+
+  // Compute the public URL the post WOULD live at. admin/post slugifies the
+  // title (after stripping a `blog/` prefix that titles never have), so we
+  // mirror that here to derive the same slug without needing to publish.
+  const slug = Manager.Utilities().slugify(article.title || '');
+  const url = slug
+    ? `${(publicConfig.brand?.url || '').replace(/\/$/, '')}/blog/${slug}`
+    : null;
+
+  // Phase 2 — PUBLISH (gated). Commit to the website repo only when asked.
+  if (!publish) {
+    assistant.log(`Newsletter generator: article generated but NOT published (publish=false) — would live at ${url}`);
+    return { url, slug, path: null, published: false, article };
+  }
+
+  const result = await publishArticle(assistant, {
+    brand: publicConfig,
+    article,
+    id: Math.round(Date.now() / 1000),
+    author: config?.article?.author,
+    postPath: 'ghostii',
+  });
+
+  return { url: result.url || url, slug: result.slug || slug, path: result.path, published: true, article };
+}
+
 /**
  * Send an internal alert email when Beehiiv draft creation fails so the
  * brand team knows there's a ready newsletter waiting for manual upload.

package/src/manager/routes/user/signup/post.js

@@ -1,4 +1,5 @@
 const moment = require('moment');
+const _ = require('lodash');
 const { inferContact } = require('../../../libraries/infer-contact.js');
 const { validate: validateEmail, isDisposable } = require('../../../libraries/email/validation.js');
 
@@ -61,7 +62,14 @@ module.exports = async ({ assistant, user, settings, libraries }) => {
   // 4. Gather all data, then write once
   const email = user.auth.email;
   const inferred = await inferUserContact(assistant, email);
-  const userRecord = buildUserRecord(assistant, settings, inferred, authUser.metadata.creationTime, userDoc);
+  const userRecord = buildUserRecord(assistant, {
+    settings,
+    inferred,
+    uid,
+    email,
+    creationTime: authUser.metadata.creationTime,
+    existingDoc: userDoc,
+  });
 
   assistant.log(`signup(): Writing user record for ${uid}`, userRecord);
 
@@ -111,16 +119,43 @@ async function pollForUserDoc(assistant, uid) {
 }
 
 /**
- * Build the full user record: client details, attribution, and inferred contact
+ * Build the complete user record to write at signup completion.
+ *
+ * Returns the WHOLE merged document (written without {merge}), layered deepest-first:
+ *   1. Manager.User() full schema shape — guarantees every leaf exists (so a doc created by a
+ *      partial path, e.g. onCreate never firing, still ends up schema-complete).
+ *   2. the existing doc — real values win over the schema defaults, so we never clobber the
+ *      user's api keys, subscription, roles, affiliate.code, or any custom/non-standard fields.
+ *   3. the signup data — attribution / activity / consent / flags / personal we own at signup
+ *      land on top.
+ *
+ * Why a full deep-merge instead of `.set(partial, {merge:true})`: Firestore's merge REPLACES a
+ * map field rather than deep-merging it, so writing a partial `attribution` flattened onCreate's
+ * full attribution object and the OMEGA migration had to re-add every leaf on every signup.
+ * Deep-merging in JS and writing the whole doc avoids that entirely.
  */
-function buildUserRecord(assistant, settings, inferred, creationTime, existingDoc) {
+function buildUserRecord(assistant, { settings, inferred, uid, email, creationTime, existingDoc }) {
   const Manager = assistant.Manager;
-  const attribution = settings.attribution;
 
-  const record = {
-    flags: {
-      signupProcessed: true,
-    },
+  // Inferred name/company (from AI/regex on the email) — only set when present.
+  const personal = {};
+  if (inferred?.firstName || inferred?.lastName) {
+    personal.name = {
+      ...(inferred.firstName ? { first: inferred.firstName } : {}),
+      ...(inferred.lastName ? { last: inferred.lastName } : {}),
+    };
+  }
+  if (inferred?.company) {
+    personal.company = { name: inferred.company };
+  }
+
+  // Layer 1: full schema shape (every leaf present with defaults).
+  const schemaShape = Manager.User({ auth: { uid, email } }).properties;
+
+  // Layer 3: the data signup owns.
+  const signupData = {
+    auth: { uid, email },
+    flags: { signupProcessed: true },
     activity: {
       ...settings.context,
       geolocation: {
@@ -132,37 +167,24 @@ function buildUserRecord(assistant, settings, inferred, creationTime, existingDo
         ...(settings.context?.client || {}),
       },
     },
-    attribution: attribution || {},
+    attribution: settings.attribution || {},
     consent: buildConsentRecord(assistant, settings.consent, creationTime, existingDoc?.consent),
     metadata: Manager.Metadata().set({ tag: 'user/signup' }),
+    ...(Object.keys(personal).length ? { personal } : {}),
   };
 
-  // Stamp metadata.created from Firebase Auth's creationTime so it matches Auth's canonical
-  // value. Normally onCreate sets this, but if onCreate didn't fire this merge write is the
-  // doc's first creation — without this the doc lands with no created date and the OMEGA
-  // migration has to backfill it. Idempotent: when onCreate already wrote it, this matches.
+  // metadata.created from Auth's creationTime (canonical), matching onCreate + the migration SSOT.
   if (creationTime) {
     const createdDate = new Date(creationTime);
-    record.metadata.created = {
+    signupData.metadata.created = {
       timestamp: createdDate.toISOString(),
       timestampUNIX: Math.round(createdDate.getTime() / 1000),
     };
   }
 
-  // Add inferred name/company if available
-  if (inferred) {
-    record.personal = {
-      ...(inferred.firstName || inferred.lastName ? {
-        name: {
-          ...(inferred.firstName ? { first: inferred.firstName } : {}),
-          ...(inferred.lastName ? { last: inferred.lastName } : {}),
-        },
-      } : {}),
-      ...(inferred.company ? { company: { name: inferred.company } } : {}),
-    };
-  }
-
-  return record;
+  // Deep-merge: schema (base) ← existing doc (real values win) ← signup data (owned fields win).
+  // _.merge mutates its first arg, so start from a fresh object.
+  return _.merge({}, schemaShape, existingDoc || {}, signupData);
 }
 
 /**
@@ -364,6 +386,7 @@ function sendWelcomeEmails(assistant, uid, firstName) {
   }
 
   sendWelcomeEmail(assistant, uid, firstName).catch(e => assistant.error('signup(): sendWelcomeEmail failed:', e));
+  sendDiscountNudgeEmail(assistant, uid, firstName).catch(e => assistant.error('signup(): sendDiscountNudgeEmail failed:', e));
   sendCheckupEmail(assistant, uid, firstName).catch(e => assistant.error('signup(): sendCheckupEmail failed:', e));
   sendFeedbackEmail(assistant, uid).catch(e => assistant.error('signup(): sendFeedbackEmail failed:', e));
 }
@@ -411,6 +434,68 @@ Thank you for choosing **${Manager.config.brand.name}**. Here's to new beginning
     });
 }
 
+/**
+ * Send discount-nudge email (24 hours after signup)
+ *
+ * A warm, personal check-in that offers a discount code in exchange for a reply.
+ * Scheduled fire-and-forget via sendAt (same pattern as checkup/feedback) — there is
+ * intentionally no premium check at send time, so a user who upgrades within 24h may
+ * still receive it. The copy is deliberately worded as a friendly thank-you (not "you
+ * haven't upgraded") so it reads fine regardless of the recipient's current plan.
+ *
+ * The reply itself is the goal: replies are a strong positive sender-reputation signal,
+ * and a real human check-in lands in the Primary tab rather than Promotions. Inbound
+ * reply handling (auto-issuing the code) is out of scope here — replies are handled
+ * separately.
+ *
+ * Subject is personalized with the recipient's first name when available, and uses
+ * intrigue framing ("something for you 🎁") rather than spam-trigger words ("free",
+ * "claim", "bonus") to protect deliverability.
+ */
+function sendDiscountNudgeEmail(assistant, uid, firstName) {
+  const Manager = assistant.Manager;
+  const mailer = Manager.Email(assistant);
+  const greeting = firstName ? `Hey ${firstName}` : 'Hey there';
+  const subject = firstName
+    ? `${firstName}, I've got something for you 🎁`
+    : `I've got something for you 🎁`;
+
+  return mailer.send({
+    to: uid,
+    sender: 'hello',
+    categories: ['engagement/discount-nudge'],
+    subject: subject,
+    template: 'default',
+    copy: false,
+    sendAt: moment().add(24, 'hours').unix(),
+    data: {
+      email: {
+        preview: `Just checking in from ${Manager.config.brand.name} — and I've got a little thank-you for you.`,
+      },
+      body: {
+        title: `How's it going?`,
+        message: `${greeting},
+
+It's Ian, the founder of **${Manager.config.brand.name}**.
+
+As a thank-you for giving us a try, I'd love to send you a code for a **premium upgrade**. **Just reply to this email** and I'll get one over to you.
+
+I read every reply, so if you have any questions, feedback, or there's anything I can help with, this is the place. Looking forward to hearing from you!`,
+      },
+      signoff: {
+        type: 'personal',
+        name: 'Ian Wiedenman, CEO',
+        url: `https://ianwiedenman.com?utm_source=discount-nudge-email&utm_medium=email&utm_campaign=${Manager.config.brand.id}`,
+        urlText: '@ianwieds',
+      },
+    },
+  })
+    .then((result) => {
+      assistant.log('sendDiscountNudgeEmail(): Success', result.status);
+      return result;
+    });
+}
+
 /**
  * Send checkup email (7 days after signup)
  */

package/src/test/test-accounts.js

@@ -205,6 +205,19 @@ const STATIC_ACCOUNTS = {
       subscription: { product: { id: 'basic' }, status: 'active' },
     },
   },
+  // Used to verify buildUserRecord's layered deep-merge: the test seeds this account's doc with
+  // real values (api keys, paid subscription, admin role, a custom non-schema field) + a partial
+  // attribution, fires /user/signup, and asserts the merge PRESERVES those real/custom values
+  // while still filling every schema leaf and applying the signup data on top.
+  'signup-merge': {
+    id: 'signup-merge',
+    uid: '_test-signup-merge',
+    email: '_test.signup-merge@{domain}',
+    properties: {
+      roles: {},
+      subscription: { product: { id: 'basic' }, status: 'active' },
+    },
+  },
 };
 
 /**

package/templates/backend-manager-config.json

@@ -153,6 +153,10 @@
         instructions: '',  // free-form text passed to the AI ("focus on X", "avoid Y", brand voice notes)
         tone: 'professional',  // 'professional', 'casual', 'actionable', 'witty', etc. — passed to AI prompt
         template: 'clean',   // 'clean' | 'editorial' | 'field-report' — layout template (each owns its own content shape and aesthetic)
+        article: {
+          enabled: false,  // when true, the newsletter's lead section is expanded into a full blog post via Ghostii, published to the website repo, and linked from the newsletter with a "Read the full article" CTA
+          author: null,  // author slug for the linked article (Ghostii/admin-post picks a default if unset)
+        },
         theme: {
           primaryColor: '#5B5BFF',   // accent color: buttons, links, brand text
           secondaryColor: '#1E1E2A', // body text color
@@ -192,9 +196,12 @@
     appId: '1:123:web:456',
     measurementId: 'G-0123456789',
   },
+  // Standalone Ghostii article publisher (daily cron). OPT-IN: disabled by
+  // default (articles: 0). Set articles >= 1 to auto-publish independent blog
+  // posts. For newsletter-linked articles, use marketing.beehiiv.content.article.enabled instead.
   ghostii: [
     {
-      articles: 1,
+      articles: 0,
       sources: [
         '$app',
         // Add more sources here
@@ -204,7 +211,7 @@
       ],
       prompt: '',
       chance: 1.0,
-      author: 'alex-raeburn',
+      author: null,
       // app: 'other-app-id',              // Optional: target a different app
       // appUrl: 'https://api.otherapp.com', // Required if app is set (fetches /backend-manager/app)
     }

package/test/marketing/newsletter-generate.js

@@ -44,8 +44,16 @@
  *   NEWSLETTER_PEEK=1                  Fetch + list ready sources, do not claim, exit.
  *   NEWSLETTER_SOURCE_ID=<id>          Generate from one specific source WITHOUT claiming it.
  *   NEWSLETTER_LIMIT=10                Sources per category for PEEK (default 10).
+ *   NEWSLETTER_CLAIM=1               CLAIM the fetched sources (claimFor=brandId), consuming them so the
+ *                                       real newsletter won't reuse them. OFF by default — the test fetches
+ *                                       without claiming so runs are repeatable and non-destructive.
  *   NEWSLETTER_RELEASE=1               Reset locally-tracked claimed sources back to 'ready'.
  *   NEWSLETTER_NO_IMAGES=1             Skip SVG/PNG generation (fast iteration on copy only).
+ *   NEWSLETTER_CREATE_ARTICLE=1       PUBLISH the linked blog article to the website repo (Ghostii → admin/post → GitHub).
+ *                                       The article is always GENERATED when the brand's
+ *                                       marketing.beehiiv.content.article.enabled is on (exercises the Ghostii write +
+ *                                       URL/CTA path); this flag only controls whether it's actually committed.
+ *                                       OFF by default — a newsletter test run never commits a real post.
  *   NEWSLETTER_PROVIDER_STRUCTURE=X    Override structure provider (openai|anthropic).
  *   NEWSLETTER_PROVIDER_SVG=X          Override SVG provider (openai|anthropic).
  *   NEWSLETTER_CAMPAIGN_ID=<id>        Override the auto-generated campaign ID (folder name in newsletter-assets).
@@ -345,13 +353,20 @@ module.exports = {
       return;
     }
 
-    // --- Fetch sources (real claim) ---
+    // --- Fetch sources ---
+    // By DEFAULT the test does NOT claim sources — it fetches them without
+    // claimFor, so they stay 'ready' and available for the real newsletter.
+    // This keeps test runs repeatable and non-destructive (a test should never
+    // silently consume production resources). Set NEWSLETTER_CLAIM=1 to exercise
+    // the real claim/consume path (then use NEWSLETTER_RELEASE=1 to put them back).
+    const claim = !!env.NEWSLETTER_CLAIM;
     const sources = await fetchSourcesForRun({
       parentUrl,
       newsletterConfig,
       brandId: config.brand?.id,
       sourceId: env.NEWSLETTER_SOURCE_ID,
       key: env.BACKEND_MANAGER_KEY,
+      claim,
     });
 
     // Environmental precondition: the parent server must have ready sources in
@@ -361,8 +376,10 @@ module.exports = {
       return skip('No ready newsletter sources available on parent server (environmental)');
     }
 
-    // Track claimed IDs for later --release-all
-    appendClaimed(claimedFile, sources.map((s) => s.id));
+    // Track claimed IDs for later --release-all (only when we actually claimed)
+    if (claim && !env.NEWSLETTER_SOURCE_ID) {
+      appendClaimed(claimedFile, sources.map((s) => s.id));
+    }
 
     // Force `beehiiv.enabled: true` and inject the per-run newsletter config
     // overrides onto Manager.config. The iteration test IS the explicit trigger
@@ -382,12 +399,18 @@ module.exports = {
     // --- Run the production generator with the local-persist image hook ---
     const generator = require('../../src/manager/libraries/email/generators/newsletter.js');
 
-    // EXTENDED mode is a MIRROR of the production cron — no escape hatches.
+    // EXTENDED mode mirrors the production cron's newsletter side effects:
     // GH upload always happens (PNGs + newsletter.html), Beehiiv draft upload
     // always happens (governed inside newsletter.js by beehiiv.enabled, which
     // we force true above). If you don't want the side effects, run fixture
     // mode instead.
     //
+    // The ONE deliberate exception is PUBLISHING the linked blog article: the
+    // article is still generated (so the test exercises the Ghostii write + CTA
+    // path), but it's NOT committed to the website repo unless you opt in with
+    // NEWSLETTER_CREATE_ARTICLE=1 (publishArticle below). Committing a real post
+    // is out of scope for a routine newsletter test.
+    //
     // persistImage is a side-effect callback that writes PNG+SVG to runDir for
     // local preview / debug. Its return value is ignored when imageHost: 'github'
     // because the generator uses the uploaded CDN URLs in the rendered HTML.
@@ -416,6 +439,11 @@ module.exports = {
         sources,
         skipClaim: true, // We manage the claim/release lifecycle ourselves
         skipImages: !!env.NEWSLETTER_NO_IMAGES,
+        // The article is GENERATED whenever the brand's config.article.enabled is on
+        // (exercises the Ghostii write + URL/CTA path), but only PUBLISHED to the
+        // website repo when you opt in with NEWSLETTER_CREATE_ARTICLE=1. Default
+        // test run generates but does not commit a real post.
+        publishArticle: !!env.NEWSLETTER_CREATE_ARTICLE,
         // Local disk persistence runs unconditionally (for preview/debug)
         persistImage,
         // EXTENDED always uploads to GitHub — mirrors production cron exactly
@@ -444,10 +472,37 @@ module.exports = {
       assets: result.assets || null,
     }, null, 2));
 
+    // Linked blog article (when content.article.enabled). Save the full Ghostii
+    // output + the computed URL so you can review what would be published — both
+    // the raw JSON and a readable markdown view of the article body.
+    if (result.article?.article) {
+      const a = result.article.article;
+      jetpack.write(path.join(runDir, 'article.json'), JSON.stringify(result.article, null, 2));
+      jetpack.write(path.join(runDir, 'article.md'), [
+        `# ${a.title || ''}`,
+        '',
+        `> ${a.description || ''}`,
+        '',
+        `**URL:** ${result.article.url || '(none)'}`,
+        `**Published:** ${result.article.published ? 'yes' : 'no (generate-only)'}`,
+        a.headerImageUrl ? `**Header image:** ${a.headerImageUrl}` : '',
+        a.categories?.length ? `**Categories:** ${a.categories.join(', ')}` : '',
+        a.keywords?.length ? `**Keywords:** ${a.keywords.join(', ')}` : '',
+        '',
+        '---',
+        '',
+        a.body || '',
+      ].filter(line => line !== undefined).join('\n'));
+    }
+
     console.log(`\nNewsletter preview written: ${previewPath}`);
     console.log(`Subject:   ${result.subject}`);
     console.log(`Preheader: ${result.preheader}`);
     console.log(`Sections:  ${result.structure.sections.length}`);
+    if (result.article?.article) {
+      console.log(`Article:   "${result.article.article.title}" → ${result.article.url} (${result.article.published ? 'published' : 'generate-only'})`);
+      console.log(`           ${path.join(runDir, 'article.md')}`);
+    }
     if (result.meta?.totals) {
       const t = result.meta.totals;
       console.log(`\nRun summary:`);
@@ -606,13 +661,14 @@ async function peekSources({ parentUrl, categories, limit, key }) {
 /**
  * Fetch sources for an actual generation run. Either:
  *   - A specific source by id — preview only, NO claim (iterate repeatedly on the same source)
- *   - Or N per category (claims them atomically for the brand)
+ *   - Or N per category. Fetches WITHOUT claiming by default (claim=false), so runs are
+ *     repeatable; pass claim=true (NEWSLETTER_CLAIM=1) to atomically claim/consume them.
  *
  * When NEWSLETTER_SOURCE_ID is set, we look the source up in any status
  * (ready, claimed, used) so you can keep iterating on it across runs without
  * the parent server's claim mechanism marking it consumed.
  */
-async function fetchSourcesForRun({ parentUrl, newsletterConfig, brandId, sourceId, key }) {
+async function fetchSourcesForRun({ parentUrl, newsletterConfig, brandId, sourceId, key, claim = false }) {
   if (sourceId) {
     // Peek across ALL ready sources (no claim). Search broadly first, then
     // fall back to any-status if needed. We never call claimFor with sourceId
@@ -657,11 +713,18 @@ async function fetchSourcesForRun({ parentUrl, newsletterConfig, brandId, source
 
   const all = [];
   for (const category of categories) {
+    // claimFor is what tells the parent server to mark sources consumed. Omit it
+    // (claim=false) to fetch the same sources without claiming them.
+    const query = { category, limit: 3, backendManagerKey: key };
+    if (claim) {
+      query.claimFor = brandId;
+    }
+
     const data = await fetch(`${parentUrl}/newsletter-sources`, {
       method: 'get',
       response: 'json',
       timeout: 15000,
-      query: { category, limit: 3, claimFor: brandId, backendManagerKey: key },
+      query,
     });
     all.push(...(data.sources || []));
   }

package/test/routes/user/signup.js

@@ -436,6 +436,85 @@ module.exports = {
       },
     },
 
+    // --- buildUserRecord layered deep-merge tests ---
+    // The signup write must: (a) fill every schema leaf so the doc is complete (no migration
+    // churn), (b) PRESERVE existing real values (api keys, subscription, roles, affiliate.code,
+    // custom non-schema fields), and (c) apply the signup data on top — without Firestore's
+    // map-replace wiping nested data. These tests seed adversarial existing state and verify.
+    {
+      name: 'merge-preserves-existing-and-fills-schema',
+      async run({ http, firestore, assert, accounts }) {
+        const uid = accounts['signup-merge'].uid;
+
+        // Seed real/custom state that the signup write must NOT clobber, plus a deliberately
+        // PARTIAL attribution (only affiliate.code) to prove leaves get filled, not replaced-away.
+        await firestore.set(`users/${uid}`, {
+          api: { clientId: 'REAL-CLIENT-ID', privateKey: 'REAL-PRIVATE-KEY' },
+          affiliate: { code: 'REALAFFILIATECODE', referrals: [{ uid: 'someone' }] },
+          subscription: { product: { id: 'pro', name: 'Pro' }, status: 'active' },
+          roles: { admin: true, betaTester: false, developer: false },
+          attribution: { affiliate: { code: 'PARTIALONLY' } },
+          myCustomIntegration: { slackWebhook: 'https://hooks.slack.com/services/XXX' },
+        }, { merge: true });
+
+        const signupResponse = await http.as('signup-merge').post('user/signup', {
+          consent: { legal: { granted: true, text: 'I agree.' }, marketing: { granted: true, text: 'Updates please.' } },
+          attribution: { utm: { tags: { utm_source: 'newsletter' } } },
+        });
+        assert.isSuccess(signupResponse, `Signup should succeed: ${JSON.stringify(signupResponse, null, 2)}`);
+
+        const doc = await firestore.get(`users/${uid}`);
+
+        // (b) Existing real values must survive untouched — NOT regenerated/reset by the schema layer.
+        assert.equal(doc?.api?.clientId, 'REAL-CLIENT-ID', 'api.clientId must be preserved (not regenerated)');
+        assert.equal(doc?.api?.privateKey, 'REAL-PRIVATE-KEY', 'api.privateKey must be preserved (not regenerated)');
+        assert.equal(doc?.affiliate?.code, 'REALAFFILIATECODE', 'affiliate.code must be preserved (not regenerated)');
+        assert.equal(doc?.subscription?.product?.id, 'pro', 'subscription must be preserved (not reset to basic)');
+        assert.equal(doc?.roles?.admin, true, 'roles.admin must be preserved (not reset to false)');
+
+        // (b) Custom non-schema field must survive the merge.
+        assert.equal(doc?.myCustomIntegration?.slackWebhook, 'https://hooks.slack.com/services/XXX', 'custom non-schema field must survive');
+
+        // (a) Every attribution leaf must be present (the bug: partial write flattened the map).
+        assert.hasProperty(doc, 'attribution.affiliate.code', 'attribution.affiliate.code must exist');
+        assert.hasProperty(doc, 'attribution.affiliate.url', 'attribution.affiliate.url must exist (filled)');
+        assert.hasProperty(doc, 'attribution.affiliate.page', 'attribution.affiliate.page must exist (filled)');
+        assert.hasProperty(doc, 'attribution.affiliate.timestamp', 'attribution.affiliate.timestamp must exist (filled)');
+        assert.hasProperty(doc, 'attribution.utm.url', 'attribution.utm.url must exist (filled)');
+        assert.hasProperty(doc, 'attribution.utm.page', 'attribution.utm.page must exist (filled)');
+        assert.hasProperty(doc, 'attribution.utm.timestamp', 'attribution.utm.timestamp must exist (filled)');
+        // filled leaves should be null, not undefined/missing
+        assert.equal(doc?.attribution?.affiliate?.url, null, 'unset attribution leaf should be null');
+
+        // (c) Signup data applied on top.
+        assert.equal(doc?.attribution?.affiliate?.code, 'PARTIALONLY', 'pre-existing affiliate.code preserved (signup did not send one)');
+        assert.equal(doc?.attribution?.utm?.tags?.utm_source, 'newsletter', 'signup utm tag applied');
+        assert.equal(doc?.flags?.signupProcessed, true, 'flags.signupProcessed set true');
+        assert.equal(doc?.consent?.legal?.status, 'granted', 'consent applied');
+      },
+    },
+    {
+      name: 'merge-fills-all-leaves-on-schema-complete-doc',
+      async run({ http, firestore, assert, accounts }) {
+        // Sanity: after signup, the doc must contain the full set of top-level schema sections,
+        // so a subsequent migration finds NOTHING to backfill. Reuses the signup-merge account
+        // (already processed above → re-fire is rejected, but the doc from the prior test is the
+        // artifact we assert against; this test just validates that doc's completeness).
+        const uid = accounts['signup-merge'].uid;
+        const doc = await firestore.get(`users/${uid}`);
+
+        for (const section of ['auth', 'roles', 'flags', 'affiliate', 'metadata', 'activity', 'api', 'personal', 'attribution', 'consent', 'subscription']) {
+          assert.hasProperty(doc, section, `doc must have top-level '${section}' section after signup`);
+        }
+        // Nested completeness spot-checks across the sections signup writes.
+        assert.hasProperty(doc, 'activity.geolocation.ip', 'activity.geolocation.ip must exist');
+        assert.hasProperty(doc, 'activity.client.userAgent', 'activity.client.userAgent must exist');
+        assert.hasProperty(doc, 'personal.name.first', 'personal.name.first must exist');
+        assert.hasProperty(doc, 'consent.marketing.revokedAt.source', 'consent.marketing.revokedAt.source must exist');
+        assert.hasProperty(doc, 'metadata.created.timestampUNIX', 'metadata.created.timestampUNIX must exist');
+      },
+    },
+
     // --- Auth rejection test (at end per convention) ---
     {
       name: 'unauthenticated-rejected',