Merge pull request #69 from constructive-io/devin/1774125055-orm-relations-composite-keys-docs

docs: M:N ORM methods, composite PKs, expose_in_api, filter type-safety

Author: pyramation

.agents/skills/constructive-graphql/SKILL.md

@@ -167,7 +167,7 @@ See [search.md](./references/search.md) for the decision matrix and combined que
 | [codegen-hooks-patterns.md](./references/codegen-hooks-patterns.md) | React Query hook patterns | Using generated hooks in React components |
 | [codegen-hooks-output.md](./references/codegen-hooks-output.md) | Hooks generated output structure | Understanding hook file structure |
 | [codegen-error-handling.md](./references/codegen-error-handling.md) | Error handling patterns | `.unwrap()`, `.unwrapOr()`, discriminated unions |
-| [codegen-relations.md](./references/codegen-relations.md) | Relation queries | Nested selects, belongsTo, hasMany, manyToMany |
+| [codegen-relations.md](./references/codegen-relations.md) | Relation queries and M:N mutations | Nested selects, belongsTo, hasMany, manyToMany, composite PKs, `expose_in_api`, add/remove methods |
 | [codegen-query-keys.md](./references/codegen-query-keys.md) | Query key factory | Cache invalidation, `invalidate.*`, `remove.*` |
 | [codegen-node-http-adapter.md](./references/codegen-node-http-adapter.md) | Node.js HTTP adapter | Subdomain routing in Node.js |
 

.agents/skills/constructive-graphql/references/codegen-orm-output.md

@@ -6,13 +6,14 @@ Reference for Prisma-like ORM client generated by `@constructive-io/graphql-code
 
 ```
 generated/orm/
-├── index.ts      # Main export (createClient, types)
-├── client.ts     # createClient() function
-├── types.ts      # All TypeScript types
-└── models/       # Entity model implementations
-    ├── user.ts
-    ├── post.ts
-    └── ...
+|- index.ts      # Main export (createClient, types)
+|- client.ts     # createClient() function
+|- types.ts      # All TypeScript types
+'- models/       # Entity model implementations
+    |- user.ts
+    |- post.ts
+    |- postTag.ts  # Junction table model (M:N)
+    '- ...
 ```
 
 ## Generated Files
@@ -75,6 +76,39 @@ db.user.update(options)     // Update existing
 db.user.delete(options)     // Delete
 ```
 
+### M:N Convenience Methods
+
+When `_meta` enrichment provides M:N relation metadata, entity models also get:
+
+```typescript
+// Generated on entities with M:N relations
+db.post.addTag(postId, tagId)      // Creates junction row
+db.post.removeTag(postId, tagId)    // Deletes junction row by composite PK
+db.tag.addPost(tagId, postId)       // Reverse direction
+db.tag.removePost(tagId, postId)
+```
+
+Method signatures use actual PK types from the junction table:
+
+```typescript
+// UUID PKs -> string parameters
+addTag(postId: string, tagId: string): QueryBuilder<...>
+
+// Integer PKs -> number parameters
+addStudent(courseId: number, studentId: number): QueryBuilder<...>
+```
+
+### Junction Table Models
+
+Junction tables get full CRUD models with composite PK support:
+
+```typescript
+// Standard CRUD on junction table
+db.postTag.create({ data: { postId, tagId } })
+db.postTag.findMany({ where: { postId: { equalTo: id } } })
+db.postTag.delete({ where: { postId, tagId } })  // Composite PK delete
+```
+
 ## Query Methods
 
 ### findMany
@@ -170,9 +204,15 @@ const result = await db.user.update({
 Delete item:
 
 ```typescript
+// Single PK
 const result = await db.user.delete({
   id: '123',
 }).execute();
+
+// Composite PK (junction table)
+const result = await db.postTag.delete({
+  where: { postId: POST_1, tagId: TAG_TECH },
+}).execute();
 ```
 
 ## Select and Type Inference
@@ -233,6 +273,7 @@ const users = await db.user.findMany({
 ### ManyToMany
 
 ```typescript
+// Query through M:N shortcut (when expose_in_api = true)
 const posts = await db.post.findMany({
   select: {
     id: true,
@@ -241,6 +282,14 @@ const posts = await db.post.findMany({
     },
   },
 }).execute();
+
+// Mutate via convenience methods
+await db.post.addTag(postId, tagId).execute();
+await db.post.removeTag(postId, tagId).execute();
+
+// Or via junction table directly
+await db.postTag.create({ data: { postId, tagId } }).execute();
+await db.postTag.delete({ where: { postId, tagId } }).execute();
 ```
 
 ### Deeply Nested