@raidiant/notifai 11.3.2 → 11.4.0

package/dist/session-handoff.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Hand one message into a running Agent Session, in place.
+ *
+ * The one harness write every hand-off shares: the answer waiter's wake routes
+ * and the Session Attendant's Session Messages both end here. It never cold
+ * resumes: a stopped session is reported as stopped, and only the answer route
+ * decides what to do about that (Session Messages never resume a session).
+ *
+ * `begin` is the commit point. It is called immediately before the
+ * irreversible write, after every check that can refuse without writing; when
+ * it returns false nothing is handed over. A `failed` result after `begin`
+ * means the write may or may not have reached the harness.
+ */
+import { type ClaudeSessionDescriptor, type ClaudeWakeAdapters } from './claude-wake.js';
+import { type CodexWakeAdapters } from './codex-wake.js';
+import { type WriteGuard } from './wake-support.js';
+export type SessionWriteResult = {
+    status: 'written';
+    route: 'inbox-socket' | 'session-queue';
+    /** Claude only: whether the session was idle or busy when the message was posted. */
+    sessionState?: 'live-idle' | 'live-busy';
+}
+/** Nothing was written: the exact session could not be proven reachable in place. */
+ | {
+    status: 'unavailable';
+    reason: string;
+}
+/** Claude only: no process hosts the session any more; nothing was written. */
+ | {
+    status: 'stopped';
+}
+/** `begin` refused (SessionEnd won, a claim lapsed, the lease cannot cover the write). */
+ | {
+    status: 'cancelled';
+}
+/** `begin` succeeded, then the write guard stopped the write before any byte left. */
+ | {
+    status: 'aborted';
+    reason: string;
+}
+/** The write started and failed; it may or may not have reached the harness. */
+ | {
+    status: 'failed';
+    reason: string;
+    error: unknown;
+};
+/**
+ * The Claude session descriptor of the process that will post, when it names
+ * this exact session. Read once, when the writer starts: a descriptor that
+ * appears later is not evidence that this process is that session's child.
+ */
+export declare function claudeSourceDescriptor(sessionId: string, sourcePid: number, adapters: Pick<ClaudeWakeAdapters, 'readDescriptor'>): ClaudeSessionDescriptor | null;
+/**
+ * Claude Code's own-child inbox route. Claude delivers an inbox-socket line
+ * only from a verified descendant of the receiving process, so the writer must
+ * be that exact session's child: `sourcePid` is its harness process, observed
+ * again right before the write.
+ *
+ * `holdAfterSend` keeps the posting process alive while macOS verifies the
+ * sender's ancestry. A resident writer (the Session Attendant) stays alive
+ * anyway and skips the wait.
+ */
+export declare function deliverIntoClaudeSession(options: {
+    sessionId: string;
+    sourcePid: number;
+    sourceDescriptor: ClaudeSessionDescriptor | null;
+    adapters: ClaudeWakeAdapters;
+    text: string;
+    begin(): boolean;
+    holdAfterSend?: boolean;
+    /** Checked at the socket itself, after it connects and before its first byte. */
+    guard?: WriteGuard;
+    /** Names the posting process in refusal reasons, which logs keep verbatim. */
+    writer: string;
+}): Promise<SessionWriteResult>;
+/**
+ * Codex's durable per-thread inbox. Exit 0 proves the queue stored the
+ * message, never that the thread consumed it, and a stopped thread drains it
+ * the next time it opens.
+ */
+export declare function deliverIntoCodexThread(options: {
+    threadId: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    adapters: CodexWakeAdapters;
+    text: string;
+    begin(): boolean;
+    /**
+     * A claimed write's bound: checked after `begin`, immediately before the
+     * queue writer starts, and its `remainingMs` then bounds the writer's whole
+     * life. A writer still running at that deadline has its process group
+     * killed and is reported `failed`: it may have written.
+     */
+    guard?: WriteGuard;
+    /** Receives the queue writer's process group as soon as it exists. */
+    onSpawn?: (pgid: number) => void;
+}): Promise<SessionWriteResult>;
+export declare function claudeSocketLine(text: string): string;

package/dist/session-handoff.js

@@ -0,0 +1,118 @@
+/**
+ * Hand one message into a running Agent Session, in place.
+ *
+ * The one harness write every hand-off shares: the answer waiter's wake routes
+ * and the Session Attendant's Session Messages both end here. It never cold
+ * resumes: a stopped session is reported as stopped, and only the answer route
+ * decides what to do about that (Session Messages never resume a session).
+ *
+ * `begin` is the commit point. It is called immediately before the
+ * irreversible write, after every check that can refuse without writing; when
+ * it returns false nothing is handed over. A `failed` result after `begin`
+ * means the write may or may not have reached the harness.
+ */
+import { CLAUDE_POST_SEND_LIVENESS_MS, observeClaudeSession, parseDescriptor, } from './claude-wake.js';
+import { inspectCodexQueue } from './codex-wake.js';
+import { WriteAbortedError, WriteDeadlineError } from './wake-support.js';
+/**
+ * The Claude session descriptor of the process that will post, when it names
+ * this exact session. Read once, when the writer starts: a descriptor that
+ * appears later is not evidence that this process is that session's child.
+ */
+export function claudeSourceDescriptor(sessionId, sourcePid, adapters) {
+    try {
+        const parsed = parseDescriptor(adapters.readDescriptor(sourcePid));
+        return parsed !== null && parsed.sessionId === sessionId && parsed.pid === sourcePid
+            ? parsed
+            : null;
+    }
+    catch {
+        // Delivery fails closed below; a missing descriptor must never break the caller.
+        return null;
+    }
+}
+/**
+ * Claude Code's own-child inbox route. Claude delivers an inbox-socket line
+ * only from a verified descendant of the receiving process, so the writer must
+ * be that exact session's child: `sourcePid` is its harness process, observed
+ * again right before the write.
+ *
+ * `holdAfterSend` keeps the posting process alive while macOS verifies the
+ * sender's ancestry. A resident writer (the Session Attendant) stays alive
+ * anyway and skips the wait.
+ */
+export async function deliverIntoClaudeSession(options) {
+    const { adapters, writer } = options;
+    const observation = await observeClaudeSession(options.sessionId, adapters);
+    if (observation.state === 'unknown')
+        return { status: 'unavailable', reason: observation.reason };
+    if (options.sourceDescriptor === null) {
+        return {
+            status: 'unavailable',
+            reason: `the ${writer} cannot prove exact Claude session ownership`,
+        };
+    }
+    if (observation.state === 'stopped')
+        return { status: 'stopped' };
+    if (observation.descriptor.pid !== options.sourcePid ||
+        options.sourceDescriptor.startedAt !== observation.descriptor.startedAt) {
+        return {
+            status: 'unavailable',
+            reason: `the ${writer} is not the observed exact Claude session child`,
+        };
+    }
+    if (!options.begin())
+        return { status: 'cancelled' };
+    try {
+        await adapters.sendSocket(observation.descriptor.messagingSocketPath, claudeSocketLine(options.text), options.guard);
+    }
+    catch (err) {
+        if (err instanceof WriteAbortedError)
+            return { status: 'aborted', reason: err.message };
+        return { status: 'failed', reason: err instanceof Error ? err.message : String(err), error: err };
+    }
+    if (options.holdAfterSend !== false)
+        await adapters.sleep(CLAUDE_POST_SEND_LIVENESS_MS);
+    return { status: 'written', route: 'inbox-socket', sessionState: observation.state };
+}
+/**
+ * Codex's durable per-thread inbox. Exit 0 proves the queue stored the
+ * message, never that the thread consumed it, and a stopped thread drains it
+ * the next time it opens.
+ */
+export async function deliverIntoCodexThread(options) {
+    const readiness = inspectCodexQueue(options.threadId, options.env);
+    if (readiness.state === 'unavailable')
+        return { status: 'unavailable', reason: readiness.reason };
+    if (!options.begin())
+        return { status: 'cancelled' };
+    if (options.guard !== undefined && !options.guard.writable()) {
+        return { status: 'aborted', reason: 'the claim or lease lapsed before the queue writer started' };
+    }
+    const budget = options.guard?.remainingMs() ?? Number.POSITIVE_INFINITY;
+    const deadline = new AbortController();
+    const timer = Number.isFinite(budget) ? setTimeout(() => deadline.abort(), Math.max(0, budget)) : undefined;
+    try {
+        await options.adapters.queue(readiness.threadId, options.cwd, options.text, options.onSpawn, deadline.signal);
+    }
+    catch (err) {
+        return { status: 'failed', reason: err instanceof Error ? err.message : String(err), error: err };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+    if (deadline.signal.aborted) {
+        // The writer finished, but only after its claim's write boundary.
+        const error = new WriteDeadlineError('the queue writer finished after its claim deadline');
+        return { status: 'failed', reason: error.message, error };
+    }
+    return { status: 'written', route: 'session-queue' };
+}
+export function claudeSocketLine(text) {
+    return `${JSON.stringify({
+        type: 'user',
+        message: { role: 'user', content: text },
+    })}\n`;
+}
+//# sourceMappingURL=session-handoff.js.map

package/dist/session-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-handoff.js","sourceRoot":"","sources":["../src/session-handoff.ts"],"names":[],"mappings":"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"}

package/dist/session-message-handoff.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How the Session Attendant hands Session Messages — Session Notes and
+ * post-delivery Answer Edits — into its running Agent Session.
+ *
+ * Each message is one claimed hand-off through the session's delivery
+ * sequencer, in the order the service accepted them: claim under the attendant's
+ * lease generation, record the acknowledgement it is owed, write the
+ * structured context in place, report. Nothing is written without a claim,
+ * nothing after the claim deadline or the attendant's own write margin, and an
+ * `unconfirmed` message is never written again.
+ */
+import type { AttendanceMessage } from '@raidiant/notifai-protocol';
+import { type SequencerDeps } from './session-delivery.js';
+import type { AttendantHandle } from './session-attendant.js';
+import type { SessionWriteResult } from './session-handoff.js';
+import type { WriteGuard } from './wake-support.js';
+/**
+ * - `done`: every message was handed off, settled elsewhere, or waits for the
+ *   next exchange (which returns every message still claimable).
+ * - `retry-soon`: a message waits on something that resolves in seconds (its
+ *   fenced answer's outcome, the delivery lock, a lease renewal); ask again
+ *   without holding the exchange open.
+ */
+export type MessageHandOffResult = 'done' | 'retry-soon';
+export interface MessageHandOffDeps {
+    sequencer: SequencerDeps;
+    /**
+     * The in-place write: `begin` is its commit point and `guard` is checked at
+     * the write itself, before the first byte. A write made by a harness
+     * subprocess (`codex queue`) begins as `subprocess` and reports that
+     * subprocess's process group through `writerGroup` as soon as it exists.
+     */
+    write(text: string, begin: (writer?: 'subprocess') => boolean, guard: WriteGuard, writerGroup: (pgid: number) => void): Promise<SessionWriteResult>;
+}
+export declare function handOffSessionMessages(messages: readonly AttendanceMessage[], attendant: AttendantHandle, deps: MessageHandOffDeps): Promise<MessageHandOffResult>;

package/dist/session-message-handoff.js

@@ -0,0 +1,99 @@
+import { clearAcknowledgementObligation, recordMessageAcknowledgementDue } from './hook-acknowledgements.js';
+import { sessionMessageContext } from './injection-render.js';
+import { answerWriterGone, beginHandOff } from './session-delivery.js';
+export async function handOffSessionMessages(messages, attendant, deps) {
+    const { sequencer } = deps;
+    const log = sequencer.log;
+    // The service lists messages in acceptance (revision) order, which is the
+    // User's order. Timestamps can tie and identifiers are random, so neither
+    // may reorder them: a later edit must never land before an earlier one.
+    for (const message of messages) {
+        const generation = attendant.generation();
+        if (generation === null || !attendant.mayWrite())
+            return 'retry-soon';
+        const handOff = await beginHandOff(sequencer, {
+            lease: { incarnation: attendant.incarnation(), generation },
+            subjects: [{ type: 'session_message', message_id: message.message_id }],
+            earlierAnswerWriterGone: () => message.kind === 'answer_edit' &&
+                answerWriterGone(sequencer.sessionId, sequencer.env, message.request_id, sequencer.liveness, sequencer.groupAlive),
+            mayWrite: () => attendant.mayWrite(),
+        });
+        if (handOff === null)
+            return 'retry-soon';
+        const refusal = handOff.refused[0];
+        if (refusal !== undefined) {
+            await handOff.finish('not-written');
+            switch (refusal.reason) {
+                case 'awaiting_earlier_answer':
+                case 'attempt_pending':
+                case 'unavailable':
+                    // Later messages keep their order behind this one.
+                    return 'retry-soon';
+                case 'generation_fenced':
+                    // The lease moved; the attendant re-acquires before anything else.
+                    return 'done';
+                case 'not_claimable':
+                case 'not_found':
+                    continue;
+            }
+        }
+        let owed = false;
+        let result;
+        try {
+            result = await deps.write(sessionMessageContext(message), (writer) => {
+                recordMessageAcknowledgementDue(sequencer.sessionId, sequencer.env, {
+                    message_id: message.message_id,
+                    recorded_at: sequencer.wall(),
+                    text_required: message.agent_acknowledgement_text_required,
+                });
+                owed = true;
+                if (handOff.begin(undefined, { subprocess: writer === 'subprocess' }))
+                    return true;
+                clearAcknowledgementObligation(sequencer.sessionId, sequencer.env, message.message_id);
+                owed = false;
+                return false;
+            }, {
+                // The lease check probes the harness and can block: the claim
+                // deadline is judged after it, at the last moment before the byte.
+                writable: () => attendant.mayWrite() && handOff.writable(),
+                remainingMs: () => handOff.remainingMs(),
+            }, (pgid) => handOff.recordGroup(pgid));
+        }
+        catch (err) {
+            // Thrown before the write (state I/O): nothing reached the harness.
+            if (owed)
+                clearAcknowledgementObligation(sequencer.sessionId, sequencer.env, message.message_id);
+            await handOff.finish('not-written');
+            throw err;
+        }
+        log?.info('delivery.handoff', {
+            message_id: message.message_id,
+            kind: message.kind,
+            write: result.status,
+            ...(result.status === 'unavailable' || result.status === 'failed' ? { reason: result.reason } : {}),
+        });
+        switch (result.status) {
+            case 'written':
+                await handOff.finish('written');
+                continue;
+            case 'failed':
+                // It may have arrived: the debt stays and the service hears `unconfirmed`.
+                await handOff.finish('failed');
+                continue;
+            case 'cancelled':
+                await handOff.finish('not-written');
+                return 'retry-soon';
+            case 'aborted':
+                // Stopped at the socket before any byte left: nothing arrived, nothing is owed.
+                clearAcknowledgementObligation(sequencer.sessionId, sequencer.env, message.message_id);
+                await handOff.finish('aborted');
+                return 'retry-soon';
+            case 'unavailable':
+            case 'stopped':
+                await handOff.finish('not-written');
+                return 'done';
+        }
+    }
+    return 'done';
+}
+//# sourceMappingURL=session-message-handoff.js.map

package/dist/session-message-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-message-handoff.js","sourceRoot":"","sources":["../src/session-message-handoff.ts"],"names":[],"mappings":"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"}

package/dist/skill-source/manifest.json

@@ -1,20 +1,36 @@
 {
   "schema_version": 1,
-  "package_version": "11.3.2",
+  "package_version": "11.4.0",
   "skill": "notifai",
-  "digest": "sha256:6b5b2a43d5798a8d6095e3884046aeb0e6758fc9211a07c6130e01e99edd00d3",
+  "digest": "sha256:a94b7564764b023ec4fdf4aa5f6bdac0e47ce6d7da9bde4795fd177dd2725aa1",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "7769c166269c9612bd3fdfc24fe2d884321f68959c999f109a18d82a41a01803"
+      "sha256": "7bc8330caa4e5e86262708b05d35767e63b229d19786ecaebf43fb1ac09c4be6"
+    },
+    {
+      "path": "references/diagnostics.md",
+      "sha256": "a3ec112b116efdf8b1f496df14dd7f12ac79d7b7c071d08c88cc1bfa5035d5d9"
     },
     {
       "path": "references/harness-setup.md",
-      "sha256": "e2ef0c2c1c81568ce7afa310d0c979795209ace5e276d65f2410976de0050a5d"
+      "sha256": "b00af6f76e7ce06d59bc2fe5fc4ac4312fd9c829c5bd2202e990aa83bc69c551"
+    },
+    {
+      "path": "references/notes-and-edits.md",
+      "sha256": "9bf5ac8fea62080a903dbb5c70044bc9644e02dc19d9e1a9b2f9b44dbf0a18a1"
+    },
+    {
+      "path": "references/send-details.md",
+      "sha256": "575011edbea8dc93b85ff119dfaef328574c765b3a6500c7a6eb132c5b9fb9f9"
     },
     {
       "path": "references/updates.md",
       "sha256": "55ee18d2c53923932605e9c30823400f7e494456bb18e0de8ea6c5206e632b79"
+    },
+    {
+      "path": "references/writing-examples.md",
+      "sha256": "ba0dc8eb849aaa513476067c4e405ea284a4228e2445b8ab7343bd3450b1eebf"
     }
   ]
 }

package/dist/skill-source/notifai/SKILL.md

@@ -5,8 +5,8 @@ description: Use when work needs a User decision, approval, sign-in, credential
 
 # Notifai
 
-Use `notifai`; never hand-roll HTTP, hooks, or polling. It owns routing,
-retries, and delivery evidence.
+Use `notifai` for routing, retries, and delivery evidence; never hand-roll
+HTTP, hooks, or polling.
 
 If missing: `npm install -g @raidiant/notifai`. Pinned
 `npx --yes @raidiant/notifai@<version>` is only for users refusing a global binary,
@@ -96,9 +96,8 @@ notifai send --kind done \
   --body "Sign-up, email verification, and login work end to end on staging. Next: password reset, unless you want something else first."
 ```
 
-Outside a Project, or when the User explicitly asks for a Projectless
-notification, pass `--projectless`. This deliberate override prevents cwd or
-saved config from inventing a Project and never enables one.
+Outside a Project, or when the User asks for a Projectless notification, pass
+`--projectless`; it keeps cwd or config from inventing a Project.
 
 `--kind` is required, and it is the most consequential word you choose:
 
@@ -125,21 +124,11 @@ Use one-way blocked only when no User reply would resume the work.
   Summary's information plus useful detail; focused views show Body or Summary,
   never both. Omit it when Summary is enough.
 
-Use readable Markdown structure. Summary has no Markdown or media markup.
+Use `--body-file <path|->` for long content.
 
-Use `--body-file <path|->` for long content. Keep wording channel-neutral.
-
-Other controls: `--thread-id` groups; `--collapse-key` replaces your earlier
-matching notification; `--ttl` bounds useful delivery.
-Use `notifai capabilities --platform <platform>` for destination contracts.
-
-Repeat `--image <path|url>` (up to 8), paired with `--image-alt`; all reach the
-gallery. Reference any or all in Body with Markdown image syntax:
-`- Bob: ![front](media:1) ![side](media:2)`. Bare `media:1`, `[…](media:1)`,
-or a position with no `--image` is an error.
-
-`--sound`, `--level`, and `--device` belong to the User.
-`--sound` takes a shipped name or a custom name/id from `notifai sounds`.
+Images (`--image`, referenced in Body as `media:1`), grouping, replacement,
+and the User-owned `--sound`, `--level`, and `--device`:
+[Sending details](references/send-details.md).
 Use `--retry` only for the same unresolved Agent Event; the CLI reuses one
 opaque attempt or refuses ambiguity.
 
@@ -151,7 +140,7 @@ It is safe to repeat the same `--session-label` on every send and ask; the first
 accepted semantic name remains authoritative. Only a generated fallback name
 can be replaced by a later semantic name.
 
-User renames sync across Companion Apps and future Requests. An agent may run
+An agent may run
 `notifai session rename "New job"` only when its job changed completely and its
 current name would now mislead. Never rename for milestones, ordinary progress,
 or same-job refinement. The command accepts no Agent Session id and fails unless
@@ -196,16 +185,15 @@ notifai status <question_id> --json
 
 States: `local`, `frozen`, `live`, `answered`, `withdrawn`, `retired`.
 
-**Registering is not the end of the turn.** In that same turn, ask the question
-in the conversation and say what each answer will make you do, then end your
-turn to start submission. Ordinary sends need no turn boundary. Continue
-independent work in later turns; preserve supervision.
+**Registering is not the end of the turn.** Ask in plain conversational text,
+say what each answer will make you do, then end the turn to start submission.
+A second harness form can remain pending after a reply. Follow
+higher-priority rules; never claim either path retires the other.
 
 **Never say where the answer must arrive** ("tell me here"). The harness owns routing.
 
-Use `--multi` for combined answers, `--body`/`--body-file` for Body,
-`--image`/`--image-alt` for evidence, or `--form <path|->` for up to 10 questions
-with a set-level `summary`.
+Use `--multi` for combined answers, `--body-file` for Body, `--image` for
+evidence, or `--form <path|->` for up to 10 questions with one `summary`.
 
 Register independent questions separately. Retire an obsolete registration or
 one they answer in the conversation with
@@ -250,10 +238,9 @@ resume later. Never create a duplicate. On exit 0, act on the answer.
 
 ## When the answer arrives
 
-The latest reply is the user's current word: a later one corrects an earlier
-one, and a typed answer arriving in parts is read together, in order. A relayed
-answer reaches you as the chosen label's text; `notifai replies <request_id>
---json` has the stable choice ids.
+The latest reply is the user's current word: later choices correct earlier
+ones; typed parts are read together in order. A relayed answer uses the chosen
+label; `notifai replies <request_id> --json` has stable choice ids.
 
 Questions normally remain answerable for a day. When resuming without a relayed
 answer, inspect the original `question_id`. If it is lost, list outstanding
@@ -264,16 +251,16 @@ notifai replies --pending --json
 ```
 
 **Acknowledge before you resume.** The user needs to know their reply was read.
-Notifai tells you the exact command; run it once per answered request that
-arrived through Notifai, before any of the work it unblocks:
+Notifai tells you the exact command; run it once per answered request or
+[note or edit](references/notes-and-edits.md) (`sm_…`) that arrived through
+Notifai, before the work it unblocks:
 
 ```bash
 notifai acknowledge <request_id> --text "Rolling out to staging now; I'll report the health checks."
 ```
 
-Keep it under 200 characters — it is a receipt, not a report.
-
-Name only the concrete work their reply causes.
+Keep it under 200 characters and name only the concrete work their reply
+causes: it is a receipt, not a report.
 
 If the written reply is off, Notifai prints the command without `--text`; run
 exactly that. The acknowledgement is never optional.
@@ -313,9 +300,6 @@ Lifecycle wiring has no scope: one install per harness for this machine;
 notifai init <--hooks|--no-hooks> [--skills --skills-scope <project|global>] --json
 ```
 
-`init` never creates `.notifai/config.toml`; use it only for tracked shared
-overrides.
-
 Branch on `states`, `can_send`, and `question_routing_ready`.
 `direct_wake_ready` assesses the route, not consumption;
 optional when a held continuation or journal recovery owns the answer,
@@ -330,11 +314,6 @@ that document has the words.
 Never emulate User-owned actions, claim to approve hooks yourself, or claim an
 unlisted harness. Harness trust wording lives in the setup reference.
 
-When sign-in looks fine but nothing sends, `notifai auth status --json` and
-`notifai auth access --json` separate a pairing problem from an account without
-an active plan — report which one it is instead of calling it a delivery
-failure.
-
 On `no_active_devices`, run `notifai init --json`, close its gap, then repeat the
 exact original send with `--retry`. A verification Notification does not deliver
 the original Agent Event.
@@ -347,7 +326,7 @@ installing hooks or diagnosing routing, not before.
 
 ## Check what happened
 
-Warning-free ordinary sends are silent on success; use `--json` for a receipt.
+Ordinary sends are silent on success; `--json` gives a receipt.
 Check `status` before calling delivery unconfirmed. Provider Acceptance proves
 acceptance, a Companion Receipt proves receipt, neither proves the User read it.
 `unknown` is not failure.
@@ -356,28 +335,10 @@ acceptance, a Companion Receipt proves receipt, neither proves the User read it.
 notifai status <question_id|request_id> # state, promotion, and evidence
 ```
 
-When something did not happen and you cannot see why — most of all after `ask`,
-whose push happens later inside a hook the harness swallows — the local log is
-the only account:
-
-```bash
-notifai logs                     # recent record for this project
-notifai logs --level error       # only what failed
-notifai logs --request <id>      # everything about one notification
-notifai logs --since 10m --json  # JSONL on stdout, for parsing
-```
-
-An empty record can mean `log_level` is `off` — check it before concluding a
-hook never ran.
-
-`hook.gate` records carry a fixed `reason` — `notifications-off`,
-`claimed-elsewhere`, `no-question`, `no-session`, `answered`,
-`acknowledgement-required`, `acknowledgement-abandoned`, `harness-cannot-continue`,
-`continuation-repeat`,
-`continuation-limit`,
-`delivery-limit`, `proceeding` — so filter on that, never on the wording of a
-message. `notifications-off` is the one the user deliberately never sees, which
-is why it is worth ruling out before concluding anything is broken.
+When something did not happen and you cannot see why — most of all after
+`ask` — `notifai logs` is the only account: its `hook.gate` records carry a
+fixed reason. Read [Diagnosing what happened](references/diagnostics.md) for
+filters, the reasons, and sign-in versus plan problems.
 
 The log never leaves the machine, and it contains the user's own answers. Treat
 it like any other private file of theirs.

package/dist/skill-source/notifai/references/diagnostics.md

@@ -0,0 +1,31 @@
+# Diagnosing what happened
+
+When something did not happen and you cannot see why — most of all after `ask`,
+whose push happens later inside a hook the harness swallows — the local log is
+the only account:
+
+```bash
+notifai logs                     # recent record for this project
+notifai logs --level error       # only what failed
+notifai logs --request <id>      # everything about one notification
+notifai logs --since 10m --json  # JSONL on stdout, for parsing
+```
+
+An empty record can mean `log_level` is `off` — check it before concluding a
+hook never ran.
+
+`hook.gate` records carry a fixed `reason` — `notifications-off`,
+`claimed-elsewhere`, `no-question`, `no-session`, `answered`,
+`acknowledgement-required`, `acknowledgement-abandoned`, `harness-cannot-continue`,
+`continuation-repeat`, `continuation-limit`, `delivery-limit`, `proceeding` —
+so filter on that, never on the wording of a message. `notifications-off` is
+the one the user deliberately never sees, which is why it is worth ruling out
+before concluding anything is broken.
+
+When sign-in looks fine but nothing sends, `notifai auth status --json` and
+`notifai auth access --json` separate a pairing problem from an account without
+an active plan — report which one it is instead of calling it a delivery
+failure.
+
+The log never leaves the machine, and it contains the user's own answers. Treat
+it like any other private file of theirs.

package/dist/skill-source/notifai/references/harness-setup.md

@@ -310,3 +310,6 @@ journal is crash recovery, not the ordinary delivery path.
 want in CI or any shell with nobody at it. `NOTIFAI_CREDENTIALS=file` stores the
 machine credential in a plaintext file rather than the OS keychain — only when
 the user has asked for it, and never on a shared machine.
+
+`notifai init` never creates `.notifai/config.toml`; that file is only for
+tracked, shared overrides a Project chooses to commit.