graphddb 0.5.2 → 0.6.0

package/dist/cli.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import {
   buildBridgeBundle,
-  buildManifest
-} from "./chunk-H5TUW2WR.js";
+  buildManifest,
+  buildOperations
+} from "./chunk-N5NQM3SO.js";
 import {
   MetadataRegistry,
   normalizeSelectSpec
-} from "./chunk-W3GEJPPV.js";
-import "./chunk-MCKGQKYU.js";
+} from "./chunk-F2DI3GTI.js";
+import {
+  createDefaultLinter
+} from "./chunk-PDUVTYC5.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -441,6 +444,105 @@ var commandDefinitions = {
         }
       }
     ]
+  },
+  "generate.docs": {
+    "effects": {
+      "risk_level": "low",
+      "reads": [
+        "ts-definitions"
+      ],
+      "writes": [
+        "generated-code"
+      ]
+    },
+    "options": [
+      {
+        "name": "entry",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "queries",
+        "schema": {
+          "type": "string"
+        },
+        "file": {
+          "mode": "read",
+          "exists": true,
+          "media_type": "application/typescript",
+          "encoding": "utf-8"
+        }
+      },
+      {
+        "name": "out",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "format",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "markdown"
+          ],
+          "default": "markdown"
+        }
+      },
+      {
+        "name": "split",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "none",
+            "entity"
+          ],
+          "default": "none"
+        }
+      },
+      {
+        "name": "template-dir",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "helpers",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "billing-mode",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "PAY_PER_REQUEST",
+            "PROVISIONED"
+          ],
+          "default": "PAY_PER_REQUEST"
+        }
+      },
+      {
+        "name": "stream",
+        "schema": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "on",
+            "off"
+          ],
+          "default": "auto"
+        }
+      }
+    ]
   }
 };
 function deriveCommandPolicy(command_id, optionValues) {
@@ -467,8 +569,8 @@ function deriveCommandPolicy(command_id, optionValues) {
 }
 
 // src/generated/contract.ts
-var CONTRACT_YAML = "cli_contracts: 0.1.0\n\ninfo:\n  title: GraphDDB CLI\n  version: 0.1.0\n  description: >-\n    Contract for the graphddb code-generation CLI. The CLI reads TypeScript\n    GraphDDB model / query / command definitions (the single source of truth)\n    and emits Python bindings (manifest.json, operations.json, types.py,\n    repositories.py, __init__.py) for the Python bridge runtime.\n  license:\n    name: MIT\n  contact:\n    name: foo-log-inc\n    url: https://github.com/foo-log-inc/graphddb\n\nartifact_slots:\n  ts-definitions:\n    description: >-\n      TypeScript GraphDDB definition modules (entity models, defineQueries,\n      defineCommands) used as the single source of truth.\n    direction: read\n  generated-code:\n    description: >-\n      Generated Python bindings and JSON specs written to the output directory\n      (manifest.json, operations.json, types.py, repositories.py, __init__.py).\n    direction: write\n\ncommand_sets:\n  graphddb:\n    summary: Graph data modeling on DynamoDB \u2014 code generation CLI.\n    x-stdin: >-\n      No command reads from stdin. All inputs are provided via file options.\n\n    commands:\n      # \u2500\u2500 generate python \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.python:\n        summary: Generate Python bindings from TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models, query definitions, and command\n          definitions, builds the serializable manifest / operations bundle, and\n          writes the Python bridge bindings (manifest.json, operations.json,\n          types.py, repositories.py, __init__.py) to the output directory.\n          Output is deterministic for a given set of inputs.\n        usage:\n          - graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/\n          - graphddb generate python --entry definitions.ts --out generated/\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import). May also export queries / commands.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: queries\n            aliases: [q]\n            description: >-\n              Module exporting `queries` (a defineQueries map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: commands\n            aliases: [c]\n            description: >-\n              Module exporting `commands` (a defineCommands map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: transactions\n            aliases: [t]\n            description: >-\n              Module exporting `transactions` (a defineTransactions map).\n              Defaults to the commands module (or the entry module) when omitted.\n              Optional \u2014 a project with no declarative transactions omits it.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contracts\n            description: >-\n              Module exporting `contracts` (a map of publicQueryModel /\n              publicCommandModel results \u2014 the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 a project with no\n              contracts omits it, and the output gains no `contracts` content.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contexts\n            description: >-\n              Module exporting `contexts` (context-ownership: context name \u2192 the\n              Model / Contract names that belong to it). Defaults to the\n              contracts module (or the entry module) when omitted. Optional \u2014\n              consumed by the boundary lint to tell own from foreign.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: dataclass\n            description: >-\n              Emit Python result / element types as @dataclass classes instead\n              of TypedDict (decimal / Optional / Connection mapped accordingly).\n            schema:\n              type: boolean\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Python bindings.\n            value_name: dir\n            schema:\n              type: string\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n            files:\n              - path: '{options.out}/manifest.json'\n                required: true\n                media_type: application/json\n                description: Entity / table / key / relation metadata.\n              - path: '{options.out}/operations.json'\n                required: true\n                media_type: application/json\n                description: Per-query / per-command execution specs.\n              - path: '{options.out}/types.py'\n                required: true\n                media_type: text/x-python\n                description: TypedDict result types derived from query selects.\n              - path: '{options.out}/repositories.py'\n                required: true\n                media_type: text/x-python\n                description: Per-entity repository classes (sync methods).\n              - path: '{options.out}/__init__.py'\n                required: true\n                media_type: text/x-python\n                description: Package re-exports for the generated bindings.\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n      # \u2500\u2500 generate cloudformation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.cloudformation:\n        summary: >-\n          Generate an AWS CloudFormation template (DynamoDB table + GSIs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and builds the serializable\n          manifest, then emits an AWS CloudFormation template describing the\n          DynamoDB table(s) the single-table design maps onto: one\n          `AWS::DynamoDB::Table` per physical table, with the base key schema\n          (`PK` / `SK`), the unioned Global Secondary Indexes\n          (`<indexName>PK` / `<indexName>SK`), `PAY_PER_REQUEST` billing, a\n          `TableName` parameter (default = physical name), and Outputs\n          (table name + ARN). Output is deterministic and, by default, YAML.\n        usage:\n          - graphddb generate cloudformation --entry models.ts --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --format json\n          - graphddb generate cloudformation --entry models.ts --gsi-projection KEYS_ONLY --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --stream on --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --pitr --sse --table-class STANDARD_INFREQUENT_ACCESS --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --rcu 10 --wcu 5 --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --autoscale --autoscale-min 5 --autoscale-max 100 --autoscale-target 70 --out table.yaml\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import).\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: out\n            aliases: [o]\n            description: >-\n              Output file for the generated CloudFormation template. Written to\n              stdout when omitted.\n            value_name: file\n            schema:\n              type: string\n\n          - name: format\n            aliases: [f]\n            description: Output serialization format (yaml or json).\n            value_name: format\n            schema:\n              type: string\n              enum: [yaml, json]\n              default: yaml\n\n          - name: gsi-projection\n            description: >-\n              GSI ProjectionType. ALL (default) projects every attribute;\n              KEYS_ONLY projects only the key attributes.\n            value_name: projection\n            schema:\n              type: string\n              enum: [ALL, KEYS_ONLY]\n              default: ALL\n\n          - name: stream\n            description: >-\n              DynamoDB Streams (StreamSpecification NEW_AND_OLD_IMAGES) emission.\n              auto (default) emits a stream only when the model set uses\n              stream-based maintenance (updateMode:'stream'); on always emits;\n              off never emits. When enabled, a StreamArn Output is added too.\n            value_name: mode\n            schema:\n              type: string\n              enum: [auto, on, off]\n              default: auto\n\n          - name: billing-mode\n            description: >-\n              DynamoDB billing mode. PAY_PER_REQUEST (default) is on-demand\n              (no provisioned throughput). PROVISIONED emits BillingMode:\n              PROVISIONED with ProvisionedThroughput (see --rcu / --wcu) on the\n              table and every GSI, and unlocks Application Auto Scaling\n              (--autoscale).\n            value_name: mode\n            schema:\n              type: string\n              enum: [PAY_PER_REQUEST, PROVISIONED]\n              default: PAY_PER_REQUEST\n\n          - name: rcu\n            description: >-\n              Provisioned ReadCapacityUnits (a positive integer) applied to the\n              table and every GSI. Only valid with --billing-mode PROVISIONED\n              (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: wcu\n            description: >-\n              Provisioned WriteCapacityUnits (a positive integer) applied to the\n              table and every GSI. Only valid with --billing-mode PROVISIONED\n              (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale\n            description: >-\n              Enable Application Auto Scaling. Emits an\n              AWS::ApplicationAutoScaling::ScalableTarget +\n              AWS::ApplicationAutoScaling::ScalingPolicy pair for the table read\n              and write capacity AND for each GSI read and write capacity. Only\n              valid with --billing-mode PROVISIONED (autoscaling is invalid on\n              on-demand and is rejected). Off by default \u2014 no autoscaling\n              resources are emitted unless this flag is passed.\n            schema:\n              type: boolean\n\n          - name: autoscale-min\n            description: >-\n              Auto Scaling minimum capacity (MinCapacity) for every scalable\n              target. Must be <= --autoscale-max. Only meaningful with\n              --autoscale. Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale-max\n            description: >-\n              Auto Scaling maximum capacity (MaxCapacity) for every scalable\n              target. Must be >= --autoscale-min. Only meaningful with\n              --autoscale. Defaults to 100 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale-target\n            description: >-\n              Auto Scaling target utilization percentage (TargetValue of the\n              TargetTrackingScaling policy). Only meaningful with --autoscale.\n              Defaults to 70 when omitted.\n            value_name: percent\n            schema:\n              type: integer\n              minimum: 1\n              maximum: 100\n\n          - name: pitr\n            description: >-\n              Enable point-in-time recovery (PointInTimeRecoverySpecification\n              PointInTimeRecoveryEnabled:true). Off by default \u2014 the property is\n              omitted entirely unless this flag is passed.\n            schema:\n              type: boolean\n\n          - name: table-class\n            description: >-\n              DynamoDB table class. Omitted by default (AWS defaults to\n              STANDARD); pass STANDARD or STANDARD_INFREQUENT_ACCESS to emit\n              TableClass.\n            value_name: class\n            schema:\n              type: string\n              enum: [STANDARD, STANDARD_INFREQUENT_ACCESS]\n\n          - name: sse\n            description: >-\n              Enable server-side encryption with the AWS-owned/managed key\n              (SSESpecification SSEEnabled:true). Off by default \u2014 the property is\n              omitted entirely unless this flag is passed.\n            schema:\n              type: boolean\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\ncomponents:\n  schemas:\n    GenerateResult:\n      type: object\n      required: [status, outDir, files]\n      properties:\n        status:\n          type: string\n          enum: [ok]\n        outDir:\n          type: string\n          description: Output directory the files were written to.\n        files:\n          type: array\n          description: Paths of the generated files (relative to outDir).\n          items:\n            type: string\n    Error:\n      type: object\n      required: [code, message]\n      properties:\n        code:\n          type: string\n        message:\n          type: string\n";
-var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "GraphDDB CLI",\n    "version": "0.1.0",\n    "description": "Contract for the graphddb code-generation CLI. The CLI reads TypeScript GraphDDB model / query / command definitions (the single source of truth) and emits Python bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) for the Python bridge runtime.",\n    "license": {\n      "name": "MIT"\n    },\n    "contact": {\n      "name": "foo-log-inc",\n      "url": "https://github.com/foo-log-inc/graphddb"\n    }\n  },\n  "artifact_slots": {\n    "ts-definitions": {\n      "description": "TypeScript GraphDDB definition modules (entity models, defineQueries, defineCommands) used as the single source of truth.",\n      "direction": "read"\n    },\n    "generated-code": {\n      "description": "Generated Python bindings and JSON specs written to the output directory (manifest.json, operations.json, types.py, repositories.py, __init__.py).",\n      "direction": "write"\n    }\n  },\n  "command_sets": {\n    "graphddb": {\n      "summary": "Graph data modeling on DynamoDB \u2014 code generation CLI.",\n      "x-stdin": "No command reads from stdin. All inputs are provided via file options.",\n      "commands": {\n        "generate.python": {\n          "summary": "Generate Python bindings from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models, query definitions, and command definitions, builds the serializable manifest / operations bundle, and writes the Python bridge bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) to the output directory. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/",\n            "graphddb generate python --entry definitions.ts --out generated/"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import). May also export queries / commands.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "queries",\n              "aliases": [\n                "q"\n              ],\n              "description": "Module exporting `queries` (a defineQueries map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "commands",\n              "aliases": [\n                "c"\n              ],\n              "description": "Module exporting `commands` (a defineCommands map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "transactions",\n              "aliases": [\n                "t"\n              ],\n              "description": "Module exporting `transactions` (a defineTransactions map). Defaults to the commands module (or the entry module) when omitted. Optional \u2014 a project with no declarative transactions omits it.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contracts",\n              "description": "Module exporting `contracts` (a map of publicQueryModel / publicCommandModel results \u2014 the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 a project with no contracts omits it, and the output gains no `contracts` content.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contexts",\n              "description": "Module exporting `contexts` (context-ownership: context name \u2192 the Model / Contract names that belong to it). Defaults to the contracts module (or the entry module) when omitted. Optional \u2014 consumed by the boundary lint to tell own from foreign.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "dataclass",\n              "description": "Emit Python result / element types as @dataclass classes instead of TypedDict (decimal / Optional / Connection mapped accordingly).",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Python bindings.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              },\n              "files": [\n                {\n                  "path": "{options.out}/manifest.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Entity / table / key / relation metadata."\n                },\n                {\n                  "path": "{options.out}/operations.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Per-query / per-command execution specs."\n                },\n                {\n                  "path": "{options.out}/types.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "TypedDict result types derived from query selects."\n                },\n                {\n                  "path": "{options.out}/repositories.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Per-entity repository classes (sync methods)."\n                },\n                {\n                  "path": "{options.out}/__init__.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Package re-exports for the generated bindings."\n                }\n              ]\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        },\n        "generate.cloudformation": {\n          "summary": "Generate an AWS CloudFormation template (DynamoDB table + GSIs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and builds the serializable manifest, then emits an AWS CloudFormation template describing the DynamoDB table(s) the single-table design maps onto: one `AWS::DynamoDB::Table` per physical table, with the base key schema (`PK` / `SK`), the unioned Global Secondary Indexes (`<indexName>PK` / `<indexName>SK`), `PAY_PER_REQUEST` billing, a `TableName` parameter (default = physical name), and Outputs (table name + ARN). Output is deterministic and, by default, YAML.",\n          "usage": [\n            "graphddb generate cloudformation --entry models.ts --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --format json",\n            "graphddb generate cloudformation --entry models.ts --gsi-projection KEYS_ONLY --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --stream on --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --pitr --sse --table-class STANDARD_INFREQUENT_ACCESS --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --rcu 10 --wcu 5 --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --autoscale --autoscale-min 5 --autoscale-max 100 --autoscale-target 70 --out table.yaml"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import).",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "description": "Output file for the generated CloudFormation template. Written to stdout when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "description": "Output serialization format (yaml or json).",\n              "value_name": "format",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "yaml",\n                  "json"\n                ],\n                "default": "yaml"\n              }\n            },\n            {\n              "name": "gsi-projection",\n              "description": "GSI ProjectionType. ALL (default) projects every attribute; KEYS_ONLY projects only the key attributes.",\n              "value_name": "projection",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "ALL",\n                  "KEYS_ONLY"\n                ],\n                "default": "ALL"\n              }\n            },\n            {\n              "name": "stream",\n              "description": "DynamoDB Streams (StreamSpecification NEW_AND_OLD_IMAGES) emission. auto (default) emits a stream only when the model set uses stream-based maintenance (updateMode:\'stream\'); on always emits; off never emits. When enabled, a StreamArn Output is added too.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "auto",\n                  "on",\n                  "off"\n                ],\n                "default": "auto"\n              }\n            },\n            {\n              "name": "billing-mode",\n              "description": "DynamoDB billing mode. PAY_PER_REQUEST (default) is on-demand (no provisioned throughput). PROVISIONED emits BillingMode: PROVISIONED with ProvisionedThroughput (see --rcu / --wcu) on the table and every GSI, and unlocks Application Auto Scaling (--autoscale).",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "PAY_PER_REQUEST",\n                  "PROVISIONED"\n                ],\n                "default": "PAY_PER_REQUEST"\n              }\n            },\n            {\n              "name": "rcu",\n              "description": "Provisioned ReadCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "wcu",\n              "description": "Provisioned WriteCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale",\n              "description": "Enable Application Auto Scaling. Emits an AWS::ApplicationAutoScaling::ScalableTarget + AWS::ApplicationAutoScaling::ScalingPolicy pair for the table read and write capacity AND for each GSI read and write capacity. Only valid with --billing-mode PROVISIONED (autoscaling is invalid on on-demand and is rejected). Off by default \u2014 no autoscaling resources are emitted unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "autoscale-min",\n              "description": "Auto Scaling minimum capacity (MinCapacity) for every scalable target. Must be <= --autoscale-max. Only meaningful with --autoscale. Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale-max",\n              "description": "Auto Scaling maximum capacity (MaxCapacity) for every scalable target. Must be >= --autoscale-min. Only meaningful with --autoscale. Defaults to 100 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale-target",\n              "description": "Auto Scaling target utilization percentage (TargetValue of the TargetTrackingScaling policy). Only meaningful with --autoscale. Defaults to 70 when omitted.",\n              "value_name": "percent",\n              "schema": {\n                "type": "integer",\n                "minimum": 1,\n                "maximum": 100\n              }\n            },\n            {\n              "name": "pitr",\n              "description": "Enable point-in-time recovery (PointInTimeRecoverySpecification PointInTimeRecoveryEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "table-class",\n              "description": "DynamoDB table class. Omitted by default (AWS defaults to STANDARD); pass STANDARD or STANDARD_INFREQUENT_ACCESS to emit TableClass.",\n              "value_name": "class",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "STANDARD",\n                  "STANDARD_INFREQUENT_ACCESS"\n                ]\n              }\n            },\n            {\n              "name": "sse",\n              "description": "Enable server-side encryption with the AWS-owned/managed key (SSESpecification SSEEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              }\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  "components": {\n    "schemas": {\n      "GenerateResult": {\n        "type": "object",\n        "required": [\n          "status",\n          "outDir",\n          "files"\n        ],\n        "properties": {\n          "status": {\n            "type": "string",\n            "enum": [\n              "ok"\n            ]\n          },\n          "outDir": {\n            "type": "string",\n            "description": "Output directory the files were written to."\n          },\n          "files": {\n            "type": "array",\n            "description": "Paths of the generated files (relative to outDir).",\n            "items": {\n              "type": "string"\n            }\n          }\n        }\n      },\n      "Error": {\n        "type": "object",\n        "required": [\n          "code",\n          "message"\n        ],\n        "properties": {\n          "code": {\n            "type": "string"\n          },\n          "message": {\n            "type": "string"\n          }\n        }\n      }\n    }\n  }\n}';
+var CONTRACT_YAML = "cli_contracts: 0.1.0\n\ninfo:\n  title: GraphDDB CLI\n  version: 0.1.0\n  description: >-\n    Contract for the graphddb code-generation CLI. The CLI reads TypeScript\n    GraphDDB model / query / command definitions (the single source of truth)\n    and emits Python bindings (manifest.json, operations.json, types.py,\n    repositories.py, __init__.py) for the Python bridge runtime.\n  license:\n    name: MIT\n  contact:\n    name: foo-log-inc\n    url: https://github.com/foo-log-inc/graphddb\n\nartifact_slots:\n  ts-definitions:\n    description: >-\n      TypeScript GraphDDB definition modules (entity models, defineQueries,\n      defineCommands) used as the single source of truth.\n    direction: read\n  generated-code:\n    description: >-\n      Generated Python bindings and JSON specs written to the output directory\n      (manifest.json, operations.json, types.py, repositories.py, __init__.py).\n    direction: write\n\ncommand_sets:\n  graphddb:\n    summary: Graph data modeling on DynamoDB \u2014 code generation CLI.\n    x-stdin: >-\n      No command reads from stdin. All inputs are provided via file options.\n\n    commands:\n      # \u2500\u2500 generate python \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.python:\n        summary: Generate Python bindings from TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models, query definitions, and command\n          definitions, builds the serializable manifest / operations bundle, and\n          writes the Python bridge bindings (manifest.json, operations.json,\n          types.py, repositories.py, __init__.py) to the output directory.\n          Output is deterministic for a given set of inputs.\n        usage:\n          - graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/\n          - graphddb generate python --entry definitions.ts --out generated/\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import). May also export queries / commands.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: queries\n            aliases: [q]\n            description: >-\n              Module exporting `queries` (a defineQueries map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: commands\n            aliases: [c]\n            description: >-\n              Module exporting `commands` (a defineCommands map). Defaults to the\n              entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: transactions\n            aliases: [t]\n            description: >-\n              Module exporting `transactions` (a defineTransactions map).\n              Defaults to the commands module (or the entry module) when omitted.\n              Optional \u2014 a project with no declarative transactions omits it.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contracts\n            description: >-\n              Module exporting `contracts` (a map of publicQueryModel /\n              publicCommandModel results \u2014 the CQRS Contract layer). Defaults to\n              the entry module when omitted. Optional \u2014 a project with no\n              contracts omits it, and the output gains no `contracts` content.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: contexts\n            description: >-\n              Module exporting `contexts` (context-ownership: context name \u2192 the\n              Model / Contract names that belong to it). Defaults to the\n              contracts module (or the entry module) when omitted. Optional \u2014\n              consumed by the boundary lint to tell own from foreign.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: dataclass\n            description: >-\n              Emit Python result / element types as @dataclass classes instead\n              of TypedDict (decimal / Optional / Connection mapped accordingly).\n            schema:\n              type: boolean\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: Output directory for the generated Python bindings.\n            value_name: dir\n            schema:\n              type: string\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n            files:\n              - path: '{options.out}/manifest.json'\n                required: true\n                media_type: application/json\n                description: Entity / table / key / relation metadata.\n              - path: '{options.out}/operations.json'\n                required: true\n                media_type: application/json\n                description: Per-query / per-command execution specs.\n              - path: '{options.out}/types.py'\n                required: true\n                media_type: text/x-python\n                description: TypedDict result types derived from query selects.\n              - path: '{options.out}/repositories.py'\n                required: true\n                media_type: text/x-python\n                description: Per-entity repository classes (sync methods).\n              - path: '{options.out}/__init__.py'\n                required: true\n                media_type: text/x-python\n                description: Package re-exports for the generated bindings.\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n      # \u2500\u2500 generate cloudformation \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.cloudformation:\n        summary: >-\n          Generate an AWS CloudFormation template (DynamoDB table + GSIs) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models and builds the serializable\n          manifest, then emits an AWS CloudFormation template describing the\n          DynamoDB table(s) the single-table design maps onto: one\n          `AWS::DynamoDB::Table` per physical table, with the base key schema\n          (`PK` / `SK`), the unioned Global Secondary Indexes\n          (`<indexName>PK` / `<indexName>SK`), `PAY_PER_REQUEST` billing, a\n          `TableName` parameter (default = physical name), and Outputs\n          (table name + ARN). Output is deterministic and, by default, YAML.\n        usage:\n          - graphddb generate cloudformation --entry models.ts --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --format json\n          - graphddb generate cloudformation --entry models.ts --gsi-projection KEYS_ONLY --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --stream on --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --pitr --sse --table-class STANDARD_INFREQUENT_ACCESS --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --rcu 10 --wcu 5 --out table.yaml\n          - graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --autoscale --autoscale-min 5 --autoscale-max 100 --autoscale-target 70 --out table.yaml\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import).\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: out\n            aliases: [o]\n            description: >-\n              Output file for the generated CloudFormation template. Written to\n              stdout when omitted.\n            value_name: file\n            schema:\n              type: string\n\n          - name: format\n            aliases: [f]\n            description: Output serialization format (yaml or json).\n            value_name: format\n            schema:\n              type: string\n              enum: [yaml, json]\n              default: yaml\n\n          - name: gsi-projection\n            description: >-\n              GSI ProjectionType. ALL (default) projects every attribute;\n              KEYS_ONLY projects only the key attributes.\n            value_name: projection\n            schema:\n              type: string\n              enum: [ALL, KEYS_ONLY]\n              default: ALL\n\n          - name: stream\n            description: >-\n              DynamoDB Streams (StreamSpecification NEW_AND_OLD_IMAGES) emission.\n              auto (default) emits a stream only when the model set uses\n              stream-based maintenance (updateMode:'stream'); on always emits;\n              off never emits. When enabled, a StreamArn Output is added too.\n            value_name: mode\n            schema:\n              type: string\n              enum: [auto, on, off]\n              default: auto\n\n          - name: billing-mode\n            description: >-\n              DynamoDB billing mode. PAY_PER_REQUEST (default) is on-demand\n              (no provisioned throughput). PROVISIONED emits BillingMode:\n              PROVISIONED with ProvisionedThroughput (see --rcu / --wcu) on the\n              table and every GSI, and unlocks Application Auto Scaling\n              (--autoscale).\n            value_name: mode\n            schema:\n              type: string\n              enum: [PAY_PER_REQUEST, PROVISIONED]\n              default: PAY_PER_REQUEST\n\n          - name: rcu\n            description: >-\n              Provisioned ReadCapacityUnits (a positive integer) applied to the\n              table and every GSI. Only valid with --billing-mode PROVISIONED\n              (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: wcu\n            description: >-\n              Provisioned WriteCapacityUnits (a positive integer) applied to the\n              table and every GSI. Only valid with --billing-mode PROVISIONED\n              (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale\n            description: >-\n              Enable Application Auto Scaling. Emits an\n              AWS::ApplicationAutoScaling::ScalableTarget +\n              AWS::ApplicationAutoScaling::ScalingPolicy pair for the table read\n              and write capacity AND for each GSI read and write capacity. Only\n              valid with --billing-mode PROVISIONED (autoscaling is invalid on\n              on-demand and is rejected). Off by default \u2014 no autoscaling\n              resources are emitted unless this flag is passed.\n            schema:\n              type: boolean\n\n          - name: autoscale-min\n            description: >-\n              Auto Scaling minimum capacity (MinCapacity) for every scalable\n              target. Must be <= --autoscale-max. Only meaningful with\n              --autoscale. Defaults to 5 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale-max\n            description: >-\n              Auto Scaling maximum capacity (MaxCapacity) for every scalable\n              target. Must be >= --autoscale-min. Only meaningful with\n              --autoscale. Defaults to 100 when omitted.\n            value_name: units\n            schema:\n              type: integer\n              minimum: 1\n\n          - name: autoscale-target\n            description: >-\n              Auto Scaling target utilization percentage (TargetValue of the\n              TargetTrackingScaling policy). Only meaningful with --autoscale.\n              Defaults to 70 when omitted.\n            value_name: percent\n            schema:\n              type: integer\n              minimum: 1\n              maximum: 100\n\n          - name: pitr\n            description: >-\n              Enable point-in-time recovery (PointInTimeRecoverySpecification\n              PointInTimeRecoveryEnabled:true). Off by default \u2014 the property is\n              omitted entirely unless this flag is passed.\n            schema:\n              type: boolean\n\n          - name: table-class\n            description: >-\n              DynamoDB table class. Omitted by default (AWS defaults to\n              STANDARD); pass STANDARD or STANDARD_INFREQUENT_ACCESS to emit\n              TableClass.\n            value_name: class\n            schema:\n              type: string\n              enum: [STANDARD, STANDARD_INFREQUENT_ACCESS]\n\n          - name: sse\n            description: >-\n              Enable server-side encryption with the AWS-owned/managed key\n              (SSESpecification SSEEnabled:true). Off by default \u2014 the property is\n              omitted entirely unless this flag is passed.\n            schema:\n              type: boolean\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n      # \u2500\u2500 generate docs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n      generate.docs:\n        summary: >-\n          Generate model-specification documentation (Markdown + Mermaid) from\n          TypeScript GraphDDB definitions.\n        description: >-\n          Loads the TypeScript entity models (and, optionally, query / command\n          definitions), builds the serializable manifest / operations bundle, then\n          renders human-facing model documentation \u2014 Table Overview, Entity\n          Relationship Diagram, Physical Key Schema, Property Matrix, Entity\n          Details, Access Patterns, Mutation Contracts, Maintained Access Paths,\n          CDC, and CloudFormation summary \u2014 as Markdown with Mermaid diagrams. The\n          layout is defined by bundled Handlebars templates users can override with\n          --template-dir (per-partial) and extend with --helpers. Output is\n          deterministic for a given set of inputs.\n        usage:\n          - graphddb generate docs --entry models.ts --out doc.md\n          - graphddb generate docs --entry models.ts --queries definitions.ts --out doc.md\n          - graphddb generate docs --entry models.ts --out docs/\n          - graphddb generate docs --entry models.ts --out docs/ --template-dir doc-templates/ --helpers doc-helpers.js\n\n        effects:\n          risk_level: low\n          reads:\n            - ts-definitions\n          writes:\n            - generated-code\n\n        x-agent:\n          recommended_before_use:\n            - \"Ensure the TypeScript definitions type-check and lint cleanly.\"\n\n        options:\n          - name: entry\n            aliases: [e]\n            required: true\n            description: >-\n              Entry module that registers the entity models (side-effecting\n              import). May also export queries / commands.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: queries\n            aliases: [q]\n            description: >-\n              Module exporting `queries` / `commands` (defineQueries /\n              defineCommands maps) used for the Access Patterns / Mutation\n              Contracts sections. Defaults to the entry module when omitted.\n            value_name: file\n            schema:\n              type: string\n            file:\n              mode: read\n              exists: true\n              media_type: application/typescript\n              encoding: utf-8\n\n          - name: out\n            aliases: [o]\n            required: true\n            description: >-\n              Output path for the generated documentation. A file path ending in\n              .md writes the single Markdown file at exactly that path (creating\n              parent directories); any other value is treated as a directory and\n              the file is written as <dir>/index.md.\n            value_name: path\n            schema:\n              type: string\n\n          - name: format\n            aliases: [f]\n            description: Output format. Only markdown is supported today.\n            value_name: format\n            schema:\n              type: string\n              enum: [markdown]\n              default: markdown\n\n          - name: split\n            description: >-\n              Output granularity. none (default) emits a single index.md; entity\n              is reserved for a future per-entity split.\n            value_name: mode\n            schema:\n              type: string\n              enum: [none, entity]\n              default: none\n\n          - name: template-dir\n            description: >-\n              Directory of override <partial>.hbs templates. Each same-named\n              partial (index / table-overview / er-diagram / key-schema /\n              property-matrix / entity / access-pattern / maintained / cdc /\n              cloudformation) overrides the bundled one; absent partials fall back\n              to the bundled default.\n            value_name: dir\n            schema:\n              type: string\n\n          - name: helpers\n            description: >-\n              JS module whose default (or named `helpers`) export is a map of extra\n              Handlebars helpers to register alongside the built-in set (eq / join\n              / pascal / mermaidId / codeOrEmpty).\n            value_name: file\n            schema:\n              type: string\n\n          - name: billing-mode\n            description: >-\n              DynamoDB billing mode used in the Table Overview (shared with\n              generate cloudformation). PAY_PER_REQUEST (default) or PROVISIONED.\n            value_name: mode\n            schema:\n              type: string\n              enum: [PAY_PER_REQUEST, PROVISIONED]\n              default: PAY_PER_REQUEST\n\n          - name: stream\n            description: >-\n              DynamoDB Streams state used in the Table Overview (shared with\n              generate cloudformation). auto (default) detects stream-based\n              maintenance (updateMode:'stream'); on always enabled; off never.\n            value_name: mode\n            schema:\n              type: string\n              enum: [auto, on, off]\n              default: auto\n\n        exits:\n          '0':\n            description: Generation succeeded.\n            stdout:\n              format: json\n              schema:\n                $ref: '#/components/schemas/GenerateResult'\n\n          '1':\n            description: Unexpected error.\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\n          '2':\n            description: Invalid arguments (missing/unreadable input or output).\n            stderr:\n              format: json\n              schema:\n                $ref: '#/components/schemas/Error'\n\ncomponents:\n  schemas:\n    GenerateResult:\n      type: object\n      required: [status, outDir, files]\n      properties:\n        status:\n          type: string\n          enum: [ok]\n        outDir:\n          type: string\n          description: Output directory the files were written to.\n        files:\n          type: array\n          description: Paths of the generated files (relative to outDir).\n          items:\n            type: string\n    Error:\n      type: object\n      required: [code, message]\n      properties:\n        code:\n          type: string\n        message:\n          type: string\n";
+var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "GraphDDB CLI",\n    "version": "0.1.0",\n    "description": "Contract for the graphddb code-generation CLI. The CLI reads TypeScript GraphDDB model / query / command definitions (the single source of truth) and emits Python bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) for the Python bridge runtime.",\n    "license": {\n      "name": "MIT"\n    },\n    "contact": {\n      "name": "foo-log-inc",\n      "url": "https://github.com/foo-log-inc/graphddb"\n    }\n  },\n  "artifact_slots": {\n    "ts-definitions": {\n      "description": "TypeScript GraphDDB definition modules (entity models, defineQueries, defineCommands) used as the single source of truth.",\n      "direction": "read"\n    },\n    "generated-code": {\n      "description": "Generated Python bindings and JSON specs written to the output directory (manifest.json, operations.json, types.py, repositories.py, __init__.py).",\n      "direction": "write"\n    }\n  },\n  "command_sets": {\n    "graphddb": {\n      "summary": "Graph data modeling on DynamoDB \u2014 code generation CLI.",\n      "x-stdin": "No command reads from stdin. All inputs are provided via file options.",\n      "commands": {\n        "generate.python": {\n          "summary": "Generate Python bindings from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models, query definitions, and command definitions, builds the serializable manifest / operations bundle, and writes the Python bridge bindings (manifest.json, operations.json, types.py, repositories.py, __init__.py) to the output directory. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate python --entry models.ts --queries queries.ts --commands commands.ts --out generated/",\n            "graphddb generate python --entry definitions.ts --out generated/"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import). May also export queries / commands.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "queries",\n              "aliases": [\n                "q"\n              ],\n              "description": "Module exporting `queries` (a defineQueries map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "commands",\n              "aliases": [\n                "c"\n              ],\n              "description": "Module exporting `commands` (a defineCommands map). Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "transactions",\n              "aliases": [\n                "t"\n              ],\n              "description": "Module exporting `transactions` (a defineTransactions map). Defaults to the commands module (or the entry module) when omitted. Optional \u2014 a project with no declarative transactions omits it.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contracts",\n              "description": "Module exporting `contracts` (a map of publicQueryModel / publicCommandModel results \u2014 the CQRS Contract layer). Defaults to the entry module when omitted. Optional \u2014 a project with no contracts omits it, and the output gains no `contracts` content.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "contexts",\n              "description": "Module exporting `contexts` (context-ownership: context name \u2192 the Model / Contract names that belong to it). Defaults to the contracts module (or the entry module) when omitted. Optional \u2014 consumed by the boundary lint to tell own from foreign.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "dataclass",\n              "description": "Emit Python result / element types as @dataclass classes instead of TypedDict (decimal / Optional / Connection mapped accordingly).",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output directory for the generated Python bindings.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              },\n              "files": [\n                {\n                  "path": "{options.out}/manifest.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Entity / table / key / relation metadata."\n                },\n                {\n                  "path": "{options.out}/operations.json",\n                  "required": true,\n                  "media_type": "application/json",\n                  "description": "Per-query / per-command execution specs."\n                },\n                {\n                  "path": "{options.out}/types.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "TypedDict result types derived from query selects."\n                },\n                {\n                  "path": "{options.out}/repositories.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Per-entity repository classes (sync methods)."\n                },\n                {\n                  "path": "{options.out}/__init__.py",\n                  "required": true,\n                  "media_type": "text/x-python",\n                  "description": "Package re-exports for the generated bindings."\n                }\n              ]\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        },\n        "generate.cloudformation": {\n          "summary": "Generate an AWS CloudFormation template (DynamoDB table + GSIs) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models and builds the serializable manifest, then emits an AWS CloudFormation template describing the DynamoDB table(s) the single-table design maps onto: one `AWS::DynamoDB::Table` per physical table, with the base key schema (`PK` / `SK`), the unioned Global Secondary Indexes (`<indexName>PK` / `<indexName>SK`), `PAY_PER_REQUEST` billing, a `TableName` parameter (default = physical name), and Outputs (table name + ARN). Output is deterministic and, by default, YAML.",\n          "usage": [\n            "graphddb generate cloudformation --entry models.ts --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --format json",\n            "graphddb generate cloudformation --entry models.ts --gsi-projection KEYS_ONLY --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --stream on --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --pitr --sse --table-class STANDARD_INFREQUENT_ACCESS --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --rcu 10 --wcu 5 --out table.yaml",\n            "graphddb generate cloudformation --entry models.ts --billing-mode PROVISIONED --autoscale --autoscale-min 5 --autoscale-max 100 --autoscale-target 70 --out table.yaml"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import).",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "description": "Output file for the generated CloudFormation template. Written to stdout when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "description": "Output serialization format (yaml or json).",\n              "value_name": "format",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "yaml",\n                  "json"\n                ],\n                "default": "yaml"\n              }\n            },\n            {\n              "name": "gsi-projection",\n              "description": "GSI ProjectionType. ALL (default) projects every attribute; KEYS_ONLY projects only the key attributes.",\n              "value_name": "projection",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "ALL",\n                  "KEYS_ONLY"\n                ],\n                "default": "ALL"\n              }\n            },\n            {\n              "name": "stream",\n              "description": "DynamoDB Streams (StreamSpecification NEW_AND_OLD_IMAGES) emission. auto (default) emits a stream only when the model set uses stream-based maintenance (updateMode:\'stream\'); on always emits; off never emits. When enabled, a StreamArn Output is added too.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "auto",\n                  "on",\n                  "off"\n                ],\n                "default": "auto"\n              }\n            },\n            {\n              "name": "billing-mode",\n              "description": "DynamoDB billing mode. PAY_PER_REQUEST (default) is on-demand (no provisioned throughput). PROVISIONED emits BillingMode: PROVISIONED with ProvisionedThroughput (see --rcu / --wcu) on the table and every GSI, and unlocks Application Auto Scaling (--autoscale).",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "PAY_PER_REQUEST",\n                  "PROVISIONED"\n                ],\n                "default": "PAY_PER_REQUEST"\n              }\n            },\n            {\n              "name": "rcu",\n              "description": "Provisioned ReadCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "wcu",\n              "description": "Provisioned WriteCapacityUnits (a positive integer) applied to the table and every GSI. Only valid with --billing-mode PROVISIONED (rejected with PAY_PER_REQUEST). Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale",\n              "description": "Enable Application Auto Scaling. Emits an AWS::ApplicationAutoScaling::ScalableTarget + AWS::ApplicationAutoScaling::ScalingPolicy pair for the table read and write capacity AND for each GSI read and write capacity. Only valid with --billing-mode PROVISIONED (autoscaling is invalid on on-demand and is rejected). Off by default \u2014 no autoscaling resources are emitted unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "autoscale-min",\n              "description": "Auto Scaling minimum capacity (MinCapacity) for every scalable target. Must be <= --autoscale-max. Only meaningful with --autoscale. Defaults to 5 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale-max",\n              "description": "Auto Scaling maximum capacity (MaxCapacity) for every scalable target. Must be >= --autoscale-min. Only meaningful with --autoscale. Defaults to 100 when omitted.",\n              "value_name": "units",\n              "schema": {\n                "type": "integer",\n                "minimum": 1\n              }\n            },\n            {\n              "name": "autoscale-target",\n              "description": "Auto Scaling target utilization percentage (TargetValue of the TargetTrackingScaling policy). Only meaningful with --autoscale. Defaults to 70 when omitted.",\n              "value_name": "percent",\n              "schema": {\n                "type": "integer",\n                "minimum": 1,\n                "maximum": 100\n              }\n            },\n            {\n              "name": "pitr",\n              "description": "Enable point-in-time recovery (PointInTimeRecoverySpecification PointInTimeRecoveryEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            },\n            {\n              "name": "table-class",\n              "description": "DynamoDB table class. Omitted by default (AWS defaults to STANDARD); pass STANDARD or STANDARD_INFREQUENT_ACCESS to emit TableClass.",\n              "value_name": "class",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "STANDARD",\n                  "STANDARD_INFREQUENT_ACCESS"\n                ]\n              }\n            },\n            {\n              "name": "sse",\n              "description": "Enable server-side encryption with the AWS-owned/managed key (SSESpecification SSEEnabled:true). Off by default \u2014 the property is omitted entirely unless this flag is passed.",\n              "schema": {\n                "type": "boolean"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              }\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        },\n        "generate.docs": {\n          "summary": "Generate model-specification documentation (Markdown + Mermaid) from TypeScript GraphDDB definitions.",\n          "description": "Loads the TypeScript entity models (and, optionally, query / command definitions), builds the serializable manifest / operations bundle, then renders human-facing model documentation \u2014 Table Overview, Entity Relationship Diagram, Physical Key Schema, Property Matrix, Entity Details, Access Patterns, Mutation Contracts, Maintained Access Paths, CDC, and CloudFormation summary \u2014 as Markdown with Mermaid diagrams. The layout is defined by bundled Handlebars templates users can override with --template-dir (per-partial) and extend with --helpers. Output is deterministic for a given set of inputs.",\n          "usage": [\n            "graphddb generate docs --entry models.ts --out doc.md",\n            "graphddb generate docs --entry models.ts --queries definitions.ts --out doc.md",\n            "graphddb generate docs --entry models.ts --out docs/",\n            "graphddb generate docs --entry models.ts --out docs/ --template-dir doc-templates/ --helpers doc-helpers.js"\n          ],\n          "effects": {\n            "risk_level": "low",\n            "reads": [\n              "ts-definitions"\n            ],\n            "writes": [\n              "generated-code"\n            ]\n          },\n          "x-agent": {\n            "recommended_before_use": [\n              "Ensure the TypeScript definitions type-check and lint cleanly."\n            ]\n          },\n          "options": [\n            {\n              "name": "entry",\n              "aliases": [\n                "e"\n              ],\n              "required": true,\n              "description": "Entry module that registers the entity models (side-effecting import). May also export queries / commands.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "queries",\n              "aliases": [\n                "q"\n              ],\n              "description": "Module exporting `queries` / `commands` (defineQueries / defineCommands maps) used for the Access Patterns / Mutation Contracts sections. Defaults to the entry module when omitted.",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              },\n              "file": {\n                "mode": "read",\n                "exists": true,\n                "media_type": "application/typescript",\n                "encoding": "utf-8"\n              }\n            },\n            {\n              "name": "out",\n              "aliases": [\n                "o"\n              ],\n              "required": true,\n              "description": "Output path for the generated documentation. A file path ending in .md writes the single Markdown file at exactly that path (creating parent directories); any other value is treated as a directory and the file is written as <dir>/index.md.",\n              "value_name": "path",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "description": "Output format. Only markdown is supported today.",\n              "value_name": "format",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "markdown"\n                ],\n                "default": "markdown"\n              }\n            },\n            {\n              "name": "split",\n              "description": "Output granularity. none (default) emits a single index.md; entity is reserved for a future per-entity split.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "none",\n                  "entity"\n                ],\n                "default": "none"\n              }\n            },\n            {\n              "name": "template-dir",\n              "description": "Directory of override <partial>.hbs templates. Each same-named partial (index / table-overview / er-diagram / key-schema / property-matrix / entity / access-pattern / maintained / cdc / cloudformation) overrides the bundled one; absent partials fall back to the bundled default.",\n              "value_name": "dir",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "helpers",\n              "description": "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set (eq / join / pascal / mermaidId / codeOrEmpty).",\n              "value_name": "file",\n              "schema": {\n                "type": "string"\n              }\n            },\n            {\n              "name": "billing-mode",\n              "description": "DynamoDB billing mode used in the Table Overview (shared with generate cloudformation). PAY_PER_REQUEST (default) or PROVISIONED.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "PAY_PER_REQUEST",\n                  "PROVISIONED"\n                ],\n                "default": "PAY_PER_REQUEST"\n              }\n            },\n            {\n              "name": "stream",\n              "description": "DynamoDB Streams state used in the Table Overview (shared with generate cloudformation). auto (default) detects stream-based maintenance (updateMode:\'stream\'); on always enabled; off never.",\n              "value_name": "mode",\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "auto",\n                  "on",\n                  "off"\n                ],\n                "default": "auto"\n              }\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Generation succeeded.",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/GenerateResult"\n                }\n              }\n            },\n            "1": {\n              "description": "Unexpected error.",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            },\n            "2": {\n              "description": "Invalid arguments (missing/unreadable input or output).",\n              "stderr": {\n                "format": "json",\n                "schema": {\n                  "$ref": "#/components/schemas/Error"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  },\n  "components": {\n    "schemas": {\n      "GenerateResult": {\n        "type": "object",\n        "required": [\n          "status",\n          "outDir",\n          "files"\n        ],\n        "properties": {\n          "status": {\n            "type": "string",\n            "enum": [\n              "ok"\n            ]\n          },\n          "outDir": {\n            "type": "string",\n            "description": "Output directory the files were written to."\n          },\n          "files": {\n            "type": "array",\n            "description": "Paths of the generated files (relative to outDir).",\n            "items": {\n              "type": "string"\n            }\n          }\n        }\n      },\n      "Error": {\n        "type": "object",\n        "required": [\n          "code",\n          "message"\n        ],\n        "properties": {\n          "code": {\n            "type": "string"\n          },\n          "message": {\n            "type": "string"\n          }\n        }\n      }\n    }\n  }\n}';
 
 // src/generated/program.ts
 function createProgram(handlers2, version) {
@@ -494,6 +596,15 @@ function createProgram(handlers2, version) {
     }
     await handlers2.generateCloudformation(opts, globalOpts);
   });
+  __cmd_generate.command("docs").description("Generate model-specification documentation (Markdown + Mermaid) from TypeScript GraphDDB definitions.").option("-e, --entry <file>", "Entry module that registers the entity models (side-effecting import). May also export queries / commands.").option("-q, --queries <file>", "Module exporting `queries` / `commands` (defineQueries / defineCommands maps) used for the Access Patterns / Mutation Contracts sections. Defaults to the entry module when omitted.").option("-o, --out <path>", "Output path for the generated documentation. A file path ending in .md writes the single Markdown file at exactly that path (creating parent directories); any other value is treated as a directory and the file is written as <dir>/index.md.").option("-f, --format <format>", "Output format. Only markdown is supported today.", "markdown").option("--split <mode>", "Output granularity. none (default) emits a single index.md; entity is reserved for a future per-entity split.", "none").option("--template-dir <dir>", "Directory of override <partial>.hbs templates. Each same-named partial (index / table-overview / er-diagram / key-schema / property-matrix / entity / access-pattern / maintained / cdc / cloudformation) overrides the bundled one; absent partials fall back to the bundled default.").option("--helpers <file>", "JS module whose default (or named `helpers`) export is a map of extra Handlebars helpers to register alongside the built-in set (eq / join / pascal / mermaidId / codeOrEmpty).").option("--billing-mode <mode>", "DynamoDB billing mode used in the Table Overview (shared with generate cloudformation). PAY_PER_REQUEST (default) or PROVISIONED.", "PAY_PER_REQUEST").option("--stream <mode>", "DynamoDB Streams state used in the Table Overview (shared with generate cloudformation). auto (default) detects stream-based maintenance (updateMode:'stream'); on always enabled; off never.", "auto").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("generate.docs", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.generateDocs(opts, globalOpts);
+  });
   program.command("extract").description("Extract contract specification for this CLI tool.").argument("[commands...]", "Command IDs to extract. Use dot notation.").option("-a, --all", "Extract all commands.", false).option("--include-meta", "Include extraction metadata.", true).option("-F, --format <format>", "Output format (yaml or json).", "yaml").action(async (commands, opts, cmd) => {
     if (commands.length === 0 && !opts.all) {
       process.stderr.write(JSON.stringify({ code: "INVALID_ARGS", message: "Specify command IDs or use --all" }) + "\n");
@@ -511,7 +622,7 @@ function createProgram(handlers2, version) {
             type: "cli-contracts/extract",
             extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
             specVersion: doc.cli_contracts ?? "0.1.0",
-            commands: ["graphddb.generate.python", "graphddb.generate.cloudformation"]
+            commands: ["graphddb.generate.python", "graphddb.generate.cloudformation", "graphddb.generate.docs"]
           };
         }
         Object.assign(out, doc);
@@ -528,7 +639,7 @@ function createProgram(handlers2, version) {
           yamlLines.push("extractedAt: " + (/* @__PURE__ */ new Date()).toISOString());
           yamlLines.push("spec_version: " + (doc.cli_contracts ?? "0.1.0"));
           yamlLines.push("commands:");
-          for (const id of ["graphddb.generate.python", "graphddb.generate.cloudformation"]) {
+          for (const id of ["graphddb.generate.python", "graphddb.generate.cloudformation", "graphddb.generate.docs"]) {
             yamlLines.push("  - " + id);
           }
         }
@@ -571,7 +682,7 @@ function createProgram(handlers2, version) {
 import { mkdirSync, writeFileSync } from "fs";
 import { dirname, relative } from "path";
 import { pathToFileURL } from "url";
-import { isAbsolute, resolve } from "path";
+import { isAbsolute, resolve as resolve2 } from "path";
 
 // src/codegen/python.ts
 var PY_HEADER = "# DO NOT EDIT. Generated by GraphDDB.";
@@ -633,6 +744,11 @@ function collectResultTypes(manifest, entity, select, typeName, out, seen) {
     const value = select[field];
     const relation = meta?.relations[field];
     if (relation) {
+      if (relation.type === "refs") {
+        throw new Error(
+          `Relation '${field}' on '${relation.target}' is a 'refs' relation (issue #197): it is resolvable only through the TS in-process runtime, not the Python runtime (its parent-list BatchGet fan-out has no static-spec / Python representation). Remove '${field}' from selects compiled to generated Python types.`
+        );
+      }
       const spec = normalizeSelectSpec(value);
       const childSelect = spec.select ?? {};
       const itemTypeName = `${typeName}${toPascalCase(field)}Item`;
@@ -1463,6 +1579,662 @@ function generateCdcRegistry(options = {}) {
   return lines.join("\n");
 }
 
+// src/codegen/docs-model.ts
+var AS_CONFIGURED = "as configured at deployment";
+function fieldTypeLabel(entity, field) {
+  const f = entity.fields[field];
+  if (!f) return "";
+  if (f.format === "datetime") return "datetime";
+  if (f.format === "date") return "date";
+  return f.type;
+}
+function collectGsiColumns(manifest) {
+  const names = /* @__PURE__ */ new Set();
+  for (const entity of Object.values(manifest.entities)) {
+    for (const gsi of entity.gsis) names.add(gsi.indexName);
+  }
+  return [...names].sort();
+}
+function gsiByName(entity, indexName) {
+  return entity.gsis.find((g) => g.indexName === indexName);
+}
+function propertyRole(entity, property) {
+  const key = entity.key;
+  if (key) {
+    if (referencesField(key.pkTemplate, property)) return "PK";
+    if (key.skTemplate && referencesField(key.skTemplate, property)) return "SK";
+  }
+  for (const gsi of entity.gsis) {
+    if (referencesField(gsi.pkTemplate, property)) return `${gsi.indexName} PK`;
+    if (gsi.skTemplate && referencesField(gsi.skTemplate, property)) {
+      return `${gsi.indexName} SK`;
+    }
+  }
+  if (entity.fields[property]) return "\u2713";
+  return "";
+}
+function referencesField(template, field) {
+  return template.includes(`{${field}}`);
+}
+function keyLabel(prefix, template) {
+  return template ? `${prefix} = ${template}` : "";
+}
+function rootIndex(spec) {
+  const root = spec.operations[0];
+  if (!root) return "";
+  return root.indexName ?? "PK";
+}
+function isRelation(spec) {
+  return spec.operations.length > 1;
+}
+function usesBatchGet(spec) {
+  return spec.operations.some((op) => op.type === "BatchGetItem");
+}
+function usesCursor(spec) {
+  return (spec.cardinality ?? "many") === "many";
+}
+function inputShape(spec) {
+  const parts = [];
+  for (const name of Object.keys(spec.params).sort()) {
+    const p = spec.params[name];
+    const opt = p.required ? "" : "?";
+    parts.push(`${name}${opt}: ${p.type}`);
+  }
+  if ("cardinality" in spec && (spec.cardinality ?? "many") === "many") {
+    parts.push("limit?: number", "cursor?: string");
+  }
+  return `{ ${parts.join(", ")} }`;
+}
+function opPkTemplate(op) {
+  if (op.indexName) {
+    return op.keyCondition[`${op.indexName}PK`] ?? op.keyCondition["PK"] ?? op.keyCondition["pk"] ?? "";
+  }
+  return op.keyCondition["PK"] ?? op.keyCondition["pk"] ?? "";
+}
+function rootEntityName(spec, manifest) {
+  const root = spec.operations[0];
+  if (!root) return "";
+  const pk = opPkTemplate(root);
+  for (const [name, entity] of Object.entries(manifest.entities)) {
+    const cand = root.indexName ? gsiByName(entity, root.indexName)?.pkTemplate : entity.key?.pkTemplate;
+    if (cand && pk && cand === pk) return name;
+  }
+  return "";
+}
+function outputShape(spec, entityName) {
+  const many = (spec.cardinality ?? "many") === "many";
+  const base = entityName || "Result";
+  return many ? `Page<${base}>` : base;
+}
+function buildResolution(spec, manifest) {
+  const root = spec.operations[0];
+  if (!root) return { resolve: "", diagram: [] };
+  if (spec.operations.length === 1) {
+    const keyLabelStr = rootKeyLabel(root);
+    const proj = root.projection.length > 0 ? `Projection(${root.projection.slice(0, 4).join(", ")})` : "Projection";
+    const resolve3 = `${keyLabelStr} \u2192 ${root.type} \u2192 ${proj}`;
+    const inParam = Object.keys(spec.params).sort()[0] ?? "key";
+    const outEntity = rootEntityName(spec, manifest) || "Result";
+    const diagram2 = [
+      { label: inParam, edge: "" },
+      { label: keyLabelStr, edge: "" },
+      { label: root.type, edge: "" },
+      { label: outEntity, edge: "" }
+    ];
+    return { resolve: resolve3, diagram: diagram2 };
+  }
+  const entityHops = [];
+  const diagram = [];
+  for (let i = 0; i < spec.operations.length; i++) {
+    const op = spec.operations[i];
+    const entity = opEntityName(op, manifest) || op.tableName;
+    entityHops.push(`${op.type}(${entity}${op.indexName ? ` by ${op.indexName}` : ""})`);
+    const edge = i < spec.operations.length - 1 ? spec.operations[i + 1].type === "BatchGetItem" ? "BatchGet" : op.indexName ?? "PK" : "";
+    diagram.push({ label: entity, edge });
+  }
+  return { resolve: entityHops.join(" \u2192 "), diagram };
+}
+function rootKeyLabel(op) {
+  const pk = opPkTemplate(op);
+  const prefix = op.indexName ? `${op.indexName} PK` : "PK";
+  return `${prefix} = ${pk}`;
+}
+function opEntityName(op, manifest) {
+  const pk = opPkTemplate(op);
+  for (const [name, entity] of Object.entries(manifest.entities)) {
+    const cand = op.indexName ? gsiByName(entity, op.indexName)?.pkTemplate : entity.key?.pkTemplate;
+    if (cand && pk) {
+      if (literalPrefix(cand) === literalPrefix(pk)) return name;
+    }
+  }
+  return "";
+}
+function literalPrefix(template) {
+  const idx = template.indexOf("{");
+  return idx === -1 ? template : template.slice(0, idx);
+}
+function commandSignature(_name, spec) {
+  const verb = spec.type === "PutItem" ? "create" : spec.type === "UpdateItem" ? "update" : "delete";
+  return `${spec.entity}.${verb}()`;
+}
+function buildMaintainedPaths(registry) {
+  const rows = [];
+  const entities = registry.getAll();
+  const byName = /* @__PURE__ */ new Map();
+  for (const [cls, meta] of entities) byName.set(cls.name, meta);
+  for (const name of [...byName.keys()].sort()) {
+    const meta = byName.get(name);
+    for (const rel of meta.relations) {
+      const row = maintainedRowForRelation(name, rel);
+      if (row) rows.push(row);
+    }
+    for (const agg of meta.aggregates) {
+      const row = maintainedRowForAggregate(name, agg);
+      if (row) rows.push(row);
+    }
+  }
+  return rows;
+}
+function maintainedRowForRelation(ownerName, rel) {
+  const pattern = rel.options?.pattern;
+  if (!pattern) return null;
+  const triggers = rel.options?.write?.maintainedOn ?? [];
+  const source = sourceFromTriggers(triggers) || rel.targetFactory().name;
+  const target = `${ownerName}.${rel.propertyName}`;
+  const update = pattern === "counter" ? "ADD +1 / \u22121 on create / remove" : `project ${source} fields into ${ownerName}`;
+  return { source, target, pattern, update };
+}
+function maintainedRowForAggregate(ownerName, agg) {
+  const pattern = agg.options.pattern;
+  if (!pattern) return null;
+  const triggers = agg.options.write?.maintainedOn ?? [];
+  const source = sourceFromTriggers(triggers) || agg.targetFactory().name;
+  const target = `${ownerName}.${agg.propertyName}`;
+  const update = pattern === "counter" ? "ADD +1 / \u22121 on create / remove" : `project ${source} into ${ownerName}`;
+  return { source, target, pattern, update };
+}
+function sourceFromTriggers(triggers) {
+  for (const t of triggers) {
+    const dot = t.indexOf(".");
+    if (dot > 0) return t.slice(0, dot);
+  }
+  return "";
+}
+function buildCdcEntries(registry) {
+  const names = [];
+  for (const [cls, meta] of registry.getAll()) {
+    if (meta.cdcProjected) names.push(cls.name);
+  }
+  return names.sort().map((model) => ({ model }));
+}
+function buildCfnResources(manifest, streamsEnabled) {
+  const rows = [
+    { resource: "AWS::DynamoDB::Table", description: "Physical table" }
+  ];
+  const gsiCols = collectGsiColumns(manifest);
+  if (gsiCols.length > 0) {
+    rows.push({
+      resource: "GlobalSecondaryIndexes",
+      description: `GSI definitions (${gsiCols.join(", ")})`
+    });
+  }
+  rows.push({
+    resource: "StreamSpecification",
+    description: streamsEnabled === void 0 ? AS_CONFIGURED : streamsEnabled ? "NEW_AND_OLD_IMAGES" : "disabled"
+  });
+  const hasTtl = Object.values(manifest.entities).some((e) => e.ttlAttribute);
+  if (hasTtl) {
+    rows.push({
+      resource: "TimeToLiveSpecification",
+      description: "TTL (when a TTL attribute is declared)"
+    });
+  }
+  rows.push(
+    { resource: "PointInTimeRecovery", description: "PITR" },
+    { resource: "Auto Scaling", description: "Optional (PROVISIONED mode)" }
+  );
+  return rows;
+}
+function buildDocModel(manifest, operations, registry = MetadataRegistry, options = {}) {
+  const entityNames = Object.keys(manifest.entities).sort();
+  const table = entityNames.length > 0 ? manifest.entities[entityNames[0]].table : "";
+  const title = options.title ?? `${table} Table Specification`;
+  const cfnFile = options.cfnFile ?? "cloudformation.yaml";
+  const overview = [
+    { item: "Table", value: `\`${table}\`` },
+    {
+      item: "Billing Mode",
+      value: options.billingMode ?? "PAY_PER_REQUEST"
+    },
+    {
+      item: "Streams",
+      value: options.streamsEnabled === void 0 ? AS_CONFIGURED : options.streamsEnabled ? "NEW_AND_OLD_IMAGES" : "Disabled"
+    },
+    {
+      item: "TTL",
+      value: Object.values(manifest.entities).some((e) => e.ttlAttribute) ? "Enabled" : "Disabled"
+    },
+    { item: "PITR", value: AS_CONFIGURED },
+    { item: "Table Class", value: AS_CONFIGURED },
+    { item: "Encryption", value: AS_CONFIGURED },
+    { item: "CloudFormation", value: `\`${cfnFile}\`` }
+  ];
+  const relationEdges = [];
+  for (const name of entityNames) {
+    const entity = manifest.entities[name];
+    for (const propName of Object.keys(entity.relations).sort()) {
+      const rel = entity.relations[propName];
+      relationEdges.push({
+        source: name,
+        target: rel.target,
+        label: rel.type
+      });
+    }
+  }
+  const gsiColumns = collectGsiColumns(manifest);
+  const keySchema = entityNames.map((name) => {
+    const entity = manifest.entities[name];
+    return {
+      model: name,
+      pk: entity.key?.pkTemplate ?? "",
+      sk: entity.key?.skTemplate ?? "",
+      gsis: gsiColumns.map((col) => {
+        const g = gsiByName(entity, col);
+        return { pk: g?.pkTemplate ?? "", sk: g?.skTemplate ?? "" };
+      })
+    };
+  });
+  const propertyOrder = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of entityNames) {
+    const entity = manifest.entities[name];
+    for (const field of Object.keys(entity.fields).sort()) {
+      if (!seen.has(field)) {
+        seen.add(field);
+        propertyOrder.push(field);
+      }
+    }
+  }
+  const propertyMatrix = propertyOrder.map((property) => {
+    let type = "";
+    let description = "";
+    for (const name of entityNames) {
+      const entity = manifest.entities[name];
+      const field = entity.fields[property];
+      if (!field) continue;
+      if (!type) type = fieldTypeLabel(entity, property);
+      if (!description && field.description) description = field.description;
+    }
+    const cells = entityNames.map(
+      (name) => propertyRole(manifest.entities[name], property)
+    );
+    return { property, type, description, cells };
+  });
+  const propertyMatrixHasDescriptions = propertyMatrix.some(
+    (row) => row.description !== ""
+  );
+  const maintainedPaths = buildMaintainedPaths(registry);
+  const entities = entityNames.map((name) => {
+    const entity = manifest.entities[name];
+    const relations = Object.keys(entity.relations).sort().map((propName) => {
+      const rel = entity.relations[propName];
+      return { property: propName, target: rel.target, type: rel.type };
+    });
+    const maintained = maintainedPaths.filter((row) => row.target.startsWith(`${name}.`)).map((row) => ({
+      field: row.target.slice(name.length + 1),
+      pattern: row.pattern
+    }));
+    return {
+      name,
+      description: entity.description ?? "",
+      pk: keyLabel("PK", entity.key?.pkTemplate ?? null),
+      sk: keyLabel("SK", entity.key?.skTemplate ?? null),
+      gsis: entity.gsis.map((g) => ({
+        indexName: g.indexName,
+        pk: g.pkTemplate,
+        sk: g.skTemplate ?? "",
+        unique: g.unique,
+        description: g.description ?? ""
+      })),
+      relations,
+      maintained,
+      fields: Object.keys(entity.fields).sort().map((field) => ({
+        field,
+        type: fieldTypeLabel(entity, field),
+        description: entity.fields[field].description ?? ""
+      })),
+      hasFieldDescriptions: Object.values(entity.fields).some(
+        (f) => (f.description ?? "") !== ""
+      )
+    };
+  });
+  const accessPatterns = [];
+  const accessMatrix = [];
+  for (const name of Object.keys(operations.queries).sort()) {
+    const spec = operations.queries[name];
+    const entityName = rootEntityName(spec, manifest);
+    const { resolve: resolve3, diagram } = buildResolution(spec, manifest);
+    const relation = isRelation(spec);
+    const batchGet = usesBatchGet(spec);
+    const cursor = usesCursor(spec);
+    const index = rootIndex(spec);
+    const signature = `${entityName || "Query"}.${name}(${Object.keys(spec.params).sort().join(", ")})`;
+    accessPatterns.push({
+      signature,
+      description: spec.description ?? "",
+      index,
+      input: inputShape(spec),
+      output: outputShape(spec, entityName),
+      resolve: resolve3,
+      relation,
+      batchGet,
+      cursor,
+      diagram
+    });
+    accessMatrix.push({ query: signature, index, relation, batchGet, cursor });
+  }
+  const mutationContracts = [];
+  for (const name of Object.keys(operations.commands).sort()) {
+    const spec = operations.commands[name];
+    const verb = spec.type === "PutItem" ? "TransactWrite \u2192 " + spec.entity + " item" : spec.type === "UpdateItem" ? "TransactWrite \u2192 " + spec.entity + " item" : "TransactWrite \u2192 delete " + spec.entity + " item";
+    mutationContracts.push({
+      signature: commandSignature(name, spec),
+      description: spec.description ?? "",
+      input: inputShape(spec),
+      output: spec.entity,
+      resolve: verb
+    });
+  }
+  const cdcEntries = buildCdcEntries(registry);
+  const cfnResources = buildCfnResources(manifest, options.streamsEnabled);
+  return {
+    table,
+    title,
+    overview,
+    entityNames,
+    relationEdges,
+    gsiColumns,
+    keySchema,
+    propertyMatrix,
+    propertyMatrixHasDescriptions,
+    entities,
+    accessPatterns,
+    accessMatrix,
+    mutationContracts,
+    maintainedPaths,
+    cdcEntries,
+    cfnResources,
+    cfnFile
+  };
+}
+
+// src/codegen/docs.ts
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import Handlebars from "handlebars";
+
+// src/codegen/docs-templates.ts
+var PARTIAL_NAMES = [
+  "index",
+  "table-overview",
+  "er-diagram",
+  "key-schema",
+  "property-matrix",
+  "entity",
+  "access-pattern",
+  "maintained",
+  "cdc",
+  "cloudformation"
+];
+var INDEX = `# {{title}}
+
+> Generated by \`graphddb generate docs\`
+
+---
+
+{{> table-overview }}
+
+---
+
+{{> er-diagram }}
+{{> key-schema }}
+
+---
+
+{{> property-matrix }}
+
+---
+
+## Entity Details
+
+{{#each entities}}
+{{> entity this }}
+{{/each}}
+{{#if accessMatrix.length}}---
+
+## Access Patterns
+
+Each query resolves to a physical operation, an index (PK or GSI), and a projection.
+The matrix summarizes; the contracts below give the input/output and execution for each.
+
+| Query | Index | Relation | BatchGet | Cursor |
+|------|------|------|------|------|
+{{#each accessMatrix}}| \`{{query}}\` | {{index}} | {{#if relation}}\u2713{{/if}} | {{#if batchGet}}\u2713{{/if}} | {{#if cursor}}\u2713{{/if}} |
+{{/each}}
+
+{{#each accessPatterns}}
+{{> access-pattern this }}
+{{/each}}
+{{/if}}
+{{#if mutationContracts.length}}---
+
+## Mutation Contracts
+
+{{#each mutationContracts}}
+### \`{{signature}}\`
+{{#if description}}
+
+{{description}}
+{{/if}}
+
+\`\`\`yaml
+Input:  {{input}}
+Output: {{output}}
+Resolve: {{resolve}}
+\`\`\`
+
+{{/each}}
+{{/if}}
+{{> maintained }}
+{{> cdc }}
+---
+
+{{> cloudformation }}
+`;
+var TABLE_OVERVIEW = `## Table Overview
+
+| Item | Value |
+|------|-------|
+{{#each overview}}| {{item}} | {{value}} |
+{{/each}}`;
+var ER_DIAGRAM = `{{#if relationEdges.length}}## Entity Relationship Diagram
+
+\`\`\`mermaid
+graph TD
+{{#each relationEdges}}  {{mermaidId source}} -->|{{label}}| {{mermaidId target}}
+{{/each}}\`\`\`
+
+---
+
+{{/if}}`;
+var KEY_SCHEMA = `## Physical Key Schema
+
+| Model | PK | SK |{{#each gsiColumns}} {{this}} PK | {{this}} SK |{{/each}}
+|------|------|------|{{#each gsiColumns}}------|------|{{/each}}
+{{#each keySchema}}| {{model}} | {{codeOrEmpty pk}} | {{codeOrEmpty sk}} |{{#each gsis}} {{codeOrEmpty pk}} | {{codeOrEmpty sk}} |{{/each}}
+{{/each}}`;
+var PROPERTY_MATRIX = `## Property Matrix
+
+| Property | Type |{{#if propertyMatrixHasDescriptions}} Description |{{/if}}{{#each entityNames}} {{this}} |{{/each}}
+|----------|------|{{#if propertyMatrixHasDescriptions}}-------------|{{/if}}{{#each entityNames}}------|{{/each}}
+{{#each propertyMatrix}}| {{property}} | {{type}} |{{#if ../propertyMatrixHasDescriptions}} {{description}} |{{/if}}{{#each cells}} {{this}} |{{/each}}
+{{/each}}
+
+Legend: **PK** primary partition key \xB7 **SK** primary sort key \xB7 GSI keys \xB7 **\u2713** normal attribute`;
+var ENTITY = `### {{name}}
+{{#if description}}
+
+{{description}}
+{{/if}}
+
+- **Key**: \`{{pk}}\`{{#if sk}} / \`{{sk}}\`{{/if}}
+{{#each gsis}}- **{{indexName}}**: \`PK = {{pk}}\`{{#if sk}} / \`SK = {{sk}}\`{{/if}}{{#if unique}} (unique){{/if}}
+{{/each}}
+{{#if relations.length}}- **Relations**: {{#each relations}}\`{{property}}\` \u2192 {{target}} ({{type}}){{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+{{#if maintained.length}}- **Maintained**: {{#each maintained}}\`{{field}}\` ({{pattern}}){{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+
+| Field | Type |{{#if hasFieldDescriptions}} Description |{{/if}}
+|------|------|{{#if hasFieldDescriptions}}------|{{/if}}
+{{#each fields}}| {{field}} | {{type}} |{{#if ../hasFieldDescriptions}} {{description}} |{{/if}}
+{{/each}}
+`;
+var ACCESS_PATTERN = `### \`{{signature}}\`
+{{#if description}}
+
+{{description}}
+{{/if}}
+
+\`\`\`yaml
+Input:  {{input}}
+Output: {{output}}
+Resolve: {{resolve}}
+\`\`\`
+
+\`\`\`mermaid
+flowchart LR
+  {{#each diagram}}{{mermaidId label}}["{{label}}"]{{#unless @last}} {{#if edge}}-- "{{edge}}" {{/if}}--> {{/unless}}{{/each}}
+\`\`\`
+
+`;
+var MAINTAINED = `{{#if maintainedPaths.length}}---
+
+## Maintained Access Paths
+
+Write-side projections kept in sync automatically, within the source write's transaction
+(or via the CDC stream for \`updateMode: 'stream'\`).
+
+| Source | Target | Pattern | Update |
+|---------|--------|--------|--------|
+{{#each maintainedPaths}}| {{source}} | {{target}} | {{pattern}} | {{update}} |
+{{/each}}
+
+\`\`\`mermaid
+flowchart LR
+{{#each maintainedPaths}}  {{mermaidId source}} -- "{{pattern}}" --> {{mermaidId target}}
+{{/each}}\`\`\`
+
+{{/if}}`;
+var CDC = `{{#if cdcEntries.length}}---
+
+## CDC
+
+\`@cdcProjected\` models expose \`fromChange\` / \`subscribe\` to parse the change stream into
+typed records. Delivery and idempotency are the consumer's responsibility.
+
+{{#each cdcEntries}}
+\`\`\`yaml
+Contract: {{model}}.subscribe
+Input:    ChangeEvent<{{model}}>
+Output:   [{{model}} | null, {{model}} | null]   # [oldRecord, newRecord]
+\`\`\`
+
+\`\`\`mermaid
+flowchart LR
+  Mutate --> Stream["DynamoDB Stream"] --> CE["ChangeEvent"]
+  CE --> FC["{{model}}.fromChange()"] --> Sub["subscribe()"] --> Consumer
+\`\`\`
+
+{{/each}}
+{{/if}}`;
+var CLOUDFORMATION = `## CloudFormation
+
+Generated by \`graphddb generate cloudformation\` (see \`{{cfnFile}}\`).
+
+| Resource | Description |
+|------|------|
+{{#each cfnResources}}| \`{{resource}}\` | {{description}} |
+{{/each}}`;
+var BUNDLED_PARTIALS = {
+  index: INDEX,
+  "table-overview": TABLE_OVERVIEW,
+  "er-diagram": ER_DIAGRAM,
+  "key-schema": KEY_SCHEMA,
+  "property-matrix": PROPERTY_MATRIX,
+  entity: ENTITY,
+  "access-pattern": ACCESS_PATTERN,
+  maintained: MAINTAINED,
+  cdc: CDC,
+  cloudformation: CLOUDFORMATION
+};
+
+// src/codegen/docs.ts
+var DOCS_INDEX_FILE = "index.md";
+function registerBuiltinHelpers(hb) {
+  hb.registerHelper("eq", (a, b) => a === b);
+  hb.registerHelper(
+    "join",
+    (list, sep) => Array.isArray(list) ? list.join(typeof sep === "string" ? sep : ", ") : ""
+  );
+  hb.registerHelper("pascal", (value) => {
+    const s = String(value ?? "");
+    return s.split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("");
+  });
+  hb.registerHelper("mermaidId", (value) => {
+    const s = String(value ?? "");
+    const id = s.replace(/[^A-Za-z0-9_]/g, "_").replace(/_+/g, "_");
+    return /^[0-9]/.test(id) ? `n_${id}` : id || "n";
+  });
+  hb.registerHelper("codeOrEmpty", (value) => {
+    const s = String(value ?? "");
+    return s ? new hb.SafeString(`\`${s}\``) : "";
+  });
+}
+function partialSource(name, templateDir) {
+  if (templateDir) {
+    const candidate = resolve(templateDir, `${name}.hbs`);
+    if (existsSync(candidate)) {
+      return readFileSync(candidate, "utf8");
+    }
+  }
+  return BUNDLED_PARTIALS[name];
+}
+function buildEnvironment(options) {
+  const hb = Handlebars.create();
+  registerBuiltinHelpers(hb);
+  if (options.helpers) {
+    for (const [name, fn] of Object.entries(options.helpers)) {
+      hb.registerHelper(name, fn);
+    }
+  }
+  for (const name of PARTIAL_NAMES) {
+    hb.registerPartial(
+      name,
+      hb.compile(partialSource(name, options.templateDir), { noEscape: true })
+    );
+  }
+  return hb;
+}
+function generateDocs(docModel, options = {}) {
+  const hb = buildEnvironment(options);
+  const index = hb.partials["index"];
+  const template = typeof index === "function" ? index : hb.compile(index, { noEscape: true });
+  let out = template(docModel);
+  out = out.replace(/([^\n])\n(---\n)/g, "$1\n\n$2").replace(/(\n---)\n([^\n])/g, "$1\n\n$2").replace(/([^\n])\n(#{1,6} )/g, "$1\n\n$2").replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "") + "\n";
+  return { [DOCS_INDEX_FILE]: out };
+}
+
 // src/codegen/index.ts
 var OUTPUT_FILES = [
   "manifest.json",
@@ -1498,7 +2270,7 @@ function renderBundle(queries = {}, commands = {}, registry = MetadataRegistry,
 // src/codegen/jsdoc.ts
 async function loadTypescript() {
   try {
-    const mod = await import("./typescript-ZUQEBJRV.js");
+    const mod = await import("typescript");
     return mod.default ?? mod;
   } catch {
     return void 0;
@@ -1727,7 +2499,7 @@ function fail(code, message, exitCode) {
   process.exit(exitCode);
 }
 function toUrl(file) {
-  const abs = isAbsolute(file) ? file : resolve(process.cwd(), file);
+  const abs = isAbsolute(file) ? file : resolve2(process.cwd(), file);
   return pathToFileURL(abs).href;
 }
 var tsxRegistered = false;
@@ -1749,6 +2521,12 @@ async function importModule(file) {
   if (/\.[mc]?ts$/.test(file)) await ensureTsx();
   return await import(toUrl(file));
 }
+async function importModelEntry(entry) {
+  await importModule(entry);
+  if (MetadataRegistry.linter === null) {
+    MetadataRegistry.linter = createDefaultLinter();
+  }
+}
 async function loadDefinitionMap(file, exportName) {
   const mod = await importModule(file);
   const value = mod[exportName];
@@ -1782,7 +2560,7 @@ var handlers = {
     if (!entry) fail("INVALID_ARGS", "Missing required option --entry.", 2);
     if (!out) fail("INVALID_ARGS", "Missing required option --out.", 2);
     try {
-      await importModule(entry);
+      await importModelEntry(entry);
       const queries = await loadDefinitionMap(queriesPath ?? entry, "queries");
       const commands = await loadDefinitionMap(commandsPath ?? entry, "commands");
       const transactions = await loadOptionalMap(
@@ -1797,7 +2575,7 @@ var handlers = {
         contextsPath ?? contractsPath ?? entry,
         "contexts"
       );
-      const abs = (p) => isAbsolute(p) ? p : resolve(process.cwd(), p);
+      const abs = (p) => isAbsolute(p) ? p : resolve2(process.cwd(), p);
       await applyJsDocDescriptions(
         {
           entry: abs(entry),
@@ -1812,19 +2590,19 @@ var handlers = {
         contracts: { contracts, contexts }
       });
       void dataclass;
-      const outDir = isAbsolute(out) ? out : resolve(process.cwd(), out);
+      const outDir = isAbsolute(out) ? out : resolve2(process.cwd(), out);
       mkdirSync(outDir, { recursive: true });
       for (const name of OUTPUT_FILES) {
-        writeFileSync(resolve(outDir, name), files[name], "utf8");
+        writeFileSync(resolve2(outDir, name), files[name], "utf8");
       }
       const emittedFiles = [...OUTPUT_FILES];
       if (cdcProjectedModelNames().length > 0) {
-        const entryAbs = isAbsolute(entry) ? entry : resolve(process.cwd(), entry);
+        const entryAbs = isAbsolute(entry) ? entry : resolve2(process.cwd(), entry);
         let modelsModule = relative(outDir, entryAbs).replace(/\\/g, "/").replace(/\.[mc]?ts$/, "");
         if (!modelsModule.startsWith(".")) modelsModule = `./${modelsModule}`;
         const cdcRegistryFile = "cdc-registry.ts";
         writeFileSync(
-          resolve(outDir, cdcRegistryFile),
+          resolve2(outDir, cdcRegistryFile),
           generateCdcRegistry({ modelsModule }),
           "utf8"
         );
@@ -1978,7 +2756,7 @@ var handlers = {
       tblClass = tableClass;
     }
     try {
-      await importModule(entry);
+      await importModelEntry(entry);
       const manifest = buildManifest();
       const streamMaintenanceDetected = streamMode === "auto" ? detectStreamMaintenance() : false;
       const template = emitCloudformation(manifest, {
@@ -2001,7 +2779,7 @@ var handlers = {
         autoscaleTarget: autoscaleTargetNum
       });
       if (out) {
-        const outFile = isAbsolute(out) ? out : resolve(process.cwd(), out);
+        const outFile = isAbsolute(out) ? out : resolve2(process.cwd(), out);
         mkdirSync(dirname(outFile), { recursive: true });
         writeFileSync(outFile, template, "utf8");
         process.stdout.write(
@@ -2018,6 +2796,131 @@ var handlers = {
       const message = err instanceof Error ? err.message : String(err);
       fail("GENERATION_FAILED", message, 1);
     }
+  },
+  /**
+   * `generate docs` (issue #183).
+   *
+   * Loads the entry model module (side-effecting import registers the entities)
+   * plus the optional query / command definitions, builds the serializable
+   * manifest + operations, then the normalized {@link buildDocModel} view model,
+   * and renders the model-spec Markdown (Mermaid fences) via the Handlebars
+   * generator to a single `index.md` in `--out`. `--template-dir` overrides
+   * bundled partials per-name and `--helpers` registers extra Handlebars helpers.
+   * Mirrors `generatePython`'s tsx-based entry loading and JSON error / exit shape.
+   *
+   * The Table Overview billing / streams are resolved from the CFn-shared flags
+   * (`--billing-mode` / `--stream`, `stream auto` detecting `updateMode:'stream'`
+   * maintenance like the CFn generator); deploy-time-only items with no flag
+   * render "as configured at deployment" in the DocModel.
+   */
+  async generateDocs(options) {
+    const {
+      entry,
+      queries: queriesPath,
+      out,
+      format,
+      split,
+      templateDir,
+      helpers: helpersPath,
+      billingMode,
+      stream
+    } = options;
+    if (!entry) fail("INVALID_ARGS", "Missing required option --entry.", 2);
+    if (!out) fail("INVALID_ARGS", "Missing required option --out.", 2);
+    if (format !== void 0 && format !== "markdown") {
+      fail("INVALID_ARGS", `Invalid --format '${format}'. Use markdown.`, 2);
+    }
+    if (split !== void 0 && split !== "none" && split !== "entity") {
+      fail("INVALID_ARGS", `Invalid --split '${split}'. Use none or entity.`, 2);
+    }
+    const outIsFile = out.toLowerCase().endsWith(".md");
+    if (split === "entity" && outIsFile) {
+      fail(
+        "INVALID_ARGS",
+        `--split entity writes multiple files and needs a directory --out, not a .md file ('${out}').`,
+        2
+      );
+    }
+    if (split === "entity") {
+      fail(
+        "INVALID_ARGS",
+        `--split entity is not yet supported. Use --split none (a single index.md).`,
+        2
+      );
+    }
+    let billing = "PAY_PER_REQUEST";
+    if (billingMode !== void 0) {
+      if (billingMode !== "PAY_PER_REQUEST" && billingMode !== "PROVISIONED") {
+        fail(
+          "INVALID_ARGS",
+          `Invalid --billing-mode '${billingMode}'. Use PAY_PER_REQUEST or PROVISIONED.`,
+          2
+        );
+      }
+      billing = billingMode;
+    }
+    let streamMode = "auto";
+    if (stream !== void 0) {
+      if (stream !== "auto" && stream !== "on" && stream !== "off") {
+        fail("INVALID_ARGS", `Invalid --stream '${stream}'. Use auto, on, or off.`, 2);
+      }
+      streamMode = stream;
+    }
+    try {
+      await importModelEntry(entry);
+      const queries = await loadOptionalMap(queriesPath ?? entry, "queries");
+      const commands = await loadOptionalMap(queriesPath ?? entry, "commands");
+      const manifest = buildManifest();
+      const operations = buildOperations(
+        queries,
+        commands
+      );
+      const streamsEnabled = streamMode === "on" ? true : streamMode === "off" ? false : detectStreamMaintenance();
+      const docModel = buildDocModel(manifest, operations, MetadataRegistry, {
+        billingMode: billing,
+        streamsEnabled
+      });
+      let helpers;
+      if (helpersPath) {
+        const mod = await importModule(helpersPath);
+        const exported = mod.helpers ?? mod.default;
+        if (!exported || typeof exported !== "object") {
+          fail(
+            "INVALID_ARGS",
+            `Module '${helpersPath}' must export a 'helpers' (or default) object mapping helper names to functions.`,
+            2
+          );
+        }
+        helpers = exported;
+      }
+      const files = generateDocs(docModel, {
+        templateDir: templateDir ? isAbsolute(templateDir) ? templateDir : resolve2(process.cwd(), templateDir) : void 0,
+        helpers
+      });
+      const outAbs = isAbsolute(out) ? out : resolve2(process.cwd(), out);
+      const emitted = [];
+      if (outIsFile) {
+        const [contents] = Object.values(files);
+        mkdirSync(dirname(outAbs), { recursive: true });
+        writeFileSync(outAbs, contents, "utf8");
+        emitted.push(out);
+        process.stdout.write(
+          JSON.stringify({ status: "ok", outDir: dirname(out), files: emitted }) + "\n"
+        );
+      } else {
+        mkdirSync(outAbs, { recursive: true });
+        for (const [name, contents] of Object.entries(files)) {
+          writeFileSync(resolve2(outAbs, name), contents, "utf8");
+          emitted.push(name);
+        }
+        process.stdout.write(
+          JSON.stringify({ status: "ok", outDir: out, files: emitted }) + "\n"
+        );
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      fail("GENERATION_FAILED", message, 1);
+    }
   }
 };