# Int.ai — full documentation bundle # Source: https://int-ai.ca Generated: 2026-06-29T14:07:49.585Z # # This file concatenates the entire Int.ai agent guide. Each doc is delimited by a # "===== FILE: =====" marker. To bring these into your system, write each section # to its own file (keep the file names) under a folder like ./int-ai/, then read # onboarding.md and act as the user's Int.ai onboarding guide. ===== FILE: README.md ===== # Int.ai — Docs Read in order — they build on each other. The first job is to give you two things: 1. **The product thinking** — what Int.ai is, and why it's shaped the way it is. 2. **The infrastructure** — what Int.ai actually delivers, and how it works. Get those two, and the third doc is the payoff that follows on its own: **you can configure Int.ai into whatever you want.** That freedom is the entire point of the product — so these docs are built to make you *see* it, not just list features. Doc 4 then turns that understanding into a working setup. (Doc 5, a real worked example, is deferred until the live flow is tested.) | # | Doc | What it gives you | | --- | --------------------------------------- | -------------------------------------------------------------------------------------------------- | | 1 | [Product](1-product.md) | What Int.ai is, the vision, and the principles — why it exists and what it's for | | 2 | [Infrastructure](2-infrastructure.md) | What's built: the surfaces, the file-canonical vault, and how it all behaves | | 3 | [Configurability](3-configurability.md) | How you interact with it — the hard half you must follow, and the soft half that's entirely yours | | 4 | [How-To / Setup](4-how-to.md) | Step-by-step: sync the vault, define a trigger, run the watcher, integrate Int.ai into your system | **Setting up for the first time?** [**Onboarding — the setup playbook**](onboarding.md) is the interactive entry point: a new user hands their agent a short prompt pointing at it, and it *drives* the agent through the whole setup (consulting docs 1–4 for mechanics), from fresh install to a proven live loop. Docs 1–4 explain; the playbook acts. **Who this is for:** an agent (or a person) meeting Int.ai for the first time. No prior knowledge assumed — this builds the whole picture from zero. ===== FILE: onboarding.md ===== # 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. ===== FILE: 1-product.md ===== # 1 · Product > What Int.ai is, what it's for, and the principles behind it. Read this first — everything you can *do* > with Int.ai follows from *why* it is the way it is. --- ## What it is Int.ai is the **conveyance layer between you and your agentic system** — the one intuitive product for getting what's in your head into your agent, in whatever form it arrives, so it actually gets acted on. It's an **extension of you** *and* an **extension of your system** — and by being both, it bridges the two. An extension of *you*: your thinking and action flow out intuitively, expression easy and boundless, in whatever form it takes. An extension of *your system*: it's as open and configurable as possible, so your system can act through it — do anything, in any configuration you want — and interact with it in every way that's possible. It earns that bridge by being radically **intuitive, accommodating, and easy to use** at both ends at once: it captures everything, in every modality, and makes it **bend to whatever your system wants to do with it.** That is the whole goal — to *be* the layer between you and your system, frictionless in both directions. It's both a **capture layer** (express anything, the moment it occurs) and an **interaction layer** (trigger and talk to your system from the same surface). Your agentic system can only be an extension of you if it stays *in sync* with you — Int.ai is the bridge that keeps it in sync: an intuitive, multimodal feed of your thoughts and your life into your system, where everything can be stored, understood, and acted on. Both ends of that bridge are yours to shape — capture in any form, interaction in any way. **Max configurability is the constant.** Int.ai is not just an inbox you pour into. It provides the surface and the interface; **how you interact with it is entirely up to you.** It doesn't have to be capture-*for*-you at all. It can be a **brainstorming space**; a place your system **sends you things to read and react to** while you're on the go; a **collaborative canvas** where you and your AI bounce ideas and think visually together — any direction you want. Our mission is simply to **enable the interaction between you and your agentic system**, in whatever shape that interaction takes for you. It is deliberately **not the intelligence.** Int.ai provides the *capability* — the surface, the primitives, the tag/trigger. Your system supplies all the *behavior* — what a capture means, where it goes, what fires, what comes back. All the thinking, routing, memory, and action is your system's. Nothing is decided inside Int.ai; everything flows through. It hands your system the wheel and stays out of the way. ## How it works — the dual-channel model Int.ai runs both ways on the same surface: - **You → your system (capture).** Speak, photograph, draw, scan, write — express anything, in the form it arrives, the moment it occurs, before it fades. Capture is the fuel. - **Your system → you (action & return).** Your agent ingests, processes, and acts on whatever comes in — however you've set it up or prompted it to. And it reaches *back* to you in whatever way you've configured — through Int.ai itself, another channel, or not at all: writing reports where you're working so you have them on the go, flagging things that need your input, posting visuals and results. The agent is a first-class actor — everything you can do in the app, and more — plus it can push to your phone. A genuine two-way channel, not a one-way inbox. ## Configurable on both sides Configurability is the whole point — the bridge bends to *you* at both ends, and you should always assume maximum configurability: - **Configure the capture.** Express and capture in whatever form and mode fits you — voice, image, sketch, text, scan — and shape the surface to how *you* think. The capture side is an extension of you, so it has to fit you, not the other way around. - **Configure the interaction.** Your agent can interact with what you capture in any way you want — what it watches, what it acts on, what it sends back, where and how it surfaces. You wire the behavior; Int.ai imposes none of it. Configurability also covers *how you engage Int itself* — the mode of interaction is yours to shape, not just what the agent does. Nothing here is fixed or pre-decided. That's what makes Int.ai intuitive and accessible for *you* and fully manipulable for your *agent* — one surface, shaped to fit both. ## The problems it solves - **Thinking leaks at both ends.** *Before capture* — no surface holds the form a thought arrives in (voice, image, sketch, text), so it's gone before you catch it. *After capture* — it rots; nothing acts on it. Thought is valuable, and today most of it goes to waste. - **You and your agent fall out of sync.** Your system can only be an extension of you if it's continuously fed your thinking. Today there's no clean channel in either direction. - **Interacting with an agentic system is technical and confusing.** Non-technical people have no intuitive front door. Assembling a notes app + plugins + protocol glue by hand is exactly the tangle Int.ai removes. - **Multimodal capture isn't legible to the agent.** Drawn, handwritten, and spoken input lands as opaque blobs. Int.ai's job is capture the agent can actually *read and act on.* ## What it is not - **Not the intelligence, not the router.** All thinking, handling, and routing is your system's. - **Not a thousand-feature suite.** One purpose, done beautifully. The product *is* the channel. ## Vision The bottleneck in the agentic era is **not capability — it's expression.** Models can already do more than people can comfortably ask of them. The unsolved problem is the **interaction layer**: getting what's in your head into your system, on the go, without breaking flow. Int.ai is the bet on that problem. **What it looks like to use it.** It's multi-platform and in sync across every device. A thought hits — and you put it wherever you are: type it on your laptop, speak it into your phone on the go, scan or photograph the thing in front of you. Or you sit down with a canvas open to do real thinking — your system loads your ideas in as nodes; you pull them together, try different configurations, and your agent works right there alongside you, on standby, giving feedback and editing as you go. One surface that bends to whatever mode you're in, everywhere you are — capture on the run, think deeply when you sit down, your system always with you in it. **Fuel for the second brain, sovereignly.** As agentic systems get more powerful, the compounding **model of you** becomes the advantage. So capture and store as much of your thinking as possible — even the small things — so your system has real context on you. Int.ai is the capture that feeds it, and it keeps that data in your hands. ## Principles 1. **Pure bridge layer — never the intelligence.** Int.ai provides capability, not behavior. 2. **Maximum agent agency, minimum prescription.** The agent has full capability; you (via your system) define the workflow. Int.ai prescribes almost nothing. 3. **Maximum configurability — ambiguity by design.** The default answer is "configure it your way." Both ends bend to you: the capture in any form, the agent's interaction in any way. Built for ambiguous operation with ambiguous systems — nothing is pinned to a single meaning. It's whatever you want it to be. 4. **Agent-first architecture.** Designed around how AI models and agentic systems actually operate — full agent access, the agent can also push back, agent-best-fit. This is an **agent-first product**: the agent can do *everything* the user can do — at minimum the same surfaces and the same actions — and then **more** (it works the files directly, can operate in bulk, and can reach back to you). The user's capabilities are the **floor** for the agent, never the ceiling. 5. **Data sovereignty.** The model of you is yours; capture and store as much as possible, kept in your hands. Not aspirational — the data layer is file-canonical on your own devices (see [2 · Infrastructure](2-infrastructure.md)). > The thread through all of it: **Int.ai gives you a surface and a signal; your system decides everything > that follows.** Hold that, and [3 · Configurability](3-configurability.md) is just the mechanics of > making it yours. ===== FILE: 2-infrastructure.md ===== # 2 · Infrastructure > What Int.ai actually is under the hood — what's built, the surfaces you act on, and how the whole thing > behaves. Once you understand the substrate, you understand exactly what you're able to do with it. --- ## The one idea to hold: it's all files Int.ai is **file-canonical.** A user's entire workspace — every canvas, note, image, and setting — is a folder of plain files on their own devices, called the **vault.** - **The vault is the source of truth.** The app doesn't ask a server for a canvas; it reads the files. Nothing important lives in a database you can't reach. - **It syncs across devices.** The same vault appears on the phone, the laptop, the tablet — kept in sync automatically (over iCloud today; the transport is swappable — see below). - **This is why an agent is first-class.** Because the workspace is just files, *any agent that can read the folder is already a participant.* No SDK to install, no API you must call, no permission beyond "can read this directory." Your agent reads and writes the vault with ordinary file tools — read, write, edit, search. **That is the whole integration.** Everything below is detail on what those files are. ## The surfaces Int.ai gives the user two surfaces to capture and think on, the media they attach, and the tags that make any of it actionable. ### Canvas — the spatial surface An infinite 2D whiteboard. The user drops text, photos, voice, and scans anywhere on it. Thought-in- progress is spatial before it's linear, so the primary surface is spatial. - A canvas is a set of **nodes** (each a card — text or media, with a position, size, and color) plus **edges** (connections between nodes). - A workspace has many canvases. ### Notes — markdown documents A note is, quite literally, a **markdown (`.md`) file** — that's all a note *is* on disk. It's the **linear** surface (prose and lists rather than a spatial field), the counterpart to the canvas. Bidirectional by design: the user writes, the agent writes back — briefs, research, summaries — and the user annotates inline. - A note's body is markdown: headings, lists, checklists, tables, links, images, highlights. ### Media — what you attach Photos, voice recordings, scans, files. Stored as **real files inside the vault**, referenced by relative path — never a web URL. That's why media loads instantly and stays private: it never becomes a public link. ### Tags & triggers — what makes capture actionable Two terms the rest of these docs use precisely: - A **tag** is any label you attach to a capture (e.g. `#research`, `#idea`, `#urgent`) that carries *meaning to your system*. The tag is the general primitive. - A **trigger** is a **tag wired to fire an immediate action** the moment it appears — a *proactive* tag. Every trigger is a tag; **not every tag is a trigger.** A tag that isn't a trigger is still useful: it's a **passive signal** your system reads on its own schedule — when it next processes your captures, or when you invoke it — to decide what to do with that item. Int.ai ships the *primitive* (the tag, and the option to make a tag fire); **you** define what any tag means and does. (That's the whole of [3 · Configurability](3-configurability.md) — here, just know tags exist, and they're configuration, not code.) ## What you can do in Int.ai (and so can your agent) Everything the app offers is available to **both** the user (through the UI) and the agent (by working the vault files directly). The core actions: **Capture & canvas** - Create nodes by **text**, **voice** (recorded and transcribed on-device), **photo**, **camera**, **scan**, or **file**. - **Move, resize, recolor,** and edit the rich text of nodes; delete them. - **Connect** nodes with edges to show relationships; pan and zoom the space; keep many separate **canvases**. **Notes** - **Create and edit** notes (rich text, stored as markdown); the first line becomes the title. - Organize with **categories**; **hide** notes or canvases you don't want surfaced. - Embed media **inline** in the note body. **Move between surfaces** - **Import a note onto a canvas** (it lands as a node) and **send canvas content into a note** — the two surfaces interchange. **Tag & act** - Apply **tags** to nodes and notes, and configure what each tag means — whether it's a **trigger** (fires now) or a **passive signal** (read later). **The agent's "and more"** - Because the agent acts by reading and writing files, it isn't bounded by the on-screen UI: it can work in **bulk**, generate whole canvases or notes at once, and **reach back to you** (e.g. push a notification to your phone). The user's capabilities are the floor, not the ceiling — see [1 · Product](1-product.md). ## The data model (the vault layout) The shape of the folder, so you know exactly what to read and write: ``` vault/ ├── canvases// │ ├── canvas.json # manifest: name, viewport, hidden │ ├── nodes/.json # ONE node per file │ └── edges/.json # one connection per file ├── notes/.md # YAML frontmatter + markdown body ├── assets/. # media, referenced by relative path ├── config/ │ └── triggers.json # your tags & triggers (a list) └── .intai/ # vault metadata + the agent contract ``` - **One node = one file.** Deliberate and load-bearing (see *How it behaves*). - **Text is markdown everywhere** — node `content` and note bodies alike (GitHub-Flavored Markdown + `==highlight==`, plus a tiny fixed set of inline HTML for color/underline). - **The id is the filename.** IDs are uppercase UUIDs; a file's name *is* its id. - The exact field-by-field shape of each file — and the rules for writing one — is in [3 · Configurability → the hard half](3-configurability.md). ## How it behaves A few behaviors matter for any agent working the vault: - **Per-file = collision-free.** Because each node and edge is its own file, you can edit one node while the user edits another — different files, no clash. This is the structural fix for the classic "two writers, one big file, last save wins and the rest is lost" problem. - **Repaired on read, never rejected.** When the app loads the vault it normalizes structure — fixes malformed JSON, defaults missing fields, clamps out-of-range values, drops broken connections, strips disallowed markup. So a structurally-imperfect write won't corrupt anything. **But** this catches only *structural* problems; it will not fix bad judgment (a summary dropped into the title field, a reply on the wrong canvas). Get the meaning right yourself. - **Sync is pluggable.** iCloud is the default transport, but because the vault is plain files it can ride Dropbox, Syncthing, git, or a hosted relay instead — a swap, not a rewrite. The user chooses. - **Conflicts resolve last-write-wins** per node/block today (true multi-writer merge is a later upgrade). In practice, per-file granularity makes real conflicts rare. ## What this means for you You don't "integrate with an API." You **work a folder.** Reading the workspace is reading files; replying on a canvas is writing a file; attaching an image is dropping a file in `assets/` and pointing at it. The next doc is how to do that correctly — and then how to make all of it behave however you want. ===== FILE: 3-configurability.md ===== # 3 · Configurability > You understand the product (a configurable bridge) and the infrastructure (a folder of files you read and > write). This is where it pays off: **how you interact with Int.ai — and how completely that interaction > is yours to shape.** There are two halves to interacting with Int.ai. The **hard half** is the small set of rules you must follow for the app to read what you write. The **soft half** is everything else — and "everything else" is deliberately enormous, because ambiguity and configurability *are* the product. --- ## The hard half — write it this way, or it won't render To put something on a surface, write the right file in the right shape. This is the only non-negotiable part. (The layout is in [2 · Infrastructure](2-infrastructure.md); these are the rules for *writing*.) **To add to a canvas** — write a new node file at `canvases//nodes/.json`: ```json { "id": "", "type": "text", "position": { "x": 450, "y": 300 }, "width": 200, "height": 80, "content": "Your markdown here", "color": "#3B82F6", "source": "agent", "timestamp": "" } ``` - **The filename must equal the `id`,** and ids are **uppercase UUIDs.** - **`content` is markdown** (GFM + `==highlight==`; for color/underline, only `` and `` are allowed — anything else is stripped on read). - **Mark your writes `"source": "agent"`** so the app, the user, and the trigger system can tell your writes from the user's. - **Set `color` explicitly** — don't lean on a default; pick the color that carries your meaning. - **To reply *next to* something,** place your node a little to the right of the original (e.g. its `x` + ~250, same `y`) so it reads as an answer, not an overlap. **To add a note** — write `notes/.md`: YAML frontmatter (`note_id`, `title`, timestamps) + a markdown body. **To attach media** — put the file in `assets/` and reference it by relative path (`![](../assets/)`), never a URL. That's the hard half in full. Everything from here is yours to decide. --- ## The soft half — you wire it however you want Int.ai imposes almost no behavior. It hands your system a surface and a signal; *you* decide what everything means and what happens next. Below are the dimensions you control. Assume maximum configurability — if you're wondering "can I make it work like X?", the answer is almost always yes, on your side. ### Tags & triggers: a primitive you wire any way you like A **tag** is just a label you put on a capture; a **trigger** is a tag you've wired to fire an action the moment it appears (the distinction is defined in [2 · Infrastructure](2-infrastructure.md)). Int.ai deliberately does *not* decide what any tag means. `#research`, `#todo`, `#draft`, `#urgent` — these mean whatever *you* wire them to mean. The tag is the primitive; the behavior is yours. A trigger doesn't dictate *how* the signal reaches your system. There are two directions, and you pick: - **Push** — the instant you tag something, Int.ai reaches out to your system (a call to an endpoint you run). Immediate, but your system needs an address reachable from the internet. - **Pull** — your system watches the vault and notices the new tag itself. No public address needed; runs entirely on your own machine. > **The one rule underneath both:** something on your side has to *already be running* to catch the signal — > nothing can wake a program that's off. So every setup has one small always-on piece: a cheap watcher that > notices the event and *launches* your real agent, which does the work and exits. The heavy agent runs > per-task; only the tiny watcher stays up, so nothing constantly burns compute. **The path Int.ai currently uses is pull**, and it's worth understanding because it needs zero public infrastructure: a lightweight always-on process on your computer watches the synced vault, and when a node or note gains a tag you care about, it launches your agent — pointed at the captured item — which reads it, acts, and writes its reply back into the vault as a new node. The reply syncs to your phone like anything else. Push is equally supported by the model when you want instant, away-from-your-computer firing; it just asks you to run a reachable endpoint (and to secure it — require a secret, reject anything without it). This is intentionally light on plumbing, because the point isn't the plumbing — it's that **the wiring is yours.** Push or pull, on your laptop or a server, one tag or fifty: Int.ai doesn't care. It fires a clean signal; where it goes and what catches it is your call. **And a tag doesn't have to fire anything at all.** Not every tag is a trigger. A tag can simply be a *signal* — meaning you attach now that your system reads later: when it next processes your captures on its own schedule, or when you explicitly invoke it. Defining which tags exist, and what each one means (fire-now vs. read-later), is entirely your side of the system. A few illustrative shapes — you define your own: - `#urgent` → a **trigger**: fires the instant you add it; your agent acts immediately. - `#read-later` → a **passive signal**: nothing fires now; next time your system sweeps the vault it knows to summarize that item and queue it for you. - `#idea` → a **marker**: no action between captures, but your system uses it to cluster and resurface related thoughts when you sit down to think. *(Fuller, real-world examples may get their own page — see the open question we're sorting out on doc structure.)* ### How your system responds is entirely yours This is the heart of it. **You dictate what your agent does with what you capture, and how it comes back.** Int.ai carries the thought and the signal; the entire response is configured on *your* side: - **The behavior.** Should a tag make your agent research, summarize, critique, expand your half-formed thought, file it away, draft something, or kick off a multi-step job? You decide, per tag. The same capture can mean "think hard about this" or "just save it," depending on how you wired the tag. - **The voice and form.** Want every reply as a long essay? Terse bullet points? The conclusion in bold? A specific tone, a house style, a fixed format? That's yours to set — it lives in your agent's prompt and configuration, not in anything Int.ai imposes. If you want it to always answer a certain way, make it so. - **The return path.** Where does the answer land — a new node beside the original, a fresh note, a push notification to your phone, a message in another channel, or nowhere visible at all (a silent file-away)? Your choice. - **What Int.ai *is* for you.** Because nothing is pinned down, the product itself becomes whatever you make it: a thinking partner that critiques as you go, a capture inbox your system quietly processes overnight, a command surface that kicks off real work, a journal that feeds your second brain. Same app, completely different products — decided entirely by how you configure it. **You make the rules.** ### The other dimensions you control Rounding out the surface, so you see how far "configurable" really goes: - **Your tag taxonomy.** Which tags exist and what each one means — and which of them are *triggers* that fire immediately versus *passive signals* read later. Your whole vocabulary of intent. - **Agent topology and routing.** One agent that handles everything, or many specialized ones. Route by sending different tags to different agents, or send everything to a single "router" agent that reads the item and decides who handles it. Int.ai prescribes no topology. - **Where your agent runs.** Your own machine (simplest, most private, and what the current pull path assumes), an always-on server you control, or a cloud function — a spectrum from "fully my own system" to "always-on but generic." Pick based on whether you need responses while your machine is off. - **The sync transport.** Since the vault is plain files, you choose how it syncs — iCloud, Dropbox, Syncthing, git, a hosted relay. The substrate doesn't change; only the pipe does. - **What each surface means.** A canvas can be a project, a mood board, a daily log, a brainstorm; a note can be a brief, a journal, a spec. Int.ai gives blank surfaces; you assign the meaning. - **Visual conventions.** Colors, placement, and structure are yours to make meaningful — e.g. one color that always signals "agent-generated," another that signals "needs my review." You set the language. - **Statefulness.** A tag can fire a one-shot reply, or your system can carry context across turns and make the surface feel like an ongoing conversation. Whether interaction is stateless or session-like is decided on your side. - **The capture side, too.** Configurability runs both ways (see [1 · Product](1-product.md)): how you capture — voice, image, sketch, text, scan — and how you shape the surface to fit the way you think, is as much yours as the agent's behavior. --- ## The throughline Int.ai gives you two things and only two things: **a surface to capture on, and a clean signal when you act.** Everything after the signal — what it means, what runs, how it answers, where it lands, what the whole product even *is* for you — is configured on your side. Understand the product and the infrastructure, and that's the realization these docs exist to produce: **you can shape this into exactly the system you want.** ===== FILE: 4-how-to.md ===== # 4 · How-To / Setup > [3 · Configurability](3-configurability.md) is *what* you can configure. This is *how* to actually stand > it up — concrete tutorials. The recommended path throughout is **pull** (an always-on watcher on your own > machine); it needs no public infrastructure. Examples are generic — swap in your own tags, agents, and > paths. **The shape of a working setup, in four moves** (one tutorial each below): 1. A **synced vault** your agent can reach. 2. A **trigger** defined (a tag bound to an action) in `config/triggers.json`. 3. The **always-on watcher** running — the one piece that catches a tag and launches your agent. 4. Your **agent integrated** into your system so it knows to use Int.ai and how. --- ## Tutorial 1 — Get the vault synced across your devices The **app provisions the vault and the sync.** You (one-time): install the Int.ai app, sign in to iCloud (the default transport). The app creates the vault on your phone and iCloud mirrors it to your Mac — it shows up as a folder in iCloud Drive. Nothing to build; this is what makes "capture on the phone, act on the Mac" work. **Your agent's job is the rest — so you don't hand-edit files:** 1. **Locate the synced vault** on your computer (the iCloud Drive folder the app created). Resolve it once and remember the path. 2. **Confirm / scaffold the structure** (see [2 · Infrastructure](2-infrastructure.md) for the full layout). A complete vault has: ``` vault/ ├── canvases//{canvas.json, nodes/, edges/} ├── notes/ ├── assets/ ├── config/triggers.json └── .intai/ ``` If a piece is missing, your agent can create it (e.g. an empty `config/triggers.json` containing `[]`). 3. **Seed it (optional).** Your agent can create a starter canvas or note so you open the app to something ready, instead of a blank slate. > **Transport is your choice.** iCloud is the default, but the vault is just files — point Dropbox, > Syncthing, git, or any sync at the same folder and it works identically. Cross-platform (no Mac) → use > one of those instead of iCloud. --- ## Tutorial 2 — Set up a trigger (what your agent edits, and how) **Triggers live in one file: `config/triggers.json`** — a JSON **array** of trigger objects. This is the file your agent edits to create or change triggers. (Unlike nodes, which are one-file-each, all triggers share this single list — so read it, modify the array, write it back whole.) A trigger object's fields: | Field | Required | Meaning | |-------|----------|---------| | `id` | yes | Uppercase UUID, unique in the list | | `tag` | yes | The text that fires it, e.g. `#research` | | `label` | yes | Short human name (shown in the app's tag picker) | | `description` | no | What it's for (shown in the app) | | `color` | yes | Hex color applied to the tagged node — and to your agent's reply node | | `action` | yes | `webhook` (dispatch to your system) · `holdback` (park the node) · `signal` (pure meaning, fires nothing) | | `webhook_url` | no | **Its presence chooses the transport:** *absent* → pull (your watcher catches it); *present* → push (Int posts to that URL) | | `instructions` | no | A per-trigger prompt carried to your agent when it fires — *this is where a lot of behavior config lives, with no code* | **To add a pull trigger,** append an object with **no `webhook_url`:** ```json { "id": "B7F3A1C2-0000-4D5E-8A9B-1122334455AA", "tag": "#research", "label": "Research", "description": "Kick off a research pass on this capture", "color": "#3B82F6", "action": "webhook", "instructions": "You were activated because the user tagged this node #research. Research the topic in the node and write a concise brief back. Do not include any #hashtags in your reply." } ``` - The **`instructions` field is your behavior lever** — change what a tag *does* by editing this string, no redeploy. (Want essays? Terse bullets? A specific job? Say so here. See [3 · Configurability → how your system responds](3-configurability.md).) - **Full parity with the app:** anything you write here, the user can also set on the triggers screen, and vice-versa. They're the same file. - **Add `webhook_url`** only if you want the **push** path (Tutorial 3, end). --- ## Tutorial 3 — Build your always-on watcher (a spec to implement) The pull path needs one always-on process — the **watcher** — on your computer. Rather than depend on a black box, **build your own** (or have your agent build it): it's roughly a hundred lines in any language, and owning it means you can shape it however you like. Here is the spec to implement. **Purpose.** Watch the vault; when a capture gains a pull-trigger tag, launch the user's agent on that capture and write the reply back to the canvas. (Nothing can wake a program that's off — this process *is* the always-on piece the whole pull path depends on.) **Configuration it needs:** - The **vault path** (from Tutorial 1). - The **pull triggers** from `config/triggers.json` — those with `action: "webhook"` and **no** `webhook_url`. - A **map of `tag → working directory`** — which folder to launch the agent from, per tag. - A poll interval and a spawn timeout. **The loop (every few seconds):** 1. Read every node file across every canvas. 2. **Skip** any node with `source: "agent"` — never react to your own write-backs. 3. For each remaining node, check whether its text contains a watched pull tag. 4. **Dedup:** handle each `(node id, tag)` pair only once; persist what you've fired so a restart doesn't replay it. 5. On a *new* match, **launch the user's agent** from the mapped directory, headless, passing the node's text plus the trigger's `instructions` as the prompt (e.g. `claude -p ""`, with stdin ignored so it can't block). 6. Capture the reply; **strip any `#tags`** from it (loop guard). 7. **Write the reply back** as a new node beside the original — `x + 250`, same `y`, `source: "agent"`, the trigger's `color`, uppercase-UUID filename = `id` (the hard contract, [doc 3](3-configurability.md)). **Required behaviors — don't skip these:** - **Baseline on first run.** Mark all *already-tagged* nodes as seen so you never back-fire history; only tags that appear after startup fire. - **Mark-before-run.** Record a `(node, tag)` as handled *before* launching, so a crash mid-run can't double-fire. - **The cwd is load-bearing.** Launch from the agent's own directory so it boots with its `CLAUDE.md`, memory, and tools — that's what makes it *your* agent, not a blank assistant. Launch from the wrong place and you get a generic model with no context. - **Headless auth is its own step.** The spawned agent needs its *own* credentials (a headless login or API key); being logged in *interactively* does **not** guarantee an unattended process can authenticate. Verify a one-line headless run (have it reply `PONG`) **before** relying on the watcher. - **Stay running.** Register the process as a background service (e.g. a `launchd` agent on macOS) so it auto-starts at login and restarts on crash. - **Mind sync lag.** Phone→computer changes take seconds to a minute over iCloud; fire once the file lands locally. **Test it.** With the watcher running, create a **new** node tagged with a configured pull tag — your agent should reply beside it within a cycle or two. **Push variant (optional, for instant firing while away from your computer).** Instead of polling, add a `webhook_url` to the trigger and run a small reachable endpoint that Int posts to the moment you tag. **Secure it** — require a secret and reject anything without it. Pull is the recommended default: it needs no public address and survives your computer sleeping (the tagged file is still there on wake); push is the upgrade when immediacy matters. --- ## Tutorial 4 — Integrate Int.ai into your system Int.ai is the surface; your system is the brain. "Integrating" means wiring your agents so they **know to work through Int.ai, where the vault is, and how to act on it.** The recommended shape is **two layers:** **Layer 1 — a small, always-loaded pointer in your agent's own instructions.** In your agent's `CLAUDE.md` (or role/system file), keep a short block it always sees: - *That* it works through Int.ai, and **where the vault is** (the resolved path from Tutorial 1). - A **link to these docs** for the mechanics (Layer 2). - **Your** tag taxonomy (what each tag means) and **your** response preferences (voice, format, where replies land). This is *your* personalization — it doesn't belong in Int.ai's generic docs; it belongs here, in your system. **Layer 2 — the full Int.ai docs saved in your system, read on demand.** Drop this doc set into a folder your agent can read (e.g. an `Int.ai/` reference folder). When the agent actually needs the exact mechanics — the write format, how to add a trigger — it opens the relevant doc. It does **not** carry the whole manual in context; the Layer-1 pointer tells it where to look. **Why two layers:** the agent must *persistently* know Int.ai exists and where the vault lives (Layer 1), but the detailed reference is large and changes over time, so keep it queryable rather than inlined (Layer 2). You get reliability without token bloat or stale copies. **What it looks like in practice.** A coordinating agent in your system (whatever plays the "reads my incoming stuff and acts on it" role) treats the vault as an input: it picks up newly-tagged captures, follows your Layer-1 preferences for what to do, consults the Layer-2 docs for *how* to read/write correctly, and writes results back to the vault — which sync carries to your phone. > **This is our recommended method, not the only one.** You could inline everything into your agent's > instructions, route through a dedicated agent, or wire it some other way entirely — Int.ai imposes > nothing. The two-layer pattern is what we'd reach for: minimal always-on pointer + on-demand reference. > A future Examples doc will walk through a real integrated system end to end (deferred until we've tested > the live flow). --- ## You're wired Vault synced (1) → a tag that means something (2) → the watcher that catches it (3) → your agent that knows what to do with it (4). Tag a capture, and your system acts on it — on the canvas, in your hands, wherever you are.