New Example Applications:
- apps/example-commercial/ - Azure Commercial Cloud preset
- apps/example-gcc-high/ - Azure Government (GCC-High) preset
- Both pre-configured with correct endpoints and settings

Features:
- Cloud-specific .env.example files with detailed comments
- Dedicated README for each preset explaining setup
- Comprehensive apps/README.md comparing all examples
- IL4 compliance notes for GCC-High
- DoD configuration guidance

Documentation:
- Updated root README with example app links
- Monorepo structure diagram updated
- Cloud comparison table (endpoints, portals, compliance)
- Common pitfalls section (wrong cloud, mixed scopes, license mismatch)
- Features demonstrated list (auth flow, Server Actions, API integration)

Testing:
- Both examples build successfully
- TypeScript strict mode enabled
- All workspace dependencies resolved
- Updated pnpm-workspace.yaml

Benefits:
- Lowers barrier to entry for new users
- Clear cloud-specific configurations
- Prevents common mistakes (wrong endpoints, mixed scopes)
- Government cloud users get IL4 compliance guidance
- Side-by-side comparison helps choosing right preset

This completes another high-priority roadmap item for v1.0 GA.

No changes to core library - purely additive example applications.

New Documentation:
- docs/MIGRATION_FROM_NEXTAUTH.md - Complete NextAuth.js migration guide
- docs/MIGRATION_FROM_MSAL.md - Complete MSAL Browser/React migration guide
- Both guides include side-by-side code comparisons
- Step-by-step migration instructions
- Feature mapping tables
- Common migration issues and solutions

README Updates:
- Added migration comparison table (Latch vs NextAuth vs MSAL)
- Added "Migrating to Latch" section with quick comparison
- Added migration guide links to documentation section
- Clear guidance on when to choose each library

NextAuth.js Migration Guide:
- Why migrate section with pros/cons
- Key differences table
- 6-step migration process
- Code comparisons (session, middleware, Server Actions)
- Feature mapping (authentication, session data, token access)
- Azure Government support comparison
- Common migration issues (session structure, access tokens, custom data)
- Performance comparison
- Complete migration checklist

MSAL Migration Guide:
- Why migrate section (Next.js benefits)
- Key differences table (token storage, configuration, etc.)
- 5-step migration process
- Code comparisons (initialization, login, logout, token acquisition)
- Feature mapping (core features, configuration, account info)
- Azure Government support comparison (verbose MSAL vs simple Latch)
- Security improvements section (HttpOnly cookies vs localStorage)
- Performance comparison
- Quick reference API mapping

Comparison Table:
- Feature comparison across all three libraries
- Clear recommendations for when to choose each
- Highlights Latch strengths (Azure Government, Server Actions, security)
- Acknowledges Latch limitations (Azure AD only)

Benefits:
- Helps users make informed migration decisions
- Lowers migration friction with clear examples
- Demonstrates Latch advantages for Azure AD + Next.js
- Comprehensive troubleshooting for common issues
- Real-world code examples users can copy

This completes the final high-priority roadmap item before security audit.

Total documentation added: ~800 lines across 2 comprehensive guides.

New Commands:
- latch scaffold - Copy API routes and Server Actions from examples
- latch validate - Validate .env.local for common mistakes
- latch doctor - Run diagnostics on Latch setup

Enhancements:
- Updated init wizard to include v0.4.1 security options (commented)
- Version bumped to 0.4.1 to match core package
- Comprehensive validation (UUIDs, cloud/scope mismatches, secret strength)
- Setup diagnostics (Next.js, package install, routes, LatchProvider)

Features:
- Scaffold: Interactive example selection, safe overwrite prompts
- Validate: Checks 8+ config issues with helpful suggestions
- Doctor: 7 diagnostic checks for complete setup verification

Benefits:
- Faster onboarding (scaffold routes instead of manual copy)
- Catch config mistakes early (validate before first run)
- Troubleshooting made easy (doctor shows exactly what's wrong)
- Production-ready validation (tested in real deployments)

Documentation Updates:
- Completely rewrote ROADMAP.md (514 → 137 lines, 73% reduction)
- Updated status: v0.4.1 production-ready, v1.0 future/community-driven
- Added v0.4.0 and v0.4.1 to CHANGELOG.md
- Removed obsolete files: NEXTAUTH_CONTRIBUTION_ROADMAP.md, PRE_PUBLISH_ROADMAP.md
- Removed internal .claude directory

Changes:
- ROADMAP now concise and accurate (reflects completed work)
- Clear production status and future direction
- Updated metrics (300 hours, 7 releases, 161 tests)
- CHANGELOG complete with all shipped features
- Removed 45KB of obsolete documentation

Focus: Complete yet concise documentation that reflects current state

Based on real production feedback, added comprehensive guide showing how to
wrap Latch's primitive helpers with app-specific logic.

New Section: Production Patterns
- Why wrapping is necessary (DB sync, roles, caching, etc.)
- Recommended pattern with complete code example
- Benefits of wrapping (performance, testing, flexibility)
- Anti-pattern: Using primitives directly everywhere
- Advanced pattern: Dependency injection for testability

Key insight: Latch provides authentication primitives (cookie reading),
but production apps need wrappers for:
- Database user synchronization
- Role/permission loading
- Request-level caching (React cache())
- Custom error handling
- Logging and analytics

Example shows:
- getCurrentUser() with DB upsert and role loading
- requireAuth() that throws if not authenticated
- requireRole() for role-based access control
- Use of React cache() to prevent redundant DB queries

This documents the pattern that production users discovered on their own,
making it an official best practice.

Based on technical review feedback, implemented two critical improvements:

1. Automatic Token Refresh (LatchProvider)
   - Users stay logged in for full 7 days (refresh token lifetime)
   - Auto-refresh fires 5 minutes before token expiry
   - Prevents unexpected 1-hour logout due to ID token expiration
   - Seamless UX with proper timer cleanup

2. PBKDF2 Key Caching (seal.ts)
   - Cache derived AES keys in memory for massive performance gain
   - First operation: ~10-20ms (key derivation)
   - Subsequent operations: <1ms (cached key reuse)
   - 10-20x performance improvement for seal/unseal
   - Zero security trade-off (secret already in memory)

Technical Details:
- Auto-refresh uses React useEffect with proper cleanup
- Handles edge cases (expires in <5 min, tab close, multiple tabs)
- Key cache is per-process, supports secret rotation
- Added clearKeyCache() export for testing/manual invalidation
- Module-level Map cache for derived keys

Tests Added:
- Performance test for key caching
- Multiple secrets independence test
- Manual cache clearing test
- All existing tests pass

Benefits:
- Production UX: No more surprise logouts
- Performance: Reduced CPU usage under high load
- Seamless: No API changes, fully backward compatible

Version: 0.4.1 → 0.4.2

Added comprehensive llms.txt following standard format:
- Project overview and target audience
- Documentation structure and locations
- Complete directory layout with descriptions
- Key files and their purposes
- Architecture decisions explained
- Common tasks for users/contributors/maintainers
- Environment variables reference
- Production patterns overview
- Testing information

Benefits:
- LLMs can quickly understand codebase structure
- Developers get a high-level map of the project
- Onboarding documentation in standard format
- All key concepts in one place

- Add requireServerSession() helper for TypeScript-friendly session validation
- Add isLatchSession() type guard for proper type narrowing
- Add checkLatchHealth() for configuration validation
- Create reference examples/nextjs16/proxy.ts with Next.js 16 compatibility
- Document session structure, cookie names, and usage patterns in API_REFERENCE.md
- Add 17 new tests for DX helpers (182 tests total, all passing)

Fixes critical Next.js 16 issues:
- Remove runtime export from proxy.ts (causes build errors)
- Fix session validation to check session.sub not session.idToken

Based on real production feedback from Scout app integration.

- Add 'latch scaffold proxy' - Generate Next.js 16 compatible proxy.ts
- Add 'latch scaffold wrapper' - Generate lib/auth.ts helper functions
- Add 'latch scaffold all' - Complete setup (proxy + wrapper + routes)
- Improve scaffold command with interactive type selection
- Update CLI version to 0.4.4

- Move recommended wrapping pattern to Quick Start (step 6)
- Emphasize centralizing auth logic with app-specific helpers
- Show complete lib/auth.ts example with database sync
- Add step 8 showing usage in Server Actions and API routes
- Makes production best practices more discoverable
- Update version to 0.4.5

- Add new helpers from v0.4.3 (requireServerSession, isLatchSession, checkLatchHealth)
- Update Features section with automatic token refresh and CLI improvements
- Mention PBKDF2 key caching performance improvement
- Add API Reference link to Server Actions section
- Reflect current state of v0.4.5

- Update version to 0.4.5
- Add DX improvements section (v0.4.3 helpers)
- Add CLI enhancements section (v0.4.4 scaffold improvements)
- Add documentation improvements section (v0.4.5)
- Update test count (164 → 182 tests)
- Update helper list in structure
- Update scaffold description
- Update last updated date

Based on real developer feedback, fixed common pain points:

1. Next.js Link gotcha - Added warning about using <a> not <Link> for auth endpoints
2. Cookie secret generation - Show multiple methods (openssl, CLI, manual)
3. TypeScript support section - Clear LatchSession vs LatchUser distinction
4. Common DX issues section - Address 5 most common developer mistakes
5. Type import examples - Show correct import paths for hooks and types
6. Session structure patterns - Wrong vs correct usage examples

These changes address actual pain points from Scout integration feedback.

CRITICAL SECURITY UPDATE

CVE-2025-55182 is a CVSS 10.0 remote code execution vulnerability
affecting React Server Components.

Changes:
- Updated peer dependencies to require patched versions:
  - next: >=15.0.5 (was >=15.0.0)
  - react: >=19.0.1 (was ^19.0.0)
  - react-dom: >=19.0.1 (was ^19.0.0)
- Updated all example apps to use Next.js 16.0.7 and React 19.0.1
- Added security advisory to SECURITY.md and README.md
- Updated CHANGELOG.md with security release notes

Latch does NOT directly depend on vulnerable packages (react-server-dom-*),
but applications using vulnerable versions of React/Next.js may be affected.

Users should upgrade immediately:
  npm install next@latest react@latest react-dom@latest

References:
- https://react.dev/blog/2024/12/03/react-19-upgrade-guide
- https://www.cve.org/CVERecord?id=CVE-2025-55182
- https://nextjs.org/blog/CVE-2025-66478

SECURITY UPDATE (December 11, 2025)

Additional vulnerabilities discovered in React Server Components after
the initial React2Shell patch:

- CVE-2025-55184 / CVE-2025-67779: Denial of Service (High Severity)
  - Infinite loop hangs server process
  - Initial fix was INCOMPLETE - CVE-2025-67779 is the complete fix

- CVE-2025-55183: Source Code Exposure (Medium Severity)
  - Server Function source code can be leaked

Changes:
- Updated peer dependencies:
  - next: >=15.0.7 (was >=15.0.5)
- Updated all example apps to use Next.js 16.0.10 (was 16.0.7)
- Updated SECURITY.md with version table and new CVE references
- Updated CHANGELOG.md with v0.4.7 release notes

Required Next.js versions per release line:
- 14.x: 14.2.35
- 15.0.x: 15.0.7
- 15.1.x: 15.1.11
- 15.2.x: 15.2.8
- 15.3.x: 15.3.8
- 15.4.x: 15.4.10
- 15.5.x: 15.5.9
- 16.0.x: 16.0.10

References:
- https://nextjs.org/blog/security-update-december-2025
- https://react.dev/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components

- Weekly npm dependency updates (Mondays)
- Groups dev dependencies for cleaner PRs
- Ignores major version bumps (manual review)
- Also monitors GitHub Actions