@type-crafter/mcp 0.4.0 → 0.6.0

package/README.md

@@ -268,20 +268,6 @@ npm run build
 npm run dev
 ```
 
-## Development
-
-### Building from Source
-
-```bash
-npm run build
-```
-
-### Watch Mode
-
-```bash
-npm run dev
-```
-
 ### Linting
 
 ```bash

package/dist/index.js

@@ -32,6 +32,9 @@ 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);
@@ -387,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.4.0",
+  "version": "0.6.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,418 @@ 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
+
+# ❌ WRONG: Using # reference in non-top file (file without info section)
+# File: docs/cart.yaml (NON-TOP FILE - no info section)
+Cart:
+  SCart:
+    type: object
+    properties:
+      items:
+        type: array
+        items:
+          $ref: '#/Cart/SCartItem'  # ❌ WRONG! Must use full path in non-top files
+
+# ❌ WRONG: Using full path in top file for same-file reference
+# File: types.yaml (TOP FILE - has info section)
+info:
+  version: '1.0.0'
+  title: 'Types'
+types:
+  User:
+    type: object
+    properties:
+      profile:
+        $ref: './types.yaml#/types/Profile'  # ❌ WRONG! Use # in top files for same-file refs
+```
+
+### ✅ 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
+
+# ✅ CORRECT: Top file using # for same-file references
+# File: types.yaml (TOP FILE - has info section)
+info:
+  version: '1.0.0'
+  title: 'API Types'
+types:
+  User:
+    type: object
+    properties:
+      profile:
+        $ref: '#/types/Profile'  # ✅ Use # in top files for same-file refs
+  Profile:
+    type: object
+    properties:
+      bio: { type: string }
+
+# ✅ CORRECT: Non-top file using full path for all references
+# File: docs/cart.yaml (NON-TOP FILE - no info section)
+Cart:
+  SCart:
+    type: object
+    properties:
+      items:
+        type: array
+        items:
+          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ Full path in non-top files
+  SCartItem:
+    type: object
+    properties:
+      id: { type: number }
+```
+
+### 🔑 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. **Referencing depends on file type**
+   - **Top file** (has `info:` at root): Use `#/types/TypeName` for same-file refs
+   - **Non-top file** (no `info:` at root): MUST use `'./path/from/root/file.yaml#/TypeName'` for ALL refs
+   - Identify top files by presence of `info` section at root level
+
+5. **Top file is required for generation**
+   - Only files with `info:` section can be used with `type-crafter generate`
+   - Non-top files must be referenced from a top file
+
+---
+
+## 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 +538,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)
+};
+```
+
+### 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
+
+```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;
 };
 ```
 
-### Rules
+#### Example 3: No 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
+  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
+  }>;
+};
+```
 
 ---
 
@@ -409,69 +1025,238 @@ export type UserWithMeta = {
 
 ## References
 
-### Local References (Same File)
+### Understanding Top Files vs Non-Top Files
+
+**CRITICAL:** Referencing rules differ based on whether you're in a top file or non-top file.
+
+#### What is a Top File?
 
+A **top file** is the root specification file that contains the `info` section at the root level.
+
+**Identifying a top file:**
 ```yaml
-# Reference to top-level type
-Post:
-  type: object
-  properties:
-    author:
-      $ref: '#/types/User'
+# ✅ This is a TOP FILE
+info:
+  version: '1.0.0'  # Has info section at root
+  title: 'My API Types'
 
-# Reference to grouped type
-Comment:
-  type: object
-  properties:
-    author:
-      $ref: '#/groupedTypes/Auth/UserProfile'
+types:
+  User: { ... }
 ```
 
-**Reference Format:**
+**Characteristics:**
+- Contains `info:` section with `version` and `title` at the root level
+- Is the root of all schemas
+- Can be directly used with `type-crafter generate` command
+- Typically referenced by other files
 
-- Top-level: `#/types/TypeName`
-- Grouped: `#/groupedTypes/GroupName/TypeName`
+#### What is a Non-Top File?
 
-### External File References
+A **non-top file** is any YAML file that does NOT have `info:` at the root level. These files are used to organize types into domain-specific files.
 
-**⚠️ IMPORTANT: Paths are from project root, not relative to current file**
+**Identifying a non-top file:**
+```yaml
+# ✅ This is a NON-TOP FILE (no info section at root)
+Cart:
+  SCart:
+    type: object
+    properties:
+      items: { ... }
+
+  SCartItem:
+    type: object
+    properties:
+      id: { ... }
+```
+
+**Characteristics:**
+- Does NOT have `info:` section at the root level
+- Must be referenced from a top file or another file
+- Used for better organization of types in domain-specific files
+- Cannot be used directly with `type-crafter generate` command
+
+### Referencing Rules
+
+#### Rule 1: References in TOP Files
+
+**In top files, you can reference types using `#` without specifying the file path.**
+
+**Example:**
 
 ```yaml
-# Reference to type in another file (path from project root)
-Post:
-  type: object
-  properties:
-    author:
-      $ref: './src/types/users.yaml#/User'
+# File: types.yaml (TOP FILE - has info section)
+info:
+  version: '0.0.0'
+  title: 'Sample Typing Spec'
 
-# Reference to grouped type in another file
-Comment:
-  type: object
-  properties:
-    metadata:
-      $ref: './docs/specs/common.yaml#/SharedTypes/Metadata'
+types:
+  TypeObjectTwo:
+    type: object
+    properties:
+      propOne:
+        $ref: '#/types/TypeObjectOne'  # ✅ Direct reference (no file path needed)
 
-# Real-world example: Shopify cart referencing cart item
-SCart:
-  type: object
-  properties:
-    items:
-      type: array
+  TypeObjectOne:
+    type: object
+    properties:
+      name:
+        type: string
+```
+
+**Valid reference formats in top files:**
+- Same file, top-level type: `#/types/TypeName`
+- Same file, grouped type: `#/groupedTypes/GroupName/TypeName`
+- External file: `'./path/from/root/file.yaml#/TypeName'` (when referencing another file)
+
+#### Rule 2: References in NON-TOP Files
+
+**In non-top files, you MUST specify the complete file path (from project root) when referencing ANY type, even types in the same file.**
+
+**Example:**
+
+```yaml
+# File: docs/cart.yaml (NON-TOP FILE - no info section)
+Cart:
+  SCart:
+    description: 'Shopify cart object'
+    type: object
+    properties:
       items:
-        $ref: './docs/specs/Cart.yaml#/Cart/SCartItem'
+        type: array
+        items:
+          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ MUST include full file path
+
+  SCartItem:
+    description: 'Individual cart item'
+    type: object
+    properties:
+      id:
+        type: number
 ```
 
-**Reference Format:**
+**Why the full path?** Non-top files don't have an `info` section, so they don't have a root context. You must always specify where the type is located.
+
+### Complete Examples
 
-- **Path from project root:** `./path/from/root/file.yaml#/TypeName`
-- External type: `./path/from/root/file.yaml#/TypeName`
-- External grouped: `./path/from/root/file.yaml#/GroupName/TypeName`
+#### Example 1: Top File with Local References
 
-**Path Rules:**
+```yaml
+# File: types.yaml (TOP FILE)
+info:
+  version: '1.0.0'
+  title: 'API Types'
+
+types:
+  Post:
+    type: object
+    properties:
+      author:
+        $ref: '#/types/User'  # ✅ Local reference in top file (no path)
+      comments:
+        type: array
+        items:
+          $ref: '#/types/Comment'  # ✅ Local reference in top file (no path)
+
+  User:
+    type: object
+    properties:
+      id: { type: string }
+      name: { type: string }
+
+  Comment:
+    type: object
+    properties:
+      text: { type: string }
+```
+
+#### Example 2: Top File Referencing Non-Top Files
+
+```yaml
+# File: types.yaml (TOP FILE)
+info:
+  version: '0.0.0'
+  title: 'Sample Typing Spec'
+
+groupedTypes:
+  Cart:
+    $ref: './docs/cart.yaml#/Cart'  # ✅ Importing entire Cart group from non-top file
+
+# Project structure:
+# .
+# ├── types.yaml (this file - top file)
+# └── docs/
+#     └── cart.yaml (non-top file)
+```
+
+```yaml
+# File: docs/cart.yaml (NON-TOP FILE)
+Cart:
+  SCart:
+    description: 'Shopify cart object'
+    type: object
+    required:
+      - items
+    properties:
+      items:
+        type: array
+        items:
+          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ Full path required in non-top file
+
+  SCartItem:
+    description: 'Individual item in the cart'
+    type: object
+    required:
+      - id
+    properties:
+      id:
+        type: number
+        description: 'Unique item identifier'
+      quantity:
+        type: number
+```
+
+#### Example 3: Non-Top File Referencing Another Non-Top File
+
+```yaml
+# File: docs/order.yaml (NON-TOP FILE)
+Order:
+  SOrder:
+    type: object
+    properties:
+      items:
+        type: array
+        items:
+          $ref: './docs/cart.yaml#/Cart/SCartItem'  # ✅ Full path to another non-top file
+      customer:
+        $ref: './docs/user.yaml#/User/SCustomer'  # ✅ Full path to another non-top file
+```
+
+### Reference Format Summary
+
+| File Type | Referencing Same File | Referencing Another File |
+|-----------|----------------------|--------------------------|
+| **Top File** | `#/types/TypeName`<br>`#/groupedTypes/Group/TypeName` | `'./path/from/root/file.yaml#/TypeName'` |
+| **Non-Top File** | `'./path/from/root/current-file.yaml#/TypeName'`<br>(full path required) | `'./path/from/root/other-file.yaml#/TypeName'` |
+
+### Path Rules (All Files)
+
+1. **Paths are from project root** (where you run `type-crafter` command), NOT relative to current file
+2. **Always start with `./`** for file paths
+3. **Never use `../`** for relative navigation
+4. **Case matters** - file paths are case-sensitive on some systems
+
+**Example project structure:**
+```
+project-root/
+├── types.yaml          (top file)
+└── docs/
+    ├── cart.yaml       (non-top file)
+    └── user.yaml       (non-top file)
+```
 
-- Paths start with `./` and are relative to **project root** (where you run the command)
-- NOT relative to the current YAML file location
-- Example: If your spec is at `./src/api.yaml` and references `./src/types/user.yaml`, the path is `./src/types/user.yaml`, not `./types/user.yaml`
+If running `type-crafter generate typescript ./types.yaml ./output` from `project-root/`:
+- Path to cart.yaml: `'./docs/cart.yaml#/...'`
+- Path to user.yaml: `'./docs/user.yaml#/...'`
 
 ### Group References (Entire Group)