feat(codegen): generate README.md and COMMANDS.md for CLI

- Add docs-generator.ts that produces README.md (overview, setup, commands)
  and COMMANDS.md (man-page style reference with synopsis, options, examples)
- Wire into CLI orchestrator so docs are always generated alongside commands
- Update snapshot tests: 15 tests, 10 snapshots covering all generated files

Author: pyramation

graphql/codegen/src/__tests__/codegen/__snapshots__/cli-generator.test.ts.snap

@@ -1,5 +1,365 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
+exports[`cli-generator generates COMMANDS.md (man-page reference) 1`] = `
+"# myapp - Command Reference
+
+> @generated by @constructive-io/graphql-codegen - DO NOT EDIT
+
+---
+
+## context(1)
+
+### NAME
+
+context - manage API endpoint contexts
+
+### SYNOPSIS
+
+    myapp context <command> [options]
+
+### COMMANDS
+
+**create** \`<name>\` \`--endpoint <url>\`
+
+    Create a named context pointing at a GraphQL endpoint.
+    Config stored at ~/.myapp/config/contexts/<name>.json
+
+**list**
+
+    List all configured contexts with auth status.
+
+**use** \`<name>\`
+
+    Set the active context for subsequent commands.
+
+**current**
+
+    Display the currently active context and its endpoint.
+
+**delete** \`<name>\`
+
+    Remove a context and its configuration.
+
+---
+
+## auth(1)
+
+### NAME
+
+auth - manage authentication tokens
+
+### SYNOPSIS
+
+    myapp auth <command> [options]
+
+### COMMANDS
+
+**set-token** \`<token>\` \`[--context <name>]\`
+
+    Store a bearer token for the current (or specified) context.
+    Credentials stored at ~/.myapp/config/credentials.json (mode 0600).
+
+**status**
+
+    Show authentication status for all contexts.
+
+**logout** \`[--context <name>]\`
+
+    Remove stored credentials for the current (or specified) context.
+
+---
+
+## car(1)
+
+### NAME
+
+car - manage Car records
+
+### SYNOPSIS
+
+    car <command> [options]
+
+### COMMANDS
+
+**list**
+
+    car list
+
+List all car records. Returns JSON array.
+
+Selected fields: id, make, model, year, isElectric, createdAt
+
+**get**
+
+    car get --id <value>
+
+Fetch a single car by its id.
+
+**create**
+
+    car create --make <value> --model <value> --year <value> --isElectric <value>
+
+Create a new car. All fields are required.
+
+  Options:
+    --make                 String (required)
+    --model                String (required)
+    --year                 Int (required)
+    --isElectric           Boolean (required)
+
+**update**
+
+    car update --id <value> [--make <value>] [--model <value>] [--year <value>] [--isElectric <value>]
+
+Update an existing car. Only provided fields are changed.
+
+  Options:
+    --id                   UUID (required)
+    --make                 String
+    --model                String
+    --year                 Int
+    --isElectric           Boolean
+
+**delete**
+
+    car delete --id <value>
+
+Delete a car by its id.
+
+---
+
+## driver(1)
+
+### NAME
+
+driver - manage Driver records
+
+### SYNOPSIS
+
+    driver <command> [options]
+
+### COMMANDS
+
+**list**
+
+    driver list
+
+List all driver records. Returns JSON array.
+
+Selected fields: id, name, licenseNumber
+
+**get**
+
+    driver get --id <value>
+
+Fetch a single driver by its id.
+
+**create**
+
+    driver create --name <value> --licenseNumber <value>
+
+Create a new driver. All fields are required.
+
+  Options:
+    --name                 String (required)
+    --licenseNumber        String (required)
+
+**update**
+
+    driver update --id <value> [--name <value>] [--licenseNumber <value>]
+
+Update an existing driver. Only provided fields are changed.
+
+  Options:
+    --id                   UUID (required)
+    --name                 String
+    --licenseNumber        String
+
+**delete**
+
+    driver delete --id <value>
+
+Delete a driver by its id.
+
+---
+
+## current-user(1)
+
+### NAME
+
+current-user - Get the currently authenticated user
+
+### SYNOPSIS
+
+    current-user
+
+### DESCRIPTION
+
+Get the currently authenticated user
+
+---
+
+## login(1)
+
+### NAME
+
+login - Authenticate a user
+
+### SYNOPSIS
+
+    login --email <value> --password <value>
+
+### DESCRIPTION
+
+Authenticate a user
+
+### OPTIONS
+
+**--email** String (required)
+
+**--password** String (required)
+
+---
+"
+`;
+
+exports[`cli-generator generates README.md 1`] = `
+"# myapp CLI
+
+> Auto-generated CLI commands from GraphQL schema
+> @generated by @constructive-io/graphql-codegen - DO NOT EDIT
+
+## Setup
+
+\`\`\`bash
+# Create a context pointing at your GraphQL endpoint
+myapp context create production --endpoint https://api.example.com/graphql
+
+# Set the active context
+myapp context use production
+
+# Authenticate
+myapp auth set-token <your-token>
+\`\`\`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`context\` | Manage API contexts (endpoints) |
+| \`auth\` | Manage authentication tokens |
+| \`car\` | car CRUD operations |
+| \`driver\` | driver CRUD operations |
+| \`current-user\` | Get the currently authenticated user |
+| \`login\` | Authenticate a user |
+
+## Infrastructure Commands
+
+### \`context\`
+
+Manage named API contexts (kubectl-style).
+
+| Subcommand | Description |
+|------------|-------------|
+| \`create <name> --endpoint <url>\` | Create a new context |
+| \`list\` | List all contexts |
+| \`use <name>\` | Set the active context |
+| \`current\` | Show current context |
+| \`delete <name>\` | Delete a context |
+
+Configuration is stored at \`~/.myapp/config/\`.
+
+### \`auth\`
+
+Manage authentication tokens per context.
+
+| Subcommand | Description |
+|------------|-------------|
+| \`set-token <token>\` | Store bearer token for current context |
+| \`status\` | Show auth status across all contexts |
+| \`logout\` | Remove credentials for current context |
+
+## Table Commands
+
+### \`car\`
+
+CRUD operations for Car records.
+
+| Subcommand | Description |
+|------------|-------------|
+| \`list\` | List all car records |
+| \`get\` | Get a car by id |
+| \`create\` | Create a new car |
+| \`update\` | Update an existing car |
+| \`delete\` | Delete a car |
+
+**Fields:**
+
+| Field | Type |
+|-------|------|
+| \`id\` | UUID |
+| \`make\` | String |
+| \`model\` | String |
+| \`year\` | Int |
+| \`isElectric\` | Boolean |
+| \`createdAt\` | Datetime |
+
+**Create fields:** \`make\`, \`model\`, \`year\`, \`isElectric\`
+
+### \`driver\`
+
+CRUD operations for Driver records.
+
+| Subcommand | Description |
+|------------|-------------|
+| \`list\` | List all driver records |
+| \`get\` | Get a driver by id |
+| \`create\` | Create a new driver |
+| \`update\` | Update an existing driver |
+| \`delete\` | Delete a driver |
+
+**Fields:**
+
+| Field | Type |
+|-------|------|
+| \`id\` | UUID |
+| \`name\` | String |
+| \`licenseNumber\` | String |
+
+**Create fields:** \`name\`, \`licenseNumber\`
+
+## Custom Operations
+
+### \`current-user\`
+
+Get the currently authenticated user
+
+- **Type:** query
+- **Arguments:** none
+
+### \`login\`
+
+Authenticate a user
+
+- **Type:** mutation
+- **Arguments:**
+
+  | Argument | Type |
+  |----------|------|
+  | \`email\` | String (required) |
+  | \`password\` | String (required) |
+
+## Output
+
+All commands output JSON to stdout. Pipe to \`jq\` for formatting:
+
+\`\`\`bash
+myapp car list | jq '.[]'
+myapp car get --id <uuid> | jq '.'
+\`\`\`
+"
+`;
+
 exports[`cli-generator generates commands.ts (command map) 1`] = `
 "/**
  * CLI command map and entry point