fix: unify goose Provider path and fail on pending migrations

Apply BasePath via fs.Sub, route CLI through Provider API, return
ErrPendingMigrations when auto-migrate is disabled, use DownTo for blank.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -1,5 +1,45 @@
 # migrate
 
-migrate provides several [app.Module](https://gitea.auvem.com/go-toolkit/app) configurations to handle basic boilerplate. Built around the [goose](https://github.com/pressly/goose) database migration tool.
+Goose migrations as [app](https://gitea.auvem.com/go-toolkit/app) modules.
 
-See migrate/cmd for ready-made [Cobra](https://github.com/spf13/cobra) commands.
+## Install
+
+```bash
+go get gitea.auvem.com/go-toolkit/migrate
+```
+
+## Quick start
+
+```go
+//go:embed migrations/*.sql
+var migrations embed.FS
+
+mod, err := migrate.ModuleMigrations(&migrate.MigrationOpts{
+    SQLO:     dbx.SQLO,
+    Dialect:  goose.DialectMySQL,
+    FS:       migrations,
+    BasePath: "migrations",
+})
+```
+
+Register `mod` and optionally `migrate.ModuleAutoMigrate(true)` after the database module.
+
+## CLI
+
+Use [migrate/cli](cli) with `appcli` — not the removed `migrate/cmd` package.
+
+## Production notes
+
+- Require a goose zero-version migration for empty databases
+- Do not run `ModuleMigrateBlank` in production
+- When auto-migration is disabled, pending migrations return `ErrPendingMigrations`
+
+## Breaking changes (V1)
+
+| Before | After |
+|--------|-------|
+| `migrate.Migration` global | `migrate.Provider()` |
+| `ModuleMigrations(cfg) *Module` (panic) | `ModuleMigrations(cfg) (*Module, error)` + `MustModuleMigrations` |
+| `ModuleMigrateUp` var | `ModuleMigrateUp()` factory |
+| `MigrationsConfig() *MigrationOpts` | `MigrationsConfig() MigrationOpts` (copy) |
+| `migrate/cmd` | removed — use `migrate/cli` |