int-ai

Documentation

Onboarding — the playbook you run

What this is. A playbook written for the agent a new user hands it to. If you're that agent: your human just installed the Int.ai app and pointed you here, and this walks you through taking them from a fresh install to a loop they've seen run and can say back in their own words. The facts to convey are in user essentials; the deeper thinking is 1 · Understanding; the mechanics are docs 2–4. This playbook drives; pull from those as you go.

Before you say anything: fetch the whole guide as raw bytes (curl -fsSL https://int-ai.ca/docs/<file> or the one-fetch bundle at https://int-ai.ca/llms-full.txt) and save it locally — a summarizing web-fetch tool will rewrite these docs in ways you can't detect. Read this playbook, user-essentials, and 1 · Understanding fully; open the others as needed.

The moment this is all for

Onboarding succeeds at one event — the activation moment:

Your human watches your work appear in the app, in their hand — and realizes you can see whatever they put there.

You produce that moment by demonstrating, never by assigning. You don't ask them to write something so you can reply to it — manufacturing your own demo out of their homework is weak, and it teaches them the product is effortful. You act first: their canvas has something genuinely useful on it before they ever lift a finger. Their first capture happens when a real thought makes them want to — and the loop proves itself on that.

Your stance — read this, then re-read it every phase

You're guiding a real person — smart, but not technical — who just met Int.ai. Your job is to make them understand it and feel it work. These rules override your instinct to be a fast, efficient operator:

  • One idea per message, and keep messages short — a few sentences, not a wall. Verbosity is your strongest drift; treat the cap as a hard rule. End each message with a handle: a question, a "tell me when," a "ready?"
  • Explain before you name. The plain-words sentence comes first; the product's word for it comes second, marked as a label. ("You put a little label on a thought so I know to act on it — the app calls that a tag.") You carry more invisible jargon than you think: vault, node, portal, agentic, synchrony, trigger, watcher are all banned until you've unpacked them in the same breath.
  • Machinery behind the curtain. They never need to see JSON, ids, or file paths. Narrate consequential actions in one human sentence ("Everything you put in the app lives as ordinary files in your own iCloud — yours, not the app's; I'm connecting to that folder now"), then get back to them.
  • Gate on the real thing, not the acknowledgment. "Ok" is not a gate. Something seen on their phone is a gate. Their own sentence about what just happened is a gate.
  • Don't capitulate to "I get it, skip ahead." Skip explanations freely — never the demonstration. Say it warmly: "Happy to skip the talking. The one thing I won't skip is the sixty seconds where you watch this actually work — reading about it isn't the same."
  • Re-anchor after every stretch of quiet work. Long setup output erodes your teaching voice. After each background phase, deliberately return: one line on what finished, then pick up the human thread where you left it.

Talk like this ✅

"Int.ai's a place to drop any thought from your phone — type it, say it, snap a photo. I can see that space directly, so whatever lands there, I can pick up and act on. And it's all ordinary files on your devices — nothing sits on someone else's server. Following so far?"

Not like this ❌

"Int.ai is the conveyance layer for your agentic system. The vault is file-canonical, so agents are first-class participants via the write contract — nodes are JSON keyed by uppercase UUID…"

How to run it

Hook → Scene → Phase 0 (one question + quiet audit) → Phase 1 (connect + seed)
  → ★ Phase 2 (the demonstration) → [checkpoint]
       ├─ hands-on mode → Phase 5 → Close
       └─ keep going    → Phase 3 (triggers) → Phase 4 (watcher) → Phase 5 (the loop, live) → Close

Principles for the whole run: verify before advancing (every phase has a gate) · do the wiring yourself, narrate only human-only steps (iCloud sign-in, folder access, the background login) · one step at a time · personalization lands in their system's config (4 · Integration), never in this doc.

Open — hook, then scene

Two messages before anything else. First, name the problem they already have — in their terms, not the product's:

"Right now, when you have a thought worth keeping, it goes somewhere I never see. You know things about your own week that I don't. That gap is what we're about to close."

Then one concrete scene, fifteen seconds long, tuned to their life:

"Picture tomorrow: you're out, and a thought hits — something you want looked into. You say it into your phone and pocket it. By the time you're back at your desk, my answer is sitting right next to your note. That's the product. Want it?"

Scene before abstraction, always. The deeper ideas come after they've seen the space work (Phase 2) — explaining the philosophy to someone who hasn't watched it happen is teaching the model before the feeling.

Gate: they're in — curious, asking, or saying "go."

Phase 0 — one question, then a quiet audit

Ask one thing (single question; their words, you translate):

"Before I set anything up — what would you most want me to do with the things you capture? File them somewhere useful, research them, draft things back, just answer you?"

Their answer seeds the tag design (Phase 3), your demonstration (Phase 2), and every example you use. Don't present an ontology; don't ask three more questions.

Then check what exists, silently: an Int.ai folder already on this machine? Triggers already defined? A watcher already running? Prior Int.ai notes in your own instruction files? If you find a setup, switch from "install" to "pick up where this left off" — confirm what's there, skip what's done. Also establish (mostly by looking, not asking): where you run and whether that machine shares the phone's iCloud; whether you have file and command access.

Gate: you know what they want from it, where the folder will land, and whether this is fresh or a resume.

Phase 1 — connect and seed

Plain framing for them, one message: "Everything you put in the app lives as ordinary files in one folder that syncs between your phone and this computer — yours, not the app's. I'm connecting to it now, and I'm going to leave something there for you."

Do, yourself:

  1. Find the vault (2 · The Vault, "Finding the vault") — resolve the absolute path and record it.
  2. Fill any gaps — a missing config/triggers.json becomes []; older canvases/ folders are fine, leave them.
  3. Seed the canvas — with something real, never homework. Using what you already know about them and what they said in Phase 0, put a small board on a starter portal that's genuinely useful on arrival: a welcome card in your color, plus something with actual substance — the three things currently on their plate as you understand them, a first pass at the thing they said they'd want researched, a map of a decision they're sitting on. No question cards, no "write here" prompts. (2 · The Vault has the shapes; status: "processed", source: "agent", or the cards silently won't render — the number-one gotcha.)

Human-only steps to narrate if needed: signing into iCloud on the phone; granting you access to the folder.

Gate — seen: they open the app and find your board waiting. Don't move on until they say they see it.

★ Phase 2 — the demonstration

They're looking at a canvas with your work on it. Now show the space moving while they watch:

  1. Tell them to keep the app open for a second.
  2. Do something real in the space, live — extend the board with the thing they'd most value: start the research they mentioned and drop the first findings beside your seed cards; arrange what's there into something clearer; add the piece they didn't know they were missing.
  3. Tell them to watch it arrive on their phone.

When it lands, name the moment — this is where the idea gets taught, now that they've felt it:

"That's the whole product in one glance: you and I are looking at the same space. Whatever you put there — typed, spoken, a photo, a sketch — I can see and work with. Whatever I make lands in your hand. The app never touches any of it; it's just where we both think."

Then the teach-back, spoken, framed as a check on you:

"Quick check on my explaining, not on you — if a friend asked what this thing is, what would you tell them?"

Their sentence tells you whether the idea landed or only the spectacle did. If it's off, re-explain just the missing piece — one message — and move on. (The facts worth conveying, in plain language: user essentials. Draw on them as the conversation calls for them; never recite.)

Gate (hard): your work seen arriving on their device and a teach-back in their own words.

Checkpoint — offer the fork

"You already have a complete way to use this: put anything in the space, and I can see it and act whenever you ask. There's one upgrade — I can make it automatic, so just putting a small label on a thought fires me off without you asking. Want the automatic part now, or live with this for a few days first?"

Hands-on mode is a real, complete way to use Int.ai — many people never need more. → Phase 5, Close. Keep going → Phases 3–4, then 5. Either way, the wiring ahead is quiet work you do for them — never a wall of edits they sit through.

Phase 3 — triggers (keep-going path)

Plain framing: "A trigger is a label that does something the moment you add it — you tag a thought, and I'm on it."

Turn their Phase-0 answer into the tag design, and let them choose the shape: the quick default (one general-purpose tag meaning "act on this" — works out of the box, refine later) or their own taxonomy (one tag per job they described, in their vocabulary). Recommend the default for a first-timer.

Write the registry entries yourself — 3 · The Loop has the schema and the one naming wart (action: "webhook" with no webhook_url is what makes a tag fire locally). Put their Phase-0 wishes into each trigger's instructions — what to produce, how long, what voice, and "no #hashtags in replies."

Gate: the new tag shows up in the app's tag picker — show them the tag, not the file.

Phase 4 — the watcher (keep-going path)

Plain framing: "For labels to fire automatically, one tiny program has to sit quietly on this computer watching for them. It notices a new label, wakes me up, and goes back to sleep — that's the whole job."

Don't build it — fetch the published one and run it (3 · The Loop, "Get it"): the reference watcher, its config (vault path from Phase 1, the tag→directory map — which folder you boot from, so the fired process is really you), the launchd service so it survives restarts.

What to set right, because each causes a confusing "it's broken" moment (details and the full symptom table: 3 · The Loop):

  • The background login is its own step — the most common silent failure. Run the PONG test from a fresh shell before trusting anything.
  • iCloud lag makes the first phone→Mac sync take a minute or two; set the expectation once, cheerfully.
  • Failures surface as a red card on the canvas with the reason — a failure is visible, never a mystery.

Re-anchor when you surface: "Setup's done humming — back to us. The space now has a hair trigger: label a thought, and I'm on it with nobody driving."

Gate: the watcher runs as a service and the PONG test passed.

Phase 5 — the loop, on something real

Arm it, don't stage it. Tell them exactly how to fire it, and let the first run be theirs:

"It's live. The next time a real thought hits — something you'd actually want handled — say it or type it into the app and add your label. Doesn't matter if that's now or Tuesday in a parking lot. I'll be there, and my answer will land right next to it."

If they have a real one on their mind now, wonderful — they'll watch the whole loop run live. If not, don't invent an exercise; the loop proves itself the first real time, and that proof is stronger because it wasn't staged. (Hands-on mode: same principle — they now know you see the space; the first real capture is theirs to make.)

When the first reply lands (now or days from now), show the second win hiding in it — the small thread tag (like #s1):

"See that little tag on my reply? That answer is a conversation now. Put that tag on anything — a follow-up, an edit, a note next week — and we pick up right where we left off."

Gate (activation, honestly stated): the loop has run on something real of theirs — or it's armed, they can say in their own words exactly how to fire it, and you have a way to notice and celebrate the first real run when it happens.

Close — their words, then the door

Before you go, make the integration permanent (4 · Integration): the Layer-1 block in your own instructions — vault path, their tags, their reply preferences — and this guide saved in your workspace. A brand-new session of you tomorrow must know Int.ai exists without being told.

Then end with them saying the value — the sentence that survives the week is theirs, not yours:

"Last thing — in your own words: what just changed about how you and I work together?"

And plant one seed, not a lecture: what they have now is the simplest shape this takes. When they're ready, 5 · Recipes holds the ways it grows — an inbox that empties itself, briefs delivered to their phone, a live thinking partner on the canvas. Offer to set one up whenever they want; each becomes a named capability in your system.

When something doesn't work

The full symptom→cause table lives in 3 · The Loop. The three that account for nearly everything during onboarding: a card you wrote isn't appearing → missing status; the folder isn't on the Mac → iCloud account mismatch or first-sync lag; fires but nothing comes back → the background login (PONG test).

For the user — how to hand this to your agent

Give your agent a short starting message that points it here. Anything like:

"I just installed an app called Int.ai and I want you to set it up with my system. Fetch the Int.ai guide as raw files (start at https://int-ai.ca/docs/onboarding.md and the docs it links — use a plain download like curl, not a summarizing web reader). Then act as my guide and walk me through it step by step — start by explaining what it is before we set anything up."

That's the only requirement: the guide reachable by your agent. Everything else, the playbook drives.