@growth-labs/cms 0.5.6 → 0.5.8

package/src/engine/ai-dek-notifications.ts

@@ -0,0 +1,50 @@
+import type { D1Database } from './d1.js'
+
+export interface DekFailureNotificationInput {
+	db: D1Database
+	workspaceId: string
+	contentId: string
+	title: string
+	reason: string
+	userId?: string | null
+}
+
+/**
+ * Create unread, in-app notifications when publication ships without a dek.
+ * Interactive publishes target the actor; background publishes target every
+ * editorial member because no actor is present to receive the failure.
+ */
+export async function createDekFailureNotifications(
+	input: DekFailureNotificationInput,
+): Promise<number> {
+	let userIds: string[]
+	if (input.userId) {
+		userIds = [input.userId]
+	} else {
+		const rows = await input.db
+			.prepare(
+				`SELECT user_id
+				 FROM workspace_memberships
+				 WHERE workspace_id = ?
+				   AND role IN ('owner', 'senior_editor', 'editor')
+				 ORDER BY user_id ASC`,
+			)
+			.bind(input.workspaceId)
+			.all<{ user_id: string }>()
+		userIds = (rows.results ?? []).map((row) => row.user_id)
+	}
+
+	const reason = input.reason.trim().slice(0, 160) || 'unknown error'
+	const body = `Content was published without a subheading: “${input.title}”. AI generation failed (${reason}). Open the item to add one manually.`
+	for (const userId of [...new Set(userIds)]) {
+		await input.db
+			.prepare(
+				`INSERT INTO cms_notifications
+				 (id, workspace_id, user_id, kind, body, created_at)
+				 VALUES (?, ?, ?, 'ai_dek_failed', ?, unixepoch())`,
+			)
+			.bind(crypto.randomUUID(), input.workspaceId, userId, body)
+			.run()
+	}
+	return new Set(userIds).size
+}

package/src/engine/ai-dek.ts

@@ -0,0 +1,138 @@
+import type { LlmDispatch } from '../providers/types.js'
+import { dekPrompt } from './ai-prompts.js'
+import { applyAiWrite, parseLockedFields } from './ai-writeback.js'
+import type { D1Database } from './d1.js'
+import { type ContentItemRecord, getContentItem } from './publisher.js'
+
+export const DEK_EXEMPLAR_LIMIT = 6
+
+export interface DekGenerationContext {
+	item: ContentItemRecord
+	source: string
+	exemplars: string[]
+}
+
+export type GenerateContentDekResult =
+	| { status: 'generated'; dek: string; written: true }
+	| { status: 'locked'; dek: string; written: false }
+	| { status: 'unavailable'; dek: null; written: false; reason: string }
+	| { status: 'not_found'; dek: null; written: false; reason: 'not_found' }
+
+async function loadTypeSource(db: D1Database, item: ContentItemRecord): Promise<string> {
+	if (item.type === 'video') {
+		const row = await db
+			.prepare('SELECT script FROM video_content WHERE content_id = ? LIMIT 1')
+			.bind(item.id)
+			.first<{ script: string | null }>()
+		return row?.script?.trim() ?? ''
+	}
+	if (item.type === 'podcast') {
+		const row = await db
+			.prepare('SELECT transcript FROM podcast_content WHERE content_id = ? LIMIT 1')
+			.bind(item.id)
+			.first<{ transcript: string | null }>()
+		return row?.transcript?.trim() ?? ''
+	}
+	const row = await db
+		.prepare(
+			`SELECT body_markdown, body_html, subtitle
+			 FROM article_content WHERE content_id = ? LIMIT 1`,
+		)
+		.bind(item.id)
+		.first<{
+			body_markdown: string | null
+			body_html: string | null
+			subtitle: string | null
+		}>()
+	return (row?.body_markdown || row?.body_html || row?.subtitle || '').trim()
+}
+
+export async function loadDekGenerationContext(
+	db: D1Database,
+	contentId: string,
+): Promise<DekGenerationContext | null> {
+	const item = await getContentItem(db, contentId)
+	if (!item) return null
+
+	const typeSource = await loadTypeSource(db, item)
+	const description = item.description?.trim() ?? ''
+	const source = [description, typeSource].filter(Boolean).join('\n\n')
+	const rows = await db
+		.prepare(
+			`SELECT title, excerpt
+			 FROM content_items
+			 WHERE status = 'published'
+			   AND deleted_at IS NULL
+			   AND id <> ?
+			   AND excerpt IS NOT NULL
+			   AND trim(excerpt) <> ''
+			 ORDER BY CASE WHEN type = ? THEN 0 ELSE 1 END,
+			          COALESCE(published_at, 0) DESC,
+			          id ASC
+			 LIMIT ?`,
+		)
+		.bind(contentId, item.type, DEK_EXEMPLAR_LIMIT)
+		.all<{ title: string; excerpt: string }>()
+	const exemplars = (rows.results ?? []).map(
+		(row) => `Headline: ${row.title}\nDek: ${row.excerpt.trim()}`,
+	)
+
+	return { item, source, exemplars }
+}
+
+function normalizeDek(text: string): string {
+	return text
+		.trim()
+		.replace(/^(["“])|(["”])$/g, '')
+		.replace(/\s+/g, ' ')
+		.trim()
+}
+
+export async function generateContentDek(input: {
+	db: D1Database
+	contentId: string
+	llm: LlmDispatch
+}): Promise<GenerateContentDekResult> {
+	const context = await loadDekGenerationContext(input.db, input.contentId)
+	if (!context) {
+		return { status: 'not_found', dek: null, written: false, reason: 'not_found' }
+	}
+
+	const result = await input.llm.dispatch({
+		...dekPrompt({
+			title: context.item.title,
+			source: context.source,
+			exemplars: context.exemplars,
+		}),
+		stream: false,
+	})
+	if (result instanceof ReadableStream) {
+		return { status: 'unavailable', dek: null, written: false, reason: 'stream_result' }
+	}
+	if (result.status === 'unavailable') {
+		return {
+			status: 'unavailable',
+			dek: null,
+			written: false,
+			reason: result.reason ?? 'unavailable',
+		}
+	}
+
+	const dek = normalizeDek(result.text)
+	if (!dek) {
+		return { status: 'unavailable', dek: null, written: false, reason: 'empty_result' }
+	}
+
+	const write = applyAiWrite({
+		locked: parseLockedFields(context.item.ai_locked_fields),
+		field: 'excerpt',
+		value: dek,
+	})
+	if (!write.written) return { status: 'locked', dek, written: false }
+
+	await input.db
+		.prepare('UPDATE content_items SET excerpt = ?, updated_at = unixepoch() WHERE id = ?')
+		.bind(dek, input.contentId)
+		.run()
+	return { status: 'generated', dek, written: true }
+}

package/src/engine/ai-prompts.ts

@@ -47,12 +47,37 @@ export interface MetaDescriptionPromptInput {
 	body: string
 }
 
+/** Input to dekPrompt. A dek is display copy, not SEO metadata. */
+export interface DekPromptInput {
+	title: string
+	source: string
+	exemplars?: string[]
+}
+
 /** The typed prompt contract shape consumed by LlmDispatch.dispatch(). */
 export interface AiPromptContract {
 	task: string
 	prompt: string
 }
 
+/**
+ * Build the prompt for a standfirst-style display subheading (dek).
+ * This deliberately differs from the SEO meta-description task: it tells the
+ * reader what the piece argues, reveals, or shows in the publication's voice.
+ */
+export function dekPrompt(input: DekPromptInput): AiPromptContract {
+	const exemplarsBlock = buildExemplarsBlock(input.exemplars)
+	const prompt = `${HOUSE_STYLE_SYSTEM}${exemplarsBlock}
+
+Task: Write one standfirst-style subheading (dek) for this piece. It must be 1–2 sentences, roughly 120–200 characters, and reader-facing. State what the piece argues, reveals, or shows. It must not repeat or lightly rephrase the headline. Avoid clickbait and never use the boilerplate shape “with context on the stakes for…”. Return only the dek text with no label, quotation marks, commentary, or preamble.
+
+Headline: ${input.title}
+
+Source material:
+${input.source}`
+	return { task: 'cms.dek', prompt }
+}
+
 /** Build the exemplars block when exemplars are supplied. */
 function buildExemplarsBlock(exemplars: string[] | undefined): string {
 	if (!exemplars || exemplars.length === 0) return ''

package/src/engine/index.ts

@@ -5,9 +5,23 @@
 
 // Activity log write helper — first-party D1, cms_activity_log (P5 Task 3).
 export { type ActivityEntry, logActivity } from './activity-log.js'
+// Display-subheading generation with deterministic house exemplars.
+export {
+	DEK_EXEMPLAR_LIMIT,
+	type DekGenerationContext,
+	type GenerateContentDekResult,
+	generateContentDek,
+	loadDekGenerationContext,
+} from './ai-dek.js'
+export {
+	createDekFailureNotifications,
+	type DekFailureNotificationInput,
+} from './ai-dek-notifications.js'
 // AI prompt contracts + house-style system prompt (P4 Task 1).
 export {
 	type AiPromptContract,
+	type DekPromptInput,
+	dekPrompt,
 	type HeadlinesPromptInput,
 	HOUSE_STYLE_SYSTEM,
 	headlinesPrompt,

package/src/integration/index.ts

@@ -121,6 +121,10 @@ export default function growthLabsCms(userOptions: CmsIntegrationOptions): Astro
 					entrypoint: resolveEntrypoint('../ui/api/content/[id]'),
 				})
 				// AI sub-routes
+				injectRoute({
+					pattern: `${base}/api/content/[id]/ai/dek`,
+					entrypoint: resolveEntrypoint('../ui/api/content/[id]/ai/dek'),
+				})
 				injectRoute({
 					pattern: `${base}/api/content/[id]/ai/headlines`,
 					entrypoint: resolveEntrypoint('../ui/api/content/[id]/ai/headlines'),

package/src/integration/options.ts

@@ -8,6 +8,11 @@ const workspaceSchema = z.object({
 	color: z.string().default('#0c4a6e'),
 })
 
+const primaryCategorySchema = z.object({
+	slug: z.string().min(1),
+	label: z.string().min(1),
+})
+
 const themeSchema = z
 	.object({
 		mode: z.enum(['light', 'dark']).default('dark'),
@@ -32,6 +37,7 @@ const surveyResultsSchema = z
 export const cmsIntegrationOptionsSchema = z
 	.object({
 		workspaces: z.array(workspaceSchema).min(1, 'at least one workspace is required'),
+		primaryCategories: z.array(primaryCategorySchema).default([]),
 		activeWorkspaceId: z.string().optional(),
 		adminBasePath: z.string().default('/admin'),
 		searchEnabled: z.boolean().default(true),

package/src/routes/ai.ts

@@ -14,6 +14,7 @@
 //   apply the ai_locked_fields gate, persist when allowed, and return the result.
 // - OG-image generation lands in Task 5.
 
+import { generateContentDek } from '../engine/ai-dek.js'
 import {
 	headlinesPrompt,
 	metaDescriptionPrompt,
@@ -24,6 +25,7 @@ import { applyAiWrite, parseLockedFields } from '../engine/ai-writeback.js'
 import { buildOgCardSpec } from '../engine/og-render.js'
 import { type ContentItemRecord, getContentItem } from '../engine/publisher.js'
 import type { LlmDispatchResult } from '../providers/types.js'
+import { canPerformContentAction } from './authz-matrix.js'
 import type { CmsRouteConfig } from './config.js'
 import { resolveConfig } from './config.js'
 import { type Authz, type Capability, json, type RouteContext, requireId } from './context.js'
@@ -45,6 +47,8 @@ async function aiGuard(authz: Authz, ctx: RouteContext): Promise<Response | null
 }
 
 export interface AiRouteHandlers {
+	/** POST /content/:id/ai/dek — sync: generate + persist a display subheading. */
+	suggestDek(ctx: RouteContext): Promise<Response>
 	/** POST /content/:id/ai/proofread — SSE streaming proofread & tighten. */
 	proofreadAndTighten(ctx: RouteContext): Promise<Response>
 	/** POST /content/:id/ai/headlines — SSE streaming 5-headline suggestions. */
@@ -171,6 +175,45 @@ async function loadArticleBody(
 export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 	const resolved = resolveConfig(config)
 
+	async function suggestDek(ctx: RouteContext): Promise<Response> {
+		const idResult = requireId(ctx)
+		if ('error' in idResult) return idResult.error
+		const item = await getContentItem(ctx.db, idResult.id)
+		if (!item) return json({ error: 'Not found' }, 404)
+
+		if (resolved.authz.getUser) {
+			const user = await resolved.authz.getUser(ctx)
+			if (!user) return json({ error: 'Unauthorized' }, 401)
+			const allowed = canPerformContentAction(
+				user.role,
+				{ actorSubject: user.subject, contentAuthorId: item.author_id },
+				item.status === 'published' ? 'write_published' : 'write',
+			)
+			if (!allowed) return json({ error: 'Forbidden', role: user.role }, 403)
+		} else {
+			const authGuard = await aiGuard(resolved.authz, ctx)
+			if (authGuard) return authGuard
+		}
+		if (!resolved.hooks.llm) {
+			return json({ error: 'AI generation is not configured' }, 501)
+		}
+
+		const result = await generateContentDek({
+			db: ctx.db,
+			contentId: idResult.id,
+			llm: resolved.hooks.llm,
+		})
+		if (result.status === 'not_found') return json({ error: 'Not found' }, 404)
+		if (result.status === 'unavailable') {
+			return llmUnavailableResponse({ reason: result.reason }, { dek: null, written: false })
+		}
+		return json({
+			dek: result.dek,
+			written: result.written,
+			...(result.status === 'locked' ? { locked: true } : {}),
+		})
+	}
+
 	async function proofreadAndTighten(ctx: RouteContext): Promise<Response> {
 		// Guard: edit_own_draft capability (any member; ownership-aware write-back).
 		const authGuard = await aiGuard(resolved.authz, ctx)
@@ -452,6 +495,7 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 	}
 
 	return {
+		suggestDek,
 		proofreadAndTighten,
 		suggestHeadlines,
 		generateKeyTakeaways,

package/src/routes/authz-matrix.ts

@@ -54,6 +54,7 @@ export const CAPABILITY_MATRIX: Record<Capability, ReadonlySet<CmsRole>> = {
 	publish_article: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
 	publish_video: new Set<CmsRole>(['owner', 'senior_editor', 'editor', 'producer']),
 	edit_own_draft: new Set<CmsRole>(['owner', 'senior_editor', 'editor', 'contributor', 'producer']),
+	edit_published: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
 	publish_others_draft: new Set<CmsRole>(['owner', 'senior_editor', 'editor']),
 	submit_for_review: new Set<CmsRole>([
 		'owner',
@@ -150,6 +151,7 @@ export function canActOnContent(
  *   - 'write'    — create / update / save a draft, set-status, snapshot,
  *                  contributors edit. Lowest bar: edit_own_draft (any member;
  *                  contributor/producer gated to OWN content by canActOnContent).
+ *   - 'write_published' — update published copy. Explicitly editorial-only.
  *   - 'publish'  — publish/unpublish/archive/unschedule an article. Requires
  *                  publish_others_draft (owner/senior_editor/editor); on OWN
  *                  content publish_article suffices (still excludes contributor).
@@ -158,7 +160,14 @@ export function canActOnContent(
  *   - 'trash'    — soft-delete / bulk-trash. Destructive → publish_others_draft.
  *   - 'media'    — dispatch-to-foundry / regenerate AI artefacts. media_pipeline.
  */
-export type ContentAction = 'write' | 'publish' | 'publish_video' | 'schedule' | 'trash' | 'media'
+export type ContentAction =
+	| 'write'
+	| 'write_published'
+	| 'publish'
+	| 'publish_video'
+	| 'schedule'
+	| 'trash'
+	| 'media'
 
 /**
  * Resolve whether `role` may perform a content `action` on an item authored by
@@ -180,6 +189,8 @@ export function canPerformContentAction(
 	switch (action) {
 		case 'write':
 			return canActOnContent(role, ownership, 'edit_own_draft')
+		case 'write_published':
+			return canActOnContent(role, ownership, 'edit_published')
 		case 'media':
 			return canActOnContent(role, ownership, 'media_pipeline')
 		case 'publish_video':

package/src/routes/content.ts

@@ -16,6 +16,8 @@
 
 import { z } from 'zod'
 import { logActivity } from '../engine/activity-log.js'
+import { generateContentDek } from '../engine/ai-dek.js'
+import { createDekFailureNotifications } from '../engine/ai-dek-notifications.js'
 import { listContributors, setContributors } from '../engine/contributors.js'
 import type { D1Database } from '../engine/d1.js'
 import {
@@ -823,6 +825,7 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			const cursor = parseCursor(url.searchParams.get('cursor'))
 			const q = url.searchParams.get('q') || null
 			const author = url.searchParams.get('author') || null
+			const channel = url.searchParams.get('channel') || null
 
 			const bindings: unknown[] = []
 			// Always exclude soft-deleted rows (migration 0002 added deleted_at).
@@ -844,6 +847,10 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				where += ' AND c.author_id = ?'
 				bindings.push(author)
 			}
+			if (channel) {
+				where += ' AND c.channel = ?'
+				bindings.push(channel)
+			}
 			if (cursor) {
 				where += ' AND (c.updated_at < ? OR (c.updated_at = ? AND c.id < ?))'
 				bindings.push(cursor.updatedAt, cursor.updatedAt, cursor.id)
@@ -857,7 +864,7 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			// EVERY row, mis-stamping all rows as PROCESSING. Mirrors the JOIN the
 			// counts handler below already uses.
 			const query = `
-				SELECT c.id, c.type, c.status, c.slug, c.title, c.visibility, c.featured,
+				SELECT c.id, c.type, c.status, c.slug, c.title, c.channel, c.visibility, c.featured,
 					c.publish_at, c.published_at, c.updated_at, c.author_id,
 					a.slug AS author_slug, a.name AS author_name,
 					vc.processing_state AS processing_state
@@ -877,6 +884,7 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 					status: ContentStatus
 					slug: string
 					title: string
+					channel: string | null
 					visibility: 'free' | 'premium'
 					featured: number | null
 					publish_at: number | null
@@ -1126,7 +1134,11 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			if (!existing) return json({ error: 'Not found' }, 404)
 
 			// Edit = write; contributor/producer gated to their own content.
-			const denied = await requireContentAction(ctx, 'write', existing.author_id)
+			const denied = await requireContentAction(
+				ctx,
+				existing.status === 'published' ? 'write_published' : 'write',
+				existing.author_id,
+			)
 			if (denied) return denied
 
 			const parsed = UpdateSchema.safeParse(await readJson(ctx))
@@ -1320,6 +1332,44 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 						422,
 					)
 				}
+
+				if (!existing.excerpt?.trim()) {
+					let failureReason: string | null = null
+					if (!resolved.hooks.llm) {
+						failureReason = 'AI generation is not configured'
+					} else {
+						try {
+							const generated = await generateContentDek({
+								db: ctx.db,
+								contentId: id,
+								llm: resolved.hooks.llm,
+							})
+							if (generated.status === 'unavailable' || generated.status === 'not_found') {
+								failureReason = generated.reason
+							}
+						} catch (error) {
+							failureReason = error instanceof Error ? error.message : String(error)
+						}
+					}
+					if (failureReason) {
+						console.error('[cms] dek generation failed; publishing without a subheading', {
+							contentId: id,
+							reason: failureReason,
+						})
+						try {
+							await createDekFailureNotifications({
+								db: ctx.db,
+								workspaceId: activeWorkspaceId,
+								contentId: id,
+								title: existing.title,
+								reason: failureReason,
+								userId: ctx.userId,
+							})
+						} catch (notificationError) {
+							console.error('[cms] failed to create dek generation notification', notificationError)
+						}
+					}
+				}
 				await publishContent(ctx.db, id, now)
 				await createRevision(ctx.db, id, ctx.userId || null)
 

package/src/routes/context.ts

@@ -25,6 +25,7 @@ export type Capability =
 	| 'publish_article'
 	| 'publish_video'
 	| 'edit_own_draft'
+	| 'edit_published'
 	| 'publish_others_draft'
 	| 'submit_for_review'
 	| 'media_pipeline'

package/src/ui/api/_content-config.ts

@@ -19,6 +19,7 @@ import { buildSiteAuthz } from './_authz.js'
  * ContentRouteConfig so adapters can surface them without a separate locals key.
  */
 type CmsHooksLocals = ContentRouteConfig['hooks'] & {
+	activeWorkspaceId?: string
 	dispatchTakeaways?: DispatchTakeawaysHook
 	dispatchFaq?: DispatchFaqHook
 	dispatchWebhook?: DispatchWebhookHook
@@ -62,6 +63,7 @@ export function toContentConfig(c: APIContext): ContentRouteConfig {
 	const hooks = locals.cmsHooks ?? {}
 	return {
 		authz: buildSiteAuthz(c),
+		activeWorkspaceId: hooks.activeWorkspaceId,
 		hooks: {
 			llm: hooks.llm,
 			foundryVideo: hooks.foundryVideo,

package/src/ui/api/content/[id]/ai/dek.ts

@@ -0,0 +1,8 @@
+// POST /admin/api/content/:id/ai/dek — generate and persist a display subheading.
+
+import type { APIContext } from 'astro'
+import { createAiRoutes } from '../../../../../routes/ai.js'
+import { toContentConfig, toContentCtx } from '../../../_content-config.js'
+
+export const POST = (c: APIContext) =>
+	createAiRoutes(toContentConfig(c)).suggestDek(toContentCtx(c, { id: c.params.id ?? '' }))

package/src/ui/client/mount.tsx

@@ -37,6 +37,7 @@ export async function mount(elementId = 'masthead-root') {
 	const initial = initialWorkspaceState(config.workspaces, config.activeWorkspaceId, user)
 	const screens = createCmsScreens({
 		allowInlineAuthorCreation: config.socialSharing.allowInlineAuthorCreation,
+		primaryCategories: config.primaryCategories,
 		surveyId: config.surveyResults?.surveyId,
 	})
 	createRoot(el).render(<CmsApp initial={initial} screens={screens} boot={boot} />)

package/src/ui/editor/AiAssistPanel.tsx

@@ -27,6 +27,13 @@ interface ActionMeta {
 }
 
 const ACTIONS: ActionMeta[] = [
+	{
+		action: 'dek',
+		icon: 'sparkle',
+		title: 'Suggest subheading',
+		description: 'Display copy in house voice',
+		kind: 'sync',
+	},
 	{
 		action: 'proofread',
 		icon: 'wand',
@@ -74,6 +81,10 @@ interface PanelState {
 	headlines: string[]
 	/** Meta description text from the sync result (for the "Apply" button). */
 	metaDescription: string | null
+	/** Generated display subheading. */
+	dek: string | null
+	/** Whether the generated subheading was applied to the controlled form. */
+	dekApplied: boolean
 	/** Whether the meta was applied/written. */
 	metaApplied: boolean
 	/** Whether the takeaways were written (server-side). */
@@ -89,6 +100,8 @@ const INITIAL_STATE: PanelState = {
 	activeAction: null,
 	headlines: [],
 	metaDescription: null,
+	dek: null,
+	dekApplied: false,
 	metaApplied: false,
 	takeawaysWritten: false,
 	locked: false,
@@ -103,9 +116,11 @@ export interface AiAssistPanelProps {
 	docId: string
 	/** Called when the meta description should be applied to the SEO description field. */
 	onMetaApplied?: (description: string) => void
+	/** Called after an unlocked generated dek is stored, keeping the form in sync. */
+	onDekApplied?: (dek: string) => void
 }
 
-export function AiAssistPanel({ docId, onMetaApplied }: AiAssistPanelProps) {
+export function AiAssistPanel({ docId, onMetaApplied, onDekApplied }: AiAssistPanelProps) {
 	const [state, setState] = useState<PanelState>(INITIAL_STATE)
 
 	const handleAction = useCallback(
@@ -118,6 +133,8 @@ export function AiAssistPanel({ docId, onMetaApplied }: AiAssistPanelProps) {
 				activeAction: meta.action,
 				headlines: [],
 				metaDescription: null,
+				dek: null,
+				dekApplied: false,
 				metaApplied: false,
 				takeawaysWritten: false,
 				locked: false,
@@ -142,7 +159,18 @@ export function AiAssistPanel({ docId, onMetaApplied }: AiAssistPanelProps) {
 				} else {
 					// Sync: takeaways or meta-description
 					const data = (await syncAi(meta.action, docId)) as Record<string, unknown>
-					if (meta.action === 'meta-description') {
+					if (meta.action === 'dek') {
+						const dek = typeof data.dek === 'string' ? data.dek : null
+						const written = data.written === true
+						if (dek && written) onDekApplied?.(dek)
+						setState((prev) => ({
+							...prev,
+							running: null,
+							dek,
+							dekApplied: Boolean(dek && written),
+							locked: data.locked === true,
+						}))
+					} else if (meta.action === 'meta-description') {
 						setState((prev) => ({
 							...prev,
 							running: null,
@@ -167,7 +195,7 @@ export function AiAssistPanel({ docId, onMetaApplied }: AiAssistPanelProps) {
 				}))
 			}
 		},
-		[docId],
+		[docId, onDekApplied],
 	)
 
 	const applyMeta = useCallback(async () => {
@@ -262,6 +290,30 @@ export function AiAssistPanel({ docId, onMetaApplied }: AiAssistPanelProps) {
 				)}
 
 			{/* Result pane — sync: meta description */}
+			{state.activeAction === 'dek' && state.dek !== null && (
+				<div style={resultPane}>
+					<div style={resultHeader}>
+						<span style={{ fontSize: 12, fontWeight: 600, color: 'var(--ink-soft)' }}>
+							Suggested subheading
+						</span>
+						{state.locked && (
+							<span style={{ fontSize: 11, color: 'var(--amber)', marginLeft: 6 }}>
+								field locked — not written
+							</span>
+						)}
+					</div>
+					<p style={{ fontSize: 13, color: 'var(--ink)', lineHeight: 1.5, margin: '6px 0' }}>
+						{state.dek}
+					</p>
+					{state.dekApplied && (
+						<span style={{ fontSize: 12, color: 'var(--green)' }}>
+							<Icon name="checkCircle" size={13} style={{ marginRight: 4 }} />
+							Applied to subheading
+						</span>
+					)}
+				</div>
+			)}
+
 			{state.activeAction === 'meta-description' && state.metaDescription !== null && (
 				<div style={resultPane}>
 					<div style={resultHeader}>