@raidiant/notifai 0.5.1 → 1.0.0

package/src/native-skills.ts

@@ -33,24 +33,16 @@ export interface SkillsAddOptions {
 export interface NativeSkills {
   /** Launch the native interactive `npx skills add` flow. */
   add(options: SkillsAddOptions): Promise<number>
-  /** Ask the native installer for its managed install inventory. */
+  /** Read installer-managed inventory from lock files. Does not spawn npx. */
   list(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): Promise<SkillsListResult>
 }
 
-interface JsonSkill {
-  name?: unknown
-  path?: unknown
-  scope?: unknown
-  source?: unknown
-  sourceType?: unknown
-  sourceUrl?: unknown
-}
-
 interface LockEntry {
   source?: unknown
   sourceType?: unknown
   sourceUrl?: unknown
   ref?: unknown
+  skillPath?: unknown
 }
 
 interface LockFile {
@@ -77,78 +69,47 @@ function readLock(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): LockF
   }
 }
 
-function lockEntryFor(lock: LockFile, name: string): LockEntry | undefined {
-  const direct = lock.skills?.[name]
-  if (direct) return direct
-  const normalized = name.toLowerCase().replace(/[\s_]+/g, '-')
-  const key = Object.keys(lock.skills ?? {}).find(
-    (candidate) => candidate.toLowerCase().replace(/[\s_]+/g, '-') === normalized,
-  )
-  return key === undefined ? undefined : lock.skills?.[key]
-}
-
-function jsonArray(stdout: string): unknown[] | null {
-  const start = stdout.indexOf('[')
-  const end = stdout.lastIndexOf(']')
-  if (start < 0 || end < start) return null
-  try {
-    const parsed: unknown = JSON.parse(stdout.slice(start, end + 1))
-    return Array.isArray(parsed) ? parsed : null
-  } catch {
-    return null
-  }
+function conventionalSkillPath(
+  scope: SkillScope,
+  name: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): string {
+  if (scope === 'project') return path.join(cwd, '.agents', 'skills', name)
+  const home = env['HOME'] ?? env['USERPROFILE'] ?? os.homedir()
+  return path.join(home, '.agents', 'skills', name)
 }
 
-function managedSkills(stdout: string, scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): NativeSkill[] | null {
-  const entries = jsonArray(stdout)
-  if (entries === null) return null
+function skillsFromLock(scope: SkillScope, cwd: string, env: NodeJS.ProcessEnv): NativeSkill[] {
   const lock = readLock(scope, cwd, env)
-  return entries.flatMap((entry): NativeSkill[] => {
+  return Object.entries(lock.skills ?? {}).flatMap(([name, entry]): NativeSkill[] => {
     if (entry === null || typeof entry !== 'object') return []
-    const value = entry as JsonSkill
-    if (
-      typeof value.name !== 'string' ||
-      typeof value.path !== 'string' ||
-      value.scope !== scope
-    ) {
-      return []
-    }
-    const lockEntry = lockEntryFor(lock, value.name)
     return [
       {
-        name: value.name,
+        name,
         scope,
-        path: value.path,
-        source: typeof value.source === 'string' ? value.source : null,
-        sourceType: typeof value.sourceType === 'string' ? value.sourceType : null,
-        sourceUrl: typeof value.sourceUrl === 'string' ? value.sourceUrl : null,
-        ref: typeof lockEntry?.ref === 'string' ? lockEntry.ref : null,
+        path:
+          typeof entry.skillPath === 'string' && entry.skillPath !== ''
+            ? entry.skillPath
+            : conventionalSkillPath(scope, name, cwd, env),
+        source: typeof entry.source === 'string' ? entry.source : null,
+        sourceType: typeof entry.sourceType === 'string' ? entry.sourceType : null,
+        sourceUrl: typeof entry.sourceUrl === 'string' ? entry.sourceUrl : null,
+        ref: typeof entry.ref === 'string' ? entry.ref : null,
       },
     ]
   })
 }
 
-function run(
-  args: string[],
-  options: { cwd: string; env: NodeJS.ProcessEnv; stdio: 'inherit' | 'capture' },
-): Promise<{ code: number; stdout: string }> {
+function run(args: string[], options: { cwd: string; env: NodeJS.ProcessEnv }): Promise<number> {
   return new Promise((resolve) => {
     const child = spawn('npx', args, {
       cwd: options.cwd,
       env: options.env,
-      stdio: options.stdio === 'inherit' ? 'inherit' : ['ignore', 'pipe', 'ignore'],
+      stdio: 'inherit',
     })
-    if (options.stdio === 'capture') {
-      let stdout = ''
-      child.stdout?.on('data', (chunk: Buffer | string) => {
-        stdout += chunk.toString()
-      })
-      child.on('error', () => resolve({ code: 1, stdout }))
-      child.on('exit', (code) => resolve({ code: code ?? 1, stdout }))
-      return
-    }
-    child.on('error', () => resolve({ code: 1, stdout: '' }))
-    child.on('exit', (code) => resolve({ code: code ?? 1, stdout: '' }))
+    child.on('error', () => resolve(1))
+    child.on('exit', (code) => resolve(code ?? 1))
   })
 }
 
@@ -160,18 +121,13 @@ export const nativeSkills: NativeSkills = {
     // An explicit scope is the unattended contract. Native `--yes` keeps all
     // remaining installer prompts non-interactive after the scope is chosen.
     if (options.scope !== undefined) args.push('--yes')
-    return (await run(args, { cwd: options.cwd, env: options.env, stdio: 'inherit' })).code
+    return run(args, { cwd: options.cwd, env: options.env })
   },
 
   async list(scope, cwd, env) {
-    const result = await run(
-      ['-y', 'skills', 'list', '--json', ...(scope === 'global' ? ['--global'] : [])],
-      { cwd, env, stdio: 'capture' },
-    )
-    if (result.code !== 0) return { skills: [], error: `npx skills list exited with code ${result.code}` }
-    const skills = managedSkills(result.stdout, scope, cwd, env)
-    return skills === null
-      ? { skills: [], error: 'npx skills list returned invalid JSON' }
-      : { skills }
+    // Presence is already on disk. `npx skills list` takes seconds and cannot
+    // change whether the notifai skill is installed — the lock file is what
+    // the installer itself consults.
+    return { skills: skillsFromLock(scope, cwd, env) }
   },
 }

package/src/pack-feedback-slice.test.ts

@@ -0,0 +1,212 @@
+import { randomBytes } from 'node:crypto'
+import { appendFileSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { gunzipSync } from 'node:zlib'
+import { describe, expect, it } from 'vitest'
+import { LOG_SCHEMA_VERSION, activeLogPath, createLogger, type LogRecord } from './logging.js'
+import { encodeFeedbackSlice, packFeedbackSlice } from './pack-feedback-slice.js'
+
+function sandbox(): NodeJS.ProcessEnv {
+  return { XDG_STATE_HOME: mkdtempSync(path.join(os.tmpdir(), 'notifai-feedback-')) }
+}
+
+function writeLog(env: NodeJS.ProcessEnv, records: LogRecord[]): void {
+  const file = activeLogPath(env)
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  writeFileSync(file, `${records.map((record) => JSON.stringify(record)).join('\n')}\n`, {
+    mode: 0o600,
+  })
+}
+
+function record(overrides: Partial<LogRecord> & Pick<LogRecord, 'ts'>): LogRecord {
+  return {
+    v: 1,
+    level: 'info',
+    event: 'cli.end',
+    run: 'r_1',
+    cmd: 'send',
+    pid: 1,
+    ...overrides,
+  }
+}
+
+describe('packFeedbackSlice', () => {
+  it('returns an empty result with no gzip when there is no log', () => {
+    const result = packFeedbackSlice(sandbox())
+
+    expect(result.record_count).toBe(0)
+    expect(result.records).toEqual([])
+    expect(result.jsonl).toBe('')
+    expect(result.gzip).toBeUndefined()
+    expect(result.uncompressed_bytes).toBe(0)
+    expect(result.compressed_bytes).toBe(0)
+    expect(result.truncated).toBe(false)
+    expect(result.consentSummary.toLowerCase()).toMatch(/credential/)
+    expect(result.consentSummary.toLowerCase()).toMatch(/title/)
+    expect(result.consentSummary.toLowerCase()).toMatch(/answer/)
+  })
+
+  it('packs records inside the default 24-hour window and drops older ones', () => {
+    const env = sandbox()
+    const now = Date.parse('2026-08-13T12:00:00.000Z')
+    writeLog(env, [
+      record({ ts: '2026-08-12T11:00:00.000Z', data: { which: 'too-old' } }),
+      record({ ts: '2026-08-12T13:00:00.000Z', data: { which: 'kept' } }),
+    ])
+
+    const result = packFeedbackSlice(env, { now })
+
+    expect(result.record_count).toBe(1)
+    expect(result.records[0]?.data).toMatchObject({ which: 'kept' })
+    expect(result.since).toBe(Date.parse('2026-08-12T12:00:00.000Z'))
+    expect(result.until).toBe(now)
+    expect(result.jsonl).toContain('kept')
+    expect(result.jsonl).not.toContain('too-old')
+    expect(result.gzip).toBeDefined()
+    expect(result.uncompressed_bytes).toBe(Buffer.byteLength(result.jsonl))
+    expect(result.compressed_bytes).toBe(result.gzip!.length)
+    expect(result.truncated).toBe(false)
+  })
+
+  it('gives consent copy that names redacted credentials, titles, answers, window, and size', () => {
+    const env = sandbox()
+    const now = Date.parse('2026-08-13T12:00:00.000Z')
+    writeLog(env, [record({ ts: '2026-08-13T11:00:00.000Z' })])
+
+    const result = packFeedbackSlice(env, { now })
+    const copy = result.consentSummary.toLowerCase()
+
+    expect(copy).toMatch(/credential/)
+    expect(copy).toMatch(/already removed|already redacted|redacted/)
+    expect(copy).toMatch(/title/)
+    expect(copy).toMatch(/answer/)
+    expect(result.consentSummary).toContain('2026-08-12T12:00:00.000Z')
+    expect(result.consentSummary).toContain('2026-08-13T12:00:00.000Z')
+    expect(result.consentSummary).toContain(String(result.uncompressed_bytes))
+    expect(result.consentSummary).toContain(String(result.compressed_bytes))
+    expect(result.consentSummary).toContain(String(result.record_count))
+  })
+
+  it('applies extra log query filters on top of the window', () => {
+    const env = sandbox()
+    const now = Date.parse('2026-08-13T12:00:00.000Z')
+    writeLog(env, [
+      record({ ts: '2026-08-13T11:00:00.000Z', event: 'cli.end', data: { which: 'end' } }),
+      record({ ts: '2026-08-13T11:01:00.000Z', event: 'cli.error', data: { which: 'error' } }),
+    ])
+
+    const result = packFeedbackSlice(env, { now, event: ['cli.error'] })
+
+    expect(result.record_count).toBe(1)
+    expect(result.records[0]?.event).toBe('cli.error')
+    expect(result.records[0]?.data).toMatchObject({ which: 'error' })
+  })
+
+  it('drops oldest records until the uncompressed JSONL cap holds', () => {
+    const env = sandbox()
+    const now = Date.parse('2026-08-13T12:00:00.000Z')
+    const start = Date.parse('2026-08-13T10:00:00.000Z')
+    const pad = 'x'.repeat(2000)
+    writeLog(
+      env,
+      Array.from({ length: 200 }, (_, sequence) =>
+        record({
+          ts: new Date(start + sequence * 1000).toISOString(),
+          data: { sequence, pad },
+        }),
+      ),
+    )
+
+    const result = packFeedbackSlice(env, { now })
+    const sequences = result.records.map((entry) => entry.data?.['sequence'])
+
+    expect(result.uncompressed_bytes).toBeLessThanOrEqual(256 * 1024)
+    expect(result.compressed_bytes).toBeLessThanOrEqual(128 * 1024)
+    expect(result.truncated).toBe(true)
+    expect(result.record_count).toBeGreaterThan(0)
+    expect(sequences[0]).toBeGreaterThan(0)
+    expect(sequences.at(-1)).toBe(199)
+  })
+
+  it('drops oldest records until the gzip cap holds', () => {
+    const env = sandbox()
+    const now = Date.parse('2026-08-13T12:00:00.000Z')
+    const start = Date.parse('2026-08-13T10:00:00.000Z')
+    const seeded = Array.from({ length: 80 }, (_, sequence) =>
+      record({
+        ts: new Date(start + sequence * 1000).toISOString(),
+        data: { sequence, pad: randomBytes(1800).toString('base64') },
+      }),
+    )
+    writeLog(env, seeded)
+
+    const result = packFeedbackSlice(env, { now })
+    const sequences = result.records.map((entry) => entry.data?.['sequence'])
+
+    expect(result.uncompressed_bytes).toBeLessThanOrEqual(256 * 1024)
+    expect(result.compressed_bytes).toBeLessThanOrEqual(128 * 1024)
+    expect(result.truncated).toBe(true)
+    expect(result.record_count).toBeGreaterThan(0)
+    expect(result.record_count).toBeLessThan(seeded.length)
+    expect(sequences[0]).toBeGreaterThan(0)
+    expect(sequences.at(-1)).toBe(79)
+  })
+
+  it('encodes the gzip slice as a gzip+base64 wire payload', () => {
+    const env = sandbox()
+    const now = Date.parse('2026-08-13T12:00:00.000Z')
+    writeLog(env, [record({ ts: '2026-08-13T11:00:00.000Z', data: { which: 'wire' } })])
+
+    const packed = packFeedbackSlice(env, { now })
+    const wire = encodeFeedbackSlice(packed)
+
+    expect(wire).toEqual({
+      encoding: 'gzip+base64',
+      bytes: packed.gzip!.toString('base64'),
+      uncompressed_bytes: packed.uncompressed_bytes,
+      compressed_bytes: packed.compressed_bytes,
+      record_count: packed.record_count,
+      truncated: false,
+      since: '2026-08-12T12:00:00.000Z',
+      until: '2026-08-13T12:00:00.000Z',
+      schema_version: packed.schema_version,
+    })
+    expect(gunzipSync(Buffer.from(wire!.bytes, 'base64')).toString('utf8')).toBe(packed.jsonl)
+    expect(encodeFeedbackSlice(packFeedbackSlice(sandbox()))).toBeUndefined()
+  })
+
+  it('honours an explicit since instead of the 24-hour default', () => {
+    const env = sandbox()
+    const now = Date.parse('2026-08-13T12:00:00.000Z')
+    writeLog(env, [
+      record({ ts: '2026-08-10T12:00:00.000Z', data: { which: 'old' } }),
+      record({ ts: '2026-08-13T11:00:00.000Z', data: { which: 'new' } }),
+    ])
+
+    const result = packFeedbackSlice(env, {
+      now,
+      since: Date.parse('2026-08-10T00:00:00.000Z'),
+    })
+
+    expect(result.records.map((entry) => entry.data?.['which'])).toEqual(['old', 'new'])
+    expect(result.since).toBe(Date.parse('2026-08-10T00:00:00.000Z'))
+  })
+
+  it('packs records written by the logger and skips a damaged line', () => {
+    const env = sandbox()
+    const logger = createLogger({ env, now: () => Date.parse('2026-08-13T11:30:00.000Z') })
+    logger.info('cli.end', { which: 'first' })
+    appendFileSync(activeLogPath(env), 'not json at all\n')
+    createLogger({ env, now: () => Date.parse('2026-08-13T11:31:00.000Z') }).info('cli.end', {
+      which: 'second',
+    })
+
+    const result = packFeedbackSlice(env, { now: Date.parse('2026-08-13T12:00:00.000Z') })
+
+    expect(result.schema_version).toBe(LOG_SCHEMA_VERSION)
+    expect(result.record_count).toBe(2)
+    expect(result.records.map((entry) => entry.data?.['which'])).toEqual(['first', 'second'])
+    expect(result.truncated).toBe(false)
+  })
+})

package/src/pack-feedback-slice.ts

@@ -0,0 +1,187 @@
+/**
+ * Consented, bounded slice of the local log for a later feedback send.
+ *
+ * This module packs. It does not upload. A caller that wants a report on
+ * the wire asks here for the bytes and the consent copy, then decides
+ * whether to send them.
+ */
+import { gzipSync } from 'node:zlib'
+import {
+  LOG_SCHEMA_VERSION,
+  readLogRecords,
+  type LogQuery,
+  type LogRecord,
+} from './logging.js'
+
+export const FEEDBACK_SLICE_UNCOMPRESSED_CAP = 256 * 1024
+export const FEEDBACK_SLICE_COMPRESSED_CAP = 128 * 1024
+export const FEEDBACK_SLICE_DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000
+
+/** High enough that on-disk rotation, not this number, bounds a full-window read. */
+const FULL_WINDOW_READ_LIMIT = 1_000_000
+
+export interface PackFeedbackSliceOptions extends LogQuery {
+  /** Epoch ms. Defaults to now. Tests freeze the window with this. */
+  now?: number
+}
+
+export interface PackedFeedbackSlice {
+  records: LogRecord[]
+  jsonl: string
+  gzip?: Buffer
+  uncompressed_bytes: number
+  compressed_bytes: number
+  record_count: number
+  truncated: boolean
+  since: number
+  until: number
+  schema_version: number
+  consentSummary: string
+}
+
+export interface FeedbackSliceWire {
+  encoding: 'gzip+base64'
+  bytes: string
+  uncompressed_bytes: number
+  compressed_bytes: number
+  record_count: number
+  truncated: boolean
+  since: string
+  until: string
+  schema_version: number
+}
+
+/** Wire form. Empty slices have nothing to encode. */
+export function encodeFeedbackSlice(slice: PackedFeedbackSlice): FeedbackSliceWire | undefined {
+  if (slice.gzip === undefined) return undefined
+  return {
+    encoding: 'gzip+base64',
+    bytes: slice.gzip.toString('base64'),
+    uncompressed_bytes: slice.uncompressed_bytes,
+    compressed_bytes: slice.compressed_bytes,
+    record_count: slice.record_count,
+    truncated: slice.truncated,
+    since: new Date(slice.since).toISOString(),
+    until: new Date(slice.until).toISOString(),
+    schema_version: slice.schema_version,
+  }
+}
+
+export function packFeedbackSlice(
+  env: NodeJS.ProcessEnv = process.env,
+  options: PackFeedbackSliceOptions = {},
+): PackedFeedbackSlice {
+  const { now, since: sinceOption, limit, ...filters } = options
+  const until = now ?? Date.now()
+  const since = sinceOption ?? until - FEEDBACK_SLICE_DEFAULT_WINDOW_MS
+  const { records } = readLogRecords(env, {
+    ...filters,
+    since,
+    limit: limit ?? FULL_WINDOW_READ_LIMIT,
+  })
+
+  if (records.length === 0) {
+    return emptySlice(since, until)
+  }
+
+  const packed = fitToCaps(records)
+  if (packed === null) {
+    return emptySlice(since, until)
+  }
+
+  return {
+    records: packed.records,
+    jsonl: packed.jsonl,
+    gzip: packed.gzip,
+    uncompressed_bytes: packed.uncompressedBytes,
+    compressed_bytes: packed.gzip.length,
+    record_count: packed.records.length,
+    truncated: packed.truncated,
+    since,
+    until,
+    schema_version: LOG_SCHEMA_VERSION,
+    consentSummary: consentSummary({
+      since,
+      until,
+      recordCount: packed.records.length,
+      uncompressedBytes: packed.uncompressedBytes,
+      compressedBytes: packed.gzip.length,
+    }),
+  }
+}
+
+function fitToCaps(records: LogRecord[]): {
+  records: LogRecord[]
+  jsonl: string
+  gzip: Buffer
+  uncompressedBytes: number
+  truncated: boolean
+} | null {
+  const lines = records.map((record) => JSON.stringify(record))
+  let start = 0
+  let truncated = false
+  while (start < lines.length) {
+    const jsonl = toJsonl(lines.slice(start))
+    const uncompressedBytes = Buffer.byteLength(jsonl)
+    if (uncompressedBytes > FEEDBACK_SLICE_UNCOMPRESSED_CAP) {
+      start += 1
+      truncated = true
+      continue
+    }
+    const gzip = gzipSync(jsonl)
+    if (gzip.length <= FEEDBACK_SLICE_COMPRESSED_CAP) {
+      return {
+        records: records.slice(start),
+        jsonl,
+        gzip,
+        uncompressedBytes,
+        truncated,
+      }
+    }
+    start += 1
+    truncated = true
+  }
+  return null
+}
+
+function emptySlice(since: number, until: number): PackedFeedbackSlice {
+  return {
+    records: [],
+    jsonl: '',
+    uncompressed_bytes: 0,
+    compressed_bytes: 0,
+    record_count: 0,
+    truncated: false,
+    since,
+    until,
+    schema_version: LOG_SCHEMA_VERSION,
+    consentSummary: consentSummary({
+      since,
+      until,
+      recordCount: 0,
+      uncompressedBytes: 0,
+      compressedBytes: 0,
+    }),
+  }
+}
+
+function toJsonl(lines: string[]): string {
+  if (lines.length === 0) return ''
+  return `${lines.join('\n')}\n`
+}
+
+function consentSummary(input: {
+  since: number
+  until: number
+  recordCount: number
+  uncompressedBytes: number
+  compressedBytes: number
+}): string {
+  const from = new Date(input.since).toISOString()
+  const to = new Date(input.until).toISOString()
+  return (
+    `About to send ${String(input.recordCount)} log records from ${from} to ${to} ` +
+    `(${String(input.uncompressedBytes)} bytes uncompressed, ${String(input.compressedBytes)} bytes compressed). ` +
+    'Credentials are already removed. Notification titles and the user\'s answers are in the log.'
+  )
+}

package/src/readiness.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { refreshAfterMenuAction } from './readiness.js'
+
+describe('refreshAfterMenuAction', () => {
+  it('does not re-assess after doctor, a test send, or a device list', () => {
+    expect(refreshAfterMenuAction('doctor', true)).toBeNull()
+    expect(refreshAfterMenuAction('test', true)).toBeNull()
+    expect(refreshAfterMenuAction('devices', true)).toBeNull()
+  })
+
+  it('does not re-assess when the action changed nothing', () => {
+    expect(refreshAfterMenuAction('account', false)).toBeNull()
+    expect(refreshAfterMenuAction('settings', false)).toBeNull()
+    expect(refreshAfterMenuAction('routing', false)).toBeNull()
+    expect(refreshAfterMenuAction('setup', false)).toBeNull()
+  })
+
+  it('re-probes the service only after an action that can change it', () => {
+    expect(refreshAfterMenuAction('setup', true)).toEqual(['local', 'remote'])
+    expect(refreshAfterMenuAction('account', true)).toEqual(['local', 'remote'])
+    expect(refreshAfterMenuAction('settings', true)).toEqual(['local'])
+    expect(refreshAfterMenuAction('routing', true)).toEqual(['local'])
+    expect(refreshAfterMenuAction('settings', true, { remote: true })).toEqual(['local', 'remote'])
+  })
+})

package/src/readiness.ts

@@ -86,3 +86,41 @@ export function isReady(readiness: Readiness): boolean {
 export function openItems(readiness: Readiness): ReadinessState[] {
   return readiness.states.filter((s) => s.status === 'gap' || s.status === 'optional-gap')
 }
+
+/**
+ * Work an assessment can do.
+ *
+ * `local` is this machine's files: project config, hook installs, skill lock
+ * files. `remote` is everything that leaves the process — the keychain, the
+ * service, the account, devices, and delivery evidence. The split exists so a
+ * redraw after a settings change does not pay for a health check.
+ */
+export type ReadinessRefresh = 'local' | 'remote'
+
+/**
+ * After a menu action, which readiness work is worth doing.
+ *
+ * `null` means keep the assessment already in hand. Doctor is the report, not
+ * a mutation: the check it just ran is the redraw. A test send and a device
+ * list cannot change setup. Settings and hook wiring stay on this machine
+ * unless the caller says the service URL itself moved.
+ */
+export function refreshAfterMenuAction(
+  action: 'setup' | 'account' | 'test' | 'devices' | 'settings' | 'routing' | 'doctor',
+  changed: boolean,
+  options: { remote?: boolean } = {},
+): readonly ReadinessRefresh[] | null {
+  switch (action) {
+    case 'doctor':
+    case 'test':
+    case 'devices':
+      return null
+    case 'setup':
+    case 'account':
+      return changed ? ['local', 'remote'] : null
+    case 'settings':
+    case 'routing':
+      if (!changed) return null
+      return options.remote === true ? ['local', 'remote'] : ['local']
+  }
+}

package/src/skill.test.ts

@@ -20,6 +20,33 @@ describe('Notifai agent skill', () => {
     expect(skill).toContain('| question (`--reply`) | `attention` | `active` |')
   })
 
+  it('makes the agent the setup wizard', () => {
+    expect(skill.indexOf('## Set Notifai up')).toBeGreaterThan(skill.indexOf('## When to notify'))
+    expect(skill.indexOf('## Set Notifai up')).toBeLessThan(skill.indexOf('## Compose and send'))
+    expect(skill).toContain('Never tell the user to run')
+    expect(skill).toContain('notifai init')
+    expect(skill).toContain('notifai hooks install')
+    expect(skill).toContain('notifai doctor')
+    expect(skill).toContain('notifai login')
+    expect(skill).toContain('Ask the user only for decisions a process cannot make')
+    expect(skill).not.toContain('relay the exact action')
+    expect(harnessReference).toContain('install hooks yourself')
+    expect(harnessReference).toContain('run `notifai login` yourself')
+    expect(harnessReference).not.toContain('the user must run `notifai login`')
+    expect(harnessReference).not.toContain('do not install them without being asked')
+  })
+
+  it('treats --sound and --level as overrides, not completeness', () => {
+    expect(skill).toMatch(/Never pass `--sound` or `--level` unless/)
+    const examples = [...skill.matchAll(/```(?:bash)?\n([\s\S]*?)```/g)].map((match) => match[1])
+    const sendExamples = examples.filter((example) => example.includes('notifai send'))
+    expect(sendExamples.length).toBeGreaterThan(0)
+    for (const example of sendExamples) {
+      expect(example).not.toMatch(/(^|\s)--sound\b/)
+      expect(example).not.toMatch(/(^|\s)--level\b/)
+    }
+  })
+
   it('documents reply lifecycle, routing, session minting, and doctor exits', () => {
     for (const required of [
       '--reply-choice',
@@ -57,6 +84,22 @@ describe('Notifai agent skill', () => {
     expect(askGuidance).toMatch(/without asking the user to\s+confirm again/)
   })
 
+  it('teaches agents to report config JSON fields instead of paraphrasing defaults', () => {
+    expect(skill).toContain('notifai config show --json')
+    expect(skill).toContain('{ value, source, summary }')
+    expect(skill).toContain('Do not paraphrase')
+    expect(skill).not.toContain('config.local.toml')
+    expect(skill).toContain('outside the repository')
+  })
+
+  it('mentions npx only as a pinned alternative to a real install', () => {
+    expect(skill).toContain('npm install -g @raidiant/notifai')
+    expect(skill.indexOf('npm install -g @raidiant/notifai')).toBeLessThan(
+      skill.indexOf('npx --yes @raidiant/notifai@'),
+    )
+    expect(skill).toContain('do not present npx as the default')
+  })
+
   it('tells the agent where to look when something did not happen', () => {
     // The log's whole value is diagnostic, so the skill has to name the case
     // that produces it — a question that was registered and never travelled.