@raidiant/notifai 7.0.2 → 8.0.0

package/src/commands.test.ts

@@ -42,6 +42,7 @@ import {
   configUnsetCommand,
   contradictingAnswer,
   describeHookFailure,
+  devicesCommand,
   doctorCommand,
   EXIT,
   hooksInstallCommand,
@@ -129,6 +130,17 @@ const currentCompatibility: CompatibilityResponse = {
       replacement_available: false,
       rollout_complete: false,
     },
+    {
+      platform: 'android',
+      recommended_version: null,
+      recommended_build: null,
+      minimum_receive_build: null,
+      minimum_answer_build: null,
+      deprecation: null,
+      sunset: null,
+      replacement_available: false,
+      rollout_complete: false,
+    },
   ],
   server_capabilities: ['answer', 'agent_acknowledgement'],
 }
@@ -453,6 +465,93 @@ describe('command contracts', () => {
     expect(io.outLines[0]).toBe('macos capability contract v1 (payload limit 4096 bytes)')
   })
 
+  it('passes the selected Android platform through to the capability client', async () => {
+    const io = new CapturedIo()
+    let requestedPlatform: string | undefined
+    const document = CAPABILITIES_V1.describe('android')!
+    const client = {
+      capabilities: async (platform?: string) => {
+        requestedPlatform = platform
+        return document
+      },
+    } as unknown as ApiClient
+
+    expect(await capabilitiesCommand(makeDeps(io, client), { platform: 'android' })).toBe(
+      EXIT.ok,
+    )
+    expect(requestedPlatform).toBe('android')
+    expect(io.outLines[0]).toBe(
+      'android capability contract v1 (payload limit 4096 bytes)',
+    )
+  })
+
+  it('filters Device Installations by Android in human and JSON output', async () => {
+    const devices = [
+      {
+        device_id: 'dev_ios',
+        display_name: 'iPhone',
+        platform: 'ios' as const,
+        permission_status: 'authorized',
+        registration_healthy: true,
+        app_version: '1.0.0',
+        app_build: '1',
+        os_version: '19',
+        capabilities: ['answer'] as const,
+        support: currentSupport,
+        support_state: 'current' as const,
+        derived_status: 'working' as const,
+        status_message: null,
+        last_seen_at: null,
+      },
+      {
+        device_id: 'dev_android',
+        display_name: 'Pixel',
+        platform: 'android' as const,
+        permission_status: 'authorized',
+        registration_healthy: true,
+        app_version: '1.0.0',
+        app_build: '2',
+        os_version: '16',
+        capabilities: ['answer'] as const,
+        support: currentSupport,
+        support_state: 'current' as const,
+        derived_status: 'working' as const,
+        status_message: null,
+        last_seen_at: null,
+      },
+    ]
+    const client = { listDevices: async () => ({ devices }) } as unknown as ApiClient
+
+    const human = new CapturedIo()
+    expect(
+      await devicesCommand(makeDeps(human, client), { platform: 'android' }),
+    ).toBe(EXIT.ok)
+    expect(human.outLines).toEqual(['dev_android  Pixel  android  Working'])
+
+    const json = new CapturedIo()
+    expect(
+      await devicesCommand(makeDeps(json, client), { platform: 'android', json: true }),
+    ).toBe(EXIT.ok)
+    expect(JSON.parse(json.outLines[0]!)['devices']).toEqual([devices[1]])
+  })
+
+  it('rejects an unknown Device Installation platform filter locally', async () => {
+    const io = new CapturedIo()
+    let calls = 0
+    const client = {
+      listDevices: async () => {
+        calls += 1
+        return { devices: [] }
+      },
+    } as unknown as ApiClient
+
+    expect(await devicesCommand(makeDeps(io, client), { platform: 'linux' })).toBe(
+      EXIT.usage,
+    )
+    expect(calls).toBe(0)
+    expect(io.errLines.join('\n')).toContain('ios or macos or android')
+  })
+
   it('rejects an invalid draft before calling submit', async () => {
     const io = new CapturedIo()
     let submitCalls = 0
@@ -474,6 +573,86 @@ describe('command contracts', () => {
     expect(io.errLines.join('\n')).toContain('project')
   })
 
+  it('authors and validates an Android-specific Notification Request', async () => {
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), {
+        kind: 'done',
+        title: 'Android build finished',
+        body: 'All checks passed.',
+        platform: 'android',
+        sound: 'none',
+        data: ['run_id=42'],
+      }),
+    ).toBe(EXIT.ok)
+    expect(submitted?.draft.platform).toEqual({
+      android: { sound: null, custom_data: { run_id: '42' } },
+    })
+    expect(io.errLines).toEqual([])
+  })
+
+  it('prints Android downgrade warnings before submitting', async () => {
+    const io = new CapturedIo()
+    let submitCalls = 0
+    const client = {
+      submit: async () => {
+        submitCalls += 1
+        return receipt
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), {
+        kind: 'update',
+        title: 'Android evidence',
+        body: 'See the attached result.',
+        platform: 'android',
+        image: ['med_result'],
+        threadId: 'android-results',
+      }),
+    ).toBe(EXIT.ok)
+    expect(submitCalls).toBe(1)
+    expect(io.errLines).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining('presentation.media'),
+        expect.stringContaining('platform.android.thread_id'),
+      ]),
+    )
+  })
+
+  it('rejects an Android interruption level before submission', async () => {
+    const io = new CapturedIo()
+    let submitCalls = 0
+    const client = {
+      submit: async () => {
+        submitCalls += 1
+        return receipt
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), {
+        kind: 'update',
+        title: 'Android update',
+        body: 'Ready.',
+        platform: 'android',
+        level: 'active',
+      }),
+    ).toBe(EXIT.usage)
+    expect(submitCalls).toBe(0)
+    expect(io.errLines.join('\n')).toContain(
+      'Android does not support caller-selected interruption levels',
+    )
+  })
+
   it('infers Project and exact Claude Source Context without printing the opaque id', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'Notifai Project '))
     const io = new CapturedIo()
@@ -557,6 +736,48 @@ describe('command contracts', () => {
     })
   })
 
+  it('uses the exact Orca worktree title for an active Codex session send', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-codex-title-'))
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | undefined
+    const client = {
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return receipt
+      },
+    } as unknown as ApiClient
+    const worktreeId = `repo-123::${cwd}`
+    const deps = {
+      ...makeDeps(io, client),
+      cwd,
+      env: {
+        XDG_CONFIG_HOME: path.join(cwd, 'config'),
+        XDG_STATE_HOME: path.join(cwd, 'state'),
+        CODEX_THREAD_ID: 'orca-codex-thread',
+        TERM_PROGRAM: 'Orca',
+        ORCA_WORKTREE_ID: worktreeId,
+      },
+      orcaSessionTitle: (lookupEnv: NodeJS.ProcessEnv) => {
+        expect(lookupEnv['ORCA_WORKTREE_ID']).toBe(worktreeId)
+        return 'Worker - semantic session implementation'
+      },
+    }
+
+    expect(
+      await sendCommand(deps, {
+        title: 'Resolver implemented',
+        body: 'The worktree title belongs to every harness Orca starts in it.',
+        kind: 'done',
+      }),
+    ).toBe(EXIT.ok)
+
+    expect(submitted?.draft.source).toMatchObject({
+      session_id: 'orca-codex-thread',
+      session_label: 'Worker - semantic session implementation',
+      harness: 'codex',
+    })
+  })
+
   it('falls back safely when Orca returns a private path as its title', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-orca-private-title-'))
     const io = new CapturedIo()
@@ -801,7 +1022,7 @@ describe('command contracts', () => {
   })
 
   it('keeps only the current public notification-authoring flags', () => {
-    const source = readFileSync(new URL('./main.ts', import.meta.url), 'utf8')
+    const source = readFileSync(new URL('./program.ts', import.meta.url), 'utf8')
     expect(source).not.toContain(".option('--badge")
     expect(source).not.toContain(".option('--relevance")
     expect(source).not.toContain(".option('--target-content-id")
@@ -823,33 +1044,6 @@ describe('command contracts', () => {
     expect(source).not.toContain('Kind profiles apply automatically')
   })
 
-  it('rejects a question nobody will wait for', async () => {
-    // --reply asks; --no-block declares nothing will wait. The answer would be
-    // captured server-side and then reachable only by hand, so the user taps a
-    // real button and nothing happens — worse than never asking, because it
-    // spends their attention and their trust in the channel.
-    const io = new CapturedIo()
-    let submitCalls = 0
-    const client = {
-      submit: async () => {
-        submitCalls += 1
-        return receipt
-      },
-    } as unknown as ApiClient
-
-    expect(
-      await sendCommand(makeDeps(io, client), {
-        title: 'Question',
-        body: 'Deploy?',
-        reply: true,
-        replyWindow: 3_600,
-        noBlock: true,
-      }),
-    ).toBe(EXIT.usage)
-    expect(submitCalls).toBe(0)
-    expect(io.errLines.join('\n')).toContain('notifai ask')
-  })
-
   it('maps reply flags into the draft and waits for the answer', async () => {
     const io = new CapturedIo()
     let submitted: SubmitNotificationRequestT | undefined
@@ -907,7 +1101,7 @@ describe('command contracts', () => {
 
     expect(await sendCommand(makeDeps(io, client), flags)).toBe(EXIT.ok)
     expect(io.errLines).toEqual([
-      'Heads up: this notification ends with a question but has no reply action. Add --reply (and optionally --reply-choice) so it can be answered from the notification.',
+      'Heads up: this notification ends with a question but has no reply action. Add --reply (and optionally --choice) so it can be answered from the notification.',
     ])
   })
 
@@ -929,7 +1123,7 @@ describe('command contracts', () => {
     expect(io.errLines).toEqual([])
   })
 
-  it('rejects --reply-choice without the --reply action it configures', async () => {
+  it('rejects --choice without the --reply action it configures', async () => {
     const io = new CapturedIo()
     let submitCalls = 0
     const client = {
@@ -943,12 +1137,12 @@ describe('command contracts', () => {
       await sendCommand(makeDeps(io, client), { kind: 'update',
         title: 'Deploy?',
         body: 'Choose when ready.',
-        replyChoice: ['Now', 'Later'],
+        choice: ['Now', 'Later'],
       }),
     ).toBe(EXIT.usage)
     expect(submitCalls).toBe(0)
     expect(io.errLines).toEqual([
-      'Use --reply with --reply-timeout, --reply-window, --reply-choice, or --no-block.',
+      'Use --reply with --reply-timeout, --reply-window, or --choice.',
     ])
   })
 
@@ -1148,13 +1342,14 @@ describe('command contracts', () => {
     })
   })
 
-  it('prints an NDJSON receipt before waiting and a result record on exit 3', async () => {
+  it('prints one combined reply_result object on exit 3, nothing before the wait', async () => {
     const io = new CapturedIo()
     let now = 0
     const client = {
       submit: async () => receipt,
       replies: async (_requestId: string, options: { waitSeconds: number }) => {
-        expect(JSON.parse(io.outLines[0] ?? '{}')).toEqual({ type: 'receipt', receipt })
+        // Nothing on stdout mid-wait: the single object arrives at the end.
+        expect(io.outLines).toHaveLength(0)
         now += options.waitSeconds * 1_000
         return replyResponse()
       },
@@ -1170,11 +1365,12 @@ describe('command contracts', () => {
         json: true,
       }),
     ).toBe(EXIT.noReply)
-    expect(io.outLines).toHaveLength(2)
+    expect(io.outLines).toHaveLength(1)
     // `degraded` is part of the shape on every reply wait, not only when it is
     // true: an agent must be able to read it without knowing it might be absent.
-    expect(JSON.parse(io.outLines[1] ?? '{}')).toEqual({
+    expect(JSON.parse(io.outLines[0] ?? '{}')).toEqual({
       type: 'reply_result',
+      receipt,
       request_id: receipt.request_id,
       reply_expires_at: '2026-08-02T18:00:00.000Z',
       replies: [],
@@ -1189,7 +1385,7 @@ describe('command contracts', () => {
     expect(io.errLines.join('\n')).toContain(`notifai close ${receipt.request_id}`)
   })
 
-  it('prints the receipt and reply result as two NDJSON records when answered', async () => {
+  it('prints one combined reply_result object with the receipt when answered', async () => {
     const io = new CapturedIo()
     const client = {
       submit: async () => receipt,
@@ -1205,10 +1401,10 @@ describe('command contracts', () => {
         json: true,
       }),
     ).toBe(EXIT.ok)
-    expect(io.outLines).toHaveLength(2)
-    expect(JSON.parse(io.outLines[0] ?? '{}')).toEqual({ type: 'receipt', receipt })
-    expect(JSON.parse(io.outLines[1] ?? '{}')).toEqual({
+    expect(io.outLines).toHaveLength(1)
+    expect(JSON.parse(io.outLines[0] ?? '{}')).toEqual({
       type: 'reply_result',
+      receipt,
       request_id: receipt.request_id,
       reply_expires_at: '2026-08-02T18:00:00.000Z',
       replies: [reply],
@@ -1220,6 +1416,41 @@ describe('command contracts', () => {
     })
   })
 
+  it('still prints the one reply_result object when the wait itself faults', async () => {
+    const io = new CapturedIo()
+    const client = {
+      submit: async () => receipt,
+      replies: async () => {
+        throw new ApiCallError(404, 'not_found', 'no such request')
+      },
+    } as unknown as ApiClient
+
+    expect(
+      await sendCommand(makeDeps(io, client), {
+        title: 'Question',
+        body: 'Deploy?',
+        reply: true,
+        replyTimeout: 10,
+        json: true,
+      }),
+    ).toBe(EXIT.failed)
+    expect(io.outLines).toHaveLength(1)
+    // The send is durable even though the wait failed; `degraded: true` says
+    // "could not find out", not "no answer".
+    expect(JSON.parse(io.outLines[0] ?? '{}')).toEqual({
+      type: 'reply_result',
+      receipt,
+      request_id: receipt.request_id,
+      replies: [],
+      agent_acknowledgement_required: true,
+      agent_acknowledgement_text_required: true,
+      agent_acknowledgement: null,
+      acknowledgement_command: null,
+      degraded: true,
+    })
+    expect(io.errLines.join('\n')).toContain('reply wait failed')
+  })
+
   it('acknowledges non-interactively, trims text, emits JSON, and logs request identity', async () => {
     const io = new CapturedIo()
     let submitted: { requestId: string; text: string } | undefined
@@ -3175,11 +3406,18 @@ describe('init', () => {
     display_name: 'Mac',
     platform: 'macos' as const,
   }
+  const readyAndroid = {
+    ...readyIphone,
+    device_id: 'dev_android',
+    display_name: 'Pixel',
+    platform: 'android' as const,
+    os_version: '16',
+  }
 
   function setupEvidence(
     requestId: string,
     companionReceipt: EvidenceSnapshot['deliveries'][number]['companion_receipt'],
-    device = readyIphone,
+    device: typeof readyIphone | typeof readyAndroid = readyIphone,
   ): EvidenceSnapshot {
     return {
       request_id: requestId,
@@ -3215,15 +3453,18 @@ describe('init', () => {
     }
   }
 
-  function setupReceipt(requestId = 'req_setup'): SubmissionReceipt {
+  function setupReceipt(
+    requestId = 'req_setup',
+    device: typeof readyIphone | typeof readyAndroid = readyIphone,
+  ): SubmissionReceipt {
     return {
       ...receipt,
       request_id: requestId,
       deliveries: [
         {
           ...receipt.deliveries[0]!,
-          device_id: readyIphone.device_id,
-          device_name: readyIphone.display_name,
+          device_id: device.device_id,
+          device_name: device.display_name,
         },
       ],
     }
@@ -3735,7 +3976,9 @@ describe('init', () => {
     expect(out).toContain('Next: Your devices')
     expect(out).toContain('https://test.notifai.invalid/support')
     expect(out).toContain('sign in with the same email as this account (alpha@example.com)')
-    expect(out).toContain('install Notifai on iPhone via https://test.notifai.invalid/support')
+    expect(out).toContain(
+      'no active Companion device registered yet; install Notifai via https://test.notifai.invalid/support',
+    )
     expect(out.match(/^Next:/gm)).toHaveLength(1)
   })
 
@@ -3784,7 +4027,7 @@ describe('init', () => {
   })
 
   it.each([
-    ['denied', 'iPhone Settings'],
+    ['denied', "the device's Settings"],
     ['not_determined', 'allow its notification prompt'],
   ])('gives one permission-specific next action for %s', async (permission, expected) => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), `init-permission-${permission}-`))
@@ -3804,12 +4047,12 @@ describe('init', () => {
 
     expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
     const out = io.outLines.join('\n')
-    expect(out).toContain(`iPhone (${permission})`)
+    expect(out).toContain(`iPhone (ios, ${permission})`)
     expect(out).toContain(expected)
     expect(out.match(/^Next:/gm)).toHaveLength(1)
   })
 
-  it('ignores a dormant Mac installation while waiting for an iPhone, then proves the iPhone receipt', async () => {
+  it('ignores a dormant Mac installation while waiting for an active Companion, then proves the iPhone receipt', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'init-device-bridge-'))
     const io = new InteractiveIo()
     let now = 0
@@ -3856,7 +4099,9 @@ describe('init', () => {
     ])
     expect(io.openedUrls).toEqual(['https://test.notifai.invalid/support'])
     expect(io.notes.some((n) => n.message.includes('I will wait up to 10 minutes'))).toBe(true)
-    expect(io.spinnerEvents).toContain('message:Waiting for the iPhone app to sign in and register…')
+    expect(io.spinnerEvents).toContain(
+      'message:Waiting for a Companion App to sign in and register…',
+    )
     expect(io.spinnerEvents).toContain('stop:iPhone is ready to receive')
     expect(io.spinnerEvents).toContain('stop:Receipt observed from iPhone')
     expect(io.outLines.join('\n')).toContain(
@@ -4047,6 +4292,51 @@ describe('init', () => {
     expect(io.outLines.join('\n')).toContain('Next: Delivery proof')
   })
 
+  it('treats Android as active Companion readiness and sends a platform-correct proof', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'init-android-proof-'))
+    mkdirSync(path.join(cwd, '.notifai'), { recursive: true })
+    writeFileSync(
+      path.join(cwd, '.notifai', 'config.toml'),
+      'project = "android-project"\ninterruption_level = "passive"\n',
+    )
+    const io = new CapturedIo()
+    let submitted: SubmitNotificationRequestT | null = null
+    const client = {
+      health: async () => true,
+      listDevices: async () => ({ devices: [readyAndroid] }),
+      submit: async (body: SubmitNotificationRequestT) => {
+        submitted = body
+        return setupReceipt('req_android_setup', readyAndroid)
+      },
+      evidence: async (requestId: string) =>
+        setupEvidence(
+          requestId,
+          {
+            state: 'observed',
+            observed_at: '2026-08-05T18:00:02.000Z',
+            latency_ms: 1_000,
+          },
+          readyAndroid,
+        ),
+    } as unknown as ApiClient
+    const deps = {
+      ...makeDeps(io, client),
+      cwd,
+      env: isolatedEnv(cwd),
+    }
+
+    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
+    expect(submitted?.draft.targets).toEqual({
+      mode: 'selected',
+      device_ids: [readyAndroid.device_id],
+    })
+    expect(submitted?.draft.platform).toEqual({ android: { sound: null } })
+    expect(io.outLines.join('\n')).toContain(
+      "Companion Receipt (the app's delivery confirmation) observed from Pixel.",
+    )
+    expect(io.outLines.join('\n')).toContain('All set.')
+  })
+
   it('does not treat a macOS-only installation as active-release readiness', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'init-macos-proof-'))
     const io = new CapturedIo()
@@ -4072,11 +4362,11 @@ describe('init', () => {
     expect(submitCalls).toBe(0)
     const out = io.outLines.join('\n')
     expect(out).toContain('Next: Your devices')
-    expect(out).toContain('no iPhone registered yet')
+    expect(out).toContain('no active Companion device registered yet')
     expect(out).not.toContain('All set.')
     expect(out).not.toMatch(/Companion Receipt observed/i)
 
-    // A human doctor must render the same iPhone-readiness failure.
+    // A human doctor must render the same active-Companion readiness failure.
     const doctorIo = new PlainInteractiveIo()
     expect(
       await doctorCommand(
@@ -4090,8 +4380,10 @@ describe('init', () => {
     ).toBe(EXIT.failed)
     const doctorOut = doctorIo.outLines.join('\n')
     expect(doctorOut).toMatch(/FAIL\s+Your devices:/)
-    expect(doctorOut).toContain('no iPhone registered yet')
-    expect(doctorOut).toContain('Delivery proof: not checked — no iPhone is ready')
+    expect(doctorOut).toContain('no active Companion device registered yet')
+    expect(doctorOut).toContain(
+      'Delivery proof: not checked — no iPhone or Android Companion App is ready',
+    )
   })
 
   it('stops login when the approval page reports no Alpha access', async () => {
@@ -4387,7 +4679,8 @@ describe('an outage is not an answer', () => {
       json: true,
     })
 
-    const payload = JSON.parse(io.outLines[1] ?? '{}') as { degraded: boolean }
+    expect(io.outLines).toHaveLength(1)
+    const payload = JSON.parse(io.outLines[0] ?? '{}') as { degraded: boolean }
     expect(payload.degraded).toBe(true)
   })
 
@@ -4568,7 +4861,7 @@ describe('asking before the hooks have ever run', () => {
     const pending = readSessionState('codex-media-thread', env).pending?.[0]
     expect(uploaded).toEqual(['med_ask_1', 'med_ask_2'])
     expect(pending?.body).toBe(
-      'Which visual should I use?\n\nCompare ![first](media:med_ask_1) with ![second](media:med_ask_2).',
+      'Compare ![first](media:med_ask_1) with ![second](media:med_ask_2).',
     )
     expect(pending?.media).toEqual([
       { media_id: 'med_ask_1', alt: 'First option' },
@@ -5591,7 +5884,7 @@ describe('command failures carrying server details', () => {
 })
 
 describe('question sets', () => {
-  it('maps --reply-multi into the single question', async () => {
+  it('maps --multi into the single question', async () => {
     const io = new CapturedIo()
     let submitted: SubmitNotificationRequestT | undefined
     const client = {
@@ -5608,8 +5901,8 @@ describe('question sets', () => {
         body: 'Which fronts?',
         reply: true,
         replyTimeout: 30,
-        replyChoice: ['CLI', 'Server', 'Apps'],
-        replyMulti: true,
+        choice: ['CLI', 'Server', 'Apps'],
+        multi: true,
       }),
     ).toBe(EXIT.ok)
     expect(submitted?.draft.reply?.questions?.[0]).toMatchObject({
@@ -5643,7 +5936,10 @@ describe('question sets', () => {
     expect(submitted?.draft.reply?.questions[0]?.text).toBe('Which environment?')
   })
 
-  it('composes one question before optional Markdown context', () => {
+  it('keeps the question out of a body that carries context', () => {
+    // The question already travels as the title and as structured questions;
+    // repeating it in the body showed it twice on the lock screen and the
+    // reply screen.
     expect(
       buildQuestions(
         { body: '## Why\nThe release window closes today.' },
@@ -5651,12 +5947,28 @@ describe('question sets', () => {
       ),
     ).toMatchObject({
       ok: true,
-      body: 'Which environment?\n\n## Why\nThe release window closes today.',
+      body: '## Why\nThe release window closes today.',
       questions: [{ text: 'Which environment?' }],
     })
   })
 
-  it('composes numbered form questions before form context', () => {
+  it('lets the question stand in for the body only when there is no context', () => {
+    expect(buildQuestions({}, 'Which environment?')).toMatchObject({
+      ok: true,
+      body: 'Which environment?',
+    })
+    expect(
+      buildQuestions(
+        { form: JSON.stringify({ questions: [{ text: 'Deploy where?' }, { text: 'What should I monitor?' }] }) },
+        undefined,
+      ),
+    ).toMatchObject({
+      ok: true,
+      body: '1. Deploy where?\n2. What should I monitor?',
+    })
+  })
+
+  it('keeps form questions out of a body that carries form context', () => {
     expect(
       buildQuestions(
         {
@@ -5669,8 +5981,7 @@ describe('question sets', () => {
       ),
     ).toMatchObject({
       ok: true,
-      body:
-        '1. Deploy where?\n2. What should I monitor?\n\n## Context\nTraffic is elevated.',
+      body: '## Context\nTraffic is elevated.',
     })
   })
 

package/src/commands.ts

@@ -47,6 +47,11 @@ export {
   configShowCommand,
   configUnsetCommand,
 } from './commands-config.js'
+export {
+  guidanceSetCommand,
+  guidanceShowCommand,
+  guidanceUnsetCommand,
+} from './commands-guidance.js'
 export { logsCommand, parseSince, type LogsFlags } from './commands-logs.js'
 export { SKILLS_SOURCE } from './commands-skill.js'
 export {