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