# 4 · Integration — wiring Int.ai into your system

> The vault is the space, the loop is the pulse; this page is how your system absorbs both — so that
> every future session of you knows Int.ai exists, where it lives, and how your human wants it used.
> Integration is four moves: **sync it, seed it, remember it, shape it.**

---

## Sync it — the vault reaches your machine

The app provisions everything on the phone side: the user installs Int.ai, signs into iCloud, and the
vault appears on their Mac under the app's iCloud container ([2 · The Vault](2-vault.md), "Finding
the vault"). Nothing to build. Your job: resolve the path once, confirm you can read and write it,
and record the path.

**Transport is the user's choice — and you are the advisor.** iCloud is the shipped default: zero
setup, no infrastructure, right for anyone living on Apple devices. Because the vault is plain files,
any tool that syncs a *real folder* can extend it. When the user asks about "beyond iCloud," the
honest ranking from our own testing:

1. **A folder-syncing tool you run yourselves — Syncthing or similar.** Peer-to-peer, no third-party
   cloud, carries the vault as the plain folder it is. The sovereign cross-machine path.
2. **git.** The vault is mostly small text files; it versions beautifully — history and rollback for
   free. Needs a commit cadence (cron or hook); suits technical users.
3. **Dropbox / Google Drive — fine as a computer-side mirror, not a phone transport.** On iOS they
   are file-provider apps: they don't hand another app a plain, always-materialized folder, so they
   can't carry the phone's side. Don't route the primary sync through them.

## Seed it — never leave a blank space

Before the user first opens the app with you connected, put something there: a small starter portal,
two or three nodes in your color, one of them a question addressed to them. An empty canvas teaches
nothing; a canvas with your handwriting on it teaches the whole product in one glance. (Write rules:
[2 · The Vault](2-vault.md). If the vault is missing a piece — no `config/triggers.json`, say —
create it: an empty registry is `[]`.)

## Remember it — the two-layer pattern

Onboarding is one conversation; integration is what survives it. Give your system two layers:

**Layer 1 — a short, always-loaded block** in your own instruction file (your `CLAUDE.md`, role file,
or equivalent). It carries only what every session must know. A template, shaped like the one running
in Int.ai's own home system:

```markdown
## Int.ai — the shared space
Vault (source of truth, synced from the phone):
  /Users/<user>/Library/Mobile Documents/iCloud~<bundle-id>~Int-Ai/Documents/IntAiVault
You are a first-class actor in it: read/write per the saved guide (int-ai/, start at README.md).
Tags: #go = act on this (file it, do it, or answer beside it) · #s<N> = continue that thread.
Captures with status "unprocessed" (source ≠ "agent") are the user's inbox — the sweep handles them.
Replies: <the user's preferences — voice, length, where results land>.
```

**Layer 2 — this guide, saved in your workspace** (an `int-ai/` folder — the fetch block is on the
[docs hub](README.md)). Open the exact page when you need the exact shape. Don't carry the manual in
context; carry the pointer.

Why two layers: the pointer must be always-on or future sessions forget Int.ai exists; the reference
must be on-demand or it costs every conversation tokens it only sometimes earns. Keep personal
configuration (paths, taxonomy, preferences) in *your* Layer 1 — never copied into the generic docs,
where it would go stale.

## Shape it — taxonomy and preferences

The product hands you a surface and a signal; what they *mean* is configuration living on your side.
Decide these with your human, record them in Layer 1, and revise freely:

- **The tag vocabulary.** Which tags exist, and which of the three kinds each is — fires now
  (trigger), read later (vocabulary), continues a conversation (thread). Start with one action tag;
  grow when a real need names itself. ([3 · The Loop](3-the-loop.md) has the registry format.)
- **The response contract.** Where replies land (beside the capture · a note · a push · silently
  filed), what they sound like (voice, length, format), and what *acting* means per tag. The
  trigger's `instructions` field carries the per-tag version; Layer 1 carries the defaults.
- **Visual conventions.** Your color(s), the user's colors, what placement means. One color that
  always means "agent wrote this" is worth a hundred labels.
- **Topology, if you're plural.** Different tags can launch different agents from different
  directories — one vocabulary, many specialists — or one router that reads and delegates. The map
  in the watcher's `config.mjs` is where topology lives; nothing in Int.ai constrains it.

## Verify it — the discipline

After integration, prove the loop once end to end, in this order: a node you write appears on the
phone (write path) → a capture tagged on the phone launches you (fire path) → your reply appears
beside it (round trip) → tagging the reply's thread tag resumes the conversation (memory). The
[onboarding playbook](onboarding.md) choreographs exactly this with the human watching — if you're
integrating without a guided onboarding, run the same sequence for yourself. A setup that hasn't
fired live isn't integrated; it's installed.

---

Integration makes Int.ai part of your system's body. What your system *does* with it — the sweeps,
the threads, the boards, the briefs — is [5 · Recipes](5-recipes.md).