int-ai

Documentation

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, "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. 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:

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