@raidiant/notifai 9.2.0 → 9.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "9.2.0",
+  "version": "9.2.2",
   "type": "module",
   "description": "Send native device notifications from agents and local programs",
   "bin": {
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "5.0.0",
+    "@raidiant/notifai-protocol": "5.0.1",
     "commander": "^14.0.0",
     "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"

package/src/commands-auth.ts

@@ -13,6 +13,7 @@ import {
   reportError,
   type CommandDeps,
 } from './commands-core.js'
+import { supportPageUrl } from './commands-devices.js'
 
 // ---------------------------------------------------------------------------
 // login / logout / auth status
@@ -123,7 +124,7 @@ export async function loginCommand(
     if (poll.status === 'no_active_plan') {
       const next =
         poll.next_action ??
-        `Open ${baseUrl.replace(/\/$/, '')}/support to request Alpha access, then retry.`
+        `Open ${supportPageUrl(baseUrl)} 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}`)
@@ -189,7 +190,7 @@ export async function accessStatusCommand(
       return access.status === 'active' ? EXIT.ok : EXIT.failed
     }
     if (access.status === 'no_active_plan') {
-      const supportUrl = `${authed.baseUrl.replace(/\/$/, '')}/support`
+      const supportUrl = supportPageUrl(authed.baseUrl)
       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

package/src/commands-devices.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+import { supportPageUrl } from './commands-devices.js'
+
+describe('supportPageUrl', () => {
+  it('routes hosted control-plane origins to the dashboard support surface', () => {
+    expect(supportPageUrl('https://api.notifai.sh')).toBe('https://app.notifai.sh/support')
+    expect(supportPageUrl('https://notifai.fly.dev/')).toBe('https://app.notifai.sh/support')
+  })
+
+  it('keeps a self-hosted deployment on its own support route', () => {
+    expect(supportPageUrl('https://notifai.example.test/')).toBe(
+      'https://notifai.example.test/support',
+    )
+  })
+})

package/src/commands-devices.ts

@@ -121,7 +121,11 @@ export async function capabilitiesCommand(
 }
 
 export function supportPageUrl(baseUrl: string): string {
-  return `${baseUrl.replace(/\/$/, '')}/support`
+  const normalized = baseUrl.replace(/\/+$/, '')
+  if (normalized === 'https://api.notifai.sh' || normalized === 'https://notifai.fly.dev') {
+    return 'https://app.notifai.sh/support'
+  }
+  return `${normalized}/support`
 }
 
 /** Same-account line for the device hop; prefers the real email when known. */

package/src/commands-harness-context.ts

@@ -6,7 +6,7 @@ import { type Harness } from './install-hooks.js'
  * 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.
+ * plugin API exposes Agent Session identity but the ordinary environment does not.
  */
 export interface ActiveHarnessSession {
   harness: Harness
@@ -67,7 +67,7 @@ interface ActiveHarnessResolution {
 }
 
 /**
- * Which harness session owns this shell, when several claim to.
+ * Which Agent Session owns this shell, when several claim to.
  *
  * Nesting is ordinary: an orchestrator running inside Claude Code starts a
  * Codex session, and that Codex process inherits `CLAUDECODE` and

package/src/commands-hooks.ts

@@ -1124,12 +1124,12 @@ export function askCommand(
       flags,
       'session_identity_missing',
       'exact_session',
-      'Could not prove which live harness session owns this command.',
-      'run it from a supported harness with exact session identity, or use a blocking `notifai send --reply` question',
+      'Could not prove which live Agent Session owns this command.',
+      'run it from a supported harness with exact Agent Session identity, or use a blocking `notifai send --reply` question',
     )
   }
   if (!sessionId) {
-    return askFailure(deps, flags, 'session_identity_missing', 'exact_session', 'No exact active session is available.', 'use a blocking `notifai send --reply` question')
+    return askFailure(deps, flags, 'session_identity_missing', 'exact_session', 'No exact active Agent Session is available.', 'use a blocking `notifai send --reply` question')
   }
   let routingConfig: CliConfig
   try {
@@ -1592,6 +1592,8 @@ function parkClosedQuestion(
 export interface HooksInstallFlags {
   harness?: string
   global?: boolean
+  /** Init owns the final setup result and suppresses per-harness close narration. */
+  narrate?: boolean
   /** Test seam; production resolves the running CLI. */
   execPath?: string
   scriptPath?: string
@@ -1706,9 +1708,11 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       return hooksInstallCommand(deps, { ...flags, global: true, harness })
     }
     const globalFile = globalInstallation?.file
-    deps.io.out(
-      `${HARNESS_LABELS[harness]} hooks already cover this machine (${globalFile}). This project does not need its own copy. To wire only this project: notifai hooks uninstall --harness ${harness} --global && notifai hooks install --harness ${harness}`,
-    )
+    if (flags.narrate !== false) {
+      deps.io.out(
+        `${HARNESS_LABELS[harness]} hooks already cover this machine (${globalFile}). This project does not need its own copy. To wire only this project: notifai hooks uninstall --harness ${harness} --global && notifai hooks install --harness ${harness}`,
+      )
+    }
     return EXIT.ok
   }
   if (wantGlobal && otherScope.some((installation) => !installation.global)) {
@@ -1731,6 +1735,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       timeoutSeconds: BLOCKING_STOP_TIMEOUT_SECONDS,
       platform: hookPlatform,
       nodePath,
+      ...(flags.narrate === undefined ? {} : { narrate: flags.narrate }),
     })
   }
 
@@ -1755,7 +1760,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
       deps.io.err(String(err))
       return EXIT.failed
     }
-    printHooksInstallClose(deps, harness, settingsTarget)
+    if (flags.narrate !== false) printHooksInstallClose(deps, harness, settingsTarget)
     return EXIT.ok
   }
 
@@ -1806,7 +1811,7 @@ export function hooksInstallCommand(deps: CommandDeps, flags: HooksInstallFlags)
     const layer = flags.global ? null : codexLayerDir(deps.cwd)
     if (layer !== null) mkdirSync(layer, { recursive: true })
   }
-  printHooksInstallClose(deps, harness, installed.file)
+  if (flags.narrate !== false) printHooksInstallClose(deps, harness, installed.file)
   if (installed.foreignStopCount > 0) {
     deps.io.out(
       "This layer already has a Stop handler. Codex runs every matching handler, so Notifai's Stop and the existing one will both fire.",
@@ -1853,6 +1858,7 @@ function installOpencodePlugin(
     timeoutSeconds: number
     platform?: NodeJS.Platform
     nodePath?: string
+    narrate?: boolean
   },
 ): number {
   try {
@@ -1874,7 +1880,7 @@ function installOpencodePlugin(
     deps.io.err(String(err))
     return EXIT.failed
   }
-  printHooksInstallClose(deps, 'opencode', file)
+  if (options.narrate !== false) printHooksInstallClose(deps, 'opencode', file)
   return EXIT.ok
 }
 

package/src/commands-init.ts

@@ -13,7 +13,14 @@ import { ApiCallError, NetworkError, type ApiClient } from './client.js'
 import { personalProjectConfigPath, type CliConfig } from './config.js'
 import { projectSlugFrom as inferredProjectSlugFrom } from './invocation-context.js'
 import { SKILLS_INSTALLER_SPEC, type SkillScope } from './native-skills.js'
-import { firstBlocker, readinessJson, type Readiness, type ReadinessRefresh, type ReadinessState } from './readiness.js'
+import {
+  firstBlocker,
+  questionRoutingReady,
+  readinessJson,
+  type Readiness,
+  type ReadinessRefresh,
+  type ReadinessState,
+} from './readiness.js'
 import { buildDraft, formatReceipt } from './send.js'
 import { loginCommand } from './commands-auth.js'
 import {
@@ -116,6 +123,7 @@ async function closeGap(
   flags: InitFlags,
 ): Promise<GapCloseResult> {
   if (state.id === 'project') {
+    if (flags.setupScope === undefined) return 'failed'
     const slug = projectSlugFrom(flags.projectId ?? path.basename(deps.cwd))
     const configPath =
       flags.setupScope === 'global'
@@ -137,7 +145,7 @@ async function closeGap(
     let ok = true
     const hookFlags = flags.setupScope === 'global' ? { global: true as const } : {}
     for (const harness of harnesses) {
-      if (hooksInstallCommand(deps, { harness, ...hookFlags }) !== EXIT.ok) ok = false
+      if (hooksInstallCommand(deps, { harness, ...hookFlags, narrate: false }) !== EXIT.ok) ok = false
     }
     return ok ? 'closed' : 'failed'
   }
@@ -619,9 +627,9 @@ async function resolveSetupScope(
     deps.io.err('No setup scope selected. Pass `--setup-scope project` or `--setup-scope global`.')
     return 'usage'
   }
-  if (flags.skills === true) {
+  if (flags.skills === true || flags.hooks === true) {
     deps.io.err(
-      'Unattended skill setup requires an explicit scope: `notifai init --skills --setup-scope project` or `... global`.',
+      'Unattended setup changes require an explicit scope: pass `--setup-scope project` or `--setup-scope global`.',
     )
     return 'usage'
   }
@@ -683,6 +691,10 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
 
       if (state.status === 'optional-gap') {
         if (remedy.by !== 'cli' || !(await wantsOptional(workingDeps, state, resolved))) continue
+        if (resolved.setupScope === undefined && state.id === 'project') {
+          stop = true
+          break
+        }
         attempted.add(state.id)
         const result = await closeGap(workingDeps, state, resolved)
         if (result === 'failed') failed = true
@@ -701,6 +713,10 @@ export async function initCommand(deps: CommandDeps, flags: InitFlags): Promise<
       }
 
       if (remedy.by === 'cli') {
+        if (resolved.setupScope === undefined && state.id === 'project') {
+          stop = true
+          break
+        }
         attempted.add(state.id)
         const result = await closeGap(workingDeps, state, resolved)
         if (result === 'failed') failed = true
@@ -783,12 +799,6 @@ function printOptionalLeftovers(deps: CommandDeps, leftovers: readonly Readiness
   }
 }
 
-function questionsWillRoute(readiness: Readiness): boolean {
-  const hooks = readiness.states.find((state) => state.id === 'hooks')
-  const settings = readiness.states.find((state) => state.id === 'question-routing-settings')
-  return hooks?.status === 'ready' && settings?.status !== 'gap'
-}
-
 async function printInitClose(
   deps: CommandDeps,
   readiness: Readiness,
@@ -796,7 +806,7 @@ async function printInitClose(
 ): Promise<void> {
   const blocker = firstBlocker(readiness)
   const canSend = readiness.states.find((state) => state.id === 'devices')?.status === 'ready'
-  const questions = questionsWillRoute(readiness)
+  const questions = questionRoutingReady(readiness)
   const leftovers = leftoverOptionals(readiness, flags).filter(
     (state) => state.id !== 'contract',
   )
@@ -813,14 +823,14 @@ async function printInitClose(
         canSend ? 'You can send notifications.' : 'You are signed in.',
         questions
           ? 'Questions will reach your devices.'
-          : 'Questions stay in the terminal until hooks are installed.',
+          : 'Questions are terminal-only until Question Routing is ready.',
       ]
       await deps.io.note?.(lines.join('\n'), 'Ready')
       printOptionalLeftovers(deps, leftovers)
       deps.io.out(
       questions
         ? 'All set. Agents in this project can notify you and ask you questions.'
-        : 'All set. Agents in this project can notify you. Questions stay in the terminal until hooks are installed.',
+        : 'All set. Agents in this project can notify you. Questions are terminal-only until Question Routing is ready.',
     )
       await deps.io.outro?.('All set ✨')
       return
@@ -840,7 +850,7 @@ async function printInitClose(
     deps.io.out(
       questions
         ? 'All set. Agents in this project can notify you and ask you questions.'
-        : 'All set. Agents in this project can notify you. Questions stay in the terminal until hooks are installed.',
+        : 'All set. Agents in this project can notify you. Questions are terminal-only until Question Routing is ready.',
     )
     return
   }

package/src/commands-send-support.ts

@@ -17,7 +17,7 @@ function managedSessionTitle(
 ): string | undefined {
   if (active?.sessionLabel !== undefined) return active.sessionLabel
   // The Orca worktree title names the workspace, not one harness: every
-  // harness session Orca starts inside that worktree inherits the same
+  // Agent Session that Orca starts inside that worktree inherits the same
   // environment selector, so any active session with an identity to label
   // may use it. An explicit label still wins without paying for the lookup.
   if (

package/src/commands-send.ts

@@ -392,7 +392,7 @@ function emitSendWarnings(
   }
   if (/^(?:update|done|question|failed|blocked)\s*(?:[·:—-]|$)/i.test(flags.title.trim())) {
     deps.io.err(
-      'Heads up: keep the title to the specific substance. Put notification type in --kind; project identity is inferred separately.',
+      'Heads up: keep the title to the specific substance. Put notification type in --kind; Project identity is inferred separately.',
     )
   }
   if (

package/src/commands.test.ts

@@ -4202,7 +4202,7 @@ describe('init', () => {
       store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'empty store' },
     }
 
-    expect(await initCommand(deps, {})).toBe(EXIT.failed)
+    expect(await initCommand(deps, { setupScope: 'project' })).toBe(EXIT.failed)
     const configPath = path.join(cwd, '.notifai', 'config.toml')
     expect(readFileSync(configPath, 'utf8')).toContain('project = "my-project-')
     // Safe by default: without an explicit --skills opt-in, init only writes
@@ -4211,7 +4211,7 @@ describe('init', () => {
     expect(io.outLines.join('\n')).not.toContain('All set.')
 
     io.outLines = []
-    expect(await initCommand(deps, { skills: false })).toBe(EXIT.failed)
+    expect(await initCommand(deps, { setupScope: 'project', skills: false })).toBe(EXIT.failed)
     // Idempotent: the second run re-derives the same slug and does not reprint
     // doctor's ready-state dump.
     expect(io.outLines.join('\n')).toMatch(/^Next:/m)
@@ -4253,7 +4253,13 @@ describe('init', () => {
       env: isolatedEnv(cwd),
     }
 
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
+    expect(
+      await initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.failed)
     expect(io.outLines).toContain("Notifai can't send notifications until you update.")
     expect(io.outLines).toContain('npm install -g @raidiant/notifai')
     expect(io.outros).toEqual([])
@@ -4264,10 +4270,16 @@ describe('init', () => {
     io.errLines = []
     io.outros = []
 
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
+    expect(
+      await initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.ok)
     expect(submissions).toBe(1)
     expect(io.outLines).toContain(
-      'All set. Agents in this project can notify you. Questions stay in the terminal until hooks are installed.',
+      'All set. Agents in this project can notify you. Questions are terminal-only until Question Routing is ready.',
     )
     expect(io.outLines).not.toContain('npm install -g @raidiant/notifai')
     expect(io.errLines).toEqual([])
@@ -4302,22 +4314,31 @@ describe('init', () => {
     const io = new CapturedIo()
     const deps = { ...makeDeps(io, {} as ApiClient), cwd }
 
-    expect(await initCommand(deps, { projectId: 'Custom Name', skills: false })).toBe(EXIT.failed)
+    expect(
+      await initCommand(deps, {
+        projectId: 'Custom Name',
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.failed)
     expect(readFileSync(path.join(cwd, '.notifai', 'config.toml'), 'utf8')).toContain(
       'project = "custom-name"',
     )
   })
 
-  it('run unattended, names the optional steps instead of running or asking about them', async () => {
-    // An agent's init must not reach for npx or a prompt.
+  it('does not let an unattended readiness pass silently choose project scope', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'init-agent-'))
     const io = new CapturedIo()
     const deps = { ...makeDeps(io, {} as ApiClient), cwd }
 
-    expect(await initCommand(deps, {})).toBe(EXIT.failed)
-    const out = io.outLines.join('\n')
-    expect(out).not.toContain('Installing the notifai agent skill')
-    // Never prompted, and never assumed into a change it did not request.
+    expect(await initCommand(deps, { json: true, hooks: false, skills: false })).toBe(EXIT.failed)
+    expect(existsSync(path.join(cwd, '.notifai', 'config.toml'))).toBe(false)
+    const result = JSON.parse(io.outLines[0] ?? '{}') as {
+      states: Array<{ id: string; status: string }>
+    }
+    expect(result.states.find((state) => state.id === 'project')).toMatchObject({
+      status: 'optional-gap',
+    })
     expect(io.errLines).toEqual([])
   })
 
@@ -4765,7 +4786,7 @@ describe('init', () => {
       list: async () => ({ skills: [] }),
     }
     const deps = setupReadyDeps(io, cwd, nativeSkills, calls)
-    await initCommand(deps, { hooks: true, skills: false })
+    await initCommand(deps, { hooks: true, setupScope: 'project', skills: false })
     const wired = findInstallations(cwd, deps.env, deps.hookAdapterHome).map(
       (installation) => installation.harness,
     )
@@ -4773,8 +4794,9 @@ describe('init', () => {
     expect(existsSync(path.join(cwd, '.claude', 'settings.local.json'))).toBe(true)
     expect(existsSync(path.join(cwd, '.codex', 'hooks.json'))).toBe(false)
     expect(existsSync(path.join(cwd, '.codex', 'config.toml'))).toBe(true)
-    expect(io.outLines.join('\n')).toContain('Installed claude-code hooks')
-    expect(io.outLines.join('\n')).toContain('Installed codex hooks')
+    expect(io.outLines.join('\n')).not.toContain('Installed claude-code hooks')
+    expect(io.outLines.join('\n')).not.toContain('Installed codex hooks')
+    expect(io.outLines.join('\n')).toContain('Next: Codex hook trust')
   })
 
   it('lets a human keep a subset of the detected harnesses', async () => {
@@ -4825,7 +4847,7 @@ describe('init', () => {
       store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'empty store' },
     }
 
-    expect(await initCommand(deps, {})).toBe(EXIT.failed)
+    expect(await initCommand(deps, { setupScope: 'project' })).toBe(EXIT.failed)
     expect(io.outLines.join('\n')).toContain('notifai login')
   })
 
@@ -4854,7 +4876,7 @@ describe('init', () => {
       store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'empty store' },
     }
 
-    expect(await initCommand(deps, {})).toBe(EXIT.failed)
+    expect(await initCommand(deps, { setupScope: 'project' })).toBe(EXIT.failed)
     expect(asked.some((q) => q.includes('Sign in'))).toBe(false)
     const out = io.outLines.join('\n')
     expect(out).toContain('Opening your browser to approve this machine — Ctrl-C to stop.')
@@ -4949,7 +4971,7 @@ describe('init', () => {
       } satisfies NativeSkills,
     }
 
-    expect(await initCommand(deps, {})).toBe(EXIT.ok)
+    expect(await initCommand(deps, { setupScope: 'project' })).toBe(EXIT.ok)
     expect(asked).toEqual(expect.arrayContaining([expect.stringMatching(/hooks/)]))
     expect(asked).toEqual(expect.arrayContaining([expect.stringMatching(/skill/)]))
     const out = io.outLines.join('\n')
@@ -5026,7 +5048,13 @@ describe('init', () => {
       },
     }
 
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
+    expect(
+      await initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.ok)
     expect(io.prompts).toEqual([
       'Open install instructions in your browser?',
       'Wait here while you finish that on your device?',
@@ -5049,7 +5077,13 @@ describe('init', () => {
     io.outLines = []
     io.prompts = []
     io.openedUrls = []
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
+    expect(
+      await initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.ok)
     expect(submitCalls).toBe(1)
     expect(io.prompts).toEqual([])
     expect(io.outLines.join('\n')).toContain('All set.')
@@ -5094,7 +5128,13 @@ describe('init', () => {
       },
     }
 
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.ok)
+    expect(
+      await initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.ok)
     expect(io.errLines.join('\n')).toContain('wait timer expired')
     expect(io.errLines.join('\n')).toMatch(/setup is not finished, only this wait/)
     expect(io.prompts.some((q) => q.includes('Keep waiting'))).toBe(true)
@@ -5130,7 +5170,13 @@ describe('init', () => {
       env: isolatedEnv(cwd),
     }
 
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
+    expect(
+      await initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.failed)
     const out = io.outLines.join('\n')
     expect(out).toContain('Next: Your devices')
     expect(out).toContain('https://test.notifai.invalid/support')
@@ -5178,7 +5224,13 @@ describe('init', () => {
       },
     }
 
-    expect(await initCommand(deps, { hooks: false, skills: false })).toBe(EXIT.failed)
+    expect(
+      await initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).toBe(EXIT.failed)
     expect(submitCalls).toBe(1)
     expect(io.outLines.join('\n')).toContain('Next: Delivery proof')
     expect(io.outLines.join('\n')).toContain('Provider accepted the notification')
@@ -5266,7 +5318,13 @@ describe('init', () => {
       env: { ...isolatedEnv(cwd), XDG_STATE_HOME: '/dev/null' },
     }
 
-    await expect(initCommand(deps, { hooks: false, skills: false })).resolves.toBe(EXIT.failed)
+    await expect(
+      initCommand(deps, {
+        hooks: false,
+        setupScope: 'project',
+        skills: false,
+      }),
+    ).resolves.toBe(EXIT.failed)
     expect(submitCalls).toBe(1)
     expect(io.errLines.join('\n')).toContain('Could not save setup proof req_unwritable')
     expect(io.outLines.join('\n')).toContain('Next: Delivery proof')
@@ -5418,7 +5476,12 @@ describe('init', () => {
         env: { ...isolatedEnv(cwd), XDG_CONFIG_HOME: stateRoot, XDG_STATE_HOME: stateRoot },
       }
       expect(
-        await initCommand(deps, { projectId: 'shared-project', hooks: false, skills: false }),
+        await initCommand(deps, {
+          projectId: 'shared-project',
+          hooks: false,
+          setupScope: 'project',
+          skills: false,
+        }),
       ).toBe(EXIT.ok)
     }
 
@@ -5500,7 +5563,7 @@ describe('readiness assessment cost', () => {
       store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'empty store' },
     }
 
-    expect(await initCommand(deps, {})).toBe(EXIT.failed)
+    expect(await initCommand(deps, { setupScope: 'project' })).toBe(EXIT.failed)
     expect(healthCalls).toBe(1)
     expect(readFileSync(path.join(cwd, '.notifai', 'config.toml'), 'utf8')).toContain('project =')
   })

package/src/config.ts

@@ -21,8 +21,8 @@ import { normalizeOrigin } from './url-policy.js'
  * preference that evaporates mid-session is worse than none.
  *
  * `project-local` is a personal file under the user's config directory, keyed
- * by the project root so a checkout does not have to gitignore anything. Shared
- * `.notifai/config.toml` stays in the tree for committed project identity.
+ * by the Project root so a checkout does not have to gitignore anything. Shared
+ * `.notifai/config.toml` stays in the tree for committed Project identity.
  *
  * `config show --explain` surfaces the winning layer per key.
  */
@@ -245,9 +245,9 @@ export function sanitizeSessionId(sessionId: string): string {
 }
 
 /**
- * Pointer from a project directory to the harness session currently working in
+ * Pointer from a Project directory to the Agent Session currently working in
  * it, written by the UserPromptSubmit hook. Without it `notifai ask` has no way
- * to learn its own session id: an ordinary agent shell command receives no hook
+ * to learn its own Agent Session id: an ordinary agent shell command receives no hook
  * payload, and no harness exports one into the environment.
  */
 export function projectSessionPointerPath(cwd: string, env: NodeJS.ProcessEnv = process.env): string {
@@ -420,7 +420,7 @@ export function loadConfig(options: {
   cwd?: string
   env?: NodeJS.ProcessEnv
   flags?: FlagOverrides
-  /** Harness session id; enables the session override layer when present. */
+  /** Agent Session id; enables the Agent Session override layer when present. */
   sessionId?: string | undefined
 }): CliConfig {
   const env = options.env ?? process.env

package/src/invocation-context.test.ts

@@ -346,7 +346,7 @@ describe('buildSourceContext', () => {
       }),
     ).toEqual({
       ok: false,
-      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact session id.',
+      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact Agent Session id.',
     })
   })
 })

package/src/invocation-context.ts

@@ -150,7 +150,7 @@ export type SourceContextBuild =
   | { ok: true; source?: SourceContextT }
   | { ok: false; error: string }
 
-/** Resolve per-field source precedence without fabricating session identity. */
+/** Resolve per-field Source Context precedence without fabricating Agent Session identity. */
 export function buildSourceContext(input: SourceContextInput): SourceContextBuild {
   const sessionId =
     input.sessionId ?? input.env['NOTIFAI_SESSION_ID'] ?? input.activeHarness?.sessionId
@@ -158,7 +158,7 @@ export function buildSourceContext(input: SourceContextInput): SourceContextBuil
   if (explicitLabel !== undefined && (sessionId === undefined || sessionId === '')) {
     return {
       ok: false,
-      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact session id.',
+      error: '--session-label (or NOTIFAI_SESSION_LABEL) needs an exact Agent Session id.',
     }
   }
   if (sessionId === '') {

package/src/onboarding-docs.test.ts

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+const publicReadme = readFileSync(new URL('../../../README.md', import.meta.url), 'utf8')
+const cliReadme = readFileSync(new URL('../README.md', import.meta.url), 'utf8')
+
+describe('public onboarding docs', () => {
+  it('installs the CLI before the first quick-start invocation', () => {
+    const using = publicReadme.slice(publicReadme.indexOf('## Using it'))
+    const install = using.indexOf('npm install -g @raidiant/notifai')
+    const firstInvocation = using.search(/^notifai(?:\s|$)/m)
+
+    expect(install).toBeGreaterThan(0)
+    expect(firstInvocation).toBeGreaterThan(install)
+    expect(using.slice(install, firstInvocation)).toContain('@raidiant/notifai')
+  })
+
+  it('states the active Android external-test boundary without promising a public release', () => {
+    const harnesses = cliReadme.slice(cliReadme.indexOf('## Agent harnesses'))
+
+    expect(harnesses).toMatch(/Android Companion App is active[\s\S]*external testing/i)
+    expect(harnesses).toMatch(/Firebase App Distribution/i)
+    expect(harnesses).toMatch(/not a\s+public release or a Google Play promise/i)
+  })
+})