Detailed content
🧪 The Connections Test
There is a simple, brutal test to see whether your AIOS has real Connections: ask a question that requires live data. Not data you pasted into the chat — data the system needs to fetch on its own. If the answer comes back without you copying anything, your Connections works.
🎯 The One-Sentence Test
"What’s on my calendar tomorrow, and which tasks are due?" — if that answer arrives without pasting, you have Connections.
- • Pasted data = you're still doing the manual search work.
- • Live data = AIOS reaches the system, searches, and responds. You just read.
- • The test applies to any domain—finance, tasks, communication, meetings.
✓ Real connections
- ✓"What’s due today?" → automatic lookup
- ✓Email summary → MCP or script
- ✓Next meeting + agenda → Calendar API
- ✓Monthly revenue → Finance API
✗ False Connections
- ✗Copy a Google Calendar meeting and paste it into the chat
- ✗Manually export CSV and upload it to the context
- ✗Type the tasks due into the prompt
- ✗Make the AIOS ask "send me the data"
🗺️ The 7 Universal Tier-1 Domains
Every knowledge-work task passes through 7 domains. They’re called Universal Tier-1 because they show up regardless of the industry — agency, SaaS, consulting, freelancer. Covering them is the foundation of a functional AIOS.
📋 Map of the 7 Domains — what to cover before anything else
| # | Domain | What it includes | Examples of tools |
|---|---|---|---|
| 1 | 💰 Revenue/Finance | Revenue, expenses, cash flow | Stripe, QuickBooks, Notion finance |
| 2 | 🤝 Client interactions | Leads, deals, support, feedback | HubSpot, Pipedrive, Intercom, Linear |
| 3 | 📅 Calendar | Personal calendar, meetings, deadlines | Google Calendar, Calendly, Notion cal |
| 4 | 💬 Communication | Email, chat, DMs, notifications | Gmail, Slack, Discord, Linear comments |
| 5 | ✅ Projects/Tasks | To-dos, sprints, backlog, deliverables | Linear, Notion, Asana, Trello |
| 6 | 🎙️ Meeting Intelligence | Transcripts, action items, recordings | Fireflies, Otter, Notion meetings |
| 7 | 📁 Knowledge/Files | Docs, wikis, SOPs, knowledge base | Notion, Drive, Confluence, Obsidian |
💡 Practical Tip — Start with the domain that hurts the most
Don’t try to connect all 7 at once. Identify which domain takes the most time to search manually in your day. Connect that one first. /audit scores coverage across all 7 domains—0 domains = a 4x multiplier on the score penalty.
⚙️ The 4 Mechanisms (tool-agnostic)
The AIS-OS kit is API-first and agnostic: no matter which tool you use, there are 4 ways to make AIOS reach a system. Each mechanism has tradeoffs in reliability, setup, and maintenance.
| # | Domain | Tool | Mechanism | Auth | Last check |
|---|---|---|---|---|---|
| 1 | Calendar | Google Calendar | mcp | OAuth | 2026-06-01 |
| 2 | Communication | Gmail | script | OAuth | 2026-05-28 |
| 3 | Projects | Linear | key+ref | .env API_KEY | 2026-05-15 |
| 4 | Knowledge | Notion | export | CSV dump | 2026-05-01 |
One line per reachable system. Keep it up to date — /audit reads this file.
The 4 mechanisms—from most to least integrated
mcp — MCP server
More integration · more complex setup · bidirectional
Claude Code connects directly to the tool’s MCP server. Real-time reading and writing. Requires configuration in .claude/settings.json. It’s the preferred mechanism when available.
script — Python/Bash calling an API
High flexibility · API-first · you’re in control
Python or Bash scripts that call the tool’s REST API. Stored in scripts/. Good when there’s no MCP. You version, test, and adapt it.
key+ref — .env key + references/{tool}-api.md
Lightweight · quick to set up · a good foundation for future skills
API key in .env + reference guide in references/{tool}-api.md. AIOS reads the guide and assembles the calls. The researched-once-saved-forever pattern.
export — CSV/JSON dump
More manual · no ongoing integration · starting point
Export manually and drop it into the context. Valid for Day 1 when the API is complex. But be careful: data becomes stale quickly. Use it as a starting point, not a final destination.
📋 connections.md — the central registry
O connections.md is your AIOS integration manifest. One line per reachable system. The /audit reads this file directly to score coverage of the 7 domains and check connection freshness.
📌 Required fields per row
- # Number — simple sequence. It means nothing beyond ordering.
- Domain One of the 7 Tier-1 (or your own custom subdomain).
- Tool Exact name from the tool (Gmail, Notion, Linear…).
- Mechanism mcp / script / export / key+ref — how the connection works.
- Auth OAuth / API Key / .env / no auth. Don’t put keys here—only the type.
- Last check Date the connection was last tested/validated. /audit penalizes poor freshness.
✓ Correct connections.md
- ✓One line per tool, simple
- ✓Mechanism filled in (mcp/script/export/key+ref)
- ✓Current check date (less than 30 days old)
- ✓7 domains represented
✗ Common errors
- ✗Put API keys in the file (it goes into git)
- ✗Leave “Last checked” blank
- ✗Don’t record export-type connections (they count toward the score)
- ✗Read-only only (see Topic 6)
💾 Researched-Once-Saved-Forever
Every time you research how an API works—endpoints, authentication, queries—you’re investing research time. Save this investment in references/{tool}-api.md is the "researched-once-saved-forever" pattern: you research once, and every future use — yours, a skill's, or an agent's — is instant.
📊 Why this matters so much
- Future skills don’t research things again — The skill reads references/{tool}-api.md and already knows the endpoints.
- /audit rewards this — The presence of API guides in references/ is scored directly in the Connections score.
- Real compounding — 10 API guides saved = an AIOS that's 10x faster for any new skill involving those systems.
- No manual re-research — You documented the Linear API once. Every skill that uses Linear inherits that knowledge.
# Linear API — Guia de Referência ## Base URL https://api.linear.app/graphql ## Auth Header: Authorization: {API_KEY} Var: LINEAR_API_KEY no .env ## Queries mais usadas - Listar issues: query { issues { nodes { id title state } } } - Issues do usuário: query { viewer { assignedIssues { ... } } } ## Mutations - Criar issue: mutation { issueCreate(input: {...}) } - Fechar issue: mutation { issueUpdate(id: "...", input: {stateId: "..."}) } ## Última atualização: 2026-06-01
💡 Tip — Document as you connect
Whenever you make a new connection (MCP, script, or key+ref), open the file references/{tool}-api.md and record the endpoints you tested, the authentication that worked, and the most common parameters. It takes 5 minutes and saves hours in the future.
⚖️ Read AND Write Balance
An AIOS that only reads is a sophisticated viewer, not an Operating System. To be a real OS, at least one connection needs to write — send email, create an issue, post a message, update a record. The ability to act in the world is what separates a consultation from automation.
🔄 The distinction that matters
- • “What meetings do I have today?”
- • “How many open issues are there in Linear?”
- • “What was last month’s revenue?”
- • “Summarize my unread emails”
Useful, but you still need to act manually.
- • Send the follow-up email
- • Creates the issue in Linear
- • Schedules the meeting
- • Post the update in Slack
AIOS takes action. You just approve (or don’t even need to).
⚠️ Caution — /audit penalizes all-read-only
If all if your connections are read-only, /audit applies a 2x multiplier to the Connections gap. That alone can take 8-12 points off your score. The requirement is small: 1 connection with write capability already clears this penalty.
💡 Where to start writing
The simplest writing connection for most people: Gmail with permission to create drafts. AIOS creates the draft — you review and send it. It covers the write-balance without the risk of accidental sending.
As you build confidence: Bike Method phase = starts by creating drafts, progresses to sending with approval, then automatic sending for specific categories.
🪜 The Integration Ladder
Not every connection is equally trustworthy. The Integration Ladder defines a reliability hierarchy: use the highest available level for each tool. Lower levels are used when higher ones don't exist — never by preference.
🪜 Reliability hierarchy — API at the top
Official, versioned, documented interface. Responds predictably. Has clear rate limits. Doesn’t break when the UI changes.
Tools like gh (GitHub), gcloud (GCP). Less granular than an API, but much more stable than a browser.
Playwright, Puppeteer, Computer Use. Fragile — any layout change breaks it. Higher maintenance costs. Use only when APIs and CLIs don’t exist.
HTML parsing of public pages. Highly unstable — breaks with every deploy. Often prohibited by terms of service. Never use as a long-term solution.
✓ Apply the Ladder
- ✓Checks whether an API exists before Browser Automation
- ✓Document the mechanism used in connections.md
- ✓Plans to move to a higher tier when available
✗ Ignore the Ladder
- ✗Using scraping when an API exists (fragile + unnecessary)
- ✗Browser automation for a tool with an official CLI
- ✗Build integration one step at a time and never review it
🔌 Module 2.2 Summary
Next Module:
2.3 — Capabilities: Knows how to do the work 🧩
One sentence triggers an artifact. Skills vs. Agents, the Autonomy Spectrum, and how /level-up builds capabilities week by week.