Centralize agent preamble into a single build-time injection

[claude]

Requested by Jake Mor · Slack thread

Before / After

Before: the ~110-line agent-only context block (Superwall subscription-infrastructure preamble, emitted only into the per-page .md / llms.txt agent output — humans never see it) was copy-pasted into 585 of 594 docs pages.

After: it lives once in AGENT_VISIBILITY_MARKDOWN and is injected at build time. Doc pages carry zero copies of it. The agent/LLM output is unchanged.

How

• src/lib/visibility.ts — getAgentVisibilityMarkdownForPage() now returns the canonical AGENT_VISIBILITY_MARKDOWN for every docs page (it was previously gated to the 6 SDK changelog paths). Removed the now-dead sdkChangelogPaths set and the extractLeadingAgentVisibilityMarkdown() helper.
• src/lib/source.ts — getPageMarkdownText() injects the preamble from the constant ahead of the page title, description, and body. The old "extract the inline block and re-hoist it" path is gone, since no page inlines the block anymore.
• content/docs/** — stripped the inline <Visibility for="agents"> preamble block from all 585 pages that carried it (matched on the canonical title line, so unrelated Visibility usages and the em-dash outlier were handled correctly). The 9 pages that never had the inline block, and content/shared/, were left untouched.
• src/lib/visibility.test.ts — updated to assert universal injection; dropped the test for the removed extract helper.

Output-equivalence verification

I captured the generated agent markdown (getPageMarkdownText) for all 594 pages before and after the change and diffed them:

• 591 pages: byte-identical. This includes the em-dash outlier (paywall-editor-slider-component.mdx), whose output was already canonicalized by remark-visibility and stays identical.
• 3 pages differ, in one direction only: integrations/onesignal.mdx, integrations/singular.mdx, and web-checkout/web-checkout-managed-payments.mdx — recently-added pages that were missing the preamble entirely — now gain the canonical preamble prepended (verified as exactly preamble + "\n\n" + previous output, nothing else changed). This is the intended normalization: they now match every other docs page.

Human-facing HTML is unaffected — Visibility renders null for agents.

Verification

• bun run build — succeeds (594 static cache files + search index generated).
• bun test — 64 pass / 0 fail (was 65; the one dropped test covered the removed extractLeadingAgentVisibilityMarkdown helper).
• bun run types:check — no new errors; the tsc error set is identical to the pre-existing repo-wide baseline (28 errors, unrelated to this change).

Possible follow-up

There are now zero <Visibility> usages of any kind in content/. The Visibility component, plugins/remark-visibility.ts, and src/lib/search-visibility.ts are consequently unexercised by current content. They were intentionally left intact here to keep this diff focused and low-risk (they harmlessly no-op and preserve the mechanism for future use); removing that infrastructure could be a separate cleanup PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JEbbev62ETTL47KjKzX443

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	superwall-docs	8c50fa7	Commit Preview URL Branch Preview URL	Jul 14 2026, 12:41 PM