# Migrating into Aden

> Instructions for an AI agent moving a music company off its current tooling and into Aden. Aden is callable end to end, so do not drive the web UI.

## Start here

- MCP (preferred): `https://mcp.aden.space`, OAuth. Typed tools, so you never guess a field name.
- Tool catalog, no auth needed: `https://mcp.aden.space/tools`
- REST schema, if you have no MCP client: `https://aden.space/openapi.json` (mounted at `/api/v1`)
- Everything else worth reading: `https://aden.space/llms.txt`

Read the tool catalog or the schema before your first write. Both are generated from the running API, so they are never behind this file.

## Rules

- Never invent a value. A field you cannot map goes in the leftovers report, not into a guess.
- Stop after each block and wait for sign-off before starting the next one.
- Keep a row-level map of source id to Aden id, so the run can be repeated or reversed.
- Treat the source as read only. Ask before changing or deleting anything in it.
- Do not trigger sends. No fan email, no notification, no social post, while the migration runs.
- Music that is already released is imported as released, never as a new release.
- Report counts per block: rows read, rows written, rows skipped, and why.

## Order of work

Run these in order. Each one depends on the ones above it: a track needs its team, a file needs its version, an invoice line needs the session it bills for.

### 1. People

Your source may call this users, staff, roster, members, clients.

Lands in: Teams, members, and the organisation that holds them

Writes: `POST /teams`, `POST /organisations`

Feature spec: `docs/features/users-teams-organisations.md`

Must survive the move:

- Name
- Email
- Role mapped to Aden permissions

**Rule.** The team creator is added by a database trigger. Never write a membership row for them, it will duplicate.

### 2. Catalogue

Your source may call this songs, masters, projects, releases, works.

Lands in: Tracks, versions, albums, playlists

Writes: `POST /tracks`, `POST /tracks/:id/versions`, `POST /albums`, `POST /playlists`

Feature spec: `docs/features/tracks.md`

Must survive the move:

- Title
- ISRC and UPC
- Release date
- Version tree

**Rule.** Music that is already out is imported as released. Do not create it as a new release, that is what fires fan notifications.

### 3. Audio and files

Your source may call this stems, bounces, a NAS folder, Dropbox.

Lands in: Version files and project files

Writes: `POST /tracks/:id/versions`, `POST /project-files`

Feature spec: `docs/features/imports.md`

Must survive the move:

- The audio itself
- Folder structure
- Which version it belongs to

**Rule.** Ask Aden for a presigned upload URL and PUT the bytes straight to storage. Never post a file body through an API route.

### 4. Studio sessions

Your source may call this bookings, the studio diary, room calendar.

Lands in: Sessions and time entries

Writes: `POST /sessions`, `POST /time-entries`

Feature spec: `docs/features/studio-sessions.md`

Must survive the move:

- Room
- Engineer
- Hours
- Rate
- Billable flag

### 5. Events and tours

Your source may call this gigs, shows, dates, routing, holds.

Lands in: Events and tours

Writes: `POST /events`, `POST /tours`

Feature spec: `docs/features/events.md`

Must survive the move:

- Date and time
- Venue
- Status
- Which tour it belongs to

### 6. Contacts and deals

Your source may call this CRM, the client list, enquiries, pipeline.

Lands in: Contacts and opportunities

Writes: `POST /contacts`, `POST /opportunities`

Feature spec: `docs/features/contacts.md`

Must survive the move:

- Company
- Role
- Stage
- Value
- Owner

### 7. Splits and credits

Your source may call this split sheets, credits, a publishing spreadsheet.

Lands in: Track collaborators

Writes: `POST /collaborators`

Feature spec: `docs/features/collaborators.md`

Must survive the move:

- Role
- Split percent
- IPI

**Rule.** Splits that do not total 100 are imported as they are and listed in the leftovers report. Never round them to fit.

### 8. Money

Your source may call this invoices, the rate card, royalty statements.

Lands in: Financial entries

Writes: `POST /financials`

Feature spec: `docs/features/financials.md`

Must survive the move:

- Line items
- Currency
- Issue and paid dates

**Rule.** Keep the source currency. Never convert, Aden stores the currency per entry.

### 9. Open work

Your source may call this tasks, the whiteboard, a Trello board.

Lands in: Todos and milestones

Writes: `POST /todos`, `POST /milestones`

Feature spec: `docs/features/todos.md`

Must survive the move:

- Assignee
- Due date
- What it hangs off

**Rule.** Only bring open work. Closed tasks from a dead tool are noise in a new workspace.

## The leftovers report

Aden will not have a home for everything your source holds. That is expected and it is not a failure. Collect every unmapped field as `leftovers.csv` with four columns: source table, source field, an example value, and the row count.

Hand that file to the person who asked for the migration. Never drop an unmapped field silently, and never park it in a notes field to make the number look better.

## When you are done

Report per block: rows read, rows written, rows skipped. Then hand over `leftovers.csv` and the source-id to Aden-id map.

Full product context: https://aden.space/llms.txt

## Tailored versions

This file is generic. If you know the company role, fetch the tailored brief instead, it names what that role usually holds:

- `https://aden.space/for/<role>/migrate.md`