joist-codegen 2.3.0-next.9 → 2.3.0-next.91

package/build/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import { pascalCase } from \"change-case\";\nimport { isPlainObject } from \"joist-utils\";\nimport { type Table } from \"pg-structure\";\nimport pluralize from \"pluralize\";\nimport { code, imp } from \"ts-poet\";\n\nimport { type Config, getTimestampConfig } from \"./config.ts\";\nimport { type DatabaseColumnType, type PrimitiveTypescriptType } from \"./EntityDbMetadata.ts\";\n\nexport function assertNever(x: never): never {\n  throw new Error(\"Unexpected object: \" + x);\n}\n\nexport function isEntityTable(config: Config, t: Table): boolean {\n  if (isIgnored(config, t) || isJoinTable(config, t)) {\n    return false;\n  }\n\n  // Depending on the config settings, we may/may not require the presence of timestamp\n  // fields to determine whether a table is an entity.\n  const columnNames = t.columns.map((c) => c.name);\n  const { updatedAtConf, createdAtConf } = getTimestampConfig(config);\n  const hasCreatedAt = createdAtConf.names.some((c) => columnNames.includes(c));\n  const hasUpdatedAt = updatedAtConf.names.some((c) => columnNames.includes(c));\n\n  // Entities always require an id column\n  const hasIdColumn = columnNames.includes(\"id\");\n  if (!hasIdColumn) return false;\n\n  // If we have no timestamp columns, but do have `name` and `code`, we're probably an enum.\n  if (hasIdColumn && !hasCreatedAt && !hasUpdatedAt) {\n    if ([\"name\", \"code\"].every((c) => columnNames.includes(c))) {\n      return false;\n    }\n  }\n\n  // If the ID column is a FK then we're a subclass\n  if (isSubClassTable(t)) return true;\n\n  // Otherwise respect the created_at/updated_at required rules\n  return hasIdColumn && (hasCreatedAt || !createdAtConf.required) && (hasUpdatedAt || !updatedAtConf.required);\n}\n\nexport function isSubClassTable(t: Table): boolean {\n  // Note that `.get(\"id\")` will blow up if there is no id column\n  return t.columns.get(\"id\").foreignKeys.length === 1;\n}\n\nexport function isEnumTable(config: Config, t: Table): boolean {\n  if (isIgnored(config, t)) {\n    return false;\n  }\n  const columnNames = t.columns.map((c) => c.name);\n  return [\"id\", \"code\", \"name\"].every((c) => columnNames.includes(c)) && !isEntityTable(config, t);\n}\n\n// Oddly enough isJoinTable showed up as a hot spot, so cache its calculation.\nconst joinTables: Map<string, boolean> = new Map();\n\nexport function isJoinTable(config: Config, t: Table): boolean {\n  if (isIgnored(config, t)) {\n    return false;\n  }\n  return getOrElse(joinTables, t.name, () => {\n    const { columns } = t;\n    const fks = columns.filter((c) => c.isForeignKey);\n    const pks = columns.filter((c) => c.isPrimaryKey);\n    // Every join table is two FKs, plus either a surrogate `id` PK (\"id-ful\") or no surrogate\n    // at all, in which case the two FKs are themselves the composite PK (\"id-less\").\n    if (fks.length !== 2) return false;\n    if (!joinTableHasId(t) && !(pks.length === 2 && pks.every((c) => c.isForeignKey))) return false;\n    // Any column beyond the two FKs and the optional `id` PK must be a single created_at.\n    const others = columns.length - fks.length - (joinTableHasId(t) ? 1 : 0);\n    const createdAts = columns.filter((c) => c.name === \"created_at\" || c.name === \"createdAt\").length;\n    return others === 0 || (others === 1 && createdAts === 1);\n  });\n}\n\n/** Whether a join table has a surrogate `id` primary key (vs. an id-less FK-pair composite PK). */\nexport function joinTableHasId(t: Table): boolean {\n  const pks = t.columns.filter((c) => c.isPrimaryKey);\n  return pks.length === 1 && !pks[0].isForeignKey;\n}\n\nfunction getOrElse<K, V>(map: Map<K, V>, key: K, fn: () => V): V {\n  let value = map.get(key);\n  if (value === undefined) {\n    value = fn();\n    map.set(key, value);\n  }\n  return value;\n}\n\n/** Converts `projects` to `Project`. */\nexport function tableToEntityName(config: Config, table: Table): string {\n  let entityName = config.__tableToEntityName?.[table.name];\n  if (!entityName) {\n    const configEntityName = Object.entries(config.entities)\n      .filter(([, conf]) => conf.tableName === table.name)\n      .map(([entityName]) => entityName)[0];\n    entityName = configEntityName || pascalCase(pluralize.singular(table.name));\n    (config.__tableToEntityName ??= {})[table.name] = entityName;\n  }\n  return entityName;\n}\n\nexport const dateCode = code`Date`;\nexport const plainDateCode = code`${imp(\"Temporal@joist-orm\")}.PlainDate`;\nexport const plainTimeCode = code`${imp(\"Temporal@joist-orm\")}.PlainTime`;\nexport const plainDateTimeCode = code`${imp(\"Temporal@joist-orm\")}.PlainDateTime`;\nexport const zonedDateTimeCode = code`${imp(\"Temporal@joist-orm\")}.ZonedDateTime`;\n\n/** Maps db types, i.e. `int`, to JS types, i.e. `number`. */\nexport function mapSimpleDbTypeToTypescriptType(config: Config, dbType: DatabaseColumnType): PrimitiveTypescriptType {\n  switch (dbType) {\n    case \"boolean\":\n      return \"boolean\";\n    case \"int\":\n    case \"numeric\":\n    case \"smallint\":\n    case \"integer\":\n    case \"decimal\":\n    case \"real\":\n    case \"smallserial\":\n    case \"serial\":\n    case \"double precision\":\n      return \"number\";\n    case \"bigserial\":\n    case \"bigint\":\n      return \"bigint\";\n    case \"text\":\n    case \"citext\":\n    case \"character varying\":\n    case \"varchar\":\n    case \"uuid\":\n    case \"tsvector\":\n    case \"tstzrange\":\n      return \"string\";\n    case \"time without time zone\":\n      return config.temporal\n        ? plainTimeCode\n        : fail(\"Joist doesn't support 'time without time zone' unless temporal is enabled\");\n    case \"timestamp with time zone\":\n      return config.temporal ? zonedDateTimeCode : dateCode;\n    case \"timestamp without time zone\":\n      return config.temporal ? plainDateTimeCode : dateCode;\n    case \"date\":\n      return config.temporal ? plainDateCode : dateCode;\n    case \"jsonb\":\n      return \"Object\";\n    case \"bytea\":\n      return \"Uint8Array\";\n    default:\n      assertNever(dbType);\n  }\n}\n\nexport function merge<T>(a: T[], b: T[]): T[] {\n  return [...a, ...b];\n}\n\n/** Returns true if `p` is resolved, otherwise false if it is rejected. */\nexport async function trueIfResolved(p: Promise<unknown>): Promise<boolean> {\n  return p.then(\n    () => true,\n    () => false,\n  );\n}\n\nexport function fail(message?: string): never {\n  throw new Error(message || \"Failed\");\n}\n\nexport function sortKeys<T extends object>(o: T): T {\n  return Object.keys(o)\n    .sort()\n    .reduce(\n      (acc, key) => {\n        const value = o[key as keyof T];\n        const newValue = typeof value === \"object\" && isPlainObject(value) ? sortKeys(value as any as object) : value;\n        acc[key as keyof T] = newValue as any;\n        return acc;\n      },\n      {} as any as T,\n    );\n}\n\nexport function parseOrder(order: string | undefined): { field: string; direction: \"ASC\" | \"DESC\" } | undefined {\n  if (!order) {\n    return undefined;\n  }\n  const [field, direction = \"ASC\"] = order.split(\" \");\n  if (direction !== \"ASC\" && direction !== \"DESC\") {\n    throw new Error(`Invalid direction: ${direction} (must be \"ASC\" or \"DESC\")`);\n  }\n  return { field, direction };\n}\n\nexport function q(s: string | undefined): string {\n  return s === undefined ? \"undefined\" : `\"${s}\"`;\n}\n\nexport function uncapitalize(s: string): string {\n  return s.charAt(0).toLowerCase() + s.slice(1);\n}\n\nfunction isIgnored(config: Config, t: Table): boolean {\n  return (config.ignoredTables || [\"migrations\", \"pgmigrations\"]).includes(t.name) || !shouldIncludeSchema(config, t);\n}\n\nfunction shouldIncludeSchema(config: Config, t: Table): boolean {\n  return config.schemas ? config.schemas.includes(t.schema.name) : t.schema.name === \"public\";\n}\n"],"mappings":"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"}

package/build/write-json-schema.cjs

@@ -0,0 +1,23 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_config = require("./config.cjs");
+let fs = require("fs");
+let _dprint_formatter = require("@dprint/formatter");
+let _dprint_json = require("@dprint/json");
+let zod = require("zod");
+//#region src/write-json-schema.ts
+const jsonFormatter = (0, _dprint_formatter.createFromBuffer)((0, fs.readFileSync)((0, _dprint_json.getPath)()));
+async function main() {
+	const jsonSchema = zod.z.toJSONSchema(require_config.config, {
+		io: "input",
+		unrepresentable: "any"
+	});
+	const content = jsonFormatter.formatText({
+		filePath: "test.json",
+		fileText: JSON.stringify(jsonSchema)
+	});
+	await fs.promises.writeFile("./config-json-schema.json", content);
+}
+main();
+//#endregion
+
+//# sourceMappingURL=write-json-schema.cjs.map

package/build/write-json-schema.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-json-schema.cjs","names":["createFromBuffer","readFileSync","getPath","z","config"],"sources":["../src/write-json-schema.ts"],"sourcesContent":["import { promises as fs, readFileSync } from \"fs\";\n\nimport { createFromBuffer } from \"@dprint/formatter\";\nimport { getPath } from \"@dprint/json\";\nimport { z } from \"zod\";\n\nimport { config } from \"./config.ts\";\n\nconst jsonFormatter = createFromBuffer(readFileSync(getPath()));\n\nasync function main() {\n  // `io: \"input\"` since the schema validates the user-authored joist-config.json, and\n  // `unrepresentable: \"any\"` to skip the `uniqueBy` transform that has no JSON Schema form.\n  const jsonSchema = z.toJSONSchema(config, { io: \"input\", unrepresentable: \"any\" });\n  const content = jsonFormatter.formatText({ filePath: \"test.json\", fileText: JSON.stringify(jsonSchema) });\n  await fs.writeFile(\"./config-json-schema.json\", content);\n}\n\nmain();\n"],"mappings":";;;;;;;AAQA,MAAM,iBAAA,GAAgBA,kBAAAA,iBAAAA,EAAAA,GAAiBC,GAAAA,aAAAA,EAAAA,GAAaC,aAAAA,QAAAA,CAAQ,CAAC,CAAC;AAE9D,eAAe,OAAO;CAGpB,MAAM,aAAaC,IAAAA,EAAE,aAAaC,eAAAA,QAAQ;EAAE,IAAI;EAAS,iBAAiB;CAAM,CAAC;CACjF,MAAM,UAAU,cAAc,WAAW;EAAE,UAAU;EAAa,UAAU,KAAK,UAAU,UAAU;CAAE,CAAC;CACxG,MAAM,GAAA,SAAG,UAAU,6BAA6B,OAAO;AACzD;AAEA,KAAK"}

package/build/write-json-schema.d.cts

@@ -0,0 +1 @@
+export {}

package/build/write-json-schema.d.mts

@@ -0,0 +1 @@
+export {}

package/build/write-json-schema.js

@@ -1,17 +1,23 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const formatter_1 = require("@dprint/formatter");
-const json_1 = require("@dprint/json");
-const fs_1 = require("fs");
-const zod_1 = require("zod");
-const config_1 = require("./config");
-const jsonFormatter = (0, formatter_1.createFromBuffer)((0, fs_1.readFileSync)((0, json_1.getPath)()));
+import { config } from "./config.js";
+import { promises, readFileSync } from "fs";
+import { createFromBuffer } from "@dprint/formatter";
+import { getPath } from "@dprint/json";
+import { z } from "zod";
+//#region src/write-json-schema.ts
+const jsonFormatter = createFromBuffer(readFileSync(getPath()));
 async function main() {
-    // `io: "input"` since the schema validates the user-authored joist-config.json, and
-    // `unrepresentable: "any"` to skip the `uniqueBy` transform that has no JSON Schema form.
-    const jsonSchema = zod_1.z.toJSONSchema(config_1.config, { io: "input", unrepresentable: "any" });
-    const content = jsonFormatter.formatText({ filePath: "test.json", fileText: JSON.stringify(jsonSchema) });
-    await fs_1.promises.writeFile("./config-json-schema.json", content);
+	const jsonSchema = z.toJSONSchema(config, {
+		io: "input",
+		unrepresentable: "any"
+	});
+	const content = jsonFormatter.formatText({
+		filePath: "test.json",
+		fileText: JSON.stringify(jsonSchema)
+	});
+	await promises.writeFile("./config-json-schema.json", content);
 }
 main();
+//#endregion
+export {};
+
 //# sourceMappingURL=write-json-schema.js.map

package/build/write-json-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-json-schema.js","sourceRoot":"","sources":["../src/write-json-schema.ts"],"names":[],"mappings":";;AAAA,iDAAqD;AACrD,uCAAuC;AACvC,2BAAkD;AAClD,6BAAwB;AACxB,qCAAkC;AAElC,MAAM,aAAa,GAAG,IAAA,4BAAgB,EAAC,IAAA,iBAAY,EAAC,IAAA,cAAO,GAAE,CAAC,CAAC,CAAC;AAEhE,KAAK,UAAU,IAAI;IACjB,oFAAoF;IACpF,0FAA0F;IAC1F,MAAM,UAAU,GAAG,OAAC,CAAC,YAAY,CAAC,eAAM,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAC;IACnF,MAAM,OAAO,GAAG,aAAa,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC1G,MAAM,aAAE,CAAC,SAAS,CAAC,2BAA2B,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED,IAAI,EAAE,CAAC"}
+{"version":3,"file":"write-json-schema.js","names":["fs"],"sources":["../src/write-json-schema.ts"],"sourcesContent":["import { promises as fs, readFileSync } from \"fs\";\n\nimport { createFromBuffer } from \"@dprint/formatter\";\nimport { getPath } from \"@dprint/json\";\nimport { z } from \"zod\";\n\nimport { config } from \"./config.ts\";\n\nconst jsonFormatter = createFromBuffer(readFileSync(getPath()));\n\nasync function main() {\n  // `io: \"input\"` since the schema validates the user-authored joist-config.json, and\n  // `unrepresentable: \"any\"` to skip the `uniqueBy` transform that has no JSON Schema form.\n  const jsonSchema = z.toJSONSchema(config, { io: \"input\", unrepresentable: \"any\" });\n  const content = jsonFormatter.formatText({ filePath: \"test.json\", fileText: JSON.stringify(jsonSchema) });\n  await fs.writeFile(\"./config-json-schema.json\", content);\n}\n\nmain();\n"],"mappings":";;;;;;AAQA,MAAM,gBAAgB,iBAAiB,aAAa,QAAQ,CAAC,CAAC;AAE9D,eAAe,OAAO;CAGpB,MAAM,aAAa,EAAE,aAAa,QAAQ;EAAE,IAAI;EAAS,iBAAiB;CAAM,CAAC;CACjF,MAAM,UAAU,cAAc,WAAW;EAAE,UAAU;EAAa,UAAU,KAAK,UAAU,UAAU;CAAE,CAAC;CACxG,MAAMA,SAAG,UAAU,6BAA6B,OAAO;AACzD;AAEA,KAAK"}

package/package.json

@@ -1,50 +1,70 @@
 {
   "name": "joist-codegen",
-  "version": "2.3.0-next.9",
+  "version": "2.3.0-next.91",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "https://github.com/joist-orm/joist-orm.git",
     "directory": "packages/codegen"
   },
-  "main": "build/index.js",
-  "types": "build/index.d.ts",
-  "bin": "build/index.js",
-  "scripts": {
-    "format": "prettier --ignore-path ../../.prettierignore --write '{schema,migrations,src}/**/*.{ts,js,tsx,jsx,graphql}'"
+  "main": "build/index.cjs",
+  "module": "build/index.js",
+  "types": "build/index.d.mts",
+  "exports": {
+    ".": {
+      "bun": {
+        "types": "./build/index.d.mts",
+        "default": "./build/index.js"
+      },
+      "module-sync": {
+        "types": "./build/index.d.mts",
+        "default": "./build/index.js"
+      },
+      "import": {
+        "types": "./build/index.d.mts",
+        "default": "./build/index.js"
+      },
+      "require": {
+        "types": "./build/index.d.cts",
+        "default": "./build/index.cjs"
+      },
+      "default": "./build/index.js"
+    }
   },
+  "bin": "build/index.cjs",
   "files": [
-    "build"
+    "build",
+    "skills"
   ],
   "peerDependencies": {
-    "joist-utils": "2.3.0-next.9",
+    "joist-utils": "2.3.0-next.91",
     "knex": "^3.1.0",
-    "pg": "^8.22.0"
+    "pg": "^8.23.0"
   },
   "dependencies": {
     "@dprint/formatter": "^0.5.1",
     "@dprint/json": "^0.21.3",
-    "@inquirer/prompts": "^8.5.2",
+    "@inquirer/prompts": "^8.6.0",
     "@types/jscodeshift": "^17.3.0",
     "@types/pluralize": "^0.0.33",
     "change-case": "^4.1.2",
     "fast-glob": "^3.3.3",
-    "jscodeshift": "^17.3.0",
+    "jscodeshift": "^17.4.0",
+    "jsonc-parser": "^3.3.1",
     "pg-structure": "^7.15.3",
     "pluralize": "^8.0.0",
-    "prettier": "^3.8.4",
+    "prettier": "^3.9.6",
     "ts-poet": "^6.12.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@swc/jest": "^0.2.39",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.2.0",
     "jest": "30.4.2",
-    "prettier-plugin-organize-imports": "^4.3.0",
-    "ts-node-dev": "^2.0.0",
     "tsconfig-paths": "^4.2.0",
-    "tsx": "^4.22.4",
-    "typescript": "6.0.3"
+    "tsx": "^4.23.12",
+    "typescript": "7.0.2"
   }
 }

package/skills/joist-docs/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: entity-docs
+description: Read the `src/entities/<Entity>.md` business-docs when working on an entity, its resolvers, jobs, or tests. Add only durable, non-obvious domain knowledge that helps readers understand a business rule or avoid a likely mistake; prioritize succinctness, clarity, and discretion. Also covers how `## Overview` and `## Fields`/`### fieldName` sections sync to JSDocs via `yarn joist-codegen`.
+---
+
+# Entity docs (`src/entities/<Entity>.md`)
+
+Many Joist entities have a sibling Markdown doc — `src/entities/Author.ts` ↔
+`src/entities/Author.md` (same basename; enums under `src/entities/enums/` too). These files hold the
+**"why"** that code can't: business rationale, worked scenarios, gotchas, domain vocabulary, and
+cross-entity workflows. They are written for **both humans and agents** — you are a primary audience.
+
+Read routinely; write selectively:
+
+1. **Read** the sibling `.md` before/while you work on an entity, to get domain context.
+2. **Write** only when a concise addition would give future readers important context they cannot
+   readily get from the code or existing docs. Leaving the docs unchanged is often the right outcome.
+
+## 1. Read it first
+
+Before editing an entity — its `src/entities/<Entity>.ts`, its resolvers, a job that touches it, or its
+tests — open `src/entities/<Entity>.md` if one exists. It routinely explains things you would otherwise
+have to reverse-engineer or would get subtly wrong:
+
+- **Business rationale** — *why* a field/entity exists and what real-world thing it models
+  (e.g. `PurchaseOrder.md` on tracking "what and why" a project's cost changed).
+- **Worked scenarios** — concrete `I.e.` walkthroughs with real values ("when an `Employee` is termined, the status workflow is...").
+- **Gotchas & edge cases** — footguns, "this looks stale but isn't", exemptions
+- **Domain vocabulary** — statuses, flags, and other "esoteric unless you know it" domain concepts
+
+Follow relevant cross-links (`[Book](Book.md)`, sometimes with anchors like
+`Book.md#Definitions`) into related docs. A missing or thin doc is not by itself a reason to add content.
+
+## 2. How the file maps to code (the codegen doc-sync)
+
+`joist-config.json` has `"docs": true`, so `yarn joist-codegen` keeps these `.md` files and the entity
+JSDocs in sync. Understanding this is what makes your writing land in the right place.
+
+**Only two heading shapes are parsed and synced; everything else is free-form narrative:**
+
+| `.md` section | Syncs to | Notes |
+|---|---|---|
+| `## Overview` (body) | the entity **class** JSDoc | exact heading `## Overview` |
+| `## Fields` → `### <fieldName>` (body) | that field/property/relation's JSDoc | `### ` heading must be the **exact member name** |
+| any other `## Section` (e.g. `## Hard vs. Soft Costs`, `## DB Constraints`, mermaid) | **nothing** | free-form; lives only in the `.md`, preserved verbatim |
+
+Synced JSDocs are tagged `@generated <Entity>.md` in the `.ts` — that tag means "this comment came from
+the `.md`; edit the `.md`, not here."
+
+**Sync is bidirectional, but the `.md` wins.** `yarn joist-codegen`:
+
+1. **Backfills** the `.md` from any hand-written `.ts` JSDoc that isn't in the `.md` yet (so a jsdoc you
+   write directly on a field gets pulled into `## Fields` for you), then
+2. **Writes the `.md` back into the `.ts`** JSDocs — so for anything already in the `.md`, the `.md` is
+   the source of truth and will overwrite a divergent `.ts` comment.
+
+Net rule: **to durably document an entity or field, edit the `.md`.** Hand-editing a `@generated` JSDoc
+in the `.ts` gets stomped on the next codegen.
+
+### Field-heading constraints (easy to get wrong)
+
+- `### <fieldName>` must be a **single word** — the parser matches `\w+` only. `### excludeFromBudget`
+  works; `### is excluded`, `` ### `excludeFromBudget` ``, or `### excludeFromBudget (derived)` are **not**
+  recognized as field docs.
+- It must be the **exact** name of a field, relation, or property on the entity, and must sit **under the
+  `## Fields` heading**. Any other `##` heading ends the fields section — so keep all `### fieldName`
+  entries together under the one `## Fields` section (conventionally at the bottom of the file).
+- **Methods don't sync** — only fields/getters/properties/relations get their JSDoc updated.
+
+## 3. Choose what is worth documenting
+
+Add a note only when the knowledge is durable, non-obvious, and useful for a future domain decision or
+for avoiding a likely mistake. Possible candidates, not a checklist to fill:
+
+- You just figured out **why** an entity or field exists, or what it really models.
+- A **non-obvious business rule**, invariant, or "this only applies to X clients" exemption.
+- A **gotcha / footgun** — a value that looks stale but isn't, an ordering requirement, a special-cased
+  type.
+- A **cross-entity interaction** or workflow that isn't visible from one file.
+- **Domain vocabulary** a newcomer (human or agent) wouldn't know.
+- A **worked scenario** needed to resolve an ambiguity that a short explanation cannot.
+
+**Omit** what the code already says plainly, transient implementation details, exhaustive edge-case
+lists, and a recap of the work just completed. Do not repeat knowledge already documented elsewhere;
+link to it when readers need it. Correct outdated guidance rather than appending a competing explanation.
+
+**Where to put it:**
+
+- Something specific to one field → a `### <fieldName>` block under `## Fields`. It syncs to that
+  member's JSDoc, so it shows on hover/`@generated` in the `.ts`.
+- The entity's purpose → a short `## Overview`, which syncs to the class JSDoc.
+- Necessary longer explanations or cross-entity workflows → a free-form `##` section, linked from the
+  field doc if needed. Keep synced JSDocs small enough to read comfortably on hover.
+
+**Style** (prioritize succinctness and clarity):
+
+- Lead with business meaning and *why*. Use plain language and state each fact once.
+- Default to one sentence for a field and one short paragraph for an overview. Add detail only when
+  shortening it would hide an important rule or make the meaning ambiguous.
+- Use a single brief `I.e. ...` example with concrete values only when it clarifies a difficult rule.
+  Do not add examples, diagrams, or sections merely to make the doc look complete.
+- Cross-link related entities with relative links: `[Book](Book.md)`.
+- Reference field/entity names in backticks.
+- Before finishing, remove any sentence that does not add necessary meaning. Match existing terminology,
+  but do not copy existing verbosity.
+
+## 4. Workflow to add or update a doc
+
+1. If an addition meets the criteria above, edit `src/entities/<Entity>.md` (create it only if needed — basename must equal the entity, e.g.
+   `Author.md`). For field docs, use the exact member name as a `### ` heading under `## Fields`.
+2. Sync into the JSDocs:
+   ```bash
+   mise exec -- yarn joist-codegen
+   ```
+   (or `mise exec -- yarn codegen` to also run graphql-codegen.)
+3. Verify the `@generated <Entity>.md` JSDoc now appears on the class / field in `src/entities/<Entity>.ts`.
+4. Commit the `.md` **and** the regenerated `.ts` JSDoc changes together.
+
+Never hand-edit a `@generated <Entity>.md` JSDoc in the `.ts` — edit the `.md` and re-run codegen. Do not
+touch files under `src/entities/codegen/` (see the repo's generated-files rules).
+
+## Skeleton for a new doc
+
+Include only the sections and fields that need explanation; this is a structure, not a checklist.
+
+```markdown
+# <Entity>
+
+## Overview
+
+<What this entity models and *why* it exists, in business terms. One short paragraph.>
+
+## <Some Business Concept>   <!-- free-form: rationale, scenarios, gotchas, diagrams; NOT synced -->
+
+<Only if needed: a concise explanation of a non-obvious business concept.>
+
+## Fields   <!-- each ### below syncs into that member's JSDoc -->
+
+### someField
+
+<Usually one sentence: why it exists or the important non-obvious rule.>
+```

package/skills/joist-em-basics/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: joist-em-basics
+description: Create, load, find, mutate, and save entities with Joist's EntityManager. Use when writing data-access or business logic in a Joist project — anything using em.create, em.load, em.find, em.flush, or walking the entity graph.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# Joist EntityManager basics
+
+The `EntityManager` (`em`) is how entities are loaded from and saved to the
+database. It is a Unit of Work: each request gets its own `em`, which tracks
+the entities it has loaded/created and writes them all out on `em.flush()`.
+
+Entities are always loaded/created _through_ the `em`, never via static methods
+on the class (Joist is not ActiveRecord). IDs are tagged strings like `"a:1"`.
+
+## Creating
+
+`em.create` is synchronous and returns the new entity immediately:
+
+```ts
+const author = em.create(Author, { firstName: "a1" });
+// Nested/related entities can be created inline
+const author = em.create(Author, { firstName: "a1", address: { street: "123 Main" } });
+```
+
+## Loading by id
+
+Use tagged ids. These throw if the id does not exist (except the `IfExists`
+variants):
+
+```ts
+const a = await em.load(Author, "a:1");
+const as = await em.loadAll(Author, ["a:1", "a:2"]);
+const as = await em.loadAllIfExists(Author, ["a:1", "a:2"]); // skips missing ids
+```
+
+To eagerly load relations, pass a populate hint as the 3rd argument; the
+returned entity is typed as "loaded" so the relations can be read synchronously:
+
+```ts
+const a = await em.load(Author, "a:1", { books: "reviews" });
+a.books.get.flatMap((b) => b.reviews.get);
+```
+
+## Walking the graph
+
+~90% of reads are just navigating relations from an entity you already have.
+These are guaranteed N+1-safe, even in a loop:
+
+```ts
+const author = await book.author.load();        // load a single relation
+const reviews = await publisher.load((p) => p.books.reviews); // lens
+const loaded = await author.populate({ books: "reviews" });   // populate + .get
+```
+
+## Finding (filtered queries)
+
+`em.find` issues a `SELECT` with a "join literal" of nested relations plus
+inline `WHERE` conditions. It is batch/N+1-safe.
+
+```ts
+const books = await em.find(Book, { author: { firstName: "a1" } });
+const recent = await em.find(Book, { publishedAt: { gte: jan1 } });
+const some = await em.find(Author, { firstName: { in: ["a1", "a2"] } });
+
+const one = await em.findOne(Book, { title: "b1" });        // undefined if none
+const one = await em.findOneOrFail(Book, { title: "b1" });  // throws if none
+const one = await em.findOrCreate(Author, { email: "a@b.com" });
+```
+
+`undefined` values are pruned (the condition and any now-unused join are
+dropped), so filters compose cleanly. To filter for null, pass `null`
+explicitly, e.g. `{ firstName: null }`. For `OR` / nested boolean logic, use
+`alias`/`aliases` with a `conditions` argument. For aggregates or group-bys,
+drop down to Knex/Kysely — Joist's `find` only returns whole entities.
+
+## Mutating
+
+Assign fields directly, or use `.set` for a batch of changes:
+
+```ts
+author.firstName = "a2";
+author.set({ firstName: "a2", lastName: "b2" });
+```
+
+For partial/RPC-style updates (treating `null` as "unset"), and for
+incrementally updating children, see the `joist-upsert` skill.
+
+## Deleting
+
+```ts
+const a = await em.load(Author, "a:1");
+em.delete(a);
+```
+
+## Saving with `em.flush()`
+
+`em.flush()` is where everything happens. It is async and:
+
+1. Runs lifecycle hooks and validation rules,
+2. Opens a transaction,
+3. Issues batched `INSERT`/`UPDATE`/`DELETE` (one batch per entity type),
+4. Commits.
+
+You don't write individual SQL statements — let Joist batch them. `flush` can
+be called multiple times as you do more work:
+
+```ts
+const author = em.create(Author, { firstName: "a1" });
+await em.flush();
+author.firstName = "a2";
+await em.flush();
+```