expandai 0.0.2 → 0.0.4

package/src/Install/Opencode/expandai-webfetch.js

@@ -8,6 +8,32 @@
 // dist/index.d.ts.
 import { spawn } from 'node:child_process'
 
+const runHook = (command, args, payload) =>
+	new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			stdio: ['pipe', 'pipe', 'inherit'],
+			env: { ...process.env, EXPANDAI_CLI_CONTEXT: 'agent', EXPANDAI_HARNESS: 'opencode' },
+		})
+		let stdout = ''
+		child.stdout.setEncoding('utf8')
+		child.stdout.on('data', (chunk) => {
+			stdout += chunk
+		})
+		child.on('error', reject)
+		child.on('close', (exitCode) => resolve({ exitCode, stdout }))
+		// Writing to stdin of a binary that failed to spawn raises EPIPE; the
+		// spawn failure itself is reported through the 'error' handler above.
+		child.stdin.on('error', () => {})
+		child.stdin.end(payload)
+	})
+
+// Prefer the installed binary; fall back to `npx -y expandai` so the plugin
+// works for people who have not installed the expandai CLI globally.
+const runExpandai = (args, payload) =>
+	runHook('expandai', args, payload).catch((error) =>
+		error?.code === 'ENOENT' ? runHook('npx', ['-y', 'expandai', ...args], payload) : Promise.reject(error),
+	)
+
 export const ExpandaiWebfetch = async () => ({
 	'tool.execute.after': async (input, output) => {
 		if (input.tool !== 'webfetch') return
@@ -15,15 +41,7 @@ export const ExpandaiWebfetch = async () => ({
 		if (typeof url !== 'string' || url.length === 0) return
 
 		try {
-			const child = spawn('expandai', ['hook', 'opencode'], {
-				stdio: ['pipe', 'pipe', 'inherit'],
-				env: { ...process.env, EXPANDAI_CLI_CONTEXT: 'agent' },
-			})
-			child.stdin.end(JSON.stringify({ url }))
-			let stdout = ''
-			child.stdout.setEncoding('utf8')
-			for await (const chunk of child.stdout) stdout += chunk
-			const exitCode = await new Promise((resolve) => child.on('close', resolve))
+			const { exitCode, stdout } = await runExpandai(['hook', 'opencode'], JSON.stringify({ url }))
 			if (exitCode !== 0 || stdout.trim().length === 0) return
 
 			const { markdown } = JSON.parse(stdout)

package/src/Install/Skill.ts

@@ -2,7 +2,7 @@ import { Console, Effect, Match } from 'effect'
 import { ClaudeSkill } from './Claude/Skill.js'
 import { CodexSkill } from './Codex/Skill.js'
 import { CursorSkill } from './Cursor/Skill.js'
-import type { Host, Scope } from './Mcp.js'
+import type { Host, InstallScope } from './Mcp.js'
 import { OpencodeSkill } from './Opencode/Skill.js'
 
 /**
@@ -30,7 +30,7 @@ export class Skill extends Effect.Service<Skill>()('@expandai/cli/Install/Skill'
 		const opencode = yield* OpencodeSkill
 		const codex = yield* CodexSkill
 
-		const install = Effect.fn('Skill.install')(function* (host: Host, scope: Scope) {
+		const install = Effect.fn('Skill.install')(function* (host: Host, scope: InstallScope) {
 			const target = yield* Match.value(host).pipe(
 				Match.when('claude-code', () => claude.install(scope)),
 				Match.when('cursor', () => cursor.install(scope)),
@@ -41,7 +41,7 @@ export class Skill extends Effect.Service<Skill>()('@expandai/cli/Install/Skill'
 			yield* Console.log(`Installed expandai skill into ${target}`)
 		})
 
-		const uninstall = Effect.fn('Skill.uninstall')(function* (host: Host, scope: Scope) {
+		const uninstall = Effect.fn('Skill.uninstall')(function* (host: Host, scope: InstallScope) {
 			const target = yield* Match.value(host).pipe(
 				Match.when('claude-code', () => claude.uninstall(scope)),
 				Match.when('cursor', () => cursor.uninstall(scope)),

package/src/Install/Uninstall.ts

@@ -1,6 +1,6 @@
 import { Array, Effect, Match, Schema } from 'effect'
 import { type HookHost, HookInstaller } from './Hook.js'
-import { Host, Mcp, Scope } from './Mcp.js'
+import { Host, InstallScope, Mcp } from './Mcp.js'
 import { Skill } from './Skill.js'
 
 export const UninstallTarget = Schema.Literal('all', 'hook', 'skill', 'mcp')
@@ -8,10 +8,10 @@ export const UninstallTarget = Schema.Literal('all', 'hook', 'skill', 'mcp')
 export class UninstallOptions extends Schema.Class<UninstallOptions>('UninstallOptions')({
 	target: Schema.optional(UninstallTarget),
 	host: Schema.optional(Host),
-	scope: Schema.optional(Scope),
+	scope: Schema.optional(InstallScope),
 }) {}
 
-const SCOPES: (typeof Scope.Type)[] = ['global', 'project']
+const SCOPES: (typeof InstallScope.Type)[] = ['global', 'project']
 const HOSTS: (typeof Host.Type)[] = ['claude-code', 'cursor', 'opencode', 'codex']
 
 const isHookHost = (host: typeof Host.Type): host is HookHost => host === 'claude-code' || host === 'opencode'

package/src/MarkdownAnsi.ts

@@ -0,0 +1,162 @@
+/**
+ * Zero-dependency ANSI syntax highlighting for markdown printed to an
+ * interactive terminal.
+ *
+ * This is a highlighter, not a renderer: the input text is preserved
+ * byte-for-byte and only wrapped in ANSI escape sequences, so copying
+ * from the terminal or stripping the escapes yields the exact document
+ * the API returned. Piped output (non-TTY) must stay unstyled — gate
+ * calls with `shouldColorizeMarkdown`.
+ */
+
+// Styling is intentionally limited to 4-bit SGR (bold/dim/underline + the 8
+// base colors): it renders on every color-capable terminal and inherits the
+// user's palette. Do NOT introduce 256-color (38;5;n) or truecolor (38;2;r;g;b)
+// sequences without adding capability detection first — truecolor needs
+// COLORTERM=truecolor|24bit (TERM alone is not enough: e.g. ghostty sets
+// TERM=xterm-ghostty), and 256-color needs TERM=*-256color; emitting either
+// tier on a lesser terminal produces garbage.
+const RESET = '\x1b[0m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+const CYAN = '\x1b[36m'
+const YELLOW = '\x1b[33m'
+const GREEN = '\x1b[32m'
+const BLUE_UNDERLINE = '\x1b[34;4m'
+const HEADING = '\x1b[1;36m'
+
+export interface ColorizeEnvironment {
+	readonly isTty: boolean
+	readonly env: Readonly<Record<string, string | undefined>>
+}
+
+/**
+ * Standard CLI color negotiation: color only on an interactive terminal,
+ * `NO_COLOR` (https://no-color.org) and `TERM=dumb` opt out, a non-zero
+ * `FORCE_COLOR` opts in regardless of the terminal.
+ */
+export function shouldColorizeMarkdown(
+	environment: ColorizeEnvironment = { isTty: process.stdout.isTTY === true, env: process.env },
+): boolean {
+	const { env, isTty } = environment
+	const forceColor = env.FORCE_COLOR?.trim()
+	if (forceColor !== undefined && forceColor !== '') return forceColor !== '0'
+	if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return false
+	if (env.TERM === 'dumb') return false
+	return isTty
+}
+
+function styleLine(style: string, line: string): string {
+	return line === '' ? line : `${style}${line}${RESET}`
+}
+
+// Inline code spans are styled first and must be shielded from the link,
+// bold, and table-pipe passes; ANSI escapes never contain \x00, so a
+// NUL-delimited stash is collision-free.
+function styleInline(line: string, options?: { readonly dimPipes: boolean }): string {
+	const stash: string[] = []
+	let out = line.replace(/`[^`\n]+`/g, (code) => {
+		stash.push(`${CYAN}${code}${RESET}`)
+		return `\x00${stash.length - 1}\x00`
+	})
+	if (options?.dimPipes) {
+		// While code spans are stashed, so pipes inside `...` keep their
+		// code styling instead of being re-wrapped in DIM.
+		out = out.replaceAll('|', `${DIM}|${RESET}`)
+	}
+	out = out.replace(
+		/\[([^\]\n]*)\]\(([^)\n]*)\)/g,
+		(_match, text: string, target: string) =>
+			`${DIM}[${RESET}${BLUE_UNDERLINE}${text}${RESET}${DIM}](${target})${RESET}`,
+	)
+	out = out.replace(/\*\*([^*\n]+)\*\*/g, (_match, text: string) => `${BOLD}**${text}**${RESET}`)
+	return out.replace(/\x00(\d+)\x00/g, (_match, index: string) => stash[Number(index)] ?? '')
+}
+
+const FENCE_PATTERN = /^(\s*)(`{3,}|~{3,})(.*)$/
+const HEADING_PATTERN = /^#{1,6}\s/
+const HR_PATTERN = /^ {0,3}(-{3,}|\*{3,}|_{3,})\s*$/
+const LIST_MARKER_PATTERN = /^(\s*)([-*+]|\d{1,9}[.)])(\s+)(.*)$/
+const FRONTMATTER_KEY_PATTERN = /^(\s*)([\w.-]+):(.*)$/
+
+/**
+ * Wrap a markdown document in ANSI styles for terminal display. Line-based:
+ * headings, fences, front matter, blockquotes, list markers, and table pipes
+ * get block styling; plain text lines get inline code / link / bold styling.
+ */
+export function highlightMarkdownAnsi(markdown: string): string {
+	const lines = markdown.split('\n')
+	const out: string[] = []
+	let inFrontmatter = false
+	let fenceClose: RegExp | undefined
+
+	lines.forEach((line, index) => {
+		if (fenceClose) {
+			if (FENCE_PATTERN.test(line) && fenceClose.test(line)) {
+				fenceClose = undefined
+				out.push(styleLine(DIM, line))
+			} else {
+				out.push(styleLine(YELLOW, line))
+			}
+			return
+		}
+
+		if (index === 0 && line === '---') {
+			inFrontmatter = true
+			out.push(styleLine(DIM, line))
+			return
+		}
+		if (inFrontmatter) {
+			if (line === '---') {
+				inFrontmatter = false
+				out.push(styleLine(DIM, line))
+				return
+			}
+			const keyMatch = line.match(FRONTMATTER_KEY_PATTERN)
+			out.push(
+				keyMatch ? `${keyMatch[1]}${CYAN}${keyMatch[2]}${RESET}${DIM}:${keyMatch[3]}${RESET}` : styleLine(DIM, line),
+			)
+			return
+		}
+
+		const fenceMatch = line.match(FENCE_PATTERN)
+		if (fenceMatch) {
+			const marker = fenceMatch[2] ?? '```'
+			fenceClose = new RegExp(`^\\s*${marker[0] === '`' ? '`' : '~'}{${marker.length},}\\s*$`)
+			out.push(styleLine(DIM, line))
+			return
+		}
+
+		if (HEADING_PATTERN.test(line)) {
+			out.push(styleLine(HEADING, line))
+			return
+		}
+		if (HR_PATTERN.test(line)) {
+			out.push(styleLine(DIM, line))
+			return
+		}
+		if (line.trimStart().startsWith('>')) {
+			out.push(styleLine(GREEN, line))
+			return
+		}
+		if (line.trimStart().startsWith('|')) {
+			out.push(styleInline(line, { dimPipes: true }))
+			return
+		}
+		const listMatch = line.match(LIST_MARKER_PATTERN)
+		if (listMatch) {
+			out.push(`${listMatch[1]}${YELLOW}${listMatch[2]}${RESET}${listMatch[3]}${styleInline(listMatch[4] ?? '')}`)
+			return
+		}
+		out.push(styleInline(line))
+	})
+
+	return out.join('\n')
+}
+
+/** Strip the escape sequences this module emits; used to verify lossless styling. */
+export function stripAnsi(text: string): string {
+	// Only SGR sequences are emitted by this module.
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escapes are control characters by definition.
+	return text.replace(/\x1b\[[0-9;]*m/g, '')
+}

package/src/Mcp/ExpandDocs.ts

@@ -1,71 +1,62 @@
 import { McpServer } from '@effect/ai'
 import { Effect, Layer, String } from 'effect'
+import { ConfigManager } from '../Config.js'
 
-export const EXPAND_AGENT_SETUP_PROMPT =
-	'Read https://expand.ai/start.md and set up Expand for this project. Ask whether I want SDK/API, CLI, or agent-harness integration, then follow the matching instructions.'
+/**
+ * These resources are read by an agent that will follow their links, so every
+ * URL must resolve to the stack this CLI is configured against — production by
+ * default, or whatever `EXPAND_APP_URL` names for local and self-hosted setups.
+ */
+export function makeAgentSetupPrompt(appUrl: string): string {
+	return `Read ${new URL('/start.md', appUrl).toString()} and set up Expand. Fetch it as raw text with curl — a summarizing web-fetch tool drops the exact commands.`
+}
 
-export const EXPAND_START_GUIDE_MARKDOWN = String.stripMargin(`
-	|# Expand Start Guide
-	|
-	|Use this local copy when an MCP client needs setup guidance without fetching the hosted guide first.
-	|
-	|## Agent Setup Prompt
-	|
-	|${EXPAND_AGENT_SETUP_PROMPT}
-	|
-	|## Required CLI Setup
-	|
-	|\`\`\`sh
-	|expandai login
-	|\`\`\`
-	|
-	|## Claude Code
-	|
-	|\`\`\`sh
-	|expandai hook install claude-code project
-	|\`\`\`
-	|
-	|## OpenCode
-	|
-	|\`\`\`sh
-	|expandai hook install opencode project
-	|\`\`\`
-	|
-	|## Cursor
-	|
-	|\`\`\`sh
-	|expandai skill install cursor project
-	|expandai mcp install cursor project
-	|\`\`\`
-	|
-	|## Codex
-	|
-	|\`\`\`sh
-	|expandai skill install codex project
-	|expandai mcp install codex project
-	|\`\`\`
-	|`)
+/**
+ * Points at the hosted guide instead of restating it. A local copy of the setup
+ * procedure drifts silently the moment the commands change, and this resource
+ * is read by an agent that can fetch the current one itself.
+ */
+export function makeStartGuideMarkdown(appUrl: string): string {
+	return String.stripMargin(`
+		|# Expand Start Guide
+		|
+		|The setup procedure is served as a single document. Fetch it and follow it:
+		|
+		|${new URL('/start.md', appUrl).toString()}
+		|
+		|## Agent Setup Prompt
+		|
+		|${makeAgentSetupPrompt(appUrl)}
+		|`)
+}
+
+export function makeAboutMarkdown(appUrl: string): string {
+	return String.stripMargin(`
+		|# expand.ai
+		|
+		|- Website: ${appUrl}
+		|- Quickstart: ${new URL('/docs', appUrl).toString()}
+		|- Dashboard: ${new URL('/dashboard', appUrl).toString()}
+		|`)
+}
+
+const appUrl = Effect.gen(function* () {
+	const configManager = yield* ConfigManager
+	return yield* configManager.getAppUrl()
+})
 
 export const ExpandDocs = McpServer.resource({
 	uri: 'expand://about',
 	name: 'About expand.ai',
 	description: 'Key links for the expand.ai platform',
-	content: Effect.succeed(
-		String.stripMargin(`
-			|# expand.ai
-			|
-			|- Website: https://expand.ai
-			|- Quickstart: https://expand.ai/docs
-			|- Dashboard: https://expand.ai/dashboard
-			|`),
-	),
+	content: Effect.map(appUrl, makeAboutMarkdown),
 })
 
 export const ExpandStartDocs = McpServer.resource({
 	uri: 'expand://start',
 	name: 'Expand Start Guide',
-	description: 'Local copy of the Expand agent and editor setup guide',
-	content: Effect.succeed(EXPAND_START_GUIDE_MARKDOWN),
+	description: 'Where to find the Expand agent setup guide, and the prompt that runs it',
+	content: Effect.map(appUrl, makeStartGuideMarkdown),
 })
 
-export const ExpandDocsLayer = Layer.mergeAll(ExpandDocs, ExpandStartDocs)
+export const ExpandDocsLayer = Layer.mergeAll(ExpandDocs, ExpandStartDocs).pipe(Layer.provide(ConfigManager.Default))

package/src/Mcp/Server.ts

@@ -1,5 +1,6 @@
 import { Layer } from 'effect'
 import { SERVER_KEY } from '../Install/Domain.js'
+import { CLI_VERSION } from '../Version.js'
 import { ExpandDocsLayer } from './ExpandDocs.js'
 import { ExpandToolKit } from './Toolkit.js'
 
@@ -7,7 +8,7 @@ export { CurrentRequestHeaders } from './RequestHeaders.js'
 
 export const ServerInfo = {
 	name: SERVER_KEY,
-	version: '0.0.1',
+	version: CLI_VERSION,
 } as const
 
 export const makeServerLayer = (options: { readonly includeDocs?: boolean } = {}) =>

package/src/Mcp/tools/Citations.ts

@@ -8,6 +8,9 @@ import * as Generated from '@expandai/sdk/Generated'
 import { citationUrl, playgroundBase, resolvePlaygroundHost } from '@expandai/sdk/Playground'
 import { Schema as S } from 'effect'
 
+export const FetchInvocationPath = S.Literal('cli-recovery', 'mcp-fetch-search')
+export type FetchInvocationPath = typeof FetchInvocationPath.Type
+
 export class CitedSnippet extends S.Class<CitedSnippet>('CitedSnippet')({
 	type: S.optionalWith(S.Literal('text'), { nullable: true, default: () => 'text' as const }),
 	source: S.Literal('markdown', 'appendix', 'statejson'),
@@ -20,6 +23,86 @@ export class CitedSnippet extends S.Class<CitedSnippet>('CitedSnippet')({
 	}),
 }) {}
 
+/**
+ * Carried in the tool result itself, not only in `SKILL.md`. A harness may not load
+ * skills at all, and the hook's snapshot note never reaches this path — so without
+ * this the model receives perfect `citationUrl`s and no instruction to use them, and
+ * answers with no citation. Observed on OpenCode before this was added.
+ */
+export const CITATION_INSTRUCTIONS =
+	'Cite every claim you take from this result. Append the ready-made `citationBlock` from this ' +
+	'result to the end of your answer. Delete every entry whose marker you did not actually place ' +
+	'in your text, and renumber what remains from [1] — an entry with no matching marker is not a ' +
+	'citation, it is clutter. Do not ' +
+	'retype the URLs, do not substitute the page you fetched, and do not build a link yourself — ' +
+	"the citation points at expand.ai's stored capture, not at the original site. Never invent an " +
+	'evidence id and never reuse one from different text. A link without `?id=` is not a citation.'
+
+const CitationInstructionsField = S.optionalWith(S.String, { default: () => CITATION_INSTRUCTIONS }).annotations({
+	description: 'How to cite this result back to the user. Follow it exactly.',
+})
+
+const CitationBlockField = S.optionalWith(S.String, { default: () => '' }).annotations({
+	description:
+		'Ready-to-append citation block, one entry per citable snippet. Copy it to the end of your ' +
+		'answer, keeping only the entries whose markers you placed in your text and renumbering ' +
+		'from [1]. You may also correct the page title.',
+})
+
+/**
+ * Prebuilds the citation markdown instead of asking the model to assemble it.
+ * Selecting `citationUrl` out of a JSON result and pasting it correctly is the step
+ * weaker models get wrong — observed repeatedly on OpenCode, which substituted the
+ * fetched page URL for the capture link. Copying one block has no such failure mode.
+ */
+const MAX_CITATION_MARKERS = 3
+const EVIDENCE_MARKER = /\{(\d{1,6})\}/gu
+
+/**
+ * Citation URLs for a plain fetch with no search. The markdown still stamps evidence
+ * ids, so a citation is always possible — without this a `fetch` called without a
+ * query produced an empty block and the model answered uncited.
+ */
+function markdownCitationUrls(markdown: string, snapshotId: string, host: string): string[] {
+	const urls: string[] = []
+	for (const match of markdown.matchAll(EVIDENCE_MARKER)) {
+		const id = Number(match[1])
+		if (!Number.isFinite(id)) continue
+		const url = citationUrl(snapshotId, { evidenceId: id }, host)
+		if (!urls.includes(url)) urls.push(url)
+		if (urls.length >= MAX_CITATION_MARKERS) break
+	}
+	return urls
+}
+
+/**
+ * `statejson` snippets are extracted page state — arrays of routes, config blobs — not
+ * prose anyone can quote. Offering one as a citable source produced a `Sources` entry
+ * pointing at a list of URLs, so only quotable text earns a citation.
+ */
+function isQuotable(snippet: CitedSnippet): boolean {
+	return snippet.source !== 'statejson'
+}
+
+function citationBlock(sourceLabel: string, snippets: ReadonlyArray<CitedSnippet>, fallback: string[] = []): string {
+	const urls: string[] = []
+	for (const snippet of snippets) {
+		if (!isQuotable(snippet)) continue
+		if (snippet.citationUrl.length > 0 && !urls.includes(snippet.citationUrl)) urls.push(snippet.citationUrl)
+	}
+	if (urls.length === 0) urls.push(...fallback)
+	if (urls.length === 0) return ''
+	// One linked source line per marker.
+	// Grouping all the sources first and all the links after loses every link when a
+	// model copies only the opening lines — observed on OpenCode.
+	const lines = ['**Sources**']
+	urls.slice(0, MAX_CITATION_MARKERS).forEach((url, index) => {
+		if (index > 0) lines.push('')
+		lines.push(`[${index + 1}] [${sourceLabel}](${url})`)
+	})
+	return lines.join('\n')
+}
+
 export class CitedSearchResult extends S.Class<CitedSearchResult>('CitedSearchResult')({
 	query: S.String,
 	snippets: S.Array(CitedSnippet),
@@ -27,13 +110,15 @@ export class CitedSearchResult extends S.Class<CitedSearchResult>('CitedSearchRe
 }) {}
 
 export class CitedObjectModeResult extends S.Class<CitedObjectModeResult>('CitedObjectModeResult')({
+	invocationPath: S.Literal('mcp-fetch-search'),
+	citationInstructions: CitationInstructionsField,
+	citationBlock: CitationBlockField,
 	meta: Generated.FetchObjectModeMeta,
 	markdown: S.String,
 	json: S.Array(Generated.FetchObjectModeEvidence),
 	data: S.optionalWith(
 		S.Struct({
 			assets: S.optionalWith(S.Array(Generated.FetchAssetReference), { nullable: true }),
-			captureTelemetry: S.optionalWith(Generated.CaptureTelemetryInfo, { nullable: true }),
 			search: S.optionalWith(CitedSearchResult, { nullable: true }),
 		}),
 		{ nullable: true },
@@ -41,6 +126,9 @@ export class CitedObjectModeResult extends S.Class<CitedObjectModeResult>('Cited
 }) {}
 
 export class CitedSnapshotSearchResult extends S.Class<CitedSnapshotSearchResult>('CitedSnapshotSearchResult')({
+	invocationPath: FetchInvocationPath,
+	citationInstructions: CitationInstructionsField,
+	citationBlock: CitationBlockField,
 	snapshotId: S.String.pipe(S.minLength(1)),
 	response: Generated.ResponseInfo,
 	search: CitedSearchResult,
@@ -59,7 +147,7 @@ function toCitedSnippet(snapshotId: string, host: string, snippet: SnippetWithJs
 		json: snippet.json,
 		score: snippet.score,
 		location: snippet.location,
-		citationUrl: citationUrl(snapshotId, snippet.source, snippet.location, host),
+		citationUrl: citationUrl(snapshotId, snippet.location, host),
 	})
 }
 
@@ -80,30 +168,51 @@ export function enrichObjectModeResult(
 	// it is somehow not a parseable URL.
 	const host = resolvePlaygroundHost(result.meta.playground, fallbackHost)
 	const data = result.data
+	const citedSearch = data?.search == null ? undefined : toCitedSearch(result.meta.snapshotId, host, data.search)
+	const block = citationBlock(
+		result.meta.url,
+		citedSearch?.snippets ?? [],
+		markdownCitationUrls(result.markdown, result.meta.snapshotId, host),
+	)
 	return new CitedObjectModeResult({
+		invocationPath: 'mcp-fetch-search',
+		citationInstructions: CITATION_INSTRUCTIONS,
+		citationBlock: block,
 		meta: result.meta,
-		markdown: result.markdown,
+		// The block is appended to the content, not just offered as a sibling field.
+		// A model summarising `markdown` carries an inline footer through; a separate
+		// JSON field it has to notice and copy gets dropped — repeatedly, on OpenCode.
+		markdown: block.length === 0 ? result.markdown : `${result.markdown.trimEnd()}\n\n---\n\n${block}\n`,
 		json: result.json,
 		data:
 			data == null
 				? data
 				: {
 						assets: data.assets,
-						captureTelemetry: data.captureTelemetry,
-						search: data.search == null ? data.search : toCitedSearch(result.meta.snapshotId, host, data.search),
+						search: citedSearch,
 					},
 	})
 }
 
-/** Add `citationUrl` to each snippet of a snapshot-search result (no server `meta.playground`). */
+/** Add `citationUrl` to each snippet of a snapshot-search result. */
 export function enrichSnapshotSearchResult(
 	result: FetchSnapshotSearchResultWithJson,
-	host: string,
+	fallbackHost: string,
+	invocationPath: FetchInvocationPath = 'mcp-fetch-search',
 ): CitedSnapshotSearchResult {
+	// `playground` is server-resolved (staging-safe), exactly like `meta.playground`
+	// above; fall back to the configured host only if it is somehow not a parseable
+	// URL. The playground is a separate deployment from the API, so the server is
+	// the only component that can say where its snapshots are publicly served.
+	const host = resolvePlaygroundHost(result.playground, fallbackHost)
+	const citedSearch = toCitedSearch(result.snapshotId, host, result.search)
 	return new CitedSnapshotSearchResult({
+		invocationPath,
+		citationInstructions: CITATION_INSTRUCTIONS,
+		citationBlock: citationBlock(result.response.url, citedSearch.snippets),
 		snapshotId: result.snapshotId,
 		response: result.response,
-		search: toCitedSearch(result.snapshotId, host, result.search),
+		search: citedSearch,
 		durationMs: result.durationMs,
 		playground: playgroundBase(result.snapshotId, host),
 	})