@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/efcore/SKILL.md

@@ -1,308 +1,88 @@
----
-name: efcore
-description: EF Core Commands - Migration and database management
-argument-hint: "<command> [options]"
-disable-model-invocation: true
----
-
-## Current state (auto-injected)
-- Preflight: !`if [ -f .git ] && grep -q '^gitdir: [A-Za-z]:' .git 2>/dev/null && grep -qi microsoft /proc/version 2>/dev/null; then p=$(sed 's/^gitdir: //' .git | tr -d '\r\n'); d=$(echo "${p:0:1}" | tr A-Z a-z); r="${p:2}"; r="${r//\\//}"; printf 'gitdir: %s\n' "$(realpath -m --relative-to="$(pwd)" "/mnt/$d$r")" > .git && echo "repaired"; else echo "ok"; fi`
-- Branch: !`git branch --show-current 2>/dev/null || echo "UNAVAILABLE"`
-
-<routing>
-
-Parse `$ARGUMENTS` to determine the command:
-
-| Command | Execution | Model |
-|---------|-----------|-------|
-| `db-status` | **Inline** `<command-db-status>` | — |
-| `db-deploy` | **Inline** `<command-db-deploy>` | — |
-| `db-reset` | **Inline** `<command-db-reset>` | — |
-| `db-seed` | **Inline** `<command-db-seed>` | — |
-| `scan` | **Inline** `<command-scan>` | — |
-| `conflicts` | **Inline** `<command-conflicts>` | — |
-| `migration` | **Agent** `efcore-migration` | sonnet |
-| `squash` | **Agent** `efcore-squash` | sonnet |
-| `rebase-snapshot` | **Agent** `efcore-rebase-snapshot` | sonnet |
-| (none) | **Inline** `<command-help>` | — |
-
-**Inline commands:** Execute directly following the matching `<command-*>` section below.
-**Agent commands:** Delegate via Agent tool:
-```
-Agent(
-  subagent_type: "{agent_name}",
-  model: "sonnet",
-  prompt: "Execute /efcore {command}.
-    Working directory: {cwd}
-    Branch: {branch}
-    Context: {--context value if provided, else 'auto-detect'}
-    Force: {true if --force flag, else false}
-    Description: {user description if provided}
-  "
-)
-```
-
-**Flags:**
-- `--context <name>` — Force DbContext (`CoreDbContext` or `ExtensionsDbContext`), skip auto-detection
-- `--force` — Skip all confirmations (backup still created)
-
-</routing>
-
-<shared>
-
-### WSL Preflight (MANDATORY before any git command)
-
-```bash
-if [ -f .git ] && grep -q '^gitdir: [A-Za-z]:' .git 2>/dev/null && grep -qi microsoft /proc/version 2>/dev/null; then
-  p=$(sed 's/^gitdir: //' .git | tr -d '\r\n'); d=$(echo "${p:0:1}" | tr A-Z a-z); r="${p:2}"; r="${r//\\//}"
-  printf 'gitdir: %s\n' "$(realpath -m --relative-to="$(pwd)" "/mnt/$d$r")" > .git
-fi
-```
-
-### dotnet-ef PATH fix (MANDATORY before any dotnet ef command)
-
-```bash
-if ! dotnet ef --version &>/dev/null; then
-  for TOOLS_DIR in "$USERPROFILE/.dotnet/tools" "$HOME/.dotnet/tools" "$LOCALAPPDATA/Microsoft/dotnet/tools"; do
-    [ -n "$TOOLS_DIR" ] && [ -d "$TOOLS_DIR" ] && export PATH="$TOOLS_DIR:$PATH"
-  done
-  dotnet ef --version &>/dev/null || { echo "ERROR: dotnet-ef not found. Install: dotnet tool install --global dotnet-ef"; exit 1; }
-fi
-```
-
-### Dual DbContext Architecture
-
-| Context | DbContext | Schema | History Table |
-|---------|-----------|--------|---------------|
-| `core` | `CoreDbContext` | `core` | `core.__EFMigrationsHistory` |
-| `extensions` | `ExtensionsDbContext` | `extensions` | `extensions.__EFMigrationsHistory` |
-
-**Deploy order:** Core FIRST, then Extensions (FK dependency).
-Both contexts share the same physical database but use different schemas.
-
-### Safety Rules
-
-1. **Production BLOCKED** — Never run on production
-2. **Backup MANDATORY** for destructive operations (db-reset, squash)
-3. **1 migration per feature** — Recreate, don't accumulate
-4. **MCP for naming** — Never hardcode migration names
-
-### Migration Naming (MCP MANDATORY)
-
-Pattern: `{context}_v{version}_{sequence}_{Description}`
-**FORBIDDEN:** Manual name calculation. Always use `mcp__smartstack__suggest_migration`.
-
-</shared>
-
-<success_criteria>
-- Command displays its summary block with no ERROR lines
-- db-status: both contexts report migration counts (no connection failure)
-- db-deploy: 0 pending migrations after execution
-- db-reset: database recreated, all migrations applied for both contexts
-- db-seed: seed method detected and executed, records inserted
-- scan: all worktree branches analyzed with risk levels
-- conflicts: EXIT CODE 0 (no HIGH/CRITICAL)
-- migration: MCP-named migration created, compiles, applies cleanly
-- squash: consolidated migration compiles and applies identically
-- rebase-snapshot: ModelSnapshot aligned with parent branch
-</success_criteria>
-
-<command-db-status>
-
-## db-status — Fast migration state check
-
-**READ-ONLY: Never modify database or migrations.**
-
-> **Troubleshooting:** See `references/troubleshooting.md` for common errors.
-
-1. Call MCP `mcp__smartstack__check_migrations` with `branch: {current_branch}`
-2. If MCP unavailable, fallback: `dotnet ef migrations list --no-build --context {Context}` per context
-3. Display compact summary
-
-```
-EF CORE — DATABASE STATUS
-──────────────────────────
-CORE (CoreDbContext)
-  Migrations: {applied}/{total} | {pending} pending
-
-EXTENSIONS (ExtensionsDbContext)
-  Migrations: {applied}/{total} | {pending} pending
-
-BRANCH: {branch}
-  Naming: {ok|warnings}
-  1-migration rule: {ok|warning}
-```
-
-</command-db-status>
-
-<command-db-deploy>
-
-## db-deploy — Apply pending migrations
-
-**ONLY runs `dotnet ef database update`. Never creates/deletes migrations.**
-
-> **Reference:** See `references/database-operations.md` for connection test and migration count utilities.
-
-1. Detect projects: `INFRA_PROJECT=$(find src -name "*Infrastructure.csproj" | head -1)` and `STARTUP_PROJECT=$(find src -name "*.Api.csproj" | head -1)`
-2. Verify `appsettings.Local.json` exists in the API project
-3. Apply Core: `dotnet ef database update --context CoreDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT" --verbose`
-4. Apply Extensions: `dotnet ef database update --context ExtensionsDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT" --verbose`
-
-If connection fails: suggest verifying SQL Server, appsettings.Local.json, or `/efcore db-reset`. See `references/troubleshooting.md`.
-
-```
-DB DEPLOY
-  Config: appsettings.Local.json
-  CORE: {n} migration(s) applied — {success|error}
-  EXTENSIONS: {n} migration(s) applied — {success|error|skipped}
-```
-
-</command-db-deploy>
-
-<command-db-reset>
-
-## db-reset — Drop + recreate database (DESTRUCTIVE)
-
-**ONLY operates on database. Never creates/deletes migration files.**
-
-> **Reference:** See `references/reset-operations.md` for drop/recreate commands.
-
-1. Detect projects: `INFRA_PROJECT=$(find src -name "*Infrastructure.csproj" | head -1)` and `STARTUP_PROJECT=$(find src -name "*.Api.csproj" | head -1)`
-2. **Confirm** (MANDATORY unless `--force`):
-   ```
-   AskUserQuestion({ question: "DELETE the database? All data will be lost.", options: ["Yes, delete", "No, cancel"] })
-   ```
-3. **Backup** (optional): `sqlcmd -S "$SERVER" -E -Q "BACKUP DATABASE [$DB] TO DISK='$FILE' WITH FORMAT, INIT, COMPRESSION"`
-4. **Drop**: `dotnet ef database drop --force --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
-5. **Recreate Core**: `dotnet ef database update --context CoreDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
-6. **Recreate Extensions**: `dotnet ef database update --context ExtensionsDbContext --project "$INFRA_PROJECT" --startup-project "$STARTUP_PROJECT"`
-7. **Ask** if user wants `/efcore db-seed`
-
-Block if ASPNETCORE_ENVIRONMENT=Production.
-
-```
-DB RESET
-  Backup: {path|none}
-  CORE: {n} migrations applied — {success|error}
-  EXTENSIONS: {n} migrations applied — {success|error}
-
-Next: /efcore db-status, /efcore db-seed
-```
-
-</command-db-reset>
-
-<command-db-seed>
-
-## db-seed — Populate test data
-
-**Never drop or recreate database.**
-
-> **Reference:** See `references/seed-methods.md` for detection and execution details.
-
-1. **Detect** seeding method:
-   - `HasData()` in EF configs → apply via `dotnet ef database update --context {Context}`
-   - `IDataSeeder` / `--seed` CLI arg → `dotnet run --project {startup} -- --seed`
-   - SQL script `scripts/seed.sql` → **WARNING**: forbidden by conventions, suggest HasData migration
-2. **Execute** the detected method
-3. **Verify** insertion
-
-```
-DB SEED
-  Method: {hasdata|cli-seed|seeder-class}
-  Status: {success|error}
-  Records: {n} inserted (if available)
-```
-
-</command-db-seed>
-
-<command-scan>
-
-## scan — Cross-branch migration scanner
-
-**READ-ONLY. Uses MCP to detect conflicts across branches.**
-
-1. List active worktrees: `git worktree list`
-2. For each branch, determine base:
-   - `feature/*` → `develop`
-   - `release/*` / `hotfix/*` / `develop` → `main`
-3. Call MCP `mcp__smartstack__check_migrations` with `branch` + `compareBranch` for each
-4. Aggregate risks and recommend merge order
-
-| MCP Type | Level | Action |
-|----------|-------|--------|
-| (none) | NONE | Merge OK |
-| `naming` | LOW | Merge OK |
-| `order` | MEDIUM | Attention |
-| `dependency` | HIGH | Rebase required |
-| `snapshot` | CRITICAL | Manual intervention |
-
-Fallback (MCP unavailable): `git worktree list` + `md5sum Migrations/*ModelSnapshot.cs`
-
-```
-EF CORE CROSS-BRANCH SCAN
-──────────────────────────
-BRANCHES ({n})
-  {branch} | {count} migrations | Risk: {level}
-
-RECOMMENDED MERGE ORDER
-  1. {branch} (reason)
-```
-
-</command-scan>
-
-<command-conflicts>
-
-## conflicts — Migration conflict analyzer (BLOCKING)
-
-**READ-ONLY. Blocks on HIGH/CRITICAL conflicts.**
-
-1. Determine base branch: `feature/*` → `develop`, others → `main`
-2. Call MCP `mcp__smartstack__check_migrations` with `branch` + `compareBranch`
-3. Display results. **EXIT CODE 1** if HIGH or CRITICAL.
-
-| Type | Level | Exit |
-|------|-------|------|
-| (none) | NONE | 0 |
-| `naming` | LOW | 0 |
-| `order` | MEDIUM | 0 (warning) |
-| `dependency` | HIGH | 1 (BLOCK) |
-| `snapshot` | CRITICAL | 1 (BLOCK) |
-
-Fallback (MCP unavailable): `diff` on ModelSnapshot files.
-
-```
-EF CORE CONFLICT ANALYSIS
-─────────────────────────
-STATUS: {OK|WARNING|CONFLICT}
-EXIT CODE: {0|1}
-
-If conflict:
-  /efcore rebase-snapshot  (recommended)
-  /efcore squash           (alternative)
-```
-
-</command-conflicts>
-
-<command-help>
-
-## (no command) — Show available commands
-
-Display the list of available `/efcore` commands:
-
-```
-EF CORE COMMANDS
-────────────────
-  db-status         Migration state check
-  db-deploy         Apply pending migrations
-  db-reset          Drop + recreate database
-  db-seed           Populate test data
-  scan              Cross-branch migration scanner
-  conflicts         Migration conflict analyzer
-  migration         Create/recreate migration
-  squash            Consolidate migrations
-  rebase-snapshot   Resync ModelSnapshot with parent
-
-Usage: /efcore <command> [--context <name>] [--force]
-```
-
-</command-help>
+---
+name: efcore
+description: >
+  EF Core migration workflow — create, squash, rebase-snapshot, apply, list,
+  status. Applies the best practices of the global /efcore agents without
+  MCP or external dependencies. Works against a single-assembly generated
+  app (CoreDbContext + ExtensionsDbContext) or the multi-assembly Studio
+  (StudioDbContext with Sqlite / Postgres / SqlServer migration projects).
+phase: infrastructure
+cli: cli/
+allowed-tools: [Read, Glob, Grep, Bash]  # Bash: CLI invocation
+---
+
+# efcore — EF Core migration workflow
+
+This skill manages EF Core migrations for any .NET project in a worktree:
+SmartStack-generated apps (dual context: Core + Extensions) or the Studio
+itself (single context, three provider assemblies).
+
+All intelligence lives in this skill + the agent prompts under `agents/`.
+The colocated CLIs in `cli/` are pure executors — they never decide what to
+do, they only do what the spec tells them.
+
+## Routing table
+
+| User intent | Agent prompt | CLI |
+|-------------|--------------|-----|
+| "Show me the migrations" | `agents/list.md` | `cli/list/` |
+| "Is anything pending?" | `agents/status.md` | `cli/status/` |
+| "Create a new migration" | `agents/create.md` | `cli/create/` |
+| "Squash branch migrations before merge" | `agents/squash.md` | `cli/squash/` |
+| "Fix snapshot after a rebase" | `agents/rebase-snapshot.md` | `cli/rebase-snapshot/` |
+| "Apply migrations to the local DB" | `agents/db-update.md` | — (runs `dotnet ef database update`) |
+| "Drop + recreate the local DB (destructive)" | `agents/recreate-db.md` | — (runs `database drop --force` then `database update`) |
+
+**Always read `_shared.md` before executing any operation.** It documents
+WSL git preflight, the `dotnet-ef` PATH trick on Git Bash, the naming
+convention, and the dual-DbContext detection heuristic.
+
+## Invariants
+
+- Never create migrations manually named — always let `cli/create/` compute
+  the name. The convention is `{contextPrefix}_v{version}_{seq3}_{PascalCaseDescription}`.
+- Never edit `ModelSnapshot.cs` by hand — it is regenerated by EF.
+- Never run `squash` or `rebase-snapshot` on `main` / `master` — the CLI
+  refuses.
+- Squash always creates a backup under `.efcore-squash-backup/<timestamp>/`
+  before deleting anything. If something goes wrong, the backup is the
+  source of truth.
+- For multi-provider contexts (the Studio itself), `create` adds the same
+  migration to every provider assembly by default. Pass `assembly` to
+  target only one.
+
+## Invocation contract for agents
+
+When Claude decides which agent to use, it invokes the corresponding CLI
+with a single `--spec '<JSON>'` argument. Every CLI returns a single JSON
+object on stdout. Exit code 0 = success, 1 = failure (inspect `error` or
+`errors[]`).
+
+Example — create a migration on the current worktree:
+
+```
+npx tsx skills/efcore/cli/create/index.ts --spec '{
+  "cwd": "D:/projets/app/features/ba-002",
+  "contextName": "CoreDbContext",
+  "description": "AddEmployeeAvatar"
+}'
+```
+
+## Consumer: DevRunner Migrations tab
+
+The Studio's DevRunner page (see `src/frontend/components/dev-runner/MigrationsTab.tsx`)
+exposes these operations through buttons. Deterministic reads (list,
+status, detect-contexts) go through the IPC router `/migrations/*`; any
+operation that mutates the worktree (create, squash, rebase-snapshot,
+db-update) is invoked via `claude -p @skills/efcore/SKILL.md ...` so that
+the agent prompts drive Claude. This keeps all business logic in Markdown
+and away from TypeScript.
+
+## When something goes wrong
+
+- **dotnet-ef not on PATH** — follow `_shared.md` "dotnet-ef PATH setup".
+- **Snapshot conflicts after rebase** — use `rebase-snapshot`.
+- **Squash produced a build error** — copy files back from the backup
+  under `.efcore-squash-backup/<timestamp>/` and investigate.
+- **Multiple contexts detected but operation only matches one** — pass the
+  `contextName` and optionally `assembly` to disambiguate.

package/templates/skills/efcore/_shared.md

@@ -0,0 +1,140 @@
+# efcore shared reference
+
+Load this file whenever you invoke any `efcore` agent. It captures the
+invariants that don't change between operations.
+
+## 1. Dual DbContext model
+
+Generated SmartStack apps ship with two contexts:
+
+| Context | Schema | Migration project | Use |
+|---------|--------|-------------------|-----|
+| `CoreDbContext` | `core` | `{App}.Infrastructure` | SmartStack platform tables |
+| `ExtensionsDbContext` | `extensions` | `{App}.Infrastructure` | Client / tenant tables |
+
+When both contexts change, apply Core **before** Extensions (Extensions FKs
+reference Core rows).
+
+The Studio itself has a single context (`StudioDbContext`) compiled
+against three migration assemblies, one per provider:
+
+| Assembly | Provider env var |
+|----------|------------------|
+| `StudioDataService.Migrations.Sqlite` | `STUDIO_DESIGN_PROVIDER=Sqlite` |
+| `StudioDataService.Migrations.Postgres` | `STUDIO_DESIGN_PROVIDER=Postgres` |
+| `StudioDataService.Migrations.SqlServer` | `STUDIO_DESIGN_PROVIDER=SqlServer` |
+
+For the Studio, every `create` / `squash` / `rebase-snapshot` operation
+runs three times — one per assembly — with the env var set correctly. The
+CLI handles this automatically when `allProviders: true` (default).
+
+## 2. Naming convention — no MCP
+
+```
+{contextPrefix}_v{version_underscore}_{seq3}_{PascalCaseDescription}
+```
+
+- `contextPrefix` — `CoreDbContext` → `core`, `ExtensionsDbContext` →
+  `ext`, `StudioDbContext` → `studio`.
+- `version_underscore` — `<Version>` from the csproj with `.` → `_`. Pre-
+  release suffixes and build metadata are stripped: `0.1.0-dev.3` becomes
+  `0_1_0`. Defaults to `0_1_0` if no version tag is found.
+- `seq3` — number of existing migrations in the assembly's migrations
+  directory + 1, zero-padded to three digits.
+- `PascalCaseDescription` — description stripped to `[A-Za-z0-9]`, split on
+  whitespace / `-` / `_`, words capitalized and joined.
+
+Examples:
+
+```
+core_v0_1_0_007_AddEmployeeAvatar
+ext_v1_0_0_003_CreateOrders
+studio_v1_0_0_005_AddBugWorkflow
+```
+
+## 3. Environment preflight
+
+### dotnet-ef on PATH (Git Bash on Windows)
+
+The `dotnet-ef` global tool lives under `$USERPROFILE\.dotnet\tools`
+(Windows) or `$HOME/.dotnet/tools` (POSIX). Git Bash does not pick these
+up by default. The CLI `ef-runner.ts` prepends both paths to `PATH`
+automatically. If you're invoking `dotnet ef` manually from a terminal,
+run:
+
+```bash
+for TOOLS_DIR in "$USERPROFILE/.dotnet/tools" "$HOME/.dotnet/tools"; do
+  [ -d "$TOOLS_DIR" ] && export PATH="$TOOLS_DIR:$PATH"
+done
+```
+
+### WSL git path repair
+
+Worktrees on Windows sometimes store `.git` with a Windows path inside WSL
+(`gitdir: C:\...`). When git commands run from WSL this breaks. Before any
+`git` command, if the worktree has a `.git` file (not directory) and it
+starts with `gitdir: ` + a drive letter, rewrite it:
+
+```bash
+if [ -f .git ] && grep -q '^gitdir: [A-Za-z]:' .git; then
+  p=$(sed 's/^gitdir: //' .git | tr -d '\r\n')
+  printf 'gitdir: %s\n' "$(realpath -m --relative-to="$(pwd)" "/mnt/$(echo ${p:0:1} | tr '[:upper:]' '[:lower:]')${p:2//"\\"/"/}")" > .git
+fi
+```
+
+The Studio runs on Windows bash, so this rarely matters in practice, but
+keep the snippet handy if you hit "not a git repository" errors.
+
+## 4. Install `dotnet-ef`
+
+If `dotnet-ef` is missing:
+
+```bash
+dotnet tool install --global dotnet-ef --version 10.0.*
+```
+
+EF Core 10 is required to match the Studio sidecar and the apps generated
+by SmartStack. The `list` / `status` CLIs both emit a warning when the
+tool isn't found; `create` / `squash` / `rebase-snapshot` refuse to run.
+
+## 5. Backups
+
+`cli/squash/` and `cli/rebase-snapshot/` write a backup before deleting
+anything. The backup directory is:
+
+```
+{cwd}/.efcore-squash-backup/<ISO-timestamp>/<AssemblyName>/<relativePath>
+```
+
+If a squash fails, restore by copying files back:
+
+```bash
+cp -r .efcore-squash-backup/<timestamp>/<AssemblyName>/* .
+```
+
+The `.efcore-squash-backup/` directory is **not** gitignored by default —
+add it to `.gitignore` if you want to keep it out of commits.
+
+## 6. Dry-run everything
+
+Every mutating CLI accepts `"dryRun": true` in its spec. The output lists
+what WOULD happen without touching the worktree. Use this from the
+Studio's MigrationsTab before firing the real command, and inside agent
+prompts when you want to preview a destructive step.
+
+## 7. Workflow summary
+
+```
+feature branch created
+    ↓
+agents/create.md  → core_v1.8.0_001_AddUserRoles.cs
+    ↓ (commit, push, review)
+    ↓ (rebase onto develop — snapshot conflict)
+agents/rebase-snapshot.md  → reset snapshot, regenerate one migration
+    ↓ (ready to merge)
+agents/squash.md  → collapse N branch migrations into 1
+    ↓ (merge to develop)
+develop
+    ↓
+agents/db-update.md  → apply pending migrations to local dev DB
+```

package/templates/skills/efcore/agents/create.md

@@ -0,0 +1,69 @@
+# Agent — Create a new migration
+
+Read `_shared.md` first.
+
+## Goal
+
+Scaffold a new EF Core migration against the correct DbContext, with a name
+that follows the SmartStack convention. Every migration belongs to one
+feature — do not mix concerns.
+
+## Inputs
+
+- `cwd` — worktree path.
+- `contextName` — the target DbContext. Pick it from `list` output if not
+  known; confirm with the user when multiple contexts are available.
+- `description` — short, intent-revealing summary in PascalCase or free
+  prose. The CLI normalizes it (`add employee avatar` → `AddEmployeeAvatar`).
+
+Optional:
+
+- `assembly` — when the context has multiple migration assemblies (Studio
+  Sqlite / Postgres / SqlServer), you can target a single one.
+- `allProviders` — default `true` for multi-assembly contexts; runs the
+  migration add in every assembly.
+- `dryRun` — produces the computed name and command without touching the
+  worktree.
+
+## Steps
+
+1. Invoke the CLI — always pass `dryRun: true` first to preview the name:
+
+   ```bash
+   npx tsx skills/efcore/cli/create/index.ts --spec '{
+     "cwd": "<WORKTREE>",
+     "contextName": "CoreDbContext",
+     "description": "AddEmployeeAvatar",
+     "dryRun": true
+   }'
+   ```
+
+2. Show the proposed name to the user. Confirm before re-running without
+   `dryRun`.
+
+3. Invoke the real create:
+
+   ```bash
+   npx tsx skills/efcore/cli/create/index.ts --spec '{
+     "cwd": "<WORKTREE>",
+     "contextName": "CoreDbContext",
+     "description": "AddEmployeeAvatar"
+   }'
+   ```
+
+4. Read the output. For each assembly, the result contains:
+   - `success`
+   - `migrationName`
+   - `filesCreated` (three paths: `.cs`, `.Designer.cs`, snapshot)
+
+5. Remind the user to `dotnet build` the solution and to review the
+   generated migration Up/Down methods before committing.
+
+## What NOT to do
+
+- Never run `dotnet ef migrations add` directly — always go through the
+  CLI so naming stays consistent.
+- Never bundle two unrelated changes into one migration. One feature =
+  one migration.
+- Never edit the generated `.cs` file to rename the migration — redo it
+  via the CLI if the name is wrong.

package/templates/skills/efcore/agents/db-update.md

@@ -0,0 +1,58 @@
+# Agent — Apply migrations to the database
+
+Read `_shared.md` first. There is **no** CLI colocated with this agent —
+`dotnet ef database update` is straightforward enough that the agent just
+runs it directly with the correct parameters.
+
+## Goal
+
+Apply every pending migration to the local development database. Always
+preview the SQL first with `--idempotent` so the user sees exactly what
+will run.
+
+## Steps
+
+1. Run `status` to see pending migrations:
+
+   ```bash
+   npx tsx skills/efcore/cli/status/index.ts --spec '{"cwd":"<WORKTREE>"}'
+   ```
+
+   If no assembly has `pending > 0`, stop — database is up to date.
+
+2. For each assembly with pending migrations, dump the idempotent script:
+
+   ```bash
+   dotnet ef migrations script --idempotent \
+     --project <csproj> \
+     --context <contextName> \
+     --startup-project <startup> \
+     -o pending-migrations.sql
+   ```
+
+   Show the user the path; they can inspect the SQL before applying.
+
+3. Apply:
+
+   ```bash
+   dotnet ef database update \
+     --project <csproj> \
+     --context <contextName> \
+     --startup-project <startup>
+   ```
+
+4. Core before Extensions (dual-context apps): always update `CoreDbContext`
+   first, then `ExtensionsDbContext`. Extensions may have foreign keys into
+   Core and the reverse order leaves Extensions broken.
+
+5. For the Studio's multi-provider context (`StudioDbContext`), the user
+   picks which provider is active (see `~/.smartstack/config.json`).
+   Update only the matching assembly — the other two are dormant until
+   the user switches providers.
+
+## What NOT to do
+
+- Never run `database update` against a production / staging DB from this
+  agent. The agent is scoped to local dev only.
+- Never skip the idempotent script — it is the user's last chance to
+  catch a destructive migration before it runs.