# Set up Notifai on this computer — instructions for agents

You are an agent, and the User asked you to follow these instructions. If what
you are reading is a summary or an excerpt, fetch the raw file first (for
example `curl -fsSL https://app.notifai.sh/setup.md`) and follow that.

Do the work yourself. The User does only the steps marked **User action**.
Talk to the User only with the message templates at the end, with the
placeholders filled in and nothing else changed.

The result: the `notifai` command-line tool on this computer, signed in to the
User's Account, their Companion App installed on their phone, and one real test
notification delivered. From then on any agent on this computer can notify them
with `notifai send` and ask them questions with `notifai ask`.

Run the commands below from the directory the User is working in: setup
enables Notifai for that project.

## 1. Node.js 20.12 or newer

```
node --version
```

Version 20.12 or newer: go to step 2.

Missing or older: install the current LTS yourself.

| Where | Run |
| --- | --- |
| macOS with Homebrew | `brew install node` |
| Windows | send **T0** first, then `winget install --id OpenJS.NodeJS.LTS -e --accept-source-agreements --accept-package-agreements` |
| Linux, or anywhere with a Node version manager (`fnm`, `nvm`, `volta`, `mise`, `asdf`) | its install command for the LTS release, for example `fnm install --lts` or `nvm install --lts` |
| Linux without a version manager | the distribution package manager, only if the packaged version is 20.12 or newer |

Then check again. If the shell still cannot find `node`, its directory is not
on this session's PATH yet. Windows: PowerShell
`$env:Path += ";C:\Program Files\nodejs"`, Git Bash
`export PATH="$PATH:/c/Program Files/nodejs"`. macOS and Linux: add the
directory the installer printed. If every command runs in a fresh shell (Codex
on Windows does this), put that PATH line in front of each later command.

If you cannot install it (no package manager, no permission): send **T1** and
stop until the User says it is done, then check again.

## 2. The Notifai command-line tool

```
notifai --version
```

If it prints a version: go to step 3. Otherwise:

```
npm install -g @raidiant/notifai
```

- `EACCES` or "permission denied" on macOS or Linux: do not use `sudo`. Give
  npm a directory the User owns, then install again:
  ```
  npm config set prefix "$HOME/.npm-global"
  export PATH="$HOME/.npm-global/bin:$PATH"
  npm install -g @raidiant/notifai
  ```
  and add that `export` line to the shell's profile (`~/.zshrc`, `~/.bashrc`,
  or `~/.profile`, whichever the User's shell reads).
- `notifai` not found after a successful install: npm's global directory is not
  on PATH. Add it to this session and to the shell profile (on Windows, to the
  User environment variable `Path`):
  - macOS and Linux: `export PATH="$PATH:$(npm prefix -g)/bin"`
  - Windows PowerShell: `$env:Path += ";$(npm prefix -g)"`
  - Windows Git Bash: `export PATH="$PATH:$(cygpath -u "$(npm prefix -g)")"`

## 3. Run setup and act on what it reports

```
notifai init --json --hooks --skills --skills-scope global
```

Give the command a tool timeout of at least 5 minutes. It never prompts and
never waits for a person. Progress goes to stderr; the final state is one JSON
object on stdout. It installs what it can (harness hooks so questions reach the
phone and answers come back, the Notifai skill for every project on this
machine, project enablement, the test notification) and reports the first
thing it cannot do alone. **Exit code 1 with JSON on stdout is the normal
blocked outcome, not an error: read the JSON.**

Read the JSON:

- `ready: true` → step 4.
- Otherwise find the first entry in `states` with `"status": "gap"`, skipping
  `skill`, `question-routing-settings`, and any `hooks`/`hooks-*` entry that has
  no `remedy.user_action` (optional automation, never a reason to stop). Act on
  its `id`:

| `id` | What it means | What you do |
| --- | --- | --- |
| `credential`, `technical.pairing_outcome` is `pending` | This computer must be approved in the User's browser. Setup already opened the page if it could. | **User action.** Send **T2** with `technical.pairing.approve_url` and `technical.pairing.code`. When the User says it is approved, run setup again: the same approval resumes. If the next run reports a new code, send T2 again. |
| `credential`, `pairing_outcome` is `denied` | The User denied this computer. | Send **T11** and stop. Do not run setup again unless the User asks. |
| `credential`, `pairing_outcome` is `expired` | The approval was not given in time. | Run setup again (it starts a fresh one) and send T2 with the new code. |
| `credential`, `pairing_outcome` is `not_started` or absent | Approval could not be started (for example the service was unreachable). | Wait 10 seconds and run setup again; if it repeats, send **T7** with `detail`. |
| `auth`, `detail` says no access | The Account has no access to Notifai yet. Access is granted by a person, so nothing here can wait for it. | **User action.** Send **T3** with `technical.access_url` and stop. The User asks you again once access is granted. |
| `auth`, `detail` says access was requested and is waiting | The request is in. | Send **T4** and stop. |
| `auth`, anything else | The saved approval is not accepted. | Run setup again once; if it repeats, send **T7** with `detail`. |
| `server` | The Notifai service is unreachable from here. | Wait 10 seconds and run setup again; if it repeats, send **T7** with `detail`. |
| `contract` | This CLI is too old for the service. | Run `remedy.command`, then setup again. |
| `cli-bin` (`gap`) | The `notifai` on PATH cannot run or is another install. | Run `remedy.command`, then setup again. |
| `cli-bin` (`optional-gap`) | A typed `notifai` resolves to nothing. | Carry on; before step 4, fix PATH as in step 2. |
| `devices`, `technical.devices` is empty | No Companion App on any phone yet. | **User action.** Send **T5** with `technical.companion_setup_url` and `technical.account_email` (when that is `null`, write "the email you approved this computer with" instead). When the User says it is done, run setup again. |
| `devices`, `technical.devices` is not empty | The app is installed but cannot receive yet. | **User action.** Send **T6** with the first device's `display_name`. When the User says it is done, run setup again. |
| `hooks` or `hooks-*` with `remedy.user_action` | The User's agent harness must approve or trust the Notifai hook itself. | **User action.** Send **T13** with `remedy.user_action.message`. When the User says it is done, run setup again. |
| `proof` | The test notification has not been confirmed by the phone yet. | Run setup again once (it re-checks the same notification). If it is still `proof`, go to step 4. |
| anything else | | If `remedy.by` is `cli`, run `remedy.command` and setup again. Otherwise send **T7** with `detail` and `remedy.summary`. |

Non-zero exit with no JSON on stdout: stderr names the problem. Exit 2 is a
usage error in the command as typed.

Never work around a gap: do not send a notification another way, do not edit
credential or hook files, do not claim a User action was done.

## 4. Done

Pick one:

- The `proof` state is still a gap → **T9**.
- Some setup run in this conversation printed `Verification notification sent`
  on stderr → **T8** if the final JSON has `question_routing_ready: true`,
  otherwise **T12**.
- Otherwise → **T10** (everything was already in place).

## Message templates

Send exactly this text. Replace only the `{placeholders}`. Do not add commentary
before or after, and do not narrate the steps you took. Each message that asks
for something ends your turn: wait for the User's reply, then continue.

**T0 — Windows will ask for permission**

> I'm installing Node.js, which Notifai needs. Windows will show a permission dialog on your screen; click Yes.

**T1 — Node.js needed**

> Notifai needs Node.js on this computer and I couldn't install it myself. Install the LTS version from https://nodejs.org, then tell me and I'll continue.

**T2 — Approve this computer**

> Notifai needs you to approve this computer within the next 10 minutes. Open {approve_url} (it may already be open in your browser), sign in with your email if asked, check that the page shows the code **{code}**, and approve. Tell me when it's done.

**T3 — Access needed**

> Your Notifai account doesn't have access yet. Request it at {access_url}. Once it's granted, ask me to finish the Notifai setup.

**T4 — Access requested, waiting**

> Your Notifai access request is in and waiting to be granted. There's nothing to do right now; once it's granted, ask me to finish the Notifai setup.

**T5 — Install the app on your phone**

> Notifai needs its app on your phone. On the phone, open {companion_setup_url} and sign in with {account_email}; it shows how to install Notifai for your phone. Install it, sign in there with the same email, and allow notifications when it asks. Tell me when it's done.

**T6 — Allow notifications**

> Notifai on {display_name} can't show notifications yet. Open Notifai on that phone and allow notifications when it asks (or allow them for Notifai in the phone's Settings). Tell me when it's done.

**T7 — Something I can't fix**

> I couldn't finish the Notifai setup. Notifai reported: "{detail}". Suggested: "{remedy_summary}".

**T8 — Done**

> Notifai is set up. A test notification just arrived on your phone. From now on I'll notify you there when work finishes or when I need you.

**T9 — Done, waiting for the phone**

> Notifai is set up on this computer and a test notification was sent, but your phone hasn't confirmed it yet. If it doesn't arrive in a minute, open the Notifai app once and ask me to check again.

**T10 — Already set up**

> Notifai was already set up on this computer. I'll notify you on your phone when work finishes or when I need you.

**T11 — Approval denied**

> You denied the approval, so I've stopped setting up Notifai. Ask me again whenever you want to connect this computer.

**T12 — Done, notifications only**

> Notifai is set up. A test notification just arrived on your phone. From now on I'll notify you there when work finishes. Questions from me will stay here until your agent harness trusts the Notifai hook.

**T13 — Your agent harness needs your approval**

> {user_action_message}