@raidiant/notifai 3.0.1 → 4.0.0

package/CHANGELOG.md

@@ -8,6 +8,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
+## [4.0.0](https://github.com/Raidiant-io/notifai/compare/v3.0.1...v4.0.0) (2026-08-15)
+
+
+### ⚠ BREAKING CHANGES
+
+* **cli:** `--detail` and `--detail-file` are removed; the one canonical Markdown body is `--body` / `--body-file`. `--session` is removed, replaced by `--session-id` and `--session-label`. `--image` is now a repeatable ordered collection (max 8) with `--image-alt` for alt text.
+
+### Features
+
+* add unified notification content and source context ([3e6479a](https://github.com/Raidiant-io/notifai/commit/3e6479ae22c64c6886c1e919ba3183486e408596))
+* add unified notification content and source context ([2473ed5](https://github.com/Raidiant-io/notifai/commit/2473ed51df42b56652435c611a57f3751fa484f5))
+
+
+### Bug Fixes
+
+* attribute the unified-content break and propagate workspace dependency bumps ([cb438ce](https://github.com/Raidiant-io/notifai/commit/cb438cec76de9b393d7673554dc440a764887f76))
+* **cli:** document replacements for the removed send flags ([44af905](https://github.com/Raidiant-io/notifai/commit/44af90536a1e6fa5af2ec6b58a19ea68f2d76b96))
+* print server rejection details on command failures ([884fc78](https://github.com/Raidiant-io/notifai/commit/884fc78b62382ad23a49e1c5b92772dd1b8d574b))
+* print server rejection details on command failures ([c9ec4e4](https://github.com/Raidiant-io/notifai/commit/c9ec4e45130784fff7b8ab4da560899eaddffcc5))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @raidiant/notifai-protocol bumped from 0.6.0 to 1.0.0
+
 ## [3.0.1](https://github.com/Raidiant-io/notifai/compare/v3.0.0...v3.0.1) (2026-08-14)
 
 

package/README.md

@@ -32,10 +32,13 @@ project or the machine. An unattended caller must select one explicitly:
 notifai send --title "Deploy finished" --body "staging, 2m14s" --kind done
 ```
 
-Write for a lock screen. The title gets a couple of seconds of attention
-and usually has to carry the whole message; assume the body may never be
-read. Long-form content belongs in `--detail`, which never appears on the
-banner and is shown in the companion app for when you sit down.
+Write a brief title whose substance is immediately understandable; type lives
+in `--kind`, and Project identity is inferred from the invocation directory.
+The one body is always Markdown. Native banners show a bounded readable
+plain-text excerpt from it, while Companion Apps render the complete body. Use
+`--body-file <path|->` for long content. Repeat `--image` for an ordered image
+collection (up to eight), pair each with `--image-alt` for alt text, and use
+`media:1`, `media:2`, and so on for inline references.
 
 ## Asking you a question
 

package/dist/commands.d.ts

@@ -205,21 +205,29 @@ export interface AskFlags {
     choice?: string[];
     /** The single question is multi-select: several answers may be chosen. */
     multi?: boolean;
-    /** Long-form markdown context; shown in the app, never on the banner. */
-    detail?: string;
+    /** Optional Markdown context appended after the question block. */
+    body?: string;
     /** Raw JSON for a multi-question form; replaces the positional question. */
     form?: string;
-    session?: string;
+    image?: string[];
+    imageAlt?: string[];
+    project?: string;
+    sessionId?: string;
+    sessionLabel?: string;
+}
+export interface BuiltQuestions {
+    questions: QuestionT[];
+    /** Canonical Markdown body: question block first, optional context second. */
+    body: string;
 }
 /**
- * Turn ask input into the question set that will ride the push. Everything is
- * validated here, at registration, because the push happens inside a hook
- * where a rejection becomes a stderr note the agent never reads.
+ * Turn ask input into questions plus their canonical body. Everything is
+ * validated at registration because a later hook failure is easy to miss.
  */
 export declare function buildQuestions(flags: AskFlags, question: string | undefined): {
     ok: true;
     questions: QuestionT[];
-    detail?: string;
+    body: string;
 } | {
     ok: false;
     error: string;
@@ -229,7 +237,7 @@ export declare function buildQuestions(flags: AskFlags, question: string | undef
  * can ask in prose and end its turn; the terminal keeps the question to itself
  * for `ask_grace_seconds` before it reaches any device.
  */
-export declare function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number;
+export declare function askCommand(deps: CommandDeps, question: string | undefined, flags: AskFlags): number | Promise<number>;
 /** Record the one Agent Acknowledgement associated with a replied-to request. */
 export declare function acknowledgeCommand(deps: CommandDeps, requestId: string, flags: {
     text?: string;
@@ -314,7 +322,7 @@ export declare function logsCommand(deps: CommandDeps, flags: LogsFlags): number
  * Null when the build cannot establish its version; see `./release.js`.
  */
 export declare const SKILLS_SOURCE: string | null;
-/** Derive a contract-valid project slug from a directory name. */
+/** Derive a contract-valid project slug; init alone needs a non-empty fallback. */
 export declare function projectSlugFrom(name: string): string;
 export interface InitFlags {
     projectId?: string;

package/dist/commands.js

@@ -21,7 +21,8 @@ import { claudeWakeRoute, inspectClaudeInbox, systemClaudeWakeAdapters, } from '
 import { codexWakeRoute, inspectCodexResume, } from './codex-wake.js';
 import { inspectHookAdapter, installHookAdapter, isNpxAdapterTarget, } from './hook-adapter.js';
 import { isOurOpencodePlugin, opencodePluginSource, } from './opencode-plugin.js';
-import { CHOICE_USAGE, buildDraft, formatReceipt, parseChoices, receiptExitCode, slugify, } from './send.js';
+import { CHOICE_USAGE, buildDraft, formatReceipt, parseChoices, receiptExitCode, slugify, validateMediaInputs, } from './send.js';
+import { buildSourceContext, inferInvocationContext, projectSlugFrom as inferredProjectSlugFrom, } from './invocation-context.js';
 import { openUrl } from './platform.js';
 /** The invocation's logger, or one that discards everything. */
 export function log(deps) {
@@ -79,6 +80,18 @@ function reportError(deps, err, context = {}) {
     });
     if (err instanceof ApiCallError) {
         deps.io.err(`${err.code}: ${err.message}`);
+        // The server's field-level details were already being logged above, but
+        // stderr is the one surface an agent's next turn actually reads — so the
+        // diagnosis has to be on it, the same way the hook path prints it.
+        const paths = rejectedPaths(err.details);
+        if (paths.length > 0)
+            deps.io.err(`the server rejected: ${paths.join(', ')}`);
+        // A 422 on a request this CLI built is not a user error: the two sides
+        // disagree about the contract, in whichever direction. `doctor` says which.
+        if (err.status === 422) {
+            deps.io.err('this build sent a field the server did not accept — the CLI and server ' +
+                'disagree about the contract; check with `notifai doctor`');
+        }
         if (err.nextAction)
             deps.io.err(`next: ${err.nextAction}`);
         if (err.code === 'auth_required' || err.code === 'machine_revoked')
@@ -324,12 +337,42 @@ export async function capabilitiesCommand(deps, flags) {
 // ---------------------------------------------------------------------------
 // send / status
 // ---------------------------------------------------------------------------
+function resolveDraftInvocation(deps, flags, active) {
+    const inferred = inferInvocationContext(deps.cwd);
+    const source = buildSourceContext({
+        env: deps.env,
+        invocation: inferred,
+        ...(flags.sessionId !== undefined ? { sessionId: flags.sessionId } : {}),
+        ...(flags.sessionLabel !== undefined ? { sessionLabel: flags.sessionLabel } : {}),
+        ...(active === null
+            ? {}
+            : {
+                activeHarness: {
+                    harness: active.harness,
+                    ...(active.sessionId === undefined ? {} : { sessionId: active.sessionId }),
+                },
+            }),
+    });
+    if (!source.ok)
+        return source;
+    return {
+        ok: true,
+        invocation: {
+            inferredProject: inferred.project,
+            ...(source.source === undefined ? {} : { source: source.source }),
+        },
+    };
+}
 export async function sendCommand(deps, flags) {
     const hasReplyChoice = Array.isArray(flags.replyChoice)
         ? flags.replyChoice.length > 0
         : flags.replyChoice !== undefined;
-    if (flags.reply && flags.kind === 'done') {
-        deps.io.err('--kind done cannot be combined with --reply; a reply request is a question.');
+    if (flags.reply && flags.kind !== undefined && flags.kind !== 'question') {
+        deps.io.err(`--kind ${flags.kind} cannot be combined with --reply; a reply request is a question.`);
+        return EXIT.usage;
+    }
+    if (!flags.reply && flags.kind === 'question') {
+        deps.io.err('--kind question requires --reply so the question can be answered.');
         return EXIT.usage;
     }
     if (!flags.reply &&
@@ -366,23 +409,39 @@ export async function sendCommand(deps, flags) {
         deps.io.err(`--reply-window must be an integer from 60 to ${REPLY_MAX_WINDOW_SECONDS} seconds.`);
         return EXIT.usage;
     }
+    const mediaInputError = validateMediaInputs(flags.image, flags.imageAlt);
+    if (mediaInputError !== null) {
+        deps.io.err(mediaInputError);
+        return EXIT.usage;
+    }
     const config = loadLoggedConfig(deps, {
         cwd: deps.cwd,
         env: deps.env,
         flags: { base_url: flags.baseUrl, wait_seconds: flags.wait },
     });
+    const source = resolveDraftInvocation(deps, flags, activeHarnessSession(deps.env, deps.cwd, (deps.now ?? Date.now)()));
+    if (!source.ok) {
+        deps.io.err(source.error);
+        return EXIT.usage;
+    }
     const authed = authedClient(deps, config);
     if (!authed)
         return EXIT.auth;
-    if (flags.image !== undefined && !flags.image.startsWith('med_')) {
-        const uploaded = await uploadImage(deps, authed.client, flags.image);
+    const mediaIds = [];
+    for (const image of flags.image ?? []) {
+        if (image.startsWith('med_')) {
+            mediaIds.push(image);
+            continue;
+        }
+        const uploaded = await uploadImage(deps, authed.client, image);
         if (!uploaded.ok) {
             deps.io.err(uploaded.error);
             return uploaded.exit;
         }
-        flags = { ...flags, image: uploaded.mediaId };
+        mediaIds.push(uploaded.mediaId);
     }
-    const build = buildDraft(config, flags);
+    flags = { ...flags, image: mediaIds };
+    const build = buildDraft(config, flags, source.invocation);
     if (!build.ok) {
         deps.io.err(build.error);
         return EXIT.usage;
@@ -529,12 +588,8 @@ function emitSendWarnings(deps, flags, config) {
     if (flags.title.length > 40) {
         deps.io.err(`Heads up: this title is ${flags.title.length} characters; notification titles work best around 40 characters or fewer.`);
     }
-    if (looksLikeMarkdown(flags.body)) {
-        deps.io.err('Heads up: --body looks like Markdown, but banners show plain text. Put long-form Markdown in --detail or --detail-file.');
-    }
-    const effectiveKind = flags.reply ? 'question' : (flags.kind ?? 'update');
-    if (effectiveKind === 'update' && /^(done|failed)\b/i.test(flags.title.trim())) {
-        deps.io.err(`Heads up: this title announces completion but the notification kind is update. Use --kind done for finished work.`);
+    if (/^(?:update|done|question|failed|blocked)\s*(?:[·:—-]|$)/i.test(flags.title.trim())) {
+        deps.io.err('Heads up: keep the title to the specific substance. Put notification type in --kind; project identity is inferred separately.');
     }
     if (flags.collapseKey === undefined &&
         config.collapse_key.value !== null &&
@@ -545,9 +600,6 @@ function emitSendWarnings(deps, flags, config) {
         deps.io.err('Heads up: this explicit --ttl is longer than 72 hours; stale notifications may arrive after they are useful.');
     }
 }
-function looksLikeMarkdown(value) {
-    return /(?:^|\n)\s{0,3}(?:#{1,6}\s|[-+*]\s|>\s|\d+\.\s|```)|(?:\*\*|__|~~|`)[^\n]+(?:\*\*|__|~~|`)|\[[^\]]+\]\([^)]+\)/m.test(value);
-}
 export async function repliesCommand(deps, requestedId, flags) {
     const waitSeconds = flags.wait ?? 0;
     const afterSeq = flags.after ?? 0;
@@ -1251,9 +1303,8 @@ function rejectedPaths(details) {
         .slice(0, 5);
 }
 /**
- * Turn ask input into the question set that will ride the push. Everything is
- * validated here, at registration, because the push happens inside a hook
- * where a rejection becomes a stderr note the agent never reads.
+ * Turn ask input into questions plus their canonical body. Everything is
+ * validated at registration because a later hook failure is easy to miss.
  */
 export function buildQuestions(flags, question) {
     if (flags.form !== undefined) {
@@ -1265,21 +1316,41 @@ export function buildQuestions(flags, question) {
             parsed = JSON.parse(flags.form);
         }
         catch {
-            return { ok: false, error: '--form must be JSON: {"questions": [{"text", "choices"?, "multi"?}], "detail"?}.' };
+            return {
+                ok: false,
+                error: '--form must be JSON: {"questions": [{"text", "choices"?, "multi"?}], "body"?}.',
+            };
         }
-        if (typeof parsed !== 'object' || parsed === null || !Array.isArray(parsed.questions)) {
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
             return { ok: false, error: '--form needs a "questions" array (1-4 entries).' };
         }
-        const form = parsed;
-        if (form.questions.length < 1 || form.questions.length > REPLY_MAX_QUESTIONS) {
-            return { ok: false, error: `A form asks 1-${REPLY_MAX_QUESTIONS} questions; this one has ${form.questions.length}.` };
+        const record = parsed;
+        const unknownKeys = Object.keys(record).filter((key) => key !== 'questions' && key !== 'body');
+        if (unknownKeys.length > 0) {
+            return {
+                ok: false,
+                error: `Unknown --form ${unknownKeys.length === 1 ? 'key' : 'keys'}: ${unknownKeys.join(', ')}. Use "body" for Markdown context.`,
+            };
+        }
+        if (!Array.isArray(record['questions'])) {
+            return { ok: false, error: '--form needs a "questions" array (1-4 entries).' };
+        }
+        const formQuestions = record['questions'];
+        if (formQuestions.length < 1 || formQuestions.length > REPLY_MAX_QUESTIONS) {
+            return {
+                ok: false,
+                error: `A form asks 1-${REPLY_MAX_QUESTIONS} questions; this one has ${formQuestions.length}.`,
+            };
+        }
+        if (record['body'] !== undefined && typeof record['body'] !== 'string') {
+            return { ok: false, error: '"body" must be a Markdown string.' };
         }
-        if (form.detail !== undefined && typeof form.detail !== 'string') {
-            return { ok: false, error: '"detail" must be a markdown string.' };
+        if (flags.body !== undefined && record['body'] !== undefined) {
+            return { ok: false, error: 'Pass form context in either --body or the form "body" key, not both.' };
         }
         const questions = [];
         const usedIds = new Set();
-        for (const [index, entry] of form.questions.entries()) {
+        for (const [index, entry] of formQuestions.entries()) {
             if (typeof entry !== 'object' || entry === null || typeof entry.text !== 'string') {
                 return { ok: false, error: `Question ${index + 1} needs a "text" string.` };
             }
@@ -1289,7 +1360,15 @@ export function buildQuestions(flags, question) {
                 return { ok: false, error: `Question ${index + 1}: ${built.error}` };
             questions.push(built.question);
         }
-        return { ok: true, questions, ...(form.detail !== undefined ? { detail: form.detail } : {}) };
+        const context = flags.body ?? record['body'];
+        const questionBlock = questions.map((entry, index) => `${index + 1}. ${entry.text}`).join('\n');
+        return {
+            ok: true,
+            questions,
+            body: context !== undefined && context.trim() !== ''
+                ? `${questionBlock}\n\n${context}`
+                : questionBlock,
+        };
     }
     if (question === undefined || question.trim() === '') {
         return { ok: false, error: 'The question cannot be empty.' };
@@ -1297,10 +1376,13 @@ export function buildQuestions(flags, question) {
     const built = buildOneQuestion(question, flags.choice, flags.multi === true, 0, new Set());
     if ('error' in built)
         return { ok: false, error: built.error };
+    const context = flags.body;
     return {
         ok: true,
         questions: [built.question],
-        ...(flags.detail !== undefined && flags.detail.trim() !== '' ? { detail: flags.detail } : {}),
+        body: context !== undefined && context.trim() !== ''
+            ? `${built.question.text}\n\n${context}`
+            : built.question.text,
     };
 }
 function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
@@ -1310,7 +1392,7 @@ function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
     if (trimmed.length > QUESTION_TEXT_MAX_LENGTH) {
         return {
             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.`,
+                `${QUESTION_TEXT_MAX_LENGTH} characters and put the longer context in --body.`,
         };
     }
     const choices = parseChoices(choiceLabels);
@@ -1332,6 +1414,108 @@ function buildOneQuestion(text, choiceLabels, multi, index, usedIds) {
         },
     };
 }
+function buildAskDraft(config, built, flags, invocation, mediaIds) {
+    const result = buildDraft(config, {
+        title: built.questions[0].text,
+        body: built.body,
+        ...(flags.project !== undefined ? { project: flags.project } : {}),
+        ...(mediaIds.length > 0 ? { image: mediaIds } : {}),
+        ...(flags.imageAlt !== undefined ? { imageAlt: flags.imageAlt } : {}),
+        reply: true,
+        questions: built.questions,
+    }, invocation);
+    if (!result.ok)
+        return result;
+    const capabilities = CAPABILITIES_V1.describe(result.platform);
+    if (capabilities === null)
+        return { ok: false, error: 'No iOS capability contract is available.' };
+    const validation = validateDraft(result.draft, capabilities);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            error: validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join('\n'),
+        };
+    }
+    return { ok: true, draft: result.draft };
+}
+function recordRegisteredQuestion(deps, sessionId, built, draft) {
+    try {
+        registerQuestion(sessionId, deps.env, {
+            question: built.questions[0].text,
+            questions: built.questions,
+            body: draft.presentation.body,
+            ...(draft.project !== undefined ? { project: draft.project } : {}),
+            ...(draft.source !== undefined ? { source: draft.source } : {}),
+            ...(draft.presentation.media !== undefined ? { media: draft.presentation.media } : {}),
+        }, (deps.now ?? Date.now)());
+    }
+    catch (err) {
+        log(deps).error('ask.registered', { ok: false, session: sessionId, message: String(err) });
+        deps.io.err(`Could not register the question: ${err instanceof Error ? err.message : String(err)}`);
+        return EXIT.failed;
+    }
+    log(deps).info('ask.registered', {
+        ok: true,
+        session: sessionId,
+        questions: built.questions.length,
+        text: built.questions[0].text,
+        choices: built.questions[0].choices?.length ?? 0,
+        media: draft.presentation.media?.length ?? 0,
+    });
+    for (const [index, entry] of built.questions.entries()) {
+        const prefix = built.questions.length > 1 ? `${index + 1}. ` : '';
+        if (entry.choices !== undefined) {
+            const kind = entry.multi === true ? 'answers offered (several may be chosen)' : 'answers offered';
+            deps.io.out(`${prefix}${entry.text} — ${kind}: ${entry.choices.map((choice) => choice.label).join(' / ')}`);
+        }
+        else if (built.questions.length > 1) {
+            deps.io.out(`${prefix}${entry.text} — free text`);
+        }
+    }
+    deps.io.out(built.questions.length > 1
+        ? `${built.questions.length} questions registered as one form. Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
+        : 'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.');
+    deps.io.out('Before ending this turn, pre-commit in your own words to the work you will resume:');
+    for (const [index, entry] of built.questions.entries()) {
+        const questionPrefix = built.questions.length > 1 ? `Question ${index + 1}, ` : '';
+        if (entry.choices !== undefined) {
+            for (const choice of entry.choices) {
+                deps.io.out(`- ${questionPrefix}If the answer is ${JSON.stringify(choice.label)}: state the concrete work you will resume.`);
+            }
+            deps.io.out(`- ${questionPrefix}For an unexpected typed answer: state how it will determine the concrete work you resume.`);
+        }
+        else {
+            deps.io.out(`- ${questionPrefix}For the free-text answer: state how its content will determine the concrete work you resume.`);
+        }
+    }
+    deps.io.out('When the answer arrives, resume the matching work without asking the user to confirm again. Frame this as work you will resume, not as approval you receive.');
+    deps.io.out('A Notifai answer cannot answer a harness permission prompt or interactive picker; leave those to the harness and user.');
+    return EXIT.ok;
+}
+async function uploadAskMedia(deps, config, sessionId, built, flags, invocation) {
+    const authed = authedClient(deps, config);
+    if (!authed)
+        return EXIT.auth;
+    const mediaIds = [];
+    for (const image of flags.image ?? []) {
+        if (image.startsWith('med_')) {
+            mediaIds.push(image);
+            continue;
+        }
+        const uploaded = await uploadImage(deps, authed.client, image);
+        if (!uploaded.ok) {
+            deps.io.err(uploaded.error);
+            return uploaded.exit;
+        }
+        mediaIds.push(uploaded.mediaId);
+    }
+    const ready = buildAskDraft(config, built, flags, invocation, mediaIds);
+    if (!ready.ok) {
+        deps.io.err(ready.error);
+        return EXIT.usage;
+    }
+    return recordRegisteredQuestion(deps, sessionId, built, ready.draft);
+}
 /**
  * Registers a question for turn-end routing. Returns immediately so the agent
  * can ask in prose and end its turn; the terminal keeps the question to itself
@@ -1346,6 +1530,11 @@ export function askCommand(deps, question, flags) {
         deps.io.err(built.error);
         return EXIT.usage;
     }
+    const mediaInputError = validateMediaInputs(flags.image, flags.imageAlt);
+    if (mediaInputError !== null) {
+        deps.io.err(mediaInputError);
+        return EXIT.usage;
+    }
     const routingConfig = loadConfig({ cwd: deps.cwd, env: deps.env });
     if (!routingConfig.ask_notifications.value) {
         deps.io.err('Question routing is disabled by ask_notifications=false; enable it or use a blocking `notifai send --reply` question.');
@@ -1383,10 +1572,6 @@ export function askCommand(deps, question, flags) {
             }
             return EXIT.usage;
         }
-        if (flags.session !== undefined && flags.session !== active.sessionId) {
-            deps.io.err(`Question routing is not ready: --session ${flags.session} does not match the exact active ${active.label} session ${active.sessionId}; refusing cross-session routing.`);
-            return EXIT.usage;
-        }
         const routeProblems = activeQuestionRouteProblems(deps, active, installations);
         if (routeProblems.length > 0) {
             for (const problem of routeProblems)
@@ -1410,57 +1595,27 @@ export function askCommand(deps, question, flags) {
             deps.io.err(line);
         return EXIT.usage;
     }
-    try {
-        registerQuestion(sessionId, deps.env, {
-            question: built.questions[0].text,
-            questions: built.questions,
-            ...(built.detail !== undefined ? { detail: built.detail } : {}),
-        }, (deps.now ?? Date.now)());
+    const source = resolveDraftInvocation(deps, flags, active);
+    if (!source.ok) {
+        deps.io.err(source.error);
+        return EXIT.usage;
     }
-    catch (err) {
-        log(deps).error('ask.registered', { ok: false, session: sessionId, message: String(err) });
-        deps.io.err(`Could not register the question: ${err instanceof Error ? err.message : String(err)}`);
-        return EXIT.failed;
+    if (source.invocation.source?.session_id !== sessionId) {
+        deps.io.err(`Question routing is not ready: --session-id or NOTIFAI_SESSION_ID does not match the exact active ${active.label} session; refusing cross-session routing.`);
+        return EXIT.usage;
     }
-    // `ask` returns immediately and the push happens later inside a hook, so this
-    // is the only local evidence that the question was ever registered — the
-    // starting point for "the agent asked, and nothing ever reached my phone".
-    log(deps).info('ask.registered', {
-        ok: true,
-        session: sessionId,
-        questions: built.questions.length,
-        text: built.questions[0].text,
-        choices: built.questions[0].choices?.length ?? 0,
-    });
-    for (const [index, entry] of built.questions.entries()) {
-        const prefix = built.questions.length > 1 ? `${index + 1}. ` : '';
-        if (entry.choices !== undefined) {
-            const kind = entry.multi === true ? 'answers offered (several may be chosen)' : 'answers offered';
-            deps.io.out(`${prefix}${entry.text} — ${kind}: ${entry.choices.map((choice) => choice.label).join(' / ')}`);
-        }
-        else if (built.questions.length > 1) {
-            deps.io.out(`${prefix}${entry.text} — free text`);
-        }
+    // Placeholders let every body, source, project, media, and payload limit fail
+    // before an upload starts. The real ids replace them only after this passes.
+    const placeholders = (flags.image ?? []).map((_, index) => `med_pending_${index + 1}`);
+    const preflight = buildAskDraft(routingConfig, built, flags, source.invocation, placeholders);
+    if (!preflight.ok) {
+        deps.io.err(preflight.error);
+        return EXIT.usage;
     }
-    deps.io.out(built.questions.length > 1
-        ? `${built.questions.length} questions registered as one form. Ask them in the conversation, state the concrete work you will resume for their answers, then end your turn.`
-        : 'Question registered. Ask it in the conversation, state the concrete work you will resume when the answer arrives, then end your turn.');
-    deps.io.out('Before ending this turn, pre-commit in your own words to the work you will resume:');
-    for (const [index, entry] of built.questions.entries()) {
-        const questionPrefix = built.questions.length > 1 ? `Question ${index + 1}, ` : '';
-        if (entry.choices !== undefined) {
-            for (const choice of entry.choices) {
-                deps.io.out(`- ${questionPrefix}If the answer is ${JSON.stringify(choice.label)}: state the concrete work you will resume.`);
-            }
-            deps.io.out(`- ${questionPrefix}For an unexpected typed answer: state how it will determine the concrete work you resume.`);
-        }
-        else {
-            deps.io.out(`- ${questionPrefix}For the free-text answer: state how its content will determine the concrete work you resume.`);
-        }
+    if ((flags.image?.length ?? 0) > 0) {
+        return uploadAskMedia(deps, routingConfig, sessionId, built, flags, source.invocation);
     }
-    deps.io.out('When the answer arrives, resume the matching work without asking the user to confirm again. Frame this as work you will resume, not as approval you receive.');
-    deps.io.out('A Notifai answer cannot answer a harness permission prompt or interactive picker; leave those to the harness and user.');
-    return EXIT.ok;
+    return recordRegisteredQuestion(deps, sessionId, built, preflight.draft);
 }
 /**
  * Every harness marker present in this environment, in declared order.
@@ -2599,14 +2754,9 @@ async function skillReadiness(deps, selectedScope) {
         },
     };
 }
-/** Derive a contract-valid project slug from a directory name. */
+/** Derive a contract-valid project slug; init alone needs a non-empty fallback. */
 export function projectSlugFrom(name) {
-    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 : 'project';
+    return inferredProjectSlugFrom(name) ?? 'project';
 }
 /** Long enough for a first TestFlight install; keep-waiting extends another budget. */
 const DEVICE_BRIDGE_TIMEOUT_MS = 10 * 60 * 1000;
@@ -3265,29 +3415,40 @@ async function contractCheck(client) {
     }
 }
 function projectReadiness(deps, config) {
-    const configPath = path.join(deps.cwd, '.notifai', 'config.toml');
-    const projectSlug = config.project.value;
-    return projectSlug !== null
-        ? {
+    const configured = config.project.value;
+    if (configured !== null) {
+        return {
             id: 'project',
             title: 'Project identity',
             status: 'ready',
-            detail: `"${projectSlug}" (${config.project.source})`,
-        }
-        : {
+            detail: `"${configured}" (${config.project.source})`,
+        };
+    }
+    const inferred = inferInvocationContext(deps.cwd).project;
+    if (inferred !== null) {
+        return {
             id: 'project',
             title: 'Project identity',
-            // Not a blocker: a send without a project simply carries no project
-            // identity. init always sets one because it is free and reversible,
-            // but an unlabelled setup works, so this must not go red.
             status: 'optional-gap',
-            detail: `not set in ${configPath} — sends from here carry no project identity`,
+            detail: `"${inferred}" is inferred for each send; init can stamp it into shared config`,
             remedy: {
                 by: 'cli',
-                summary: 'name this project after its directory',
+                summary: 'make the inferred Project identity explicit for every checkout',
                 command: 'notifai init',
             },
         };
+    }
+    return {
+        id: 'project',
+        title: 'Project identity',
+        status: 'optional-gap',
+        detail: 'the directory name has no characters a Project identifier can use',
+        remedy: {
+            by: 'cli',
+            summary: 'choose an explicit Project identifier',
+            command: 'notifai init --project-id my-project',
+        },
+    };
 }
 function remoteStatesFrom(previous) {
     const pick = (id) => previous.states.find((state) => state.id === id);