docs: tighten migration authoring and adapter guidance

migrate/README.md

@@ -12,57 +12,53 @@ unchanged with this package's provider-local registration:
 ```sh
 go install go.auvem.com/corestack/cmd/corestack-goose@<release>
 mkdir -p migrations
-corestack-goose create --dir ./migrations create_events sql
-corestack-goose fix --dir ./migrations
-corestack-goose create --dir ./migrations populate_events go
-corestack-goose fix --dir ./migrations
+cd migrations
+corestack-goose create create_events sql
+corestack-goose fix
+corestack-goose create populate_events go
+corestack-goose fix
 # Or use the version selected by your consumer module:
-go run go.auvem.com/corestack/cmd/corestack-goose create --dir ./migrations add_index sql
+go run go.auvem.com/corestack/cmd/corestack-goose create add_index sql
 ```
 
-The directory must exist and contain regular migration files, with no symlink
-components in its path (on macOS use `/private/tmp`, rather than `/tmp`). Names
-are lowercase ASCII words separated by underscores. Creation uses Goose's stock
-SQL template and a custom transactional Go template. Go files use the fixed
-`<version>_<name>_migration.go` suffix, so names such as `test`, `create_test` and
-`windows` stay buildable on every platform. Edit the SQL or Go up/down function bodies;
-leave factories and the generated `register.go` aggregate intact.
-`GoMigrations()` supplies fresh registrations on each call. The aggregate exists
-even for SQL-only sets. Versions are unique across SQL and Go; Goose timestamps
-have second resolution, so fix a new migration before creating another in the
-same second, or wait for a distinct timestamp.
+Both commands default to the current working directory; use `--dir <dir>` to
+select another existing directory. Paths must have no symlink components (on
+macOS use `/private/tmp`, rather than `/tmp`), and migration files must be regular.
+Names are lowercase ASCII words separated by underscores. Templates are stock
+Goose SQL or transactional Go. The Go suffix `<version>_<name>_migration.go`
+keeps names such as `test`, `create_test` and `windows` buildable on every platform.
+Edit up/down bodies; leave factories and generated `register.go` intact.
+Its `GoMigrations()` returns fresh registrations, even for SQL-only sets.
 
-`fix` preserves sequential IDs, allocates timestamps after the highest sequential
-ID with at least five-digit padding, and updates filenames and registration
-literals together. It preserves migration bodies. It rejects unsupported Go
-layouts, edited aggregates, duplicate versions/factories, unsafe paths, collisions,
-overflow and lexical/numeric order disagreement before writing. It does not adapt
-stock Goose Go output, whose global `init` registry is incompatible here.
+Versions must be unique across SQL and Go. Goose timestamps have second
+resolution: fix each new migration before creating another in the same second,
+or wait for a distinct timestamp. `fix` preserves sequential IDs and migration
+bodies, allocates timestamps after the highest sequential ID with at least
+five-digit padding, and updates filenames and registration literals together.
+Preflight rejects unsafe paths, collisions, unsupported Go layouts, edited
+aggregates, duplicate versions/factories, overflow and lexical/numeric order
+disagreement. Stock Goose Go output uses an incompatible global `init` registry.
 For concepts, see Goose's [hybrid versioning](https://github.com/pressly/goose#hybrid-versioning)
 and [SQL annotations](https://pressly.github.io/goose/documentation/annotations/).
 
 Before `fix`, commit or separately back up the **complete source set**, including
-untracked migrations and tracked edits. Run one authoring process with no concurrent
-editor changes. New destinations are exclusive; the tool stages output and fully
-publishes each destination before removing its old source. This is **not an atomic
-multi-file operation**. On a write/removal failure, stop and inspect the reported
-completed, partial/current and outstanding paths. Restore the complete source set
-and aggregate from that commit/backup before retrying; ordinary Git restore cannot
-recover untracked files or unsaved edits. Interruption can leave duplicates,
-aggregate drift or staging files; there is no automatic rollback or journal.
+untracked migrations and tracked edits. Use one authoring process without concurrent
+editor changes. New destinations are exclusive; staged destinations are fully
+published before old sources are removed. This is **not an atomic multi-file
+operation**: interruption can leave duplicates, aggregate drift or staging files,
+with no automatic rollback or journal. On failure inspect the reported completed,
+partial/current and outstanding paths, then restore the complete source set and
+aggregate from backup before retrying. Ordinary Git restore cannot recover
+untracked files or unsaved edits.
 
 Source reconciliation never rewrites database history. Use it before those IDs
 reach a shared database; preserve deployed IDs and add migrations afterward. The
 tool cannot determine deployment history.
 
-The standalone tool has no database setup. Production imports `migrate` and,
-optionally, `migrate/lifecycle`; neither imports authoring code. No build tags are
-needed. The generated consumer imports only Goose and the standard library.
-The artifact test builds both executables, decodes production dependency identities,
-and checks linker symbols for project authoring and Goose Create/CreateWithTemplate/
-Fix/SetSequential entrypoints. Goose's package remains a runtime dependency;
-these checks establish the tested build's boundary, not a universal ban on file I/O
-or proof about arbitrary downstream binaries. Build your application normally.
+The standalone tool needs no database or build tags. Production imports `migrate`
+and optionally `migrate/lifecycle`; neither imports authoring code. Generated
+migrations import only Goose and the standard library. Artifact tests verify the
+runtime dependency and executable boundary for the tested build.
 
 Embed migrations in the application's binary and run them before serving traffic:
 
@@ -102,9 +98,8 @@ without recursively searching subdirectories.
 Preserve the tool's creator/fix filenames and ship the complete migration history.
 The pinned Goose SQL-only provider relies on lexical filename order matching
 numeric version order. Timestamp versions and gaps are supported; never derive
-versions from file counts. For operations, errors, and SQL annotations, use the
-[Provider API](https://pkg.go.dev/github.com/pressly/goose/v3#Provider) and
-[SQL migration docs](https://pressly.github.io/goose/documentation/annotations/).
+versions from file counts. For operations and errors, use the
+[Provider API](https://pkg.go.dev/github.com/pressly/goose/v3#Provider).
 
 For generated Go functions, import the consumer's migration package and pass
 `migrations.GoMigrations()...` as the trailing arguments to `migrate.New`.