The actual documents the agents read and work from, shown exactly as they are on disk — not a summary. See the progress view instead · All projects
Owner: Nick (sign-off) · Onboarding lane (execution)
Purpose: instruction — the one governing file for building the migration route for every tool on the onboarding list and every data set the plan names for it.
# PLAN — Onboarding integrations: every tool on the list, every data set in the plan
**🔴 THIS IS THE ONLY FILE FOR THIS PROJECT.** Its state, questions and deltas live below (Nick, 2026-08-26: "we only need one project file ever"). The progress page is generated from this file's STEPS. The Hub-side lifecycle spec stays in the Hub repository at `HUB-UIUX-AUDIT/PLAN.md` (onboarding sections) and is cited, not copied.
**NORTH STAR:** a new customer picks the tools they use today on the onboarding page, signs in once per tool (or drops in an export file), and every kind of data the plan says that tool holds lands in their own Hub account — checked, receipted, undoable, and nothing sent to anyone.
**FINISH LINE:**
1. Every one of the 37 tools on the onboarding tool list has a working way in on the live Hub: one-click sign-in (ours or Composio's), an API key, or an export file — and the page offers the lowest-friction one that works.
2. For every tool, every data set the plan names for that tool's family (§1a row 2) either lands in a Hub destination through the same run engine (preview → sample → approval → batches → readback → receipt → undo), or is shown to the customer as "kept or rebuilt, never ported" where the plan says so.
3. One generated coverage matrix (tool × data set) is the truth, and a gate fails the Hub build when an in-scope cell has no route, no reader, no destination or no proof.
4. Each tool family is proven end to end on a real test account, not only on fixtures.
5. Fresh audit rounds over the whole migration stop only when a round's best finding is minor.
**Owner:** Nick · **Overseer:** this session (Opus) · **Builders:** the cheap lane (`projects/ops/cheap-task.mjs`) · **Checkers:** independent verifier sessions
## Already true (facts, not story)
- The onboarding tool list holds 37 tools across 8 data kinds (contacts, deals, tasks, messages, events, finance, files, forms) — evidence: `publicCatalogue()` in the Hub's `app/functions/api/onboarding-setup.js`, printed 2026-09-30.
- Readers already exist for 31 of the 37: contacts and deals for 9 CRMs, notes for 5 of them, projects and tasks for 6 work tools, audiences for 10 email tools, answers for 7 form tools, and GoHighLevel's full set (contacts, deals, notes, tasks, conversations, calendars, files, forms) — evidence: code inventory 2026-09-30 (provider files `_onboarding-provider-<id>.js`, harnesses `_selfchecks/harness-onb*.mjs`).
- No reader at all: Google, Microsoft, Calendly, and the two accounting tools — same inventory.
- Rows with nowhere to land: export-file tasks, bookings and form responses (`FAMILY_WRITERS` sets them null in `_onboarding-receiver-family.js:22`); companies as their own records; custom-field definitions; email templates and campaigns; invoices and payments — same inventory.
- Production holds the credential-sealing key and the Composio key (`ONB_CRED_KEY`, `COMPOSIO_API_KEY`) and no per-vendor sign-in apps of our own — evidence: `wrangler pages secret list --project-name=deck-business`, names only, 2026-09-30.
- Composio holds its own approved sign-in apps for 19 of our tools (HubSpot, Keap, Google Calendar, Gmail, Outlook, OneDrive, Google Drive, Asana, Trello, ClickUp, monday, Wrike, Basecamp, Kit, Zoho, Mailchimp, Calendly, QuickBooks, Typeform); only 4 are wired today — evidence: Composio toolkit API, 2026-09-30.
- Our Composio link passes the tool's own API calls through unchanged (`composioFetch`, `_onboarding-connectors.js:240`), so any reader we have works over it — evidence: that function, read 2026-09-30.
## 0 · Gate Zero receipts (the plan may not exist without these)
- Failure Mode Registry loaded: 2026-09-30. Entries this build is exposed to are named with their measures in §4.
- Canonical specs loaded: the Hub onboarding lifecycle and provider contracts (`HUB-UIUX-AUDIT/PLAN.md` onboarding sections, its migration rules at :5239–5406 and route order at :6076–6082), the migration map (`app/_design/migration-map.html`, 106 tools, 367 asset groups), the four map gaps spec v3.
- Ownership check: the project status registry read 2026-09-30 — no row for onboarding integrations; the Hub onboarding lane is this session's own lane (memory `project_onboarding_landed_for_restart_2026-09-24`). Accounting code belongs to the finance lane and is walled off from dispatched agents; STEP 19 is built in the overseer session only and reviewed with the finance owner.
- Expected inputs confirmed to exist: the run engine (`onboarding-tick.js`, `_onboarding-run.js`), the provider registry (`_onboarding-connectors.js`), the Composio link (`_onboarding-composio*.js`), the export-file route (`upload_source`/`map_source`), the receivers listed in §3, and the Composio toolkit list — each read 2026-09-30.
- PLAN AUTHOR: this session (Opus 5.5, Nick's Studio), 2026-09-30.
- COLD READER: `none — SINGLE-AUTHOR, UNREVIEWED` at authoring; STEP 1's checker is the first independent read of the scope table.
- PROMPT-SPEC scan (P1–P7): **P1 fired twice.** "every tool on the list" — settled V2 as the 37 tools of the onboarding tool list (the list the customer picks from). "every single data set that is in the plan" — settled V1 as every asset group the migration map and the Hub plan name for each of those tools' families (§1a row 2). **P4 fired once:** the plan also marks some assets "kept or rebuilt, never ported" (domains, phone numbers, sender reputation, payment set-ups); those stay out, named in the anti-scope. No other ambiguity material.
## 1 · Goal and definition of done
**What we're building, one paragraph.** The onboarding page already lets a customer pick their tools, and the migration engine already moves data safely for GoHighLevel and for contacts and deals from most CRMs. But most tools cannot actually be connected on the live Hub, and many kinds of data the plan promises (email history, calendars, bookings, CRM tasks and notes, templates, automations, finance history) have no reader or nowhere to land. This build closes every one of those gaps through the one engine that already exists, adds one coverage matrix that says exactly what works for every tool, and proves each family on real test accounts.
- **HOW IT'S USED:** a customer on the onboarding page picks a tool, presses Sign in (or pastes a key, or drops an export), sees what will come across, approves a sample, and watches it land; staff do the same on the customer's behalf on a call. · HOW WE KNOW: Nick, 2026-09-28, "migration of every possilbe data/asset/system etc that a customer might want to move over … lowest possible friction"; the live onboarding flow, walked 2026-09-29.
- **WHAT IT LOOKS LIKE:** no new screens; each tool card on the tools step gets a working Sign in, and the review step lists every data set that tool will bring, with a count and a destination. · HOW WE KNOW: the existing tools and review steps, which already draw from the catalogue and the connections.
- **WHERE IT LIVES:** the Hub at hub.heroesandsidekicks.io/onboarding, opened by customers and by Nick, Chantelle and the team; the code in the Hub repository; this plan in the workspace repository. · HOW WE KNOW: the live page and repositories, 2026-09-30.
- **WHAT IT MUST DO:** 1 · offer a working way in for every listed tool; 2 · bring every in-scope data set for each tool into its Hub destination through the one run engine; 3 · never send anything to anyone (imported drafts stay drafts, workflows stay off, calendars send no invitations); 4 · keep every record inside the customer's own account; 5 · prove every cell of the coverage matrix by a harness that can fail, and each family on a real account; 6 · fail the Hub build when the matrix has an unproven in-scope cell. · HOW WE KNOW: each restates a clause of Nick's 2026-09-30 instruction ("build the integration for every tool on the list and get a system built to bring every single data set over that is in the plan") or a migration rule in the Hub plan (:5239–5406).
- **NOT in scope:** the ANTI-SCOPE.
- **Tools in the migration map that are not on the onboarding list** (the map's other 69 tools). They join by adding a catalogue row later; this build makes that a one-file change.
- **Assets the plan marks "kept or rebuilt, never ported"**: domains, phone numbers, sender reputation, payment processor set-ups, GoHighLevel snapshots, live billing (Hub plan :5220, :5543, :7775).
- **Moving money or recreating a ledger.** Finance history lands read-only; nothing is charged, invoiced or reconciled.
- **Sending anything.** No email, SMS, invitation or campaign is sent by an import.
- **The onboarding punch list items Nick will take himself** (his own look at the live page; GoHighLevel scopes; developer registrations that need his identity).
- **Trip-over protocol:** anything outside the fence gets one handover line to its owner (a security-shaped thing: one line in `projects/ops/sp-sec/PLAN.md`), then back to building.
## 1a · Critical variables — the confirmation sheet is GENERATED from this table
| # | The variable, in plain words | Value chosen | Alternatives rejected | Class | HOW WE KNOW | Cost if wrong | CONFIRMED |
|---|---|---|---|---|---|---|---|
| 1 | **SURFACE — which screen this lands on, and who opens it** | The Hub onboarding page's tools and review steps, opened by customers and staff | A separate import screen | V1 | Nick names the onboarding flow and "lowest possible friction" | A second import path nobody finds | `Nick, 2026-09-28, "migration of every possilbe data/asset/system etc that a customer might want to move over not just contacts deals and notes … lowest possible friction"` |
| 2 | Which data sets count as "in the plan" for each tool | Every asset group the migration map and the Hub plan name for that tool's family, P1 and P2 and "later" alike, minus the "kept or rebuilt, never ported" set | Only P1; only what the catalogue's 8 kinds list | V1 | Nick's own words widen it to every data set | Customers stranded on a data set the plan promised | `Nick, 2026-09-30, "build the integration for every tool on the list and get a system built to bring every single data set over that is in the plan"` |
| 3 | Which tools are "the list" | The 37 tools on the onboarding tool list | The map's 106 tools | V2 | The tool list is what a customer picks from | Building for tools nobody can pick, or missing one they can | `opened publicCatalogue(), 2026-09-30, saw: 37 tools` |
| 4 | The default one-click route where we have no registered app | Composio's own approved app, through our existing pass-through link | Registering our own app per vendor first | V2 | Composio toolkit API lists managed sign-in for 19 of our tools | Weeks waiting on vendor approvals | `opened Composio's toolkit API, 2026-09-30, saw: managed OAUTH2 for hubspot, keap, googlecalendar, gmail, outlook, one_drive, googledrive, asana, trello (OAUTH1), clickup, monday, wrike, basecamp, kit, zoho, mailchimp, calendly, quickbooks, typeform` |
**Considered and ruled NOT critical:** which cheap vendor builds a step (the failover ladder decides); the order within a family (dependency order below decides).
## 1b · Subproject decomposition — could a piece of this ship on its own?
| Subproject | End goal (one sentence — what's TRUE when done) | Depends on (named artefact) | Owner | Own PLAN.md path | Confirmation-sheet status |
|---|---|---|---|---|---|
| A · The matrix | One generated tool × data-set matrix says what works, and the build fails on a gap | none — start now | Onboarding lane | this file, STEP 1 | rows 2, 3 confirmed |
| B · Ways in | Every listed tool can be connected on the live Hub | STEP 1's matrix | Onboarding lane | this file, STEPS 2, 20 | row 4 confirmed |
| C · Every data set lands | Every in-scope cell has a reader, a destination and a proof | STEP 1's matrix | Onboarding lane | this file, STEPS 3–19 | row 2 confirmed |
| D · Proven for real | Every family is proven on a real test account and audited | B and C | Onboarding lane | this file, STEPS 21–22 | row 1 confirmed |
**Carve-out rule:** accounting code is carved out to the finance lane's review; STEP 19 is built in the overseer session only.
## 2 · The complete UX map (this becomes the test manifest verbatim)
| Id | Screen / entry point | State (default·empty·error·loading) | Element / interaction | Expected behavior | Navigation from → to |
|---|---|---|---|---|---|
| U1 | Onboarding → Tools | default | A picked tool's card | Offers the lowest-friction working route: Sign in, then key, then export file | — |
| U2 | Onboarding → Tools | loading | Sign in with a Composio-backed tool | Opens the vendor's sign-in; on return the card shows the account and the data sets it will read | tools → vendor → tools |
| U3 | Onboarding → Tools | error | A sign-in the vendor refused or a key that failed | Says what failed in plain words and offers the next route down | — |
| U4 | Onboarding → Tools | default | An export file dropped for a tool | Recognised; every row family lands somewhere or is named as held with the reason | — |
| U5 | Onboarding → Review | default | The list of what comes across | One line per data set per tool with a count and where it lands; "kept or rebuilt" items named as such | tools → review |
| U6 | Onboarding → Progress | default | A running move | Each data set shows its own progress and final outcome | review → progress |
| U7 | Hub destinations (CRM, contacts, tasks, calendar/booking, conversations, files, forms, email drafts, workflows) | default | An imported record | Marked as imported, inside the customer's own account, never sent | progress → the destination screen |
## 2d · DESIGN FIDELITY GATE
`DESIGN FIDELITY GATE: N/A — nothing newly rendered.` The tools, review and progress steps already exist and draw from the catalogue and the matrix; any new wording is covered by the existing onboarding harnesses and audit rounds (STEP 22).
## 3 · Lanes and frozen contracts
| Lane | Scope (in / out) | Owner | Definition of done | Builder (cheap, named) | Backup builder | Checker (different model) | Backup checker |
|---|---|---|---|---|---|---|---|
| A · Matrix | in: the matrix generator and its gate. out: the engine | Onboarding lane | The matrix is generated and the gate fails on a gap | GLM 5.3 (`zai`) | DeepSeek V4 Pro (`deepseek`) | Sonnet verifier | Qwen 3.8 (`qwen`) |
| B · Routes | in: catalogue route fields, Composio toolkit rows, provider auth specs. out: credentials handling (the floor) | Onboarding lane | Every tool has a working route | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) |
| C · Readers and writers | in: provider readers, export parsers, receivers. out: the run engine's safety rules | Onboarding lane | Every in-scope cell lands with a proof | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) |
| D · Finance | in: read-only accounting readers and a read-only history store. out: any ledger, billing or payment | Onboarding lane, reviewed by the finance owner | Accounting history lands read-only | Sonnet (overseer session only, finance wall) | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | DeepSeek V4 Pro (`deepseek`) |
**Contracts between lanes (FROZEN at plan time — change = a dated delta in §7):**
- **A new tool or data set is added in exactly one place:** a provider file `_onboarding-provider-<id>.js` (auth + `readers.<kind>`), a catalogue row, and (for Composio) a `COMPOSIO_TOOLKITS` row. No second connector framework.
- **Every data set lands through `onboarding-tick.js`'s importer choice and one receiver per kind**, with the plan's safety rules (preview, sample, batches ≤50, readback, receipt, undo, account wall, no sending). No receiver writes outside the customer's account.
- **The matrix is generated from code, never hand-kept:** catalogue × readers × receivers × harness registry.
- **The one-lit-button and plain-words rules of the onboarding page stand** (harness-onbkeypage, harness-onbghlpage).
## 3b · Execution map — the Step map, then one STEP block per row
A task is DONE only when its review-ledger row is CLOSED by a reviewer that is not the builder, and it is live.
| Stage | # | Task (step name) | Needs (named artefact, or `none — start now`) | EXECUTOR (cheap model) | EXECUTOR BACKUP | CHECKER (different model) | CHECKER BACKUP | DONE-PROOF (runnable command) |
|---|---|---|---|---|---|---|---|---|
| Plan | 1 | The coverage matrix and its gate | none — start now | GLM 5.3 (`zai`) | DeepSeek V4 Pro (`deepseek`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbcoverage-20260930.mjs` — CREATED BY STEP 1, which is this step |
| Routes | 2 | One-click through Composio for every managed tool with a reader | STEP 1 | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbcomposio2-20260930.mjs` — CREATED BY STEP 2 |
| Land | 3 | Export files land: tasks, bookings, form responses | STEP 1 | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbfamilywriters-20260930.mjs` — CREATED BY STEP 3 |
| Read | 4 | Calendly: booking types and appointments | STEP 3 | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbcalendly-20260930.mjs` — CREATED BY STEP 4 |
| Read | 5 | Google contacts | STEP 2 | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbgoogle-20260930.mjs` — CREATED BY STEP 5 |
| Read | 6 | Google Calendar events | STEP 5 | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbgoogle-20260930.mjs` — CREATED BY STEP 5 |
| Read | 7 | Gmail history into conversations | STEP 5 | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbgoogle-20260930.mjs` — CREATED BY STEP 5 |
| Read | 8 | Microsoft: contacts, calendar, mail | STEP 2 | GLM 5.3 (`zai`) | DeepSeek V4 Pro (`deepseek`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbmicrosoft-20260930.mjs` — CREATED BY STEP 8 |
| Read | 9 | Drive and OneDrive files into the file library | STEPS 5, 8 | Qwen 3.8 (`qwen`) | GLM 5.3 (`zai`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbcloudfiles-20260930.mjs` — CREATED BY STEP 9 |
| Read | 10 | CRM notes on people and deals, every CRM | STEP 1 | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbcrmnotes-20260930.mjs` — CREATED BY STEP 10 |
| Read | 11 | CRM tasks and activities into the task list | STEP 1 | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbcrmtasks-20260930.mjs` — CREATED BY STEP 11 |
| Read | 12 | Companies, custom-field definitions, tags, owners, consent | STEP 1 | GLM 5.3 (`zai`) | DeepSeek V4 Pro (`deepseek`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbcrmshape-20260930.mjs` — CREATED BY STEP 12 |
| Read | 13 | Email audiences with consent, suppression and segments | STEP 1 | Qwen 3.8 (`qwen`) | GLM 5.3 (`zai`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbaudience-20260930.mjs` — CREATED BY STEP 13 |
| Read | 14 | Email templates and campaigns as drafts, send history as a report | STEP 13 | DeepSeek V4 Pro (`deepseek`) | Qwen 3.8 (`qwen`) | Sonnet verifier | GLM 5.3 (`zai`) | `node _selfchecks/harness-onbcampaigns-20260930.mjs` — CREATED BY STEP 14 |
| Read | 15 | Automations and sequences as switched-off drafts | STEP 14 | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbautomations-20260930.mjs` — CREATED BY STEP 15 |
| Read | 16 | Work tools in depth: subtasks, sections, dependencies, attachments | STEP 2 | GLM 5.3 (`zai`) | DeepSeek V4 Pro (`deepseek`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbworkdepth-20260930.mjs` — CREATED BY STEP 16 |
| Read | 17 | Forms in depth: definitions and logic | STEP 1 | Qwen 3.8 (`qwen`) | GLM 5.3 (`zai`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbformdefs-20260930.mjs` — CREATED BY STEP 17 |
| Read | 18 | GoHighLevel's remaining assets | STEP 1 | DeepSeek V4 Pro (`deepseek`) | GLM 5.3 (`zai`) | Sonnet verifier | Qwen 3.8 (`qwen`) | `node _selfchecks/harness-onbghlrest-20260930.mjs` — CREATED BY STEP 18 |
| Read | 19 | Accounting history, read-only | STEP 1 | Sonnet | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbfinance-20260930.mjs` — CREATED BY STEP 19 |
| Routes | 20 | Constant Contact and AWeber sign-in | a vendor app registration (a person) | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | Sonnet verifier | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbcoverage-20260930.mjs` — CREATED BY STEP 1 |
| Proof | 21 | Every family proven on a real test account | STEPS 2–19; test accounts connected once by a person | Sonnet | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbcoverage-20260930.mjs --live` — CREATED BY STEP 1 |
| Proof | 22 | Fresh audit rounds until the best finding is minor | STEP 21 | Sonnet | GLM 5.3 (`zai`) | Qwen 3.8 (`qwen`) | DeepSeek V4 Pro (`deepseek`) | `node _selfchecks/harness-onbcoverage-20260930.mjs --audits` — CREATED BY STEP 1 |
### STEP 1 — The coverage matrix and its gate
**FOR NICK:** one table that says, for every tool and every kind of data, whether it comes across today — and the Hub refuses to publish if something promised has quietly lost its route. · **Tier:** FRONT
**Start when:** none — start now.
**Do exactly this:** generate `app/functions/api/_onboarding-coverage.js` from the catalogue, the provider readers, the receivers and the harness registry; write the in-scope set (§1a row 2) as data; the harness fails on any in-scope cell without route, reader, destination and proof, and reports the matrix; `--audits` prints the recorded audit rounds; wire it into `gates.js` as a report first, then as a blocker once STEPS 2–19 close.
**PROOF:** `node _selfchecks/harness-onbcoverage-20260930.mjs` prints the matrix and its gap count; red first (today's gaps).
### STEP 2 — One-click through Composio for every managed tool with a reader
**FOR NICK:** Keap, Asana, Trello, ClickUp, monday, Wrike, Basecamp and Typeform get a one-click Sign in with no app registration of our own. · **Tier:** FRONT
**Start when:** STEP 1. **Do exactly this:** add a `COMPOSIO_TOOLKITS` row and `composio_evidence` per tool; prove each reader over the pass-through with a stubbed Composio answer. **PROOF:** `harness-onbcomposio2-20260930.mjs`.
### STEPS 3–19
Each follows the same shape: a red-first harness, a provider reader (or export parser) and a receiver through the one engine, the no-sending and account-wall rules proven, an independent verifier, the tier-1 sweep, merge, live check. Exact briefs are written per step into §8 as each starts.
### STEP 20 — Constant Contact and AWeber sign-in
Neither has a Composio-managed app; each needs one vendor app registration by a person. The sign-in code already exists; this step closes when the registration's keys are stored and a real sign-in works.
### STEP 21 — Every family proven on a real test account
A person connects each test account once (agents never type passwords); the matrix runs `--live` and each family's sample lands, is read back and is undone.
### STEP 22 — Fresh audit rounds
A fresh auditor walks the whole migration; fix, ship, repeat until a round's best finding is minor. Each round is recorded in §8 under a heading starting "AUDIT ROUND".
**Step-writing rules:** red first for every build; cheap builders; an independent checker; nothing is done until it is live.
## 4 · Regret Check (the registry failures this build is actually exposed to)
| Failure mode (registry entry) | The measure in THIS plan that prevents it | Where it lives (section / artifact / gate) |
|---|---|---|
| A second system was built because the first was invisible | Every tool and data set goes through the one provider registry and the one run engine; the contracts forbid a second framework | §3 contracts |
| A pipeline broke silently and looked identical to a working one | The coverage matrix is generated from code and gates the build, so a route that disappears fails loudly | STEP 1 |
| A proof passed on fixtures and failed on the real surface | STEP 21 proves every family on a real account, and the matrix marks fixture-only cells as unproven | STEP 21 · §6 |
| An import sent something to a real person | The no-sending rule is a proof in every step's harness (drafts stay drafts, workflows off, zero invitations) | STEPS 3–19 |
| A write landed outside the customer's own account | The receiver wall is required for every new receiver and asserted in each harness | §3 contracts |
| A hand-picked gate sweep missed a check and broke every Hub deploy | Every new harness is registered in `gates.js` in the same change, and the tier-1 sweep runs against a clean-main baseline before each merge | every step |
## 5 · Topology and roles
- **OVERSEER-AUTHORITY:** none named. **The four approval classes (money leaving · credential rotation · irreversible destruction · a message sent as Nick) and the floor (logins · credentials, tokens and keys · government IDs · card, bank and routing numbers) never move on the overseer's word.**
- Thread layout: one overseer thread (this one); cheap builders per edit; verifier sessions per step.
- Overseer: Opus (this session) · Workers: GLM 5.3 (`zai`), DeepSeek V4 Pro (`deepseek`), Qwen 3.8 (`qwen`), Sonnet as checker · Cap: 8 per session.
- State files location: this file, §8.
- **Board card id:** `ac-ai-builds-hub-onboarding-integrations-every-tool-on-the-li`
- **Artefact consumers:** the matrix → the Hub build gate and this plan's STEPS · each provider reader → the run engine · the progress page → Nick.
- **Write-contention:** the Hub's `onboarding-setup.js` is edited by one step at a time; each step works in its own Hub worktree and merges one at a time.
**Per-stage topology — counts DECLARED at plan time:**
| Stage | Overseer | Sub-overseers | Workers |
|---|---|---|---|
| Plan | 1 | 0 | 2 |
| Routes | 1 | 0 | 3 |
| Land / Read | 1 | 0 | 4 |
| Proof | 1 | 0 | 2 |
**The walk-away contract — a stranger resumes the drive from files alone:**
- **STATE FILE:** this file, §8
- **HEARTBEAT ROW:** `onboarding-integrations-drive` in `projects/personal/skippy-app/ala-state/work-threads.json`
- **MORNING-REPORT LINE:** `Onboarding integrations — <n> of 22 steps closed` in `projects/ops/walkaway/REPORT.md`
## 6 · Evals — what "working" means, decided now
| Capability | Check (exact command or procedure) | Pass looks like |
|---|---|---|
| 1 · Every tool has a way in | `node _selfchecks/harness-onbcoverage-20260930.mjs` | The routes column has no empty in-scope row |
| 2 · Every in-scope data set lands | the same harness | No in-scope cell lacks reader, destination or proof |
| 3 · Nothing is sent | each step's harness no-sending case | Zero sends, zero invitations, drafts stay drafts |
| 4 · Nothing leaves the account | each step's harness account-wall case | Every write inside the customer's account |
| 5 · Real accounts | `node _selfchecks/harness-onbcoverage-20260930.mjs --live` after test accounts are connected | Each family's sample lands, reads back and undoes |
| 6 · The build refuses a gap | remove one route in a scratch copy and run the gate | The gate fails naming the tool and data set |
## 7 · Assumptions and dated deltas
**Assumptions this drive runs on:**
- "The list" is the 37-tool onboarding tool list (V2, §1a row 3).
- "Every data set in the plan" is every asset group the migration map and the Hub plan name for those tools' families, minus the "kept or rebuilt, never ported" set (V1, §1a row 2).
- Composio's approved apps are an acceptable one-click route wherever we have no registered app of our own (V2, §1a row 4); our own apps replace them as registrations land.
- Accounting history is imported read-only; no ledger is recreated (Hub plan :7775).
**Open questions:** none blocking. The person-only items are named in §8.
## 🎬 PICK UP HERE
**Where it stands, 2026-09-30 ~8:50 am:** plan written and the Hub card open; STEP 1 (the coverage matrix) starts now. Detail in §8.
## 8 · State — the resume point
**2026-09-30, plan written.** Inventory measured the gaps listed under "Already true". Next: STEP 1.
**Needs a person (not blocking any build step):** a vendor app registration each for Constant Contact and AWeber (STEP 20); connecting each test account once for the live proofs (STEP 21). Both already have a Hub task for Mae (nt-20260928-205644-ee81, nt-onb-test-accounts-20260927).
## If you get stuck (all steps)
Before writing "blocked": re-read the step's Start-when line, try a concrete workaround, then write one line naming the one missing artefact — and keep working every other step whose inputs exist.
## Your loop
Every pass: every step whose inputs exist and which is not closed is running → each builds red-first, hands to its checker → PASS closes it and it goes live → repeat until the FINISH LINE is proven.
## SUMMARY — a few plain-English lines, read by the status generator
A new customer should be able to pick the tools they use today, sign in once per tool, and have everything the plan promises move into their Hub account safely. Today most tools cannot actually be connected on the live Hub, and several kinds of data (email history, calendars, bookings, CRM tasks and notes, templates, automations, finance history) have no way across. This build gives every listed tool a working way in (mostly through Composio's approved sign-in apps, so no waiting on vendor registrations), brings every promised kind of data across through the one migration engine that already exists, and adds one table that proves what works for every tool.
## STEPS
```
1. [Plan] The coverage matrix and its gate — 0%
DEFINITION OF DONE: a generated tool × data-set matrix exists and a harness fails on any in-scope gap
PROOF: `node _selfchecks/harness-onbcoverage-20260930.mjs`
VERIFIED: not yet
2. [Routes] One-click through Composio for every managed tool with a reader — 0%
DEFINITION OF DONE: Keap, Asana, Trello, ClickUp, monday, Wrike, Basecamp and Typeform offer Composio sign-in and their readers work over it
PROOF: `node _selfchecks/harness-onbcomposio2-20260930.mjs`
VERIFIED: not yet
3. [Land] Export files land: tasks, bookings, form responses — 0%
DEFINITION OF DONE: export-file task, booking and form-response rows reach the task list, bookings and forms instead of being held
PROOF: `node _selfchecks/harness-onbfamilywriters-20260930.mjs`
VERIFIED: not yet
4. [Read] Calendly: booking types and appointments — 0%
DEFINITION OF DONE: Calendly booking types land as switched-off drafts and appointments as history, sending nothing
PROOF: `node _selfchecks/harness-onbcalendly-20260930.mjs`
VERIFIED: not yet
5. [Read] Google contacts — 0%
DEFINITION OF DONE: Google contacts land in the customer's contacts through one-click sign-in
PROOF: `node _selfchecks/harness-onbgoogle-20260930.mjs`
VERIFIED: not yet
6. [Read] Google Calendar events — 0%
DEFINITION OF DONE: past and upcoming events land as calendar history with zero invitations sent
PROOF: `node _selfchecks/harness-onbgoogle-20260930.mjs`
VERIFIED: not yet
7. [Read] Gmail history into conversations — 0%
DEFINITION OF DONE: email threads with known contacts land in conversation history, nothing sent
PROOF: `node _selfchecks/harness-onbgoogle-20260930.mjs`
VERIFIED: not yet
8. [Read] Microsoft: contacts, calendar, mail — 0%
DEFINITION OF DONE: Outlook contacts, events and mail land like Google's
PROOF: `node _selfchecks/harness-onbmicrosoft-20260930.mjs`
VERIFIED: not yet
9. [Read] Drive and OneDrive files into the file library — 0%
DEFINITION OF DONE: chosen folders' files land in the customer's file library
PROOF: `node _selfchecks/harness-onbcloudfiles-20260930.mjs`
VERIFIED: not yet
10. [Read] CRM notes on people and deals, every CRM — 0%
DEFINITION OF DONE: every CRM on the list brings its notes onto the matching person and deal
PROOF: `node _selfchecks/harness-onbcrmnotes-20260930.mjs`
VERIFIED: not yet
11. [Read] CRM tasks and activities into the task list — 0%
DEFINITION OF DONE: every CRM on the list brings open tasks and activity history across
PROOF: `node _selfchecks/harness-onbcrmtasks-20260930.mjs`
VERIFIED: not yet
12. [Read] Companies, custom-field definitions, tags, owners, consent — 0%
DEFINITION OF DONE: companies are records, custom fields keep their definitions, the most restrictive consent wins
PROOF: `node _selfchecks/harness-onbcrmshape-20260930.mjs`
VERIFIED: not yet
13. [Read] Email audiences with consent, suppression and segments — 0%
DEFINITION OF DONE: every email tool brings its lists, segments and unsubscribes, with suppression kept
PROOF: `node _selfchecks/harness-onbaudience-20260930.mjs`
VERIFIED: not yet
14. [Read] Email templates and campaigns as drafts, send history as a report — 0%
DEFINITION OF DONE: templates and campaigns land as Broadcasts drafts that never send; past sends land as a read-only report
PROOF: `node _selfchecks/harness-onbcampaigns-20260930.mjs`
VERIFIED: not yet
15. [Read] Automations and sequences as switched-off drafts — 0%
DEFINITION OF DONE: automations land as switched-off workflow drafts or as a named rebuild list where the API gives no steps
PROOF: `node _selfchecks/harness-onbautomations-20260930.mjs`
VERIFIED: not yet
16. [Read] Work tools in depth: subtasks, sections, dependencies, attachments — 0%
DEFINITION OF DONE: the full project hierarchy comes across for all six work tools
PROOF: `node _selfchecks/harness-onbworkdepth-20260930.mjs`
VERIFIED: not yet
17. [Read] Forms in depth: definitions and logic — 0%
DEFINITION OF DONE: form definitions, fields and logic come across, not only answers
PROOF: `node _selfchecks/harness-onbformdefs-20260930.mjs`
VERIFIED: not yet
18. [Read] GoHighLevel's remaining assets — 0%
DEFINITION OF DONE: email templates, surveys, custom fields and values, tags and users-as-labels come across; workflows listed for rebuild
PROOF: `node _selfchecks/harness-onbghlrest-20260930.mjs`
VERIFIED: not yet
19. [Read] Accounting history, read-only — 0%
DEFINITION OF DONE: QuickBooks and Xero customers and suppliers land as contacts and invoice and payment history as read-only records
PROOF: `node _selfchecks/harness-onbfinance-20260930.mjs`
VERIFIED: not yet
20. [Routes] Constant Contact and AWeber sign-in — 0%
DEFINITION OF DONE: a real sign-in works for both
PROOF: `node _selfchecks/harness-onbcoverage-20260930.mjs`
VERIFIED: not yet
21. [Proof] Every family proven on a real test account — 0%
DEFINITION OF DONE: every family's sample lands, reads back and undoes on a real account
PROOF: `node _selfchecks/harness-onbcoverage-20260930.mjs --live`
VERIFIED: not yet
22. [Proof] Fresh audit rounds until the best finding is minor — 0%
DEFINITION OF DONE: a round's best finding is minor
PROOF: `node _selfchecks/harness-onbcoverage-20260930.mjs --audits`
VERIFIED: not yet
```