docs: add comprehensive deep linking documentation

Changes:
- Add detailed JSDoc headers to deep linking files
- Document type system and validation strategy
- Add architecture overview and error handling docs
- Include usage examples and integration points
- Improve code organization comments

This improves maintainability by documenting the deep linking
system's architecture, type safety, and integration points.

src/types/deepLinks.ts

@@ -1,3 +1,30 @@
+/**
+ * @file Deep Link Type Definitions and Validation Schemas
+ * @author Matthew Raymer
+ * 
+ * This file defines the type system and validation schemas for deep linking in the TimeSafari app.
+ * It uses Zod for runtime validation while providing TypeScript types for compile-time checking.
+ * 
+ * Type Strategy:
+ * 1. Define base URL schema to validate the fundamental deep link structure
+ * 2. Define route-specific parameter schemas with exact validation rules
+ * 3. Generate TypeScript types from Zod schemas for type safety
+ * 4. Export both schemas and types for use in deep link handling
+ * 
+ * Usage:
+ * - Import schemas for runtime validation in deep link handlers
+ * - Import types for type-safe parameter handling in components
+ * - Use DeepLinkParams type for type-safe access to route parameters
+ * 
+ * @example
+ * // Runtime validation
+ * const params = deepLinkSchemas.claim.parse({ id: "123", view: "details" });
+ * 
+ * // Type-safe parameter access
+ * function handleClaimParams(params: DeepLinkParams["claim"]) {
+ *   // TypeScript knows params.id exists and params.view is optional
+ * }
+ */
 import { z } from "zod";
 
 // Base URL validation schema