@raidiant/notifai 0.1.7 → 0.1.8

package/src/commands.ts

@@ -9,6 +9,7 @@ import {
   REPLY_MAX_WINDOW_SECONDS,
   validateDraft,
   type EvidenceSnapshot,
+  type AccountAccessResponse,
   type ListRepliesResponse,
   type Platform,
   type ReplyView,
@@ -46,9 +47,12 @@ import {
   parseHookInput,
   pruneAbandonedSessions,
   readProjectSession,
+  readProjectSessionPointer,
+  readSessionState,
   registerQuestion,
   type HookContext,
   type HookEnvelope,
+  type HookHarness,
 } from './hooks.js'
 import { readIdleSeconds } from './idle.js'
 import {
@@ -85,6 +89,7 @@ import {
   receiptExitCode,
   type SendFlags,
 } from './send.js'
+import type { NativeSkill, NativeSkills, SkillScope } from './native-skills.js'
 
 export interface CommandIo {
   out(line: string): void
@@ -127,6 +132,8 @@ export interface CommandDeps {
   sleep?: (milliseconds: number) => Promise<void>
   /** Test seam for the OS idle probe; production shells out to the platform. */
   idleSeconds?: () => number | null
+  /** Test seam and production adapter for the external native skills installer. */
+  nativeSkills?: NativeSkills
 }
 
 export const EXIT = {
@@ -207,7 +214,7 @@ export async function loginCommand(
 
   const interactive = deps.io.interactive === true
   if (interactive) {
-    await deps.io.intro?.('NotifAI sign in')
+    await deps.io.intro?.('Notifai sign in')
     await deps.io.note?.(`Code: ${begin.code}\n${begin.approve_url}`, 'Approve this machine')
   } else {
     deps.io.out(`Pairing code: ${begin.code}`)
@@ -220,7 +227,15 @@ export async function loginCommand(
   const intervalMs = Math.max(begin.poll_interval_seconds, 1) * 1000
   const now = deps.now ?? Date.now
   const sleep = deps.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)))
-  const spinner = interactive ? await deps.io.spinner?.('Waiting for approval…') : null
+  const approvalWaitMessage = (): string => {
+    const remainingSec = Math.max(0, Math.ceil((expiresAt - now()) / 1000))
+    const minutes = Math.floor(remainingSec / 60)
+    const seconds = remainingSec % 60
+    const remaining =
+      minutes > 0 ? `${minutes}m ${seconds.toString().padStart(2, '0')}s` : `${seconds}s`
+    return `Waiting for approval… code ${begin.code} · ${remaining} left`
+  }
+  const spinner = interactive ? await deps.io.spinner?.(approvalWaitMessage()) : null
   while (now() < expiresAt) {
     await sleep(intervalMs)
     let poll
@@ -228,7 +243,7 @@ export async function loginCommand(
       poll = await client.pollPairing(begin.pairing_id, pollVerifier)
     } catch (err) {
       if (err instanceof NetworkError) {
-        spinner?.message('Connection lost — retrying…')
+        spinner?.message(`Connection lost — retrying… code ${begin.code}`)
         continue
       }
       spinner?.error('Pairing failed')
@@ -249,8 +264,18 @@ export async function loginCommand(
       deps.io.err('Pairing was denied from the dashboard.')
       return EXIT.auth
     }
+    if (poll.status === 'no_active_plan') {
+      const next =
+        poll.next_action ??
+        `Open ${baseUrl.replace(/\/$/, '')}/support to request Alpha access, then retry.`
+      spinner?.error('Account has no Alpha access')
+      deps.io.err('This account has no active plan or temporary Alpha access.')
+      deps.io.err(`next: ${next}`)
+      deps.io.err('After access is granted, run `notifai login` again.')
+      return EXIT.auth
+    }
     if (poll.status === 'expired') break
-    spinner?.message('Waiting for approval…')
+    spinner?.message(approvalWaitMessage())
   }
   spinner?.error('Pairing expired')
   deps.io.err('Pairing expired before it was approved. Run `notifai login` again.')
@@ -293,6 +318,34 @@ export function authStatusCommand(deps: CommandDeps, flags: { json?: boolean }):
   return EXIT.ok
 }
 
+/** Show the server's account access decision without attempting a product mutation. */
+export async function accessStatusCommand(
+  deps: CommandDeps,
+  flags: { json?: boolean },
+): Promise<number> {
+  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  try {
+    const access: AccountAccessResponse = await authed.client.accessStatus()
+    if (flags.json) {
+      deps.io.out(JSON.stringify(access, null, 2))
+      return access.status === 'active' ? EXIT.ok : EXIT.failed
+    }
+    if (access.status === 'no_active_plan') {
+      const supportUrl = `${authed.baseUrl.replace(/\/$/, '')}/support`
+      deps.io.out('No active plan or temporary Alpha access for this account.')
+      deps.io.out(`next: Open ${supportUrl} to request Alpha access, then retry.`)
+      return EXIT.failed
+    }
+    const expiry = access.expires_at ? ` until ${access.expires_at}` : ''
+    deps.io.out(`Access active (${access.reason})${expiry}`)
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // devices / capabilities
 // ---------------------------------------------------------------------------
@@ -308,7 +361,16 @@ export async function devicesCommand(deps: CommandDeps, flags: { json?: boolean
       return EXIT.ok
     }
     if (result.devices.length === 0) {
-      deps.io.out('No devices. Install a NotifAI companion app on a device and sign in.')
+      const supportUrl = supportPageUrl(authed.baseUrl)
+      let email: string | null = null
+      try {
+        email = (await authed.client.accessStatus()).email
+      } catch {
+        // Best-effort: the empty-state copy still points at /support without it.
+      }
+      deps.io.out(
+        `No devices yet. Install Notifai from ${supportUrl}, ${sameAccountSignInLine(email)}, and allow notifications.`,
+      )
       return EXIT.ok
     }
     for (const d of result.devices) {
@@ -365,6 +427,10 @@ export async function sendCommand(
   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.')
+    return EXIT.usage
+  }
   if (
     !flags.reply &&
     (flags.replyTimeout !== undefined || flags.replyWindow !== undefined || flags.noBlock || hasReplyChoice)
@@ -435,6 +501,7 @@ export async function sendCommand(
     for (const issue of validation.errors) deps.io.err(`${issue.path}: ${issue.message}`)
     return EXIT.usage
   }
+  emitSendWarnings(deps, flags, config)
   if (
     !flags.reply &&
     (flags.title.trim().endsWith('?') || flags.body.trim().endsWith('?'))
@@ -452,11 +519,21 @@ export async function sendCommand(
     )
     const receiptExit = receiptExitCode(receipt)
     if (!flags.json) deps.io.out(formatReceipt(receipt))
+    else if (flags.reply) deps.io.out(JSON.stringify({ type: 'receipt', receipt }))
 
     // A zero wait can no longer reach here: --reply guarantees a positive one.
     if (!flags.reply || receiptExit !== EXIT.ok) {
       if (flags.json) {
-        deps.io.out(JSON.stringify(flags.reply ? { receipt, replies: [] } : receipt, null, 2))
+        deps.io.out(
+          flags.reply
+            ? JSON.stringify({
+                type: 'reply_result',
+                request_id: receipt.request_id,
+                replies: [],
+                degraded: false,
+              })
+            : JSON.stringify(receipt, null, 2),
+        )
       }
       return receiptExit
     }
@@ -469,11 +546,12 @@ export async function sendCommand(
     })
     if (flags.json) {
       deps.io.out(
-        JSON.stringify(
-          { receipt, replies: result.response.replies, degraded: result.degraded },
-          null,
-          2,
-        ),
+        JSON.stringify({
+          type: 'reply_result',
+          request_id: receipt.request_id,
+          replies: result.response.replies,
+          degraded: result.degraded,
+        }),
       )
     } else if (result.response.replies.length > 0) printReplies(deps, result.response.replies)
     else printNoReply(deps, receipt.request_id, result.response.reply_expires_at)
@@ -481,16 +559,65 @@ export async function sendCommand(
       deps.io.err(DEGRADED_WAIT_WARNING)
       return EXIT.network
     }
+    if (result.timedOut) {
+      deps.io.err(
+        `No reply yet. Retrieve it with \`notifai replies ${receipt.request_id}\` or retire the question with ` +
+          `\`notifai close ${receipt.request_id}\`.`,
+      )
+    }
     return result.timedOut ? EXIT.noReply : EXIT.ok
   } catch (err) {
     return reportError(deps, err)
   }
 }
 
+function emitSendWarnings(
+  deps: CommandDeps,
+  flags: SendFlags,
+  config: ReturnType<typeof loadConfig>,
+): void {
+  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 (
+    flags.collapseKey === undefined &&
+    config.collapse_key.value !== null &&
+    config.collapse_key.source.startsWith('global:')
+  ) {
+    deps.io.err(
+      'Heads up: collapse_key comes from machine-global config, so unrelated notifications may replace each other. Prefer a project or command-specific --collapse-key.',
+    )
+  }
+  if (flags.ttl !== undefined && flags.ttl > 259_200) {
+    deps.io.err(
+      'Heads up: this explicit --ttl is longer than 72 hours; stale notifications may arrive after they are useful.',
+    )
+  }
+}
+
+function looksLikeMarkdown(value: string): boolean {
+  return /(?:^|\n)\s{0,3}(?:#{1,6}\s|[-+*]\s|>\s|\d+\.\s|```)|(?:\*\*|__|~~|`)[^\n]+(?:\*\*|__|~~|`)|\[[^\]]+\]\([^)]+\)/m.test(
+    value,
+  )
+}
+
 export async function repliesCommand(
   deps: CommandDeps,
-  requestId: string,
-  flags: { wait?: number; after?: number; json?: boolean },
+  requestedId: string | undefined,
+  flags: { wait?: number; after?: number; json?: boolean; pending?: boolean },
 ): Promise<number> {
   const waitSeconds = flags.wait ?? 0
   const afterSeq = flags.after ?? 0
@@ -503,6 +630,28 @@ export async function repliesCommand(
     return EXIT.usage
   }
 
+  if (flags.pending === true && requestedId !== undefined) {
+    deps.io.err('Pass a request id or --pending, not both.')
+    return EXIT.usage
+  }
+  let requestId = requestedId
+  if (flags.pending === true) {
+    const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)())
+    if (sessionId === null) {
+      deps.io.err('No active session pointer is available in this directory.')
+      return EXIT.noReply
+    }
+    requestId = readSessionState(sessionId, deps.env).pending?.request_id
+    if (requestId === undefined) {
+      deps.io.err(`Session ${sessionId} has no pushed question pending.`)
+      return EXIT.noReply
+    }
+  }
+  if (requestId === undefined) {
+    deps.io.err('Pass a request id or --pending.')
+    return EXIT.usage
+  }
+
   const config = loadConfig({ cwd: deps.cwd, env: deps.env })
   const authed = authedClient(deps, config)
   if (!authed) return EXIT.auth
@@ -515,7 +664,10 @@ export async function repliesCommand(
     })
     if (flags.json) {
       deps.io.out(JSON.stringify({ ...result.response, degraded: result.degraded }, null, 2))
-    } else if (result.response.replies.length > 0) printReplies(deps, result.response.replies)
+    } else if (result.response.replies.length > 0) {
+      if (flags.pending === true) deps.io.out(`pending request ${requestId}`)
+      printReplies(deps, result.response.replies)
+    }
     else printNoReply(deps, requestId, result.response.reply_expires_at)
     if (result.degraded) {
       deps.io.err(DEGRADED_WAIT_WARNING)
@@ -679,12 +831,12 @@ export async function statusCommand(
       if (d.companion_receipt.state === 'observed') {
         const latency = d.companion_receipt.latency_ms
         deps.io.out(
-          `    Companion Receipt: observed at ${d.companion_receipt.observed_at}` +
+          `    Companion Receipt (the app's delivery confirmation): observed at ${d.companion_receipt.observed_at}` +
             (latency === null ? '' : ` (${formatElapsed(latency)} after Provider Acceptance)`),
         )
       } else {
         deps.io.out(
-          '    Companion Receipt: unknown — not observed; this is not a failure or proof of non-receipt',
+          "    Companion Receipt (the app's delivery confirmation): unknown — not observed; this is not a failure or proof of non-receipt",
         )
       }
       for (const e of d.events) {
@@ -772,7 +924,7 @@ export async function hookRunCommand(
   deps: CommandDeps,
   event: string,
   readStdin: () => Promise<string>,
-  harness?: 'cursor',
+  harness?: HookHarness,
 ): Promise<number> {
   if (!(HOOK_EVENTS as readonly string[]).includes(event)) {
     deps.io.err(`Unknown hook event "${event}". Valid: ${HOOK_EVENTS.join(', ')}`)
@@ -780,7 +932,17 @@ export async function hookRunCommand(
   }
   let envelope: HookEnvelope
   try {
-    envelope = parseHookInput(await readStdin())
+    const raw = await readStdin()
+    if (raw.trim() !== '') {
+      try {
+        const parsed: unknown = JSON.parse(raw)
+        if (typeof parsed !== 'object' || parsed === null) throw new Error('not an object')
+      } catch {
+        deps.io.err('notifai: ignored malformed or truncated hook input; no routing action was taken')
+        return EXIT.ok
+      }
+    }
+    envelope = parseHookInput(raw)
     if (harness === 'cursor') {
       const sessionId = envelope.session_id ?? envelope.conversation_id
       const cwd = envelope.cwd ?? envelope.workspace_roots?.[0]
@@ -814,7 +976,10 @@ export async function hookRunCommand(
     const cwd = envelope.cwd ?? deps.cwd
     const config = loadConfig({ cwd, env: deps.env, sessionId: envelope.session_id })
     const credential = deps.store.load()
-    if (!credential) return EXIT.ok
+    if (!credential) {
+      deps.io.err('notifai: hook skipped: this machine is not paired; run `notifai login`')
+      return EXIT.ok
+    }
     // Pin authenticated traffic to the origin the credential was issued for. A
     // repository can commit `.notifai/config.toml`, and honouring a base_url
     // from it would hand this machine's bearer token to whatever host it names.
@@ -854,6 +1019,7 @@ export async function hookRunCommand(
           degraded: result.degraded,
         }
       },
+      ...(harness === undefined ? {} : { harness }),
     }
 
     // Real clock, deliberately, not `deps.now`. This compares against file
@@ -941,18 +1107,50 @@ export interface AskFlags {
  * `require_idle = false` intentionally permits a push while the user is active.
  */
 export function askCommand(deps: CommandDeps, question: string, flags: AskFlags): number {
-  // An agent calling this gets no hook payload and no harness exports its
-  // session id, so the UserPromptSubmit hook leaves a pointer keyed on the
-  // project directory and we read it back here. The pointer outranks the
+  // An agent calling this gets no hook payload. Harness-native environment
+  // markers identify the active owner, while the UserPromptSubmit hook leaves
+  // a pointer keyed on the project directory with the hook's canonical id.
+  // The pointer outranks the
   // NOTIFAI_SESSION fallback deliberately: the exported id is often a chosen
   // label rather than the harness's own id, and the hooks key state by the
   // latter — the env var is only trusted when no hook has spoken.
   const now = (deps.now ?? Date.now)()
-  const sessionId =
-    flags.session ??
-    readProjectSession(deps.cwd, deps.env, now) ??
-    deps.env['NOTIFAI_SESSION'] ??
-    undefined
+  const projectPointer = readProjectSessionPointer(deps.cwd, deps.env, now)
+  const pointer = projectPointer?.sessionId ?? null
+  const active = activeHarnessSession(deps.env)
+  let sessionId: string | undefined
+  if (flags.session !== undefined) {
+    sessionId = flags.session
+  } else if (active !== null) {
+    const installations = findInstallations(deps.cwd, deps.env)
+    const activeInstalled = installations.some(
+      (installation) => installation.harness === active.harness,
+    )
+    if (!activeInstalled) {
+      for (const line of diagnoseActiveHarnessSession(active, 'not-installed', installations)) {
+        deps.io.err(line)
+      }
+      return EXIT.usage
+    }
+    if (projectPointer === null) {
+      for (const line of diagnoseActiveHarnessSession(active, 'not-fired', installations)) {
+        deps.io.err(line)
+      }
+      return EXIT.usage
+    }
+    if (
+      projectPointer.harness !== active.harness ||
+      (active.sessionId !== undefined && projectPointer.sessionId !== active.sessionId)
+    ) {
+      for (const line of diagnoseActiveHarnessSession(active, 'different-session', installations)) {
+        deps.io.err(line)
+      }
+      return EXIT.usage
+    }
+    sessionId = projectPointer.sessionId
+  } else {
+    sessionId = pointer ?? deps.env['NOTIFAI_SESSION'] ?? undefined
+  }
   if (!sessionId) {
     for (const line of diagnoseMissingSession(deps)) deps.io.err(line)
     return EXIT.usage
@@ -994,6 +1192,79 @@ export function askCommand(deps: CommandDeps, question: string, flags: AskFlags)
   return EXIT.ok
 }
 
+/**
+ * Exact evidence that this shell command is running inside one supported
+ * harness. Configuration-directory variables are deliberately absent: they
+ * describe where a tool stores files, not which tool owns the current shell.
+ * OpenCode's generated plugin supplies the Notifai-owned marker because its
+ * plugin API exposes session identity but the ordinary environment does not.
+ */
+interface ActiveHarnessSession {
+  harness: Harness
+  label: string
+  sessionId?: string
+}
+
+function activeHarnessSession(env: NodeJS.ProcessEnv): ActiveHarnessSession | null {
+  const explicit = env['NOTIFAI_ACTIVE_HARNESS']
+  if (explicit === 'opencode') {
+    const sessionId = env['NOTIFAI_ACTIVE_SESSION_ID']
+    return {
+      harness: 'opencode',
+      label: 'OpenCode',
+      ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
+    }
+  }
+  if (env['CLAUDECODE'] === '1') {
+    const sessionId = env['CLAUDE_CODE_SESSION_ID']
+    return {
+      harness: 'claude-code',
+      label: 'Claude Code',
+      ...(sessionId === undefined || sessionId === '' ? {} : { sessionId }),
+    }
+  }
+  const codexSession = env['CODEX_THREAD_ID']
+  if (codexSession !== undefined && codexSession !== '') {
+    return { harness: 'codex', label: 'Codex', sessionId: codexSession }
+  }
+  if ((env['CURSOR_AGENT'] ?? '') !== '') return { harness: 'cursor', label: 'Cursor' }
+  return null
+}
+
+type ActiveHarnessProblem = 'not-installed' | 'not-fired' | 'different-session'
+
+function diagnoseActiveHarnessSession(
+  active: ActiveHarnessSession,
+  problem: ActiveHarnessProblem,
+  installations: Installation[],
+): string[] {
+  if (problem === 'not-installed') {
+    const others = installations.map((installation) => installation.harness)
+    return [
+      `Could not register the question for the active ${active.label} session: Notifai ${active.label} hooks are not installed for this project.`,
+      ...(others.length === 0
+        ? []
+        : [
+            `Hooks installed for ${[...new Set(others)].join(', ')} do not route an active ${active.label} session.`,
+          ]),
+      `Run \`notifai hooks install --harness ${active.harness}\`, then send one ${active.label} prompt and run \`notifai doctor\`.`,
+      `Retry \`notifai ask\` only after doctor reports that the ${active.label} hooks fired.`,
+    ]
+  }
+  if (problem === 'different-session') {
+    return [
+      `Could not register the question for the active ${active.label} session: the project pointer belongs to another ${active.label} session or harness.`,
+      `Refusing to guess or cross-wire the question. Send one prompt in this ${active.label} session, then run \`notifai doctor\`.`,
+      `Retry \`notifai ask\` only after doctor reports that this active ${active.label} session fired the hooks.`,
+    ]
+  }
+  return [
+    `Could not register the question for the active ${active.label} session: Notifai hooks are installed, but this session has not published its pointer.`,
+    `Send one ${active.label} prompt, then run \`notifai doctor\`.`,
+    `Retry \`notifai ask\` only after doctor reports that the active ${active.label} session fired the hooks.`,
+  ]
+}
+
 /**
  * Why `ask` cannot see a session, in terms of what to do about it.
  *
@@ -1007,13 +1278,13 @@ function diagnoseMissingSession(deps: CommandDeps): string[] {
   const installations = findInstallations(deps.cwd, deps.env)
   if (installations.length === 0) {
     return [
-      'Could not tell which harness session this is: no NotifAI hooks are installed for this project.',
+      'Could not tell which harness session this is: no Notifai hooks are installed for this project.',
       'Run `notifai hooks install`, then follow the activation instruction it prints.',
     ]
   }
   const where = installations.map((i) => `${i.harness} in ${i.file}`).join(', ')
   return [
-    `Could not tell which harness session this is. NotifAI hooks are installed (${where}),`,
+    `Could not tell which harness session this is. Notifai hooks are installed (${where}),`,
     'but no usable session pointer from the last 24 hours exists here.',
     hookActivationAdvice(installations),
     'To ask from this session anyway, pass --session <id>.',
@@ -1060,7 +1331,9 @@ function hookActivationAdvice(installations: Installation[]): string {
     )
   }
   if (harnesses.has('opencode')) {
-    advice.push('OpenCode: restart it, then send one prompt; plugins load at startup')
+    advice.push(
+      'OpenCode: restart it, then send one prompt; plugins load at startup, and a device answer is delivered on the next prompt',
+    )
   }
   return `${advice.join('. ')}.`
 }
@@ -1123,6 +1396,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
         scriptPath,
         replyTimeoutSeconds: config.hook_reply_timeout_seconds.value,
         graceSeconds: config.ask_grace_seconds.value,
+        harness: 'cursor',
       }),
       scriptPath,
     )
@@ -1142,8 +1416,8 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       deps.io.out('Send one Cursor prompt, then check `notifai doctor`. If the hook has not fired,')
       deps.io.out('start a new Cursor session and try one prompt again.')
     }
-    deps.io.out('A companion-device answer is submitted as one')
-    deps.io.out('follow-up user message; loop_limit = 1 prevents repeated answer turns.')
+    deps.io.out('A companion-device answer is submitted as one follow-up user message.')
+    deps.io.out('loop_limit = 3 permits bounded chained questions without an unbounded loop.')
     return EXIT.ok
   }
 
@@ -1161,6 +1435,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       scriptPath,
       replyTimeoutSeconds: config.hook_reply_timeout_seconds.value,
       graceSeconds: config.ask_grace_seconds.value,
+      harness,
     }),
     scriptPath,
   )
@@ -1184,11 +1459,11 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
           `nothing is pushed. A question registered with \`notifai ask\` stays in the terminal ` +
           `until its ${config.ask_grace_seconds.value}s grace window, counted from registration, ` +
           `has elapsed; it goes to your devices only while the machine also meets the idle threshold. ` +
-          `Set \`require_idle = false\` to be notified even while you are working.`
+          `Run \`notifai config set require_idle false\` to be notified even while you are working.`
       : `A question registered with \`notifai ask\` stays in the terminal for ` +
           `${config.ask_grace_seconds.value}s from registration and then goes to your devices ` +
           `whether or not you are at this machine ` +
-          `(\`require_idle = false\`).`,
+          `(\`notifai config set require_idle false\` is already in effect).`,
   )
   if (config.require_idle.value) {
     deps.io.out(
@@ -1226,7 +1501,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
 }
 
 /**
- * Writes the OpenCode plugin, replacing any NotifAI plugin already there —
+ * Writes the OpenCode plugin, replacing any Notifai plugin already there —
  * including one a different checkout wrote, matched on the managed marker for
  * the same reason command hooks are.
  */
@@ -1238,7 +1513,7 @@ function installOpencodePlugin(
   if (existsSync(file)) {
     const existing = readFileSync(file, 'utf8')
     if (!isOurOpencodePlugin(existing)) {
-      deps.io.err(`${file} exists and was not written by NotifAI; move it aside first.`)
+      deps.io.err(`${file} exists and was not written by Notifai; move it aside first.`)
       return EXIT.failed
     }
   }
@@ -1254,8 +1529,9 @@ function installOpencodePlugin(
   deps.io.out('It maps chat.message to presence, session.idle to question escalation, and')
   deps.io.out('session.deleted to local cleanup through the same `notifai hook` commands')
   deps.io.out('the other harnesses run. Permission prompts stay in OpenCode.')
-  deps.io.out('OpenCode cannot reliably resume an idle agent turn with a device answer; use')
-  deps.io.out('`notifai send --reply` when the answer must return to the agent.')
+  deps.io.out('OpenCode pushes without holding its idle event open; the next user prompt')
+  deps.io.out('collects a device answer and adds it to the agent context. Use `notifai')
+  deps.io.out('send --reply` only when the answer must return before another prompt.')
   deps.io.out('')
   deps.io.out('Restart OpenCode: it loads plugins once at start.')
   return EXIT.ok
@@ -1273,11 +1549,11 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
   if (harness === 'opencode') {
     // We own the whole file, but only if we wrote it.
     if (!isOurOpencodePlugin(readFileSync(file, 'utf8'))) {
-      deps.io.out(`Left ${file} alone: NotifAI did not write it.`)
+      deps.io.out(`Left ${file} alone: Notifai did not write it.`)
       return EXIT.ok
     }
     rmSync(file, { force: true })
-    deps.io.out(`Removed the NotifAI OpenCode plugin at ${file}`)
+    deps.io.out(`Removed the Notifai OpenCode plugin at ${file}`)
     return EXIT.ok
   }
   if (harness === 'cursor') {
@@ -1297,8 +1573,8 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
     }
     deps.io.out(
       stripped.replaced.length > 0
-        ? `Removed NotifAI hooks (${stripped.replaced.join(', ')}) from ${file}`
-        : `No NotifAI hooks found in ${file}`,
+        ? `Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${file}`
+        : `No Notifai hooks found in ${file}`,
     )
     return EXIT.ok
   }
@@ -1318,8 +1594,8 @@ export function hooksUninstallCommand(deps: CommandDeps, flags: HooksInstallFlag
   }
   deps.io.out(
     stripped.replaced.length > 0
-      ? `Removed NotifAI hooks (${stripped.replaced.join(', ')}) from ${file}`
-      : `No NotifAI hooks found in ${file}`,
+      ? `Removed Notifai hooks (${stripped.replaced.join(', ')}) from ${file}`
+      : `No Notifai hooks found in ${file}`,
   )
   return EXIT.ok
 }
@@ -1453,27 +1729,69 @@ export async function configSetCommand(
  * 1.5.x, `owner/repo@name` selects a skill; a Git ref belongs after `#`.
  * Keep this immutable and public because the command is printed to users.
  */
-export const SKILLS_SOURCE = 'RafaelVidaurre/notifai#v0.1.7'
+export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.1.8'
 
-function pinnedSkillInstalled(cwd: string): boolean {
+function skillSourceParts(): { source: string; ref: string } | null {
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
-  if (!match) return false
-  const lockPath = path.join(cwd, 'skills-lock.json')
-  const installedPath = path.join(cwd, '.agents', 'skills', 'notifai', 'SKILL.md')
-  if (!existsSync(lockPath) || !existsSync(installedPath)) return false
-  try {
-    const parsed = JSON.parse(readFileSync(lockPath, 'utf8')) as {
-      skills?: Record<string, { source?: unknown; ref?: unknown; skillPath?: unknown }>
+  return match === null ? null : { source: match[1]!, ref: match[2]! }
+}
+
+function expectedSkill(skill: NativeSkill): boolean {
+  const expected = skillSourceParts()
+  return (
+    expected !== null &&
+    skill.name === 'notifai' &&
+    skill.source === expected.source &&
+    skill.sourceType === 'github' &&
+    skill.ref === expected.ref
+  )
+}
+
+async function skillReadiness(
+  deps: CommandDeps,
+  selectedScope?: SkillScope,
+): Promise<ReadinessState> {
+  const scopes: SkillScope[] = selectedScope === undefined ? ['project', 'global'] : [selectedScope]
+  const results = await Promise.all(
+    scopes.map(async (scope) => {
+      if (deps.nativeSkills === undefined) return { scope, skills: [] as NativeSkill[] }
+      try {
+        return { scope, ...(await deps.nativeSkills.list(scope, deps.cwd, deps.env)) }
+      } catch (err) {
+        return { scope, skills: [] as NativeSkill[], error: String(err) }
+      }
+    }),
+  )
+  const installed = results.flatMap(({ skills }) => skills).find(expectedSkill)
+  if (installed !== undefined) {
+    return {
+      id: 'skill',
+      title: 'Agent guidance skill',
+      status: 'ready',
+      detail: `installed from ${SKILLS_SOURCE} in the ${installed.scope} scope`,
     }
-    const skill = parsed.skills?.notifai
-    if (!skill) return false
-    return (
-      skill.source === match[1] &&
-      skill.ref === match[2] &&
-      skill.skillPath === 'skills/notifai/SKILL.md'
-    )
-  } catch {
-    return false
+  }
+
+  const errors = results
+    .filter((result) => result.error !== undefined)
+    .map((result) => `${result.scope}: ${result.error}`)
+  const scopeText = selectedScope === undefined ? 'project or machine-global scope' : `${selectedScope} scope`
+  return {
+    id: 'skill',
+    title: 'Agent guidance skill',
+    status: 'optional-gap',
+    detail:
+      errors.length > 0
+        ? `could not verify installer-managed state in ${scopeText} (${errors.join('; ')})`
+        : `not installed from ${SKILLS_SOURCE} in ${scopeText}`,
+    remedy: {
+      by: 'cli',
+      summary: 'install the skill agents follow when deciding to notify',
+      command:
+        selectedScope === undefined
+          ? 'notifai init --skills'
+          : `notifai init --skills --skills-scope ${selectedScope}`,
+    },
   }
 }
 
@@ -1496,6 +1814,8 @@ export interface InitFlags {
    * never spawn npx against the network by default.
    */
   skills?: boolean
+  /** Scope selected by an unattended caller; humans choose inside npx skills. */
+  skillsScope?: SkillScope
   /** Same tri-state, for the harness hooks. */
   hooks?: boolean
 }
@@ -1507,11 +1827,47 @@ interface SetupProofRecord {
   started_at: string
 }
 
-const DEVICE_BRIDGE_TIMEOUT_MS = 5 * 60 * 1000
+/** Long enough for a first TestFlight install; keep-waiting extends another budget. */
+const DEVICE_BRIDGE_TIMEOUT_MS = 10 * 60 * 1000
 const DEVICE_BRIDGE_POLL_MS = 2_000
 const PROOF_TIMEOUT_MS = 30_000
 const PROOF_POLL_MS = 1_000
 
+function supportPageUrl(baseUrl: string): string {
+  return `${baseUrl.replace(/\/$/, '')}/support`
+}
+
+function formatWaitBudget(milliseconds: number): string {
+  const minutes = Math.round(milliseconds / 60_000)
+  return minutes === 1 ? '1 minute' : `${minutes} minutes`
+}
+
+/** Same-account line for the device hop; prefers the real email when known. */
+function sameAccountSignInLine(email: string | null | undefined): string {
+  return email
+    ? `sign in with the same email as this account (${email})`
+    : 'sign in with the same email as this account'
+}
+
+function deviceInstallRemedy(options: {
+  baseUrl: string
+  email: string | null
+  devices: readonly RoutableDevice[]
+}): string {
+  const support = supportPageUrl(options.baseUrl)
+  const sameEmail = sameAccountSignInLine(options.email)
+  if (options.devices.length === 0) {
+    return (
+      `open the install steps at ${support} on that device (or your phone’s browser), ` +
+      `install Notifai, ${sameEmail}, and allow notifications`
+    )
+  }
+  if (options.devices.some((d) => d.permission_status === 'denied')) {
+    return 'allow notifications for Notifai in that device’s system settings'
+  }
+  return 'open Notifai on that device and allow its notification prompt'
+}
+
 function setupProofPath(deps: CommandDeps): string {
   let projectDir = path.resolve(deps.cwd)
   try {
@@ -1624,18 +1980,27 @@ async function closeGap(
   }
 
   if (state.id === 'skill') {
-    deps.io.out(`Installing the notifai agent skill (npx skills add ${SKILLS_SOURCE})...`)
-    const code = await new Promise<number>((resolve) => {
-      const child = spawn('npx', ['-y', 'skills', 'add', SKILLS_SOURCE, '--skill', 'notifai'], {
-        cwd: deps.cwd,
-        stdio: 'inherit',
-      })
-      child.on('error', () => resolve(1))
-      child.on('exit', (exitCode) => resolve(exitCode ?? 1))
-    })
+    if (deps.nativeSkills === undefined) {
+      deps.io.err('Skill installation failed — the native `npx skills` flow is unavailable.')
+      return 'failed'
+    }
+    const scopeText = flags.skillsScope === undefined ? 'the scope you choose' : `${flags.skillsScope} scope`
+    deps.io.out(`Starting the native npx skills setup for the notifai agent skill (${scopeText})...`)
+    const addOptions = {
+      source: SKILLS_SOURCE,
+      skill: 'notifai',
+      cwd: deps.cwd,
+      env: deps.env,
+      ...(flags.skillsScope === undefined ? {} : { scope: flags.skillsScope }),
+    }
+    const code = await deps.nativeSkills.add(addOptions)
     if (code !== 0) {
       deps.io.err('Skill installation failed — run it manually with:')
-      deps.io.err(`  npx skills add ${SKILLS_SOURCE} --skill notifai`)
+      deps.io.err(
+        `  npx skills add ${SKILLS_SOURCE} --skill notifai${
+          flags.skillsScope === 'global' ? ' --global' : ''
+        }${flags.skillsScope === undefined ? '' : ' --yes'}`,
+      )
     }
     return code === 0 ? 'closed' : 'failed'
   }
@@ -1669,55 +2034,104 @@ function deviceBridgeMessage(devices: readonly RoutableDevice[]): string {
 
 /**
  * Observe the supported Device Installation path while the user finishes the
- * app-side work. There is deliberately no invented QR or download URL here:
- * this release exposes neither an App Store/TestFlight URL nor a device-pairing
- * endpoint, and a placeholder bridge is worse than an explicit boundary.
+ * app-side work. The live bridge is the dashboard `/support` page (TestFlight
+ * steps). Interactive runs offer to open it so the user never types the URL;
+ * non-interactive/agent paths only print plain text and never wait on a prompt.
+ *
+ * The wait budget is stated up front. On expiry we say the *timer* expired —
+ * not the setup — and offer another budget when a human is present. Agents
+ * never hang: this whole path is gated on `io.interactive`, and keep-waiting
+ * uses `confirm` which resolves the safe default when not interactive.
  */
 async function waitForReadyDevice(deps: CommandDeps, state: ReadinessState): Promise<GapCloseResult> {
   const remedy = state.remedy
   if (deps.io.interactive !== true || remedy?.by !== 'user-elsewhere') return 'pending'
 
+  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) {
+    deps.io.err('Could not start the companion-device wait: this machine is not signed in.')
+    return 'failed'
+  }
+
+  const budgetLabel = formatWaitBudget(DEVICE_BRIDGE_TIMEOUT_MS)
+  const supportUrl = supportPageUrl(authed.baseUrl)
   await deps.io.note?.(
-    `${state.detail}\n${remedy.summary}`,
+    [
+      state.detail,
+      remedy.summary,
+      `Install steps (no typing): ${supportUrl}`,
+      `I will wait up to ${budgetLabel} for a companion device to become ready.`,
+    ].join('\n'),
     'Finish setup on your companion device',
   )
+
+  // Open the real support page so the user never has to type the URL. Decline
+  // is fine — the URL remains in the note and in the Next: line if they leave.
+  if (await deps.io.confirm('Open install instructions in your browser?', true)) {
+    deps.io.openUrl(supportUrl)
+  }
+
   if (!(await deps.io.confirm('Wait here while you finish that on your device?', true))) {
+    deps.io.out(
+      `OK — finish device setup when you can (install steps: ${supportUrl}), then re-run \`notifai init\`.`,
+    )
     return 'pending'
   }
 
-  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
-  const authed = authedClient(deps, config)
-  if (!authed) return 'failed'
   const now = deps.now ?? Date.now
-  const sleep = deps.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)))
-  const deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS
-  const spinner = await deps.io.spinner?.('Waiting for a companion device…')
+  const sleep =
+    deps.sleep ??
+    ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)))
+  const spinner = await deps.io.spinner?.(`Waiting up to ${budgetLabel} for a companion device…`)
   let lastDevices: RoutableDevice[] = []
+  let deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS
 
-  while (now() < deadline) {
-    try {
-      const response = await authed.client.listDevices()
-      lastDevices = response.devices
-      const ready = response.devices.find(deviceCanReceive)
-      if (ready) {
-        spinner?.stop(`${ready.display_name} is ready to receive`)
-        return 'closed'
-      }
-      spinner?.message(deviceBridgeMessage(response.devices))
-    } catch (err) {
-      if (!(err instanceof NetworkError)) {
-        spinner?.error('Could not check companion readiness')
-        reportError(deps, err)
-        return 'failed'
+  for (;;) {
+    while (now() < deadline) {
+      try {
+        const response = await authed.client.listDevices()
+        lastDevices = response.devices
+        const ready = response.devices.find(deviceCanReceive)
+        if (ready) {
+          spinner?.stop(`${ready.display_name} is ready to receive`)
+          return 'closed'
+        }
+        spinner?.message(deviceBridgeMessage(response.devices))
+      } catch (err) {
+        if (!(err instanceof NetworkError)) {
+          spinner?.error('Could not check companion readiness')
+          reportError(deps, err)
+          return 'failed'
+        }
+        spinner?.message('Connection lost — still watching…')
       }
-      spinner?.message('Connection lost — still watching…')
+      await sleep(Math.min(DEVICE_BRIDGE_POLL_MS, Math.max(0, deadline - now())))
     }
-    await sleep(Math.min(DEVICE_BRIDGE_POLL_MS, Math.max(0, deadline - now())))
-  }
 
-  spinner?.error('No companion device became ready')
-  deps.io.err(deviceBridgeMessage(lastDevices).replace(/…$/, '.'))
-  return 'pending'
+    // Timer expired — setup did not. Offer another budget only when a human
+    // can answer; confirm() already returns the fallback for agents, so this
+    // never hangs unattended even if interactive were mis-set.
+    spinner?.error(`The ${budgetLabel} wait timer expired`)
+    deps.io.err(
+      `The ${budgetLabel} wait timer expired — setup is not finished, only this wait.`,
+    )
+    deps.io.err(deviceBridgeMessage(lastDevices).replace(/…$/, '.'))
+    deps.io.err(
+      `Re-run \`notifai init\` later and it will pick up from here (install steps: ${supportUrl}).`,
+    )
+
+    const keepWaiting = await deps.io.confirm(
+      `Keep waiting for another ${budgetLabel}?`,
+      false,
+    )
+    if (!keepWaiting) {
+      deps.io.out('Stopping the wait. Device setup can continue; re-run `notifai init` when ready.')
+      return 'pending'
+    }
+    spinner?.message(`Waiting another ${budgetLabel} for a companion device…`)
+    deadline = now() + DEVICE_BRIDGE_TIMEOUT_MS
+  }
 }
 
 function setupProofDraft(
@@ -1726,7 +2140,7 @@ function setupProofDraft(
 ): ReturnType<typeof buildDraft> {
   const project = config.project.value
   return buildDraft(config, {
-    title: 'NotifAI is ready',
+    title: 'Notifai is ready',
     body:
       project === null
         ? 'This real notification completed setup verification.'
@@ -1804,7 +2218,7 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
     ) ?? candidates[0]
   if (!target) {
     deps.io.err(
-      'Setup proof needs a receipt-capable iPhone. The current macOS notification path does not emit Companion Receipts.',
+      "Setup proof needs a receipt-capable iPhone. The current macOS notification path does not emit Companion Receipts (the app's delivery confirmation).",
     )
     return 'pending'
   }
@@ -1836,7 +2250,9 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
   const sleep = deps.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)))
   const deadline = now() + PROOF_TIMEOUT_MS
   const spinner = deps.io.interactive === true
-    ? await deps.io.spinner?.('Waiting for a Companion Receipt…')
+    ? await deps.io.spinner?.(
+        "Waiting for a Companion Receipt (the app's delivery confirmation)…",
+      )
     : null
   let lastError: unknown = null
   let replacedMissingProof = false
@@ -1887,11 +2303,11 @@ async function runSetupProof(deps: CommandDeps): Promise<GapCloseResult> {
     await sleep(Math.min(PROOF_POLL_MS, Math.max(0, deadline - now())))
   }
 
-  spinner?.error('Companion Receipt not observed yet')
+  spinner?.stop('Delivery confirmation not observed yet')
   if (lastError instanceof NetworkError) deps.io.err(lastError.message)
-  deps.io.err(
-    `No Companion Receipt was observed for ${proof.request_id} within ${PROOF_TIMEOUT_MS / 1000}s. ` +
-      'That is not proof of non-receipt; re-run `notifai init` to check this same notification again.',
+  deps.io.out(
+    `Provider accepted the notification; Companion Receipt (the app's delivery confirmation) for ${proof.request_id} was not observed within ${PROOF_TIMEOUT_MS / 1000}s. ` +
+      'Proof may still arrive — re-run `notifai init` and it will re-check this same notification.',
   )
   return 'pending'
 }
@@ -1910,7 +2326,7 @@ function wantsOptional(deps: CommandDeps, state: ReadinessState, flags: InitFlag
   const question =
     state.id === 'hooks'
       ? 'Install harness hooks, so questions reach your devices when you are away?'
-      : 'Install/update the agent guidance skill in this repo?'
+      : 'Install/update the agent guidance skill through the native npx skills flow?'
   return deps.io.confirm(question, true)
 }
 
@@ -1931,9 +2347,36 @@ function wantsOptional(deps: CommandDeps, state: ReadinessState, flags: InitFlag
  * states rather than four branches to enumerate.
  */
 export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<number> {
-  await deps.io.intro?.('NotifAI setup')
+  if (
+    flags.skillsScope !== undefined &&
+    flags.skillsScope !== 'project' &&
+    flags.skillsScope !== 'global'
+  ) {
+    deps.io.err('Invalid skill scope. Choose `project` or `global`.')
+    return EXIT.usage
+  }
+  if (flags.skillsScope !== undefined && flags.skills !== true) {
+    deps.io.err('`--skills-scope` requires `--skills`. Choose project or global in the native installer.')
+    return EXIT.usage
+  }
+  if (
+    flags.skills === true &&
+    deps.io.interactive !== true &&
+    flags.skillsScope === undefined
+  ) {
+    deps.io.err(
+      'Unattended skill setup requires an explicit scope: `notifai init --skills --skills-scope project` or `... global`.',
+    )
+    return EXIT.usage
+  }
+  await deps.io.intro?.('Notifai setup')
 
-  let readiness = await assessReadiness(deps)
+  const reassess = () =>
+    assessReadiness(
+      deps,
+      flags.skillsScope === undefined ? {} : { skillScope: flags.skillsScope },
+    )
+  let readiness = await reassess()
   let failed = false
   const attempted = new Set<string>()
 
@@ -1963,11 +2406,16 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
         attempted.add(state.id)
         const result = await closeGap(deps, state, flags)
         if (result === 'failed') failed = true
+        if (result === 'failed' && state.status === 'optional-gap') {
+          readiness = await reassess()
+          advanced = true
+          break
+        }
         if (result !== 'closed') {
           stop = true
           break
         }
-        readiness = await assessReadiness(deps)
+        readiness = await reassess()
         advanced = true
         break
       }
@@ -1980,30 +2428,26 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
           stop = true
           break
         }
-        readiness = await assessReadiness(deps)
+        readiness = await reassess()
         advanced = true
         break
       }
 
-      // Its to launch, theirs to complete. Offering to start the sign-in is
-      // useful only when someone is demonstrably watching; an agent never
-      // reaches this prompt or opens a browser.
+      // Its to launch, theirs to complete. Running `init` is the consent; announce
+      // and open rather than re-asking. An agent never reaches this path.
       if (
         remedy.by === 'user-here' &&
         remedy.interactive === true &&
         deps.io.interactive === true
       ) {
         attempted.add(state.id)
-        if (!(await deps.io.confirm('Sign in now? (opens your browser)', true))) {
-          stop = true
-          break
-        }
+        deps.io.out('Opening your browser to approve this machine — Ctrl-C to stop.')
         if ((await loginCommand(deps, {})) !== EXIT.ok) {
           failed = true
           stop = true
           break
         }
-        readiness = await assessReadiness(deps)
+        readiness = await reassess()
         advanced = true
         break
       }
@@ -2020,7 +2464,7 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
           stop = true
           break
         }
-        readiness = await assessReadiness(deps)
+        readiness = await reassess()
         advanced = true
         break
       }
@@ -2033,14 +2477,16 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
     if (stop || !advanced) break
   }
 
-  readiness = await assessReadiness(deps)
+  readiness = await reassess()
   for (const state of readiness.states.filter((s) => s.status === 'ready')) {
     deps.io.out(`${state.title}: ${state.detail}`)
   }
 
   const blocker = firstBlocker(readiness)
   if (blocker === null) {
-    const skipped = openItems(readiness)
+    const skipped = openItems(readiness).filter(
+      (state) => !(state.id === 'skill' && flags.skills === false),
+    )
     for (const state of skipped) deps.io.out(`Optional, not set up — ${remedyLine(state)}`)
     deps.io.out('All set. Agents in this project can notify you and ask questions.')
     await deps.io.outro?.('All set ✨')
@@ -2053,7 +2499,9 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
   deps.io.out('')
   deps.io.out(`Next: ${blocker.title} — ${blocker.detail}`)
   deps.io.out(`  ${remedyLine(blocker)}`)
-  if (blocker.remedy?.by === 'user-elsewhere') {
+  // Both "do it here" and "do it elsewhere" leave setup mid-journey; re-run is
+  // how the rest is recovered either way.
+  if (blocker.remedy?.by === 'user-elsewhere' || blocker.remedy?.by === 'user-here') {
     deps.io.out('  Then re-run `notifai init` and it will pick up from here.')
   }
   await deps.io.outro?.('One step remains (above)')
@@ -2093,9 +2541,8 @@ async function contractCheck(client: ApiClient): Promise<{ name: string; ok: boo
       ok: false,
       detail:
         local !== undefined && remote < local
-          ? `server speaks schema v${remote}, this CLI speaks v${local} — the server needs deploying, ` +
-            'until then sends carrying newer fields are rejected'
-          : `server speaks schema v${remote}, this CLI speaks v${local} — update the CLI`,
+          ? `server speaks schema v${remote}, this CLI speaks v${local} — the service is being updated; try again later`
+          : `server speaks schema v${remote}, this CLI speaks v${local} — update the CLI: npm install -g @raidiant/notifai`,
     }
   } catch (err) {
     return {
@@ -2115,7 +2562,10 @@ async function contractCheck(client: ApiClient): Promise<{ name: string; ok: boo
  * `unknown`, which is the honest answer and keeps a network outage from
  * looking like a broken install.
  */
-export async function assessReadiness(deps: CommandDeps): Promise<Readiness> {
+export async function assessReadiness(
+  deps: CommandDeps,
+  options: { skillScope?: SkillScope } = {},
+): Promise<Readiness> {
   const config = loadConfig({ cwd: deps.cwd, env: deps.env })
   const states: ReadinessState[] = []
   let accountClient: ApiClient | null = null
@@ -2223,58 +2673,35 @@ export async function assessReadiness(deps: CommandDeps): Promise<Readiness> {
     )
   }
 
+  let accountEmail: string | null = null
+  let accountLookupFailed = false
   if (!credential || !reachable) {
     const why = !credential ? 'this machine is not paired' : 'the server is unreachable'
     states.push({ id: 'auth', title: 'Account', status: 'unknown', detail: `not checked — ${why}` })
-    states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: `not checked — ${why}` })
   } else {
     const client = makeClient(deps, baseUrl, `Bearer nfm_${credential.machineId}.${credential.secret}`)
     accountClient = client
     try {
-      const { devices } = await client.listDevices()
+      const [{ devices }, email] = await Promise.all([
+        client.listDevices(),
+        Promise.resolve()
+          .then(async () => (await client.accessStatus()).email)
+          .catch(() => null as string | null),
+      ])
       accountDevices = devices
-      const ready = devices.filter(deviceCanReceive)
+      accountEmail = email
       states.push({
         id: 'auth',
         title: 'Account',
         status: 'ready',
-        detail: `machine ${credential.machineId} accepted`,
+        detail: accountEmail
+          ? `machine ${credential.machineId} accepted (${accountEmail})`
+          : `machine ${credential.machineId} accepted`,
       })
-      states.push(
-        ready.length > 0
-          ? {
-              id: 'devices',
-              title: 'Your devices',
-              status: 'ready',
-              detail: `${ready.map((d) => d.display_name).join(', ')} ready to receive`,
-            }
-          : {
-              id: 'devices',
-              title: 'Your devices',
-              status: 'gap',
-              // The one gap that cannot be closed from this terminal, and the
-              // likeliest place a first setup is abandoned. Naming which of
-              // the three sub-states it is matters: "install the app" is
-              // useless advice to someone who installed it and denied the
-              // permission prompt.
-              detail:
-                devices.length === 0
-                  ? 'nothing registered yet; this release has no supported App Store/TestFlight URL for the CLI to open'
-                  : `${devices.map((d) => `${d.display_name} (${d.permission_status})`).join(', ')} — registered but not able to receive`,
-              remedy: {
-                by: 'user-elsewhere',
-                summary:
-                  devices.length === 0
-                    ? 'install NotifAI through a supported distribution you already have, open it, sign in with the same account, and allow notifications'
-                    : devices.some((d) => d.permission_status === 'denied')
-                      ? 'allow notifications for NotifAI in that device’s system settings'
-                      : 'open NotifAI on that device and allow its notification prompt',
-              },
-            },
-      )
     } catch (err) {
       // A credential the server rejects is revocation, not absence, and the
       // remedy is the same sign-in either way.
+      accountLookupFailed = true
       states.push({
         id: 'auth',
         title: 'Account',
@@ -2286,32 +2713,56 @@ export async function assessReadiness(deps: CommandDeps): Promise<Readiness> {
           command: 'notifai login',
         },
       })
-      states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: 'not checked — sign-in failed' })
     }
   }
 
+  // Optional setup that works without a companion device must appear before the
+  // device gap: init stops at the first user-elsewhere blocker, and hooks/skill
+  // are reachable without a phone.
   states.push(...hookStates(deps))
+  states.push(await skillReadiness(deps, options.skillScope))
 
-  states.push(
-    pinnedSkillInstalled(deps.cwd)
-      ? {
-          id: 'skill',
-          title: 'Agent guidance skill',
-          status: 'ready',
-          detail: `installed from ${SKILLS_SOURCE} in this project`,
-        }
-      : {
-          id: 'skill',
-          title: 'Agent guidance skill',
-          status: 'optional-gap',
-          detail: `not installed from ${SKILLS_SOURCE} in this project`,
-          remedy: {
-            by: 'cli',
-            summary: 'install the skill agents follow when deciding to notify',
-            command: 'notifai init --skills',
+  if (!credential || !reachable) {
+    const why = !credential ? 'this machine is not paired' : 'the server is unreachable'
+    states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: `not checked — ${why}` })
+  } else if (accountLookupFailed || accountDevices === null) {
+    states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: 'not checked — sign-in failed' })
+  } else {
+    const devices = accountDevices
+    const ready = devices.filter(deviceCanReceive)
+    states.push(
+      ready.length > 0
+        ? {
+            id: 'devices',
+            title: 'Your devices',
+            status: 'ready',
+            detail: `${ready.map((d) => d.display_name).join(', ')} ready to receive`,
+          }
+        : {
+            id: 'devices',
+            title: 'Your devices',
+            status: 'gap',
+            // The one gap that cannot be closed from this terminal, and the
+            // likeliest place a first setup is abandoned. Naming which of
+            // the three sub-states it is matters: "install the app" is
+            // useless advice to someone who installed it and denied the
+            // permission prompt. The live bridge is /support on the
+            // dashboard origin — not a placeholder, and not typed by hand.
+            detail:
+              devices.length === 0
+                ? `nothing registered yet; install Notifai on iPhone or Mac via ${supportPageUrl(baseUrl)}`
+                : `${devices.map((d) => `${d.display_name} (${d.permission_status})`).join(', ')} — registered but not able to receive`,
+            remedy: {
+              by: 'user-elsewhere',
+              summary: deviceInstallRemedy({
+                baseUrl,
+                email: accountEmail,
+                devices,
+              }),
+            },
           },
-        },
-  )
+    )
+  }
 
   states.push(await setupProofState(deps, config, accountClient, accountDevices))
 
@@ -2345,16 +2796,18 @@ async function setupProofState(
 
   const ios = readyIosDevices(devices)
   if (ios.length === 0) {
+    // Honest non-blocking caveat: notifications can reach the Mac; only the
+    // receipt proof path is unavailable in this release. Never emit a Next:
+    // step the user cannot satisfy, and never claim unobserved proof.
     return {
       id: 'proof',
       title: 'Delivery proof',
-      status: 'gap',
+      status: 'optional-gap',
       detail:
-        'blocked — the current macOS notification path does not emit Companion Receipts, so this CLI cannot prove receipt on a macOS-only setup',
+        "unprovable in this release — notifications can reach your Mac, but the macOS path does not emit Companion Receipts (the app's delivery confirmation); receipt proof needs an iPhone",
       remedy: {
         by: 'user-elsewhere',
-        summary:
-          'pair a receipt-capable iPhone build; no supported macOS receipt bridge is available in this release',
+        summary: 'receipt proof needs an iPhone in this release (notifications still reach this Mac)',
       },
     }
   }
@@ -2366,10 +2819,12 @@ async function setupProofState(
       id: 'proof',
       title: 'Delivery proof',
       status: 'gap',
-      detail: 'no Companion Receipt has proven this project on this machine yet',
+      detail:
+        "no Companion Receipt (the app's delivery confirmation) has proven this project on this machine yet",
       remedy: {
         by: 'cli',
-        summary: 'send one real verification notification and wait for its Companion Receipt',
+        summary:
+          "send one real verification notification and wait for its Companion Receipt (the app's delivery confirmation)",
         command: 'notifai init',
       },
     }
@@ -2383,14 +2838,14 @@ async function setupProofState(
         id: 'proof',
         title: 'Delivery proof',
         status: 'ready',
-        detail: `Companion Receipt observed from ${observed.delivery.device_name} at ${observed.observedAt} (${proof.request_id})`,
+        detail: `Companion Receipt (the app's delivery confirmation) observed from ${observed.delivery.device_name} at ${observed.observedAt} (${proof.request_id})`,
       }
     }
     return {
       id: 'proof',
       title: 'Delivery proof',
       status: 'gap',
-      detail: `${proof.request_id} was sent, but its Companion Receipt is still unknown`,
+      detail: `${proof.request_id} was sent, but its Companion Receipt (the app's delivery confirmation) is still unknown`,
       remedy: {
         by: 'cli',
         summary: 'check the same verification notification again',
@@ -2418,7 +2873,7 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   const ok = blocker === null
 
   if (flags.json) {
-    deps.io.out(JSON.stringify({ ok, states: readiness.states }, null, 2))
+    deps.io.out(JSON.stringify({ ok, exit_code: ok ? EXIT.ok : EXIT.failed, states: readiness.states }, null, 2))
     return ok ? EXIT.ok : EXIT.failed
   }
 
@@ -2428,12 +2883,19 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   // problems in dependency order has an obvious first move and saying so
   // costs nothing.
   if (deps.io.interactive === true && deps.io.check) {
-    await deps.io.intro?.('NotifAI doctor')
+    await deps.io.intro?.('Notifai doctor')
     for (const s of readiness.states) await deps.io.check(s.status !== 'gap', line(s))
     await deps.io.outro?.(ok ? 'Everything looks good' : `Start with: ${remedyLine(blocker)}`)
   } else {
     for (const s of readiness.states) {
-      const mark = s.status === 'gap' ? 'FAIL' : s.status === 'unknown' ? '  ? ' : 'ok  '
+      const mark =
+        s.status === 'gap'
+          ? 'FAIL'
+          : s.status === 'unknown'
+            ? '  ? '
+            : s.status === 'optional-gap'
+              ? '  --'
+              : 'ok  '
       deps.io.out(`${mark}  ${line(s)}`)
     }
     if (!ok) deps.io.out(`\nStart with: ${remedyLine(blocker)}`)
@@ -2476,39 +2938,67 @@ function remedyLine(state: ReadinessState): string {
  */
 function hookStates(deps: CommandDeps): ReadinessState[] {
   const installations = findInstallations(deps.cwd, deps.env)
+  const active = activeHarnessSession(deps.env)
+  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
+  const settings: ReadinessState = {
+    id: 'question-routing-settings',
+    title: 'Question routing settings',
+    status: 'ready',
+    detail: [
+      `ask_notifications=${config.ask_notifications.value} (${config.ask_notifications.source})`,
+      `require_idle=${config.require_idle.value} (${config.require_idle.source})`,
+      `away_after_seconds=${config.away_after_seconds.value} (${config.away_after_seconds.source})`,
+      `ask_grace_seconds=${config.ask_grace_seconds.value} (${config.ask_grace_seconds.source})`,
+      `hook_reply_timeout_seconds=${config.hook_reply_timeout_seconds.value} (${config.hook_reply_timeout_seconds.source})`,
+    ].join(', '),
+  }
   if (installations.length === 0) {
     return [
       {
         id: 'hooks',
         title: 'Question routing',
-        status: 'optional-gap',
-        detail: 'hooks not installed, so questions stay in the terminal',
+        status: active === null ? 'optional-gap' : 'gap',
+        detail:
+          active === null
+            ? 'hooks not installed, so questions stay in the terminal'
+            : `active ${active.label} session detected, but ${active.label} hooks are not installed; \`notifai ask\` cannot route this session`,
         remedy: {
           by: 'cli',
           summary: 'install harness hooks so questions reach your devices when you are away',
-          command: 'notifai hooks install',
+          command:
+            active === null
+              ? 'notifai hooks install'
+              : `notifai hooks install --harness ${active.harness}`,
         },
       },
+      settings,
     ]
   }
 
   /** Real but not in the way; see the note above. */
-  const informational = new Set(['hooks (fired)', 'hooks (opencode continuation)'])
-  return hookChecks(deps).map((check) => ({
-    id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
-    title: check.name === 'hooks' ? 'Question routing' : check.name,
-    status: check.ok ? 'ready' : informational.has(check.name) ? 'optional-gap' : 'gap',
-    detail: check.detail,
-    ...(check.ok
-      ? {}
-      : {
-          remedy: {
-            by: 'user-here' as const,
-            summary: 'the detail above names what to change',
-            command: 'notifai hooks install',
-          },
-        }),
-  }))
+  const informational = new Set(['hooks (opencode continuation)'])
+  if (active === null) informational.add('hooks (fired)')
+  return [
+    ...hookChecks(deps).map((check) => ({
+      id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
+      title:
+        check.name === 'hooks' || check.name.startsWith('hooks (active')
+          ? 'Question routing'
+          : check.name,
+      status: check.ok ? 'ready' as const : informational.has(check.name) ? 'optional-gap' as const : 'gap' as const,
+      detail: check.detail,
+      ...(check.ok
+        ? {}
+        : {
+            remedy: {
+              by: 'user-here' as const,
+              summary: 'the detail above names what to change',
+              command: 'notifai hooks install',
+            },
+          }),
+    })),
+    settings,
+  ]
 }
 
 function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: string }[] {
@@ -2533,6 +3023,39 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
       .join(', '),
   })
 
+  const active = activeHarnessSession(deps.env)
+  const activeInstallations =
+    active === null
+      ? []
+      : installations.filter((installation) => installation.harness === active.harness)
+  if (active !== null) {
+    checks.push({
+      name: 'hooks (active harness)',
+      ok: activeInstallations.length > 0,
+      detail:
+        activeInstallations.length > 0
+          ? `active ${active.label} session has a matching hook installation`
+          : `active ${active.label} session has no matching hook installation — run \`notifai hooks install --harness ${active.harness}\``,
+    })
+    if (activeInstallations.length > 0) {
+      const pointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)())
+      const matches =
+        pointer !== null &&
+        pointer.harness === active.harness &&
+        (active.sessionId === undefined || pointer.sessionId === active.sessionId)
+      checks.push({
+        name: 'hooks (active session)',
+        ok: matches,
+        detail:
+          pointer === null
+            ? `active ${active.label} session has not published a live pointer — send one ${active.label} prompt, then check again`
+            : matches
+              ? `the project pointer belongs to the active ${active.label} session`
+              : `the project pointer belongs to another ${active.label} session or harness; refusing cross-session routing`,
+      })
+    }
+  }
+
   // A handler naming an event this build dropped exits 2 every time the harness
   // fires it, which the harness reports as a hook failure.
   const stale = installations.flatMap((i) =>
@@ -2563,6 +3086,29 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
     })
   }
 
+  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
+  const requiredTimeout = blockingHookTimeoutSeconds(
+    config.ask_grace_seconds.value,
+    config.hook_reply_timeout_seconds.value,
+  )
+  const shortTimeouts = installations.flatMap((installation) =>
+    installation.handlers
+      .filter((handler) => handlerEvent(handler.command) === 'stop')
+      .filter((handler) => handler.timeout === undefined || handler.timeout < requiredTimeout)
+      .map(
+        (handler) =>
+          `${installation.harness} declares ${handler.timeout ?? 'no'}s, needs ${requiredTimeout}s — run \`notifai hooks install --harness ${installation.harness}${installation.global ? ' --global' : ''}\``,
+      ),
+  )
+  checks.push({
+    name: 'hooks (timeout)',
+    ok: shortTimeouts.length === 0,
+    detail:
+      shortTimeouts.length === 0
+        ? `installed Stop timeouts cover the current ${requiredTimeout}s grace/reply budget`
+        : shortTimeouts.join('; '),
+  })
+
   // Two checkouts each installing hooks means both fire for the same event, and
   // the user gets every question twice.
   //
@@ -2586,19 +3132,22 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
       detail: duplicated
         .map(
           (entry) =>
-            `${entry.harness}: ${entry.scripts.size} different NotifAI builds are installed, so each event will fire all of them. Uninstall the ones you do not want: ${[...entry.scripts].join(', ')}`,
+            `${entry.harness}: ${entry.scripts.size} different Notifai builds are installed, so each event will fire all of them. Uninstall the ones you do not want: ${[...entry.scripts].join(', ')}`,
         )
         .join('; '),
     })
   }
 
-  const fired = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)()) !== null
+  const firedPointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)())
+  const fired = firedPointer !== null
+  const activationInstallations =
+    active !== null && activeInstallations.length > 0 ? activeInstallations : installations
   checks.push({
     name: 'hooks (fired)',
     ok: fired,
     detail: fired
       ? 'a session in this directory has run them'
-      : `no session pointer from the last 24 hours — ${hookActivationAdvice(installations)}`,
+      : `no session pointer from the last 24 hours — ${hookActivationAdvice(activationInstallations)}`,
   })
 
   if (installations.some((installation) => installation.harness === 'opencode')) {
@@ -2606,7 +3155,7 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
       name: 'hooks (opencode continuation)',
       ok: false,
       detail:
-        'question routing is installed, but OpenCode cannot reliably resume an idle agent turn with the answer; use `notifai send --reply` for decisions',
+        'question routing is installed; OpenCode cannot resume an idle turn automatically, but its next user prompt collects the answer',
     })
   }
 
@@ -2731,10 +3280,16 @@ export function realIo(env: NodeJS.ProcessEnv = process.env): CommandIo {
       else log.error(message)
     },
     openUrl: (url) => {
-      const command =
-        process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'
       try {
-        spawn(command, [url], { stdio: 'ignore', detached: true }).unref()
+        if (process.platform === 'darwin') {
+          spawn('open', [url], { stdio: 'ignore', detached: true }).unref()
+        } else if (process.platform === 'win32') {
+          // `start` is a cmd builtin; spawn('start', …) cannot work on Windows.
+          // Empty title argument keeps URLs with special characters intact.
+          spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref()
+        } else {
+          spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref()
+        }
       } catch {
         // Browser opening is best-effort; the URL is printed anyway.
       }