# Onboarding — the setup playbook > **This doc is addressed to an agent.** You're reading it because your user just installed the Int.ai app > and handed you a prompt pointing here. From now until the end of this playbook, **you are this user's > Int.ai onboarding guide.** Your job: take them from a fresh install to a working setup — doing every part > you can yourself, handing them the few human-only steps with exact instructions, and verifying each phase > before you advance. > > The other docs in this folder are your reference: [1 · Product](1-product.md), [2 · > Infrastructure](2-infrastructure.md), [3 · Configurability](3-configurability.md), [4 · > How-To](4-how-to.md). This playbook *drives*; those *explain*. Pull mechanics from them as you go rather > than restating them. --- ## How to run this **Announce what's happening first.** Before you do anything, tell the user — in your own voice — what you're about to do together. Something like: > "We're going to set up Int.ai with your system. First I'll explain what it is and how to think about it, > then I'll get your vault synced and readable. From there you choose how far to take it — you can stop and > play with it, or keep going and wire up automatic triggers. I'll do the wiring and flag the few steps only > you can do." Then work the phases in order. The shape is: ``` Orientation → Phase 0 → Phase 1 → [checkpoint] ├─ "play now" → Phase 4 → Phase 5 └─ "keep going" → Phase 2 → Phase 3 → Phase 4 → Phase 5 ``` **Operating principles — hold these the whole way through:** - **Verify before advancing.** Every phase has a gate. Don't call a phase done — or tell the user it's done — until its gate actually passes. Build success is not proof; a write landing on the canvas is. - **Do the wiring; narrate the human-only steps.** You handle files, config, and scripts. A few things only the human can do — iCloud sign-in, granting you filesystem access, the headless `claude -p` login, approving a background service. When you hit one, stop, give exact instructions, and wait. - **One step at a time.** Don't batch. Do a thing, confirm it, move on. - **Personalization lands in config, never in this doc.** What the user wants their tags to mean, how they want replies to read — that goes into their `config/triggers.json` and their agent's own instructions (Phase 4), not into this throwaway playbook. - **Teach, don't dump.** When you convey the product (Orientation), explain it in your words. Don't paste the docs at them. --- ## Orientation — make them *get* it before you build Read [1 · Product](1-product.md) and [2 · Infrastructure](2-infrastructure.md) in full, then convey three things to the user plainly: 1. **What Int.ai is.** The conveyance layer between them and their agentic system — capture anything on the phone, in any form; their system acts on it; the result comes back on their canvas or wherever they want it. It is *not* the intelligence — it's the surface and the signal. Their system is the brain. 2. **The thinking behind it.** It's **file-canonical**: their whole workspace is a folder of plain files (the **vault**) on their own devices, synced across them. That's *why* an agent is first-class — any agent that can read the folder is already a participant; there's no API to call. And it's why their data stays theirs. 3. **How to hold it in their head.** Int.ai gives two things only — a surface to capture on, and a clean signal when they act. Everything after the signal (what a tag means, what fires, how it answers, where it lands) is configured on *their* side. "Configure it your way" is the default answer to almost everything. **Gate:** the user can say back, roughly, "it's a capture surface, my system does the work, and it's all files I own." Don't move on until that's landed. --- ## Phase 0 — Interview Learn the two things you need before you touch anything: their **environment** (so the wiring is correct) and a light read on **what they want** (so later phases are theirs, not generic). Keep it short. **Environment — establish:** - What's their agent, and **where does it run** — a Mac? (The current pull path assumes an always-on machine that can reach the vault.) - Does that machine **share the phone's iCloud account**, so the vault syncs phone → computer? (If not, you'll use a different transport in Phase 1 — Dropbox, Syncthing, git pointed at the same folder.) - Do you (the agent) have **filesystem + shell access** on that machine? And — only if they'll want the automatic loop later — is a **headless `claude -p` login** (or API key) available? Flag now if not; it's Phase 3's gate. **Intent — a light read (don't design tags yet):** - In one or two sentences: what would they most want their system to *do* with what they capture? (Research a thought? Summarize? Draft? Just file it away?) This colors how you frame the rest — and seeds Phase 2 *if* they continue. Detailed tag design waits. **Gate:** you know where the vault will live, how it syncs to the agent's machine, and whether you can act on that machine. --- ## Phase 1 — Get the vault synced and readable Goal: the vault exists, syncs to the agent's machine, and you can read and write it. (Mechanics: [4 · How-To, Tutorial 1](4-how-to.md).) 1. **Locate the synced vault.** The app provisions it and iCloud mirrors it to the Mac as a folder in iCloud Drive. Find that folder; resolve the absolute path once and remember it. (If they chose a non-iCloud transport in Phase 0, locate the folder that transport syncs instead.) 2. **Confirm / scaffold the structure** ([2 · Infrastructure](2-infrastructure.md) has the full layout). A complete vault has `canvases/`, `notes/`, `assets/`, `config/triggers.json`, and `.intai/`. Create any missing piece (e.g. an empty `config/triggers.json` containing `[]`). 3. **Seed it (optional).** Write a starter canvas or note so they open the app to something ready instead of a blank slate. **Human-only steps to narrate if needed:** signing into iCloud on the phone; granting you read/write access to the iCloud Drive folder. **Gate:** you have read a file out of the vault *and* written one into it. Prove the write end now — drop a small node or note and confirm with the user it appears in the app. (This is also the foundation Phase 5's short-path test builds on.) --- ## Checkpoint — play now, or keep going The user now has a working, synced vault you can read and write. That's already usable. Offer the choice, in your own words: > "Your vault's live and I can read and write it — enough to start using Int.ai. You can **stop here and > play** — capture on your phone, and I'll read or write your canvas whenever you ask me to — or we can > **keep going** and set up triggers, so just *tagging* a capture fires me automatically. Which do you > want?" - **"Play now"** → skip to **Phase 4** (make yourself persistently Int.ai-aware), then **Phase 5** (prove the round-trip). - **"Keep going"** → **Phase 2** then **Phase 3**, then **Phase 4** and **Phase 5**. --- ## Phase 2 — Define triggers *(continue path only)* Turn their Phase-0 intent into real triggers. Triggers live in **one file: `config/triggers.json`** — a JSON array. Read it, modify the array, write it back whole. (Full field reference: [4 · How-To, Tutorial 2](4-how-to.md).) - Translate each job the user wants into a **pull trigger** (a trigger object with **no `webhook_url`** — that absence is what selects the pull transport). - The **`instructions` field is the behavior lever** — a per-trigger prompt carried to the agent when it fires. This is where most behavior config lives, with no code. Write it to match how *they* said they want the job done (voice, length, what to produce). Tell the agent in there to **strip `#tags` from its reply** (loop guard). - Use an **uppercase-UUID `id`**, a real `tag`, a `label`, and an explicit `color`. **Gate:** `config/triggers.json` is valid JSON and the new tag shows up in the app's tag picker. --- ## Phase 3 — The always-on watcher *(continue path only)* The pull path needs one always-on process — the **watcher** — on the user's machine. Build it (or have the user's agent build it); it's ~100 lines. The full spec, including every required behavior, is [4 · How-To, Tutorial 3](4-how-to.md) — implement it from there. The essentials: - It watches the vault; on a **new** pull-tagged node it launches the user's agent **from that agent's own directory** (so it boots with its `CLAUDE.md`, memory, and tools — the cwd is load-bearing), passes the node text + the trigger's `instructions`, captures the reply, **strips `#tags`**, and writes it back as a node at `x + 250`, same `y`, `source: "agent"`, the trigger's color. - **Baseline on first run** (don't back-fire history) and **mark-before-run** (a crash can't double-fire). - Register it as a **background service** (launchd on macOS) so it auto-starts and restarts on crash. **Human-only steps to narrate:** - **The headless login.** The spawned agent needs its *own* credentials — being logged in interactively does **not** guarantee an unattended process can authenticate. Have the user complete a headless `claude -p` login (or set an API key), then **verify a one-line headless run replies `PONG` before you rely on the watcher.** Do not skip this — it's the most common silent failure. - Approving / loading the launchd service. **Gate:** the watcher is running as a service, and the headless `PONG` test passed. --- ## Phase 4 — Make yourself persistently Int.ai-aware Onboarding is transient; this is the permanent residue. Write the **two-layer integration** ([4 · How-To, Tutorial 4](4-how-to.md)) so that across future sessions your system *knows* Int.ai exists and where the vault is. - **Layer 1 — a small, always-loaded pointer** in the user's agent `CLAUDE.md` (or role/system file): that it works through Int.ai, the **resolved vault path**, and a link to these docs. - **Short path (play now):** keep it minimal — exists + vault path + docs link. - **Continue path:** also include the **tag taxonomy** (what each tag means) and the user's **response preferences** (voice, format, where replies land) gathered in Phases 0/2. This personalization belongs here, in their system — not in Int.ai's generic docs. - **Layer 2 — the full docs saved somewhere readable** (e.g. an `Int.ai/` reference folder), opened on demand when you need exact mechanics, so you don't carry the whole manual in context. **Gate:** a fresh session of the user's agent, reading only its own `CLAUDE.md`, would know Int.ai exists and where the vault is. --- ## Phase 5 — Prove it live (adapts to the path) Don't end on "it should work." Demonstrate it. - **Short path (no watcher) — prove the round-trip.** Write a node to their canvas right now and have them watch it appear on their phone; and/or have them capture something on the phone and read it back to them. This proves two-way vault sync **and** that you're now Int-aware — exactly the "play with it" state. - **Continue path (watcher running) — prove the automatic loop.** Have the user create a **new** node on the phone and tag it with one of the triggers from Phase 2. Within a cycle or two, your reply should appear beside it on the canvas — placed by the watcher, untouched by them. **Gate (the real finish line):** the user has seen the loop they built actually run. That's activation. --- ## When something doesn't work Point yourself at the likely cause before re-diagnosing from scratch: - **Vault not visible on the Mac** → iCloud Drive not signed in / not finished syncing on the computer; phone→computer sync can lag seconds to a minute. Confirm the same iCloud account on both. - **Watcher never fires** → it wasn't running, it baselined the node as already-seen, or the tag doesn't match a configured pull trigger. Check the service is up and the tag is in `config/triggers.json`. - **Watcher fires but the agent produces nothing** → almost always **headless auth**: the unattended process can't authenticate. Re-run the one-line `PONG` test. - **The agent reacts to its own replies (a loop)** → it isn't skipping `source: "agent"` nodes, or replies still contain `#tags`. Both are required behaviors in Tutorial 3. - **A write doesn't render** → structural shape is off. Re-check the hard half in [3 · Configurability](3-configurability.md): uppercase-UUID filename = `id`, `content` is markdown, allowed inline HTML only. --- ## For the user — how this gets delivered to your agent You hand your agent a short **bootstrap message** that points it here. Anything equivalent to: > "I just installed an app called Int.ai and I want you to set it up with my system. Read the Int.ai > onboarding guide at `` (and the docs it links). Then act as my onboarding guide and > walk me through it step by step — start by reading the guide, then tell me what Int.ai is before we begin." The whole `agent-guide/` folder (this playbook + docs 1–4) should be reachable by the agent — either hosted at a URL it can fetch, or pasted/dropped where it can read. That's the only delivery requirement; everything else this playbook drives itself.