@mriekki/lean 0.4.1 → 0.4.3

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "defaultProfile": "greenfield-poc",
   "profiles": {
     "greenfield-poc": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "7d6b6ce00d83063775d7491626fe6b253b9c51c8",
+      "commit": "1420caf15d5c078af8800f35966b47836b6da99f",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "4e52b74e1f23829e37b5f16ac03ada124621ffa0",
+      "commit": "2763e604c20e64720d7de71fa93a88d99677be36",
       "distribution": "greenfield-poc",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/core/distribution.json

@@ -24,6 +24,7 @@
     {"source":"core/skills/deploy/SKILL.md","destination":".github/skills/deploy/SKILL.md"},
     {"source":"core/skills/tear-down/SKILL.md","destination":".github/skills/tear-down/SKILL.md"},
     {"source":"core/skills/coach/SKILL.md","destination":".github/skills/coach/SKILL.md"},
+    {"source":"core/skills/db-lab/SKILL.md","destination":".github/skills/db-lab/SKILL.md"},
     {"source":"core/skills/code-walkthrough/SKILL.md","destination":".github/skills/code-walkthrough/SKILL.md"},
     {"source":"core/skills/learning-review/SKILL.md","destination":".github/skills/learning-review/SKILL.md"},
     {"source":"core/process/WORK_ITEM_MODEL.md","destination":"docs/process/WORK_ITEM_MODEL.md"},
@@ -33,6 +34,7 @@
     {"source":"core/process/GUIDED_NEXT_STEPS.md","destination":"docs/process/GUIDED_NEXT_STEPS.md"},
     {"source":"core/process/INTERACTIVE_SESSION_GUIDE.md","destination":"docs/process/INTERACTIVE_SESSION_GUIDE.md"},
     {"source":"core/process/COACHING_GUIDE.md","destination":"docs/process/COACHING_GUIDE.md"},
+    {"source":"core/process/DATABASE_LEARNING_WORKBENCH.md","destination":"docs/process/DATABASE_LEARNING_WORKBENCH.md"},
     {"source":"core/process/SETUP_ACCEPTANCE_CHECKLIST.md","destination":"docs/process/SETUP_ACCEPTANCE_CHECKLIST.md"},
     {"source":"core/templates/PULL_REQUEST_TEMPLATE.md","destination":".github/PULL_REQUEST_TEMPLATE.md"},
     {"source":"core/templates/PRODUCT_BRIEF_TEMPLATE.md","destination":"docs/templates/PRODUCT_BRIEF_TEMPLATE.md"},
@@ -46,6 +48,7 @@
     {"source":"core/learning/SYSTEM_DESIGN_DRILLS.md","destination":"learning/SYSTEM_DESIGN_DRILLS.md"},
     {"source":"core/learning/DIAGRAM_GUIDE.md","destination":"learning/DIAGRAM_GUIDE.md"},
     {"source":"core/learning/RESOURCE_CATALOG.md","destination":"learning/RESOURCE_CATALOG.md"},
+    {"source":"tools/db_lab/sqlite_workbench.py","destination":"tools/lean-db-lab/sqlite-workbench.py"},
     {"source":"tools/package/check_baseline.py","destination":"tools/lean-core/check-core-baseline.py"},
     {"source":"tools/package/check_upstream.py","destination":"tools/lean-core/check-core-upstream.py"}
   ]

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "7d6b6ce00d83063775d7491626fe6b253b9c51c8",
+      "commit": "1420caf15d5c078af8800f35966b47836b6da99f",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -117,7 +117,12 @@
         {
           "source": "core/skills/coach/SKILL.md",
           "destination": ".github/skills/coach/SKILL.md",
-          "sha256": "123983c51bd2d9958d8a6593101dc57eb6e4974cc9678d17c434ac61d29e4378"
+          "sha256": "9a15c5876b6dcaaa5157c65c28f797302bd3f869048261f0d070904713b239e7"
+        },
+        {
+          "source": "core/skills/db-lab/SKILL.md",
+          "destination": ".github/skills/db-lab/SKILL.md",
+          "sha256": "6c7868002b7408215e20807a427213b1d5a15473379c91396e8757a50a1be947"
         },
         {
           "source": "core/skills/code-walkthrough/SKILL.md",
@@ -162,7 +167,12 @@
         {
           "source": "core/process/COACHING_GUIDE.md",
           "destination": "docs/process/COACHING_GUIDE.md",
-          "sha256": "0ccadef39db53f85a5092cb4d1343ed3c1fe13291291afd33c59d5a60fd22905"
+          "sha256": "afe5d77028768d5a2d47cad94dc3436f368b94c22d87fe9a36fa0fdcaa5c461f"
+        },
+        {
+          "source": "core/process/DATABASE_LEARNING_WORKBENCH.md",
+          "destination": "docs/process/DATABASE_LEARNING_WORKBENCH.md",
+          "sha256": "8db2008cce0fd1b63aea27c1e47ab2c96ad380a2f80cc9be1743c3961d86d0a7"
         },
         {
           "source": "core/process/SETUP_ACCEPTANCE_CHECKLIST.md",
@@ -192,12 +202,12 @@
         {
           "source": "core/learning/ENGINEERING_LEARNING_WORKBOOK.md",
           "destination": "learning/ENGINEERING_LEARNING_WORKBOOK.md",
-          "sha256": "fd9d6b3561c5d433be4a58ad2d8c74f30e2c831d7de6cd7296a1b3f8999c55da"
+          "sha256": "e46909fe4b88cf1b617b9eb1f9b8cd1d78b9332e9c8825bd6e6021aadcd99552"
         },
         {
           "source": "core/learning/LEARNING_MAP.md",
           "destination": "learning/LEARNING_MAP.md",
-          "sha256": "48985521dd22213add526910ead486db2ca54e88533d49bd35cd6bcda5f92180"
+          "sha256": "172385b97c4fd41c08bc5344e29d026e48950b7bf98e9225288ab254b51ea9e0"
         },
         {
           "source": "core/learning/LEARNING_PROGRESS.md",
@@ -212,7 +222,7 @@
         {
           "source": "core/learning/SQL_DRILLS.md",
           "destination": "learning/SQL_DRILLS.md",
-          "sha256": "22075d135afbee73aabb11a33077946a0444362ff3f678495386b0996da6a95c"
+          "sha256": "696b9c97d3c1bd7adc7be1a43dcd655056bbf55ab58bc7741c59225d52f8c239"
         },
         {
           "source": "core/learning/SYSTEM_DESIGN_DRILLS.md",
@@ -229,6 +239,11 @@
           "destination": "learning/RESOURCE_CATALOG.md",
           "sha256": "88fc894dd51da7280aabd3df439bcbda337f437ece43640d86dfc0842dd0f91e"
         },
+        {
+          "source": "tools/db_lab/sqlite_workbench.py",
+          "destination": "tools/lean-db-lab/sqlite-workbench.py",
+          "sha256": "a5bb99a3f67f88f00b99c10b2c0698710b6b2fa302becc6ff3435c4321cdd4d3"
+        },
         {
           "source": "tools/package/check_baseline.py",
           "destination": "tools/lean-core/check-core-baseline.py",
@@ -243,7 +258,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "4e52b74e1f23829e37b5f16ac03ada124621ffa0",
+      "commit": "2763e604c20e64720d7de71fa93a88d99677be36",
       "distribution": "greenfield-poc",
       "files": [
         {
@@ -324,7 +339,7 @@
         {
           "source": "src/lean_poc_deployment/registry_access.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/registry_access.py",
-          "sha256": "daab56f3a09a11f61e12c4da62fef44b068f1b71172ba68ecf71837bbc0d1af3"
+          "sha256": "5815a1921ecf37dc395f9c68b1ebda2b17dd6a44620b2356d1adff5df44c4382"
         },
         {
           "source": "src/lean_poc_deployment/registry_cli.py",

package/assets/generated/core/core/learning/ENGINEERING_LEARNING_WORKBOOK.md

@@ -12,10 +12,13 @@ Use the learning tools for different purposes:
 /code-walkthrough — instructional walkthrough of actual implementation changes
 /learning-review   — assessment of whether the developer can explain and defend the implementation
 /coach             — targeted concept learning, debugging practice, design discussion, drills, and deeper follow-up
+/db-lab            — evidence-backed database/schema/ORM/query-plan exploration and database interview practice
 ```
 
 All learning activity is optional and never an engineering delivery gate.
 
+For database usage examples, see `docs/process/DATABASE_LEARNING_WORKBENCH.md` in a greenfield consumer.
+
 ## Preferred project-first sequence
 
 When an implementation is stable enough to study, a useful optional sequence is:
@@ -24,7 +27,7 @@ When an implementation is stable enough to study, a useful optional sequence is:
 implementation
 → /code-walkthrough
 → /learning-review
-→ targeted /coach follow-up where gaps remain
+→ targeted /coach or /db-lab follow-up where gaps remain
 ```
 
 A code walkthrough should connect two views of every meaningful change:

package/assets/generated/core/core/learning/LEARNING_MAP.md

@@ -28,6 +28,26 @@ L5 Defend / Design
 L6 Interview Ready
 ```
 
+## Database learning is multi-dimensional
+
+Do not reduce database learning to one "SQL" level. When database depth matters, assess the relevant areas independently:
+
+```text
+relational modeling
+keys + integrity constraints
+normalization + anomalies
+SQL query construction
+indexes + access patterns
+query plans + performance reasoning
+transactions + concurrency
+ORM translation
+schema evolution + migrations
+database debugging
+design defense / interview communication
+```
+
+Use `/db-lab` for evidence-backed exploration of the current project's schema, queries, ORM translation, query plans, migrations, and query-to-ERD relationships. Use `/coach` for adaptive teaching and reinforcement.
+
 ## How real-code learning maps to the levels
 
 A structured `/code-walkthrough` is especially useful for the first three levels:
@@ -46,6 +66,8 @@ L5 Defend / Design — explain choices, alternatives, tradeoffs, and architectur
 L6 Interview Ready — explain the implementation clearly under follow-up questioning
 ```
 
+For database work, L4-L6 should include evidence-based reasoning about schema choices, constraints, access patterns, indexes/plans, transactions, ORM behavior, migration safety, and credible alternatives where relevant.
+
 Use `/learning-review` to assess understanding after a walkthrough. Use `/coach` for targeted reinforcement, practice, or deeper exploration. These activities are optional and do not affect engineering delivery state.
 
 Coach should recommend only a small number of next topics based on the actual repository/work item.

package/assets/generated/core/core/learning/SQL_DRILLS.md

@@ -1,27 +1,90 @@
-# SQL / Database Drills
+# SQL / Database Learning and Drills
 
-Optional practice areas:
+Use the actual repository and domain whenever possible. SQL syntax is only one database competency; do not let query fluency hide weak relational design, indexing, transaction, or ORM reasoning.
 
-- joins,
-- aggregates,
-- GROUP BY/HAVING,
-- pagination,
-- deterministic sorting,
-- indexes,
-- query plans,
-- constraints,
-- transactions,
-- concurrency,
-- N+1,
-- ORM translation.
+For evidence-backed hands-on exploration use `/db-lab`. For adaptive explanation, questioning, and reinforcement use `/coach`.
 
-Preferred flow:
+## Competencies
+
+Assess independently using the common L1-L6 learning levels:
+
+- relational modeling and cardinality;
+- primary/foreign/candidate keys and integrity constraints;
+- normalization, anomalies, and deliberate denormalization;
+- query construction: joins, aggregates, GROUP BY/HAVING, subqueries/CTEs, pagination, deterministic sorting;
+- indexes and access-pattern reasoning;
+- query-plan interpretation and performance diagnosis;
+- transactions, isolation, concurrency, and failure behavior;
+- ORM translation, N+1 behavior, tracking/materialization, and abstraction leaks;
+- schema evolution and migration safety;
+- database debugging;
+- design defense and interview communication.
+
+## Query drill
 
 ```text
 problem
-→ developer writes SQL
+→ developer writes/predicts SQL
 → correctness
 → edge cases
+→ access pattern
 → indexing/query-plan follow-up
-→ ORM discussion
+→ ORM translation when useful
+→ interview-style defense when useful
+```
+
+Do not reveal the complete query immediately unless the developer asks for explanation-first teaching.
+
+## Design drill
+
+```text
+requirements
+→ entities
+→ relationships/cardinality
+→ keys
+→ constraints
+→ normalization
+→ expected queries
+→ indexes
+→ transactions/concurrency
+→ migration/evolution concerns
+→ defend tradeoffs
+```
+
+Prefer practical anomaly questions over memorized normalization definitions.
+
+## Debugging drill
+
+```text
+symptom
+→ hypotheses
+→ SQL + parameters
+→ plan / constraints / transaction evidence
+→ root cause
+→ fix concept
+→ prevention
 ```
+
+Use provider-native plan evidence where available and distinguish candidate indexes from indexes actually selected by the planner.
+
+## ORM drill
+
+Trace both directions:
+
+```text
+ORM/LINQ expression → generated/captured SQL → plan → result materialization
+SQL/schema constraint → ORM behavior/error → application-visible effect
+```
+
+When a framework exposes both a translation preview and actual executed commands, keep them distinct.
+
+## Suggested interview prompts
+
+- Model a many-to-many relationship that later needs attributes on the relationship itself.
+- Explain where uniqueness, nullability, and referential-integrity rules should be enforced.
+- Given three common queries, design only the indexes you can justify.
+- Diagnose why a query performs a scan instead of the expected indexed search.
+- Explain an N+1 problem and two credible fixes with tradeoffs.
+- Design a safe migration from nullable to required data.
+- Define a transaction boundary for a multi-table operation and discuss concurrency failure modes.
+- Defend when a surrogate key is preferable to a natural/composite key and when it is not.

package/assets/generated/core/core/process/COACHING_GUIDE.md

@@ -33,6 +33,8 @@ For a structured walkthrough of an implementation change set, use `/code-walkthr
 
 Use `/coach` for broader or ad-hoc concept learning. Use `/learning-review` when the primary goal is to assess whether the developer can explain and defend what was built.
 
+For hands-on database learning, `/db-lab` is the evidence-backed companion to Coach. Coach can teach database concepts, probe gaps, and run interview drills; Database Lab inspects the actual project schema/ORM/query/migration/query-plan evidence and can drive query-to-ERD highlighting when an interactive workbench is installed. See `DATABASE_LEARNING_WORKBENCH.md` for quick-start commands and examples.
+
 ## Levels
 
 ```text
@@ -49,7 +51,7 @@ A useful optional sequence after stable implementation is:
 ```text
 code walkthrough
 → learning review
-→ targeted coaching as needed
+→ targeted coaching / database lab as needed
 ```
 
 None of those learning activities is an engineering delivery gate.

package/assets/generated/core/core/process/DATABASE_LEARNING_WORKBENCH.md

@@ -0,0 +1,346 @@
+# Database Learning Workbench
+
+The Database Learning Workbench is the reusable Lean learning contract behind `/db-lab`. It makes database behavior that frameworks and ORMs often hide visible enough to inspect, explain, debug, and defend.
+
+It is project-aware rather than a generic SQL course: use the current repository's domain, schema, migrations, ORM mappings, queries, and safe development/test database evidence as the curriculum.
+
+Learning remains optional and never changes engineering delivery state.
+
+## Quick start
+
+Use `/coach` for explanation, adaptive questioning, and gap assessment. Use `/db-lab` when the learning needs concrete database evidence.
+
+```text
+/coach database design
+/db-lab schema
+/db-lab trace <query/file/symbol>
+/db-lab plan <query>
+/db-lab debug <symptom/query>
+/db-lab migration <migration>
+/db-lab interview database
+```
+
+Natural-language arguments are preferred over rigid syntax. Examples:
+
+```text
+/db-lab show me how Recipes and Ingredients are related
+/db-lab trace the EF query used by GetWeeklyMealPlan
+/db-lab why is this query scanning MealPlanItems
+/db-lab show which indexes this query actually uses
+/db-lab walk me through the latest migration without applying it
+/db-lab give me a database-design interview based on this domain
+```
+
+## SQLite interactive workbench — V1
+
+Greenfield consumers that include the Core learning payload receive:
+
+```text
+tools/lean-db-lab/sqlite-workbench.py
+```
+
+The tool is dependency-free Python and opens SQLite databases read-only. It generates a self-contained interactive `index.html` and a machine-readable `workbench.json`.
+
+### PowerShell example
+
+From the repository root, using a known development/test SQLite file:
+
+```powershell
+$out = Join-Path $env:TEMP "lean-db-lab"
+python .\tools\lean-db-lab\sqlite-workbench.py export `
+  --db .\.data\app.db `
+  --out $out
+Start-Process (Join-Path $out "index.html")
+```
+
+Use the actual project database path; `.data/app.db` is only an example. Do not point the learning tool at Production data.
+
+### macOS/Linux example
+
+```bash
+out="${TMPDIR:-/tmp}/lean-db-lab"
+python3 tools/lean-db-lab/sqlite-workbench.py export \
+  --db .data/app.db \
+  --out "$out"
+open "$out/index.html"  # macOS; use the local browser command appropriate to the environment
+```
+
+### Add query-to-ERD evidence
+
+Create a disposable query-evidence JSON file from captured or otherwise verified SQL:
+
+```json
+[
+  {
+    "name": "Get weekly meal plan",
+    "sql": "SELECT r.Id, r.Name FROM MealPlanItems mpi JOIN Recipes r ON r.Id = mpi.RecipeId WHERE mpi.MealPlanId = :mealPlanId",
+    "parameters": {
+      "mealPlanId": 42
+    }
+  }
+]
+```
+
+Then regenerate the workbench:
+
+```powershell
+$out = Join-Path $env:TEMP "lean-db-lab"
+python .\tools\lean-db-lab\sqlite-workbench.py export `
+  --db .\.data\app.db `
+  --queries .\tmp\db-lab-queries.json `
+  --out $out
+Start-Process (Join-Path $out "index.html")
+```
+
+The query-evidence file and generated workbench are learning artifacts. Keep them disposable/local unless the project explicitly chooses to make a sanitized artifact durable.
+
+### What the V1 viewer shows
+
+The SQLite V1 workbench supports:
+
+- tables and views;
+- columns, types, nullability, and primary-key participation;
+- foreign-key relationships and delete/update actions;
+- indexes, uniqueness, origin, partial-index status, key columns, and stored DDL when available;
+- junction-table candidates, clearly labeled as a heuristic rather than domain truth;
+- clickable tables, columns, and indexes with a learning/details panel;
+- query selection and highlighting of referenced tables;
+- highlighting of relationship edges when both related tables participate in the selected query;
+- highlighting of qualified query columns when resolvable;
+- `EXPLAIN QUERY PLAN` evidence for parameterized `SELECT`/`WITH` queries;
+- a distinction between indexes selected by the planner and indexes that are merely plausible candidates/relevant to highlighted columns.
+
+The viewer does not claim to understand arbitrary SQL perfectly. SQL-to-table/column mapping includes heuristic parsing, while planner-selected indexes come from SQLite's own query-plan evidence.
+
+## What to expect from `/db-lab`
+
+A useful Database Lab session follows evidence rather than guesses:
+
+```text
+repository intent
+→ ORM model
+→ physical schema
+→ query / executed SQL
+→ query plan
+→ indexes / constraints / transaction behavior
+→ explanation or exercise
+```
+
+The exact evidence depends on the stack. The lab should explicitly state which layers were verified and which were inferred.
+
+## Example 1 — explore the schema
+
+Prompt:
+
+```text
+/db-lab schema
+```
+
+Expected learning flow:
+
+1. Identify the configured development/test database and relevant ORM/migration artifacts.
+2. Build the table/entity/relationship picture from safe evidence.
+3. Show primary keys, foreign keys, nullability, constraints, and indexes.
+4. Explain important relationship cardinalities.
+5. Compare Domain Model, ORM Model, and Physical Model where they differ.
+6. Ask one or two high-value questions, such as why a junction table exists or what invariant belongs in the database.
+
+With SQLite, use the distributed workbench when a safe local database is available. Selecting an index should explain its columns, uniqueness, how SQLite created it, and whether the active query plan actually selected it.
+
+## Example 2 — Entity Framework to raw SQL
+
+Suppose application code contains:
+
+```csharp
+var recipes = await db.Recipes
+    .Include(r => r.Ingredients)
+    .Where(r => r.IsFavorite)
+    .OrderBy(r => r.Name)
+    .ToListAsync();
+```
+
+Prompt:
+
+```text
+/db-lab trace this EF query
+```
+
+The lab should connect:
+
+```text
+LINQ / EF expression
+→ translation preview when available
+→ captured executed SQL when available
+→ parameters
+→ tables and relationships
+→ provider query plan
+→ indexes selected by the planner
+→ result materialization
+```
+
+Important teaching point: a translation preview and an actually executed command are different kinds of evidence. Label them separately.
+
+For EF Core, `ToQueryString()` can help inspect translation. Framework-supported command logging/interception can provide evidence of the actual `DbCommand`. The SQLite workbench consumes captured SQL; it does not replace EF command capture.
+
+## Example 3 — query-to-ERD highlighting
+
+Prompt:
+
+```text
+/db-lab trace GetWeeklyMealPlan and show it on the ERD
+```
+
+For a query that touches `MealPlans`, `MealPlanItems`, and `Recipes`, the workbench highlights those tables. If both ends of an FK relationship participate, the corresponding relationship edge is emphasized. Qualified columns found in the query are highlighted in their table cards.
+
+If `EXPLAIN QUERY PLAN` shows an index was actually used, the viewer marks it as **planner selected**. If an index's leading column matches highlighted query columns but the planner did not select it, the viewer can mark it as a **candidate/relevant** index without claiming usage.
+
+Selecting a table, column, or index opens a learning/details panel. The query panel shows the captured SQL and SQLite plan details alongside the ERD.
+
+If the interactive viewer is unavailable, use a temporary Mermaid/text diagram and explain that the rich query-to-ERD interaction is unavailable in the current checkout.
+
+## Example 4 — query-plan debugging
+
+Prompt:
+
+```text
+/db-lab why is this query slow?
+```
+
+Preferred learning sequence:
+
+```text
+show query/access pattern
+→ developer predicts plan/index behavior
+→ inspect provider-native plan
+→ identify scan/search/join evidence
+→ developer proposes a change
+→ predict the changed plan
+→ compare safely when a sandbox is available
+```
+
+For SQLite, the V1 workbench uses `EXPLAIN QUERY PLAN` for `SELECT`/`WITH` queries when supplied parameters are sufficient. A learning session should connect `SCAN`/`SEARCH` behavior to concrete predicates, joins, ordering, and available indexes rather than simply recommending more indexes.
+
+## Example 5 — migration review
+
+Prompt:
+
+```text
+/db-lab migration AddRecipeRatings
+```
+
+The lab should show, when available:
+
+```text
+migration intent
+↔ migration/ORM operations
+↔ generated SQL/DDL
+↔ schema before
+↔ schema after
+↔ data-safety concerns
+```
+
+Useful questions include:
+
+- Is existing data compatible with a new non-null column?
+- Is a backfill required?
+- Does a new uniqueness constraint match the domain invariant?
+- Is a table rebuild or destructive operation involved?
+- What rollback limitations exist?
+
+Do not apply the migration in Database Lab mode.
+
+## Example 6 — database-design interview
+
+Prompt:
+
+```text
+/db-lab interview database
+```
+
+The interviewer should use the project domain for familiarity but change requirements so memorizing the existing schema does not solve the exercise.
+
+Example follow-ups:
+
+```text
+Why does this many-to-many relationship need an associative table?
+Could the two foreign keys be the primary key? What requirement would break that design?
+Which invariants belong in database constraints rather than application validation?
+What queries justify this index?
+What happens to historical records if the parent entity is deleted?
+How would this design change if multiple users edit the same aggregate concurrently?
+```
+
+Use the standard L1-L6 learning levels, but assess database competencies independently. SQL syntax skill must not hide weak schema-design or indexing reasoning.
+
+## Database competency model
+
+```text
+Relational modeling             entities, relationships, cardinality
+Keys + integrity                PK/FK/unique/check/nullability choices
+Normalization                   anomalies and deliberate denormalization
+SQL query construction          joins, aggregation, subqueries/CTEs, pagination
+Indexes + access patterns       index choices tied to real reads/writes
+Query plans                     evidence-based performance reasoning
+Transactions + concurrency      atomicity, isolation, conflict/failure behavior
+ORM translation                 what the abstraction generates/hides
+Schema evolution                migrations, compatibility, data safety
+Debugging                       symptom → evidence → cause
+Design defense                  tradeoffs and interview follow-up
+```
+
+A developer can be at different levels in each competency. Do not report one undifferentiated "SQL score".
+
+## Provider / ORM architecture
+
+The workbench stays provider/ORM-adapter oriented rather than becoming Family Meal Planner-specific.
+
+```text
+Database adapter
+  SQLite V1
+  PostgreSQL / SQL Server / ... future
+
+ORM evidence
+  EF Core first concrete path
+  Hibernate / SQLAlchemy / ... future
+
+Canonical learning model
+  tables
+  columns
+  constraints
+  relationships
+  indexes
+  queries
+  query-plan steps
+  migrations
+
+Interactive viewer
+  schema navigation
+  learning panels
+  query-to-ERD highlighting
+```
+
+SQLite + EF Core is the first concrete learning path, not a permanent architectural restriction.
+
+## IDE tooling
+
+Database extensions can improve the human exploration loop, but `/db-lab` must not depend on manipulating their UI.
+
+For SQLite projects, Bootstrap may recommend SQLTools plus its SQLite driver so the developer can independently browse/query the same local database. The reusable skill and workbench still obtain their authoritative evidence from repository/framework/provider-supported mechanisms.
+
+## Safety and fallbacks
+
+Database Lab is read-only learning by default.
+
+Do not:
+
+- connect to Production for learning exercises;
+- mutate real application data;
+- apply/revert migrations;
+- create/drop indexes;
+- change code to prove a point;
+- claim an index was used without plan evidence;
+- manufacture executed SQL when only ORM source is available.
+
+The SQLite V1 workbench opens the database with SQLite `mode=ro`. Generated HTML/JSON are disposable learning artifacts and should normally go to a temp directory rather than tracked project paths.
+
+If evidence is missing, say so and continue with the strongest safe layer available. A missing database runtime, ORM trace, or interactive viewer should degrade the experience; it should not block learning or engineering delivery.