fix(agent-ready-content): harden markdown serializers + align @sanity/client for the Next app

[plsrd]

What this PR does

Fixes two markdown-serialization bugs from the internal review of agent-ready-content: code blocks that contain a triple-backtick run could break out of their fence, and callouts dropped the custom renderers when recursing into their content. It also aligns the starter's @sanity/client catalog on v8 so a fresh install typechecks again (main's CI was already red on this step).

The third reported bug (Next app has no Accept: text/markdown negotiation) turned out not to be a bug — see below — so no code changed for it.

Changes

1. Code fences sized to the content (packages/agent-markdown/src/serializers.ts, new src/fence.ts)

What was wrong: the code renderer wrapped code.code in a literal three-backtick fence. Per CommonMark a fence closes at the first backtick run at least as long as the opener, so any code snippet that itself contained ``` (a markdown tutorial, a shell snippet quoting a fence) closed the block early and everything after rendered as prose.

What changed: a small pure fenceFor(code) picks a fence one backtick longer than the longest run inside the code (never shorter than three), and the renderer uses it for both the opener and closer. Plain code still gets the familiar ```.

2. Callouts forward the renderers on the recursive pass (serializers.ts)

What was wrong: the callout renderer called portableTextToMarkdown(value.content) with no options, so blocks nested inside a callout fell back to the library defaults: code lost the language:filename info string and the sized fence from (1), and image rendered as a JSON dump of the block.

What changed: the renderer map is hoisted to a renderers const and passed on the recursive call. The callout renderer is the only recursive renderer in the file. Note the starter's own callout schema currently only allows block children, so this is latent with the shipped schema; it matters as soon as someone widens callout.content when porting the pattern (which the bundled skill encourages).

3. Next.js content negotiation: not a bug

The review said apps/next has no middleware.ts and so can't honor Accept: text/markdown as its llms.txt promises. The Next app implements negotiation without middleware: apps/next/next.config.ts has beforeFiles rewrites with has: [{type: 'header', key: 'accept', value: '(.*)text/markdown(.*)'}] that send /docs/:section and /docs/:section/:article to the /md/... route handlers, and the README documents this under "How the markdown routes work". Both apps also already skip Vary: Accept (the README calls out the CDN caching caveat), so behavior matches between the two. No code changed.

4. @sanity/client catalog on v8 (pnpm-workspace.yaml, packages/agent-markdown/package.json)

Not from the review, but it blocked verification. Per-starter lockfiles are gitignored, so a fresh install resolves next-sanity@13.3.4 (and sanity@6.12, @sanity/vision, @sanity/image-url) against @sanity/client@8.5, while the catalog pinned ^7.24. createMarkdown(client) in apps/next/src/lib/markdown.ts then fails typecheck with a private-member mismatch between the two SanityClient classes. The catalog now says ^8.4.0 and @agent-ready/markdown peers on ^8.0.0. Only @sanity/workflow-cli still pulls v7 transitively, which doesn't reach app code.

Testing

Run from agent-ready-content/ after pnpm install:

• SANITY_STUDIO_PROJECT_ID=placeholder SANITY_STUDIO_DATASET=production pnpm typecheck (typegen + all 5 workspaces): passes. Before commit 4 it failed in apps/next with the SanityClient$1 mismatch, which is also what main's last CI run failed on.
• pnpm lint, pnpm format:check, pnpm validate: pass.
• pnpm --filter astro-app build: passes.
• pnpm --filter next-app build: compiles, then fails at the static export of / with Dataset "production" not found for project ID "placeholder". Expected without a real project; not verified against a live dataset.
• Serializer behavior checked with a throwaway tsx script (no test runner exists in the package, so none was committed): fenceFor returns ``` for plain code and one-longer fences for embedded runs; a markdown code block containing ```js renders inside a four-backtick fence; a callout with a nested code and image renders the sized fence and the CDN image URL instead of a JSON dump.
• Not run live: the Next app under next dev with curl -H "Accept: text/markdown"; the negotiation rewrites are unchanged from main.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
agentic-localization	Ready	Preview	Sep 3, 2026 8:45pm UTC
ai-shopping-assistant	Ready	Preview	Sep 3, 2026 8:45pm UTC
commerce-pdp-starter	Ready	Preview	Sep 3, 2026 8:45pm UTC
commerce-plp-starter	Ready	Preview	Sep 3, 2026 8:45pm UTC
content-analytics-starter	Ready	Preview	Sep 3, 2026 8:45pm UTC

[cursor]

Approved: Cursor Bugbot was not present after the first check poll, so that signal was skipped, and no applicable approval policy or prior review required human attention. Reviewers were not assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}