# 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.