@type-crafter/mcp 0.3.0 → 0.5.0

package/dist/index.js

@@ -6,7 +6,35 @@ import path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { z } from 'zod';
 const execAsync = promisify(exec);
+// Zod schemas for all tools
+const generateTypesSchema = z.object({
+    language: z
+        .enum(['typescript', 'typescript-with-decoders'])
+        .describe('Target language for type generation'),
+    specFilePath: z.string().describe('Path to the YAML specification file'),
+    outputDirectory: z.string().describe('Directory where generated types will be written'),
+    typesWriterMode: z
+        .enum(['SingleFile', 'Files'])
+        .optional()
+        .describe('Writer mode for types: SingleFile or Files'),
+    groupedTypesWriterMode: z
+        .enum(['FolderWithFiles', 'SingleFile'])
+        .optional()
+        .describe('Writer mode for grouped types: FolderWithFiles or SingleFile'),
+});
+const validateSpecSchema = z.object({
+    specFilePath: z.string().describe('Path to the YAML specification file to validate'),
+});
+const listLanguagesSchema = z.object({});
+const getSpecInfoSchema = z.object({
+    specFilePath: z.string().describe('Path to the YAML specification file'),
+});
+const getSpecRulesSchema = z.object({});
+const checkSpecSchema = z.object({
+    specFilePath: z.string().describe('Path to the YAML specification file to check for common mistakes'),
+});
 // Type guards
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -67,74 +95,10 @@ const server = new McpServer({
         tools: {},
     },
 });
-// Schema definitions for all tools
-const generateTypesSchema = {
-    type: 'object',
-    properties: {
-        language: {
-            type: 'string',
-            description: 'Target language for type generation',
-            enum: ['typescript', 'typescript-with-decoders'],
-        },
-        specFilePath: {
-            type: 'string',
-            description: 'Path to the YAML specification file',
-        },
-        outputDirectory: {
-            type: 'string',
-            description: 'Directory where generated types will be written',
-        },
-        typesWriterMode: {
-            type: 'string',
-            description: 'Writer mode for types: SingleFile or Files',
-            enum: ['SingleFile', 'Files'],
-        },
-        groupedTypesWriterMode: {
-            type: 'string',
-            description: 'Writer mode for grouped types: FolderWithFiles or SingleFile',
-            enum: ['FolderWithFiles', 'SingleFile'],
-        },
-    },
-    required: ['language', 'specFilePath', 'outputDirectory'],
-    additionalProperties: false,
-};
-const validateSpecSchema = {
-    type: 'object',
-    properties: {
-        specFilePath: {
-            type: 'string',
-            description: 'Path to the YAML specification file to validate',
-        },
-    },
-    required: ['specFilePath'],
-    additionalProperties: false,
-};
-const listLanguagesSchema = {
-    type: 'object',
-    properties: {},
-    additionalProperties: false,
-};
-const getSpecInfoSchema = {
-    type: 'object',
-    properties: {
-        specFilePath: {
-            type: 'string',
-            description: 'Path to the YAML specification file',
-        },
-    },
-    required: ['specFilePath'],
-    additionalProperties: false,
-};
-const getSpecRulesSchema = {
-    type: 'object',
-    properties: {},
-    additionalProperties: false,
-};
 // Register generate-types tool
 server.registerTool('generate-types', {
     description: 'Generate type definitions from a YAML specification file. Supports TypeScript and TypeScript with decoders. ' +
         'The YAML spec should follow the Type Crafter format with info, types, and/or groupedTypes sections.',
-    // @ts-expect-error - MCP SDK schema type mismatch
     inputSchema: generateTypesSchema,
 }, async (args) => {
     if (!isGenerateTypesArgs(args)) {
@@ -221,7 +185,6 @@ server.registerTool('generate-types', {
 server.registerTool('validate-spec', {
     description: 'Validate a YAML specification file without generating types. ' +
         'Checks if the spec file is valid and can be processed by Type Crafter.',
-    // @ts-expect-error - MCP SDK schema type mismatch
     inputSchema: validateSpecSchema,
 }, async (args) => {
     if (!isSpecFilePathArgs(args)) {
@@ -283,7 +246,6 @@ server.registerTool('validate-spec', {
 // Register list-languages tool
 server.registerTool('list-languages', {
     description: 'List all supported target languages for type generation',
-    // @ts-expect-error - MCP SDK schema type mismatch
     inputSchema: listLanguagesSchema,
 }, async () => {
     return {
@@ -299,7 +261,6 @@ server.registerTool('list-languages', {
 server.registerTool('get-spec-info', {
     description: 'Get information about a YAML specification file including version, title, ' +
         'and counts of types and grouped types defined in the spec.',
-    // @ts-expect-error - MCP SDK schema type mismatch
     inputSchema: getSpecInfoSchema,
 }, async (args) => {
     if (!isSpecFilePathArgs(args)) {
@@ -391,7 +352,6 @@ server.registerTool('get-spec-rules', {
     description: 'Get comprehensive rules and guidelines for writing Type Crafter YAML specification files. ' +
         'This provides LLMs with detailed information about the YAML spec format, type mappings, nullable types, ' +
         'references, composition, best practices, and common patterns. Use this before creating or modifying spec files.',
-    // @ts-expect-error - MCP SDK schema type mismatch
     inputSchema: getSpecRulesSchema,
 }, async () => {
     try {
@@ -430,6 +390,187 @@ server.registerTool('get-spec-rules', {
         };
     }
 });
+// Register check-spec tool
+server.registerTool('check-spec', {
+    description: 'Check a YAML specification file for common mistakes and provide helpful feedback. ' +
+        'This tool detects issues like using nullable/optional properties, incorrect array definitions, ' +
+        'wrong file paths, and other common errors. Use this before generating types to catch mistakes early.',
+    inputSchema: checkSpecSchema,
+}, async (args) => {
+    if (!isSpecFilePathArgs(args)) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'Error: Invalid arguments provided',
+                },
+            ],
+            isError: true,
+        };
+    }
+    const { specFilePath } = args;
+    // Resolve path
+    const resolvedSpecPath = path.resolve(specFilePath);
+    // Check if spec file exists
+    try {
+        await fs.access(resolvedSpecPath);
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: Specification file not found at ${resolvedSpecPath}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Read the spec file
+    let specContent;
+    try {
+        specContent = await fs.readFile(resolvedSpecPath, 'utf-8');
+    }
+    catch (error) {
+        if (!isExecError(error)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error: Unknown error occurred while reading spec file',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error reading spec file: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const issues = [];
+    const warnings = [];
+    // Check for common mistakes
+    const lines = specContent.split('\n');
+    lines.forEach((line, index) => {
+        const lineNum = index + 1;
+        // Check for 'nullable: true'
+        if (line.match(/nullable\s*:\s*true/i)) {
+            issues.push(`Line ${lineNum}: Found 'nullable: true' - This property does NOT exist in Type Crafter. ` +
+                `Use the 'required' array to control nullability instead.`);
+        }
+        // Check for 'optional: true'
+        if (line.match(/optional\s*:\s*true/i)) {
+            issues.push(`Line ${lineNum}: Found 'optional: true' - This property does NOT exist in Type Crafter. ` +
+                `Use the 'required' array to control optionality instead.`);
+        }
+        // Check for property names with '?'
+        if (line.match(/^\s+[\w]+\?\s*:/)) {
+            issues.push(`Line ${lineNum}: Found property name with '?' suffix - This syntax is NOT supported. ` +
+                `Use the 'required' array instead.`);
+        }
+        // Check for type: [string, null] pattern
+        if (line.match(/type\s*:\s*\[.*,\s*null\]/)) {
+            issues.push(`Line ${lineNum}: Found 'type: [type, null]' pattern - This is NOT supported. ` +
+                `Use the 'required' array to control nullability instead.`);
+        }
+        // Check for top-level array types (heuristic)
+        if (line.match(/^\w+:\s*$/) && lines[index + 1]?.match(/^\s+type\s*:\s*array/)) {
+            warnings.push(`Line ${lineNum}: Possible top-level array type - Arrays cannot be top-level types. ` +
+                `They must be properties within objects. Verify this is inside an object's properties.`);
+        }
+        // Check for '../' in $ref paths
+        if (line.match(/\$ref\s*:\s*['"].*\.\.\//)) {
+            issues.push(`Line ${lineNum}: Found relative path with '../' in $ref - Paths should be from project root, ` +
+                `not relative to the current file. Use './path/from/root/file.yaml#/Type' format.`);
+        }
+        // Check for missing './' prefix in external $ref
+        if (line.match(/\$ref\s*:\s*['"][^#'][^/]/)) {
+            const match = line.match(/\$ref\s*:\s*['"]([^'"]+)['"]/);
+            if (match && match[1] && !match[1].startsWith('#') && !match[1].startsWith('./')) {
+                warnings.push(`Line ${lineNum}: External $ref path should start with './' - ` +
+                    `Use './path/from/root/file.yaml#/Type' format.`);
+            }
+        }
+    });
+    // Try to parse YAML and check for structural issues
+    try {
+        const specData = parseYaml(specContent);
+        if (!isRecord(specData)) {
+            issues.push('Spec file root is not an object. Expected YAML object at root level.');
+        }
+        else {
+            // Check for missing info section
+            if (!isRecord(specData.info)) {
+                issues.push("Missing 'info' section - Every spec file must have an 'info' section with 'version' and 'title'.");
+            }
+            else if (!isSpecInfo(specData.info)) {
+                if (typeof specData.info.version !== 'string') {
+                    issues.push("Missing 'info.version' - Must be a string in semver format (e.g., '1.0.0').");
+                }
+                if (typeof specData.info.title !== 'string') {
+                    issues.push("Missing 'info.title' - Must be a string describing the spec.");
+                }
+            }
+            // Check if at least one of types or groupedTypes exists
+            const hasTypes = isRecord(specData.types);
+            const hasGroupedTypes = isRecord(specData.groupedTypes);
+            if (!hasTypes && !hasGroupedTypes) {
+                issues.push("Missing 'types' or 'groupedTypes' section - At least one must be defined.");
+            }
+        }
+    }
+    catch (error) {
+        if (isExecError(error)) {
+            issues.push(`YAML parsing error: ${error.message}`);
+        }
+        else {
+            issues.push('YAML parsing error: Unable to parse spec file.');
+        }
+    }
+    // Generate response
+    if (issues.length === 0 && warnings.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: '✅ No common mistakes detected!\n\nThe spec file looks good. You can proceed with validation using validate-spec or generation using generate-types.',
+                },
+            ],
+        };
+    }
+    let response = '';
+    if (issues.length > 0) {
+        response += '❌ Issues Found:\n\n';
+        issues.forEach((issue, idx) => {
+            response += `${idx + 1}. ${issue}\n\n`;
+        });
+    }
+    if (warnings.length > 0) {
+        if (issues.length > 0)
+            response += '\n';
+        response += '⚠️  Warnings:\n\n';
+        warnings.forEach((warning, idx) => {
+            response += `${idx + 1}. ${warning}\n\n`;
+        });
+    }
+    response +=
+        '\n📖 For detailed rules and examples, use the get-spec-rules tool to see complete documentation.';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: response,
+            },
+        ],
+        isError: issues.length > 0,
+    };
+});
 // Start the server
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@type-crafter/mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "MCP server for Type Crafter - generate types from YAML specifications",
   "type": "module",
   "main": "./dist/index.js",

package/src/GUIDE.md

@@ -42,7 +42,7 @@ types:                          export type User = {
 
 **When to use:** ALWAYS use this FIRST before creating or modifying YAML specs
 
-**What it does:** Returns comprehensive rules for writing Type Crafter YAML specs
+**What it does:** Returns comprehensive rules for writing Type Crafter YAML specs, including common mistakes section, multi-file spec patterns, and detailed examples
 
 **Workflow:**
 
@@ -50,27 +50,75 @@ types:                          export type User = {
 User asks: "Create types for my API"
      ↓
 1. Call get-spec-rules to learn the format
-2. Read the returned rules (nullable types, arrays, paths, etc.)
+2. Read the returned rules (especially common mistakes, nullable types, arrays, paths)
 3. Now you know how to write valid YAML specs
 ```
 
-### 2. `validate-spec` ✅
+**Important:** The rules include a "Common Mistakes" section at the top that shows what NOT to do (like using `nullable: true`, `optional: true`, or `?` suffixes).
 
-**When to use:** After creating or modifying a YAML spec
+### 2. `check-spec` 🔍
 
-**What it does:** Validates the spec structure without generating types
+**When to use:** IMMEDIATELY after creating or modifying a YAML spec, BEFORE validation or generation
+
+**What it does:** Scans the spec file for common mistakes and provides specific feedback with line numbers
+
+**Detects:**
+
+- Invalid properties like `nullable: true` or `optional: true`
+- Property names with `?` suffix
+- Incorrect type arrays like `type: [string, null]`
+- Top-level array types (which are invalid)
+- Wrong file paths (using `../` or missing `./` prefix)
+- Missing `info` section
+- Structural issues
 
 **Workflow:**
 
 ```
-You created: my-types.yaml
+You created/modified: my-types.yaml
+     ↓
+1. Call check-spec with path to my-types.yaml
+2. Review issues and warnings with specific line numbers
+3. Fix all issues before proceeding
+4. Run check-spec again to verify fixes
+```
+
+**Example Output:**
+
+```
+❌ Issues Found:
+
+1. Line 15: Found 'nullable: true' - This property does NOT exist in Type Crafter.
+   Use the 'required' array to control nullability instead.
+
+2. Line 42: Found relative path with '../' in $ref - Paths should be from project root.
+   Use './path/from/root/file.yaml#/Type' format.
+
+⚠️  Warnings:
+
+1. Line 28: Possible top-level array type - Arrays cannot be top-level types.
+   They must be properties within objects.
+```
+
+### 3. `validate-spec` ✅
+
+**When to use:** After check-spec passes, to do full structural validation
+
+**What it does:** Validates the spec structure and reports counts of types
+
+**Workflow:**
+
+```
+check-spec passed
      ↓
 1. Call validate-spec with path to my-types.yaml
-2. Check if valid or see error messages
-3. Fix errors if needed and validate again
+2. Get confirmation with type counts
+3. Proceed to generation
 ```
 
-### 3. `generate-types` 🔨
+**Note:** Use `check-spec` first to catch common mistakes, then `validate-spec` for final structural validation.
+
+### 4. `generate-types` 🔨
 
 **When to use:** After spec is validated and user wants TypeScript output
 
@@ -94,7 +142,7 @@ Spec is valid
 3. User can now import and use them in TypeScript
 ```
 
-### 4. `get-spec-info` 📊
+### 5. `get-spec-info` 📊
 
 **When to use:** To understand what's in an existing spec file
 
@@ -110,7 +158,7 @@ User asks: "What types are in my spec?"
 3. Understand the structure before modifying
 ```
 
-### 5. `list-languages` 📝
+### 6. `list-languages` 📝
 
 **When to use:** User asks what output formats are supported
 
@@ -121,6 +169,35 @@ User asks: "What types are in my spec?"
 - `typescript` - TypeScript type definitions
 - `typescript-with-decoders` - TypeScript + runtime decoders
 
+## Quick Decision Tree
+
+**What tool should I use?**
+
+```
+User asks to create/modify spec file?
+  → get-spec-rules FIRST (learn the format)
+  → Create/modify the file
+  → check-spec (catch common mistakes)
+  → validate-spec (structural validation)
+  → generate-types (create TypeScript)
+
+User asks "is my spec valid?"
+  → check-spec (find specific issues)
+  → validate-spec (confirm structure)
+
+User asks "what types are in this spec?"
+  → get-spec-info
+
+User asks "what languages are supported?"
+  → list-languages
+
+User wants to generate types?
+  → Ensure spec is valid first (check-spec + validate-spec)
+  → generate-types
+```
+
+**IMPORTANT: Always use check-spec IMMEDIATELY after creating or modifying a spec file. It will catch common mistakes like `nullable: true`, `optional: true`, wrong file paths, and more.**
+
 ## Complete Workflows
 
 ### Workflow 1: Creating Types from Scratch
@@ -130,7 +207,8 @@ User: "I need types for my e-commerce cart API"
 
 Step 1: Learn the rules
 → Call: get-spec-rules
-→ Read and understand: nullable types, arrays, structure
+→ Read and understand: common mistakes, nullable types, arrays, structure
+→ Pay special attention to the "Common Mistakes" section
 
 Step 2: Gather requirements
 → Ask user: What fields does the cart have?
@@ -140,16 +218,22 @@ Step 3: Create YAML spec
 → Create spec file following the rules
 → Remember: Properties not in 'required' → Type | null
 → Remember: Arrays must be properties, not top-level
+→ Remember: NO nullable/optional properties, use 'required' array
+
+Step 4: Check for common mistakes
+→ Call: check-spec with the spec path
+→ Review any issues or warnings with line numbers
+→ Fix all issues before proceeding
 
-Step 4: Validate
+Step 5: Validate structure
 → Call: validate-spec with the spec path
-→ Fix any errors
+→ Confirm type counts are correct
 
-Step 5: Generate
+Step 6: Generate
 → Call: generate-types with language and paths
 → Types are now available in output directory
 
-Step 6: Confirm
+Step 7: Confirm
 → Tell user where types were generated
 → Optionally show a snippet of generated types
 ```
@@ -161,6 +245,7 @@ User: "Add a 'description' field to the Product type"
 
 Step 1: Understand current spec
 → Call: get-spec-info to see what types exist
+→ Identify where Product type is defined
 → Optionally: get-spec-rules to refresh on rules
 
 Step 2: Read the spec file
@@ -169,11 +254,16 @@ Step 2: Read the spec file
 Step 3: Modify the spec
 → Add the new field
 → Decide if it's required or optional (Type | null)
+→ Use 'required' array ONLY, no nullable/optional properties
 
-Step 4: Validate
+Step 4: Check for mistakes
+→ Call: check-spec with the modified spec path
+→ Fix any issues found
+
+Step 5: Validate structure
 → Call: validate-spec
 
-Step 5: Regenerate
+Step 6: Regenerate
 → Call: generate-types to update TypeScript files
 ```
 
@@ -182,14 +272,18 @@ Step 5: Regenerate
 ```
 User: "Can you check if my spec is valid?"
 
-Step 1: Validate
+Step 1: Check for common mistakes
+→ Call: check-spec with their spec path
+→ Report any issues with line numbers
+
+Step 2: Validate structure (if no issues)
 → Call: validate-spec with their spec path
 
-Step 2: Report results
+Step 3: Report results
 → If valid: Confirm and show summary
-→ If invalid: Explain errors and suggest fixes
+→ If issues: Explain errors and suggest fixes
 
-Step 3: Optionally generate
+Step 4: Optionally generate
 → Ask if they want to generate types now
 → Call: generate-types if yes
 ```

package/src/SPEC_RULES.md

@@ -6,6 +6,8 @@ Complete guide for writing Type Crafter YAML specifications and understanding Ty
 
 ## Table of Contents
 
+- [🚨 Common Mistakes (Read This First)](#-common-mistakes-read-this-first)
+- [Multi-File Specifications](#multi-file-specifications)
 - [Root Structure](#root-structure)
 - [Data Types & Type Mapping](#data-types--type-mapping)
 - [Constraints & Limitations](#constraints--limitations)
@@ -20,6 +22,359 @@ Complete guide for writing Type Crafter YAML specifications and understanding Ty
 
 ---
 
+## 🚨 Common Mistakes (Read This First)
+
+### ❌ NEVER Do These
+
+```yaml
+# ❌ WRONG: Adding 'nullable: true' property
+User:
+  type: object
+  properties:
+    name:
+      type: string
+      nullable: true  # ❌ INVALID! This property does NOT exist
+
+# ❌ WRONG: Using 'optional: true' property
+User:
+  type: object
+  properties:
+    name:
+      type: string
+      optional: true  # ❌ INVALID! This property does NOT exist
+
+# ❌ WRONG: Using '?' suffix for optional
+User:
+  type: object
+  properties:
+    name?:  # ❌ INVALID! Don't use ? suffix
+      type: string
+
+# ❌ WRONG: Creating top-level array types
+Tags:
+  type: array  # ❌ INVALID! Arrays cannot be top-level types
+  items:
+    type: string
+
+# ❌ WRONG: Using relative paths from current file
+# File: src/api/users.yaml
+User:
+  type: object
+  properties:
+    profile:
+      $ref: './profile.yaml#/Profile'  # ❌ WRONG! Not relative to current file
+```
+
+### ✅ CORRECT Ways
+
+```yaml
+# ✅ CORRECT: Use 'required' array to control nullable
+User:
+  type: object
+  required:
+    - id      # id is required (NOT nullable)
+    # name is NOT in required, so it's nullable
+  properties:
+    id:
+      type: string      # Generates: string
+    name:
+      type: string      # Generates: string | null (because not in required)
+
+# ✅ CORRECT: Arrays must be properties within objects
+Post:
+  type: object
+  properties:
+    tags:
+      type: array
+      items:
+        type: string
+
+# ✅ CORRECT: Use paths from project root
+# File: src/api/users.yaml (running type-crafter from project root)
+User:
+  type: object
+  properties:
+    profile:
+      $ref: './src/api/profile.yaml#/Profile'  # ✅ From project root
+```
+
+### 🔑 Key Rules to Remember
+
+1. **Nullable is controlled by `required` array ONLY**
+   - In `required` → generates `Type`
+   - NOT in `required` → generates `Type | null`
+   - No properties like `nullable`, `optional`, `?` exist
+
+2. **Arrays cannot be top-level types**
+   - Arrays MUST be properties within objects
+   - Use `type: array` with `items` specification
+
+3. **File paths are from project root**
+   - NOT relative to current YAML file
+   - Always use `./path/from/root/file.yaml#/Type`
+
+4. **Every spec file needs `info` section**
+   - Even sub-files need `info: { version, title }`
+   - Top-level file and all referenced files must have `info`
+
+---
+
+## Multi-File Specifications
+
+### File Organization Patterns
+
+#### Pattern 1: Single Top-Level File
+
+**Best for:** Small to medium projects
+
+```
+project/
+├── types.yaml          # Single file with all types
+└── src/
+    └── index.ts
+```
+
+**types.yaml:**
+```yaml
+info:
+  version: '1.0.0'
+  title: 'Project Types'
+
+types:
+  User:
+    type: object
+    properties:
+      id: { type: string }
+
+  Post:
+    type: object
+    properties:
+      author: { $ref: '#/types/User' }
+```
+
+#### Pattern 2: Multiple Files with Main Entry Point
+
+**Best for:** Large projects with logical domain separation
+
+```
+project/
+├── types/
+│   ├── index.yaml      # Main entry point (top-level file)
+│   ├── user.yaml       # User-related types (sub-file)
+│   ├── post.yaml       # Post-related types (sub-file)
+│   └── comment.yaml    # Comment-related types (sub-file)
+└── src/
+    └── index.ts
+```
+
+**types/index.yaml (Top-level file):**
+```yaml
+info:
+  version: '1.0.0'
+  title: 'Main API Types'
+
+# Import types from other files
+types:
+  # Reference to external file (from project root)
+  User:
+    $ref: './types/user.yaml#/User'
+
+  Post:
+    $ref: './types/post.yaml#/Post'
+
+  Comment:
+    $ref: './types/comment.yaml#/Comment'
+```
+
+**types/user.yaml (Sub-file):**
+```yaml
+info:
+  version: '1.0.0'
+  title: 'User Types'
+
+types:
+  User:
+    type: object
+    required:
+      - id
+      - email
+    properties:
+      id:
+        type: string
+      email:
+        type: string
+      name:
+        type: string  # nullable (not in required)
+```
+
+**types/post.yaml (Sub-file):**
+```yaml
+info:
+  version: '1.0.0'
+  title: 'Post Types'
+
+types:
+  Post:
+    type: object
+    required:
+      - id
+      - title
+      - author
+    properties:
+      id:
+        type: string
+      title:
+        type: string
+      author:
+        # Reference to user.yaml from project root
+        $ref: './types/user.yaml#/User'
+```
+
+#### Pattern 3: Grouped Types with External References
+
+**Best for:** Complex domains with many related types
+
+```
+project/
+├── specs/
+│   ├── api.yaml        # Main entry point
+│   ├── auth/
+│   │   └── types.yaml  # Auth domain types
+│   └── shop/
+│       ├── cart.yaml   # Shopping cart types
+│       └── product.yaml # Product types
+└── src/
+```
+
+**specs/api.yaml (Top-level file):**
+```yaml
+info:
+  version: '1.0.0'
+  title: 'API Specification'
+
+groupedTypes:
+  # Import entire groups from external files
+  Auth:
+    $ref: './specs/auth/types.yaml#/AuthTypes'
+
+  Shop:
+    Cart:
+      $ref: './specs/shop/cart.yaml#/ShopTypes/Cart'
+    Product:
+      $ref: './specs/shop/product.yaml#/ShopTypes/Product'
+```
+
+**specs/auth/types.yaml:**
+```yaml
+info:
+  version: '1.0.0'
+  title: 'Authentication Types'
+
+groupedTypes:
+  AuthTypes:
+    LoginRequest:
+      type: object
+      required:
+        - email
+        - password
+      properties:
+        email: { type: string }
+        password: { type: string }
+
+    LoginResponse:
+      type: object
+      required:
+        - token
+        - user
+      properties:
+        token: { type: string }
+        user:
+          $ref: './specs/user.yaml#/User'  # Cross-file reference
+```
+
+### Multi-File Reference Rules
+
+#### 1. Every File Needs `info` Section
+
+```yaml
+# ✅ CORRECT: All files need info section
+info:
+  version: '1.0.0'
+  title: 'File Title'
+
+types:
+  # ... your types
+```
+
+#### 2. Reference Format
+
+```yaml
+# Local reference (same file)
+$ref: '#/types/TypeName'
+$ref: '#/groupedTypes/GroupName/TypeName'
+
+# External reference (from project root)
+$ref: './path/from/root/file.yaml#/TypeName'
+$ref: './path/from/root/file.yaml#/GroupName/TypeName'
+```
+
+#### 3. Path Resolution
+
+**CRITICAL:** All paths are from **project root** (where you run `type-crafter` command)
+
+```bash
+# If you run this command from /project
+cd /project
+type-crafter generate typescript ./specs/api.yaml ./output
+
+# Then all $ref paths in ANY file are relative to /project
+```
+
+**Example:**
+```
+/project/
+├── specs/
+│   ├── api.yaml        # File A
+│   └── user/
+│       └── types.yaml  # File B
+```
+
+**In specs/api.yaml:**
+```yaml
+# ✅ CORRECT: Path from project root
+User:
+  $ref: './specs/user/types.yaml#/User'
+
+# ❌ WRONG: Don't use relative path from current file
+User:
+  $ref: './user/types.yaml#/User'
+```
+
+**In specs/user/types.yaml:**
+```yaml
+# ✅ CORRECT: Path from project root
+Profile:
+  $ref: './specs/api.yaml#/ApiTypes/Profile'
+
+# ❌ WRONG: Don't use relative path
+Profile:
+  $ref: '../api.yaml#/ApiTypes/Profile'
+```
+
+### Generating Types from Multi-File Specs
+
+```bash
+# Generate from top-level file (references will be resolved automatically)
+type-crafter generate typescript ./types/index.yaml ./output
+
+# Or from any entry point
+type-crafter generate typescript ./specs/api.yaml ./src/types
+```
+
+All referenced files will be automatically processed and types generated.
+
+---
+
 ## Root Structure
 
 ### Required Fields
@@ -124,40 +479,242 @@ Only these can be top-level types:
 
 **Properties NOT in `required` array become nullable (`Type | null`)**
 
+This is controlled EXCLUSIVELY by the `required` array. There are NO other properties or syntax for controlling nullability.
+
+### ❌ WRONG: What NOT to Do
+
+```yaml
+# ❌ WRONG: Do NOT use 'nullable' property
+User:
+  type: object
+  properties:
+    name:
+      type: string
+      nullable: true  # ❌ INVALID! This property does NOT exist in Type Crafter
+
+# ❌ WRONG: Do NOT use 'optional' property
+User:
+  type: object
+  properties:
+    name:
+      type: string
+      optional: true  # ❌ INVALID! This property does NOT exist
+
+# ❌ WRONG: Do NOT use '?' suffix
+User:
+  type: object
+  properties:
+    name?:  # ❌ INVALID! Don't use ? in property names
+      type: string
+
+# ❌ WRONG: Do NOT use null in type
+User:
+  type: object
+  properties:
+    name:
+      type: [string, null]  # ❌ INVALID! Don't use array of types here
+```
+
+### ✅ CORRECT: Use `required` Array Only
+
 ```yaml
+# ✅ CORRECT: Control nullability with 'required' array
 User:
   type: object
   required:
-    - id # Will be: id: string
-    - email # Will be: email: string
+    - id      # id is required → generates: string
+    - email   # email is required → generates: string
+    # name is NOT in required → generates: string | null
+    # age is NOT in required → generates: number | null
   properties:
     id:
       type: string
     email:
       type: string
     name:
-      type: string # NOT in required → becomes: string | null
+      type: string
     age:
-      type: number # NOT in required → becomes: number | null
+      type: number
 ```
 
 **TypeScript Output:**
 
 ```typescript
 export type User = {
-  id: string; // Required - no null
-  email: string; // Required - no null
-  name: string | null; // Optional - nullable
-  age: number | null; // Optional - nullable
+  id: string; // Required (in required array)
+  email: string; // Required (in required array)
+  name: string | null; // Nullable (NOT in required array)
+  age: number | null; // Nullable (NOT in required array)
 };
 ```
 
-### Rules
+### Detailed Rules
+
+1. ✅ **Property in `required` array** → Generates `Type` (NOT nullable)
+
+   ```yaml
+   User:
+     type: object
+     required:
+       - name
+     properties:
+       name: { type: string }
+   # Generates: name: string
+   ```
+
+2. ✅ **Property NOT in `required` array** → Generates `Type | null` (nullable)
+
+   ```yaml
+   User:
+     type: object
+     required:
+       - id
+     properties:
+       id: { type: string }
+       name: { type: string } # NOT in required
+   # Generates: name: string | null
+   ```
+
+3. ✅ **No `required` array at all** → All properties are `Type | null`
+
+   ```yaml
+   User:
+     type: object
+     # No required array
+     properties:
+       id: { type: string }
+       name: { type: string }
+   # Generates: id: string | null, name: string | null
+   ```
+
+4. ✅ **Empty `required: []`** → All properties are `Type | null`
+   ```yaml
+   User:
+     type: object
+     required: [] # Empty array
+     properties:
+       id: { type: string }
+   # Generates: id: string | null
+   ```
+
+### Complete Examples
+
+#### Example 1: All Properties Required
 
-1. ✅ **In `required` array** → `Type`
-2. ✅ **NOT in `required` array** → `Type | null`
-3. ✅ **No `required` array** → All properties are `Type | null`
-4. ❌ **Empty `required: []`** → All properties are `Type | null`
+```yaml
+User:
+  type: object
+  required:
+    - id
+    - email
+    - name
+    - age
+  properties:
+    id: { type: string }
+    email: { type: string }
+    name: { type: string }
+    age: { type: number }
+```
+
+```typescript
+// Generated TypeScript
+export type User = {
+  id: string;
+  email: string;
+  name: string;
+  age: number;
+};
+```
+
+#### Example 2: Some Properties Required
+
+```yaml
+User:
+  type: object
+  required:
+    - id
+    - email
+  properties:
+    id: { type: string }
+    email: { type: string }
+    name: { type: string }
+    age: { type: number }
+```
+
+```typescript
+// Generated TypeScript
+export type User = {
+  id: string;
+  email: string;
+  name: string | null;
+  age: number | null;
+};
+```
+
+#### Example 3: No Properties Required
+
+```yaml
+User:
+  type: object
+  properties:
+    id: { type: string }
+    email: { type: string }
+    name: { type: string }
+    age: { type: number }
+```
+
+```typescript
+// Generated TypeScript - All nullable
+export type User = {
+  id: string | null;
+  email: string | null;
+  name: string | null;
+  age: number | null;
+};
+```
+
+### Nested Objects and Arrays
+
+```yaml
+User:
+  type: object
+  required:
+    - profile
+    - posts
+  properties:
+    profile:
+      type: object
+      required:
+        - name
+      properties:
+        name: { type: string }
+        bio: { type: string } # NOT in profile.required
+    posts:
+      type: array
+      items:
+        type: object
+        required:
+          - title
+        properties:
+          title: { type: string }
+          content: { type: string } # NOT in items.required
+```
+
+```typescript
+// Generated TypeScript
+export type User = {
+  profile: {
+    // profile is required (in User.required)
+    name: string; // required in profile
+    bio: string | null; // NOT required in profile
+  };
+  posts: Array<{
+    // posts array is required
+    title: string; // required in post item
+    content: string | null; // NOT required in post item
+  }>;
+};
+```
 
 ---