@raidiant/notifai 7.0.2 → 8.0.0

package/src/config-schema.ts

@@ -41,7 +41,7 @@ export const CONFIG_GROUPS: { id: ConfigGroup; title: string; blurb: string }[]
   {
     id: 'project',
     title: 'This project',
-    blurb: 'How work in this directory identifies itself, and the house rules agents read before notifying.',
+    blurb: 'How work in this directory identifies itself. House rules for agents live in `notifai guidance`.',
   },
   {
     id: 'diagnostics',
@@ -83,7 +83,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     label: 'Send questions to my devices',
     group: 'questions',
     kind: 'boolean',
-    summary: 'Whether a registered question may reach your iPhone at all',
+    summary: 'Whether a registered question may reach your Companion devices at all',
     detail:
       'The master switch for question routing. When this is off, a question an agent registers with `notifai ask` stays in the terminal and never leaves this machine, whatever else is configured. Turn it off to stop being reached for a while without uninstalling the harness hooks.',
     example: 'true',
@@ -137,10 +137,10 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
       active: 'wakes the screen and plays the sound',
       time_sensitive: 'marks the notification urgent; Focus breakthrough is not available yet',
     },
-    summary: 'Set how insistently notifications from here arrive',
+    summary: 'Set how insistently notifications reach Apple devices',
     detail:
-      'How hard a notification tries to reach you, in the operating system\'s terms. Setting this pins one level for everything sent from here; kind chooses the sound, never this.\n\nLeave this unset to omit the field and let the destination use its normal behavior. `time_sensitive` is accepted and marks the notification urgent, but Focus breakthrough is not available yet — run `notifai capabilities` for what a platform actually honours.',
-    unsetMeans: 'not specified; the destination uses its normal behavior',
+      'Apple interruption level controls how hard a notification tries to reach you in the operating system\'s terms. Setting this pins one Apple-only level for sends from here; kind chooses the sound, never this. Android does not accept caller-selected interruption levels: its product-owned channels and your device settings own attention.\n\nLeave this unset to omit the field and let each destination use its normal behavior. `time_sensitive` is accepted on Apple platforms and marks the notification urgent, but Focus breakthrough is not available yet — run `notifai capabilities --platform <platform>` for the exact contract.',
+    unsetMeans: 'not specified; each destination uses its normal behavior',
   },
   devices: {
     label: 'Default devices',
@@ -193,17 +193,6 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     unsetMeans: 'inferred from Git or the current directory',
     example: 'my-app',
   },
-  notify_criteria: {
-    label: 'House rules for agents',
-    group: 'project',
-    kind: 'string',
-    summary: 'Free text an agent reads before deciding whether to notify you',
-    detail:
-      'Your own guidance, in your own words, about what is worth a notification in this project — read by agents before they send. Something like "only tell me about failures and finished deploys; never per-file progress".\n\nIt is advice to the agent, not a filter the service enforces. Agents follow it as your literal standing word, so an agent may write it only when you ask for a preference to be remembered — and only in your words, never its own summary.',
-    unsetMeans: 'agents fall back to their default judgement',
-    example: 'Only failures and completed deploys',
-  },
-
   log_level: {
     label: 'Log level',
     group: 'diagnostics',
@@ -217,7 +206,7 @@ const INFO: Record<ConfigKey, Omit<ConfigKeyInfo, 'key'>> = {
     },
     summary: 'How much this machine records about what it did',
     detail:
-      'Notifai keeps a local record of what it did — every command, every notification, and in particular every decision a harness hook made about whether a question could leave the terminal. Hooks run headless, so without this there is no account of them at all: `notifai logs` is how an agent finds out afterwards why a question never reached your phone.\n\nThe log never leaves this machine. It is not uploaded, and nothing sends it anywhere.\n\n`debug` also records which config layer won and the detail of each request, which is what to turn on when something is behaving in a way the ordinary log does not explain.',
+      'Notifai keeps a local record of what it did — every command, every notification, and in particular every decision a harness hook made about whether a question could leave the terminal. Hooks run headless, so without this there is no account of them at all: `notifai logs` is how an agent finds out afterwards why a question never reached your device.\n\nThe log never leaves this machine. It is not uploaded, and nothing sends it anywhere.\n\n`debug` also records which config layer won and the detail of each request, which is what to turn on when something is behaving in a way the ordinary log does not explain.',
     example: 'info',
   },
   log_max_bytes: {

package/src/config.test.ts

@@ -201,7 +201,11 @@ describe('draft building', () => {
       targets: { mode: 'all' },
       delivery: { ttl_seconds: 86400, collapse_key: null },
       // An unlabelled draft is ordinary news, and news has a sound.
-      platform: { ios: { sound: 'default' }, macos: { sound: 'default' } },
+      platform: {
+        ios: { sound: 'default' },
+        macos: { sound: 'default' },
+        android: { sound: 'default' },
+      },
     })
   })
 
@@ -218,6 +222,7 @@ describe('draft building', () => {
     const build = buildDraft(config, { title: 'T', body: 'B', ...flags })
     if (!build.ok) throw new Error(build.error)
     expect(build.draft.platform?.ios?.sound).toBe(sound)
+    expect(build.draft.platform?.android?.sound).toBe(sound)
     expect(build.draft.platform?.ios?.interruption_level).toBeUndefined()
   })
 
@@ -239,6 +244,7 @@ describe('draft building', () => {
       sound: 'alert',
       interruption_level: 'active',
     })
+    expect(configured.draft.platform?.android).toEqual({ sound: 'alert' })
 
     const explicit = buildDraft(config, {
       title: 'T',
@@ -252,6 +258,7 @@ describe('draft building', () => {
       sound: null,
       interruption_level: 'time_sensitive',
     })
+    expect(explicit.draft.platform?.android).toEqual({ sound: null })
   })
 
   it('keeps a question answerable for a day by default', () => {
@@ -453,6 +460,10 @@ describe('draft building', () => {
       custom_data: { run_id: '42', branch: 'main' },
     })
     expect(build.draft.platform?.macos).toEqual(build.draft.platform?.ios)
+    expect(build.draft.platform?.android).toEqual({
+      sound: null,
+      custom_data: { run_id: '42', branch: 'main' },
+    })
   })
 
   it('maps optional fields into the selected macOS platform slot', () => {
@@ -479,6 +490,50 @@ describe('draft building', () => {
     })
   })
 
+  it('maps supported optional fields into the selected Android platform slot', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    const build = buildDraft(config, {
+      title: 'T',
+      body: 'B',
+      platform: 'android',
+      sound: 'none',
+      threadId: 'mobile-builds',
+      data: ['run_id=42'],
+    })
+    if (!build.ok) throw new Error(build.error)
+
+    expect(build.platform).toBe('android')
+    expect(build.draft.platform).toEqual({
+      android: {
+        sound: null,
+        thread_id: 'mobile-builds',
+        custom_data: { run_id: '42' },
+      },
+    })
+  })
+
+  it('rejects explicit or configured interruption levels for Android', () => {
+    const config = loadConfig({ cwd: base.cwd, env: base.env })
+    expect(
+      buildDraft(config, {
+        title: 'T',
+        body: 'B',
+        platform: 'android',
+        level: 'active',
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: expect.stringContaining('Android does not support caller-selected interruption levels'),
+    })
+
+    const configuredCase = setup({ projectToml: 'interruption_level = "passive"\n' })
+    const configured = loadConfig({ cwd: configuredCase.cwd, env: configuredCase.env })
+    expect(buildDraft(configured, { title: 'T', body: 'B', platform: 'android' })).toMatchObject({
+      ok: false,
+      error: expect.stringContaining('unset the configured interruption_level'),
+    })
+  })
+
   it('limits collapse keys by UTF-8 bytes', () => {
     const config = loadConfig({ cwd: base.cwd, env: base.env })
     expect(buildDraft(config, { title: 'T', body: 'B', collapseKey: '😀'.repeat(16) }).ok).toBe(

package/src/config.ts

@@ -61,8 +61,6 @@ export interface CliConfig {
   interruption_level: ResolvedValue<CliInterruptionLevel | null>
   /** Project identifier stamped on sends; typically set in .notifai/config.toml. */
   project: ResolvedValue<string | null>
-  /** Free-text notification criteria agents consult before sending. */
-  notify_criteria: ResolvedValue<string | null>
   /** Whether a registered agent question may reach companion devices at all. */
   ask_notifications: ResolvedValue<boolean>
   /**
@@ -105,7 +103,6 @@ export const CONFIG_KEYS = [
   'sound',
   'interruption_level',
   'project',
-  'notify_criteria',
   'ask_notifications',
   'ask_grace_seconds',
   'reply_window_seconds',
@@ -152,7 +149,6 @@ const DEFAULTS = {
   sound: null,
   interruption_level: null,
   project: null,
-  notify_criteria: null,
   // Installing the hooks is the opt-in; these exist to switch the behaviour
   // back off for a project or a session without uninstalling anything.
   ask_notifications: true,
@@ -427,7 +423,6 @@ export function loadConfig(options: {
     sound: resolve('sound'),
     interruption_level: resolve('interruption_level'),
     project: resolve('project'),
-    notify_criteria: resolve('notify_criteria'),
     ask_notifications: resolve('ask_notifications'),
     ask_grace_seconds: resolve('ask_grace_seconds'),
     reply_window_seconds: resolve('reply_window_seconds'),

package/src/guidance-content.ts

@@ -0,0 +1,190 @@
+/**
+ * The shipped notification-writing guidance: what agents follow when the user
+ * has not said otherwise.
+ *
+ * Each topic is a small Markdown document named for the moment an agent
+ * consults it. Users override a topic by placing a file with the same name in
+ * a guidance directory — resolution and layering live in `guidance.ts`, and
+ * the topics ship here as source rather than as packaged files so the packed
+ * CLI cannot lose them.
+ *
+ * The governing principle, stated once: the user hired the outcome, not the
+ * pipeline. Tests, coverage, review passes, hashes and exit codes are how the
+ * work got done; a notification carries what the work means — what is now
+ * finished, what went wrong, what needs them. A detail earns its place only
+ * when it changes what the user does next.
+ */
+
+export interface GuidanceTopic {
+  /** Topic name; also the override filename, `<name>.md`. */
+  name: string
+  /** One line for lists and JSON output. */
+  summary: string
+  /** The Markdown the agent reads. */
+  content: string
+}
+
+const WHEN_TO_NOTIFY = `# When to notify
+
+Notify when something changed for the user:
+
+- Long-running work finished — succeeded or failed.
+- You are blocked on something only they can give: a key, an approval, a
+  decision.
+- You found something that needs their attention soon.
+
+Never notify for:
+
+- Routine progress: starting, still working, one more subtask done.
+- Anything they will see in the terminal within seconds.
+- A problem you hit and fixed yourself.
+
+One notification per event. When a status changes, replace your stale
+notification rather than stacking a new one.
+`
+
+const TITLES = `# Titles
+
+The user hired the outcome, not the pipeline. A title says what the work means
+to them — what is now finished, what went wrong, what needs them — in about 40
+characters, understandable alone. Never put the kind or the project in it;
+both travel as their own fields.
+
+Good:
+
+- \`Users can now create accounts\` — the capability, not the process behind it
+- \`Password reset emails aren't sending\` — the failure as the user experiences it
+- \`Refund flow needs your Stripe key\` — what is stuck and what unblocks it
+- \`Found why checkout was flaky\` — the finding they were waiting on
+- \`3 orders didn't import and need review\` — a count that earns its place
+  because acting on it is theirs to do
+
+Bad:
+
+- \`All 42 tests passed\` — machinery; say what work is done
+- \`Adversarial review found 3 issues\` — process report; say what it means for
+  what ships
+- \`Migration 0007 failed\` — internal identifier; say what the user lost
+- \`Task complete\` / \`Build failed\` / \`Need input\` — no substance, and the
+  kind restated
+- \`Exit code 1\` — mechanics, not meaning
+`
+
+const BODIES = `# Bodies
+
+The first sentence is what the lock screen shows — make it say what this means
+for the user. The rest is what changes for them and what is needed from them,
+never how many tests ran, how long a step took, or which internal stage
+produced it. Keep wording channel-neutral: no device names, no gestures.
+
+Work finished:
+
+> Account creation works end to end now: sign-up, email verification, and
+> login are live on staging.
+>
+> Next I'll start on password reset unless you want something else first.
+
+Work failed:
+
+> The new pricing page isn't live. The deploy failed and I rolled it back, so
+> the site still shows the old page — nothing is broken for users.
+>
+> The blocker is on my side and I'm fixing it; I'll retry and confirm when the
+> page is up. Nothing needed from you.
+
+Blocked:
+
+> The refund flow is built and working against the test environment. Going
+> live needs the Stripe key that only you can issue.
+>
+> That's the last open item — everything else is done.
+
+Bad bodies: a build report (\`42/42 green, coverage 87%, rebased onto main\`)
+where the news is "users can now create accounts"; the journey ("first I
+tried…") instead of the result; a log with the conclusion at the bottom; "see
+terminal for details".
+
+Add a summary line only when the body is long enough that its first line is
+not a fair summary of what is inside: one short line answering what the title
+raises, such as \`Rolled back cleanly; production is untouched\` over a long
+failure report.
+`
+
+const QUESTIONS = `# Questions
+
+A question is answerable from the notification alone, in the user's terms, not
+the machinery's. One askable sentence; reasoning and stakes follow as context.
+Offer closed choices whose wording carries its own consequence.
+
+Good:
+
+- \`The schema change is ready. It touches live order data — deploy now or
+  wait for off-peak?\` with choices \`Deploy now\` / \`Wait for off-peak\`
+- \`The API key in .env.example is live. Revoke it now, or wait until the
+  replacement is provisioned?\` with \`Revoke now\` / \`Wait for the new key\`
+
+Bad:
+
+- \`What should I do?\` — nothing to answer without the terminal
+- \`Deploy to staging and notify the team?\` with \`Yes\` / \`No\` — two
+  decisions, one answer
+- \`Retry with --force-with-lease?\` — machinery; the real decision is
+  \`Overwrite the remote branch, or keep both versions?\`
+- Choices \`Option A\` / \`Option B\` — labels that point back into the body
+- \`Reply here with your choice\` — never name where the answer must arrive
+`
+
+const ACKNOWLEDGEMENTS = `# Acknowledgements
+
+An acknowledgement names the concrete work the reply sets in motion — only
+work you will actually do, and nothing generic.
+
+Good:
+
+- \`Rolling out to staging now; I'll report the health checks.\`
+- \`Holding the deploy. I'll re-raise it once staging is green.\`
+- \`Shipping the fix; I'll confirm when password reset works again.\`
+
+Bad:
+
+- \`Acknowledged.\` / \`Got it!\` — a receipt that shows nothing was understood
+- \`You chose "Deploy now".\` — echoes the reply instead of naming the work
+- \`Deploying now, and I'll also refactor the retry logic.\` — promises work
+  the reply did not cause
+`
+
+/**
+ * Topic order is reading order: decide first, then each thing an agent writes,
+ * in the order it writes them.
+ */
+export const SHIPPED_GUIDANCE: readonly GuidanceTopic[] = [
+  {
+    name: 'when-to-notify',
+    summary: 'What is worth a notification at all',
+    content: WHEN_TO_NOTIFY,
+  },
+  {
+    name: 'titles',
+    summary: 'What a title carries, with examples',
+    content: TITLES,
+  },
+  {
+    name: 'bodies',
+    summary: 'What a body and its summary line carry, with examples',
+    content: BODIES,
+  },
+  {
+    name: 'questions',
+    summary: 'How a question and its choices are worded',
+    content: QUESTIONS,
+  },
+  {
+    name: 'acknowledgements',
+    summary: 'How an acknowledgement is worded',
+    content: ACKNOWLEDGEMENTS,
+  },
+]
+
+export function shippedGuidanceTopic(name: string): GuidanceTopic | undefined {
+  return SHIPPED_GUIDANCE.find((topic) => topic.name === name)
+}

package/src/guidance.test.ts

@@ -0,0 +1,268 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import type { CommandDeps } from './commands-core.js'
+import {
+  guidanceSetCommand,
+  guidanceShowCommand,
+  guidanceUnsetCommand,
+} from './commands-guidance.js'
+import { SHIPPED_GUIDANCE, shippedGuidanceTopic } from './guidance-content.js'
+import {
+  GUIDANCE_TOPIC_MAX_BYTES,
+  personalProjectGuidanceDir,
+  resolveGuidance,
+} from './guidance.js'
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), 'notifai-guidance-'))
+afterAll(() => rmSync(tmp, { recursive: true, force: true }))
+
+function setup(options: {
+  global?: Record<string, string>
+  project?: Record<string, string>
+  projectLocal?: Record<string, string>
+} = {}) {
+  const home = path.join(tmp, `case-${Math.random().toString(36).slice(2)}`)
+  const cwd = path.join(home, 'repo', 'nested')
+  mkdirSync(cwd, { recursive: true })
+  const env = { XDG_CONFIG_HOME: home, XDG_STATE_HOME: path.join(home, 'state') } as NodeJS.ProcessEnv
+  const write = (dir: string, files: Record<string, string>) => {
+    mkdirSync(dir, { recursive: true })
+    for (const [name, content] of Object.entries(files)) writeFileSync(path.join(dir, name), content)
+  }
+  if (options.global !== undefined) write(path.join(home, 'notifai', 'guidance'), options.global)
+  if (options.project !== undefined) write(path.join(home, 'repo', '.notifai', 'guidance'), options.project)
+  if (options.projectLocal !== undefined) write(personalProjectGuidanceDir(cwd, env), options.projectLocal)
+  return { env, cwd, home }
+}
+
+// ---------------------------------------------------------------------------
+// The shipped content: the contract clauses that used to live in SKILL.md.
+// Like skill.test.ts, these assert what the guidance has to teach, not the
+// sentences it teaches it in.
+// ---------------------------------------------------------------------------
+
+describe('shipped guidance content', () => {
+  it('ships the five topics in reading order', () => {
+    expect(SHIPPED_GUIDANCE.map((topic) => topic.name)).toEqual([
+      'when-to-notify',
+      'titles',
+      'bodies',
+      'questions',
+      'acknowledgements',
+    ])
+    for (const topic of SHIPPED_GUIDANCE) {
+      expect(topic.content, topic.name).toMatch(/^# /)
+      expect(topic.summary, topic.name).not.toBe('')
+    }
+  })
+
+  it('teaches when to notify and when not to, one notification per event', () => {
+    const content = shippedGuidanceTopic('when-to-notify')!.content
+    expect(content).toMatch(/finished — succeeded or failed/i)
+    expect(content).toMatch(/blocked on something only they can give/i)
+    expect(content).toMatch(/needs their attention soon/i)
+    expect(content).toMatch(/routine progress/i)
+    expect(content).toMatch(/terminal within seconds/i)
+    expect(content).toMatch(/one notification per event/i)
+  })
+
+  it('teaches outcome-altitude titles that stand alone, without kind or project', () => {
+    const content = shippedGuidanceTopic('titles')!.content
+    expect(content).toMatch(/hired the outcome, not the pipeline/i)
+    expect(content).toMatch(/understandable alone/i)
+    expect(content).toMatch(/40\s*characters/i)
+    expect(content).toMatch(/never put the kind or the project in it/i)
+    // Both example lists survive: good models the altitude, bad names the traps.
+    expect(content).toMatch(/machinery/i)
+    expect(content).toContain('Task complete')
+  })
+
+  it('teaches the leading sentence, user-facing detail only, and channel neutrality', () => {
+    const content = shippedGuidanceTopic('bodies')!.content
+    expect(content).toMatch(/first sentence is what the lock screen shows/i)
+    expect(content).toMatch(/never how many tests ran/i)
+    expect(content).toMatch(/channel-neutral/i)
+    expect(content).toMatch(/summary line only when/i)
+  })
+
+  it('teaches questions answerable alone, with meaningful choices and no route', () => {
+    const content = shippedGuidanceTopic('questions')!.content
+    expect(content).toMatch(/answerable from the notification alone/i)
+    expect(content).toMatch(/closed choices/i)
+    expect(content).toMatch(/never name where the answer must arrive/i)
+  })
+
+  it('teaches acknowledgements that name the concrete work and only that', () => {
+    const content = shippedGuidanceTopic('acknowledgements')!.content
+    expect(content).toMatch(/concrete work the reply sets in motion/i)
+    expect(content).toMatch(/only\s+work you will actually do/i)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Resolution across layers
+// ---------------------------------------------------------------------------
+
+describe('guidance layers', () => {
+  it('serves the shipped defaults when no layer overrides them', () => {
+    const { env, cwd } = setup()
+    const resolved = resolveGuidance({ cwd, env })
+    expect(resolved.map((topic) => topic.name)).toEqual(SHIPPED_GUIDANCE.map((topic) => topic.name))
+    for (const topic of resolved) expect(topic.source).toBe('default')
+  })
+
+  it('lets a layer replace one topic and orders project-local over project over global', () => {
+    const { env, cwd } = setup({
+      global: { 'titles.md': 'global titles\n', 'bodies.md': 'global bodies\n' },
+      project: { 'titles.md': 'project titles\n' },
+      projectLocal: { 'titles.md': 'personal titles\n' },
+    })
+    const resolved = resolveGuidance({ cwd, env })
+    const byName = new Map(resolved.map((topic) => [topic.name, topic]))
+    expect(byName.get('titles')).toMatchObject({
+      content: 'personal titles\n',
+      source: expect.stringMatching(/^project-local:/),
+    })
+    expect(byName.get('bodies')).toMatchObject({
+      content: 'global bodies\n',
+      source: expect.stringMatching(/^global:/),
+    })
+    // A replaced topic keeps its place in reading order.
+    expect(resolved.map((topic) => topic.name)).toEqual(SHIPPED_GUIDANCE.map((topic) => topic.name))
+    // Untouched topics still come from the ship.
+    expect(byName.get('when-to-notify')!.source).toBe('default')
+  })
+
+  it('appends user topics that match no shipped name, in name order', () => {
+    const { env, cwd } = setup({
+      project: { 'house-rules.md': 'always name the branch\n', 'deploys.md': 'deploy rules\n' },
+    })
+    const names = resolveGuidance({ cwd, env }).map((topic) => topic.name)
+    expect(names.slice(SHIPPED_GUIDANCE.length)).toEqual(['deploys', 'house-rules'])
+  })
+
+  it('drops files that are not topics and empty overrides', () => {
+    const { env, cwd } = setup({
+      project: {
+        'notes.txt': 'not markdown\n',
+        'Bad Name.md': 'invalid topic name\n',
+        'titles.md': '   \n',
+      },
+    })
+    const resolved = resolveGuidance({ cwd, env })
+    expect(resolved.map((topic) => topic.name)).toEqual(SHIPPED_GUIDANCE.map((topic) => topic.name))
+    // The empty override does not win; the shipped topic still applies.
+    expect(resolved.find((topic) => topic.name === 'titles')!.source).toBe('default')
+  })
+
+  it('truncates an oversized topic instead of reading it whole into context', () => {
+    const { env, cwd } = setup({
+      project: { 'titles.md': `start-${'x'.repeat(GUIDANCE_TOPIC_MAX_BYTES)}` },
+    })
+    const titles = resolveGuidance({ cwd, env }).find((topic) => topic.name === 'titles')!
+    expect(titles.content.length).toBeLessThan(GUIDANCE_TOPIC_MAX_BYTES + 200)
+    expect(titles.content).toMatch(/\[Truncated:/)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+interface CapturedIo {
+  out: string[]
+  err: string[]
+}
+
+function makeDeps(env: NodeJS.ProcessEnv, cwd: string, confirmAnswer = false) {
+  const captured: CapturedIo = { out: [], err: [] }
+  const deps = {
+    io: {
+      out: (line: string) => captured.out.push(line),
+      err: (line: string) => captured.err.push(line),
+      confirm: async () => confirmAnswer,
+      openUrl: () => {},
+    },
+    store: {
+      load: () => null,
+      save: () => {},
+      clear: () => {},
+      describe: () => 'test credential store',
+    },
+    env,
+    cwd,
+  } as unknown as CommandDeps
+  return { deps, captured }
+}
+
+describe('guidance commands', () => {
+  it('shows every topic under a provenance comment', () => {
+    const { env, cwd } = setup({ project: { 'titles.md': 'my titles\n' } })
+    const { deps, captured } = makeDeps(env, cwd)
+    expect(guidanceShowCommand(deps, {})).toBe(0)
+    const output = captured.out.join('\n')
+    expect(output).toMatch(/<!-- when-to-notify · shipped default -->/)
+    expect(output).toMatch(/<!-- titles · this project \(shared\) · .*titles\.md -->/)
+    expect(output).toContain('my titles')
+  })
+
+  it('emits machine-readable topics with name, source, summary, and content', () => {
+    const { env, cwd } = setup()
+    const { deps, captured } = makeDeps(env, cwd)
+    expect(guidanceShowCommand(deps, { json: true })).toBe(0)
+    const topics = JSON.parse(captured.out.join('\n')) as { name: string; source: string }[]
+    expect(topics.map((topic) => topic.name)).toEqual(SHIPPED_GUIDANCE.map((topic) => topic.name))
+    expect(topics.every((topic) => topic.source === 'default')).toBe(true)
+  })
+
+  it('writes a topic to the chosen layer and resolution picks it up', async () => {
+    const { env, cwd, home } = setup()
+    const { deps } = makeDeps(env, cwd)
+    const code = await guidanceSetCommand(deps, 'titles', 'Prefix titles with 🚀', {
+      project: true,
+      yes: true,
+    })
+    expect(code).toBe(0)
+    const file = path.join(cwd, '.notifai', 'guidance', 'titles.md')
+    expect(readFileSync(file, 'utf8')).toBe('Prefix titles with 🚀\n')
+    expect(resolveGuidance({ cwd, env })).toContainEqual(
+      expect.objectContaining({ name: 'titles', content: 'Prefix titles with 🚀\n' }),
+    )
+    expect(home).toBeTruthy()
+  })
+
+  it('holds the confirmation gate: no --yes and no consent means no write', async () => {
+    const { env, cwd } = setup()
+    const { deps, captured } = makeDeps(env, cwd, false)
+    const code = await guidanceSetCommand(deps, 'titles', 'in my own words', {})
+    expect(code).toBe(2)
+    expect(captured.err.join('\n')).toMatch(/not confirmed/i)
+    expect(resolveGuidance({ cwd, env }).find((topic) => topic.name === 'titles')!.source).toBe(
+      'default',
+    )
+  })
+
+  it('rejects a name that is not a topic and rejects an oversized write', async () => {
+    const { env, cwd } = setup()
+    const { deps, captured } = makeDeps(env, cwd)
+    expect(await guidanceSetCommand(deps, 'Not A Topic', 'text', { yes: true })).toBe(2)
+    expect(captured.err.join('\n')).toMatch(/not a topic name/i)
+    expect(
+      await guidanceSetCommand(deps, 'titles', 'x'.repeat(GUIDANCE_TOPIC_MAX_BYTES + 1), {
+        yes: true,
+      }),
+    ).toBe(2)
+  })
+
+  it('unsets an override so the inherited guidance applies again', async () => {
+    const { env, cwd } = setup({ project: { 'titles.md': 'override\n' } })
+    const { deps } = makeDeps(env, cwd)
+    expect(await guidanceUnsetCommand(deps, 'titles', { project: true, yes: true })).toBe(0)
+    expect(existsSync(path.join(cwd, '..', '.notifai', 'guidance', 'titles.md'))).toBe(false)
+    expect(resolveGuidance({ cwd, env }).find((topic) => topic.name === 'titles')!.source).toBe(
+      'default',
+    )
+  })
+})