@happyvertical/smrt-education 0.57.46 → 0.57.47

package/dist/smrt-knowledge.json

@@ -3,20 +3,21 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-education",
-  "packageVersion": "0.57.46",
+  "packageVersion": "0.57.47",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "c5e585b8bbf4ba004fa381349a5bbd77cb834ad41b40ea452c188a319870c46a",
-    "packageJson": "94831ed17f24489215be11ef71781fd0add57cbb2192d3658b8ae2e30c7c96bf",
-    "agents": "57c43cd254f4d22602c8829fb01699a3cea56c9717ca0ef2a571c61bffac5507",
-    "moduleDoc:agents/learner-service.md": "8ad25eb6afd23d7ba04ecccbed02b154be83c24d3a54bd172b19faae30601f98",
-    "moduleDoc:agents/submission-service.md": "ae22d789d5e6a695787a2c64bf6720430c91196aab2bbc2892f831b3155bb1ce",
+    "manifest": "7a282ef48121d8974c20caf03da98bb6fe75a94b335a4457efc635c9d875a3e4",
+    "packageJson": "c62d4a8c38d361751bf6e154967bf8f6fef8541769ed181413ddc1c53ffe4b0c",
+    "agents": "19156c524f18604ae422a663606ecaff4c3c0d077fd88cce2dc47a3a43f98d1a",
+    "moduleDoc:agents/learner-service.md": "936d8bbe10f6be53353fc6a0e2b8c53b398f0810477147c82139309b62e8fe63",
+    "moduleDoc:agents/submission-service.md": "b5c1cb3863e06530c0b575ba5598c8a329c0e907ea42226267faa7317680eaa1",
     "moduleDoc:agents/workbook-service.md": "ae3a0f208b42766e417eac226e4a24ec15fe17c1ba9cde26a325ded982614278",
     "moduleDoc:agents/photo-intake.md": "3b7057201ee30b2361aad23ea52e8a55c8ed5354e7a7e4a8193b7de17ca2f0db",
     "moduleDoc:agents/course-authoring-service.md": "9ac4b8d85974e0dd3e43457fd18c4befd2c42c865bb26446cffdfe2712febab8",
     "moduleDoc:agents/course-generation-review.md": "579b960994e96a9c17a935ae18920a323e95dfbf968b25e6628f424e75ebab7f",
     "moduleDoc:agents/question-records.md": "335fe247f7294c6b891885d43d4eaccb20885bfb4a861cf66ae245e8be1fa781",
+    "moduleDoc:agents/question-extraction.md": "68ce7d627304fbb39e35f34db6e8caad9ca480147f7f1d8e74a5b82079ef648e",
     "moduleDoc:agents/source-import.md": "30ee823589d655442bcf1abcd86a2132172065b4bc5e3c4d89b1e8b7afcc66bc",
     "moduleDoc:agents/family-intake.md": "540b6d37f438496acb0208b6ac7258264e2142bce3d2f986967b7741606fe4f7",
     "moduleDoc:agents/catalog-previews.md": "5f4e0352274009b3ce00408017a16666036d24df695a7078c27317ba4e66f0a7",
@@ -2371,6 +2372,23 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "LessonSelfAttestationCollection",
+      "qualifiedName": "@happyvertical/smrt-education:LessonSelfAttestationCollection",
+      "collection": "lessonselfattestations",
+      "tableName": "lesson_self_attestations",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "GradeCollection",
       "qualifiedName": "@happyvertical/smrt-education:GradeCollection",
@@ -7786,11 +7804,11 @@
       "risks": []
     },
     {
-      "name": "Learner",
-      "qualifiedName": "@happyvertical/smrt-education:Learner",
-      "collection": "learners",
-      "description": "A learner is a real user/profile identity with active family membership.",
-      "tableName": "learners",
+      "name": "LessonProgressTransition",
+      "qualifiedName": "@happyvertical/smrt-education:LessonProgressTransition",
+      "collection": "lessonprogresstransitions",
+      "description": "Append-only status history for one LessonProgress row. The progress row keeps one identity per enrollment and lesson, so earlier states live here.",
+      "tableName": "lesson_progress_transitions",
       "packageName": "@happyvertical/smrt-education",
       "extends": "SmrtObject",
       "fields": [
@@ -7801,40 +7819,62 @@
           "columnType": "UUID"
         },
         {
-          "name": "userId",
-          "type": "crossPackageRef",
+          "name": "progressId",
+          "type": "foreignKey",
           "required": true,
-          "related": "@happyvertical/smrt-users:User",
+          "related": "LessonProgress",
           "columnType": "UUID"
         },
         {
-          "name": "profileId",
-          "type": "crossPackageRef",
+          "name": "enrollmentId",
+          "type": "foreignKey",
           "required": true,
-          "related": "@happyvertical/smrt-profiles:Profile",
+          "related": "Enrollment",
           "columnType": "UUID"
         },
         {
-          "name": "displayName",
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
+          "columnType": "UUID"
+        },
+        {
+          "name": "fromStatus",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "default": "not_started"
         },
         {
-          "name": "birthDate",
-          "type": "datetime",
+          "name": "toStatus",
+          "type": "text",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TEXT",
+          "default": "not_started"
         },
         {
-          "name": "level",
-          "type": "integer",
-          "required": true,
-          "columnType": "INTEGER",
-          "default": 0
+          "name": "kind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "put-back"
         },
         {
-          "name": "settings",
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
           "type": "text",
           "required": false,
           "columnType": "TEXT"
@@ -7842,29 +7882,43 @@
       ],
       "relationships": [
         {
-          "name": "userId",
-          "type": "crossPackageRef",
+          "name": "progressId",
+          "type": "foreignKey",
           "required": true,
-          "related": "@happyvertical/smrt-users:User",
+          "related": "LessonProgress",
           "columnType": "UUID"
         },
         {
-          "name": "profileId",
-          "type": "crossPackageRef",
+          "name": "enrollmentId",
+          "type": "foreignKey",
           "required": true,
-          "related": "@happyvertical/smrt-profiles:Profile",
+          "related": "Enrollment",
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
           "columnType": "UUID"
         }
       ],
       "methods": [
-        "getSettings",
-        "save",
-        "setSettings"
+        "delete",
+        "save"
       ],
       "methodSignatures": [
         {
-          "name": "getSettings",
-          "returns": "Record<string, unknown>"
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
         },
         {
           "name": "save",
@@ -7873,13 +7927,6 @@
             "options?: SmrtSaveOptions"
           ],
           "returns": "Promise<this>"
-        },
-        {
-          "name": "setSettings",
-          "params": [
-            "value: Record<string, unknown>"
-          ],
-          "returns": "void"
         }
       ],
       "tenant": {
@@ -7896,40 +7943,49 @@
       "withheldSurfaces": [
         {
           "kind": "api",
-          "operation": "getSettings",
+          "operation": "delete",
           "code": "api-disabled",
           "reason": "api is disabled",
-          "objectName": "@happyvertical/smrt-education:Learner"
+          "objectName": "@happyvertical/smrt-education:LessonProgressTransition"
         },
         {
           "kind": "api",
           "operation": "save",
           "code": "api-disabled",
           "reason": "api is disabled",
-          "objectName": "@happyvertical/smrt-education:Learner"
-        },
-        {
-          "kind": "api",
-          "operation": "setSettings",
-          "code": "api-disabled",
-          "reason": "api is disabled",
-          "objectName": "@happyvertical/smrt-education:Learner"
+          "objectName": "@happyvertical/smrt-education:LessonProgressTransition"
         }
       ],
       "relationshipFeatures": [
-        "crossPackageRef",
+        "foreignKey",
         "uuidColumns"
       ],
       "tags": [],
       "risks": []
     },
     {
-      "name": "Curriculum",
-      "qualifiedName": "@happyvertical/smrt-education:Curriculum",
-      "displayLabelField": "title",
-      "collection": "curriculums",
-      "description": "A distinct plan retains its own enrollment history.",
-      "tableName": "curricula",
+      "name": "LessonProgressTransitionCollection",
+      "qualifiedName": "@happyvertical/smrt-education:LessonProgressTransitionCollection",
+      "collection": "lessonprogresstransitions",
+      "tableName": "lesson_progress_transitions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "EnrollmentStatusChange",
+      "qualifiedName": "@happyvertical/smrt-education:EnrollmentStatusChange",
+      "collection": "enrollmentstatuschanges",
+      "description": "Append-only audit of one enrollment status change made through LearnerService.setEnrollmentStatus: who changed it and the host policy setting relied on, in the same transaction as the change.",
+      "tableName": "enrollment_status_changes",
       "packageName": "@happyvertical/smrt-education",
       "extends": "SmrtObject",
       "fields": [
@@ -7939,6 +7995,13 @@
           "required": true,
           "columnType": "UUID"
         },
+        {
+          "name": "enrollmentId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Enrollment",
+          "columnType": "UUID"
+        },
         {
           "name": "learnerId",
           "type": "foreignKey",
@@ -7947,32 +8010,46 @@
           "columnType": "UUID"
         },
         {
-          "name": "title",
+          "name": "fromStatus",
           "type": "text",
-          "required": true,
-          "columnType": "TEXT"
+          "required": false,
+          "columnType": "TEXT",
+          "default": "planned"
         },
         {
-          "name": "startsOn",
-          "type": "datetime",
+          "name": "toStatus",
+          "type": "text",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TEXT",
+          "default": "planned"
         },
         {
-          "name": "endsOn",
-          "type": "datetime",
+          "name": "actorUserId",
+          "type": "text",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TEXT"
         },
         {
-          "name": "status",
+          "name": "policyBasis",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "default": "planned"
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
         }
       ],
       "relationships": [
+        {
+          "name": "enrollmentId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Enrollment",
+          "columnType": "UUID"
+        },
         {
           "name": "learnerId",
           "type": "foreignKey",
@@ -7982,9 +8059,15 @@
         }
       ],
       "methods": [
+        "delete",
         "save"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
         {
           "name": "save",
           "async": true,
@@ -8006,12 +8089,19 @@
       ],
       "surfaces": [],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:EnrollmentStatusChange"
+        },
         {
           "kind": "api",
           "operation": "save",
           "code": "api-disabled",
           "reason": "api is disabled",
-          "objectName": "@happyvertical/smrt-education:Curriculum"
+          "objectName": "@happyvertical/smrt-education:EnrollmentStatusChange"
         }
       ],
       "relationshipFeatures": [
@@ -8022,11 +8112,28 @@
       "risks": []
     },
     {
-      "name": "Enrollment",
-      "qualifiedName": "@happyvertical/smrt-education:Enrollment",
-      "collection": "enrollments",
-      "description": "One course in one curriculum; a new curriculum means a new enrollment.",
-      "tableName": "enrollments",
+      "name": "EnrollmentStatusChangeCollection",
+      "qualifiedName": "@happyvertical/smrt-education:EnrollmentStatusChangeCollection",
+      "collection": "enrollmentstatuschanges",
+      "tableName": "enrollment_status_changes",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "Learner",
+      "qualifiedName": "@happyvertical/smrt-education:Learner",
+      "collection": "learners",
+      "description": "A learner is a real user/profile identity with active family membership.",
+      "tableName": "learners",
       "packageName": "@happyvertical/smrt-education",
       "extends": "SmrtObject",
       "fields": [
@@ -8037,45 +8144,281 @@
           "columnType": "UUID"
         },
         {
-          "name": "curriculumId",
-          "type": "foreignKey",
-          "required": true,
-          "related": "Curriculum",
-          "columnType": "UUID"
-        },
-        {
-          "name": "learnerId",
-          "type": "foreignKey",
+          "name": "userId",
+          "type": "crossPackageRef",
           "required": true,
-          "related": "Learner",
+          "related": "@happyvertical/smrt-users:User",
           "columnType": "UUID"
         },
         {
-          "name": "courseId",
-          "type": "foreignKey",
+          "name": "profileId",
+          "type": "crossPackageRef",
           "required": true,
-          "related": "Course",
+          "related": "@happyvertical/smrt-profiles:Profile",
           "columnType": "UUID"
         },
         {
-          "name": "status",
+          "name": "displayName",
           "type": "text",
           "required": false,
-          "columnType": "TEXT",
-          "default": "planned"
+          "columnType": "TEXT"
         },
         {
-          "name": "startedAt",
+          "name": "birthDate",
           "type": "datetime",
           "required": false,
           "columnType": "TIMESTAMP"
         },
         {
-          "name": "completedAt",
-          "type": "datetime",
-          "required": false,
-          "columnType": "TIMESTAMP"
-        },
+          "name": "level",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "settings",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "userId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-users:User",
+          "columnType": "UUID"
+        },
+        {
+          "name": "profileId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "getSettings",
+        "save",
+        "setSettings"
+      ],
+      "methodSignatures": [
+        {
+          "name": "getSettings",
+          "returns": "Record<string, unknown>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        },
+        {
+          "name": "setSettings",
+          "params": [
+            "value: Record<string, unknown>"
+          ],
+          "returns": "void"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getSettings",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:Learner"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:Learner"
+        },
+        {
+          "kind": "api",
+          "operation": "setSettings",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:Learner"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "Curriculum",
+      "qualifiedName": "@happyvertical/smrt-education:Curriculum",
+      "displayLabelField": "title",
+      "collection": "curriculums",
+      "description": "A distinct plan retains its own enrollment history.",
+      "tableName": "curricula",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "title",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "startsOn",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "endsOn",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "planned"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "slug",
+        "context"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:Curriculum"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "Enrollment",
+      "qualifiedName": "@happyvertical/smrt-education:Enrollment",
+      "collection": "enrollments",
+      "description": "One course in one curriculum; a new curriculum means a new enrollment.",
+      "tableName": "enrollments",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "curriculumId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Curriculum",
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "courseId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Course",
+          "columnType": "UUID"
+        },
+        {
+          "name": "status",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "planned"
+        },
+        {
+          "name": "startedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
+        {
+          "name": "completedAt",
+          "type": "datetime",
+          "required": false,
+          "columnType": "TIMESTAMP"
+        },
         {
           "name": "targetMinutesPerWeek",
           "type": "integer",
@@ -8287,75 +8630,379 @@
         }
       ],
       "relationshipFeatures": [
-        "foreignKey",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "LessonAsset",
+      "qualifiedName": "@happyvertical/smrt-education:LessonAsset",
+      "collection": "lessonassets",
+      "tableName": "lesson_assets",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": false,
+          "columnType": "UUID"
+        },
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "relationship",
+          "type": "text",
+          "required": true,
+          "columnType": "TEXT",
+          "default": "attachment"
+        },
+        {
+          "name": "sortOrder",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        }
+      ],
+      "relationships": [
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": true,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "optional",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "lesson_id",
+        "asset_id",
+        "relationship"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:LessonAsset"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "QuestionExtractionRecord",
+      "qualifiedName": "@happyvertical/smrt-education:QuestionExtractionRecord",
+      "collection": "questionextractionrecords",
+      "description": "Append-only preserved question extraction: one row per tenant, intake item and ingestion analysis attempt.",
+      "tableName": "question_extractions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeItemId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "analysisAttemptId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceIdentity",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceKind",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT",
+          "default": "worksheet_scan"
+        },
+        {
+          "name": "proposalDigest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "inputDigest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "extractorJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "extractionJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "matchJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedByUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "intake_item_id",
+        "analysis_attempt_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:QuestionExtractionRecord"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:QuestionExtractionRecord"
+        }
+      ],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "QuestionExtractionRecordCollection",
+      "qualifiedName": "@happyvertical/smrt-education:QuestionExtractionRecordCollection",
+      "collection": "questionextractionrecords",
+      "tableName": "question_extractions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
         "uuidColumns"
       ],
       "tags": [],
       "risks": []
     },
     {
-      "name": "LessonAsset",
-      "qualifiedName": "@happyvertical/smrt-education:LessonAsset",
-      "collection": "lessonassets",
-      "tableName": "lesson_assets",
+      "name": "ExtractedQuestionLink",
+      "qualifiedName": "@happyvertical/smrt-education:ExtractedQuestionLink",
+      "collection": "extractedquestionlinks",
+      "description": "Append-only applied outcome of one extracted question: which question record it created or matched (or why none), with its source anchors and media refs.",
+      "tableName": "extracted_question_links",
       "packageName": "@happyvertical/smrt-education",
       "extends": "SmrtObject",
       "fields": [
         {
           "name": "tenantId",
           "type": "text",
-          "required": false,
+          "required": true,
           "columnType": "UUID"
         },
         {
-          "name": "lessonId",
+          "name": "extractionId",
           "type": "foreignKey",
           "required": true,
-          "related": "Lesson",
+          "related": "QuestionExtractionRecord",
           "columnType": "UUID"
         },
         {
-          "name": "assetId",
-          "type": "crossPackageRef",
-          "required": true,
-          "related": "@happyvertical/smrt-assets:Asset",
-          "columnType": "UUID"
+          "name": "questionKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
         },
         {
-          "name": "relationship",
+          "name": "sourceIdentity",
           "type": "text",
-          "required": true,
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "outcome",
+          "type": "text",
+          "required": false,
           "columnType": "TEXT",
-          "default": "attachment"
+          "default": "needs_review"
         },
         {
-          "name": "sortOrder",
-          "type": "integer",
-          "required": true,
-          "columnType": "INTEGER",
-          "default": 0
+          "name": "questionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Question",
+          "columnType": "UUID"
+        },
+        {
+          "name": "questionRevisionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "QuestionRevision",
+          "columnType": "UUID"
+        },
+        {
+          "name": "anchorsJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "mediaJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "appliedByUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
         }
       ],
       "relationships": [
         {
-          "name": "lessonId",
+          "name": "extractionId",
           "type": "foreignKey",
           "required": true,
-          "related": "Lesson",
+          "related": "QuestionExtractionRecord",
           "columnType": "UUID"
         },
         {
-          "name": "assetId",
-          "type": "crossPackageRef",
-          "required": true,
-          "related": "@happyvertical/smrt-assets:Asset",
+          "name": "questionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Question",
+          "columnType": "UUID"
+        },
+        {
+          "name": "questionRevisionId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "QuestionRevision",
           "columnType": "UUID"
         }
       ],
       "methods": [
+        "delete",
         "save"
       ],
       "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
         {
           "name": "save",
           "async": true,
@@ -8367,33 +9014,55 @@
       ],
       "tenant": {
         "scoped": true,
-        "mode": "optional",
+        "mode": "required",
         "field": "tenantId"
       },
       "conflictColumns": [
         "tenant_id",
-        "lesson_id",
-        "asset_id",
-        "relationship"
+        "extraction_id",
+        "question_key"
       ],
       "surfaces": [],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:ExtractedQuestionLink"
+        },
         {
           "kind": "api",
           "operation": "save",
           "code": "api-disabled",
           "reason": "api is disabled",
-          "objectName": "@happyvertical/smrt-education:LessonAsset"
+          "objectName": "@happyvertical/smrt-education:ExtractedQuestionLink"
         }
       ],
       "relationshipFeatures": [
-        "crossPackageRef",
         "foreignKey",
         "uuidColumns"
       ],
       "tags": [],
       "risks": []
     },
+    {
+      "name": "ExtractedQuestionLinkCollection",
+      "qualifiedName": "@happyvertical/smrt-education:ExtractedQuestionLinkCollection",
+      "collection": "extractedquestionlinks",
+      "tableName": "extracted_question_links",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "LearningObjective",
       "qualifiedName": "@happyvertical/smrt-education:LearningObjective",
@@ -10084,7 +10753,7 @@
       "name": "Attestation",
       "qualifiedName": "@happyvertical/smrt-education:Attestation",
       "collection": "submissions",
-      "description": "A guardian's statement that work was completed.",
+      "description": "A statement that work was completed.",
       "tableName": "submissions",
       "packageName": "@happyvertical/smrt-education",
       "extends": "Submission",
@@ -10241,6 +10910,150 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "LessonSelfAttestation",
+      "qualifiedName": "@happyvertical/smrt-education:LessonSelfAttestation",
+      "collection": "lessonselfattestations",
+      "description": "Marks an Attestation as self-reported by the learner (Reading/Video \"I read it\" / \"I watched it\"), with the host policy setting relied on.",
+      "tableName": "lesson_self_attestations",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "submissionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Submission",
+          "columnType": "UUID"
+        },
+        {
+          "name": "progressId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "LessonProgress",
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
+          "columnType": "UUID"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "policyBasis",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "recordedAt",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "submissionId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Submission",
+          "columnType": "UUID"
+        },
+        {
+          "name": "progressId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "LessonProgress",
+          "columnType": "UUID"
+        },
+        {
+          "name": "learnerId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Learner",
+          "columnType": "UUID"
+        },
+        {
+          "name": "lessonId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "Lesson",
+          "columnType": "UUID"
+        }
+      ],
+      "methods": [
+        "delete",
+        "save"
+      ],
+      "methodSignatures": [
+        {
+          "name": "delete",
+          "async": true,
+          "returns": "Promise<void>"
+        },
+        {
+          "name": "save",
+          "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
+          "returns": "Promise<this>"
+        }
+      ],
+      "tenant": {
+        "scoped": true,
+        "mode": "required",
+        "field": "tenantId"
+      },
+      "conflictColumns": [
+        "tenant_id",
+        "submission_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:LessonSelfAttestation"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:LessonSelfAttestation"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "SubmissionAsset",
       "qualifiedName": "@happyvertical/smrt-education:SubmissionAsset",
@@ -12426,24 +13239,24 @@
   "surfaces": [],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 154,
+    "foreignKeyFields": 167,
     "crossPackageRefFields": 22,
     "junctionCollections": 2,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 650
+    "uuidColumns": 696
   },
-  "agentDoc": "# smrt-education\n\nCatalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,\nor AI surface. Applications use `CatalogService`, supplying their actor-bound\nauthorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`\nadapter from smrt-users. Catalog authorization receives the exact shared collection\nexecutor; live session/permission checks must use that executor. That read scope may widen only an allowlisted catalog\ncollection's `list` to self, ancestors, and globals; it never authorizes a get,\nwrite, raw query, sibling, or descendant read.\n\n`personal-use-copy` courses and all `answer-key` lesson assets are private\nfamily material. Do not publish them, promote them, or expose them through a\nlearner-facing result. `LessonAsset` is the sole owner join for lesson files;\ndo not add asset-id fields to lesson subclasses.\n\nLearner objects require exact tenant ownership and close generated surfaces.\n`LearnerService` owns actor/resource authorization and transactional planning and\nstart-progress; see [learner contract](agents/learner-service.md). Guardian\nrelationships require a host decision about their type and effective terms.\nNever expose direct collection writes as learner handlers, reset progress on a\nretry, or treat an unscored nullable decimal as zero.\n\nSubmission capture, guardian grading and private PDF packet splitting use\n`SubmissionService`; see [submission contract](agents/submission-service.md).\nKeep asset metadata on the same transaction and compensate only newly planned\nfiles after rollback; never expose source URIs or accept learner grade patches.\n\nValidation: `pnpm --filter @happyvertical/smrt-education test`,\n`test:postgres`, `typecheck`, and `build`.\n\nPhysical workbook capture, immutable assessment/feedback history and descriptive\nevidence use [WorkbookService](agents/workbook-service.md). Keep provisional\nsharing separate from guardian Grade authority. Photo-first receipt/context\ncapture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references\nnever create learning evidence, and blank exercises need explicit work intent.\n\nRevisioned authored courses, release, archive, enrollment pins and licence use\n[CourseAuthoringService](agents/course-authoring-service.md). Keep history\nappend-only, require request keys, and never weaken personal-use-copy rules.\n\nGeneration proposals into new draft revisions and revision-bound educational\nreview use [CourseGenerationReviewService](agents/course-generation-review.md).\nKeep supplied content unless a decision is recorded; reviews carry no score.\n\nImmutable questions, answer keys/rubrics, stable learning objectives, worksheet\nrender ids and exact-revision references use [QuestionAuthoringService](agents/question-records.md).\nKeep keys out of learner bundles; a missing key stays null. `attachGeneratedPrintable`\nstores the rendered PDFs; the guardian copy is always an `answer-key`, never `printable`.\n\nSource import: [host boundary and transaction contract](agents/source-import.md).\n`SourceImportService` requires host opt-in, matching active actor/tenant and\nexplicit licensing authorization; never add a system/global write bypass.\n\nFamily-owned unassigned originals and audited learner adoption use\n[FamilyIntakeService](agents/family-intake.md). Keep family source scope immutable;\nassignment alone never creates learning history or grants learner inbox access.\n\nPublisher catalog previews use [the preview contract](agents/catalog-previews.md).\nKeep independent image rights and source revisions; serve via `CatalogPreviewService`\nwith live actor/tenant authorization, never direct provider image URLs.\n\nEnrollment Plan projections and guardian-only parent notes use\n[the Plan contract](agents/learner-plan.md). Keep awaiting review separate from\nContinue; note authority/provenance never grants learner access or learning evidence.\n\nHomeschool group sharing uses [GroupSharingService](agents/group-sharing.md),\nits read-only reader and revision comment service. Group tenants never become\nfamily ancestors or guardians. Enumerate only the group-owned opaque roster index,\nthen revalidate each exact family edge and current policy. Media delivery must call\nthe reader on every request; signed storage URLs are not a sharing grant. Saved\nparent comment visibility applies on every child read. Progress with feedback\ndisabled contains counts only, never correctness, scores or concept labels.\n",
+  "agentDoc": "# smrt-education\n\nCatalog objects are optional-tenant scoped and have no generated REST, CLI, MCP,\nor AI surface. Applications use `CatalogService`, supplying their actor-bound\nauthorization decision and the trusted `TenantCollection.withTenantCatalogReadScope`\nadapter from smrt-users. Catalog authorization receives the exact shared collection\nexecutor; live session/permission checks must use that executor. That read scope may widen only an allowlisted catalog\ncollection's `list` to self, ancestors, and globals; it never authorizes a get,\nwrite, raw query, sibling, or descendant read.\n\n`personal-use-copy` courses and all `answer-key` lesson assets are private\nfamily material. Do not publish them, promote them, or expose them through a\nlearner-facing result. `LessonAsset` is the sole owner join for lesson files;\ndo not add asset-id fields to lesson subclasses.\n\nLearner objects require exact tenant ownership and close generated surfaces.\n`LearnerService` owns actor/resource authorization and transactional planning and\nstart-progress; see [learner contract](agents/learner-service.md). Guardian\nrelationships require a host decision about their type and effective terms.\nNever expose direct collection writes as learner handlers, reset progress on a\nretry, or treat an unscored nullable decimal as zero.\n\nSubmission capture, guardian grading and private PDF packet splitting use\n`SubmissionService`; see [submission contract](agents/submission-service.md).\nKeep asset metadata on the same transaction and compensate only newly planned\nfiles after rollback; never expose source URIs or accept learner grade patches.\n\nValidation: `pnpm --filter @happyvertical/smrt-education test`,\n`test:postgres`, `typecheck`, and `build`.\n\nPhysical workbook capture, immutable assessment/feedback history and descriptive\nevidence use [WorkbookService](agents/workbook-service.md). Keep provisional\nsharing separate from guardian Grade authority. Photo-first receipt/context\ncapture uses [WorkbookPhotoService](agents/photo-intake.md); covers/references\nnever create learning evidence, and blank exercises need explicit work intent.\n\nRevisioned authored courses, release, archive, enrollment pins and licence use\n[CourseAuthoringService](agents/course-authoring-service.md). Keep history\nappend-only, require request keys, and never weaken personal-use-copy rules.\n\nGeneration proposals into new draft revisions and revision-bound educational\nreview use [CourseGenerationReviewService](agents/course-generation-review.md).\nKeep supplied content unless a decision is recorded; reviews carry no score.\n\nImmutable questions, answer keys/rubrics, stable learning objectives, worksheet\nrender ids and exact-revision references use [QuestionAuthoringService](agents/question-records.md).\nKeep keys out of learner bundles; a missing key stays null. `attachGeneratedPrintable`\nstores the rendered PDFs; the guardian copy is always an `answer-key`, never `printable`.\n\nStructured questions from scans and imported course files use\n[QuestionExtractionService](agents/question-extraction.md) and the `extract-questions`\ningestion handler. Anchors come from provider region catalogs only; match by worksheet\nid and layout, never text; ambiguous matches stay unattached; source-keyed replays.\n\nSource import: [host boundary and transaction contract](agents/source-import.md).\n`SourceImportService` requires host opt-in, matching active actor/tenant and\nexplicit licensing authorization; never add a system/global write bypass.\n\nFamily-owned unassigned originals and audited learner adoption use\n[FamilyIntakeService](agents/family-intake.md). Keep family source scope immutable;\nassignment alone never creates learning history or grants learner inbox access.\n\nPublisher catalog previews use [the preview contract](agents/catalog-previews.md).\nKeep independent image rights and source revisions; serve via `CatalogPreviewService`\nwith live actor/tenant authorization, never direct provider image URLs.\n\nEnrollment Plan projections and guardian-only parent notes use\n[the Plan contract](agents/learner-plan.md). Keep awaiting review separate from\nContinue; note authority/provenance never grants learner access or learning evidence.\n\nHomeschool group sharing uses [GroupSharingService](agents/group-sharing.md),\nits read-only reader and revision comment service. Group tenants never become\nfamily ancestors or guardians. Enumerate only the group-owned opaque roster index,\nthen revalidate each exact family edge and current policy. Media delivery must call\nthe reader on every request; signed storage URLs are not a sharing grant. Saved\nparent comment visibility applies on every child read. Progress with feedback\ndisabled contains counts only, never correctness, scores or concept labels.\n",
   "moduleDocs": [
     {
       "path": "agents/learner-service.md",
       "module": "learner-service",
-      "content": "# Learner service boundary\n\n`Learner`, `Curriculum`, `Enrollment`, and `LessonProgress` require an exact\nowning tenant. Their generated API, CLI, MCP, and AI operations are closed.\nThe corresponding collections and model saves are trusted server persistence\nAPIs, not request handlers. Hosts must not wrap them in generic learner CRUD.\n\n## Identity and authority\n\nProvision a Person Profile, a linked User, and an active Membership before\ncreating a Learner with explicit `tenantId`, `userId`, and `profileId`. User\nemail is optional. Learner identity cannot be reassigned after creation.\nGuardianship is a directed `ProfileRelationship`, not a Learner `parentId`.\nThe shared Tenant has no family discriminator: “family” means a tenant that\nthe host has provisioned and authorized for this purpose.\n\nConstruct `LearnerService(db, authorizeLearner, authorizeCatalog)` with one\nroot database executor and trusted server-side authorizers. Enable tenancy\nand establish `withTenant({ tenantId, userId }, callback)` from authenticated\ncredentials. Every request must match that active actor and tenant exactly;\nmissing context, spoofed identifiers, and super-admin bypass contexts fail.\nBoth the actor and learner must hold active memberships in that exact tenant.\nA learner's User must still link to the learner's Person Profile.\n\nFor a different actor, supply `guardianRelationshipId`. The service checks\nthat this relationship is owned by the active tenant and directed from the\nactor's User Profile to the learner's Profile. `authorizeLearner` receives\n`own`, `action`, and the verified `relationshipTypeId`; the host must check\nthat the type represents guardianship, its terms are effective, and that\nits permission policy allows the action. An arbitrary relationship is not a\nguardian grant. Missing relationships and host denials/exceptions fail closed.\nThe authorizer also receives `executor`, the service's active database\nexecutor. Host policy reads, including relationship and revocation checks, must\nuse that executor so they share a `withTransaction` or `withExecutor` boundary.\nSame-tenant membership alone never grants sibling access.\n\n## Supported workflow\n\n- `getLearnerSetupStatus({ tenantId, actorUserId, learnerUserId })` is a\n  host-authorized onboarding probe for an active tenant member. It returns only\n  `{ needsSetup }`; it neither returns learner or relationship data nor grants\n  relationships. The host authorizer receives `education.learner.setup`, the\n  target user id, and the active executor. `provisionLearner` remains the write\n  path and still requires a directed guardian relationship.\n- `getLearner` returns authorized learner metadata and parsed settings.\n- `createCurriculum` creates a **planned** curriculum for an authorized guardian.\n  A learner cannot plan their own curriculum. Title is required.\n- `enroll` requires that guardian authority and a matching tenant curriculum.\n  It returns the existing enrollment for the same curriculum/course unchanged.\n  A delegated agent may enroll, only when the host opts in: construct\n  `LearnerService(db, authorize, authorizeCatalog, { verifyDelegation })` where\n  `verifyDelegation(executor, { tenantId, actorUserId, delegatingGuardianUserId,\n  delegationId, learnerId, courseId? }) => boolean | { allowed, reason?, code? }` runs on the\n  current executor. Without the port, or if it denies or throws, `enroll` refuses with\n  `LearnerAuthorizationError` before the learner authorizer and before any write. Supply\n  `delegatingGuardianUserId` and `delegationId` (both or neither, 1-200 printable characters,\n  guardian not the agent). After the port, the service re-checks the DELEGATING guardian's\n  active membership and `guardianRelationshipId` (that guardian's profile to the learner, same\n  tenant) and the agent's active membership. The authorizer gets `education.learner.plan`,\n  `own: false`, `delegated: true`, `relationshipTypeId` undefined (so a legacy\n  `relationshipTypeId === guardian` rule denies), the guardian's type as\n  `delegatingRelationshipTypeId`, `delegatingGuardianUserId` and `delegationId`, and decides.\n  A new delegated enrollment appends one `EnrollmentAssignmentRecord` (`Enrollment` is\n  unchanged). Only `enroll` and `createCurriculum` accept a delegation (on `LearnerService` itself; subclasses without\n  the port refuse); every other operation ignores it, so the agent has no\n  other learner authority. Catalog reads still use the agent as actor.\n  `createCurriculum` accepts the same delegated actor (`operation: 'create-curriculum'`\n  on the verifier request, `enroll` sends `'enroll'`), with identical verification, guardian\n  relationship recheck, authorizer shape and stripping of caller authority keys; each new\n  delegated curriculum appends one `CurriculumCreationRecord` (own table, `Curriculum` unchanged).\n- `startLesson` allows the learner or authorized guardian to create their own\n  enrollment's lesson progress in `in_progress`. It derives learner identity\n  from the validated enrollment. Repeated starts return existing state without\n  resetting counters, scores, completion, or timestamps.\n- `listProgress` reads only the validated learner/enrollment and lessons still\n  visible in that enrollment's course. Inconsistent persisted links fail\n  closed or are omitted from the list.\n- An enrollment with an `EnrollmentReleasePin` uses its effective lesson set\n  instead of `enrollment.courseId` alone (`resolveEnrollmentLessons`, shared\n  with `CourseAuthoringService.getEnrollmentRelease`, on the current executor):\n  lessons started (non-`not_started` status or attempts) stay on their original\n  immutable rows in any release the enrollment followed; the rest follow the\n  current pin, in that release's order. `nextLessons`, `assignmentLessons`,\n  `listProgress`, plan reads, `startLesson` and submission/workbook lesson\n  assertions all use it, so a lesson outside the set is rejected and progress\n  rows never move. Unpinned enrollments (or hosts without the authoring\n  tables) read their own course as before. Pins recorded for another learner\n  fail closed. `LessonProgress` accepts a lesson on any release course the\n  enrollment is pinned to; no data migration.\n\nService results are data-only views, with no persistence or database methods.\nExtra request fields are never model patches: a learner cannot set score,\nattempt count, or completion status through this API. Curriculum activation,\ncompletion transitions and dashboard aggregation are not supported by this\nbase service. SubmissionService extends its owning transaction/auth boundary for\ncapture and guardian grading; see [submission contract](submission-service.md).\nDirect model writes require trusted authority.\n\nCatalog visibility and child ownership reuse `CatalogService` on the same\nexecutor. Learner operations request private-inclusive catalog access, so the\nhost catalog authorizer must permit both `education.catalog.read` and\n`education.catalog.read-private` for the supported enrollment workflow.\nPrivate copies remain restricted to the exact owner. The service constructs a\nwhitelisted catalog request; caller options and answer-key flags are discarded.\nAnswer keys are never requested or returned. A catalog grant does not grant learner authorization.\n\n## Transactions and history\n\n`withTransaction(async transaction => ...)` composes service operations on the\ncallback's transaction-bound service. Use that service for every operation in\nthe unit. Throwing rolls back its curriculum, enrollment, and progress writes.\nThe callback's service closes when the transaction ends and rejects later calls.\nA failed mutation poisons the unit even if the callback catches its rejection;\nqueued mutations are cancelled. Callback failure stops pending work and waits for\nalready-running mutations to settle before rollback releases the executor. On\nsuccess, already-enqueued mutations finish before commit. Do not retain the\ncallback's service beyond the callback. The constructor\naccepts a root database; callers composing work use this method instead of\npassing an unmanaged transaction handle.\n\nPostgreSQL locks the parent curriculum/enrollment row before find-or-create.\nEmbedded writes use the core transaction queue. Concurrent mutations inside\none callback transaction are ordered on that connection, so duplicate starts\nwithin a `Promise.all` also return the same row. Database natural-key constraints\narbitrate enrollment `(tenant_id, curriculum_id, course_id)` and progress\n`(tenant_id, enrollment_id, lesson_id)` identities. Explicit storage conflict\nkeys include the tenant prefix because core does not add it to explicit keys.\nThe logical keys required by #3968 remain curriculum/course and enrollment/lesson:\nimmutable parent ownership and parent-tenant checks reject any second tenant\nfor the same parent. The storage prefix cannot create a second valid logical row. Ordinary repeated and concurrent calls\nreturn one row; an aborted workflow can be retried. No in-memory process lock\nis used for PostgreSQL concurrency.\n\nA new year is a new curriculum and enrollment, producing independent progress.\nUnscored `bestScore` persists as null; score zero is a real score. Scores are\nnullable decimals in [0,1]; counters are nonnegative safe integers. Settings\nare stored as JSON text and accessed through guarded `getSettings`/`setSettings`.\n\nThe shared executable workflows in `src/__tests__/learner-workflows.ts` run\nagainst SQLite and PostgreSQL, including actor/resource/context denial,\nconcurrent creation, rollback, history preservation, and zero/null scores.\nFull DuckDB schemas remain blocked by existing upstream DDL restrictions;\nno full learner workflow support on DuckDB is claimed.\n"
+      "content": "# Learner service boundary\n\n`Learner`, `Curriculum`, `Enrollment`, and `LessonProgress` require an exact\nowning tenant. Their generated API, CLI, MCP, and AI operations are closed.\nThe corresponding collections and model saves are trusted server persistence\nAPIs, not request handlers. Hosts must not wrap them in generic learner CRUD.\n\n## Identity and authority\n\nProvision a Person Profile, a linked User, and an active Membership before\ncreating a Learner with explicit `tenantId`, `userId`, and `profileId`. User\nemail is optional. Learner identity cannot be reassigned after creation.\nGuardianship is a directed `ProfileRelationship`, not a Learner `parentId`.\nThe shared Tenant has no family discriminator: “family” means a tenant that\nthe host has provisioned and authorized for this purpose.\n\nConstruct `LearnerService(db, authorizeLearner, authorizeCatalog)` with one\nroot database executor and trusted server-side authorizers. Enable tenancy\nand establish `withTenant({ tenantId, userId }, callback)` from authenticated\ncredentials. Every request must match that active actor and tenant exactly;\nmissing context, spoofed identifiers, and super-admin bypass contexts fail.\nBoth the actor and learner must hold active memberships in that exact tenant.\nA learner's User must still link to the learner's Person Profile.\n\nFor a different actor, supply `guardianRelationshipId`. The service checks\nthat this relationship is owned by the active tenant and directed from the\nactor's User Profile to the learner's Profile. `authorizeLearner` receives\n`own`, `action`, and the verified `relationshipTypeId`; the host must check\nthat the type represents guardianship, its terms are effective, and that\nits permission policy allows the action. An arbitrary relationship is not a\nguardian grant. Missing relationships and host denials/exceptions fail closed.\nThe authorizer also receives `executor`, the service's active database\nexecutor. Host policy reads, including relationship and revocation checks, must\nuse that executor so they share a `withTransaction` or `withExecutor` boundary.\nSame-tenant membership alone never grants sibling access.\n\n## Supported workflow\n\n- `getLearnerSetupStatus({ tenantId, actorUserId, learnerUserId })` is a\n  host-authorized onboarding probe for an active tenant member. It returns only\n  `{ needsSetup }`; it neither returns learner or relationship data nor grants\n  relationships. The host authorizer receives `education.learner.setup`, the\n  target user id, and the active executor. `provisionLearner` remains the write\n  path and still requires a directed guardian relationship.\n- `getLearner` returns authorized learner metadata and parsed settings.\n- `createCurriculum` creates a **planned** curriculum for an authorized guardian.\n  A learner cannot plan their own curriculum. Title is required.\n- `enroll` requires that guardian authority and a matching tenant curriculum.\n  It returns the existing enrollment for the same curriculum/course unchanged.\n  A delegated agent may enroll, only when the host opts in: construct\n  `LearnerService(db, authorize, authorizeCatalog, { verifyDelegation })` where\n  `verifyDelegation(executor, { tenantId, actorUserId, delegatingGuardianUserId,\n  delegationId, learnerId, courseId? }) => boolean | { allowed, reason?, code? }` runs on the\n  current executor. Without the port, or if it denies or throws, `enroll` refuses with\n  `LearnerAuthorizationError` before the learner authorizer and before any write. Supply\n  `delegatingGuardianUserId` and `delegationId` (both or neither, 1-200 printable characters,\n  guardian not the agent). After the port, the service re-checks the DELEGATING guardian's\n  active membership and `guardianRelationshipId` (that guardian's profile to the learner, same\n  tenant) and the agent's active membership. The authorizer gets `education.learner.plan`,\n  `own: false`, `delegated: true`, `relationshipTypeId` undefined (so a legacy\n  `relationshipTypeId === guardian` rule denies), the guardian's type as\n  `delegatingRelationshipTypeId`, `delegatingGuardianUserId` and `delegationId`, and decides.\n  A new delegated enrollment appends one `EnrollmentAssignmentRecord` (`Enrollment` is\n  unchanged). Only `enroll` and `createCurriculum` accept a delegation (on `LearnerService` itself; subclasses without\n  the port refuse); every other operation ignores it, so the agent has no\n  other learner authority. Catalog reads still use the agent as actor.\n  `createCurriculum` accepts the same delegated actor (`operation: 'create-curriculum'`\n  on the verifier request, `enroll` sends `'enroll'`), with identical verification, guardian\n  relationship recheck, authorizer shape and stripping of caller authority keys; each new\n  delegated curriculum appends one `CurriculumCreationRecord` (own table, `Curriculum` unchanged).\n- `startLesson` allows the learner or authorized guardian to create their own\n  enrollment's lesson progress in `in_progress`. It derives learner identity\n  from the validated enrollment. Repeated starts return existing state without\n  resetting counters, scores, completion, or timestamps. A `not_started` row\n  (a put-back lesson) moves to `in_progress` again with its counters, score and\n  first `startedAt` kept.\n- `putBackLesson({ enrollmentId, lessonId })` takes `in_progress` work back to\n  `not_started` for the learner or an authorized guardian under\n  `education.progress.put-back` (the host decides; own is not blocked). The\n  progress row keeps its one (enrollment, lesson) identity, so each change\n  appends an immutable `LessonProgressTransition` (from, to, kind, actor,\n  time) in the same transaction; restarting appends a `start` row when the\n  table exists. Counters, score, submissions, grades, workbook and evidence\n  rows are never touched. It returns `{ changed, progress }`: no progress or\n  already `not_started` is an idempotent no-op. `submitted`, `needs_review`,\n  `complete`, `skipped` (stored or workbook-projected) refuse with\n  `LessonPutBackError` (`.status`); completion is undone only through guardian\n  paths. A host without `lesson_progress_transitions` gets\n  `LearnerHistoryUnavailableError` from put-back; other operations still run.\n- `setEnrollmentStatus({ enrollmentId, status, policyBasis })` moves an\n  enrollment along `ENROLLMENT_STATUS_TRANSITIONS`: planned→active,\n  active→paused|dropped, paused→active|dropped. `completed` is reached only by\n  the completion path; completed and dropped are final. The authorizer gets\n  `education.enrollment.set-status` and decides whether a learner may act on\n  their own enrollment. `policyBasis` (1-200 characters, no control characters,\n  `requirePolicyBasis`) names the host setting relied on; it and the actor are\n  appended to an immutable `EnrollmentStatusChange` with the change, as\n  `pinEnrollment` records its basis. The first activation sets `startedAt`.\n  The current status is an idempotent `{ changed: false }`; any other move\n  throws `EnrollmentStatusTransitionError` (`.from`, `.to`). Progress,\n  submissions and history never cascade. Bad input throws\n  `LearnerValidationError`; a host without `enrollment_status_changes` gets\n  `LearnerHistoryUnavailableError`.\n- `listProgress` reads only the validated learner/enrollment and lessons still\n  visible in that enrollment's course. Inconsistent persisted links fail\n  closed or are omitted from the list.\n- An enrollment with an `EnrollmentReleasePin` uses its effective lesson set\n  instead of `enrollment.courseId` alone (`resolveEnrollmentLessons`, shared\n  with `CourseAuthoringService.getEnrollmentRelease`, on the current executor):\n  lessons started (non-`not_started` status or attempts) stay on their original\n  immutable rows in any release the enrollment followed; the rest follow the\n  current pin, in that release's order. `nextLessons`, `assignmentLessons`,\n  `listProgress`, plan reads, `startLesson` and submission/workbook lesson\n  assertions all use it, so a lesson outside the set is rejected and progress\n  rows never move. Unpinned enrollments (or hosts without the authoring\n  tables) read their own course as before. Pins recorded for another learner\n  fail closed. `LessonProgress` accepts a lesson on any release course the\n  enrollment is pinned to; no data migration.\n\nService results are data-only views, with no persistence or database methods.\nExtra request fields are never model patches: a learner cannot set score,\nattempt count, or completion status through this API. Curriculum activation,\nenrollment completion and dashboard aggregation are not supported by this\nbase service. SubmissionService extends its owning transaction/auth boundary for\ncapture and guardian grading; see [submission contract](submission-service.md).\nDirect model writes require trusted authority.\n\nCatalog visibility and child ownership reuse `CatalogService` on the same\nexecutor. Learner operations request private-inclusive catalog access, so the\nhost catalog authorizer must permit both `education.catalog.read` and\n`education.catalog.read-private` for the supported enrollment workflow.\nPrivate copies remain restricted to the exact owner. The service constructs a\nwhitelisted catalog request; caller options and answer-key flags are discarded.\nAnswer keys are never requested or returned. A catalog grant does not grant learner authorization.\n\n## Transactions and history\n\n`withTransaction(async transaction => ...)` composes service operations on the\ncallback's transaction-bound service. Use that service for every operation in\nthe unit. Throwing rolls back its curriculum, enrollment, and progress writes.\nThe callback's service closes when the transaction ends and rejects later calls.\nA failed mutation poisons the unit even if the callback catches its rejection;\nqueued mutations are cancelled. Callback failure stops pending work and waits for\nalready-running mutations to settle before rollback releases the executor. On\nsuccess, already-enqueued mutations finish before commit. Do not retain the\ncallback's service beyond the callback. The constructor\naccepts a root database; callers composing work use this method instead of\npassing an unmanaged transaction handle.\n\nPostgreSQL locks the parent curriculum/enrollment row before find-or-create.\nEmbedded writes use the core transaction queue. Concurrent mutations inside\none callback transaction are ordered on that connection, so duplicate starts\nwithin a `Promise.all` also return the same row. Database natural-key constraints\narbitrate enrollment `(tenant_id, curriculum_id, course_id)` and progress\n`(tenant_id, enrollment_id, lesson_id)` identities. Explicit storage conflict\nkeys include the tenant prefix because core does not add it to explicit keys.\nThe logical keys required by #3968 remain curriculum/course and enrollment/lesson:\nimmutable parent ownership and parent-tenant checks reject any second tenant\nfor the same parent. The storage prefix cannot create a second valid logical row. Ordinary repeated and concurrent calls\nreturn one row; an aborted workflow can be retried. No in-memory process lock\nis used for PostgreSQL concurrency.\n\nA new year is a new curriculum and enrollment, producing independent progress.\nUnscored `bestScore` persists as null; score zero is a real score. Scores are\nnullable decimals in [0,1]; counters are nonnegative safe integers. Settings\nare stored as JSON text and accessed through guarded `getSettings`/`setSettings`.\n\nThe shared executable workflows in `src/__tests__/learner-workflows.ts` run\nagainst SQLite and PostgreSQL, including actor/resource/context denial,\nconcurrent creation, rollback, history preservation, and zero/null scores.\nFull DuckDB schemas remain blocked by existing upstream DDL restrictions;\nno full learner workflow support on DuckDB is claimed.\n"
     },
     {
       "path": "agents/submission-service.md",
       "module": "submission-service",
-      "content": "# Submission and paper workflow\n\nConstruct `SubmissionService(db, authorizeLearner, authorizeCatalog, {storage,\nstoreOptions?, signAsset?})` from trusted server configuration. It extends\n`LearnerService`: the same active actor/tenant, memberships, linked person,\ndirected guardian relationship and host permission checks apply. The host must\nallow `education.learner.submit`, `education.learner.grade` or\n`education.learner.packet` as appropriate. Grade and packet actions always reject\nthe learner's own identity, even if the host authorizer returns true.\n\nThe protected transaction/auth hooks are internal owning-service extension\npoints. They are not handler APIs. All public service results remain data-only.\nUse the callback's service in `withTransaction`; escaped services are closed.\nSubmission operations share its serial queue, poison-on-failure behavior and\nPostgreSQL enrollment lock. No runtime schema creation occurs.\n\n## Capture and grading\n\n`captureSubmission` takes the learner request, `enrollmentId`, `lessonId`, a\nnonempty stable `requestKey`, and `pages` containing `name`, `mimeType` and Buffer\n`data`. Each upload becomes a fresh Asset owned by the learner's profile and\nexact tenant, joined solely through `SubmissionAsset`. Up to 100 uploads of\n25 MiB each are accepted (JPEG, PNG, WebP, or PDF). It atomically creates the\nsubmission/asset metadata and moves only that enrollment's progress to\n`submitted`, incrementing attempts once. Caller status, score, grader, asset ID,\nand answer-key flags are never patches. Equal request-key/content retries return\nthe existing submission; altered retries fail. Submitted/review/complete/skipped\nprogress rejects new captures. Content includes ordered filenames, MIME types,\nbytes and notes. Hosts should impose tighter request/body limits as needed.\n\n`captureBlankReference` records a workbook-page scan as immutable\n`blank_reference` evidence without advancing completion or creating a grade.\nTrusted ingestion scopes each receipt to the exact `enrollmentId` and calls\n`assertLessonAssignment` before reading retained evidence; it proves the active\ntenant, actor, learner, enrollment, and lesson without creating progress. A\nstable `intakeItemId` is claimed once in the durable tenant/item binding table,\nthen bound to the tenant, learner, lesson, progress, kind and predecessor; an\naltered retry fails. The binding is database-unique across enrollments while\nordinary uploads remain unbound. `resubmitSubmission` requires the current completed-work predecessor and\ncreates a new immutable `completed_work` attempt. Old pages, grades and feedback\nremain history; stale predecessors cannot be graded or replaced. A correction may\nreopen submitted, review or complete progress, while an AI proposal remains a\nnon-authoritative Grade until guardian review.\n\n`reviewSubmission` accepts an existing authorized submission and optional score\nand feedback. `attestLesson` creates/reuses an Attestation for a matching progress\nitem without requiring uploads. Both require a verified guardian and create a\nnew guardian Grade and set submission to `graded`. Ordinary non-workbook progress\nbecomes `complete`. Workbook-backed progress instead uses its explicit parent\ncompletion decision; grading alone leaves it in progress, including through a\nplain SubmissionService instance. Existing explicit completion on the current\nattempt is retained. The owning workbook join determines this policy, never a\ncaller flag.\nOmitted/null score is unscored; zero is a real score. The latest guardian grade\nwins over auto/AI/instructor proposals, and its score replaces progress's score.\nReview history is retained. ExternalCompletion is available for trusted server\npersistence; phase-zero learner handlers cannot forge reported scores. Online\nsubmissions and automatic grading are not implemented.\n\n`getSubmission` returns only submission metadata, page asset IDs and the selected\ngrade. It does not include catalog answers, extracted answers, storage paths,\nmodel objects, or database handles.\n\n`getLatestLessonSubmission` takes the learner request, `enrollmentId` and\n`lessonId`, repeats live read authorization and exact enrollment/catalog lesson\nscope, and returns the same safe view or `null` when no eligible work exists.\nIt reads at most one submission for that exact progress, choosing `completed_work`\nin `captured`, `needs_review` or `graded` status by `submittedAt DESC, id DESC`.\nBlank references, extracting and rejected work are excluded. Committed capture\nis retained evidence; it does not assert lesson completion. Hosts select completed\nlessons from authorized progress separately. An empty safe page list does not\nfall back to older work; asset signing still requires its own live authorization.\n\n## Storage and signed routes\n\nThe service creates an AssetRuntime bound to the operation's transaction. It\nrequires a resolved URI whose filename retains the fresh asset UUID and MIME\nextension; custom resolvers may choose its provider/directory but must route\nthat URI to the corresponding unique file. Shared existing locators are\nrejected before preservation or cleanup registration. It plans and persists\nthat unique asset URI before writing, registering that new\nasset for cleanup before the provider can partially write. After rollback,\nfiles are removed through the runtime store. Before deletion, the root database\nmust confirm that no asset owner committed: uncertain commit/read failures never\ncause committed bytes to be removed. Only this operation's newly created assets\nare candidates; pre-existing files are never adopted into its cleanup ledger.\n\nDatabase metadata is atomic; external storage uses compensation, not a database\ntransaction. If cleanup cannot complete, `SubmissionStorageCleanupError` contains\nfresh asset IDs and the original cause. Operators must reconcile those IDs in\nthe configured `education-page/<id>.<extension>` storage namespace (custom\nresolvers must retain their routing audit). A successful retry uses fresh IDs\nand cannot delete or reuse orphaned bytes. Process termination may also leave\nunreferenced files; hosts need storage orphan reconciliation. Do not suppress\ncleanup failures or claim crash-safe distributed atomicity.\n\n`signSubmissionAsset` verifies the submission/enrollment/learner ownership and\nits noun join, then verifies the Asset's tenant and learner profile before\ncalling the configured trusted signer. Claims contain actor, tenant, learner,\nenrollment, submission, asset and a five-minute expiry; no static source URI is\nreturned. The host signs every claim and its serving endpoint must verify the\nsignature, expiry, current actor/tenant and object authorization before serving.\nA bearer URL must never become a cross-family or sibling access bypass.\n\n`signLessonPrintable` signs only the exact authorized `printable` LessonAsset\njoin for an enrolled lesson. It never accepts an answer-key join and carries the\nsame tenant, actor, learner and enrollment scope as a submission claim.\n\n## Personal worksheet packets\n\n`splitWorksheetPacket` takes the guardian learner request, exact-owned\n`personal-use-copy` `courseId`, PDF bytes and ranges `{lessonId, firstPage,\nlastPage}`. Page bounds are inclusive and one-based. Ranges must be in bounds,\ndisjoint and target distinct Worksheet lessons in that private course. The\n50 MiB / 100-range limits are enforced before PDF parsing. `pdf-lib` extracts\nactual pages into independent PDFs and records private printable LessonAssets.\nAll resulting metadata commits together; storage failure compensates new PDFs.\nThe source packet is not retained. No shared/global course is accepted and no\nanswer-key join is created. A successful repeated packet upload intentionally\nadds another printable version; a failed upload can be retried safely.\n\nShared integration workflows run on SQLite and real PostgreSQL. Full DuckDB\nworkflow support remains outside the existing supported schema boundary.\n\n## Private asset boundary\n\nCaptured pages and split packet pages use `Asset.accessMode: 'private'` from their\ninitial insert. Ordinary generated Asset REST/MCP operations cannot list, hydrate,\nupdate or delete them, including through the parent STI model. The service opens\nan exact tenant/actor/learner-owner/asset-ID capability only after its normal learner\nrelationship checks. A host's signed serving route must repeat authorization and\nopen that exact capability before loading the asset. See the owning\n[private asset contract](../../assets/agents/private-assets.md).\n\nStorage must be private (including provider ACLs). Public HTTP(S) source locators\nare rejected; a hidden URL alone cannot protect publicly accessible bytes. Apply\nthe manifest migration adding `assets.access_mode` before deploying this runtime;\nlegacy ordinary assets retain the public default. Runtime creates no schema.\n\nPrivate lesson files must already be private Assets in the same tenant. Saving\nan answer-key join, or any join under a personal-use-copy course, requires the\nhost's exact actor/owner/asset capability; a public asset is never automatically\npromoted. Packet splitting retains this capability while creating each join.\nPersisted course tenant/license and section/lesson parent identity cannot change;\ncreate new structure and explicitly re-author its joins instead. Mandatory\nwrite predicates enforce this even for natural-key adoption and concurrent writes.\nOrdinary content and metadata refresh remains supported. This\nprevents existing public material being reclassified by moving its parent.\n\nFor pre-existing invalid joins, an authorized host must inventory private-material\njoins and remove invalid associations, recreate the bytes in private storage as a\nnew privately classified Asset, then re-author the join under its exact capability.\nDo not merely hide the URI, mutate access_mode with raw SQL, or delete shared\npublic bytes. This repair requires explicit storage/ownership authorization;\nnormal runtime does not migrate existing records.\n"
+      "content": "# Submission and paper workflow\n\nConstruct `SubmissionService(db, authorizeLearner, authorizeCatalog, {storage,\nstoreOptions?, signAsset?})` from trusted server configuration. It extends\n`LearnerService`: the same active actor/tenant, memberships, linked person,\ndirected guardian relationship and host permission checks apply. The host must\nallow `education.learner.submit`, `education.learner.grade` or\n`education.learner.packet` as appropriate. Grade and packet actions always reject\nthe learner's own identity, even if the host authorizer returns true.\n\nThe protected transaction/auth hooks are internal owning-service extension\npoints. They are not handler APIs. All public service results remain data-only.\nUse the callback's service in `withTransaction`; escaped services are closed.\nSubmission operations share its serial queue, poison-on-failure behavior and\nPostgreSQL enrollment lock. No runtime schema creation occurs.\n\n## Capture and grading\n\n`captureSubmission` takes the learner request, `enrollmentId`, `lessonId`, a\nnonempty stable `requestKey`, and `pages` containing `name`, `mimeType` and Buffer\n`data`. Each upload becomes a fresh Asset owned by the learner's profile and\nexact tenant, joined solely through `SubmissionAsset`. Up to 100 uploads of\n25 MiB each are accepted (JPEG, PNG, WebP, or PDF). It atomically creates the\nsubmission/asset metadata and moves only that enrollment's progress to\n`submitted`, incrementing attempts once. Caller status, score, grader, asset ID,\nand answer-key flags are never patches. Equal request-key/content retries return\nthe existing submission; altered retries fail. Submitted/review/complete/skipped\nprogress rejects new captures. Content includes ordered filenames, MIME types,\nbytes and notes. Hosts should impose tighter request/body limits as needed.\n\n`captureBlankReference` records a workbook-page scan as immutable\n`blank_reference` evidence without advancing completion or creating a grade.\nTrusted ingestion scopes each receipt to the exact `enrollmentId` and calls\n`assertLessonAssignment` before reading retained evidence; it proves the active\ntenant, actor, learner, enrollment, and lesson without creating progress. A\nstable `intakeItemId` is claimed once in the durable tenant/item binding table,\nthen bound to the tenant, learner, lesson, progress, kind and predecessor; an\naltered retry fails. The binding is database-unique across enrollments while\nordinary uploads remain unbound. `resubmitSubmission` requires the current completed-work predecessor and\ncreates a new immutable `completed_work` attempt. Old pages, grades and feedback\nremain history; stale predecessors cannot be graded or replaced. A correction may\nreopen submitted, review or complete progress, while an AI proposal remains a\nnon-authoritative Grade until guardian review.\n\n`reviewSubmission` accepts an existing authorized submission and optional score\nand feedback. `attestLesson` creates/reuses an Attestation for a matching progress\nitem without requiring uploads. Both require a verified guardian and create a\nnew guardian Grade and set submission to `graded`. Ordinary non-workbook progress\nbecomes `complete`. Workbook-backed progress instead uses its explicit parent\ncompletion decision; grading alone leaves it in progress, including through a\nplain SubmissionService instance. Existing explicit completion on the current\nattempt is retained. The owning workbook join determines this policy, never a\ncaller flag.\n`attestOwnLesson({ enrollmentId, lessonId, policyBasis, notes? })` is the\nlearner's own \"I read it\" / \"I watched it\" for `SELF_ATTESTABLE_LESSON_KINDS`\n(Reading, Video) under `education.learner.attest-own`. Any other actor is\nrefused before the host authorizer; the host decides from its own setting\n(passed as `policyBasis`, 1-200 characters) whether the learner may. It writes\nan ungraded `Attestation` and an insert-only `LessonSelfAttestation` (learner\nactor, basis), moves progress to `submitted` with one attempt, and creates no\nGrade: it is not a grade and never completes the lesson. A repeat returns the\nsame attestation. Other kinds throw `OwnAttestationLessonKindError`;\nsubmitted, review, complete, skipped or already-attested progress throws\n`OwnAttestationConflictError`. Submission views carry `selfReported: true` for\nit; a guardian confirms with `attestLesson` (which grades that attestation) or\n`reviewSubmission`, and the guardian grade then distinguishes confirmed from\nself-reported evidence. A host without `lesson_self_attestations` gets\n`LearnerHistoryUnavailableError`.\nOmitted/null score is unscored; zero is a real score. The latest guardian grade\nwins over auto/AI/instructor proposals, and its score replaces progress's score.\nReview history is retained. ExternalCompletion is available for trusted server\npersistence; phase-zero learner handlers cannot forge reported scores. Online\nsubmissions and automatic grading are not implemented.\n\n`getSubmission` returns only submission metadata, page asset IDs and the selected\ngrade. It does not include catalog answers, extracted answers, storage paths,\nmodel objects, or database handles.\n\n`getLatestLessonSubmission` takes the learner request, `enrollmentId` and\n`lessonId`, repeats live read authorization and exact enrollment/catalog lesson\nscope, and returns the same safe view or `null` when no eligible work exists.\nIt reads at most one submission for that exact progress, choosing `completed_work`\nin `captured`, `needs_review` or `graded` status by `submittedAt DESC, id DESC`.\nBlank references, extracting and rejected work are excluded. Committed capture\nis retained evidence; it does not assert lesson completion. Hosts select completed\nlessons from authorized progress separately. An empty safe page list does not\nfall back to older work; asset signing still requires its own live authorization.\n\n## Storage and signed routes\n\nThe service creates an AssetRuntime bound to the operation's transaction. It\nrequires a resolved URI whose filename retains the fresh asset UUID and MIME\nextension; custom resolvers may choose its provider/directory but must route\nthat URI to the corresponding unique file. Shared existing locators are\nrejected before preservation or cleanup registration. It plans and persists\nthat unique asset URI before writing, registering that new\nasset for cleanup before the provider can partially write. After rollback,\nfiles are removed through the runtime store. Before deletion, the root database\nmust confirm that no asset owner committed: uncertain commit/read failures never\ncause committed bytes to be removed. Only this operation's newly created assets\nare candidates; pre-existing files are never adopted into its cleanup ledger.\n\nDatabase metadata is atomic; external storage uses compensation, not a database\ntransaction. If cleanup cannot complete, `SubmissionStorageCleanupError` contains\nfresh asset IDs and the original cause. Operators must reconcile those IDs in\nthe configured `education-page/<id>.<extension>` storage namespace (custom\nresolvers must retain their routing audit). A successful retry uses fresh IDs\nand cannot delete or reuse orphaned bytes. Process termination may also leave\nunreferenced files; hosts need storage orphan reconciliation. Do not suppress\ncleanup failures or claim crash-safe distributed atomicity.\n\n`signSubmissionAsset` verifies the submission/enrollment/learner ownership and\nits noun join, then verifies the Asset's tenant and learner profile before\ncalling the configured trusted signer. Claims contain actor, tenant, learner,\nenrollment, submission, asset and a five-minute expiry; no static source URI is\nreturned. The host signs every claim and its serving endpoint must verify the\nsignature, expiry, current actor/tenant and object authorization before serving.\nA bearer URL must never become a cross-family or sibling access bypass.\n\n`signLessonPrintable` signs only the exact authorized `printable` LessonAsset\njoin for an enrolled lesson. It never accepts an answer-key join and carries the\nsame tenant, actor, learner and enrollment scope as a submission claim.\n\n## Personal worksheet packets\n\n`splitWorksheetPacket` takes the guardian learner request, exact-owned\n`personal-use-copy` `courseId`, PDF bytes and ranges `{lessonId, firstPage,\nlastPage}`. Page bounds are inclusive and one-based. Ranges must be in bounds,\ndisjoint and target distinct Worksheet lessons in that private course. The\n50 MiB / 100-range limits are enforced before PDF parsing. `pdf-lib` extracts\nactual pages into independent PDFs and records private printable LessonAssets.\nAll resulting metadata commits together; storage failure compensates new PDFs.\nThe source packet is not retained. No shared/global course is accepted and no\nanswer-key join is created. A successful repeated packet upload intentionally\nadds another printable version; a failed upload can be retried safely.\n\nShared integration workflows run on SQLite and real PostgreSQL. Full DuckDB\nworkflow support remains outside the existing supported schema boundary.\n\n## Private asset boundary\n\nCaptured pages and split packet pages use `Asset.accessMode: 'private'` from their\ninitial insert. Ordinary generated Asset REST/MCP operations cannot list, hydrate,\nupdate or delete them, including through the parent STI model. The service opens\nan exact tenant/actor/learner-owner/asset-ID capability only after its normal learner\nrelationship checks. A host's signed serving route must repeat authorization and\nopen that exact capability before loading the asset. See the owning\n[private asset contract](../../assets/agents/private-assets.md).\n\nStorage must be private (including provider ACLs). Public HTTP(S) source locators\nare rejected; a hidden URL alone cannot protect publicly accessible bytes. Apply\nthe manifest migration adding `assets.access_mode` before deploying this runtime;\nlegacy ordinary assets retain the public default. Runtime creates no schema.\n\nPrivate lesson files must already be private Assets in the same tenant. Saving\nan answer-key join, or any join under a personal-use-copy course, requires the\nhost's exact actor/owner/asset capability; a public asset is never automatically\npromoted. Packet splitting retains this capability while creating each join.\nPersisted course tenant/license and section/lesson parent identity cannot change;\ncreate new structure and explicitly re-author its joins instead. Mandatory\nwrite predicates enforce this even for natural-key adoption and concurrent writes.\nOrdinary content and metadata refresh remains supported. This\nprevents existing public material being reclassified by moving its parent.\n\nFor pre-existing invalid joins, an authorized host must inventory private-material\njoins and remove invalid associations, recreate the bytes in private storage as a\nnew privately classified Asset, then re-author the join under its exact capability.\nDo not merely hide the URI, mutate access_mode with raw SQL, or delete shared\npublic bytes. This repair requires explicit storage/ownership authorization;\nnormal runtime does not migrate existing records.\n"
     },
     {
       "path": "agents/workbook-service.md",
@@ -12470,6 +13283,11 @@
       "module": "question-records",
       "content": "# Question and learning-objective records\n\n`QuestionAuthoringService` (SMRT #4515, extends `CourseAuthoringService`, consumed\nby Hearth #68) keeps authored questions and learning objectives. Risk is high:\nschema and public contract. It reuses the course authorizer: writes need\n`education.course.author` (plus `generate` for generated provenance), reads that\nreturn answer keys need `education.course.read-draft`; every call receives the\ntransaction executor and the operation (`create-question`, `save-question`,\n`link-objectives`, `create-objective`, `save-objective`, `read-question`,\n`read-worksheet`, `resolve-question-revisions`, `attach-printable`). Tenant is required; foreign ids are not-found.\n\n## Models (closed, required tenant, no REST/CLI/MCP/AI, append-only)\n\n`Question` (identity, optional authored `courseId`), `QuestionRevision`,\n`LearningObjective` (identity with tenant-unique stable `externalKey`, for\ncoordination with hearthed.org#35), `LearningObjectiveRevision`,\n`QuestionResponse`. `save()` on an existing row and `delete()` throw. There is no\nhead row: the head is the highest `sequence`, and writes take an expected-head\ntoken under a row lock and a unique `(identity, sequence)` index.\n\nA revision holds prompt, response type, choices, subparts, media (tenant assets),\nobjective identity ids, concept ids, answer key, rubric and points. A missing key\nor rubric is stored NULL and read back `null`; an empty key is invalid and is never\ninferred. Provenance (`supplied|inferred|generated|edited|extracted`) is recorded\nfor each present field, defaulting to the revision's; provenance for an absent\nfield is refused. Objectives are linked by identity id, so wording changes, variants\nand themes keep the same objective.\n\n## Writes\n\n`createQuestion`, `saveQuestionRevision`, `linkObjectives`,\n`createLearningObjective`, `saveLearningObjectiveRevision`. Every write needs a\nrequest key; a retry replays its original result and the same key with another\npayload throws `CourseRequestKeyConflictError`. A stale head throws\n`CourseStaleHeadError`; a reused objective key throws\n`LearningObjectiveKeyConflictError`. Errors keep stable `code`s.\n\n`resolveQuestionRevisions({ revisionIds })` (`read-draft`, no course; the executor and delegation fields\nare passed) returns `{ items, missing }`: per found id `revisionId`, `questionId`, `sequence`,\n`responseType`, `promptSummary` (plain text, whitespace collapsed, at most 200 characters) and, when\nlinked, `learningObjectiveKeys`. Never keys, rubrics, choices, media or provenance. 1-200 ids (else\nvalidation error), de-duplicated, request order. An id with no revision in this tenant, foreign or\nunknown alike, appears only in `missing`.\n\n## Lessons, attempts, grades\n\nA lesson input may carry ordered `questions` (revision id, section, column, source\npage/rect anchor) and flat `layoutParams`; they are part of the lesson revision\ndigest, and saving requires each id to be an existing question revision of the\ntenant (`QuestionReferenceError`). Newer question revisions never move a pin.\n\n`WorkbookQuestion.questionRevisionId`/`lessonRevisionId` and the nullable\n`Grade.questionRevisionId` are additive. A referenced revision must exist in the\ntenant; `Grade.rubricResults` must then fit its rubric (criterion id, number or\n`{points}` up to `maxPoints`; empty stays unscored; results need a rubric).\nUnreferenced legacy records are unchanged. `QuestionResponse` is an append-only\nlearner response to one exact revision with completion mode\n(`printable|online|interactive`), assistance, a correction chain, `episodeId` and\nthe `worksheetVersionId` seen, a numbered `attemptNumber` and the writing request's\n`payloadDigest`. Writes go through `QuestionResponseService` below.\n\n## Responses (`QuestionResponseService`)\n\nExtends `LearnerService`, so it uses the learner authorizer, active-actor/tenant\nchecks and executor-bound policy reads. New authorizer actions:\n`education.learner.respond` (the learner's own enrollment; a guardian never starts\nan attempt) and `education.learner.review-response` (guardian only; a learner\nclaiming it is refused before the host is asked).\n\n- `recordResponse`: online attempt (new episode, next `attemptNumber`) or, with\n  `correctsResponseId`, the learner's correction in the same episode.\n- `recordGuardianCorrection`: names the response it corrects; `response` omitted\n  records assistance only and keeps the answer. Both append; nothing is rewritten.\n- `readLessonResponses`: the audience follows the actor. The learner gets the\n  keyless bundle (keys never leave the database call), the guardian the keyed one.\n\nThe question revision must be in the enrollment's effective lesson set\n(`resolveEnrollmentLessons`, then the lesson revision's `questions`); otherwise\n`QuestionResponseScopeError`. Unpinned enrollments have no authored questions.\nThe response is a closed shape (`text`, `numeric`, `choiceIds`, `parts`) checked\nagainst the revision's choices and subparts (`QuestionResponseValidationError`).\nEvery write needs a request key (unique per learner); a replay returns the stored\nrow, another payload throws `CourseRequestKeyConflictError`. Other errors:\n`QuestionResponseNotFoundError`, `LearnerAuthorizationError`.\n\n## Rendering\n\n`getWorksheet` (or the pure `buildLearnerWorksheet`/`buildGuardianWorksheet`)\nbuilds one bundle from a release lesson's pinned revisions. `worksheetVersionId` is\na digest of ordered revision ids, placement and layout params, so printable and\nonline renders of the same revision match and a scan can be matched later. The\nlearner bundle is built from an allowlist and has no key, rubric or provenance\ntype members; only the guardian bundle carries them. Both service audiences need\n`read-draft`; learner delivery belongs to the host.\n\n## Generated printables (`attachGeneratedPrintable`)\n\nHosts render worksheets from `QuestionRevision` records but cannot write `LessonAsset`\nrows. `attachGeneratedPrintable({ ...actor, lessonId, worksheetVersionId, audience })`\n(`audience`: `learner` or `guardian`) renders the released lesson's worksheet to a PDF\nupstream with `pdf-lib` (no host PDF dependency), stores it as a private education-owned\nasset and links it to the lesson, so the durable print queue can serve it. It returns the\nclosed `{ lessonId, worksheetVersionId, audience, assetId, relationship, created }`; never keys,\nanswers or source URIs.\n\n- `lessonId` is the materialised `lessons` row id of a released lesson (`released_lessons.lesson_id`),\n  resolved in the actor's tenant; unknown and foreign ids alike are `QuestionNotFoundError`.\n  `worksheetVersionId` must equal the digest of that lesson revision's refs and layout, else\n  `WorksheetVersionMismatchError` (`worksheet-version-mismatch`), so a later scan matches. A lesson with no\n  questions is a validation error.\n- Relationship rules: the learner copy is built from the keyless learner bundle only and linked\n  `printable`; the guardian copy is built from the keyed bundle (answer keys, explanations, rubric summaries)\n  and linked `answer-key`. `SubmissionService.signLessonPrintable` matches only `printable` joins\n  (explicit filter, test-pinned), so an answer-key copy is never signed for a learner.\n- Authorization: `education.course.author` for either audience, plus `education.course.read-draft`\n  for `guardian` (the audience only picks the artefact and never widens authority). A learner of the\n  tenant, or a delegation naming one as actor or delegating guardian, is refused with\n  `CourseAuthoringAuthorizationError` before the host authorizer is asked. Delegated agents use\n  `verifyDelegation` like every authoring call (refused without it).\n- Idempotent per (tenant, lesson, worksheet version, audience) via the append-only closed\n  `GeneratedPrintable` model (unique index). A repeat returns the same asset with `created: false` and\n  renders and stores nothing. The lesson row is locked before the check; a lost unique-index race is\n  compensated and replayed once, so concurrent first calls converge on one asset with no orphan file.\n- Storage: pass `printableAssets: { storage, storeOptions? }` (same shape as `SubmissionService`) to the\n  service. Without it the call throws `PrintableStorageNotConfiguredError`. The PDF is a `private` asset\n  (`typeSlug` `education-page`) owned by the acting guardian's profile, or for a delegated agent the delegating\n  guardian's; none available is `PrintableOwnerError`. Asset rows, the join and the model row commit in one\n  transaction; newly planned files are removed after rollback unless the asset row committed\n  (`PrintableStorageCleanupError` carries fresh asset ids if removal fails).\n- Renderer limits: standard Helvetica fonts only, Letter pages. Characters outside WinAnsi are replaced\n  with `?` (never an error); media refs print as a short placeholder line, never the media. Bounded:\n  200 items, 10,000 characters per text value, 400,000 in total, 150 pages (`CourseAuthoringValidationError`).\n  Output is deterministic: fixed creation/modification dates, footer on every page with the worksheet\n  version id and audience, PDF title/subject/keywords carrying the version id.\n\n## Migration\n\nSchema ships through normal manifest migrations: six new tables (`question_responses` and `generated_printables` included) plus nullable\ncolumns on `grades` (`question_revision_id`) and `lesson_revisions` (`questions_json`,\n`layout_params_json`); test-pinned as additive. The runtime never creates tables.\n"
     },
+    {
+      "path": "agents/question-extraction.md",
+      "module": "question-extraction",
+      "content": "# Question extraction from scans and imported courses\n\n`QuestionExtractionService` (SMRT #4517, extends `QuestionAuthoringService`,\nconsumed by Hearth #80 and #94) turns ingestion proposals into structured,\nversioned question records. Risk is high: new schema, a public contract and\nidempotent writes. It reuses the course authorizer: preserve and apply need\n`education.course.author`; `readExtraction`, `findExtraction` and\n`resolveWorksheet` need `education.course.read-draft`. Operations:\n`preserve-question-extraction`, `apply-question-extraction`,\n`read-question-extraction`, `read-worksheet`.\n\n## Flow\n\n1. Receive the scan or course file through ingestion and extract it (OCR or\n   vision, with `observeAnswerRegions` for image region catalogs).\n2. Offer `educationQuestionExtractionHandler({ extractions, request })` (from\n   `@happyvertical/smrt-education/ingestion`) in the execution catalog and\n   generate proposals. Its closed `QUESTION_EXTRACTION_ARGS_SCHEMA` is the\n   extracted question set. Keep `requireReview: true` on every policy layer.\n   Size the policy `maxBytes` and proposal output limits for whole worksheets:\n   up to 200 questions, 400 student-work entries and 1000 pages.\n3. `preserveQuestionExtractionAnalysis({ ingestion, extractions, request,\n   itemId, expectedWorksheetVersionId?, worksheets? })` reads the completed\n   proposal, validates it against retained evidence, matches it and records a\n   `QuestionExtractionRecord`. It returns `QuestionExtractionView` for\n   extraction review. Not ready, no proposal or competing proposals throw\n   `QuestionExtractionPendingError` (`reason`); invalid output throws\n   `QuestionExtractionValidationError`. No question records are written.\n4. The reviewer previews and decides through ingestion. The handler apply\n   calls `applyExtraction` on the ingestion transaction and returns the\n   per-question outcomes (`ExtractedQuestionResult[]`, also on `view.applied`).\n\nHosts without an ingestion proposal (for example a trusted bundle importer)\ncall `preserveExtraction` directly with their own grounding and extractor\nidentity, then `applyExtraction`.\n\n## Extraction contract\n\n- Every retained source, and each page the provider reported, has a `pages`\n  entry with a role (`exercise`, `example`, `instructions`, `cover`,\n  `answer_key`, `mixed`, `unknown`) and readability. A missing page is invalid,\n  so unreadable or unsupported content is marked, never dropped. Items that\n  cannot be read keep their key and numbering with `status` `unreadable` or\n  `unsupported` and a null prompt; other gaps go in `omissions`.\n- What ingestion itself did not extract stays visible. A retained original with\n  no result, and pages that ingestion omitted or failed, are kept in the\n  grounding: the extractor may cite them, and any it does not cover are added as\n  `unreadable` pages with a `not_extracted` omission. Truncation and\n  `source_incomplete` warnings are carried to `extraction.sourceWarnings` and\n  the handler preview. More than 1000 pages is refused, never trimmed.\n- Questions hold printed text only. Learner handwriting goes in `studentWork`\n  (null `observed` when illegible) and never becomes question content.\n- Anchors cite an original `evidenceId`, a physical page the provider\n  reported (null when unknown) and a `regionId` from that evidence's\n  `observedRegions` catalog. The rect comes from the catalog only; an unknown\n  region is invalid. Coordinates are never accepted from the extractor.\n- `origin: 'source' | 'inferred'` marks response type, keys, rubrics and points.\n  On apply, printed facts get `extracted` provenance and inferred facts get\n  `inferred`. An empty key is invalid; a missing key stays null.\n- Diagram and media references are kept on the link with their anchor. They\n  are not question `media`, which must name a tenant asset.\n\n## Matching\n\n`matchExtractedQuestions(extraction, worksheets, { expectedWorksheetVersionId })`\nis pure. A match needs a worksheet identity (the `wsv1-` id generated printables\nprint in their footer, or a host-supplied expectation), plus the printed\nposition (`1`, `1.`, `Q1`) of an item on that worksheet. Every claimant of a\nposition counts, including one that fails a layout check. Section label, a\nsource-printed response type, and choice and subpart counts must agree. Prompt\ntext is never used. A printed id that disagrees with the expectation, any layout\nconflict, or two items claiming one position is `ambiguous` and stays\nunattached. Examples are never matched. `resolveWorksheet` finds a worksheet by\nid through `generated_printables`; host-supplied worksheets must be this\ntenant's revisions. Student work gets a `questionRevisionId` only when its\nquestion matched. Recording attempts and grades stays with the workbook and\nresponse services.\n\n## Idempotency\n\n`sourceIdentity` is a digest of the source kind and the sorted retained evidence\nhashes, never text. Preserve is idempotent per (tenant, intake item, analysis\nattempt). A different payload for the same attempt throws\n`CourseRequestKeyConflictError`. The payload includes the grounding, the\nextractor identity and the expected and supplied worksheets. Apply writes questions through `createQuestion`\nwith request key `qx:<sourceIdentity>:<questionKey>`, so re-ingesting the same\nbytes replays the same questions (`replayed`). Identical prompts under different\nkeys stay separate records. If the same source is extracted again with different\ncontent, the outcome is `source_changed`: nothing is overwritten. A new scan has\nnew bytes, so it is a new source, and it links to known questions only by\nmatching. A repeated apply replays the stored `ExtractedQuestionLink` rows.\n\nOutcomes: `created`, `replayed`, `matched` (these carry a revision),\n`needs_review` (ambiguous), `source_changed`, `invalid_content` (fails question\nvalidation), `unreadable`, `unsupported`, `not_an_exercise`.\n\n## Models (closed, required tenant, no REST/CLI/MCP/AI, append-only)\n\n`QuestionExtractionRecord` (`question_extractions`: unique tenant/item/attempt,\nindexed source identity, extractor identity, validated extraction and match JSON,\nproposal digest) and `ExtractedQuestionLink` (`extracted_question_links`: unique\ntenant/extraction/key; outcome, question and revision ids, anchors and media).\nBoth ship through normal manifest migrations. The originals stay in ingestion\nand are never copied. Imported material keeps its course licence; extraction\ndoes not change sharing.\n\nNot in this release: zip/bundle manifests (SMRT #4578), automatic new\nrevisions on `source_changed`, and media assets for extracted diagrams.\n"
+    },
     {
       "path": "agents/source-import.md",
       "module": "source-import",
@@ -12574,7 +13392,7 @@
         "description": "Courses and lessons for learning."
       },
       "help": {
-        "markdown": "# Learners\n\nUse `LearnerService` in an authenticated exact-tenant context to read a learner,\nplan a curriculum as an authorized guardian, enroll in a visible course, and\nstart a lesson. Recipe metadata does not expose model CRUD. Hosts authenticate\nusers, provision family membership, and validate guardian ProfileRelationship\ntypes and effective terms. See `agents/learner-service.md` for the boundary.\n",
+        "markdown": "# Learners\n\nUse `LearnerService` in an authenticated exact-tenant context to read a learner,\nplan a curriculum as an authorized guardian, enroll in a visible course, start\nor put back a lesson, and start, pause, resume or drop an enrollment. Recipe\nmetadata does not expose model CRUD. Hosts authenticate users, provision family\nmembership, and validate guardian ProfileRelationship types and effective\nterms. See `agents/learner-service.md` for the boundary.\n",
         "fieldRefs": []
       },
       "runtime": "both",