docs: add migration conflict resolution and worked migrate.ts example

[dqn]

Summary

Document the recovery procedure for migration number conflicts and add a worked migrate.ts example to the TailorDB migration guide.

Added guidance

• Resolving a migration number conflict (Team Workflow): step-by-step add/add conflict recovery — save script edits from ORIG_HEAD, take the other side's directory in full, delete leftovers that never conflicted, re-generate, and port the script — plus when a plain directory rename is acceptable and how tailor tailordb migration validate arbitrates it.
• Worked example (Migration Script Anatomy): a complete required-enum-field backfill paired with its schema change, with links to the repository's migration fixture templates for other breaking-change patterns.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f4ddaf6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@tailor-platform/create-sdk

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/create-sdk@f4ddaf6

@tailor-platform/eslint-plugin-sdk

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/eslint-plugin-sdk@f4ddaf6

@tailor-platform/sdk

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk@f4ddaf6

@tailor-platform/sdk-plugin-seed

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk-plugin-seed@f4ddaf6

@tailor-platform/sdk-plugin-tailordb-erd

pnpm add https://pkg.pr.new/tailor-platform/sdk/@tailor-platform/sdk-plugin-tailordb-erd@f4ddaf6

commit: f4ddaf6

[github-actions]

Code Metrics Report (packages/sdk)

	main (6396b4d)	#1987 (c2c0d33)	+/-
Coverage	78.5%	78.5%	0.0%
Code to Test Ratio	1:0.4	1:0.4	0.0

Details

  |                    | main (6396b4d) | #1987 (c2c0d33) | +/-  |
  |--------------------|----------------|-----------------|------|
  | Coverage           |          78.5% |           78.5% | 0.0% |
  |   Files            |            463 |             463 |    0 |
  |   Lines            |          17768 |           17768 |    0 |
  |   Covered          |          13956 |           13956 |    0 |
  | Code to Test Ratio |          1:0.4 |           1:0.4 |  0.0 |
  |   Code             |         126901 |          126901 |    0 |
  |   Test             |          62068 |           62068 |    0 |

SDK Configure Bundle Size

	main (6396b4d)	#1987 (c2c0d33)	+/-
configure-index-size	39.25KB	39.25KB	0KB
dependency-chunks-size	24.96KB	24.96KB	0KB
total-bundle-size	64.22KB	64.22KB	0KB

Runtime Performance

	main (6396b4d)	#1987 (c2c0d33)	+/-
Generate Median	2,379ms	2,367ms	-12ms
Generate Max	2,429ms	2,380ms	-49ms
Apply Build Median	2,409ms	2,405ms	-4ms
Apply Build Max	2,436ms	2,436ms	0ms

Type Performance (instantiations)

	main (6396b4d)	#1987 (c2c0d33)	+/-
tailordb-basic	40,450	40,450	0
tailordb-optional	4,535	4,535	0
tailordb-relation	3,854	3,854	0
tailordb-validate	666	666	0
tailordb-hooks	5,499	5,499	0
tailordb-object	16,345	16,345	0
tailordb-enum	1,538	1,538	0
resolver-basic	12,120	12,120	0
resolver-nested	35,419	35,419	0
resolver-array	24,056	24,056	0
executor-schedule	4,489	4,489	0
executor-webhook	1,130	1,130	0
executor-record	4,542	4,542	0
executor-resolver	5,808	5,808	0
executor-operation-function	1,118	1,118	0
executor-operation-gql	1,126	1,126	0
executor-operation-webhook	1,137	1,137	0
executor-operation-workflow	1,931	1,931	0

---

Reported by octocov

[github-actions]

📖 Docs Quality & Consistency Check

✅ Docs are consistent with the implementation and contain no user-facing internal-detail leaks.

Checked areas:

• Worked example (backfilling a new required enum field):

  • Verified db.table(), db.string(), db.enum(), db.fields.timestamps() APIs match actual SDK patterns in example/tailordb/user.ts
  • Verified Transaction type import from "./db" is correct
  • Verified Kysely API usage (trx.updateTable().set().where().execute()) is accurate
  • Verified idempotency pattern (where("role", "is", null)) matches template patterns
  • Verified links to migration fixture templates at example/tests/migration-fixtures/templates/0005 and 0006 exist and contain the described patterns

• Migration conflict resolution procedure:

  • Verified tailor tailordb migration generate, validate, and script CLI commands exist in packages/sdk/src/cli/commands/tailordb/migrate/
  • Verified ORIG_HEAD git reference usage is standard and correct
  • Verified file structure references (migrations/NNNN/diff.json, migrate.ts) match the documented migration system
  • Verified terminology ("warning-tier change", "breaking change") is consistent with existing documentation

• Reader perspective:

  • Confirmed all documented content describes user-facing behavior (git operations, CLI commands, file structure)
  • No internal implementation details leaked (no parser/bundler internals, no internal class names)
  • GitHub links point to public repository (tailor-platform/sdk)
  • All content appropriately addresses SDK users

Re-run this check by adding the docs-check label to the PR.

---

[toiroakr]

LGTM