@happyvertical/smrt-education 0.57.37 → 0.57.39

package/dist/smrt-knowledge.json

@@ -3,18 +3,20 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-education",
-  "packageVersion": "0.57.37",
+  "packageVersion": "0.57.39",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "13a3f757f18cc0cfed8d07ffc42cda60e62cf40766265cc23d08ed0482704806",
-    "packageJson": "8707ae756fce4cae2c1ad80e92b1352ecd85386f1b7f6b58c925cfba44e5d19b",
-    "agents": "bf8b00b31d2dfc9394ab1766421bbeb2dcc5326db3ea60ecc9922b6800f21f48",
+    "manifest": "5c6a35e0af4e4612477d70216ad90e72b2bdaec842ee8cf11d726588dad34486",
+    "packageJson": "b7020102a3bac6fe5771314550029c5157fd9a68e47205dbe45210ea4192ff5f",
+    "agents": "f06312dca0737d6487b4f310b22b6c24b3276644e9ccaf9b7a27b71ebc1ca2ff",
     "moduleDoc:agents/learner-service.md": "7da70d214547eb78fbf058e997599cc80ab86f5bb55748bd158a9a4b30070d3b",
     "moduleDoc:agents/submission-service.md": "8e63b83ac84628d5e5ddacbb6a47077c0e65eee3da87518d9bf6e30fb8348336",
     "moduleDoc:agents/workbook-service.md": "3ca3fb60d39daf76b94ec668fc19dc67aa7e090b7f44412bed5c9d92e8efaf5a",
     "moduleDoc:agents/photo-intake.md": "3b7057201ee30b2361aad23ea52e8a55c8ed5354e7a7e4a8193b7de17ca2f0db",
-    "moduleDoc:agents/source-import.md": "30ee823589d655442bcf1abcd86a2132172065b4bc5e3c4d89b1e8b7afcc66bc"
+    "moduleDoc:agents/source-import.md": "30ee823589d655442bcf1abcd86a2132172065b4bc5e3c4d89b1e8b7afcc66bc",
+    "moduleDoc:agents/family-intake.md": "540b6d37f438496acb0208b6ac7258264e2142bce3d2f986967b7741606fe4f7",
+    "moduleDoc:agents/catalog-previews.md": "5f4e0352274009b3ce00408017a16666036d24df695a7078c27317ba4e66f0a7"
   },
   "exports": [
     ".",
@@ -59,7 +61,7 @@
     "smrt"
   ],
   "risks": [
-    "cross-package-refs:6",
+    "cross-package-refs:8",
     "sensitive-fields-excluded",
     "sti-inheritance"
   ],
@@ -282,6 +284,12 @@
           "required": false,
           "columnType": "TEXT"
         },
+        {
+          "name": "preview",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
         {
           "name": "licenseEvidence",
           "type": "text",
@@ -317,14 +325,27 @@
       ],
       "relationships": [],
       "methods": [
+        "getPreview",
         "getRepresentation",
+        "setPreview",
         "setRepresentation"
       ],
       "methodSignatures": [
+        {
+          "name": "getPreview",
+          "returns": "CatalogPreview | undefined"
+        },
         {
           "name": "getRepresentation",
           "returns": "CatalogResourceRepresentation | undefined"
         },
+        {
+          "name": "setPreview",
+          "params": [
+            "value: CatalogPreview | undefined"
+          ],
+          "returns": "void"
+        },
         {
           "name": "setRepresentation",
           "params": [
@@ -335,6 +356,13 @@
       ],
       "surfaces": [],
       "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "getPreview",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:CatalogResource"
+        },
         {
           "kind": "api",
           "operation": "getRepresentation",
@@ -342,6 +370,13 @@
           "reason": "api is disabled",
           "objectName": "@happyvertical/smrt-education:CatalogResource"
         },
+        {
+          "kind": "api",
+          "operation": "setPreview",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:CatalogResource"
+        },
         {
           "kind": "api",
           "operation": "setRepresentation",
@@ -741,6 +776,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -923,6 +961,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1094,6 +1135,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1166,6 +1210,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1306,6 +1353,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1448,6 +1498,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1585,6 +1638,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1735,6 +1791,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -1866,6 +1925,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -2501,6 +2563,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -2568,6 +2633,401 @@
       "tags": [],
       "risks": []
     },
+    {
+      "name": "FamilyIntake",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntake",
+      "collection": "familyintakes",
+      "description": "Family-owned receipt, independent of learner attribution and ingestion expiry.",
+      "tableName": "family_intakes",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "itemId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "ownerProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "columnType": "UUID"
+        },
+        {
+          "name": "contentDigest",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sourceJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "ownerProfileId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-profiles:Profile",
+          "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",
+        "item_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntake"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntake"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeCollection",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeCollection",
+      "collection": "familyintakes",
+      "tableName": "family_intakes",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeAsset",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeAsset",
+      "displayLabelField": "name",
+      "collection": "familyintakeassets",
+      "description": "Sole family owner join; adoption borrows this exact immutable original.",
+      "tableName": "family_intake_assets",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "columnType": "UUID"
+        },
+        {
+          "name": "name",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "mimeType",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sha256",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "position",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        }
+      ],
+      "relationships": [
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "assetId",
+          "type": "crossPackageRef",
+          "required": false,
+          "related": "@happyvertical/smrt-assets:Asset",
+          "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",
+        "intake_id",
+        "asset_id"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeAsset"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeAsset"
+        }
+      ],
+      "relationshipFeatures": [
+        "crossPackageRef",
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeAssetCollection",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeAssetCollection",
+      "collection": "familyintakeassets",
+      "tableName": "family_intake_assets",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeDecision",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeDecision",
+      "collection": "familyintakedecisions",
+      "description": "Append-only attribution/adoption audit; no marks or learning outcomes.",
+      "tableName": "family_intake_decisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtObject",
+      "fields": [
+        {
+          "name": "tenantId",
+          "type": "text",
+          "required": true,
+          "columnType": "UUID"
+        },
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
+        {
+          "name": "requestKey",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "sequence",
+          "type": "integer",
+          "required": true,
+          "columnType": "INTEGER",
+          "default": 0
+        },
+        {
+          "name": "actorUserId",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        },
+        {
+          "name": "bodyJson",
+          "type": "text",
+          "required": false,
+          "columnType": "TEXT"
+        }
+      ],
+      "relationships": [
+        {
+          "name": "intakeId",
+          "type": "foreignKey",
+          "required": true,
+          "related": "FamilyIntake",
+          "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",
+        "intake_id",
+        "request_key"
+      ],
+      "surfaces": [],
+      "withheldSurfaces": [
+        {
+          "kind": "api",
+          "operation": "delete",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeDecision"
+        },
+        {
+          "kind": "api",
+          "operation": "save",
+          "code": "api-disabled",
+          "reason": "api is disabled",
+          "objectName": "@happyvertical/smrt-education:FamilyIntakeDecision"
+        }
+      ],
+      "relationshipFeatures": [
+        "foreignKey",
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
+    {
+      "name": "FamilyIntakeDecisionCollection",
+      "qualifiedName": "@happyvertical/smrt-education:FamilyIntakeDecisionCollection",
+      "collection": "familyintakedecisions",
+      "tableName": "family_intake_decisions",
+      "packageName": "@happyvertical/smrt-education",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "Learner",
       "qualifiedName": "@happyvertical/smrt-education:Learner",
@@ -2652,6 +3112,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -2768,6 +3231,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -2898,6 +3364,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3034,6 +3503,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3130,6 +3602,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3299,6 +3774,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3376,6 +3854,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3567,6 +4048,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -3765,6 +4249,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -3923,6 +4410,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4011,6 +4501,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4145,6 +4638,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         },
         {
@@ -4269,6 +4765,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4436,6 +4935,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4615,6 +5117,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4800,6 +5305,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -4982,6 +5490,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5141,6 +5652,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5286,6 +5800,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5363,6 +5880,13 @@
           "related": "Learner",
           "columnType": "UUID"
         },
+        {
+          "name": "familyIntakeId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
+        },
         {
           "name": "itemId",
           "type": "text",
@@ -5389,6 +5913,13 @@
           "required": true,
           "related": "Learner",
           "columnType": "UUID"
+        },
+        {
+          "name": "familyIntakeId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "FamilyIntake",
+          "columnType": "UUID"
         }
       ],
       "methods": [
@@ -5404,6 +5935,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5556,6 +6090,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5695,6 +6232,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5828,6 +6368,9 @@
         {
           "name": "save",
           "async": true,
+          "params": [
+            "options?: SmrtSaveOptions"
+          ],
           "returns": "Promise<this>"
         }
       ],
@@ -5885,14 +6428,14 @@
   "surfaces": [],
   "prompts": [],
   "relationshipsV2": {
-    "foreignKeyFields": 70,
-    "crossPackageRefFields": 6,
+    "foreignKeyFields": 73,
+    "crossPackageRefFields": 8,
     "junctionCollections": 2,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 298
+    "uuidColumns": 320
   },
-  "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\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",
+  "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\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",
   "moduleDocs": [
     {
       "path": "agents/learner-service.md",
@@ -5918,6 +6461,16 @@
       "path": "agents/source-import.md",
       "module": "source-import",
       "content": "# Source import integration\n\n`SourceImportService` is a server-side host boundary, with no generated REST,\nCLI, MCP or AI operation. Recipes remain metadata only. Provision a closed\n`CourseSource` in the owning tenant, then construct the service with the root\nSQL database and an actor-bound `SourceImportAuthorizer`. Enable tenancy and\ncall within `withTenant({ tenantId, userId })`; the request must match both.\nMissing context, a different actor/tenant and super-admin bypass fail closed.\n\nRegister Easy Peasy only after the host operator accepts its terms, using\n`registerEasyPeasy({ termsAccepted: true, fetchPage })`. Do not derive that\nboolean from an HTTP request. `fetchPage(url, { redirect: 'error' })` must reject\nredirects, bound time/size and return `{ html, url }`. It fetches the page only,\nnever a PDF. The service checks the approved HTTPS URL before fetching, checks\nthe response URL, limits HTML to 2 million characters, then parses the complete\npage before any write. There is no automatic registration or network access. Structural h1–h6 headings delimit day content, including trailing Resources\nsections; ordinary non-lesson bold instructions do not. Supported\nheading blocks are h1–h6 or a lesson marker as the first bold run in a\nparagraph/list item.\nRecognizable markers outside that layout, including multiple markers in one\nparagraph, fail closed rather than silently assigning a PDF to the wrong day.\n\nThe authorizer must verify the authenticated actor's management grant and the\nprovisioned tenant's family/group classification. Tenant has no built-in kind;\nneither hierarchy position nor client input establishes a family. Authorization\nis required before fetch and again inside the transaction; callbacks must be\nread-only decisions, since a rolled-back contention retry can call them again.\n\n`sharing` is a ceiling: private permits private-family import only; group and\nglobal permit private-family or group import. Group imports additionally require\nnonblank host-recorded `config.licenseEvidence` and an explicit host grant that\nvalidates that permission. Global/null destinations are unsupported and rejected;\nthere is no global/system bypass. Widening a source never promotes existing\nimports. Private imports are draft `personal-use-copy` courses and retain the\ncatalog's immutable owner/license and no-publication protection. A host may\ncreate a new licensed group source and import there after receiving permission.\n\nUse a stable `courseRef` independent of source URLs. Identities derive from the\nowning tenant, source row ID, course reference and lesson day; retain the source\nrow when updating policy. Changes to titles/page/PDF URLs update in place.\nMissing days are retained, not deleted, so enrollment, progress, submission and\nasset foreign keys remain valid. A changed lesson kind fails the whole import\nrather than replacing a row. Only title and pointer fields are refreshed; body,\nanswer keys, learner state and manually authored settings are never replaced.\nThe packet URL is returned as a source link and is not downloaded or mirrored.\n\nAll source policy rechecks and catalog mutations use collections bound to the\nsame SQL transaction. Embedded writes use the public write queue; PostgreSQL\nserializes an import identity with a transaction-scoped advisory lock. Only\nrolled-back busy/serialization/deadlock errors retry (at most three retries),\nwithout repeating fetch. Connection-invalidated and other failures propagate.\nDo not wrap the service in a caller transaction if the caller expects a durable\ncommit before returning; any outer transaction remains the caller's boundary.\n\nSQLite and PostgreSQL integration tests exercise real transactions and rollback.\nFull catalog children remain unavailable on DuckDB due to core's existing\nON UPDATE CASCADE/self-referential schema limitations documented in\n[catalog-service.md](catalog-service.md); no alternate schema is substituted.\nTests use synthetic local HTML and an injected fetch callback, never the network.\n\nGoogle Drive discovery defaults every record to `teacher`. A trusted host may\nmake only an exact reviewed file ID visible by passing `studentSafeFileIds`;\nfolder IDs and descendant membership never grant visibility. A teacher-marked\nfolder or name still wins over that allowlist. File shortcuts are excluded: a\nshortcut does not prove the target remains under a reviewed root or retains the\ntarget's teacher-path classification. Resync after changing the allowlist: the\ndurable sync upsert rewrites existing visibility rather than retaining a\nprevious learner classification.\n\nGeneric “Printable” and “Printables” labels identify lesson PDFs; course packets\nrequire explicit packet/whole-course/complete-course wording. Only actual href\nattributes supply pointers; data-href metadata does not.\n"
+    },
+    {
+      "path": "agents/family-intake.md",
+      "module": "family-intake",
+      "content": "# Family intake\n\n`FamilyIntakeService` retains guardian-only originals before a learner is known.\nThe host supplies a trusted actor/tenant and a current family authorizer; each\nread, original download, assignment and adoption revalidates this authority on\nthe service's exact executor. Learners cannot browse the family inbox. Generated\nCRUD, CLI, MCP and AI surfaces remain closed.\n\nRetain the whole document with its source identity, delivery key, immutable hash\nand original private assets. Source delivery retries must preserve identical\ncontent and provenance. Email and scanner adapters are separate host configuration;\nthis service does not configure or select them. Trusted candidate DTOs and their\nquoted evidence are advisory. A guardian's active learner preference, visible\nmarks, uncertain names or a first-page guess never establish ownership. Mixed\nlearner PDFs stay unresolved until an explicit whole-document assignment is safe.\n\nAssignment records an immutable guardian decision with a revision and request\nkey. It does not create learner work. Adoption freezes that assignment and borrows\nthe exact original assets through learner photo ownership joins; it never rewrites\nsource confidentiality or creates grades. The existing photo resolution and\ncompleted-work capture preconditions still apply. Existing derived capture copies\nare permitted. Once adopted, a receipt cannot silently change learners; recovery\nrequires a separate explicit policy. An unadopted attribution can be corrected by\nanother audited decision with the current revision.\n\nFamily ownership retains originals beyond generic receipt expiry. Adoption does\nnot transfer or delete that ownership. Cleanup and rollback must preserve shared\nretained bytes and compensate only newly created files. Every access checks the\noriginal hash before adoption or download.\n\nValidation uses shared family workflows on real SQLite and isolated PostgreSQL;\nno AI providers, scanner/email services or containers are required.\n\nImport `FamilyIntakeService`, `receiveFamilyIntake` and\n`retainFamilyIntakeReceipt` from `@happyvertical/smrt-education/ingestion`.\nThe bridge uses the fixed `familyIntakeScopeId(tenantId)` namespace and public\n`getReceiptSource` to retain authoritative delivery identity. This namespace is\nnever an authorization grant. The host's `IngestionService.authorize` callback\nmust call the same current family authorizer on every operation, including direct\n`getEvidence`, `readEvidence` and `getReceiptSource` calls. For example, await\n`family.authorizeFamilyIntake({ tenantId: scope.tenantId, actorUserId: scope.actorId })`\nthen return true; propagate denial. Actor equality or tenant membership alone is\ninsufficient. This protects raw envelopes and rejected/unretained originals as\nwell as adopted receipts. Adoption permits only normal authorized learner work\nreads; it never grants the learner generic family ingestion access. A receive that\nsucceeds before education retention fails is repaired by retrying the same\nreceipt, never by inventing another delivery identity.\n\nDeploy manifest migrations for all three FamilyIntake models and the nullable\n`WorkbookPhotoIntake.familyIntakeId` FK before use. There is no runtime DDL.\nAdoption commits its immutable audit and exact photo/original joins atomically;\nthe family asset remains the sole original owner. Existing derived submission\ncopies use normal capture compensation. The exact adoption audit is required\nwhen validating borrowing joins, reads and immutable family-scope analysis.\n`countFamilyIntakes` counts unadopted receipts across the full inbox, while\n`listFamilyIntakes` pages the complete receipt history.\n\nAfter adoption, use the returned `photoIntakeId` with ordinary photo\nresolution/capture methods. Family-scope photo analysis checks the exact adopted\nitem/learner binding; learner-scoped uploads retain their existing strict scope.\nThe existing submission/assessment ingestion handlers still revalidate the\ncaptured learner/attempt. Temporary ingestion expiry does not prevent manual\nresolution/capture from retained education originals; re-analysis of an expired\nreceipt needs a separately authorized retained-input orchestration.\n\nThis initial contract assigns a whole receipt/document. It does not split a\nmixed-child PDF, automatically infer a child or configure a source adapter.\nFuture range adoption must preserve original hashes and page provenance; the\nretained immutable originals remain available for such an explicit workflow.\n\nSource-tree retention includes image/PDF attachments beneath metadata envelopes.\nA supported-media descendant of another supported original (for example a PDF's\npage thumbnail) stays in the evidence graph but is not duplicated as learner\nwork. Photo identification and captured-work analysis preservation use this same\noriginal-selection convention, so retained attachment hashes remain authoritative\nafter adoption and retries. The immutable graph retains only IDs, parent IDs, media types and hashes;\nit does not copy email bodies, arbitrary headers or credentials into public\nsource metadata. A source image such as an email logo is not automatically\nclassified as completed work. Whole-document attribution/classification remains\nan explicit guardian decision; ambiguous mixed contents need resolution.\n\nCustom source adapters must follow this supported convention: metadata parents\ncontain independent original attachments; descendants of supported media are\nrenditions of that media. Extraction outputs already live separately from source\nevidence. An adapter that uses media-child relationships for independently\nauthored attachments is unsupported by this bridge until its role is explicitly\nestablished; do not claim complete attachment fidelity for that shape or infer\nroles from first-page content. Full immutable evidence lineage is retained even\nwhen a rendition is excluded from capture pages.\n\nThe bridge rejects an entire receipt containing an unsupported independent\noriginal, including a mixed PDF/TIFF bundle, before family retention. Generic\nsource originals remain available for recovery; no partial family receipt or\nadoption is created. Hosts must acknowledge successful family import only after\nfamily retention succeeds and surface failed source imports. Known JSON\nmetadata wrappers and media descendants under the supported rendition convention\nare not independent originals.\n"
+    },
+    {
+      "path": "agents/catalog-previews.md",
+      "module": "catalog-previews",
+      "content": "# Publisher catalog previews\n\n`CatalogSourceRecord.preview` and `CatalogResourceView.preview` are optional\n`CatalogPreview` metadata. They describe a publisher image, not an acquired\noriginal, cover guarantee, download permission, or learner access grant. The\npublic root exports `CatalogPreviewService`, `CatalogPreviewStore`,\n`CatalogPreviewLoader`, `catalogPreviewFor`, and `normalizeCatalogPreview`.\n`CatalogResource.getPreview()` reads the guarded persisted JSON. Deploy the normal\nadditive manifest migration for its nullable `preview` column before sync; legacy\nrows have no preview. Sync retains the first retrieval timestamp on identical\nrevision retries and rejects changing an existing preview within that revision.\nNew revisions replace the current reference; old revision requests become 404.\nPNG verification resolves its Node host capability only when invoked; importing\ncatalog metadata/models remains browser-safe. Serving/verification requires a\nNode host and fails closed without it.\nThe image hash participates in the IM page record's revision, so changed bytes\ncannot silently reuse a preview revision.\n\nThe public IM first-edition adapter automatically selects at most one embedded\ninstructional diagram on a K–5 family-materials page. It requires that exact\npage's CC BY 4.0 footer and attribution, an official ImageFile figure with an\nempty caption, no separate credits or image-license notice in the instructional\ncontent, a descriptive chart/diagram alt, and an exact official asset identifier.\nBranding, photographs, credited or ambiguous images, other providers, unsupported\nformats and missing metadata remain absent. This narrow page-scoped policy does\nnot grant a provider-wide image license. The source footer explicitly excludes\nthe name/logo and preserves third-party image licenses; never remove those\nexclusions or apply this rule to arbitrary images. Existing teacher visibility\nis retained, including family hierarchy records currently classified teacher.\n\nConcrete publisher evidence, retrieved 2026-10-28:\n[Grade 1 Unit 1 Family Materials](https://im.kendallhunt.com/k5/families/grade-1/unit-1/family-materials.html)\nembeds ImageFile 38531, “Tally Chart. Turtle, tallies, 6. Dog, tallies, 2.\nRabbit, tallies, 12.” Its\n[official PNG](https://cms-assets.illustrativemathematics.org/fd1cykl2wl4zyfc6vzfkl3x09pvr)\nis 93,072 bytes, 1350 × 674. The licensed instructional fragment and PNG are\nfixtures in `src/__tests__/fixtures/im-family-*`, attributed to © 2021\nIllustrative Mathematics, CC BY 4.0. The image is unmodified. Captions or separate\nattribution appearing in a future sync make the preview unavailable.\n\nEnumeration performs metadata reads and at most one **preview image** GET per\npage; it never GETs original PDFs/ZIPs. It accepts only official HTTPS origin and\nopaque path, refuses redirects, and bounds the complete network/body operation\nby the adapter deadline (20 seconds default, 60 maximum). Required HTML/HEAD\nwork completes before optional sync previews, which get an independent deadline\nof one quarter of that budget, capped at two seconds and the remaining total\nenumeration budget. A hung preview cannot pause\nmetadata enumeration or its cursor. PNG previews have a\n2 MiB byte cap and 4096-pixel width/height cap. SVG, HTML, JPEG and other formats\nare currently unavailable. Only non-interlaced, static 8-bit RGB/RGBA PNGs are\nverified: complete chunks/CRCs/IEND and bounded inflated scanlines must be valid;\ntruncated or corrupt data never becomes a verified preview. This uses existing provider request bounds rather\nthan a general URL proxy. A preview failure leaves catalog metadata readable.\n`CatalogReadService.search()` performs no image or content fetches.\n\nWire a host endpoint using only the published root API:\n\n```ts\nimport {\n  CatalogPreviewService,\n  createPublicIllustrativeMathematicsFirstEditionAdapter,\n} from '@happyvertical/smrt-education';\n\nconst previews = new CatalogPreviewService({\n  // Both functions use your trusted active-session/tenant executor. Adapt your\n  // persisted resource to CatalogSourceRecord, including row.getPreview().\n  getResource: (id, actor) => catalogStore.getReadableResource(id, actor),\n  authorize: (actor, resource) => catalogPolicy.canReadNow(actor, resource.id),\n}, createPublicIllustrativeMathematicsFirstEditionAdapter());\n\n// Inside GET /catalog/preview; actor is derived from the server session.\nreturn previews.serve({ actor, resourceId, revision });\n```\n\nRender your own endpoint URL only when `view.preview` is present, using `alt`,\nwidth/height and rights attribution. Never place `reference` or `sourceUrl` into\nan image URL. The endpoint re-reads the current resource and checks active\nhost authorization, tenant/actor identity, teacher visibility, withdrawal,\nrevision and optional rights expiry on **every request**, including cache hits.\nThe host must check actor membership/active tenant, not merely trust strings in a\nrequest. Do not expose an unscoped collection read as this adapter.\n\nRights expiry is checked again after awaited loading/verification and before\nserving or inserting cached bytes. The per-service cache holds at most 16 MiB of verified public image bytes for at\nmost 60 seconds; reuse a service instance to benefit from it. Cache lookup occurs\nafter authorization. Changed length, dimensions or SHA-256, expiry, missing or\ninvalid metadata, upstream failures and access denial yield uniform 404 with\n`Cache-Control: no-store`; successful responses are PNG, `nosniff`, sandboxed,\nand `private, no-store`, so browsers cannot serve a revoked preview from cache.\nNo credential, upstream image URL, redirect or raw provider error reaches the\nbrowser. Synchronize regularly to observe publisher withdrawal/license changes;\nserver byte caching never bypasses the durable current-resource decision.\n\nPrivate asset previews and derivatives of acquired originals are unavailable in\nthis publisher-only contract. Use the asset authority and the separate acquired\noriginal derivative capability (#4470), with authorization on every private\nasset read. Possessing an asset, granting full-resource download/print, or being\nable to view a publisher page never supplies preview permission here.\n"
     }
   ],
   "recipes": [