docs: update AI docs for embed.FS migration fix (ADR-030)

- status.md: add entry #27 documenting the embed migration fix
- todo.md: add critical bug entry for plugin migrations in Docker
- decisions.md: add ADR-030 (Embed Plugin Migrations via embed.FS)
- conventions.md: update migration section with embed.FS pattern
- architecture.md: add embed.go, migrations/, plugin_schema.go to structure

https://claude.ai/code/session_01QJLkgjQDu5qohzJKGV4hj9

Author: claude

.ai/architecture.md

@@ -94,9 +94,11 @@ chronicle/
 │   ├── config/                       # CORE: Configuration loading (env vars)
 │   │   └── config.go
 │   │
-│   ├── database/                     # CORE: Database connections
+│   ├── database/                     # CORE: Database connections + migrations
 │   │   ├── mariadb.go                #   MariaDB connection pool
-│   │   └── redis.go                  #   Redis client
+│   │   ├── redis.go                  #   Redis client
+│   │   ├── plugin_schema.go          #   Plugin migration runner (reads embed.FS)
+│   │   └── plugin_health.go          #   Plugin health registry
 │   │
 │   ├── middleware/                    # CORE: HTTP middleware
 │   │   ├── auth.go                   #   Session validation
@@ -220,6 +222,7 @@ Every plugin follows this exact structure. No exceptions.
 ```
 internal/plugins/<name>/
   .ai.md              # Plugin-level AI documentation
+  embed.go            # Embeds migrations/*.sql via Go embed.FS (ADR-030)
   handler.go          # Echo handlers (thin: bind, call service, render)
   handler_test.go     # Handler tests (HTTP-level, mock service)
   service.go          # Business logic (never imports Echo types)
@@ -228,6 +231,9 @@ internal/plugins/<name>/
   repository_test.go  # Repository tests (integration, real DB)
   model.go            # Domain models, DTOs, request/response structs
   routes.go           # Route registration function
+  migrations/         # Plugin-specific schema migrations (embedded in binary)
+    001_*.up.sql
+    001_*.down.sql
   templates/          # Templ components for this plugin
     index.templ       #   List view
     show.templ        #   Detail view

.ai/conventions.md

@@ -253,8 +253,11 @@ Chronicle uses a **plugin-isolated database schema architecture**:
 - **Core schema** (`db/migrations/`): Single baseline migration with all core tables.
   Runs via golang-migrate on startup. Failure is fatal.
 - **Plugin schema** (`internal/plugins/<name>/migrations/`): Each built-in plugin
-  has its own numbered migration files. Runs via `RunPluginMigrations()` after core
-  migrations. Failure disables that plugin; app continues serving.
+  has its own numbered migration files **embedded in the binary** via Go's `embed.FS`
+  (ADR-030). Each plugin has an `embed.go` exporting `MigrationsFS`. Runs via
+  `RunPluginMigrations()` after core migrations. Failure disables that plugin; app
+  continues serving. `RegisteredPlugins()` lives in `cmd/server/main.go` (not in
+  the database package) to avoid import cycles.
 
 ```sql
 -- Core migration example: db/migrations/000001_baseline.up.sql
@@ -280,6 +283,9 @@ CREATE TABLE IF NOT EXISTS calendars ( ... );
    in migration SQL. Update the valid sets there when adding new ENUM values.
 6. **Plugin tables**: Plugin tables belong in `internal/plugins/<name>/migrations/`,
    not in `db/migrations/`. Plugin schema failures degrade gracefully (ADR-028).
+   Migrations are embedded in the binary via `embed.FS` (ADR-030). When adding a
+   new plugin with migrations, create an `embed.go` in the plugin package and
+   register it in `registeredPlugins()` in `cmd/server/main.go`.
 
 ### Permission Model
 

.ai/decisions.md

@@ -1050,3 +1050,42 @@ capabilities. Non-owners could see features but couldn't tell which were enabled
 - Single source of truth for feature management.
 - Owners can manage features directly from the same page all members see.
 - Future enhancements (per-addon entity usage, "offline" banners) have one target page.
+
+---
+
+## ADR-030: Embed Plugin Migrations via Go embed.FS
+
+**Date:** 2026-03-11
+**Status:** Accepted (amends ADR-028)
+
+**Context:** ADR-028 introduced per-plugin migration directories at
+`internal/plugins/<name>/migrations/`. The migration runner used `os.Stat` and
+`os.ReadDir` with relative filesystem paths. This worked in development (CWD =
+project root) but failed silently in Docker: the runtime image copies the binary
+to `/app` but never copies plugin migration directories. Since `os.Stat` returned
+`os.IsNotExist`, the runner treated each plugin as "healthy with 0 migrations"
+— no tables were created, entity pages crashed, and the DB Explorer showed 0/0.
+
+**Decision:** Embed plugin migration SQL files in the binary using Go's `embed.FS`:
+- Each plugin package gets an `embed.go` that exports `MigrationsFS embed.FS`
+  with `//go:embed migrations/*.sql`.
+- `PluginSchema.MigrationsDir` (string) replaced with `MigrationsFS` (`fs.FS`).
+- `parsePluginMigrations` and `LatestMigrationVersion` read from `fs.FS` instead
+  of the real filesystem.
+- `RegisteredPlugins()` moved from `database` package to `cmd/server/main.go`
+  to avoid import cycles (database can't import plugin packages). Uses `fs.Sub`
+  to strip the `migrations/` prefix from each embed.FS.
+- `PluginSchemas` stored on `App` struct and passed to `DatabaseExplorer` for
+  on-demand re-migration from the admin panel.
+
+**Alternatives considered:**
+- Copy plugin migration dirs to Docker runtime image: fragile, requires syncing
+  Dockerfile whenever plugins are added/removed. Still fails if CWD changes.
+- Centralise all plugin migrations in one directory: loses per-plugin isolation
+  that ADR-028 established.
+
+**Consequences:**
+- Migrations work in any environment regardless of working directory.
+- No Dockerfile changes needed when adding new plugins with migrations.
+- Each plugin must have an `embed.go` exporting its `MigrationsFS`.
+- `RegisteredPlugins()` now lives in `cmd/server/main.go` instead of `database`.

.ai/status.md

@@ -10,6 +10,11 @@
 ## Last Updated
 2026-03-11 -- **Sprint W-0.5: Visual Customization + Admin DB Explorer (IN PROGRESS).**
 
+27. **Fix: Embed plugin migrations in binary (ADR-030).** Root cause of entity page errors and DB Explorer showing 0/0: plugin migrations used relative filesystem paths (`internal/plugins/*/migrations/`) that only resolve when the binary's CWD is the project root. In Docker, the binary runs from `/app` so migration directories were never found, tables were never created, and entity pages crashed. Fix: each plugin now embeds its `migrations/*.sql` via Go's `embed.FS`. `PluginSchema.MigrationsDir` (string) replaced with `MigrationsFS` (`fs.FS`). `RegisteredPlugins()` moved from `database` package to `cmd/server/main.go` to avoid import cycles (database can't import plugin packages). `PluginSchemas` stored on `App` struct and passed to `DatabaseExplorer` for on-demand re-migration. New `embed.go` files in calendar, maps, sessions, timeline, syncapi plugins.
+
+### Previous Update
+2026-03-11 -- **Sprint W-0.5: Visual Customization + Admin DB Explorer (IN PROGRESS).**
+
 26. Admin Database Explorer: New `/admin/database` page with interactive D3.js schema diagram showing all tables, FK relationships, plugin grouping, and migration status. Table detail panel on click. "Apply Pending Migrations" button (fixes sessions table missing issue). Removed "Manual DB Record (Advanced)" form from Features page. New files: `database_service.go` (info_schema introspection), `database.templ`, `db_explorer.js` widget. Added `LatestMigrationVersion()` to database package. Dashboard card + sidebar link.
 
 ### Previous Update

.ai/todo.md

@@ -16,6 +16,7 @@ Known broken or missing things, ordered by severity.
 ### Critical
 
 - [x] **Public campaign widget 403s** — Editor and attributes widgets return 403 for non-member visitors on public campaigns. Root cause: GET `/entry`, `/fields`, `/tags`, `/relations` only registered in authenticated route group, not in public-capable group. Fixed by adding routes to `pub` group in entities/routes.go, tags/routes.go, relations/routes.go.
+- [x] **Plugin migrations not applied in Docker (entity page errors, 0/0 in DB Explorer)** — Plugin migrations used relative filesystem paths (`internal/plugins/*/migrations/`) that only resolve when CWD is the project root. In Docker, binary runs from `/app` so dirs were never found, tables never created, entity pages crashed on missing tables, and DB Explorer showed 0/0 for all plugins. Fixed by embedding migrations in the binary via Go's `embed.FS` (ADR-030). Each plugin now has `embed.go` exporting `MigrationsFS`. `PluginSchema.MigrationsDir` replaced with `MigrationsFS` (`fs.FS`).
 
 ### High