Epic: RMM migration onboarding — make moving off Datto/Ninja/Automate/Kaseya/N-central onto Breeze a supported path

[ToddHebebrand]

Why

Migrating off an incumbent RMM is the single largest barrier to an MSP adopting Breeze. Nobody evaluates an RMM in isolation — they evaluate it against the cost of moving 1,500 endpoints and 60 customers onto it without losing visibility on any of them.

The vendor-neutral playbook and the per-vendor guides now ship at apps/docs/src/content/docs/migration/ (Datto RMM, NinjaOne, ConnectWise Automate, Kaseya VSA, N-able N-central, Atera, Syncro, plus Pulseway/Action1/Automox/Level/Tactical/ScreenConnect). Writing them surfaced exactly where the product makes a migration harder than it needs to be.

What we already do well

Worth stating, because it shapes the priorities below:

• Agent mass enrollment is strong. Enrollment keys support maxUsage up to 100,000 and TTL up to 365 days, signed MSI with properties, ZIP bundles, token-authenticated installer links, short links, and pre-staging for golden images. Nothing needs to change here for a migration wave.
• Competing-RMM detection already ships. agent/internal/mgmtdetect/ fingerprints 11 competing RMMs on every enrolled endpoint. This is a genuine differentiator for the highest-stakes step of a migration, and it is currently invisible outside a single device tab.
• The read API is broad, and the org/site/enrollment-key write endpoints exist and behave correctly — they are just single-record and hard to reach unattended.

The gaps

#	Gap	Phase it blocks
#3242	No bulk import for organizations or sites	Phase 2 — rebuild the tenancy tree
#3243	No machine-to-machine credential can provision tenancy (JWT + MFA only)	Phase 2 — blocks scripting the workaround
#3244	Management Posture has no fleet-wide migration/decommission report	Phases 4 and 6 — verify and cut over
#3245	No script library import/export	Phase 5 — rebuild content
#3246	PSA getCompanies() implemented everywhere, called nowhere	Phase 2 — the zero-effort path for ConnectWise/Autotask shops
#3247	API reference wrongly documents X-API-Key as general auth	Blocks anyone scripting anything
#3248	No GPO / Intune / JAMF deployment guide	Steady state after migration

Suggested order

1. [Docs] API reference wrongly documents X-API-Key as general-purpose auth — the /devices example returns 401 #3247 — a docs correction that currently sends every integrator into a wall of 401s. Hours, not days.
2. [API][Web] No bulk import for organizations or sites — every RMM migration starts with hundreds of manual forms #3242 + [API][Security] No machine-to-machine credential can provision tenancy — org/site writes are interactive-JWT + MFA only #3243 — together these are the actual onboarding blocker. Import without an unattended credential still forces a human through the flow, and a credential without import still forces shell scripting; either alone is half a fix.
3. [API][Web] Fleet migration/decommission report — Management Posture already detects 11 competing RMMs and nothing consumes it #3244 — the highest-leverage feature, because the detection already exists and no competitor can offer it: we can report on endpoints whose incumbent agent is broken, which the incumbent's own console cannot see.
4. [API] PSA getCompanies() is implemented by every adapter and called by nothing — wire it to organization import #3246 — narrower than [API][Web] No bulk import for organizations or sites — every RMM migration starts with hundreds of manual forms #3242 but nearly free, and covers the large ConnectWise/Autotask segment with no CSV at all.
5. [API][Web] No script library import/export — a migrated script library must be pasted in one script at a time #3245, [Docs] No GPO / Intune / JAMF / config-management agent deployment guide #3248 — real, but workarounds are documented and tolerable.

Not proposed

Automated uninstall of a competing RMM. Detection informs; the operator drives removal through their own tooling. Adding remote-uninstall-the-competitor capability is a separate and deliberate decision, not a migration convenience.

[ToddHebebrand]

Phasing

Spec for #3242 is drafted at docs/superpowers/specs/onboarding-signup/2026-08-08-bulk-org-site-import-design.md. Writing it surfaced two more gaps that were not in the original epic, plus a clearer phase order. Recording it here so the deferred work does not get lost between PRs.

Phase 1 — foundations

#3247	API-key docs bug. Hours, not days. Do it first — it currently sends every integrator into a wall of 401s.
#3242	Bulk org/site import. Establishes organization_external_links (one-to-many external linkage) and the shared preview→commit orgImport seam that everything below reuses.
#3243	M2M provisioning credential. Until this lands, import is requireMfa()-gated by inheritance and cannot run unattended or scheduled.

Phase 2 — directly unblocked by #3242

#3246	PSA getCompanies() becomes an OrgImportSource. Should be small once the seam exists.
—	Migrate the QuickBooks importer onto the shared seam, so there is one importer rather than two divergent ones. Follow-up to #3242.
—	Drop organizations.accounting_provider / accounting_external_id + partial unique index, once all readers use the link table. Contract phase. Must also update the organizations entry in CORE_TENANT_EXPORT_POLICY — removing a column from a registered table breaks the export-policy test exactly as adding one does.

Phase 3 — the rest of the migration data model (newly filed)

#3257	Custom-field / UDF backfill import. Datto udf1–udf30, Automate EDFs, Ninja/N-central custom properties. This is the largest chunk of genuine customer data a migration currently abandons — warranty dates, asset tags, primary users. Separate phase because values attach to devices, which only exist after enrollment.
#3258	Organizations have no first-class contacts. No contacts table (JSONB blobs only) and aiToolsOrgs.ts:473 add_contact is unimplemented, so no importer can create them. Needs a data-model decision — possibly "the PSA owns contacts, link read-through" rather than a local table — before any importer can target it.

Phase 4 — surfacing and content

#3244	Fleet migration/decommission report from Management Posture. Independent of everything above; could be pulled forward at any point since detection already ships.
#3245	Script library import/export bundle.
#3248	GPO / Intune / JAMF deployment guide.

Not planned

Device import by upload (devices arrive by enrollment), two-way push to PSA/accounting, and automated uninstall of a competing RMM.

Open decision

#3242 §0 — one-to-many link table vs. generalising the shipped single-valued accounting_* columns. Recommendation is the link table; the independent advisor review has not run yet (expired Codex auth), so it should be re-checked before implementation starts.