@raidiant/notifai 0.2.1 → 0.3.0

package/src/commands.test.ts

@@ -17,7 +17,9 @@ import {
   buildQuestions,
   assessReadiness,
   capabilitiesCommand,
+  configExplainCommand,
   configSetCommand,
+  configShowCommand,
   contradictingAnswer,
   describeHookFailure,
   doctorCommand,
@@ -38,6 +40,8 @@ import {
 import { applyPlan, buildHookConfig } from './install-hooks.js'
 import { readSessionState, writeProjectSession, writeSessionState } from './hooks.js'
 import type { NativeSkill, NativeSkills, SkillScope } from './native-skills.js'
+import { CONFIG_KEYS } from './config.js'
+import type { Tone } from './ui/theme.js'
 
 class CapturedIo implements CommandIo {
   outLines: string[] = []
@@ -72,7 +76,7 @@ class InteractiveIo extends CapturedIo {
   intros: string[] = []
   outros: string[] = []
   spinnerEvents: string[] = []
-  checks: { ok: boolean; message: string }[] = []
+  checks: { ok: boolean; message: string; tone?: Tone }[] = []
 
   override async confirm(question: string) {
     this.prompts.push(question)
@@ -111,8 +115,8 @@ class InteractiveIo extends CapturedIo {
     }
   }
 
-  async check(ok: boolean, message: string) {
-    this.checks.push({ ok, message })
+  async check(ok: boolean, message: string, tone?: Tone) {
+    this.checks.push({ ok, message, ...(tone === undefined ? {} : { tone }) })
   }
 }
 
@@ -919,6 +923,67 @@ describe('projectSlugFrom', () => {
   })
 })
 
+describe('config surfaces', () => {
+  function configDeps(io: CapturedIo): CommandDeps {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-config-surface-'))
+    return { ...makeDeps(io, {} as ApiClient), cwd, env: { XDG_CONFIG_HOME: path.join(cwd, 'xdg') } }
+  }
+
+  it('gives an agent the same flat key = value output it always had', () => {
+    // The whole point of gating the readable rendering on a human terminal.
+    // Anything parsing this today must keep parsing it tomorrow.
+    const io = new CapturedIo()
+    expect(configShowCommand(configDeps(io), {})).toBe(EXIT.ok)
+    expect(io.outLines).toHaveLength(CONFIG_KEYS.length)
+    expect(io.outLines[0]).toMatch(/^base_url = "/)
+    for (const line of io.outLines) expect(line).toMatch(/^[a-z_]+ = /)
+  })
+
+  it('explains each setting once a human is at the terminal', () => {
+    const io = new InteractiveIo()
+    expect(configShowCommand(configDeps(io), {})).toBe(EXIT.ok)
+    const text = io.outLines.join('\n')
+    expect(text).toContain('Questions & presence')
+    expect(text).toContain('Whether sitting at this keyboard holds a question back')
+  })
+
+  it('keeps --plain available to a human who wants the parseable form', () => {
+    const io = new InteractiveIo()
+    expect(configShowCommand(configDeps(io), { plain: true })).toBe(EXIT.ok)
+    expect(io.outLines).toHaveLength(CONFIG_KEYS.length)
+  })
+
+  it('explains one setting, and says so in JSON when asked', () => {
+    const io = new InteractiveIo()
+    expect(configExplainCommand(configDeps(io), 'require_idle', { json: true })).toBe(EXIT.ok)
+    const parsed = JSON.parse(io.outLines.join('\n')) as Record<string, unknown>
+    expect(parsed['key']).toBe('require_idle')
+    expect(parsed['accepts']).toBe('true or false')
+    expect(parsed['detail']).toContain('question waits while you are using this machine')
+  })
+
+  it('rejects an unknown setting and points at the nearest real one', () => {
+    const io = new CapturedIo()
+    expect(configExplainCommand(configDeps(io), 'require_idl')).toBe(EXIT.usage)
+    expect(io.errLines[0]).toBe('Unknown setting "require_idl".')
+  })
+
+  it('refuses an enum value the sender would later reject', async () => {
+    // `config set sound whatever` used to be written straight to disk: the
+    // typo only surfaced when a notification failed to carry the sound.
+    const io = new CapturedIo()
+    expect(await configSetCommand(configDeps(io), 'sound', 'whatever', { yes: true })).toBe(
+      EXIT.usage,
+    )
+    expect(io.errLines[0]).toContain('default, done, attention, alert, none')
+  })
+
+  it('still accepts a legal enum value', async () => {
+    const io = new CapturedIo()
+    expect(await configSetCommand(configDeps(io), 'sound', 'none', { yes: true })).toBe(EXIT.ok)
+  })
+})
+
 describe('interactive command UX', () => {
   it('styles login pairing progress for a human terminal', async () => {
     const io = new InteractiveIo()
@@ -1052,7 +1117,9 @@ describe('interactive command UX', () => {
     )
     expect(io.errLines).toEqual([
       'ask_grace_seconds must be between 0 and 540.',
-      '"1.5" is not an integer.',
+      // Names the key and its range: `"1.5" is not an integer` left the reader
+      // to work out which of the two settings they had just mistyped.
+      'ask_grace_seconds takes a whole number from 0s–540s, not "1.5".',
     ])
     expect(existsSync(configFile)).toBe(false)
   })
@@ -1081,6 +1148,18 @@ describe('interactive command UX', () => {
     expect(io.checks.some((check) => !check.ok && check.message.startsWith('This machine:'))).toBe(true)
     expect(io.checks.some((check) => check.ok && check.message.startsWith('Protocol version:'))).toBe(true)
     expect(io.outLines).toEqual([])
+
+    // Four tones, not two. A boolean has to round `optional-gap` and `unknown`
+    // to pass or fail, and rounding them to pass put a tick beside things the
+    // user had declined and beside things nothing had checked.
+    const tone = (prefix: string): Tone | undefined =>
+      io.checks.find((check) => check.message.startsWith(prefix))?.tone
+    expect(tone('This machine:')).toBe('bad')
+    expect(tone('Protocol version:')).toBe('ok')
+    // Never evaluated: the account cannot be checked without a credential.
+    expect(tone('Account:')).toBe('pending')
+    // Legitimately declined rather than broken.
+    expect(tone('Project identity:')).toBe('warn')
   })
 
   it('keeps doctor JSON as one machine-readable stdout document', async () => {
@@ -1181,7 +1260,7 @@ describe('init', () => {
       source: 'Raidiant-io/notifai',
       sourceType: 'github',
       sourceUrl: 'https://github.com/Raidiant-io/notifai.git',
-      ref: 'v0.2.1',
+      ref: 'v0.3.0',
     }
   }
 
@@ -1284,7 +1363,7 @@ describe('init', () => {
   })
 
   it('pins the skill installer to the tagged public release syntax', () => {
-    expect(SKILLS_SOURCE).toBe('Raidiant-io/notifai#v0.2.1')
+    expect(SKILLS_SOURCE).toBe('Raidiant-io/notifai#v0.3.0')
     expect(SKILLS_SOURCE).not.toContain('@v')
   })
 
@@ -1307,7 +1386,7 @@ describe('init', () => {
             source: 'Raidiant-io/notifai',
             sourceType: 'github',
             sourceUrl: 'https://github.com/Raidiant-io/notifai.git',
-            ref: 'v0.2.1',
+            ref: 'v0.3.0',
           },
         ],
       }),
@@ -2207,7 +2286,7 @@ describe('asking before the hooks have ever run', () => {
                   source: 'Raidiant-io/notifai',
                   sourceType: 'github',
                   sourceUrl: 'https://github.com/Raidiant-io/notifai.git',
-                  ref: 'v0.2.1',
+                  ref: 'v0.3.0',
                 },
               ]
             : [],

package/src/commands.ts

@@ -41,8 +41,21 @@ import {
   type ConfigKey,
   type FlagOverrides,
 } from './config.js'
+import { acceptedValues, configInfo } from './config-schema.js'
+import {
+  renderConfigExplain,
+  renderConfigList,
+  renderConfigPlain,
+} from './ui/config-view.js'
 import type { CredentialStore, MachineCredential } from './credentials.js'
-import { firstBlocker, openItems, type Readiness, type ReadinessState } from './readiness.js'
+import {
+  firstBlocker,
+  openItems,
+  type Readiness,
+  type ReadinessState,
+  type StateStatus,
+} from './readiness.js'
+import type { Tone } from './ui/theme.js'
 import {
   handleSessionEnd,
   handleStop,
@@ -113,7 +126,13 @@ export interface CommandIo {
   outro?(message: string): Promise<void>
   note?(message: string, title?: string): Promise<void>
   spinner?(message: string): Promise<CommandSpinner | null>
-  check?(ok: boolean, message: string): Promise<void>
+  /**
+   * A report line. `tone` distinguishes the two states that are neither pass
+   * nor fail — something optional the user declined, and something that was
+   * never evaluated — which a boolean has to round to one or the other.
+   * Optional so existing implementations keep type-checking.
+   */
+  check?(ok: boolean, message: string, tone?: Tone): Promise<void>
 }
 
 export interface CommandSpinner {
@@ -387,6 +406,32 @@ export async function devicesCommand(deps: CommandDeps, flags: { json?: boolean
   }
 }
 
+/**
+ * Devices as data, for surfaces that render them themselves.
+ *
+ * `devicesCommand` prints and returns an exit code, which is the right shape
+ * for a command and the wrong one for a menu that wants to show names beside
+ * checkboxes. Silent on every failure by design: the interactive app already
+ * shows the credential and connectivity state on its status card, so a second
+ * error line here would be reporting the same fault twice.
+ */
+export async function deviceInventory(deps: CommandDeps): Promise<RoutableDevice[] | null> {
+  if (!deps.store.load()) return null
+  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) return null
+  try {
+    return (await authed.client.listDevices()).devices
+  } catch {
+    return null
+  }
+}
+
+/** Whether a device is in a state where a notification would actually arrive. */
+export function canDeviceReceive(device: RoutableDevice): boolean {
+  return deviceCanReceive(device)
+}
+
 export async function capabilitiesCommand(
   deps: CommandDeps,
   flags: { json?: boolean; platform?: Platform },
@@ -1750,7 +1795,7 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
 
 export function configShowCommand(
   deps: CommandDeps,
-  flags: { json?: boolean; explain?: boolean },
+  flags: { json?: boolean; explain?: boolean; plain?: boolean },
 ): number {
   const config = loadConfig({ cwd: deps.cwd, env: deps.env })
   if (flags.json) {
@@ -1760,14 +1805,111 @@ export function configShowCommand(
     deps.io.out(JSON.stringify(output, null, 2))
     return EXIT.ok
   }
-  for (const key of CONFIG_KEYS) {
-    const entry = config[key]
-    const provenance = flags.explain ? `  [${entry.source}]` : ''
-    deps.io.out(`${key} = ${JSON.stringify(entry.value)}${provenance}`)
+  // Anything that is not a person at a terminal keeps the flat `key = value`
+  // form it has always had. Scripts parse this, and a prettier layout for an
+  // audience that cannot see it would only be a breaking change.
+  if (deps.io.interactive !== true || flags.plain === true) {
+    for (const line of renderConfigPlain(config, flags.explain === true)) deps.io.out(line)
+    return EXIT.ok
+  }
+  for (const line of renderConfigList(config, { showAdvanced: flags.explain === true })) {
+    deps.io.out(line)
   }
   return EXIT.ok
 }
 
+/**
+ * One setting, explained in full.
+ *
+ * The gap this closes: `config show` prints `require_idle = true` and there was
+ * nowhere to go from there. Every key already had a careful explanation — in a
+ * TypeScript comment, read by everyone except the person who needed it.
+ */
+export function configExplainCommand(
+  deps: CommandDeps,
+  key: string,
+  flags: { json?: boolean } = {},
+): number {
+  if (!(CONFIG_KEYS as readonly string[]).includes(key)) {
+    deps.io.err(`Unknown setting "${key}".`)
+    deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`)
+    return EXIT.usage
+  }
+  const configKey = key as ConfigKey
+  const config = loadConfig({ cwd: deps.cwd, env: deps.env })
+  const info = configInfo(configKey)
+  const entry = config[configKey]
+
+  if (flags.json) {
+    deps.io.out(
+      JSON.stringify(
+        {
+          key: configKey,
+          label: info.label,
+          group: info.group,
+          kind: info.kind,
+          summary: info.summary,
+          detail: info.detail,
+          accepts: acceptedValues(configKey),
+          ...(info.choices !== undefined ? { choices: info.choices } : {}),
+          value: entry.value,
+          source: entry.source,
+        },
+        null,
+        2,
+      ),
+    )
+    return EXIT.ok
+  }
+
+  if (deps.io.interactive !== true) {
+    deps.io.out(`${configKey} = ${JSON.stringify(entry.value)}  [${entry.source}]`)
+    deps.io.out(info.detail.replace(/\n\n/g, '\n'))
+    deps.io.out(`accepts: ${acceptedValues(configKey)}`)
+    return EXIT.ok
+  }
+  for (const line of renderConfigExplain(configKey, config)) deps.io.out(line)
+  return EXIT.ok
+}
+
+/**
+ * Closest config key by edit distance, or null when nothing is close.
+ *
+ * The threshold matters more than the algorithm: suggesting a key that shares
+ * three letters with the typo sends the reader to the wrong setting with
+ * confidence, which is worse than listing all fourteen and letting them look.
+ */
+function nearestKey(input: string): string | null {
+  let best: string | null = null
+  let bestDistance = Number.POSITIVE_INFINITY
+  for (const candidate of CONFIG_KEYS) {
+    const distance = editDistance(input.toLowerCase(), candidate)
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = candidate
+    }
+  }
+  return best !== null && bestDistance <= Math.max(2, Math.floor(best.length / 3)) ? best : null
+}
+
+function editDistance(a: string, b: string): number {
+  const previous = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i += 1) {
+    let diagonal = previous[0]!
+    previous[0] = i
+    for (let j = 1; j <= b.length; j += 1) {
+      const above = previous[j]!
+      previous[j] = Math.min(
+        previous[j]! + 1,
+        previous[j - 1]! + 1,
+        diagonal + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+      diagonal = above
+    }
+  }
+  return previous[b.length]!
+}
+
 export async function configSetCommand(
   deps: CommandDeps,
   key: string,
@@ -1775,30 +1917,43 @@ export async function configSetCommand(
   flags: { project?: boolean; local?: boolean; session?: string; yes?: boolean },
 ): Promise<number> {
   if (!(CONFIG_KEYS as readonly string[]).includes(key)) {
-    deps.io.err(`Unknown key "${key}". Valid keys: ${CONFIG_KEYS.join(', ')}`)
+    deps.io.err(`Unknown setting "${key}".`)
+    const near = nearestKey(key)
+    if (near !== null) deps.io.err(`Did you mean "${near}"?`)
+    deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`)
+    deps.io.err('Run `notifai config explain <key>` to see what one of them does.')
     return EXIT.usage
   }
+  const configKey = key as ConfigKey
+  const info = configInfo(configKey)
   let value: unknown = rawValue
-  if (NUMERIC_CONFIG_KEYS.includes(key as ConfigKey)) {
+  if (NUMERIC_CONFIG_KEYS.includes(configKey)) {
     const numeric = Number(rawValue)
     if (!Number.isInteger(numeric)) {
-      deps.io.err(`"${rawValue}" is not an integer.`)
+      deps.io.err(`${key} takes ${acceptedValues(configKey)}, not "${rawValue}".`)
       return EXIT.usage
     }
-    const bounds = configBounds(key as ConfigKey)
+    const bounds = configBounds(configKey)
     if (bounds !== undefined && (numeric < bounds.min || numeric > bounds.max)) {
       deps.io.err(`${key} must be between ${bounds.min} and ${bounds.max}.`)
       return EXIT.usage
     }
     value = numeric
   }
-  if (BOOLEAN_CONFIG_KEYS.includes(key as ConfigKey)) {
+  if (BOOLEAN_CONFIG_KEYS.includes(configKey)) {
     if (rawValue !== 'true' && rawValue !== 'false') {
       deps.io.err(`${key} is a toggle — pass "true" or "false", not "${rawValue}".`)
       return EXIT.usage
     }
     value = rawValue === 'true'
   }
+  // Enum keys were accepted unchecked, so `config set sound whatever` wrote a
+  // value the sender would later reject — a typo that only surfaces at the
+  // moment a notification fails to carry the sound you asked for.
+  if (info.kind === 'enum' && info.choices !== undefined && !info.choices.includes(rawValue)) {
+    deps.io.err(`${key} takes one of: ${info.choices.join(', ')} — not "${rawValue}".`)
+    return EXIT.usage
+  }
   if (key === 'devices') value = rawValue.split(',').map((s) => s.trim()).filter(Boolean)
 
   let layer = flags.local ? 'local' : flags.project ? 'project' : 'global'
@@ -1857,7 +2012,7 @@ 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 = 'Raidiant-io/notifai#v0.2.1'
+export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.3.0'
 
 function skillSourceParts(): { source: string; ref: string } | null {
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
@@ -3012,7 +3167,13 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   // costs nothing.
   if (deps.io.interactive === true && deps.io.check) {
     await deps.io.intro?.('Notifai doctor')
-    for (const s of readiness.states) await deps.io.check(s.status !== 'gap', line(s))
+    for (const s of readiness.states) {
+      // Four states, not two. Rendering `optional-gap` and `unknown` as
+      // successes made a green report that had never checked half of what it
+      // listed, and put a tick beside things the reader had deliberately
+      // declined.
+      await deps.io.check(s.status !== 'gap', line(s), doctorTone(s.status))
+    }
     await deps.io.outro?.(ok ? 'Everything looks good' : `Start with: ${remedyLine(blocker)}`)
   } else {
     for (const s of readiness.states) {
@@ -3031,6 +3192,20 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   return ok ? EXIT.ok : EXIT.failed
 }
 
+/** Readiness status as a report tone. */
+function doctorTone(status: StateStatus): Tone {
+  switch (status) {
+    case 'ready':
+      return 'ok'
+    case 'gap':
+      return 'bad'
+    case 'optional-gap':
+      return 'warn'
+    case 'unknown':
+      return 'pending'
+  }
+}
+
 /** One line telling the reader what to actually do about a state. */
 function remedyLine(state: ReadinessState): string {
   const remedy = state.remedy
@@ -3463,11 +3638,21 @@ export function realIo(env: NodeJS.ProcessEnv = process.env): CommandIo {
         error: (next) => progress.error(next),
       }
     },
-    check: async (ok, message) => {
+    check: async (ok, message, tone) => {
       if (!interactive()) return
       const { log } = await clack()
-      if (ok) log.success(message)
-      else log.error(message)
+      switch (tone ?? (ok ? 'ok' : 'bad')) {
+        case 'ok':
+          return log.success(message)
+        case 'warn':
+          return log.warn(message)
+        case 'pending':
+          // Never checked. `log.info` reads as neutral, which is the honest
+          // rendering for a state no evidence was gathered about.
+          return log.info(message)
+        case 'bad':
+          return log.error(message)
+      }
     },
     openUrl: (url) => {
       try {

package/src/config-schema.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+import {
+  BOOLEAN_CONFIG_KEYS,
+  CONFIG_KEYS,
+  NUMERIC_CONFIG_KEYS,
+  configBounds,
+  type ConfigKey,
+} from './config.js'
+import {
+  CONFIG_GROUPS,
+  acceptedValues,
+  configInfo,
+  configKeysByGroup,
+  describeSource,
+  formatDuration,
+  formatValue,
+} from './config-schema.js'
+
+describe('coverage', () => {
+  it('describes every configuration key', () => {
+    // The failure this prevents is silent: a key added to `config.ts` without
+    // an entry here still resolves, still applies, and still appears in
+    // `config show` — with no label, no summary and no way for the reader to
+    // find out what it does.
+    for (const key of CONFIG_KEYS) {
+      const info = configInfo(key)
+      expect(info.label, key).toBeTruthy()
+      expect(info.summary, key).toBeTruthy()
+      expect(info.detail, key).toBeTruthy()
+      expect(info.detail.length, key).toBeGreaterThan(info.summary.length)
+    }
+  })
+
+  it('files every key under exactly one declared group', () => {
+    const grouped = CONFIG_GROUPS.flatMap((group) => configKeysByGroup(group.id).map((info) => info.key))
+    expect([...grouped].sort()).toEqual([...CONFIG_KEYS].sort())
+  })
+
+  it('keeps summaries short enough to sit beside a value', () => {
+    for (const key of CONFIG_KEYS) {
+      expect(configInfo(key).summary.length, key).toBeLessThanOrEqual(80)
+    }
+  })
+
+  it('agrees with config.ts about which keys are numbers and toggles', () => {
+    // Two sources of truth for a key's type would let the prompt offer a text
+    // box for something `config set` will only accept as `true` or `false`.
+    for (const key of NUMERIC_CONFIG_KEYS) expect(configInfo(key).kind, key).toBe('integer')
+    for (const key of BOOLEAN_CONFIG_KEYS) expect(configInfo(key).kind, key).toBe('boolean')
+  })
+
+  it('offers choices for every enum key', () => {
+    for (const key of CONFIG_KEYS) {
+      const info = configInfo(key)
+      if (info.kind !== 'enum') continue
+      expect(info.choices, key).toBeDefined()
+      expect(info.choices!.length, key).toBeGreaterThan(1)
+      for (const choice of info.choices!) expect(info.choiceHints?.[choice], `${key}.${choice}`).toBeTruthy()
+    }
+  })
+})
+
+describe('acceptedValues', () => {
+  it('states the range for a bounded number', () => {
+    const bounds = configBounds('ask_grace_seconds')!
+    expect(acceptedValues('ask_grace_seconds')).toBe(
+      `a whole number from ${bounds.min}s–${bounds.max}s`,
+    )
+  })
+
+  it('lists the choices for an enum', () => {
+    expect(acceptedValues('sound')).toContain('none')
+  })
+
+  it('names both values for a toggle', () => {
+    expect(acceptedValues('require_idle')).toBe('true or false')
+  })
+})
+
+describe('formatValue', () => {
+  it('renders toggles as words rather than JSON', () => {
+    expect(formatValue('require_idle', true)).toBe('yes')
+    expect(formatValue('require_idle', false)).toBe('no')
+  })
+
+  it('explains what an unset value means instead of printing null', () => {
+    // `sound = null` is accurate and tells the reader nothing about what will
+    // happen; the whole complaint about the old output in one line.
+    expect(formatValue('sound', null)).toBe('each notification uses the sound for its kind')
+    expect(formatValue('devices', null)).toBe('every device that can receive')
+  })
+
+  it('renders durations in units a person reads', () => {
+    expect(formatValue('ask_grace_seconds', 300)).toBe('5m')
+    expect(formatValue('ttl_seconds', 86400)).toBe('1d')
+    expect(formatValue('wait_seconds', 10)).toBe('10s')
+  })
+
+  it('joins a device list', () => {
+    expect(formatValue('devices', ['dev_a', 'dev_b'])).toBe('dev_a, dev_b')
+  })
+})
+
+describe('formatDuration', () => {
+  it('keeps exact values readable across scales', () => {
+    expect(formatDuration(0, 's')).toBe('0s (immediately)')
+    expect(formatDuration(45, 's')).toBe('45s')
+    expect(formatDuration(120, 's')).toBe('2m')
+    expect(formatDuration(3600, 's')).toBe('1h')
+    expect(formatDuration(90, 's')).toBe('1m 30s')
+  })
+})
+
+describe('describeSource', () => {
+  it('turns a tagged path into words plus the file', () => {
+    expect(describeSource('default')).toEqual({ label: 'default', path: null })
+    expect(describeSource('global:/home/me/.config/notifai/config.toml')).toEqual({
+      label: 'this machine',
+      path: '/home/me/.config/notifai/config.toml',
+    })
+    expect(describeSource('project:/repo/.notifai/config.toml').label).toBe('this project (shared)')
+    expect(describeSource('project-local:/repo/.notifai/config.local.toml').label).toBe(
+      'this project (personal)',
+    )
+  })
+
+  it('does not invent a label for an unrecognised layer', () => {
+    expect(describeSource('future-layer:/tmp/x').label).toBe('future-layer')
+  })
+})
+
+describe('examples', () => {
+  it('suggests a value `config set` would actually accept', () => {
+    // The explain screen prints `notifai config set <key> <example>` as a
+    // copyable line, so an example that fails validation is worse than none.
+    for (const key of CONFIG_KEYS as readonly ConfigKey[]) {
+      const info = configInfo(key)
+      if (info.example === undefined) continue
+      if (info.kind === 'integer') {
+        const bounds = configBounds(key)
+        const parsed = Number(info.example)
+        expect(Number.isInteger(parsed), key).toBe(true)
+        if (bounds) {
+          expect(parsed, key).toBeGreaterThanOrEqual(bounds.min)
+          expect(parsed, key).toBeLessThanOrEqual(bounds.max)
+        }
+      }
+      if (info.kind === 'boolean') expect(['true', 'false']).toContain(info.example)
+      if (info.kind === 'enum') expect(info.choices).toContain(info.example)
+    }
+  })
+})