@happyvertical/smrt-projects 0.55.6 → 0.55.8

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-projects",
-  "packageVersion": "0.55.6",
+  "packageVersion": "0.55.8",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "73fd367068244b6ee05f326fa7c52c6345f729b6a706b038b2ac1db4806d5d8f",
-    "packageJson": "2246018a856fc65f5e8fc573c1b46836b4632bbb4fef674e68e0798327842982",
-    "agents": "0bfcad468f2684901c34ae04db8a82343060ed97f9917ca415a82501fefed78d"
+    "manifest": "9b4beb24d74e64b7e5b50382d0ab7ab50cc1b3015d5a487b790743d2beac9bfc",
+    "packageJson": "1cafa7e6e0721830898133f6d527b25a981b08eb0b7791b80bf4e61efaed0aa1",
+    "agents": "014098eac2bb1699b653ccd3029e062a2312a521862e39225dd8ca73b6ae8206"
   },
   "exports": [
     ".",
@@ -83,6 +83,23 @@
     "sti-inheritance"
   ],
   "objects": [
+    {
+      "name": "CommentCollection",
+      "qualifiedName": "@happyvertical/smrt-projects:CommentCollection",
+      "collection": "comments",
+      "tableName": "comments",
+      "packageName": "@happyvertical/smrt-projects",
+      "extends": "SmrtCollection",
+      "fields": [],
+      "relationships": [],
+      "methods": [],
+      "surfaces": [],
+      "relationshipFeatures": [
+        "uuidColumns"
+      ],
+      "tags": [],
+      "risks": []
+    },
     {
       "name": "DevelopmentRequestHistoryCollection",
       "qualifiedName": "@happyvertical/smrt-projects:DevelopmentRequestHistoryCollection",
@@ -227,6 +244,7 @@
         "findByAssignee",
         "findByLabel",
         "findByNumber",
+        "findByProject",
         "findByRepository",
         "findByTenant",
         "findGlobal",
@@ -280,6 +298,14 @@
           ],
           "returns": "Promise<Issue | null>"
         },
+        {
+          "name": "findByProject",
+          "async": true,
+          "params": [
+            "projectId: string"
+          ],
+          "returns": "Promise<Issue[]>"
+        },
         {
           "name": "findByRepository",
           "async": true,
@@ -335,6 +361,14 @@
         }
       ],
       "surfaces": [
+        {
+          "kind": "api",
+          "name": "issues.findByProject",
+          "operation": "findByProject",
+          "objectName": "@happyvertical/smrt-projects:IssueCollection",
+          "path": "/issues/findByProject",
+          "method": "POST"
+        },
         {
           "kind": "api",
           "name": "issues.findByRepository",
@@ -421,6 +455,12 @@
           "operation": "discover",
           "objectName": "@happyvertical/smrt-projects:IssueCollection"
         },
+        {
+          "kind": "cli",
+          "name": "issuecollection_findByProject",
+          "operation": "findByProject",
+          "objectName": "@happyvertical/smrt-projects:IssueCollection"
+        },
         {
           "kind": "cli",
           "name": "issuecollection_findByRepository",
@@ -493,6 +533,12 @@
           "operation": "discover",
           "objectName": "@happyvertical/smrt-projects:IssueCollection"
         },
+        {
+          "kind": "mcp",
+          "name": "issuecollection_findbyproject",
+          "operation": "findByProject",
+          "objectName": "@happyvertical/smrt-projects:IssueCollection"
+        },
         {
           "kind": "mcp",
           "name": "issuecollection_findbyrepository",
@@ -1826,7 +1872,8 @@
           "type": "foreignKey",
           "required": false,
           "related": "Issue",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The issue this comment is on."
         },
         {
           "name": "commentId",
@@ -1840,14 +1887,16 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The comment text."
         },
         {
           "name": "author",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Who wrote it."
         },
         {
           "name": "createdAt",
@@ -2300,10 +2349,18 @@
         {
           "name": "repositoryId",
           "type": "foreignKey",
-          "required": true,
+          "required": false,
           "related": "Repository",
           "columnType": "UUID"
         },
+        {
+          "name": "projectId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Project",
+          "columnType": "UUID",
+          "description": "The project this issue belongs to."
+        },
         {
           "name": "number",
           "type": "integer",
@@ -2323,42 +2380,48 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short summary of the issue."
         },
         {
           "name": "body",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The full description."
         },
         {
           "name": "state",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "open"
+          "default": "open",
+          "description": "open or closed."
         },
         {
           "name": "author",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Who raised the issue."
         },
         {
           "name": "labels",
           "type": "json",
           "required": false,
           "columnType": "JSON",
-          "default": []
+          "default": [],
+          "description": "The labels attached to the issue."
         },
         {
           "name": "assignees",
           "type": "json",
           "required": false,
           "columnType": "JSON",
-          "default": []
+          "default": [],
+          "description": "The people working on it."
         },
         {
           "name": "commentsCount",
@@ -2392,9 +2455,16 @@
         {
           "name": "repositoryId",
           "type": "foreignKey",
-          "required": true,
+          "required": false,
           "related": "Repository",
           "columnType": "UUID"
+        },
+        {
+          "name": "projectId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Project",
+          "columnType": "UUID"
         }
       ],
       "methods": [
@@ -2407,6 +2477,7 @@
         "getComments",
         "getRepository",
         "getUrl",
+        "hasRepository",
         "incorporateFeedback",
         "isBugReport",
         "isFeatureRequest",
@@ -2469,6 +2540,10 @@
           "name": "getUrl",
           "returns": "string"
         },
+        {
+          "name": "hasRepository",
+          "returns": "boolean"
+        },
         {
           "name": "incorporateFeedback",
           "async": true,
@@ -2686,6 +2761,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-projects:Issue"
         },
+        {
+          "kind": "api",
+          "operation": "hasRepository",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-projects:Issue"
+        },
         {
           "kind": "api",
           "operation": "incorporateFeedback",
@@ -2766,26 +2848,37 @@
           "related": "Repository",
           "columnType": "UUID"
         },
+        {
+          "name": "projectId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Project",
+          "columnType": "UUID",
+          "description": "The project this label belongs to."
+        },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The label's name, for example bug."
         },
         {
           "name": "color",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The label's colour."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the label means."
         }
       ],
       "relationships": [
@@ -2795,6 +2888,13 @@
           "required": false,
           "related": "Repository",
           "columnType": "UUID"
+        },
+        {
+          "name": "projectId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Project",
+          "columnType": "UUID"
         }
       ],
       "methods": [
@@ -3032,28 +3132,32 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The project's name."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the project is about."
         },
         {
           "name": "owner",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Who owns or runs the project."
         },
         {
           "name": "url",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A link to the project elsewhere."
         },
         {
           "name": "providerType",
@@ -3692,10 +3796,18 @@
         {
           "name": "repositoryId",
           "type": "foreignKey",
-          "required": true,
+          "required": false,
           "related": "Repository",
           "columnType": "UUID"
         },
+        {
+          "name": "projectId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Project",
+          "columnType": "UUID",
+          "description": "The project this issue belongs to."
+        },
         {
           "name": "number",
           "type": "integer",
@@ -3715,42 +3827,48 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short summary of the issue."
         },
         {
           "name": "body",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The full description."
         },
         {
           "name": "state",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "open"
+          "default": "open",
+          "description": "open or closed."
         },
         {
           "name": "author",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Who raised the issue."
         },
         {
           "name": "labels",
           "type": "json",
           "required": false,
           "columnType": "JSON",
-          "default": []
+          "default": [],
+          "description": "The labels attached to the issue."
         },
         {
           "name": "assignees",
           "type": "json",
           "required": false,
           "columnType": "JSON",
-          "default": []
+          "default": [],
+          "description": "The people working on it."
         },
         {
           "name": "commentsCount",
@@ -3846,9 +3964,16 @@
         {
           "name": "repositoryId",
           "type": "foreignKey",
-          "required": true,
+          "required": false,
           "related": "Repository",
           "columnType": "UUID"
+        },
+        {
+          "name": "projectId",
+          "type": "foreignKey",
+          "required": false,
+          "related": "Project",
+          "columnType": "UUID"
         }
       ],
       "methods": [
@@ -3864,6 +3989,7 @@
         "getComments",
         "getRepository",
         "getUrl",
+        "hasRepository",
         "incorporateFeedback",
         "isBugReport",
         "isFeatureRequest",
@@ -3946,6 +4072,10 @@
           "name": "getUrl",
           "returns": "string"
         },
+        {
+          "name": "hasRepository",
+          "returns": "boolean"
+        },
         {
           "name": "incorporateFeedback",
           "async": true,
@@ -4226,6 +4356,13 @@
           "reason": "not listed in api.include",
           "objectName": "@happyvertical/smrt-projects:PullRequest"
         },
+        {
+          "kind": "api",
+          "operation": "hasRepository",
+          "code": "not-included",
+          "reason": "not listed in api.include",
+          "objectName": "@happyvertical/smrt-projects:PullRequest"
+        },
         {
           "kind": "api",
           "operation": "incorporateFeedback",
@@ -4673,6 +4810,7 @@
       "name": "DevelopmentRequestWorkLink",
       "qualifiedName": "@happyvertical/smrt-projects:DevelopmentRequestWorkLink",
       "collection": "developmentrequestworklinks",
+      "description": "Provider-neutral connection from a Development Request to canonical work.",
       "tableName": "development_request_work_links",
       "packageName": "@happyvertical/smrt-projects",
       "extends": "SmrtObject",
@@ -4759,6 +4897,7 @@
       "name": "ProjectDeliveryEvent",
       "qualifiedName": "@happyvertical/smrt-projects:ProjectDeliveryEvent",
       "collection": "projectdeliveryevents",
+      "description": "Ordered, idempotent delivery update emitted by the control plane.",
       "tableName": "project_delivery_events",
       "packageName": "@happyvertical/smrt-projects",
       "extends": "SmrtObject",
@@ -4872,6 +5011,7 @@
       "name": "PreviewApproval",
       "qualifiedName": "@happyvertical/smrt-projects:PreviewApproval",
       "collection": "previewapprovals",
+      "description": "Client decision state for one preview produced during delivery.",
       "tableName": "preview_approvals",
       "packageName": "@happyvertical/smrt-projects",
       "extends": "SmrtObject",
@@ -4969,6 +5109,7 @@
       "name": "AssistanceRequest",
       "qualifiedName": "@happyvertical/smrt-projects:AssistanceRequest",
       "collection": "assistancerequests",
+      "description": "Lossless conversational intake before support/development classification.",
       "tableName": "assistance_requests",
       "packageName": "@happyvertical/smrt-projects",
       "extends": "SmrtObject",
@@ -5079,6 +5220,7 @@
       "name": "AssistanceRequestEvent",
       "qualifiedName": "@happyvertical/smrt-projects:AssistanceRequestEvent",
       "collection": "assistancerequestevents",
+      "description": "Append-only explanation of Assistance Request routing decisions.",
       "tableName": "assistance_request_events",
       "packageName": "@happyvertical/smrt-projects",
       "extends": "SmrtObject",
@@ -5248,6 +5390,14 @@
     }
   ],
   "surfaces": [
+    {
+      "kind": "api",
+      "name": "issues.findByProject",
+      "operation": "findByProject",
+      "objectName": "@happyvertical/smrt-projects:IssueCollection",
+      "path": "/issues/findByProject",
+      "method": "POST"
+    },
     {
       "kind": "api",
       "name": "issues.findByRepository",
@@ -5334,6 +5484,12 @@
       "operation": "discover",
       "objectName": "@happyvertical/smrt-projects:IssueCollection"
     },
+    {
+      "kind": "cli",
+      "name": "issuecollection_findByProject",
+      "operation": "findByProject",
+      "objectName": "@happyvertical/smrt-projects:IssueCollection"
+    },
     {
       "kind": "cli",
       "name": "issuecollection_findByRepository",
@@ -5406,6 +5562,12 @@
       "operation": "discover",
       "objectName": "@happyvertical/smrt-projects:IssueCollection"
     },
+    {
+      "kind": "mcp",
+      "name": "issuecollection_findbyproject",
+      "operation": "findByProject",
+      "objectName": "@happyvertical/smrt-projects:IssueCollection"
+    },
     {
       "kind": "mcp",
       "name": "issuecollection_findbyrepository",
@@ -6747,12 +6909,165 @@
     }
   ],
   "relationshipsV2": {
-    "foreignKeyFields": 13,
+    "foreignKeyFields": 16,
     "crossPackageRefFields": 0,
     "junctionCollections": 0,
     "hierarchicalObjects": 0,
     "polymorphicAssociations": 0,
-    "uuidColumns": 79
+    "uuidColumns": 87
   },
-  "agentDoc": "# @happyvertical/smrt-projects\n\nProvider-agnostic project management plus the managed-application delivery\ncontrol plane. Repository and board providers remain canonical; managed apps\nonly receive scoped Project Integration credentials and provider-neutral\nrequest/delivery projections.\n\n## Managed application delivery (#1949)\n\n- `ProjectIntegration` stores capability grants and a sensitive credential\n  hash; the raw credential is returned once by\n  `ProjectIntegrationCollection.provision()`/`rotate()` and is never persisted.\n  Provisioning, rotation, and revocation are append-only audited.\n- The stable requester identity is supplied when authenticating\n  `ManagedProjectClient`; request reads are always restricted to that requester\n  and integration.\n- `DevelopmentRequest` preserves evidence, origin, discussion, visibility, and\n  lifecycle history. `ManagedProjectClient` owns managed intake and\n  `DevelopmentRequestService` adds internal triage and work projection.\n- `DevelopmentRequestWorkLink` connects zero-to-many provider-neutral work\n  items. Canonical status stays on the link and drives request lifecycle\n  projection without granting the managed app provider credentials.\n- `ProjectDeliveryEvent` is idempotent per integration key and sequenced for\n  replay. Preview decisions flow through the control-plane adapter, never\n  directly to repository providers.\n- `AssistanceRequest` preserves conversational intake before lossless routing\n  to Support, Development, or both. `smrt-support` supplies the concrete\n  `ProjectAssistanceSupportAdapter`.\n- `ManagedProjectClient` deliberately exposes no repository or board client;\n  delivery and assistance use separate capability-gated service facades.\n\n## Shared Professional Service evidence (#1955, #3288)\n\n`ServiceTimeEntry`, `ServiceChargeSnapshot`, `ServiceCompensationSnapshot`,\ntheir collections, and `ServiceEvidenceService` are owned by\n`@happyvertical/smrt-timesheets` (#3288) and **re-exported** here unchanged,\non the unchanged `service_time_entries` / snapshot tables. Do not reintroduce\na projects subclass: a third same-named class on the table breaks the\nsingle-table-family resolution (see `packages/timesheets/AGENTS.md`).\n`caseId` / `specialistId` exist only on smrt-support's subtype;\n`SubscriptionServiceCommercialResolver` reads them duck-typed when a support\nentry is priced. It prices client work through `smrt-subscriptions` (#1925);\nprovider compensation remains a separate resolver and snapshot. The\ntime-entry Svelte components are re-exported from smrt-timesheets too. See\n`SERVICE_TIME_MIGRATION.md`.\n\n## Models\n\n| Model | Key Fields | Notes |\n|-------|-----------|-------|\n| **Repository** | `owner`, `name`, `providerType`, `tokenConfigKey` | `sync()`, `getIssues()`, `getPullRequests()` |\n| **Issue** | `repositoryId` (FK), `number`, `title`, `body`, `state`, `labels[]` | `incorporateFeedback()`, `rollback()`, `suggestLabels()` |\n| **PullRequest** | extends Issue + `headRef`, `baseRef`, `merged`, `draft` | STI on Issue table. `summarize()`, `merge()` |\n| **Project** | `projectId`, `title`, `statuses[]`, `statusFieldId` | GitHub Projects V2. `addItem()`, `moveItem()`, `analyzeHealth()` |\n| **Comment** | `issueId` (FK), `body`, `authorLogin` | AI analysis support |\n| **Label** | `repositoryId` (FK), `name`, `color` | |\n\n## Key Patterns\n\n- **Token config reference**: stores env var name (`tokenConfigKey: 'GITHUB_TOKEN'`), not the token itself. Resolved at runtime from `process.env` or `getModuleConfig()`\n- **Living spec** (`incorporateFeedback()`): AI synthesizes issue comments into updated body. Supports preview mode and `rollback()`\n- **Provider-agnostic**: GitHub primary, GitLab/Bitbucket/Azure planned. Uses `@happyvertical/repos` and `@happyvertical/projects` SDK packages\n- **PullRequest is STI on Issue**: shares table, discriminated by `_meta_type`\n\n## Collection Methods\n\nAll collections provide: `discover({ repository, filters })`, `findByRepository(repoId)`, `findOpen(repoId?)`, `batchSync(repository)`.\n\n## Gotchas\n\n- **Money is integer minor units** (cents) — `$19.99` is `1999`.\n  `ServiceChargeSnapshot.amount` and `ServiceCompensationSnapshot.amount`\n  (declared in smrt-timesheets)\n  initialize `= 0`, never `= 0.0`: the integer literal is what maps them to\n  INTEGER columns (BIGINT on fresh PostgreSQL/DuckDB databases; #2401, #2373). The two convert as a pair — the delivery margin is\n  `charge - compensation`, an exact integer subtraction with no tolerance —\n  and both are fed verbatim by `CommercialSnapshot.amount`, so a resolver that\n  returns major units is wrong on every engine: snapshot `save()` refuses a\n  fractional value (`19.99`) on SQLite and PostgreSQL alike, but a whole\n  major-unit value (`150` for $150.00) is a valid integer and is stored\n  100× too small. `pnpm --filter @happyvertical/smrt-timesheets\n  test:postgres` is the lane that holds the line (moved with the snapshots in\n  #3288).\n- **UI formats by dividing, never by `toFixed`**: `formatCurrency()` and\n  `ServiceEvidenceList`'s `money()` scale back to major units using the\n  currency's own minor-unit exponent, so zero-decimal currencies (JPY, KRW) are\n  not divided.\n- **Migrating an existing database**: `preflightProjectsMoneyMinorUnits(db)`\n  reports which columns still hold major units and which rows would be rounded\n  or exceed JavaScript's safe-integer range; `migrateProjectsMoneyToMinorUnits(db)` converts them\n  (idempotent via `_smrt_backfills`). On SQLite the values are rescaled but the\n  declared type needs the table-rebuild path (#2370). Fresh PostgreSQL/DuckDB\n  INTEGER columns are BIGINT and hydration rejects values outside JavaScript's\n  safe-integer range; existing PostgreSQL `int4` columns require #2424.\n- **SDK dependency**: requires `@happyvertical/repos` and `@happyvertical/projects` from SDK\n- **tokenConfigKey not tokenValue**: never store actual tokens in the database\n- **synthesisCount tracks incorporateFeedback calls**: incremented on each apply\n"
+  "agentDoc": "# @happyvertical/smrt-projects\n\nProvider-agnostic project management plus the managed-application delivery\ncontrol plane. Repository and board providers remain canonical; managed apps\nonly receive scoped Project Integration credentials and provider-neutral\nrequest/delivery projections.\n\n## Managed application delivery (#1949)\n\n- `ProjectIntegration` stores capability grants and a sensitive credential\n  hash; the raw credential is returned once by\n  `ProjectIntegrationCollection.provision()`/`rotate()` and is never persisted.\n  Provisioning, rotation, and revocation are append-only audited.\n- The stable requester identity is supplied when authenticating\n  `ManagedProjectClient`; request reads are always restricted to that requester\n  and integration.\n- `DevelopmentRequest` preserves evidence, origin, discussion, visibility, and\n  lifecycle history. `ManagedProjectClient` owns managed intake and\n  `DevelopmentRequestService` adds internal triage and work projection.\n- `DevelopmentRequestWorkLink` connects zero-to-many provider-neutral work\n  items. Canonical status stays on the link and drives request lifecycle\n  projection without granting the managed app provider credentials.\n- `ProjectDeliveryEvent` is idempotent per integration key and sequenced for\n  replay. Preview decisions flow through the control-plane adapter, never\n  directly to repository providers.\n- `AssistanceRequest` preserves conversational intake before lossless routing\n  to Support, Development, or both. `smrt-support` supplies the concrete\n  `ProjectAssistanceSupportAdapter`.\n- `ManagedProjectClient` deliberately exposes no repository or board client;\n  delivery and assistance use separate capability-gated service facades.\n\n## Shared Professional Service evidence (#1955, #3288)\n\n`ServiceTimeEntry`, `ServiceChargeSnapshot`, `ServiceCompensationSnapshot`,\ntheir collections, and `ServiceEvidenceService` are owned by\n`@happyvertical/smrt-timesheets` (#3288) and **re-exported** here unchanged,\non the unchanged `service_time_entries` / snapshot tables. Do not reintroduce\na projects subclass: a third same-named class on the table breaks the\nsingle-table-family resolution (see `packages/timesheets/AGENTS.md`).\n`caseId` / `specialistId` exist only on smrt-support's subtype;\n`SubscriptionServiceCommercialResolver` reads them duck-typed when a support\nentry is priced. It prices client work through `smrt-subscriptions` (#1925);\nprovider compensation remains a separate resolver and snapshot. The\ntime-entry Svelte components are re-exported from smrt-timesheets too. See\n`SERVICE_TIME_MIGRATION.md`.\n\n## Models\n\n| Model | Key Fields | Notes |\n|-------|-----------|-------|\n| **Repository** | `owner`, `name`, `providerType`, `tokenConfigKey` | `sync()`, `getIssues()`, `getPullRequests()` |\n| **Issue** | `repositoryId` (optional FK), `projectId` (optional FK), `number`, `title`, `body`, `state`, `labels[]` | `incorporateFeedback()`, `rollback()`, `suggestLabels()` |\n| **PullRequest** | extends Issue + `headRef`, `baseRef`, `merged`, `draft` | STI on Issue table. `summarize()`, `merge()` |\n| **Project** | `projectId`, `title`, `statuses[]`, `statusFieldId` | GitHub Projects V2. `addItem()`, `moveItem()`, `analyzeHealth()` |\n| **Comment** | `issueId` (FK), `body`, `authorLogin` | AI analysis support |\n| **Label** | `repositoryId` (optional FK), `projectId` (optional FK), `name`, `color` | Scope: repository, project, or neither |\n\n## Key Patterns\n\n- **Repository is optional (project-native issues)**: an Issue/Label may carry only a `projectId`. `issue.hasRepository()` gates every provider call: `sync()` is a no-op, `close/addLabels/removeLabel/assign/addComment/rollback/incorporateFeedback(apply)` change local state only, `getComments()` reads stored `Comment` rows, `getRepository()` throws, `getUrl()` returns `''`. No unique key spans `repositoryId`+`number` (lookups only), so NULL repositories need no partial index. Schema change adds `issues.project_id`/`labels.project_id` and relaxes `repository_id` to nullable on both; `db:migrate` generates it from the manifest.\n\n- **Token config reference**: stores env var name (`tokenConfigKey: 'GITHUB_TOKEN'`), not the token itself. Resolved at runtime from `process.env` or `getModuleConfig()`\n- **Living spec** (`incorporateFeedback()`): AI synthesizes issue comments into updated body. Supports preview mode and `rollback()`\n- **Provider-agnostic**: GitHub primary, GitLab/Bitbucket/Azure planned. Uses `@happyvertical/repos` and `@happyvertical/projects` SDK packages\n- **PullRequest is STI on Issue**: shares table, discriminated by `_meta_type`\n\n## Collection Methods\n\nAll collections provide: `discover({ repository, filters })`, `findByRepository(repoId)`, `findOpen(repoId?)`, `batchSync(repository)`.\n\n## Gotchas\n\n- **Money is integer minor units** (cents) — `$19.99` is `1999`.\n  `ServiceChargeSnapshot.amount` and `ServiceCompensationSnapshot.amount`\n  (declared in smrt-timesheets)\n  initialize `= 0`, never `= 0.0`: the integer literal is what maps them to\n  INTEGER columns (BIGINT on fresh PostgreSQL/DuckDB databases; #2401, #2373). The two convert as a pair — the delivery margin is\n  `charge - compensation`, an exact integer subtraction with no tolerance —\n  and both are fed verbatim by `CommercialSnapshot.amount`, so a resolver that\n  returns major units is wrong on every engine: snapshot `save()` refuses a\n  fractional value (`19.99`) on SQLite and PostgreSQL alike, but a whole\n  major-unit value (`150` for $150.00) is a valid integer and is stored\n  100× too small. `pnpm --filter @happyvertical/smrt-timesheets\n  test:postgres` is the lane that holds the line (moved with the snapshots in\n  #3288).\n- **UI formats by dividing, never by `toFixed`**: `formatCurrency()` and\n  `ServiceEvidenceList`'s `money()` scale back to major units using the\n  currency's own minor-unit exponent, so zero-decimal currencies (JPY, KRW) are\n  not divided.\n- **Migrating an existing database**: `preflightProjectsMoneyMinorUnits(db)`\n  reports which columns still hold major units and which rows would be rounded\n  or exceed JavaScript's safe-integer range; `migrateProjectsMoneyToMinorUnits(db)` converts them\n  (idempotent via `_smrt_backfills`). On SQLite the values are rescaled but the\n  declared type needs the table-rebuild path (#2370). Fresh PostgreSQL/DuckDB\n  INTEGER columns are BIGINT and hydration rejects values outside JavaScript's\n  safe-integer range; existing PostgreSQL `int4` columns require #2424.\n- **SDK dependency**: requires `@happyvertical/repos` and `@happyvertical/projects` from SDK\n- **tokenConfigKey not tokenValue**: never store actual tokens in the database\n- **synthesisCount tracks incorporateFeedback calls**: incremented on each apply\n",
+  "recipes": [
+    {
+      "id": "projects.tracker",
+      "className": "ProjectTrackerRecipe",
+      "label": "Projects",
+      "summary": "Track projects and the issues, labels and comments inside them.",
+      "synonyms": [
+        "issues",
+        "tasks",
+        "tickets",
+        "bugs",
+        "kanban"
+      ],
+      "models": [
+        "@happyvertical/smrt-projects:Project",
+        "@happyvertical/smrt-projects:Issue",
+        "@happyvertical/smrt-projects:Label",
+        "@happyvertical/smrt-projects:Comment"
+      ],
+      "nav": [
+        {
+          "label": "Projects",
+          "model": "@happyvertical/smrt-projects:Project",
+          "icon": "folder",
+          "description": "Bigger jobs broken into steps you can follow."
+        },
+        {
+          "label": "Issues",
+          "model": "@happyvertical/smrt-projects:Issue",
+          "icon": "wrench",
+          "description": "Problems and to-dos to track until they are done."
+        },
+        {
+          "label": "Labels",
+          "model": "@happyvertical/smrt-projects:Label",
+          "icon": "tag",
+          "description": "Tags to sort your projects and issues your way."
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "projects",
+        "label": "Projects",
+        "icon": "briefcase",
+        "description": "Projects, their issues, labels and comments."
+      },
+      "options": {
+        "@happyvertical/smrt-projects:Project": {
+          "fields": {
+            "projectId": {
+              "visibility": "hidden"
+            },
+            "projectNumber": {
+              "visibility": "hidden"
+            },
+            "providerType": {
+              "visibility": "hidden"
+            },
+            "tokenConfigKey": {
+              "visibility": "hidden"
+            },
+            "statuses": {
+              "visibility": "hidden"
+            },
+            "fields": {
+              "visibility": "hidden"
+            },
+            "statusFieldId": {
+              "visibility": "hidden"
+            },
+            "statusOptions": {
+              "visibility": "hidden"
+            },
+            "lastSyncedAt": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-projects:Issue": {
+          "fields": {
+            "nodeId": {
+              "visibility": "hidden"
+            },
+            "originalBody": {
+              "visibility": "hidden"
+            },
+            "synthesisCount": {
+              "visibility": "hidden"
+            },
+            "lastSyncedAt": {
+              "visibility": "hidden"
+            },
+            "commentsCount": {
+              "visibility": "hidden"
+            },
+            "repositoryId": {
+              "visibility": "hidden"
+            },
+            "number": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-projects:Comment": {
+          "fields": {
+            "commentId": {
+              "visibility": "hidden"
+            },
+            "url": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-projects:Label": {
+          "fields": {
+            "repositoryId": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nProjects tracks the work you are planning: projects, the issues in them, and\nthe labels and comments that organise them.\n\n## Tasks\n\n### Start a project\n\n1. Create a new project.\n2. Give it a **{field:title}** and a **{field:description}**.\n\n### Log an issue\n\n1. Create a new issue and pick the **{field:projectId}**.\n2. Write a **{field:title}** and a **{field:body}**.\n3. Close it by setting **{field:state}** to closed. Comments are attached to the\n   issue.\n",
+        "fieldRefs": [
+          "body",
+          "description",
+          "projectId",
+          "state",
+          "title"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: node:crypto/async_hooks; core migrations; repos and ai SDKs; and its package depends on @happyvertical/smrt-subscriptions, @happyvertical/smrt-tenancy, @happyvertical/smrt-timesheets, which do not build for a browser (#3624, #3626, #3627)."
+        ]
+      }
+    }
+  ],
+  "browser": {
+    "status": "server-only",
+    "issues": [
+      "#3624",
+      "#3626",
+      "#3627"
+    ],
+    "reason": "node:crypto/async_hooks; core migrations; repos and ai SDKs",
+    "via": [
+      "@happyvertical/smrt-subscriptions",
+      "@happyvertical/smrt-tenancy",
+      "@happyvertical/smrt-timesheets"
+    ]
+  }
 }