@raidiant/notifai 2.0.2 → 4.0.0

package/src/invocation-context.ts

@@ -0,0 +1,176 @@
+import { execFileSync } from 'node:child_process'
+import path from 'node:path'
+import {
+  sessionLabelFromId,
+  type SourceContextT,
+} from '@raidiant/notifai-protocol'
+import type { Harness } from './harnesses.js'
+
+export type GitCommand = (cwd: string, args: readonly string[]) => string | null
+
+const runGit: GitCommand = (cwd, args) => {
+  try {
+    return execFileSync('git', ['-C', cwd, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2_000,
+      windowsHide: true,
+    }).trim()
+  } catch {
+    return null
+  }
+}
+
+/** The useful, privacy-safe context inferred from one invocation directory. */
+export interface InvocationContext {
+  project: string | null
+  branch?: string
+  worktree?: string
+}
+
+/** Contract-valid Project slug, or null when the name has no safe characters. */
+export function projectSlugFrom(name: string): string | null {
+  const slug = name
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9._-]+/g, '-')
+    .replaceAll(/^[^a-z0-9]+|[^a-z0-9._-]+$/g, '')
+    .slice(0, 64)
+  return slug.length > 0 && /^[a-z0-9]/.test(slug) ? slug : null
+}
+
+function usesWindowsPaths(...values: string[]): boolean {
+  return values.some((value) => /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value))
+}
+
+function pathApi(...values: string[]): typeof path.posix | typeof path.win32 {
+  return usesWindowsPaths(...values) ? path.win32 : path.posix
+}
+
+/** Basename that can be fixture-tested for POSIX, drive, and UNC paths on any OS. */
+export function portableBasename(value: string): string {
+  const api = pathApi(value)
+  return api.basename(api.normalize(value))
+}
+
+function resolveGitPath(cwd: string, value: string): string {
+  const api = pathApi(cwd, value)
+  return api.isAbsolute(value) ? api.normalize(value) : api.resolve(cwd, value)
+}
+
+function samePath(left: string, right: string): boolean {
+  const api = pathApi(left, right)
+  const normalizedLeft = api.normalize(left)
+  const normalizedRight = api.normalize(right)
+  return api === path.win32
+    ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    : normalizedLeft === normalizedRight
+}
+
+/** Truncate a display string by Unicode characters and keep the ellipsis inside the bound. */
+export function truncateContext(value: string, maxLength: number): string {
+  const characters = Array.from(value)
+  if (characters.length <= maxLength) return value
+  return `${characters.slice(0, Math.max(0, maxLength - 1)).join('')}…`
+}
+
+/**
+ * Infer stable Project identity plus branch/worktree display context.
+ *
+ * Linked worktrees share the parent of Git's common directory, while a non-Git
+ * directory falls back to its own basename. Only basenames and branch names are
+ * returned; no absolute path can leave this function.
+ */
+export function inferInvocationContext(
+  cwd: string,
+  git: GitCommand = runGit,
+): InvocationContext {
+  const commonRaw = git(cwd, ['rev-parse', '--git-common-dir'])
+  if (commonRaw === null || commonRaw === '') {
+    return { project: projectSlugFrom(portableBasename(cwd)) }
+  }
+
+  const commonDir = resolveGitPath(cwd, commonRaw)
+  const api = pathApi(cwd, commonDir)
+  const gitDirRaw = git(cwd, ['rev-parse', '--git-dir'])
+  const topLevelRaw = git(cwd, ['rev-parse', '--show-toplevel'])
+  const linked =
+    gitDirRaw !== null &&
+    gitDirRaw !== '' &&
+    !samePath(resolveGitPath(cwd, gitDirRaw), commonDir)
+
+  // In an ordinary checkout the worktree root is the useful Project root. A
+  // linked worktree needs its shared repository identity instead: standard Git
+  // stores that in <main>/.git, while submodules and --separate-git-dir use a
+  // named common directory whose basename is the only stable, path-free label.
+  // Treating every common directory as `.git` would infer `modules` or `public`
+  // for submodules — an implementation detail, not the repository's identity.
+  const commonName = api.basename(commonDir)
+  const projectName = linked
+    ? commonName.toLowerCase() === '.git'
+      ? api.basename(api.dirname(commonDir))
+      : commonName
+    : topLevelRaw !== null && topLevelRaw !== ''
+      ? portableBasename(topLevelRaw)
+      : commonName.toLowerCase() === '.git'
+        ? api.basename(api.dirname(commonDir))
+        : commonName
+  const project = projectSlugFrom(projectName)
+
+  const branchRaw = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  const branch =
+    branchRaw === null || branchRaw === '' || branchRaw === 'HEAD'
+      ? undefined
+      : truncateContext(branchRaw, 128)
+
+  const worktree =
+    linked && topLevelRaw !== null && topLevelRaw !== ''
+      ? truncateContext(portableBasename(topLevelRaw), 64)
+      : undefined
+
+  return {
+    project,
+    ...(branch !== undefined ? { branch } : {}),
+    ...(worktree !== undefined && worktree !== '' ? { worktree } : {}),
+  }
+}
+
+export interface SourceContextInput {
+  env: NodeJS.ProcessEnv
+  invocation: InvocationContext
+  sessionId?: string
+  sessionLabel?: string
+  activeHarness?: { harness: Harness; sessionId?: string }
+}
+
+export type SourceContextBuild =
+  | { ok: true; source?: SourceContextT }
+  | { ok: false; error: string }
+
+/** Resolve per-field source precedence without fabricating session identity. */
+export function buildSourceContext(input: SourceContextInput): SourceContextBuild {
+  const sessionId =
+    input.sessionId ?? input.env['NOTIFAI_SESSION_ID'] ?? input.activeHarness?.sessionId
+  const explicitLabel = input.sessionLabel ?? input.env['NOTIFAI_SESSION_LABEL']
+  if (explicitLabel !== undefined && (sessionId === undefined || sessionId === '')) {
+    return {
+      ok: false,
+      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact session id.',
+    }
+  }
+  if (sessionId === '') {
+    return { ok: false, error: '--session-id must not be empty.' }
+  }
+
+  const sessionLabel =
+    sessionId === undefined ? undefined : (explicitLabel ?? sessionLabelFromId(sessionId))
+  const source: SourceContextT = {
+    ...(sessionId !== undefined ? { session_id: sessionId } : {}),
+    ...(sessionLabel !== undefined ? { session_label: sessionLabel } : {}),
+    ...(sessionId !== undefined && input.activeHarness !== undefined
+      ? { harness: input.activeHarness.harness }
+      : {}),
+    ...(input.invocation.branch !== undefined ? { branch: input.invocation.branch } : {}),
+    ...(input.invocation.worktree !== undefined ? { worktree: input.invocation.worktree } : {}),
+  }
+  return Object.keys(source).length === 0 ? { ok: true } : { ok: true, source }
+}

package/src/main.ts

@@ -262,18 +262,29 @@ const send = program
   .summary('Send a notification')
   .description('Send a notification')
   .optionsGroup(SEND_GROUP.content)
-  .requiredOption('--title <title>', 'notification title')
-  .requiredOption('--body <body>', 'notification body')
-  .option('--subtitle <subtitle>', 'a line between the title and the body')
-  .option('--detail <markdown>', 'long-form markdown shown only in the app, never on the banner')
-  .option('--detail-file <path>', 'read --detail from a file (use - for stdin)')
-  .option('--image <path|url|media_id>', 'upload or attach an image')
+  .requiredOption('--title <title>', 'brief title whose substance is immediately understandable')
+  .option('--body <markdown>', 'canonical Markdown body')
+  .option('--body-file <path>', 'read the canonical Markdown body from a file (use - for stdin)')
+  .option('--subtitle <subtitle>', 'a plain-text line between the title and body')
+  .option(
+    '--image <path|url|media_id>',
+    'upload or attach an image in collection order (repeatable, maximum 8)',
+    (v: string, all: string[]) => [...all, v],
+    [],
+  )
+  .option(
+    '--image-alt <text>',
+    'alt text paired with --image occurrences by position (repeatable)',
+    (v: string, all: string[]) => [...all, v],
+    [],
+  )
   .optionsGroup(SEND_GROUP.routing)
-  .option('--kind <kind>', 'what this is: update (default) | done | question (requires --reply)')
-  .option('--project <id>', 'project identifier, e.g. my-app (lazily registered)')
+  .option('--kind <kind>', 'what this is: update (default) | done | failed | blocked | question (requires --reply)')
+  .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
   .option('--device <id>', 'target a device id (repeatable)', (v: string, all: string[]) => [...all, v], [])
   .option('--all', 'target all routable devices (overrides configured devices)')
-  .option('--session <id>', 'session identity (env: NOTIFAI_SESSION); presentation varies by surface')
+  .option('--session-id <id>', 'opaque exact-session override (env: NOTIFAI_SESSION_ID)')
+  .option('--session-label <text>', 'human session label override (env: NOTIFAI_SESSION_LABEL)')
   .option('--event <event>', 'agent event name, e.g. tests_passed')
   .optionsGroup(SEND_GROUP.presentation)
   .option('--collapse-key <key>', 'replace earlier notifications with the same key')
@@ -294,8 +305,8 @@ const send = program
   // a message pointing at `ask` instead of "unknown option".
   .option('--no-block', 'rejected with --reply; use `notifai ask` to ask and end the turn')
   .optionsGroup(SEND_GROUP.advanced)
-  .option('--sound <sound>', 'override kind profile / saved config: default | done | attention | alert | none')
-  .option('--level <level>', 'override kind profile / saved config: passive | active | time_sensitive')
+  .option('--sound <sound>', 'override saved sound: default | done | attention | alert | none')
+  .option('--level <level>', 'override saved interruption level: passive | active | time_sensitive')
   .option('--wait <seconds>', 'how long to wait for provider outcomes', (v: string) => Number(v))
   .option('--no-wait', 'return immediately after acceptance')
   .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[]) => [...all, v], [])
@@ -308,24 +319,22 @@ const send = program
     const wait = typeof opts['wait'] === 'number' ? opts['wait'] : undefined
     const noBlock = opts['block'] === false
     const sendOpts = { ...opts }
-    // Same empty-collector normalisation as `ask`.
-    if (Array.isArray(sendOpts['replyChoice']) && sendOpts['replyChoice'].length === 0) {
-      delete sendOpts['replyChoice']
+    // Commander collectors default to []; an empty list means "not passed".
+    for (const key of ['replyChoice', 'image', 'imageAlt']) {
+      if (Array.isArray(sendOpts[key]) && sendOpts[key].length === 0) delete sendOpts[key]
     }
     delete sendOpts['block']
-    // Long-form detail is usually a build log or a diff summary, which nobody
-    // wants to shell-escape onto a command line.
-    const detailFile = sendOpts['detailFile']
-    delete sendOpts['detailFile']
-    if (typeof detailFile === 'string') {
-      if (sendOpts['detail'] !== undefined) {
-        deps.io.err('Pass either --detail or --detail-file, not both.')
+    const bodyFile = sendOpts['bodyFile']
+    delete sendOpts['bodyFile']
+    if (typeof bodyFile === 'string') {
+      if (sendOpts['body'] !== undefined) {
+        deps.io.err('Pass either --body or --body-file, not both.')
         process.exit(2)
       }
       try {
-        sendOpts['detail'] = readFileSync(detailFile === '-' ? 0 : detailFile, 'utf8')
+        sendOpts['body'] = readFileSync(bodyFile === '-' ? 0 : bodyFile, 'utf8')
       } catch (err) {
-        deps.io.err(`Could not read ${detailFile}: ${String(err)}`)
+        deps.io.err(`Could not read ${bodyFile}: ${String(err)}`)
         process.exit(2)
       }
     }
@@ -337,7 +346,7 @@ const send = program
 
 send.addHelpText(
   'after',
-  `\nKind profiles apply automatically. Pass --sound or --level only to override them or saved user config:\n  update    sound none       level passive\n  done      sound done       level passive\n  question  sound attention  level active (--reply)\n`,
+  `\nKind describes status in the Companion Apps; it never chooses banner sound or interruption level.\nWithout --sound/--level or saved preferences, those fields are omitted for the destination to handle.\n`,
 )
 
 program
@@ -387,28 +396,46 @@ program
     (v: string, all: string[]) => [...all, v], [],
   )
   .option('--multi', 'with --choice, several answers may be selected')
-  .option('--detail <markdown>', 'long-form context shown only in the app, never on the banner')
-  .option('--detail-file <path>', 'read --detail from a file (use - for stdin)')
+  .option('--body <markdown>', 'optional Markdown context appended after the question block')
+  .option('--body-file <path>', 'read optional Markdown context from a file (use - for stdin)')
   .option('--form <path>', 'ask several questions as one form; JSON file (use - for stdin)')
-  .option('--session <id>', 'session id (default: the session working in this directory, else $NOTIFAI_SESSION)')
-  .action((question: string | undefined, opts: {
+  .option(
+    '--image <path|url|media_id>',
+    'upload or attach an image in collection order (repeatable, maximum 8)',
+    (v: string, all: string[]) => [...all, v],
+    [],
+  )
+  .option(
+    '--image-alt <text>',
+    'alt text paired with --image occurrences by position (repeatable)',
+    (v: string, all: string[]) => [...all, v],
+    [],
+  )
+  .option('--project <id>', 'project identifier override (otherwise configured or inferred)')
+  .option('--session-id <id>', 'opaque exact-session override (env: NOTIFAI_SESSION_ID)')
+  .option('--session-label <text>', 'human session label override (env: NOTIFAI_SESSION_LABEL)')
+  .action(async (question: string | undefined, opts: {
     choice?: string[]
     multi?: boolean
-    detail?: string
-    detailFile?: string
+    body?: string
+    bodyFile?: string
     form?: string
-    session?: string
+    image?: string[]
+    imageAlt?: string[]
+    project?: string
+    sessionId?: string
+    sessionLabel?: string
   }) => {
-    let detail = opts.detail
-    if (typeof opts.detailFile === 'string') {
-      if (detail !== undefined) {
-        deps.io.err('Pass either --detail or --detail-file, not both.')
+    let body = opts.body
+    if (typeof opts.bodyFile === 'string') {
+      if (body !== undefined) {
+        deps.io.err('Pass either --body or --body-file, not both.')
         process.exit(2)
       }
       try {
-        detail = readFileSync(opts.detailFile === '-' ? 0 : opts.detailFile, 'utf8')
+        body = readFileSync(opts.bodyFile === '-' ? 0 : opts.bodyFile, 'utf8')
       } catch (err) {
-        deps.io.err(`Could not read ${opts.detailFile}: ${String(err)}`)
+        deps.io.err(`Could not read ${opts.bodyFile}: ${String(err)}`)
         process.exit(2)
       }
     }
@@ -421,15 +448,19 @@ program
         process.exit(2)
       }
     }
-    // commander's collector defaults to []; an empty list means "not asked".
+    // Commander collectors default to []; an empty list means "not passed".
     const flags: Parameters<typeof askCommand>[2] = {
-      ...(opts.session !== undefined ? { session: opts.session } : {}),
       ...(opts.choice?.length ? { choice: opts.choice } : {}),
       ...(opts.multi ? { multi: true } : {}),
-      ...(detail !== undefined ? { detail } : {}),
+      ...(body !== undefined ? { body } : {}),
       ...(form !== undefined ? { form } : {}),
+      ...(opts.image?.length ? { image: opts.image } : {}),
+      ...(opts.imageAlt?.length ? { imageAlt: opts.imageAlt } : {}),
+      ...(opts.project !== undefined ? { project: opts.project } : {}),
+      ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
+      ...(opts.sessionLabel !== undefined ? { sessionLabel: opts.sessionLabel } : {}),
     }
-    process.exit(askCommand(deps, question, flags))
+    process.exit(await askCommand(deps, question, flags))
   })
 
 program

package/src/send.ts

@@ -2,16 +2,20 @@ import {
   CLI_SOUNDS,
   COLLAPSE_KEY_MAX_BYTES,
   INTERRUPTION_LEVELS,
+  MEDIA_MAX_ITEMS,
   NOTIFICATION_SCHEMA_VERSION,
   QUESTION_TEXT_MAX_LENGTH,
+  bannerExcerpt,
   type IosOptionsT,
   type LifecycleT,
   type MacosOptionsT,
+  type MediaItemT,
   type NotificationDraftT,
   NOTIFICATION_KINDS,
   PLATFORMS,
   type Platform,
   type QuestionT,
+  type SourceContextT,
   type SubmissionReceipt,
 } from '@raidiant/notifai-protocol'
 import type { CliConfig } from './config.js'
@@ -20,15 +24,17 @@ type CliSound = (typeof CLI_SOUNDS)[number]
 
 export interface SendFlags {
   title: string
+  /** The one canonical Markdown body. */
   body: string
   subtitle?: string
-  /** Long-form markdown for the app's detail view; never on the banner. */
-  detail?: string
   event?: string
-  /** What this notification is: update (default), done, or question. */
+  /** What this notification is; absent means update. */
   kind?: string
   project?: string
-  session?: string
+  /** Opaque exact-session override. */
+  sessionId?: string
+  /** Human-readable session label override. */
+  sessionLabel?: string
   device?: string[]
   all?: boolean
   ttl?: number
@@ -37,7 +43,15 @@ export interface SendFlags {
   threadId?: string
   level?: string
   data?: string[]
-  image?: string
+  /** Ready media ids in author-supplied order. Commands resolve paths and URLs first. */
+  image?: string[]
+  /** Optional alt text paired with images by position. */
+  imageAlt?: string[]
+  /**
+   * Complete canonical media manifest for internal callers that already froze
+   * uploads and alt text. Mutually exclusive with the CLI's parallel inputs.
+   */
+  media?: MediaItemT[]
   /** Enable the inline reply action for this Notification Request. */
   reply?: boolean
   /** How long the server accepts a reply after submission. */
@@ -67,33 +81,109 @@ export type DraftBuild =
   | { ok: true; draft: NotificationDraftT; platform: Platform }
   | { ok: false; error: string }
 
+/** Invocation-derived values beneath explicit and configured author input. */
+export interface DraftInvocation {
+  inferredProject?: string | null
+  source?: SourceContextT
+}
+
+const POSITIONAL_MEDIA_REFERENCE = /media:(\d+)(?![A-Za-z0-9_-])/g
+
+/** Validate media cardinality and positional alt pairing before any upload starts. */
+export function validateMediaInputs(
+  images: readonly string[] | undefined,
+  alts: readonly string[] | undefined,
+): string | null {
+  const imageCount = images?.length ?? 0
+  const imageAlts = alts ?? []
+  if (imageCount > MEDIA_MAX_ITEMS) return `Attach at most ${MEDIA_MAX_ITEMS} images.`
+  if (imageAlts.length > imageCount) {
+    return `Received ${imageAlts.length} --image-alt values for ${imageCount} --image values.`
+  }
+  if (imageAlts.some((alt) => alt.length < 1 || alt.length > 256)) {
+    return '--image-alt must be 1-256 characters.'
+  }
+  return null
+}
+
+/** Validate a frozen value-object manifest without collapsing sparse alt text. */
+function validateMediaManifest(media: readonly MediaItemT[]): string | null {
+  if (media.length > MEDIA_MAX_ITEMS) return `Attach at most ${MEDIA_MAX_ITEMS} images.`
+  if (media.some((item) => item.alt !== undefined && (item.alt.length < 1 || item.alt.length > 256))) {
+    return 'Media alt text must be 1-256 characters.'
+  }
+  return null
+}
+
+/** Rewrite authorable 1-based media positions to canonical ready media ids. */
+export function rewriteMediaReferences(
+  body: string,
+  mediaIds: readonly string[],
+): { ok: true; body: string } | { ok: false; error: string } {
+  let error: string | undefined
+  const rewritten = body.replace(POSITIONAL_MEDIA_REFERENCE, (reference, digits: string) => {
+    const position = Number(digits)
+    if (
+      !Number.isSafeInteger(position) ||
+      position < 1 ||
+      position > MEDIA_MAX_ITEMS ||
+      digits !== String(position) ||
+      mediaIds[position - 1] === undefined
+    ) {
+      error = `Body reference "${reference}" has no matching --image occurrence.`
+      return reference
+    }
+    return `media:${mediaIds[position - 1]}`
+  })
+  return error === undefined ? { ok: true, body: rewritten } : { ok: false, error }
+}
+
 /** Merge flags over resolved config into a Notification Request draft. */
-export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
+export function buildDraft(
+  config: CliConfig,
+  flags: SendFlags,
+  invocation: DraftInvocation = {},
+): DraftBuild {
   if (!flags.title || !flags.body) return { ok: false, error: 'Both --title and --body are required.' }
   const platform = resolvePlatform(flags.platform)
   if (!platform) {
     return { ok: false, error: `Unknown platform "${flags.platform}" — use ${PLATFORMS.join(' or ')}.` }
   }
 
+  if (flags.media !== undefined && (flags.image !== undefined || flags.imageAlt !== undefined)) {
+    return { ok: false, error: 'Internal media manifests cannot be combined with --image or --image-alt.' }
+  }
+  const imageIds = flags.media?.map((item) => item.media_id) ?? flags.image ?? []
+  const imageAlts = flags.imageAlt ?? []
+  const mediaInputError =
+    flags.media === undefined
+      ? validateMediaInputs(imageIds, imageAlts)
+      : validateMediaManifest(flags.media)
+  if (mediaInputError !== null) return { ok: false, error: mediaInputError }
+  const media =
+    flags.media ??
+    imageIds.map((media_id, index) => ({
+      media_id,
+      ...(imageAlts[index] !== undefined ? { alt: imageAlts[index] } : {}),
+    }))
+  const body = rewriteMediaReferences(flags.body, imageIds)
+  if (!body.ok) return body
+
   const deviceIds = flags.all ? null : (flags.device?.length ? flags.device : config.devices.value)
   const targets: NotificationDraftT['targets'] =
     deviceIds && deviceIds.length > 0 ? { mode: 'selected', device_ids: deviceIds } : { mode: 'all' }
 
-  const effectiveKind = flags.reply ? 'question' : (flags.kind ?? 'update')
-  const profile = KIND_PROFILES[effectiveKind as keyof typeof KIND_PROFILES]
-  const configuredSound = config.sound.source === 'default' ? undefined : config.sound.value
-  const sound = flags.sound ?? configuredSound ?? profile?.sound
+  // Kind is semantic status metadata for Companion presentation. It never
+  // chooses native-banner attention; only an explicit flag or saved preference
+  // may add sound or interruption fields to the platform payload.
+  const sound = flags.sound ?? config.sound.value
   if (sound !== null && sound !== undefined && !CLI_SOUNDS.includes(sound as CliSound)) {
     return {
       ok: false,
       error: `Unknown sound "${sound}" — supported: ${CLI_SOUNDS.map((value) => `"${value}"`).join(', ')}.`,
     }
   }
-  const configuredLevel =
-    config.interruption_level.source === 'default'
-      ? undefined
-      : config.interruption_level.value
-  const level = flags.level ?? configuredLevel ?? profile?.level
+  const level = flags.level ?? config.interruption_level.value
   if (
     level !== null &&
     level !== undefined &&
@@ -144,10 +234,7 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
     }
   }
 
-  const project = flags.project ?? config.project.value
-  // Harnesses can export NOTIFAI_SESSION once instead of passing the flag
-  // on every send.
-  const session = flags.session ?? process.env['NOTIFAI_SESSION']
+  const project = flags.project ?? config.project.value ?? invocation.inferredProject
 
   // Ids are derived from labels so an agent writing a one-liner does not have
   // to invent them, but they stay the stable thing it branches on afterwards.
@@ -161,19 +248,19 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
   if (flags.replyMulti && choices === null && flags.questions === undefined) {
     return { ok: false, error: '--reply-multi needs answers to select between; add --reply-choice.' }
   }
-  // The banner body doubles as the question text on a single-question send, so
-  // it inherits the question's readable-in-full bound; context beyond that
-  // belongs in --detail, which never rides the banner.
+  // A single reply question is the first readable block of the canonical body.
+  // Context may follow after a blank line without changing what the user answers.
+  const derivedQuestion = bannerExcerpt(body.body).split('\n', 1)[0]!.trim()
   if (
     flags.reply &&
     flags.questions === undefined &&
-    flags.body.length > QUESTION_TEXT_MAX_LENGTH
+    derivedQuestion.length > QUESTION_TEXT_MAX_LENGTH
   ) {
     return {
       ok: false,
       error:
-        `A question must be readable where it is answered: keep it within ${QUESTION_TEXT_MAX_LENGTH} ` +
-        'characters and put the longer context in --detail.',
+        `Keep the question within ${QUESTION_TEXT_MAX_LENGTH} characters and put ` +
+        'the longer context after a blank line — the first paragraph is the question.',
     }
   }
 
@@ -185,15 +272,12 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
       : {}),
     ...(flags.lifecycle !== undefined ? { lifecycle: flags.lifecycle } : {}),
     ...(project !== null && project !== undefined ? { project } : {}),
-    ...(session !== undefined && session !== '' ? { session } : {}),
+    ...(invocation.source !== undefined ? { source: invocation.source } : {}),
     presentation: {
       title: flags.title,
-      body: flags.body,
+      body: body.body,
       ...(flags.subtitle !== undefined ? { subtitle: flags.subtitle } : {}),
-      ...(flags.detail !== undefined && flags.detail.trim() !== ''
-        ? { detail: flags.detail }
-        : {}),
-      ...(flags.image !== undefined ? { image: { media_id: flags.image } } : {}),
+      ...(media.length > 0 ? { media } : {}),
     },
     targets,
     delivery: { ttl_seconds: ttl, collapse_key: collapse },
@@ -204,7 +288,7 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
             questions: flags.questions ?? [
               {
                 id: 'q1',
-                text: flags.body,
+                text: derivedQuestion,
                 ...(choices !== null ? { choices } : {}),
                 ...(flags.replyMulti ? { multi: true } : {}),
               },
@@ -223,12 +307,6 @@ export function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild {
   return { ok: true, draft, platform }
 }
 
-const KIND_PROFILES = {
-  update: { sound: 'none', level: 'passive' },
-  done: { sound: 'done', level: 'passive' },
-  question: { sound: 'attention', level: 'active' },
-} as const
-
 function resolvePlatform(value: string | undefined): Platform | null {
   if (value === undefined) return 'ios'
   return (PLATFORMS as readonly string[]).includes(value) ? (value as Platform) : null